@desplega.ai/agent-swarm 1.20.0 → 1.49.0

package/CLAUDE.md

@@ -1,10 +1,43 @@
-# Agent Swarm MCP
+# Agent Swarm
 
-Multi-agent orchestration layer for Claude Code, Codex, Gemini CLI. Enables task distribution, agent communication, and service discovery.
+Multi-agent orchestration for Claude Code, Codex, Gemini CLI. Enables task distribution, agent communication, and service discovery.
 
 **Getting Started**: See [CONTRIBUTING.md](./CONTRIBUTING.md) for setup. Run `bun run start:http` to start the server.
 
-**Database**: Uses `bun:sqlite` (SQLite with WAL mode). DB file at `./agent-swarm-db.sqlite` (auto-created). Schema defined in `src/be/db.ts`.
+**Database**: Uses `bun:sqlite` (SQLite with WAL mode). DB file at `./agent-swarm-db.sqlite` (auto-created). Schema defined in `src/be/migrations/` as numbered SQL files, run by `src/be/migrations/runner.ts`. Query functions in `src/be/db.ts`.
+
+### Database Migrations
+
+Schema changes use a file-based migration system (`src/be/migrations/`):
+
+```bash
+# Migration files: numbered SQL files executed in order
+src/be/migrations/
+  001_initial.sql    # Baseline: all tables, indexes, seed data
+  runner.ts          # Migration runner (auto-runs on startup)
+```
+
+**Adding a new migration:**
+1. Create `src/be/migrations/NNN_descriptive_name.sql` (next number after highest existing)
+2. Write forward-only SQL (CREATE TABLE, ALTER TABLE, CREATE INDEX, etc.)
+3. Test with both fresh DB (`rm agent-swarm-db.sqlite && bun run start:http`) and existing DB
+4. The runner applies it automatically on next startup
+
+**How it works:**
+- `_migrations` table tracks which migrations have been applied (version, name, checksum)
+- On startup, runner compares SQL files against `_migrations` and applies pending ones
+- Each migration runs in a transaction — atomic success or rollback
+- Checksums detect accidental edits to applied migrations (logged as warnings)
+- Bootstrap is schema-aware for pre-migration DBs:
+  - If baseline tables already exist, runner marks `001_initial` as applied without re-executing it
+  - If schema is partial/incomplete, runner executes `001_initial` to reach baseline safely
+- `initDb()` also runs compatibility guards after migrations for legacy DBs (for example, adding missing `agents` profile columns before seeding context versions)
+
+**Rules:**
+- Never modify an already-applied migration — create a new one instead
+- No `down` migrations (SQLite limitations make rollbacks unreliable)
+- Use `IF NOT EXISTS` for CREATE TABLE/INDEX in migrations for safety
+- Keep the `AgentTaskSourceSchema` in `src/types.ts` in sync with CHECK constraints in SQL
 
 ## Quick Reference
 
@@ -43,21 +76,141 @@ src/
   cli.tsx       # CLI entry point (Ink)
   tools/        # MCP tool definitions
   be/           # Backend utilities (DB, storage)
+    db.ts       # DB init + query functions
+    migrations/ # SQL migration files + runner
   github/       # GitHub webhook handlers
   slack/        # Slack integration
