Flatten docs routes to match blog pattern#619
Conversation
Changes docs from [[...slug]] catch-all to [slug] single segment, matching how blog works. This prevents OpenNext from incorrectly classifying /docs as an S3 static route prefix. - Flatten nested docs (reference/sdk → reference-sdk, etc.) - Add /docs index page that redirects to /docs/introduction - Update internal links, sitemap, and nav slugs Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
![devin-ai-integration[bot]](https://avatars.githubusercontent.com/in/811515?s=60&v=4){kind=small}
| <CardGroup cols={2}> | ||
| <Card title="Spawn Agents" icon="users"> | ||
| Programmatically create Claude, Codex, Gemini, or OpenCode agents with a specific model and task. | ||
|
|
||
| <Card title="Send Messages" icon="messages"> | ||
| Route messages between agents — direct, broadcast, or channel-based. | ||
|
|
||
| <Card title="Connect Frameworks" icon="plug"> | ||
| Put OpenAI Agents, Claude SDK, Google ADK, Pi, Agno, Swarms, or CrewAI agents on the relay. | ||
|
|
||
| <Card title="Multi-Provider" icon="shuffle"> | ||
| Mix Claude, Codex, Gemini, and OpenCode agents in a single workflow, each using their strengths. | ||
|
|
There was a problem hiding this comment.
🔴 MDX <CardGroup> and <Card> components used in plain markdown mirror docs/introduction.md
The docs-sync rule (.claude/rules/docs-sync.md, rule #2) requires that .md files convert MDX components to plain markdown. This PR introduces <CardGroup cols={2}> and <Card> MDX components directly into docs/introduction.md at two locations: the "What You Can Do" section (lines 53-65) and the "Next Steps" section (lines 100-112). Additionally, the <Card> tags are missing their </Card> closing tags (the MDX counterpart at web/content/docs/introduction.mdx:64-76 has them), and the closing </CardGroup> is also absent. The old version correctly used plain markdown bullet points. These raw MDX components will render as broken HTML in any plain markdown viewer, GitHub, or LLM consumer.
| <CardGroup cols={2}> | |
| <Card title="Spawn Agents" icon="users"> | |
| Programmatically create Claude, Codex, Gemini, or OpenCode agents with a specific model and task. | |
| <Card title="Send Messages" icon="messages"> | |
| Route messages between agents — direct, broadcast, or channel-based. | |
| <Card title="Connect Frameworks" icon="plug"> | |
| Put OpenAI Agents, Claude SDK, Google ADK, Pi, Agno, Swarms, or CrewAI agents on the relay. | |
| <Card title="Multi-Provider" icon="shuffle"> | |
| Mix Claude, Codex, Gemini, and OpenCode agents in a single workflow, each using their strengths. | |
| - **Spawn Agents** — Programmatically create Claude, Codex, Gemini, or OpenCode agents with a specific model and task. | |
| - **Send Messages** — Route messages between agents — direct, broadcast, or channel-based. | |
| - **Connect Frameworks** — Put OpenAI Agents, Claude SDK, Google ADK, Pi, Agno, Swarms, or CrewAI agents on the relay. | |
| - **Multi-Provider** — Mix Claude, Codex, Gemini, and OpenCode agents in a single workflow, each using their strengths. | |
Was this helpful? React with 👍 or 👎 to provide feedback.
| <CardGroup cols={2}> | ||
| - [Quickstart](/docs/quickstart) | ||
| Get your first agents talking to each other in minutes. | ||
|
|
||
| - [Communicate Mode](/docs/communicate) | ||
| Put any framework agent on the relay with on_relay(). | ||
|
|
||
| - [TypeScript SDK](/docs/reference-sdk) | ||
| Full API reference for the TypeScript SDK. | ||
|
|
||
| - [Python SDK](/docs/reference-sdk-py) | ||
| Full API reference for the Python SDK. | ||
|
|
There was a problem hiding this comment.
🔴 MDX <CardGroup> used in plain markdown mirror docs/introduction.md Next Steps section
The "Next Steps" section of docs/introduction.md wraps links in a <CardGroup cols={2}> MDX component (lines 100-112) instead of using plain markdown links, violating docs-sync rule #2. The MDX counterpart (web/content/docs/introduction.mdx:111-124) uses <CardGroup> with <Card> components, but the .md mirror should convert these to plain markdown links.
| <CardGroup cols={2}> | |
| - [Quickstart](/docs/quickstart) | |
| Get your first agents talking to each other in minutes. | |
| - [Communicate Mode](/docs/communicate) | |
| Put any framework agent on the relay with on_relay(). | |
| - [TypeScript SDK](/docs/reference-sdk) | |
| Full API reference for the TypeScript SDK. | |
| - [Python SDK](/docs/reference-sdk-py) | |
| Full API reference for the Python SDK. | |
| - [Quickstart](quickstart.md) — Get your first agents talking to each other in minutes. | |
| - [Communicate Mode](communicate.md) — Put any framework agent on the relay with on_relay(). | |
| - [TypeScript SDK](reference-sdk.md) — Full API reference for the TypeScript SDK. | |
| - [Python SDK](reference-sdk-py.md) — Full API reference for the Python SDK. | |
Was this helpful? React with 👍 or 👎 to provide feedback.
| <CardGroup cols={2}> | ||
| - [AI SDK](/docs/communicate-ai-sdk) — TypeScript adapter for Vercel AI SDK apps | ||
| - [OpenAI Agents](/docs/communicate-openai-agents) — Python adapter for OpenAI Agents SDK | ||
| - [Claude Agent SDK](/docs/communicate-claude-sdk) — Python + TypeScript adapter | ||
| - [Google ADK](/docs/communicate-google-adk) — Python adapter for Google ADK | ||
| - [Pi](/docs/communicate-pi) — TypeScript adapter for Pi coding agent | ||
| - [Agno](/docs/communicate-agno) — Python adapter for Agno | ||
| - [Swarms](/docs/communicate-swarms) — Python adapter for Swarms | ||
| - [CrewAI](/docs/communicate-crewai) — Python adapter for CrewAI |
There was a problem hiding this comment.
🔴 MDX <CardGroup> used in plain markdown mirror docs/communicate.md
The "Per-Framework Guides" section of docs/communicate.md wraps the adapter links in <CardGroup cols={2}> (line 71) instead of using a plain markdown list, violating docs-sync rule #2. The </CardGroup> closing tag is also missing. The old version correctly used plain markdown links. The MDX counterpart at web/content/docs/communicate.mdx:78-87 uses <CardGroup>/<Card> which should be converted to plain links in the .md mirror.
| <CardGroup cols={2}> | |
| - [AI SDK](/docs/communicate-ai-sdk) — TypeScript adapter for Vercel AI SDK apps | |
| - [OpenAI Agents](/docs/communicate-openai-agents) — Python adapter for OpenAI Agents SDK | |
| - [Claude Agent SDK](/docs/communicate-claude-sdk) — Python + TypeScript adapter | |
| - [Google ADK](/docs/communicate-google-adk) — Python adapter for Google ADK | |
| - [Pi](/docs/communicate-pi) — TypeScript adapter for Pi coding agent | |
| - [Agno](/docs/communicate-agno) — Python adapter for Agno | |
| - [Swarms](/docs/communicate-swarms) — Python adapter for Swarms | |
| - [CrewAI](/docs/communicate-crewai) — Python adapter for CrewAI | |
| - [AI SDK](communicate-ai-sdk.md) — TypeScript adapter for Vercel AI SDK apps | |
| - [OpenAI Agents](communicate-openai-agents.md) — Python adapter for OpenAI Agents SDK | |
| - [Claude Agent SDK](communicate-claude-sdk.md) — Python + TypeScript adapter | |
| - [Google ADK](communicate-google-adk.md) — Python adapter for Google ADK | |
| - [Pi](communicate-pi.md) — TypeScript adapter for Pi coding agent | |
| - [Agno](communicate-agno.md) — Python adapter for Agno | |
| - [Swarms](communicate-swarms.md) — Python adapter for Swarms | |
| - [CrewAI](communicate-crewai.md) — Python adapter for CrewAI | |
Was this helpful? React with 👍 or 👎 to provide feedback.
| <CardGroup cols={2}> | ||
| - [TypeScript SDK Reference](/docs/reference-sdk) | ||
| Complete TypeScript API reference. | ||
|
|
||
| - [Python SDK Reference](/docs/reference-sdk-py) | ||
| Complete Python API reference. | ||
|
|
There was a problem hiding this comment.
🔴 MDX <CardGroup> used in plain markdown mirror docs/quickstart.md
The "Next Steps" section of docs/quickstart.md wraps links in <CardGroup cols={2}> (lines 92-98) instead of plain markdown, violating docs-sync rule #2. The old version correctly used plain markdown links. The closing </CardGroup> is also absent.
| <CardGroup cols={2}> | |
| - [TypeScript SDK Reference](/docs/reference-sdk) | |
| Complete TypeScript API reference. | |
| - [Python SDK Reference](/docs/reference-sdk-py) | |
| Complete Python API reference. | |
| - [TypeScript SDK Reference](reference-sdk.md) — Complete TypeScript API reference. | |
| - [Python SDK Reference](reference-sdk-py.md) — Complete Python API reference. | |
Was this helpful? React with 👍 or 👎 to provide feedback.
| **Tier 1 (Push)**: Messages are injected mid-execution via hooks or callbacks. | ||
| **Tier 2 (Poll)**: Messages are available at natural tool-call boundaries. |
There was a problem hiding this comment.
🔴 Broken blockquote formatting in Note sections — > prefix removed from content lines
Across multiple adapter .md files, the > blockquote prefix was removed from Note content lines while the > **Note:** header was kept. This causes the note content to fall outside the blockquote in standard markdown rendering. For example, in docs/communicate.md:35-37:
Broken blockquote example
> **Note:**
**Tier 1 (Push)**: Messages are injected...
Should be:
> **Note:**
> **Tier 1 (Push)**: Messages are injected...
The docs-sync rule #2 says <Note> → > **Note:**, meaning the full content should be blockquoted. This affects: docs/communicate.md:36-37, docs/communicate-agno.md:41, docs/communicate-claude-sdk.md:54, docs/communicate-crewai.md:13,48, docs/communicate-google-adk.md, docs/communicate-openai-agents.md, docs/communicate-pi.md, docs/communicate-swarms.md.
| **Tier 1 (Push)**: Messages are injected mid-execution via hooks or callbacks. | |
| **Tier 2 (Poll)**: Messages are available at natural tool-call boundaries. | |
| > **Tier 1 (Push)**: Messages are injected mid-execution via hooks or callbacks. | |
| > **Tier 2 (Poll)**: Messages are available at natural tool-call boundaries. | |
Was this helpful? React with 👍 or 👎 to provide feedback.
| - [Quickstart](/quickstart) — Spawn agents and exchange messages quickly | ||
| - [Python SDK Reference](/reference/sdk-py) — Python API reference |
There was a problem hiding this comment.
🔴 docs/reference-sdk.md is severely out of sync with its MDX counterpart
Per docs-sync rule #1, .md and .mdx files must stay in sync. The new docs/reference-sdk.md (134 lines) is missing large sections present in web/content/docs/reference-sdk.mdx (307 lines). Missing sections include: AgentRelay constructor and AgentRelayOptions table (reference-sdk.mdx:12-36), Agent interface (reference-sdk.mdx:89-117), ReleaseOptions (reference-sdk.mdx:119-129), Event Hooks (reference-sdk.mdx:151-179), Complete Example (reference-sdk.mdx:217-256), and Error Types (reference-sdk.mdx:285-300). Additionally, the "See Also" links at docs/reference-sdk.md:133-134 use stale paths (/quickstart, /reference/sdk-py) that were not updated to the new flat structure (reference-sdk-py.md).
Prompt for agents
The file docs/reference-sdk.md needs to be regenerated to mirror the full content of web/content/docs/reference-sdk.mdx. It is currently missing most sections. Per .claude/rules/docs-sync.md, mirror the MDX content with these conversions: remove frontmatter (--- YAML block), remove <CodeGroup>/<CodeGroup> tags (keep code blocks), and update the See Also links at the bottom from /quickstart to quickstart.md and from /reference/sdk-py to reference-sdk-py.md. The missing sections that must be added are: AgentRelay constructor (mdx lines 12-36), Agent interface (mdx lines 89-117), ReleaseOptions (mdx lines 119-129), Event Hooks (mdx lines 151-179), Complete Example (mdx lines 217-256), and Error Types (mdx lines 285-300).
Was this helpful? React with 👍 or 👎 to provide feedback.
| - [Quickstart](/quickstart) — Spawn agents and exchange messages quickly | ||
| - [TypeScript SDK Reference](/reference/sdk) — TypeScript API reference |
There was a problem hiding this comment.
🔴 docs/reference-sdk-py.md is severely out of sync with its MDX counterpart
Per docs-sync rule #1, .md and .mdx files must stay in sync. The new docs/reference-sdk-py.md (122 lines) is missing large sections present in web/content/docs/reference-sdk-py.mdx (272 lines). Missing sections include: AgentRelay constructor and options (reference-sdk-py.mdx:14-31), Agent class (reference-sdk-py.mdx:84-104), Event Hooks (reference-sdk-py.mdx:127-155), Complete Example (reference-sdk-py.mdx:177-220), and Error Types (reference-sdk-py.mdx:254-265). Additionally, the "See Also" links at docs/reference-sdk-py.md:121-122 use stale paths (/quickstart, /reference/sdk) that were not updated to the new flat structure.
Prompt for agents
The file docs/reference-sdk-py.md needs to be regenerated to mirror the full content of web/content/docs/reference-sdk-py.mdx. It is currently missing most sections. Per .claude/rules/docs-sync.md, mirror the MDX content with these conversions: remove frontmatter (--- YAML block), remove horizontal rules (---), and update the See Also links at the bottom from /quickstart to quickstart.md and from /reference/sdk to reference-sdk.md. The missing sections that must be added are: AgentRelay constructor (mdx lines 14-31), Agent class (mdx lines 84-104), Event Hooks (mdx lines 127-155), Complete Example (mdx lines 177-220), and Error Types (mdx lines 254-265).
Was this helpful? React with 👍 or 👎 to provide feedback.
1 participant
Summary
[[...slug]]catch-all to[slug]single segment, matching how blog works/docsas an S3 static route prefix, which was causing Access Denied errorsreference/sdk→reference-sdk, etc.)/docsindex page that redirects to/docs/introductionRoot cause
OpenNext was adding
/docsto the S3 routes list in the CloudFront KV store because of the[[...slug]]catch-all pattern. All/docs/*requests were routed to S3 instead of the Lambda server, resulting in Access Denied.Test plan
/docs,/docs/introduction,/docs/reference-sdkall load/docsredirects to/docs/introduction🤖 Generated with Claude Code