Update docs, add getting started guide, CI, and future plans

Documentation:
- Rewrite docs/cli.md to match current command tree (add task detail,
  task search, board audit/overview, delivery list; remove old audit
  and search commands)
- Rewrite docs/http-api.md to include all current endpoints (/me,
  task_detail, task_search, board_overview, SSE, delivery list),
  fix min roles, add all server config env vars
- Add Getting Started guide to README with actor creation workflow

Server:
- Support TASKFLOW_SEED_ADMIN_KEY env var for deterministic seed keys
  (useful for CI and automation)

CI:
- Add GitHub Actions workflow: fmt check, vet, unit/integration tests
  with race detector, QA smoke test, Docker build + push to Docker Hub

Infrastructure:
- Include taskflow-mcp in Dockerfile

Future plans:
- Capture pagination and dashboard improvements as active plans

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: bricef

.github/workflows/ci.yml

@@ -0,0 +1,65 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-go@v5
+        with:
+          go-version-file: go.mod
+
+      - name: Check formatting
+        run: test -z "$(gofmt -l .)" || (echo "Files need formatting:" && gofmt -l . && exit 1)
+
+      - name: Vet
+        run: go vet ./...
+
+      - name: Unit and integration tests
+        run: go test -count=1 -race ./...
+
+      - name: Build all binaries
+        run: |
+          go build -o taskflow-server ./cmd/taskflow-server
+          go build -o taskflow ./cmd/taskflow
+          go build -o taskflow-mcp ./cmd/taskflow-mcp
+
+      - name: QA smoke test
+        run: |
+          # Install jq for the QA script.
+          sudo apt-get install -qy jq
+          ./scripts/qa-test.sh
+
+  docker:
+    needs: test
+    runs-on: ubuntu-latest
+    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Log in to Docker Hub
+        uses: docker/login-action@v3
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+      - name: Build and push
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          push: true
+          tags: |
+            ${{ secrets.DOCKERHUB_USERNAME }}/taskflow:latest
+            ${{ secrets.DOCKERHUB_USERNAME }}/taskflow:${{ github.sha }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max

Dockerfile

@@ -8,6 +8,7 @@ COPY . .
 
 RUN CGO_ENABLED=0 go build -o /taskflow-server ./cmd/taskflow-server
 RUN CGO_ENABLED=0 go build -o /taskflow ./cmd/taskflow
+RUN CGO_ENABLED=0 go build -o /taskflow-mcp ./cmd/taskflow-mcp
 
 # Runtime stage
 FROM alpine:3.21
@@ -16,6 +17,7 @@ RUN apk add --no-cache ca-certificates
 
 COPY --from=builder /taskflow-server /usr/local/bin/taskflow-server
 COPY --from=builder /taskflow /usr/local/bin/taskflow
+COPY --from=builder /taskflow-mcp /usr/local/bin/taskflow-mcp
 
 RUN mkdir -p /data
 WORKDIR /data

README.md

@@ -2,27 +2,72 @@
 
 TaskFlow is a task tracker designed for fluid collaboration between humans and AI agents. It provides a durable server as the single source of truth, with tasks organized on kanban boards that have explicitly configured workflow state machines. Any actor — human or AI — can create, advance, review, and manage tasks, with a full audit trail recording every action with actor attribution and timestamps.
 
-## Quick Start
+## Getting Started
+
+### 1. Start the server
 
 ```bash
-# Option 1: Docker Compose (recommended)
+# Option A: Docker Compose
 just docker-up
-docker compose exec taskflow cat /data/seed-admin-key.txt
 
-# Option 2: Run locally
+# Option B: Run locally
 just build
 just run
-cat seed-admin-key.txt
+```
+
+On first start, the server creates a seed admin actor and writes the API key to `seed-admin-key.txt`. The admin name defaults to the value of `TASKFLOW_SEED_ADMIN_NAME` (set to `admin` in docker-compose.yml).
+
+```bash
+# Get the seed admin key
+cat seed-admin-key.txt                              # local
+docker compose exec taskflow cat /data/seed-admin-key.txt  # Docker
+```
+
+To set a specific key instead of a random one (useful for CI/automation):
 
-# Use the CLI
+```bash
+TASKFLOW_SEED_ADMIN_NAME=admin TASKFLOW_SEED_ADMIN_KEY=my-known-key ./taskflow-server
+```
+
+### 2. Configure the CLI
+
+```bash
 export TASKFLOW_API_KEY=$(cat seed-admin-key.txt)
+# Or add to config file:
+# echo "api_key: $(cat seed-admin-key.txt)" >> ~/.config/taskflow/config.yaml
+```
+
+### 3. Create a board and tasks
+
+```bash
 taskflow board create --slug my-board --name "My Board"
 taskflow task create my-board --title "Fix auth bug" --priority high
 taskflow task list my-board
 taskflow task transition my-board 1 --transition start --comment "On it"
+```
+
+### 4. Add more actors
+
+Create actors for team members and AI agents. Each gets their own API key for identity and audit attribution.
+
+```bash
+# Create a human member
+taskflow actor create --name alice --display_name "Alice Chen" --type human --role member
+
+# Create an AI agent
+taskflow actor create --name claude --display_name "Claude" --type ai_agent --role member
+```
+
+The API key is returned in the response (shown once). Share it with the actor for CLI, TUI, or MCP configuration.
+
+### 5. Use other interfaces
+
+```bash
+# TUI — interactive terminal UI
+TASKFLOW_API_KEY=<key> taskflow-tui
 
-# Or use the TUI
-taskflow-tui
+# MCP — AI agent integration (see docs/mcp.md)
+TASKFLOW_API_KEY=<agent-key> taskflow-mcp
 ```
 
 ## Documentation

cmd/taskflow-server/main.go

@@ -79,9 +79,15 @@ func seedAdmin(svc taskflow.TaskFlow) error {
 		return nil // actors already exist, skip seeding
 	}
 
-	apiKey, err := generateAPIKey()
-	if err != nil {
-		return fmt.Errorf("generating API key: %w", err)
+	// Allow setting the seed admin key via environment variable.
+	// If not set, generate a random one.
+	apiKey := os.Getenv("TASKFLOW_SEED_ADMIN_KEY")
+	if apiKey == "" {
+		var err error
+		apiKey, err = generateAPIKey()
+		if err != nil {
+			return fmt.Errorf("generating API key: %w", err)
+		}
 	}
 
 	displayName := envOr("TASKFLOW_SEED_ADMIN_DISPLAY_NAME", name)

docs/cli.md

@@ -1,6 +1,6 @@
 # TaskFlow CLI
 
-The `taskflow` CLI is a thin HTTP client that calls the TaskFlow server. Commands are derived automatically from the domain operation definitions — adding a new server operation makes it available in the CLI with no additional code.
+The `taskflow` CLI is a thin HTTP client that calls the TaskFlow server. Commands are derived automatically from the domain model — every Resource and Operation in the model becomes a CLI command.
 
 ## Configuration
 
@@ -38,34 +38,46 @@ taskflow actor get      <name>
 taskflow actor update   <name> [--display_name <name>] [--role <role>] [--active <bool>]
 ```
 
+### admin
+
+```
+taskflow admin stats                                    # system-wide statistics (admin only)
+```
+
 ### board
 
 ```
-taskflow board create   --slug <slug> --name <name> --workflow <json>
+taskflow board create   --slug <slug> --name <name> [--workflow <json>]
 taskflow board list     [--include_deleted]
 taskflow board get      <slug>
 taskflow board update   <slug> [--name <name>] [--description <desc>]
-taskflow board delete   <slug>
+taskflow board delete   <slug>                          # soft-delete (admin only)
 taskflow board reassign <slug> --target_board <slug> [--states <state1,state2>]
+taskflow board detail   <slug>                          # full board dump
+taskflow board overview <slug>                          # task counts by state
+taskflow board audit    <slug>                          # board audit log
 ```
 
 ### task
 
 ```
-taskflow task create     <slug> --title <title> [--description <desc>] [--priority <priority>] [--tags <t1,t2>]
+taskflow task create     <slug> --title <title> [--description <desc>] [--priority <priority>] [--tags <t1,t2>] [--assignee <name>]
 taskflow task list       <slug> [--state <state>] [--assignee <name>] [--priority <p>] [--tag <tag>] [--q <search>]
                                 [--sort <field>] [--order <asc|desc>] [--include_closed] [--include_deleted]
 taskflow task get        <slug> <num>
-taskflow task update     <slug> <num> [--title <title>] [--description <desc>] [--priority <p>] [--tags <t1,t2>]
+taskflow task detail     <slug> <num>                   # task with comments, deps, attachments, audit
+taskflow task update     <slug> <num> [--title <title>] [--description <desc>] [--priority <p>] [--tags <t1,t2>] [--assignee <name>]
 taskflow task transition <slug> <num> --transition <name> [--comment <text>]
 taskflow task delete     <slug> <num>
+taskflow task search     [--q <query>] [--state <state>] [--assignee <name>] [--priority <p>] [--include_closed]
+taskflow task audit      <slug> <num>                   # task audit log
 ```
 
 ### workflow
 
 ```
 taskflow workflow get    <slug>
-taskflow workflow set    <slug>          (reads workflow JSON from stdin or --workflow flag)
+taskflow workflow set    <slug>                          # reads workflow JSON from --workflow flag
 taskflow workflow health <slug>
 ```
 
@@ -103,34 +115,22 @@ taskflow webhook update  <id> [--url <url>] [--events <e1,e2>] [--active <bool>]
 taskflow webhook delete  <id>
 ```
 
-### audit
+### delivery
 
 ```
-taskflow audit list <slug> <num>       # task audit log
-taskflow audit list <slug>             # board audit log
+taskflow delivery list   <id>                           # webhook delivery attempts
 ```
 
-### Convenience commands
+### tag
 
 ```
-taskflow board detail <slug>                         # complete board dump (tasks, comments, deps, audit)
-taskflow admin stats                                 # system-wide statistics
-taskflow search --q <query> [--state] [--assignee] [--priority]  # cross-board search
+taskflow tag list        <slug>                         # tags in use on a board
 ```
 
-## Input Validation
-
-The CLI validates required flags before making HTTP requests. Missing required flags show an error with usage:
-
-```
-$ taskflow webhook create
-Usage:
-  taskflow webhook create [flags]
-...
-missing required flag(s): --url, --events, --secret
-```
+## Special Values
 
-Optional fields (like `--description`, `--tags`) are not required.
+- **`@me`** — use as `--assignee @me` to assign tasks to yourself or filter by your own tasks
+- **Priority values** — `critical`, `high`, `medium`, `low`, or omit for none
 
 ## Output Formats