diff --git a/.github/templates/index.html b/.github/templates/index.html
index d273ad0746..04f83dfca0 100644
--- a/.github/templates/index.html
+++ b/.github/templates/index.html
@@ -18,7 +18,7 @@
       <h1>GitHub Copilot SDK for <span class="gradient-text">Java</span></h1>
       <p class="hero-subtitle">The official SDK for building AI-powered tools with GitHub Copilot's agentic runtime.</p>
       <div class="header-buttons">
-        <a href="https://github.com/github/copilot-sdk-java" class="btn btn-github">
+        <a href="https://github.com/github/copilot-sdk/tree/main/java" class="btn btn-github">
           <svg height="20" width="20" viewBox="0 0 16 16"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"></path></svg>
           View on GitHub
         </a>
@@ -75,7 +75,7 @@ <h2 class="section-title">Available Versions</h2>
 
     <footer class="footer">
       <div class="footer-links">
-        <a href="https://github.com/github/copilot-sdk-java">GitHub Repository</a>
+        <a href="https://github.com/github/copilot-sdk/tree/main/java">GitHub Repository</a>
         <span class="sep">·</span>
         <a href="https://central.sonatype.com/artifact/com.github/copilot-sdk">Maven Central</a>
         <span class="sep">·</span>
diff --git a/.github/workflows/deploy-site.yml b/.github/workflows/deploy-site.yml
index 91e3b9e5b4..fe4db89d49 100644
--- a/.github/workflows/deploy-site.yml
+++ b/.github/workflows/deploy-site.yml
@@ -1,72 +1,96 @@
-# Workflow for deploying versioned documentation to GitHub Pages
+# Workflow for deploying versioned documentation to GitHub Pages.
+# Site content (src/site/, pom.xml) lives in THIS repo.
+# Java source code is checked out from the monorepo (github/copilot-sdk) at a release tag.
 name: Deploy Documentation
 
-env:
-    # Disable Husky Git hooks in CI to prevent local development hooks
-    # (e.g., pre-commit formatting checks) from running during automated
-    # workflows that perform git commits and pushes.
-    HUSKY: 0
-
 on:
-  # Runs after Build & Test succeeds on main (publishes to /snapshot/)
-  workflow_run:
-    workflows: ["Build & Test"]
-    types: [completed]
-    branches: [main]
-
-  # Runs on release publish (publishes to /latest/ and /vX.Y.Z/)
-  release:
-    types: [published]
-
-  # Allows manual trigger
   workflow_dispatch:
     inputs:
       version:
-        description: 'Specific version/tag to build (leave empty for snapshot from main)'
+        description: 'Version to build in tag format (e.g., java/v1.0.1-java.0). The java/v prefix is stripped to form the site directory name.'
         type: string
-        default: ''
+        required: true
       publish_as_latest:
-        description: 'Also publish as latest?'
+        description: 'Also publish as /latest/?'
         type: boolean
-        default: false
-      rebuild_all_versions:
-        description: 'Rebuild documentation for all release tags?'
-        type: boolean
-        default: false
+        default: true
+      monorepo_tag:
+        description: 'Tag in github/copilot-sdk monorepo (e.g., java/v1.0.1-java.0)'
+        type: string
+        required: true
 
-# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
 permissions:
-  actions: read      # Required to download artifacts from Build & Test workflow
   contents: write
   pages: write
   id-token: write
 
-# Allow only one concurrent deployment
 concurrency:
   group: "pages"
   cancel-in-progress: false
 
 jobs:
   build-and-deploy:
-    # Skip if triggered by workflow_run that failed
-    if: ${{ github.event_name != 'workflow_run' || github.event.workflow_run.conclusion == 'success' }}
     runs-on: ubuntu-latest
     environment:
       name: github-pages
       url: ${{ steps.deployment.outputs.page_url }}
     steps:
-      - name: Checkout
+      # 0. Validate required secrets and inputs
+      - name: Validate inputs and secrets
+        env:
+          MONOREPO_READ_TOKEN: ${{ secrets.MONOREPO_READ_TOKEN }}
+        run: |
+          if [[ -z "${MONOREPO_READ_TOKEN}" ]]; then
+            echo "::error::MONOREPO_READ_TOKEN secret is required but not configured."
+            exit 1
+          fi
+          VERSION="${{ inputs.version }}"
+          if [[ "${VERSION}" != java/v* ]]; then
+            echo "::error::VERSION must start with 'java/v' (got: '${VERSION}')"
+            exit 1
+          fi
+          if [[ "${VERSION}" == *"../"* ]]; then
+            echo "::error::VERSION must not contain '../'"
+            exit 1
+          fi
+          DEPLOY_VERSION="${VERSION#java/v}"
+          echo "DEPLOY_VERSION=${DEPLOY_VERSION}" >> "$GITHUB_ENV"
+
+      # 1. Checkout this (standalone) repo — has src/site/, pom.xml, templates
+      - name: Checkout standalone repo
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      # 2. Checkout the monorepo at the release tag (for Java source code)
+      - name: Checkout monorepo at release tag
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
-          fetch-depth: 0
+          repository: github/copilot-sdk
+          ref: ${{ inputs.monorepo_tag }}
+          path: monorepo
+          token: ${{ secrets.MONOREPO_READ_TOKEN }}
 
-      - name: Set up JDK 17
+      # 3. Set up JDK
+      - name: Set up JDK 25
         uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5
         with:
-          java-version: '17'
-          distribution: 'temurin'
+          java-version: '25'
+          distribution: 'microsoft'
           cache: 'maven'
 
+      # 4. Compile monorepo Java source (needed for javadoc, SpotBugs, etc.)
+      - name: Compile monorepo Java source
+        working-directory: monorepo/java
+        run: |
+          echo "Compiling Java source from tag ${{ inputs.monorepo_tag }}"
+          mvn clean compile test -DskipTests=false -Dcheckstyle.skip=true -B
+
+      # 5. Build the Maven Site using THIS repo's pom.xml + src/site/
+      - name: Build documentation site
+        run: |
+          echo "Building site for version ${{ env.DEPLOY_VERSION }}"
+          mvn site -Dsite.version=${{ env.DEPLOY_VERSION }} -B
+
+      # 6. Checkout gh-pages branch from this (standalone) repo
       - name: Checkout gh-pages branch
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
@@ -85,209 +109,91 @@ jobs:
             git remote add origin "https://x-access-token:${{ secrets.GITHUB_TOKEN }}@github.com/${{ github.repository }}.git"
           fi
 
-      - name: Get all release tags
-        id: tags
+      # 7. Copy generated site to version directory
+      - name: Deploy version documentation
         run: |
-          # Get all tags that look like version numbers (v1.0.0 or 1.0.0)
-          TAGS=$(git tag -l | grep -E '^v?[0-9]+\.[0-9]+' | sort -Vr)
-          echo "all_tags<<EOF" >> $GITHUB_OUTPUT
-          echo "$TAGS" >> $GITHUB_OUTPUT
-          echo "EOF" >> $GITHUB_OUTPUT
-          
-          # Get the latest tag
-          LATEST_TAG=$(echo "$TAGS" | head -n 1)
-          echo "latest_tag=$LATEST_TAG" >> $GITHUB_OUTPUT
-          
-          # Determine what to build
-          if [[ "${{ github.event_name }}" == "release" ]]; then
-            echo "build_tag=${{ github.event.release.tag_name }}" >> $GITHUB_OUTPUT
-            echo "is_release=true" >> $GITHUB_OUTPUT
-          elif [[ -n "${{ inputs.version }}" ]]; then
-            # Manual trigger with specific version
-            VERSION="${{ inputs.version }}"
-            # Add 'v' prefix if not present for tag lookup
-            if [[ ! "$VERSION" =~ ^v ]]; then
-              TAG="v$VERSION"
-            else
-              TAG="$VERSION"
-            fi
-            echo "build_tag=$TAG" >> $GITHUB_OUTPUT
-            echo "is_release=true" >> $GITHUB_OUTPUT
-          else
-            echo "build_tag=" >> $GITHUB_OUTPUT
-            echo "is_release=false" >> $GITHUB_OUTPUT
-          fi
+          echo "Deploying documentation for version ${DEPLOY_VERSION}"
 
-      - name: Download test results from Build & Test
-        if: steps.tags.outputs.is_release == 'false' && inputs.rebuild_all_versions != true && github.event_name == 'workflow_run'
-        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8
-        with:
-          name: test-results-for-site
-          path: /tmp/test-results
-          run-id: ${{ github.event.workflow_run.id }}
-          github-token: ${{ secrets.GITHUB_TOKEN }}
-        continue-on-error: true
+          rm -rf "site/${DEPLOY_VERSION}"
+          mkdir -p "site/${DEPLOY_VERSION}"
+          cp -r target/site/* "site/${DEPLOY_VERSION}/"
 
-      - name: Build snapshot documentation (main branch)
-        if: steps.tags.outputs.is_release == 'false' && inputs.rebuild_all_versions != true
-        run: |
-          # Compile sources (needed for javadoc and other reports)
-          ./mvnw clean compile -DskipTests -Dcheckstyle.skip=true
-          
-          # Restore test results from Build & Test (for JaCoCo + Surefire reports)
-          # upload-artifact strips the common ancestor (target/), so files are at root
-          if [ -d "/tmp/test-results/surefire-reports" ]; then
-            mkdir -p target/surefire-reports
-            cp -r /tmp/test-results/surefire-reports/* target/surefire-reports/
-            echo "Surefire reports restored"
-          fi
-          if [ -f "/tmp/test-results/jacoco-test-results/sdk-tests.exec" ]; then
-            mkdir -p target/jacoco-test-results
-            cp /tmp/test-results/jacoco-test-results/sdk-tests.exec target/jacoco-test-results/
-            echo "JaCoCo exec restored"
-          fi
-          
-          # Generate site (report plugins pick up the restored data)
-          ./mvnw site -DskipTests -Dcheckstyle.skip=true
-          
-          rm -rf "site/snapshot"
-          mkdir -p "site/snapshot"
-          cp -r target/site/* "site/snapshot/"
-
-      - name: Build documentation for specific version
-        if: steps.tags.outputs.is_release == 'true' && inputs.rebuild_all_versions != true
-        run: |
-          TAG="${{ steps.tags.outputs.build_tag }}"
-          VERSION="${TAG#v}"  # Remove 'v' prefix
-          
-          echo "Building documentation for $TAG (version $VERSION)"
-          git checkout "$TAG"
-          
-          ./mvnw clean site -DskipTests -Dcheckstyle.skip=true
-          
-          rm -rf "site/$VERSION"
-          mkdir -p "site/$VERSION"
-          cp -r target/site/* "site/$VERSION/"
-          
-          # Update /latest/ if this is a release event or publish_as_latest is true
-          if [[ "${{ github.event_name }}" == "release" ]] || [[ "${{ inputs.publish_as_latest }}" == "true" ]]; then
+          # Also publish as /latest/ if requested
+          if [[ "${{ inputs.publish_as_latest }}" == "true" ]]; then
             rm -rf "site/latest"
             mkdir -p "site/latest"
             cp -r target/site/* "site/latest/"
           fi
-          
-          git checkout main
-
-      - name: Build documentation for all release tags
-        if: inputs.rebuild_all_versions == true
-        run: |
-          LATEST_TAG="${{ steps.tags.outputs.latest_tag }}"
-          
-          while IFS= read -r TAG; do
-            if [[ -z "$TAG" ]]; then continue; fi
-            
-            VERSION="${TAG#v}"  # Remove 'v' prefix
-            echo "Building documentation for $TAG (version $VERSION)"
-            
-            git checkout "$TAG"
-            ./mvnw clean site -DskipTests -Dcheckstyle.skip=true
-            
-            rm -rf "site/$VERSION"
-            mkdir -p "site/$VERSION"
-            cp -r target/site/* "site/$VERSION/"
-            
-            # If this is the latest tag, also update /latest/
-            if [[ "$TAG" == "$LATEST_TAG" ]]; then
-              rm -rf "site/latest"
-              mkdir -p "site/latest"
-              cp -r target/site/* "site/latest/"
-            fi
-            
-          done <<< "${{ steps.tags.outputs.all_tags }}"
-          
-          # Return to main and build snapshot
-          git checkout main
-          ./mvnw clean site -DskipTests -Dcheckstyle.skip=true
-          
-          rm -rf "site/snapshot"
-          mkdir -p "site/snapshot"
-          cp -r target/site/* "site/snapshot/"
 
+      # 8. Copy version index page from templates
       - name: Copy version index page
         run: |
           cp .github/templates/index.html site/index.html
           cp .github/templates/styles.css site/styles.css
 
-      - name: Update version list from git tags
+      # 9. Update version list based on directories present in gh-pages
+      - name: Update version list from deployed directories
         run: |
           cd site
-          
-          REPO_URL="https://github.com/github/copilot-sdk-java"
-          
-          # Get versions from git tags (already sorted by version, descending)
-          VERSIONS=$(git -C .. tag -l | grep -E '^v?[0-9]+\.[0-9]+' | sed 's/^v//' | sort -Vr)
+
+          MONOREPO_URL="https://github.com/github/copilot-sdk"
+          STANDALONE_URL="https://github.com/github/copilot-sdk-java"
+
+          VERSIONS=$(ls -d */ 2>/dev/null | sed 's|/||' | grep -E '^[0-9]+\.[0-9]+' | sort -Vr || true)
+
           HAS_SNAPSHOT=$([ -d "snapshot" ] && echo "true" || echo "false")
-          
-          # Generate version links
+
           CURRENT_HTML=""
           OLDER_HTML=""
           IS_FIRST_VERSION="true"
-          
-          # Add snapshot if exists (goes to current versions)
+
           if [ "$HAS_SNAPSHOT" = "true" ]; then
-            CURRENT_HTML+='<li><span class="version-name">Development (main branch)</span><span class="version-links"><a href="./snapshot/" class="doc-link">documentation ↗</a><a href="'"$REPO_URL"'/blob/main/CHANGELOG.md" class="release-link">changelog ↗</a><span class="badge snapshot">snapshot</span></span></li>'
+            CURRENT_HTML+='<li><span class="version-name">Development (main branch)</span><span class="version-links"><a href="./snapshot/" class="doc-link">documentation ↗</a><a href="'"${MONOREPO_URL}"'/blob/main/java/CHANGELOG.md" class="release-link">changelog ↗</a><span class="badge snapshot">snapshot</span></span></li>'
           fi
-          
-          # Add versioned releases from tags (first one is latest, rest go to older)
+
           for v in $VERSIONS; do
-            if [ -d "$v" ]; then
-              if [ "$IS_FIRST_VERSION" = "true" ]; then
-                CURRENT_HTML+='<li class="latest-version"><span class="version-name">Version '"$v"'</span><span class="version-links"><a href="./'"$v"'/" class="doc-link">documentation ↗</a><a href="'"$REPO_URL"'/releases/tag/v'"$v"'" class="release-link">release notes ↗</a><span class="badge latest">latest</span></span></li>'
-                IS_FIRST_VERSION="false"
-              else
-                OLDER_HTML+='<li><span>'"$v"'</span><span class="older-links"><a href="./'"$v"'/" class="doc-link">documentation ↗</a><a href="'"$REPO_URL"'/releases/tag/v'"$v"'" class="release-link">release notes ↗</a></span></li>'
-              fi
+            RELEASE_URL="${MONOREPO_URL}/releases/tag/java/v${v}"
+
+            if [ "$IS_FIRST_VERSION" = "true" ]; then
+              CURRENT_HTML+='<li class="latest-version"><span class="version-name">Version '"$v"'</span><span class="version-links"><a href="./'"$v"'/" class="doc-link">documentation ↗</a><a href="'"$RELEASE_URL"'" class="release-link">release notes ↗</a><span class="badge latest">latest</span></span></li>'
+              IS_FIRST_VERSION="false"
+            else
+              OLDER_HTML+='<li><span>'"$v"'</span><span class="older-links"><a href="./'"$v"'/" class="doc-link">documentation ↗</a><a href="'"$RELEASE_URL"'" class="release-link">release notes ↗</a></span></li>'
             fi
           done
-          
-          # Update the index.html using the placeholders
+
           sed -i "s|<!-- CURRENT_VERSIONS_PLACEHOLDER -->|$CURRENT_HTML|" index.html
           sed -i "s|<!-- OLDER_VERSIONS_PLACEHOLDER -->|$OLDER_HTML|" index.html
 
+      # 10. Overlay custom JaCoCo CSS
       - name: Overlay custom JaCoCo CSS
         run: |
           cd site
-          for dir in */jacoco/jacoco-resources; do
-            if [ -d "$dir" ]; then
-              cp ../src/site/jacoco-resources/report.css "$dir/report.css"
-              echo "Overlaid JaCoCo CSS in $dir"
-            fi
-          done
+          JACOCO_CSS="../src/site/jacoco-resources/report.css"
+          if [ -f "${JACOCO_CSS}" ]; then
+            for dir in */jacoco/jacoco-resources; do
+              if [ -d "$dir" ]; then
+                cp "${JACOCO_CSS}" "$dir/report.css"
+                echo "Overlaid JaCoCo CSS in $dir"
+              fi
+            done
+          fi
 
+      # 11. Push to gh-pages
       - name: Deploy to GitHub Pages
         run: |
           cd site
           git config user.name "github-actions[bot]"
           git config user.email "github-actions[bot]@users.noreply.github.com"
-          
-          # Set remote URL with token for authentication
+
           git remote set-url origin "https://x-access-token:${{ secrets.GITHUB_TOKEN }}@github.com/${{ github.repository }}.git" 2>/dev/null || \
             git remote add origin "https://x-access-token:${{ secrets.GITHUB_TOKEN }}@github.com/${{ github.repository }}.git"
-          
+
           git add -A
-          
-          # Create descriptive commit message
-          if [[ "${{ inputs.rebuild_all_versions }}" == "true" ]]; then
-            COMMIT_MSG="Rebuild documentation for all versions"
-          elif [[ "${{ steps.tags.outputs.is_release }}" == "true" ]]; then
-            COMMIT_MSG="Deploy documentation: ${{ steps.tags.outputs.build_tag }}"
-          else
-            COMMIT_MSG="Deploy documentation: snapshot"
-          fi
-          
+
+          COMMIT_MSG="Deploy documentation: ${DEPLOY_VERSION} (from ${{ inputs.monorepo_tag }})"
           git diff --staged --quiet || git commit -m "$COMMIT_MSG"
