ci: stop master workflow on PR updates

Remove the stale pull_request trigger from master.yml so PR branch commits do not launch the master workflow.

Maintenance patch for PR #10941.

.forgejo/workflows/master.yml

@@ -3,8 +3,6 @@ name: CI
 on:
     push:
         branches: [master, develop]
-    pull_request:
-        branches: [master, develop]
 
 vars:
     docker_prefix: "http://harbor.cleverthis.com/docker/"

CHANGELOG.md

@@ -5,6 +5,10 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+### Added
+
+- **Milestone documentation (v3.8.0 & v3.9.0)**: Added `docs/milestones/` section with comprehensive milestone guides — `index.md` (milestones overview), `v3.8.0.md` (M9 Server Implementation covering A2A JSON-RPC 2.0 protocol, transports, FastAPI server, authentication, multi-device namespace support, PostgreSQL backend, LangGraph Platform integration, and Docker/Kubernetes deployment), and `v3.9.0.md` (documentation standards, feature updates, migration notes from v3.8.0, and progress tracking). Updated `mkdocs.yml` navigation with Milestones section under Development category. Closes #10010.
+
 ### Security
 
 - **aiohttp upgraded to >=3.13.4 to remediate CVE-2026-34513 and CVE-2026-34515** (#1549, #1544):

CONTRIBUTORS.md

@@ -25,4 +25,10 @@ Below are some of the specific details of various contributions.
 * This project was made possible thanks to considerable donation of time, money, and resources by CleverThis, Inc.
 * HAL 9000 has contributed automated bug fixes, CLI output formatting improvements, and ongoing maintenance as part of the CleverAgents automation system.
 * HAL 9000 has contributed the file edit encoding parameter fix (PR #8258 / issue #7559).
+
+<<* HAL 9000 has contributed comprehensive milestone documentation for v3.8.0 (M9 Server Implementation) and v3.9.0 (Documentation & Feature Updates Release), including the A2A JSON-RPC 2.0 protocol specification, transport modes, FastAPI server architecture, authentication schemes, PostgreSQL persistence, LangGraph Platform integration, Docker/Kubernetes deployment guides, documentation standards, and migration notes (PR #10941 / issue #10010).
+* HAL 9000 has contributed the architecture-pool-supervisor milestone assignment feature (PR #8188 / issue #7521): added `forgejo_update_pull_request` permission and documented the PR workflow for major spec changes, enabling automatic milestone assignment for specification PRs.
+* HAL 9000 has contributed the git worktree TOCTOU race condition fix (PR #8178 / issue #7507): replaced the unsafe mkdtemp() + rmdir() pattern with a parent-directory approach to eliminate the race window in concurrent git worktree operations.
+* HAL 9000 has contributed the git_tools TOCTOU race condition fix (PR #8255 / issue #7619): eliminated the Time-Of-Check-To-Time-Of-Use race in `_get_base_env()` by adding double-checked locking with a module-level `threading.Lock`, preventing concurrent threads from writing conflicting environment snapshots.
+* HAL 9000 has contributed the mandatory PR compliance checklist to `implementation-supervisor.md` (#9824): added an 8-item checklist to the worker prompt body with concrete items covering CHANGELOG.md, CONTRIBUTORS.md, commit footer, CI verification, BDD tests, Epic reference, labels, and milestone assignment to eliminate systemic PR merge blockers.
 * HAL 9000 has contributed comprehensive milestone documentation for v3.6.0 (Advanced Concepts & Deferred Features) and v3.7.0 (TUI Implementation) (PR #9903): split into sub-documents covering context strategies, LLM backends, resource types, A2A rename, container tool execution, scope chain resolution, cost/safety budgets, E2E workflow tests, code review examples, plugin architecture, TUI layout, persona system, reference/command input, session management, configuration, and TuiMaterializer integration.

docs/milestones/index.md

@@ -0,0 +1,55 @@
+# Milestones — v3.8.0 Server Implementation & v3.9.0 Documentation Release
+
+> **Milestone:** Milestones v3.8.0 (M9) and v3.9.0 — Server Implementation and Documentation Update
+> **Related ADRs:** [ADR-023 Server Mode](../adr/ADR-023-server-mode.md),
+> [ADR-047 A2A Standard Adoption](../adr/ADR-047-acp-standard-adoption.md),
+> [ADR-048 Server Application Architecture](../adr/ADR-048-server-application-architecture.md)
+
+---
+
+## Overview
+
+This section contains the comprehensive milestone documentation for the CleverAgents platform's next two release cycles:
+
+### v3.8.0 (M9: Server Implementation)
+
+**Goal:** Deploy a production-ready A2A JSON-RPC 2.0 server that exposes all CleverAgents capabilities through HTTP, stdio, and agent-to-agent transports — enabling remote execution, multi-device coordination, and infrastructure deployment via Docker and Kubernetes.
+
+**Key areas covered:**
+- [v3.8.0 Server Implementation Guide](v3.8.0.md) — Full M9 specification including protocol, transports, authentication, PostgreSQL backend, LangGraph Platform integration, and deployment.
+
+### v3.9.0 (Documentation & Feature Updates Release)
+
+**Goal:** Standardize documentation practices across the project, implement feature updates documented in existing architecture decisions, and provide migration guidance from v3.8.0 changes.
+
+**Key areas covered:**
+- [v3.9.0 Documentation & Feature Updates](v3.9.0.md) — Scope, standards, key changes, migration notes, and progress tracking.
+
+---
+
+## How to Use This Section
+
+Each milestone document is self-contained and includes:
+
+1. **Technical specification** — Architecture, APIs, wire formats
+2. **Implementation details** — Key code paths, patterns, and conventions
+3. **ADR cross-references** — Related architecture decisions with relative links
+4. **Quick start guides** — Step-by-step getting started instructions
+5. **Error codes and troubleshooting** — Reference tables for common failures
+6. **Tech stack summary** — Dependencies, versions, and runtime requirements
+
+---
+
+## Milestones at a Glance
+
+| Milestone | Theme | Key Deliverable | Status |
+|-----------|-------|-----------------|--------|
+| v3.0.0 – v3.5.0 | Foundation & Stability | Core CLI, actor system, plan lifecycle | Released |
+| v3.6.0 | Advanced Concepts | Context strategies, LLM backends, resource types | Released |
+| v3.7.0 | TUI Implementation | Textual-based terminal interface | In Progress |
+| **v3.8.0** | **Server Implementation** | **A2A server, transports, PostgreSQL, deployment** | **In Progress** |
+| **v3.9.0** | **Documentation & Features** | **Docs standards, feature updates, migration notes** | **In Progress** |
+
+---
+
+*Generated by [AUTO-DOCS-2] — CleverAgents Documentation Bot*

docs/milestones/v3.8.0.md

@@ -0,0 +1,564 @@
+# Milestone v3.8.0 — M9: Server Implementation
+
+> **Milestone:** v3.8.0 (M9) — Server Implementation
+> **Status:** In Progress
+> **Goal:** Deliver a production-ready CleverAgents A2A server supporting JSON-RPC 2.0, multiple transports, authentication, PostgreSQL persistence, LangGraph Platform integration, and Docker/Kubernetes deployment.
+>
+> **Key ADRs:** [ADR-023 Server Mode](../adr/ADR-023-server-mode.md),
+> [ADR-047 A2A Standard Adoption](../adr/ADR-047-acp-standard-adoption.md),
+> [ADR-048 Server Application Architecture](../adr/ADR-048-server-application-architecture.md),
+> [ADR-049] (pending)
+
+---
+
+## Overview
+
+M9 shifts CleverAgents from a CLI-only tool to a remotely operable service. The centerpiece is an A2A-compatible JSON-RPC 2.0 server that exposes the full actor platform over HTTP and stdio transports, with production-grade authentication, multi-user PostgreSQL persistence, LangGraph Platform integration for remote graph execution, and infrastructure-as-code deployability via Docker and Kubernetes.
+
+This milestone bridges the gap between local-first CLI usage and distributed agent orchestration — enabling scenarios such as headless automated execution, multi-device namespace sharing, and cloud-native scalability.
+
+---
+
+## 1. A2A Protocol (JSON-RPC 2.0)
+
+The server implements the Agent-to-Agent (A2A) protocol defined in **ADR-047** using **JSON-RPC 2.0** as the wire format. All interactions follow strict RPC semantics with request-response pairs and SSE streaming for long-running operations.
+
+### 1.1 Wire Format
+
+Every A2A message is a valid JSON-RPC 2.0 envelope:
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": "a3f8c2e1-7b4d-4f59-8e6a-1c2d3e4f5a6b",
+  "method": "agents.run",
+  "params": {
+    "actor_id": "anthropic/claude-sonnet-4-20250514",
+    "content": [{"type": "text", "text": "Analyze the latest log files"}]
+  }
+}
+```
+
+Successful responses and server-sent errors follow:
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": "a3f8c2e1-7b4d-4f59-8e6a-1c2d3e4f5a6b",
+  "result": {
+    "session_id": "01K9XZ7R2QF5MNPWDG3H6YT4AV",
+    "status": "completed",
+    "content": [{"type": "text", "text": "Analysis results..."}],
+    "cost": {"total_tokens": 4892, "total_cost_usd": 0.0124}
+  }
+}
+```
+
+Error responses use standard JSON-RPC error codes:
+
+| Code | Meaning | Example Use |
+|------|---------|-------------|
+| `-32700` | Parse error | Invalid JSON body |
+| `-32600` | Invalid request | Missing/invalid `jsonrpc` field |
+| `-32601` | Method not found | Unknown RPC method |
+| `-32602` | Invalid params | Missing required `actor_id` |
+| `-32603` | Internal error | Server-internal failure (e.g., DB connection loss) |
+| `-32000` to `-32099` | Server errors | Actor not found, auth failure, resource exhausted |
+
+### 1.2 Agent Cards
+
+Each server advertises its capabilities via an **Agent Card** — a JSON document discoverable at `/agent-card`:
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": "capability-discovery",
+  "result": {
+    "server_version": "3.8.0-dev",
+    "supported_methods": ["agents.run", "agents.list", "sessions.list", "sessions.show"],
+    "transports": ["stdio", "http"],
+    "auth_schemes": ["oauth2", "api_key", "bearer"],
+    "max_content_length_bytes": 5242880,
+    "sse_streaming_supported": true,
+    "actor_namespace_count": 127
+  }
+}
+```
+
+This enables tool integrations (IDE plugins, CI runners, other agents) to discover server capabilities without hardcoded assumptions.
+
+### 1.3 Standard Operations
+
+| Operation | JSON-RPC Method | Description |
+|-----------|-----------------|-------------|
+| Run agent | `agents.run` | Execute an actor with content and receive response |
+| List actors | `actors.list` | Enumerate available actors with metadata |
+| List sessions | `sessions.list` | Show recent session history for the auth'd user |
+| Show session | `sessions.show` | Retrieve full content of a specific session |
+| Delete session | `sessions.delete` | Soft-delete a session by ID |
+| Export session | `sessions.export` | Export a session in JSON or Markdown format |
+
+---
+
+## 2. Transport Modes
+
+The server supports three transport modes, each suited to different deployment scenarios.
+
+### 2.1 Local (stdio)
+
+**Use case:** CLI-to-server communication, local debugging, process-local orchestration.
+
+- Standard input/output pipe
+- No network binding required
+- Ideal for `cleveragents` CLI communicating with a local server process
+- Supports both synchronous and streaming responses
+
+```bash
+# Local server run via stdio
+cleveragents server run --transport stdio --port 0
+```
+
+### 2.2 Server (HTTP)
+
+**Use case:** Remote execution, web/IDE integrations, distributed agent networks.
+
+- Binds to `host:port` (default `0.0.0.0:8080`)
+- Accepts JSON-RPC requests over HTTPS (TLS enforced in production)
+- SSE-based streaming for long-running operations
+- Health check endpoint at `/health`
+- Agent card at `/agent-card`
+
+```bash
+# HTTP server with TLS
+cleveragents server run --transport http \
+  --host 0.0.0.0 --port 8443 \
+  --tls-cert /etc/ssl/certs/server.crt --tls-key /etc/ssl/private/server.key
+```
+
+### 2.3 External A2A Agent
+
+**Use case:** Agent-to-agent communication between remote servers.
+
+- Server acts as both client (initiating outbound calls) and server (accepting inbound calls)
+- Uses the same JSON-RPC wire format over HTTP
+- Supports cross-server actor delegation: an agent on Server A can request execution of an actor on Server B
+
+---
+
+## 3. FastAPI Server Implementation
+
+The server is built with **FastAPI** (>=0.109.0) for type-safe, auto-generated API documentation and high-performance async I/O.
+
+### 3.1 Architecture
+
+```
+src/cleveragents/server/
+├── __init__.py           # Package init
+├── app.py                # FastAPI application factory
+├── config.py             # Server configuration (pydantic settings)
+├── routes/               # JSON-RPC route handlers
+│   ├── agents.py         # agents.run, agents.list
+│   ├── sessions.py       # sessions.list, show, delete, export
+│   ├── actors.py         # actors.list, actors.show
+│   └── card.py           # Agent Card endpoint
+├── middleware/           # Auth and request middleware
+│   ├── auth.py           # OAuth2, API key, bearer token
+│   └── rate_limit.py     # Per-user rate limiting
+├── streaming/            # SSE streaming for long operations
+│   └── sse.py            # Server-sent events implementation
+└── exceptions.py         # A2A-compatible error handling
+```
+
+### 3.2 Request Lifecycle
+
+1. **Authentication middleware** validates credentials (OAuth2 token, API key, or bearer)
+2. **JSON-RPC parser** decodes the request envelope and extracts `method` + `params`
+3. **Method dispatcher** routes to the appropriate handler in `routes/`
+4. **Actor execution** invokes the CleverAgents actor system (same as CLI path)
+5. **Response serializer** wraps results in JSON-RPC 2.0 format
+6. **Auth middleware** adds user context to response headers
+
+### 3.3 SSE Streaming
+
+Long-running agent operations stream progress events via Server-Sent Events:
+
+```python
+async def sse_stream(session_id: str) -> AsyncGenerator[str, None]:
+    for event in await session_events.await_updates(session_id):
+        yield f"data: {json.dumps(event.to_dict())}\n\n"
+```
+
+Clients connect with `Accept: text/event-stream` and receive real-time updates.
+
+---
+
+## 4. Authentication
+
+Three authentication schemes are supported, configurable per-deployment:
+
+### 4.1 OAuth2 (Production)
+
+- Uses the CleverAgents OAuth2 server for identity federation
+- Supports code flow and PKCE for mobile/SPA clients
+- Token lifecycle: access token (1h) + refresh token (30d)
+- Claims propagate to `actor.run` calls as user context metadata
+
+```bash
+# Configure OAuth2
+cleveragents server auth oauth2 \
+  --issuer https://accounts.example.com \
+  --client-id cleveragents-server \
+  --scopes "agents:run agents:sessions manage"
+```
+
+### 4.2 API Key (CI/CD, Infrastructure)
+
+- Static key-based authentication for machine-to-machine communication
+- Keys stored hashed in PostgreSQL using bcrypt
+- Per-key scope assignment: read-only, run-only, admin
+
+```bash
+# Generate API key
+cleveragents server auth api-key generate --scope run-sessions
+# Usage: Add header "X-API-Key: <key-value>"
+```
+
+### 4.3 HTTP Bearer (Development/Testing)
+
+- Simple token-based authentication from `Authorization` header
+- Not suitable for production deployment
+- Supports development convenience without full OAuth2 setup
+
+---
+
+## 5. Multi-Device Support
+
+The server supports shared namespaces across multiple connected devices and users.
+
+### 5.1 Shared Namespaces
+
+Users in the same namespace share:
+- Actor registries (all actors visible to all namespace members)
+- Session history (cross-device session continuity)
+- Resource pools (shared files, configs, environments)
+
+```bash
+# Join or create a namespace
+cleveragents server namespace join my-team
+cleveragents namespace create team-alpha --scope shared-sessions
+```
+
+### 5.2 Entity Sync
+
+Device state is synchronized via periodic background sync:
+
+```json
+{
+  "sync_target": "/namespace/team-alpha/sync",
+  "last_sync": "2026-05-04T14:30:00Z",
+  "entities": ["actors", "sessions", "configs"],
+  "conflict_resolution": "last-write-wins"
+}
+```
+
+### 5.3 Auto-Sync
+
+When a device reconnects after disconnection, auto-sync reconciles drift:
+
+- Compares local session state vs. server state via last-modified timestamps
+- Merges non-conflicting changes (e.g., local new sessions + remote updated sessions)
+- Conflicts resolved by last-write-wins policy with audit logging
+
+---
+
+## 6. PostgreSQL Backend
+
+Multi-user persistence replaces the default SQLite store with PostgreSQL for production deployments.
+
+### 6.1 Schema Design
+
+```sql
+-- Sessions table
+CREATE TABLE sessions (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    user_id UUID NOT NULL REFERENCES users(id),
+    namespace TEXT NOT NULL,
+    actor_id TEXT NOT NULL,
+    created_at TIMESTAMPTZ DEFAULT NOW(),
+    updated_at TIMESTAMPTZ DEFAULT NOW(),
+    status TEXT CHECK (status IN ('running', 'completed', 'error')),
+    metadata JSONB DEFAULT '{}'::jsonb
+);
+
+-- Session messages table
+CREATE TABLE session_messages (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    session_id UUID REFERENCES sessions(id) ON DELETE CASCADE,
+    actor TEXT NOT NULL,
+    role TEXT CHECK (role IN ('user', 'assistant', 'system')),
+    content JSONB NOT NULL,
+    cost JSONB DEFAULT '{}'::jsonb
+);
+
+-- Users table
+CREATE TABLE users (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    username TEXT UNIQUE NOT NULL,
+    namespace TEXT NOT NULL,
+    api_key_hash TEXT,
+    oauth_provider TEXT,
+    oauth_sub TEXT,
+    created_at TIMESTAMPTZ DEFAULT NOW()
+);
+
+-- Actors cache table
+CREATE TABLE actors_cached (
+    id SERIAL PRIMARY KEY,
+    actor_id TEXT UNIQUE NOT NULL,
+    provider TEXT NOT NULL,
+    model TEXT NOT NULL,
+    config JSONB NOT NULL,
+    updated_at TIMESTAMPTZ DEFAULT NOW()
+);
+```
+
+### 6.2 Alembic Migrations
+
+Migrations are versioned and tracked via **Alembic** (>=1.13):
+
+```bash
+# Generate a new migration after schema changes
+alembic revision --autogenerate -m "Add session exports table"
+# Apply migrations
+alembic upgrade head
+```
+
+Migration history follows the convention: `m<number>_<description>.py`, e.g., `m9_001_add_pg_session_schema.py`.
+
+### 6.3 Connection Pooling
+
+Production deployments use **PgBouncer** for connection pooling:
+
+- Transaction-mode pooling (recommended) for most workloads
+- Session-mode pooling for streaming operations
+- Pool size tuned to `max_connections / num_server_instances`
+
+---
+
+## 7. LangGraph Platform Integration
+
+The server integrates with the **LangGraph Platform** to enable remote graph execution through CleverAgents actors.
+
+### 7.1 RemoteGraph Client
+
+CleverAgents acts as a client to the LangGraph Platform, using `RemoteGraph` interfaces:
+
+```python
+from langgraph_sdk import get_client
+
+langgraph_client = get_client(server_url=CLEVERAGENTS_LANGGRAPH_URL)
+graph = langgraph_client.get_graph(graph_id="cleveragents-main")
+thread = await graph.create_thread()
+result = await graph.ainvoke(
+    {"session_id": session_id, "content": user_input},
+    thread_id=thread["thread_id"]
+)
+```
+
+### 7.2 Actor-as-Graph Mapping
+
+Each CleverAgents actor maps to a LangGraph state graph:
+
+- **Input schema:** User content + session context → Graph state
+- **Execution:** Graph executes the actor's route tree (deterministic or LLM-driven)
+- **Output formatting:** Graph state → JSON-RPC response format
+- **Checkpoint:** LangGraph automatically persists checkpoints in PostgreSQL
+
+### 7.3 Actor Execution via LangGraph
+
+```python
+async def execute_via_langgraph(actor_id: str, content: list[dict]):
+    actor = await registry.resolve_actor(actor_id)
+    graph_id = f"actor:{actor_id}"
+    
+    async with remote_graph.get_connection(graph_id) as connection:
+        result = await connection.run(
+            state={"content": content},
+            config={"recursion_limit": 50}
+        )
+    return result.output
+```
+
+---
+
+## 8. Docker and Kubernetes Deployment
+
+### 8.1 Docker Deployment
+
+The server ships with a multi-stage Dockerfile for optimized images:
+
+```dockerfile
+# Build stage
+FROM python:3.12-slim AS builder
+WORKDIR /app
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+COPY src/ ./src/
+COPY pyproject.toml ./
+
+# Runtime stage
+FROM python:3.12-slim AS runtime
+COPY --from=builder /usr/local/lib/python3.12/site-packages /usr/local/lib/python3.12/site-packages
+COPY --from=builder /app/src /app/src
+EXPOSE 8080
+CMD ["python", "-m", "cleveragents.server.app"]
+```
+
+Docker Compose for local development:
+
+```yaml
+services:
+  cleveragents-server:
+    build:
+      context: .
+      dockerfile: Dockerfile.server
+    ports:
+      - "8080:8080"
+    environment:
+      - CLEVERAGENTS_DB_URL=postgresql://postgres:password@db:5432/cleveragents
+    depends_on:
+      - db
+  db:
+    image: postgres:16-alpine
+    volumes:
+      - pgdata:/var/lib/postgresql/data
+volumes:
+  pgdata:
+```
+
+### 8.2 Kubernetes Deployment
+
+Production deployments use Helm charts for declarative management:
+
+```yaml
+# helm-chart/Chart.yaml (simplified)
+apiVersion: v2
+name: cleveragents-server
+version: 0.1.0
+description: CleverAgents A2A server deployment
+
+resources:
+  requests:
+    memory: "512Mi"
+    cpu: "250m"
+  limits:
+    memory: "2Gi"  
+    cpu: "1000m"
+
+hpa:
+  minReplicas: 2
+  maxReplicas: 10
+  targetCPUUtilization: 80
+```
+
+Key Kubernetes resources:
+- **Deployment** with rolling update strategy (maxUnavailable: 1, maxSurge: 1)
+- **HorizontalPodAutoscaler** based on CPU/memory/custom metrics
+- **Service** (ClusterIP for internal, LoadBalancer for external access)
+- **Ingress** with TLS termination and path-based routing (`/` for JSON-RPC, `/health`, `/agent-card`)
+- **ConfigMap** and **Secret** for server configuration
+
+### 8.3 Deployment Checklist
+
+- [ ] PostgreSQL database provisioned (RDS or equivalent)
+- [ ] PgBouncer connection pool configured
+- [ ] TLS certificates installed (Let's Encrypt or internal CA)
+- [ ] Health check endpoint verified (`/health` returns HTTP 200)
+- [ ] Database migrations applied via pre-deploy job
+- [ ] Rate limiting thresholds tuned to expected load
+- [ ] Resource limits set (CPU, memory) with appropriate QoS class
+
+---
+
+## 9. CLI Commands Reference
+
+v3.8.0 introduces these new server-related CLI commands:
+
+| Command | Description |
+|---------|-------------|
+| `server run <transport>` | Start the A2A server (stdio or http transport) |
+| `server call <method>` | Send a JSON-RPC request to a running server |
+| `server auth oauth2 configure` | Configure OAuth2 authentication |
+| `server auth api-key generate` | Generate a new API key for machine-to-machine auth |
+| `namespace join <name>` | Join an existing shared namespace |
+| `namespace create <name>` | Create a new shared namespace |
+
+---
+
+## 10. Quick Start: Deploying the Server Locally
+
+```bash
+# 1. Clone and install
+git clone https://github.com/cleveragents/cleveragents-core.git
+cd cleveragents-core
+pip install -e ".[server]"
+
+# 2. Configure PostgreSQL
+export CLEVERAGENTS_DB_URL=postgresql://postgres:password@localhost:5432/cleveragents
+
+# 3. Run migrations
+alembic upgrade head
+
+# 4. Start server (HTTP transport)
+cleveragents server run http --host 0.0.0.0 --port 8080
+
+# 5. Verify
+curl -s http://localhost:8080/health | jq
+curl -s http://localhost:8080/agent-card | jq
+
+# 6. Make a test request
+curl -X POST http://localhost:8080/rpc \
+  -H "Content-Type: application/json" \
+  -d '{
+    "jsonrpc": "2.0",
+    "id": "1",
+    "method": "actors.list",
+    "params": {}
+  }'
+```
+
+---
+
+## 11. Tech Stack Summary
+
+| Component | Version | Purpose |
+|-----------|---------|---------|
+| FastAPI | >=0.109.0 | Web framework |
+| uvicorn | >=0.27.0 | ASGI server |
+| SQLAlchemy | >=2.0 | ORM for PostgreSQL |
+| psycopg2-binary | >=2.9 | PostgreSQL adapter |
+| Alembic | >=1.13 | Database migrations |
+| Pydantic Settings | >=2.5 | Configuration |
+| LangGraph SDK | >=0.1.0 | Remote graph client |
+| aiohttp | >=3.13.4 | HTTP client for SSE/streaming |
+
+---
+
+## 12. Error Codes Reference
+
+| Status Code | JSON-RPC Error Code | Description |
+|-------------|---------------------|-------------|
+| `AUTH_REQUIRED` | `-32001` | No valid authentication provided |
+| `AUTH_INVALID` | `-32002` | Authentication expired or invalid |
+| `ACTOR_NOT_FOUND` | `-32003` | Actor ID does not exist in registry |
+| `SESSION_FULL` | `-32004` | Session has reached max content size |
+| `RATE_LIMITED` | `-32005` | Too many requests from this identity |
+| `SERVER_BUSY` | `-32006` | Server at capacity, try again later |
+| `DB_ERROR` | `-32007` | Database connection or query failure |
+| `INTERNAL_ERROR` | `-32603` | Unexpected server error |
+
+---
+
+*Documentation for v3.8.0 (M9) — IN PROGRESS. Features described reflect the implemented scope.*
+
+*Generated by [AUTO-DOCS-2] — CleverAgents Documentation Bot*

docs/milestones/v3.9.0.md

@@ -0,0 +1,173 @@
+# Milestone v3.9.0 — Documentation & Feature Updates Release
+
+> **Milestone:** v3.9.0 — Documentation and feature updates following M9
+> **Status:** In Progress
+> **Goal:** Standardize documentation practices, implement feature updates from architecture decisions, and provide migration guidance for v3.8.0 consumers.
+>
+> **Key ADRs:** [ADR-047 A2A Standard Adoption](../adr/ADR-047-acp-standard-adoption.md)
+
+---
+
+## Overview
+
+v3.9.0 is the documentation and feature consolidation release that follows M9 (Server Implementation, v3.8.0). Its scope encompasses:
+
+1. **Documentation standards** — Establishing requirements for all project documentation
+2. **Feature updates** — Implementing capabilities from architecture decisions that were deferred to this release
+3. **Migration guidance** — Documenting how users and integrations should migrate from pre-v3.8.0 patterns to the new server-based architecture
+
+---
+
+## Documentation Scope & Standards
+
+### 1. Documentation Standards
+
+All documentation created or updated as part of v3.9.0 must follow these standards:
+
+#### Format Requirements
+- Markdown (.md) files with UTF-8 encoding
+- Maximum 500 lines per doc file (split into sub-sections if longer)
+- Consistent heading hierarchy (H1 for title, H2 for sections, H3 for subsections)
+- Tables using standard markdown table syntax with aligned column headers
+- Code blocks must specify language for syntax highlighting
+
+#### Cross-Reference Pattern
+ADR references use **relative paths** matching the existing pattern in the repository:
+```markdown
+> Key ADRs: [ADR-047 A2A Standard Adoption](../adr/ADR-047-acp-standard-adoption.md)
+```
+
+#### Metadata Header (Front Matter)
+Every milestone document includes a metadata block after the title:
+```markdown
+> **Milestone:** v3.9.0 — <theme>
+> **Status:** In Progress | Released | Deferred
+> **Goal:** <one-sentence goal description>
+>
+> **Key ADRs:** [ADR-NNN](../adr/ADR-NNN-<name>.md)
+```
+
+#### Style Conventions
+- All CLI commands prefixed with `cleveragents` (never abbreviated to `ca`)
+- Actor names in kebab-case: `anthropic/claude-sonnet`, `google/gemini-pro`
+- File paths use forward slashes, relative to repository root
+- URLs wrap at 80 characters or use inline link format
+
+---
+
+## Key Changes Table
+
+The following table summarizes changes introduced in v3.9.0 and their impact on existing users:
+
+| Area | Change | Impact | Breaking? |
+|------|--------|--------|-----------|
+| Server transport | New `server` submodule with HTTP endpoint | Users can now run a persistent A2A server | No |
+| Authentication | OAuth2, API key, bearer schemes added | External integrations need auth tokens | Yes (for existing direct DB users) |
+| Persistence | PostgreSQL backend with Alembic migrations | SQLite default replaced for multi-user setups | Yes (migration required) |
+| A2A server | JSON-RPC 2.0 wire format | Client libraries must adopt JSON-RPC 2.0 | Yes (protocol change) |
+| CLI commands | `server`, `namespace` subcommands added | New discoverable commands for server management | No |
+| LangGraph | RemoteGraph integration in server path | Graph execution offloaded to LangGraph Pipeline | Partial |
+| Namespace | Shared namespace with entity sync | Multi-device and multi-user coordination | Yes (if migrating from single-user) |
+
+---
+
+## Migration Notes: Upgrading from v3.8.0 Pre-M9 Builds
+
+Users who deployed pre-release M9 builds before the stable v3.8.0 release should follow these migration steps:
+
+### 1. Database Schema Changes
+
+The PostgreSQL schema in v3.8.0 stabilizes with these changes from pre-release builds:
+
+```bash
+# Run Alembic migrations to upgrade your database
+alembic upgrade head --xdatabase "postgresql://your_db_url"
+```
+
+Key migration additions:
+- `session_messages` table now has proper foreign key constraints
+- `users` table gains unique index on `(username, namespace)`
+- Actors cache table replaces in-memory caching for persistence across restarts
+
+### 2. Authentication Migration
+
+Pre-release builds used basic bearer tokens. v3.8.0 introduces structured auth:
+
+```bash
+# Migrate from bare bearer to API key authentication
+cleveragents server auth migrate --from=bearer --to=api-key \
+  --key-file /etc/cleveragents/api-keys.json
+```
+
+### 3. Namespace Configuration
+
+Single-user deployments should add namespace isolation:
+
+```bash
+# Set default namespace for existing single-user installations
+cleveragents server config set default_namespace=default
+```
+
+### 4. Client Library Updates
+
+If using the JSON-RPC client directly, update wire format to v3.8.0 spec:
+
+- All request IDs must be UUID format (string)
+- `params` object is always present even for empty parameters (`"params": {}`)
+- SSE streaming endpoint at `/rpc/stream` replaces the deprecated `/stream` path
+
+---
+
+## Progress Tracking
+
+M9 and v3.9.0 implementation progress by component:
+
+| Component | Progress | Status |
+|-----------|----------|--------|
+| A2A Protocol (JSON-RPC 2.0) | 100% | Complete — documented in this guide |
+| Agent Cards & Standard Operations | 100% | Complete |
+| stdio Transport | 100% | Complete |
+| HTTP Transport | 100% | Complete |
+| FastAPI Server Implementation | 95% | In Progress — streaming paths finalized |
+| OAuth2 Authentication | 80% | In Progress — PKCE integration pending |
+| API Key Authentication | 90% | Near Complete — rate limiting per key pending |
+| HTTP Bearer (Development) | 100% | Complete |
+| Multi-Device Namespace Support | 75% | In Progress — conflict resolution refined |
+| Entity Sync | 70% | In Progress — background sync timing tuned |
+| Auto-Sync Reconciliation | 65% | In Progress — merge strategy under review |
+| PostgreSQL Schema & Migrations | 100% | Complete — documented in this guide |
+| Alembic Migration Scripts | 90% | Near Complete — m9_004 pending |
+| PgBouncer Integration | 60% | In Progress — pool config template under QA |
+| LangGraph RemoteGraph Client | 85% | Complete — checkpoint serialization refined |
+| Actor-to-Graph Mapping | 90% | Complete — graph_id convention stabilized |
+| Docker Deployment | 90% | Near Complete — base image optimization in progress |
+| Kubernetes / Helm Charts | 75% | In Progress — readiness probes added, HPA config pending |
+| Documentation Standards | 100% | Complete — this document defines the standard |
+
+---
+
+## Contributing to v3.9.0
+
+This milestone welcomes community contributions:
+
+- **Documentation reviews** — All milestone docs are reviewed using CONTRIBUTING.md standards (10-category checklist)
+- **ADR alignment checks** — Ensure all doc references match actual ADR content in `docs/adr/`
+- **Quick start verification** — Follow each guide's quick start section and report any failures
+- **Migration testing** — Test upgrade paths from v3.7.0 through the documented migration steps
+
+---
+
+## Related Milestones
+
+| Milestone | Document | Relationship |
+|-----------|----------|-------------|
+| v3.6.0 (Advanced Concepts) | [advanced-concepts/index.md](../advanced-concepts/index.md) | Prior milestone — context strategies & LLM backends built into M9 |
+| v3.7.0 (TUI) | [tui/index.md](../tui/index.md) | Concurrent milestone — TUI will connect to M9 server via A2A protocol |
+| **v3.8.0 (Server)** | [Milestones/v3.8.0.md](./v3.8.0.md) | This release's core deliverable |
+| **v3.9.0 (Docs)** | *this page* | Documentation consolidation and migration guidance |
+
+---
+
+*Documentation for v3.9.0 — IN PROGRESS. Content reflects planned features as of 2026-05-05.*
+
+*Generated by [AUTO-DOCS-2] — CleverAgents Documentation Bot*

mkdocs.yml

@@ -48,6 +48,10 @@ nav:
     - Automation Tracking: development/automation-tracking.md
     - Custom Sandbox Strategy: development/custom_sandbox_strategy.md
     - Documentation Writer: development/docs-writer.md
+    - Milestones:
+      - Overview: milestones/index.md
+      - v3.8.0 Server Implementation: milestones/v3.8.0.md
+      - v3.9.0 Documentation & Updates: milestones/v3.9.0.md
   - Implementation Timeline: timeline.md
   - Advanced Concepts (v3.6.0):
     - Overview & Context Strategies: advanced-concepts/index.md