scriptoriumadmin/veritas-kanban
1
0
Fork 0
mirror of https://github.com/BradGroux/veritas-kanban.git synced 2026-08-28 10:54:59 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 1

fix: update default API port from 3001 to 3002 across codebase

Browse source 
Avoids conflict with OpenClaw gateway on port 3001.
Updated: server config, docs, README, WebSocket hook.
This commit is contained in:
V.K. Watson 2026-02-20 21:11:40 -06:00
parent 095a181b5f
commit 1b7a9feb03
32 changed files with 309 additions and 309 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

28
README.md
View file

@ -272,7 +272,7 @@ All gates are toggleable via `PATCH /api/settings/features` under the `enforceme
▼
┌──────────────────────────────┐
│ REST API + WebSocket │
│ http://localhost:3001 │
│ http://localhost:3002 │
│ │
│ ┌───────┐ ┌───────────┐ │
│ │ Tasks │ │ Workflows │ │
@ -348,7 +348,7 @@ All API endpoints support versioned paths. The current (and default) version is
Every response includes an `X-API-Version: v1` header. Clients may optionally request a specific version:
```bash
curl -H "X-API-Version: v1" http://localhost:3001/api/tasks
curl -H "X-API-Version: v1" http://localhost:3002/api/tasks
```
- **Non-breaking changes** (new fields, new endpoints) are added to the current version.
@ -385,13 +385,13 @@ The `vk begin` and `vk done` commands replace multi-step API workflows with sing
**Before (6 separate curl calls):**
```bash
curl -X PATCH http://localhost:3001/api/tasks/<id> -H "Content-Type: application/json" -d '{"status":"in-progress"}'
curl -X POST http://localhost:3001/api/tasks/<id>/time/start
curl -X POST http://localhost:3001/api/agent/status -H "Content-Type: application/json" -d '{"status":"working","taskId":"<id>","taskTitle":"Title"}'
curl -X PATCH http://localhost:3002/api/tasks/<id> -H "Content-Type: application/json" -d '{"status":"in-progress"}'
curl -X POST http://localhost:3002/api/tasks/<id>/time/start
curl -X POST http://localhost:3002/api/agent/status -H "Content-Type: application/json" -d '{"status":"working","taskId":"<id>","taskTitle":"Title"}'
# ... work happens ...
curl -X POST http://localhost:3001/api/tasks/<id>/time/stop
curl -X PATCH http://localhost:3001/api/tasks/<id> -H "Content-Type: application/json" -d '{"status":"done"}'
curl -X POST http://localhost:3001/api/tasks/<id>/comments -H "Content-Type: application/json" -d '{"author":"agent","text":"summary"}'
curl -X POST http://localhost:3002/api/tasks/<id>/time/stop
curl -X PATCH http://localhost:3002/api/tasks/<id> -H "Content-Type: application/json" -d '{"status":"done"}'
curl -X POST http://localhost:3002/api/tasks/<id>/comments -H "Content-Type: application/json" -d '{"author":"agent","text":"summary"}'
```
**After (2 commands):**
@ -500,17 +500,17 @@ Built and tested with [OpenClaw](https://github.com/openclaw/openclaw) (formerly
```bash
# Create a task
curl -X POST http://localhost:3001/api/tasks \
curl -X POST http://localhost:3002/api/tasks \
-H "Content-Type: application/json" \
-H "X-API-Key: $YOUR_KEY" \
-d '{"title": "Implement feature X", "type": "code", "status": "in-progress"}'
# Start time tracking
curl -X POST http://localhost:3001/api/tasks/<id>/time/start \
curl -X POST http://localhost:3002/api/tasks/<id>/time/start \
-H "X-API-Key: $YOUR_KEY"
# Mark complete
curl -X POST http://localhost:3001/api/agents/<id>/complete \
curl -X POST http://localhost:3002/api/agents/<id>/complete \
-H "Content-Type: application/json" \
-H "X-API-Key: $YOUR_KEY" \
-d '{"success": true, "summary": "What was done"}'
@ -520,11 +520,11 @@ curl -X POST http://localhost:3001/api/agents/<id>/complete \
```bash
# Trigger a manual sync
curl -X POST http://localhost:3001/api/github/sync \
curl -X POST http://localhost:3002/api/github/sync \
-H "X-API-Key: $YOUR_KEY"
# Check sync status
curl http://localhost:3001/api/github/sync/status \
curl http://localhost:3002/api/github/sync/status \
-H "X-API-Key: $YOUR_KEY"
```
@ -553,7 +553,7 @@ For AI assistants (Claude Desktop, etc.):
"command": "node",
"args": ["/path/to/veritas-kanban/mcp/dist/index.js"],
"env": {
"VK_API_URL": "http://localhost:3001"
"VK_API_URL": "http://localhost:3002"
}
}
}

14
docs/AGENT-REGISTRY.md
View file

@ -257,7 +257,7 @@ Removes the agent from the registry entirely.
Every agent must register itself when it starts working. This is the **first thing** you do.
```bash
curl -s -X POST http://localhost:3001/api/agents/register \
curl -s -X POST http://localhost:3002/api/agents/register \
-H 'Content-Type: application/json' \
-d '{
"id": "YOUR_AGENT_NAME",
@ -275,7 +275,7 @@ curl -s -X POST http://localhost:3001/api/agents/register \
Update your status to `busy` with the task info:
```bash
curl -s -X POST http://localhost:3001/api/agents/register/YOUR_AGENT_NAME/heartbeat \
curl -s -X POST http://localhost:3002/api/agents/register/YOUR_AGENT_NAME/heartbeat \
-H 'Content-Type: application/json' \
-d '{
"status": "busy",
@ -289,7 +289,7 @@ curl -s -X POST http://localhost:3001/api/agents/register/YOUR_AGENT_NAME/heartb
Send heartbeats to stay marked as online. If you skip this for 5 minutes, the registry marks you `offline`.
```bash
curl -s -X POST http://localhost:3001/api/agents/register/YOUR_AGENT_NAME/heartbeat \
curl -s -X POST http://localhost:3002/api/agents/register/YOUR_AGENT_NAME/heartbeat \
-H 'Content-Type: application/json' \
-d '{"status": "busy"}'
```
@ -299,7 +299,7 @@ curl -s -X POST http://localhost:3001/api/agents/register/YOUR_AGENT_NAME/heartb
Clear the task assignment and go idle:
```bash
curl -s -X POST http://localhost:3001/api/agents/register/YOUR_AGENT_NAME/heartbeat \
curl -s -X POST http://localhost:3002/api/agents/register/YOUR_AGENT_NAME/heartbeat \
-H 'Content-Type: application/json' \
-d '{
"status": "idle",
@ -315,17 +315,17 @@ When the orchestrator (VERITAS) spawns a sub-agent via `sessions_spawn`, include
```
FIRST ACTION (before any other work):
1. Register yourself with Veritas Kanban:
curl -s -X POST http://localhost:3001/api/agents/register \
curl -s -X POST http://localhost:3002/api/agents/register \
-H 'Content-Type: application/json' \
-d '{"id":"AGENT_NAME","name":"AGENT_NAME","model":"MODEL","provider":"anthropic","capabilities":[{"name":"SKILL"}],"version":"2.0.0","metadata":{"role":"ROLE"}}'
2. Set yourself as busy on the task:
curl -s -X POST http://localhost:3001/api/agents/register/AGENT_NAME/heartbeat \
curl -s -X POST http://localhost:3002/api/agents/register/AGENT_NAME/heartbeat \
-H 'Content-Type: application/json' \
-d '{"status":"busy","currentTaskId":"TASK_ID","currentTaskTitle":"TASK_TITLE"}'
3. When finished, set idle:
curl -s -X POST http://localhost:3001/api/agents/register/AGENT_NAME/heartbeat \
curl -s -X POST http://localhost:3002/api/agents/register/AGENT_NAME/heartbeat \
-H 'Content-Type: application/json' \
-d '{"status":"idle","currentTaskId":null,"currentTaskTitle":null}'
```

28
docs/AGENTS-TEMPLATE.md
View file

@ -29,7 +29,7 @@ List what this agent can do. Used for task routing.
On startup, register with Veritas Kanban:
```bash
curl -X POST http://localhost:3001/api/agents/register \
curl -X POST http://localhost:3002/api/agents/register \
-H 'Content-Type: application/json' \
-d '{
"id": "my-agent-id",
@ -49,7 +49,7 @@ curl -X POST http://localhost:3001/api/agents/register \
Send periodic heartbeats to stay registered (every 2-3 minutes):
```bash
curl -X POST http://localhost:3001/api/agents/register/my-agent-id/heartbeat \
curl -X POST http://localhost:3002/api/agents/register/my-agent-id/heartbeat \
-H 'Content-Type: application/json' \
-d '{
"status": "busy",
@ -72,7 +72,7 @@ curl -X POST http://localhost:3001/api/agents/register/my-agent-id/heartbeat \
On shutdown, deregister cleanly:
```bash
curl -X DELETE http://localhost:3001/api/agents/register/my-agent-id
curl -X DELETE http://localhost:3002/api/agents/register/my-agent-id
```
## Discovery
@ -80,31 +80,31 @@ curl -X DELETE http://localhost:3001/api/agents/register/my-agent-id
### List all agents
```bash
curl http://localhost:3001/api/agents/register
curl http://localhost:3002/api/agents/register
```
### Filter by status
```bash
curl http://localhost:3001/api/agents/register?status=online
curl http://localhost:3002/api/agents/register?status=online
```
### Filter by capability
```bash
curl http://localhost:3001/api/agents/register?capability=code
curl http://localhost:3002/api/agents/register?capability=code
```
### Find agents for a capability
```bash
curl http://localhost:3001/api/agents/register/capabilities/research
curl http://localhost:3002/api/agents/register/capabilities/research
```
### Registry stats
```bash
curl http://localhost:3001/api/agents/register/stats
curl http://localhost:3002/api/agents/register/stats
```
## Task Integration
@ -126,7 +126,7 @@ The dashboard's **Success Rate**, **Token Usage**, and **Average Run Duration**
### When Starting a Task
```bash
curl -X POST http://localhost:3001/api/telemetry/events \
curl -X POST http://localhost:3002/api/telemetry/events \
-H "Content-Type: application/json" \
-d '{"type":"run.started","taskId":"<TASK_ID>","agent":"my-agent-id"}'
```
@ -135,12 +135,12 @@ curl -X POST http://localhost:3001/api/telemetry/events \
```bash
# Report run result (success or failure)
curl -X POST http://localhost:3001/api/telemetry/events \
curl -X POST http://localhost:3002/api/telemetry/events \
-H "Content-Type: application/json" \
-d '{"type":"run.completed","taskId":"<TASK_ID>","agent":"my-agent-id","durationMs":<MS>,"success":true}'
# Report token usage (powers Token Usage + Monthly Budget)
curl -X POST http://localhost:3001/api/telemetry/events \
curl -X POST http://localhost:3002/api/telemetry/events \
-H "Content-Type: application/json" \
-d '{"type":"run.tokens","taskId":"<TASK_ID>","agent":"my-agent-id","model":"<MODEL>","inputTokens":<N>,"outputTokens":<N>,"cacheTokens":<N>,"cost":<N>}'
```
@ -148,7 +148,7 @@ curl -X POST http://localhost:3001/api/telemetry/events \
### On Failure
```bash
curl -X POST http://localhost:3001/api/telemetry/events \
curl -X POST http://localhost:3002/api/telemetry/events \
-H "Content-Type: application/json" \
-d '{"type":"run.completed","taskId":"<TASK_ID>","agent":"my-agent-id","durationMs":<MS>,"success":false}'
```
@ -170,10 +170,10 @@ The registry enables agents to discover each other:
```bash
# Find who can help with code review
curl http://localhost:3001/api/agents/register/capabilities/review
curl http://localhost:3002/api/agents/register/capabilities/review
# Check if a specific agent is available
curl http://localhost:3001/api/agents/register/codex-1
curl http://localhost:3002/api/agents/register/codex-1
```
This is the foundation for multi-agent task assignment (#29) and @mention notifications (#30).

10
docs/ANALYTICS.md
View file

@ -31,7 +31,7 @@ Returns timeline data showing task execution periods and parallelism snapshots.
#### Example Request
```bash
curl -X GET "http://localhost:3001/api/analytics/timeline?from=2026-01-01T00:00:00Z&to=2026-02-01T23:59:59Z&project=veritas"
curl -X GET "http://localhost:3002/api/analytics/timeline?from=2026-01-01T00:00:00Z&to=2026-02-01T23:59:59Z&project=veritas"
```
#### Response Schema
@ -107,7 +107,7 @@ Returns aggregate metrics for a time period or sprint.
#### Example Request
```bash
curl -X GET "http://localhost:3001/api/analytics/metrics?sprint=v1.5"
curl -X GET "http://localhost:3002/api/analytics/metrics?sprint=v1.5"
```
#### Response Schema
@ -350,21 +350,21 @@ The service reads from:
FROM=$(date -u -d '7 days ago' +%Y-%m-%dT%H:%M:%SZ)
TO=$(date -u +%Y-%m-%dT%H:%M:%SZ)
curl -s "http://localhost:3001/api/analytics/timeline?from=$FROM&to=$TO" | \
curl -s "http://localhost:3002/api/analytics/timeline?from=$FROM&to=$TO" | \
jq '.data.parallelism | max_by(.concurrentTaskCount)'
```
### Example 2: Get Sprint Metrics
```bash
curl -s "http://localhost:3001/api/analytics/metrics?sprint=v1.5" | \
curl -s "http://localhost:3002/api/analytics/metrics?sprint=v1.5" | \
jq '.data.efficiency'
```
### Example 3: Agent Comparison
```bash
curl -s "http://localhost:3001/api/analytics/metrics?from=2026-01-01T00:00:00Z&to=2026-02-01T00:00:00Z" | \
curl -s "http://localhost:3002/api/analytics/metrics?from=2026-01-01T00:00:00Z&to=2026-02-01T00:00:00Z" | \
jq '.data.agentUtilization | sort_by(.durationSeconds) | reverse'
```

