docs: add Java language tabs across all SDK documentation

[brunoborges]

Summary

Adds Java code examples to all 23 language-tabbed documentation files in docs/, bringing Java to parity with Node.js, Python, Go, and .NET.

51 Java tabs added — matching exactly the 51 .NET tabs across the docs.

Files changed (23 files, +1,335 lines)

Getting Started

• docs/getting-started.md — All 8 tutorial steps + telemetry table + text references + Learn More links

Features

• docs/features/index.md — Updated language list to include Java
• docs/features/hooks.md — Registering hooks, permission control
• docs/features/custom-agents.md — Defining agents, selection, sub-agent events
• docs/features/image-input.md — File and blob attachments
• docs/features/streaming-events.md — Event subscription
• docs/features/steering-and-queueing.md — Steering and queue modes
• docs/features/skills.md — Loading and disabling skills

Hooks Reference

• docs/hooks/index.md — Quick start
• docs/hooks/pre-tool-use.md — Signature, allow-all example
• docs/hooks/post-tool-use.md — Signature, logging example
• docs/hooks/user-prompt-submitted.md — Signature, logging example
• docs/hooks/session-lifecycle.md — Start and end hooks
• docs/hooks/error-handling.md — Error policy and handler

Auth & Setup

• docs/auth/index.md — Signed-in user, OAuth, auto-login
• docs/auth/byok.md — Azure AI Foundry, custom model listing
• docs/setup/local-cli.md — Quick start
• docs/setup/bundled-cli.md — Note: Java doesn't bundle CLI
• docs/setup/backend-services.md — External CLI server
• docs/setup/github-oauth.md — Per-user token config

Other

• docs/observability/opentelemetry.md — Telemetry config + tables
• docs/troubleshooting/debugging.md — Debug logging, CLI issues
• docs/integrations/microsoft-agent-framework.md — Standalone SDK usage (Java has no MAF package)

Java SDK patterns used

All examples use idiomatic Java:

• CompletableFuture.get() for blocking async calls
• try-with-resources for client cleanup (AutoCloseable)
• ToolDefinition.create() / createOverride() / createSkipPermission()
• PermissionHandler.APPROVE_ALL
• Typed event handlers: session.on(EventType.class, handler)
• Builder-style config: new SessionConfig().setModel(...).setStreaming(true)

The Java SDK is maintained in github/copilot-sdk-java

[Copilot]

Pull request overview

Adds Java as a first-class language tab across the SDK documentation in docs/, aiming to bring Java examples to parity with existing Node.js, Python, Go, and .NET snippets.

Changes:

• Added Java <details> tabs and code samples across Getting Started, Features, Hooks, Auth/Setup, Observability, Troubleshooting, and Integrations docs.
• Updated language lists/links and at least one cross-language configuration table to include Java.
• Documented Java-specific limitations/notes in a few places (e.g., no bundled CLI, MAF guidance).

Show a summary per file

File	Description
docs/getting-started.md	Adds Java install + tutorial steps (first message, streaming, tools, assistant), plus references/links to Java SDK docs.
docs/features/index.md	Updates supported-language list to include Java.
docs/features/hooks.md	Adds Java hook registration + permission-control examples.
docs/features/custom-agents.md	Adds Java custom-agent configuration and sub-agent event examples.
docs/features/image-input.md	Adds Java file/blob attachment examples.
docs/features/streaming-events.md	Adds Java event subscription examples.
docs/features/steering-and-queueing.md	Adds Java steering/enqueue examples.
docs/features/skills.md	Adds Java skill directories + disabling skills examples.
docs/hooks/index.md	Adds Java hooks quickstart snippet.
docs/hooks/pre-tool-use.md	Adds Java pre-tool-use hook signature + usage example.
docs/hooks/post-tool-use.md	Adds Java post-tool-use hook signature + usage example.
docs/hooks/user-prompt-submitted.md	Adds Java user-prompt-submitted hook signature + usage example.
docs/hooks/session-lifecycle.md	Adds Java session start/end hook signatures.
docs/hooks/error-handling.md	Adds Java guidance for event error policy/handler in lieu of an error hook.
docs/auth/index.md	Adds Java examples for logged-in user, OAuth token usage, and disabling logged-in user.
docs/auth/byok.md	Adds Java BYOK/provider + custom model listing examples.
docs/setup/local-cli.md	Adds Java local-CLI quickstart snippet.
docs/setup/bundled-cli.md	Adds Java note about not bundling CLI + configuration example.
docs/setup/backend-services.md	Adds Java external CLI server connection example.
docs/setup/github-oauth.md	Adds Java per-user client creation example.
docs/observability/opentelemetry.md	Adds Java telemetry snippet and Java row in a table.
docs/troubleshooting/debugging.md	Adds Java debugging/logging configuration snippets and notes.
docs/integrations/microsoft-agent-framework.md	Adds Java guidance/snippets for using the standard SDK (no MAF integration package).

