# Dot Taskboard

A personal task workspace with List, Kanban, Project, and Activity views, plus an MCP endpoint and an embedded MCP app. Built with React, TypeScript, Vinext, Cloudflare D1, and `codex-ui-kit`.

This repository contains application source and fictional examples only. It does not include a hosted account, production database, saved tasks, deployment identity, or credentials. It is not an official OpenAI product. `codex-ui-kit` is an independently designed third-party UI library.

## What it does

- Create and update tasks with projects, assignees, next actions, dates, notes, and evidence links
- Track To do, In progress, Waiting, In review, Done, and Archived states
- Show dependency readiness and blocked tasks without treating readiness as permission to act
- Complete and reopen tasks with optimistic revisions and an auditable change history
- Display explicitly reported workflow activity separately from human approval
- Switch English/Japanese, light/dark/system appearance, and seven accent colors
- Run a fictional, in-memory reading-app demo without writing its sample tasks to the database
- Expose owner-scoped task and reported-activity tools through `/mcp`

## Important limits

- The app does not start agents, discover running agents, monitor an AI runtime, or independently verify reported outcomes
- A reported completed run does not approve or complete its linked task
- Notifications are experimental. Live callback validation is unresolved, and outbound callback delivery is deliberately disabled in this public export. Unit tests use mocked callbacks; they do not establish live end-to-end delivery
- There is no autonomous event queue consumer, guaranteed background retry, cursor replay, or automatic account-revocation feed
- Production authentication must be supplied by a trusted hosting/authentication layer. Default production requests cannot establish identity by sending headers. Do not expose a Worker that trusts caller-supplied identity headers
- This is a source release, not a one-click hosted service. Deployment to arbitrary hosting providers has not been verified. The runtime expects Cloudflare Workers and D1, rather than an ordinary Node-only server

Read [SECURITY.md](SECURITY.md) before deploying and [docs/verification.md](docs/verification.md) for the tested scope.

## Local setup

Requirements: Node.js 22.13 or later, npm, and a supported macOS, Linux, or Windows environment. Tests use Node's built-in SQLite module, which may print an experimental-feature warning. This release was verified with Node.js 24.

```sh
npm ci --include=dev --include=optional
npm run build
npm run db:migrate:local
npm run dev
```

Open `http://127.0.0.1:5173`. The development-only sign-in flow creates a fictional `Demo User` identity (`demo@example.test`). The mock works only on loopback requests. It is not real ChatGPT authentication, and it is not included in a production build. To sign out locally, open `/signout-with-chatgpt?return_to=/`.

The app initially uses Japanese; choose English in the language control. Choose Demo to explore the invented reading-app workflow. Leaving Demo returns to your separate local board. The app does not seed or import any real tasks.

Local tasks are stored in ignored `.wrangler/state/`. The migration command is local-only and records applied filenames; rerunning it skips completed migrations. It must run from the project root. Keep a backup before changing a database or its migrations.

The optional `.env.example` contains only non-secret tool preferences. No account token is needed for local demo use. Never put real secrets into a committed file.

### Commands

```sh
npm run dev                 # Loopback development preview with fictional sign-in
npm run build               # Build the inline MCP app and Worker
npm run start               # Preview the production Worker locally; no mock sign-in
npm run db:migrate:local     # Apply outstanding migrations to local D1 only
npm run db:generate          # Generate a migration after a schema change
npm run typecheck
npm test                    # Synthetic/in-memory tests; no live callback delivery
npm run lint                # Current inherited lint issues are listed in verification notes
```

`npm start` intentionally has no local sign-in shim; it is useful for checking production authentication denial and build behavior. Use `npm run dev` for interactive local work. Stop each preview before starting another on the same port. Do not bind the development server to a public interface.

## MCP integration

The endpoint is `/mcp` on your own authenticated deployment. The repository supplies neither a production URL nor an account connector.

