@taskforcehq/taskforce 0.3.304 → 0.3.306

package/README.md

@@ -1,291 +1,184 @@
 # Taskforce
 
-<p align="center">
-  <img src="https://img.shields.io/npm/v/%40taskforcehq%2Ftaskforce?style=for-the-badge&color=8b5cf6" alt="NPM Version" />
-  <img src="https://img.shields.io/npm/l/%40taskforcehq%2Ftaskforce?style=for-the-badge&color=14b8a6" alt="License" />
-  <img src="https://img.shields.io/badge/Status-Beta-amber?style=for-the-badge" alt="Status" />
-  <img src="https://img.shields.io/badge/Powered%20By-Vite-646CFF?style=for-the-badge&logo=vite" alt="Powered by Vite" />
-</p>
-
-<h3 align="center">The High-Bandwidth Collaborative Synapse for AI-Developer Pairs</h3>
-
----
-
-> **Beta Release:** Taskforce is under active development. For the latest experimental features, use `npm i -g @taskforcehq/taskforce@beta`.
-> **Development Tooling:** This is strictly a development-time tool. It is designed to automatically **not render** in production environments to ensure zero overhead.
-
-Taskforce is more than just a task manager; it's a **contextual bridge**. In the age of AI-assisted coding, the gap between "what needs to be done" and "how it was implemented" can grow exponentially. 
-
-Taskforce bridges this gap by providing a persistent, AI-accessible layer of intent that sits directly atop your live application during development. It transforms ephemeral chat history into structured project state.
-
-## ✨ Key Features
-
-- 📍 **Intelligent Context Capture**: Automatically tracks URLs, timestamps, and contextual metadata. Screenshots can be attached directly to tasks for visual debugging.
-- ⚡ **Model Context Protocol (MCP)**: Built-in MCP server allows AI agents (like Claude) to read from and write to your project's task nexus with full awareness of your workspace.
-- 🎨 **Premium Visual Engine**: Hand-crafted Light, Dark, and Midnight themes with a sophisticated token-based color system.
-- ⌨️ **Quick-Access Flow**: Configurable global hotkeys (`Alt+T` default) to toggle the nexus without breaking your flow.
-- 🤝 **Collaborative Loop**: AI-friendly JSON storage enables "staged" updates—AI suggests changes, and you approve the final state.
+Taskforce is a task management system for humans working with AI.
+
+It combines structured task tracking, planning layers, document and image review workflows, and built-in MCP access so AI collaborators can participate in the same operational system instead of living in a separate chat transcript.
+
+Taskforce is currently in beta and under active development.
+
+## What Taskforce includes today
+
+### Core task management
+- Tasks with title, description, status, priority, type, category, assignee, due date, scheduled date, and checklist support
+- Custom workspace taxonomy for categories, types, priorities, approaches, and complexity
+- Task comments and task attachments
+- Schedule board for planning work by day
+- Archive and restore flows for completed or cancelled work
+
+### Planning model
+- Initiatives, workstreams, tasks, and checklists
+- Workstream and initiative assignment for tasks
+- Initiative templates for reusable planning structures such as launch, migration, or incident work
+
+### AI collaboration
+- Built-in MCP support for local and cloud usage
+- AI profile resolution and task ownership for agent collaborators
+- MCP tools for reading and updating tasks, planning entities, documents, image reviews, schedules, and attachments
+- Local MCP configuration for local clients such as Codex, Claude Code CLI, and Gemini CLI
+- Cloud MCP token flow for remote clients
+
+### Document and image review
+- Canonical document assets with document review sessions and threaded review comments
+- Image Notes for visual review with saved annotation sessions and markers
+- MCP helper flows for document review and image review
+
+### Runtime and deployment model
+- Local runtime and cloud runtime support
+- Separate app, site, and admin surfaces in the repo
+- Auth, billing, and account flows for the hosted product
+- Workspace sync and cloud/local runtime routing infrastructure
+
+## What is intentionally not part of the product right now
+
+These exist in the codebase in some form, but should not be treated as current product surface area.
+
+- **Workflow editor**: currently disabled and should not be presented as an active feature
+- **Embedded widget/in-app overlay version**: not part of the product right now, not tested recently, and likely to be deprecated
+
+The README below reflects the product that is actually safe to describe today.
+
+## Product surfaces
+
+- `apps/app` - the main Taskforce application
+- `apps/site` - the public website / marketing surface
+- `apps/admin` - the admin surface
+
+## Repository structure
+
+```text
+apps/
+  app/          Main product app
+  site/         Public website
+  admin/        Admin surface
+src/
+  components/   UI components and product modules
+  core/         Core application logic
+  server/       Server routes and runtime logic
+  mcp/          MCP runtime and tool registry
+  sync/         Sync model and transfer logic
+  storage/      Persistence and asset storage
+tests/
+  e2e/          Playwright realtime and interactive browser scenarios
+  soak/         Playwright soak and endurance scenarios
+```
 