-          
-          # Push, creating the branch if it doesn't exist
+
           git push -u origin gh-pages --force
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
diff --git a/pom.xml b/pom.xml
new file mode 100644
index 0000000000..09fe864bd0
--- /dev/null
+++ b/pom.xml
@@ -0,0 +1,261 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+  Site-only POM for github/copilot-sdk-java.
+  This POM builds the Maven Site (javadoc, JaCoCo, SpotBugs, etc.) from
+  Java source code checked out from the monorepo (github/copilot-sdk) at
+  a release tag. It is NOT used for compiling/testing the SDK itself.
+
+  Expected layout at build time (set up by deploy-site.yml):
+    .                     (this repo — standalone)
+    ├── pom.xml           (this file)
+    ├── src/site/         (site content: markdown, site.xml, CSS)
+    └── monorepo/         (checkout of github/copilot-sdk at release tag)
+        └── java/
+            └── src/main/java/   (SDK source for javadoc)
+            └── target/          (compiled classes from monorepo build)
+-->
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+
+    <groupId>com.github</groupId>
+    <artifactId>copilot-sdk-java-site</artifactId>
+    <version>${site.version}</version>
+    <packaging>pom</packaging>
+
+    <name>GitHub Copilot SDK for Java — Documentation Site</name>
+    <description>Maven Site build for the GitHub Copilot SDK for Java</description>
+    <url>https://github.com/github/copilot-sdk-java</url>
+
+    <properties>
+        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+        <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
+        <!-- Overridden at build time via -Dsite.version=... -->
+        <site.version>0.0.0-SNAPSHOT</site.version>
+        <!-- Path to the monorepo checkout (relative to this POM) -->
+        <monorepo.java.dir>${project.basedir}/monorepo/java</monorepo.java.dir>
+    </properties>
+
+    <!-- Dependencies needed on classpath for javadoc link resolution -->
+    <dependencies>
+        <dependency>
+            <groupId>com.fasterxml.jackson.core</groupId>
+            <artifactId>jackson-databind</artifactId>
+            <version>2.21.3</version>
+            <scope>provided</scope>
+        </dependency>
+        <dependency>
+            <groupId>com.fasterxml.jackson.core</groupId>
+            <artifactId>jackson-annotations</artifactId>
+            <version>2.21</version>
+            <scope>provided</scope>
+        </dependency>
+    </dependencies>
+
+    <build>
+        <!-- Point source directory at monorepo's Java source for reports -->
+        <sourceDirectory>${monorepo.java.dir}/src/main/java</sourceDirectory>
+
+        <plugins>
+            <!-- Maven Resources Plugin — site-filtering executions -->
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-resources-plugin</artifactId>
+                <version>3.5.0</version>
+                <executions>
+                    <execution>
+                        <id>filter-site-markdown</id>
+                        <phase>pre-site</phase>
+                        <goals>
+                            <goal>copy-resources</goal>
+                        </goals>
+                        <configuration>
+                            <outputDirectory>${project.build.directory}/filtered-site/markdown</outputDirectory>
+                            <resources>
+                                <resource>
+                                    <directory>src/site/markdown</directory>
+                                    <filtering>true</filtering>
+                                </resource>
+                            </resources>
+                        </configuration>
+                    </execution>
+                    <execution>
+                        <id>copy-site-descriptor</id>
+                        <phase>pre-site</phase>
+                        <goals>
+                            <goal>copy-resources</goal>
+                        </goals>
+                        <configuration>
+                            <outputDirectory>${project.build.directory}/filtered-site</outputDirectory>
+                            <resources>
+                                <resource>
+                                    <directory>src/site</directory>
+                                    <includes>
+                                        <include>site.xml</include>
+                                    </includes>
+                                    <filtering>false</filtering>
+                                </resource>
+                            </resources>
+                        </configuration>
+                    </execution>
+                    <execution>
+                        <id>copy-site-resources</id>
+                        <phase>pre-site</phase>
+                        <goals>
+                            <goal>copy-resources</goal>
+                        </goals>
+                        <configuration>
+                            <outputDirectory>${project.build.directory}/filtered-site/resources</outputDirectory>
+                            <resources>
+                                <resource>
+                                    <directory>src/site/resources</directory>
+                                    <filtering>false</filtering>
+                                </resource>
+                            </resources>
+                        </configuration>
+                    </execution>
+                    <execution>
+                        <id>overlay-jacoco-css</id>
+                        <phase>site</phase>
+                        <goals>
+                            <goal>copy-resources</goal>
+                        </goals>
+                        <configuration>
+                            <outputDirectory>${project.reporting.outputDirectory}/jacoco/jacoco-resources</outputDirectory>
+                            <resources>
+                                <resource>
+                                    <directory>src/site/jacoco-resources</directory>
+                                    <filtering>false</filtering>
+                                </resource>
+                            </resources>
+                            <overwrite>true</overwrite>
+                        </configuration>
+                    </execution>
+                </executions>
+            </plugin>
+            <!-- Maven Site Plugin -->
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-site-plugin</artifactId>
+                <version>3.21.0</version>
+                <configuration>
+                    <inputEncoding>UTF-8</inputEncoding>
+                    <outputEncoding>UTF-8</outputEncoding>
+                    <siteDirectory>${project.build.directory}/filtered-site</siteDirectory>
+                    <generatedSiteDirectory>${project.build.directory}/filtered-site-generated</generatedSiteDirectory>
+                </configuration>
+                <dependencies>
+                    <dependency>
+                        <groupId>org.apache.maven.doxia</groupId>
+                        <artifactId>doxia-module-markdown</artifactId>
+                        <version>2.1.0</version>
+                    </dependency>
+                </dependencies>
+            </plugin>
+        </plugins>
+    </build>
+
+    <!-- Reporting plugins for Maven Site -->
+    <reporting>
+        <plugins>
+            <!-- Project Info Reports -->
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-project-info-reports-plugin</artifactId>
+                <version>3.9.0</version>
+            </plugin>
+            <!-- Javadoc from monorepo source -->
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-javadoc-plugin</artifactId>
+                <version>3.11.2</version>
+                <configuration>
+                    <sourcepath>${monorepo.java.dir}/src/main/java</sourcepath>
+                    <subpackages>com.github.copilot</subpackages>
+                </configuration>
+                <reportSets>
+                    <reportSet>
+                        <reports>
+                            <report>javadoc</report>
+                        </reports>
+                    </reportSet>
+                </reportSets>
+            </plugin>
+            <!-- JaCoCo coverage (from monorepo test run) -->
+            <plugin>
+                <groupId>org.jacoco</groupId>
+                <artifactId>jacoco-maven-plugin</artifactId>
+                <version>0.8.14</version>
+                <configuration>
+                    <dataFile>${monorepo.java.dir}/target/jacoco-test-results/sdk-tests.exec</dataFile>
+                </configuration>
+                <reportSets>
+                    <reportSet>
+                        <reports>
+                            <report>report</report>
+                        </reports>
+                    </reportSet>
+                </reportSets>
+            </plugin>
+            <!-- Surefire test results report -->
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-surefire-report-plugin</artifactId>
+                <version>3.5.5</version>
+                <configuration>
+                    <reportsDirectories>
+                        <reportsDirectory>${monorepo.java.dir}/target/surefire-reports</reportsDirectory>
+                    </reportsDirectories>
+                </configuration>
+            </plugin>
+            <!-- SpotBugs static analysis -->
+            <plugin>
+                <groupId>com.github.spotbugs</groupId>
+                <artifactId>spotbugs-maven-plugin</artifactId>
+                <version>4.9.8.3</version>
+                <configuration>
+                    <excludeFilterFile>${monorepo.java.dir}/config/spotbugs/spotbugs-exclude.xml</excludeFilterFile>
+                </configuration>
+            </plugin>
+            <!-- TODO/FIXME tag tracker -->
+            <plugin>
+                <groupId>org.codehaus.mojo</groupId>
+                <artifactId>taglist-maven-plugin</artifactId>
+                <version>3.2.2</version>
+                <configuration>
+                    <tagListOptions>
+                        <tagClasses>
+                            <tagClass>
+                                <displayName>Todo Work</displayName>
+                                <tags>
+                                    <tag>
+                                        <matchString>TODO</matchString>
+                                        <matchType>ignoreCase</matchType>
+                                    </tag>
+                                    <tag>
+                                        <matchString>FIXME</matchString>
+                                        <matchType>ignoreCase</matchType>
+                                    </tag>
+                                </tags>
+                            </tagClass>
+                        </tagClasses>
+                    </tagListOptions>
+                </configuration>
+            </plugin>
+            <!-- Dependency analysis report -->
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-dependency-plugin</artifactId>
+                <version>3.10.0</version>
+                <reportSets>
+                    <reportSet>
+                        <reports>
+                            <report>analyze-report</report>
+                        </reports>
+                    </reportSet>
+                </reportSets>
+            </plugin>
+        </plugins>
+    </reporting>
+</project>
diff --git a/src/site/jacoco-resources/report.css b/src/site/jacoco-resources/report.css
new file mode 100644
index 0000000000..585ab68210
--- /dev/null
+++ b/src/site/jacoco-resources/report.css
@@ -0,0 +1,299 @@
+/* ===== Custom JaCoCo Report Theme ===== */
+/* Matches the Copilot SDK site design */
+
+body, td {
+  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, Cantarell, sans-serif;
+  font-size: 10pt;
+  color: #24292f;
+  -webkit-font-smoothing: antialiased;
+}
+
+body {
+  background: #f6f8fa;
+  margin: 0;
+  padding: 20px;
+}
+
+h1 {
+  font-weight: 800;
+  font-size: 18pt;
+  color: #24292f;
+  margin-bottom: 16px;
+}
+
+a {
+  color: #0969da;
+  text-decoration: none;
+}
+
+a:hover {
+  color: #0550ae;
+  text-decoration: underline;
+}
+
+/* ===== Breadcrumb ===== */
+.breadcrumb {
+  background: #fff;
+  border: 1px solid #d0d7de;
+  border-radius: 10px;
+  padding: 10px 16px;
+  margin-bottom: 20px;
+}
+
+.breadcrumb .info {
+  float: right;
+}
+
+.breadcrumb .info a {
+  margin-left: 8px;
+  color: #57606a;
+  font-size: 0.9em;
+}
+
+.breadcrumb .info a:hover {
+  color: #0969da;
+}
+
+/* ===== Element Icons ===== */
+.el_report {
+  padding-left: 18px;
+  background-image: url(report.gif);
+  background-position: left center;
+  background-repeat: no-repeat;
+}
+
+.el_group {
+  padding-left: 18px;
+  background-image: url(group.gif);
+  background-position: left center;
+  background-repeat: no-repeat;
+}
+
+.el_bundle {
+  padding-left: 18px;
+  background-image: url(bundle.gif);
+  background-position: left center;
+  background-repeat: no-repeat;
+}
+
+.el_package {
+  padding-left: 18px;
+  background-image: url(package.gif);
+  background-position: left center;
+  background-repeat: no-repeat;
+}
+
+.el_class {
+  padding-left: 18px;
+  background-image: url(class.gif);
+  background-position: left center;
+  background-repeat: no-repeat;
+}
+
+.el_source {
+  padding-left: 18px;
+  background-image: url(source.gif);
+  background-position: left center;
+  background-repeat: no-repeat;
+}
+
+.el_method {
+  padding-left: 18px;
+  background-image: url(method.gif);
+  background-position: left center;
+  background-repeat: no-repeat;
+}
+
+.el_session {
+  padding-left: 18px;
+  background-image: url(session.gif);
+  background-position: left center;
+  background-repeat: no-repeat;
+}
+
+/* ===== Source Code ===== */
+pre.source {
+  background: #fff;
+  border: 1px solid #d0d7de;
+  border-radius: 10px;
+  font-family: 'SFMono-Regular', Consolas, 'Liberation Mono', Menlo, monospace;
+  overflow-x: auto;
+}
+
+pre.source ol {
+  margin-bottom: 0;
+  margin-top: 0;
+}
+
+pre.source li {
+  border-left: 1px solid #d0d7de;
+  color: #8b949e;
+  padding-left: 0;
+}
+
+pre.source span.fc {
+  background-color: #dafbe1;
+}
+
+pre.source span.nc {
+  background-color: #ffeef0;
+}
+
+pre.source span.pc {
+  background-color: #fff8c5;
+}
+
+pre.source span.bfc {
+  background-image: url(branchfc.gif);
+  background-repeat: no-repeat;
+  background-position: 2px center;
+}
+
+pre.source span.bfc:hover {
+  background-color: #aff5b4;
+}
+
+pre.source span.bnc {
+  background-image: url(branchnc.gif);
+  background-repeat: no-repeat;
+  background-position: 2px center;
+}
+
+pre.source span.bnc:hover {
+  background-color: #ffcecb;
+}
+
+pre.source span.bpc {
+  background-image: url(branchpc.gif);
+  background-repeat: no-repeat;
+  background-position: 2px center;
+}
+
+pre.source span.bpc:hover {
+  background-color: #fff2b2;
+}
+
+/* ===== Coverage Table ===== */
+table.coverage {
+  empty-cells: show;
+  border-collapse: separate;
+  border-spacing: 0;
+  border: 1px solid #d0d7de;
+  border-radius: 10px;
+  overflow: hidden;
+  width: 100%;
+  background: #fff;
+}
+
+table.coverage thead {
+  background: #f6f8fa;
+}
+
+table.coverage thead td {
+  white-space: nowrap;
+  padding: 10px 14px 10px 10px;
+  border-bottom: 2px solid #d0d7de;
+  font-weight: 700;
+  color: #24292f;
+  font-size: 0.92em;
+}
+
+table.coverage thead td.bar {
+  border-left: 1px solid #eaeef2;
+}
+
+table.coverage thead td.ctr1 {
+  text-align: right;
+  border-left: 1px solid #eaeef2;
+}
+
+table.coverage thead td.ctr2 {
+  text-align: right;
+  padding-left: 2px;
+}
+
+table.coverage thead td.sortable {
+  cursor: pointer;
+  background-image: url(sort.gif);
+  background-position: right center;
+  background-repeat: no-repeat;
+}
+
+table.coverage thead td.up {
+  background-image: url(up.gif);
+}
+
+table.coverage thead td.down {
+  background-image: url(down.gif);
+}
+
+table.coverage tbody td {
+  white-space: nowrap;
+  padding: 8px 10px;
+  border-bottom: 1px solid #eaeef2;
+}
+
+table.coverage tbody tr:hover {
+  background: rgba(102, 126, 234, 0.04) !important;
+}
+
+table.coverage tbody td.bar {
+  border-left: 1px solid #eaeef2;
+}
+
+table.coverage tbody td.ctr1 {
+  text-align: right;
+  padding-right: 14px;
+  border-left: 1px solid #eaeef2;
+}
+
+table.coverage tbody td.ctr2 {
+  text-align: right;
+  padding-right: 14px;
+  padding-left: 2px;
+}
+
+table.coverage tfoot td {
+  white-space: nowrap;
+  padding: 8px 10px;
+  font-weight: 700;
+  background: #f6f8fa;
+  border-top: 2px solid #d0d7de;
+}
+
+table.coverage tfoot td.bar {
+  border-left: 1px solid #eaeef2;
+}
+
+table.coverage tfoot td.ctr1 {
+  text-align: right;
+  padding-right: 14px;
+  border-left: 1px solid #eaeef2;
+}
+
+table.coverage tfoot td.ctr2 {
+  text-align: right;
+  padding-right: 14px;
+  padding-left: 2px;
+}
+
+/* ===== Footer ===== */
+.footer {
+  margin-top: 24px;
+  border-top: 1px solid #d0d7de;
+  padding-top: 8px;
+  font-size: 8pt;
+  color: #8b949e;
+}
+
+.footer a {
+  color: #8b949e;
+}
+
+.footer a:hover {
+  color: #0969da;
+}
+
+.right {
+  float: right;
+}
diff --git a/src/site/markdown/advanced.md b/src/site/markdown/advanced.md
new file mode 100644
index 0000000000..5a2cafda37
--- /dev/null
+++ b/src/site/markdown/advanced.md
@@ -0,0 +1,1418 @@
+# Advanced Usage
+
+This guide covers advanced scenarios for extending and customizing your Copilot integration.
+
+## Table of Contents
+
+- [Custom Tools](#Custom_Tools)
+  - [Overriding Built-in Tools](#Overriding_Built-in_Tools)
+  - [Skipping Permission for Safe Tools](#Skipping_Permission_for_Safe_Tools)
+- [Switching Models Mid-Session](#Switching_Models_Mid-Session)
+- [System Messages](#System_Messages)
+  - [Adding Rules](#Adding_Rules)
+  - [Full Control](#Full_Control)
+  - [Fine-grained Customization](#Fine-grained_Customization)
+- [File Attachments](#File_Attachments)
+  - [Inline Blob Attachments](#Inline_Blob_Attachments)
+- [OpenTelemetry](#OpenTelemetry)
+- [Bring Your Own Key (BYOK)](#Bring_Your_Own_Key_BYOK)
+- [Infinite Sessions](#Infinite_Sessions)
+  - [Manual Compaction](#Manual_Compaction)
+  - [Compaction Events](#Compaction_Events)
+- [MCP Servers](#MCP_Servers)
+- [Custom Agents](#Custom_Agents)
+  - [Programmatic Agent Selection](#Programmatic_Agent_Selection)
+- [Skills Configuration](#Skills_Configuration)
+  - [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)
+- [Manual Server Control](#Manual_Server_Control)
+- [Session Context and Filtering](#Session_Context_and_Filtering)
+  - [Listing Sessions with Context](#Listing_Sessions_with_Context)
+  - [Filtering Sessions by Context](#Filtering_Sessions_by_Context)
+  - [Context Changed Events](#Context_Changed_Events)
+- [Session Lifecycle Events](#Session_Lifecycle_Events)
+  - [Subscribing to All Lifecycle Events](#Subscribing_to_All_Lifecycle_Events)
+  - [Subscribing to Specific Event Types](#Subscribing_to_Specific_Event_Types)
+- [Foreground Session Control (TUI+Server Mode)](#Foreground_Session_Control_TUIServer_Mode)
+  - [Getting the Foreground Session](#Getting_the_Foreground_Session)
+  - [Setting the Foreground Session](#Setting_the_Foreground_Session)
+- [Error Handling](#Error_Handling)
+  - [Event Handler Exceptions](#Event_Handler_Exceptions)
+  - [Custom Event Error Handler](#Custom_Event_Error_Handler)
+  - [Event Error Policy](#Event_Error_Policy)
+- [OpenTelemetry](#OpenTelemetry)
+- [Slash Commands](#Slash_Commands)
+  - [Registering Commands](#Registering_Commands)
+- [Elicitation (UI Dialogs)](#Elicitation_UI_Dialogs)
+  - [Incoming Elicitation Handler](#Incoming_Elicitation_Handler)
+  - [Session Capabilities](#Session_Capabilities)
+  - [Outgoing Elicitation via session.getUi()](#Outgoing_Elicitation_via_session.getUi)
+- [Mode Handlers](#Mode_Handlers)
+  - [Exit Plan Mode](#Exit_Plan_Mode)
+  - [Auto Mode Switch](#Auto_Mode_Switch)
+- [Getting Session Metadata by ID](#Getting_Session_Metadata_by_ID)
+
+---
+
+## Custom Tools
+
+Let the AI call back into your application to fetch data or perform actions.
+
+```java
+// Define strongly-typed arguments with a record
+record IssueArgs(String id) {}
+
+var lookupTool = ToolDefinition.create(
+    "lookup_issue",
+    "Fetch issue details from our tracker",
+    Map.of(
+        "type", "object",
+        "properties", Map.of(
+            "id", Map.of("type", "string", "description", "Issue identifier")
+        ),
+        "required", List.of("id")
+    ),
+    invocation -> {
+        IssueArgs args = invocation.getArgumentsAs(IssueArgs.class);
+        return CompletableFuture.completedFuture(fetchIssue(args.id()));
+    }
+);
+
+var session = client.createSession(
+    new SessionConfig().setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
+        .setTools(List.of(lookupTool))
+).get();
+```
+
+See [ToolDefinition](apidocs/com/github/copilot/rpc/ToolDefinition.html) Javadoc for schema details.
+
+### Overriding Built-in Tools
+
+You can replace a built-in CLI tool (such as `grep` or `read_file`) with your own implementation
+by using `ToolDefinition.createOverride()`. This signals to the CLI that the name collision is
+intentional and your custom implementation should be used instead.
+
+```java
+var customGrep = ToolDefinition.createOverride(
+    "grep",
+    "Project-aware search with custom filtering",
+    Map.of(
+        "type", "object",
+        "properties", Map.of(
+            "query", Map.of("type", "string", "description", "Search query")
+        ),
+        "required", List.of("query")
+    ),
+    invocation -> {
+        String query = (String) invocation.getArguments().get("query");
+        // Your custom search logic here
+        return CompletableFuture.completedFuture("Results for: " + query);
+    }
+);
+
+var session = client.createSession(
+    new SessionConfig()
+        .setTools(List.of(customGrep))
+        .setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
+).get();
+```
+
+### Skipping Permission for Safe Tools
+
+When a tool performs only read-only or non-destructive operations, you can mark it to skip the
+permission prompt entirely using `ToolDefinition.createSkipPermission()`:
+
+```java
+var safeLookup = ToolDefinition.createSkipPermission(
+    "safe_lookup",
+    "Look up a record by ID (read-only, no side effects)",
+    Map.of(
+        "type", "object",
+        "properties", Map.of(
+            "id", Map.of("type", "string")
+        ),
+        "required", List.of("id")
+    ),
+    invocation -> {
+        String id = (String) invocation.getArguments().get("id");
+        return CompletableFuture.completedFuture("Record: " + lookupRecord(id));
+    }
+);
+```
+
+The CLI bypasses the permission request for this tool invocation, so no `PermissionRequestedEvent`
+is emitted and the `onPermissionRequest` handler is not called.
+
+See [ToolDefinition](apidocs/com/github/copilot/rpc/ToolDefinition.html) Javadoc for details.
+
+---
+
+## Switching Models Mid-Session
+
+You can change the model used by an existing session without losing conversation history.
+The new model takes effect starting with the next message sent.
+
+```java
+var session = client.createSession(
+    new SessionConfig()
+        .setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
+).get();
+
+// Switch to a different model mid-conversation
+session.setModel("gpt-4.1").get();
+
+// Switch with a specific reasoning effort level
+session.setModel("claude-sonnet-4.6", "high").get();
+
+// Next message will use the new model
+session.sendAndWait(new MessageOptions().setPrompt("Continue with the new model")).get();
+```
+
+The `reasoningEffort` parameter accepts `"low"`, `"medium"`, `"high"`, or `"xhigh"` for models
+that support reasoning. Pass `null` (or use the single-argument overload) to use the default.
+
+The session emits a [`SessionModelChangeEvent`](apidocs/com/github/copilot/generated/SessionModelChangeEvent.html)
+when the switch completes, which you can observe with `session.on(SessionModelChangeEvent.class, event -> ...)`.
+
+See [CopilotSession.setModel()](apidocs/com/github/copilot/CopilotSession.html#setModel(java.lang.String)) Javadoc for details.
+
+---
+
+## System Messages
+
+Customize the AI's behavior by adding rules or replacing the default prompt.
+
+### Adding Rules
+
+Use `APPEND` mode to add constraints while keeping default guardrails:
+
+```java
+var session = client.createSession(
+    new SessionConfig().setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
+        .setSystemMessage(new SystemMessageConfig()
+            .setMode(SystemMessageMode.APPEND)
+            .setContent("""
+                <rules>
+                - Always check for security vulnerabilities
+                - Suggest performance improvements
+                </rules>
+            """))
+).get();
+```
+
+### Full Control
+
+Use `REPLACE` mode for complete control (removes default guardrails):
+
+```java
+var session = client.createSession(
+    new SessionConfig().setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
+        .setSystemMessage(new SystemMessageConfig()
+            .setMode(SystemMessageMode.REPLACE)
+            .setContent("You are a helpful coding assistant."))
+).get();
+```
+
+### Fine-grained Customization
+
+Use `CUSTOMIZE` mode to override individual sections of the default system prompt without
+replacing it entirely. You can replace, remove, append, prepend, or transform specific sections
+using the section identifiers from `SystemPromptSections`.
+
+**Static overrides:**
+
+```java
+var session = client.createSession(
+    new SessionConfig().setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
+        .setSystemMessage(new SystemMessageConfig()
+            .setMode(SystemMessageMode.CUSTOMIZE)
+            .setSections(Map.of(
+                // Replace the tone section
+                SystemPromptSections.TONE,
+                    new SectionOverride()
+                        .setAction(SectionOverrideAction.REPLACE)
+                        .setContent("Be concise and formal in all responses."),
+                // Remove the code-change-rules section entirely
+                SystemPromptSections.CODE_CHANGE_RULES,
+                    new SectionOverride()
+                        .setAction(SectionOverrideAction.REMOVE)
+            ))
+            // Optional: extra content appended after all sections
+            .setContent("Always mention quarterly earnings."))
+).get();
+```
+
+**Transform callbacks** let you inspect and modify section content at runtime:
+
+```java
+var session = client.createSession(
+    new SessionConfig().setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
+        .setSystemMessage(new SystemMessageConfig()
+            .setMode(SystemMessageMode.CUSTOMIZE)
+            .setSections(Map.of(
+                SystemPromptSections.IDENTITY,
+                    new SectionOverride()
+                        .setTransform(content ->
+                            CompletableFuture.completedFuture(
+                                content + "\nAlways end your reply with DONE."))
+            )))
+).get();
+```
+
+See [SystemMessageConfig](apidocs/com/github/copilot/rpc/SystemMessageConfig.html),
+[SectionOverride](apidocs/com/github/copilot/rpc/SectionOverride.html), and
+[SystemPromptSections](apidocs/com/github/copilot/rpc/SystemPromptSections.html) Javadoc for details.
+
+---
+
+## File Attachments
+
+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()
+    .setPrompt("Review this file for bugs")
+    .setAttachments(List.of(
+        new Attachment("file", "/path/to/file.java", "MyService.java")
+    ))
+).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();
+```
+
+### Inline Blob Attachments
+
+Use `BlobAttachment` to pass inline base64-encoded binary data — for example, an image captured
+at runtime — without writing it to disk first:
+
+```java
+// Load image bytes and base64-encode them
+byte[] imageBytes = Files.readAllBytes(Path.of("/path/to/screenshot.png"));
+String base64Data = Base64.getEncoder().encodeToString(imageBytes);
+
+session.send(new MessageOptions()
+    .setPrompt("Describe this screenshot")
+    .setAttachments(List.of(
+        new BlobAttachment()
+            .setData(base64Data)
+            .setMimeType("image/png")
+            .setDisplayName("screenshot.png")
+    ))
+).get();
+```
+
+See [BlobAttachment](apidocs/com/github/copilot/rpc/BlobAttachment.html) Javadoc for details.
+
+Both `Attachment` and `BlobAttachment` implement the sealed `MessageAttachment` interface.
+For a mixed list with both types, use an explicit type hint:
+
+```java
+session.send(new MessageOptions()
+    .setPrompt("Analyze these")
+    .setAttachments(List.<MessageAttachment>of(
+        new Attachment("file", "/path/to/file.java", "Source"),
+        new BlobAttachment()
+            .setData(base64Data)
+            .setMimeType("image/png")
+            .setDisplayName("screenshot.png")
+    ))
+).get();
+```
+
+---
+
+## Bring Your Own Key (BYOK)
+
+Use your own OpenAI or Azure OpenAI API key instead of GitHub Copilot.
+
+Supported providers:
+
+| Provider | Type value | Notes |
+|----------|-----------|-------|
+| OpenAI | `"openai"` | Standard OpenAI API |
+| Azure OpenAI / Azure AI Foundry | `"azure"` | Azure-hosted models |
+| Anthropic | `"anthropic"` | Claude models |
+| Ollama | `"openai"` | Local models via OpenAI-compatible API |
+| Microsoft Foundry Local | `"openai"` | Run AI models locally on your device via OpenAI-compatible API |
+| Other OpenAI-compatible | `"openai"` | vLLM, LiteLLM, etc. |
+
+### API Key Authentication
+
+```java
+var session = client.createSession(
+    new SessionConfig().setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
+        .setProvider(new ProviderConfig()
+            .setType("openai")
+            .setBaseUrl("https://api.openai.com/v1")
+            .setApiKey("sk-..."))
+).get();
+```
+
+### Bearer Token Authentication
+
+Some providers require bearer token authentication instead of API keys:
+
+```java
+var session = client.createSession(
+    new SessionConfig().setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
+        .setProvider(new ProviderConfig()
+            .setType("openai")
+            .setBaseUrl("https://my-custom-endpoint.example.com/v1")
+            .setBearerToken(System.getenv("MY_BEARER_TOKEN")))
+).get();
+```
+
+> **Note:** The `bearerToken` option accepts a **static token string** only. The SDK does not refresh this token automatically. If your token expires, requests will fail and you'll need to create a new session with a fresh token.
+
+### Model Overrides
+
+Use `modelId` and `wireModel` to control model resolution and the model name on the wire:
+
+```java
+var session = client.createSession(
+    new SessionConfig().setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
+        .setProvider(new ProviderConfig()
+            .setType("openai")
+            .setBaseUrl("https://api.openai.com/v1")
+            .setApiKey("sk-...")
+            .setModelId("gpt-4o")           // Runtime config lookup
+            .setWireModel("my-finetune-v3") // Sent to the provider API
+            .setMaxPromptTokens(100_000)    // Override max prompt tokens
+            .setMaxOutputTokens(4096))      // Override max output tokens
+).get();
+```
+
+- **`modelId`** — Well-known model name used by the runtime to look up agent configuration (tools, prompts, reasoning behavior) and default token limits. Also used as the wire model when `wireModel` is not set.
+- **`wireModel`** — Model name sent to the provider API for inference. Use when the provider's model name (e.g., an Azure deployment name or a custom fine-tune name) differs from `modelId`.
+- **`maxPromptTokens`** — Overrides the resolved model's default max prompt tokens. The runtime triggers conversation compaction when the prompt would exceed this limit.
+- **`maxOutputTokens`** — Overrides the resolved model's default max output tokens.
+
+### Microsoft Foundry Local
+
+[Microsoft Foundry Local](https://foundrylocal.ai) lets you run AI models locally on your own device with an OpenAI-compatible API. Install it via the Foundry Local CLI, then point the SDK at your local endpoint:
+
+```java
+var session = client.createSession(
+    new SessionConfig().setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
+        .setProvider(new ProviderConfig()
+            .setType("openai")
+            .setBaseUrl("http://localhost:<PORT>/v1"))
+            // No apiKey needed for local Foundry Local
+).get();
+```
+
+> **Note:** Foundry Local starts on a **dynamic port** — the port is not fixed. Use `foundry service status` to confirm the port the service is currently listening on, then use that port in your `baseUrl`.
+
+To get started with Foundry Local:
+
+```bash
+# Windows: Install Foundry Local CLI (requires winget)
+winget install Microsoft.FoundryLocal
+
+# macOS / Linux: see https://foundrylocal.ai for installation instructions
+
+# List available models
+foundry model list
+
+# Run a model (starts the local server automatically)
+foundry model run phi-4-mini
+
+# Check the port the service is running on
+foundry service status
+```
+
+### Limitations
+
+When using BYOK, be aware of these limitations:
+
+#### Identity Limitations
+
+BYOK authentication uses **static credentials only**. The following identity providers are NOT supported:
+
+- ❌ **Microsoft Entra ID (Azure AD)** - No support for Entra managed identities or service principals
+- ❌ **Third-party identity providers** - No OIDC, SAML, or other federated identity
+- ❌ **Managed identities** - Azure Managed Identity is not supported
+
+You must use an API key or static bearer token that you manage yourself.
+
+**Why not Entra ID?** While Entra ID does issue bearer tokens, these tokens are short-lived (typically 1 hour) and require automatic refresh via the Azure Identity SDK. The `bearerToken` option only accepts a static string—there is no callback mechanism for the SDK to request fresh tokens. For long-running workloads requiring Entra authentication, you would need to implement your own token refresh logic and create new sessions with updated tokens.
+
+---
+
+## Infinite Sessions
+
+Run long conversations without hitting context limits.
+
+When enabled (default), the session automatically compacts older messages as the context window fills up.
+
+```java
+var session = client.createSession(
+    new SessionConfig().setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
+        .setInfiniteSessions(new InfiniteSessionConfig()
+            .setEnabled(true)
+            .setBackgroundCompactionThreshold(0.80)  // Start compacting at 80%
+            .setBufferExhaustionThreshold(0.95))     // Block at 95%
+).get();
+
+// Access the workspace where session state is persisted
+var workspace = session.getWorkspacePath();
+```
+
+### Manual Compaction
+
+Trigger compaction immediately when you want to reduce context usage before the automatic threshold is reached:
+
+```java
+session.compact().get();
+```
+
+### Compaction Events
+
+When compaction occurs, the session emits events that you can listen for:
+
+```java
+session.on(SessionCompactionStartEvent.class, start -> {
+    System.out.println("Compaction started");
+});
+session.on(SessionCompactionCompleteEvent.class, complete -> {
+    var data = complete.getData();
+    System.out.println("Compaction completed - success: " + data.success() 
+        + ", tokens removed: " + data.tokensRemoved());
+});
+```
+
+For short conversations, disable to avoid overhead:
+
+```java
+new InfiniteSessionConfig().setEnabled(false)
+```
+
+---
+
+## MCP Servers
+
+Extend the AI with external tools via the Model Context Protocol.
+
+```java
+Map<String, Object> server = Map.of(
+    "type", "local",
+    "command", "npx",
+    "args", List.of("-y", "@modelcontextprotocol/server-filesystem", "/tmp"),
+    "tools", List.of("*")
+);
+
+var session = client.createSession(
+    new SessionConfig().setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
+        .setMcpServers(Map.of("filesystem", server))
+).get();
+```
+
+📖 **[Full MCP documentation →](mcp.html)** for local/remote servers and all options.
+
+---
+
+## Custom Agents
+
+Extend the base Copilot assistant with specialized agents that have their own tools, prompts, and behavior. Users can invoke agents using the `@agent-name` mention syntax in messages.
+
+```java
+var reviewer = new CustomAgentConfig()
+    .setName("code-reviewer")
+    .setDisplayName("Code Reviewer")
+    .setDescription("Reviews code for best practices and security")
+    .setPrompt("You are a code review expert. Focus on security, performance, and maintainability.")
+    .setTools(List.of("read_file", "search_code"));
+
+var session = client.createSession(
+    new SessionConfig().setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
+        .setCustomAgents(List.of(reviewer))
+).get();
+
+// The user can now mention @code-reviewer in messages
+session.send("@code-reviewer Review src/Main.java").get();
+```
+
+### Configuration Options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `name` | String | Unique identifier used for `@mentions` (alphanumeric and hyphens) |
+| `displayName` | String | Human-readable name shown to users |
+| `description` | String | Describes the agent's capabilities |
+| `prompt` | String | System prompt that defines the agent's behavior |
+| `tools` | List&lt;String&gt; | Tool names available to this agent |
+| `mcpServers` | Map | MCP servers available to this agent |
+| `infer` | Boolean | Whether the agent can be auto-selected based on context |
+| `skills` | List&lt;String&gt; | Skill names to preload into the agent's context |
+| `model` | String | Model identifier for this agent (e.g., "claude-haiku-4.5"); falls back to the parent session model if unavailable |
+
+### Multiple Agents
+
+Register multiple agents for different tasks:
+
+```java
+var agents = List.of(
+    new CustomAgentConfig()
+        .setName("reviewer")
+        .setDescription("Code review")
+        .setPrompt("You review code for issues."),
+    new CustomAgentConfig()
+        .setName("documenter")
+        .setDescription("Documentation writer")
+        .setPrompt("You write clear documentation.")
+        .setInfer(true)  // Auto-select when appropriate
+);
+
+var session = client.createSession(
+    new SessionConfig().setOnPermissionRequest(PermissionHandler.APPROVE_ALL).setCustomAgents(agents)
+).get();
+```
+
+See [CustomAgentConfig](apidocs/com/github/copilot/rpc/CustomAgentConfig.html) Javadoc for full details.
+
+### Programmatic Agent Selection
+
+You can inspect and switch agents at runtime:
+
+```java
+var available = session.listAgents().get();
+
+var current = session.getCurrentAgent().get();
+if (current != null) {
+    System.out.println("Current agent: " + current.name());
+}
+
+var selected = session.selectAgent("reviewer").get();
+System.out.println("Selected: " + selected.name());
+
+session.deselectAgent().get(); // Return to the default agent
+```
+
+---
+
+## Skills Configuration
+
+Load custom skills from directories to extend the AI's capabilities with domain-specific knowledge.
+
+### Loading Skills
+
+Skills are loaded from `SKILL.md` files in subdirectories of the specified skill directories:
+
+```java
+var session = client.createSession(
+    new SessionConfig().setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
+        .setSkillDirectories(List.of("/path/to/skills"))
+).get();
+```
+
+Each skill subdirectory should contain a `SKILL.md` file with YAML frontmatter:
+
+```markdown
+---
+name: my-skill
+description: A skill that provides domain-specific knowledge
+---
+
+# Skill Instructions
+
+Your skill instructions go here...
+```
+
+### Disabling Skills
+
+Disable specific skills by name:
+
+```java
+var session = client.createSession(
+    new SessionConfig().setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
+        .setSkillDirectories(List.of("/path/to/skills"))
+        .setDisabledSkills(List.of("my-skill"))
+).get();
+```
+
+---
+
+## Instruction Directories
+
+Provide additional directories containing custom instruction files. These instructions are automatically included in the system message for all conversations in the session.
+
+```java
+var session = client.createSession(
+    new SessionConfig().setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
+        .setInstructionDirectories(List.of("/path/to/instructions"))
+).get();
+```
+
+Instruction files are discovered from `.github/instructions/` subdirectories within each specified path and should use the `.instructions.md` extension.
+
+This is also supported on session resume:
+
+```java
+var session = client.resumeSession(sessionId,
+    new ResumeSessionConfig()
+        .setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
+        .setInstructionDirectories(List.of("/path/to/instructions"))
+);
+```
+
+---
+
+## Custom Configuration Directory
+
+Use a custom configuration directory for session settings:
+
+```java
+var session = client.createSession(
+    new SessionConfig().setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
+        .setConfigDir("/path/to/custom/config")
+).get();
+```
+
+This is useful when you need to isolate session configuration or use different settings for different environments.
+
+---
+
+## 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/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<SessionEvent>();
+
+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.
+
+```java
+var session = client.createSession(
+    new SessionConfig().setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
+        .setOnUserInputRequest((request, invocation) -> {
+            System.out.println("Agent asks: " + request.getQuestion());
+            
+            // Check if choices are provided
+            if (request.getChoices() != null && !request.getChoices().isEmpty()) {
+                System.out.println("Options: " + request.getChoices());
+                // Return one of the provided choices
+                var selectedChoice = request.getChoices().get(0);
+                return CompletableFuture.completedFuture(
+                    new UserInputResponse()
+                        .setAnswer(selectedChoice)
+                        .setWasFreeform(false)
+                );
+            }
+            
+            // Freeform input
+            var userAnswer = getUserInput(); // your input method
+            return CompletableFuture.completedFuture(
+                new UserInputResponse()
+                    .setAnswer(userAnswer)
+                    .setWasFreeform(true)
+            );
+        })
+).get();
+```
+
+The `UserInputRequest` contains:
+- `getQuestion()` - The question the AI is asking
+- `getChoices()` - Optional list of choices for the user to select from
+
+The `UserInputResponse` should include:
+- `setAnswer(String)` - The user's answer
+- `setWasFreeform(boolean)` - `true` if the answer was freeform text, `false` if it was from the provided choices
+
+See [UserInputHandler](apidocs/com/github/copilot/rpc/UserInputHandler.html) Javadoc for more details.
+
+---
+
+## Permission Handling
+
+Approve or deny permission requests from the AI.
+
+```java
+var session = client.createSession(
+    new SessionConfig().setOnPermissionRequest((request, invocation) -> {
+        // Inspect request and approve/deny using typed constants
+        var result = new PermissionRequestResult();
+        result.setKind(PermissionRequestResultKind.APPROVED);
+        return CompletableFuture.completedFuture(result);
+    })
+).get();
+```
+
+The `PermissionRequestResultKind` class provides well-known constants for common outcomes:
+
+| Constant | Value | Meaning |
+|---|---|---|
+| `PermissionRequestResultKind.APPROVED` | `"approve-once"` | The permission was approved for this one instance |
+| `PermissionRequestResultKind.REJECTED` | `"reject"` | The permission was denied interactively by the user |
+| `PermissionRequestResultKind.USER_NOT_AVAILABLE` | `"user-not-available"` | Denied because user confirmation was unavailable |
+| `PermissionRequestResultKind.NO_RESULT` | `"no-result"` | No permission decision was made (protocol v3 only) |
+
+You can also pass a raw string to `setKind(String)` for custom or extension values. Use
+[`PermissionHandler.APPROVE_ALL`](apidocs/com/github/copilot/rpc/PermissionHandler.html) to approve all
+requests without writing a handler.
+
+---
+
+## Session Hooks
+
+Intercept tool execution and session lifecycle events using hooks.
+
+```java
+var hooks = new SessionHooks()
+    .setOnPreToolUse((input, invocation) -> {
+        System.out.println("Tool: " + input.getToolName());
+        return CompletableFuture.completedFuture(PreToolUseHookOutput.allow());
+    })
+    .setOnPreMcpToolCall((input, invocation) -> {
+        System.out.println("MCP Tool: " + input.getServerName() + "/" + input.getToolName());
+        // Set metadata on the MCP request
+        JsonNode meta = mapper.valueToTree(Map.of("source", "my-app"));
+        return CompletableFuture.completedFuture(PreMcpToolCallHookOutput.withMeta(meta));
+    })
+    .setOnPostToolUse((input, invocation) -> {
+        System.out.println("Result: " + input.getToolResult());
+        return CompletableFuture.completedFuture(null);
+    });
+
+var session = client.createSession(
+    new SessionConfig().setOnPermissionRequest(PermissionHandler.APPROVE_ALL).setHooks(hooks)
+).get();
+```
+
+📖 **[Full Session Hooks documentation →](hooks.html)** for all 6 hook types, inputs/outputs, and examples.
+
+---
+
+## Manual Server Control
+
+Control the CLI lifecycle yourself instead of auto-start.
+
+```java
+var client = new CopilotClient(
+    new CopilotClientOptions().setAutoStart(false)
+);
+
+client.start().get();   // Start manually
+// ... use client ...
+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 session cleanup happens automatically.
+> `close()` is blocking and waits up to `CopilotClient.AUTOCLOSEABLE_TIMEOUT_SECONDS` seconds for shutdown to complete.
+
+---
+
+## Session Context and Filtering
+
+Track and filter sessions by their working directory context including the current directory, git repository, and branch information.
+
+### Listing Sessions with Context
+
+Session metadata may include context information for persisted sessions:
+
+```java
+var sessions = client.listSessions().get();
+for (var session : sessions) {
+    var context = session.getContext();
+    if (context != null) {
+        System.out.println("Session: " + session.getSessionId());
+        System.out.println("  Working dir: " + context.getCwd());
+        System.out.println("  Repository: " + context.getRepository());
+        System.out.println("  Branch: " + context.getBranch());
+        System.out.println("  Git root: " + context.getGitRoot());
+    }
+}
+```
+
+### Filtering Sessions by Context
+
+Use `SessionListFilter` to filter sessions by context fields:
+
+```java
+// Find sessions for a specific repository
+var filter = new SessionListFilter()
+    .setRepository("owner/myproject")
+    .setBranch("main");
+
+var sessions = client.listSessions(filter).get();
+```
+
+Filter options:
+- `setCwd(String)` - Filter by exact working directory match
+- `setGitRoot(String)` - Filter by git repository root
+- `setRepository(String)` - Filter by repository in "owner/repo" format
+- `setBranch(String)` - Filter by git branch name
+
+### Context Changed Events
+
+Listen for changes to the working directory context:
+
+```java
+session.on(SessionContextChangedEvent.class, event -> {
+    var newContext = event.getData();
+    System.out.println("Context changed:");
+    System.out.println("  New CWD: " + newContext.getCwd());
+    System.out.println("  Repository: " + newContext.getRepository());
+    System.out.println("  Branch: " + newContext.getBranch());
+});
+```
+
+The `session.context_changed` event fires when the working directory context changes between conversation turns.
+
+---
+
+## Session Lifecycle Events
+
+Subscribe to lifecycle events to be notified when sessions are created, deleted, updated, or change foreground/background state.
+
+### Subscribing to All Lifecycle Events
+
+```java
+var subscription = client.onLifecycle(event -> {
+    System.out.println("Session " + event.getSessionId() + ": " + event.getType());
+    
+    if (event.getMetadata() != null) {
+        System.out.println("  Summary: " + event.getMetadata().getSummary());
+    }
+});
+
+// Later, when done listening:
+subscription.close();
+```
+
+### Subscribing to Specific Event Types
+
+```java
+import com.github.copilot.rpc.SessionLifecycleEventTypes;
+
+// Listen only for session creation
+var subscription = client.onLifecycle(
+    SessionLifecycleEventTypes.CREATED,
+    event -> System.out.println("New session: " + event.getSessionId())
+);
+```
+
+Available event types:
+- `SessionLifecycleEventTypes.CREATED` - Session was created
+- `SessionLifecycleEventTypes.DELETED` - Session was deleted
+- `SessionLifecycleEventTypes.UPDATED` - Session was updated
+- `SessionLifecycleEventTypes.FOREGROUND` - Session moved to foreground (TUI+server mode)
+- `SessionLifecycleEventTypes.BACKGROUND` - Session moved to background (TUI+server mode)
+
+---
+
+## Foreground Session Control (TUI+Server Mode)
+
+When connecting to a server running in TUI+server mode (`--ui-server`), you can control which session is displayed in the TUI.
+
+### Getting the Foreground Session
+
+```java
+var sessionId = client.getForegroundSessionId().get();
+if (sessionId != null) {
+    System.out.println("TUI is displaying session: " + sessionId);
+}
+```
+
+### Setting the Foreground Session
+
+```java
+client.setForegroundSessionId("session-123").get();
+```
+
+---
+
+## Error Handling
+
+All SDK methods return `CompletableFuture`. Errors surface via `ExecutionException`:
+
+```java
+try {
+    session.send(new MessageOptions().setPrompt("Hello")).get();
+} catch (ExecutionException ex) {
+    System.err.println("Error: " + ex.getCause().getMessage());
+}
+```
+
+For reactive error handling, use `exceptionally()` or `handle()`:
+
+```java
+session.send(new MessageOptions().setPrompt("Hello"))
+    .exceptionally(ex -> {
+        System.err.println("Failed: " + ex.getMessage());
+        return null;
+    });
+```
+
+### Event Handler Exceptions
+
+If an event handler registered via `session.on()` throws an exception, the SDK
+catches it and logs it at `WARNING` level. By default, dispatch **stops** after
+the first handler error (`PROPAGATE_AND_LOG_ERRORS` policy). You can opt in to
+continue dispatching despite errors using `SUPPRESS_AND_LOG_ERRORS`:
+
+```java
+// With SUPPRESS_AND_LOG_ERRORS, second handler still runs
+session.setEventErrorPolicy(EventErrorPolicy.SUPPRESS_AND_LOG_ERRORS);
+
+session.on(AssistantMessageEvent.class, msg -> {
+    throw new RuntimeException("bug in handler 1");
+});
+
+session.on(AssistantMessageEvent.class, msg -> {
+    // This handler executes normally despite the exception above
+    System.out.println(msg.getData().content());
+});
+```
+
+Errors are **always logged** at `WARNING` level regardless of the policy or
+whether a custom error handler is set.
+
+### Custom Event Error Handler
+
+Set a custom `EventErrorHandler` for additional handling beyond the default
+logging — such as metrics, alerts, or integration with external
+error-reporting systems:
+
+```java
+session.setEventErrorHandler((event, exception) -> {
+    metrics.increment("handler.errors");
+    logger.error("Handler failed on {}: {}",
+        event.getType(), exception.getMessage());
+});
+```
+
+The error handler receives both the event that was being dispatched and the
+exception that was thrown. If the error handler itself throws, that exception
+is caught and logged at `SEVERE`, and dispatch is stopped to prevent cascading
+failures.
+
+Pass `null` to use only the default logging behavior:
+
+```java
+session.setEventErrorHandler(null);
+```
+
+### Event Error Policy
+
+By default, the SDK propagates errors and stops dispatch on the first handler
+error (`EventErrorPolicy.PROPAGATE_AND_LOG_ERRORS`). You can opt in to
+**suppress** errors so that all handlers execute despite errors:
+
+```java
+session.setEventErrorPolicy(EventErrorPolicy.SUPPRESS_AND_LOG_ERRORS);
+```
+
+The `EventErrorHandler` (if set) is always invoked regardless of the policy —
+the policy only controls whether remaining handlers execute after the error
+handler returns. Errors are always logged at `WARNING` level.
+
+| Policy | Behavior |
+|---|---|
+| `PROPAGATE_AND_LOG_ERRORS` (default) | Log the error; dispatch halts after the first error |
+| `SUPPRESS_AND_LOG_ERRORS` | Log the error; all remaining handlers execute |
+
+You can combine both for full control:
+
+```java
+// Log errors via custom handler and suppress (continue dispatching)
+session.setEventErrorPolicy(EventErrorPolicy.SUPPRESS_AND_LOG_ERRORS);
+session.setEventErrorHandler((event, ex) ->
+    logger.error("Handler failed, continuing: {}", ex.getMessage(), ex));
+```
+
+Or switch policies dynamically:
+
+```java
+// Start strict (propagate errors, stop dispatch)
+session.setEventErrorPolicy(EventErrorPolicy.PROPAGATE_AND_LOG_ERRORS);
+
+// Later, switch to lenient mode (suppress errors, continue)
+session.setEventErrorPolicy(EventErrorPolicy.SUPPRESS_AND_LOG_ERRORS);
+```
+
+See [EventErrorPolicy](apidocs/com/github/copilot/EventErrorPolicy.html) and [EventErrorHandler](apidocs/com/github/copilot/EventErrorHandler.html) Javadoc for details.
+
+---
+
+## OpenTelemetry
+
+Enable OpenTelemetry tracing in the Copilot CLI server by configuring a `TelemetryConfig`
+on the `CopilotClientOptions`. This is useful for observability, performance monitoring,
+and debugging.
+
+```java
+var options = new CopilotClientOptions()
+    .setTelemetry(new TelemetryConfig()
+        .setOtlpEndpoint("http://localhost:4318")  // OTLP/HTTP exporter
+        .setSourceName("my-app"));
+
+var client = new CopilotClient(options);
+```
+
+To export to a local file instead:
+
+```java
+var options = new CopilotClientOptions()
+    .setTelemetry(new TelemetryConfig()
+        .setExporterType("file")
+        .setFilePath("/tmp/copilot-traces.json")
+        .setCaptureContent(true));  // include message content in spans
+```
+
+| Property | Environment Variable | Description |
+|----------|---------------------|-------------|
+| `otlpEndpoint` | `OTEL_EXPORTER_OTLP_ENDPOINT` | OTLP exporter endpoint URL |
+| `filePath` | `COPILOT_OTEL_FILE_EXPORTER_PATH` | File path for the file exporter |
+| `exporterType` | `COPILOT_OTEL_EXPORTER_TYPE` | `"otlp-http"` or `"file"` |
+| `sourceName` | `COPILOT_OTEL_SOURCE_NAME` | Source name for telemetry spans |
+| `captureContent` | `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT` | Whether to capture message content |
+
+See [TelemetryConfig](apidocs/com/github/copilot/rpc/TelemetryConfig.html) Javadoc for details.
+
+---
+
+## Slash Commands
+
+Register custom slash commands that users can invoke from the CLI TUI with `/commandname`.
+
+### Registering Commands
+
+```java
+var config = new SessionConfig()
+    .setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
+    .setCommands(List.of(
+        new CommandDefinition()
+            .setName("deploy")
+            .setDescription("Deploy the current branch")
+            .setHandler(context -> {
+                System.out.println("Deploying with args: " + context.getArgs());
+                // perform deployment ...
+                return CompletableFuture.completedFuture(null);
+            }),
+        new CommandDefinition()
+            .setName("rollback")
+            .setDescription("Roll back the last deployment")
+            .setHandler(context -> {
+                // perform rollback ...
+                return CompletableFuture.completedFuture(null);
+            })
+    ));
+
+try (CopilotClient client = new CopilotClient()) {
+    client.start().get();
+    var session = client.createSession(config).get();
+    // Users can now type /deploy or /rollback in the TUI
+}
+```
+
+Each `CommandDefinition` requires a `name` (without the leading `/`), an optional `description` shown in the TUI's command completion UI, and a `CommandHandler` that is invoked when the user executes the command.
+
+The `CommandContext` passed to the handler provides:
+- `getSessionId()` — the ID of the session where the command was invoked
+- `getCommand()` — the full command text (e.g., `/deploy production`)
+- `getCommandName()` — command name without the leading `/` (e.g., `deploy`)
+- `getArgs()` — the argument string after the command name (e.g., `production`)
+
+---
+
+## Elicitation (UI Dialogs)
+
+Elicitation allows your application to present structured UI dialogs to the user. There are two directions:
+
+1. **Incoming** — The server or an MCP tool requests input from the user via your `onElicitationRequest` handler.
+2. **Outgoing** — Your session-side code proactively requests input via `session.getUi()`.
+
+### Incoming Elicitation Handler
+
+Register a handler to receive elicitation requests from the server:
+
+```java
+var config = new SessionConfig()
+    .setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
+    .setOnElicitationRequest(context -> {
+        System.out.println("Elicitation request: " + context.getMessage());
+        // Show the form to the user ...
+        var content = Map.of("confirmed", true);
+        return CompletableFuture.completedFuture(
+            new ElicitationResult()
+                .setAction(ElicitationResultAction.ACCEPT)
+                .setContent(content)
+        );
+    });
+```
+
+When `onElicitationRequest` is set, the SDK reports elicitation as a supported capability and the server will route elicitation requests to your handler.
+
+### Session Capabilities
+
+After `createSession` or `resumeSession`, check `session.getCapabilities()` to see what the host supports:
+
+```java
+var session = client.createSession(config).get();
+
+var caps = session.getCapabilities();
+if (caps.getUi() != null && Boolean.TRUE.equals(caps.getUi().getElicitation())) {
+    System.out.println("Elicitation is supported");
+}
+```
+
+Capabilities are updated in real time when a `capabilities.changed` event is received.
+
+### Outgoing Elicitation via `session.getUi()`
+
+If the host reports elicitation support, you can call the convenience methods on `session.getUi()`:
+
+```java
+var ui = session.getUi();
+
+// Boolean confirmation
+boolean confirmed = ui.confirm("Are you sure you want to proceed?").get();
+
+// Selection from options
+String choice = ui.select("Choose an environment", new String[]{"dev", "staging", "prod"}).get();
+
+// Text input
+String value = ui.input("Enter your name", null).get();
+
+// Custom schema
+var result = ui.elicitation(new ElicitationParams()
+    .setMessage("Enter deployment details")
+    .setRequestedSchema(new ElicitationSchema()
+        .setProperties(Map.of(
+            "branch", Map.of("type", "string"),
+            "environment", Map.of("type", "string", "enum", List.of("dev", "staging", "prod"))
+        ))
+        .setRequired(List.of("branch", "environment"))
+    )).get();
+```
+
+All `getUi()` methods throw `IllegalStateException` if the host does not support elicitation. Always check capabilities first.
+
+---
+
+## Mode Handlers
+
+Mode handlers let your application respond to mode transitions requested by the Copilot CLI.
+
+### Exit Plan Mode
+
+When the model finishes creating a plan and wants to transition out of plan mode, it invokes the `exitPlanMode` handler. Register the handler via `SessionConfig.setOnExitPlanMode()`:
+
+```java
+var session = client.createSession(new SessionConfig()
+    .setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
+    .setOnExitPlanMode((request, invocation) -> {
+        System.out.println("Plan summary: " + request.getSummary());
+        System.out.println("Available actions: " + request.getActions());
+        System.out.println("Recommended: " + request.getRecommendedAction());
+
+        return CompletableFuture.completedFuture(
+            new ExitPlanModeResult()
+                .setApproved(true)
+                .setSelectedAction("interactive")
+                .setFeedback("Looks good, proceed!"));
+    })).get();
+```
+
+When no handler is registered, the SDK automatically approves the plan (`approved=true`). The handler receives an `ExitPlanModeRequest` with:
+
+| Field               | Description                                     |
+|---------------------|-------------------------------------------------|
+| `summary`           | Summary of the plan that was created            |
+| `planContent`       | Full content of the plan file                   |
+| `actions`           | Available actions (e.g., interactive, autopilot) |
+| `recommendedAction` | The recommended action for the user             |
+
+### Auto Mode Switch
+
+When the model encounters a rate limit or similar constraint, it may request to switch modes automatically. Register the handler via `SessionConfig.setOnAutoModeSwitch()`:
+
+```java
+var session = client.createSession(new SessionConfig()
+    .setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
+    .setOnAutoModeSwitch((request, invocation) -> {
+        System.out.println("Error: " + request.getErrorCode());
+        System.out.println("Retry after: " + request.getRetryAfterSeconds() + "s");
+
+        return CompletableFuture.completedFuture(AutoModeSwitchResponse.YES);
+    })).get();
+```
+
+When no handler is registered, the SDK returns `NO` (declining the mode switch). The response options are:
+
+| Response                        | Description                              |
+|---------------------------------|------------------------------------------|
+| `AutoModeSwitchResponse.YES`       | Allow the mode switch this time          |
+| `AutoModeSwitchResponse.YES_ALWAYS`| Always allow automatic mode switches     |
+| `AutoModeSwitchResponse.NO`        | Decline the mode switch                  |
+
+Both handlers are also available on `ResumeSessionConfig` for resumed sessions.
+
+---
+
+## Getting Session Metadata by ID
+
+Retrieve metadata for a specific session without listing all sessions:
+
+```java
+SessionMetadata metadata = client.getSessionMetadata("session-123").get();
+if (metadata != null) {
+    System.out.println("Session: " + metadata.getSessionId());
+    System.out.println("Started: " + metadata.getStartTime());
+} else {
+    System.out.println("Session not found");
+}
+```
+
+This is more efficient than `listSessions()` when you already know the session ID, as it performs a direct O(1) lookup instead of scanning all sessions.
+
+---
+
+## Remote Sessions
+
+Remote sessions enable Mission Control integration, making sessions accessible from GitHub web and mobile. When enabled, sessions in a GitHub repository working directory receive a remote URL.
+
+### Enabling Remote Sessions
+
+Set `remote(true)` on the client options to enable remote session support for all sessions:
+
+```java
+var options = new CopilotClientOptions()
+    .setRemote(true)
+    .setCwd("/path/to/github-repo");
+
+try (var client = new CopilotClient(options)) {
+    var session = client.createSession(
+        new SessionConfig().setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
+    ).get();
+
+    // Listen for the remote URL info event
+    session.on(SessionInfoEvent.class, event -> {
+        System.out.println("Remote URL: " + event.getData());
+    });
+}
+```
+
+### Prerequisites
+
+- The user must be authenticated (GitHub token or logged-in user)
+- The session's working directory must be a GitHub repository
+- This option is only used when the SDK spawns the CLI process; it is ignored when connecting to an external server via `setCliUrl()`
+
+### Cloud Sessions
+
+Cloud sessions create a remote session in the cloud instead of a local session. Optionally associate repository metadata with the cloud session:
+
+```java
+var cloudOptions = new CloudSessionOptions()
+    .setRepository(new CloudSessionRepository()
+        .setOwner("my-org")
+        .setName("my-repo")
+        .setBranch("main"));
+
+var session = client.createSession(
+    new SessionConfig()
+        .setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
+        .setCloud(cloudOptions)
+).get();
+```
+
+See [CloudSessionOptions](apidocs/com/github/copilot/rpc/CloudSessionOptions.html) and [CloudSessionRepository](apidocs/com/github/copilot/rpc/CloudSessionRepository.html) Javadoc for details.
+
+---
+
+## Next Steps
+
+- 📖 **[Documentation](documentation.html)** - Core concepts, events, streaming, models, tool filtering, reasoning effort
+- 📖 **[Session Hooks](hooks.html)** - All 6 hook types with inputs, outputs, and examples
+- 📖 **[MCP Servers](mcp.html)** - Local and remote MCP server integration
+- 📖 **[Setup & Deployment](setup.html)** - OAuth, backend services, scaling, configuration reference
+- 📖 **[API Javadoc](apidocs/index.html)** - Complete API reference
diff --git a/src/site/markdown/cookbook/README.md b/src/site/markdown/cookbook/README.md
new file mode 100644
index 0000000000..0b51c03776
--- /dev/null
+++ b/src/site/markdown/cookbook/README.md
@@ -0,0 +1,38 @@
+# GitHub Copilot SDK Cookbook — Java
+
+This folder hosts short, practical recipes for using the GitHub Copilot SDK with Java. Each recipe is concise, copy‑pasteable, and points to fuller examples and tests.
+
+## Prerequisites
+
+All cookbook examples can be run directly using [JBang](https://www.jbang.dev/), which allows you to run Java code without a full project setup.
+
+**Install JBang:**
+
+```bash
+# macOS (using Homebrew)
+brew install jbangdev/tap/jbang
+
+# Linux/macOS (using curl)
+curl -Ls https://sh.jbang.dev | bash -s - app setup
+
+# Windows (using Scoop)
+scoop install jbang
+```
+
+For other installation methods, see the [JBang installation guide](https://www.jbang.dev/download/).
+
+## Recipes
+
+- [Error Handling](error-handling.md): Handle errors gracefully including connection failures, timeouts, and cleanup.
+- [Multiple Sessions](multiple-sessions.md): Manage multiple independent conversations simultaneously.
+- [Managing Local Files](managing-local-files.md): Organize files by metadata using AI-powered grouping strategies.
+- [PR Visualization](pr-visualization.md): Generate interactive PR age charts using GitHub MCP Server.
+- [Persisting Sessions](persisting-sessions.md): Save and resume sessions across restarts.
+
+## Contributing
+
+Add a new recipe by creating a markdown file in this folder and linking it above. Follow repository guidance in the [main README](https://github.com/github/copilot-sdk-java#contributing).
+
+## Status
+
+These recipes are complete, practical examples and can be used directly or adapted for your own projects.
diff --git a/src/site/markdown/cookbook/error-handling.md b/src/site/markdown/cookbook/error-handling.md
new file mode 100644
index 0000000000..0f07e10ff5
--- /dev/null
+++ b/src/site/markdown/cookbook/error-handling.md
@@ -0,0 +1,281 @@
+# Error Handling Patterns
+
+Handle errors gracefully in your Copilot SDK applications.
+
+## Prerequisites
+
+Install [JBang](https://www.jbang.dev/) to run these examples:
+
+```bash
+# macOS (using Homebrew)
+brew install jbangdev/tap/jbang
+
+# Linux/macOS (using curl)
+curl -Ls https://sh.jbang.dev | bash -s - app setup
+
+# Windows (using Scoop)
+scoop install jbang
+```
+
+## Example scenario
+
+You need to handle various error conditions like connection failures, timeouts, and invalid responses.
+
+## Basic error handling
+
+**Usage:**
+```bash
+jbang BasicErrorHandling.java
+```
+
+**Code:**
+```java
+//DEPS com.github:copilot-sdk-java:1.0.0-beta-8-java.0
+import com.github.copilot.CopilotClient;
+import com.github.copilot.generated.AssistantMessageEvent;
+import com.github.copilot.rpc.MessageOptions;
+import com.github.copilot.rpc.PermissionHandler;
+import com.github.copilot.rpc.SessionConfig;
+
+public class BasicErrorHandling {
+    public static void main(String[] args) {
+        try (var client = new CopilotClient()) {
+            client.start().get();
+
+            var session = client.createSession(
+                new SessionConfig().setOnPermissionRequest(PermissionHandler.APPROVE_ALL).setModel("gpt-5")).get();
+
+            session.on(AssistantMessageEvent.class, msg -> {
+                System.out.println(msg.getData().content());
+            });
+
+            session.sendAndWait(new MessageOptions()
+                .setPrompt("Hello!")).get();
+
+            session.close();
+        } catch (Exception ex) {
+            System.err.println("Error: " + ex.getMessage());
+            ex.printStackTrace();
+        }
+    }
+}
+```
+
+## Handling specific error types
+
+```java
+//DEPS com.github:copilot-sdk-java:1.0.0-beta-8-java.0
+import com.github.copilot.CopilotClient;
+import java.util.concurrent.ExecutionException;
+
+public class SpecificErrorHandling {
+    public static void startClient() {
+        try (var client = new CopilotClient()) {
+            client.start().get();
+            // ... use client ...
+        } catch (ExecutionException ex) {
+            Throwable cause = ex.getCause();
+            if (cause instanceof java.io.IOException) {
+                System.err.println("Copilot CLI not found. Please install it first.");
+                System.err.println("Details: " + cause.getMessage());
+            } else if (cause instanceof java.util.concurrent.TimeoutException) {
+                System.err.println("Could not connect to Copilot CLI server.");
+                System.err.println("Details: " + cause.getMessage());
+            } else {
+                System.err.println("Unexpected error: " + cause.getMessage());
+                cause.printStackTrace();
+            }
+        } catch (InterruptedException ex) {
+            Thread.currentThread().interrupt();
+            System.err.println("Operation interrupted: " + ex.getMessage());
+        } catch (Exception ex) {
+            System.err.println("Unexpected error: " + ex.getMessage());
+            ex.printStackTrace();
+        }
+    }
+}
+```
+
+## Timeout handling
+
+```java
+//DEPS com.github:copilot-sdk-java:1.0.0-beta-8-java.0
+import com.github.copilot.CopilotSession;
+import com.github.copilot.generated.AssistantMessageEvent;
+import com.github.copilot.rpc.MessageOptions;
+import java.util.concurrent.TimeUnit;
+import java.util.concurrent.TimeoutException;
+
+public class TimeoutHandling {
+    public static void sendWithTimeout(CopilotSession session) {
+        try {
+            session.on(AssistantMessageEvent.class, msg -> {
+                System.out.println(msg.getData().content());
+            });
+
+            // Wait up to 30 seconds for response
+            session.sendAndWait(new MessageOptions()
+                .setPrompt("Complex question..."))
+                .get(30, TimeUnit.SECONDS);
+
+        } catch (TimeoutException ex) {
+            System.err.println("Request timed out");
+        } catch (Exception ex) {
+            System.err.println("Error: " + ex.getMessage());
+        }
+    }
+}
+```
+
+## Aborting a request
+
+```java
+//DEPS com.github:copilot-sdk-java:1.0.0-beta-8-java.0
+import com.github.copilot.CopilotSession;
+import com.github.copilot.rpc.MessageOptions;
+import java.util.concurrent.Executors;
+import java.util.concurrent.ScheduledExecutorService;
+import java.util.concurrent.TimeUnit;
+
+public class AbortRequest {
+    public static void abortAfterDelay(CopilotSession session) {
+        // Start a request (non-blocking)
+        session.send(new MessageOptions()
+            .setPrompt("Write a very long story..."));
+
+        // Schedule abort after 5 seconds
+        ScheduledExecutorService scheduler = Executors.newScheduledThreadPool(1);
+        scheduler.schedule(() -> {
+            try {
+                session.abort().get();
+                System.out.println("Request aborted");
+            } catch (Exception ex) {
+                System.err.println("Failed to abort: " + ex.getMessage());
+            } finally {
+                scheduler.shutdown();
+            }
+        }, 5, TimeUnit.SECONDS);
+    }
+}
+```
+
+## Graceful shutdown
+
+```java
+//DEPS com.github:copilot-sdk-java:1.0.0-beta-8-java.0
+import com.github.copilot.CopilotClient;
+
+public class GracefulShutdown {
+    public static void main(String[] args) {
+        var client = new CopilotClient();
+
+        // Set up shutdown hook
+        Runtime.getRuntime().addShutdownHook(new Thread(() -> {
+            System.out.println("\nShutting down...");
+            try {
+                client.close();
+            } catch (Exception ex) {
+                System.err.println("Error during shutdown: " + ex.getMessage());
+            }
+        }));
+
+        try {
+            client.start().get();
+            // ... do work ...
+        } catch (Exception ex) {
+            ex.printStackTrace();
+        }
+    }
+}
+```
+
+## Try-with-resources pattern
+
+```java
+//DEPS com.github:copilot-sdk-java:1.0.0-beta-8-java.0
+import com.github.copilot.CopilotClient;
+import com.github.copilot.generated.AssistantMessageEvent;
+import com.github.copilot.rpc.MessageOptions;
+import com.github.copilot.rpc.PermissionHandler;
+import com.github.copilot.rpc.SessionConfig;
+
+public class TryWithResources {
+    public static void doWork() throws Exception {
+        try (var client = new CopilotClient()) {
+            client.start().get();
+
+            try (var session = client.createSession(
+                    new SessionConfig().setOnPermissionRequest(PermissionHandler.APPROVE_ALL).setModel("gpt-5")).get()) {
+
+                session.on(AssistantMessageEvent.class, msg -> {
+                    System.out.println(msg.getData().content());
+                });
+
+                session.sendAndWait(new MessageOptions()
+                    .setPrompt("Hello!")).get();
+
+                // Session and client are automatically closed
+            }
+        }
+    }
+}
+```
+
+## Handling tool errors
+
+```java
+//DEPS com.github:copilot-sdk-java:1.0.0-beta-8-java.0
+import com.github.copilot.CopilotClient;
+import com.github.copilot.generated.AssistantMessageEvent;
+import com.github.copilot.rpc.MessageOptions;
+import com.github.copilot.rpc.PermissionHandler;
+import com.github.copilot.rpc.SessionConfig;
+import com.github.copilot.rpc.ToolDefinition;
+import com.github.copilot.rpc.ToolResultObject;
+import java.util.Map;
+import java.util.List;
+import java.util.concurrent.CompletableFuture;
+
+public class ToolErrorHandling {
+    public static void handleToolErrors() throws Exception {
+        var errorTool = ToolDefinition.create(
+            "get_user_location",
+            "Gets the user's location",
+            Map.of("type", "object", "properties", Map.of()),
+            invocation -> {
+                // Return an error result
+                return CompletableFuture.completedFuture(
+                    ToolResultObject.error("Location service unavailable")
+                );
+            }
+        );
+
+        try (var client = new CopilotClient()) {
+            client.start().get();
+
+            var session = client.createSession(
+                new SessionConfig().setOnPermissionRequest(PermissionHandler.APPROVE_ALL).setTools(List.of(errorTool))).get();
+
+            session.on(AssistantMessageEvent.class, msg -> {
+                System.out.println(msg.getData().content());
+            });
+
+            // Session continues even when tool fails
+            session.sendAndWait(new MessageOptions()
+                .setPrompt("What is my location? If you can't find out, just say 'unknown'."))
+                .get();
+
+            session.close();
+        }
+    }
+}
+```
+
+## Best practices
+
+1. **Always clean up**: Use try-with-resources to ensure `close()` is called
+2. **Handle connection errors**: The CLI might not be installed or running
+3. **Set appropriate timeouts**: Use `get(timeout, TimeUnit)` for long-running requests
+4. **Log errors**: Capture error details for debugging
+5. **Wrap operations**: Consider wrapping SDK operations in methods that handle common errors
+6. **Check error causes**: Use `ExecutionException.getCause()` to get the actual error from `CompletableFuture`
diff --git a/src/site/markdown/cookbook/managing-local-files.md b/src/site/markdown/cookbook/managing-local-files.md
new file mode 100644
index 0000000000..2e986850e1
--- /dev/null
+++ b/src/site/markdown/cookbook/managing-local-files.md
@@ -0,0 +1,213 @@
+# Grouping Files by Metadata
+
+Use Copilot to intelligently organize files in a folder based on their metadata.
+
+## Prerequisites
+
+Install [JBang](https://www.jbang.dev/) to run these examples:
+
+```bash
+# macOS (using Homebrew)
+brew install jbangdev/tap/jbang
+
+# Linux/macOS (using curl)
+curl -Ls https://sh.jbang.dev | bash -s - app setup
+
+# Windows (using Scoop)
+scoop install jbang
+```
+
+## Example scenario
+
+You have a folder with many files and want to organize them into subfolders based on metadata like file type, creation date, size, or other attributes. Copilot can analyze the files and suggest or execute a grouping strategy.
+
+## Example code
+
+**Usage:**
+```bash
+# Use with a specific folder (recommended)
+jbang ManagingLocalFiles.java /path/to/your/folder
+
+# Or run without arguments to use a safe default (temp directory)
+jbang ManagingLocalFiles.java
+```
+
+**Code:**
+```java
+//DEPS com.github:copilot-sdk-java:1.0.0-beta-8-java.0
+import com.github.copilot.CopilotClient;
+import com.github.copilot.generated.AssistantMessageEvent;
+import com.github.copilot.generated.SessionIdleEvent;
+import com.github.copilot.generated.ToolExecutionCompleteEvent;
+import com.github.copilot.generated.ToolExecutionStartEvent;
+import com.github.copilot.rpc.MessageOptions;
+import com.github.copilot.rpc.PermissionHandler;
+import com.github.copilot.rpc.SessionConfig;
+import java.nio.file.Paths;
+import java.util.concurrent.CountDownLatch;
+
+public class ManagingLocalFiles {
+    public static void main(String[] args) throws Exception {
+        try (var client = new CopilotClient()) {
+            client.start().get();
+
+            // Create session
+            var session = client.createSession(
+                new SessionConfig().setOnPermissionRequest(PermissionHandler.APPROVE_ALL).setModel("gpt-5")).get();
+
+            // Set up event handlers
+            var done = new CountDownLatch(1);
+
+            session.on(AssistantMessageEvent.class, msg -> 
+                System.out.println("\nCopilot: " + msg.getData().content())
+            );
+
+            session.on(ToolExecutionStartEvent.class, evt -> 
+                System.out.println("  → Running: " + evt.getData().toolName())
+            );
+
+            session.on(ToolExecutionCompleteEvent.class, evt -> 
+                System.out.println("  ✓ Completed: " + evt.getData().toolCallId())
+            );
+
+            session.on(SessionIdleEvent.class, evt -> done.countDown());
+
+            // Ask Copilot to organize files - using a safe example folder
+            // For real use, replace with your target folder
+            String targetFolder = args.length > 0 ? args[0] : 
+                System.getProperty("java.io.tmpdir") + "/example-files";
+
+            String prompt = String.format("""
+                Analyze the files in "%s" and show how you would organize them into subfolders.
+
+                1. First, list all files and their metadata
+                2. Preview grouping by file extension
+                3. Suggest appropriate subfolders (e.g., "images", "documents", "videos")
+                
+                IMPORTANT: DO NOT move any files. Only show the plan.
+                """, targetFolder);
+
+            session.send(new MessageOptions().setPrompt(prompt));
+
+            // Wait for completion
+            done.await();
+
+            session.close();
+        }
+    }
+}
+```
+
+## Grouping strategies
+
+### By file extension
+
+```java
+// Groups files like:
+// images/   -> .jpg, .png, .gif
+// documents/ -> .pdf, .docx, .txt
+// videos/   -> .mp4, .avi, .mov
+```
+
+### By creation date
+
+```java
+// Groups files like:
+// 2024-01/ -> files created in January 2024
+// 2024-02/ -> files created in February 2024
+```
+
+### By file size
+
+```java
+// Groups files like:
+// tiny-under-1kb/
+// small-under-1mb/
+// medium-under-100mb/
+// large-over-100mb/
+```
+
+## Dry-run mode
+
+For safety, you can ask Copilot to only preview changes:
+
+```java
+String prompt = String.format("""
+    Analyze files in "%s" and show me how you would organize them
+    by file type. DO NOT move any files - just show me the plan.
+    """, targetFolder);
+
+session.send(new MessageOptions().setPrompt(prompt));
+```
+
+## Custom grouping with AI analysis
+
+Let Copilot determine the best grouping based on file content:
+
+```java
+String prompt = String.format("""
+    Look at the files in "%s" and suggest a logical organization.
+    Consider:
+    - File names and what they might contain
+    - File types and their typical uses
+    - Date patterns that might indicate projects or events
+
+    Propose folder names that are descriptive and useful.
+    """, targetFolder);
+
+session.send(new MessageOptions().setPrompt(prompt));
+```
+
+## Interactive file organization
+
+```java
+//DEPS com.github:copilot-sdk-java:1.0.0-beta-8-java.0
+import java.io.BufferedReader;
+import java.io.InputStreamReader;
+
+public class InteractiveFileOrganizer {
+    public static void main(String[] args) throws Exception {
+        try (var client = new CopilotClient();
+             var reader = new BufferedReader(new InputStreamReader(System.in))) {
+            
+            client.start().get();
+
+            var session = client.createSession(
+                new SessionConfig().setOnPermissionRequest(PermissionHandler.APPROVE_ALL).setModel("gpt-5")).get();
+
+            session.on(AssistantMessageEvent.class, msg -> 
+                System.out.println("\nCopilot: " + msg.getData().content())
+            );
+
+            System.out.print("Enter folder path to organize: ");
+            String folderPath = reader.readLine();
+
+            String initialPrompt = String.format("""
+                Analyze the files in "%s" and suggest an organization strategy.
+                Wait for my confirmation before making any changes.
+                """, folderPath);
+
+            session.send(new MessageOptions().setPrompt(initialPrompt));
+
+            // Interactive loop
+            System.out.println("\nEnter commands (or 'exit' to quit):");
+            String line;
+            while ((line = reader.readLine()) != null) {
+                if (line.equalsIgnoreCase("exit")) {
+                    break;
+                }
+                session.send(new MessageOptions().setPrompt(line));
+            }
+
+            session.close();
+        }
+    }
+}
+```
+
+## Safety considerations
+
+1. **Confirm before moving**: Ask Copilot to confirm before executing moves
+2. **Handle duplicates**: Consider what happens if a file with the same name exists
+3. **Preserve originals**: Consider copying instead of moving for important files
+4. **Test with dry-run**: Always test with a dry-run first to preview the changes
diff --git a/src/site/markdown/cookbook/multiple-sessions.md b/src/site/markdown/cookbook/multiple-sessions.md
new file mode 100644
index 0000000000..653f8edeff
--- /dev/null
+++ b/src/site/markdown/cookbook/multiple-sessions.md
@@ -0,0 +1,235 @@
+# Working with Multiple Sessions
+
+Manage multiple independent conversations simultaneously.
+
+## Prerequisites
+
+Install [JBang](https://www.jbang.dev/) to run these examples:
+
+```bash
+# macOS (using Homebrew)
+brew install jbangdev/tap/jbang
+
+# Linux/macOS (using curl)
+curl -Ls https://sh.jbang.dev | bash -s - app setup
+
+# Windows (using Scoop)
+scoop install jbang
+```
+
+## Example scenario
+
+You need to run multiple conversations in parallel, each with its own context and history.
+
+## Java
+
+**Usage:**
+```bash
+jbang MultipleSessions.java
+```
+
+**Code:**
+```java
+//DEPS com.github:copilot-sdk-java:1.0.0-beta-8-java.0
+import com.github.copilot.CopilotClient;
+import com.github.copilot.generated.AssistantMessageEvent;
+import com.github.copilot.rpc.MessageOptions;
+import com.github.copilot.rpc.PermissionHandler;
+import com.github.copilot.rpc.SessionConfig;
+
+public class MultipleSessions {
+    public static void main(String[] args) throws Exception {
+        try (var client = new CopilotClient()) {
+            client.start().get();
+
+            // Create multiple independent sessions
+            var session1 = client.createSession(
+                new SessionConfig().setOnPermissionRequest(PermissionHandler.APPROVE_ALL).setModel("gpt-5")).get();
+            var session2 = client.createSession(
+                new SessionConfig().setOnPermissionRequest(PermissionHandler.APPROVE_ALL).setModel("gpt-5")).get();
+            var session3 = client.createSession(
+                new SessionConfig().setOnPermissionRequest(PermissionHandler.APPROVE_ALL).setModel("claude-sonnet-4.5")).get();
+
+            // Set up event handlers for each session
+            session1.on(AssistantMessageEvent.class, msg -> 
+                System.out.println("Session 1: " + msg.getData().content()));
+            session2.on(AssistantMessageEvent.class, msg -> 
+                System.out.println("Session 2: " + msg.getData().content()));
+            session3.on(AssistantMessageEvent.class, msg -> 
+                System.out.println("Session 3: " + msg.getData().content()));
+
+            // Each session maintains its own conversation history
+            session1.send(new MessageOptions()
+                .setPrompt("You are helping with a Python project"));
+            session2.send(new MessageOptions()
+                .setPrompt("You are helping with a TypeScript project"));
+            session3.send(new MessageOptions()
+                .setPrompt("You are helping with a Go project"));
+
+            // Follow-up messages stay in their respective contexts
+            session1.send(new MessageOptions()
+                .setPrompt("How do I create a virtual environment?"));
+            session2.send(new MessageOptions()
+                .setPrompt("How do I set up tsconfig?"));
+            session3.send(new MessageOptions()
+                .setPrompt("How do I initialize a module?"));
+
+            // Wait for all sessions to complete
+            Thread.sleep(5000);
+
+            // Clean up
+            session1.close();
+            session2.close();
+            session3.close();
+        }
+    }
+}
+```
+
+## Custom session IDs
+
+Use custom IDs for easier tracking:
+
+```java
+var session = client.createSession(
+    new SessionConfig().setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
+        .setSessionId("user-123-chat")
+        .setModel("gpt-5")
+).get();
+
+System.out.println(session.getSessionId()); // "user-123-chat"
+```
+
+## Listing sessions
+
+```java
+var sessions = client.listSessions().get();
+for (var sessionInfo : sessions) {
+    System.out.println("Session: " + sessionInfo.getSessionId());
+}
+```
+
+## Deleting sessions
+
+```java
+// Delete a specific session
+try {
+    client.deleteSession("user-123-chat").get();
+} catch (Exception ex) {
+    System.err.println("Failed to delete session: " + ex.getMessage());
+}
+```
+
+## Managing session lifecycle with CompletableFuture
+
+```java
+//DEPS com.github:copilot-sdk-java:1.0.0-beta-8-java.0
+import java.util.concurrent.CompletableFuture;
+import java.util.List;
+
+public class ParallelSessions {
+    public static void runParallelSessions(CopilotClient client) throws Exception {
+        // Create sessions in parallel
+        var sessionFutures = List.of(
+            client.createSession(new SessionConfig().setOnPermissionRequest(PermissionHandler.APPROVE_ALL).setModel("gpt-5")),
+            client.createSession(new SessionConfig().setOnPermissionRequest(PermissionHandler.APPROVE_ALL).setModel("gpt-5")),
+            client.createSession(new SessionConfig().setOnPermissionRequest(PermissionHandler.APPROVE_ALL).setModel("claude-sonnet-4.5"))
+        );
+
+        // Wait for all sessions to be created
+        CompletableFuture.allOf(sessionFutures.toArray(new CompletableFuture[0]))
+            .get();
+
+        // Get the created sessions
+        var session1 = sessionFutures.get(0).get();
+        var session2 = sessionFutures.get(1).get();
+        var session3 = sessionFutures.get(2).get();
+
+        // Send messages in parallel
+        var messageFutures = List.of(
+            session1.sendAndWait(new MessageOptions().setPrompt("Question 1")),
+            session2.sendAndWait(new MessageOptions().setPrompt("Question 2")),
+            session3.sendAndWait(new MessageOptions().setPrompt("Question 3"))
+        );
+
+        // Wait for all responses
+        CompletableFuture.allOf(messageFutures.toArray(new CompletableFuture[0]))
+            .get();
+
+        // Clean up
+        session1.close();
+        session2.close();
+        session3.close();
+    }
+}
+```
+
+## Providing a custom Executor for parallel sessions
+
+By default, `CompletableFuture` operations run on `ForkJoinPool.commonPool()`,
+which has limited parallelism (typically `Runtime.availableProcessors() - 1`
+threads). When multiple sessions block waiting for CLI responses, those threads
+are unavailable for other work—a condition known as *pool starvation*.
+
+Use `CopilotClientOptions.setExecutor(Executor)` to supply a dedicated thread
+pool so that SDK work does not compete with the rest of your application for
+common-pool threads:
+
+```java
+//DEPS com.github:copilot-sdk-java:${project.version}
+import com.github.copilot.CopilotClient;
+import com.github.copilot.rpc.CopilotClientOptions;
+import com.github.copilot.rpc.SessionConfig;
+import com.github.copilot.rpc.MessageOptions;
+import com.github.copilot.rpc.PermissionHandler;
+import java.util.List;
+import java.util.concurrent.CompletableFuture;
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.Executors;
+
+public class ParallelSessionsWithExecutor {
+    public static void main(String[] args) throws Exception {
+        ExecutorService pool = Executors.newFixedThreadPool(4);
+        try {
+            var options = new CopilotClientOptions().setExecutor(pool);
+            try (CopilotClient client = new CopilotClient(options)) {
+                client.start().get();
+
+                var s1 = client.createSession(new SessionConfig()
+                    .setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
+                    .setModel("gpt-5")).get();
+                var s2 = client.createSession(new SessionConfig()
+                    .setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
+                    .setModel("gpt-5")).get();
+                var s3 = client.createSession(new SessionConfig()
+                    .setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
+                    .setModel("claude-sonnet-4.5")).get();
+
+                CompletableFuture.allOf(
+                    s1.sendAndWait(new MessageOptions().setPrompt("Question 1")),
+                    s2.sendAndWait(new MessageOptions().setPrompt("Question 2")),
+                    s3.sendAndWait(new MessageOptions().setPrompt("Question 3"))
+                ).get();
+
+                s1.close();
+                s2.close();
+                s3.close();
+            }
+        } finally {
+            pool.shutdown();
+        }
+    }
+}
+```
+
+Passing `null` (or omitting `setExecutor` entirely) keeps the default
+`ForkJoinPool.commonPool()` behaviour. The executor is used for all internal
+`CompletableFuture.runAsync` / `supplyAsync` calls—including client start/stop,
+tool-call dispatch, permission dispatch, user-input dispatch, and hooks.
+
+## Use cases
+
+- **Multi-user applications**: One session per user
+- **Multi-task workflows**: Separate sessions for different tasks
+- **A/B testing**: Compare responses from different models
+- **Parallel processing**: Process multiple requests simultaneously
diff --git a/src/site/markdown/cookbook/persisting-sessions.md b/src/site/markdown/cookbook/persisting-sessions.md
new file mode 100644
index 0000000000..478502e887
--- /dev/null
+++ b/src/site/markdown/cookbook/persisting-sessions.md
@@ -0,0 +1,293 @@
+# Session Persistence and Resumption
+
+Save and restore conversation sessions across application restarts.
+
+## Prerequisites
+
+Install [JBang](https://www.jbang.dev/) to run these examples:
+
+```bash
+# macOS (using Homebrew)
+brew install jbangdev/tap/jbang
+
+# Linux/macOS (using curl)
+curl -Ls https://sh.jbang.dev | bash -s - app setup
+
+# Windows (using Scoop)
+scoop install jbang
+```
+
+## Example scenario
+
+You want users to be able to continue a conversation even after closing and reopening your application.
+
+## Creating a session with a custom ID
+
+**Usage:**
+```bash
+jbang PersistingSessions.java
+```
+
+**Code:**
+```java
+//DEPS com.github:copilot-sdk-java:1.0.0-beta-8-java.0
+import com.github.copilot.CopilotClient;
+import com.github.copilot.generated.AssistantMessageEvent;
+import com.github.copilot.rpc.MessageOptions;
+import com.github.copilot.rpc.PermissionHandler;
+import com.github.copilot.rpc.SessionConfig;
+
+public class PersistingSessions {
+    public static void main(String[] args) throws Exception {
+        try (var client = new CopilotClient()) {
+            client.start().get();
+
+            // Create session with a memorable ID
+            var session = client.createSession(
+                new SessionConfig().setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
+                    .setSessionId("user-123-conversation")
+                    .setModel("gpt-5")
+            ).get();
+
+            session.on(AssistantMessageEvent.class, msg -> 
+                System.out.println(msg.getData().content())
+            );
+
+            session.sendAndWait(new MessageOptions()
+                .setPrompt("Let's discuss TypeScript generics")).get();
+
+            // Session ID is preserved
+            System.out.println("Session ID: " + session.getSessionId());
+
+            // Close session but keep data on disk
+            session.close();
+        }
+    }
+}
+```
+
+## Resuming a session
+
+```java
+public class ResumeSession {
+    public static void main(String[] args) throws Exception {
+        try (var client = new CopilotClient()) {
+            client.start().get();
+
+            // Resume the previous session
+            var session = client.resumeSession("user-123-conversation", new ResumeSessionConfig().setOnPermissionRequest(PermissionHandler.APPROVE_ALL)).get();
+
+            session.on(AssistantMessageEvent.class, msg -> 
+                System.out.println(msg.getData().content())
+            );
+
+            // Previous context is restored
+            session.sendAndWait(new MessageOptions()
+                .setPrompt("What were we discussing?")).get();
+
+            session.close();
+        }
+    }
+}
+```
+
+## Listing available sessions
+
+```java
+public class ListSessions {
+    public static void main(String[] args) throws Exception {
+        try (var client = new CopilotClient()) {
+            client.start().get();
+
+            var sessions = client.listSessions().get();
+            for (var sessionInfo : sessions) {
+                System.out.println("Session: " + sessionInfo.getSessionId());
+            }
+        }
+    }
+}
+```
+
+## Deleting a session permanently
+
+```java
+public class DeleteSession {
+    public static void main(String[] args) throws Exception {
+        try (var client = new CopilotClient()) {
+            client.start().get();
+
+            // Remove session and all its data from disk
+            client.deleteSession("user-123-conversation").get();
+            System.out.println("Session deleted");
+        }
+    }
+}
+```
+
+## Getting session history
+
+```java
+//DEPS com.github:copilot-sdk-java:1.0.0-beta-8-java.0
+import com.github.copilot.CopilotClient;
+import com.github.copilot.generated.AssistantMessageEvent;
+import com.github.copilot.generated.UserMessageEvent;
+import com.github.copilot.rpc.PermissionHandler;
+import com.github.copilot.rpc.ResumeSessionConfig;
+
+public class SessionHistory {
+    public static void main(String[] args) throws Exception {
+        try (var client = new CopilotClient()) {
+            client.start().get();
+
+            var session = client.resumeSession("user-123-conversation", new ResumeSessionConfig().setOnPermissionRequest(PermissionHandler.APPROVE_ALL)).get();
+
+            var messages = session.getMessages().get();
+            for (var event : messages) {
+                // Print different event types appropriately
+                if (event instanceof AssistantMessageEvent msg) {
+                    System.out.printf("[assistant] %s%n", msg.getData().content());
+                } else if (event instanceof UserMessageEvent userMsg) {
+                    System.out.printf("[user] %s%n", userMsg.getData().content());
+                } else {
+                    System.out.printf("[%s]%n", event.getType());
+                }
+            }
+
+            session.close();
+        }
+    }
+}
+```
+
+## Complete example with session management
+
+```java
+//DEPS com.github:copilot-sdk-java:1.0.0-beta-8-java.0
+import java.util.Scanner;
+
+public class SessionManager {
+    public static void main(String[] args) throws Exception {
+        try (var client = new CopilotClient();
+             var scanner = new Scanner(System.in)) {
+            
+            client.start().get();
+
+            System.out.println("Session Manager");
+            System.out.println("1. Create new session");
+            System.out.println("2. Resume existing session");
+            System.out.println("3. List sessions");
+            System.out.print("Choose an option: ");
+
+            int choice = scanner.nextInt();
+            scanner.nextLine(); // consume newline
+
+            CopilotSession session = null;
+
+            switch (choice) {
+                case 1:
+                    System.out.print("Enter session ID: ");
+                    String sessionId = scanner.nextLine();
+                    session = client.createSession(
+                        new SessionConfig().setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
+                            .setSessionId(sessionId)
+                            .setModel("gpt-5")
+                    ).get();
+                    System.out.println("Created session: " + sessionId);
+                    break;
+
+                case 2:
+                    System.out.print("Enter session ID to resume: ");
+                    String resumeId = scanner.nextLine();
+                    try {
+                        session = client.resumeSession(resumeId, new ResumeSessionConfig().setOnPermissionRequest(PermissionHandler.APPROVE_ALL)).get();
+                        System.out.println("Resumed session: " + resumeId);
+                    } catch (Exception ex) {
+                        System.err.println("Failed to resume session: " + ex.getMessage());
+                        return;
+                    }
+                    break;
+
+                case 3:
+                    var sessions = client.listSessions().get();
+                    System.out.println("\nAvailable sessions:");
+                    for (var s : sessions) {
+                        System.out.println("  - " + s.getSessionId());
+                    }
+                    return;
+
+                default:
+                    System.out.println("Invalid choice");
+                    return;
+            }
+
+            if (session != null) {
+                session.on(AssistantMessageEvent.class, msg -> 
+                    System.out.println("\nCopilot: " + msg.getData().content())
+                );
+
+                // Interactive conversation loop
+                System.out.println("\nStart chatting (type 'exit' to quit):");
+                while (true) {
+                    System.out.print("\nYou: ");
+                    String input = scanner.nextLine();
+                    
+                    if (input.equalsIgnoreCase("exit")) {
+                        break;
+                    }
+
+                    session.send(new MessageOptions().setPrompt(input));
+                    Thread.sleep(2000); // Give time for response
+                }
+
+                session.close();
+            }
+        }
+    }
+}
+```
+
+## Checking if a session exists
+
+```java
+public class CheckSession {
+    public static boolean sessionExists(CopilotClient client, String sessionId) {
+        try {
+            var sessions = client.listSessions().get();
+            return sessions.stream()
+                .anyMatch(s -> s.getSessionId().equals(sessionId));
+        } catch (Exception ex) {
+            return false;
+        }
+    }
+
+    public static void main(String[] args) throws Exception {
+        try (var client = new CopilotClient()) {
+            client.start().get();
+
+            String sessionId = "user-123-conversation";
+            
+            if (sessionExists(client, sessionId)) {
+                System.out.println("Session exists, resuming...");
+                var session = client.resumeSession(sessionId, new ResumeSessionConfig().setOnPermissionRequest(PermissionHandler.APPROVE_ALL)).get();
+                // ... use session ...
+                session.close();
+            } else {
+                System.out.println("Session doesn't exist, creating new one...");
+                var session = client.createSession(
+                    new SessionConfig().setOnPermissionRequest(PermissionHandler.APPROVE_ALL).setSessionId(sessionId).setModel("gpt-5")
+                ).get();
+                // ... use session ...
+                session.close();
+            }
+        }
+    }
+}
+```
+
+## Best practices
+
+1. **Use meaningful session IDs**: Include user ID or context in the session ID (e.g., "user-123-chat", "task-456-review")
+2. **Handle missing sessions**: Check if a session exists before resuming
+3. **Clean up old sessions**: Periodically delete sessions that are no longer needed
+4. **Error handling**: Always wrap resume operations in try-catch blocks
+5. **Workspace awareness**: Sessions are tied to workspace paths, ensure consistency
diff --git a/src/site/markdown/cookbook/pr-visualization.md b/src/site/markdown/cookbook/pr-visualization.md
new file mode 100644
index 0000000000..7f45b94883
--- /dev/null
+++ b/src/site/markdown/cookbook/pr-visualization.md
@@ -0,0 +1,236 @@
+# Generating PR Age Charts
+
+Build an interactive CLI tool that visualizes pull request age distribution for a GitHub repository using Copilot's built-in capabilities.
+
+## Prerequisites
+
+Install [JBang](https://www.jbang.dev/) to run this example:
+
+```bash
+# macOS (using Homebrew)
+brew install jbangdev/tap/jbang
+
+# Linux/macOS (using curl)
+curl -Ls https://sh.jbang.dev | bash -s - app setup
+
+# Windows (using Scoop)
+scoop install jbang
+```
+
+## Example scenario
+
+You want to understand how long PRs have been open in a repository. This tool detects the current Git repo or accepts a repo as input, then lets Copilot fetch PR data via the GitHub MCP Server and generate a chart image.
+
+## Usage
+
+```bash
+# Auto-detect from current git repo
+jbang PRVisualization.java
+
+# Specify a repo explicitly
+jbang PRVisualization.java github/copilot-sdk
+```
+
+## Full example: PRVisualization.java
+
+```java
+//DEPS com.github:copilot-sdk-java:1.0.0-beta-8-java.0
+import com.github.copilot.CopilotClient;
+import com.github.copilot.generated.AssistantMessageEvent;
+import com.github.copilot.generated.ToolExecutionStartEvent;
+import com.github.copilot.rpc.MessageOptions;
+import com.github.copilot.rpc.PermissionHandler;
+import com.github.copilot.rpc.SessionConfig;
+import com.github.copilot.rpc.SystemMessageConfig;
+import java.io.BufferedReader;
+import java.io.EOFException;
+import java.io.IOException;
+import java.io.InputStreamReader;
+import java.util.regex.Pattern;
+
+public class PRVisualization {
+
+    public static void main(String[] args) throws Exception {
+        System.out.println("🔍 PR Age Chart Generator\n");
+
+        // Determine the repository
+        String repo;
+        if (args.length > 0) {
+            repo = args[0];
+            System.out.println("📦 Using specified repo: " + repo);
+        } else if (isGitRepo()) {
+            String detected = getGitHubRemote();
+            if (detected != null && !detected.isEmpty()) {
+                repo = detected;
+                System.out.println("📦 Detected GitHub repo: " + repo);
+            } else {
+                System.out.println("⚠️  Git repo found but no GitHub remote detected.");
+                repo = promptForRepo();
+            }
+        } else {
+            System.out.println("📁 Not in a git repository.");
+            repo = promptForRepo();
+        }
+
+        if (repo == null || !repo.contains("/")) {
+            System.err.println("❌ Invalid repo format. Expected: owner/repo");
+            System.exit(1);
+        }
+
+        String[] parts = repo.split("/", 2);
+        String owner = parts[0];
+        String repoName = parts[1];
+
+        // Create Copilot client
+        try (var client = new CopilotClient()) {
+            client.start().get();
+
+            String cwd = System.getProperty("user.dir");
+            var systemMessage = String.format("""
+                <context>
+                You are analyzing pull requests for the GitHub repository: %s/%s
+                The current working directory is: %s
+                </context>
+
+                <instructions>
+                - Use the GitHub MCP Server tools to fetch PR data
+                - Use your file and code execution tools to generate charts
+                - Save any generated images to the current working directory
+                - Be concise in your responses
+                </instructions>
+                """, owner, repoName, cwd);
+
+            var session = client.createSession(
+                new SessionConfig().setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
+                    .setModel("gpt-5")
+                    .setSystemMessage(new SystemMessageConfig().setContent(systemMessage))
+            ).get();
+
+            // Set up event handling
+            session.on(AssistantMessageEvent.class, msg -> 
+                System.out.println("\n🤖 " + msg.getData().content() + "\n")
+            );
+
+            session.on(ToolExecutionStartEvent.class, evt -> 
+                System.out.println("  ⚙️  " + evt.getData().toolName())
+            );
+
+            // Initial prompt - let Copilot figure out the details
+            System.out.println("\n📊 Starting analysis...\n");
+
+            String prompt = String.format("""
+                Fetch the open pull requests for %s/%s from the last week.
+                Calculate the age of each PR in days.
+                Then generate a bar chart image showing the distribution of PR ages
+                (group them into sensible buckets like <1 day, 1-3 days, etc.).
+                Save the chart as "pr-age-chart.png" in the current directory.
+                Finally, summarize the PR health - average age, oldest PR, and how many might be considered stale.
+                """, owner, repoName);
+
+            session.send(new MessageOptions().setPrompt(prompt));
+
+            // Wait a bit for initial processing
+            Thread.sleep(10000);
+
+            // Interactive loop
+            System.out.println("\n💡 Ask follow-up questions or type \"exit\" to quit.\n");
+            System.out.println("Examples:");
+            System.out.println("  - \"Expand to the last month\"");
+            System.out.println("  - \"Show me the 5 oldest PRs\"");
+            System.out.println("  - \"Generate a pie chart instead\"");
+            System.out.println("  - \"Group by author instead of age\"");
+            System.out.println();
+
+            try (var reader = new BufferedReader(new InputStreamReader(System.in))) {
+                while (true) {
+                    System.out.print("You: ");
+                    String input = reader.readLine();
+                    if (input == null) break;
+                    input = input.trim();
+
+                    if (input.isEmpty()) continue;
+                    if (input.equalsIgnoreCase("exit") || input.equalsIgnoreCase("quit")) {
+                        System.out.println("👋 Goodbye!");
+                        break;
+                    }
+
+                    session.send(new MessageOptions().setPrompt(input));
+                    Thread.sleep(2000); // Give time for response
+                }
+            }
+
+            session.close();
+        }
+    }
+
+    // ============================================================================
+    // Git & GitHub Detection
+    // ============================================================================
+
+    private static boolean isGitRepo() {
+        try {
+            Process proc = Runtime.getRuntime().exec(new String[]{"git", "rev-parse", "--git-dir"});
+            return proc.waitFor() == 0;
+        } catch (Exception e) {
+            return false;
+        }
+    }
+
+    private static String getGitHubRemote() {
+        try {
+            Process proc = Runtime.getRuntime().exec(new String[]{"git", "remote", "get-url", "origin"});
+            try (BufferedReader reader = new BufferedReader(new InputStreamReader(proc.getInputStream()))) {
+                String remoteURL = reader.readLine();
+                if (remoteURL == null) return null;
+                remoteURL = remoteURL.trim();
+
+                // Handle SSH: git@github.com:owner/repo.git
+                var sshPattern = Pattern.compile("git@github\\.com:(.+/.+?)(?:\\.git)?$");
+                var sshMatcher = sshPattern.matcher(remoteURL);
+                if (sshMatcher.find()) {
+                    return sshMatcher.group(1);
+                }
+
+                // Handle HTTPS: https://github.com/owner/repo.git
+                var httpsPattern = Pattern.compile("https://github\\.com/(.+/.+?)(?:\\.git)?$");
+                var httpsMatcher = httpsPattern.matcher(remoteURL);
+                if (httpsMatcher.find()) {
+                    return httpsMatcher.group(1);
+                }
+            }
+        } catch (Exception e) {
+            // Ignore
+        }
+        return null;
+    }
+
+    private static String promptForRepo() throws IOException {
+        BufferedReader reader = new BufferedReader(new InputStreamReader(System.in));
+        System.out.print("Enter GitHub repo (owner/repo): ");
+        String line = reader.readLine();
+        if (line == null) {
+            throw new EOFException("End of input while reading repository name");
+        }
+        return line.trim();
+    }
+}
+```
+
+## How it works
+
+1. **Repository detection**: Checks command-line argument → git remote → prompts user
+2. **No custom tools**: Relies entirely on Copilot CLI's built-in capabilities:
+   - **GitHub MCP Server** - Fetches PR data from GitHub
+   - **File tools** - Saves generated chart images
+   - **Code execution** - Generates charts using Python/matplotlib or other methods
+3. **Interactive session**: After initial analysis, user can ask for adjustments
+
+## Why this approach?
+
+| Aspect          | Custom Tools      | Built-in Copilot                  |
+| --------------- | ----------------- | --------------------------------- |
+| Code complexity | High              | **Minimal**                       |
+| Maintenance     | You maintain      | **Copilot maintains**             |
+| Flexibility     | Fixed logic       | **AI decides best approach**      |
+| Chart types     | What you coded    | **Any type Copilot can generate** |
+| Data grouping   | Hardcoded buckets | **Intelligent grouping**          |
diff --git a/src/site/markdown/documentation.md b/src/site/markdown/documentation.md
new file mode 100644
index 0000000000..5812e83fdf
--- /dev/null
+++ b/src/site/markdown/documentation.md
@@ -0,0 +1,737 @@
+# GitHub Copilot SDK for Java - Documentation
+
+This guide covers common use cases for the GitHub Copilot SDK for Java. For complete API details, see the [Javadoc](apidocs/index.html).
+
+## Table of Contents
+
+- [Basic Usage](#Basic_Usage)
+- [Handling Responses](#Handling_Responses)
+- [Troubleshooting Event Handling](#Troubleshooting_Event_Handling)
+- [Event Types Reference](#Event_Types_Reference)
+- [Streaming Responses](#Streaming_Responses)
+- [Session Operations](#Session_Operations)
+- [Choosing a Model](#Choosing_a_Model)
+- [Reasoning Effort](#Reasoning_Effort)
+- [Tool Filtering](#Tool_Filtering)
+- [Working Directory](#Working_Directory)
+- [Connection State & Diagnostics](#Connection_State__Diagnostics)
+- [Message Delivery Mode](#Message_Delivery_Mode)
+- [Session Management](#Session_Management)
+- [SessionConfig Reference](#SessionConfig_Reference)
+    - [Cloning SessionConfig](#Cloning_SessionConfig)
+
+---
+
+## Basic Usage
+
+Create a client, start a session, and send a message:
+
+```java
+import com.github.copilot.CopilotClient;
+import com.github.copilot.rpc.PermissionHandler;
+import com.github.copilot.rpc.SessionConfig;
+
+try (var client = new CopilotClient()) {
+    client.start().get();
+
+    var session = client.createSession(
+        new SessionConfig().setOnPermissionRequest(PermissionHandler.APPROVE_ALL).setModel("gpt-4.1")
+    ).get();
+
+    var response = session.sendAndWait("Explain Java records in one sentence").get();
+    System.out.println(response.getData().content());
+
+    session.close();
+}
+```
+
+The client manages the connection to the Copilot CLI. Sessions are independent conversations that can run concurrently.
+
+---
+
+## Handling Responses
+
+### Simple Request-Response
+
+For straightforward interactions, use `sendAndWait()`:
+
+```java
+var response = session.sendAndWait("What is the capital of France?").get();
+System.out.println(response.getData().content());
+```
+
+### Event-Based Processing
+
+For more control, subscribe to events and use `send()`:
+
+> **Exception isolation:** If a handler throws an exception, the SDK logs the
+> error. By default, dispatch stops after the first handler error
+> (`PROPAGATE_AND_LOG_ERRORS`). To continue dispatching to remaining handlers,
+> set `EventErrorPolicy.SUPPRESS_AND_LOG_ERRORS`. You can customize error
+> handling with `session.setEventErrorHandler()` — see the
+> [Advanced Usage](advanced.html#Custom_Event_Error_Handler) guide.
+
+## Troubleshooting Event Handling
+
+### Symptoms of policy misconfiguration
+
+- You registered multiple `session.on(...)` handlers, but only the first one runs
+- A handler throws once and later handlers stop receiving events
+- You expected "best effort" fan-out, but dispatch halts on errors
+
+### Fix
+
+Set the event error policy to suppress-and-continue:
+
+```java
+session.setEventErrorPolicy(EventErrorPolicy.SUPPRESS_AND_LOG_ERRORS);
+```
+
+Optionally add a custom error handler for observability:
+
+```java
+session.setEventErrorHandler((event, exception) -> {
+    System.err.println("Handler failed for event " + event.getType() + ": " + exception.getMessage());
+});
+```
+
+Use `PROPAGATE_AND_LOG_ERRORS` when you want fail-fast behavior.
+
+```java
+var done = new CompletableFuture<Void>();
+
+// Type-safe event handlers (recommended)
+session.on(AssistantMessageEvent.class, msg -> {
+    System.out.println("Response: " + msg.getData().content());
+});
+
+session.on(SessionErrorEvent.class, err -> {
+    System.err.println("Error: " + err.getData().message());
+});
+
+session.on(SessionIdleEvent.class, idle -> {
+    done.complete(null);
+});
+
+session.send("Tell me a joke").get();
+done.get(); // Wait for completion
+```
+
+You can also use a single handler for all events:
+
+```java
+session.on(event -> {
+    switch (event) {
+        case AssistantMessageEvent msg -> 
+            System.out.println("Response: " + msg.getData().content());
+        case SessionErrorEvent err -> 
+            System.err.println("Error: " + err.getData().message());
+        case SessionIdleEvent idle -> 
+            done.complete(null);
+        default -> { }
+    }
+});
+```
+
+### Key Event Types
+
+| Event | Description |
+|-------|-------------|
+| `AssistantMessageEvent` | Complete assistant response |
+| `AssistantMessageDeltaEvent` | Streaming chunk (when streaming enabled) |
+| `SessionIdleEvent` | Session finished processing |
+| `SessionErrorEvent` | An error occurred |
+
+For the complete list of all event types, see [Event Types Reference](#Event_Types_Reference) below.
+
+---
+
+## Event Types Reference
+
+The SDK supports event types organized by category. All events extend `SessionEvent`.
+
+### Session Events
+
+| Event | Type String | Description |
+|-------|-------------|-------------|
+| `SessionStartEvent` | `session.start` | Session has started |
+| `SessionResumeEvent` | `session.resume` | Session was resumed |
+| `SessionIdleEvent` | `session.idle` | Session finished processing, ready for input |
+| `SessionErrorEvent` | `session.error` | An error occurred in the session |
+| `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 |
+| `SessionUsageInfoEvent` | `session.usage_info` | Token usage information |
+| `SessionCompactionStartEvent` | `session.compaction_start` | Context compaction started (infinite sessions) |
+| `SessionCompactionCompleteEvent` | `session.compaction_complete` | Context compaction completed |
+| `SessionContextChangedEvent` | `session.context_changed` | Working directory context changed |
+| `SessionTaskCompleteEvent` | `session.task_complete` | Task completed with summary |
+
+### Assistant Events
+
+| Event | Type String | Description |
+|-------|-------------|-------------|
+| `AssistantTurnStartEvent` | `assistant.turn_start` | Assistant began processing |
+| `AssistantIntentEvent` | `assistant.intent` | Assistant's detected intent |
+| `AssistantReasoningEvent` | `assistant.reasoning` | Full reasoning content (reasoning models) |
+| `AssistantReasoningDeltaEvent` | `assistant.reasoning_delta` | Streaming reasoning chunk |
+| `AssistantMessageEvent` | `assistant.message` | Complete assistant message |
+| `AssistantMessageDeltaEvent` | `assistant.message_delta` | Streaming message chunk |
+| `AssistantStreamingDeltaEvent` | `assistant.streaming_delta` | Streaming progress with size metrics |
+| `AssistantTurnEndEvent` | `assistant.turn_end` | Assistant finished processing |
+| `AssistantUsageEvent` | `assistant.usage` | Token usage for this turn |
+
+### Tool Events
+
+| Event | Type String | Description |
+|-------|-------------|-------------|
+| `ToolUserRequestedEvent` | `tool.user_requested` | User requested a tool invocation |
+| `ToolExecutionStartEvent` | `tool.execution_start` | Tool execution started |
+| `ToolExecutionProgressEvent` | `tool.execution_progress` | Tool execution progress update |
+| `ToolExecutionPartialResultEvent` | `tool.execution_partial_result` | Partial result from tool |
+| `ToolExecutionCompleteEvent` | `tool.execution_complete` | Tool execution completed |
+
+### User Events
+
+| Event | Type String | Description |
+|-------|-------------|-------------|
+| `UserMessageEvent` | `user.message` | User sent a message |
+| `PendingMessagesModifiedEvent` | `pending_messages.modified` | Pending message queue changed |
+
+### Subagent Events
+
+| Event | Type String | Description |
+|-------|-------------|-------------|
+| `SubagentStartedEvent` | `subagent.started` | Subagent was spawned |
+| `SubagentSelectedEvent` | `subagent.selected` | Subagent was selected for task |
+| `SubagentDeselectedEvent` | `subagent.deselected` | Subagent was deselected |
+| `SubagentCompletedEvent` | `subagent.completed` | Subagent completed its task |
+| `SubagentFailedEvent` | `subagent.failed` | Subagent failed |
+
+### Other Events
+
+| Event | Type String | Description |
+|-------|-------------|-------------|
+| `AbortEvent` | `abort` | Operation was aborted |
+| `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 |
+| `CommandExecuteEvent` | `command.execute` | A registered slash command was dispatched for execution |
+
+### Elicitation Events
+
+| Event | Type String | Description |
+|-------|-------------|-------------|
+| `ElicitationRequestedEvent` | `elicitation.requested` | An elicitation (UI dialog) request was received |
+
+### Capability Events
+
+| Event | Type String | Description |
+|-------|-------------|-------------|
+| `CapabilitiesChangedEvent` | `capabilities.changed` | Session capabilities were updated |
+
+### 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 [generated package Javadoc](apidocs/com/github/copilot/generated/package-summary.html) for detailed event data structures.
+
+---
+
+## Streaming Responses
+
+Enable streaming to receive response chunks as they're generated:
+
+```java
+var session = client.createSession(
+    new SessionConfig().setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
+        .setModel("gpt-4.1")
+        .setStreaming(true)
+).get();
+
+var done = new CompletableFuture<Void>();
+
+session.on(AssistantMessageDeltaEvent.class, delta -> {
+    // Print each chunk as it arrives
+    System.out.print(delta.getData().deltaContent());
+});
+
+session.on(SessionIdleEvent.class, idle -> {
+    System.out.println(); // Newline at end
+    done.complete(null);
+});
+
+session.send("Write a haiku about Java").get();
+done.get();
+```
+
+---
+
+## Session Operations
+
+### Get Conversation History
+
+Retrieve all messages and events from a session using `getMessages()`:
+
+```java
+var history = session.getMessages().get();
+
+for (var event : history) {
+    switch (event) {
+        case UserMessageEvent user -> 
+            System.out.println("User: " + user.getData().content());
+        case AssistantMessageEvent assistant -> 
+            System.out.println("Assistant: " + assistant.getData().content());
+        case ToolExecutionCompleteEvent tool -> 
+            System.out.println("Tool: " + tool.getData().toolCallId());
+        default -> { }
+    }
+}
+```
+
+This is useful for:
+- Displaying conversation history in a UI
+- Persisting conversations for later review
+- Debugging and logging session state
+
+### Abort Current Operation
+
+Cancel a long-running operation using `abort()`:
+
+```java
+// Start a potentially long operation
+var messageFuture = session.send("Analyze this large codebase...");
+
+// User clicks cancel button
+session.abort().get();
+
+// The session will emit an AbortEvent
+session.on(AbortEvent.class, evt -> {
+    System.out.println("Operation was cancelled");
+});
+```
+
+Use cases:
+- User-initiated cancellation in interactive applications
+- Timeout handling in automated pipelines
+- Graceful shutdown when application is closing
+
+### Custom Timeout
+
+Use `sendAndWait` with a custom timeout for CI/CD pipelines:
+
+```java
+try {
+    // 30-second timeout
+    var response = session.sendAndWait(
+        new MessageOptions().setPrompt("Quick question"),
+        30000  // timeout in milliseconds
+    ).get();
+} catch (ExecutionException e) {
+    if (e.getCause() instanceof TimeoutException) {
+        System.err.println("Request timed out");
+        session.abort().get();
+    }
+}
+```
+
+---
+
+## Choosing a Model
+
+### List Available Models
+
+Query available models before creating a session:
+
+```java
+var models = client.listModels().get();
+
+for (var model : models) {
+    System.out.printf("%s (%s)%n", model.getId(), model.getName());
+}
+```
+
+### Use a Specific Model
+
+```java
+var session = client.createSession(
+    new SessionConfig().setOnPermissionRequest(PermissionHandler.APPROVE_ALL).setModel("claude-sonnet-4")
+).get();
+```
+
+---
+
+## Reasoning Effort
+
+For models that support it, control how much effort the model spends reasoning before responding:
+
+```java
+var session = client.createSession(
+    new SessionConfig().setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
+        .setModel("o3-mini")
+        .setReasoningEffort("high")
+).get();
+```
+
+| Level | Description |
+|-------|-------------|
+| `"low"` | Fastest responses, less detailed reasoning |
+| `"medium"` | Balanced speed and reasoning depth |
+| `"high"` | Thorough reasoning, slower responses |
+| `"xhigh"` | Maximum reasoning effort |
+
+> **Note:** Only applies to reasoning models (e.g., `o3-mini`). Non-reasoning models ignore this setting.
+
+---
+
+## Tool Filtering
+
+Control which built-in tools the assistant can use with allowlists and blocklists.
+
+### Allowlist (Available Tools)
+
+Restrict the session to only specific tools:
+
+```java
+var session = client.createSession(
+    new SessionConfig().setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
+        .setAvailableTools(List.of("read_file", "search_code", "list_dir"))
+).get();
+```
+
+When `availableTools` is set, the assistant can **only** use tools in this list.
+
+### Blocklist (Excluded Tools)
+
+Allow all tools except specific ones:
+
+```java
+var session = client.createSession(
+    new SessionConfig().setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
+        .setExcludedTools(List.of("execute_command", "write_file"))
+).get();
+```
+
+Tools in the `excludedTools` list will not be available to the assistant.
+
+### Combining with Custom Tools
+
+Tool filtering applies to built-in tools. Your custom tools (registered via `setTools()`) are always available:
+
+```java
+var lookupTool = ToolDefinition.create("lookup_issue", "Fetch issue", schema, handler);
+
+var session = client.createSession(
+    new SessionConfig().setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
+        .setTools(List.of(lookupTool))           // Custom tool always available
+        .setAvailableTools(List.of("read_file")) // Only allow read_file from built-ins
+).get();
+```
+
+---
+
+## Working Directory
+
+Set the working directory for file operations in the session:
+
+```java
+var session = client.createSession(
+    new SessionConfig().setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
+        .setWorkingDirectory("/path/to/project")
+).get();
+```
+
+This affects how the assistant resolves relative file paths when using tools like `read_file`, `write_file`, and `search_code`.
+
+---
+
+## Connection State & Diagnostics
+
+### Checking Connection State
+
+Query the client's connection state at any time without making a server call:
+
+```java
+ConnectionState state = client.getState();
+switch (state) {
+    case CONNECTED -> System.out.println("Ready");
+    case CONNECTING -> System.out.println("Starting up...");
+    case DISCONNECTED -> System.out.println("Not connected");
+    case ERROR -> System.out.println("Connection failed");
+}
+```
+
+The four states are:
+
+| State | Description |
+|-------|-------------|
+| `DISCONNECTED` | Client has not been started yet |
+| `CONNECTING` | `start()` was called but hasn't completed |
+| `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:
+
+```java
+var status = client.getStatus().get();
+System.out.println("CLI version: " + status.getVersion());
+System.out.println("Protocol version: " + status.getProtocolVersion());
+```
+
+### Authentication Status
+
+Check whether the current connection is authenticated and how:
+
+```java
+var auth = client.getAuthStatus().get();
+if (auth.isAuthenticated()) {
+    System.out.println("Logged in as: " + auth.getLogin());
+    System.out.println("Auth type: " + auth.getAuthType());
+    System.out.println("Host: " + auth.getHost());
+} else {
+    System.out.println("Not authenticated: " + auth.getStatusMessage());
+}
+```
+
+### Ping
+
+Verify server connectivity:
+
+```java
+var pong = client.ping("hello").get();
+System.out.println("Server responded, protocol version: " + pong.protocolVersion());
+```
+
+See [ConnectionState](apidocs/com/github/copilot/ConnectionState.html), [GetStatusResponse](apidocs/com/github/copilot/rpc/GetStatusResponse.html), and [GetAuthStatusResponse](apidocs/com/github/copilot/rpc/GetAuthStatusResponse.html) Javadoc for details.
+
+---
+
+## Message Delivery Mode
+
+Control how messages are delivered to the session:
+
+```java
+// Default: message is enqueued for processing
+session.send(new MessageOptions()
+    .setPrompt("Analyze this codebase")
+).get();
+
+// Immediate: process the message right away
+session.send(new MessageOptions()
+    .setPrompt("Quick question")
+    .setMode("immediate")
+).get();
+```
+
+| Mode | Description |
+|------|-------------|
+| `"enqueue"` | Queue the message for processing (default) |
+| `"immediate"` | Process the message immediately |
+
+---
+
+## Session Management
+
+### Multiple Concurrent Sessions
+
+```java
+var session1 = client.createSession(
+    new SessionConfig().setOnPermissionRequest(PermissionHandler.APPROVE_ALL).setModel("gpt-4.1")
+).get();
+
+var session2 = client.createSession(
+    new SessionConfig().setOnPermissionRequest(PermissionHandler.APPROVE_ALL).setModel("claude-sonnet-4")
+).get();
+
+// Send messages concurrently
+var future1 = session1.sendAndWait("Summarize REST APIs");
+var future2 = session2.sendAndWait("Summarize GraphQL");
+
+System.out.println("GPT: " + future1.get().getData().content());
+System.out.println("Claude: " + future2.get().getData().content());
+```
+
+### Resume a Previous Session
+
+```java
+// Get the last session ID
+var lastSessionId = client.getLastSessionId().get();
+
+// Or list all sessions
+var sessions = client.listSessions().get();
+
+// Resume a session
+var session = client.resumeSession(lastSessionId, new ResumeSessionConfig().setOnPermissionRequest(PermissionHandler.APPROVE_ALL)).get();
+```
+
+### Resume Options
+
+When resuming a session, you can optionally reconfigure many settings. This is useful when you need to change the model, update tool configurations, or modify behavior.
+
+| Option | Description |
+|--------|-------------|
+| `model` | Change the model for the resumed session |
+| `systemMessage` | Override or extend the system prompt |
+| `availableTools` | Restrict which tools are available |
+| `excludedTools` | Disable specific tools |
+| `provider` | Re-provide BYOK credentials (required for BYOK sessions) |
+| `reasoningEffort` | Adjust reasoning effort level |
+| `streaming` | Enable/disable streaming responses |
+| `workingDirectory` | Change the working directory |
+| `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 |
+| `commands` | Slash command definitions for the resumed session |
+| `onElicitationRequest` | Handler for incoming elicitation requests |
+| `disableResume` | When `true`, resumes without emitting a `session.resume` event |
+| `onEvent` | Event handler registered before session resumption |
+
+**Example: Changing Model on Resume**
+
+```java
+// Resume with a different model
+var config = new ResumeSessionConfig().setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
+    .setModel("claude-sonnet-4")    // Switch to a different model
+    .setReasoningEffort("high");    // Increase reasoning effort
+
+var session = client.resumeSession("user-123-task-456", config).get();
+```
+
+See [ResumeSessionConfig](apidocs/com/github/copilot/rpc/ResumeSessionConfig.html) Javadoc for complete options.
+
+### Clean Up Sessions
+
+Closing a session releases its in-memory resources but **preserves session data on disk**, so
+it can be resumed later. Use `deleteSession()` to permanently remove session data from disk:
+
+```java
+// Close a session (releases in-memory resources; session can be resumed later)
+session.close();
+
+// Permanently delete a session and all its data from disk (cannot be resumed)
+client.deleteSession(sessionId).get();
+```
+
+---
+
+## SessionConfig Reference
+
+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&lt;ToolDefinition&gt; | Custom tools the assistant can invoke | [Custom Tools](advanced.html#Custom_Tools) |
+| `systemMessage` | SystemMessageConfig | Customize assistant behavior | [System Messages](advanced.html#System_Messages) |
+| `availableTools` | List&lt;String&gt; | Allowlist of built-in tool names | [Tool Filtering](#Tool_Filtering) |
+| `excludedTools` | List&lt;String&gt; | Blocklist of built-in tool names | [Tool Filtering](#Tool_Filtering) |
+| `provider` | ProviderConfig | BYOK API provider configuration | [BYOK](advanced.html#Bring_Your_Own_Key_BYOK) |
+| `onPermissionRequest` | PermissionHandler | Handler for permission requests | [Permission Handling](advanced.html#Permission_Handling) |
+| `onUserInputRequest` | UserInputHandler | Handler for user input requests | [User Input Handling](advanced.html#User_Input_Handling) |
+| `hooks` | SessionHooks | Lifecycle and tool execution hooks | [Session Hooks](hooks.html) |
+| `workingDirectory` | String | Working directory for file operations | [Working Directory](#Working_Directory) |
+| `streaming` | boolean | Enable streaming response chunks | [Streaming Responses](#Streaming_Responses) |
+| `mcpServers` | Map&lt;String, Object&gt; | MCP server configurations | [MCP Servers](mcp.html) |
+| `customAgents` | List&lt;CustomAgentConfig&gt; | 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&lt;String&gt; | Directories to load skills from | [Skills](advanced.html#Skills_Configuration) |
+| `disabledSkills` | List&lt;String&gt; | Skills to disable by name | [Skills](advanced.html#Skills_Configuration) |
+| `configDir` | String | Custom configuration directory | [Config Dir](advanced.html#Custom_Configuration_Directory) |
+| `commands` | List&lt;CommandDefinition&gt; | Slash command definitions | [Slash Commands](advanced.html#Slash_Commands) |
+| `onElicitationRequest` | ElicitationHandler | Handler for incoming elicitation requests | [Elicitation](advanced.html#Elicitation_UI_Dialogs) |
+| `onEvent` | Consumer&lt;SessionEvent&gt; | Event handler registered before session creation | [Early Event Registration](advanced.html#Early_Event_Registration) |
+
+### Cloning SessionConfig
+
+Use `clone()` to copy a base configuration before making per-session changes:
+
+```java
+var base = new SessionConfig().setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
+    .setModel("gpt-4.1")
+    .setStreaming(true);
+
+var derived = base.clone()
+    .setWorkingDirectory("/repo-a");
+```
+
+`clone()` creates a shallow copy. Collection fields are copied into new collection instances, while nested objects/handlers are shared references.
+
+See [SessionConfig](apidocs/com/github/copilot/rpc/SessionConfig.html) Javadoc for full details.
+
+---
+
+## Next Steps
+
+- 📖 **[Advanced Usage](advanced.html)** - Tools, BYOK, MCP Servers, System Messages, Infinite Sessions, Skills
+- 📖 **[Session Hooks](hooks.html)** - Intercept tool execution and session lifecycle events
+- 📖 **[MCP Servers](mcp.html)** - Integrate external tools via Model Context Protocol
+- 📖 **[API Javadoc](apidocs/index.html)** - Complete API reference
diff --git a/src/site/markdown/getting-started.md b/src/site/markdown/getting-started.md
new file mode 100644
index 0000000000..0bde2ef50d
--- /dev/null
+++ b/src/site/markdown/getting-started.md
@@ -0,0 +1,378 @@
+!# Build Your First Copilot-Powered App
+
+In this tutorial, you'll use the GitHub Copilot SDK for Java to build a command-line assistant. You'll start with the basics, add streaming responses, then add custom tools - giving Copilot the ability to call your code.
+
+**What you'll build:**
+
+```
+You: What's the weather like in Seattle?
+Copilot: Let me check the weather for Seattle...
+         Currently 62°F and cloudy with a chance of rain.
+         Typical Seattle weather!
+
+You: How about Tokyo?
+Copilot: In Tokyo it's 75°F and sunny. Great day to be outside!
+```
+
+## Prerequisites
+
+Before you begin, make sure you have:
+
+- **Java 17+** installed
+- **GitHub Copilot CLI** installed and authenticated ([Installation guide](https://docs.github.com/en/copilot/how-tos/set-up/install-copilot-cli))
+
+Verify the CLI is working:
+
+```bash
+copilot --version
+```
+
+## Step 1: Install the SDK
+
+> If you want to test a _-SNAPSHOT_ version, you may have to clone the project's repository and install the library locally with _mvn install_.
+
+### Apache Maven
+
+Add the dependency to your `pom.xml`:
+
+```xml
+<dependency>
+    <groupId>com.github</groupId>
+    <artifactId>copilot-sdk-java</artifactId>
+    <version>${project.version}</version>
+</dependency>
+```
+
+### Gradle
+
+Add the dependency to your `build.gradle`:
+
+```groovy
+implementation 'com.github:copilot-sdk-java:${project.version}'
+```
+
+### JBang (Quick Start)
+
+For the fastest way to try the SDK without setting up a project, use [JBang](https://www.jbang.dev/). Create a file named `HelloCopilot.java` with the following header, and then proceed to Step 2 by appending the proposed content into this same file.
+
+```bash
+//DEPS com.github:copilot-sdk-java:${project.version}
+```
+
+## Step 2: Send Your First Message
+
+Create a new file and add the following code. This is the simplest way to use the SDK.
+
+```java
+import com.github.copilot.CopilotClient;
+import com.github.copilot.rpc.MessageOptions;
+import com.github.copilot.rpc.PermissionHandler;
+import com.github.copilot.rpc.SessionConfig;
+
+public class HelloCopilot {
+    public static void main(String[] args) throws Exception {
+        try (var client = new CopilotClient()) {
+            client.start().get();
+            
+            var session = client.createSession(
+                new SessionConfig().setOnPermissionRequest(PermissionHandler.APPROVE_ALL).setModel("gpt-4.1")
+            ).get();
+
+            var response = session.sendAndWait(
+                new MessageOptions().setPrompt("What is 2 + 2?")
+            ).get();
+
+            System.out.println(response.getData().content());
+        }
+    }
+}
+```
+
+Run the code with your preferred build tool or IDE. 
+
+Or run it directly with JBang:
+
+```bash
+jbang HelloCopilot.java
+```
+
+**You should see:**
+
+```
+2 + 2 = 4
+```
+
+Congratulations! You just built your first Copilot-powered app.
+
+## Step 3: Add Streaming Responses
+
+Right now, you wait for the complete response before seeing anything. Let's make it interactive by streaming the response as it's generated.
+
+```java
+import com.github.copilot.CopilotClient;
+import com.github.copilot.generated.AssistantMessageDeltaEvent;
+import com.github.copilot.generated.SessionIdleEvent;
+import com.github.copilot.rpc.MessageOptions;
+import com.github.copilot.rpc.PermissionHandler;
+import com.github.copilot.rpc.SessionConfig;
+import java.util.concurrent.CompletableFuture;
+
+public class StreamingExample {
+    public static void main(String[] args) throws Exception {
+        try (var client = new CopilotClient()) {
+            client.start().get();
+            
+            var session = client.createSession(
+                new SessionConfig().setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
+                    .setModel("gpt-4.1")
+                    .setStreaming(true)
+            ).get();
+
+            var done = new CompletableFuture<Void>();
+
+            // Listen for response chunks
+            session.on(AssistantMessageDeltaEvent.class, delta -> {
+                System.out.print(delta.getData().deltaContent());
+            });
+            session.on(SessionIdleEvent.class, idle -> {
+                System.out.println(); // New line when done
+                done.complete(null);
+            });
+
+            session.send(
+                new MessageOptions().setPrompt("Tell me a short joke")
+            ).get();
+            
+            done.get(); // Wait for completion
+        }
+    }
+}
+```
+
+Run the code again. You'll see the response appear word by word.
+
+## Step 4: Add a Custom Tool
+
+Now for the powerful part. Let's give Copilot the ability to call your code by defining a custom tool. We'll create a simple weather lookup tool.
+
+```java
+import com.github.copilot.CopilotClient;
+import com.github.copilot.generated.AssistantMessageDeltaEvent;
+import com.github.copilot.generated.SessionIdleEvent;
+import com.github.copilot.rpc.MessageOptions;
+import com.github.copilot.rpc.PermissionHandler;
+import com.github.copilot.rpc.SessionConfig;
+import com.github.copilot.rpc.ToolDefinition;
+import java.util.List;
+import java.util.Map;
+import java.util.Random;
+import java.util.concurrent.CompletableFuture;
+
+public class ToolExample {
+    public static void main(String[] args) throws Exception {
+        try (var client = new CopilotClient()) {
+            client.start().get();
+
+            // Define a tool that Copilot can call
+            var getWeather = ToolDefinition.create(
+                "get_weather",
+                "Get the current weather for a city",
+                Map.of(
+                    "type", "object",
+                    "properties", Map.of(
+                        "city", Map.of(
+                            "type", "string",
+                            "description", "The city name"
+                        )
+                    ),
+                    "required", List.of("city")
+                ),
+                invocation -> {
+                    var params = invocation.getArguments();
+                    var city = (String) params.get("city");
+                    
+                    // In a real app, you'd call a weather API here
+                    String[] conditions = {"sunny", "cloudy", "rainy", "partly cloudy"};
+                    int temp = new Random().nextInt(30) + 50;
+                    var condition = conditions[new Random().nextInt(conditions.length)];
+                    
+                    return CompletableFuture.completedFuture(Map.of(
+                        "city", city,
+                        "temperature", temp + "°F",
+                        "condition", condition
+                    ));
+                }
+            );
+
+            var session = client.createSession(
+                new SessionConfig().setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
+                    .setModel("gpt-4.1")
+                    .setStreaming(true)
+                    .setTools(List.of(getWeather))
+            ).get();
+
+            var done = new CompletableFuture<Void>();
+
+            session.on(AssistantMessageDeltaEvent.class, delta -> {
+                System.out.print(delta.getData().deltaContent());
+            });
+            session.on(SessionIdleEvent.class, idle -> {
+                System.out.println();
+                done.complete(null);
+            });
+
+            session.send(
+                new MessageOptions().setPrompt("What's the weather like in Seattle and Tokyo?")
+            ).get();
+            
+            done.get();
+        }
+    }
+}
+```
+
+Run it and you'll see Copilot call your tool to get weather data, then respond with the results!
+
+## Step 5: Build an Interactive Assistant
+
+Let's put it all together into a useful interactive assistant:
+
+```java
+import com.github.copilot.CopilotClient;
+import com.github.copilot.generated.AssistantMessageDeltaEvent;
+import com.github.copilot.generated.SessionIdleEvent;
+import com.github.copilot.rpc.MessageOptions;
+import com.github.copilot.rpc.PermissionHandler;
+import com.github.copilot.rpc.SessionConfig;
+import com.github.copilot.rpc.ToolDefinition;
+import java.util.List;
+import java.util.Map;
+import java.util.Random;
+import java.util.Scanner;
+import java.util.concurrent.CompletableFuture;
+import java.util.concurrent.atomic.AtomicReference;
+
+public class WeatherAssistant {
+    public static void main(String[] args) throws Exception {
+        try (var client = new CopilotClient();
+             var scanner = new Scanner(System.in)) {
+            
+            client.start().get();
+
+            var getWeather = ToolDefinition.create(
+                "get_weather",
+                "Get the current weather for a city",
+                Map.of(
+                    "type", "object",
+                    "properties", Map.of(
+                        "city", Map.of(
+                            "type", "string",
+                            "description", "The city name"
+                        )
+                    ),
+                    "required", List.of("city")
+                ),
+                invocation -> {
+                    var params = invocation.getArguments();
+                    var city = (String) params.get("city");
+                    String[] conditions = {"sunny", "cloudy", "rainy", "partly cloudy"};
+                    int temp = new Random().nextInt(30) + 50;
+                    var condition = conditions[new Random().nextInt(conditions.length)];
+                    return CompletableFuture.completedFuture(Map.of(
+                        "city", city,
+                        "temperature", temp + "°F",
+                        "condition", condition
+                    ));
+                }
+            );
+
+            var session = client.createSession(
+                new SessionConfig().setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
+                    .setModel("gpt-4.1")
+                    .setStreaming(true)
+                    .setTools(List.of(getWeather))
+            ).get();
+
+            System.out.println("🌤️  Weather Assistant (type 'exit' to quit)");
+            System.out.println("   Try: 'What's the weather in Paris?'\n");
+
+            var done = new AtomicReference<CompletableFuture<Void>>();
+
+            // Register listener once, outside the loop
+            session.on(AssistantMessageDeltaEvent.class, delta -> {
+                System.out.print(delta.getData().deltaContent());
+            });
+            session.on(SessionIdleEvent.class, idle -> {
+                System.out.println();
+                var f = done.get();
+                if (f != null) f.complete(null);
+            });
+
+            while (true) {
+                System.out.print("You: ");
+                String input = scanner.nextLine();
+                
+                if ("exit".equalsIgnoreCase(input.trim())) {
+                    break;
+                }
+
+                done.set(new CompletableFuture<>());
+
+                System.out.print("Assistant: ");
+                session.send(new MessageOptions().setPrompt(input)).get();
+                done.get().get();
+            }
+        }
+    }
+}
+```
+
+## What's Next?
+
+You've learned the core concepts of the Copilot SDK:
+
+- ✅ Creating a client and session
+- ✅ Sending messages and receiving responses
+- ✅ Streaming for real-time output
+- ✅ Custom tools for extending Copilot's capabilities
+- ✅ Building interactive applications
+
+**Explore more:**
+
+- [Documentation](documentation.html) - Basic usage and session management
+- [Advanced Usage](advanced.html) - Tools, BYOK, infinite sessions, and more
+- [MCP Servers](mcp.html) - Connect to Model Context Protocol servers
+
+## Troubleshooting
+
+### "Copilot CLI not found"
+
+Make sure the GitHub Copilot CLI is installed and in your PATH:
+
+```bash
+copilot --version
+```
+
+If not installed, follow the [GitHub Copilot CLI installation guide](https://docs.github.com/en/copilot/how-tos/set-up/install-copilot-cli).
+
+### "Authentication failed"
+
+The CLI needs to be authenticated with your GitHub account:
+
+```bash
+copilot auth login
+```
+
+### "Connection timeout"
+
+Check your internet connection and firewall settings. The SDK communicates with GitHub's Copilot service.
+
+---
+
+## Next Steps
+
+- 📖 **[Documentation](documentation.html)** - Core concepts, events, streaming, session management
+- 📖 **[Advanced Usage](advanced.html)** - Tools, BYOK, MCP Servers, System Messages, Custom Agents
+- 📖 **[Session Hooks](hooks.html)** - Intercept tool execution and session lifecycle events
+- 📖 **[Setup & Deployment](setup.html)** - OAuth, backend services, scaling
+- 📖 **[API Javadoc](apidocs/index.html)** - Complete API reference
diff --git a/src/site/markdown/hooks.md b/src/site/markdown/hooks.md
new file mode 100644
index 0000000000..3bed031df8
--- /dev/null
+++ b/src/site/markdown/hooks.md
@@ -0,0 +1,475 @@
+# Session Hooks
+
+Session hooks allow you to intercept and modify tool execution, user prompts, and session lifecycle events. Use hooks to implement custom logic like logging, security controls, or context injection.
+
+---
+
+## Overview
+
+| Hook | When It's Called | Can Modify |
+|------|------------------|------------|
+| [Pre-Tool Use](#Pre-Tool_Use_Hook) | Before a tool executes | Tool arguments, permission decision |
+| [Pre-MCP-Tool-Call](#Pre-MCP-Tool-Call_Hook) | Before an MCP tool call is dispatched | MCP request metadata (`_meta`) |
+| [Post-Tool Use](#Post-Tool_Use_Hook) | After a tool executes | Tool result, additional context |
+| [User Prompt Submitted](#User_Prompt_Submitted_Hook) | When user sends a message | Nothing (observation only) |
+| [Session Start](#Session_Start_Hook) | When session begins | Nothing (observation only) |
+| [Session End](#Session_End_Hook) | When session ends | Nothing (observation only) |
+| [Checking Whether Hooks Are Registered](#Checking_Whether_Hooks_Are_Registered) | Before session creation | Whether any handlers are configured |
+
+---
+
+## Quick Start
+
+Register hooks when creating a session:
+
+```java
+var hooks = new SessionHooks()
+    .setOnPreToolUse((input, invocation) -> {
+        System.out.println("Tool: " + input.getToolName());
+        return CompletableFuture.completedFuture(PreToolUseHookOutput.allow());
+    })
+    .setOnPostToolUse((input, invocation) -> {
+        System.out.println("Result: " + input.getToolResult());
+        return CompletableFuture.completedFuture(null);
+    });
+
+var session = client.createSession(
+    new SessionConfig().setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
+        .setModel("gpt-4.1")
+        .setHooks(hooks)
+).get();
+```
+
+---
+
+## Pre-Tool Use Hook
+
+Called **before** a tool executes. Use this to:
+- Approve, deny, or prompt for tool execution
+- Modify tool arguments
+- Add context for the LLM
+- Suppress tool output from being shown
+
+### Input
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `getSessionId()` | `String` | Runtime session ID of the session that triggered the hook |
+| `getToolName()` | `String` | Name of the tool being called |
+| `getToolArgs()` | `JsonNode` | Arguments passed to the tool |
+| `getCwd()` | `String` | Current working directory |
+| `getTimestamp()` | `long` | Timestamp in milliseconds |
+
+### Output
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `setPermissionDecision(String)` | `"allow"`, `"deny"`, `"ask"` | Whether to execute the tool |
+| `setPermissionDecisionReason(String)` | `String` | Reason shown to user/LLM |
+| `setModifiedArgs(JsonNode)` | `JsonNode` | Modified arguments (optional) |
+| `setAdditionalContext(String)` | `String` | Extra context for the LLM |
+| `setSuppressOutput(Boolean)` | `Boolean` | Hide output from display |
+
+### Example: Security Gate
+
+Block dangerous tool calls:
+
+```java
+var hooks = new SessionHooks()
+    .setOnPreToolUse((input, invocation) -> {
+        String tool = input.getToolName();
+        
+        // Block file deletion
+        if (tool.equals("delete_file")) {
+            return CompletableFuture.completedFuture(
+                PreToolUseHookOutput.deny("File deletion is not allowed")
+            );
+        }
+        
+        // Require confirmation for shell commands
+        if (tool.equals("run_terminal_cmd")) {
+            return CompletableFuture.completedFuture(PreToolUseHookOutput.ask());
+        }
+        
+        // Allow everything else
+        return CompletableFuture.completedFuture(PreToolUseHookOutput.allow());
+    });
+```
+
+### Example: Argument Modification
+
+Inject context into tool arguments:
+
+```java
+var hooks = new SessionHooks()
+    .setOnPreToolUse((input, invocation) -> {
+        if (input.getToolName().equals("search_code")) {
+            // Add project root to search path
+            var mapper = new ObjectMapper();
+            var modifiedArgs = mapper.createObjectNode();
+            modifiedArgs.put("path", "/my/project/src");
+            modifiedArgs.set("query", input.getToolArgs().get("query"));
+            
+            return CompletableFuture.completedFuture(
+                PreToolUseHookOutput.withModifiedArgs("allow", modifiedArgs)
+            );
+        }
+        return CompletableFuture.completedFuture(PreToolUseHookOutput.allow());
+    });
+```
+
+---
+
+## Pre-MCP-Tool-Call Hook
+
+Called **before** an MCP tool call is dispatched to an MCP server. Use this to:
+- Inspect or log MCP tool calls
+- Set, replace, or remove MCP request metadata (`_meta`)
+
+### Input
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `getSessionId()` | `String` | Runtime session ID of the session that triggered the hook |
+| `getTimestamp()` | `long` | Unix timestamp in milliseconds |
+| `getCwd()` | `String` | Current working directory |
+| `getServerName()` | `String` | Name of the MCP server being called |
+| `getToolName()` | `String` | Name of the MCP tool being called |
+| `getArguments()` | `JsonNode` | Arguments for the MCP tool call |
+| `getToolCallId()` | `String` | Tool call ID (may be null) |
+| `getMeta()` | `Map<String, JsonNode>` | Existing MCP request metadata (may be null) |
+
+### Output
+
+Return `null` from the handler to preserve existing `_meta` (no-op). Otherwise, return a `PreMcpToolCallHookOutput`:
+
+| Factory Method | Effect |
+|----------------|--------|
+| `PreMcpToolCallHookOutput.withMeta(jsonNode)` | Replace `_meta` with the given JSON object |
+| `PreMcpToolCallHookOutput.removeMeta()` | Remove `_meta` from the request |
+
+### Example: Inject metadata into MCP requests
+
+```java
+var hooks = new SessionHooks()
+    .setOnPreMcpToolCall((input, invocation) -> {
+        System.out.println("MCP call: " + input.getServerName() + "/" + input.getToolName());
+        
+        // Inject custom metadata into the MCP request
+        var mapper = new ObjectMapper();
+        JsonNode meta = mapper.valueToTree(Map.of(
+            "source", "my-application",
+            "requestId", UUID.randomUUID().toString()
+        ));
+        return CompletableFuture.completedFuture(PreMcpToolCallHookOutput.withMeta(meta));
+    });
+```
+
+---
+
+## Post-Tool Use Hook
+
+Called **after** a tool executes. Use this to:
+- Log tool results
+- Modify the result shown to the LLM
+- Add additional context based on results
+- Suppress output from display
+
+### Input
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `getSessionId()` | `String` | Runtime session ID of the session that triggered the hook |
+| `getToolName()` | `String` | Name of the tool that was called |
+| `getToolArgs()` | `JsonNode` | Arguments that were passed |
+| `getToolResult()` | `JsonNode` | Result from the tool |
+| `getCwd()` | `String` | Current working directory |
+| `getTimestamp()` | `long` | Timestamp in milliseconds |
+
+### Output
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `setModifiedResult(String)` | `String` | Modified result for the LLM |
+| `setAdditionalContext(String)` | `String` | Extra context for the LLM |
+| `setSuppressOutput(Boolean)` | `Boolean` | Hide output from display |
+
+### Example: Result Logging
+
+Log all tool executions:
+
+```java
+var hooks = new SessionHooks()
+    .setOnPostToolUse((input, invocation) -> {
+        System.out.printf("[%d] %s completed%n", 
+            input.getTimestamp(), 
+            input.getToolName());
+        System.out.println("Result: " + input.getToolResult());
+        
+        return CompletableFuture.completedFuture(null);
+    });
+```
+
+### Example: Result Enrichment
+
+Add context to file read results:
+
+```java
+var hooks = new SessionHooks()
+    .setOnPostToolUse((input, invocation) -> {
+        if (input.getToolName().equals("read_file")) {
+            String context = "Note: This file was last modified 2 hours ago.";
+            return CompletableFuture.completedFuture(
+                new PostToolUseHookOutput(null, context, null)
+            );
+        }
+        return CompletableFuture.completedFuture(null);
+    });
+```
+
+---
+
+## User Prompt Submitted Hook
+
+Called when the user submits a prompt, before the LLM processes it. This is an observation hook - you cannot modify the prompt.
+
+### Input
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `sessionId()` | `String` | Runtime session ID of the session that triggered the hook |
+| `prompt()` | `String` | The user's prompt text |
+| `timestamp()` | `long` | Timestamp in milliseconds |
+
+### Output
+
+Return `null` - this hook is observation-only.
+
+### Example: Prompt Logging
+
+```java
+var hooks = new SessionHooks()
+    .setOnUserPromptSubmitted((input, invocation) -> {
+        System.out.println("User asked: " + input.prompt());
+        
+        // Track prompts for analytics
+        analytics.track("user_prompt", Map.of(
+            "sessionId", invocation.getSessionId(),
+            "promptLength", input.prompt().length()
+        ));
+        
+        return CompletableFuture.completedFuture(null);
+    });
+```
+
+---
+
+## Session Start Hook
+
+Called when a session starts (either new or resumed).
+
+### Input
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `sessionId()` | `String` | Runtime session ID of the session that triggered the hook |
+| `source()` | `String` | `"startup"`, `"resume"`, or `"new"` |
+| `timestamp()` | `long` | Timestamp in milliseconds |
+
+### Output
+
+Return `null` - this hook is observation-only.
+
+### Example: Session Initialization
+
+```java
+var hooks = new SessionHooks()
+    .setOnSessionStart((input, invocation) -> {
+        System.out.println("Session started: " + invocation.getSessionId());
+        System.out.println("Source: " + input.source());
+        
+        // Initialize session-specific resources
+        sessionResources.put(invocation.getSessionId(), new ResourceManager());
+        
+        return CompletableFuture.completedFuture(null);
+    });
+```
+
+---
+
+## Session End Hook
+
+Called when a session ends.
+
+### Input
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `sessionId()` | `String` | Runtime session ID of the session that triggered the hook |
+| `reason()` | `String` | Why the session ended |
+| `timestamp()` | `long` | Timestamp in milliseconds |
+
+### Output
+
+Return `null` - this hook is observation-only.
+
+### Example: Session Cleanup
+
+```java
+var hooks = new SessionHooks()
+    .setOnSessionEnd((input, invocation) -> {
+        System.out.println("Session ended: " + input.reason());
+        
+        // Clean up session resources
+        var resources = sessionResources.remove(invocation.getSessionId());
+        if (resources != null) {
+            resources.close();
+        }
+        
+        return CompletableFuture.completedFuture(null);
+    });
+```
+
+---
+
+## Complete Example
+
+Combining multiple hooks for comprehensive session control:
+
+```java
+import com.github.copilot.CopilotClient;
+import com.github.copilot.rpc.PermissionHandler;
+import com.github.copilot.rpc.PreToolUseHookOutput;
+import com.github.copilot.rpc.SessionConfig;
+import com.github.copilot.rpc.SessionHooks;
+import java.util.concurrent.CompletableFuture;
+
+public class HooksExample {
+    public static void main(String[] args) throws Exception {
+        try (var client = new CopilotClient()) {
+            client.start().get();
+            
+            var hooks = new SessionHooks()
+                // Security: control tool execution
+                .setOnPreToolUse((input, invocation) -> {
+                    System.out.println("→ " + input.getToolName());
+                    
+                    // Deny dangerous operations
+                    if (input.getToolName().contains("delete")) {
+                        return CompletableFuture.completedFuture(
+                            PreToolUseHookOutput.deny("Deletion not allowed")
+                        );
+                    }
+                    
+                    return CompletableFuture.completedFuture(PreToolUseHookOutput.allow());
+                })
+                
+                // Logging: track tool results
+                .setOnPostToolUse((input, invocation) -> {
+                    System.out.println("← " + input.getToolName() + " completed");
+                    return CompletableFuture.completedFuture(null);
+                })
+                
+                // Analytics: track user prompts
+                .setOnUserPromptSubmitted((input, invocation) -> {
+                    System.out.println("User: " + input.prompt());
+                    return CompletableFuture.completedFuture(null);
+                })
+                
+                // Lifecycle: initialization and cleanup
+                .setOnSessionStart((input, invocation) -> {
+                    System.out.println("Session started (" + input.source() + ")");
+                    return CompletableFuture.completedFuture(null);
+                })
+                .setOnSessionEnd((input, invocation) -> {
+                    System.out.println("Session ended: " + input.reason());
+                    return CompletableFuture.completedFuture(null);
+                });
+            
+            var session = client.createSession(
+                new SessionConfig().setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
+                    .setModel("gpt-4.1")
+                    .setHooks(hooks)
+            ).get();
+            
+            var response = session.sendAndWait("List files in /tmp").get();
+            System.out.println(response.getData().content());
+            
+            session.close();
+        }
+    }
+}
+```
+
+---
+
+## Hook Invocation Object
+
+All hook handlers receive a `HookInvocation` object as the second parameter:
+
+| Method | Description |
+|--------|-------------|
+| `getSessionId()` | The session ID where the hook was triggered |
+
+This allows you to correlate hooks with specific sessions when managing multiple concurrent sessions.
+
+## Checking Whether Hooks Are Registered
+
+Use `hasHooks()` to quickly verify that at least one hook handler is configured:
+
+```java
+var hooks = new SessionHooks()
+    .setOnPreToolUse((input, invocation) ->
+        CompletableFuture.completedFuture(PreToolUseHookOutput.allow()));
+
+if (hooks.hasHooks()) {
+    var session = client.createSession(
+        new SessionConfig().setOnPermissionRequest(PermissionHandler.APPROVE_ALL).setHooks(hooks)
+    ).get();
+}
+```
+
+---
+
+## Error Handling
+
+If a hook throws an exception, the SDK logs the error and continues with default behavior:
+- Pre-tool hooks default to allowing execution
+- Post-tool hooks have no effect on the result
+- Lifecycle hooks are observation-only
+
+To handle errors gracefully in your hooks:
+
+```java
+.setOnPreToolUse((input, invocation) -> {
+    try {
+        // Your logic here
+        return CompletableFuture.completedFuture(PreToolUseHookOutput.allow());
+    } catch (Exception e) {
+        logger.error("Hook error", e);
+        // Fail-safe: deny if something goes wrong
+        return CompletableFuture.completedFuture(
+            PreToolUseHookOutput.deny("Internal error")
+        );
+    }
+})
+```
+
+---
+
+## See Also
+
+- [SessionHooks Javadoc](apidocs/com/github/copilot/rpc/SessionHooks.html)
+- [PreToolUseHookInput Javadoc](apidocs/com/github/copilot/rpc/PreToolUseHookInput.html)
+- [PreToolUseHookOutput Javadoc](apidocs/com/github/copilot/rpc/PreToolUseHookOutput.html)
+- [PostToolUseHookInput Javadoc](apidocs/com/github/copilot/rpc/PostToolUseHookInput.html)
+- [PostToolUseHookOutput Javadoc](apidocs/com/github/copilot/rpc/PostToolUseHookOutput.html)
+
+---
+
+## Next Steps
+
+- 📖 **[Documentation](documentation.html)** - Core concepts, events, session management
+- 📖 **[Advanced Usage](advanced.html)** - Tools, BYOK, MCP Servers, Custom Agents
+- 📖 **[MCP Servers](mcp.html)** - Integrate external tools via Model Context Protocol
+- 📖 **[API Javadoc](apidocs/index.html)** - Complete API reference
diff --git a/src/site/markdown/index.md b/src/site/markdown/index.md
new file mode 100644
index 0000000000..645645d4bc
--- /dev/null
+++ b/src/site/markdown/index.md
@@ -0,0 +1,123 @@
+# GitHub Copilot SDK for Java
+
+> ℹ️ **Public Preview:** This is the official Java SDK for GitHub Copilot. This repository treats the official .NET and Node.js SDKs for GitHub Copilot as reference implementations. These SDKs are all officially supported as GitHub open source projects. The Java implementation follows the backward compatibility guarantees offered by the reference implementations. While in public preview, minor breaking changes may still occur between releases.
+
+Welcome to the documentation for the **GitHub Copilot SDK for Java** — a Java SDK for programmatic control of GitHub Copilot CLI, enabling you to build AI-powered applications and agentic workflows.
+
+## Getting Started
+
+### Requirements
+
+- Java 17 or later
+- GitHub Copilot CLI 1.0.17 or later installed and in PATH (or provide custom `cliPath`)
+
+### Installation
+
+Add the dependency to your project:
+
+> **Note:** If this is a `-SNAPSHOT` version, clone the project repository and run `./mvnw install` locally first so the artifact is available in your local Maven cache. Otherwise, the version is available on Maven Central.
+
+**Maven:**
+
+```xml
+<dependency>
+    <groupId>com.github</groupId>
+    <artifactId>copilot-sdk-java</artifactId>
+    <version>${project.version}</version>
+</dependency>
+```
+
+**Gradle:**
+
+```groovy
+implementation 'com.github:copilot-sdk-java:${project.version}'
+```
+
+### Quick Example
+
+```java
+import com.github.copilot.CopilotClient;
+import com.github.copilot.generated.AssistantMessageEvent;
+import com.github.copilot.generated.SessionIdleEvent;
+import com.github.copilot.rpc.MessageOptions;
+import com.github.copilot.rpc.PermissionHandler;
+import com.github.copilot.rpc.SessionConfig;
+import java.util.concurrent.CompletableFuture;
+
+public class Example {
+    public static void main(String[] args) throws Exception {
+        try (var client = new CopilotClient()) {
+            client.start().get();
+            
+            var session = client.createSession(
+                new SessionConfig().setOnPermissionRequest(PermissionHandler.APPROVE_ALL).setModel("claude-sonnet-4.5")
+            ).get();
+
+            var done = new CompletableFuture<Void>();
+            session.on(AssistantMessageEvent.class, msg -> {
+                System.out.println(msg.getData().content());
+            });
+            session.on(SessionIdleEvent.class, idle -> done.complete(null));
+
+            session.send(new MessageOptions().setPrompt("What is 2+2?")).get();
+            done.get();
+        }
+    }
+}
+```
+
+## Documentation
+
+| Document | Description |
+|----------|-------------|
+| [Documentation](documentation.html) | Basic usage, streaming, handling responses, and session management |
+| [Advanced Usage](advanced.html) | Tools, BYOK, MCP servers, infinite sessions, skills, and more |
+| [MCP Servers](mcp.html) | Integrating Model Context Protocol servers |
+| [Javadoc](apidocs/index.html) | Generated API documentation |
+
+## Try it with JBang
+
+You can quickly try the SDK without setting up a full project using [JBang](https://www.jbang.dev/):
+
+```bash
+# Install JBang (if not already installed)
+# macOS: brew install jbang
+# Linux/Windows: curl -Ls https://sh.jbang.dev | bash -s - app setup
+
+# Create a simple script
+cat > hello-copilot.java << 'EOF'
+//DEPS com.github:copilot-sdk-java:${project.version}
+import com.github.copilot.CopilotClient;
+import com.github.copilot.generated.AssistantMessageEvent;
+import com.github.copilot.generated.SessionIdleEvent;
+import com.github.copilot.rpc.MessageOptions;
+import com.github.copilot.rpc.PermissionHandler;
+import com.github.copilot.rpc.SessionConfig;
+import java.util.concurrent.CompletableFuture;
+
+class hello {
+    public static void main(String[] args) throws Exception {
+        try (var client = new CopilotClient()) {
+            client.start().get();
+            var session = client.createSession(new SessionConfig().setOnPermissionRequest(PermissionHandler.APPROVE_ALL)).get();
+            var done = new CompletableFuture<Void>();
+            session.on(AssistantMessageEvent.class, msg -> {
+                System.out.print(msg.getData().content());
+            });
+            session.on(SessionIdleEvent.class, idle -> done.complete(null));
+            session.send(new MessageOptions().setPrompt("Say hello!")).get();
+            done.get();
+        }
+    }
+}
+EOF
+
+# Run it
+jbang hello-copilot.java
+```
+
+## Source Code
+
+- [GitHub Repository](https://github.com/github/copilot-sdk-java)
+- [Issue Tracker](https://github.com/github/copilot-sdk-java/issues)
+- [Contributing Guide](https://github.com/github/copilot-sdk-java/blob/main/CONTRIBUTING.md)
diff --git a/src/site/markdown/mcp.md b/src/site/markdown/mcp.md
new file mode 100644
index 0000000000..8f830da574
--- /dev/null
+++ b/src/site/markdown/mcp.md
@@ -0,0 +1,126 @@
+# MCP Servers
+
+Extend the AI's capabilities with external tools using the [Model Context Protocol](https://modelcontextprotocol.io/).
+
+---
+
+## Quick Start
+
+Give the AI access to your filesystem.
+
+```java
+Map<String, Object> server = Map.of(
+    "type", "local",
+    "command", "npx",
+    "args", List.of("-y", "@modelcontextprotocol/server-filesystem", "/tmp"),
+    "tools", List.of("*")
+);
+
+var session = client.createSession(
+    new SessionConfig().setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
+        .setMcpServers(Map.of("filesystem", server))
+).get();
+
+var result = session.sendAndWait("List files in the directory").get();
+System.out.println(result.getData().content());
+```
+
+> **Tip:** Browse the [MCP Servers Directory](https://github.com/modelcontextprotocol/servers) for community servers like GitHub, SQLite, and Puppeteer.
+
+---
+
+## Local Servers
+
+Run a tool as a subprocess (stdin/stdout communication).
+
+```java
+var server = new HashMap<String, Object>();
+server.put("type", "local");
+server.put("command", "node");
+server.put("args", List.of("./mcp-server.js"));
+server.put("env", Map.of("DEBUG", "true"));
+server.put("cwd", "./servers");
+server.put("tools", List.of("*"));
+```
+
+| Option | Description |
+|--------|-------------|
+| `command` | Executable to run |
+| `args` | Command-line arguments |
+| `env` | Environment variables |
+| `cwd` | Working directory |
+| `tools` | `["*"]` for all, `[]` for none, or specific tool names |
+| `timeout` | Timeout in milliseconds |
+
+---
+
+## Remote Servers
+
+Connect to a cloud-hosted MCP server via HTTP.
+
+```java
+Map<String, Object> server = Map.of(
+    "type", "http",
+    "url", "https://api.githubcopilot.com/mcp/",
+    "headers", Map.of("Authorization", "Bearer " + token),
+    "tools", List.of("*")
+);
+```
+
+| Option | Description |
+|--------|-------------|
+| `type` | `"http"` or `"sse"` |
+| `url` | Server endpoint |
+| `headers` | HTTP headers for authentication |
+| `tools` | Tools to enable |
+| `timeout` | Timeout in milliseconds |
+
+---
+
+## Multiple Servers
+
+Combine tools from several sources.
+
+```java
+var session = client.createSession(
+    new SessionConfig().setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
+        .setMcpServers(Map.of(
+            "filesystem", filesystemServer,
+            "github", githubServer,
+            "database", sqliteServer
+        ))
+).get();
+```
+
+---
+
+## Troubleshooting
+
+| Problem | Solution |
+|---------|----------|
+| Tools not invoked | Set `tools` to `["*"]` or list specific tool names |
+| Server not found | Verify `command` path is correct and executable |
+| Connection refused | Check URL and authentication headers |
+| Timeout errors | Increase `timeout` or check server performance |
+
+**Debug tips:**
+- Test your MCP server independently before integrating
+- Enable verbose logging in the server
+- Start with a simple tool to verify the integration
+
+---
+
+## Resources
+
+- [MCP Specification](https://modelcontextprotocol.io/)
+- [MCP Servers Directory](https://github.com/modelcontextprotocol/servers)
+- [GitHub MCP Server](https://github.com/github/github-mcp-server)
+
+---
+
+## Next Steps
+
+- 📖 **[Documentation](documentation.html)** - Core concepts, events, session management
+- 📖 **[Advanced Usage](advanced.html)** - Tools, BYOK, System Messages, Custom Agents
+- 📖 **[Session Hooks](hooks.html)** - Intercept tool execution and session lifecycle events
+- 📖 **[API Javadoc](apidocs/index.html)** - Complete API reference
diff --git a/src/site/markdown/setup.md b/src/site/markdown/setup.md
new file mode 100644
index 0000000000..224fc1948c
--- /dev/null
+++ b/src/site/markdown/setup.md
@@ -0,0 +1,435 @@
+# Setup & Deployment Guide
+
+This guide explains how to configure the Copilot SDK for different deployment scenarios — from local development to production multi-user applications.
+
+## Quick Reference
+
+| Scenario | Configuration | Guide Section |
+|----------|--------------|---------------|
+| Local development | Default (no options) | [Local CLI](#local-cli) |
+| Multi-user app | `setGitHubToken(userToken)` | [GitHub OAuth](#github-oauth-authentication) |
+| Server deployment | `setCliUrl("host:port")` | [Backend Services](#backend-services) |
+| Custom CLI location | `setCliPath("/path/to/copilot")` | [Bundled CLI](#bundled-cli) |
+| Own model keys | Provider configuration | [BYOK](advanced.html#Bring_Your_Own_Key_BYOK) |
+
+## Local CLI
+
+The simplest setup uses the Copilot CLI already signed in on your development machine.
+
+**Use when:** Building personal projects, prototyping, or learning the SDK.
+
+```java
+try (var client = new CopilotClient()) {
+    client.start().get();
+    var session = client.createSession(
+        new SessionConfig().setOnPermissionRequest(PermissionHandler.APPROVE_ALL).setModel("gpt-4.1")
+    ).get();
+    // Use session...
+}
+```
+
+**How it works:** The SDK automatically spawns the CLI process and uses credentials from your system keychain.
+
+**Requirements:**
+- Copilot CLI installed and signed in (`copilot auth login`)
+- Active Copilot subscription
+
+See [Getting Started](getting-started.html) for a complete tutorial.
+
+## GitHub OAuth Authentication
+
+For multi-user applications where users authenticate with their GitHub accounts.
+
+**Use when:** Building apps where users have GitHub accounts and Copilot subscriptions.
+
+### Basic Setup
+
+After obtaining a user's GitHub OAuth token, pass it to the SDK:
+
+```java
+var options = new CopilotClientOptions()
+    .setGitHubToken(userAccessToken)
+    .setUseLoggedInUser(false);
+
+try (var client = new CopilotClient(options)) {
+    client.start().get();
+    var session = client.createSession(
+        new SessionConfig().setOnPermissionRequest(PermissionHandler.APPROVE_ALL).setModel("gpt-4.1")
+    ).get();
+    // Requests are made on behalf of the authenticated user
+}
+```
+
+### OAuth Flow Integration
+
+Your application handles the OAuth flow:
+
+1. Create a GitHub OAuth App in your GitHub settings
+2. Redirect users to GitHub's authorization URL
+3. Exchange the authorization code for an access token
+4. Pass the token to `CopilotClientOptions.setGitHubToken()`
+
+### Per-User Client Management
+
+Each authenticated user should get their own client instance:
+
+```java
+private final Map<String, CopilotClient> clients = new ConcurrentHashMap<>();
+
+public CopilotClient getClientForUser(String userId, String gitHubToken) {
+    return clients.computeIfAbsent(userId, id -> {
+        var options = new CopilotClientOptions()
+            .setGitHubToken(gitHubToken)
+            .setUseLoggedInUser(false);
+        var client = new CopilotClient(options);
+        try {
+            client.start().get();
+        } catch (Exception e) {
+            throw new RuntimeException("Failed to start client for user: " + userId, e);
+        }
+        return client;
+    });
+}
+```
+
+### Token Types
+
+| Token Prefix | Description | Supported |
+|--------------|-------------|-----------|
+| `gho_` | OAuth user access token | ✅ |
+| `ghu_` | GitHub App user access token | ✅ |
+| `github_pat_` | Fine-grained personal access token | ✅ |
+
+**Note:** Token lifecycle management (storage, refresh, expiration) is your application's responsibility.
+
+## Backend Services
+
+Run the SDK in server-side applications by connecting to an external CLI server.
+
+**Use when:** Building web backends, APIs, microservices, or any server-side workload.
+
+### Architecture
+
+Instead of spawning a CLI process, your application connects to a separately-running CLI server:
+
+```
+┌─────────────────┐       ┌─────────────────┐
+│   Your Backend  │       │  CLI Server     │
+│                 │       │  (headless)     │
+│  ┌───────────┐  │       │  ┌───────────┐  │
+│  │    SDK    ├──┼──────►│  │JSON-RPC   │  │
+│  └───────────┘  │ TCP   │  │:4321      │  │
+└─────────────────┘       │  └───────────┘  │
+                          └─────────────────┘
+```
+
+### Start the CLI Server
+
+Run the CLI in headless server mode:
+
+```bash
+copilot server --port 4321
+```
+
+Or with authentication:
+
+```bash
+export GITHUB_TOKEN=your_token
+copilot server --port 4321
+```
+
+### Connect from Your Application
+
+Configure the SDK to connect to the external server:
+
+```java
+var options = new CopilotClientOptions()
+    .setCliUrl("localhost:4321");
+
+try (var client = new CopilotClient(options)) {
+    client.start().get();
+    // Client connects to the external server
+}
+```
+
+### Multiple SDK Clients, One Server
+
+Multiple application instances can share a single CLI server:
+
+```java
+// Use an explicit connection token so all clients can authenticate
+var token = "my-shared-secret";
+var client1 = new CopilotClient(new CopilotClientOptions()
+    .setCliUrl("cli-server:4321").setTcpConnectionToken(token));
+var client2 = new CopilotClient(new CopilotClientOptions()
+    .setCliUrl("cli-server:4321").setTcpConnectionToken(token));
+// Both connect to the same CLI server
+```
+
+### Connection Token (TCP Security)
+
+When the SDK spawns the CLI in TCP mode, a random connection token is generated automatically
+to protect the loopback listener. You can also provide an explicit token:
+
+```java
+var options = new CopilotClientOptions()
+    .setUseStdio(false)
+    .setTcpConnectionToken("my-secret-token");
+```
+
+> **Note:** `tcpConnectionToken` cannot be used with `useStdio = true`.
+
+### Deployment Patterns
+
+**Container deployment:**
+```yaml
+# docker-compose.yml
+services:
+  cli-server:
+    image: copilot-cli:latest
+    command: copilot server --port 4321
+    environment:
+      - GITHUB_TOKEN=${GITHUB_TOKEN}
+    ports:
+      - "4321:4321"
+  
+  backend:
+    image: your-backend:latest
+    environment:
+      - CLI_URL=cli-server:4321
+    depends_on:
+      - cli-server
+```
+
+**Kubernetes deployment:**
+```yaml
+apiVersion: v1
+kind: Service
+metadata:
+  name: copilot-cli
+spec:
+  selector:
+    app: copilot-cli
+  ports:
+    - port: 4321
+---
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: copilot-cli
+spec:
+  replicas: 1
+  template:
+    spec:
+      containers:
+      - name: cli
+        image: copilot-cli:latest
+        args: ["server", "--port", "4321"]
+        env:
+        - name: GITHUB_TOKEN
+          valueFrom:
+            secretKeyRef:
+              name: copilot-auth
+              key: token
+```
+
+## Bundled CLI
+
+Package the Copilot CLI with your application so users don't need to install it separately.
+
+**Use when:** Distributing desktop applications or standalone tools.
+
+### Configuration
+
+Point the SDK to your bundled CLI binary:
+
+```java
+var options = new CopilotClientOptions()
+    .setCliPath("./bundled/copilot");  // Relative to working directory
+
+try (var client = new CopilotClient(options)) {
+    client.start().get();
+    // SDK uses the bundled CLI
+}
+```
+
+### Packaging
+
+1. Download the appropriate CLI binary for your target platform
+2. Include it in your application bundle:
+   ```
+   my-app/
+   ├── bin/
+   │   └── copilot      # CLI binary
+   ├── lib/
+   │   └── my-app.jar
+   └── run.sh
+   ```
+3. Configure the path in your application
+
+### Platform-Specific Binaries
+
+For cross-platform applications, detect the platform and use the appropriate binary:
+
+```java
+private String getCliPathForPlatform() {
+    String os = System.getProperty("os.name").toLowerCase();
+    String arch = System.getProperty("os.arch").toLowerCase();
+    
+    if (os.contains("win")) {
+        return "./bin/copilot-windows-" + arch + ".exe";
+    } else if (os.contains("mac")) {
+        return "./bin/copilot-darwin-" + arch;
+    } else {
+        return "./bin/copilot-linux-" + arch;
+    }
+}
+
+var options = new CopilotClientOptions()
+    .setCliPath(getCliPathForPlatform());
+```
+
+## Scaling & Multi-Tenancy
+
+For applications serving many concurrent users, consider these patterns:
+
+### Session Isolation
+
+Each user's sessions are automatically isolated within their client instance. For strongest isolation, use one CLI server per user:
+
+```java
+// Pattern: Isolated CLI per user (requires CLI server per user)
+public CopilotClient createIsolatedClient(String userId, int port) {
+    // Start CLI server for this user: copilot server --port {port}
+    var options = new CopilotClientOptions()
+        .setCliUrl("localhost:" + port);
+    return new CopilotClient(options);
+}
+```
+
+### Resource Management
+
+For high-concurrency scenarios:
+
+```java
+// Use a client pool with bounded resources
+public class CopilotClientPool {
+    private final Semaphore permits;
+    private final CopilotClient sharedClient;
+    
+    public CopilotClientPool(int maxConcurrentSessions) {
+        this.permits = new Semaphore(maxConcurrentSessions);
+        this.sharedClient = new CopilotClient(/* options */);
+    }
+    
+    public <T> T withSession(SessionConfig config, 
+                              Function<CopilotSession, T> action) throws Exception {
+        permits.acquire();
+        try {
+            var session = sharedClient.createSession(config).get();
+            try {
+                return action.apply(session);
+            } finally {
+                session.close();
+            }
+        } finally {
+            permits.release();
+        }
+    }
+}
+```
+
+### Horizontal Scaling
+
+When scaling beyond a single server:
+
+1. Run multiple CLI servers (one per app server or shared)
+2. Use load balancing at the application tier
+3. Each app server connects to its assigned CLI server via `setCliUrl()`
+
+## Configuration Reference
+
+Complete list of `CopilotClientOptions` settings:
+
+| Option | Type | Description | Default |
+|--------|------|-------------|---------|
+| `cliPath` | String | Path to CLI executable | `"copilot"` from PATH |
+| `cliUrl` | String | External CLI server URL | `null` (spawn process) |
+| `cliArgs` | String[] | Extra CLI arguments | `null` |
+| `copilotHome` | String | Base directory for Copilot data | `null` (~/.copilot) |
+| `gitHubToken` | String | GitHub OAuth token | `null` |
+| `useLoggedInUser` | Boolean | Use system credentials | `true` |
+| `useStdio` | boolean | Use stdio transport | `true` |
+| `port` | int | TCP port for CLI | `0` (random) |
+| `tcpConnectionToken` | String | Connection token for TCP mode | `null` (auto-generated) |
+| `autoStart` | boolean | Auto-start server | `true` |
+| `autoRestart` | boolean | Auto-restart on crash | `true` |
+| `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
+
+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
+
+- Use default configuration (local CLI) for fastest iteration
+- Enable debug logging: `setLogLevel("debug")`
+- Test with multiple models to ensure compatibility
+
+### Production
+
+- Use external CLI servers (`setCliUrl`) for better resource management
+- Implement health checks on the CLI server endpoint
+- Monitor CLI server resource usage (CPU, memory)
+- Use connection pooling for high-concurrency scenarios
+- Implement proper token refresh for OAuth-based auth
+- Set appropriate timeouts for session operations
+
+### Security
+
+- Never log or expose GitHub tokens
+- Use environment variables for tokens in production
+- Regularly rotate tokens
+- Implement proper access controls for multi-user apps
+- Validate user input before sending to sessions
+
+## Next Steps
+
+- **[Getting Started](getting-started.html)** - Complete tutorial
+- **[Documentation](documentation.html)** - Core concepts
+- **[Advanced Usage](advanced.html)** - Tools, BYOK, MCP servers
+- **[API Javadoc](apidocs/index.html)** - Complete API reference
diff --git a/src/site/resources/css/site.css b/src/site/resources/css/site.css
new file mode 100644
index 0000000000..3135895b6c
--- /dev/null
+++ b/src/site/resources/css/site.css
@@ -0,0 +1,319 @@
+/* ===== Custom theme for GitHub Copilot SDK for Java ===== */
+/* Layered on top of Maven Fluido Skin (Bootstrap 2.x) */
+
+/* ===== Typography & Base ===== */
+body {
+  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, Cantarell, sans-serif;
+  color: #24292f;
+  background: #f6f8fa;
+  -webkit-font-smoothing: antialiased;
+}
+
+a {
+  color: #0969da;
+}
+
+a:hover {
+  color: #0550ae;
+}
+
+code, pre {
+  font-family: 'SFMono-Regular', Consolas, 'Liberation Mono', Menlo, monospace;
+}
+
+/* ===== Navbar ===== */
+.navbar .navbar-inner {
+  background: #24292f;
+  background-image: none;
+  border: none;
+  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.12);
+}
+
+.navbar .brand,
+.navbar .nav > li > a,
+.navbar .nav > li > a:hover,
+.navbar .nav .dropdown-toggle {
+  color: #e6edf3;
+  text-shadow: none;
+  font-weight: 600;
+}
+
+.navbar .nav > li > a:hover,
+.navbar .nav > .active > a {
+  color: #fff;
+  background: rgba(255, 255, 255, 0.08);
+}
+
+.navbar .nav .dropdown-menu {
+  background: #fff;
+  border: 1px solid #d0d7de;
+  border-radius: 10px;
+  box-shadow: 0 8px 24px rgba(0, 0, 0, 0.12);
+  padding: 8px 0;
+}
+
+.navbar .nav .dropdown-menu li > a {
+  color: #24292f;
+  padding: 8px 16px;
+  font-weight: 500;
+}
+
+.navbar .nav .dropdown-menu li > a:hover {
+  background: rgba(102, 126, 234, 0.06);
+  color: #0969da;
+}
+
+/* ===== GitHub Ribbon ===== */
+.github-fork-ribbon:before {
+  background-color: #667eea !important;
+  background-image: linear-gradient(135deg, #667eea, #764ba2) !important;
+}
+
+.github-fork-ribbon:after {
+  content: 'View on GitHub' !important;
+}
+
+/* ===== Breadcrumbs ===== */
+#breadcrumbs {
+  background: #fff;
+  border-bottom: 1px solid #d0d7de;
+  padding: 10px 20px;
+}
+
+#breadcrumbs .breadcrumb {
+  background: transparent;
+  margin: 0;
+}
+
+/* ===== Left Sidebar ===== */
+#leftColumn .well {
+  background: #fff;
+  border: 1px solid #d0d7de;
+  border-radius: 10px;
+  box-shadow: none;
+}
+
+#leftColumn .nav-list > li > a {
+  color: #24292f;
+  border-radius: 6px;
+  margin: 2px 0;
+  font-weight: 500;
+}
+
+#leftColumn .nav-list > li > a:hover {
+  background: rgba(102, 126, 234, 0.06);
+  color: #0969da;
+}
+
+#leftColumn .nav-list > .active > a,
+#leftColumn .nav-list > .active > a:hover {
+  background: linear-gradient(135deg, #667eea, #764ba2);
+  color: #fff;
+}
+
+#leftColumn .nav-header {
+  color: #57606a;
+  font-weight: 700;
+  text-transform: uppercase;
+  font-size: 0.8em;
+  letter-spacing: 0.5px;
+  padding: 8px 14px 4px;
+}
+
+/* ===== Main Content ===== */
+#bodyColumn {
+  line-height: 1.7;
+}
+
+#bodyColumn h1,
+#bodyColumn h2,
+#bodyColumn h3,
+#bodyColumn h4 {
+  color: #24292f;
+  font-weight: 700;
+}
+
+#bodyColumn h2 {
+  border-bottom: 1px solid #d0d7de;
+  padding-bottom: 8px;
+  margin-top: 32px;
+}
+
+/* ===== Code Blocks ===== */
+#bodyColumn pre {
+  background: #eef1f6;
+  color: #24292f;
+  border: 1px solid #d0d7de;
+  border-radius: 10px;
+  padding: 16px 20px;
+  font-size: 0.88em;
+  line-height: 1.6;
+  overflow-x: auto;
+}
+
+#bodyColumn code {
+  background: rgba(102, 126, 234, 0.1);
+  color: #24292f;
+  padding: 2px 6px;
+  border-radius: 4px;
+  font-size: 0.9em;
+}
+
+#bodyColumn pre code {
+  background: transparent;
+  color: inherit;
+  padding: 0;
+  border-radius: 0;
+}
+
+/* ===== Alert Boxes (from markdown) ===== */
+#bodyColumn .alert,
+#bodyColumn blockquote {
+  border-radius: 10px;
+  border-left: 4px solid;
+  padding: 16px 20px;
+  margin: 20px 0;
+}
+
+#bodyColumn .alert-info,
+#bodyColumn blockquote {
+  background: rgba(102, 126, 234, 0.06);
+  border-left-color: #667eea;
+  color: #4a5067;
+}
+
+#bodyColumn .alert-warning {
+  background: #fff8c5;
+  border-left-color: #d4a72c;
+  color: #6a5300;
+}
+
+#bodyColumn .alert-danger,
+#bodyColumn .alert-error {
+  background: #ffeef0;
+  border-left-color: #cf222e;
+  color: #82071e;
+}
+
+#bodyColumn .alert-success {
+  background: #dafbe1;
+  border-left-color: #1a7f37;
+  color: #116329;
+}
+
+/* ===== Tables ===== */
+#bodyColumn table {
+  border-collapse: separate;
+  border-spacing: 0;
+  border: 1px solid #d0d7de;
+  border-radius: 10px;
+  overflow: hidden;
+  width: 100%;
+  margin: 20px 0;
+}
+
+#bodyColumn table thead th {
+  background: #f6f8fa;
+  color: #24292f;
+  font-weight: 700;
+  border-bottom: 2px solid #d0d7de;
+  padding: 12px 16px;
+  text-align: left;
+}
+
+#bodyColumn table tbody td {
+  padding: 10px 16px;
+  border-bottom: 1px solid #eaeef2;
+}
+
+#bodyColumn table tbody tr:last-child td {
+  border-bottom: none;
+}
+
+#bodyColumn table tbody tr:hover {
+  background: rgba(102, 126, 234, 0.03);
+}
+
+/* ===== Badges / Labels ===== */
+.label, .badge {
+  font-weight: 600;
+  border-radius: 100px;
+  padding: 3px 10px;
+  font-size: 0.8em;
+}
+
+.label-info, .badge-info {
+  background: linear-gradient(135deg, #667eea, #764ba2);
+}
+
+/* ===== Cards (for section-like divs) ===== */
+#bodyColumn .section {
+  background: #fff;
+  border: 1px solid #d0d7de;
+  border-radius: 10px;
+  padding: 24px 28px;
+  margin-bottom: 24px;
+}
+
+#bodyColumn .section .section {
+  background: transparent;
+  border: none;
+  border-radius: 0;
+  padding: 0;
+  margin-bottom: 16px;
+}
+
+/* ===== Footer ===== */
+#footer {
+  background: #fff;
+  border-top: 1px solid #d0d7de;
+  color: #57606a;
+  font-size: 0.88em;
+  padding: 24px 0;
+}
+
+#footer a {
+  color: #57606a;
+  font-weight: 500;
+}
+
+#footer a:hover {
+  color: #0969da;
+}
+
+/* ===== Powered By (add GitHub Copilot) ===== */
+#poweredBy {
+  text-align: center;
+}
+
+#poweredBy::after {
+  content: '';
+  display: block;
+  margin: 8px auto 0;
+  width: 240px;
+  height: 120px;
+  background-image: url('../images/github-copilot.jpg');
+  background-size: contain;
+  background-repeat: no-repeat;
+  background-position: center;
+  border-radius: 6px;
+}
+
+/* ===== Scrollbar (subtle) ===== */
+::-webkit-scrollbar {
+  width: 8px;
+  height: 8px;
+}
+
+::-webkit-scrollbar-track {
+  background: transparent;
+}
+
+::-webkit-scrollbar-thumb {
+  background: #d0d7de;
+  border-radius: 4px;
+}
+
+::-webkit-scrollbar-thumb:hover {
+  background: #8b949e;
+}
diff --git a/src/site/resources/image.png b/src/site/resources/image.png
new file mode 100644
index 0000000000..bb83912a33
Binary files /dev/null and b/src/site/resources/image.png differ
diff --git a/src/site/resources/images/github-copilot.jpg b/src/site/resources/images/github-copilot.jpg
new file mode 100644
index 0000000000..75efcdba2c
Binary files /dev/null and b/src/site/resources/images/github-copilot.jpg differ
diff --git a/src/site/site.xml b/src/site/site.xml
new file mode 100644
index 0000000000..f63ff29b2d
--- /dev/null
+++ b/src/site/site.xml
@@ -0,0 +1,80 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+  ~ Copyright (c) Microsoft Corporation. All rights reserved.
+  -->
+<site xmlns="http://maven.apache.org/SITE/2.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/SITE/2.0.0 https://maven.apache.org/xsd/site-2.0.0.xsd"
+         name="GitHub Copilot SDK :: Java">
+
+    <skin>
+        <groupId>org.apache.maven.skins</groupId>
+        <artifactId>maven-fluido-skin</artifactId>
+        <version>2.1.0</version>
+    </skin>
+
+    <custom>
+        <fluidoSkin>
+            <topBarEnabled>true</topBarEnabled>
+            <topBarIcon>
+                <name>GitHub Copilot SDK for Java</name>
+                <href>index.html</href>
+            </topBarIcon>
+            <gitHub>
+                <projectId>github/copilot-sdk</projectId>
+                <ribbonOrientation>right</ribbonOrientation>
+                <ribbonColor>gray</ribbonColor>
+            </gitHub>
+        </fluidoSkin>
+    </custom>
+
+    <body>
+        <breadcrumbs>
+            <item name="Home" href="index.html"/>
+        </breadcrumbs>
+
+        <menu name="Overview">
+            <item name="Introduction" href="index.html"/>
+            <item name="Getting Started" href="getting-started.html"/>
+            <item name="Setup" href="setup.html"/>
+            <item name="Documentation" href="documentation.html"/>
+            <item name="MCP Servers" href="mcp.html"/>
+            <item name="Session Hooks" href="hooks.html"/>
+            <item name="Advanced Usage" href="advanced.html"/>
+            <item name="API Javadoc" href="apidocs/index.html"/>
+        </menu>
+
+        <menu name="Guides">
+            <item name="Basic Usage" href="documentation.html#Basic_Usage"/>
+            <item name="Handling Responses" href="documentation.html#Handling_Responses"/>
+            <item name="Streaming" href="documentation.html#Streaming_Responses"/>
+            <item name="Choosing a Model" href="documentation.html#Choosing_a_Model"/>
+            <item name="Session Management" href="documentation.html#Session_Management"/>
+        </menu>
+
+        <menu name="Advanced">
+            <item name="Custom Tools" href="advanced.html#Custom_Tools"/>
+            <item name="System Messages" href="advanced.html#System_Messages"/>
+            <item name="File Attachments" href="advanced.html#File_Attachments"/>
+            <item name="BYOK" href="advanced.html#Bring_Your_Own_Key_.28BYOK.29"/>
+            <item name="Infinite Sessions" href="advanced.html#Infinite_Sessions"/>
+            <item name="MCP Servers" href="advanced.html#MCP_Servers"/>
+            <item name="Slash Commands" href="advanced.html#Slash_Commands"/>
+            <item name="Elicitation" href="advanced.html#Elicitation_UI_Dialogs"/>
+            <item name="Session Metadata" href="advanced.html#Getting_Session_Metadata_by_ID"/>
+            <item name="Session Hooks" href="hooks.html"/>
+        </menu>
+
+        <menu name="Cookbook">
+            <item name="Overview" href="cookbook/README.html"/>
+            <item name="Error Handling" href="cookbook/error-handling.html"/>
+            <item name="Multiple Sessions" href="cookbook/multiple-sessions.html"/>
+            <item name="Managing Local Files" href="cookbook/managing-local-files.html"/>
+            <item name="PR Visualization" href="cookbook/pr-visualization.html"/>
+            <item name="Persisting Sessions" href="cookbook/persisting-sessions.html"/>
+        </menu>
+
+        <menu ref="reports"/>
+
+    </body>
+</site>