docs: reorganize docs/ into intent-based sections#723
Merged
Conversation
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>
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>
Contributor
There was a problem hiding this comment.
Pull request overview
Restructures the documentation under docs/ into intent-based sections (setup/auth/features/hooks/troubleshooting/observability) and updates internal cross-references so navigation and discovery are easier across the SDK docs.
Changes:
- Added new intent-based landing pages (
docs/index.md,docs/features/index.md) and new feature guides (e.g., streaming events, image input, custom agents, MAF integration). - Consolidated troubleshooting docs under
docs/troubleshooting/and updated “See also” cross-links across docs. - Moved/retargeted setup and feature references (e.g., BYOK, session persistence, MCP) and removed a duplicated BYOK guide.
Reviewed changes
Copilot reviewed 28 out of 32 changed files in this pull request and generated no comments.
Show a summary per file
| File | Description |
|---|---|
| docs/troubleshooting/mcp-debugging.md | Updates “See also” links to the new troubleshooting/features locations. |
| docs/troubleshooting/debugging.md | Fixes MCP debugging references to the new mcp-debugging.md location and updates “See also” links. |
| docs/troubleshooting/compatibility.md | Updates “See also” links for getting started/hooks/MCP to new paths. |
| docs/setup/scaling.md | Updates next-step links for session persistence and BYOK to new locations. |
| docs/setup/local-cli.md | Updates BYOK + next-step links to new getting-started/auth/features paths. |
| docs/setup/index.md | Updates BYOK and getting-started links to new locations. |
| docs/setup/github-oauth.md | Updates BYOK/auth links to new locations. |
| docs/setup/bundled-cli.md | Updates BYOK/session persistence/getting-started links to new locations. |
| docs/setup/backend-services.md | Updates BYOK and session persistence links to new locations. |
| docs/setup/azure-managed-identity.md | Updates BYOK references to new auth location. |
| docs/observability/opentelemetry.md | Adds a new OpenTelemetry instrumentation guide under the new observability/ section. |
| docs/index.md | Adds a top-level docs index with intent-based routing and a documentation map. |
| docs/hooks/user-prompt-submitted.md | Updates hooks overview link from overview.md to index.md. |
| docs/hooks/session-lifecycle.md | Updates hooks overview and debugging guide links to new paths. |
| docs/hooks/pre-tool-use.md | Updates hooks overview and debugging guide links to new paths. |
| docs/hooks/post-tool-use.md | Updates hooks overview link to index.md. |
| docs/hooks/index.md | Updates debugging guide link to new troubleshooting location. |
| docs/hooks/error-handling.md | Updates hooks overview and debugging guide links to new paths. |
| docs/guides/setup/byok.md | Removes duplicate BYOK guide content (per PR description). |
| docs/getting-started.md | Updates MCP documentation links to the new features page. |
| docs/features/streaming-events.md | Adds a new, detailed streaming session events reference. |
| docs/features/steering-and-queueing.md | Updates hooks link to the new hooks index. |
| docs/features/skills.md | Updates MCP link to the new features MCP guide. |
| docs/features/session-persistence.md | Updates compatibility/hooks/debugging links to new troubleshooting/hooks locations. |
| docs/features/microsoft-agent-framework.md | Adds a new MAF integration guide and examples. |
| docs/features/mcp.md | Updates MCP debugging and related-resource links to new troubleshooting locations. |
| docs/features/index.md | Adds a new “Features” hub page linking to feature guides. |
| docs/features/image-input.md | Adds a new guide documenting image attachments / vision usage. |
| docs/features/hooks.md | Updates hooks overview/debugging links to new hooks/troubleshooting locations. |
| docs/features/custom-agents.md | Adds a new custom agents & sub-agent orchestration guide. |
| docs/auth/index.md | Updates MCP link to the new features MCP guide. |
| README.md | Expands “Quick Links” to include docs index + new sections. |
Comments suppressed due to low confidence (1)
docs/features/mcp.md:269
- The "General Debugging Guide" link is broken (".../" in the path) and also points to the MCP debugging page instead of the SDK-wide debugging guide. Update it to the correct relative path from
docs/features/mcp.md(e.g.,../troubleshooting/debugging.md).
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Restructures the
docs/folder from an organic flat layout into intent-based sections that are easier to navigate and discover.Changes
New structure
docs/index.mdsetup/guides/setup/(nested two levels deep)auth/features/guides/(flat grab-bag)hooks/overview.md→index.md)troubleshooting/debugging.md,compatibility.md,mcp/debugging.md)observability/opentelemetry-instrumentation.md)Key improvements
docs/index.mdroutes users by intent ("I want to build my first app", "I want to debug an issue", etc.)docs/features/index.mdprovides an overview of all SDK capabilitiesguides/setup/byok.md(was a copy ofauth/byok.md)guides/setup/tosetup/(one level shallower)Validation
just validate-docs-extractpasses (31 files, 298 code blocks extracted)just validate-docs-checkpasses (all TS/Go/C# blocks valid)