----
+Most fast regression coverage is colocated beside the code under `src/` and `apps/` as `*.test.ts` and `*.test.tsx` files.
 
-## 🛠️ Getting Started
+## Getting started
 
-### Installation
+### Prerequisites
+- Node.js 20+
+- npm
 
-Recommendation: Install **globally** to use the CLI and MCP server across any project:
+### Install dependencies
 
 ```bash
-npm i -g @taskforcehq/taskforce
+npm ci
 ```
 
-#### 🧪 Trying the Latest Unstable Features
-If you want to test the latest untested/beta version (e.g., `v0.3.13-beta.0`):
+### Run the main app locally
 
 ```bash
-npm i -g @taskforcehq/taskforce@beta
+npm run dev
 ```
 
-Taskforce is installed globally for all supported usage patterns:
+If you need the runtime-oriented local flow used by the product rather than simple frontend dev mode, use the repo scripts documented in `package.json` and the active docs under `docs/reference/` and `docs/runbooks/`.
+
+### Build
 
 ```bash
-npm i -g @taskforcehq/taskforce
+npm run build
 ```
 
-*Note: Taskforce includes a dashboard server, so you can use it with ANY framework (Next.js, Angular, Python, etc.) without needing Vite config.*
-
-### Database Backend (Preparation)
-
-Taskforce currently runs on SQLite by default. Backend selection is scaffolded:
-
-- `TASKFORCE_DB_PROVIDER=sqlite` (default)
-- `TASKFORCE_DB_PROVIDER=postgres` (requires `TASKFORCE_DATABASE_URL`)
-- `TASKFORCE_TENANT_ID=default` (optional; enables tenant scoping groundwork)
-
-Readiness endpoint:
-
-- `GET /api/taskforce/health` returns API + database health state.
-
-Migration prep utilities:
-
-- Postgres schema: `src/migrations/postgres/001_init.sql`
-- SQLite export script: `npm run db:export:postgres` (writes `.taskforce/postgres-bootstrap.sql` by default)
+## MCP
 
-### Cloud App Endpoint Configuration
+Taskforce includes built-in MCP support so AI clients can operate directly against the workspace.
 
-Canonical selectors:
-
-- `TASKFORCE_RUNTIME_MODE=local|cloud`
-- `TASKFORCE_CLOUD_ENVIRONMENT=production|staging|performance`
-
-For cloud deployments where the frontend host differs from the API/websocket host, set:
-
-- `VITE_TASKFORCE_API_BASE_URL` (example: `https://app-api.taskforcehq.ai`)
-- `VITE_TASKFORCE_WS_BASE_URL` (optional; defaults to `VITE_TASKFORCE_API_BASE_URL`)
-
-These `VITE_TASKFORCE_*` variables are endpoint overrides. They are still supported, but `TASKFORCE_CLOUD_ENVIRONMENT` is now the canonical cloud target selector.
-
-For local runtime with cloud-only authentication (while keeping local SQLite task APIs):
-
-- The standalone app is configured to use `https://app.taskforcehq.ai` for cloud auth by default (see `apps/app/main.tsx`).
-- No environment-variable setup is required for end users of the packaged local app.
-
-Behavior:
+### Local MCP
+Use Local MCP for local stdio-based clients. This is the intended path for tools such as:
+- Codex
+- Claude Code CLI
+- Gemini CLI
 
