feat(core): add roots list support and improve documentation

- Add roots list capability to allow servers to understand filesystem boundaries
- Move architecture diagram and add detailed documentation for transports and sessions
- Enhance client capabilities with roots and sampling features
- Rename withRequestTimeout to requestTimeout for better API consistency
- Add tests for roots list functionality

Resolves #8

docs/CLIENT.STDIO.TRANSPORT.md

@@ -0,0 +1,123 @@
+# StdioClientTransport
+
+The `StdioClientTransport` class implements the [MCP Stdio Transport](https://spec.modelcontextprotocol.io/specification/basic/transports/#stdio) specification, providing communication with MCP servers over standard input/output streams.
+
+## Overview
+
+The Stdio transport uses standard input/output streams for bidirectional communication between the client and server:
+- Messages are sent to the server via stdout
+- Messages are received from the server via stdin
+- Error and debug information is sent via stderr
+
+## Message Format
+
+Messages are exchanged as newline-delimited JSON-RPC messages:
+- Each message is a single line of JSON text
+- Messages are terminated with a newline character (`\n`)
+- Messages follow the JSON-RPC 2.0 specification
+- UTF-8 encoding is used for all messages
+
+### Message Types
+
+The transport handles three types of JSON-RPC messages:
+
+1. **Requests** - Messages with both `method` and `id` fields:
+```json
+{
+    "jsonrpc": "2.0",
+    "id": 1,
+    "method": "example.method",
+    "params": {}
+}
+```
+
+2. **Notifications** - Messages with `method` but no `id` field:
+```json
+{
+    "jsonrpc": "2.0",
+    "method": "example.notification",
+    "params": {}
+}
+```
+
+3. **Responses** - Messages with either `result` or `error` fields:
+```json
+{
+    "jsonrpc": "2.0",
+    "id": 1,
+    "result": {}
+}
+```
+
+## Implementation Details
+
+### Process Management
+
+The transport manages a server process with:
+- Command and arguments specified via `ServerParameters`
+- Environment variables for configuration
+- Proper process cleanup on shutdown
+
+### Threading Model
+
+The implementation uses three dedicated threads:
+1. **Inbound** - Reads and processes messages from stdin
+2. **Outbound** - Writes messages to stdout
+3. **Error** - Handles stderr messages
+
+### Error Handling
+
+Errors are handled at multiple levels:
+- Process startup failures
+- Stream I/O errors
+- Message parsing errors
+- Process termination handling
+
+## Usage Example
+
+```java
+// Create server parameters
+ServerParameters params = ServerParameters.builder()
+    .command("path/to/server")
+    .args(List.of("--arg1", "value1"))
+    .env(Map.of("ENV_VAR", "value"))
+    .build();
+
+// Create transport
+StdioClientTransport transport = new StdioClientTransport(params);
+
+// Start transport
+transport.start();
+
+// Send message
+JSONRPCRequest request = new JSONRPCRequest();
+request.setId(1);
+request.setMethod("example.method");
+request.setParams(new HashMap<>());
+transport.send(request);
+
+// Close transport
+transport.closeGracefully().block();
+```
+
+## Error Messages
+
+Error messages from the server process are:
+- Written to stderr
+- Logged at ERROR level
+- Emitted through the error sink for handling
+- UTF-8 encoded
+
+## Debugging
+
+For debugging purposes:
+1. Enable DEBUG level logging to see detailed message flow
+2. Monitor stderr for server process errors
+3. Check process exit codes for abnormal termination
+
+## Implementation Notes
+
+- The transport ensures thread safety through dedicated schedulers
+- Messages are processed asynchronously using Project Reactor
+- Resources are properly cleaned up on shutdown
+- The implementation is resilient to various failure modes