github · patniko · Mar 8, 2026 · Mar 8, 2026 · Mar 8, 2026
@@ -107,8 +107,12 @@ Please use the [GitHub Issues](https://github.com/github/copilot-sdk/issues) pag
 
 ## Quick Links
 
+- **[Documentation](./docs/index.md)** – Full documentation index
 - **[Getting Started](./docs/getting-started.md)** – Tutorial to get up and running
+- **[Setup Guides](./docs/setup/index.md)** – Architecture, deployment, and scaling
 - **[Authentication](./docs/auth/index.md)** – GitHub OAuth, BYOK, and more
+- **[Features](./docs/features/index.md)** – Hooks, custom agents, MCP, skills, and more
+- **[Troubleshooting](./docs/troubleshooting/debugging.md)** – Common issues and solutions
 - **[Cookbook](https://github.com/github/awesome-copilot/blob/main/cookbook/copilot-sdk)** – Practical recipes for common tasks across all languages
 - **[More Resources](https://github.com/github/awesome-copilot/blob/main/collections/copilot-sdk.md)** – Additional examples, tutorials, and community resources
 

@@ -355,4 +355,4 @@ await using var client = new CopilotClient(new CopilotClientOptions
 
 - [BYOK Documentation](./byok.md) - Learn how to use your own API keys
 - [Getting Started Guide](../getting-started.md) - Build your first Copilot-powered app
-- [MCP Servers](../mcp) - Connect to external tools
+- [MCP Servers](../features/mcp.md) - Connect to external tools
@@ -973,7 +973,7 @@ const session = await client.createSession({
 
 For full type definitions, input/output field tables, and additional examples for every hook, see the API reference:
 
-- [Hooks Overview](../hooks/overview.md)
+- [Hooks Overview](../hooks/index.md)
 - [Pre-Tool Use](../hooks/pre-tool-use.md)
 - [Post-Tool Use](../hooks/post-tool-use.md)
 - [User Prompt Submitted](../hooks/user-prompt-submitted.md)
@@ -985,4 +985,4 @@ For full type definitions, input/output field tables, and additional examples fo
 - [Getting Started](../getting-started.md)
 - [Custom Agents & Sub-Agent Orchestration](./custom-agents.md)
 - [Streaming Session Events](./streaming-events.md)
-- [Debugging Guide](../debugging.md)
+- [Debugging Guide](../troubleshooting/debugging.md)
@@ -0,0 +1,25 @@
+# Features
+
+These guides cover the capabilities you can add to your Copilot SDK application. Each guide includes examples in all supported languages (TypeScript, Python, Go, and .NET).
+
+> **New to the SDK?** Start with the [Getting Started tutorial](../getting-started.md) first, then come back here to add more capabilities.
+
+## Guides
+
+| Feature | Description |
+|---|---|
+| [Hooks](./hooks.md) | Intercept and customize session behavior — control tool execution, transform results, handle errors |
+| [Custom Agents](./custom-agents.md) | Define specialized sub-agents with scoped tools and instructions |
+| [MCP Servers](./mcp.md) | Integrate Model Context Protocol servers for external tool access |
+| [Skills](./skills.md) | Load reusable prompt modules from directories |
+| [Image Input](./image-input.md) | Send images to sessions as attachments |
+| [Streaming Events](./streaming-events.md) | Subscribe to real-time session events (40+ event types) |
+| [Steering & Queueing](./steering-and-queueing.md) | Control message delivery — immediate steering vs. sequential queueing |
+| [Session Persistence](./session-persistence.md) | Resume sessions across restarts, manage session storage |
+
+## Related
+
+- [Hooks Reference](../hooks/index.md) — detailed API reference for each hook type
+- [Integrations](../integrations/microsoft-agent-framework.md) — use the SDK with other platforms (MAF, etc.)
+- [Troubleshooting](../troubleshooting/debugging.md) — when things don't work as expected
+- [Compatibility](../troubleshooting/compatibility.md) — SDK vs CLI feature matrix
@@ -258,18 +258,18 @@ directories for different applications.
 | "Timeout" errors | Increase the `timeout` value or check server performance |
 | Tools work but aren't called | Ensure your prompt clearly requires the tool's functionality |
 
-For detailed debugging guidance, see the **[MCP Debugging Guide](./debugging.md)**.
+For detailed debugging guidance, see the **[MCP Debugging Guide](../troubleshooting/mcp-debugging.md)**.
 
 ## Related Resources
 
 - [Model Context Protocol Specification](https://modelcontextprotocol.io/)
 - [MCP Servers Directory](https://github.com/modelcontextprotocol/servers) - Community MCP servers
 - [GitHub MCP Server](https://github.com/github/github-mcp-server) - Official GitHub MCP server
 - [Getting Started Guide](../getting-started.md) - SDK basics and custom tools
-- [General Debugging Guide](../debugging.md) - SDK-wide debugging
+- [General Debugging Guide](.../troubleshooting/mcp-debugging.md) - SDK-wide debugging
 
 ## See Also
 
-- [MCP Debugging Guide](./debugging.md) - Detailed MCP troubleshooting
+- [MCP Debugging Guide](../troubleshooting/mcp-debugging.md) - Detailed MCP troubleshooting
 - [Issue #9](https://github.com/github/copilot-sdk/issues/9) - Original MCP tools usage question
 - [Issue #36](https://github.com/github/copilot-sdk/issues/36) - MCP documentation tracking issue
@@ -561,7 +561,7 @@ const session = await client.createSession({
 });
 ```
 
-> **Note:** Thresholds are context utilization ratios (0.0-1.0), not absolute token counts. See the [Compatibility Guide](../compatibility.md) for details.
+> **Note:** Thresholds are context utilization ratios (0.0-1.0), not absolute token counts. See the [Compatibility Guide](../troubleshooting/compatibility.md) for details.
 
 ## Limitations & Considerations
 
@@ -621,6 +621,6 @@ await withSessionLock("user-123-task-456", async () => {
 
 ## Next Steps
 
-- [Hooks Overview](../hooks/overview.md) - Customize session behavior with hooks
-- [Compatibility Guide](../compatibility.md) - SDK vs CLI feature comparison
-- [Debugging Guide](../debugging.md) - Troubleshoot session issues
+- [Hooks Overview](../hooks/index.md) - Customize session behavior with hooks
+- [Compatibility Guide](../troubleshooting/compatibility.md) - SDK vs CLI feature comparison
+- [Debugging Guide](../troubleshooting/debugging.md) - Troubleshoot session issues
@@ -365,4 +365,4 @@ If multiple skills provide conflicting instructions:
 
 - [Custom Agents](../getting-started.md#create-custom-agents) - Define specialized AI personas
 - [Custom Tools](../getting-started.md#step-4-add-a-custom-tool) - Build your own tools
-- [MCP Servers](../mcp/overview.md) - Connect external tool providers
+- [MCP Servers](./mcp.md) - Connect external tool providers
@@ -575,5 +575,5 @@ class InteractiveChat {
 
 - [Getting Started](../getting-started.md) — Set up a session and send messages
 - [Custom Agents](./custom-agents.md) — Define specialized agents with scoped tools
-- [Session Hooks](../hooks/overview.md) — React to session lifecycle events
+- [Session Hooks](../hooks/index.md) — React to session lifecycle events
 - [Session Persistence](./session-persistence.md) — Resume sessions across restarts
@@ -1224,7 +1224,7 @@ const session = await client.createSession({
 });
 ```
 
-📖 **[Full MCP documentation →](./mcp/overview.md)** - Learn about local vs remote servers, all configuration options, and troubleshooting.
+📖 **[Full MCP documentation →](./features/mcp.md)** - Learn about local vs remote servers, all configuration options, and troubleshooting.
 
 ### Create Custom Agents
 
@@ -1401,7 +1401,7 @@ await using var session = await client.CreateSessionAsync(new()
 - [Python SDK Reference](../python/README.md)
 - [Go SDK Reference](../go/README.md)
 - [.NET SDK Reference](../dotnet/README.md)
-- [Using MCP Servers](./mcp) - Integrate external tools via Model Context Protocol
+- [Using MCP Servers](./features/mcp.md) - Integrate external tools via Model Context Protocol
 - [GitHub MCP Server Documentation](https://github.com/github/github-mcp-server)
 - [MCP Servers Directory](https://github.com/modelcontextprotocol/servers) - Explore more MCP servers