-- `/api/taskforce/*` requests are routed to `VITE_TASKFORCE_API_BASE_URL` when set.
-- websocket connects to `${VITE_TASKFORCE_WS_BASE_URL}/taskforce-ws` using `wss` on HTTPS pages.
+Local MCP does not require a cloud token.
 
-### API Auth Gate (Cloud Hardening)
+### Cloud MCP
+Use Cloud MCP for hosted remote clients. Cloud MCP uses token-based access and the hosted MCP endpoint.
 
-To protect API routes at the application layer (in addition to Cloudflare Access), configure:
+## Major product capabilities
 
-- `TASKFORCE_RUNTIME_MODE=cloud` (recommended for hosted app; `local` for standalone/local usage)
-- `TASKFORCE_CLOUD_ENVIRONMENT=production|staging|performance`
-- `TASKFORCE_AUTH_ENABLED=true`
-- `TASKFORCE_AUTH_SESSION_SECRET=<strong-random-secret>`
-- `TASKFORCE_EMAIL_PROVIDER=console|resend|google-workspace` (default: `console`)
-- `TASKFORCE_EMAIL_FROM='Taskforce <no-reply@yourdomain.com>'`
-- `TASKFORCE_EMAIL_REPLY_TO='support@yourdomain.com'` (optional)
-- `TASKFORCE_EMAIL_RESEND_API_KEY=<resend-api-key>` (required when provider=`resend`)
-- `TASKFORCE_EMAIL_GOOGLE_APP_PASSWORD=<google-app-password>` (required when provider=`google-workspace`)
-- Optional canonical secret key for either live provider: `TASKFORCE_EMAIL_PROVIDER_API_KEY=<provider-secret>`
-- Note: live delivery provider settings are only configurable in cloud runtime; local runtime uses `console`.
-- For production deliverability, configure sender domain records: SPF, DKIM, and DMARC.
-- Rotate `TASKFORCE_EMAIL_PROVIDER_API_KEY` regularly and use Admin > Settings > Email > `Clear Saved Key` during rotation cutovers.
-- Optional: `TASKFORCE_AUTH_REQUIRED_FOR_API=true` (default `true`)
-- Optional: `TASKFORCE_AUTH_EXCLUDED_PATHS=/api/taskforce/health` (comma-separated)
-- Optional: `TASKFORCE_API_RATE_LIMIT_ENABLED=true` (default `true`)
-- Optional: `TASKFORCE_API_RATE_LIMIT_MAX_REQUESTS=120` (default `120` per `60s`)
-- Optional: `TASKFORCE_API_RATE_LIMIT_WINDOW_MS=60000`
-- Auth rate-limit controls are configured in Admin > System Settings and persisted in Taskforce global settings.
+### 1. Shared task system for humans and AI
+Taskforce is designed so people and AI agents can work from the same task graph, rather than forcing humans to maintain one system and agents to operate from another.
 
-Defaults:
-- `cloud` mode: auth defaults to enabled + required for API routes.
-- `local` mode: guest usage is allowed unless auth is explicitly enabled.
+### 2. Planning beyond flat tasks
+Taskforce supports a planning hierarchy that can represent real work:
+- Initiative
+- Workstream
+- Task
+- Checklist
 
-Request auth options:
+This is meant to support launch work, migrations, larger feature tracks, and other multi-layer efforts.
 
-- `Cookie: taskforce_session=<signed-session-cookie>`
+### 3. Review-native workflows
+Taskforce includes first-class review surfaces for:
+- documents, via document review sessions and comments
+- images, via Image Notes sessions and markers
 
-### Integration
+These are not decorative attachments. They are structured review workflows.
 
