docs(v2.0): features/value doc + plan↔code↔docs consistency review

- docs/FEATURES.md (new): feature summaries + real value, what's new since 1.0,
  first-of-its-kind/differentiated (hedged), full catalog + roadmap. Sourced from
  the repo + the author's "Agentic AI Architectures" manuscript (ch08/ch09).
- Architect consistency review (master plan ↔ code ↔ docs): fixed stale-doc bugs
  in place — SPEC.md (THINKING emit, KaibanHandlerResult/signal, 20KB→bytes),
  ACTOR_MODEL.md (state diagram), SECURITY_FEATURES.md + ASVS-5.0 (paths + the
  now-built global limiter), README/EXAMPLES (linear-backoff wording, Vite 8,
  Node ≥20.19, test count 1155), .env.example (VALID_HITL_DECISIONS default +
  ROLE var), ADR-005 (sanitizeTraceHeaders note), llms.txt (a2a-executor ref).
- docs/roadmap/V2.1-ROADMAP.md: recorded genuine deferrals (CR-1 A2A forward-compat
  gRPC/webhook/JWS/lifecycle states; CR-2 supervision backoff+jitter/loop guards/
  half-open breaker; CR-3 provenance gate-validator + egress; CR-4 Evals/Langfuse/
  Promptfoo/anti-hallucination harness).

Verdict: v2.0 plan/code/docs are consistent. No code changes; CI stays green.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: andreibesleaga

.env.example

@@ -33,7 +33,13 @@ MESSAGING_DRIVER=bullmq
 # Leave unset to use ConsoleSpanExporter (dev mode — verbose, not suitable for production)
 # OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318/v1/traces
 
-# Comma-separated list of agent IDs this worker node serves (required)
+# Process role for the single combined image (src/main/index.ts dispatches on it).
+#   ROLE=gateway → HTTP / WebSocket / A2A / MCP front door only (no task-consuming actors)
+#   ROLE=worker  → loads the AGENT_IDS pool and wires real LLM-backed handlers
+# Unset defaults to "gateway". (ADR-013 gateway/worker split.)
+# ROLE=gateway
+
+# Comma-separated list of agent IDs this worker node serves (required for ROLE=worker)
 AGENT_IDS=researcher,writer,editor
 
 # LLM Configuration — Standard OpenAI OR OpenRouter (or any OpenAI-compatible API)
@@ -146,8 +152,10 @@ OPENAI_API_KEY=your_openai_api_key_here
 # ── HITL Decision Options ───────────────────────────────────────
 # Comma-separated list of valid human decisions for the HITL gate.
 # The gateway validates incoming board decisions against this list.
-# VIEW is informational only (re-prompts terminal); it does not resolve the gate.
-VALID_HITL_DECISIONS=PUBLISH,REVISE,REJECT,VIEW
+# This matches the code default (src/main/config.ts). Do NOT add VIEW here:
+# VIEW is an interactive terminal-only action that re-prompts the orchestrator
+# prompt — it does not resolve the gate and is NOT a valid board/gateway decision.
+VALID_HITL_DECISIONS=PUBLISH,REVISE,REJECT
 
 # ── Agent Identity (set per-node process / container) ───────────
 # Each agent node reads its own identity from AGENT_ID.

EXAMPLES.md

@@ -571,7 +571,7 @@ interactive Human-in-the-Loop Approve / Revise / Reject controls.
 ### Prerequisites
 
 - Any kaiban-distributed gateway running (e.g. `./scripts/blog-team.sh start`)
-- Node.js ≥ 18 (board only; gateway still needs ≥ 22)
+- Node.js ≥ 20.19 (board uses Vite 8, which needs Node 20.19+/22.12+; gateway needs ≥ 22)
 
 ### Start
 

README.md

@@ -277,7 +277,7 @@ stateDiagram-v2
     TODO --> DOING : Worker Claims Task
 
     DOING --> DONE : Inference Success
-    DOING --> TODO : Retry (max 3×, exp. backoff)
+    DOING --> TODO : Retry (max 3×, linear backoff)
     DOING --> BLOCKED : Max Retries Exceeded (→ kaiban-events-failed)
 
     DOING --> AWAITING_VALIDATION : HITL Required
@@ -956,7 +956,7 @@ kaiban-distributed/
 │   │       └── circuit-breaker.ts    # ICircuitBreaker — success/failure tracking
 │   ├── application/
 │   │   └── actor/
-│   │       └── AgentActor.ts  # Core: retry×3 + exp backoff, DLQ, firewall, circuit breaker
+│   │       └── AgentActor.ts  # Core: retry×3 + linear backoff, DLQ, firewall, circuit breaker
 │   ├── adapters/
 │   │   ├── gateway/
 │   │   │   ├── GatewayApp.ts       # Express: /health, agent-card, /a2a/rpc, 404
@@ -989,7 +989,7 @@ kaiban-distributed/
 │       ├── index.ts    # Composition root: wires all layers + security deps, starts HTTP + actors
 │       └── config.ts   # loadConfig(); TLS config; security feature flags
 ├── tests/
-│   ├── unit/           # 769 unit tests — mirrors src/ structure, 100% coverage
+│   ├── unit/           # 1155 unit tests — mirrors src/ structure, 100% coverage
 │   └── e2e/
 │       ├── distributed-execution.test.ts      # BullMQ: execution, fault tolerance, state sync
 │       ├── fan-out-fan-in.test.ts             # Parallel fan-out/fan-in workflow (7 scenarios)
@@ -1027,7 +1027,7 @@ kaiban-distributed/
 │   │   ├── store/boardStore.ts            # Zustand: applyDelta, setConnectionStatus, addLog
 │   │   ├── socket/socketClient.ts         # Socket.io singleton + sendHitlDecision()
 │   │   └── components/                    # layout/ · workflow/ · agents/ · kanban/ · economics/ · log/
-│   ├── package.json                       # React 18, Vite 6, Tailwind, socket.io-client, zustand
+│   ├── package.json                       # React 18, Vite 8, Tailwind, socket.io-client, zustand
 │   └── .env.example                       # VITE_GATEWAY_URL=http://localhost:3000
 ├── docker-compose.yml                     # Full root stack (Redis + Kafka + single worker)
 ├── Dockerfile                             # Multi-stage: builder (npm install + tsc) → runner (non-root)