docs: weekly architecture docs refresh

sdk/arch/overview.mdx

@@ -194,17 +194,94 @@ For full list of implemented workspaces, see the [source code](https://github.co
 
 **Purpose:** FastAPI-based HTTP/WebSocket server for remote agent execution.
 
-**Features:**
-- REST API & WebSocket endpoints for conversations, bash, files, events, desktop, and VSCode
-- Service management with isolated per-user sessions
-- API key authentication and health checking
+**Source:** [`openhands-agent-server/`](https://github.com/OpenHands/software-agent-sdk/tree/main/openhands-agent-server)
 
-**Deployment:** Runs inside containers (via `DockerWorkspace`) or as standalone process (connected via `RemoteWorkspace`).
+**Deployment:** Runs inside containers (via `DockerWorkspace`) or as standalone process (connected via `RemoteWorkspace`). The agent server itself does not manage containers—containerization and lifecycle are handled by [workspace implementations](/sdk/arch/workspace).
 
 **Use Cases:** Multi-user web apps, SaaS products, distributed systems.
 
+#### Architecture
+
+```mermaid
+%%{init: {"theme": "default", "flowchart": {"nodeSpacing": 28, "rankSpacing": 40}} }%%
+flowchart TB
+    Client[Client / SDK] -->|HTTP/WS| API[FastAPI App]
+
+    subgraph Routers["Routers under /api"]
+        Conv[conversations]
+        Events[events]
+        Bash[bash]
+        File[file]
+        Git[git]
+        Tools[tools]
+    end
+
+    WS["WebSocket under /sockets"]
+
+    API --> Routers
+    API --> WS
+
+    subgraph Services[Services]
+        ConvSvc[ConversationService]
+        EventSvc[EventService]
+    end
+
+    Routers --> ConvSvc
+    Routers --> EventSvc
+    WS --> EventSvc
+
+    classDef primary fill:#f3e8ff,stroke:#7c3aed,stroke-width:2px
+    classDef secondary fill:#e8f3ff,stroke:#2b6cb0,stroke-width:2px
+    classDef tertiary fill:#fff4df,stroke:#b7791f,stroke-width:2px
+
+    class API primary
+    class Routers,WS secondary
+    class Services tertiary
+```
+
+#### Key Components
+
+| Component | Purpose | Source |
+|-----------|---------|--------|
+| **FastAPI App** | Main application with lifespan management | [api.py](https://github.com/OpenHands/software-agent-sdk/blob/HEAD/openhands-agent-server/openhands/agent_server/api.py) |
+| **ConversationService** | Manages conversation state and execution | [conversation_service.py](https://github.com/OpenHands/software-agent-sdk/blob/HEAD/openhands-agent-server/openhands/agent_server/conversation_service.py) |
+| **EventService** | Handles event storage and streaming | [event_service.py](https://github.com/OpenHands/software-agent-sdk/blob/HEAD/openhands-agent-server/openhands/agent_server/event_service.py) |
+| **Request/Response Models** | Pydantic models for API payloads | [models.py](https://github.com/OpenHands/software-agent-sdk/blob/HEAD/openhands-agent-server/openhands/agent_server/models.py) |
+
+#### API Endpoints
+
+**REST Endpoints (`/api`):**
+
+| Router | Endpoint | Description |
+|--------|----------|-------------|
+| **Conversations** | `POST /api/conversations` | Start new conversation |
+| | `POST /api/conversations/{id}/run` | Run agent loop |
+| | `POST /api/conversations/{id}/events` | Send message (optionally with `run: true`) |
+| **Events** | `GET /api/conversations/{id}/events/search` | List events |
+| | `GET /api/conversations/{id}/events/{event_id}` | Get specific event |
+| **Bash** | `POST /api/bash/start_bash_command` | Start background command |
+| | `GET /api/bash/bash_events/search` | List bash events |
+| **Files** | `POST /api/file/upload/{path}` | Upload file |
+| | `GET /api/file/download/{path}` | Download file |
+| **Tools** | `GET /api/tools/` | List registered tools |
+| **Server** | `GET /server_info` | Get uptime and idle time |
+
+**WebSocket Endpoints (`/sockets`):**
+
+| Endpoint | Description |
+|----------|-------------|
+| `/sockets/events/{conversation_id}` | Stream conversation events |
+| `/sockets/bash-events` | Stream bash command events |
+
+#### Authentication
+
+| Method | Authentication | Source |
+|--------|---------------|--------|
+| **HTTP** | `X-Session-API-Key` header | [dependencies.py](https://github.com/OpenHands/software-agent-sdk/blob/HEAD/openhands-agent-server/openhands/agent_server/dependencies.py) |
+| **WebSocket** | `session_api_key` query parameter | [sockets.py](https://github.com/OpenHands/software-agent-sdk/blob/HEAD/openhands-agent-server/openhands/agent_server/sockets.py) |
+
 <Note>
-For implementation details, see the [source code](https://github.com/OpenHands/software-agent-sdk/tree/main/openhands-agent-server).
+For practical usage guides on deploying and connecting to agent servers, see the [Remote Agent Server Guide](/sdk/guides/agent-server/overview).
 </Note>
 
 ## How Components Work Together

sdk/arch/sdk.mdx

@@ -455,7 +455,7 @@ Everything uses Pydantic models:
 
 - [Tool System](/sdk/arch/tool-system) - Built-in tool implementations
 - [Workspace Architecture](/sdk/arch/workspace) - Execution environments
-- [Agent Server Architecture](/sdk/arch/agent-server) - Remote execution
+- [Agent Server Architecture](/sdk/arch/overview#agent-server-package-openhandsagent_server) - Remote execution
 
 ### For Implementation Details
 

sdk/arch/security.mdx

@@ -5,7 +5,7 @@ description: High-level architecture of action security analysis and validation
 
 The **Security** system evaluates agent actions for potential risks before execution. It provides pluggable security analyzers that assess action risk levels and enforce confirmation policies based on security characteristics.
 
-**Source:** [`openhands-sdk/penhands/sdk/security/`](https://github.com/OpenHands/software-agent-sdk/tree/main/openhands-sdk/openhands/sdk/security)
+**Source:** [`openhands-sdk/openhands/sdk/security/`](https://github.com/OpenHands/software-agent-sdk/tree/main/openhands-sdk/openhands/sdk/security)
 
 ## Core Responsibilities
 
@@ -58,7 +58,7 @@ flowchart TB
 
     Check --> Mode
     Mode --> Decision
-    
+
     classDef primary fill:#f3e8ff,stroke:#7c3aed,stroke-width:2px
     classDef secondary fill:#e8f3ff,stroke:#2b6cb0,stroke-width:2px
     classDef tertiary fill:#fff4df,stroke:#b7791f,stroke-width:2px
@@ -102,7 +102,8 @@ flowchart TB
     Analyze --> Medium
     Analyze --> High
     Analyze --> Unknown
-
+
+
     style Low fill:#d1fae5,stroke:#10b981,stroke-width:2px
     style Medium fill:#fef3c7,stroke:#f59e0b,stroke-width:2px
     style High fill:#ffe8e8,stroke:#dc2626,stroke-width:2px
@@ -308,3 +309,8 @@ flowchart LR
 - **[Agent Architecture](/sdk/arch/agent)** - How agents use security analyzers
 - **[Tool System](/sdk/arch/tool-system)** - Tool annotations and metadata; includes MCP tool hints
 - **[Security Guide](/sdk/guides/security)** - Configuring security policies
+
+---
+Last updated: 2025-12-09 06:57 UTC  
+Source commit (software-agent-sdk): `93d405c9`
+

sdk/arch/workspace.mdx

@@ -203,5 +203,5 @@ flowchart LR
 ## See Also
 
 - **[Conversation Architecture](/sdk/arch/conversation)** - How workspace type determines conversation implementation
-- **[Agent Server](/sdk/arch/agent-server)** - Remote execution API
+- **[Agent Server](/sdk/arch/overview#agent-server-package-openhandsagent_server)** - Remote execution API
 - **[Tool System](/sdk/arch/tool-system)** - Tools that use workspace for execution

sdk/guides/agent-server/api-sandbox.mdx

@@ -194,7 +194,7 @@ All agent execution happens on the remote runtime infrastructure.
 
 ## Next Steps
 
-- **[Docker Sandboxed Server](/sdk/guides/agent-server/docker-sandbox)**
-- **[Local Agent Server](/sdk/guides/agent-server/local-server)**
-- **[Agent Server Overview](/sdk/guides/agent-server/overview)** - Architecture and implementation details
-- **[Agent Server Package Architecture](/sdk/arch/agent-server)** - Remote execution architecture
+- **[Docker Sandbox](/sdk/guides/agent-server/docker-sandbox)** - Run with DockerWorkspace
+- **[Local Agent Server](/sdk/guides/agent-server/local-server)** - Development without containers
+- **[Remote Agent Server Overview](/sdk/guides/agent-server/overview)** - Workspace types and deployment options
+- **[Agent Server Architecture](/sdk/arch/overview#agent-server-package-openhandsagent_server)** - Technical details, endpoints, authentication

sdk/guides/agent-server/cloud-workspace.mdx

@@ -205,7 +205,8 @@ This verifies connectivity to the cloud sandbox and ensures the environment is r
 
 ## Next Steps
 
-- **[API-based Sandbox](/sdk/guides/agent-server/api-sandbox)** - Connect to Runtime API service
-- **[Docker Sandboxed Server](/sdk/guides/agent-server/docker-sandbox)** - Run locally with Docker
+- **[API Sandbox](/sdk/guides/agent-server/api-sandbox)** - Runtime API integration
+- **[Docker Sandbox](/sdk/guides/agent-server/docker-sandbox)** - Isolated Docker containers
 - **[Local Agent Server](/sdk/guides/agent-server/local-server)** - Development without containers
-- **[Agent Server Overview](/sdk/guides/agent-server/overview)** - Architecture and implementation details
+- **[Remote Agent Server Overview](/sdk/guides/agent-server/overview)** - Workspace types and deployment options
+- **[Agent Server Architecture](/sdk/arch/overview#agent-server-package-openhandsagent_server)** - Technical details, endpoints, authentication

sdk/guides/agent-server/docker-sandbox.mdx

@@ -602,7 +602,8 @@ http://localhost:8012/vnc.html?autoconnect=1&resize=remote
 
 ## Next Steps
 
-- **[Local Agent Server](/sdk/guides/agent-server/local-server)**
-- **[Agent Server Overview](/sdk/guides/agent-server/overview)** - Architecture and implementation details
-- **[API Sandboxed Server](/sdk/guides/agent-server/api-sandbox)** - Connect to hosted API service
-- **[Agent Server Package Architecture](/sdk/arch/agent-server)** - Remote execution architecture
+- **[Local Agent Server](/sdk/guides/agent-server/local-server)** - Development without containers
+- **[API Sandbox](/sdk/guides/agent-server/api-sandbox)** - Runtime API integration
+- **[Cloud Workspace](/sdk/guides/agent-server/cloud-workspace)** - OpenHands Cloud managed sandboxes
+- **[Remote Agent Server Overview](/sdk/guides/agent-server/overview)** - Workspace types and deployment options
+- **[Agent Server Architecture](/sdk/arch/overview#agent-server-package-openhandsagent_server)** - Technical details, endpoints, authentication

sdk/guides/agent-server/local-server.mdx

@@ -359,7 +359,8 @@ This allows you to inspect the conversation history, analyze agent behavior, and
 
 ## Next Steps
 
-- **[Docker Sandboxed Server](/sdk/guides/agent-server/docker-sandbox)** - Run server in Docker for isolation
-- **[API Sandboxed Server](/sdk/guides/agent-server/api-sandbox)** - Connect to hosted API service
-- **[Agent Server Overview](/sdk/guides/agent-server/overview)** - Architecture and implementation details
-- **[Agent Server Package Architecture](/sdk/arch/agent-server)** - Remote execution architecture
+- **[Docker Sandbox](/sdk/guides/agent-server/docker-sandbox)** - Isolated Docker containers
+- **[API Sandbox](/sdk/guides/agent-server/api-sandbox)** - Runtime API integration
+- **[Cloud Workspace](/sdk/guides/agent-server/cloud-workspace)** - OpenHands Cloud managed sandboxes
+- **[Remote Agent Server Overview](/sdk/guides/agent-server/overview)** - Workspace types and deployment options
+- **[Agent Server Architecture](/sdk/arch/overview#agent-server-package-openhandsagent_server)** - Technical details, endpoints, authentication