-Wrap your app or specific routes with the Taskforce component. It's designed to be transparent.
+### 4. AI-operable product state
+Taskforce exposes product state through MCP so agents can:
+- read tasks and planning structures
+- update status and ownership
+- create and comment on review sessions
+- work with schedules and attachments
 
-Standalone app guide: `docs/guides/widget-standalone-integration.md`
+## What to avoid saying about Taskforce right now
 
-```tsx
-import { Taskforce } from '@taskforcehq/taskforce';
+Do not describe Taskforce as:
+- a production-ready embedded widget product
+- a workflow editor product
+- a generic developer overlay tool
+- something centered only on AI-developer pairs
 
-const App = () => {
-    return (
-        <BrowserRouter>
-            {/* Your Application Logic */}
-            <Taskforce config={{
-                theme: 'midnight',
-                categories: ['Frontend', 'Backend', 'Refactor'],
-                position: 'bottom-right'
-            }} />
-        </BrowserRouter>
-    );
-};
-```
+That undersells or misstates where the product is now.
 
----
+A better framing is:
 
-## 🖥️ Usage Modes
+> Taskforce is a task and planning system for humans collaborating with AI, with built-in review workflows and MCP access.
 
-Taskforce adapts to your current working style.
+## Development notes
 
-### 📊 The Dashboard
-For heavy-duty project management. Drag-and-drop task prioritization, bulk archiving, and deep-linking support for sharing specific tasks.
+### Validation
+Useful local checks include:
 
-To launch dashboard mode (works in any project folder):
 ```bash
-npx @taskforcehq/taskforce open [port]
-# Example: npx @taskforcehq/taskforce open 5174
+npm run build
+npm run test
 ```
 