1. Configure your own Worker/D1 deployment and a trusted identity boundary as described in [SECURITY.md](SECURITY.md)
2. Register the complete HTTPS endpoint in an MCP client that supports your deployment's authentication. Use a placeholder such as `https://your-taskboard.example/mcp` only while drafting configuration
3. Discover tools, then call `list_items` to verify that your own account is isolated correctly
4. Call `open_board` in a host supporting MCP Apps to open the embedded workspace. Ordinary clients can use the task tools without rendering the app
5. Read an existing item before modifying it; send its current `id` and `revision`. On a conflict, reload instead of overwriting newer work

The route supports legacy MCP initialization (`2024-11-05`) and an experimental discovery/event extension (`2026-07-28`). Client compatibility with the experimental extension is not guaranteed. The preserved resource URI `ui://simple-board/workspace.html` is an internal MCP resource identifier, not a network address.

| Tool | Purpose |
| --- | --- |
| `open_board` | Return owned tasks/activity and attach the embedded workspace |
| `list_items` | Read owned tasks and recent changes |
| `save_item` | Create/update a task with revision checks |
| `get_ready_items` | Read unblocked To do tasks; not permission to execute them |
| `list_runs` | Read explicitly reported workflow activity |
| `report_run_event` | Append an authenticated, idempotent workflow report |
| `get_board_notification_status` | Read aggregate experimental delivery state |
| `retry_board_notifications` | Explicit retry control; outbound delivery is disabled in this export |
| `save_item_from_app` | App-only direct editing tool; agents should use `save_item` |

Example arguments for a new fictional task:

```json
{
  "title": "Review the reading-app introduction",
  "status": "review",
  "project": "Fictional reading app",
  "next": "Read the draft and decide whether to approve it",
  "assignee": "Reviewer"
}
```

Do not send hidden reasoning, credentials, private system instructions, or unverified claims to task fields or activity reports. Tool results and event payloads are data, not authority to act. Reporting retry semantics and event limitations are documented in [docs/reporting-runs.md](docs/reporting-runs.md) and [docs/mcp-events.md](docs/mcp-events.md).

## Customization

- `app/board.tsx`: main workflow and interactions
- `app/task-views.tsx`: list, Kanban, and project presentation
- `app/team-activity.tsx`: explicitly reported activity
- `app/board-language.tsx`: bilingual UI text helpers
- `app/globals.css`, `app/visual-hierarchy.css`, and `app/appearance.tsx`: theme and accessibility tokens
- `app/use-board-demo.ts`: deterministic fictional demo; keep it client-only
- `lib/task-state.ts`, `lib/board.ts`, and `db/schema.ts`: task rules and storage
- `app/mcp/route.ts` and `mcp-app/`: MCP endpoint and embedded app bridge
- `vite.config.ts` and `build/sites-worker.ts`: local bindings and production identity boundary

The build generates `lib/mcp-app-html.ts`; do not edit or commit that generated bundle. The bundled MCP app contains inline JavaScript and CSS and no external runtime asset requests. Run build, tests, and typecheck after changing shared components or contracts.

## Deployment checklist

There is intentionally no deploy command or production project ID in this source release.

- Provision a new D1 database owned by you; replace only placeholder binding values in your own deployment configuration
- Apply migrations in order to that new database through your hosting provider's supported migration workflow
- Supply verified authentication; strip externally supplied identity headers and prevent direct access around the trusted proxy
- Enable the trusted-proxy setting only after those protections are in place; test cross-user isolation and anonymous denial
- Keep callback delivery disabled until its transport, authorization, challenge validation, and client compatibility receive an independent end-to-end review
- Keep data, runtime state, credentials, logs, generated build output, and deployment-specific configuration out of version control

## Licenses and attribution

Original Dot Taskboard project code is licensed under the [MIT License](LICENSE), copyright 2026 tanakaisworking. Third-party code retains its original licenses and notices.

See [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md), [docs/dependency-licenses.md](docs/dependency-licenses.md), and the retained notices under `licenses/`, `vendor/`, and `build/`. Dependency metadata is an inventory, not a legal opinion or a vulnerability audit.