72
docs/API-WORKFLOWS.md
View file

@ -2,7 +2,7 @@
**Version**: v3.3
**Last Updated**: 2026-02-15
**Base URL**: `http://localhost:3001/api`
**Base URL**: `http://localhost:3002/api`
---
@ -52,7 +52,7 @@ List all workflows (metadata only, filtered by user permissions).
**Request**:
```bash
curl http://localhost:3001/api/workflows
curl http://localhost:3002/api/workflows
```
**Response**:
@ -97,7 +97,7 @@ Get a specific workflow definition (full YAML content).
**Request**:
```bash
curl http://localhost:3001/api/workflows/feature-dev
curl http://localhost:3002/api/workflows/feature-dev
```
**Response**:
@ -172,7 +172,7 @@ Create a new workflow.
**Request**:
```bash
curl -X POST http://localhost:3001/api/workflows \
curl -X POST http://localhost:3002/api/workflows \
-H "Content-Type: application/json" \
-d '{
"id": "hello-world",
@ -240,7 +240,7 @@ Update an existing workflow (auto-increments version).
**Request**:
```bash
curl -X PUT http://localhost:3001/api/workflows/hello-world \
curl -X PUT http://localhost:3002/api/workflows/hello-world \
-H "Content-Type: application/json" \
-d '{
"id": "hello-world",
@ -314,7 +314,7 @@ Delete a workflow.
**Request**:
```bash
curl -X DELETE http://localhost:3001/api/workflows/hello-world
curl -X DELETE http://localhost:3002/api/workflows/hello-world
```
**Response**:
@ -348,7 +348,7 @@ Start a new workflow run.
**Request**:
```bash
curl -X POST http://localhost:3001/api/workflows/feature-dev/runs \
curl -X POST http://localhost:3002/api/workflows/feature-dev/runs \
-H "Content-Type: application/json" \
-d '{
"taskId": "US-42",
@ -436,16 +436,16 @@ List workflow runs with optional filters.
```bash
# All runs
curl http://localhost:3001/api/workflow-runs
curl http://localhost:3002/api/workflow-runs
# Runs for a specific workflow
curl "http://localhost:3001/api/workflow-runs?workflowId=feature-dev"
curl "http://localhost:3002/api/workflow-runs?workflowId=feature-dev"
# Runs for a specific task
curl "http://localhost:3001/api/workflow-runs?taskId=US-42"
curl "http://localhost:3002/api/workflow-runs?taskId=US-42"
# Failed runs only
curl "http://localhost:3001/api/workflow-runs?status=failed"
curl "http://localhost:3002/api/workflow-runs?status=failed"
```
**Response**:
@ -492,7 +492,7 @@ Get full details of a specific workflow run.
**Request**:
```bash
curl http://localhost:3001/api/workflow-runs/run_20260209_abc123
curl http://localhost:3002/api/workflow-runs/run_20260209_abc123
```
**Response**:
@ -562,7 +562,7 @@ Get currently running workflow runs only.
**Request**:
```bash
curl http://localhost:3001/api/workflow-runs/active
curl http://localhost:3002/api/workflow-runs/active
```
**Response**:
@ -603,7 +603,7 @@ Get aggregated workflow statistics for a given period.
**Request**:
```bash
curl "http://localhost:3001/api/workflow-runs/stats?period=7d"
curl "http://localhost:3002/api/workflow-runs/stats?period=7d"
```
**Response**:
@ -662,7 +662,7 @@ Resume a blocked workflow run (after human approval or escalation).
**Request**:
```bash
curl -X POST http://localhost:3001/api/workflow-runs/run_20260209_abc123/resume \
curl -X POST http://localhost:3002/api/workflow-runs/run_20260209_abc123/resume \
-H "Content-Type: application/json" \
-d '{
"context": {
@ -717,7 +717,7 @@ Approve a gate step (allows workflow to continue).
**Request**:
```bash
curl -X POST http://localhost:3001/api/workflow-runs/run_20260209_abc123/steps/quality-gate/approve
curl -X POST http://localhost:3002/api/workflow-runs/run_20260209_abc123/steps/quality-gate/approve
```
**Response**:
@ -763,7 +763,7 @@ Reject a gate step (marks workflow as failed).
**Request**:
```bash
curl -X POST http://localhost:3001/api/workflow-runs/run_20260209_abc123/steps/quality-gate/reject
curl -X POST http://localhost:3002/api/workflow-runs/run_20260209_abc123/steps/quality-gate/reject
```
**Response**:
@ -797,7 +797,7 @@ Get detailed status of a specific step (useful for parallel sub-steps).
**Request**:
```bash
curl http://localhost:3001/api/workflow-runs/run_20260209_abc123/steps/implement/status
curl http://localhost:3002/api/workflow-runs/run_20260209_abc123/steps/implement/status
```
**Response**:
@ -841,7 +841,7 @@ List all tool policies (default + custom).
**Request**:
```bash
curl http://localhost:3001/api/tool-policies
curl http://localhost:3002/api/tool-policies
```
**Response**:
@ -884,7 +884,7 @@ Get a specific tool policy by role.
**Request**:
```bash
curl http://localhost:3001/api/tool-policies/planner
curl http://localhost:3002/api/tool-policies/planner
```
**Response**:
@ -914,7 +914,7 @@ Create a new custom tool policy.
**Request**:
```bash
curl -X POST http://localhost:3001/api/tool-policies \
curl -X POST http://localhost:3002/api/tool-policies \
-H "Content-Type: application/json" \
-d '{
"role": "custom-auditor",
@ -969,7 +969,7 @@ Update an existing tool policy (including defaults).
**Request**:
```bash
curl -X PUT http://localhost:3001/api/tool-policies/custom-auditor \
curl -X PUT http://localhost:3002/api/tool-policies/custom-auditor \
-H "Content-Type: application/json" \
-d '{
"role": "custom-auditor",
@ -1007,7 +1007,7 @@ Delete a custom tool policy.
**Request**:
```bash
curl -X DELETE http://localhost:3001/api/tool-policies/custom-auditor
curl -X DELETE http://localhost:3002/api/tool-policies/custom-auditor
```
**Response**:
@ -1035,7 +1035,7 @@ Validate if a specific tool is allowed for a role.
**Request**:
```bash
curl -X POST http://localhost:3001/api/tool-policies/planner/validate \
curl -X POST http://localhost:3002/api/tool-policies/planner/validate \
-H "Content-Type: application/json" \
-d '{
"tool": "exec"
@ -1079,7 +1079,7 @@ Get the full dependency graph for a task (recursive tree traversal).
**Request**:
```bash
curl http://localhost:3001/api/tasks/US-42/dependencies
curl http://localhost:3002/api/tasks/US-42/dependencies
```
**Response**:
@ -1140,7 +1140,7 @@ Add a dependency to a task.
**Request**:
```bash
curl -X POST http://localhost:3001/api/tasks/US-42/dependencies \
curl -X POST http://localhost:3002/api/tasks/US-42/dependencies \
-H "Content-Type: application/json" \
-d '{
"dependsOn": "US-40",
@ -1178,7 +1178,7 @@ Remove a dependency from a task.
**Request**:
```bash
curl -X DELETE http://localhost:3001/api/tasks/US-42/dependencies/US-40?direction=depends_on
curl -X DELETE http://localhost:3002/api/tasks/US-42/dependencies/US-40?direction=depends_on
```
**Query Parameters**:
@ -1201,7 +1201,7 @@ Save checkpoint state for a task.
**Request**:
```bash
curl -X POST http://localhost:3001/api/tasks/US-42/checkpoint \
curl -X POST http://localhost:3002/api/tasks/US-42/checkpoint \
-H "Content-Type: application/json" \
-d '{
"state": {
@ -1263,7 +1263,7 @@ Resume checkpoint state for a task.
**Request**:
```bash
curl http://localhost:3001/api/tasks/US-42/checkpoint
curl http://localhost:3002/api/tasks/US-42/checkpoint
```
**Response**:
@ -1307,7 +1307,7 @@ Clear checkpoint state for a task.
**Request**:
```bash
curl -X DELETE http://localhost:3001/api/tasks/US-42/checkpoint
curl -X DELETE http://localhost:3002/api/tasks/US-42/checkpoint
```
**Status Codes**:
@ -1326,7 +1326,7 @@ Add an observation to a task.
**Request**:
```bash
curl -X POST http://localhost:3001/api/observations \
curl -X POST http://localhost:3002/api/observations \
-H "Content-Type: application/json" \
-d '{
"taskId": "US-42",
@ -1384,7 +1384,7 @@ Get all observations for a task.
**Request**:
```bash
curl http://localhost:3001/api/tasks/US-42/observations
curl http://localhost:3002/api/tasks/US-42/observations
```
**Response**:
@ -1429,7 +1429,7 @@ Full-text search across all observations for all tasks.
**Request**:
```bash
curl "http://localhost:3001/api/observations/search?query=react+query&limit=10&offset=0"
curl "http://localhost:3002/api/observations/search?query=react+query&limit=10&offset=0"
```
**Query Parameters**:
@ -1481,7 +1481,7 @@ Delete an observation.
**Request**:
```bash
curl -X DELETE http://localhost:3001/api/observations/obs_abc123
curl -X DELETE http://localhost:3002/api/observations/obs_abc123
```
**Status Codes**:
@ -1504,7 +1504,7 @@ Filter tasks by assigned agent name.
**Request**:
```bash
curl "http://localhost:3001/api/tasks?agent=codex"
curl "http://localhost:3002/api/tasks?agent=codex"
```
**Query Parameters**:
@ -1560,7 +1560,7 @@ All workflow state changes are broadcast via WebSocket for real-time UI updates.
**Connection**:
```javascript
const ws = new WebSocket('ws://localhost:3001/ws');
const ws = new WebSocket('ws://localhost:3002/ws');
ws.onmessage = (event) => {
const message = JSON.parse(event.data);

18
docs/CLI-GUIDE.md
View file

@ -478,30 +478,30 @@ Before v1.4, starting or finishing a task required multiple separate API calls.
```bash
# Starting a task (3 calls)
curl -X PATCH http://localhost:3001/api/tasks/<id> \
curl -X PATCH http://localhost:3002/api/tasks/<id> \
-H "Content-Type: application/json" \
-d '{"status":"in-progress"}'
curl -X POST http://localhost:3001/api/tasks/<id>/time/start
curl -X POST http://localhost:3002/api/tasks/<id>/time/start
curl -X POST http://localhost:3001/api/agent/status \
curl -X POST http://localhost:3002/api/agent/status \
-H "Content-Type: application/json" \
-d '{"status":"working","taskId":"<id>","taskTitle":"Implement OAuth"}'
# ... work happens ...
# Completing a task (4 calls)
curl -X POST http://localhost:3001/api/tasks/<id>/time/stop
curl -X POST http://localhost:3002/api/tasks/<id>/time/stop
curl -X PATCH http://localhost:3001/api/tasks/<id> \
curl -X PATCH http://localhost:3002/api/tasks/<id> \
-H "Content-Type: application/json" \
-d '{"status":"done"}'
curl -X POST http://localhost:3001/api/tasks/<id>/comments \
curl -X POST http://localhost:3002/api/tasks/<id>/comments \
-H "Content-Type: application/json" \
-d '{"author":"agent","text":"Added OAuth2 with Google and GitHub providers"}'
curl -X POST http://localhost:3001/api/agent/status \
curl -X POST http://localhost:3002/api/agent/status \
-H "Content-Type: application/json" \
-d '{"status":"idle"}'
```
@ -612,14 +612,14 @@ The CLI reads configuration from environment variables:
| Variable | Default | Description |
| ------------ | ----------------------- | -------------------------- |
| `VK_API_URL` | `http://localhost:3001` | Veritas Kanban server URL |
| `VK_API_URL` | `http://localhost:3002` | Veritas Kanban server URL |
| `VK_API_KEY` | _(none)_ | API key for authentication |
### Setting the API URL
```bash
# Default — local development
export VK_API_URL=http://localhost:3001
export VK_API_URL=http://localhost:3002
# Remote server
export VK_API_URL=https://kanban.example.com

30
docs/DEPLOYMENT.md
View file

@ -40,11 +40,11 @@ cp server/.env.example server/.env
docker compose up -d --build
# Verify it's running
curl http://localhost:3001/health
curl http://localhost:3002/health
# → {"status":"ok","timestamp":"..."}
```
The app is now available at **http://localhost:3001**.
The app is now available at **http://localhost:3002**.
Data is persisted in a Docker named volume (`kanban-data`), so it survives container restarts.
@ -169,10 +169,10 @@ NODE_ENV=production node server/dist/index.js
The server:
- Serves the API at `http://localhost:3001/api`
- Serves the built React frontend at `http://localhost:3001`
- Provides WebSocket updates at `ws://localhost:3001/ws`
- Exposes API docs at `http://localhost:3001/api-docs`
- Serves the API at `http://localhost:3002/api`
- Serves the built React frontend at `http://localhost:3002`
- Provides WebSocket updates at `ws://localhost:3002/ws`
- Exposes API docs at `http://localhost:3002/api-docs`
### Reverse Proxy (nginx)
@ -266,7 +266,7 @@ Caddy handles TLS automatically:
```caddyfile
kanban.example.com {
reverse_proxy localhost:3001
reverse_proxy localhost:3002
}
```
@ -394,13 +394,13 @@ The API supports three authentication methods:
```bash
# 1. Authorization header (Bearer token)
curl -H "Authorization: Bearer <api-key>" http://localhost:3001/api/tasks
curl -H "Authorization: Bearer <api-key>" http://localhost:3002/api/tasks
# 2. X-API-Key header
curl -H "X-API-Key: <api-key>" http://localhost:3001/api/tasks
curl -H "X-API-Key: <api-key>" http://localhost:3002/api/tasks
# 3. Query parameter (for WebSocket connections)
wscat -c "ws://localhost:3001/ws?api_key=<api-key>"
wscat -c "ws://localhost:3002/ws?api_key=<api-key>"
```
### Role Permissions
@ -524,7 +524,7 @@ docker compose up -d --build
# Verify
docker compose logs -f
curl http://localhost:3001/health
curl http://localhost:3002/health
```
### Bare Metal
@ -545,7 +545,7 @@ pnpm build
sudo systemctl restart veritas-kanban
# Verify
curl http://localhost:3001/health
curl http://localhost:3002/health
sudo journalctl -u veritas-kanban --since "1 min ago"
```
@ -560,7 +560,7 @@ Veritas Kanban runs startup migrations automatically (`runStartupMigrations()` i
The server exposes an unauthenticated health endpoint:
```bash
curl http://localhost:3001/health
curl http://localhost:3002/health
# → {"status":"ok","timestamp":"2026-01-29T12:00:00.000Z"}
```
@ -596,7 +596,7 @@ docker compose logs veritas-kanban
```bash
# Check auth diagnostics (requires admin key)
curl -H "X-API-Key: your-admin-key" http://localhost:3001/api/auth/diagnostics
curl -H "X-API-Key: your-admin-key" http://localhost:3002/api/auth/diagnostics
```
### WebSocket connection refused
@ -618,5 +618,5 @@ node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
The built-in Swagger UI is available at:
```
http://localhost:3001/api-docs
http://localhost:3002/api-docs
```

10
docs/EXAMPLES-agent-workflows.md
View file

@ -125,16 +125,16 @@ See [WORKFLOW-GUIDE.md](WORKFLOW-GUIDE.md) for full YAML examples.
```bash
# Save checkpoint mid-work
curl -X POST http://localhost:3001/api/tasks/US-42/checkpoint \
curl -X POST http://localhost:3002/api/tasks/US-42/checkpoint \
-H "Content-Type: application/json" \
-d '{"state":{"step":3,"completed":["auth","db"],"notes":"Working on API layer"}}'
# After restart, resume from checkpoint
CHECKPOINT=$(curl -s http://localhost:3001/api/tasks/US-42/checkpoint)
CHECKPOINT=$(curl -s http://localhost:3002/api/tasks/US-42/checkpoint)
# Feed $CHECKPOINT into agent prompt for continuity
# Clean up after completion
curl -X DELETE http://localhost:3001/api/tasks/US-42/checkpoint
curl -X DELETE http://localhost:3002/api/tasks/US-42/checkpoint
```
---
@ -145,10 +145,10 @@ curl -X DELETE http://localhost:3001/api/tasks/US-42/checkpoint
```bash
# Log a decision
curl -X POST http://localhost:3001/api/observations \
curl -X POST http://localhost:3002/api/observations \
-H "Content-Type: application/json" \
-d '{"taskId":"US-42","type":"decision","content":"Chose WebSocket over SSE for real-time updates — lower latency, bidirectional","importance":9}'
# Future agent searches before making the same decision
curl "http://localhost:3001/api/observations/search?query=websocket+vs+sse"
curl "http://localhost:3002/api/observations/search?query=websocket+vs+sse"
```

24
docs/FEATURES.md
View file

@ -272,16 +272,16 @@ Save and resume agent state across crashes and restarts with automatic secret sa
```bash
# Save checkpoint
curl -X POST http://localhost:3001/api/tasks/US-42/checkpoint \
curl -X POST http://localhost:3002/api/tasks/US-42/checkpoint \
-H "Content-Type: application/json" \
-d '{"state":{"current_step":3,"completed":["step1","step2"],"api_key":"sk-1234"}}'
# Resume checkpoint (secrets sanitized in response)
curl http://localhost:3001/api/tasks/US-42/checkpoint
curl http://localhost:3002/api/tasks/US-42/checkpoint
# Returns: {"state":{"current_step":3,"completed":["step1","step2"],"api_key":"[REDACTED]"},...}
# Clear checkpoint
curl -X DELETE http://localhost:3001/api/tasks/US-42/checkpoint
curl -X DELETE http://localhost:3002/api/tasks/US-42/checkpoint
```
---
@ -311,15 +311,15 @@ Capture and search critical insights, decisions, blockers, and context across ag
```bash
# Add observation
curl -X POST http://localhost:3001/api/observations \
curl -X POST http://localhost:3002/api/observations \
-H "Content-Type: application/json" \
-d '{"taskId":"US-42","type":"decision","content":"Chose React Query over Redux for simpler data fetching","importance":8}'
# Search across all tasks
curl "http://localhost:3001/api/observations/search?query=react+query&limit=10"
curl "http://localhost:3002/api/observations/search?query=react+query&limit=10"
# Get observations for task
curl http://localhost:3001/api/tasks/US-42/observations
curl http://localhost:3002/api/tasks/US-42/observations
```
---
@ -343,13 +343,13 @@ Query tasks by agent name for precise agent workload tracking.
```bash
# Get all tasks for agent "codex"
curl "http://localhost:3001/api/tasks?agent=codex"
curl "http://localhost:3002/api/tasks?agent=codex"
# Get blocked tasks for agent "veritas"
curl "http://localhost:3001/api/tasks?agent=veritas&status=blocked"
curl "http://localhost:3002/api/tasks?agent=veritas&status=blocked"
# Paginated results
curl "http://localhost:3001/api/tasks?agent=codex&limit=25&offset=0"
curl "http://localhost:3002/api/tasks?agent=codex&limit=25&offset=0"
```
---
@ -555,7 +555,7 @@ Deploy Veritas Kanban behind nginx, Caddy, Traefik, or any reverse proxy.
```nginx
location / {
proxy_pass http://localhost:3001;
proxy_pass http://localhost:3002;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_http_version 1.1;
@ -1243,7 +1243,7 @@ Model Context Protocol server for AI assistant integration (Claude Desktop, etc.
"veritas-kanban": {
"command": "node",
"args": ["/path/to/veritas-kanban/mcp/dist/index.js"],
"env": { "VK_API_URL": "http://localhost:3001" }
"env": { "VK_API_URL": "http://localhost:3002" }
}
}
}
@ -1507,7 +1507,7 @@ RESTful API designed for both human and AI agent consumption.
### Real-Time Updates
- **WebSocket server** — Real-time task change broadcasts on `ws://localhost:3001`
- **WebSocket server** — Real-time task change broadcasts on `ws://localhost:3002`
- **WebSocket connection indicator** — UI shows connected/disconnected status
![WebSocket activity](../assets/scr-menu_websocket_activity.png)

4
docs/GETTING-STARTED.md
View file

@ -116,7 +116,7 @@ Visit [http://localhost:3000](http://localhost:3000) → follow the onboarding f
### REST call (curl)
```bash
curl -X POST http://localhost:3001/api/tasks \
curl -X POST http://localhost:3002/api/tasks \
-H "Content-Type: application/json" \
-H "X-API-Key: <YOUR_ADMIN_KEY>" \
-d '{
@ -176,7 +176,7 @@ These cover the "something feels off" moments before you deep-dive logs.
### 1. API health (up in <1s)
```bash
curl -s http://localhost:3001/api/health | jq
curl -s http://localhost:3002/api/health | jq
```
Expect `{ "ok": true, "service": "veritas-kanban", ... }`. If the call hangs or returns HTML, something else is on the port.

34
docs/SOP-agent-task-workflow.md
View file

@ -31,40 +31,40 @@ Use this playbook anytime an agent (human or LLM) takes a task from **todo** to
```bash
# ── 1. Claim ──────────────────────────────────────────────
curl -X PATCH http://localhost:3001/api/tasks/<id> \
curl -X PATCH http://localhost:3002/api/tasks/<id> \
-H "Content-Type: application/json" \
-d '{"status":"in-progress"}'
curl -X POST http://localhost:3001/api/tasks/<id>/time/start
curl -X POST http://localhost:3002/api/tasks/<id>/time/start
curl -X POST http://localhost:3001/api/agent/status \
curl -X POST http://localhost:3002/api/agent/status \
-H "Content-Type: application/json" \
-d '{"status":"working","taskId":"<id>","taskTitle":"Fix CLI"}'
# ⚠️ Emit run.started telemetry (powers Success Rate + Run Duration graphs)
curl -X POST http://localhost:3001/api/telemetry/events \
curl -X POST http://localhost:3002/api/telemetry/events \
-H "Content-Type: application/json" \
-d '{"type":"run.started","taskId":"<id>","agent":"<agent-name>"}'
# ── 2. Update (optional comment) ─────────────────────────
curl -X POST http://localhost:3001/api/tasks/<id>/comments \
curl -X POST http://localhost:3002/api/tasks/<id>/comments \
-H "Content-Type: application/json" \
-d '{"text":"Blocked on dependency"}'
# ── 3. Complete ───────────────────────────────────────────
curl -X POST http://localhost:3001/api/tasks/<id>/time/stop
curl -X POST http://localhost:3002/api/tasks/<id>/time/stop
# ⚠️ Emit run.completed telemetry (durationMs = ms since run.started)
curl -X POST http://localhost:3001/api/telemetry/events \
curl -X POST http://localhost:3002/api/telemetry/events \
-H "Content-Type: application/json" \
-d '{"type":"run.completed","taskId":"<id>","agent":"<agent-name>","durationMs":<DURATION_MS>,"success":true}'
# ⚠️ Report token usage (powers Token Usage + Monthly Budget graphs)
curl -X POST http://localhost:3001/api/telemetry/events \
curl -X POST http://localhost:3002/api/telemetry/events \
-H "Content-Type: application/json" \
-d '{"type":"run.tokens","taskId":"<id>","agent":"<agent-name>","model":"<model>","inputTokens":<N>,"outputTokens":<N>,"cacheTokens":<N>,"cost":<N>}'
curl -X PATCH http://localhost:3001/api/tasks/<id> \
curl -X PATCH http://localhost:3002/api/tasks/<id> \
-H "Content-Type: application/json" \
-d '{
"status":"done",
@ -74,7 +74,7 @@ curl -X PATCH http://localhost:3001/api/tasks/<id> \
# ── On Failure ────────────────────────────────────────────
# Same as complete, but success=false:
curl -X POST http://localhost:3001/api/telemetry/events \
curl -X POST http://localhost:3002/api/telemetry/events \
-H "Content-Type: application/json" \
-d '{"type":"run.completed","taskId":"<id>","agent":"<agent-name>","durationMs":<DURATION_MS>,"success":false}'
```
@ -101,7 +101,7 @@ Veritas Kanban supports **6 enforcement gates** that can harden your workflow by
**Check if enforcement is enabled before starting work:**
```bash
curl http://localhost:3001/api/settings/features | jq '.data.enforcement'
curl http://localhost:3002/api/settings/features | jq '.data.enforcement'
```
**Example response:**
@ -252,15 +252,15 @@ For long-running tasks, save agent state periodically so work can resume after c
```bash
# Save checkpoint mid-work (secrets auto-sanitized)
curl -X POST http://localhost:3001/api/tasks/<id>/checkpoint \
curl -X POST http://localhost:3002/api/tasks/<id>/checkpoint \
-H "Content-Type: application/json" \
-d '{"state":{"current_step":3,"completed":["step1","step2"],"notes":"Working on step 3"}}'
# On restart, check for existing checkpoint
curl http://localhost:3001/api/tasks/<id>/checkpoint
curl http://localhost:3002/api/tasks/<id>/checkpoint
# Clear after task completion
curl -X DELETE http://localhost:3001/api/tasks/<id>/checkpoint
curl -X DELETE http://localhost:3002/api/tasks/<id>/checkpoint
```
**Rules:**
@ -275,12 +275,12 @@ Capture important decisions, blockers, and insights as task observations:
```bash
# Log a decision
curl -X POST http://localhost:3001/api/observations \
curl -X POST http://localhost:3002/api/observations \
-H "Content-Type: application/json" \
-d '{"taskId":"<id>","type":"decision","content":"Chose approach X over Y because...","importance":8}'
# Search observations across all tasks
curl "http://localhost:3001/api/observations/search?query=approach+X"
curl "http://localhost:3002/api/observations/search?query=approach+X"
```
**When to create observations:**
@ -296,7 +296,7 @@ Before starting a task, check its dependency status:
```bash
# Check dependencies
curl http://localhost:3001/api/tasks/<id>/dependencies
curl http://localhost:3002/api/tasks/<id>/dependencies
# If upstream blockers are incomplete, don't start — pick another task instead.
```

2
docs/SOP-cross-model-code-review.md
View file

@ -114,7 +114,7 @@ VK's built-in enforcement gates integrate directly with the cross-model review w
4. **Enabling gates**:
```bash
curl -X PATCH http://localhost:3001/api/settings/features \
curl -X PATCH http://localhost:3002/api/settings/features \
-H 'Content-Type: application/json' \
-d '{"enforcement": {"reviewGate": true, "closingComments": true}}'
```

8
docs/SOP-lifecycle-hooks.md
View file

@ -29,7 +29,7 @@ Each hook can:
Enable hooks via the settings API:
```bash
curl -X PATCH http://localhost:3001/api/config/settings \
curl -X PATCH http://localhost:3002/api/config/settings \
-H "Content-Type: application/json" \
-d '{
"hooks": {
@ -199,19 +199,19 @@ app.listen(3002);
Check current hooks configuration:
```bash
curl http://localhost:3001/api/config/settings | jq '.data.hooks'
curl http://localhost:3002/api/config/settings | jq '.data.hooks'
```
Enable/disable hooks quickly:
```bash
# Enable all hooks
curl -X PATCH http://localhost:3001/api/config/settings \
curl -X PATCH http://localhost:3002/api/config/settings \
-H "Content-Type: application/json" \
-d '{"hooks": {"enabled": true}}'
# Disable all hooks
curl -X PATCH http://localhost:3001/api/config/settings \
curl -X PATCH http://localhost:3002/api/config/settings \
-H "Content-Type: application/json" \
-d '{"hooks": {"enabled": false}}'
```

2
docs/SOP-sprint-planning.md
View file

@ -42,7 +42,7 @@ Store the final prompt under `prompt-registry/sprint-planning.md`.
Use the bulk endpoint to create the entire sprint quickly:
```bash
curl -X POST http://localhost:3001/api/tasks/bulk \
curl -X POST http://localhost:3002/api/tasks/bulk \
-H "Authorization: Bearer <admin-key>" \
-H "Content-Type: application/json" \
-d '{

6
docs/SQUAD-CHAT-PROTOCOL.md
View file

@ -26,7 +26,7 @@ Squad chat is the **glass box** — the real-time visibility layer that lets hum
### curl (when script isn't available)
```bash
curl -s -X POST "http://localhost:3001/api/chat/squad" \
curl -s -X POST "http://localhost:3002/api/chat/squad" \
-H 'Content-Type: application/json' \
-d '{
"agent": "YOUR_NAME",
@ -55,7 +55,7 @@ The script supports these env vars for non-default configurations:
### Troubleshooting
- **Connection refused:** Verify VK server is running (`curl http://localhost:3001/api/health`)
- **Connection refused:** Verify VK server is running (`curl http://localhost:3002/api/health`)
- **Script fails silently:** Check that `jq` is installed (`which jq`)
- **Wrong port:** Set `VK_PORT` env var to match your server configuration
@ -95,7 +95,7 @@ Every sub-agent task **must** include this block:
```
SQUAD CHAT (mandatory): Post updates to squad chat as YOUR_NAME throughout your work.
Use this command for regular updates:
curl -s -X POST "http://localhost:3001/api/chat/squad" \
curl -s -X POST "http://localhost:3002/api/chat/squad" \
-H 'Content-Type: application/json' \
-d '{"agent":"YOUR_NAME","message":"YOUR UPDATE","tags":["relevant","tags"],"model":"YOUR_MODEL"}'

42
docs/TESTING_ANALYTICS.md
View file

@ -20,7 +20,7 @@ Create 3 tasks that run in parallel to test the parallelism detection:
```bash
# Task 1: 10:00-10:30 (30 min)
curl -X POST http://localhost:3001/api/tasks \
curl -X POST http://localhost:3002/api/tasks \
-H "Content-Type: application/json" \
-d '{
"title": "Feature A - Backend",
@ -36,7 +36,7 @@ curl -X POST http://localhost:3001/api/tasks \
TASK1=$(jq -r '.data.id' /tmp/task1.json)
# Add time entries (10:00-10:30)
curl -X POST http://localhost:3001/api/tasks/$TASK1/time/entry \
curl -X POST http://localhost:3002/api/tasks/$TASK1/time/entry \
-H "Content-Type: application/json" \
-d '{
"duration": 1800,
@ -44,7 +44,7 @@ curl -X POST http://localhost:3001/api/tasks/$TASK1/time/entry \
}'
# Task 2: 10:15-11:00 (45 min) - overlaps with Task 1
curl -X POST http://localhost:3001/api/tasks \
curl -X POST http://localhost:3002/api/tasks \
-H "Content-Type: application/json" \
-d '{
"title": "Feature B - Frontend",
@ -58,7 +58,7 @@ curl -X POST http://localhost:3001/api/tasks \
TASK2=$(jq -r '.data.id' /tmp/task2.json)
curl -X POST http://localhost:3001/api/tasks/$TASK2/time/entry \
curl -X POST http://localhost:3002/api/tasks/$TASK2/time/entry \
-H "Content-Type: application/json" \
-d '{
"duration": 2700,
@ -66,7 +66,7 @@ curl -X POST http://localhost:3001/api/tasks/$TASK2/time/entry \
}'
# Task 3: 10:45-11:30 (45 min) - overlaps with Task 2 only
curl -X POST http://localhost:3001/api/tasks \
curl -X POST http://localhost:3002/api/tasks \
-H "Content-Type: application/json" \
-d '{
"title": "Feature C - Testing",
@ -80,7 +80,7 @@ curl -X POST http://localhost:3001/api/tasks \
TASK3=$(jq -r '.data.id' /tmp/task3.json)
curl -X POST http://localhost:3001/api/tasks/$TASK3/time/entry \
curl -X POST http://localhost:3002/api/tasks/$TASK3/time/entry \
-H "Content-Type: application/json" \
-d '{
"duration": 2700,
@ -95,7 +95,7 @@ echo "Created tasks: $TASK1, $TASK2, $TASK3"
### Test 1: Get Timeline (No Filters)
```bash
curl -s http://localhost:3001/api/analytics/timeline | jq .
curl -s http://localhost:3002/api/analytics/timeline | jq .
```
**Expected Output:**
@ -108,7 +108,7 @@ curl -s http://localhost:3001/api/analytics/timeline | jq .
```bash
# Get timeline for today
curl -s "http://localhost:3001/api/analytics/timeline?from=2026-02-04T00:00:00Z&to=2026-02-05T23:59:59Z" | jq .
curl -s "http://localhost:3002/api/analytics/timeline?from=2026-02-04T00:00:00Z&to=2026-02-05T23:59:59Z" | jq .
```
**Expected Output:**
@ -119,7 +119,7 @@ curl -s "http://localhost:3001/api/analytics/timeline?from=2026-02-04T00:00:00Z&
### Test 3: Filter by Project
```bash
curl -s "http://localhost:3001/api/analytics/timeline?project=veritas" | jq '.data.tasks | length'
curl -s "http://localhost:3002/api/analytics/timeline?project=veritas" | jq '.data.tasks | length'
```
**Expected Output:**
@ -129,7 +129,7 @@ curl -s "http://localhost:3001/api/analytics/timeline?project=veritas" | jq '.da
### Test 4: Get Metrics for Sprint
```bash
curl -s "http://localhost:3001/api/analytics/metrics?sprint=v1.5" | jq .
curl -s "http://localhost:3002/api/analytics/metrics?sprint=v1.5" | jq .
```
**Expected Output:**
@ -142,7 +142,7 @@ curl -s "http://localhost:3001/api/analytics/metrics?sprint=v1.5" | jq .
### Test 5: Verify Parallelism Calculation
```bash
curl -s http://localhost:3001/api/analytics/timeline | \
curl -s http://localhost:3002/api/analytics/timeline | \
jq '.data.parallelism | sort_by(.timestamp) | .[] | {timestamp: .timestamp, count: .concurrentTaskCount}'
```
@ -174,7 +174,7 @@ curl -s http://localhost:3001/api/analytics/timeline | \
### Test 6: Agent Utilization
```bash
curl -s "http://localhost:3001/api/analytics/metrics?sprint=v1.5" | \
curl -s "http://localhost:3002/api/analytics/metrics?sprint=v1.5" | \
jq '.data.agentUtilization'
```
@ -190,7 +190,7 @@ To test performance with many tasks:
```bash
# Generate 100 tasks with overlapping time entries
for i in {1..100}; do
TASK=$(curl -s -X POST http://localhost:3001/api/tasks \
TASK=$(curl -s -X POST http://localhost:3002/api/tasks \
-H "Content-Type: application/json" \
-d "{
\"title\": \"Test Task $i\",
@ -201,7 +201,7 @@ for i in {1..100}; do
\"sprint\": \"load-test\"
}" | jq -r '.data.id')
curl -s -X POST http://localhost:3001/api/tasks/$TASK/time/entry \
curl -s -X POST http://localhost:3002/api/tasks/$TASK/time/entry \
-H "Content-Type: application/json" \
-d "{\"duration\": $((RANDOM % 3600 + 300))}"
@ -209,7 +209,7 @@ for i in {1..100}; do
done
# Time the metrics endpoint
time curl -s "http://localhost:3001/api/analytics/metrics?sprint=load-test" > /dev/null
time curl -s "http://localhost:3002/api/analytics/metrics?sprint=load-test" > /dev/null
```
**Expected:** Should complete in <2 seconds even with 100 tasks
@ -220,20 +220,20 @@ time curl -s "http://localhost:3001/api/analytics/metrics?sprint=load-test" > /d
```bash
TASK_ID="task_20260205_xxxxx"
curl -s http://localhost:3001/api/tasks/$TASK_ID | jq '.data.timeTracking'
curl -s http://localhost:3002/api/tasks/$TASK_ID | jq '.data.timeTracking'
```
### Verify Parallelism Snapshots
```bash
curl -s http://localhost:3001/api/analytics/timeline | \
curl -s http://localhost:3002/api/analytics/timeline | \
jq '.data | {totalTasks: .summary.totalTasks, snapshotCount: (.parallelism | length), maxConcurrency: .summary.maxConcurrency}'
```
### Check Timeline Period
```bash
curl -s http://localhost:3001/api/analytics/timeline | \
curl -s http://localhost:3002/api/analytics/timeline | \
jq '.data.period'
```
@ -241,19 +241,19 @@ curl -s http://localhost:3001/api/analytics/timeline | \
### No Data in Timeline
1. Verify tasks have time entries: `curl http://localhost:3001/api/tasks | jq '.data[] | select(.timeTracking.entries | length > 0)'`
1. Verify tasks have time entries: `curl http://localhost:3002/api/tasks | jq '.data[] | select(.timeTracking.entries | length > 0)'`
2. Check date range is correct
3. Ensure timer was stopped (not still running)
### Incorrect Parallelism
1. Review individual time entries: `curl http://localhost:3001/api/tasks/TASK_ID | jq '.data.timeTracking.entries'`
1. Review individual time entries: `curl http://localhost:3002/api/tasks/TASK_ID | jq '.data.timeTracking.entries'`
2. Check entry start/end times
3. Verify 5-minute sampling window includes the overlap points
### Performance Issues
1. Check number of tasks: `curl http://localhost:3001/api/tasks | jq '.data | length'`
1. Check number of tasks: `curl http://localhost:3002/api/tasks | jq '.data | length'`
2. If >1000 tasks, consider narrowing date range
3. Use project/sprint filters to reduce data volume

2
docs/TIPS-AND-TRICKS.md
View file

@ -58,7 +58,7 @@ Pipe outputs to `jq` or `fzf` for custom dashboards.
"command": "node",
"args": ["/path/to/veritas-kanban/mcp/dist/index.js"],
"env": {
"VK_API_URL": "http://localhost:3001",
"VK_API_URL": "http://localhost:3002",
"VK_API_KEY": "<admin-key>"
}
}

26
docs/TROUBLESHOOTING.md
View file

@ -53,7 +53,7 @@ This:
VK provides a canonical health endpoint for tooling:
```bash
curl -s http://localhost:3001/api/health
curl -s http://localhost:3002/api/health
```
Expected: HTTP 200 JSON like:
@ -176,7 +176,7 @@ node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
Check the auth diagnostics endpoint:
```bash
curl -H "X-API-Key: your-admin-key" http://localhost:3001/api/auth/diagnostics
curl -H "X-API-Key: your-admin-key" http://localhost:3002/api/auth/diagnostics
```
Verify your `.env` has the correct key format:
@ -204,13 +204,13 @@ See [Deployment Guide](DEPLOYMENT.md#reverse-proxy-nginx) for full configuration
```bash
# 1. Authorization header (Bearer token)
curl -H "Authorization: Bearer your-api-key" http://localhost:3001/api/tasks
curl -H "Authorization: Bearer your-api-key" http://localhost:3002/api/tasks
# 2. X-API-Key header
curl -H "X-API-Key: your-api-key" http://localhost:3001/api/tasks
curl -H "X-API-Key: your-api-key" http://localhost:3002/api/tasks
# 3. Query parameter (useful for WebSocket connections)
ws://localhost:3001/ws?api_key=your-api-key
ws://localhost:3002/ws?api_key=your-api-key
```
---
@ -235,7 +235,7 @@ HOST=127.0.0.1 pnpm dev
ssh -L 127.0.0.1:3001:127.0.0.1:3001 user@server
# May cause issues — binds to all interfaces
ssh -L 3001:localhost:3001 user@server
ssh -L 3001:localhost:3002 user@server
ssh -L 0.0.0.0:3001:127.0.0.1:3001 user@server
```
@ -386,12 +386,12 @@ docker compose up -d
### Agent can't connect to the API
1. Verify the server is running: `curl http://localhost:3001/api/health`
1. Verify the server is running: `curl http://localhost:3002/api/health`
2. Check your agent's API key has the `agent` role:
```bash
VERITAS_API_KEYS=my-agent:my-secret-key:agent
```
3. For agents running in Docker/containers, use `host.docker.internal:3001` instead of `localhost:3001`
3. For agents running in Docker/containers, use `host.docker.internal:3001` instead of `localhost:3002`
### Agent names/models — is it hardcoded?
@ -410,7 +410,7 @@ Verify the MCP server config in your Claude Desktop settings:
"command": "node",
"args": ["/path/to/veritas-kanban/mcp/dist/index.js"],
"env": {
"VK_API_URL": "http://localhost:3001",
"VK_API_URL": "http://localhost:3002",
"VK_API_KEY": "your-admin-key"
}
}
@ -429,7 +429,7 @@ Build the MCP server first: `cd mcp && pnpm build`
1. Check the browser console for errors (F12 → Console)
2. Verify both services are running:
- Web: http://localhost:3000
- API: http://localhost:3001/api/health
- API: http://localhost:3002/api/health
3. Try a hard refresh: `Ctrl+Shift+R` (Windows/Linux) or `Cmd+Shift+R` (Mac)
### Drag and drop not working
@ -500,11 +500,11 @@ pnpm cli create # Create a task
pnpm cli update # Update a task
# Health checks
curl http://localhost:3001/api/health # Server health
curl http://localhost:3001/api/auth/diagnostics # Auth diagnostics (needs admin key)
curl http://localhost:3002/api/health # Server health
curl http://localhost:3002/api/auth/diagnostics # Auth diagnostics (needs admin key)
# API docs
open http://localhost:3001/api-docs # Swagger UI
open http://localhost:3002/api-docs # Swagger UI
```
---

6
docs/WORKFLOW-GUIDE.md
View file

@ -124,7 +124,7 @@ steps:
```bash
# Start a workflow run
curl -X POST http://localhost:3001/api/workflows/hello-world/runs \
curl -X POST http://localhost:3002/api/workflows/hello-world/runs \
-H "Content-Type: application/json" \
-d '{}'
@ -523,7 +523,7 @@ Tool policies define which tools each agent role can access, enabling least-priv
**Via API:**
```bash
curl -X POST http://localhost:3001/api/tool-policies \
curl -X POST http://localhost:3002/api/tool-policies \
-H "Content-Type: application/json" \
-d '{
"role": "auditor",
@ -1202,7 +1202,7 @@ If the server crashes mid-workflow, runs can be recovered:
3. **Resume manually** (if blocked):
```bash
curl -X POST http://localhost:3001/api/workflow-runs/run_XYZ/resume
curl -X POST http://localhost:3002/api/workflow-runs/run_XYZ/resume
```
> **📝 Note**: Automatic recovery is planned for a future release.

26
docs/enforcement.md
View file

@ -25,13 +25,13 @@ enforcement gates.
### Fetch current settings
```bash
curl http://localhost:3001/api/settings/features | jq
curl http://localhost:3002/api/settings/features | jq
```
### Enable review gate + closing comments
```bash
curl -X PATCH http://localhost:3001/api/settings/features \
curl -X PATCH http://localhost:3002/api/settings/features \
-H 'Content-Type: application/json' \
-d '{
"enforcement": {
@ -44,7 +44,7 @@ curl -X PATCH http://localhost:3001/api/settings/features \
### Enable automation gates
```bash
curl -X PATCH http://localhost:3001/api/settings/features \
curl -X PATCH http://localhost:3002/api/settings/features \
-H 'Content-Type: application/json' \
-d '{
"enforcement": {
@ -58,7 +58,7 @@ curl -X PATCH http://localhost:3001/api/settings/features \
### Enable orchestrator delegation warnings
```bash
curl -X PATCH http://localhost:3001/api/settings/features \
curl -X PATCH http://localhost:3002/api/settings/features \
-H 'Content-Type: application/json' \
-d '{
"enforcement": {
@ -70,7 +70,7 @@ curl -X PATCH http://localhost:3001/api/settings/features \
### Disable all enforcement gates
```bash
curl -X PATCH http://localhost:3001/api/settings/features \
curl -X PATCH http://localhost:3002/api/settings/features \
-H 'Content-Type: application/json' \
-d '{
"enforcement": {
@ -274,7 +274,7 @@ If you're an autonomous agent interacting with the Veritas Kanban API, here's ho
**Before attempting a status change to `done`:**
```bash
curl http://localhost:3001/api/settings/features | jq '.data.enforcement'
curl http://localhost:3002/api/settings/features | jq '.data.enforcement'
```
**Response:**
@ -304,14 +304,14 @@ curl http://localhost:3001/api/settings/features | jq '.data.enforcement'
1. **If `reviewGate` is enabled:** Fetch the task and check `reviewScores`:
```bash
curl http://localhost:3001/api/tasks/US-42 | jq '.data.reviewScores'
curl http://localhost:3002/api/tasks/US-42 | jq '.data.reviewScores'
```
All four dimensions (`security`, `reliability`, `performance`, `accessibility`) must be `10`.
2. **If `closingComments` is enabled:** Fetch task comments and ensure at least one is ≥20 characters:
```bash
curl http://localhost:3001/api/tasks/US-42 | jq '.data.comments'
curl http://localhost:3002/api/tasks/US-42 | jq '.data.comments'
```
If either check fails, **fix the deficiency before attempting completion:**
@ -326,7 +326,7 @@ If either check fails, **fix the deficiency before attempting completion:**
**Example: reviewGate violation**
```bash
curl -X PATCH http://localhost:3001/api/tasks/US-42 \
curl -X PATCH http://localhost:3002/api/tasks/US-42 \
-H "Content-Type: application/json" \
-d '{"status":"done"}'
```
@ -380,7 +380,7 @@ If you are the orchestrator and `orchestratorDelegation` is enabled:
```bash
# Orchestrator creates a sub-agent task
curl -X POST http://localhost:3001/api/tasks \
curl -X POST http://localhost:3002/api/tasks \
-H "Content-Type: application/json" \
-d '{
"title": "Implement OAuth login",
@ -415,7 +415,7 @@ curl -X POST http://localhost:3001/api/tasks \
```bash
# Cache enforcement config at session start
ENFORCEMENT=$(curl -s http://localhost:3001/api/settings/features | jq '.data.enforcement')
ENFORCEMENT=$(curl -s http://localhost:3002/api/settings/features | jq '.data.enforcement')
# Use cached values for pre-flight checks
if [ "$(echo $ENFORCEMENT | jq -r '.reviewGate')" == "true" ]; then
@ -436,13 +436,13 @@ The API does not fail silently — it returns `400 Bad Request` with an error co
Check the enforcement config:
```bash
curl http://localhost:3001/api/settings/features | jq '.data.enforcement'
curl http://localhost:3002/api/settings/features | jq '.data.enforcement'
```
If a gate is `true` and you want it off, disable it:
```bash
curl -X PATCH http://localhost:3001/api/settings/features \
curl -X PATCH http://localhost:3002/api/settings/features \
-H 'Content-Type: application/json' \
-d '{"enforcement":{"<gate-name>":false}}'
```

34
docs/features/broadcasts.md
View file

@ -22,7 +22,7 @@ Broadcast Notifications provide a system-wide notification mechanism for importa
```bash
# Info notification
curl -X POST http://localhost:3001/api/notifications/broadcast \
curl -X POST http://localhost:3002/api/notifications/broadcast \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_KEY" \
-d '{
@ -32,7 +32,7 @@ curl -X POST http://localhost:3001/api/notifications/broadcast \
}'
# Warning notification with expiration
curl -X POST http://localhost:3001/api/notifications/broadcast \
curl -X POST http://localhost:3002/api/notifications/broadcast \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_KEY" \
-d '{
@ -43,7 +43,7 @@ curl -X POST http://localhost:3001/api/notifications/broadcast \
}'
# Critical notification with action button
curl -X POST http://localhost:3001/api/notifications/broadcast \
curl -X POST http://localhost:3002/api/notifications/broadcast \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_KEY" \
-d '{
@ -55,7 +55,7 @@ curl -X POST http://localhost:3001/api/notifications/broadcast \
}'
# Agent-specific notification
curl -X POST http://localhost:3001/api/notifications/broadcast \
curl -X POST http://localhost:3002/api/notifications/broadcast \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_KEY" \
-d '{
@ -70,22 +70,22 @@ curl -X POST http://localhost:3001/api/notifications/broadcast \
```bash
# Get all active broadcasts
curl http://localhost:3001/api/notifications/broadcast \
curl http://localhost:3002/api/notifications/broadcast \
-H "X-API-Key: YOUR_KEY"
# Get broadcasts for specific agent
curl "http://localhost:3001/api/notifications/broadcast?agent=TARS" \
curl "http://localhost:3002/api/notifications/broadcast?agent=TARS" \
-H "X-API-Key: YOUR_KEY"
# Include dismissed broadcasts
curl "http://localhost:3001/api/notifications/broadcast?includeDismissed=true" \
curl "http://localhost:3002/api/notifications/broadcast?includeDismissed=true" \
-H "X-API-Key: YOUR_KEY"
```
### Mark as Read
```bash
curl -X POST http://localhost:3001/api/notifications/broadcast/{id}/read \
curl -X POST http://localhost:3002/api/notifications/broadcast/{id}/read \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_KEY" \
-d '{
@ -97,7 +97,7 @@ curl -X POST http://localhost:3001/api/notifications/broadcast/{id}/read \
```bash
# Dismiss for specific agent
curl -X POST http://localhost:3001/api/notifications/broadcast/{id}/dismiss \
curl -X POST http://localhost:3002/api/notifications/broadcast/{id}/dismiss \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_KEY" \
-d '{
@ -105,7 +105,7 @@ curl -X POST http://localhost:3001/api/notifications/broadcast/{id}/dismiss \
}'
# Dismiss globally (requires admin role)
curl -X DELETE http://localhost:3001/api/notifications/broadcast/{id} \
curl -X DELETE http://localhost:3002/api/notifications/broadcast/{id} \
-H "X-API-Key: ADMIN_KEY"
```
@ -174,7 +174,7 @@ Broadcasts appear at the top of the board (sticky header) with the following beh
### Deployment Announcements
```bash
curl -X POST http://localhost:3001/api/notifications/broadcast \
curl -X POST http://localhost:3002/api/notifications/broadcast \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_KEY" \
-d '{
@ -189,7 +189,7 @@ curl -X POST http://localhost:3001/api/notifications/broadcast \
### Agent Task Completion
```bash
curl -X POST http://localhost:3001/api/notifications/broadcast \
curl -X POST http://localhost:3002/api/notifications/broadcast \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_KEY" \
-d '{
@ -204,7 +204,7 @@ curl -X POST http://localhost:3001/api/notifications/broadcast \
### Critical Security Alerts
```bash
curl -X POST http://localhost:3001/api/notifications/broadcast \
curl -X POST http://localhost:3002/api/notifications/broadcast \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_KEY" \
-d '{
@ -219,7 +219,7 @@ curl -X POST http://localhost:3001/api/notifications/broadcast \
### Maintenance Windows
```bash
curl -X POST http://localhost:3001/api/notifications/broadcast \
curl -X POST http://localhost:3002/api/notifications/broadcast \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_KEY" \
-d '{
@ -255,11 +255,11 @@ Agents should poll for broadcasts on startup and periodically:
```bash
# Check for unread broadcasts
BROADCASTS=$(curl -s "http://localhost:3001/api/notifications/broadcast?agent=TARS" \
BROADCASTS=$(curl -s "http://localhost:3002/api/notifications/broadcast?agent=TARS" \
-H "X-API-Key: YOUR_KEY")
# Mark as read after displaying
curl -X POST http://localhost:3001/api/notifications/broadcast/{id}/read \
curl -X POST http://localhost:3002/api/notifications/broadcast/{id}/read \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_KEY" \
-d '{ "agent": "TARS" }'
@ -268,7 +268,7 @@ curl -X POST http://localhost:3001/api/notifications/broadcast/{id}/read \
Agents can dismiss broadcasts after acknowledging:
```bash
curl -X POST http://localhost:3001/api/notifications/broadcast/{id}/dismiss \
curl -X POST http://localhost:3002/api/notifications/broadcast/{id}/dismiss \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_KEY" \
-d '{ "agent": "TARS" }'

34
docs/features/delegation.md
View file

@ -22,7 +22,7 @@ Approval Delegation allows users to delegate their approval authority to another
```bash
# Delegate all approvals (vacation mode)
curl -X POST http://localhost:3001/api/approvals/delegate \
curl -X POST http://localhost:3002/api/approvals/delegate \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_KEY" \
-d '{
@ -34,7 +34,7 @@ curl -X POST http://localhost:3001/api/approvals/delegate \
}'
# Delegate specific project approvals
curl -X POST http://localhost:3001/api/approvals/delegate \
curl -X POST http://localhost:3002/api/approvals/delegate \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_KEY" \
-d '{
@ -49,7 +49,7 @@ curl -X POST http://localhost:3001/api/approvals/delegate \
}'
# Delegate by task type and priority
curl -X POST http://localhost:3001/api/approvals/delegate \
curl -X POST http://localhost:3002/api/approvals/delegate \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_KEY" \
-d '{
@ -65,7 +65,7 @@ curl -X POST http://localhost:3001/api/approvals/delegate \
}'
# Delegate to multiple people with fallback
curl -X POST http://localhost:3001/api/approvals/delegate \
curl -X POST http://localhost:3002/api/approvals/delegate \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_KEY" \
-d '{
@ -84,15 +84,15 @@ curl -X POST http://localhost:3001/api/approvals/delegate \
```bash
# Get all active delegations
curl http://localhost:3001/api/approvals/delegate \
curl http://localhost:3002/api/approvals/delegate \
-H "X-API-Key: YOUR_KEY"
# Get delegations for specific user
curl "http://localhost:3001/api/approvals/delegate?user=brad" \
curl "http://localhost:3002/api/approvals/delegate?user=brad" \
-H "X-API-Key: YOUR_KEY"
# Get delegations where user is delegate
curl "http://localhost:3001/api/approvals/delegate?delegate=VERITAS" \
curl "http://localhost:3002/api/approvals/delegate?delegate=VERITAS" \
-H "X-API-Key: YOUR_KEY"
```
@ -100,7 +100,7 @@ curl "http://localhost:3001/api/approvals/delegate?delegate=VERITAS" \
```bash
# Extend delegation end date
curl -X PATCH http://localhost:3001/api/approvals/delegate/{delegationId} \
curl -X PATCH http://localhost:3002/api/approvals/delegate/{delegationId} \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_KEY" \
-d '{
@ -108,7 +108,7 @@ curl -X PATCH http://localhost:3001/api/approvals/delegate/{delegationId} \
}'
# Change delegate
curl -X PATCH http://localhost:3001/api/approvals/delegate/{delegationId} \
curl -X PATCH http://localhost:3002/api/approvals/delegate/{delegationId} \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_KEY" \
-d '{
@ -116,7 +116,7 @@ curl -X PATCH http://localhost:3001/api/approvals/delegate/{delegationId} \
}'
# Update scope
curl -X PATCH http://localhost:3001/api/approvals/delegate/{delegationId} \
curl -X PATCH http://localhost:3002/api/approvals/delegate/{delegationId} \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_KEY" \
-d '{
@ -130,7 +130,7 @@ curl -X PATCH http://localhost:3001/api/approvals/delegate/{delegationId} \
```bash
# Cancel delegation early
curl -X DELETE http://localhost:3001/api/approvals/delegate/{delegationId} \
curl -X DELETE http://localhost:3002/api/approvals/delegate/{delegationId} \
-H "X-API-Key: YOUR_KEY"
```
@ -265,7 +265,7 @@ Approval audit logs include delegation references:
Delegate all approvals while away:
```bash
curl -X POST http://localhost:3001/api/approvals/delegate \
curl -X POST http://localhost:3002/api/approvals/delegate \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_KEY" \
-d '{
@ -282,7 +282,7 @@ curl -X POST http://localhost:3001/api/approvals/delegate \
Delegate urgent approvals to on-call agent:
```bash
curl -X POST http://localhost:3001/api/approvals/delegate \
curl -X POST http://localhost:3002/api/approvals/delegate \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_KEY" \
-d '{
@ -302,7 +302,7 @@ curl -X POST http://localhost:3001/api/approvals/delegate \
Delegate specific project during transition:
```bash
curl -X POST http://localhost:3001/api/approvals/delegate \
curl -X POST http://localhost:3002/api/approvals/delegate \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_KEY" \
-d '{
@ -322,7 +322,7 @@ curl -X POST http://localhost:3001/api/approvals/delegate \
Delegate code reviews when overloaded:
```bash
curl -X POST http://localhost:3001/api/approvals/delegate \
curl -X POST http://localhost:3002/api/approvals/delegate \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_KEY" \
-d '{
@ -358,11 +358,11 @@ Agents should check for delegated approvals:
```bash
# Check if agent has delegated authority
curl "http://localhost:3001/api/approvals/delegate?delegate=VERITAS" \
curl "http://localhost:3002/api/approvals/delegate?delegate=VERITAS" \
-H "X-API-Key: YOUR_KEY"
# Approve on behalf of delegator
curl -X POST http://localhost:3001/api/tasks/{taskId}/approve \
curl -X POST http://localhost:3002/api/tasks/{taskId}/approve \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_KEY" \
-d '{

