docs: reorganize docs/ into intent-based sections (#723)

* docs: reorganize docs/ around user intent

Restructure the docs folder from an organic flat layout into
intent-based sections that are easier to navigate:

- setup/     — get it running (was guides/setup/, moved up one level)
- auth/      — configure access (unchanged)
- features/  — build things (was guides/, scoped to SDK capabilities)
- hooks/     — API reference per hook (unchanged, overview.md → index.md)
- troubleshooting/ — fix problems (new, consolidates debugging + compatibility)
- observability/   — monitoring (new, houses OpenTelemetry docs)

Key changes:
- Add docs/index.md as top-level table of contents with persona routing
- Add docs/features/index.md as feature guide overview
- Remove duplicate guides/setup/byok.md (auth/byok.md is source of truth)
- Rename hooks/overview.md → hooks/index.md for consistency
- Move mcp/overview.md → features/mcp.md, mcp/debugging.md → troubleshooting/
- Update all internal cross-references (verified zero broken links)
- Expand README Quick Links to surface more documentation sections

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

* docs: move Microsoft Agent Framework to new integrations/ section

Create a dedicated integrations/ section at the bottom of the docs
hierarchy for platform/framework-specific guides. Move MAF out of
features/ since it's an integration pattern, not an SDK capability.

This makes it easy to add future guides for other platforms alongside MAF.

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

---------

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

Author: patniko

README.md

@@ -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
 

docs/auth/index.md

@@ -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

docs/guides/custom-agents.md docs/features/custom-agents.mddocs/guides/custom-agents.md renamed to docs/features/custom-agents.md

@@ -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)

docs/guides/hooks.md docs/features/hooks.mddocs/guides/hooks.md renamed to docs/features/hooks.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

docs/guides/image-input.md docs/features/image-input.mddocs/guides/image-input.md renamed to docs/features/image-input.md

@@ -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

docs/features/index.md

@@ -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

docs/mcp/overview.md docs/features/mcp.mddocs/mcp/overview.md renamed to docs/features/mcp.md

@@ -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

docs/guides/session-persistence.md docs/features/session-persistence.mddocs/guides/session-persistence.md renamed to docs/features/session-persistence.md

@@ -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