Organize and ship package-owned docs

Author: mattzcarey

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

.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

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                |

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
 

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:
 

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
 
@@ -544,4 +544,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)

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
 

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.

docs/adding-to-existing-project.md docs/agents/adding-to-existing-project.mddocs/adding-to-existing-project.md renamed to docs/agents/adding-to-existing-project.md

@@ -112,7 +112,7 @@ An important note is that `Server` **does NOT persist to the DO storage** so you
 
 `partyserver` exposes helper to address your DOs instead of manually through your bindings. This allows `partyserver` to implement several improvements, including a unique URL routing scheme for your DOs (e.g. `<your-worker>/servers/:durableClass/:durableName`).
 
-Compare this to the DO addressing [example above](#RPC).
+Compare this to the DO addressing [example above](#rpc).
 
 ```ts
 // Note the await here!