Copilot's findings

Comments suppressed due to low confidence (4)

docs/integrations/microsoft-agent-framework.md:372

• These Java snippets use getData().getContent() on the response objects, while other Java examples use data.content() accessors. Please align on the correct Java API so these examples compile consistently.

).get();

var docs = documentor.sendAndWait(new MessageOptions()
    .setPrompt("Write documentation for these changes: " + review.getData().getContent())).get();
System.out.println(docs.getData().getContent());

docs/integrations/microsoft-agent-framework.md:450

• These Java snippets use getData().getContent() when printing the responses; other Java examples in the docs use data.content(). Please align on the correct accessor to avoid non-compiling examples.

CompletableFuture.allOf(securityFuture, perfFuture).get();

System.out.println("Security: " + securityFuture.get().getData().getContent());
System.out.println("Performance: " + perfFuture.get().getData().getContent());

docs/features/steering-and-queueing.md:434

• This Java enqueue-mode example references SessionConfig, PermissionHandler, and MessageOptions but only imports CopilotClient. Please add the missing SDK/json and java.util imports so the snippet compiles when copy/pasted.

```java
import com.github.copilot.sdk.CopilotClient;

try (var client = new CopilotClient()) {
    client.start().get();

    var session = client.createSession(
        new SessionConfig()
            .setModel("gpt-4.1")
            .setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
    ).get();

docs/features/image-input.md:452

• This Java blob-attachment snippet uses SessionConfig, PermissionHandler, MessageOptions, List, and BlobAttachment but only imports CopilotClient. Please add the missing com.github.copilot.sdk.json.* and java.util.* imports (or fully qualify) so the example compiles.

```java
import com.github.copilot.sdk.CopilotClient;

