# dots-kanban

A personal task board shared by you, your dot, and local Codex. One Sites-hosted database powers a standalone web view, MCP tools, and an MCP App UI with a global sidebar entry point.

The interface is currently Chinese. The design adapts the compact Hermes Kanban workflow and teal/ivory theme for personal use.

## What it does

- Five manual stages: todo, doing, blocked, review, done; reversible archive
- Task descriptions, results, blockers, P0–P3 priorities, labels, due dates
- Responsible-party intent: unassigned, me, dot, local Codex
- Projects with optional repository URL, computer reference, and absolute working directory
- Prerequisite graph with cycle checks, progress comments, and change history
- Search, filters, drag/drop, keyboard stage menus, batch actions, detail dialog
- Shared cloud persistence, optimistic concurrency, retry-safe mutations
- Host light/dark theme, responsive layout, 20-second visible-view refresh

Selecting dot or Codex does not start a process. Project paths are unverified metadata. Starting work requires an explicit conversation request, a capable connected client, and checks on the actual target computer. This repository does not include a dispatcher or agent runtime.

## Deploy with your dot

Give your dot this repository and ask it to deploy a private copy in **your own Sites account**, including the Site-hosted MCP and global MCP App entry point. [AGENTS.md](AGENTS.md) provides the implementation checklist.

Each installation needs its own Site, D1 binding, authentication boundary, associated plugin, and user-approved connection. There are no original-owner credentials, deployment IDs, account details, databases, or personal tasks in this repository. Availability of Sites and plugin capabilities depends on the recipient's environment. This is a source-based deployment workflow, **not a verified one-click installer or a completed second-account deployment test**.

If your dot lacks the required Sites capabilities, it should explain the missing capability instead of guessing deployment endpoints or requesting secrets in chat. Do not publish the raw Worker with its current header-based identity adapter; see [SECURITY.md](SECURITY.md).

## Local development

Requirements: Node.js 22.13+ and npm. The lockfile is included.

```sh
npm ci
npm run typecheck
npm run build
npm test
```

`npm test` creates a temporary local D1 database, inserts a synthetic legacy row before applying the additive migrations, starts a loopback-only Worker, runs the request/DOM/bridge suites, and removes that test database. It does not use remote credentials or production data. Port 8788 must be free; set `TEST_PORT` to change it. Build before testing.

For interactive local development:

```sh
npm run dev
```

The portable development adapter provides a local mock identity. Initialize the dev database with the three SQL migrations in order through the local D1 tooling before using the board. Do not point test scripts or mock identity headers at a production deployment. The production identity adapter relies on Sites, not this local mock.

## Architecture

- `lib/tasks.ts`, `lib/projects.ts`: owner-scoped domain services
- `db/`, `drizzle/`: D1 schema and additive SQL migrations
- `app/api/tasks/route.ts`: authenticated web API
- `app/mcp/route.ts`: stateless MCP JSON-RPC endpoint
- `lib/tool-definitions.ts`: twelve MCP tool definitions and global UI metadata
- `lib/board-ui.ts`, `lib/board-client.js`, `lib/board-style.css`: shared renderer
- `build/`: **source code** for the Sites build/preview adapters, not compiled output
- `scripts/verify-*.mjs`: local request and UI bridge checks

The MCP App is delivered by `resources/read` as self-contained HTML/CSS/JavaScript. Its data calls use the host `tools/call` bridge. The standalone view uses `/api/tasks`; both reach the same domain service. It is not an iframe navigating to the standalone website. Task data is not cached in localStorage; only theme preference is.

## MCP tools

`open_task_board`, `list_tasks`, `create_task`, `update_task_status`, `get_task`, `update_task`, `set_task_dependencies`, `add_task_comment`, `archive_task`, `list_projects`, `create_project`, `update_project`

Read current IDs and versions before writes. Use `expected_version` for optimistic concurrency and reuse `mutation_id` only for the same retry. Original `status` values todo/doing/done remain supported; richer workflow uses `stage`. Blocked and review map to legacy doing. The old v1 resource URI remains readable for cached clients.

Plugin tool metadata may be cached or scanned independently of a deployment. Confirm that the connected client's catalog actually exposes all twelve tools. Use the host's supported refresh/rescan flow if available; never assume that fresh HTML proves new tools are registered. Details are in [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md).

## Security and persistence

Trusted Sites identity scopes every record to its owner. D1 prepared statements, version guards, and atomic batches protect mutations and event history. Dependency cycles are rejected within the transaction. Incomplete prerequisites block entry into doing. Archive is recoverable; there is no permanent-delete tool.

Identity headers are **not cryptographically verified by application code**. Only a trusted hosting edge may supply them. Arbitrary public hosting requires an independently implemented and verified authentication adapter. See [SECURITY.md](SECURITY.md).

## Hermes inspiration and differences

Reference: [NousResearch/hermes-agent](https://github.com/NousResearch/hermes-agent/tree/af92ea8e5b852518c523c3e8b2cbd95f0f3d79dc), pinned at `af92ea8e5b852518c523c3e8b2cbd95f0f3d79dc`.

Adapted concepts include compact columns, metadata chips, a detail drawer, prerequisites, comments, durable events, and the teal (`#041c1c`) / ivory (`#ffe6cb`) palette. This implementation uses five personal, manual stages instead of system-owned worker states; it has no tenants, runs, claims, schedules, worktree creation, or automatic project routing. P0 is highest priority here; upstream numeric ordering differs. Labels and due dates are personal-workflow additions. D1 batches and polling replace upstream local SQLite transactions and event streaming.

Upstream notices are preserved in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md), with separate notices beside vendored files.

## Verification and current limits

The local suites cover original API compatibility, additive migration preservation, CAS conflicts, idempotent retries, concurrent mutation collisions, prerequisites, archive/restore, owner isolation, project validation, DOM interactions, and MCP bridge calls. DOM tests are simulated; they do not prove pixel rendering, browser focus behavior, or native ChatGPT integration.

A real installation must separately verify native plugin discovery, sidebar rendering, and cross-client read/write. Listing currently caps at 1,000 tasks and 200 projects; detail returns at most 500 comments and the latest 200 events. There is no automated execution or attachment system.

## 中文简介

这是个人与 dot、本地 Codex 共用的任务看板。通过自己的 Sites 部署私有副本，数据保存在自己的云端数据库；网页和 MCP App 共用同一套数据与服务。负责人和项目仅表示计划，明确提出“开始任务”后，再由具备权限的客户端核对电脑、目录并执行。仓库不包含原部署的个人数据或凭据，也不承诺一键安装。

## License

MIT for this repository's original application work; see [LICENSE](LICENSE). Third-party material retains its own notices and terms. No ownership claim over upstream projects is implied. This is an independent project, not an official OpenAI or Nous Research product.