feat: enhance documentation with detailed file attachment parameters and session shutdown methods

Author: brunoborges

src/site/markdown/advanced.md

@@ -110,7 +110,13 @@ var session = client.createSession(
 
 ## File Attachments
 
-Include files as context for the AI to analyze.
+Include files as context for the AI to analyze. The `Attachment` record takes three parameters:
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `type` | String | The attachment type — use `"file"` for filesystem files |
+| `path` | String | The absolute path to the file on disk |
+| `displayName` | String | A human-readable label shown to the AI (e.g., the filename or a description) |
 
 ```java
 session.send(new MessageOptions()
@@ -121,6 +127,18 @@ session.send(new MessageOptions()
 ).get();
 ```
 
+You can attach multiple files in a single message:
+
+```java
+session.send(new MessageOptions()
+    .setPrompt("Compare these two implementations")
+    .setAttachments(List.of(
+        new Attachment("file", "/src/main/OldImpl.java", "Old Implementation"),
+        new Attachment("file", "/src/main/NewImpl.java", "New Implementation")
+    ))
+).get();
+```
+
 ---
 
 ## Bring Your Own Key (BYOK)
@@ -454,6 +472,31 @@ client.start().get();   // Start manually
 client.stop().get();    // Stop manually
 ```
 
+### Graceful Stop vs Force Stop
+
+The SDK provides two shutdown methods:
+
+| Method | Behavior |
+|--------|----------|
+| `stop()` | Gracefully closes all open sessions, then shuts down the connection |
+| `forceStop()` | Immediately clears sessions and shuts down — no graceful session cleanup |
+
+Use `stop()` for normal shutdown — it ensures each session is properly closed (flushing pending operations) before terminating the connection:
+
+```java
+// Graceful: closes all sessions, then disconnects
+client.stop().get();
+```
+
+Use `forceStop()` when you need to terminate immediately, such as during error recovery or when the server is unresponsive:
+
+```java
+// Immediate: skips session cleanup, kills connection
+client.forceStop().get();
+```
+
+> **Tip:** In `try-with-resources` blocks, `close()` delegates to `stop()`, so graceful cleanup happens automatically.
+
 ---
 
 ## Session Lifecycle Events

src/site/markdown/documentation.md

@@ -425,6 +425,33 @@ The four states are:
 | `CONNECTED` | Client is connected and ready |
 | `ERROR` | Connection failed (check logs for details) |
 
+### State Transitions
+
+```
+                 start()
+  DISCONNECTED ──────────► CONNECTING
+                               │
+                    ┌──────────┼──────────┐
+                    │ success  │          │ failure
+                    ▼          │          ▼
+              CONNECTED        │        ERROR
+                    │          │
+        stop() /    │          │
+        forceStop() │          │
+                    ▼          │
+              DISCONNECTED ◄───┘
+                    │
+                    │ start()  (retry)
+                    ▼
+               CONNECTING
+```
+
+- **DISCONNECTED → CONNECTING:** `start()` was called
+- **CONNECTING → CONNECTED:** Server connection and protocol handshake succeeded
+- **CONNECTING → ERROR:** Connection or protocol verification failed
+- **CONNECTED → DISCONNECTED:** `stop()` or `forceStop()` was called, or `close()` via try-with-resources
+- **DISCONNECTED → CONNECTING:** `start()` can be called again to retry
+
 ### Server Status
 
 Get CLI version and protocol information:

src/site/markdown/setup.md

@@ -350,6 +350,39 @@ Complete list of `CopilotClientOptions` settings:
 | `environment` | Map | Environment variables | inherited |
 | `cwd` | String | Working directory | current dir |
 
+### Extra CLI Arguments
+
+Pass additional command-line arguments to the CLI process:
+
+```java
+var options = new CopilotClientOptions()
+    .setCliArgs(new String[]{"--verbose", "--no-telemetry"});
+
+try (var client = new CopilotClient(options)) {
+    client.start().get();
+    // CLI process receives the extra flags
+}
+```
+
+### Custom Environment Variables
+
+Set environment variables for the CLI process (merged with the inherited system environment):
+
+```java
+var options = new CopilotClientOptions()
+    .setEnvironment(Map.of(
+        "HTTPS_PROXY", "http://proxy.example.com:8080",
+        "NO_PROXY", "localhost,127.0.0.1"
+    ));
+
+try (var client = new CopilotClient(options)) {
+    client.start().get();
+    // CLI process uses the proxy settings
+}
+```
+
+This is useful for configuring proxy servers, custom CA certificates, or any environment-specific settings the CLI needs.
+
 ## Best Practices
 
 ### Development