docs: Update readme (#127)

Author: benbrandt

README.md

@@ -8,6 +8,33 @@ The Agent Client Protocol (ACP) standardizes communication between _code editors
 
 Learn more at [agentclientprotocol.com](https://agentclientprotocol.com/).
 
+This repository is the official **Rust SDK** for ACP. It provides crates for building clients, agents, and proxies, plus a conductor that orchestrates chains of proxies between an editor and an agent so that behavior can be extended without modifying the agent itself.
+
+## Crates
+
+**Core SDK**
+
+- [`agent-client-protocol`](./src/agent-client-protocol/) – Roles (Client, Agent, Proxy, Conductor), connection builders, handlers, and protocol types.
+- [`agent-client-protocol-tokio`](./src/agent-client-protocol-tokio/) – Tokio utilities for spawning agent processes and wiring stdio transports.
+- [`agent-client-protocol-rmcp`](./src/agent-client-protocol-rmcp/) – Integration with the [`rmcp`](https://docs.rs/rmcp) MCP SDK.
+- [`agent-client-protocol-derive`](./src/agent-client-protocol-derive/) – Derive macros used by the core crate.
+
+**Proxy orchestration**
+
+- [`agent-client-protocol-conductor`](./src/agent-client-protocol-conductor/) – Binary and library that manages chains of proxy components.
+- [`agent-client-protocol-trace-viewer`](./src/agent-client-protocol-trace-viewer/) – Interactive sequence-diagram viewer for conductor trace files.
+
+**Patterns, examples, and testing**
+
+- [`agent-client-protocol-cookbook`](./src/agent-client-protocol-cookbook/) – Practical patterns for clients, agents, and proxies, rendered as rustdoc.
+- [`agent-client-protocol-test`](./src/agent-client-protocol-test/) – Shared test utilities and fixtures.
+- [`yopo`](./src/yopo/) – "You Only Prompt Once", an example client.
+
+## Documentation
+
+- **API reference** for individual crates is on [docs.rs/agent-client-protocol](https://docs.rs/agent-client-protocol).
+- **Design and architecture documentation** lives in the mdbook at [agentclientprotocol.github.io/rust-sdk](https://agentclientprotocol.github.io/rust-sdk/). Source is in [`md/`](./md/).
+
 ## Integrations
 
 - [Schema](./schema/schema.json)