🥇 export from upstream (a1fa8e3a)

README.md

@@ -31,8 +31,25 @@ These tools are developed in this monorepo but distributed as independent reposi
 **Layers top-to-bottom:**
 - **Consumers** *(shadow)* — server assembly, web app, integrations — not in this repo
 - **Standalone Tools** — installable from their own repositories; depend on these crates
-- **Orchestration** — connector runtime, ACP server, introspection
-- **Foundation** — protocol types, tool sandbox, configuration, auth, process management
+- **Orchestration** — connector runtime, ACP server
+- **Foundation** — protocol types, tool sandbox, configuration, auth
+
+---
+
+## Core Runtime
+
+`dirigent_core` is the central crate. It manages long-lived connections to external agent systems through a **Connector** abstraction — each connector wraps a bidirectional communication channel to an agent (Claude Code over stdio, OpenCode.ai over HTTP+SSE, or an incoming ACP connection).
+
+<p align="center">
+  <img src="core-architecture.svg" alt="dirigent_core internal architecture" width="720">
+</p>
+
+**Key concepts:**
+
+- **CoreRuntime** is a stateless orchestrator. It owns the connector registry, the event bus, and lifecycle hooks — but never caches session state. The external agent is always authoritative.
+- **Connectors** implement a common trait (`command_tx()` to send commands, `subscribe()` to receive events) and run as independent background tasks. Four implementations ship today: ACP (stdio/HTTP JSON-RPC), Gateway (local echo + session transfer), OpenCode (REST+SSE), and AcpAcceptor (incoming connections).
+- **SharingBus** is the event backbone. Every connector event is published once and fan-out to filtered subscribers — archivist, web UI, stream integrations — without the bus knowing about any of them.
+- **Lifecycle Hooks** let the server assembly inject services (inspector, process manager, archivist) at connector creation time. Core defines abstract traits (`ConnectorInspector`, `ProcessGroupManager`) and never depends on their implementations directly.
 
 ---
 
@@ -43,10 +60,8 @@ These tools are developed in this monorepo but distributed as independent reposi
 | `dirigent_core` | beta | Multi-connector orchestration runtime |
 | `dirigent_protocol` | beta | ACP protocol types — messages, events, and RPC definitions |
 | `dirigent_acp_api` | beta | ACP server for incoming agent connections |
-| `dirigent_inspector` | concept | Runtime introspection tree |
 | `dirigent_config` | beta | Configuration management |
 | `dirigent_auth` | concept | User authorization model |
-| `dirigent_process` | beta | Child process management |
 | `dirigent_tools` | concept | Tool sandbox and execution abstractions |
 | `opencode_client` | beta | OpenCode.ai HTTP client |