34
docs/features/deliverables.md
View file

@ -22,7 +22,7 @@ Task Deliverables provide structured tracking of work products created during ta
```bash
# Code deliverable
curl -X POST http://localhost:3001/api/tasks/{taskId}/deliverables \
curl -X POST http://localhost:3002/api/tasks/{taskId}/deliverables \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_KEY" \
-d '{
@ -34,7 +34,7 @@ curl -X POST http://localhost:3001/api/tasks/{taskId}/deliverables \
}'
# Documentation deliverable with URL
curl -X POST http://localhost:3001/api/tasks/{taskId}/deliverables \
curl -X POST http://localhost:3002/api/tasks/{taskId}/deliverables \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_KEY" \
-d '{
@ -46,7 +46,7 @@ curl -X POST http://localhost:3001/api/tasks/{taskId}/deliverables \
}'
# Data deliverable with metadata
curl -X POST http://localhost:3001/api/tasks/{taskId}/deliverables \
curl -X POST http://localhost:3002/api/tasks/{taskId}/deliverables \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_KEY" \
-d '{
@ -67,15 +67,15 @@ curl -X POST http://localhost:3001/api/tasks/{taskId}/deliverables \
```bash
# Get all deliverables for a task
curl http://localhost:3001/api/tasks/{taskId}/deliverables \
curl http://localhost:3002/api/tasks/{taskId}/deliverables \
-H "X-API-Key: YOUR_KEY"
# Filter by type
curl "http://localhost:3001/api/tasks/{taskId}/deliverables?type=code" \
curl "http://localhost:3002/api/tasks/{taskId}/deliverables?type=code" \
-H "X-API-Key: YOUR_KEY"
# Filter by status
curl "http://localhost:3001/api/tasks/{taskId}/deliverables?status=complete" \
curl "http://localhost:3002/api/tasks/{taskId}/deliverables?status=complete" \
-H "X-API-Key: YOUR_KEY"
```
@ -83,7 +83,7 @@ curl "http://localhost:3001/api/tasks/{taskId}/deliverables?status=complete" \
```bash
# Update status
curl -X PATCH http://localhost:3001/api/tasks/{taskId}/deliverables/{deliverableId} \
curl -X PATCH http://localhost:3002/api/tasks/{taskId}/deliverables/{deliverableId} \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_KEY" \
-d '{
@ -91,7 +91,7 @@ curl -X PATCH http://localhost:3001/api/tasks/{taskId}/deliverables/{deliverable
}'
# Update description and metadata
curl -X PATCH http://localhost:3001/api/tasks/{taskId}/deliverables/{deliverableId} \
curl -X PATCH http://localhost:3002/api/tasks/{taskId}/deliverables/{deliverableId} \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_KEY" \
-d '{
@ -105,7 +105,7 @@ curl -X PATCH http://localhost:3001/api/tasks/{taskId}/deliverables/{deliverable
### Delete Deliverable
```bash
curl -X DELETE http://localhost:3001/api/tasks/{taskId}/deliverables/{deliverableId} \
curl -X DELETE http://localhost:3002/api/tasks/{taskId}/deliverables/{deliverableId} \
-H "X-API-Key: YOUR_KEY"
```
@ -203,7 +203,7 @@ deliverables:
Track specific files or modules created during development:
```bash
curl -X POST http://localhost:3001/api/tasks/{taskId}/deliverables \
curl -X POST http://localhost:3002/api/tasks/{taskId}/deliverables \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_KEY" \
-d '{
@ -225,7 +225,7 @@ curl -X POST http://localhost:3001/api/tasks/{taskId}/deliverables \
Link to generated docs or external documentation:
```bash
curl -X POST http://localhost:3001/api/tasks/{taskId}/deliverables \
curl -X POST http://localhost:3002/api/tasks/{taskId}/deliverables \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_KEY" \
-d '{
@ -242,7 +242,7 @@ curl -X POST http://localhost:3001/api/tasks/{taskId}/deliverables \
Reference design files or tools:
```bash
curl -X POST http://localhost:3001/api/tasks/{taskId}/deliverables \
curl -X POST http://localhost:3002/api/tasks/{taskId}/deliverables \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_KEY" \
-d '{
@ -263,7 +263,7 @@ curl -X POST http://localhost:3001/api/tasks/{taskId}/deliverables \
Track data exports, migrations, or datasets:
```bash
curl -X POST http://localhost:3001/api/tasks/{taskId}/deliverables \
curl -X POST http://localhost:3002/api/tasks/{taskId}/deliverables \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_KEY" \
-d '{
@ -284,7 +284,7 @@ curl -X POST http://localhost:3001/api/tasks/{taskId}/deliverables \
Track test files and coverage:
```bash
curl -X POST http://localhost:3001/api/tasks/{taskId}/deliverables \
curl -X POST http://localhost:3002/api/tasks/{taskId}/deliverables \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_KEY" \
-d '{
@ -317,7 +317,7 @@ Agents should create deliverables when completing work:
```bash
# After creating/modifying a file
curl -X POST http://localhost:3001/api/tasks/{taskId}/deliverables \
curl -X POST http://localhost:3002/api/tasks/{taskId}/deliverables \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_KEY" \
-d '{
@ -332,7 +332,7 @@ Update deliverable status as work progresses:
```bash
# After code review
curl -X PATCH http://localhost:3001/api/tasks/{taskId}/deliverables/{deliverableId} \
curl -X PATCH http://localhost:3002/api/tasks/{taskId}/deliverables/{deliverableId} \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_KEY" \
-d '{
@ -340,7 +340,7 @@ curl -X PATCH http://localhost:3001/api/tasks/{taskId}/deliverables/{deliverable
}'
# After approval
curl -X PATCH http://localhost:3001/api/tasks/{taskId}/deliverables/{deliverableId} \
curl -X PATCH http://localhost:3002/api/tasks/{taskId}/deliverables/{deliverableId} \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_KEY" \
-d '{

26
docs/features/polling.md
View file

@ -21,15 +21,15 @@ The `/api/changes` endpoint provides an efficient mechanism for agents to detect
```bash
# Initial poll (get current state)
curl http://localhost:3001/api/changes \
curl http://localhost:3002/api/changes \
-H "X-API-Key: YOUR_KEY"
# Poll for changes since timestamp
curl "http://localhost:3001/api/changes?since=2026-02-07T15:00:00Z" \
curl "http://localhost:3002/api/changes?since=2026-02-07T15:00:00Z" \
-H "X-API-Key: YOUR_KEY"
# Poll with ETag (server returns 304 if nothing changed)
curl "http://localhost:3001/api/changes?since=2026-02-07T15:00:00Z" \
curl "http://localhost:3002/api/changes?since=2026-02-07T15:00:00Z" \
-H "X-API-Key: YOUR_KEY" \
-H "If-None-Match: \"abc123\""
```
@ -121,7 +121,7 @@ Content-Type: application/json
Agents should save the ETag and include it in the next request:
```bash
curl "http://localhost:3001/api/changes?since=2026-02-07T15:00:00Z" \
curl "http://localhost:3002/api/changes?since=2026-02-07T15:00:00Z" \
-H "X-API-Key: YOUR_KEY" \
-H "If-None-Match: \"abc123\""
```
@ -149,7 +149,7 @@ ETAG=""
while true; do
# Poll for changes
RESPONSE=$(curl -s -w "\n%{http_code}" \
"http://localhost:3001/api/changes?since=$LAST_CHECK" \
"http://localhost:3002/api/changes?since=$LAST_CHECK" \
-H "X-API-Key: $YOUR_KEY" \
-H "If-None-Match: $ETAG")
@ -162,7 +162,7 @@ while true; do
# Update timestamp and ETag
LAST_CHECK=$(echo "$BODY" | jq -r '.timestamp')
ETAG=$(curl -I -s "http://localhost:3001/api/changes?since=$LAST_CHECK" \
ETAG=$(curl -I -s "http://localhost:3002/api/changes?since=$LAST_CHECK" \
-H "X-API-Key: $YOUR_KEY" | grep -i 'etag:' | cut -d' ' -f2 | tr -d '\r\n')
elif [ "$STATUS_CODE" -eq 304 ]; then
@ -188,7 +188,7 @@ MAX_INTERVAL=300
while true; do
RESPONSE=$(curl -s -w "\n%{http_code}" \
"http://localhost:3001/api/changes?since=$LAST_CHECK" \
"http://localhost:3002/api/changes?since=$LAST_CHECK" \
-H "X-API-Key: $YOUR_KEY" \
-H "If-None-Match: $ETAG")
@ -229,7 +229,7 @@ done
```bash
# Poll for changes
CHANGES=$(curl -s "http://localhost:3001/api/changes?since=$LAST_CHECK" \
CHANGES=$(curl -s "http://localhost:3002/api/changes?since=$LAST_CHECK" \
-H "X-API-Key: YOUR_KEY")
# Filter for agent assignments
@ -246,7 +246,7 @@ done
### Detect Completed Tasks
```bash
CHANGES=$(curl -s "http://localhost:3001/api/changes?since=$LAST_CHECK" \
CHANGES=$(curl -s "http://localhost:3002/api/changes?since=$LAST_CHECK" \
-H "X-API-Key: YOUR_KEY")
COMPLETED=$(echo "$CHANGES" | jq -r \
@ -255,7 +255,7 @@ COMPLETED=$(echo "$CHANGES" | jq -r \
for TASK_ID in $COMPLETED; do
echo "Task completed: $TASK_ID"
# Post to squad chat
curl -X POST http://localhost:3001/api/chat/squad \
curl -X POST http://localhost:3002/api/chat/squad \
-H "Content-Type: application/json" \
-H "X-API-Key: $YOUR_KEY" \
-d "{\"agent\":\"VERITAS\",\"message\":\"Task $TASK_ID completed!\"}"
@ -266,7 +266,7 @@ done
```bash
# Only check changes for rubicon project
CHANGES=$(curl -s "http://localhost:3001/api/changes?since=$LAST_CHECK&project=rubicon" \
CHANGES=$(curl -s "http://localhost:3002/api/changes?since=$LAST_CHECK&project=rubicon" \
-H "X-API-Key: YOUR_KEY")
echo "Changes in Rubicon project:"
@ -313,7 +313,7 @@ elif response.status == 200:
```bash
# Fetch entire task list every poll
curl http://localhost:3001/api/tasks \
curl http://localhost:3002/api/tasks \
-H "X-API-Key: YOUR_KEY"
# Returns ~100KB for 50 tasks
# Requires parsing entire list to find changes
@ -323,7 +323,7 @@ curl http://localhost:3001/api/tasks \
```bash
# Fetch only changes
curl "http://localhost:3001/api/changes?since=..." \
curl "http://localhost:3002/api/changes?since=..." \
-H "X-API-Key: YOUR_KEY"
# Returns ~2KB for 5 changes
# Changes are pre-identified

56
docs/features/prd-driven-development.md
View file

@ -43,7 +43,7 @@ Veritas Kanban provides native infrastructure for every phase of autonomous deve
Before setting up PRD-driven autonomous development:
1. **VK server running** — `http://localhost:3001` (or your configured port)
1. **VK server running** — `http://localhost:3002` (or your configured port)
2. **API access** — API key configured (`VERITAS_API_KEY` or `VERITAS_ADMIN_KEY`)
3. **Git repository** — Your project is a git repository
4. **Quality checks** — You have automated checks (tests, linters, typecheck)
@ -92,7 +92,7 @@ Before setting up PRD-driven autonomous development:
**Via API:**
```bash
curl -X POST http://localhost:3001/api/templates \
curl -X POST http://localhost:3002/api/templates \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
@ -164,7 +164,7 @@ QUALITY GATES (enforced by reviewGate):
- Safety: Input validation, error handling, no secrets (≥8/10)
- Testing: Unit tests, edge cases covered (≥8/10)
VK_API: http://localhost:3001
VK_API: http://localhost:3002
SQUAD_CHAT_ENDPOINT: POST /api/chat/squad
When all subtasks complete:
@ -192,7 +192,7 @@ vk create "Feature: Test PRD Workflow" \
vk automation:start <task-id>
```
Monitor via Squad Chat at `http://localhost:3001/squad` (if available) or Activity page.
Monitor via Squad Chat at `http://localhost:3002/squad` (if available) or Activity page.
---
@ -209,7 +209,7 @@ When assigned a PRD task (identified by subtasks and enforcement gates), follow
1. **Fetch task details:**
```bash
GET http://localhost:3001/api/tasks/{TASK_ID}
GET http://localhost:3002/api/tasks/{TASK_ID}
```
2. **Verify it's a PRD task:**
@ -219,7 +219,7 @@ When assigned a PRD task (identified by subtasks and enforcement gates), follow
3. **Announce start to Squad Chat:**
```bash
POST http://localhost:3001/api/chat/squad
POST http://localhost:3002/api/chat/squad
{
"agent": "YOUR_AGENT_NAME",
"message": "Starting {{task.title}} — {{task.subtasks.length}} stories",
@ -231,12 +231,12 @@ When assigned a PRD task (identified by subtasks and enforcement gates), follow
4. **Start time tracking:**
```bash
POST http://localhost:3001/api/tasks/{TASK_ID}/time/start
POST http://localhost:3002/api/tasks/{TASK_ID}/time/start
```
5. **Emit telemetry start:**
```bash
POST http://localhost:3001/api/telemetry/events
POST http://localhost:3002/api/telemetry/events
{
"type": "run.started",
"taskId": "{TASK_ID}",
@ -260,7 +260,7 @@ Parse previous learnings to inform current implementation.
**Step 2: Find next incomplete story**
```bash
GET http://localhost:3001/api/tasks/{TASK_ID}
GET http://localhost:3002/api/tasks/{TASK_ID}
# Filter subtasks where completed === false
# Pick first incomplete subtask
@ -273,7 +273,7 @@ If no incomplete stories remain, proceed to **Completion** section.
**Step 3: Announce story start**
```bash
POST http://localhost:3001/api/chat/squad
POST http://localhost:3002/api/chat/squad
{
"agent": "YOUR_AGENT_NAME",
"message": "{{CURRENT_STORY_TITLE}}: Implementing...",
@ -321,7 +321,7 @@ EXIT_CODE_TEST=$?
```bash
# Announce failure
POST http://localhost:3001/api/chat/squad
POST http://localhost:3002/api/chat/squad
{
"agent": "YOUR_AGENT_NAME",
"message": "{{CURRENT_STORY_TITLE}}: Quality check failed (typecheck: {{EXIT_CODE_TYPECHECK}}, lint: {{EXIT_CODE_LINT}}, test: {{EXIT_CODE_TEST}}) — fixing...",
@ -331,13 +331,13 @@ POST http://localhost:3001/api/chat/squad
# Fix issues and retry (max 2 attempts)
# If 2 failures, escalate:
POST http://localhost:3001/api/tasks/{TASK_ID}
POST http://localhost:3002/api/tasks/{TASK_ID}
{
"status": "blocked",
"blockReason": "Quality checks failing after 2 attempts — human review needed"
}
POST http://localhost:3001/api/tasks/{TASK_ID}/comments
POST http://localhost:3002/api/tasks/{TASK_ID}/comments
{
"text": "Story {{CURRENT_STORY_TITLE}} blocked: quality checks failing. Errors:\n\n{{ERROR_DETAILS}}",
"author": "YOUR_AGENT_NAME"
@ -355,7 +355,7 @@ git commit -m "feat({{CURRENT_STORY_ID}}): {{CURRENT_STORY_TITLE}}"
COMMIT_HASH=$(git rev-parse --short HEAD)
# Announce commit
POST http://localhost:3001/api/chat/squad
POST http://localhost:3002/api/chat/squad
{
"agent": "YOUR_AGENT_NAME",
"message": "{{CURRENT_STORY_TITLE}}: Tests passing — committed ({{COMMIT_HASH}})",
@ -390,10 +390,10 @@ EOF
**Step 9: Mark subtask complete**
```bash
POST http://localhost:3001/api/tasks/{TASK_ID}/subtasks/{CURRENT_STORY_ID}/complete
POST http://localhost:3002/api/tasks/{TASK_ID}/subtasks/{CURRENT_STORY_ID}/complete
# Announce completion
POST http://localhost:3001/api/chat/squad
POST http://localhost:3002/api/chat/squad
{
"agent": "YOUR_AGENT_NAME",
"message": "{{CURRENT_STORY_TITLE}}: Complete — marked as done",
@ -413,7 +413,7 @@ When all subtasks are complete:
**Step 1: Submit review scores**
```bash
POST http://localhost:3001/api/tasks/{TASK_ID}/review
POST http://localhost:3002/api/tasks/{TASK_ID}/review
{
"decision": "approved",
"scores": {
@ -436,7 +436,7 @@ POST http://localhost:3001/api/tasks/{TASK_ID}/review
**Step 2: Add closing comment**
```bash
POST http://localhost:3001/api/tasks/{TASK_ID}/comments
POST http://localhost:3002/api/tasks/{TASK_ID}/comments
{
"text": "Completed {{task.title}}:\n{{STORY_SUMMARY_LIST}}\n\nAll tests passing, security review clean.",
"author": "YOUR_AGENT_NAME"
@ -460,13 +460,13 @@ EOF
**Step 4: Stop time tracking**
```bash
POST http://localhost:3001/api/tasks/{TASK_ID}/time/stop
POST http://localhost:3002/api/tasks/{TASK_ID}/time/stop
```
**Step 5: Emit telemetry completion**
```bash
POST http://localhost:3001/api/telemetry/events
POST http://localhost:3002/api/telemetry/events
{
"type": "run.completed",
"taskId": "{TASK_ID}",
@ -476,7 +476,7 @@ POST http://localhost:3001/api/telemetry/events
}
# Report token usage
POST http://localhost:3001/api/telemetry/events
POST http://localhost:3002/api/telemetry/events
{
"type": "run.tokens",
"taskId": "{TASK_ID}",
@ -492,13 +492,13 @@ POST http://localhost:3001/api/telemetry/events
**Step 6: Mark task complete**
```bash
POST http://localhost:3001/api/tasks/{TASK_ID}/complete
POST http://localhost:3002/api/tasks/{TASK_ID}/complete
{
"summary": "Completed {{task.title}} — {{COMPLETED_COUNT}} stories, all tests passing"
}
# Announce completion
POST http://localhost:3001/api/chat/squad
POST http://localhost:3002/api/chat/squad
{
"agent": "YOUR_AGENT_NAME",
"message": "{{task.title}}: Complete — {{COMPLETED_COUNT}} stories, {{COMMIT_COUNT}} commits, {{TOTAL_ELAPSED}}",
@ -513,7 +513,7 @@ POST http://localhost:3001/api/chat/squad
```bash
# Log error details
POST http://localhost:3001/api/errors
POST http://localhost:3002/api/errors
{
"taskId": "{TASK_ID}",
"errorType": "api_error",
@ -522,7 +522,7 @@ POST http://localhost:3001/api/errors
}
# Notify via Squad Chat
POST http://localhost:3001/api/chat/squad
POST http://localhost:3002/api/chat/squad
{
"agent": "YOUR_AGENT_NAME",
"message": "ERROR: API call failed ({{API_ENDPOINT}}) — {{ERROR_MESSAGE}}",
@ -538,7 +538,7 @@ Block task and escalate to human (see Step 6 retry logic above).
**On git conflicts:**
```bash
POST http://localhost:3001/api/tasks/{TASK_ID}
POST http://localhost:3002/api/tasks/{TASK_ID}
{
"status": "blocked",
"blockReason": "Git merge conflict — human resolution needed"
@ -772,7 +772,7 @@ Squad Chat provides real-time visibility — ensure it's configured:
```bash
# Test Squad Chat posting
curl -X POST http://localhost:3001/api/chat/squad \
curl -X POST http://localhost:3002/api/chat/squad \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
@ -916,7 +916,7 @@ Use interactive development to design and build the first iteration, then use PR
**Check:**
1. Squad Chat endpoint: `POST http://localhost:3001/api/chat/squad`
1. Squad Chat endpoint: `POST http://localhost:3002/api/chat/squad`
2. Authorization header
3. Required fields: `agent`, `message`, `model`, `tags`

18
docs/features/squad-chat.md
View file

@ -21,7 +21,7 @@ Squad Chat provides a dedicated communication channel for AI agents working on y
```bash
# Agent message
curl -X POST http://localhost:3001/api/chat/squad \
curl -X POST http://localhost:3002/api/chat/squad \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_KEY" \
-d '{
@ -30,7 +30,7 @@ curl -X POST http://localhost:3001/api/chat/squad \
}'
# System message (agent event)
curl -X POST http://localhost:3001/api/chat/squad \
curl -X POST http://localhost:3002/api/chat/squad \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_KEY" \
-d '{
@ -43,7 +43,7 @@ curl -X POST http://localhost:3001/api/chat/squad \
}'
# Human message
curl -X POST http://localhost:3001/api/chat/squad \
curl -X POST http://localhost:3002/api/chat/squad \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_KEY" \
-d '{
@ -56,15 +56,15 @@ curl -X POST http://localhost:3001/api/chat/squad \
```bash
# Get all messages (default: includes system messages)
curl http://localhost:3001/api/chat/squad \
curl http://localhost:3002/api/chat/squad \
-H "X-API-Key: YOUR_KEY"
# Hide system messages
curl "http://localhost:3001/api/chat/squad?includeSystem=false" \
curl "http://localhost:3002/api/chat/squad?includeSystem=false" \
-H "X-API-Key: YOUR_KEY"
# Get messages for specific date
curl "http://localhost:3001/api/chat/squad?date=2026-02-07" \
curl "http://localhost:3002/api/chat/squad?date=2026-02-07" \
-H "X-API-Key: YOUR_KEY"
```
@ -181,7 +181,7 @@ System messages include `[system]` and `[event_type]` tags, plus optional metada
Agents can coordinate work by posting status updates:
```bash
curl -X POST http://localhost:3001/api/chat/squad \
curl -X POST http://localhost:3002/api/chat/squad \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_KEY" \
-d '{
@ -195,7 +195,7 @@ curl -X POST http://localhost:3001/api/chat/squad \
Humans can check progress and provide guidance:
```bash
curl -X POST http://localhost:3001/api/chat/squad \
curl -X POST http://localhost:3002/api/chat/squad \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_KEY" \
-d '{
@ -234,7 +234,7 @@ The squad chat panel is accessible via the main navigation. It includes:
### Messages Not Appearing
1. Check WebSocket connection status in browser dev tools
2. Verify API key is valid: `curl http://localhost:3001/api/health -H "X-API-Key: YOUR_KEY"`
2. Verify API key is valid: `curl http://localhost:3002/api/health -H "X-API-Key: YOUR_KEY"`
3. Check server logs for errors
### Webhook Not Firing

2
docs/internal/V3_FINAL_REVIEW.md
View file

@ -235,7 +235,7 @@ steps:
**curl commands work** (validated against live server):
```bash
curl -X POST http://localhost:3001/api/workflows/hello-world/runs \
curl -X POST http://localhost:3002/api/workflows/hello-world/runs \
-H "Content-Type: application/json" \
-d '{}'
# ✅ Returns 201 with run object

2
docs/lessons/2026-02-07-parallel-merge-incident.md
View file

@ -93,7 +93,7 @@ const port = window.location.port === '3000' ? 3001 : 3000;
### 8. Hardcoded Values Throughout Codebase
**What:** Agent callback URLs, API client defaults, Swagger base URL all hardcoded to `localhost:3001`. Various timeouts and limits were magic numbers.
**What:** Agent callback URLs, API client defaults, Swagger base URL all hardcoded to `localhost:3002`. Various timeouts and limits were magic numbers.
**Why:** Quick-and-dirty development without env var abstraction.
**Impact:** Every hardcoded value had to be hunted down and fixed manually.

12
docs/security.md
View file

@ -38,20 +38,20 @@ Clients can authenticate using any of these methods:
```bash
curl -H "Authorization: Bearer your-api-key" \
http://localhost:3001/api/tasks
http://localhost:3002/api/tasks
```
### 2. X-API-Key Header
```bash
curl -H "X-API-Key: your-api-key" \
http://localhost:3001/api/tasks
http://localhost:3002/api/tasks
```
### 3. Query Parameter (WebSocket)
```javascript
const ws = new WebSocket('ws://localhost:3001/ws?api_key=your-api-key');
const ws = new WebSocket('ws://localhost:3002/ws?api_key=your-api-key');
```
## Roles and Permissions
@ -114,7 +114,7 @@ const key = generateApiKey('vk'); // e.g., vk_AbCdEf123...
Check the current authentication configuration:
```bash
curl http://localhost:3001/api/auth/status
curl http://localhost:3002/api/auth/status
```
Response:
@ -131,7 +131,7 @@ Response:
### Health Check (Unauthenticated)
```bash
curl http://localhost:3001/health
curl http://localhost:3002/health
```
## WebSocket Authentication
@ -140,7 +140,7 @@ WebSocket connections are authenticated on connect:
```javascript
// With API key
const ws = new WebSocket('ws://localhost:3001/ws?api_key=your-key');
const ws = new WebSocket('ws://localhost:3002/ws?api_key=your-key');
ws.onclose = (event) => {
if (event.code === 4001) {

2
server/src/config/env.ts
View file

@ -47,7 +47,7 @@ const booleanString = z
export const envSchema = z.object({
// ── Server ──────────────────────────────────────────────────────────
/** HTTP port the server listens on */
PORT: portSchema.default('3001'),
PORT: portSchema.default('3002'),
/** Node environment: development | production | test */
NODE_ENV: z.enum(['development', 'production', 'test']).optional().default('development'),

4
server/src/index.ts
View file

@ -135,7 +135,7 @@ if (trustProxy !== undefined && trustProxy !== '') {
}
}
const PORT = process.env.PORT || 3001;
const PORT = process.env.PORT || 3002;
// ============================================
// Performance: ETag Generation
@ -179,7 +179,7 @@ app.set('etag', 'weak');
// new Function() for module evaluation.
//
// Note: In dev, Vite (port 3000) serves the frontend and proxies /api
// to Express (port 3001). These CSP headers apply to Express responses
// to Express (port 3002). These CSP headers apply to Express responses
// only, not to Vite-served HTML. They still matter for any HTML served
// directly by Express (e.g., error pages) and as defense-in-depth.
//

2
web/src/hooks/useWebSocket.ts
View file

@ -63,7 +63,7 @@ const DEFAULT_MAX_RECONNECT_ATTEMPTS = 20;
function getDefaultWsUrl(): string {
const protocol = window.location.protocol === 'https:' ? 'wss:' : 'ws:';
// Always use the same host:port as the current page for WebSocket connection
// This works for both dev (Vite on :5173) and production (server on :3000/:3001)
// This works for both dev (Vite on :5173) and production (server on :3000/:3002)
return `${protocol}//${window.location.host}/ws`;
}