-### App/Website Surfaces
-
-- `apps/app` - full product app source (built to `dist/ui`, served by standalone server / Railway runtime).
-- `apps/site` - public website/landing source (Cloudflare Pages).
-- `apps/admin` - admin web surface source (Cloudflare Pages).
-- `taskforce open` behavior is unchanged and continues to use the built app bundle in `dist/ui`.
-
-### Local Runtime Sync Troubleshooting
-
-- `npm run dev:runtime` serves the built app output from `dist`, while `vite build --watch` keeps that bundle fresh.
-- Before changing sync logic, confirm the watched build actually rebuilt, restart the local CLI/runtime if behavior still looks stale, and then retest sync.
-- If a sync bug seems "fixed in code but still reproducible," treat stale build output or a long-lived local runtime process as the first thing to rule out.
-
-### Local Validation Runbooks
-
-These checks used to exist as manual-only GitHub Actions workflows, but they now live as local runbooks to avoid burning Actions credits.
-
-- Full surface validation:
-  - `npm ci`
-  - `npm run check:deploy-preflight`
-  - `npm run build:app`
-  - `npm run build:site`
-  - `npm run build:admin`
-  - `npm run test -- src/server/auth.test.ts src/server/routes.test.ts src/server/cors.test.ts`
-- Auth and runtime guard:
-  - `npm ci`
-  - `npm run test:auth-runtime-guard`
-- Sync regression guard:
-  - `npm ci`
-  - `npx vitest src/sync/workspaceSyncModel.test.ts src/sync/syncService.test.ts src/sync/cloudSyncApi.test.ts src/hooks/useWorkspaceSyncController.test.ts src/hooks/useSyncOrchestrator.retry-closure.test.tsx src/server/routes.sync.integration.test.ts src/server/routes.test.ts`
-  - optional realtime attachment check: `npm run test:e2e:realtime:attachments`
-
-### 🧭 Initiatives
-Initiatives provide template-based planning for complex work (for example `launch`, `migration`, `incident`) with reusable Definition of Done and Rollback checklist blocks.
-
-Guide: `docs/guides/initiatives-guide.md`
-
-Initiative API endpoints:
-- `GET /api/taskforce/initiative-templates`
-- `POST /api/taskforce/initiative-templates/create`
-- `POST /api/taskforce/initiative-templates/clone-checklists`
-
----
-
-## 🤖 AI Superpowers (MCP Server)
-
-Empower your AI agents to be productive members of your team. By exposing Taskforce via the Model Context Protocol, your agent can:
-
-- **Discover**: Find where tasks are stored and what specialists are available.
-- **Plan**: Create complex multi-step choreographies for large features.
-- **Refine**: Update task statuses as code is written and tests are passed.
-
-### Local MCP
-Use `Settings > MCP > Local MCP` for local stdio clients. Taskforce generates the config for you, including:
-
-- the local command and args
-- any required env vars
-- optional advanced path-mapping guidance for Docker / WSL / remote-dev setups
-
-Local MCP does **not** require a cloud token.
-Local runtime uses MCP over stdio, not over the app's HTTP server. In local runtime, `taskforce mcp <project-path>` is the MCP entrypoint; the app's `/mcp` HTTP endpoint is cloud-only.
-
-### Cloud MCP
-Use `Settings > MCP > Cloud MCP` for remote MCP clients. The app provides:
-
-- workspace-scoped token generation
-- client-specific configuration output and instructions
-- a `Test Connection` flow for troubleshooting
-
-Cloud MCP uses the hosted `/mcp` endpoint and a bearer token instead of local filesystem paths.
-If you see `/mcp` return a cloud-runtime-only error on a local app instance, that is expected behavior: use Local MCP (stdio) for local clients and Cloud MCP (hosted `/mcp`) for remote clients.
-
-### Current client status
-Validated cloud/client paths:
-- Antigravity
-- Codex
-- Claude Code CLI
-- Gemini CLI
-
-Implemented cloud config output, still worth manual validation in your environment:
-- Cursor
-- Cline
-- VS Code / Copilot
-- Windsurf
-
-Not yet supported in the cloud flow:
-- Claude Desktop
-- ChatGPT Desktop
-
-ChatGPT support is blocked on OAuth. Claude Desktop remains disabled until connector-auth behavior is validated for Taskforce.
-
----
-
-## ⚙️ Configuration
-
-| Option | Type | Default | Description |
-|:---|:---|:---|:---|
-| `theme` | `'dark' \| 'light' \| 'midnight'` | `'dark'` | Visual aesthetic style. |
-| `categories` | `CategoryConfig[]` | `['General']` | Custom groupings with specific path mapping. |
-| `taxonomies` | `TaxonomyDefinition[]` | `[]` | Advanced custom metadata fields for tasks. |
-
----
-
-## 🧱 Project Architecture
+Testing guidance lives in:
 
-- `apps/app/` - Product app entrypoint (`index.html`, `main.tsx`, websocket hook).
-- `apps/site/` - Public website source.
-- `apps/admin/` - Admin web surface source.
-- `src/config/surfaceBase.ts` - single source-of-truth for Vite surface base paths (`app`, `site`, `admin`).
-- `src/StandalonePage.tsx` - High-density management board.
-- `src/TaskforceCore.tsx` - Shared state and UI primitives.
-- `src/mcp/` - Native Model Context Protocol implementation.
-- `src/types.ts` - Centralized contract for project state.
+- `docs/reference/engineering/test-infrastructure.md`
+- `docs/runbooks/sync-soak-runbook.md`
+- `docs/reference/operations/external-qa-workflow.md`
 
-Deployment runbooks:
-- `docs/launch/deployment-surfaces.md`
-- `docs/launch/runtime-boundaries.md`
-- `docs/launch/stage0-slo-observability.md`
-- `docs/launch/docker-runtime-runbook.md`
+### Important docs
+- `docs/reference/engineering/test-infrastructure.md`
+- `docs/reference/platform/runtime-modes-contract.md`
+- `docs/reference/operations/external-qa-workflow.md`
+- `docs/runbooks/sync-soak-runbook.md`
 
----
+## Status
 
-<p align="center">
-  Built with ❤️ by <a href="https://taskforcehq.ai">Taskforce HQ</a>.
-</p>
+Taskforce is in active beta development. The product surface is moving, so this README is intentionally conservative and only describes capabilities that are complete enough to stand behind today.