-ui/             # Dashboard (separate React app)
+new-ui/          # Dashboard (Next.js app)
+templates/       # Template data (official + community)
+  official/      # 9 official templates (lead, coder, researcher, reviewer, tester, fde, content-writer, content-reviewer, content-strategist)
+  community/     # Community-contributed templates
+  schema.ts      # Shared TypeScript types
+templates-ui/    # Templates registry (Next.js app)
 ```
 
+## Architecture Invariants
+
+**Worker/API DB boundary**: The API server (`src/http.ts`, `src/server.ts`, `src/tools/`, `src/http/`) is the **sole owner** of the SQLite database. Worker-side code (`src/commands/`, `src/hooks/`, `src/providers/`, `src/prompts/`, `src/cli.tsx`, `src/claude.ts`) must **never** import from `src/be/db` or `bun:sqlite`. Workers communicate with the API exclusively via HTTP using `API_KEY` and `X-Agent-ID` headers.
+
+Enforced by `scripts/check-db-boundary.sh` (pre-push hook + CI merge gate). If you need to share pure logic between API and worker code, put it in a shared module (e.g., `src/prompts/`, `src/utils/`).
+
 ## Code Style
 
 - Run `bun run lint:fix` before committing (lint + format)
 - Run `bun run format` for formatting only
 - Use Bun APIs, not Node.js equivalents
 - Prefer `Bun.$` over execa for shell commands
+- Use `google/gemini-3-flash-preview` as the default Gemini model in tests, workflows, and examples (not `gemini-2.0-flash-001`)
+
+### CLI Commands & Help System
+
+CLI help is plain `console.log` (not Ink), defined in `src/cli.tsx` via the `COMMAND_HELP` record and `printHelp()` function.
+
+**When adding or modifying CLI commands:**
+1. Add/update the command's entry in the `COMMAND_HELP` record (usage, description, options, examples)
+2. Add the command to the `commands` array in `printHelp()` (general help listing)
+3. Add routing in the `App` switch statement (UI commands) or the non-UI section before `render()` (simple commands like `docs`, `help`, `version`)
+4. Run `bun run src/cli.tsx help` and `bun run src/cli.tsx <command> --help` to verify
+
+**Command types:**
+- **Non-UI commands** (handled before `render()`): `help`, `version`, `docs`, `hook`, `artifact` — use `console.log` + `process.exit(0)`
+- **UI commands** (rendered by Ink): `onboard`, `connect`, `api`, `claude`, `worker`, `lead` — return JSX from the `App` switch
+
+### Adding HTTP Endpoints
+
+**Always use the `route()` factory** from `src/http/route-def.ts` when creating new REST endpoints. This auto-registers the route in the OpenAPI spec. Do NOT use raw `matchRoute` — it bypasses OpenAPI generation.
+
+```typescript
+// In src/http/my-feature.ts
+import { route } from "./route-def";
+
+const myRoute = route({
+  method: "post",
+  path: "/api/my-feature",
+  pattern: ["api", "my-feature"],
+  summary: "What this endpoint does",
+  tags: ["MyTag"],
+  body: z.object({ ... }),
+  responses: { 200: { description: "Success" }, 400: { description: "Error" } },
+  auth: { apiKey: true },
+});
+
+export async function handleMyFeature(req, res, pathSegments, queryParams): Promise<boolean> {
+  if (!myRoute.match(req.method, pathSegments)) return false;
+  const parsed = await myRoute.parse(req, res, pathSegments, queryParams);
+  if (!parsed) return true; // parse() already sent 400
+  // ... business logic using parsed.body, parsed.params, parsed.query
+  json(res, result);
+  return true;
+}
+```
+
+After creating the handler:
+1. Import and add to handler chain in `src/http/index.ts`
+2. Add the import to `scripts/generate-openapi.ts` (for spec generation)
+3. Run `bun run docs:openapi` to regenerate `openapi.json` and commit it
+
+## Workflow Authoring Guide
+
+Workflows are defined as a DAG of nodes connected via `next`. Key concepts for creating workflows with `create-workflow`:
+
+### Cross-node data access (`inputs` mapping)
+
+**By default, upstream step outputs are NOT available for interpolation.** Only `trigger` (trigger data) and `input` (workflow-level resolved inputs) are in scope. To access another node's output, you MUST declare an `inputs` mapping:
+
+```json
+{
+  "id": "summarize",
+  "type": "agent-task",
+  "inputs": { "cityData": "generate-city" },
+  "config": {
+    "template": "The city is {{cityData.taskOutput.city}} in {{cityData.taskOutput.country}}"
+  }
+}
+```
+
+- Keys are local names used in `{{interpolation}}`, values are context paths (usually a node ID)
+- Agent-task output shape is `{ taskId: string, taskOutput: <agent's JSON> }`, so access fields via `localName.taskOutput.field`
+- For trigger data: `{ "pr": "trigger.pullRequest" }` → `{{pr.number}}`
+- Without `inputs`, templates referencing upstream nodes silently resolve to empty strings (check `diagnostics.unresolvedTokens` on the step)
+
+### Structured output (`outputSchema`)
+
+There are **two different `outputSchema` locations** — they validate at different layers:
+
+| Location | Validates | Example schema |
+|----------|-----------|---------------|
+| `config.outputSchema` (inside config) | The **agent's raw JSON** response | `{ type: "object", required: ["city"], properties: { city: { type: "string" } } }` |
+| Node-level `outputSchema` (sibling of config) | The **executor's return** (`{ taskId, taskOutput }` for agent-task) | Rarely needed — executor schemas are built-in |
+
+For agent-task nodes, put your schema in `config.outputSchema`. The agent will be prompted to produce JSON matching this schema, and `store-progress` validates it inline.
+
+### Interpolation
+
+- Syntax: `{{path.to.value}}` in any string field inside `config`
+- Paths traverse the interpolation context (built from `inputs` + `trigger` + `input`)
+- Objects are JSON-stringified, nulls resolve to empty string
+- Unresolved tokens are logged in step `diagnostics` and the step proceeds (soft failure)
+
+### Agent-task executor config fields
+
+```
+template       (required) — Task description / prompt for the agent
+outputSchema   (optional) — JSON Schema for agent's structured output
+agentId        (optional) — Assign to specific agent (UUID)
+tags           (optional) — Task tags for filtering
+priority       (optional) — 0-100, default 50
+offerMode      (optional) — Offer to agent instead of direct assign
+dir            (optional) — Working directory for the agent
+vcsRepo        (optional) — Git repo for workspace scoping
+model          (optional) — Model override for the agent
+parentTaskId   (optional) — Link to parent task
+```
 
 ## Related
 
-- [UI Dashboard](./ui/CLAUDE.md) - React monitoring dashboard
+- [UI Dashboard](./new-ui/) - Next.js monitoring dashboard
+- [Templates Registry](./templates-ui/) - Template gallery and compose builder
 - [MCP.md](./MCP.md) - MCP tools reference
 - [DEPLOYMENT.md](./DEPLOYMENT.md) - Production deployment
 - [CONTRIBUTING.md](./CONTRIBUTING.md) - Development setup
@@ -83,6 +236,270 @@ curl -H "Authorization: Bearer 123123" -H "X-Agent-ID: <uuid>" http://localhost:
 - `API_KEY` - Auth token for API requests
 - `MCP_BASE_URL` - API server URL (default: http://localhost:3013)
 - `SLACK_DISABLE=true` / `GITHUB_DISABLE=true` - Disable integrations locally
+- `HARNESS_PROVIDER` - Provider selection: `claude` (default) or `pi` (pi-mono)
+- `TEMPLATE_ID` - Template for initial worker profile (e.g., `official/coder`). Fetched from registry on first boot.
+- `TEMPLATE_REGISTRY_URL` - Templates registry URL (default: https://templates.agent-swarm.dev)
+
+**Portless (local dev):**
+`bun run dev:http` uses [portless](https://port1355.dev/) → `https://api.swarm.localhost:1355`. Set `MCP_BASE_URL=https://api.swarm.localhost:1355` and `APP_URL=https://ui.swarm.localhost:1355` in `.env`. Update `.mcp.json` URL to match. Non-portless fallback: `bun run start:http`. Worktrees auto-get `<branch>.api.swarm.localhost:1355` subdomains.
+
+**Local Docker Compose (builds from source):**
+```bash
+# Runs: API + Claude lead + Pi-mono worker
+docker compose -f docker-compose.local.yml up --build
+
+# Tear down
+docker compose -f docker-compose.local.yml down
+```
+Requires `.env` with `API_KEY`, `CLAUDE_CODE_OAUTH_TOKEN`, `ANTHROPIC_API_KEY` (or `OPENROUTER_API_KEY`).
+
+**Production Docker Compose (pulls from registry):** See `docker-compose.example.yml`.
+
+---
+
+## Testing
+
+### Unit Tests
+
+```bash
+bun test src/tests/<test-file>.test.ts   # Run specific test
+bun test                                  # Run all tests
+```
+
+- Tests use isolated SQLite DBs (e.g. `./test-<name>.sqlite`) with `initDb()`/`closeDb()` in `beforeAll`/`afterAll`
+- Tests that need HTTP use a minimal `node:http` handler — NOT the full `src/http.ts` server
+- Use unique test ports to avoid conflicts (e.g. 13022, 13023)
+- Clean up DB files (including `-wal` and `-shm`) in `afterAll`
+
+### E2E Testing with Docker
+
+For full integration tests (session capture, `--resume`, hooks), use a Docker worker against a local API server.
+
+**Worktree port check**: When working in a worktree, other worktrees may already be running the API server on port 3013. Always check `.env` for `PORT` and `MCP_BASE_URL` first:
+
+```bash
+lsof -i :3013    # Check if default port is in use
+```
+
+If occupied, set `PORT=<alt-port>` in `.env` and update `MCP_BASE_URL` to match. Also update `.env.docker` `MCP_BASE_URL` (use `host.docker.internal:<port>`):
+
+```bash
+# Start API on alternate port
+PORT=3014 bun run start:http &
+
+# Build image with current code changes
+docker build -f Dockerfile.worker -t agent-swarm-worker:<tag> .
+
+# Run worker pointing at alternate port, on alternate host port
+docker run --rm -d \
+  --name e2e-test-worker \
+  --env-file .env.docker \
+  -e MCP_BASE_URL=http://host.docker.internal:3014 \
+  -e MAX_CONCURRENT_TASKS=1 \
+  -p 3203:3000 \
+  agent-swarm-worker:<tag>
+```
+
+**E2E flow**:
+1. Start API server (check port first)
+2. Rebuild Docker image: `bun run docker:build:worker` (or with custom tag)
+3. Start worker container pointing at your API port
+4. Create tasks via `curl` against the API
+5. Poll `GET /api/tasks/:id` to verify status, `claudeSessionId`, etc.
+6. Check worker logs: `docker logs <container-name>`
+7. Clean up: `docker stop <container-name>` and kill the API process
+
+**Task cancellation caveat**: Direct DB updates (`sqlite3 ... UPDATE`) bypass the hook-based cancellation flow. The Claude process inside Docker won't stop — you'll need to `docker restart` the container. Use the MCP `cancel-task` tool for proper cancellation when possible.
+
+**Keep test tasks trivial**: Use simple tasks like "Say hi" for E2E tests. Complex tasks (web searches, research) waste time and API credits during testing.
+
+**Quick E2E setup (clean DB + API + Docker lead/worker):**
+
+```bash
+# 1. Clean DB for fresh state
+rm -f agent-swarm-db.sqlite agent-swarm-db.sqlite-wal agent-swarm-db.sqlite-shm
+
+# 2. Start API server (NOT pm2 — it starts extra services)
+bun run start:http &
+
+# 3. Build Docker image with current code
+bun run docker:build:worker
+
+# 4a. Start a LEAD container (uses .env.docker-lead)
+docker run --rm -d \
+  --name e2e-test-lead \
+  --env-file .env.docker-lead \
+  -e AGENT_ROLE=lead \
+  -e MAX_CONCURRENT_TASKS=1 \
+  -p 3201:3000 \
+  agent-swarm-worker:latest
+
+# 4b. Start a WORKER container (uses .env.docker)
+docker run --rm -d \
+  --name e2e-test-worker \
+  --env-file .env.docker \
+  -e MAX_CONCURRENT_TASKS=1 \
+  -p 3203:3000 \
+  agent-swarm-worker:latest
+
+# 5. Verify registration
+curl -s -H "Authorization: Bearer 123123" http://localhost:3013/api/agents | jq '.agents[] | {name, isLead, status}'
+
+# 6. Cleanup
+docker stop e2e-test-lead e2e-test-worker
+kill $(lsof -ti :3013)
+```
+
+Key differences between lead and worker env files:
+- `.env.docker-lead` — lead-specific `AGENT_ID`, no `OPENROUTER_API_KEY`
+- `.env.docker` — worker-specific `AGENT_ID`, includes `OPENROUTER_API_KEY`
+- `AGENT_ROLE=lead` must be passed explicitly (not in the env file)
+
+### Entrypoint Integration Testing
+
+When modifying `docker-entrypoint.sh` (e.g. adding new conditional bootstrap logic), validate beyond `bash -n` syntax checks with a full Docker round-trip:
+
+1. **Validate API endpoints first**: Before Docker testing, verify the exact HTTP methods and paths used by `curl` calls in the entrypoint against the actual route definitions in `src/http/`. Common gotcha: config API uses `PUT /api/config` (not `POST`). Use `context-mode execute` for curl calls to avoid hook blocks.
+2. **Test idempotency**: Start a container (first boot = registers), stop it, start another with the same env file (same `AGENT_ID`). Second boot should skip registration via the config check (e.g. `if [ -z "$SOME_KEY" ]`).
+3. **Test failure mode**: Stop the external service, boot a container. The entrypoint should continue (via `|| true` guards) with a warning log.
+4. **Test lead vs worker paths**: Use `.env.docker-lead` + `-e AGENT_ROLE=lead` for lead, `.env.docker` for worker. They have different `AGENT_ID` values and different bootstrap paths.
+5. **Grep logs for your feature**: `docker logs <name> 2>&1 | grep -i "<feature>"` to verify the exact log lines.
+6. **Verify persisted state**: After boot, check `GET /api/config?includeSecrets=true` to confirm secrets/config were stored correctly.
+
+**Entrypoint E2E commands:**
+```bash
+# 1. Clean DB + start API
+rm -f agent-swarm-db.sqlite agent-swarm-db.sqlite-wal agent-swarm-db.sqlite-shm
+bun run start:http &
+
+# 2. Set any required global config (use PUT, not POST!)
+curl -s -X PUT "http://localhost:3013/api/config" \
+  -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
+  -d '{"scope":"global","key":"SOME_KEY","value":"some-value","isSecret":false}'
+
+# 3. Build image with current code
+bun run docker:build:worker
+
+# 4. First boot (lead)
+docker run --rm -d --name e2e-lead \
+  --env-file .env.docker-lead -e AGENT_ROLE=lead \
+  -e MAX_CONCURRENT_TASKS=1 -p 3201:3000 agent-swarm-worker:latest
+
+# 5. First boot (worker)
+docker run --rm -d --name e2e-worker \
+  --env-file .env.docker \
+  -e MAX_CONCURRENT_TASKS=1 -p 3203:3000 agent-swarm-worker:latest
+
+# 6. Check logs (wait ~15s for boot)
+docker logs e2e-lead 2>&1 | grep -i "<feature>"
+docker logs e2e-worker 2>&1 | grep -i "<feature>"
+
+# 7. Idempotency: stop and restart same worker (same AGENT_ID)
+docker stop e2e-worker
+docker run --rm -d --name e2e-worker-2 \
+  --env-file .env.docker \
+  -e MAX_CONCURRENT_TASKS=1 -p 3203:3000 agent-swarm-worker:latest
+# Should see "Already registered" or equivalent skip message
+docker logs e2e-worker-2 2>&1 | grep -i "<feature>"
+
+# 8. Cleanup
+docker stop e2e-lead e2e-worker-2 2>/dev/null
+kill $(lsof -ti :3013) 2>/dev/null
+```
+
+### MCP Tool Testing (Streamable HTTP)
+
+To test MCP tools via curl, you need a proper session handshake:
+
+```bash
+# 1. Initialize session (capture session ID from response headers)
+curl -s -D /tmp/mcp-headers.txt -X POST \
+  -H "Authorization: Bearer $API_KEY" \
+  -H "Content-Type: application/json" \
+  -H "Accept: application/json, text/event-stream" \
+  -H "X-Agent-ID: <uuid>" \
+  http://localhost:$PORT/mcp \
+  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}'
+
+# 2. Extract session ID
+SESSION_ID=$(grep -i 'mcp-session-id' /tmp/mcp-headers.txt | awk '{print $2}' | tr -d '\r\n')
+
+# 3. Send initialized notification
+curl -s -X POST \
+  -H "Authorization: Bearer $API_KEY" \
+  -H "Content-Type: application/json" \
+  -H "Accept: application/json, text/event-stream" \
+  -H "X-Agent-ID: <uuid>" \
+  -H "mcp-session-id: $SESSION_ID" \
+  http://localhost:$PORT/mcp \
+  -d '{"jsonrpc":"2.0","method":"notifications/initialized"}'
+
+# 4. Call tools using the session
+curl -s -X POST \
+  -H "Authorization: Bearer $API_KEY" \
+  -H "Content-Type: application/json" \
+  -H "Accept: application/json, text/event-stream" \
+  -H "X-Agent-ID: <uuid>" \
+  -H "mcp-session-id: $SESSION_ID" \
+  http://localhost:$PORT/mcp \
+  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"join-swarm","arguments":{...}}}'
+```
+
+Key gotchas:
+- `Accept` header MUST include both `application/json` and `text/event-stream`
+- `X-Agent-ID` must be a valid UUID (use `uuidgen` to generate)
+- Session must be initialized before calling tools
+
+### UI Testing
+
+Use the `qa-use` tool (`/qa-use:test-run`, `/qa-use:verify`, `/qa-use:explore`) for browser-based UI testing of the dashboard.
+
+**Worktree port check for UI**: The dashboard dev server defaults to port 5274 (see `APP_URL` in `.env`). Check before starting:
+
+```bash
+lsof -i :5274    # Check if UI port is in use
+```
+
+If occupied by another worktree, start on an alternate port and update `APP_URL`:
+
+```bash
+cd ui && pnpm run dev --port 5275
+```
+
+The UI connects to the API via `VITE_API_URL` (defaults to `http://localhost:3013`). When using alternate API ports, update accordingly in the UI `.env` or pass as env var.
+
+---
+
+## Pre-PR Checklist
+
+Before pushing a PR, run the checks that CI will enforce. Which checks to run depends on what files you changed:
+
+**Root project (src/, tools/, etc.):**
+```bash
+bun run lint:fix             # Biome lint + format
+bun run tsc:check            # TypeScript type check
+bun test                     # Unit tests
+bash scripts/check-db-boundary.sh  # Worker/API DB boundary
+```
+
+**If you changed `plugin/commands/*.md`:** Rebuild pi-mono skills and commit the result:
+```bash
+bun run build:pi-skills  # Regenerate plugin/pi-skills/ from commands
+```
+CI enforces freshness — the merge gate will fail if generated pi-skills are out of date.
+
+**new-ui/ (dashboard):**
+```bash
+cd new-ui
+pnpm lint               # Biome check (lint + format)
+pnpm exec tsc --noEmit  # TypeScript type check
+```
+
+**Both:** Run both sets if your changes span root and new-ui.
+
+**Docker changes (Dockerfile, Dockerfile.worker):** CI does a build test — verify locally with `docker build -f <Dockerfile> .` if unsure.
+
+All of these are enforced by the Merge Gate workflow (`.github/workflows/merge-gate.yml`). The gate job blocks merge if any check fails.
 
 ---
 

package/CONTRIBUTING.md

@@ -1,6 +1,6 @@
 # Contributing to Agent Swarm
 
-Thanks for your interest in contributing to Agent Swarm MCP!
+Thanks for your interest in contributing to Agent Swarm!
 
 ## Table of Contents
 
@@ -89,6 +89,51 @@ bun run docker:run:worker
 bun run docker:run:lead
 ```
 
+### Local Development with Portless
+
+[Portless](https://port1355.dev/) replaces port numbers with friendly domain URLs:
+- API: `https://api.swarm.localhost:1355`
+- UI: `https://ui.swarm.localhost:1355`
+
+**One-time setup:**
+
+```bash
+bun add -g portless
+portless trust                    # Add CA to system trust store
+portless proxy start --https      # Start HTTPS proxy (runs as daemon)
+```
+
+**Usage:**
+
+```bash
+# Start API
+bun run dev:http
+# → https://api.swarm.localhost:1355
+
+# Start UI (separate terminal)
+cd new-ui && pnpm dev
+# → https://ui.swarm.localhost:1355
+
+# Or start everything with PM2
+bun run pm2-start
+```
+
+**Environment:** Set these in your `.env`:
+
+```bash
+MCP_BASE_URL=https://api.swarm.localhost:1355
+APP_URL=https://ui.swarm.localhost:1355
+```
+
+Update `.mcp.json`:
+```json
+{ "url": "https://api.swarm.localhost:1355/mcp" }
+```
+
+**Worktrees:** Each worktree gets a unique subdomain from the branch name. `.wts-setup.ts` handles this automatically.
+
+**Without portless:** Use `bun run start:http` (no portless required).
+
 ---
 
 ## Code Quality

package/DEPLOYMENT.md

@@ -1,6 +1,6 @@
 # Deployment Guide
 
-This guide covers all deployment options for Agent Swarm MCP.
+This guide covers all deployment options for Agent Swarm.
 
 ## Table of Contents
 
@@ -41,6 +41,10 @@ docker-compose up -d
 
 > **Note:** `.env.example` contains API server settings, `.env.docker.example` contains Docker worker settings. For docker-compose, you need both sets of variables in a single `.env` file.
 
+### ARM Compatibility (Apple Silicon)
+
+All services in the docker-compose files include `platform: linux/amd64` to avoid `no matching manifest for linux/arm64/v8` errors on Apple Silicon Macs. The Docker images are built for `linux/amd64` and run via Rosetta emulation.
+
 ### What's Included
 
 The example `docker-compose.yml` sets up:
@@ -48,6 +52,7 @@ The example `docker-compose.yml` sets up:
 - **API service** (port 3013) - MCP HTTP server
 - **2 Worker agents** - Containerized Claude workers
 - **1 Lead agent** - Coordinator agent
+- **3 Content agents** (optional) - Content writer, reviewer, and strategist using `TEMPLATE_ID` for profile bootstrapping
 
 ### Configuration
 
@@ -57,6 +62,7 @@ Edit your `.env` file:
 # Required
 API_KEY=your-secret-api-key
 CLAUDE_CODE_OAUTH_TOKEN=your-oauth-token  # Run `claude setup-token` to get this
+# Multiple tokens for load balancing: CLAUDE_CODE_OAUTH_TOKEN=token1,token2,token3
 
 # Agent IDs (optional, auto-generated if not set)
 AGENT_ID=worker-1-uuid
@@ -111,6 +117,9 @@ docker build -f Dockerfile.worker -t agent-swarm-worker .
 
 # Or using npm script
 bun run docker:build:worker
+
+# Override the pinned Claude Code version (default: 2.1.80)
+docker build -f Dockerfile.worker --build-arg CLAUDE_CODE_VERSION=2.2.0 -t agent-swarm-worker .
 ```
 
 ### Run
@@ -177,9 +186,9 @@ The Docker worker image uses a multi-stage build:
 - **Languages**: Python 3, Node.js 22, Bun
 - **Build tools**: gcc, g++, make, cmake
 - **Process manager**: PM2 (for background services)
-- **CLI tools**: GitHub CLI (`gh`), sqlite3
-- **Agent tools**: `wts` (git worktree manager), `cc-ai-tracker` (code change tracking)
-- **Utilities**: git, git-lfs, vim, nano, jq, curl, wget, ssh
+- **CLI tools**: GitHub CLI (`gh`), GitLab CLI (`glab`), sqlite3
+- **Agent tools**: `wts` (git worktree manager), `archil` (FUSE/R2-backed storage)
+- **Utilities**: git, git-lfs, vim, nano, jq, curl, wget, ssh, fuse3
 - **Sudo access**: Worker can install packages with `sudo apt-get install`
 
 **Volumes:**
@@ -337,11 +346,13 @@ When a worker starts, it:
 
 ## Environment Variables
 
+> For the complete reference of all environment variables, see [docs/ENVS.md](./docs/ENVS.md).
+
 ### Docker Worker Variables
 
 | Variable | Required | Description |
 |----------|----------|-------------|
-| `CLAUDE_CODE_OAUTH_TOKEN` | Yes | OAuth token for Claude CLI (run `claude setup-token`) |
+| `CLAUDE_CODE_OAUTH_TOKEN` | Yes | OAuth token for Claude CLI (run `claude setup-token`). Supports comma-separated values for [multi-credential load balancing](./docs/ENVS.md#multi-credential-support). |
 | `API_KEY` | Yes | API key for MCP server |
 | `AGENT_ID` | No | Agent UUID (assigned on join if not set). **Keep stable for task resume.** |
 | `AGENT_ROLE` | No | Role: `worker` (default) or `lead` |
@@ -355,7 +366,9 @@ When a worker starts, it:
 | `SHUTDOWN_TIMEOUT` | No | Grace period in ms before pausing tasks (default: `30000`) |
 | `MAX_CONCURRENT_TASKS` | No | Maximum parallel tasks per worker (default: `1`) |
 | `SWARM_URL` | No | Base domain for service URLs (default: `localhost`) |
-| `SERVICE_PORT` | No | Host port for exposed services (default: `3000`) |
+| `LEAD_PORT` | No | Host port for lead service (default: `3020`). Example — adjust to your setup. In isolated network namespaces all services can share the same port. |
+| `WORKER1_PORT` | No | Host port for worker-1 service (default: `3021`). Example — see `LEAD_PORT`. |
+| `WORKER2_PORT` | No | Host port for worker-2 service (default: `3022`). Example — see `LEAD_PORT`. |
 | `PM2_HOME` | No | PM2 state directory (default: `/workspace/.pm2`) |
 | `GITHUB_TOKEN` | No | GitHub token for git operations |
 | `GITHUB_EMAIL` | No | Git commit email (default: `worker-agent@desplega.ai`) |
@@ -375,6 +388,8 @@ When a worker starts, it:
 | `ENV` | Environment mode (`development` adds prefix to Slack agent names) | - |
 | `SCHEDULER_INTERVAL_MS` | Polling interval for scheduled tasks | `10000` |
 | `DATABASE_PATH` | SQLite database file path | `./agent-swarm-db.sqlite` |
+| `OPENAI_API_KEY` | OpenAI key for memory embeddings (optional) | - |
+| `CAPABILITIES` | Comma-separated feature flags | All enabled |
 
 ---
 
@@ -384,10 +399,12 @@ Enable Slack for task creation and agent communication via direct messages.
 
 ### Setup
 
-1. Create a Slack App at https://api.slack.com/apps
+1. Create a Slack App at https://api.slack.com/apps (or import `slack-manifest.json` from the repo root)
 2. Enable Socket Mode (for real-time events without public webhooks)
-3. Add required scopes: `chat:write`, `users:read`, `users:read.email`, `channels:history`, `im:history`
-4. Install to workspace and copy tokens
+3. Enable Interactivity and Assistant View
+4. Add required scopes: `app_mentions:read`, `assistant:write`, `channels:history`, `channels:read`, `chat:write`, `chat:write.customize`, `chat:write.public`, `commands`, `files:read`, `files:write`, `groups:history`, `groups:read`, `im:history`, `im:read`, `im:write`, `mpim:history`, `mpim:read`, `mpim:write`, `reactions:write`, `users:read`
+5. Subscribe to bot events: `app_mention`, `assistant_thread_started`, `assistant_thread_context_changed`, `message.channels`, `message.groups`, `message.im`, `message.mpim`
+6. Install to workspace and copy tokens
 
 ### Configuration
 

package/Dockerfile

@@ -24,6 +24,8 @@ FROM debian:bookworm-slim
 RUN apt-get update && apt-get install -y --no-install-recommends \
     ca-certificates \
     wget \
+    curl \
+    fuse3 libfuse2 \
     && rm -rf /var/lib/apt/lists/*
 
 WORKDIR /app
@@ -35,11 +37,19 @@ RUN chmod +x /usr/local/bin/agent-swarm-api
 # Copy package.json for version info
 COPY package.json ./
 
+# Copy migration SQL files (compiled binary can't read from /$bunfs virtual filesystem)
+COPY src/be/migrations/*.sql /app/migrations/
+
+# Install archil CLI for FUSE/R2-backed disk mounts
+RUN curl https://s3.amazonaws.com/archil-client/install | sh
+
 # Create data directory for SQLite (WAL mode needs .sqlite, .sqlite-wal, .sqlite-shm on same filesystem)
-RUN mkdir -p /app/data
+# Create Archil mount point directories
+RUN mkdir -p /app/data /mnt/data /workspace/shared
 
 ENV PORT=3013
 ENV DATABASE_PATH=/app/data/agent-swarm-db.sqlite
+ENV MIGRATIONS_DIR=/app/migrations
 
 VOLUME /app/data
 
@@ -49,9 +59,7 @@ EXPOSE 3013
 HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
   CMD wget -qO- http://localhost:3013/health || exit 1
 
-# Print version on startup and run the server
-CMD echo "=== Agent Swarm API v$(cat /app/package.json | grep '\"version\"' | cut -d'"' -f4) ===" && \
-    echo "Port: $PORT" && \
-    echo "Database: $DATABASE_PATH" && \
-    echo "==============================" && \
-    exec /usr/local/bin/agent-swarm-api
+COPY api-entrypoint.sh /api-entrypoint.sh
+RUN chmod +x /api-entrypoint.sh
+
+ENTRYPOINT ["/api-entrypoint.sh"]