try (var client = new CopilotClient()) {
    client.start().get();

    var session = client.createSession(
        new SessionConfig()
            .setModel("gpt-4.1")
            .setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
    ).get();

    var base64ImageData = "..."; // your base64-encoded image
    session.send(new MessageOptions()
        .setPrompt("Describe what you see in this image")
        .setAttachments(List.of(
            new BlobAttachment()
                .setData(base64ImageData)
                .setMimeType("image/png")
                .setDisplayName("screenshot.png")
        ))

• Files reviewed: 23/23 changed files
• Comments generated: 15

[Copilot]

Pull request overview

This PR updates the SDK documentation set to include Java alongside the existing TypeScript, Python, Go, and .NET examples, aiming to bring Java to parity across all language-tabbed docs.

Changes:

• Added Java <details> tabs and example snippets across 23 documentation pages in docs/.
• Updated language lists/tables to include Java (e.g., features index, telemetry option tables).
• Added Java-specific notes where feature parity differs (e.g., bundled CLI / some hook differences).

Show a summary per file

File	Description
docs/getting-started.md	Adds Java install + tutorial steps (first message, streaming, tools, interactive assistant) and updates language references/tables.
docs/features/index.md	Adds Java to the list of supported languages in feature guides.
docs/features/hooks.md	Adds Java examples for hook registration and permission-control patterns.
docs/features/custom-agents.md	Adds Java examples for defining/selecting custom agents and handling sub-agent events.
docs/features/image-input.md	Adds Java examples for file and blob image attachments.
docs/features/streaming-events.md	Adds Java examples for subscribing to streaming events.
docs/features/steering-and-queueing.md	Adds Java examples for steering and enqueue modes.
docs/features/skills.md	Adds Java examples for skill directories and disabling skills.
docs/hooks/index.md	Adds Java quick start for session hooks.
docs/hooks/pre-tool-use.md	Adds Java hook signature + usage examples for pre-tool-use.
docs/hooks/post-tool-use.md	Adds Java hook signature + usage examples for post-tool-use.
docs/hooks/user-prompt-submitted.md	Adds Java hook signature + usage examples for user prompt submitted.
docs/hooks/session-lifecycle.md	Adds Java hook signature examples for session start/end.
docs/hooks/error-handling.md	Adds Java guidance for error handling (Java-specific approach).
docs/auth/index.md	Adds Java examples for logged-in user auth and explicit token auth.
docs/auth/byok.md	Adds Java BYOK configuration and custom model listing examples.
docs/setup/local-cli.md	Adds Java quick start for local CLI usage.
docs/setup/bundled-cli.md	Adds Java note + example clarifying Java does not bundle the CLI.
docs/setup/backend-services.md	Adds Java example for connecting to an external CLI server.
docs/setup/github-oauth.md	Adds Java per-user OAuth client/session example.
docs/observability/opentelemetry.md	Adds Java telemetry configuration example and extends TelemetryConfig options/dependency tables.
docs/troubleshooting/debugging.md	Adds Java snippets for enabling debug logging and troubleshooting setup/auth.
docs/integrations/microsoft-agent-framework.md	Adds Java guidance/examples for using the standard SDK directly (no MAF package).

Copilot's findings

Comments suppressed due to low confidence (3)

docs/features/custom-agents.md:363

• This Java snippet uses List.of(...) but doesn't include any imports. Please add import java.util.List; (and the relevant SDK imports if needed) so the example is copy/pasteable.

var session = client.createSession(
    new SessionConfig()
        .setCustomAgents(List.of(
            new CustomAgentConfig()
                .setName("researcher")

docs/features/image-input.md:456

• This Java blob-attachment example uses List.of(...) but doesn't import java.util.List, so it won't compile as shown. Please add the missing import (or qualify it).

    var base64ImageData = "..."; // your base64-encoded image
    session.send(new MessageOptions()
        .setPrompt("Describe what you see in this image")
        .setAttachments(List.of(
            new BlobAttachment()
                .setData(base64ImageData)
                .setMimeType("image/png")
                .setDisplayName("screenshot.png")
        ))

docs/features/skills.md:285

• This Java skills snippet uses List.of(...) but doesn't import java.util.List, so it won't compile as shown. Please add the missing import (or qualify it).

var session = client.createSession(
    new SessionConfig()
        .setSkillDirectories(List.of("./skills"))
        .setDisabledSkills(List.of("experimental-feature", "deprecated-tool"))
        .setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
).get();

• Files reviewed: 23/23 changed files
• Comments generated: 20

[Copilot]

This Java example creates a session without setOnPermissionRequest(...). The Java SDK docs indicate an on-permission handler is required; please add setOnPermissionRequest(PermissionHandler.APPROVE_ALL) (or another handler) to keep the snippet runnable.

[Copilot]

The Java backend-services snippet uses userId and message but doesn't define them in the block, unlike the .NET example above. Please add minimal placeholder declarations so the example is self-contained.

[Copilot]

This Java streaming example creates a session without setOnPermissionRequest(...). The Java SDK docs indicate an on-permission handler is required when creating sessions; please add it here to keep the tutorial runnable.

Suggested change

	.setStreaming(true)
	.setStreaming(true)
	.setOnPermissionRequest(request -> PermissionDecision.allow())

[Copilot]

The Java telemetry snippet uses TelemetryConfig but doesn't import it (unlike other Java examples that import com.github.copilot.sdk.json.*). Please add the missing import so the snippet compiles as shown.