docs: replace 72 skip directives with hidden compilable blocks (#721)

that the validator checks, while keeping user-facing snippets unchanged.

Changes across 22 markdown files:
- Hook type signatures (5 files × 4 langs): 20 skips removed
- Hook Go/C# implementations (4 files): 10 skips removed
- Guide Go/C#/Py snippets (8 files): 21 skips removed
- Setup/auth snippets (7 files): 11 skips removed
- OpenTelemetry Python (1 file): 4 skips removed
- Misc snippets (2 files): 4 skips removed

Remaining 14 skips are due to external package dependencies not
available to the validator (Microsoft.Agents.AI, @azure/identity,
Azure.Identity, aiofiles, Microsoft.Extensions.Logging).

All 305 extracted code blocks pass validation across TypeScript (160),
Python (62), Go (41), and C# (42).

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: patniko

docs/auth/byok.md

@@ -363,7 +363,21 @@ const session = await client.createSession({
 
 For Azure OpenAI endpoints (`*.openai.azure.com`), use the correct type:
 
-<!-- docs-validate: skip -->
+<!-- docs-validate: hidden -->
+```typescript
+import { CopilotClient } from "@github/copilot-sdk";
+
+const client = new CopilotClient();
+const session = await client.createSession({
+    model: "gpt-4.1",
+    provider: {
+        type: "azure",
+        baseUrl: "https://my-resource.openai.azure.com",
+    },
+});
+```
+<!-- /docs-validate: hidden -->
+
 ```typescript
 // ❌ Wrong: Using "openai" type with native Azure endpoint
 provider: {
@@ -380,7 +394,21 @@ provider: {
 
 However, if your Azure AI Foundry deployment provides an OpenAI-compatible endpoint path (e.g., `/openai/v1/`), use `type: "openai"`:
 
-<!-- docs-validate: skip -->
+<!-- docs-validate: hidden -->
+```typescript
+import { CopilotClient } from "@github/copilot-sdk";
+
+const client = new CopilotClient();
+const session = await client.createSession({
+    model: "gpt-4.1",
+    provider: {
+        type: "openai",
+        baseUrl: "https://your-resource.openai.azure.com/openai/v1/",
+    },
+});
+```
+<!-- /docs-validate: hidden -->
+
 ```typescript
 // ✅ Correct: OpenAI-compatible Azure AI Foundry endpoint
 provider: {

docs/auth/index.md

@@ -50,7 +50,20 @@ await client.start()
 <details>
 <summary><strong>Go</strong></summary>
 
-<!-- docs-validate: skip -->
+<!-- docs-validate: hidden -->
+```go
+package main
+
+import copilot "github.com/github/copilot-sdk/go"
+
+func main() {
+	// Default: uses logged-in user credentials
+	client := copilot.NewClient(nil)
+	_ = client
+}
+```
+<!-- /docs-validate: hidden -->
+
 ```go
 import copilot "github.com/github/copilot-sdk/go"
 
@@ -120,7 +133,23 @@ await client.start()
 <details>
 <summary><strong>Go</strong></summary>
 
-<!-- docs-validate: skip -->
+<!-- docs-validate: hidden -->
+```go
+package main
+
+import copilot "github.com/github/copilot-sdk/go"
+
+func main() {
+	userAccessToken := "token"
+	client := copilot.NewClient(&copilot.ClientOptions{
+		GitHubToken:     userAccessToken,
+		UseLoggedInUser: copilot.Bool(false),
+	})
+	_ = client
+}
+```
+<!-- /docs-validate: hidden -->
+
 ```go
 import copilot "github.com/github/copilot-sdk/go"
 
@@ -135,7 +164,19 @@ client := copilot.NewClient(&copilot.ClientOptions{
 <details>
 <summary><strong>.NET</strong></summary>
 
-<!-- docs-validate: skip -->
+<!-- docs-validate: hidden -->
+```csharp
+using GitHub.Copilot.SDK;
+
+var userAccessToken = "token";
+await using var client = new CopilotClient(new CopilotClientOptions
+{
+    GithubToken = userAccessToken,
+    UseLoggedInUser = false,
+});
+```
+<!-- /docs-validate: hidden -->
+
 ```csharp
 using GitHub.Copilot.SDK;
 
@@ -254,7 +295,16 @@ const client = new CopilotClient({
 <details>
 <summary><strong>Python</strong></summary>
 
-<!-- docs-validate: skip -->
+<!-- docs-validate: hidden -->
+```python
+from copilot import CopilotClient
+
+client = CopilotClient({
+    "use_logged_in_user": False,
+})
+```
+<!-- /docs-validate: hidden -->
+
 ```python
 client = CopilotClient({
     "use_logged_in_user": False,  # Only use explicit tokens
@@ -266,7 +316,21 @@ client = CopilotClient({
 <details>
 <summary><strong>Go</strong></summary>
 
-<!-- docs-validate: skip -->
+<!-- docs-validate: hidden -->
+```go
+package main
+
+import copilot "github.com/github/copilot-sdk/go"
+
+func main() {
+	client := copilot.NewClient(&copilot.ClientOptions{
+		UseLoggedInUser: copilot.Bool(false),
+	})
+	_ = client
+}
+```
+<!-- /docs-validate: hidden -->
+
 ```go
 client := copilot.NewClient(&copilot.ClientOptions{
     UseLoggedInUser: copilot.Bool(false),  // Only use explicit tokens

docs/debugging.md

@@ -44,7 +44,21 @@ client = CopilotClient({"log_level": "debug"})
 <details>
 <summary><strong>Go</strong></summary>
 
-<!-- docs-validate: skip -->
+<!-- docs-validate: hidden -->
+```go
+package main
+
+import copilot "github.com/github/copilot-sdk/go"
+
+func main() {
+	client := copilot.NewClient(&copilot.ClientOptions{
+		LogLevel: "debug",
+	})
+	_ = client
+}
+```
+<!-- /docs-validate: hidden -->
+
 ```go
 import copilot "github.com/github/copilot-sdk/go"
 
@@ -59,6 +73,7 @@ client := copilot.NewClient(&copilot.ClientOptions{
 <summary><strong>.NET</strong></summary>
 
 <!-- docs-validate: skip -->
+
 ```csharp
 using GitHub.Copilot.SDK;
 using Microsoft.Extensions.Logging;
@@ -110,7 +125,18 @@ const client = new CopilotClient({
 <details>
 <summary><strong>Go</strong></summary>
 
-<!-- docs-validate: skip -->
+<!-- docs-validate: hidden -->
+```go
+package main
+
+func main() {
+	// The Go SDK does not currently support passing extra CLI arguments.
+	// For custom log directories, run the CLI manually with --log-dir
+	// and connect via CLIUrl option.
+}
+```
+<!-- /docs-validate: hidden -->
+
 ```go
 // The Go SDK does not currently support passing extra CLI arguments.
 // For custom log directories, run the CLI manually with --log-dir

docs/guides/custom-agents.md

@@ -97,7 +97,47 @@ session = await client.create_session({
 <details>
 <summary><strong>Go</strong></summary>
 
-<!-- docs-validate: skip -->
+<!-- docs-validate: hidden -->
+```go
+package main
+
+import (
+	"context"
+	copilot "github.com/github/copilot-sdk/go"
+)
+
+func main() {
+	ctx := context.Background()
+	client := copilot.NewClient(nil)
+	client.Start(ctx)
+
+	session, _ := client.CreateSession(ctx, &copilot.SessionConfig{
+		Model: "gpt-4.1",
+		CustomAgents: []copilot.CustomAgentConfig{
+			{
+				Name:        "researcher",
+				DisplayName: "Research Agent",
+				Description: "Explores codebases and answers questions using read-only tools",
+				Tools:       []string{"grep", "glob", "view"},
+				Prompt:      "You are a research assistant. Analyze code and answer questions. Do not modify any files.",
+			},
+			{
+				Name:        "editor",
+				DisplayName: "Editor Agent",
+				Description: "Makes targeted code changes",
+				Tools:       []string{"view", "edit", "bash"},
+				Prompt:      "You are a code editor. Make minimal, surgical changes to files as requested.",
+			},
+		},
+		OnPermissionRequest: func(req copilot.PermissionRequest, inv copilot.PermissionInvocation) (copilot.PermissionRequestResult, error) {
+			return copilot.PermissionRequestResult{Kind: copilot.PermissionRequestResultKindApproved}, nil
+		},
+	})
+	_ = session
+}
+```
+<!-- /docs-validate: hidden -->
+
 ```go
 ctx := context.Background()
 client := copilot.NewClient(nil)
@@ -287,7 +327,51 @@ response = await session.send_and_wait({
 <details>
 <summary><strong>Go</strong></summary>
 
-<!-- docs-validate: skip -->
+<!-- docs-validate: hidden -->
+```go
+package main
+
+import (
+	"context"
+	"fmt"
+	copilot "github.com/github/copilot-sdk/go"
+)
+
+func main() {
+	ctx := context.Background()
+	client := copilot.NewClient(nil)
+	client.Start(ctx)
+
+	session, _ := client.CreateSession(ctx, &copilot.SessionConfig{
+		Model: "gpt-4.1",
+		OnPermissionRequest: func(req copilot.PermissionRequest, inv copilot.PermissionInvocation) (copilot.PermissionRequestResult, error) {
+			return copilot.PermissionRequestResult{Kind: copilot.PermissionRequestResultKindApproved}, nil
+		},
+	})
+
+	session.On(func(event copilot.SessionEvent) {
+		switch event.Type {
+		case "subagent.started":
+			fmt.Printf("▶ Sub-agent started: %s\n", *event.Data.AgentDisplayName)
+			fmt.Printf("  Description: %s\n", *event.Data.AgentDescription)
+			fmt.Printf("  Tool call ID: %s\n", *event.Data.ToolCallID)
+		case "subagent.completed":
+			fmt.Printf("✅ Sub-agent completed: %s\n", *event.Data.AgentDisplayName)
+		case "subagent.failed":
+			fmt.Printf("❌ Sub-agent failed: %s — %v\n", *event.Data.AgentDisplayName, event.Data.Error)
+		case "subagent.selected":
+			fmt.Printf("🎯 Agent selected: %s\n", *event.Data.AgentDisplayName)
+		}
+	})
+
+	_, err := session.SendAndWait(ctx, copilot.MessageOptions{
+		Prompt: "Research how authentication works in this codebase",
+	})
+	_ = err
+}
+```
+<!-- /docs-validate: hidden -->
+
 ```go
 session.On(func(event copilot.SessionEvent) {
     switch event.Type {