Update documentation for releases, versioning, and key rotation

README:
- Add Releasing section (just release, CI pipeline, Watchtower deploy)
- Add versioning note under Deployment
- Update build comment to mention all binaries
- Fix endpoint count (43)

ARCHITECTURE.md:
- Add Versioning section (build-time ldflags, headers, client checks)
- Document API key generation on actor create and key rotation

docs/http-api.md:
- Add PATCH /actors/{name}/rotate-key
- Note that POST /actors returns API key once

docs/cli.md:
- Add actor rotate_key command
- Document key lifecycle (create returns key, rotate, deactivate)

docs/mcp.md:
- Add actor_rotate_key tool

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

Author: bricef

ARCHITECTURE.md

@@ -253,9 +253,18 @@ Each board has a workflow defined as a JSON state machine:
 
 The workflow engine validates transitions, enforces terminal states, and provides health checks (detecting tasks orphaned in states with no outgoing transitions). Workflows are validated on board creation and replacement.
 
+## Versioning
+
+All binaries embed a version string from `git describe --tags --always` at build time via ldflags. The `internal/version.Version` variable defaults to `"dev"` if not set.
+
+- Server adds `X-TaskFlow-Version` to all response headers
+- `/health` includes `version` in the JSON response
+- MCP reports the version during capability negotiation
+- The httpclient checks the server version on the first request and warns on stderr if versions differ or the header is missing
+
 ## Authentication and RBAC
 
-API keys are SHA-256 hashed and stored with actor records. Three roles:
+API keys are SHA-256 hashed and stored with actor records. Creating an actor via the API generates a random key and returns it once in the response. Keys can be rotated with `PATCH /actors/{name}/rotate-key` — the old key is immediately invalidated. Three roles:
 
 | Role | Permissions |
 |------|------------|

README.md

@@ -111,7 +111,7 @@ TASKFLOW_URL=http://localhost:8374 TASKFLOW_API_KEY=<agent-key> taskflow-mcp
 ## Features
 
 - HTTP API with auth (SHA-256 keys), RBAC, idempotency keys, and batch operations
-- 42 domain endpoints (19 Resources + 23 Operations) auto-derived from the model
+- 43 domain endpoints (19 Resources + 24 Operations) auto-derived from the model
 - OpenAPI 3.1 spec auto-generated at startup
 - CLI with commands derived from the same model
 - Interactive TUI with kanban, list, workflow graph, and live event stream — see **[TUI Reference](docs/tui.md)**
@@ -208,7 +208,7 @@ Requires Go 1.25+ and [just](https://github.com/casey/just).
 just check          # fmt-check + vet + test (full suite)
 just test           # unit + integration + QA smoke test (45 endpoint checks)
 just test-unit      # unit + integration tests only (no server startup)
-just build          # build server + CLI binaries
+just build          # build all binaries (server, CLI, TUI, MCP)
 just run            # start the server locally
 just fmt            # format code
 just seed           # generate test database
@@ -222,13 +222,30 @@ just clean          # remove build artifacts
 
 Set `TASKFLOW_DEV_MODE=true` to disable all rate limiting (useful for testing and development). See [TESTING.md](TESTING.md) for the full manual QA checklist.
 
-### Deployment note
+### Releasing
+
+```bash
+just release v0.1.2
+```
+
+This creates an annotated git tag and pushes it. CI then:
+1. Runs the full test suite
+2. Cross-compiles binaries for linux/amd64, linux/arm64, darwin/amd64, darwin/arm64
+3. Creates a GitHub Release with downloadable archives and auto-generated release notes
+4. Builds and pushes Docker images tagged `:latest`, `:sha`, and `:v0.1.2`
+5. Watchtower deploys the new image to the VPS within 3 minutes
+
+To build release archives locally: `just dist` (outputs to `dist/`).
+
+### Deployment
 
 The server must be hosted at the root of a domain (e.g. `https://taskflow.example.com`). Hosting at a subpath (e.g. `/taskflow`) is not currently supported — the dashboard, OpenAPI spec, and SSE endpoints generate absolute paths without a configurable prefix.
 
+All binaries embed a version string from `git describe` at build time. The server exposes it via the `X-TaskFlow-Version` response header and the `/health` endpoint. Clients warn on stderr if their version differs from the server.
+
 ### Testing with the simulator
 
-The activity simulator generates realistic board activity for testing SSE live updates:
+The activity simulator generates realistic board activity for testing live updates:
 
 ```bash
 # Terminal 1: server with test database

docs/cli.md

@@ -32,12 +32,15 @@ api_key: your-api-key-here
 ### actor
 
 ```
-taskflow actor create   --name <name> --display_name <name> --type <human|ai_agent> --role <admin|member|read_only>
+taskflow actor create      --name <name> --display_name <name> --type <human|ai_agent> --role <admin|member|read_only>
 taskflow actor list
-taskflow actor get      <name>
-taskflow actor update   <name> [--display_name <name>] [--role <role>] [--active <bool>]
+taskflow actor get         <name>
+taskflow actor update      <name> [--display_name <name>] [--role <role>] [--active <bool>]
+taskflow actor rotate_key  <name>                         # generate new API key (shown once)
 ```
 
+Creating an actor returns the API key in the response (shown once — save it). Use `rotate_key` to generate a new key if compromised. Use `update --active false` to deactivate an actor (revokes access, preserves audit history).
+
 ### admin
 
 ```

docs/http-api.md

@@ -77,9 +77,10 @@ curl "/boards/my-board/tasks?assignee=@me" -H "Authorization: Bearer $KEY"
 
 | Method | Path | Description | Min Role |
 |--------|------|-------------|----------|
-| POST | `/actors` | Create an actor | admin |
+| POST | `/actors` | Create an actor (returns API key once) | admin |
 | GET | `/actors` | List all actors | read_only |
 | GET | `/actors/{name}` | Get an actor by name | read_only |
+| PATCH | `/actors/{name}/rotate-key` | Rotate API key (returns new key once) | admin |
 | PATCH | `/actors/{name}` | Update an actor | admin |
 
 ### Self

docs/mcp.md

@@ -122,6 +122,7 @@ Tools are mutations that change state. Path parameters and body fields are passe
 | Tool | Description | Key Inputs |
 |------|-------------|------------|
 | `actor_create` | Create an actor (admin) | `name`, `type`, `role` |
+| `actor_rotate_key` | Rotate an actor's API key (admin) | `name` |
 | `actor_update` | Update an actor (admin) | `name`, fields to change |
 | `webhook_create` | Create a webhook (admin) | `url`, `events`, `secret` |
 | `webhook_update` | Update a webhook (admin) | `id`, fields to change |