cloudflare · mattzcarey · Jun 17, 2026
diff --git a/.changeset/soft-docs-ship.md b/.changeset/soft-docs-ship.md
@@ -0,0 +1,9 @@
+---
+"agents": patch
+"@cloudflare/codemode": patch
+"@cloudflare/shell": patch
+"@cloudflare/think": patch
+"@cloudflare/voice": patch
+---
+
+Include each package's documentation in its published package.
diff --git a/.gitignore b/.gitignore
@@ -91,6 +91,9 @@ out
 .nuxt
 dist
 
+# Generated package documentation (source lives in /docs)
+packages/*/docs
+
 # Gatsby files
 .cache/
 # Comment in the public line in if your project uses Gatsby and not Next.js

diff --git a/design/README.md b/design/README.md
@@ -12,7 +12,7 @@ The goal is to give contributors (and future-us) a quick way to understand _why_
 | [think-durable-submissions.md](./think-durable-submissions.md)                   | Think durable submissions — async programmatic turns, recovery, idempotency   |
 | [visuals.md](./visuals.md)                                                       | UI component library choice, Kumo usage, custom patterns                      |
 | [readonly-connections.md](./readonly-connections.md)                             | Readonly connection enforcement, storage, tradeoffs, and caveats              |
-| [workspace.md](./workspace.md)                                                   | Workspace — hybrid SQLite+R2 filesystem, bash, symlinks                       |
+| [workspace.md](./shell/index.md)                                                 | Workspace — hybrid SQLite+R2 filesystem, bash, symlinks                       |
 | [agent-tools.md](./agent-tools.md)                                               | Agent tools — chat sub-agent orchestration, parent registry, replay           |
 | [sub-agent-routing.md](./sub-agent-routing.md)                                   | Sub-agent routing as shipped — facets, nested URLs, registry, parent lookup   |
 | [rfc-sub-agents.md](./rfc-sub-agents.md)                                         | RFC: Sub-agents — child DOs via facets, typed stubs, mixin API                |

diff --git a/design/think-durable-submissions.md b/design/think-durable-submissions.md
@@ -10,8 +10,8 @@ Related:
 - [think.md](./think.md) — overall Think architecture
 - [think-sessions.md](./think-sessions.md) — Session-backed message storage
 - [docs/think/programmatic-submissions.md](../docs/think/programmatic-submissions.md) — user-facing API guide
-- [server-driven-messages.md](../docs/server-driven-messages.md) — lighter-weight server message patterns
-- [workflows.md](../docs/workflows.md) — durable multi-step orchestration
+- [server-driven-messages.md](../docs/agents/server-driven-messages.md) — lighter-weight server message patterns
+- [workflows.md](../docs/agents/workflows.md) — durable multi-step orchestration
 
 ## Problem
 

diff --git a/design/think-roadmap.md b/design/think-roadmap.md
@@ -2,7 +2,7 @@
 
 The implementation plan for `@cloudflare/think` — an opinionated chat agent base class built on Session for conversation storage and the Agents SDK for execution.
 
-> This roadmap is retained as a historical implementation record. All phases are complete, and current recovery behavior is documented in [`docs/think/index.md`](../docs/think/index.md) and [`docs/chat-agents.md#stream-recovery`](../docs/chat-agents.md#stream-recovery).
+> This roadmap is retained as a historical implementation record. All phases are complete, and current recovery behavior is documented in [`docs/think/index.md`](../docs/think/index.md) and [`docs/agents/chat-agents.md#stream-recovery`](../docs/agents/chat-agents.md#stream-recovery).
 
 This document synthesizes four prior analyses:
 

diff --git a/design/think.md b/design/think.md
@@ -7,7 +7,7 @@ An opinionated Agent base class for AI assistants. Handles the chat lifecycle
 > This is a historical design note. For current user-facing API behavior, see
 > [`docs/think/index.md`](../docs/think/index.md),
 > [`docs/think/lifecycle-hooks.md`](../docs/think/lifecycle-hooks.md), and
-> [`docs/chat-agents.md#stream-recovery`](../docs/chat-agents.md#stream-recovery).
+> [`docs/agents/chat-agents.md#stream-recovery`](../docs/agents/chat-agents.md#stream-recovery).
 
 ## Problem
 
@@ -518,4 +518,4 @@ Think's design — skills, extensions, tree-structured sessions, compaction, and
 - [chat-shared-layer.md](./chat-shared-layer.md) — shared streaming, sanitization, and protocol primitives (Think uses `StreamAccumulator`, `sanitizeMessage`, `enforceRowSizeLimit`, `CHAT_MESSAGE_TYPES`, `TurnQueue`, `ResumableStream`, `ContinuationState` from `agents/chat`)
 - [rfc-sub-agents.md](./rfc-sub-agents.md) — sub-agents via facets (Think's `subAgent()` is built on this)
 - [loopback.md](./loopback.md) — cross-boundary RPC pattern (used by extension host bridge)
-- [workspace.md](./workspace.md) — Workspace design (Think's file tools are backed by this)
+- [workspace.md](./shell/index.md) — Workspace design (Think's file tools are backed by this)
diff --git a/design/voice.md b/design/voice.md
@@ -1,6 +1,6 @@
 # Voice Pipeline — Design (Experimental)
 
-> **Status: experimental.** The voice API is in `@cloudflare/voice` and will break between releases. See `docs/voice.md` for user-facing docs.
+> **Status: experimental.** The voice API is in `@cloudflare/voice` and will break between releases. See `docs/voice/index.md` for user-facing docs.
 
 How the voice pipeline works and why it is built this way.
 
@@ -35,7 +35,7 @@ What you give up:
 - WebRTC-grade network resilience (TCP head-of-line blocking on bad networks)
 - Tightly coupled echo cancellation (browser AEC via `getUserMedia` constraints still works)
 
-SFU integration is documented as an advanced option in `docs/voice.md`.
+SFU integration is documented as an advanced option in `docs/voice/index.md`.
 
 ## Two mixins
 

diff --git a/docs/AGENTS.md b/docs/AGENTS.md
@@ -1,6 +1,6 @@
 # AGENTS.md — docs/
 
-User-facing documentation for the Agents SDK. These markdown files are manually synced to [developers.cloudflare.com/agents/](https://developers.cloudflare.com/agents/).
+User-facing documentation for the Agents SDK monorepo. Each package owns the directory under `docs/` matching its unscoped package name. These markdown files are manually synced to [developers.cloudflare.com/agents/](https://developers.cloudflare.com/agents/) where applicable.
 
 ## Diátaxis framework
 
@@ -31,14 +31,15 @@ There is no automated sync workflow. Changes here must be manually ported to `cl
 - Be concrete: code snippets over prose, real examples over abstract descriptions
 - No contractions (Cloudflare style guide requirement — "do not" not "don't")
 - Use TypeScript for all code examples
-- Link to related docs within this folder using relative paths (`./state.md`)
+- Link within a package directory using relative paths (`./state.md`)
+- Link across package directories with an absolute repository URL, and name the installed package path in prose when relevant
 
 ## Adding a new doc
 
-1. Write the markdown file in this folder
-2. Add it to `index.md` in the appropriate section
+1. Write the markdown file in the directory owned by its package
+2. Add it to that package's `index.md`
 3. If it documents a design decision, consider whether a companion entry in `/design` is warranted
 
 ## TODO backlog
 
-`index.md` has ~15 entries marked `TODO` — these are known gaps. When filling one, remove the TODO marker and follow the steps above.
+`agents/index.md` has entries marked `TODO` — these are known gaps. When filling one, remove the TODO marker and follow the steps above.
diff --git a/docs/adding-to-existing-project.md → docs/agents/adding-to-existing-project.md b/docs/adding-to-existing-project.md → docs/agents/adding-to-existing-project.md
diff --git a/docs/agent-class.md → docs/agents/agent-class.md b/docs/agent-class.md → docs/agents/agent-class.md
diff --git a/docs/agent-tools.md → docs/agents/agent-tools.md b/docs/agent-tools.md → docs/agents/agent-tools.md
@@ -16,7 +16,7 @@ For Think children, prefer agent tools when the parent model or workflow
 delegates work and you want retained child runs, event replay, abort bridging,
 and UI drill-in. Use raw `subAgent(...).chat()` only for lower-level streaming
 RPC where your code owns forwarding, cancellation, and replay policy. For the
-full comparison, see [Choosing a turn API](./think/index.md#choosing-a-turn-api).
+full comparison, see [Choosing a turn API](https://github.com/cloudflare/agents/blob/main/docs/think/index.md#choosing-a-turn-api).
 
 ## Use an Agent as an AI SDK tool
 

diff --git a/docs/browse-the-web.md → docs/agents/browse-the-web.md b/docs/browse-the-web.md → docs/agents/browse-the-web.md
@@ -140,7 +140,7 @@ export class MyAgent extends Agent<Env> {
 }
 ```
 
-> Using `@cloudflare/think`? The unified execute tool (`createExecuteTool(this)`) already includes `cdp.*` alongside `state.*` and `tools.*` when `env.BROWSER` is bound. See the [Think tools documentation](./think/tools.md).
+> Using `@cloudflare/think`? The unified execute tool (`createExecuteTool(this)`) already includes `cdp.*` alongside `state.*` and `tools.*` when `env.BROWSER` is bound. See the [Think tools documentation](https://github.com/cloudflare/agents/blob/main/docs/think/tools.md).
 
 ## TanStack AI
 
@@ -427,4 +427,4 @@ Use `cdpUrl` only when you intentionally want to connect to some other CDP-compa
 
 ## Example
 
-See [`examples/ai-chat/`](../examples/ai-chat/) for a working example that combines browser tools with other AI SDK tools, MCP servers, and tool approval, and [`examples/codemode-connectors/`](../examples/codemode-connectors/) for the connector playground (including in-sandbox approvals).
+See [`examples/ai-chat/`](https://github.com/cloudflare/agents/tree/main/examples/ai-chat) for a working example that combines browser tools with other AI SDK tools, MCP servers, and tool approval, and [`examples/codemode-connectors/`](https://github.com/cloudflare/agents/tree/main/examples/codemode-connectors) for the connector playground (including in-sandbox approvals).
diff --git a/docs/callable-methods.md → docs/agents/callable-methods.md b/docs/callable-methods.md → docs/agents/callable-methods.md
diff --git a/docs/chat-agents.md → docs/agents/chat-agents.md b/docs/chat-agents.md → docs/agents/chat-agents.md
@@ -845,7 +845,7 @@ The right strategy depends on whether the provider supports assistant prefill an
 | OpenAI (Responses API) | Retrieve completed response by ID — zero wasted tokens       | Zero       |
 | Anthropic              | Persist partial, send a synthetic user message to continue   | Medium     |
 
-For a complete multi-provider implementation, see the [`forever-chat` example](../experimental/forever-chat/) and the [`forever.md` design doc](../experimental/forever.md). For how chat recovery fits into the broader long-running agents story, see [Long-Running Agents: Recovering interrupted LLM streams](./long-running-agents.md#recovering-interrupted-llm-streams).
+For a complete multi-provider implementation, see the [`forever-chat` example](https://github.com/cloudflare/agents/tree/main/experimental/forever-chat) and the [`forever.md` design doc](https://github.com/cloudflare/agents/tree/main/experimental/forever.md). For how chat recovery fits into the broader long-running agents story, see [Long-Running Agents: Recovering interrupted LLM streams](./long-running-agents.md#recovering-interrupted-llm-streams).
 
 ## Client API
 
@@ -1669,11 +1669,11 @@ The chat protocol uses typed JSON messages over WebSocket:
 
 ## Examples
 
-- [AI Chat Example](../examples/ai-chat/) — Modern example with server tools, client tools, and approval
-- [Dynamic Tools](../examples/dynamic-tools/) — SDK/platform pattern with dynamic client-defined tools
-- [Resumable Stream Chat](../examples/resumable-stream-chat/) — Automatic stream resumption demo
-- [Human in the Loop Guide](../guides/human-in-the-loop/) — Tool approval with `needsApproval` and `onToolCall`
-- [Playground](../examples/playground/) — Kitchen-sink demo of all SDK features
+- [AI Chat Example](https://github.com/cloudflare/agents/tree/main/examples/ai-chat) — Modern example with server tools, client tools, and approval
+- [Dynamic Tools](https://github.com/cloudflare/agents/tree/main/examples/dynamic-tools) — SDK/platform pattern with dynamic client-defined tools
+- [Resumable Stream Chat](https://github.com/cloudflare/agents/tree/main/examples/resumable-stream-chat) — Automatic stream resumption demo
+- [Human in the Loop Guide](https://github.com/cloudflare/agents/tree/main/guides/human-in-the-loop) — Tool approval with `needsApproval` and `onToolCall`
+- [Playground](https://github.com/cloudflare/agents/tree/main/examples/playground) — Kitchen-sink demo of all SDK features
 
 ## Related Docs
 

diff --git a/docs/chat-sdk.md → docs/agents/chat-sdk.md b/docs/chat-sdk.md → docs/agents/chat-sdk.md
diff --git a/docs/client-sdk.md → docs/agents/client-sdk.md b/docs/client-sdk.md → docs/agents/client-sdk.md
diff --git a/docs/client-tools-continuation.md → docs/agents/client-tools-continuation.md b/docs/client-tools-continuation.md → docs/agents/client-tools-continuation.md
diff --git a/docs/configuration.md → docs/agents/configuration.md b/docs/configuration.md → docs/agents/configuration.md
diff --git a/docs/cross-domain-authentication.md → docs/agents/cross-domain-authentication.md b/docs/cross-domain-authentication.md → docs/agents/cross-domain-authentication.md
diff --git a/docs/durable-execution.md → docs/agents/durable-execution.md b/docs/durable-execution.md → docs/agents/durable-execution.md
@@ -466,7 +466,7 @@ Key points:
 
 ### Chat recovery
 
-`AIChatAgent` builds on fibers for LLM streaming recovery. When `chatRecovery` is enabled, each chat turn is wrapped in a fiber automatically. The framework handles the internal recovery path and exposes `onChatRecovery` for provider-specific strategies. See [Long-Running Agents: Recovering interrupted LLM streams](./long-running-agents.md#recovering-interrupted-llm-streams) and the [`forever-chat` example](../experimental/forever-chat/).
+`AIChatAgent` builds on fibers for LLM streaming recovery. When `chatRecovery` is enabled, each chat turn is wrapped in a fiber automatically. The framework handles the internal recovery path and exposes `onChatRecovery` for provider-specific strategies. See [Long-Running Agents: Recovering interrupted LLM streams](./long-running-agents.md#recovering-interrupted-llm-streams) and the [`forever-chat` example](https://github.com/cloudflare/agents/tree/main/experimental/forever-chat).
 
 ## Concurrent fibers
 
@@ -533,5 +533,5 @@ Run an async function while keeping the DO alive. Heartbeat starts before `fn` a
 - [Scheduling](./scheduling.md) — `keepAlive` details and the alarm system
 - [Workflows](./workflows.md) — durable multi-step execution outside the agent
 - [Chat Agents](./chat-agents.md) — `chatRecovery` and `onChatRecovery`
-- [`forever-chat` example](../experimental/forever-chat/) — multi-provider LLM recovery demo
-- [`forever.md` design doc](../experimental/forever.md) — internal design details, tradeoffs, and architecture
+- [`forever-chat` example](https://github.com/cloudflare/agents/tree/main/experimental/forever-chat) — multi-provider LLM recovery demo
+- [`forever.md` design doc](https://github.com/cloudflare/agents/tree/main/experimental/forever.md) — internal design details, tradeoffs, and architecture
diff --git a/docs/email.md → docs/agents/email.md b/docs/email.md → docs/agents/email.md
diff --git a/docs/get-current-agent.md → docs/agents/get-current-agent.md b/docs/get-current-agent.md → docs/agents/get-current-agent.md
diff --git a/docs/getting-started.md → docs/agents/getting-started.md b/docs/getting-started.md → docs/agents/getting-started.md
diff --git a/docs/http-websockets.md → docs/agents/http-websockets.md b/docs/http-websockets.md → docs/agents/http-websockets.md
diff --git a/docs/human-in-the-loop.md → docs/agents/human-in-the-loop.md b/docs/human-in-the-loop.md → docs/agents/human-in-the-loop.md
@@ -25,13 +25,13 @@ Human-in-the-loop (HITL) patterns allow agents to pause execution and wait for h
 
 Agents SDK supports multiple human-in-the-loop patterns. Choose based on your use case:
 
-| Use Case               | Pattern           | Best For                                           | Example                                                           |
-| ---------------------- | ----------------- | -------------------------------------------------- | ----------------------------------------------------------------- |
-| Long-running workflows | Workflow Approval | Multi-step processes, durable approval gates       | [examples/workflows/](../examples/workflows/)                     |
-| AIChatAgent tools      | `needsApproval`   | Chat-based tool calls with `@cloudflare/ai-chat`   | [guides/human-in-the-loop/](../guides/human-in-the-loop/)         |
-| OpenAI Agents SDK      | `needsApproval`   | Using OpenAI's agent SDK with conditional approval | [openai-sdk/human-in-the-loop/](../openai-sdk/human-in-the-loop/) |
-| Client-side tools      | `onToolCall`      | Tools that need browser APIs or user interaction   | Pattern below                                                     |
-| MCP Servers            | Elicitation       | MCP tools requesting structured user input         | [examples/mcp-elicitation/](../examples/mcp-elicitation/)         |
+| Use Case               | Pattern           | Best For                                           | Example                                                                                                      |
+| ---------------------- | ----------------- | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
+| Long-running workflows | Workflow Approval | Multi-step processes, durable approval gates       | [examples/workflows/](https://github.com/cloudflare/agents/tree/main/examples/workflows)                     |
+| AIChatAgent tools      | `needsApproval`   | Chat-based tool calls with `@cloudflare/ai-chat`   | [guides/human-in-the-loop/](https://github.com/cloudflare/agents/tree/main/guides/human-in-the-loop)         |
+| OpenAI Agents SDK      | `needsApproval`   | Using OpenAI's agent SDK with conditional approval | [openai-sdk/human-in-the-loop/](https://github.com/cloudflare/agents/tree/main/openai-sdk/human-in-the-loop) |
+| Client-side tools      | `onToolCall`      | Tools that need browser APIs or user interaction   | Pattern below                                                                                                |
+| MCP Servers            | Elicitation       | MCP tools requesting structured user input         | [examples/mcp-elicitation/](https://github.com/cloudflare/agents/tree/main/examples/mcp-elicitation)         |
 
 ### Decision Guide
 
@@ -350,7 +350,7 @@ This sends a `tool_result` to the LLM with your custom error text, so it can res
 
 `addToolOutput` with `state: "output-error"` does **not** auto-continue — it gives you full control over what happens next. If you want the LLM to respond to the error, call `sendMessage()` afterward.
 
-See the complete example: [guides/human-in-the-loop/](../guides/human-in-the-loop/)
+See the complete example: [guides/human-in-the-loop/](https://github.com/cloudflare/agents/tree/main/guides/human-in-the-loop)
 
 ### Surviving restarts while waiting for a human
 
@@ -448,7 +448,7 @@ export class WeatherAgent extends Agent<Env, AgentState> {
 }
 ```
 
-See the complete example: [openai-sdk/human-in-the-loop/](../openai-sdk/human-in-the-loop/)
+See the complete example: [openai-sdk/human-in-the-loop/](https://github.com/cloudflare/agents/tree/main/openai-sdk/human-in-the-loop)
 
 ### MCP Elicitation
 
@@ -530,7 +530,7 @@ export class MyMcpAgent extends Agent<Env, State> {
 - The **MCP client** (Claude Desktop, etc.) handles UI rendering
 - Returns `{ action: "accept" | "decline", content: {...} }`
 
-See the complete example: [examples/mcp-elicitation/](../examples/mcp-elicitation/)
+See the complete example: [examples/mcp-elicitation/](https://github.com/cloudflare/agents/tree/main/examples/mcp-elicitation)
 
 ## State Patterns for Approvals
 
@@ -647,12 +647,12 @@ async submitForApproval(request: ApprovalRequest): Promise<string> {
 
 ## Complete Examples
 
-| Pattern           | Location                                                          | Description                                        |
-| ----------------- | ----------------------------------------------------------------- | -------------------------------------------------- |
-| Workflow approval | [examples/workflows/](../examples/workflows/)                     | Multi-step task processing with approval gate      |
-| AIChatAgent tools | [guides/human-in-the-loop/](../guides/human-in-the-loop/)         | Chat tool approval with needsApproval + onToolCall |
-| OpenAI Agents SDK | [openai-sdk/human-in-the-loop/](../openai-sdk/human-in-the-loop/) | Conditional tool approval with modal               |
-| MCP Elicitation   | [examples/mcp-elicitation/](../examples/mcp-elicitation/)         | MCP server requesting structured user input        |
+| Pattern           | Location                                                                                                     | Description                                        |
+| ----------------- | ------------------------------------------------------------------------------------------------------------ | -------------------------------------------------- |
+| Workflow approval | [examples/workflows/](https://github.com/cloudflare/agents/tree/main/examples/workflows)                     | Multi-step task processing with approval gate      |
+| AIChatAgent tools | [guides/human-in-the-loop/](https://github.com/cloudflare/agents/tree/main/guides/human-in-the-loop)         | Chat tool approval with needsApproval + onToolCall |
+| OpenAI Agents SDK | [openai-sdk/human-in-the-loop/](https://github.com/cloudflare/agents/tree/main/openai-sdk/human-in-the-loop) | Conditional tool approval with modal               |
+| MCP Elicitation   | [examples/mcp-elicitation/](https://github.com/cloudflare/agents/tree/main/examples/mcp-elicitation)         | MCP server requesting structured user input        |
 
 For detailed API documentation, see: