Merge pull request #186 from copilot-community-sdk/docs/fix-documentation-coverage-gaps

Fix documentation coverage gaps

Author: brunoborges

src/site/markdown/advanced.md

@@ -24,6 +24,8 @@ This guide covers advanced scenarios for extending and customizing your Copilot
   - [Loading Skills](#Loading_Skills)
   - [Disabling Skills](#Disabling_Skills)
 - [Custom Configuration Directory](#Custom_Configuration_Directory)
+- [Session Logging](#Session_Logging)
+- [Early Event Registration](#Early_Event_Registration)
 - [User Input Handling](#User_Input_Handling)
 - [Permission Handling](#Permission_Handling)
 - [Session Hooks](#Session_Hooks)
@@ -506,6 +508,54 @@ This is useful when you need to isolate session configuration or use different s
 
 ---
 
+## Session Logging
+
+Send log messages to the session for debugging, status updates, or UI feedback.
+
+```java
+// Simple log message (defaults to "info" level)
+session.log("Processing step 1 of 3").get();
+
+// Log with explicit level and ephemeral flag
+session.log("Downloading dependencies...", "info", true).get();
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `message` | String | The log message text |
+| `level` | String | Log level: `"info"`, `"warning"`, `"error"` |
+| `ephemeral` | Boolean | If `true`, the message is transient and may not be persisted |
+
+Use cases:
+- Displaying progress in a UI while the session processes a request
+- Sending status updates to the session log
+- Debugging session behavior with contextual messages
+
+See [CopilotSession.log()](apidocs/com/github/copilot/sdk/CopilotSession.html#log(java.lang.String)) Javadoc for details.
+
+---
+
+## Early Event Registration
+
+Register an event handler *before* the `session.create` RPC is issued, ensuring no early events are missed.
+
+When you register handlers with `session.on()` after `createSession()` returns, you may miss events emitted during session creation (e.g., `SessionStartEvent`). Use `SessionConfig.setOnEvent()` to guarantee delivery of all events from the very start:
+
+```java
+var events = new CopyOnWriteArrayList<AbstractSessionEvent>();
+
+var session = client.createSession(
+    new SessionConfig().setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
+        .setOnEvent(events::add)  // Registered before session.create RPC
+).get();
+
+// events list now includes SessionStartEvent and any other early events
+```
+
+This is equivalent to calling `session.on(handler)` immediately after creation, but executes earlier in the lifecycle. The same option is available on `ResumeSessionConfig.setOnEvent()` for resumed sessions.
+
+---
+
 ## User Input Handling
 
 Handle user input requests when the AI uses the `ask_user` tool to gather information from the user.

src/site/markdown/documentation.md

@@ -162,6 +162,9 @@ The SDK supports event types organized by category. All events extend `AbstractS
 | `SessionInfoEvent` | `session.info` | Informational message from the session |
 | `SessionShutdownEvent` | `session.shutdown` | Session is shutting down (includes reason and exit code) |
 | `SessionModelChangeEvent` | `session.model_change` | The model was changed mid-session |
+| `SessionModeChangedEvent` | `session.mode_changed` | Session mode changed (e.g., plan mode) |
+| `SessionPlanChangedEvent` | `session.plan_changed` | Session plan was updated |
+| `SessionWorkspaceFileChangedEvent` | `session.workspace_file_changed` | A file in the workspace was modified |
 | `SessionHandoffEvent` | `session.handoff` | Session handed off to another agent |
 | `SessionTruncationEvent` | `session.truncation` | Context was truncated due to limits |
 | `SessionSnapshotRewindEvent` | `session.snapshot_rewind` | Session rewound to a previous snapshot |
@@ -220,8 +223,37 @@ The SDK supports event types organized by category. All events extend `AbstractS
 | `HookStartEvent` | `hook.start` | Hook execution started |
 | `HookEndEvent` | `hook.end` | Hook execution completed |
 | `SystemMessageEvent` | `system.message` | System-level message |
+| `SystemNotificationEvent` | `system.notification` | System notification (informational) |
 | `SkillInvokedEvent` | `skill.invoked` | A skill was invoked |
 
+### External Tool Events
+
+| Event | Type String | Description |
+|-------|-------------|-------------|
+| `ExternalToolRequestedEvent` | `external_tool.requested` | An external tool invocation was requested |
+| `ExternalToolCompletedEvent` | `external_tool.completed` | An external tool invocation completed |
+
+### Permission Events
+
+| Event | Type String | Description |
+|-------|-------------|-------------|
+| `PermissionRequestedEvent` | `permission.requested` | A permission request was issued |
+| `PermissionCompletedEvent` | `permission.completed` | A permission request was resolved |
+
+### Command Events
+
+| Event | Type String | Description |
+|-------|-------------|-------------|
+| `CommandQueuedEvent` | `command.queued` | A command was queued for execution |
+| `CommandCompletedEvent` | `command.completed` | A queued command completed |
+
+### Plan Mode Events
+
+| Event | Type String | Description |
+|-------|-------------|-------------|
+| `ExitPlanModeRequestedEvent` | `exit_plan_mode.requested` | Exit from plan mode was requested |
+| `ExitPlanModeCompletedEvent` | `exit_plan_mode.completed` | Exit from plan mode completed |
+
 See the [events package Javadoc](apidocs/com/github/copilot/sdk/events/package-summary.html) for detailed event data structures.
 
 ---
@@ -598,9 +630,12 @@ When resuming a session, you can optionally reconfigure many settings. This is u
 | `configDir` | Override configuration directory |
 | `mcpServers` | Configure MCP servers |
 | `customAgents` | Configure custom agents |
+| `agent` | Pre-select a custom agent at session start |
 | `skillDirectories` | Directories to load skills from |
 | `disabledSkills` | Skills to disable |
 | `infiniteSessions` | Configure infinite session behavior |
+| `disableResume` | When `true`, resumes without emitting a `session.resume` event |
+| `onEvent` | Event handler registered before session resumption |
 
 **Example: Changing Model on Resume**
 
@@ -637,6 +672,7 @@ Complete list of all `SessionConfig` options for `createSession()`:
 | Option | Type | Description | Guide |
 |--------|------|-------------|-------|
 | `sessionId` | String | Custom session ID (auto-generated if omitted) | — |
+| `clientName` | String | Client name for User-Agent identification | — |
 | `model` | String | AI model to use | [Choosing a Model](#Choosing_a_Model) |
 | `reasoningEffort` | String | Reasoning depth: `"low"`, `"medium"`, `"high"`, `"xhigh"` | [Reasoning Effort](#Reasoning_Effort) |
 | `tools` | List<ToolDefinition> | Custom tools the assistant can invoke | [Custom Tools](advanced.html#Custom_Tools) |
@@ -651,10 +687,12 @@ Complete list of all `SessionConfig` options for `createSession()`:
 | `streaming` | boolean | Enable streaming response chunks | [Streaming Responses](#Streaming_Responses) |
 | `mcpServers` | Map<String, Object> | MCP server configurations | [MCP Servers](mcp.html) |
 | `customAgents` | List<CustomAgentConfig> | Custom agent definitions | [Custom Agents](advanced.html#Custom_Agents) |
+| `agent` | String | Pre-select a custom agent at session start | [Custom Agents](advanced.html#Custom_Agents) |
 | `infiniteSessions` | InfiniteSessionConfig | Auto-compaction for long conversations | [Infinite Sessions](advanced.html#Infinite_Sessions) |
 | `skillDirectories` | List<String> | Directories to load skills from | [Skills](advanced.html#Skills_Configuration) |
 | `disabledSkills` | List<String> | Skills to disable by name | [Skills](advanced.html#Skills_Configuration) |
 | `configDir` | String | Custom configuration directory | [Config Dir](advanced.html#Custom_Configuration_Directory) |
+| `onEvent` | Consumer<AbstractSessionEvent> | Event handler registered before session creation | [Early Event Registration](advanced.html#Early_Event_Registration) |
 
 ### Cloning SessionConfig
 

src/site/markdown/setup.md

@@ -349,6 +349,7 @@ Complete list of `CopilotClientOptions` settings:
 | `logLevel` | String | CLI log level | `"info"` |
 | `environment` | Map | Environment variables | inherited |
 | `cwd` | String | Working directory | current dir |
+| `onListModels` | Supplier | Custom model listing implementation | `null` (use CLI) |
 
 ### Extra CLI Arguments