Add 0.9.0 documentation: roadmap, README updates, CHANGELOG

- Create plans/DOCS-ROADMAP.md with Forge-format 3-stage docs roadmap
- Update README: add Mintlify docs link, version 0.9.0-SNAPSHOT → 0.9.0,
  remove snapshots repository, add annotation-based agent example first,
  add tutorial links, add Maven artifacts table
- Update CHANGELOG: [Unreleased] → [0.9.0], expand with full feature list
  organized by subsystem (core, agent, annotations, capabilities, etc.)
- Update acp-agent-support/README.md: remove "Spring MVC-style" phrasing

Author: mark-tuvium

CHANGELOG.md

@@ -5,19 +5,72 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [0.9.0] - 2026-02-XX
 
 ### Added
-- Initial release of ACP Java SDK
+
+#### Core SDK
 - Pure Java implementation of Agent Client Protocol (ACP) specification
-- `AcpSchema` - Complete protocol type definitions (1071 lines)
-- `AcpClientSession` - Low-level client session implementation
-- `AcpAsyncClient` - Reactive async client with Project Reactor
-- `AcpSyncClient` - Synchronous wrapper client
-- `StdioAcpClientTransport` - STDIO transport implementation
-- `AgentParameters` - Process configuration builder
-- Integration tests with Gemini CLI
+- `AcpSchema` — complete protocol type definitions (sealed interfaces and records)
+- `AcpSyncClient` — synchronous blocking client
+- `AcpAsyncClient` — reactive async client with Project Reactor
+- `AcpClientSession` — low-level client session implementation
+- `StdioAcpClientTransport` — stdio transport for launching agents as subprocesses
+- `WebSocketAcpClientTransport` — JDK-native WebSocket client transport (no extra dependencies)
+- `AgentParameters` — process configuration builder for agent launch
+
+#### Agent SDK
+- `AcpSyncAgent` — synchronous agent with blocking handlers
+- `AcpAsyncAgent` — reactive agent with `Mono`-returning handlers
+- `StdioAcpAgentTransport` — stdio transport for agents
+- `SyncPromptContext` — convenience API for sending messages, reading files, requesting permissions
+- All handler types: initialize, newSession, loadSession, prompt, setSessionMode, setSessionModel, cancel
+
+#### Annotation-Based Agent API
+- `@AcpAgent` — class-level agent annotation with name/version
+- `@Initialize`, `@NewSession`, `@LoadSession`, `@Prompt`, `@Cancel` — handler annotations
+- `@SetSessionMode`, `@SetSessionModel` — session configuration annotations
+- `@SessionId`, `@SessionState` — parameter annotations
+- `AcpAgentSupport` — bootstrap and builder for annotation-based agents
+- Flexible method signatures with automatic parameter resolution
+- Auto-conversion of return values (`String` → `PromptResponse`, `void` → `endTurn()`)
+- Interceptor support for cross-cutting concerns
+- Custom argument resolvers and return value handlers
+
+#### Capabilities
+- `NegotiatedCapabilities` — capability negotiation between client and agent
+- Client capabilities: file read/write, terminal execution, permission requests
+- Agent capabilities: load session, image content, slash commands
+- `require*()` methods that throw `AcpCapabilityException` if unsupported
+
+#### Error Handling
+- `AcpProtocolException` — structured JSON-RPC errors with codes
+- `AcpCapabilityException` — capability not supported
+- `AcpConnectionException` — transport-level failures
+- Standard error codes via `AcpErrorCodes`
+
+#### Transports
+- Stdio transport (client and agent)
+- WebSocket client transport (JDK-native)
+- WebSocket agent transport (Jetty-based, `acp-websocket-jetty` module)
+- In-memory transport pair for testing (`acp-test` module)
+
+#### Testing
+- `InMemoryTransportPair` — bidirectional in-memory transport for unit tests
+- `MockAcpClient` — mock client builder with file content fixtures
+- Fast, deterministic testing without subprocess I/O
+
+#### Protocol Compliance
+- Full SessionUpdate types: AgentMessageChunk, AgentThoughtChunk, ToolCall, ToolCallUpdateNotification, Plan, AvailableCommandsUpdate, CurrentModeUpdate
+- MCP server configuration in session requests
+- `_meta` extensibility on all protocol messages
+- All StopReason values: END_TURN, MAX_TOKENS, REFUSAL, CANCELLED
+
+#### Infrastructure
 - Maven Central Portal publishing configuration
+- CI workflow with GitHub Actions
+- 258 unit tests
+- Integration tests with Gemini CLI
 
 ### Dependencies
 - Java 17 (LTS)
@@ -26,9 +79,4 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - MCP JSON utilities 0.15.0-SNAPSHOT
 - SLF4J 2.0.16
 
-## [0.1.0] - TBD
-
-Initial release.
-
-[Unreleased]: https://github.com/acp-java/acp-java-sdk/compare/v0.1.0...HEAD
-[0.1.0]: https://github.com/acp-java/acp-java-sdk/releases/tag/v0.1.0
+[0.9.0]: https://github.com/agentclientprotocol/java-sdk/releases/tag/v0.9.0

README.md

@@ -1,24 +1,32 @@
 # ACP Java SDK
 
+> **Documentation**: https://springaicommunity.mintlify.app/acp-java-sdk
+
 Pure Java implementation of the [Agent Client Protocol (ACP)](https://agentclientprotocol.com/) specification for building both clients and agents.
 
 ## Overview
 
-The Agent Client Protocol (ACP) standardizes communication between code editors and coding agents. This SDK enables Java applications to:
+The Agent Client Protocol (ACP) standardizes communication between code editors and coding agents. This SDK provides two modules:
+
+- **Client** — connect to and interact with ACP-compliant agents
+- **Agent** — build ACP-compliant agents in Java
+
+Three API styles for building agents:
 
-- **Connect to** ACP-compliant agents (Client SDK)
-- **Build** ACP-compliant agents in Java (Agent SDK)
+| Style | Best for | Example |
+|-------|----------|---------|
+| [**Annotation-based**](#2-hello-world-agent-annotation-based) | Least boilerplate — `@AcpAgent`, `@Prompt` annotations | [Jump to example](#2-hello-world-agent-annotation-based) |
+| [**Sync**](#3-hello-world-agent-sync) | Simple blocking handlers with plain return values | [Jump to example](#3-hello-world-agent-sync) |
+| [**Async**](#4-hello-world-agent-async) | Reactive applications using Project Reactor `Mono` | [Jump to example](#4-hello-world-agent-async) |
 
 **Key Features:**
-- Java 17+, reactive (Project Reactor), type-safe
-- Async and sync APIs
-- Stdio and WebSocket transports
+- Java 17+, type-safe, stdio and WebSocket transports
 - Capability negotiation and structured error handling
-- **[Annotation-based agents](acp-agent-support/README.md)** - Spring MVC-style `@AcpAgent`, `@Prompt` annotations
+- For a hands-on walkthrough, see the **[ACP Java Tutorial](https://github.com/markpollack/acp-java-tutorial)**
 
 ## Installation
 
-> **Note:** Not yet published to Maven Central. For now, build and install locally using `./mvnw install`.
+Published to Maven Central:
 
 ```xml
 <dependency>
@@ -52,7 +60,7 @@ For WebSocket server support (agents accepting WebSocket connections):
 
 ### 1. Hello World Client
 
-Connect to an ACP agent and send a prompt:
+Connect to an ACP agent and send a prompt ([tutorial](https://github.com/markpollack/acp-java-tutorial/tree/main/module-01-first-contact)):
 
 ```java
 import com.agentclientprotocol.sdk.client.*;
@@ -78,9 +86,45 @@ var response = client.prompt(new PromptRequest(
 client.close();
 ```
 
-### 2. Hello World Agent (Sync)
+### 2. Hello World Agent (Annotation-Based)
+
+The simplest way to build an agent — use annotations ([tutorial](https://github.com/markpollack/acp-java-tutorial/tree/main/module-12-echo-agent)):
+
+```java
+import com.agentclientprotocol.sdk.annotation.*;
+import com.agentclientprotocol.sdk.agent.SyncPromptContext;
+import com.agentclientprotocol.sdk.agent.support.AcpAgentSupport;
+import com.agentclientprotocol.sdk.spec.AcpSchema.*;
+
+@AcpAgent
+class HelloAgent {
+
+    @Initialize
+    InitializeResponse init() {
+        return InitializeResponse.ok();
+    }
+
+    @NewSession
+    NewSessionResponse newSession() {
+        return new NewSessionResponse(UUID.randomUUID().toString(), null, null);
+    }
+
+    @Prompt
+    PromptResponse prompt(PromptRequest req, SyncPromptContext ctx) {
+        ctx.sendMessage("Hello from the agent!");
+        return PromptResponse.endTurn();
+    }
+}
+
+// Bootstrap and run
+AcpAgentSupport.create(new HelloAgent())
+    .transport(new StdioAcpAgentTransport())
+    .run();
+```
+
+### 3. Hello World Agent (Sync)
 
-Create a minimal ACP agent using the sync API (recommended for simplicity):
+The builder API with blocking handlers and plain return values ([tutorial](https://github.com/markpollack/acp-java-tutorial/tree/main/module-13-agent-handlers)):
 
 ```java
 import com.agentclientprotocol.sdk.agent.*;
@@ -112,9 +156,9 @@ AcpSyncAgent agent = AcpAgent.sync(transport)
 agent.run();
 ```
 
-### 2b. Hello World Agent (Async)
+### 4. Hello World Agent (Async)
 
-For reactive applications, use the async API:
+For reactive applications, use the async API with Project Reactor ([tutorial](https://github.com/markpollack/acp-java-tutorial/tree/main/module-22-async-agent)):
 
 ```java
 import com.agentclientprotocol.sdk.agent.*;
@@ -142,56 +186,28 @@ AcpAsyncAgent agent = AcpAgent.async(transport)
 agent.start().then(agent.awaitTermination()).block();
 ```
 
-### 2c. Hello World Agent (Annotation-Based)
-
-For the simplest agent development experience, use annotations (see [full documentation](acp-agent-support/README.md)):
-
-```java
-import com.agentclientprotocol.sdk.annotation.*;
-import com.agentclientprotocol.sdk.agent.SyncPromptContext;
-import com.agentclientprotocol.sdk.agent.support.AcpAgentSupport;
-import com.agentclientprotocol.sdk.spec.AcpSchema.*;
+---
 
-@AcpAgent
-class HelloAgent {
+## Progressive Examples
 
-    @Initialize
-    InitializeResponse init() {
-        return InitializeResponse.ok();
-    }
+### 5. Streaming Updates
 
-    @NewSession
-    NewSessionResponse newSession() {
-        return new NewSessionResponse(UUID.randomUUID().toString(), null, null);
-    }
+Send real-time updates to the client during prompt processing (tutorial: [client-side](https://github.com/markpollack/acp-java-tutorial/tree/main/module-05-streaming-updates), [agent-side](https://github.com/markpollack/acp-java-tutorial/tree/main/module-14-sending-updates)).
 
-    @Prompt
-    PromptResponse prompt(PromptRequest req, SyncPromptContext ctx) {
-        ctx.sendMessage("Hello from the agent!");
-        return PromptResponse.endTurn();
-    }
+**Annotation-based:**
+```java
+@Prompt
+PromptResponse prompt(PromptRequest req, SyncPromptContext ctx) {
+    ctx.sendUpdate(req.sessionId(),
+        new AgentThoughtChunk("agent_thought_chunk", new TextContent("Thinking...")));
+    ctx.sendMessage("Here's my response.");
+    return PromptResponse.endTurn();
 }
-
-// Bootstrap and run
-AcpAgentSupport.create(new HelloAgent())
-    .transport(new StdioAcpAgentTransport())
-    .run();
 ```
 
-This approach reduces boilerplate by ~50% compared to the builder API while producing identical runtime behavior.
-
----
-
-## Progressive Examples
-
-### 3. Streaming Updates
-
-Send real-time updates to the client during prompt processing.
-
-**Agent (Sync) - recommended:**
+**Sync:**
 ```java
 .promptHandler((req, context) -> {
-    // Blocking void calls - simple and straightforward
     context.sendUpdate(req.sessionId(),
         new AgentThoughtChunk("agent_thought_chunk",
             new TextContent("Thinking...")));
@@ -202,7 +218,7 @@ Send real-time updates to the client during prompt processing.
 })
 ```
 
-**Agent (Async):**
+**Async:**
 ```java
 .promptHandler((request, context) -> {
     return context.sendUpdate(request.sessionId(),
@@ -227,9 +243,9 @@ AcpSyncClient client = AcpClient.sync(transport)
     .build();
 ```
 
-### 4. Agent-to-Client Requests
+### 6. Agent-to-Client Requests
 
-Agents can request file operations from the client. The `context` parameter provides access to all agent capabilities.
+Agents can request file operations from the client ([tutorial](https://github.com/markpollack/acp-java-tutorial/tree/main/module-15-agent-requests)). The `context` parameter provides access to all agent capabilities.
 
 **Agent (Sync) - reading files:**
 ```java
@@ -266,9 +282,9 @@ AcpSyncClient client = AcpClient.sync(transport)
     .build();
 ```
 
-### 5. Capability Negotiation
+### 7. Capability Negotiation
 
-Check what features the peer supports before using them:
+Check what features the peer supports before using them ([tutorial](https://github.com/markpollack/acp-java-tutorial/tree/main/module-17-capability-negotiation)):
 
 ```java
 // Client: check agent capabilities after initialize
@@ -297,9 +313,9 @@ clientCaps.requireWriteTextFile();
 agent.writeTextFile(...);
 ```
 
-### 6. Error Handling
+### 8. Error Handling
 
-Handle protocol errors with structured exceptions:
+Handle protocol errors with structured exceptions ([tutorial](https://github.com/markpollack/acp-java-tutorial/tree/main/module-11-error-handling)):
 
 ```java
 import com.agentclientprotocol.sdk.error.*;
@@ -321,7 +337,7 @@ try {
 }
 ```
 
-### 7. WebSocket Transport
+### 9. WebSocket Transport
 
 Use WebSocket instead of stdio for network-based communication:
 
@@ -369,6 +385,16 @@ agent.start().block();  // Starts WebSocket server on port 8080
 | `com.agentclientprotocol.sdk.capabilities` | Capability negotiation (`NegotiatedCapabilities`) |
 | `com.agentclientprotocol.sdk.error` | Exceptions (`AcpProtocolException`, `AcpCapabilityException`) |
 
+### Maven Artifacts
+
+| Artifact | Description |
+|----------|-------------|
+| [`acp-core`](https://central.sonatype.com/artifact/com.agentclientprotocol/acp-core) | Client and Agent SDKs, stdio and WebSocket client transports |
+| [`acp-annotations`](https://central.sonatype.com/artifact/com.agentclientprotocol/acp-annotations) | `@AcpAgent`, `@Prompt`, and other annotations |
+| [`acp-agent-support`](https://central.sonatype.com/artifact/com.agentclientprotocol/acp-agent-support) | Annotation-based agent runtime |
+| [`acp-test`](https://central.sonatype.com/artifact/com.agentclientprotocol/acp-test) | In-memory transport and mock utilities for testing |
+| [`acp-websocket-jetty`](https://central.sonatype.com/artifact/com.agentclientprotocol/acp-websocket-jetty) | Jetty-based WebSocket server transport for agents |
+
 ### Transports
 
 | Transport | Client | Agent | Module |
@@ -422,6 +448,10 @@ MockAcpClient mockClient = MockAcpClient.builder(pair.clientTransport())
 
 ---
 
+## Tutorial
+
+For a hands-on, progressive introduction to the SDK, see the **[ACP Java Tutorial](https://github.com/markpollack/acp-java-tutorial)** -- 30 modules covering client basics, agent development, streaming, testing, and IDE integration.
+
 ## Roadmap
 
 ### v0.9.0 (Current)
@@ -430,9 +460,10 @@ MockAcpClient mockClient = MockAcpClient.builder(pair.clientTransport())
 - Capability negotiation
 - Structured error handling
 - Full protocol compliance (all SessionUpdate types, MCP configs, `_meta` extensibility)
+- Snapshot builds published to Maven Central
 - 258 tests
 
 ### v1.0.0 (Planned)
-- Maven Central publishing
+- Stable release to Maven Central
 - Production hardening
 - Performance optimizations

acp-agent-support/README.md

@@ -1,6 +1,6 @@
 # ACP Agent Support Module
 
-The `acp-agent-support` module provides a Spring MVC-style annotation-based programming model for building ACP agents. It eliminates boilerplate code while maintaining full compatibility with the builder-based API from `acp-core`.
+The `acp-agent-support` module provides an annotation-based programming model for building ACP agents. It eliminates boilerplate code while maintaining full compatibility with the builder-based API from `acp-core`.
 
 ## Quick Start