diff --git a/.claude/skills/write-docs/SKILL.md b/.claude/skills/write-docs/SKILL.md
index 6ff4d736d5..ac593ad3e1 100644
--- a/.claude/skills/write-docs/SKILL.md
+++ b/.claude/skills/write-docs/SKILL.md
@@ -57,6 +57,8 @@ AI Transport is the testbed for the new principles. Other Ably products will ali
 
 Pick the template that matches the page you are writing.
 
+**Templates describe structure, not headings.** The numbered items below are the *section shape* — what each section covers and roughly in what order. They are not the literal H2 text for the page. A concept-page template item like "Problem statement" becomes a descriptive imperative on the page itself: `## Why Runs exist`, `## Why sessions exist`. "Model" becomes `## Understand the Run lifecycle`, `## Understand sessions and channels`. "Code proof" becomes `## Trigger a Run`, `## Attach to a session`. Adapt the heading to the specific concept; never copy the template label verbatim. Use imperative or descriptive verb phrases per the writing-style guide.
+
 ### Feature page
 
 A feature page maps to one developer JTBD. The section order below distils the structural pattern feature pages follow.
@@ -380,6 +382,13 @@ grep -rn -E "key\s*:\s*['\"][^'\"]+['\"]" "$P" | grep -v authUrl
 # No "docs under construction" / WIP markers
 grep -rni "under construction\|coming soon\|todo:\|wip\b" "$P"
 
+# Every H2 carries an inline anchor (CLAUDE.md convention: `## Heading <a id="slug"/>`)
+for f in "$P"/*.mdx; do
+  total=$(grep -c "^## " "$f")
+  anchored=$(grep -cE '^## .* <a id="[^"]+"' "$f")
+  [ "$total" != "$anchored" ] && echo "$f: $anchored/$total H2s anchored"
+done
+
 # No em dashes (style guide forbids)
 grep -rn "—" "$P"
 
@@ -474,21 +483,23 @@ When reviewing someone else's docs PR (or your own at PR time), walk this list.
 **Mechanics**
 
 14. Frontmatter complete: `title`, `meta_description`, `meta_keywords`, `intro`, `redirect_from` where the page moved or merged. (Per-interface API reference pages omit `intro`.)
-15. New page added to the relevant nav file under `src/data/nav/`.
-16. `<Aside>` used sparingly and load-bearing. No decorative asides.
-17. Internal links resolve. No references to URLs that only exist in `redirect_from` frontmatter.
+15. Every H2 carries an inline anchor — `## Heading <a id="slug"/>`, per the CLAUDE.md convention. Use the H2-anchor grep above.
+16. Section headings are descriptive imperatives or noun phrases tied to the specific content, not template labels copied verbatim (no `## The model`, `## The problem X solves`, `## Code proof`).
+17. New page added to the relevant nav file under `src/data/nav/`.
+18. `<Aside>` used sparingly and load-bearing. No decorative asides.
+19. Internal links resolve. No references to URLs that only exist in `redirect_from` frontmatter.
 
 **API reference pages only** (additional checks)
 
-18. Method H2s use descriptive verb phrases (`## Create a client transport`), not bare method names. Anchor is JS-canonical kebab-case.
-19. Every method H2 is followed by `<MethodSignature>{` … `}</MethodSignature>` (template-literal form for signatures with `<` or `>`).
-20. Every method with parameters has `### Parameters <a id="{slug}-params"/>` with a 4-column `Parameter | Required | Description | Type` table.
-21. Every method has `### Returns <a id="{slug}-returns"/>` unless it returns `void`/`Unit`.
-22. Type tables default to hidden (`<Table id='X' hidden>`) referenced via `<Table id='X'/>`. Visible types only when they meet one of the four promotion criteria.
-23. Hidden table audit passes. Every hidden has at least one inline reference; every reference has a definition.
-24. Error type referenced via cross-page link to its canonical home (lowercase `#errorinfo` anchor).
-25. Page ends with `## Example` showing end-to-end usage.
-26. No same-page markdown anchor links to type anchors (`[X](#X)`). Type names in prose are backticked; cross-page references go to the type's own page.
+20. Method H2s use descriptive verb phrases (`## Create a client transport`), not bare method names. Anchor is JS-canonical kebab-case.
+21. Every method H2 is followed by `<MethodSignature>{` … `}</MethodSignature>` (template-literal form for signatures with `<` or `>`).
+22. Every method with parameters has `### Parameters <a id="{slug}-params"/>` with a 4-column `Parameter | Required | Description | Type` table.
+23. Every method has `### Returns <a id="{slug}-returns"/>` unless it returns `void`/`Unit`.
+24. Type tables default to hidden (`<Table id='X' hidden>`) referenced via `<Table id='X'/>`. Visible types only when they meet one of the four promotion criteria.
+25. Hidden table audit passes. Every hidden has at least one inline reference; every reference has a definition.
+26. Error type referenced via cross-page link to its canonical home (lowercase `#errorinfo` anchor).
+27. Page ends with `## Example` showing end-to-end usage.
+28. No same-page markdown anchor links to type anchors (`[X](#X)`). Type names in prose are backticked; cross-page references go to the type's own page.
 
 ## When the SDK or product changes shape
 
diff --git a/src/data/languages/languageData.ts b/src/data/languages/languageData.ts
index 730b1c5baf..b7bbd5e8a2 100644
--- a/src/data/languages/languageData.ts
+++ b/src/data/languages/languageData.ts
@@ -44,8 +44,7 @@ export default {
     android: '1.2',
   },
   aiTransport: {
-    javascript: '0.1',
-    react: '0.1',
+    javascript: '0.2',
   },
   spaces: {
     javascript: '0.5',
diff --git a/src/data/nav/aitransport.ts b/src/data/nav/aitransport.ts
index 433af3f1a9..28dc6b6fe0 100644
--- a/src/data/nav/aitransport.ts
+++ b/src/data/nav/aitransport.ts
@@ -29,6 +29,14 @@ export default {
             },
           ],
         },
+        {
+          name: 'Set up authentication',
+          link: '/docs/ai-transport/getting-started/authentication',
+        },
+        {
+          name: 'Enable channel rules',
+          link: '/docs/ai-transport/getting-started/channel-rules',
+        },
       ],
     },
     {
@@ -58,16 +66,24 @@ export default {
           link: '/docs/ai-transport/concepts/sessions',
         },
         {
-          name: 'Conversation tree',
-          link: '/docs/ai-transport/concepts/conversation-tree',
+          name: 'Connections',
+          link: '/docs/ai-transport/concepts/connections',
+        },
+        {
+          name: 'Runs',
+          link: '/docs/ai-transport/concepts/runs',
         },
         {
-          name: 'Turns',
-          link: '/docs/ai-transport/concepts/turns',
+          name: 'Invocations',
+          link: '/docs/ai-transport/concepts/invocations',
         },
         {
-          name: 'Transport',
-          link: '/docs/ai-transport/concepts/transport',
+          name: 'Codecs',
+          link: '/docs/ai-transport/concepts/codecs',
+        },
+        {
+          name: 'Conversation tree',
+          link: '/docs/ai-transport/concepts/conversation-tree',
         },
         {
           name: 'Authentication',
@@ -116,7 +132,7 @@ export default {
           link: '/docs/ai-transport/features/history',
         },
         {
-          name: 'Conversation branching',
+          name: 'Branching, edit, and regenerate',
           link: '/docs/ai-transport/features/branching',
         },
         {
@@ -182,20 +198,38 @@ export default {
           name: 'JavaScript',
           pages: [
             {
-              name: 'Client transport',
-              link: '/docs/ai-transport/api/javascript/client-transport',
-            },
-            {
-              name: 'Server transport',
-              link: '/docs/ai-transport/api/javascript/server-transport',
-            },
-            {
-              name: 'Vercel integration',
-              link: '/docs/ai-transport/api/javascript/vercel',
+              name: 'Core SDK',
+              pages: [
+                {
+                  name: 'Client session',
+                  link: '/docs/ai-transport/api/javascript/core/client-session',
+                },
+                {
+                  name: 'Agent session',
+                  link: '/docs/ai-transport/api/javascript/core/agent-session',
+                },
+                {
+                  name: 'Codec',
+                  link: '/docs/ai-transport/api/javascript/core/codec',
+                },
+              ],
             },
             {
-              name: 'Codec',
-              link: '/docs/ai-transport/api/javascript/codec',
+              name: 'Vercel',
+              pages: [
+                {
+                  name: 'Chat transport',
+                  link: '/docs/ai-transport/api/javascript/vercel/chat-transport',
+                },
+                {
+                  name: 'Codec',
+                  link: '/docs/ai-transport/api/javascript/vercel/codec',
+                },
+                {
+                  name: 'Run outcome',
+                  link: '/docs/ai-transport/api/javascript/vercel/run-outcome',
+                },
+              ],
             },
           ],
         },
@@ -203,40 +237,50 @@ export default {
           name: 'React',
           pages: [
             {
-              name: 'Providers',
-              link: '/docs/ai-transport/api/react/providers',
-            },
-            {
-              name: 'useClientTransport',
-              link: '/docs/ai-transport/api/react/use-client-transport',
-            },
-            {
-              name: 'useView',
-              link: '/docs/ai-transport/api/react/use-view',
-            },
-            {
-              name: 'useCreateView',
-              link: '/docs/ai-transport/api/react/use-create-view',
-            },
-            {
-              name: 'useTree',
-              link: '/docs/ai-transport/api/react/use-tree',
-            },
-            {
-              name: 'useActiveTurns',
-              link: '/docs/ai-transport/api/react/use-active-turns',
-            },
-            {
-              name: 'useAblyMessages',
-              link: '/docs/ai-transport/api/react/use-ably-messages',
-            },
-            {
-              name: 'useChatTransport',
-              link: '/docs/ai-transport/api/react/use-chat-transport',
+              name: 'Core SDK',
+              pages: [
+                {
+                  name: 'Providers',
+                  link: '/docs/ai-transport/api/react/core/providers',
+                },
+                {
+                  name: 'useClientSession',
+                  link: '/docs/ai-transport/api/react/core/use-client-session',
+                },
+                {
+                  name: 'useView',
+                  link: '/docs/ai-transport/api/react/core/use-view',
+                },
+                {
+                  name: 'useCreateView',
+                  link: '/docs/ai-transport/api/react/core/use-create-view',
+                },
+                {
+                  name: 'useTree',
+                  link: '/docs/ai-transport/api/react/core/use-tree',
+                },
+                {
+                  name: 'useAblyMessages',
+                  link: '/docs/ai-transport/api/react/core/use-ably-messages',
+                },
+              ],
             },
             {
-              name: 'useMessageSync',
-              link: '/docs/ai-transport/api/react/use-message-sync',
+              name: 'Vercel',
+              pages: [
+                {
+                  name: 'ChatTransportProvider',
+                  link: '/docs/ai-transport/api/react/vercel/chat-transport-provider',
+                },
+                {
+                  name: 'useChatTransport',
+                  link: '/docs/ai-transport/api/react/vercel/use-chat-transport',
+                },
+                {
+                  name: 'useMessageSync',
+                  link: '/docs/ai-transport/api/react/vercel/use-message-sync',
+                },
+              ],
             },
           ],
         },
diff --git a/src/images/content/diagrams/ai-transport-multi-device-co-pilots-architecture.png b/src/images/content/diagrams/ai-transport-multi-device-co-pilots-architecture.png
deleted file mode 100644
index e8b764fe47..0000000000
Binary files a/src/images/content/diagrams/ai-transport-multi-device-co-pilots-architecture.png and /dev/null differ
diff --git a/src/images/content/diagrams/ait-cancellation.png b/src/images/content/diagrams/ait-cancellation.png
new file mode 100644
index 0000000000..0d4ae8793e
Binary files /dev/null and b/src/images/content/diagrams/ait-cancellation.png differ
diff --git a/src/images/content/diagrams/ait-chain-of-thought.png b/src/images/content/diagrams/ait-chain-of-thought.png
new file mode 100644
index 0000000000..070d3f4ff6
Binary files /dev/null and b/src/images/content/diagrams/ait-chain-of-thought.png differ
diff --git a/src/images/content/diagrams/ait-concepts-codecs.png b/src/images/content/diagrams/ait-concepts-codecs.png
new file mode 100644
index 0000000000..96f731568a
Binary files /dev/null and b/src/images/content/diagrams/ait-concepts-codecs.png differ
diff --git a/src/images/content/diagrams/ait-concepts-connections.png b/src/images/content/diagrams/ait-concepts-connections.png
new file mode 100644
index 0000000000..81f9da6429
Binary files /dev/null and b/src/images/content/diagrams/ait-concepts-connections.png differ
diff --git a/src/images/content/diagrams/ait-concepts-conversation-tree.png b/src/images/content/diagrams/ait-concepts-conversation-tree.png
new file mode 100644
index 0000000000..c6373ee52c
Binary files /dev/null and b/src/images/content/diagrams/ait-concepts-conversation-tree.png differ
diff --git a/src/images/content/diagrams/ait-concepts-invocations.png b/src/images/content/diagrams/ait-concepts-invocations.png
new file mode 100644
index 0000000000..d6ca5a1bcf
Binary files /dev/null and b/src/images/content/diagrams/ait-concepts-invocations.png differ
diff --git a/src/images/content/diagrams/ait-concepts-overview.png b/src/images/content/diagrams/ait-concepts-overview.png
new file mode 100644
index 0000000000..a887d21b45
Binary files /dev/null and b/src/images/content/diagrams/ait-concepts-overview.png differ
diff --git a/src/images/content/diagrams/ait-concepts-runs.png b/src/images/content/diagrams/ait-concepts-runs.png
new file mode 100644
index 0000000000..6c8e5ecbc4
Binary files /dev/null and b/src/images/content/diagrams/ait-concepts-runs.png differ
diff --git a/src/images/content/diagrams/ait-concepts-sessions.png b/src/images/content/diagrams/ait-concepts-sessions.png
new file mode 100644
index 0000000000..4cef07081f
Binary files /dev/null and b/src/images/content/diagrams/ait-concepts-sessions.png differ
diff --git a/src/images/content/diagrams/ait-concurrent-turns.png b/src/images/content/diagrams/ait-concurrent-turns.png
new file mode 100644
index 0000000000..8678ee9a7a
Binary files /dev/null and b/src/images/content/diagrams/ait-concurrent-turns.png differ
diff --git a/src/images/content/diagrams/ait-double-texting.png b/src/images/content/diagrams/ait-double-texting.png
new file mode 100644
index 0000000000..9d2540fc07
Binary files /dev/null and b/src/images/content/diagrams/ait-double-texting.png differ
diff --git a/src/images/content/diagrams/ait-feature-appends.png b/src/images/content/diagrams/ait-feature-appends.png
deleted file mode 100644
index 258cfb9f2d..0000000000
Binary files a/src/images/content/diagrams/ait-feature-appends.png and /dev/null differ
diff --git a/src/images/content/diagrams/ait-history-replay.png b/src/images/content/diagrams/ait-history-replay.png
new file mode 100644
index 0000000000..0d7ffe0d8a
Binary files /dev/null and b/src/images/content/diagrams/ait-history-replay.png differ
diff --git a/src/images/content/diagrams/ait-human-in-the-loop.png b/src/images/content/diagrams/ait-human-in-the-loop.png
new file mode 100644
index 0000000000..16a7d5ee34
Binary files /dev/null and b/src/images/content/diagrams/ait-human-in-the-loop.png differ
diff --git a/src/images/content/diagrams/ait-multi-device-handover.png b/src/images/content/diagrams/ait-multi-device-handover.png
new file mode 100644
index 0000000000..09139d1705
Binary files /dev/null and b/src/images/content/diagrams/ait-multi-device-handover.png differ
diff --git a/src/images/content/diagrams/ait-optimistic-update.png b/src/images/content/diagrams/ait-optimistic-update.png
new file mode 100644
index 0000000000..8bf8ef58b0
Binary files /dev/null and b/src/images/content/diagrams/ait-optimistic-update.png differ
diff --git a/src/images/content/diagrams/ait-overview.png b/src/images/content/diagrams/ait-overview.png
new file mode 100644
index 0000000000..4b7627c47a
Binary files /dev/null and b/src/images/content/diagrams/ait-overview.png differ
diff --git a/src/images/content/diagrams/ait-push-notifications.png b/src/images/content/diagrams/ait-push-notifications.png
new file mode 100644
index 0000000000..42e265579a
Binary files /dev/null and b/src/images/content/diagrams/ait-push-notifications.png differ
diff --git a/src/images/content/diagrams/ait-reconnection-recovery.png b/src/images/content/diagrams/ait-reconnection-recovery.png
new file mode 100644
index 0000000000..60f1f6f287
Binary files /dev/null and b/src/images/content/diagrams/ait-reconnection-recovery.png differ
diff --git a/src/images/content/diagrams/ait-sse-stream-failures.png b/src/images/content/diagrams/ait-sse-stream-failures.png
new file mode 100644
index 0000000000..d86217cb09
Binary files /dev/null and b/src/images/content/diagrams/ait-sse-stream-failures.png differ
diff --git a/src/images/content/diagrams/ait-token-streaming.png b/src/images/content/diagrams/ait-token-streaming.png
new file mode 100644
index 0000000000..03e3c75219
Binary files /dev/null and b/src/images/content/diagrams/ait-token-streaming.png differ
diff --git a/src/images/content/diagrams/ait-tool-calling.png b/src/images/content/diagrams/ait-tool-calling.png
new file mode 100644
index 0000000000..ea9a62e320
Binary files /dev/null and b/src/images/content/diagrams/ait-tool-calling.png differ
diff --git a/src/pages/docs/ai-transport/api/errors.mdx b/src/pages/docs/ai-transport/api/errors.mdx
index 190cdf911e..f0c3246689 100644
--- a/src/pages/docs/ai-transport/api/errors.mdx
+++ b/src/pages/docs/ai-transport/api/errors.mdx
@@ -2,7 +2,7 @@
 title: "Errors"
 meta_description: "ErrorInfo type and numeric error codes for Ably AI Transport. Codes, descriptions, HTTP status, and recovery guidance."
 meta_keywords: "AI Transport errors, ErrorInfo, error codes, error handling, errorInfoIs, Ably"
-intro: "The ErrorInfo type that every AI Transport failure path surfaces, the numeric codes you match against, and the patterns for handling errors on the client and the server."
+intro: "The ErrorInfo type that every AI Transport failure path surfaces, the numeric codes you match against, and the patterns for handling errors on the client and the agent."
 redirect_from:
   - /docs/ai-transport/api-reference/error-codes
   - /docs/ai-transport/api-reference/errors
@@ -32,24 +32,26 @@ The `ErrorInfo` type is exported from `ably`. AI Transport surfaces it as the re
 
 ### General errors <a id="general"/>
 
-| Code | Name | HTTP status | Description | Recovery |
-| --- | --- | --- | --- | --- |
-| 40000 | BadRequest | 400 | The request was malformed or missing required fields. | Check the request payload and ensure all required fields are present. |
-| 40003 | InvalidArgument | 400 | An argument passed to a transport method was invalid. | Verify the arguments match the expected types and constraints. |
-
-### Transport errors <a id="transport"/>
-
-| Code | Name | HTTP status | Description | Recovery |
-| --- | --- | --- | --- | --- |
-| 104000 | EncoderRecoveryFailed | 500 | The encoder failed to recover after a publish error. The turn cannot continue. | End the turn with reason `'error'` and start a new one. The client sees the partial response up to the failure point. |
-| 104001 | TransportSubscriptionError | 500 | A channel subscription callback threw unexpectedly. | Check the subscription callback for unhandled exceptions. Inspect the underlying error for details. |
-| 104002 | CancelListenerError | 500 | The transport failed to register or process a cancel listener. | The turn does not respond to cancel signals. End the turn manually if needed. |
-| 104003 | TurnLifecycleError | 500 | A turn lifecycle event failed to publish. | Check channel permissions and connection state. The turn-start or turn-end message could not be published. |
-| 104004 | TransportClosed | 400 | An operation was attempted on a transport that has been closed. | Create a new transport instance. Do not reuse a closed transport. |
-| 104005 | TransportSendFailed | 500 | The client transport failed to send a message to the API endpoint. | Check the API endpoint URL, network connectivity, and authentication. Inspect the underlying error for details. |
-| 104006 | ChannelContinuityLost | 500 | The Ably channel lost message continuity. The channel entered `FAILED`, `SUSPENDED`, or `DETACHED`, or re-attached with `resumed: false`. Active streams cannot be guaranteed to receive all events. | Surfaced via the transport's `on('error')` and the server transport's `onError` option. Active turns should be ended; subsequent operations can resume once the channel reattaches. |
-| 104007 | ChannelNotReady | 500 | An operation was attempted but the channel is not in a usable state (not `ATTACHED` or `ATTACHING`). | Wait for the channel to attach before retrying, or inspect channel state and connection state for the underlying cause. |
-| 104008 | StreamError | 500 | An error occurred while piping a response stream to the channel. Either the source event stream threw (LLM provider rate limit, model error, network failure) or an underlying publish failed mid-stream. | Inspect `cause` for the provider error. End the turn with reason `'error'`. |
+| Code  | Name                   | HTTP status | Description                                                                                          | Recovery                                                                                          |
+| ----- | ---------------------- | ----------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
+| 40000 | BadRequest             | 400         | The request was malformed or missing required fields.                                                | Check the request payload and ensure all required fields are present.                             |
+| 40003 | InvalidArgument        | 400         | An argument passed to a session or run method was invalid.                                           | Verify the arguments match the expected types and constraints.                                    |
+| 40160 | InsufficientCapability | 401         | The Ably channel rejected a publish for a capability reason. The token does not permit the operation. | Add the missing capability to the token. See [authentication](/docs/ai-transport/concepts/authentication). |
+
+### Session and run errors <a id="session-run"/>
+
+| Code   | Name                     | HTTP status | Description                                                                                                                                                                                                                       | Recovery                                                                                                                                                          |
+| ------ | ------------------------ | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 104000 | EncoderRecoveryFailed    | 500         | The encoder failed to recover after a publish error. One or more `updateMessage` calls could not recover a failed append pipeline.                                                                                                | End the Run with reason `'error'` and start a new one. The client sees the partial response up to the failure point.                                              |
+| 104001 | SessionSubscriptionError | 500         | A session-level channel subscription callback threw unexpectedly.                                                                                                                                                                 | Check the subscription callback for unhandled exceptions. Inspect the underlying error for details.                                                               |
+| 104002 | CancelListenerError      | 500         | The cancel listener or `onCancel` hook threw while processing a cancel message.                                                                                                                                                   | Check the `onCancel` hook for unhandled exceptions. The Run may not respond to subsequent cancels.                                                                |
+| 104003 | RunLifecycleError        | 500         | A publish within a Run failed (lifecycle event, message, or codec event).                                                                                                                                                         | Check channel permissions and connection state. Surface the error to the calling HTTP handler so the client's pending send fails.                                 |
+| 104004 | SessionClosed            | 400         | An operation was attempted on a session that has already been closed.                                                                                                                                                             | Create a new session. Do not reuse a closed session.                                                                                                              |
+| 104005 | SessionSendFailed        | 500         | A send failed: either the core's channel publish failed, or the Vercel chat transport's agent-invocation POST failed (network error or non-2xx response).                                                                                                                                                   | Check the API endpoint URL, network connectivity, and authentication. Inspect the underlying error for details.                                                   |
+| 104006 | ChannelContinuityLost    | 500         | The Ably channel lost message continuity. The channel entered `FAILED`, `SUSPENDED`, or `DETACHED`, or re-attached with `resumed: false`. Active streams can no longer be guaranteed to receive all events.                       | Surfaced via the session's `on('error')` and the agent session's `onError` option. End active Runs; subsequent operations can resume once the channel reattaches. |
+| 104007 | ChannelNotReady          | 400         | An operation was attempted but the channel is not in a usable state (not `ATTACHED` or `ATTACHING`).                                                                                                                              | Wait for the channel to attach before retrying, or inspect channel state and connection state for the underlying cause.                                           |
+| 104008 | StreamError              | 500         | An error occurred while piping a response stream to the channel. Either the source event stream threw (LLM provider rate limit, model error, network failure) or an underlying publish failed mid-stream.                         | Inspect `cause` for the provider error. End the Run with reason `'error'`. The error is also returned on `StreamResult.error` from `Run.pipe`.                    |
+| 104010 | InputEventNotFound       | 504         | The agent attached to the channel and waited for the input events the invocation points at (rewind + live wait) but `inputEventLookupTimeoutMs` lapsed without seeing them.                                                       | Surface the rejection from `Run.start()` as a non-2xx response so the client's pending send fails. The client retries with a fresh send.                          |
 
 ### Auth and channel errors <a id="platform"/>
 
@@ -58,7 +60,6 @@ Auth and channel errors come from the Ably platform, not AI Transport. The most
 | Code | Description | Recovery |
 | --- | --- | --- |
 | 40142 | Token expired. | Refresh the token (handled automatically with `authUrl`/`authCallback`). |
-| 40160 | Token capability does not permit the operation. | Add the missing capability to the token. See [authentication](/docs/ai-transport/concepts/authentication). |
 | 40300 | Forbidden. | The token is valid but not authorised for this resource. |
 | 80000 | Channel attach failed. | Check the channel name and capability. |
 | 90000 | Internal channel error. | Retry the operation. If the error persists, contact support. |
@@ -75,50 +76,55 @@ The full Ably error code list lives at [Ably error codes](/docs/sdks/error-codes
 ```javascript
 import { errorInfoIs, ErrorCode } from '@ably/ai-transport';
 
-transport.on('error', (error) => {
-  if (errorInfoIs(error, ErrorCode.TransportClosed)) {
+session.on('error', (error) => {
+  if (errorInfoIs(error, ErrorCode.SessionClosed)) {
     reconnect();
   }
 });
 ```
 </Code>
 
-## Example
+## Example <a id="example"/>
+
+Handle session-level and run-level errors separately. The client subscribes to session errors. The agent uses the `onError` option on `AgentSessionOptions` for session-wide events and the run runtime's `onError` for per-Run failures.
 
 <Code>
 ```javascript
 import { errorInfoIs, ErrorCode } from '@ably/ai-transport';
 
-// Client-side: subscribe to transport-level errors.
-transport.on('error', (error) => {
+// Client side: subscribe to session-level errors.
+session.on('error', (error) => {
   console.error(`Error ${error.code}: ${error.message}`);
-  if (errorInfoIs(error, ErrorCode.TransportClosed)) {
-    reconnect();
+  if (errorInfoIs(error, ErrorCode.ChannelContinuityLost)) {
+    showReconnectBanner();
   }
 });
 
-// Server-side: handle transport and turn-level errors separately.
-const serverTransport = createServerTransport({
-  channel,
+// Agent side: handle session and run-level errors separately.
+const agentSession = createAgentSession({
+  client: ably,
+  channelName,
   codec,
   onError(error) {
-    console.error('Transport error:', error);
+    console.error('Session error:', error);
   },
 });
 
-const turn = serverTransport.newTurn({
-  turnId,
+await agentSession.connect();
+
+const run = agentSession.createRun(invocation, {
+  signal: req.signal,
   onError(error) {
-    console.error('Turn error:', error);
+    console.error('Run error:', error);
   },
 });
 
-// End a turn with reason 'error' when streaming fails.
+// End a Run with reason 'error' when piping fails.
 try {
-  const { reason } = await turn.streamResponse(llmStream);
-  await turn.end(reason);
+  const result = await run.pipe(llmStream);
+  await run.end(result.reason);
 } catch (error) {
-  await turn.end('error');
+  await run.end('error');
 }
 ```
 </Code>
diff --git a/src/pages/docs/ai-transport/api/index.mdx b/src/pages/docs/ai-transport/api/index.mdx
index 38d489c990..910457785b 100644
--- a/src/pages/docs/ai-transport/api/index.mdx
+++ b/src/pages/docs/ai-transport/api/index.mdx
@@ -1,7 +1,7 @@
 ---
 title: "API reference"
-meta_description: "API reference for Ably AI Transport. Client transport, server transport, React hooks, Vercel integration, codec, and errors."
-meta_keywords: "API reference, AI Transport, client transport, server transport, React hooks, Vercel, codec, errors, Ably"
+meta_description: "API reference for Ably AI Transport. Sessions, codec, React hooks, Vercel integration, and errors."
+meta_keywords: "API reference, AI Transport, ClientSession, AgentSession, codec, React hooks, Vercel, errors, Ably"
 intro: "Reference for every public API surface in the @ably/ai-transport package. The SDK is organised into four entry points so you only import what you need."
 redirect_from:
   - /docs/ai-transport/api-reference
@@ -11,42 +11,164 @@ This reference covers every public API surface in the `@ably/ai-transport` packa
 
 ## Quick example <a id="quick-example"/>
 
-A minimal client transport setup:
+A minimal client session setup using the Vercel-pre-bound factory:
 
 <Code>
 ```javascript
 import * as Ably from 'ably';
-import { createClientTransport } from '@ably/ai-transport/vercel';
+import { createClientSession } from '@ably/ai-transport/vercel';
 
-const ably = new Ably.Realtime({ authUrl: '/auth' });
-const channel = ably.channels.get('conversation-42');
+const ably = new Ably.Realtime({ authUrl: '/api/auth/token' });
 
-const transport = createClientTransport({ channel });
+const session = createClientSession({
+  client: ably,
+  channelName: 'conversation-42',
+});
+
+await session.connect();
 ```
 </Code>
 
 See the individual reference pages for the full API.
 
-## API surfaces <a id="surfaces"/>
-
-| Surface | Description | Reference |
-| --- | --- | --- |
-| ClientTransport | Subscribe to turns, build conversation views, cancel and control from the client. | [ClientTransport](/docs/ai-transport/api/javascript/client-transport) |
-| ServerTransport | Manage turn lifecycle, stream responses, handle cancellation on the server. | [ServerTransport](/docs/ai-transport/api/javascript/server-transport) |
-| Vercel AI SDK integration | Pre-built codec and factories for the Vercel AI SDK. | [Vercel AI SDK integration](/docs/ai-transport/api/javascript/vercel) |
-| Codec | Interface for bridging any AI framework to Ably messages. | [Codec](/docs/ai-transport/api/javascript/codec) |
-| Errors | The `ErrorInfo` type and numeric error codes with recovery guidance. | [Errors](/docs/ai-transport/api/errors) |
-| React | Providers and hooks for building chat UIs. | [Providers](/docs/ai-transport/api/react/providers) and the per-hook pages under `react/`. |
-
 ## Entry points <a id="entry-points"/>
 
 | Entry point | Import path | Contents |
 | --- | --- | --- |
-| Core | `@ably/ai-transport` | `createClientTransport`, `createServerTransport`, codec interfaces |
-| React | `@ably/ai-transport/react` | Generic React hooks (`useClientTransport`, `useView`, and so on) |
-| Vercel | `@ably/ai-transport/vercel` | `UIMessageCodec`, Vercel-specific transport factories |
-| Vercel React | `@ably/ai-transport/vercel/react` | `useChatTransport`, `useMessageSync` |
+| Core | `@ably/ai-transport` | `createClientSession`, `createAgentSession`, `Invocation`, `Codec` interface |
+| React | `@ably/ai-transport/react` | `ClientSessionProvider`, `useClientSession`, `useView`, `useTree`, `useCreateView`, `useAblyMessages`, `createSessionHooks` |
+| Vercel | `@ably/ai-transport/vercel` | `UIMessageCodec`, Vercel-bound `createClientSession` and `createAgentSession`, `createChatTransport`, `vercelRunOutcome` |
+| Vercel React | `@ably/ai-transport/vercel/react` | `ChatTransportProvider`, `useChatTransport`, `useMessageSync`, plus the Vercel-baked re-exports of `ClientSessionProvider`, `useClientSession`, `useView`, `useCreateView`, `useTree`, and `useAblyMessages` |
 
 <Aside data-type='note'>
-The Vercel entry points re-export the core transport factories with the codec pre-bound. If you use `@ably/ai-transport/vercel`, you do not need to import from `@ably/ai-transport` separately.
+The Vercel entry points re-export the core factories with the codec pre-bound. If you use `@ably/ai-transport/vercel`, you do not need to import from `@ably/ai-transport` separately.
 </Aside>
+
+## JavaScript <a id="javascript"/>
+
+### Core
+
+<Tiles>
+{[
+  {
+    title: 'ClientSession',
+    description: 'Subscribe to a channel, build a conversation tree, send messages, and cancel Runs from the client.',
+    image: 'icon-product-pubsub',
+    link: '/docs/ai-transport/api/javascript/core/client-session',
+  },
+  {
+    title: 'AgentSession',
+    description: 'Manage Run lifecycles, publish lifecycle events, and pipe streamed assistant output from the server.',
+    image: 'icon-product-pubsub',
+    link: '/docs/ai-transport/api/javascript/core/agent-session',
+  },
+  {
+    title: 'Codec',
+    description: 'Bridge any AI framework to Ably channel messages by implementing the codec contract.',
+    image: 'icon-product-pubsub',
+    link: '/docs/ai-transport/api/javascript/core/codec',
+  },
+]}
+</Tiles>
+
+### Vercel
+
+<Tiles>
+{[
+  {
+    title: 'ChatTransport',
+    description: 'The Vercel-bound session factories and the ChatTransport adapter for useChat.',
+    image: 'icon-tech-vercel',
+    link: '/docs/ai-transport/api/javascript/vercel/chat-transport',
+  },
+  {
+    title: 'UIMessageCodec',
+    description: 'The pre-built codec for the Vercel AI SDK and its type parameters.',
+    image: 'icon-tech-vercel',
+    link: '/docs/ai-transport/api/javascript/vercel/codec',
+  },
+  {
+    title: 'vercelRunOutcome',
+    description: 'Map a Vercel streamText finish reason and a pipe result to the RunEndReason for Run.end.',
+    image: 'icon-tech-vercel',
+    link: '/docs/ai-transport/api/javascript/vercel/run-outcome',
+  },
+]}
+</Tiles>
+
+## React <a id="react"/>
+
+### Core
+
+<Tiles>
+{[
+  {
+    title: 'Providers',
+    description: 'ClientSessionProvider and the createSessionHooks factory for baking codec types into the hooks.',
+    image: 'icon-tech-react',
+    link: '/docs/ai-transport/api/react/core/providers',
+  },
+  {
+    title: 'useClientSession',
+    description: 'Read a ClientSession from the nearest provider.',
+    image: 'icon-tech-react',
+    link: '/docs/ai-transport/api/react/core/use-client-session',
+  },
+  {
+    title: 'useView',
+    description: 'Subscribe to the session\'s default view: visible messages, branch navigation, send and regenerate.',
+    image: 'icon-tech-react',
+    link: '/docs/ai-transport/api/react/core/use-view',
+  },
+  {
+    title: 'useCreateView',
+    description: 'Create an independent view with its own branch selection and pagination state.',
+    image: 'icon-tech-react',
+    link: '/docs/ai-transport/api/react/core/use-create-view',
+  },
+  {
+    title: 'useTree',
+    description: 'Stable structural query callbacks for inspecting Runs outside the visible branch.',
+    image: 'icon-tech-react',
+    link: '/docs/ai-transport/api/react/core/use-tree',
+  },
+  {
+    title: 'useAblyMessages',
+    description: 'Accumulate the raw Ably InboundMessages observed on the session\'s channel.',
+    image: 'icon-tech-react',
+    link: '/docs/ai-transport/api/react/core/use-ably-messages',
+  },
+]}
+</Tiles>
+
+### Vercel
+
+<Tiles>
+{[
+  {
+    title: 'useChatTransport',
+    description: 'Read a ChatTransport and its underlying ClientSession from the nearest ChatTransportProvider.',
+    image: 'icon-tech-vercel',
+    link: '/docs/ai-transport/api/react/vercel/use-chat-transport',
+  },
+  {
+    title: 'useMessageSync',
+    description: 'Sync view updates into useChat\'s setMessages so observer tabs see new messages live.',
+    image: 'icon-tech-vercel',
+    link: '/docs/ai-transport/api/react/vercel/use-message-sync',
+  },
+]}
+</Tiles>
+
+## Errors <a id="errors"/>
+
+<Tiles>
+{[
+  {
+    title: 'Errors',
+    description: 'The ErrorInfo type and the numeric error codes with recovery guidance.',
+    image: 'icon-gui-warning',
+    link: '/docs/ai-transport/api/errors',
+  },
+]}
+</Tiles>
diff --git a/src/pages/docs/ai-transport/api/javascript/client-transport.mdx b/src/pages/docs/ai-transport/api/javascript/client-transport.mdx
deleted file mode 100644
index ec9e40acef..0000000000
--- a/src/pages/docs/ai-transport/api/javascript/client-transport.mdx
+++ /dev/null
@@ -1,562 +0,0 @@
----
-title: "ClientTransport"
-meta_description: "API reference for the AI Transport client transport: options, properties, methods, the View interface, and the ActiveTurn type."
-meta_keywords: "AI Transport, ClientTransport, View, createClientTransport, ActiveTurn, cancel, waitForTurn, Ably"
-redirect_from:
-  - /docs/ai-transport/api-reference/client-transport
----
-
-The `ClientTransport` subscribes to an Ably channel, decodes incoming messages through a codec, and builds a conversation tree. It exposes a default branch-aware `View` for rendering, plus methods for cancellation, turn tracking, and lifecycle management.
-
-Construct one with `createClientTransport` from the core entry point, or use the Vercel-pre-bound factory from `@ably/ai-transport/vercel` when the channel carries Vercel `UIMessage` content.
-
-<Code>
-```javascript
-import { createClientTransport } from '@ably/ai-transport';
-import { UIMessageCodec } from '@ably/ai-transport/vercel';
-
-const transport = createClientTransport({
-  channel,
-  codec: UIMessageCodec,
-  api: '/api/chat',
-});
-```
-</Code>
-
-## Properties
-
-The `ClientTransport` instance has the following properties:
-
-<Table id='ClientTransportProperties'>
-
-| Property | Description | Type |
-| --- | --- | --- |
-| tree | The complete conversation tree. Holds every known node, emits events on any change. Use the view in most cases; reach for the tree for low-level inspection. | <Table id='Tree'/> |
-| view | The default paginated, branch-aware view for rendering. Events are scoped to the visible messages. | `View` |
-
-</Table>
-
-<Table id='Tree' hidden>
-
-| Property | Description | Type |
-| --- | --- | --- |
-| getNode | `(msgId: string) => MessageNode \| undefined`. Get a node by message ID. | Function |
-| getHeaders | `(msgId: string) => Record<string, string> \| undefined`. Get the stored transport headers for a node. | Function |
-| getSiblings | `(msgId: string) => TMessage[]`. Get all sibling messages at a fork point. | Function |
-| hasSiblings | `(msgId: string) => boolean`. Whether a message has sibling alternatives. | Function |
-| upsert | `(msgId: string, message: TMessage, headers: Record<string, string>, serial?: string) => void`. Insert or update a message in the tree. | Function |
-| delete | `(msgId: string) => void`. Remove a message from the tree. | Function |
-| getActiveTurnIds | `() => Map<string, Set<string>>`. Active turn IDs grouped by `clientId` across the whole tree. | Function |
-| on | `(event: 'update' \| 'ably-message' \| 'turn', handler) => () => void`. Subscribe to tree structure changes, raw Ably messages, or turn lifecycle events. Returns an unsubscribe function. | Function |
-
-</Table>
-
-## Create a client transport <a id="constructor"/>
-
-<MethodSignature>{`function createClientTransport<TEvent, TMessage>(options: ClientTransportOptions<TEvent, TMessage>): ClientTransport<TEvent, TMessage>`}</MethodSignature>
-
-Construct a `ClientTransport` bound to an Ably channel. The transport attaches to the channel lazily on first use.
-
-<Code>
-```javascript
-import * as Ably from 'ably';
-import { createClientTransport } from '@ably/ai-transport';
-import { UIMessageCodec } from '@ably/ai-transport/vercel';
-
-const ably = new Ably.Realtime({ authUrl: '/auth' });
-const channel = ably.channels.get('conversation-42');
-
-const transport = createClientTransport({
-  channel,
-  codec: UIMessageCodec,
-  api: '/api/chat',
-});
-```
-</Code>
-
-### Parameters <a id="constructor-params"/>
-
-<Table id='CreateClientTransportParameters'>
-
-| Parameter | Required | Description | Type |
-| --- | --- | --- | --- |
-| options | Required | Configuration for the client transport. | <Table id='ClientTransportOptions'/> |
-
-</Table>
-
-<Table id='ClientTransportOptions' hidden>
-
-| Property | Description | Type |
-| --- | --- | --- |
-| channel | The Ably channel to receive responses on and publish cancel signals to. | `Ably.RealtimeChannel` |
-| codec | The codec to use for encoding and decoding messages. See [Codec](/docs/ai-transport/api/javascript/codec). | `Codec<TEvent, TMessage>` |
-| api | Server endpoint URL for the HTTP POST that triggers a new turn. The Vercel-pre-bound factory defaults this to `/api/chat`; the core factory requires it. | String |
-| clientId | The client's identity. Sent to the server in the POST body. | String or Undefined |
-| headers | Headers for the HTTP POST. Function form for dynamic values such as auth tokens. | `Record<string, string>` or `() => Record<string, string>` or Undefined |
-| body | Additional body fields merged into the HTTP POST. Function form for dynamic values. | `Record<string, unknown>` or `() => Record<string, unknown>` or Undefined |
-| credentials | Fetch credentials mode for the HTTP POST. | `RequestCredentials` or Undefined |
-| fetch | Custom fetch implementation. Defaults to `globalThis.fetch`. | `typeof fetch` or Undefined |
-| messages | Initial messages to seed the conversation tree with. Forms a linear chain. | `TMessage[]` or Undefined |
-| logger | Logger instance for diagnostic output. | `Logger` or Undefined |
-
-</Table>
-
-### Returns <a id="constructor-returns"/>
-
-`ClientTransport<TEvent, TMessage>`
-
-A new client transport. Lifecycle is managed by the caller; call `close()` to release resources.
-
-## Create an additional view <a id="create-view"/>
-
-<MethodSignature>{`createView(): View<TEvent, TMessage>`}</MethodSignature>
-
-Create an additional `View` over the same conversation tree. Each view has independent branch selections and pagination state. The caller is responsible for closing the returned view when it is no longer needed, or it will be closed when the transport closes.
-
-<Code>
-```javascript
-const sideView = transport.createView();
-```
-</Code>
-
-### Returns <a id="create-view-returns"/>
-
-`View<TEvent, TMessage>`
-
-A new view bound to the same tree as `transport.view`.
-
-## Cancel turns <a id="cancel"/>
-
-<MethodSignature>{`cancel(filter?: CancelFilter): Promise<void>`}</MethodSignature>
-
-Publish a cancel signal on the channel for every turn that matches `filter`. Defaults to `{ own: true }` (every turn started by this client).
-
-<Code>
-```javascript
-await transport.cancel();                          // cancel own turns
-await transport.cancel({ turnId: 'abc' });         // cancel one specific turn
-await transport.cancel({ all: true });             // cancel every turn on the channel
-```
-</Code>
-
-### Parameters <a id="cancel-params"/>
-
-<Table id='CancelParameters'>
-
-| Parameter | Required | Description | Type |
-| --- | --- | --- | --- |
-| filter | Optional | Scope of the cancellation. Defaults to `{ own: true }`. | <Table id='CancelFilter'/> |
-
-</Table>
-
-<Table id='CancelFilter' hidden>
-
-| Property | Description | Type |
-| --- | --- | --- |
-| turnId | Cancel a specific turn by ID. | String or Undefined |
-| own | Cancel every turn belonging to the sender's `clientId`. | Boolean or Undefined |
-| clientId | Cancel every turn belonging to a specific `clientId`. | String or Undefined |
-| all | Cancel every turn on the channel. | Boolean or Undefined |
-
-</Table>
-
-### Returns <a id="cancel-returns"/>
-
-`Promise<void>`
-
-Returns a promise. The promise is fulfilled when the cancel signal has been published, or rejected with an [`ErrorInfo`](/docs/ai-transport/api/errors#errorinfo) object.
-
-## Wait for turns to complete <a id="wait-for-turn"/>
-
-<MethodSignature>{`waitForTurn(filter?: CancelFilter): Promise<void>`}</MethodSignature>
-
-Wait for every active turn matching `filter` to complete. Resolves immediately if no matching turns are active. Defaults to `{ own: true }`.
-
-<Code>
-```javascript
-await transport.waitForTurn();                         // own turns
-await transport.waitForTurn({ turnId: 'abc' });        // one specific turn
-await transport.waitForTurn({ all: true });            // every turn on the channel
-```
-</Code>
-
-### Parameters <a id="wait-for-turn-params"/>
-
-<Table id='WaitForTurnParameters'>
-
-| Parameter | Required | Description | Type |
-| --- | --- | --- | --- |
-| filter | Optional | Scope of the wait. Defaults to `{ own: true }`. | <Table id='CancelFilter'/> |
-
-</Table>
-
-### Returns <a id="wait-for-turn-returns"/>
-
-`Promise<void>`
-
-Returns a promise. The promise is fulfilled when every matching turn has ended, or rejected with an [`ErrorInfo`](/docs/ai-transport/api/errors#errorinfo) object.
-
-## Stage events on a message <a id="stage-events"/>
-
-<MethodSignature>{`stageEvents(msgId: string, events: TEvent[]): void`}</MethodSignature>
-
-Apply events to an existing tree message locally and queue them for delivery on the next send. The events are applied via the codec's accumulator (the tree's `update` fires once with the merged message) and are flushed into the next send operation's POST body for the server to republish.
-
-Use for cross-turn updates where the event value is produced on the client (for example, after `addToolResult` resolves a client-executed tool) and must appear in the tree immediately.
-
-If `msgId` is not present in the tree, the call is a no-op and a warning is logged.
-
-### Parameters <a id="stage-events-params"/>
-
-<Table id='StageEventsParameters'>
-
-| Parameter | Required | Description | Type |
-| --- | --- | --- | --- |
-| msgId | Required | The `x-ably-msg-id` of the existing message to amend. | String |
-| events | Required | Events to apply locally and ship on the next send. | `TEvent[]` |
-
-</Table>
-
-## Stage a replacement message <a id="stage-message"/>
-
-<MethodSignature>{`stageMessage(msgId: string, message: TMessage): void`}</MethodSignature>
-
-Replace the tree's copy of an existing message with a caller-provided version, preserving headers and serial. Runs synchronously.
-
-Use for `useChat`-style state transitions the codec cannot express as chunks. The canonical example is `addToolApprovalResponse`, which sets `state: 'approval-responded'` on a `dynamic-tool` part directly on the `UIMessage` and has no corresponding chunk variant.
-
-Staged messages are not queued for the next send. The tree is authoritative for the POST body's history, so updating it is sufficient.
-
-If `msgId` is not present in the tree, the call is a no-op and a warning is logged.
-
-### Parameters <a id="stage-message-params"/>
-
-<Table id='StageMessageParameters'>
-
-| Parameter | Required | Description | Type |
-| --- | --- | --- | --- |
-| msgId | Required | The `x-ably-msg-id` of the existing message to replace. | String |
-| message | Required | The patched message to store. | `TMessage` |
-
-</Table>
-
-## Subscribe to errors <a id="on"/>
-
-<MethodSignature>{`on(event: 'error', handler: (error: Ably.ErrorInfo) => void): () => void`}</MethodSignature>
-
-Subscribe to non-fatal transport errors. These indicate something went wrong but the transport is still operational. Returns an unsubscribe function.
-
-<Code>
-```javascript
-const off = transport.on('error', (error) => {
-  console.error(`Transport error ${error.code}: ${error.message}`);
-});
-
-// Later, to stop listening:
-off();
-```
-</Code>
-
-### Parameters <a id="on-params"/>
-
-<Table id='OnParameters'>
-
-| Parameter | Required | Description | Type |
-| --- | --- | --- | --- |
-| event | Required | The event name. Currently only `'error'` is supported. | `'error'` |
-| handler | Required | Called with each emitted [`ErrorInfo`](/docs/ai-transport/api/errors#errorinfo). | `(error: Ably.ErrorInfo) => void` |
-
-</Table>
-
-### Returns <a id="on-returns"/>
-
-`() => void`
-
-A function that unsubscribes the handler.
-
-## Close the transport <a id="close"/>
-
-<MethodSignature>{`close(options?: CloseOptions): Promise<void>`}</MethodSignature>
-
-Tear down the transport: unsubscribe from the channel, close active streams, clear handlers, and prevent further operations. Pass `cancel` to publish a cancel message before closing; without it, only local state is torn down (the server keeps streaming).
-
-<Code>
-```javascript
-await transport.close();                                 // local teardown only
-await transport.close({ cancel: { own: true } });        // cancel own turns first
-```
-</Code>
-
-### Parameters <a id="close-params"/>
-
-<Table id='CloseParameters'>
-
-| Parameter | Required | Description | Type |
-| --- | --- | --- | --- |
-| options | Optional | Close options. | <Table id='CloseOptions'/> |
-
-</Table>
-
-<Table id='CloseOptions' hidden>
-
-| Property | Description | Type |
-| --- | --- | --- |
-| cancel | Cancel in-progress turns before closing. Publishes a cancel message to the channel. | <Table id='CancelFilter'/> or Undefined |
-
-</Table>
-
-### Returns <a id="close-returns"/>
-
-`Promise<void>`
-
-Returns a promise. The promise is fulfilled when teardown completes, or rejected with an [`ErrorInfo`](/docs/ai-transport/api/errors#errorinfo) object.
-
-## View <a id="View"/>
-
-A `View` is a paginated, branch-aware projection of the conversation tree. It tracks which branch is selected at each fork point and supports lazy loading of older messages. The transport exposes a default view as `transport.view`; create additional views with `transport.createView()`.
-
-### Get visible messages <a id="View-getMessages"/>
-
-<MethodSignature>getMessages(): TMessage[]</MethodSignature>
-
-The visible domain messages along the selected branch. Shorthand for `flattenNodes().map(n => n.message)`.
-
-### Get visible nodes <a id="View-flattenNodes"/>
-
-<MethodSignature>{`flattenNodes(): MessageNode<TMessage>[]`}</MethodSignature>
-
-Visible nodes along the selected branch, filtered by the pagination window. Each node wraps the domain message with tree metadata: <Table id='MessageNode'/>
-
-### Check for older messages <a id="View-hasOlder"/>
-
-<MethodSignature>hasOlder(): boolean</MethodSignature>
-
-Whether there are older messages that can be loaded or revealed.
-
-### Load older messages <a id="View-loadOlder"/>
-
-<MethodSignature>{`loadOlder(limit?: number): Promise<void>`}</MethodSignature>
-
-Reveal older messages. Loads from channel history if the tree does not have enough, then advances the window to show up to `limit` more messages. Emits `'update'` when the visible list changes. Returns a promise; rejection surfaces an [`ErrorInfo`](/docs/ai-transport/api/errors#errorinfo).
-
-### Select a sibling at a fork point <a id="View-select"/>
-
-<MethodSignature>{`select(msgId: string, index: number): void`}</MethodSignature>
-
-Select a sibling at a fork point by index. Updates this view's branch selection. Index is clamped to `[0, siblings.length - 1]`. Emits `'update'` when the visible output changes.
-
-### Get the selected sibling index <a id="View-getSelectedIndex"/>
-
-<MethodSignature>{`getSelectedIndex(msgId: string): number`}</MethodSignature>
-
-The index of the currently selected sibling at a fork point.
-
-### Get sibling messages <a id="View-getSiblings"/>
-
-<MethodSignature>{`getSiblings(msgId: string): TMessage[]`}</MethodSignature>
-
-Every sibling message at a fork point, ordered chronologically by serial.
-
-### Check for siblings <a id="View-hasSiblings"/>
-
-<MethodSignature>{`hasSiblings(msgId: string): boolean`}</MethodSignature>
-
-Whether a message has sibling alternatives. Use this to decide whether to render branch-navigation arrows.
-
-### Get a node by ID <a id="View-getNode"/>
-
-<MethodSignature>{`getNode(msgId: string): MessageNode<TMessage> | undefined`}</MethodSignature>
-
-The node for a given message ID, or `undefined` if the tree has no such node.
-
-### Send one or more messages <a id="View-send"/>
-
-<MethodSignature>{`send(messages: TMessage | TMessage[], options?: SendOptions): Promise<ActiveTurn<TEvent>>`}</MethodSignature>
-
-Send one or more user messages and start a new turn. The parent is auto-computed from this view's selected branch unless overridden in `options`. Messages are inserted optimistically into the tree. The HTTP POST is fire-and-forget; the returned stream is available immediately.
-
-<Code>
-```javascript
-const turn = await transport.view.send([
-  { id: crypto.randomUUID(), role: 'user', parts: [{ type: 'text', text: 'Hello' }] },
-]);
-
-for await (const chunk of turn.stream) {
-  // chunk is one decoded event from the agent.
-}
-```
-</Code>
-
-#### Parameters <a id="View-send-params"/>
-
-<Table id='ViewSendParameters'>
-
-| Parameter | Required | Description | Type |
-| --- | --- | --- | --- |
-| messages | Required | One message or an array of messages to send. | `TMessage` or `TMessage[]` |
-| options | Optional | Per-send overrides for headers, body, and branching metadata. | <Table id='SendOptions'/> |
-
-</Table>
-
-<Table id='SendOptions' hidden>
-
-| Property | Description | Type |
-| --- | --- | --- |
-| body | Additional fields merged into the HTTP POST body for this send. | `Record<string, unknown>` or Undefined |
-| headers | Additional headers for the HTTP POST for this send. | `Record<string, string>` or Undefined |
-| forkOf | The msg-id of the message this send replaces. Set for regeneration (forkOf an assistant message) or edit (forkOf a user message). | String or Undefined |
-| parent | Override the auto-computed parent msg-id for this send. | String or Undefined |
-
-</Table>
-
-#### Returns <a id="View-send-returns"/>
-
-`Promise<ActiveTurn<TEvent>>`
-
-Returns a promise. The promise is fulfilled with an [`ActiveTurn`](#ActiveTurn) carrying the decoded event `stream`, `turnId`, and a `cancel()` method.
-
-### Regenerate an assistant message <a id="View-regenerate"/>
-
-<MethodSignature>{`regenerate(messageId: string, options?: SendOptions): Promise<ActiveTurn<TEvent>>`}</MethodSignature>
-
-Regenerate an assistant message. Creates a new turn that forks the target message with no new user messages. `forkOf`, `parent`, and the truncated history are computed automatically from this view's branch.
-
-#### Parameters <a id="View-regenerate-params"/>
-
-<Table id='ViewRegenerateParameters'>
-
-| Parameter | Required | Description | Type |
-| --- | --- | --- | --- |
-| messageId | Required | The msg-id of the assistant message to regenerate. | String |
-| options | Optional | Per-send overrides. | <Table id='SendOptions'/> |
-
-</Table>
-
-#### Returns <a id="View-regenerate-returns"/>
-
-`Promise<ActiveTurn<TEvent>>`
-
-Returns a promise. The promise is fulfilled with an [`ActiveTurn`](#ActiveTurn), or rejected with an [`ErrorInfo`](/docs/ai-transport/api/errors#errorinfo) object.
-
-### Edit a user message <a id="View-edit"/>
-
-<MethodSignature>{`edit(messageId: string, newMessages: TMessage | TMessage[], options?: SendOptions): Promise<ActiveTurn<TEvent>>`}</MethodSignature>
-
-Edit a user message and start a new turn from that point. The original message and its descendants remain in the tree as a separate branch. `forkOf`, `parent`, and history are computed automatically.
-
-#### Parameters <a id="View-edit-params"/>
-
-<Table id='ViewEditParameters'>
-
-| Parameter | Required | Description | Type |
-| --- | --- | --- | --- |
-| messageId | Required | The msg-id of the user message to fork. | String |
-| newMessages | Required | The replacement message or messages. | `TMessage` or `TMessage[]` |
-| options | Optional | Per-send overrides. | <Table id='SendOptions'/> |
-
-</Table>
-
-#### Returns <a id="View-edit-returns"/>
-
-`Promise<ActiveTurn<TEvent>>`
-
-Returns a promise. The promise is fulfilled with an [`ActiveTurn`](#ActiveTurn), or rejected with an [`ErrorInfo`](/docs/ai-transport/api/errors#errorinfo) object.
-
-### Update an existing message <a id="View-update"/>
-
-<MethodSignature>{`update(msgId: string, events: TEvent[], options?: SendOptions): Promise<ActiveTurn<TEvent>>`}</MethodSignature>
-
-Update an existing message in place and start a continuation turn. The local tree is updated optimistically, then the events are sent to the server in the POST body. The server publishes them to the channel and streams a continuation response. Commonly used for delivering client-executed tool results.
-
-#### Parameters <a id="View-update-params"/>
-
-<Table id='ViewUpdateParameters'>
-
-| Parameter | Required | Description | Type |
-| --- | --- | --- | --- |
-| msgId | Required | The `x-ably-msg-id` of the existing message to amend. | String |
-| events | Required | Events to apply to the target message (for example, tool output). | `TEvent[]` |
-| options | Optional | Per-send overrides. | <Table id='SendOptions'/> |
-
-</Table>
-
-#### Returns <a id="View-update-returns"/>
-
-`Promise<ActiveTurn<TEvent>>`
-
-Returns a promise. The promise is fulfilled with an [`ActiveTurn`](#ActiveTurn) carrying the continuation response stream, or rejected with an [`ErrorInfo`](/docs/ai-transport/api/errors#errorinfo) object.
-
-## ActiveTurn <a id="ActiveTurn"/>
-
-An `ActiveTurn` is the handle returned by `view.send()`, `view.regenerate()`, `view.edit()`, and `view.update()`. It exposes the decoded event stream, the turn's identity, and a cancel handle.
-
-<Table id='ActiveTurnProperties'>
-
-| Property | Description | Type |
-| --- | --- | --- |
-| stream | The decoded event stream for this turn. May error if the delivery guarantee is broken (POST failure, channel continuity loss). | `ReadableStream<TEvent>` |
-| turnId | The turn's unique identifier. | String |
-| cancel | `() => Promise<void>`. Cancel this specific turn. Publishes a cancel message and closes the local stream. | Function |
-| optimisticMsgIds | The msg-ids of optimistically inserted user messages, in order. Present when the send included user messages (`send`, `edit`); empty for `regenerate`. | `string[]` |
-
-</Table>
-
-<Table id='MessageNode' hidden>
-
-| Property | Description | Type |
-| --- | --- | --- |
-| kind | `'message'`. Distinguishes a message node from an events node. | String |
-| msgId | The Ably message ID. Primary key in the tree. | String |
-| message | The decoded domain message. | `TMessage` |
-| parentId | The parent node's `msgId`, or `undefined` for root messages. | String or Undefined |
-| forkOf | The `msgId` this node forks from (for example, regeneration or edit), or `undefined` if it is the first version. | String or Undefined |
-| headers | Transport headers for tree identity, ordering, and branching. | `Record<string, string>` |
-| serial | The Ably serial for tree ordering. Absent on optimistically-inserted nodes until the server relay arrives. | String or Undefined |
-
-</Table>
-
-## Example
-
-<Code>
-```javascript
-import * as Ably from 'ably';
-import { createClientTransport } from '@ably/ai-transport';
-import { UIMessageCodec } from '@ably/ai-transport/vercel';
-
-const ably = new Ably.Realtime({ authUrl: '/auth' });
-const channel = ably.channels.get('conversation-42');
-
-const transport = createClientTransport({
-  channel,
-  codec: UIMessageCodec,
-  api: '/api/chat',
-});
-
-transport.on('error', (error) => {
-  console.error(`Transport error ${error.code}: ${error.message}`);
-});
-
-// Send a message and consume the response stream.
-const turn = await transport.view.send([
-  { id: crypto.randomUUID(), role: 'user', parts: [{ type: 'text', text: 'Summarise this contract.' }] },
-]);
-
-for await (const chunk of turn.stream) {
-  // chunk is one decoded event for this turn.
-}
-
-// Browse history and regenerate the last response.
-await transport.view.loadOlder(50);
-const last = transport.view.getMessages().at(-1);
-if (last?.role === 'assistant') {
-  await transport.view.regenerate(last.id);
-}
-
-// Cancel an in-flight turn from anywhere.
-await transport.cancel({ own: true });
-
-// Wait for the current set of own turns to finish before tearing down.
-await transport.waitForTurn();
-await transport.close();
-```
-</Code>
diff --git a/src/pages/docs/ai-transport/api/javascript/codec.mdx b/src/pages/docs/ai-transport/api/javascript/codec.mdx
deleted file mode 100644
index af71acef6e..0000000000
--- a/src/pages/docs/ai-transport/api/javascript/codec.mdx
+++ /dev/null
@@ -1,360 +0,0 @@
----
-title: "Codec"
-meta_description: "API reference for the AI Transport codec interface. Build custom codecs to integrate any AI framework with Ably channels."
-meta_keywords: "AI Transport, Codec, StreamEncoder, StreamDecoder, MessageAccumulator, ChannelWriter, custom codec, Ably"
-redirect_from:
-  - /docs/ai-transport/api-reference/codec
----
-
-The `Codec` interface is the bridge between an AI framework and Ably channel messages. It defines how domain events (LLM token deltas, tool calls, finish signals) are encoded into Ably publish operations and decoded back into domain events on the client.
-
-Implement `Codec<TEvent, TMessage>` to integrate any AI framework with AI Transport. The SDK ships `UIMessageCodec` for the Vercel AI SDK; for other frameworks, implement the four methods below.
-
-<Code>
-```javascript
-import type { Codec } from '@ably/ai-transport';
-
-const myCodec: Codec<MyEvent, MyMessage> = {
-  createEncoder(channel, options) { /* ... */ },
-  createDecoder() { /* ... */ },
-  createAccumulator() { /* ... */ },
-  isTerminal(event) { /* ... */ },
-};
-```
-</Code>
-
-## Create an encoder <a id="createEncoder"/>
-
-<MethodSignature>{`createEncoder(channel: ChannelWriter, options?: EncoderOptions): StreamEncoder<TEvent, TMessage>`}</MethodSignature>
-
-Create a streaming encoder bound to a channel. Called by the server transport once per turn. The returned encoder owns the message-append lifecycle for the turn (start a stream, append tokens, close).
-
-### Parameters <a id="createEncoder-params"/>
-
-<Table id='CreateEncoderParameters'>
-
-| Parameter | Required | Description | Type |
-| --- | --- | --- | --- |
-| channel | Required | The channel writer to publish through. Provided by the transport. Documented as a visible section below. | `ChannelWriter` |
-| options | Optional | Default identity, extras, and hooks shared across every write through this encoder. | <Table id='EncoderOptions'/> |
-
-</Table>
-
-<Table id='EncoderOptions' hidden>
-
-| Property | Description | Type |
-| --- | --- | --- |
-| clientId | Default `clientId` for every write. | String or Undefined |
-| extras | Default extras (headers) merged into every Ably message. | <Table id='Extras'/> or Undefined |
-| onMessage | Hook called before each Ably message is published. Mutate the message in place to add transport-level headers. | `(message: Ably.Message) => void` or Undefined |
-| messageId | Domain-level message identity. Used as a fallback when a lifecycle chunk does not provide one, ensuring downstream observers and the transport accumulator assign the same ID. | String or Undefined |
-
-</Table>
-
-<Table id='Extras' hidden>
-
-| Property | Description | Type |
-| --- | --- | --- |
-| headers | Headers to attach to the Ably message `extras`. | `Record<string, string>` or Undefined |
-
-</Table>
-
-### Returns <a id="createEncoder-returns"/>
-
-`StreamEncoder<TEvent, TMessage>`
-
-A streaming encoder. See [`StreamEncoder`](#StreamEncoder) for the full method surface.
-
-## Create a decoder <a id="createDecoder"/>
-
-<MethodSignature>{`createDecoder(): StreamDecoder<TEvent, TMessage>`}</MethodSignature>
-
-Create a decoder for converting inbound Ably messages back into domain outputs. Called by the client transport on attach.
-
-### Returns <a id="createDecoder-returns"/>
-
-`StreamDecoder<TEvent, TMessage>`
-
-A decoder. See [`StreamDecoder`](#StreamDecoder).
-
-## Create an accumulator <a id="createAccumulator"/>
-
-<MethodSignature>{`createAccumulator(): MessageAccumulator<TEvent, TMessage>`}</MethodSignature>
-
-Create an accumulator for building complete domain messages from a sequence of decoder outputs. Used internally by the client transport to reconstruct in-progress messages.
-
-### Returns <a id="createAccumulator-returns"/>
-
-`MessageAccumulator<TEvent, TMessage>`
-
-An accumulator. See [`MessageAccumulator`](#MessageAccumulator).
-
-## Check whether an event is terminal <a id="isTerminal"/>
-
-<MethodSignature>{`isTerminal(event: TEvent): boolean`}</MethodSignature>
-
-Return `true` if the event signals stream completion (finish, error, abort). The transport uses this to close the stream at the right time.
-
-### Parameters <a id="isTerminal-params"/>
-
-<Table id='IsTerminalParameters'>
-
-| Parameter | Required | Description | Type |
-| --- | --- | --- | --- |
-| event | Required | The domain event to inspect. | `TEvent` |
-
-</Table>
-
-### Returns <a id="isTerminal-returns"/>
-
-`boolean`
-
-`true` if the event ends a stream, otherwise `false`.
-
-## StreamEncoder <a id="StreamEncoder"/>
-
-A streaming encoder bound to a single turn. Extends `DiscreteEncoder` (the stateless subset, documented below) with stateful streaming operations: `appendEvent` for content streams, `abort` for cancellation, `close` to flush. Every write method accepts a per-write `WriteOptions`: <Table id='WriteOptions'/>
-
-### Append a streaming event <a id="StreamEncoder-appendEvent"/>
-
-<MethodSignature>{`appendEvent(event: TEvent, options?: WriteOptions): Promise<void>`}</MethodSignature>
-
-Encode and append a streaming domain event to an in-progress stream. Delta semantics: subsequent calls accumulate text under the same Ably message lifecycle.
-
-### Publish complete messages <a id="StreamEncoder-writeMessages"/>
-
-<MethodSignature>{`writeMessages(messages: TMessage[], options?: WriteOptions): Promise<Ably.PublishResult>`}</MethodSignature>
-
-Encode and publish one or more domain messages atomically. All messages share the encoder's transport headers (including `x-ably-msg-id`), so they form one logical unit in the conversation tree.
-
-### Publish a discrete event <a id="StreamEncoder-writeEvent"/>
-
-<MethodSignature>{`writeEvent(event: TEvent, options?: WriteOptions): Promise<Ably.PublishResult>`}</MethodSignature>
-
-Encode and publish a single domain event as a standalone discrete message. Use to publish events outside the streaming flow. Implementations should throw for event types that are only meaningful within a stream (such as text deltas).
-
-### Abort the encoder <a id="StreamEncoder-abort"/>
-
-<MethodSignature>{`abort(reason?: string): Promise<void>`}</MethodSignature>
-
-Abort all in-progress streams and publish a codec-specific abort signal. Called by the transport when a turn is cancelled. Idempotent — calling abort after all streams have already aborted is a no-op.
-
-### Close the encoder <a id="StreamEncoder-close"/>
-
-<MethodSignature>{`close(): Promise<void>`}</MethodSignature>
-
-Flush all pending appends and close the encoder.
-
-<Table id='WriteOptions' hidden>
-
-| Property | Description | Type |
-| --- | --- | --- |
-| clientId | Override the default `clientId` for this write. | String or Undefined |
-| extras | Override the default extras for this write. | <Table id='Extras'/> or Undefined |
-| messageId | Message identity for accumulator correlation. Stamped as `x-ably-msg-id`. | String or Undefined |
-
-</Table>
-
-## DiscreteEncoder <a id="DiscreteEncoder"/>
-
-The stateless subset of `StreamEncoder`. Has only `writeMessages` and `writeEvent` and is safe for long-lived reuse across turns. The server transport uses a `DiscreteEncoder` to publish user messages (via `addMessages`); `writeEvent` is also a public surface for consumers publishing standalone discrete events.
-
-### Publish complete messages <a id="DiscreteEncoder-writeMessages"/>
-
-<MethodSignature>{`writeMessages(messages: TMessage[], options?: WriteOptions): Promise<Ably.PublishResult>`}</MethodSignature>
-
-Same as `StreamEncoder.writeMessages` above.
-
-### Publish a discrete event <a id="DiscreteEncoder-writeEvent"/>
-
-<MethodSignature>{`writeEvent(event: TEvent, options?: WriteOptions): Promise<Ably.PublishResult>`}</MethodSignature>
-
-Same as `StreamEncoder.writeEvent` above.
-
-## StreamDecoder <a id="StreamDecoder"/>
-
-Decodes Ably messages into domain events and messages.
-
-### Decode a message <a id="StreamDecoder-decode"/>
-
-<MethodSignature>{`decode(message: Ably.InboundMessage): DecoderOutput<TEvent, TMessage>[]`}</MethodSignature>
-
-Decode a single inbound Ably message into zero or more domain outputs. The accumulator routes the outputs to the correct in-progress message using the `messageId` field on event outputs. Each output is a <Table id='DecoderOutput'/>.
-
-<Table id='DecoderOutput' hidden>
-
-| Property | Description | Type |
-| --- | --- | --- |
-| kind | `'event'` for a streamed event, `'message'` for a complete message. | `'event'` or `'message'` |
-| event | The decoded event. Present when `kind` is `'event'`. | `TEvent` or Undefined |
-| messageId | The `x-ably-msg-id` header from the source message. Present on event outputs; used by the accumulator to route the event. | String or Undefined |
-| message | The decoded message. Present when `kind` is `'message'`. | `TMessage` or Undefined |
-
-</Table>
-
-## MessageAccumulator <a id="MessageAccumulator"/>
-
-Accumulates decoder outputs into a list of domain messages, tracking which streams are still active. The client transport owns one accumulator per view.
-
-### Properties
-
-<Table id='MessageAccumulatorProperties'>
-
-| Property | Description | Type |
-| --- | --- | --- |
-| messages | Every message accumulated so far, in-progress and completed. | `TMessage[]` |
-| completedMessages | Only messages whose streams have finished. | `TMessage[]` |
-| hasActiveStream | Whether any stream is still actively receiving data. | Boolean |
-
-</Table>
-
-### Process decoder outputs <a id="MessageAccumulator-processOutputs"/>
-
-<MethodSignature>{`processOutputs(outputs: DecoderOutput<TEvent, TMessage>[]): void`}</MethodSignature>
-
-Process a batch of decoder outputs, updating internal message state.
-
-### Apply an external message update <a id="MessageAccumulator-updateMessage"/>
-
-<MethodSignature>{`updateMessage(message: TMessage): void`}</MethodSignature>
-
-Apply an external update to a message, for example from an update callback that bypasses the chunk stream.
-
-### Initialise tracking for a message <a id="MessageAccumulator-initMessage"/>
-
-<MethodSignature>{`initMessage(messageId: string, message: TMessage): void`}</MethodSignature>
-
-Ensure the accumulator is ready to process events for the given message. If not already active, creates internal tracking state from the message. If already active, syncs internal state with the provided message (picking up external changes like cross-turn amendments). Idempotent — safe to call before every `processOutputs`.
-
-### Complete a message <a id="MessageAccumulator-completeMessage"/>
-
-<MethodSignature>{`completeMessage(messageId: string): void`}</MethodSignature>
-
-Mark a message as completed. Removes it from active tracking so it appears in `completedMessages`. No-op if not active.
-
-## ChannelWriter <a id="ChannelWriter"/>
-
-The thin write interface a `Codec` uses to publish to Ably. The transport supplies a `ChannelWriter` to `createEncoder`; testing harnesses and decorators can implement their own.
-
-### Publish discrete messages <a id="ChannelWriter-publish"/>
-
-<MethodSignature>{`publish(message: Ably.Message | Ably.Message[], options?: Ably.PublishOptions): Promise<Ably.PublishResult>`}</MethodSignature>
-
-Publish one or more discrete messages to the channel.
-
-### Append to an existing message <a id="ChannelWriter-appendMessage"/>
-
-<MethodSignature>{`appendMessage(message: Ably.Message, operation?: Ably.MessageOperation, options?: Ably.PublishOptions): Promise<Ably.UpdateDeleteResult>`}</MethodSignature>
-
-Append data to an existing message identified by its serial. Used by the encoder for token-by-token streaming.
-
-### Replace an existing message <a id="ChannelWriter-updateMessage"/>
-
-<MethodSignature>{`updateMessage(message: Ably.Message, operation?: Ably.MessageOperation, options?: Ably.PublishOptions): Promise<Ably.UpdateDeleteResult>`}</MethodSignature>
-
-Replace the data of an existing message identified by its serial. The encoder's recovery path uses this to publish accumulated content when an append fails.
-
-`Ably.RealtimeChannel` satisfies `ChannelWriter` directly, so passing a channel where a `ChannelWriter` is expected works without an adapter.
-
-## Helper factories <a id="helpers"/>
-
-The SDK ships helper factories that pre-implement the encoder, decoder, and lifecycle-tracker scaffolding so a custom codec only writes the framework-specific parts.
-
-### createEncoderCore <a id="createEncoderCore"/>
-
-<MethodSignature>{`function createEncoderCore(writer: ChannelWriter, options?: EncoderCoreOptions): EncoderCore`}</MethodSignature>
-
-Create a base encoder with common publish logic and recovery already implemented. A custom codec composes it inside `createEncoder` and supplies framework-specific encoding hooks.
-
-`EncoderCore` exposes the publish primitives a codec encoder delegates to: `publishDiscrete`, `publishDiscreteBatch`, `startStream`, `appendStream`, `closeStream`, `abortStream`, `abortAllStreams`, and `close`. The codec wires these into the `StreamEncoder` methods it returns from `createEncoder`.
-
-### createDecoderCore <a id="createDecoderCore"/>
-
-<MethodSignature>{`function createDecoderCore<TEvent, TMessage>(hooks: DecoderCoreHooks<TEvent, TMessage>, options?: DecoderCoreOptions): DecoderCore<TEvent, TMessage>`}</MethodSignature>
-
-Create a base decoder with common message-parsing logic already implemented. The hooks describe how to convert inbound Ably messages into domain events for the target framework.
-
-`DecoderCoreHooks` has four methods: `buildStartEvents(tracker)` and `buildEndEvents(tracker, closingHeaders)` fire at the start and end of each streamed message; `buildDeltaEvents(tracker, delta)` fires on every appended chunk; `decodeDiscrete(payload)` handles discrete (non-streaming) messages such as user messages and lifecycle events. Each hook returns an array of `DecoderOutput` so a single inbound message can produce zero or more domain outputs.
-
-### createLifecycleTracker <a id="createLifecycleTracker"/>
-
-<MethodSignature>{`function createLifecycleTracker<TEvent>(phases: PhaseConfig<TEvent>[]): LifecycleTracker<TEvent>`}</MethodSignature>
-
-Create a configurable lifecycle tracker that synthesises missing phase events (for example, a synthesised `start` chunk when a client joins mid-stream). Use inside a custom decoder to keep the event sequence consistent regardless of when the client attached.
-
-## Example
-
-The end-to-end shape for writing a custom codec. The encoder composes `createEncoderCore` and maps each domain event to a publish primitive. The decoder composes `createDecoderCore` and emits domain outputs from the four lifecycle hooks.
-
-<Code>
-```javascript
-import {
-  createEncoderCore,
-  createDecoderCore,
-  type Codec,
-} from '@ably/ai-transport';
-
-type MyEvent =
-  | { type: 'text-start'; messageId: string }
-  | { type: 'text-delta'; messageId: string; text: string }
-  | { type: 'finish' };
-
-type MyMessage = { id: string; text: string };
-
-const myCodec: Codec<MyEvent, MyMessage> = {
-  createEncoder(channel, options) {
-    const core = createEncoderCore(channel, options);
-
-    return {
-      // DiscreteEncoder operations — atomic publishes outside the stream.
-      writeMessages: (messages, opts) =>
-        core.publishDiscreteBatch(messages.map((m) => ({ name: 'message', data: m })), opts),
-      writeEvent: (event, opts) => {
-        if (event.type !== 'finish') throw new Error('only finish is a discrete event');
-        return core.publishDiscrete({ name: 'finish', data: {} }, opts);
-      },
-
-      // StreamEncoder operations — lifecycle of an in-progress stream.
-      appendEvent: async (event) => {
-        if (event.type === 'text-start') {
-          await core.startStream(event.messageId, { name: 'text', data: '' });
-        } else if (event.type === 'text-delta') {
-          core.appendStream(event.messageId, event.text);
-        }
-      },
-      abort: () => core.abortAllStreams(),
-      close: () => core.close(),
-    };
-  },
-
-  createDecoder() {
-    return createDecoderCore<MyEvent, MyMessage>({
-      buildStartEvents: (tracker) => [
-        { kind: 'event', event: { type: 'text-start', messageId: tracker.streamId } },
-      ],
-      buildDeltaEvents: (tracker, delta) => [
-        { kind: 'event', event: { type: 'text-delta', messageId: tracker.streamId, text: delta } },
-      ],
-      buildEndEvents: () => [
-        { kind: 'event', event: { type: 'finish' } },
-      ],
-      decodeDiscrete: (payload) =>
-        payload.name === 'finish'
-          ? [{ kind: 'event', event: { type: 'finish' } }]
-          : [{ kind: 'message', message: payload.data as MyMessage }],
-    });
-  },
-
-  createAccumulator() {
-    // Build an accumulator that owns the running list of MyMessage values.
-    // See the SDK source for the canonical UIMessage accumulator implementation.
-  },
-
-  isTerminal(event) {
-    return event.type === 'finish';
-  },
-};
-```
-</Code>
-
-See the [codec architecture internals](/docs/ai-transport/internals/codec-architecture) for the encoder and decoder pipelines in depth.
diff --git a/src/pages/docs/ai-transport/api/javascript/core/agent-session.mdx b/src/pages/docs/ai-transport/api/javascript/core/agent-session.mdx
new file mode 100644
index 0000000000..bb3bf5830c
--- /dev/null
+++ b/src/pages/docs/ai-transport/api/javascript/core/agent-session.mdx
@@ -0,0 +1,399 @@
+---
+title: "AgentSession"
+meta_description: "API reference for the AI Transport AgentSession: factory, lifecycle methods, the Run interface, and the Invocation value object."
+meta_keywords: "AI Transport, AgentSession, createAgentSession, Run, Invocation, createRun, pipe, end, Ably"
+redirect_from:
+  - /docs/ai-transport/api-reference/server-transport
+  - /docs/ai-transport/api/javascript/server-transport
+---
+
+The `AgentSession` is the server-side counterpart to [`ClientSession`](/docs/ai-transport/api/javascript/core/client-session). It subscribes to the channel for cancel signals and creates `Run` instances that publish lifecycle events, user messages, and streamed assistant output.
+
+Construct one with `createAgentSession` from the core entry point. For Vercel `UIMessage` channels, use the pre-bound factory from [`@ably/ai-transport/vercel`](/docs/ai-transport/api/javascript/vercel/chat-transport) instead.
+
+<Code>
+```javascript
+import * as Ably from 'ably';
+import { createAgentSession, Invocation } from '@ably/ai-transport';
+import { UIMessageCodec } from '@ably/ai-transport/vercel';
+
+const ably = new Ably.Realtime({ key: process.env.ABLY_API_KEY });
+
+const invocation = Invocation.fromJSON(await req.json());
+
+const session = createAgentSession({
+  client: ably,
+  channelName: invocation.sessionName,
+  codec: UIMessageCodec,
+});
+
+await session.connect();
+const run = session.createRun(invocation, { signal: req.signal });
+await run.start();
+```
+</Code>
+
+## Create an agent session <a id="constructor"/>
+
+<MethodSignature>{`function createAgentSession<TInput, TOutput, TProjection, TMessage>(options: AgentSessionOptions<TInput, TOutput, TProjection, TMessage>): AgentSession<TOutput, TProjection, TMessage>`}</MethodSignature>
+
+Construct an `AgentSession` bound to an Ably channel. The session does not attach until [`connect()`](#connect) resolves.
+
+<Code>
+```javascript
+import * as Ably from 'ably';
+import { createAgentSession } from '@ably/ai-transport';
+import { UIMessageCodec } from '@ably/ai-transport/vercel';
+
+const ably = new Ably.Realtime({ key: process.env.ABLY_API_KEY });
+
+const session = createAgentSession({
+  client: ably,
+  channelName: 'conversation-42',
+  codec: UIMessageCodec,
+});
+```
+</Code>
+
+### Parameters <a id="constructor-params"/>
+
+<Table id='AgentSessionOptions'>
+
+| Parameter | Required | Description | Type |
+| --- | --- | --- | --- |
+| client | required | The Ably Realtime client. The caller owns its lifecycle; `session.close()` does not close the client. | `Ably.Realtime` |
+| channelName | required | The channel to publish to. The session owns this channel; do not also resolve it elsewhere with conflicting options. | String |
+| codec | required | The codec used to encode events and messages. | `Codec<TInput, TOutput, TProjection, TMessage>` |
+| logger | optional | Logger instance for diagnostic output. | `Logger` |
+| onError | optional | Called with non-fatal session-level errors not scoped to any run (cancel listener failures, channel continuity loss). | `(error: Ably.ErrorInfo) => void` |
+| inputEventLookupTimeoutMs | optional | How long `Run.start()` waits for the run's input event(s) to arrive on the channel before rejecting with `InputEventNotFound`. Defaults to 30000. | Number |
+| inputEventBufferLimit | optional | Maximum number of distinct input events that may be buffered while waiting for `Run.start()` to register a lookup listener. FIFO-evicted when exceeded. Defaults to 200. | Number |
+| rewindWindow | optional | Channel rewind applied when the agent attaches. Passed verbatim to Ably's `params.rewind`. Accepts duration strings (`"2m"`, `"30s"`) or message counts as strings (`"50"`). Defaults to `"2m"`. | String |
+
+</Table>
+
+### Returns <a id="constructor-returns"/>
+
+`AgentSession<TOutput, TProjection, TMessage>`. The session instance. Call [`connect()`](#connect) before [`createRun`](#create-run).
+
+## Connect the session <a id="connect"/>
+
+<MethodSignature>{`connect(): Promise<void>`}</MethodSignature>
+
+Subscribe to the cancel channel and implicitly attach. Idempotent: subsequent calls return the same promise. All `Run` methods (`start`, `addEvents`, `pipe`, `suspend`, `end`) throw `InvalidArgument` until `connect()` resolves.
+
+<Code>
+```javascript
+await session.connect();
+```
+</Code>
+
+### Returns <a id="connect-returns"/>
+
+`Promise<void>`. Resolves when the channel is attached and the session is ready to create runs.
+
+## Create a run <a id="create-run"/>
+
+<MethodSignature>{`createRun(invocation: Invocation, runtime?: RunRuntime<TOutput>): Run<TOutput, TProjection, TMessage>`}</MethodSignature>
+
+Create a new `Run` from an `Invocation`. Synchronous: no channel activity until [`Run.start`](#run-start) is called. The Run is registered for cancel routing immediately so early cancels fire the `abortSignal`.
+
+<Code>
+```javascript
+const invocation = Invocation.fromJSON(await req.json());
+const run = session.createRun(invocation, { signal: req.signal });
+```
+</Code>
+
+### Parameters <a id="create-run-params"/>
+
+<Table id='CreateRunParameters'>
+
+| Parameter | Required | Description | Type |
+| --- | --- | --- | --- |
+| invocation | required | The `Invocation` carrying run identity and conversation context. | <Table id='Invocation'/> |
+| runtime | optional | Per-run hooks and an external abort signal. | <Table id='RunRuntime'/> |
+
+</Table>
+
+<Table id='Invocation' hidden>
+
+| Property | Description | Type |
+| --- | --- | --- |
+| inputEventId | The specific input event on the channel that triggered this invocation. Run identity is resolved from that event's wire headers. | String |
+| sessionName | Logical name of the session, used as the Ably channel name. | String |
+
+</Table>
+
+<Table id='RunRuntime' hidden>
+
+| Property | Description | Type |
+| --- | --- | --- |
+| invocationId | Override the invocation id for this Run. Defaults to a fresh `crypto.randomUUID()` (the normal path; one per HTTP request). Supply a non-empty value for deterministic ids in tests. | String |
+| runId | Override the run id for a fresh run. Defaults to a fresh `crypto.randomUUID()`. Continuations ignore this and read the existing `runId` off the triggering input event. Supply a non-empty value for deterministic ids in tests. | String |
+| signal | External `AbortSignal` (typically the HTTP request's `req.signal`) that cancels the run when fired. | `AbortSignal` |
+| onMessage | Called before each Ably message is published. Mutate the message in place to add custom headers under `extras.ai`. | `(message: Ably.Message) => void` |
+| onCancelled | Called when the run is cancelled. Receives a `write` function to publish final outputs before cancellation finalises. | `(write: (output: TOutput) => Promise<void>) => void \| Promise<void>` |
+| onCancel | Called when a cancel arrives. Return `true` to accept, `false` to reject. Defaults to accepting all. | `(req: CancelRequest) => Promise<boolean>` |
+| onError | Called with non-fatal run-scoped errors. | `(error: Ably.ErrorInfo) => void` |
+
+</Table>
+
+### Returns <a id="create-run-returns"/>
+
+A `Run<TOutput, TProjection, TMessage>` handle for publishing lifecycle events, user messages, and streamed output. See [Run interface](#run) below.
+
+## Run <a id="run"/>
+
+The handle returned by [`createRun`](#create-run).
+
+### Properties
+
+<Table id='RunProperties'>
+
+| Property | Description | Type |
+| --- | --- | --- |
+| runId | The Run's unique identifier. | String |
+| invocationId | The invocation id minted by the agent for this `createRun` call (one per HTTP request). Readable synchronously; the application returns it on the HTTP response. The agent stamps it on every event it publishes for this invocation. | String |
+| abortSignal | `AbortSignal` scoped to this Run. Fires when a cancel event arrives. | `AbortSignal` |
+| view | Read-only view of the conversation messages associated with this Run. | <Table id='RunView'/> |
+| messages | The conversation messages this Run should feed to the model. See [Conversation hydration](#conversation-hydration). | `TMessage[]` |
+
+</Table>
+
+<Table id='RunView' hidden>
+
+| Property | Description | Type |
+| --- | --- | --- |
+| messages | Invocation input messages handed to this Run. No branch awareness today. | `MessageNode<TMessage>[]` |
+
+</Table>
+
+### Start the run <a id="run-start"/>
+
+<MethodSignature>{`start(): Promise<void>`}</MethodSignature>
+
+Publish the `ai-run-start` event to the channel and wait for the Run's input event to arrive (rewind + live wait). Must be called before `pipe`, `addEvents`, `suspend`, or `end`.
+
+Rejects with `InputEventNotFound` (code `104010`) if the input event for this invocation does not arrive within `inputEventLookupTimeoutMs`. Surface the rejection as a non-2xx response so the client's pending send fails.
+
+### Pipe the response stream <a id="pipe"/>
+
+<MethodSignature>{`pipe(stream: ReadableStream<TOutput>, options?: PipeOptions<TOutput>): Promise<StreamResult>`}</MethodSignature>
+
+Pipe a `ReadableStream` of outputs through the encoder to the channel. Returns when the stream completes, is cancelled, or errors. Does NOT call `end()`; the caller must call `end()` after `pipe()` returns.
+
+#### Parameters <a id="pipe-params"/>
+
+<Table id='PipeParameters'>
+
+| Parameter | Required | Description | Type |
+| --- | --- | --- | --- |
+| stream | required | The output stream from your LLM call. | `ReadableStream<TOutput>` |
+| options | optional | Branching and per-output hooks. | <Table id='PipeOptions'/> |
+
+</Table>
+
+<Table id='PipeOptions' hidden>
+
+| Property | Description | Type |
+| --- | --- | --- |
+| parent | The codec-message-id of the immediately preceding message in this branch. | String |
+| forkOf | The codec-message-id of the message this response replaces (for regeneration). | String |
+| resolveWriteOptions | Per-output hook returning `WriteOptions` overrides for a single encode call. | Function |
+
+</Table>
+
+#### Returns <a id="pipe-returns"/>
+
+`Promise<StreamResult>`. Resolves when the stream ends. Pass `result.reason` to [`Run.end`](#run-end). <Table id='StreamResult'/>
+
+<Table id='StreamResult' hidden>
+
+| Property | Description | Type |
+| --- | --- | --- |
+| reason | Why the stream ended. | `RunEndReason` |
+| error | The original error when `reason` is `'error'`. | `Error` |
+
+</Table>
+
+### Add events to existing messages <a id="add-events"/>
+
+<MethodSignature>{`addEvents(nodes: EventsNode<TOutput>[]): Promise<void>`}</MethodSignature>
+
+Publish events targeting existing messages. Each node specifies a `codecMessageId` and the events to apply. Used for cross-Run updates such as tool result delivery after approval.
+
+#### Parameters <a id="add-events-params"/>
+
+<Table id='AddEventsParameters'>
+
+| Parameter | Required | Description | Type |
+| --- | --- | --- | --- |
+| nodes | required | Events to apply, each tagged with the codec-message-id of the message to update. | <Table id='EventsNode'/> |
+
+</Table>
+
+<Table id='EventsNode' hidden>
+
+| Property | Description | Type |
+| --- | --- | --- |
+| kind | Discriminator: `'event'`. | `'event'` |
+| codecMessageId | The codec-message-id of the existing message to update. | String |
+| events | Outputs to apply to the target message. | `TOutput[]` |
+
+</Table>
+
+### Load a Run's projection <a id="load-projection"/>
+
+<MethodSignature>{`loadProjection(): Promise<TProjection>`}</MethodSignature>
+
+Fetch every channel message bound to this Run and fold them through the codec into a single projection. Use this to reconstruct a single Run's full state (including client-published tool-output amends the agent did not observe live) when resuming a suspended Run before piping fresh output. The companion to [`loadConversation`](#load-conversation), which walks ancestors; `loadProjection` covers only the current Run.
+
+The caller extracts what they need via [`Codec.getMessages`](/docs/ai-transport/api/javascript/core/codec).
+
+#### Returns <a id="load-projection-returns"/>
+
+`Promise<TProjection>`. The codec projection produced by folding every event for this Run in serial order.
+
+### Load the full conversation <a id="load-conversation"/>
+
+<MethodSignature>{`loadConversation(options?: LoadConversationOptions): Promise<TMessage[]>`}</MethodSignature>
+
+Reconstruct the full multi-turn conversation by walking the ancestor Run chain and concatenating each Run's messages, oldest turn first. After this call, `Run.messages` returns the complete conversation, ready to pass to the LLM.
+
+#### Parameters <a id="load-conversation-params"/>
+
+<Table id='LoadConversationParameters'>
+
+| Parameter | Required | Description | Type |
+| --- | --- | --- | --- |
+| options | optional | History pagination tuning. | <Table id='LoadConversationOptions'/> |
+
+</Table>
+
+<Table id='LoadConversationOptions' hidden>
+
+| Property | Description | Type |
+| --- | --- | --- |
+| pageLimit | Wire messages per history page. Defaults to 200. | Number |
+| maxMessages | Maximum wire messages collected across all pages. Defaults to 2000. | Number |
+
+</Table>
+
+### Suspend the run <a id="run-suspend"/>
+
+<MethodSignature>{`suspend(): Promise<void>`}</MethodSignature>
+
+Publish the `ai-run-suspend` event to the channel, pausing the Run pending external input (a tool approval, a human-in-the-loop response). The Run is not terminal: `RunInfo.status` becomes `'suspended'`, and a continuation Invocation resumes it via `ai-run-resume`.
+
+Use `suspend` instead of `end` when you want the run to come back. Use `end` only for terminal outcomes.
+
+### End the run <a id="run-end"/>
+
+<MethodSignature>{`end(reason: RunEndReason): Promise<void>`}</MethodSignature>
+
+Publish the `ai-run-end` event to the channel terminally and clean up. `reason` is one of `'complete'`, `'cancelled'`, or `'error'`. To pause a Run instead of ending it, use [`suspend`](#run-suspend).
+
+## Close the session <a id="close"/>
+
+<MethodSignature>{`close(): void`}</MethodSignature>
+
+Unsubscribe from the channel and clear handlers. Local-state-only; does not end in-progress Runs. End each Run explicitly before closing the session.
+
+## Invocation <a id="invocation"/>
+
+A value object wrapping the JSON body a client sends to the agent's HTTP endpoint to start a Run.
+
+### Build from JSON <a id="from-json"/>
+
+<MethodSignature>{`Invocation.fromJSON(data: InvocationData): Invocation`}</MethodSignature>
+
+The entry point used by agent handlers: parse the request body and pass it to `Invocation.fromJSON`, then hand the result to [`createRun`](#create-run).
+
+<Code>
+```javascript
+import { Invocation } from '@ably/ai-transport';
+
+const data = await req.json();
+const invocation = Invocation.fromJSON(data);
+```
+</Code>
+
+#### Parameters <a id="from-json-params"/>
+
+<Table id='FromJSONParameters'>
+
+| Parameter | Required | Description | Type |
+| --- | --- | --- | --- |
+| data | required | The parsed JSON request body matching the `InvocationData` wire shape. | <Table id='InvocationData'/> |
+
+</Table>
+
+<Table id='InvocationData' hidden>
+
+| Property | Description | Type |
+| --- | --- | --- |
+| inputEventId | Identifier for the input event on the channel that triggered this invocation. Run identity is resolved from that event's wire headers, not from the body. | String |
+| sessionName | Logical name of the session, used as the Ably channel name. | String |
+
+</Table>
+
+## Conversation hydration <a id="conversation-hydration"/>
+
+`Run.messages` returns different content depending on lifecycle stage:
+
+- Before [`start`](#run-start) resolves: empty array.
+- After `start`: the user-prompt messages looked up on the channel for this invocation.
+- After [`loadConversation`](#load-conversation): the full multi-turn conversation, with ancestor Run messages followed by the current Run's messages, oldest turn first.
+
+Use [`loadConversation`](#load-conversation) before piping to the LLM in any conversation past the first turn.
+
+## RunEndReason <a id="run-end-reason"/>
+
+`'complete' | 'cancelled' | 'error'`. Passed to [`Run.end`](#run-end) and reflected on `RunInfo.status` once the Run terminates.
+
+A Run that pauses for external input (tool approval, human-in-the-loop) uses [`Run.suspend`](#run-suspend) instead of `end`, which publishes `ai-run-suspend` and leaves the Run alive at `RunInfo.status === 'suspended'`. A continuation Invocation resumes it via `ai-run-resume`.
+
+## Example <a id="example"/>
+
+An HTTP handler that sets up the session, creates a Run, loads the conversation, pipes the LLM stream, and ends the Run.
+
+<Code>
+```javascript
+import * as Ably from 'ably';
+import { createAgentSession, Invocation } from '@ably/ai-transport';
+import { UIMessageCodec } from '@ably/ai-transport/vercel';
+
+const ably = new Ably.Realtime({ key: process.env.ABLY_API_KEY });
+
+export async function POST(req: Request) {
+  const invocation = Invocation.fromJSON(await req.json());
+
+  const session = createAgentSession({
+    client: ably,
+    channelName: invocation.sessionName,
+    codec: UIMessageCodec,
+  });
+
+  await session.connect();
+
+  const run = session.createRun(invocation, { signal: req.signal });
+
+  try {
+    await run.start();
+    await run.loadConversation();
+
+    const llmStream = await callMyLLM(run.messages);
+    const result = await run.pipe(llmStream);
+    await run.end(result.reason);
+  } catch (err) {
+    await run.end('error');
+    throw err;
+  } finally {
+    session.close();
+  }
+
+  return Response.json({ runId: run.runId, invocationId: run.invocationId });
+}
+```
+</Code>
diff --git a/src/pages/docs/ai-transport/api/javascript/core/client-session.mdx b/src/pages/docs/ai-transport/api/javascript/core/client-session.mdx
new file mode 100644
index 0000000000..bb44d2b099
--- /dev/null
+++ b/src/pages/docs/ai-transport/api/javascript/core/client-session.mdx
@@ -0,0 +1,298 @@
+---
+title: "ClientSession"
+meta_description: "API reference for the AI Transport ClientSession: factory, properties, lifecycle methods, and the View interface returned by createView()."
+meta_keywords: "AI Transport, ClientSession, createClientSession, View, Tree, connect, createView, cancel, Ably"
+redirect_from:
+  - /docs/ai-transport/api-reference/client-transport
+  - /docs/ai-transport/api/javascript/client-transport
+---
+
+The `ClientSession` subscribes to an Ably channel, decodes incoming messages through a codec, and builds a conversation tree. It owns the channel attach and the cancel-publish path, exposes a default branch-aware `View` for rendering, and lets you derive additional views over the same tree.
+
+Construct one with `createClientSession` from the core entry point. For Vercel `UIMessage` channels, use the pre-bound factory from [`@ably/ai-transport/vercel`](/docs/ai-transport/api/javascript/vercel/chat-transport) instead.
+
+<Code>
+```javascript
+import * as Ably from 'ably';
+import { createClientSession } from '@ably/ai-transport';
+import { UIMessageCodec } from '@ably/ai-transport/vercel';
+
+const ably = new Ably.Realtime({ authUrl: '/api/auth/token' });
+
+const session = createClientSession({
+  client: ably,
+  channelName: 'conversation-42',
+  codec: UIMessageCodec,
+});
+
+await session.connect();
+```
+</Code>
+
+## Properties <a id="properties"/>
+
+<Table id='ClientSessionProperties'>
+
+| Property | Description | Type |
+| --- | --- | --- |
+| tree | The complete conversation tree. Holds every known Run node and emits events on any change. Use `view` in most cases; reach for `tree` for low-level inspection. | <Table id='Tree'/> |
+| view | The default paginated, branch-aware view for rendering. Events scope to the visible messages. | <Table id='View'/> |
+
+</Table>
+
+<Table id='Tree' hidden>
+
+| Property | Description | Type |
+| --- | --- | --- |
+| getRunNode | `(runId: string) => RunNode \| undefined`. Get a Run by id. | Function |
+| getNodeByCodecMessageId | `(codecMessageId: string) => ConversationNode \| undefined`. Get the input or run node that owns a given codec-message-id. Narrow on `kind` (`'input'` or `'run'`) before reading kind-specific fields. | Function |
+| getSiblingNodes | `(key: string) => ConversationNode[]`. The sibling group for a node key: edit versions for an input node, regenerate siblings for a reply run. Ordered oldest-first by serial; single-element when there are no siblings; empty when the key is unknown. | Function |
+| on | `(event: 'update' \| 'ably-message' \| 'run' \| 'output', handler) => () => void`. Subscribe to tree changes. Returns an unsubscribe function. | Function |
+
+</Table>
+
+<Table id='View' hidden>
+
+| Property | Description | Type |
+| --- | --- | --- |
+| getMessages | `() => CodecMessage<TMessage>[]`. Visible messages along the selected branch, each paired with its `codecMessageId`. Read the domain object from each entry's `message` field; correlate back to the transport (run lookups, branch navigation, continuation routing) via `codecMessageId`. | Function |
+| runs | `() => RunInfo[]`. Visible Runs along the selected branch. | Function |
+| runOf | `(codecMessageId: string) => RunInfo \| undefined`. Run that owns the message. | Function |
+| run | `(runId: string) => RunInfo \| undefined`. Direct Run lookup by id. | Function |
+| branchSelection | `(codecMessageId: string) => BranchSelection`. Branch siblings at the anchor. | Function |
+| selectSibling | `(codecMessageId: string, index: number) => void`. Select a sibling at the anchor. | Function |
+| hasOlder | `() => boolean`. Whether older Runs can be loaded. | Function |
+| loadOlder | `(limit?: number) => Promise<void>`. Reveal older Runs. | Function |
+| send | `(events, options?) => Promise<ActiveRun>`. Send one or more `TInput`s on the channel and fire a POST. Wrap a domain message via `codec.createUserMessage` to send a fresh user message. | Function |
+| regenerate | `(messageId, options?) => Promise<ActiveRun>`. Regenerate an assistant message. | Function |
+| edit | `(messageId, inputs, options?) => Promise<ActiveRun>`. Edit a user message. | Function |
+| on | `(event: 'update' \| 'ably-message' \| 'run', handler) => () => void`. Subscribe to view updates, raw Ably messages for visible nodes, or run lifecycle events. Returns an unsubscribe function. | Function |
+| close | `() => void`. Tear down the view. | Function |
+
+</Table>
+
+## Create a client session <a id="constructor"/>
+
+<MethodSignature>{`function createClientSession<TInput, TOutput, TProjection, TMessage>(options: ClientSessionOptions<TInput, TOutput, TProjection, TMessage>): ClientSession<TInput, TOutput, TProjection, TMessage>`}</MethodSignature>
+
+Construct a `ClientSession` bound to an Ably channel. The session does not attach to the channel until [`connect()`](#connect) resolves.
+
+<Code>
+```javascript
+import * as Ably from 'ably';
+import { createClientSession } from '@ably/ai-transport';
+import { UIMessageCodec } from '@ably/ai-transport/vercel';
+
+const ably = new Ably.Realtime({ authUrl: '/api/auth/token' });
+
+const session = createClientSession({
+  client: ably,
+  channelName: 'conversation-42',
+  codec: UIMessageCodec,
+  clientId: 'user-abc',
+});
+```
+</Code>
+
+### Parameters <a id="constructor-params"/>
+
+<Table id='ClientSessionOptions'>
+
+| Parameter | Required | Description | Type |
+| --- | --- | --- | --- |
+| client | required | The Ably Realtime client. The caller owns its lifecycle; `session.close()` does not close the client. | `Ably.Realtime` |
+| channelName | required | The channel to subscribe to and publish cancel signals on. The session owns this channel; do not also resolve it elsewhere with conflicting options. | String |
+| codec | required | The codec used to encode and decode events and messages. | `Codec<TInput, TOutput, TProjection, TMessage>` |
+| clientId | optional | The client's identity, used as the Ably publisher `clientId` on everything this session publishes. Surfaces on the wire as the run-owner / input-owner id so other clients can attribute messages. | String |
+| messages | optional | Initial messages to seed the conversation tree with. Forms a linear chain. | `TMessage[]` |
+| logger | optional | Logger instance for diagnostic output. | `Logger` |
+
+</Table>
+
+### Returns <a id="constructor-returns"/>
+
+`ClientSession<TInput, TOutput, TProjection, TMessage>`. The session instance. Call [`connect()`](#connect) to attach before sending or cancelling.
+
+## Connect the session <a id="connect"/>
+
+<MethodSignature>{`connect(): Promise<void>`}</MethodSignature>
+
+Subscribe to the channel and implicitly attach. Idempotent: subsequent calls return the same promise.
+
+All write methods on [`view`](/docs/ai-transport/api/javascript/core/client-session#view) and [`cancel`](#cancel) throw `InvalidArgument` until `connect()` resolves.
+
+<Code>
+```javascript
+await session.connect();
+```
+</Code>
+
+### Returns <a id="connect-returns"/>
+
+`Promise<void>`. Resolves when the channel is attached and the session is ready for writes.
+
+## Create an additional view <a id="create-view"/>
+
+<MethodSignature>{`createView(): View<TInput, TMessage>`}</MethodSignature>
+
+Create an additional view over the same conversation tree. Each view has independent branch selections and pagination state.
+
+The caller owns the returned view's lifecycle: call its `close()` when it is no longer needed, or `session.close()` closes it.
+
+<Code>
+```javascript
+const secondaryView = session.createView();
+secondaryView.selectSibling(messageId, 1);
+
+// the default view is unaffected
+session.view.branchSelection(messageId).index; // 0
+```
+</Code>
+
+### Returns <a id="create-view-returns"/>
+
+`View<TInput, TMessage>`. A new view with its own pagination window and branch selection state.
+
+## Cancel a run <a id="cancel"/>
+
+<MethodSignature>{`cancel(runId: string): Promise<void>`}</MethodSignature>
+
+Publish a cancel signal for the specified Run. The agent receives the cancel through its own channel subscription and ends the Run with reason `'cancelled'`.
+
+<Code>
+```javascript
+const activeRun = await session.view.send({
+  kind: 'user-message',
+  message: {
+    id: crypto.randomUUID(),
+    role: 'user',
+    parts: [{ type: 'text', text: 'Tell me a story' }],
+  },
+});
+
+// later, cancel from the UI.
+// activeRun.cancel() works immediately, even before the runId
+// promise on activeRun has resolved.
+await activeRun.cancel();
+
+// Or, when you already have a resolved runId (for example from a
+// RunInfo in view.runs()):
+// await session.cancel(someRunInfo.runId);
+```
+</Code>
+
+### Parameters <a id="cancel-params"/>
+
+<Table id='CancelParameters'>
+
+| Parameter | Required | Description | Type |
+| --- | --- | --- | --- |
+| runId | required | The Run to cancel. Typically obtained from `ActiveRun.runId` returned by a send. | String |
+
+</Table>
+
+### Returns <a id="cancel-returns"/>
+
+`Promise<void>`. Resolves once the cancel message has been published. The cancel is best-effort: if the agent has already ended the Run, the cancel is a no-op.
+
+## Subscribe to session errors <a id="on"/>
+
+<MethodSignature>{`on(event: 'error', handler: (error: Ably.ErrorInfo) => void): () => void`}</MethodSignature>
+
+Subscribe to non-fatal session errors. These indicate something went wrong but the session is still operational; examples are subscription callback failures and channel continuity loss.
+
+<Code>
+```javascript
+const unsubscribe = session.on('error', (error) => {
+  console.error('Session error:', error.code, error.message);
+});
+
+// later, when the listener is no longer needed
+unsubscribe();
+```
+</Code>
+
+### Parameters <a id="on-params"/>
+
+<Table id='OnParameters'>
+
+| Parameter | Required | Description | Type |
+| --- | --- | --- | --- |
+| event | required | The event to subscribe to. Currently only `'error'`. | `'error'` |
+| handler | required | Called with an [`ErrorInfo`](/docs/ai-transport/api/errors#errorinfo) for every non-fatal error. | Function |
+
+</Table>
+
+### Returns <a id="on-returns"/>
+
+`() => void`. An unsubscribe function. Call it to remove the listener.
+
+## Close the session <a id="close"/>
+
+<MethodSignature>{`close(): Promise<void>`}</MethodSignature>
+
+Tear down the session. Unsubscribe from the channel, close active streams, clear handlers, and prevent further operations.
+
+`close()` is local-state-only. The server keeps streaming until its Runs end on their own. To stop in-progress Runs, call [`cancel`](#cancel) for each before `close()`.
+
+<Code>
+```javascript
+const runIds = session.view.runs()
+  .filter((run) => run.status === 'active')
+  .map((run) => run.runId);
+
+await Promise.all(runIds.map((runId) => session.cancel(runId)));
+await session.close();
+```
+</Code>
+
+### Returns <a id="close-returns"/>
+
+`Promise<void>`. Resolves once the channel has been released.
+
+## Example <a id="example"/>
+
+End-to-end usage covering construction, connect, send, and teardown.
+
+<Code>
+```javascript
+import * as Ably from 'ably';
+import { createClientSession } from '@ably/ai-transport';
+import { UIMessageCodec } from '@ably/ai-transport/vercel';
+
+const ably = new Ably.Realtime({ authUrl: '/api/auth/token' });
+
+const session = createClientSession({
+  client: ably,
+  channelName: 'conversation-42',
+  codec: UIMessageCodec,
+  clientId: 'user-abc',
+});
+
+await session.connect();
+
+session.view.on('update', () => {
+  render(session.view.getMessages().map(({ message }) => message));
+});
+
+const activeRun = await session.view.send(UIMessageCodec.createUserMessage({
+  id: crypto.randomUUID(),
+  role: 'user',
+  parts: [{ type: 'text', text: 'Plan a 3-day trip to Lisbon.' }],
+}));
+
+// The SDK doesn't POST. The application wakes the agent itself.
+await fetch('/api/chat', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify(activeRun.toInvocation().toJSON()),
+});
+
+// The agent assigns the runId on the server, so activeRun.runId is a
+// Promise. Await it to read the id.
+const runId = await activeRun.runId;
+
+await session.close();
+ably.close();
+```
+</Code>
diff --git a/src/pages/docs/ai-transport/api/javascript/core/codec.mdx b/src/pages/docs/ai-transport/api/javascript/core/codec.mdx
new file mode 100644
index 0000000000..deef39b80d
--- /dev/null
+++ b/src/pages/docs/ai-transport/api/javascript/core/codec.mdx
@@ -0,0 +1,397 @@
+---
+title: "Codec"
+meta_description: "API reference for the AI Transport Codec interface. Build custom codecs to integrate any AI framework with Ably channels."
+meta_keywords: "AI Transport, Codec, Encoder, Decoder, DecodedMessage, CodecInputEvent, CodecOutputEvent, Reducer, custom codec, Ably"
+redirect_from:
+  - /docs/ai-transport/api-reference/codec
+  - /docs/ai-transport/api/javascript/codec
+---
+
+The `Codec` interface is the bridge between an AI framework and Ably channel messages. It describes the wire as a flat stream of input and output events and folds those events into a per-Run projection that the SDK extracts messages from for the conversation tree.
+
+Implement `Codec<TInput, TOutput, TProjection, TMessage>` to integrate any AI framework with AI Transport. The SDK ships [`UIMessageCodec`](/docs/ai-transport/api/javascript/vercel/codec) for the Vercel AI SDK. For other frameworks, implement the methods below.
+
+<Code>
+```typescript
+import type { Codec } from '@ably/ai-transport';
+
+const myCodec: Codec<MyInput, MyOutput, MyProjection, MyMessage> = {
+  init() { /* ... */ },
+  fold(state, event, meta) { /* ... */ },
+  createEncoder(channel, options) { /* ... */ },
+  createDecoder() { /* ... */ },
+  getMessages(projection) { /* ... */ },
+  createUserMessage(message) { /* ... */ },
+  createRegenerate(target, parent) { /* ... */ },
+};
+```
+</Code>
+
+## Properties <a id="properties"/>
+
+`Codec` extends [`Reducer<TInput | TOutput, TProjection>`](#reducer) and adds factories for encoders, decoders, and the message-extraction step the SDK uses to populate the tree.
+
+<Table id='CodecProperties'>
+
+| Property | Description | Type |
+| --- | --- | --- |
+| init | Build an empty initial projection. Called once per Run before any events are folded. | `() => TProjection` |
+| fold | Fold one event into the projection and return the updated projection. May mutate `state` in place. | `(state, event, meta) => TProjection` |
+| createEncoder | Create a stateful encoder bound to the given channel writer. Takes optional <Table id='EncoderOptions'/>. | `(channel, options?) => Encoder<TInput, TOutput>` |
+| createDecoder | Create a stateful decoder that maps inbound Ably messages to typed inputs and outputs. Each call returns a <Table id='DecodedMessage'/>. | `() => Decoder<TInput, TOutput>` |
+| getMessages | Extract the per-message list from a projection as `{ codecMessageId, message }` pairs. The SDK uses the pairs to correlate rendered messages back to the wire id; the View concatenates them across the visible Run chain. | `(projection) => CodecMessage<TMessage>[]` |
+| createUserMessage | Wrap a `TMessage` as the codec's `UserMessage` variant for publishing on the `ai-input` wire. Returns the codec's `TInput` so the result is usable as a `View.send` argument without a cast. | `(message) => TInput` |
+| createRegenerate | Build a `Regenerate` input that targets an assistant message. The View calls this from `regenerate()`. | `(target, parent) => TInput` |
+| createToolResult | Optional. Build a `ToolResult` input addressed at the assistant codec-message containing the tool call. The codec defines the payload shape (for example the Vercel layer's `{ toolCallId, output }`). | `(codecMessageId, payload) => TInput` |
+| createToolResultError | Optional. Build a `ToolResultError` input. The codec defines the payload shape (for example `{ toolCallId, message }`). | `(codecMessageId, payload) => TInput` |
+| createToolApprovalResponse | Optional. Build a `ToolApprovalResponse` input. The codec defines the payload shape (for example `{ toolCallId, approved, reason? }`). | `(codecMessageId, payload) => TInput` |
+
+</Table>
+
+## Fold an event into a projection <a id="fold"/>
+
+<MethodSignature>{`fold(state: TProjection, event: TInput | TOutput, meta: ReducerMeta): TProjection`}</MethodSignature>
+
+The reducer contract: fold one event into the projection. The same `(state, event, meta)` triple must produce the same result every time. Re-folding an event whose serial has already been incorporated must be a no-op. The reducer is free to store a high-water-mark inside the projection.
+
+<Table id='ReducerMeta' hidden>
+
+| Property | Description | Type |
+| --- | --- | --- |
+| serial | Ably channel serial of the message that produced this event. The reducer uses this for idempotency and deduplication. | String |
+| messageId | Optional `codec-message-id` from the inbound Ably message. Reducers use this to route an event to a target message within the projection. | String |
+
+</Table>
+
+### Parameters <a id="fold-params"/>
+
+<Table id='FoldParameters'>
+
+| Parameter | Required | Description | Type |
+| --- | --- | --- | --- |
+| state | required | The current projection. May be mutated and returned. | `TProjection` |
+| event | required | The next input or output event to fold. | `TInput \| TOutput` |
+| meta | required | Transport-derived metadata stamped from the inbound Ably message. | <Table id='ReducerMeta'/> |
+
+</Table>
+
+### Returns <a id="fold-returns"/>
+
+`TProjection`. The updated projection.
+
+## Create an encoder <a id="create-encoder"/>
+
+<MethodSignature>{`createEncoder(channel: ChannelWriter, options?: EncoderOptions): Encoder<TInput, TOutput>`}</MethodSignature>
+
+Build a stateful encoder bound to a channel. The encoder owns the message-append lifecycle for both directions on a single channel.
+
+### Parameters <a id="create-encoder-params"/>
+
+<Table id='CreateEncoderParameters'>
+
+| Parameter | Required | Description | Type |
+| --- | --- | --- | --- |
+| channel | required | The channel writer to publish through. An `Ably.RealtimeChannel` satisfies this directly. | `ChannelWriter` |
+| options | optional | Per-encoder defaults (clientId, extras, messageId, onMessage hook). | <Table id='EncoderOptions'/> |
+
+</Table>
+
+<Table id='EncoderOptions' hidden>
+
+| Property | Description | Type |
+| --- | --- | --- |
+| clientId | Default clientId for all writes. | String |
+| extras | Default extras merged into every Ably message. | <Table id='Extras'/> |
+| onMessage | Hook called before each Ably message is published. Mutate the message in place to add transport-level headers under `extras.ai`. | `(message: Ably.Message) => void` |
+| messageId | Default `codec-message-id` for messages where the event payload doesn't supply one. | String |
+
+</Table>
+
+<Table id='Extras' hidden>
+
+| Property | Description | Type |
+| --- | --- | --- |
+| headers | Transport-tier headers to attach to the message's `extras.ai.transport` namespace. | `Record<string, string>` |
+
+</Table>
+
+### Returns <a id="create-encoder-returns"/>
+
+[`Encoder<TInput, TOutput>`](#encoder). A stateful encoder bound to the supplied channel.
+
+## Create a decoder <a id="create-decoder"/>
+
+<MethodSignature>{`createDecoder(): Decoder<TInput, TOutput>`}</MethodSignature>
+
+Build a stateful decoder for a single channel subscription. The decoder maintains stream-tracker state across messages so that mid-stream join synthesises any missing start events before deltas reach the SDK. The reducer always sees a clean `(start, delta*, end)` sequence.
+
+### Returns <a id="create-decoder-returns"/>
+
+[`Decoder<TInput, TOutput>`](#decoder). A stateful decoder for the channel.
+
+## Encoder <a id="encoder"/>
+
+A stateful encoder for a single channel. Two publish methods enforce direction at the call site. `publishInput` writes to the `ai-input` wire, `publishOutput` writes to the `ai-output` wire. Stream-tracker state lives inside the encoder and is shared across both directions.
+
+### Properties
+
+<Table id='EncoderProperties'>
+
+| Property | Description | Type |
+| --- | --- | --- |
+| publishInput | Encode and publish a single client input on the `ai-input` wire. Throws synchronously if the codec cannot encode the given input variant. | `(input, options?) => Promise<void>` |
+| publishOutput | Encode and publish a single agent output on the `ai-output` wire. Throws synchronously if the codec cannot encode the given output variant. | `(output, options?) => Promise<void>` |
+| cancel | Cancel any in-progress streams and emit a codec-specific cancel signal. Idempotent. | `(reason?: string) => Promise<void>` |
+| close | Flush pending appends and release encoder resources. | `() => Promise<void>` |
+
+</Table>
+
+<Table id='WriteOptions' hidden>
+
+| Property | Description | Type |
+| --- | --- | --- |
+| clientId | Override the default clientId for this write. | String |
+| extras | Override the default extras for this write. | <Table id='Extras'/> |
+| messageId | Message identity for projection routing. Stamped as `codec-message-id`. | String |
+
+</Table>
+
+### Publish an input <a id="publish-input"/>
+
+<MethodSignature>{`publishInput(input: TInput, options?: WriteOptions): Promise<void>`}</MethodSignature>
+
+Encode and publish a single client input on the `ai-input` wire. Per-write overrides live in [`WriteOptions`](#write-options).
+
+#### Parameters <a id="publish-input-params"/>
+
+<Table id='PublishInputParameters'>
+
+| Parameter | Required | Description | Type |
+| --- | --- | --- | --- |
+| input | required | The input event to encode and publish. | `TInput` |
+| options | optional | Per-write overrides (clientId, extras, messageId). | <Table id='WriteOptions'/> |
+
+</Table>
+
+### Publish an output <a id="publish-output"/>
+
+<MethodSignature>{`publishOutput(output: TOutput, options?: WriteOptions): Promise<void>`}</MethodSignature>
+
+Encode and publish a single agent output on the `ai-output` wire.
+
+#### Parameters <a id="publish-output-params"/>
+
+<Table id='PublishOutputParameters'>
+
+| Parameter | Required | Description | Type |
+| --- | --- | --- | --- |
+| output | required | The output event to encode and publish. | `TOutput` |
+| options | optional | Per-write overrides. | <Table id='WriteOptions'/> |
+
+</Table>
+
+## Decoder <a id="decoder"/>
+
+A stateful decoder for a single channel subscription. Decodes one Ably inbound message into the input and output halves.
+
+### Decode a message <a id="decode"/>
+
+<MethodSignature>{`decode(message: Ably.InboundMessage): DecodedMessage<TInput, TOutput>`}</MethodSignature>
+
+Tagged result of decoding one inbound Ably message. The codec routes by the wire `name` and returns inputs and outputs separately so the SDK never has to introspect direction.
+
+<Table id='DecodedMessage' hidden>
+
+| Property | Description | Type |
+| --- | --- | --- |
+| inputs | Inputs decoded from the inbound message (populated when the wire `name` is `ai-input`). | `TInput[]` |
+| outputs | Outputs decoded from the inbound message (populated when the wire `name` is `ai-output`). | `TOutput[]` |
+
+</Table>
+
+### Returns <a id="decode-returns"/>
+
+`DecodedMessage<TInput, TOutput>`. Tagged inputs and outputs. <Table id='DecodedMessage'/>
+
+## Well-known input variants <a id="input-variants"/>
+
+Codec input variants extend the `CodecInputEvent` base. The SDK reserves a handful of well-known `kind` literals so callers can publish a user message, regenerate an assistant message, or resolve a tool call without inventing their own shapes. Codec-specific variants pick any other literal. (Edits ride the user-message path with a `forkOf` routing header; there is no separate `'edit'` kind on the wire.)
+
+<Table id='CodecInputEvent'>
+
+| Property | Description | Type |
+| --- | --- | --- |
+| kind | Discriminator. The SDK reserves `'user-message'`, `'regenerate'`, `'tool-result'`, `'tool-result-error'`, and `'tool-approval-response'`. | String |
+| parent | The codec-message-id of the preceding codec-message on this branch. Auto-computed when omitted. | String |
+| target | Pointer to another codec-message this input references. Semantic depends on `kind`. | String |
+| codecMessageId | Targets an existing codec-message-id instead of minting a fresh one. Used by continuation inputs that amend an existing assistant message. | String |
+
+</Table>
+
+The full input union is the codec author's responsibility. Use the variants below directly or extend them with extra fields.
+
+### UserMessage <a id="user-message"/>
+
+<Table id='UserMessage'>
+
+| Property | Description | Type |
+| --- | --- | --- |
+| kind | Pinned to `'user-message'`. | `'user-message'` |
+| message | The user's message in the codec's domain representation. | `TMessage` |
+
+</Table>
+
+A new user message. Produced by `Codec.createUserMessage` and surfaced via `View.send` (wrap a domain message via `codec.createUserMessage(message)` or build the literal directly).
+
+### Regenerate <a id="regenerate"/>
+
+<Table id='Regenerate'>
+
+| Property | Description | Type |
+| --- | --- | --- |
+| kind | Pinned to `'regenerate'`. | `'regenerate'` |
+| target | The codec-message-id of the assistant to regenerate. Required. | String |
+| parent | The codec-message-id of the parent user message the new assistant threads under. Required. | String |
+
+</Table>
+
+A signal to regenerate an existing assistant codec-message. Produced by `Codec.createRegenerate` and surfaced via `View.regenerate`.
+
+### ToolResult <a id="tool-result"/>
+
+<Table id='ToolResult'>
+
+| Property | Description | Type |
+| --- | --- | --- |
+| kind | Pinned to `'tool-result'`. | `'tool-result'` |
+| codecMessageId | The assistant codec-message containing the tool call. | String |
+| payload | Codec-defined domain payload describing the result. The Vercel codec uses `{ toolCallId, output }`; custom codecs pick their own shape. | `TPayload` |
+
+</Table>
+
+A client-published tool result for a successful execution. Mutates the assistant codec-message addressed by `codecMessageId`.
+
+### ToolResultError <a id="tool-result-error"/>
+
+<Table id='ToolResultError'>
+
+| Property | Description | Type |
+| --- | --- | --- |
+| kind | Pinned to `'tool-result-error'`. | `'tool-result-error'` |
+| codecMessageId | The assistant codec-message containing the tool call. | String |
+| payload | Codec-defined domain payload describing the failure. The Vercel codec uses `{ toolCallId, message }`. | `TPayload` |
+
+</Table>
+
+A client-published tool result for a failed execution.
+
+### ToolApprovalResponse <a id="tool-approval-response"/>
+
+<Table id='ToolApprovalResponse'>
+
+| Property | Description | Type |
+| --- | --- | --- |
+| kind | Pinned to `'tool-approval-response'`. | `'tool-approval-response'` |
+| codecMessageId | The assistant codec-message containing the tool call. | String |
+| payload | Codec-defined domain payload describing the decision. The Vercel codec uses `{ toolCallId, approved, reason? }`. | `TPayload` |
+
+</Table>
+
+A client-published response to an agent-emitted tool-approval request. Flips the targeted tool call from pending-approval to approved or denied.
+
+## Codec output base <a id="output-base"/>
+
+<Table id='CodecOutputEvent'>
+
+| Property | Description | Type |
+| --- | --- | --- |
+| type | Discriminator. Codec authors pick the literal value per variant. | String |
+
+</Table>
+
+Every codec output variant must satisfy `CodecOutputEvent`. The SDK reads `type` so it can reliably narrow `TInput | TOutput` (inputs carry `kind`, outputs carry `type`).
+
+## Wire payloads <a id="payloads"/>
+
+The encoder and decoder cores describe Ably messages with two payload shapes, used internally by `createEncoderCore` and `createDecoderCore`. Custom codec implementations that build on those cores work with these shapes directly.
+
+`MessagePayload` describes a discrete Ably message.
+
+<Table id='MessagePayload'>
+
+| Property | Description | Type |
+| --- | --- | --- |
+| name | Ably message name (for example `"text"`, `"tool-input"`, `"user-message"`). | String |
+| data | Message data. Ably handles serialisation. | `unknown` |
+| codecHeaders | Codec-tier headers carried under `extras.ai.codec`. | `Record<string, string>` |
+| transportHeaders | Transport-tier headers carried under `extras.ai.transport`. | `Record<string, string>` |
+| ephemeral | Mark this message as ephemeral (not persisted in channel history). | Boolean |
+
+</Table>
+
+`StreamPayload` describes a streamed message. Data must be a string because the append lifecycle uses text append semantics. Deltas are concatenated for recovery and prefix-matching on the decoder.
+
+<Table id='StreamPayload'>
+
+| Property | Description | Type |
+| --- | --- | --- |
+| name | Ably message name. | String |
+| data | Initial or closing data for the stream. Must be a string for append/accumulate semantics. | String |
+| codecHeaders | Codec-tier headers carried under `extras.ai.codec`. | `Record<string, string>` |
+| transportHeaders | Transport-tier headers carried under `extras.ai.transport`. | `Record<string, string>` |
+
+</Table>
+
+## Reducer <a id="reducer"/>
+
+The reducer is a pure, stateless folding contract that `Codec` extends.
+
+<Table id='Reducer'>
+
+| Property | Description | Type |
+| --- | --- | --- |
+| init | Build an empty initial projection. | `() => TProjection` |
+| fold | Fold one event into the projection. | `(state, event, meta) => TProjection` |
+
+</Table>
+
+## Example <a id="example"/>
+
+A minimal codec skeleton that folds a single input and output variant and extracts a flat message list.
+
+<Code>
+```typescript
+import type {
+  Codec,
+  CodecInputEvent,
+  CodecOutputEvent,
+  CodecMessage,
+  ReducerMeta,
+} from '@ably/ai-transport';
+
+interface MyInput extends CodecInputEvent { kind: 'user-message'; message: MyMessage }
+interface MyOutput extends CodecOutputEvent { type: 'text-delta'; text: string }
+interface MyProjection { highWater: string; messages: CodecMessage<MyMessage>[] }
+interface MyMessage { id: string; role: 'user' | 'assistant'; text: string }
+
+const myCodec: Codec<MyInput, MyOutput, MyProjection, MyMessage> = {
+  init: () => ({ highWater: '', messages: [] }),
+  fold: (state, event, meta: ReducerMeta) => {
+    if (meta.serial <= state.highWater) return state;
+    state.highWater = meta.serial;
+    if ('kind' in event && event.kind === 'user-message') {
+      state.messages.push({ codecMessageId: meta.messageId ?? event.message.id, message: event.message });
+    } else if ('type' in event && event.type === 'text-delta') {
+      const last = state.messages.at(-1);
+      if (last?.message.role === 'assistant') last.message.text += event.text;
+    }
+    return state;
+  },
+  createEncoder: (channel, options) => buildEncoder(channel, options),
+  createDecoder: () => buildDecoder(),
+  getMessages: (projection) => projection.messages,
+  createUserMessage: (message) => ({ kind: 'user-message', message }),
+  createRegenerate: (target, parent) => ({ kind: 'regenerate', target, parent }),
+};
+```
+</Code>
diff --git a/src/pages/docs/ai-transport/api/javascript/server-transport.mdx b/src/pages/docs/ai-transport/api/javascript/server-transport.mdx
deleted file mode 100644
index 018b308fdc..0000000000
--- a/src/pages/docs/ai-transport/api/javascript/server-transport.mdx
+++ /dev/null
@@ -1,426 +0,0 @@
----
-title: "ServerTransport"
-meta_description: "API reference for the AI Transport server transport: turn lifecycle, cancel routing, abort hooks, and configuration options."
-meta_keywords: "AI Transport, ServerTransport, Turn, newTurn, streamResponse, addMessages, addEvents, onCancel, Ably"
-redirect_from:
-  - /docs/ai-transport/api-reference/server-transport
----
-
-The `ServerTransport` publishes to an Ably channel on behalf of the agent, manages the turn lifecycle, and routes cancel signals from clients to active turns. It is the server-side counterpart to [`ClientTransport`](/docs/ai-transport/api/javascript/client-transport).
-
-Construct one with `createServerTransport` from the core entry point, or use the Vercel-pre-bound factory from `@ably/ai-transport/vercel` when the channel carries Vercel `UIMessage` content.
-
-<Code>
-```javascript
-import { createServerTransport } from '@ably/ai-transport';
-import { UIMessageCodec } from '@ably/ai-transport/vercel';
-
-const transport = createServerTransport({
-  channel,
-  codec: UIMessageCodec,
-});
-
-const turn = transport.newTurn({ turnId, clientId });
-```
-</Code>
-
-## Create a server transport <a id="constructor"/>
-
-<MethodSignature>{`function createServerTransport<TEvent, TMessage>(options: ServerTransportOptions<TEvent, TMessage>): ServerTransport<TEvent, TMessage>`}</MethodSignature>
-
-Construct a `ServerTransport` bound to an Ably channel. The transport attaches to the channel lazily on first use.
-
-<Code>
-```javascript
-import Ably from 'ably';
-import { createServerTransport } from '@ably/ai-transport';
-import { UIMessageCodec } from '@ably/ai-transport/vercel';
-
-const ably = new Ably.Realtime({ key: process.env.ABLY_API_KEY });
-const channel = ably.channels.get('conversation-42');
-
-const transport = createServerTransport({
-  channel,
-  codec: UIMessageCodec,
-  onError(error) {
-    console.error(`Transport error ${error.code}: ${error.message}`);
-  },
-});
-```
-</Code>
-
-### Parameters <a id="constructor-params"/>
-
-<Table id='CreateServerTransportParameters'>
-
-| Parameter | Required | Description | Type |
-| --- | --- | --- | --- |
-| options | Required | Configuration for the server transport. | <Table id='ServerTransportOptions'/> |
-
-</Table>
-
-<Table id='ServerTransportOptions' hidden>
-
-| Property | Description | Type |
-| --- | --- | --- |
-| channel | The Ably channel to publish to. Must match the client's channel. | `Ably.RealtimeChannel` |
-| codec | The codec to use for encoding events and messages. See [Codec](/docs/ai-transport/api/javascript/codec). | `Codec<TEvent, TMessage>` |
-| logger | Logger instance for diagnostic output. | `Logger` or Undefined |
-| onError | Called with non-fatal transport-level errors not scoped to any turn. Examples: cancel listener subscription failure, channel attach errors, channel continuity loss. | `(error: Ably.ErrorInfo) => void` or Undefined |
-
-</Table>
-
-### Returns <a id="constructor-returns"/>
-
-`ServerTransport<TEvent, TMessage>`
-
-A new server transport. Lifecycle is managed by the caller; call `close()` to release resources.
-
-## Create a turn <a id="new-turn"/>
-
-<MethodSignature>{`newTurn(options: NewTurnOptions<TEvent>): Turn<TEvent, TMessage>`}</MethodSignature>
-
-Create a new turn. Synchronous; no channel activity until `start()` is called on the returned turn. The turn is registered for cancel routing immediately so that early cancels fire the abort signal.
-
-<Code>
-```javascript
-const turn = transport.newTurn({
-  turnId,
-  clientId,
-  parent,
-  forkOf,
-  onCancel: async (request) => {
-    const owner = request.turnOwners.get(request.filter.turnId);
-    return owner === request.message.clientId;
-  },
-});
-```
-</Code>
-
-### Parameters <a id="new-turn-params"/>
-
-<Table id='NewTurnParameters'>
-
-| Parameter | Required | Description | Type |
-| --- | --- | --- | --- |
-| options | Required | Turn configuration. | <Table id='NewTurnOptions'/> |
-
-</Table>
-
-<Table id='NewTurnOptions' hidden>
-
-| Property | Description | Type |
-| --- | --- | --- |
-| turnId | The turn identifier (generated by the client transport or the server). | String |
-| clientId | The user's `clientId` for attribution. | String or Undefined |
-| parent | The msg-id of the immediately preceding message in this branch. Used as the default parent for `addMessages` and `streamResponse` when not overridden per-operation. | String or Undefined |
-| forkOf | The msg-id of the message this turn replaces. Stamped on user messages (for edits) or assistant messages (for regeneration). | String or Undefined |
-| onMessage | Called before each Ably message is published in this turn. Mutate the Ably message in place to add custom `extras.headers`. | `(message: Ably.Message) => void` or Undefined |
-| onAbort | Called when the turn's stream is aborted (by cancel or server). Receives a `write` function to publish final events before the abort finalises. | `(write: (event: TEvent) => Promise<void>) => void \| Promise<void>` or Undefined |
-| onCancel | Called when a cancel message arrives matching this turn. Return `true` to allow cancellation (fires the abort signal, stream aborts); return `false` to reject (cancel ignored, stream continues). If not provided, all cancels are accepted. The handler receives a <Table id='CancelRequest'/>. | `(request: CancelRequest) => Promise<boolean>` or Undefined |
-| onError | Called with non-fatal turn-scoped errors that have no other delivery path. See description below. | `(error: Ably.ErrorInfo) => void` or Undefined |
-| signal | External abort signal (typically the HTTP request's `req.signal`) that, when fired, aborts this turn. Use to wire platform-level cancellation (request cancellation, serverless function timeout). | `AbortSignal` or Undefined |
-
-</Table>
-
-<Table id='CancelRequest' hidden>
-
-| Property | Description | Type |
-| --- | --- | --- |
-| message | The raw Ably message that carried the cancel signal. | `Ably.InboundMessage` |
-| filter | The parsed cancel scope from the message headers. | <Table id='CancelFilter'/> |
-| matchedTurnIds | Which active turnIds would be cancelled if allowed. | `string[]` |
-| turnOwners | Map of `turnId` to the owner `clientId` for the matched turns. | `Map<string, string>` |
-
-</Table>
-
-<Table id='CancelFilter' hidden>
-
-| Property | Description | Type |
-| --- | --- | --- |
-| turnId | A specific turn ID to cancel. | String or Undefined |
-| own | Cancel every turn belonging to the sender's `clientId`. | Boolean or Undefined |
-| clientId | Cancel every turn belonging to a specific `clientId`. | String or Undefined |
-| all | Cancel every turn on the channel. | Boolean or Undefined |
-
-</Table>
-
-`onError` fires in two scenarios. First, stream failures in `streamResponse` (the underlying error is also returned on `StreamResult.error`, but this callback delivers it wrapped as an [`ErrorInfo`](/docs/ai-transport/api/errors#errorinfo) with code `StreamError` for standardised observability). Second, failures in the `onCancel` handler. Publish failures in `start`, `addMessages`, `addEvents`, and `end` reject the returned promise instead and are not delivered to `onError`. Channel-wide events (continuity loss) are delivered via the transport-level `onError` on `ServerTransportOptions`.
-
-### Returns <a id="new-turn-returns"/>
-
-`Turn<TEvent, TMessage>`
-
-A new turn. Call its lifecycle methods (`start`, `addMessages`, `streamResponse`, `addEvents`, `end`) to publish to the channel.
-
-## Close the transport <a id="close"/>
-
-<MethodSignature>close(): void</MethodSignature>
-
-Unsubscribe from cancel messages, abort all active turns, and clean up. Synchronous.
-
-<Code>
-```javascript
-transport.close();
-```
-</Code>
-
-## Turn <a id="Turn"/>
-
-A `Turn` is the server-side handle for a single turn's lifecycle. Create one with `transport.newTurn()` and call its methods in order: `start` → optionally `addMessages` → `streamResponse` (and/or `addEvents`) → `end`.
-
-### Properties
-
-<Table id='TurnProperties'>
-
-| Property | Description | Type |
-| --- | --- | --- |
-| turnId | The turn's unique identifier. | String |
-| abortSignal | Abort signal scoped to this turn. Fires when a cancel event arrives for this `turnId`. Pass to the LLM call so generation stops on cancel. | `AbortSignal` |
-
-</Table>
-
-### Start the turn <a id="Turn-start"/>
-
-<MethodSignature>{`start(): Promise<void>`}</MethodSignature>
-
-Publish the turn-start event to the channel. Must be called before `addMessages` or `streamResponse`.
-
-#### Returns <a id="Turn-start-returns"/>
-
-`Promise<void>`
-
-Returns a promise. The promise is fulfilled when the turn-start event has been published, or rejected with an [`ErrorInfo`](/docs/ai-transport/api/errors#errorinfo) object.
-
-### Add user messages <a id="Turn-addMessages"/>
-
-<MethodSignature>{`addMessages(messages: MessageNode<TMessage>[], options?: AddMessageOptions): Promise<AddMessagesResult>`}</MethodSignature>
-
-Publish user messages to the channel, scoped to this turn. Each node's `msgId`, `parentId`, and `forkOf` are used for message identity and branching. The node's `headers` override transport-generated defaults (used for optimistic reconciliation with the client's inserts).
-
-#### Parameters <a id="Turn-addMessages-params"/>
-
-<Table id='TurnAddMessagesParameters'>
-
-| Parameter | Required | Description | Type |
-| --- | --- | --- | --- |
-| messages | Required | User messages to publish. Each node carries identity, headers, and the domain message. | <Table id='MessageNode'/> |
-| options | Optional | Per-operation overrides for attribution. | <Table id='AddMessageOptions'/> |
-
-</Table>
-
-<Table id='AddMessageOptions' hidden>
-
-| Property | Description | Type |
-| --- | --- | --- |
-| clientId | The user's `clientId` for attribution. Overrides the turn's `clientId`. | String or Undefined |
-
-</Table>
-
-<Table id='MessageNode' hidden>
-
-| Property | Description | Type |
-| --- | --- | --- |
-| kind | `'message'`. Distinguishes a message node from an events node. | String |
-| msgId | The Ably message ID to publish under. Primary key in the tree. | String |
-| message | The domain message to encode. | `TMessage` |
-| parentId | The parent node's `msgId`, or `undefined` for root messages. | String or Undefined |
-| forkOf | The `msgId` this node forks from (regeneration or edit), or `undefined` if it is the first version. | String or Undefined |
-| headers | Transport headers overriding transport-generated defaults. | `Record<string, string>` |
-| serial | The Ably serial for tree ordering. Set on tree-side; not used by the encoder. | String or Undefined |
-
-</Table>
-
-#### Returns <a id="Turn-addMessages-returns"/>
-
-`Promise<AddMessagesResult>`
-
-Returns a promise. The promise is fulfilled with an <Table id='AddMessagesResult'/> containing the `x-ably-msg-id` of each published message in order, or rejected with an [`ErrorInfo`](/docs/ai-transport/api/errors#errorinfo) object.
-
-<Table id='AddMessagesResult' hidden>
-
-| Property | Description | Type |
-| --- | --- | --- |
-| msgIds | The `x-ably-msg-id` of each published message, in order. | `string[]` |
-
-</Table>
-
-### Stream a response <a id="Turn-streamResponse"/>
-
-<MethodSignature>{`streamResponse(stream: ReadableStream<TEvent>, options?: StreamResponseOptions<TEvent>): Promise<StreamResult>`}</MethodSignature>
-
-Pipe a `ReadableStream` through the encoder to the channel. Returns when the stream completes, is cancelled, or errors. Does not call `end()`; the caller must call `end()` after `streamResponse` returns.
-
-<Code>
-```javascript
-const result = streamText({
-  model: anthropic('claude-sonnet-4-20250514'),
-  messages: history,
-  abortSignal: turn.abortSignal,
-});
-
-const { reason } = await turn.streamResponse(result.toUIMessageStream());
-await turn.end(reason);
-```
-</Code>
-
-#### Parameters <a id="Turn-streamResponse-params"/>
-
-<Table id='TurnStreamResponseParameters'>
-
-| Parameter | Required | Description | Type |
-| --- | --- | --- | --- |
-| stream | Required | The event stream to encode and publish. | `ReadableStream<TEvent>` |
-| options | Optional | Per-operation overrides for the assistant message. | <Table id='StreamResponseOptions'/> |
-
-</Table>
-
-<Table id='StreamResponseOptions' hidden>
-
-| Property | Description | Type |
-| --- | --- | --- |
-| parent | The msg-id of the immediately preceding message in this branch. Overrides the turn's `parent`. | String or Undefined |
-| forkOf | The msg-id of the message this response replaces (for regeneration). | String or Undefined |
-| resolveWriteOptions | Per-event hook invoked before each event is encoded. The returned `WriteOptions` (if any) override the stream's default headers and `msgId` for that one encode call only; return `undefined` to use the stream defaults. Used to carry a subset of events within the stream to a different message (for example, `tool-output-available` chunks that belong on a prior assistant message). Must not be used for events that participate in the encoder's stream-append pipeline. | `(event: TEvent) => WriteOptions \| undefined` or Undefined |
-
-</Table>
-
-#### Returns <a id="Turn-streamResponse-returns"/>
-
-`Promise<StreamResult>`
-
-Returns a promise. The promise is fulfilled with a <Table id='StreamResult'/> describing why the stream ended, or rejected with an [`ErrorInfo`](/docs/ai-transport/api/errors#errorinfo) object.
-
-<Table id='StreamResult' hidden>
-
-| Property | Description | Type |
-| --- | --- | --- |
-| reason | Why the stream ended. One of `'complete'`, `'cancelled'`, `'error'`. | `TurnEndReason` |
-| error | The error that caused the stream to fail, present when `reason` is `'error'`. The original error from the LLM provider, preserved so the caller can inspect provider-specific fields. | `Error` or Undefined |
-
-</Table>
-
-### Add events to existing messages <a id="Turn-addEvents"/>
-
-<MethodSignature>{`addEvents(nodes: EventsNode<TEvent>[]): Promise<void>`}</MethodSignature>
-
-Publish events targeting existing messages in the tree. Each node specifies a target message (by `msgId`) and the events to apply. Events are encoded and published with the target's `x-ably-msg-id`, so receiving clients apply them to the existing node rather than creating a new one.
-
-Used for cross-turn updates such as tool result delivery after approval or client-side tool execution.
-
-#### Parameters <a id="Turn-addEvents-params"/>
-
-<Table id='TurnAddEventsParameters'>
-
-| Parameter | Required | Description | Type |
-| --- | --- | --- | --- |
-| nodes | Required | Events nodes targeting existing messages. | <Table id='EventsNode'/> |
-
-</Table>
-
-<Table id='EventsNode' hidden>
-
-| Property | Description | Type |
-| --- | --- | --- |
-| kind | `'event'`. Distinguishes an events node from a message node. | String |
-| msgId | The `x-ably-msg-id` of the existing message to update. | String |
-| events | Events to apply to the target message. | `TEvent[]` |
-
-</Table>
-
-#### Returns <a id="Turn-addEvents-returns"/>
-
-`Promise<void>`
-
-Returns a promise. The promise is fulfilled when every targeted message has received its events, or rejected with an [`ErrorInfo`](/docs/ai-transport/api/errors#errorinfo) object.
-
-### End the turn <a id="Turn-end"/>
-
-<MethodSignature>{`end(reason: TurnEndReason): Promise<void>`}</MethodSignature>
-
-Publish the turn-end event to the channel and clean up. `reason` is one of `'complete'`, `'cancelled'`, or `'error'`.
-
-<Code>
-```javascript
-await turn.end('complete');
-```
-</Code>
-
-#### Parameters <a id="Turn-end-params"/>
-
-<Table id='TurnEndParameters'>
-
-| Parameter | Required | Description | Type |
-| --- | --- | --- | --- |
-| reason | Required | Why the turn ended. | `'complete'` or `'cancelled'` or `'error'` |
-
-</Table>
-
-#### Returns <a id="Turn-end-returns"/>
-
-`Promise<void>`
-
-Returns a promise. The promise is fulfilled when the turn-end event has been published, or rejected with an [`ErrorInfo`](/docs/ai-transport/api/errors#errorinfo) object.
-
-## Example
-
-<Code>
-```javascript
-import { after } from 'next/server';
-import { streamText, convertToModelMessages } from 'ai';
-import { anthropic } from '@ai-sdk/anthropic';
-import Ably from 'ably';
-import { createServerTransport } from '@ably/ai-transport/vercel';
-
-const ably = new Ably.Realtime({ key: process.env.ABLY_API_KEY });
-
-export async function POST(req) {
-  const { messages, id, turnId, clientId, parent, forkOf } = await req.json();
-  const channel = ably.channels.get(id);
-
-  const transport = createServerTransport({
-    channel,
-    onError(error) {
-      console.error('Transport error:', error);
-    },
-  });
-
-  const turn = transport.newTurn({
-    turnId,
-    clientId,
-    parent,
-    forkOf,
-    signal: req.signal,
-    onCancel: async (request) => {
-      const owner = request.turnOwners.get(request.filter.turnId);
-      return owner === request.message.clientId;
-    },
-  });
-
-  await turn.start();
-
-  if (messages.length > 0) {
-    await turn.addMessages(messages.map((m) => ({ kind: 'message', ...m })), { clientId });
-  }
-
-  const result = streamText({
-    model: anthropic('claude-sonnet-4-20250514'),
-    messages: await convertToModelMessages(messages),
-    abortSignal: turn.abortSignal,
-  });
-
-  after(async () => {
-    try {
-      const { reason } = await turn.streamResponse(result.toUIMessageStream());
-      await turn.end(reason);
-    } catch {
-      await turn.end('error');
-    } finally {
-      transport.close();
-    }
-  });
-
-  return new Response(null, { status: 200 });
-}
-```
-</Code>
diff --git a/src/pages/docs/ai-transport/api/javascript/vercel.mdx b/src/pages/docs/ai-transport/api/javascript/vercel.mdx
deleted file mode 100644
index 92ce2ba96b..0000000000
--- a/src/pages/docs/ai-transport/api/javascript/vercel.mdx
+++ /dev/null
@@ -1,245 +0,0 @@
----
-title: "Vercel AI SDK integration"
-meta_description: "API reference for the AI Transport Vercel AI SDK integration. UIMessageCodec, ChatTransport, and pre-bound transport factories."
-meta_keywords: "Vercel AI SDK, AI Transport, UIMessageCodec, ChatTransport, createChatTransport, Ably"
-redirect_from:
-  - /docs/ai-transport/api-reference/vercel
----
-
-The Vercel integration provides a pre-built codec and three pre-bound factories for the Vercel AI SDK. It maps Vercel's `UIMessageChunk` events to `UIMessage` objects, so you can use AI Transport with `useChat` without writing a custom codec.
-
-<Code>
-```javascript
-import {
-  UIMessageCodec,
-  createClientTransport,
-  createServerTransport,
-  createChatTransport,
-} from '@ably/ai-transport/vercel';
-```
-</Code>
-
-React-side hooks (`useChatTransport`, `useMessageSync`, `ChatTransportProvider`) live on the [React hooks reference](/docs/ai-transport/api/react/providers).
-
-## UIMessageCodec <a id="ui-message-codec"/>
-
-A pre-built `Codec<UIMessageChunk, UIMessage>` for the Vercel AI SDK. It handles encoding and decoding of Vercel's message types over Ably channels.
-
-You do not need to import `UIMessageCodec` directly if you use the Vercel-pre-bound transport factories or the React hooks; they bind the codec automatically.
-
-<Code>
-```javascript
-import { UIMessageCodec } from '@ably/ai-transport/vercel';
-```
-</Code>
-
-## Create a Vercel client transport <a id="create-client-transport"/>
-
-<MethodSignature>{`function createClientTransport(options: VercelClientTransportOptions): ClientTransport<UIMessageChunk, UIMessage>`}</MethodSignature>
-
-Pre-bound version of the core `createClientTransport` with `codec: UIMessageCodec` already supplied and `api` defaulted to `/api/chat`.
-
-<Code>
-```javascript
-import * as Ably from 'ably';
-import { createClientTransport } from '@ably/ai-transport/vercel';
-
-const ably = new Ably.Realtime({ authUrl: '/auth' });
-const channel = ably.channels.get('conversation-42');
-
-const transport = createClientTransport({ channel });
-```
-</Code>
-
-### Parameters <a id="create-client-transport-params"/>
-
-<Table id='CreateVercelClientTransportParameters'>
-
-| Parameter | Required | Description | Type |
-| --- | --- | --- | --- |
-| options | Required | Vercel client transport configuration. | <Table id='VercelClientTransportOptions'/> |
-
-</Table>
-
-<Table id='VercelClientTransportOptions' hidden>
-
-| Property | Description | Type |
-| --- | --- | --- |
-| channel | The Ably channel to receive responses on and publish cancel signals to. | `Ably.RealtimeChannel` |
-| api | Server endpoint URL for the HTTP POST that triggers a new turn. Defaults to `/api/chat`. | String or Undefined |
-| clientId | The client's identity. Sent to the server in the POST body. | String or Undefined |
-| headers | Headers for the HTTP POST. Function form for dynamic values. | `Record<string, string>` or `() => Record<string, string>` or Undefined |
-| body | Additional body fields merged into the HTTP POST. Function form for dynamic values. | `Record<string, unknown>` or `() => Record<string, unknown>` or Undefined |
-| credentials | Fetch credentials mode for the HTTP POST. | `RequestCredentials` or Undefined |
-| fetch | Custom fetch implementation. Defaults to `globalThis.fetch`. | `typeof fetch` or Undefined |
-| messages | Initial messages to seed the conversation tree with. | `UIMessage[]` or Undefined |
-| logger | Logger instance for diagnostic output. | `Logger` or Undefined |
-
-</Table>
-
-### Returns <a id="create-client-transport-returns"/>
-
-`ClientTransport<UIMessageChunk, UIMessage>`
-
-A `ClientTransport` typed for Vercel's `UIMessage` content. See [`ClientTransport`](/docs/ai-transport/api/javascript/client-transport) for the full surface.
-
-## Create a Vercel server transport <a id="create-server-transport"/>
-
-<MethodSignature>{`function createServerTransport(options: VercelServerTransportOptions): ServerTransport<UIMessageChunk, UIMessage>`}</MethodSignature>
-
-Pre-bound version of the core `createServerTransport` with `codec: UIMessageCodec` already supplied.
-
-<Code>
-```javascript
-import Ably from 'ably';
-import { createServerTransport } from '@ably/ai-transport/vercel';
-
-const ably = new Ably.Realtime({ key: process.env.ABLY_API_KEY });
-const channel = ably.channels.get('conversation-42');
-
-const transport = createServerTransport({ channel });
-```
-</Code>
-
-### Parameters <a id="create-server-transport-params"/>
-
-<Table id='CreateVercelServerTransportParameters'>
-
-| Parameter | Required | Description | Type |
-| --- | --- | --- | --- |
-| options | Required | Vercel server transport configuration. | <Table id='VercelServerTransportOptions'/> |
-
-</Table>
-
-<Table id='VercelServerTransportOptions' hidden>
-
-| Property | Description | Type |
-| --- | --- | --- |
-| channel | The Ably channel to publish to. Must match the client's channel. | `Ably.RealtimeChannel` |
-| logger | Logger instance for diagnostic output. | `Logger` or Undefined |
-| onError | Called with non-fatal transport-level errors. | `(error: Ably.ErrorInfo) => void` or Undefined |
-
-</Table>
-
-### Returns <a id="create-server-transport-returns"/>
-
-`ServerTransport<UIMessageChunk, UIMessage>`
-
-A `ServerTransport` typed for Vercel's `UIMessage` content. See [`ServerTransport`](/docs/ai-transport/api/javascript/server-transport) for the full surface.
-
-## Create a chat transport <a id="create-chat-transport"/>
-
-<MethodSignature>{`function createChatTransport(transport: ClientTransport<UIMessageChunk, UIMessage>, chatOptions?: ChatTransportOptions): ChatTransport`}</MethodSignature>
-
-Create a `ChatTransport` adapter around an existing `ClientTransport`. The `ChatTransport` is the object you pass to Vercel's `useChat` as `transport`. In most cases you will use the [`ChatTransportProvider`](/docs/ai-transport/api/react/providers) and read the adapter via `useChatTransport` rather than calling this factory directly.
-
-<Code>
-```javascript
-import { createClientTransport, createChatTransport } from '@ably/ai-transport/vercel';
-
-const clientTransport = createClientTransport({ channel });
-const chatTransport = createChatTransport(clientTransport);
-```
-</Code>
-
-### Parameters <a id="create-chat-transport-params"/>
-
-<Table id='CreateChatTransportParameters'>
-
-| Parameter | Required | Description | Type |
-| --- | --- | --- | --- |
-| transport | Required | The underlying client transport. | `ClientTransport<UIMessageChunk, UIMessage>` |
-| chatOptions | Optional | Options customising the chat-transport behaviour. | <Table id='ChatTransportOptions'/> |
-
-</Table>
-
-<Table id='ChatTransportOptions' hidden>
-
-| Property | Description | Type |
-| --- | --- | --- |
-| prepareSendMessagesRequest | Hook to customise the HTTP POST body and headers before each send. Called with the conversation context (see <Table id='SendMessagesRequestContext'/>); returns the body and headers to use. Default sends all previous messages as `history`. | `(context: SendMessagesRequestContext) => { body?: Record<string, unknown>; headers?: Record<string, string> }` or Undefined |
-
-</Table>
-
-<Table id='SendMessagesRequestContext' hidden>
-
-| Property | Description | Type |
-| --- | --- | --- |
-| chatId | Chat session ID (from `useChat`'s `id`). | String or Undefined |
-| trigger | What triggered the request: `'submit-message'` for new messages, `'regenerate-message'` for regeneration. | `'submit-message'` or `'regenerate-message'` |
-| messageId | The message ID for edit or regeneration. For regeneration, the assistant message to regenerate. For edits (`submit-message` with `messageId`), the user message being replaced. Undefined when submitting a new message. | String or Undefined |
-| history | Previous messages in the conversation (context for the LLM). | `UIMessage[]` |
-| messages | The new messages being sent. Empty for regeneration. | `UIMessage[]` |
-| forkOf | The msg-id of the message being forked (regenerated or edited). | String or Undefined |
-| parent | The msg-id of the predecessor in the conversation thread. | String or Undefined |
-
-</Table>
-
-### Returns <a id="create-chat-transport-returns"/>
-
-`ChatTransport`
-
-A `ChatTransport` adapter that satisfies Vercel's `useChat({ transport })` parameter shape.
-
-## ChatTransport <a id="ChatTransport"/>
-
-The adapter object Vercel's `useChat` expects as `transport`. Has two methods, both invoked by `useChat` internally; you typically pass the adapter and never call these directly.
-
-### Send messages <a id="ChatTransport-sendMessages"/>
-
-<MethodSignature>{`sendMessages(options: SendMessagesOptions): Promise<ReadableStream<UIMessageChunk>>`}</MethodSignature>
-
-Send messages and return a streaming response of `UIMessageChunk` events. Called by `useChat` when the user submits a new message or requests a regeneration.
-
-### Reconnect to a stream <a id="ChatTransport-reconnectToStream"/>
-
-<MethodSignature>{`reconnectToStream(options: { chatId: string }): Promise<ReadableStream<UIMessageChunk> | null>`}</MethodSignature>
-
-Reconnect to an existing streaming response. Returns `null` if no active stream exists for the specified chat session.
-
-### Close the chat transport <a id="ChatTransport-close"/>
-
-<MethodSignature>{`close(options?: CloseOptions): Promise<void>`}</MethodSignature>
-
-Close the underlying [`ClientTransport`](/docs/ai-transport/api/javascript/client-transport), releasing all resources. Delegates to `ClientTransport.close()`; pass `{ cancel }` to publish a cancel before tearing down. When the `ChatTransportProvider` owns the lifecycle, it calls this automatically on unmount.
-
-### Streaming flag <a id="ChatTransport-streaming"/>
-
-<MethodSignature>streaming: boolean</MethodSignature>
-
-Read-only flag indicating whether an own-turn stream is currently being consumed by `useChat`. Used internally by [`useMessageSync`](/docs/ai-transport/api/react/use-message-sync) to gate `setMessages` calls during active streams.
-
-### Subscribe to streaming-state changes <a id="ChatTransport-onStreamingChange"/>
-
-<MethodSignature>{`onStreamingChange(callback: (streaming: boolean) => void): () => void`}</MethodSignature>
-
-Subscribe to transitions between streaming and idle. The callback fires with `true` when an own-turn stream starts and `false` when it ends. Returns an unsubscribe function. Used by `useMessageSync` to coordinate message-state writes with the streaming gate.
-
-## Example
-
-<Code>
-```javascript
-import * as Ably from 'ably';
-import { createClientTransport, createChatTransport } from '@ably/ai-transport/vercel';
-import { useChat } from '@ai-sdk/react';
-
-const ably = new Ably.Realtime({ authUrl: '/auth' });
-const channel = ably.channels.get('conversation-42');
-
-const clientTransport = createClientTransport({ channel });
-const chatTransport = createChatTransport(clientTransport, {
-  prepareSendMessagesRequest({ chatId, trigger, history, messages, forkOf, parent }) {
-    return {
-      body: { chatId, trigger, history, messages, forkOf, parent, locale: 'en-GB' },
-      headers: { 'x-tenant-id': tenantId },
-    };
-  },
-});
-
-// In a React component:
-const { messages, sendMessage, stop } = useChat({
-  id: 'conversation-42',
-  transport: chatTransport,
-});
-```
-</Code>
diff --git a/src/pages/docs/ai-transport/api/javascript/vercel/chat-transport.mdx b/src/pages/docs/ai-transport/api/javascript/vercel/chat-transport.mdx
new file mode 100644
index 0000000000..4e621b7f72
--- /dev/null
+++ b/src/pages/docs/ai-transport/api/javascript/vercel/chat-transport.mdx
@@ -0,0 +1,230 @@
+---
+title: "ChatTransport"
+meta_description: "API reference for the AI Transport Vercel ChatTransport adapter and the Vercel-bound createClientSession and createAgentSession factories."
+meta_keywords: "Vercel AI SDK, AI Transport, ChatTransport, createChatTransport, createClientSession, createAgentSession, UIMessageCodec, Ably"
+redirect_from:
+  - /docs/ai-transport/api-reference/vercel
+  - /docs/ai-transport/api/javascript/vercel
+---
+
+The Vercel entry point pre-binds the [`UIMessageCodec`](/docs/ai-transport/api/javascript/vercel/codec) and exposes a `ChatTransport` adapter that satisfies the contract Vercel AI SDK's `useChat` hook expects. Use these factories whenever you build a chat UI on top of `useChat` so you do not have to wire the codec yourself.
+
+<Code>
+```javascript
+import * as Ably from 'ably';
+import { createClientSession, createChatTransport } from '@ably/ai-transport/vercel';
+
+const ably = new Ably.Realtime({ authUrl: '/api/auth/token' });
+
+const session = createClientSession({
+  client: ably,
+  channelName: 'conversation-42',
+});
+
+await session.connect();
+
+const chatTransport = createChatTransport(session);
+```
+</Code>
+
+React-side wiring (`ChatTransportProvider`, `useChatTransport`, `useMessageSync`) lives at [`@ably/ai-transport/vercel/react`](/docs/ai-transport/api/react/vercel/use-chat-transport).
+
+## Create a Vercel client session <a id="create-client-session"/>
+
+<MethodSignature>{`function createClientSession(options: VercelClientSessionOptions): ClientSession<VercelInput, VercelOutput, VercelProjection, UIMessage>`}</MethodSignature>
+
+A pre-bound version of the core [`createClientSession`](/docs/ai-transport/api/javascript/core/client-session#constructor) with `codec: UIMessageCodec` already supplied. The `api` default is set on [`createChatTransport`](#create-chat-transport), not here.
+
+<Code>
+```javascript
+import * as Ably from 'ably';
+import { createClientSession } from '@ably/ai-transport/vercel';
+
+const ably = new Ably.Realtime({ authUrl: '/api/auth/token' });
+
+const session = createClientSession({
+  client: ably,
+  channelName: 'conversation-42',
+  clientId: 'user-abc',
+});
+```
+</Code>
+
+### Parameters <a id="create-client-session-params"/>
+
+<Table id='VercelClientSessionOptions'>
+
+| Parameter | Required | Description | Type |
+| --- | --- | --- | --- |
+| client | required | The Ably Realtime client. The caller owns its lifecycle. | `Ably.Realtime` |
+| channelName | required | The channel to subscribe to and publish cancel signals on. | String |
+| clientId | optional | The client's identity, used as the Ably publisher `clientId` on everything this session publishes. | String |
+| messages | optional | Initial messages to seed the conversation tree with. | `UIMessage[]` |
+| logger | optional | Logger instance for diagnostic output. | `Logger` |
+
+</Table>
+
+### Returns <a id="create-client-session-returns"/>
+
+`ClientSession<VercelInput, VercelOutput, VercelProjection, UIMessage>`. A client session whose codec is pre-bound to `UIMessageCodec`.
+
+## Create a Vercel agent session <a id="create-agent-session"/>
+
+<MethodSignature>{`function createAgentSession(options: VercelAgentSessionOptions): AgentSession<VercelOutput, VercelProjection, UIMessage>`}</MethodSignature>
+
+A pre-bound version of the core [`createAgentSession`](/docs/ai-transport/api/javascript/core/agent-session#constructor) with `codec: UIMessageCodec` already supplied. Construct one inside your HTTP handler when the request arrives.
+
+<Code>
+```javascript
+import * as Ably from 'ably';
+import { Invocation } from '@ably/ai-transport';
+import { createAgentSession } from '@ably/ai-transport/vercel';
+
+const ably = new Ably.Realtime({ key: process.env.ABLY_API_KEY });
+
+const invocation = Invocation.fromJSON(await req.json());
+
+const session = createAgentSession({
+  client: ably,
+  channelName: invocation.sessionName,
+});
+```
+</Code>
+
+### Parameters <a id="create-agent-session-params"/>
+
+<Table id='VercelAgentSessionOptions'>
+
+| Parameter | Required | Description | Type |
+| --- | --- | --- | --- |
+| client | required | The Ably Realtime client. The caller owns its lifecycle. | `Ably.Realtime` |
+| channelName | required | The channel to publish to. | String |
+| logger | optional | Logger instance for diagnostic output. | `Logger` |
+| onError | optional | Called with non-fatal session-level errors not scoped to any run. | `(error: ErrorInfo) => void` |
+| inputEventLookupTimeoutMs | optional | How long `Run.start()` waits for the input event to arrive. Defaults to 30000. | Number |
+| inputEventBufferLimit | optional | Max distinct input events that may be buffered while waiting for `Run.start()` to register a lookup listener. Defaults to 200. | Number |
+| rewindWindow | optional | Channel rewind applied when the agent attaches. Passed verbatim to Ably's `params.rewind`. Defaults to `"2m"`. | String |
+
+</Table>
+
+### Returns <a id="create-agent-session-returns"/>
+
+`AgentSession<VercelOutput, VercelProjection, UIMessage>`. An agent session whose codec is pre-bound to `UIMessageCodec`.
+
+## Create a chat transport <a id="create-chat-transport"/>
+
+<MethodSignature>{`function createChatTransport(session: ClientSession<VercelInput, VercelOutput, VercelProjection, UIMessage>, chatOptions?: ChatTransportOptions): ChatTransport`}</MethodSignature>
+
+Wrap a `ClientSession` in a `ChatTransport` adapter that satisfies Vercel AI SDK's `useChat` `transport` option. The adapter maps `useChat`'s `sendMessages` and `reconnectToStream` contract onto the session's `view.send`, `view.regenerate`, and tool-resolution paths.
+
+<Code>
+```javascript
+import { useChat } from '@ai-sdk/react';
+import { createChatTransport } from '@ably/ai-transport/vercel';
+
+const chatTransport = createChatTransport(session, {
+  prepareSendMessagesRequest: ({ history }) => ({
+    body: { history },
+  }),
+});
+
+const chat = useChat({ transport: chatTransport });
+```
+</Code>
+
+### Parameters <a id="create-chat-transport-params"/>
+
+<Table id='CreateChatTransportParameters'>
+
+| Parameter | Required | Description | Type |
+| --- | --- | --- | --- |
+| session | required | The core client session to wrap. | `ClientSession<VercelInput, VercelOutput, VercelProjection, UIMessage>` |
+| chatOptions | optional | Hooks for customising request construction. | <Table id='ChatTransportOptions'/> |
+
+</Table>
+
+<Table id='ChatTransportOptions' hidden>
+
+| Property | Description | Type |
+| --- | --- | --- |
+| api | Endpoint the transport POSTs the invocation pointer to, to wake the agent. Defaults to `/api/chat`. | String |
+| credentials | Fetch credentials mode for the invocation POST (for example `'include'`). | `RequestCredentials` |
+| fetch | Custom fetch implementation for the invocation POST. Defaults to `globalThis.fetch`. | `typeof globalThis.fetch` |
+| prepareSendMessagesRequest | Customise the POST body and headers before sending. Called by `sendMessages` with the conversation <Table id='SendMessagesRequestContext'/>. The returned `body` is merged into the POST body (the run's invocation identifiers always take precedence) and `headers` are added to the request. | `(context: SendMessagesRequestContext) => { body?, headers? }` |
+
+</Table>
+
+<Table id='SendMessagesRequestContext' hidden>
+
+| Property | Description | Type |
+| --- | --- | --- |
+| chatId | Chat session ID (from `useChat`'s id). Optional; `undefined` when `useChat` is mounted without one. | String or Undefined |
+| trigger | What triggered the request. | `'submit-message'` or `'regenerate-message'` |
+| messageId | The message ID for edit or regeneration requests. | String |
+| history | Previous messages in the conversation (context for the LLM). | `UIMessage[]` |
+| messages | The new messages being sent. Empty for regeneration. | `UIMessage[]` |
+| forkOf | The codec-message-id of the message being forked. | String |
+| parent | The codec-message-id of the predecessor in the conversation thread. | String |
+
+</Table>
+
+### Returns <a id="create-chat-transport-returns"/>
+
+[`ChatTransport`](#chat-transport). The adapter to pass to `useChat`'s `transport` option.
+
+## ChatTransport <a id="chat-transport"/>
+
+The transport adapter returned by [`createChatTransport`](#create-chat-transport). Structurally compatible with the AI SDK's internal `ChatTransport<UIMessage>` interface, extended with `close()`, `streaming`, and `onStreamingChange` for coordinating with [`useMessageSync`](/docs/ai-transport/api/react/vercel/use-message-sync).
+
+### Properties
+
+<Table id='ChatTransportProperties'>
+
+| Property | Description | Type |
+| --- | --- | --- |
+| sendMessages | Send messages and return a `ReadableStream` of `UIMessageChunk` events. | `(options) => Promise<ReadableStream<UIMessageChunk>>` |
+| reconnectToStream | Reconnect to an existing streaming response. Returns `null` because observer mode handles in-progress streams automatically. | `(options) => Promise<ReadableStream<UIMessageChunk> \| null>` |
+| close | Close the underlying transport, releasing all resources. | `() => Promise<void>` |
+| streaming | Whether an own-run stream is currently being consumed by `useChat`. | Boolean |
+| onStreamingChange | Subscribe to streaming state changes. Used by `useMessageSync` to gate `setMessages` calls during active streams. | `(callback: (streaming: boolean) => void) => () => void` |
+
+</Table>
+
+## Example <a id="example"/>
+
+End-to-end client-side wiring: open a session, wrap it in a chat transport, and hand it to `useChat`.
+
+<Code>
+```javascript
+import * as Ably from 'ably';
+import { useChat } from '@ai-sdk/react';
+import { createClientSession, createChatTransport } from '@ably/ai-transport/vercel';
+
+const ably = new Ably.Realtime({ authUrl: '/api/auth/token' });
+
+const session = createClientSession({
+  client: ably,
+  channelName: 'conversation-42',
+});
+
+await session.connect();
+
+const chatTransport = createChatTransport(session, {
+  prepareSendMessagesRequest: ({ history, messages }) => ({
+    body: { history, messages },
+  }),
+});
+
+function Chat() {
+  const { messages, sendMessage } = useChat({ transport: chatTransport });
+  return (
+    <>
+      {messages.map((m) => (
+        <Message key={m.id} message={m} />
+      ))}
+      <Composer onSubmit={(text) => sendMessage({ role: 'user', parts: [{ type: 'text', text }] })} />
+    </>
+  );
+}
+```
+</Code>
diff --git a/src/pages/docs/ai-transport/api/javascript/vercel/codec.mdx b/src/pages/docs/ai-transport/api/javascript/vercel/codec.mdx
new file mode 100644
index 0000000000..59fbca5cdb
--- /dev/null
+++ b/src/pages/docs/ai-transport/api/javascript/vercel/codec.mdx
@@ -0,0 +1,92 @@
+---
+title: "UIMessageCodec"
+meta_description: "API reference for UIMessageCodec, the pre-built AI Transport codec for the Vercel AI SDK."
+meta_keywords: "Vercel AI SDK, AI Transport, UIMessageCodec, VercelInput, VercelOutput, VercelProjection, codec, Ably"
+---
+
+`UIMessageCodec` is the pre-built codec for the Vercel AI SDK. It implements [`Codec<VercelInput, VercelOutput, VercelProjection, UIMessage>`](/docs/ai-transport/api/javascript/core/codec) so a session can encode `UIMessageChunk` events out and decode them back into `UIMessage` objects without a custom implementation.
+
+You rarely import `UIMessageCodec` directly. The Vercel-pre-bound [`createClientSession`](/docs/ai-transport/api/javascript/vercel/chat-transport#create-client-session) and [`createAgentSession`](/docs/ai-transport/api/javascript/vercel/chat-transport#create-agent-session) already supply it. Import it explicitly when you build a codec wrapper, run the encoder or decoder outside of a session, or compose `UIMessageCodec` into a different codec.
+
+<Code>
+```javascript
+import { UIMessageCodec } from '@ably/ai-transport/vercel';
+
+const decoder = UIMessageCodec.createDecoder();
+const projection = UIMessageCodec.init();
+```
+</Code>
+
+## Properties <a id="properties"/>
+
+`UIMessageCodec` is a value, not a type. It satisfies the full [`Codec`](/docs/ai-transport/api/javascript/core/codec) interface for the Vercel `TInput`, `TOutput`, `TProjection`, and `TMessage` parameters listed below.
+
+<Table id='UIMessageCodecProperties'>
+
+| Property | Description | Type |
+| --- | --- | --- |
+| init | Build an empty `VercelProjection`. | `() => VercelProjection` |
+| fold | Fold a `VercelInput` or `VercelOutput` into the projection. | `(state, event, meta) => VercelProjection` |
+| createEncoder | Create a Vercel encoder bound to the supplied channel writer. | `(channel, options?) => Encoder<VercelInput, VercelOutput>` |
+| createDecoder | Create a Vercel decoder for the channel. | `() => Decoder<VercelInput, VercelOutput>` |
+| getMessages | Extract `{ codecMessageId, message }` pairs from a `VercelProjection`. The domain `UIMessage.id` is preserved verbatim from the source stream; the SDK keys correlation off the paired `codecMessageId`. | `(projection) => CodecMessage<UIMessage>[]` |
+| createUserMessage | Wrap a `UIMessage` as the `UserMessage` input variant. | `(message: UIMessage) => VercelInput` |
+| createRegenerate | Build a `Regenerate` input targeting an assistant `UIMessage`. | `(target, parent) => VercelInput` |
+| createToolResult | Build a `ToolResult` input addressed at the assistant codec-message that contains the tool call. | `(codecMessageId, { toolCallId, output }) => VercelInput` |
+| createToolResultError | Build a `ToolResultError` input. | `(codecMessageId, { toolCallId, message }) => VercelInput` |
+| createToolApprovalResponse | Build a `ToolApprovalResponse` input. | `(codecMessageId, { toolCallId, approved, reason? }) => VercelInput` |
+
+</Table>
+
+## Type parameters <a id="types"/>
+
+<Table id='VercelInput'>
+
+| Property | Description | Type |
+| --- | --- | --- |
+| TInput | Discriminated union of every record-shape a client publishes on the `ai-input` wire. Composed from the SDK's well-known input variants, with the tool variants parameterised by the Vercel domain payload shapes (`VercelToolResultPayload`, `VercelToolResultErrorPayload`, `VercelToolApprovalResponsePayload`). | `UserMessage<UIMessage> \| Regenerate \| ToolResult<VercelToolResultPayload> \| ToolResultError<VercelToolResultErrorPayload> \| ToolApprovalResponse<VercelToolApprovalResponsePayload>` |
+
+</Table>
+
+<Table id='VercelOutput'>
+
+| Property | Description | Type |
+| --- | --- | --- |
+| TOutput | Every record-shape the agent publishes on the `ai-output` wire. The codec passes Vercel's `UIMessageChunk` through unchanged. | `AI.UIMessageChunk` |
+
+</Table>
+
+<Table id='VercelProjection'>
+
+| Property | Description | Type |
+| --- | --- | --- |
+| TProjection | Per-Run projection. Carries the `{ codecMessageId, message }` pair list plus internal stream-tracker state and a high-water-mark serial for idempotency. The SDK does not inspect this shape. Reach for `getMessages` instead. | `{ messages: CodecMessage<UIMessage>[], ... }` |
+
+</Table>
+
+The well-known input variants ([`UserMessage`](/docs/ai-transport/api/javascript/core/codec#user-message), [`Regenerate`](/docs/ai-transport/api/javascript/core/codec#regenerate), [`ToolResult`](/docs/ai-transport/api/javascript/core/codec#tool-result), [`ToolResultError`](/docs/ai-transport/api/javascript/core/codec#tool-result-error), [`ToolApprovalResponse`](/docs/ai-transport/api/javascript/core/codec#tool-approval-response)) are documented on the [`Codec` reference page](/docs/ai-transport/api/javascript/core/codec#input-variants). The Vercel codec layers no extra input variants.
+
+## Example <a id="example"/>
+
+Decode a single Ably message and fold the resulting events into a fresh projection. `ReducerMeta.serial` is required (the reducer uses it as the high-water-mark for idempotency); the `messageId` field is optional and only needed when the codec routes events to an existing message.
+
+<Code>
+```javascript
+import { UIMessageCodec } from '@ably/ai-transport/vercel';
+
+const decoder = UIMessageCodec.createDecoder();
+let projection = UIMessageCodec.init();
+
+channel.subscribe((message) => {
+  if (!message.serial) return; // live channel-subscribe messages always carry one
+  const { inputs, outputs } = decoder.decode(message);
+  for (const input of inputs) {
+    projection = UIMessageCodec.fold(projection, input, { serial: message.serial });
+  }
+  for (const output of outputs) {
+    projection = UIMessageCodec.fold(projection, output, { serial: message.serial });
+  }
+  render(UIMessageCodec.getMessages(projection).map((entry) => entry.message));
+});
+```
+</Code>
diff --git a/src/pages/docs/ai-transport/api/javascript/vercel/run-outcome.mdx b/src/pages/docs/ai-transport/api/javascript/vercel/run-outcome.mdx
new file mode 100644
index 0000000000..9a3c490c9f
--- /dev/null
+++ b/src/pages/docs/ai-transport/api/javascript/vercel/run-outcome.mdx
@@ -0,0 +1,118 @@
+---
+title: "vercelRunOutcome"
+meta_description: "API reference for vercelRunOutcome, the helper that maps a Vercel streamText finishReason and Run.pipe result to a RunEndReason or a 'suspend' sentinel."
+meta_keywords: "AI Transport, vercelRunOutcome, RunEndReason, streamText, finishReason, Vercel AI SDK, Ably"
+---
+
+`vercelRunOutcome` resolves the outcome of a Vercel `streamText` response that was piped through [`Run.pipe`](/docs/ai-transport/api/javascript/core/agent-session#pipe). It returns either a terminal [`RunEndReason`](/docs/ai-transport/api/javascript/core/agent-session#run-end-reason) you pass to [`Run.end`](/docs/ai-transport/api/javascript/core/agent-session#run-end), or the sentinel `'suspend'` telling you to call [`Run.suspend`](/docs/ai-transport/api/javascript/core/agent-session#run-suspend) instead.
+
+It preserves transport-level outcomes (`'cancelled'`, `'error'`) from the pipe result. When the pipe completed naturally, it awaits Vercel's `finishReason` and returns `'suspend'` for `'tool-calls'` (the LLM requested tools the SDK did not auto-execute, so the run should pause for the next client-published tool result), or `'complete'` otherwise.
+
+Use it at the end of every Vercel route handler so the lifecycle event you publish matches what actually happened on the LLM side.
+
+<Code>
+```javascript
+import { streamText } from 'ai';
+import { vercelRunOutcome } from '@ably/ai-transport/vercel';
+
+const result = streamText({ model, messages, tools });
+const pipeResult = await run.pipe(result.toUIMessageStream());
+const outcome = await vercelRunOutcome(pipeResult, result.finishReason);
+
+if (outcome === 'suspend') {
+  await run.suspend();
+} else {
+  await run.end(outcome);
+}
+```
+</Code>
+
+## Resolve the run outcome <a id="vercel-run-outcome"/>
+
+<MethodSignature>{`vercelRunOutcome(pipeResult: StreamResult, finishReason: PromiseLike<FinishReason>): Promise<RunEndReason | 'suspend'>`}</MethodSignature>
+
+The helper applies two rules:
+
+1. If `pipeResult.reason` is `'cancelled'` or `'error'`, return it as-is. The transport already knows the run ended for a non-completion reason.
+2. If `pipeResult.reason` is `'complete'`, await `finishReason` and translate:
+   - `'tool-calls'` returns `'suspend'`. The LLM requested tools the SDK did not auto-execute, so the run should pause for the next client-published tool result.
+   - Any other Vercel finish reason returns `'complete'`.
+   - If `finishReason` rejects, classify the rejection: abort-shaped errors return `'cancelled'`; anything else (for example `NoOutputGeneratedError`) returns `'error'`.
+
+The rejection guard matters: Vercel AI SDK v6 rejects `streamText().finishReason` with the abort signal's reason when the stream is aborted before any step completes, and with `NoOutputGeneratedError` when the model produced nothing at all. Without the guard the rejection would bubble out of the route handler, skip `Run.end`, and leave the run with no `ai-run-end` event on the channel.
+
+### Parameters <a id="vercel-run-outcome-params"/>
+
+<Table id='VercelRunOutcomeParameters'>
+
+| Parameter | Required | Description | Type |
+| --- | --- | --- | --- |
+| pipeResult | required | The result returned by [`Run.pipe`](/docs/ai-transport/api/javascript/core/agent-session#pipe). | <Table id='StreamResult'/> |
+| finishReason | required | The `finishReason` promise from a Vercel `streamText` result. | `PromiseLike<AI.FinishReason>` |
+
+</Table>
+
+<Table id='StreamResult' hidden>
+
+| Property | Description | Type |
+| --- | --- | --- |
+| reason | Why the stream ended. | `'complete' \| 'cancelled' \| 'error'` |
+| error | The original error when `reason` is `'error'`. | `Error` |
+
+</Table>
+
+### Returns <a id="vercel-run-outcome-returns"/>
+
+`Promise<RunEndReason | 'suspend'>`. Either a terminal reason (`'complete'`, `'cancelled'`, `'error'`) to pass to [`Run.end`](/docs/ai-transport/api/javascript/core/agent-session#run-end), or the sentinel `'suspend'` telling the caller to invoke [`Run.suspend`](/docs/ai-transport/api/javascript/core/agent-session#run-suspend) so a continuation Invocation can resume the Run.
+
+## Example <a id="example"/>
+
+A Vercel route handler that runs a tool-capable model, pipes the stream, and either suspends (for tool resolution) or ends the run with the correct reason.
+
+<Code>
+```javascript
+import * as Ably from 'ably';
+import { streamText } from 'ai';
+import { openai } from '@ai-sdk/openai';
+import { Invocation } from '@ably/ai-transport';
+import { createAgentSession, vercelRunOutcome } from '@ably/ai-transport/vercel';
+
+const ably = new Ably.Realtime({ key: process.env.ABLY_API_KEY });
+
+export async function POST(req: Request) {
+  const invocation = Invocation.fromJSON(await req.json());
+
+  const session = createAgentSession({
+    client: ably,
+    channelName: invocation.sessionName,
+  });
+
+  await session.connect();
+  const run = session.createRun(invocation, { signal: req.signal });
+
+  try {
+    await run.start();
+    await run.loadConversation();
+
+    const result = streamText({
+      model: openai('gpt-4'),
+      messages: run.messages,
+      tools: myTools,
+    });
+
+    const pipeResult = await run.pipe(result.toUIMessageStream());
+    const outcome = await vercelRunOutcome(pipeResult, result.finishReason);
+
+    if (outcome === 'suspend') {
+      await run.suspend();
+    } else {
+      await run.end(outcome);
+    }
+  } finally {
+    session.close();
+  }
+
+  return Response.json({ invocationId: run.invocationId });
+}
+```
+</Code>
diff --git a/src/pages/docs/ai-transport/api/react/core/providers.mdx b/src/pages/docs/ai-transport/api/react/core/providers.mdx
new file mode 100644
index 0000000000..9afb5a0483
--- /dev/null
+++ b/src/pages/docs/ai-transport/api/react/core/providers.mdx
@@ -0,0 +1,151 @@
+---
+title: "Providers"
+meta_description: "API reference for the AI Transport React providers: ClientSessionProvider and the createSessionHooks factory."
+meta_keywords: "AI Transport, React, ClientSessionProvider, createSessionHooks, ClientSessionSlot, providers, Ably"
+redirect_from:
+  - /docs/ai-transport/api-reference/providers
+  - /docs/ai-transport/api/react/providers
+---
+
+`ClientSessionProvider` creates a `ClientSession` once on mount, connects it, and exposes it to descendants through React context. The hooks in `@ably/ai-transport/react` read the session via this provider, so wrap every subtree that uses them in one.
+
+Nest multiple providers with distinct `channelName` values to manage more than one session in the same tree. Each provider merges its slot into the parent registry so descendants can address any registered session by `channelName`.
+
+<Code>
+```javascript
+import * as Ably from 'ably';
+import { AblyProvider } from 'ably/react';
+import { ClientSessionProvider } from '@ably/ai-transport/react';
+import { UIMessageCodec } from '@ably/ai-transport/vercel';
+
+const ably = new Ably.Realtime({ authUrl: '/api/auth/token' });
+
+function App() {
+  return (
+    <AblyProvider client={ably}>
+      <ClientSessionProvider channelName="conversation-42" codec={UIMessageCodec}>
+        <Chat />
+      </ClientSessionProvider>
+    </AblyProvider>
+  );
+}
+```
+</Code>
+
+## ClientSessionProvider <a id="client-session-provider"/>
+
+The provider reads the Ably Realtime client from the surrounding `<AblyProvider>` and forwards it, along with the supplied props, to `createClientSession`. The session is created once on first render via `useRef`. `connect()` is invoked from a `useEffect` so the session is subscribed and attached before the first descendant read.
+
+If `createClientSession` throws, the error is stored on the slot alongside an undefined session. `useClientSession` surfaces it as [`sessionError`](/docs/ai-transport/api/react/core/use-client-session#returns) so the component tree does not crash.
+
+### Props <a id="client-session-provider-props"/>
+
+`ClientSessionProviderProps` extends all [`ClientSessionOptions`](/docs/ai-transport/api/javascript/core/client-session#constructor-params) except `client` (which is read from `<AblyProvider>`).
+
+<Table id='ClientSessionProviderProps'>
+
+| Property | Description | Type |
+| --- | --- | --- |
+| channelName | The channel the session subscribes to. Used as the registry key for nested providers. | String |
+| codec | The codec used to encode and decode events and messages. | `Codec<TInput, TOutput, TProjection, TMessage>` |
+| clientId | The client's identity, used as the Ably publisher `clientId` for everything the session publishes. | String |
+| messages | Initial messages to seed the conversation tree with. | `TMessage[]` |
+| logger | Logger instance for diagnostic output. | `Logger` |
+| children | Descendant components that consume the session via hooks. | `ReactNode` |
+
+</Table>
+
+## ClientSessionSlot <a id="client-session-slot"/>
+
+A single entry in the registry holding the session and any error from construction. [`useClientSession`](/docs/ai-transport/api/react/core/use-client-session) returns this shape.
+
+<Table id='ClientSessionSlot'>
+
+| Property | Description | Type |
+| --- | --- | --- |
+| session | The constructed session, or `undefined` if construction failed. | `ClientSession<TInput, TOutput, TProjection, TMessage>` or Undefined |
+| sessionError | Construction error from `createClientSession`, or `undefined` on success. | `Ably.ErrorInfo` or Undefined |
+
+</Table>
+
+## Bake hook types with createSessionHooks <a id="create-session-hooks"/>
+
+<MethodSignature>{`function createSessionHooks<TInput, TOutput, TProjection, TMessage>(): SessionHooks<TInput, TOutput, TProjection, TMessage>`}</MethodSignature>
+
+A factory that captures the codec's four type parameters once and returns a bundle of type-safe hooks plus a narrowed `ClientSessionProvider`. Hook call sites need no type parameters once you have called the factory.
+
+Use this when you have one codec for the whole app and want call sites that look like `const view = useView({ limit: 30 })` without generics. The Vercel React entry point already exports a bundle baked to the Vercel types.
+
+<Code>
+```javascript
+// session.ts: shared module
+import { createSessionHooks } from '@ably/ai-transport/react';
+import type {
+  VercelInput,
+  VercelOutput,
+  VercelProjection,
+} from '@ably/ai-transport/vercel';
+import type { UIMessage } from 'ai';
+
+export const {
+  ClientSessionProvider,
+  useClientSession,
+  useView,
+  useTree,
+  useCreateView,
+  useAblyMessages,
+} = createSessionHooks<VercelInput, VercelOutput, VercelProjection, UIMessage>();
+```
+</Code>
+
+The factory takes four type parameters. Omitting them leaves every hook inferred as `unknown`; pass them explicitly so call sites stay type-safe.
+
+### Returns <a id="create-session-hooks-returns"/>
+
+<Table id='SessionHooks'>
+
+| Property | Description | Type |
+| --- | --- | --- |
+| ClientSessionProvider | `ClientSessionProvider` narrowed to the captured types. No JSX type params needed. | `ComponentType<ClientSessionProviderProps>` |
+| useClientSession | Type-narrowed [`useClientSession`](/docs/ai-transport/api/react/core/use-client-session). | Function |
+| useView | Type-narrowed [`useView`](/docs/ai-transport/api/react/core/use-view). | Function |
+| useTree | Type-narrowed [`useTree`](/docs/ai-transport/api/react/core/use-tree). | Function |
+| useAblyMessages | Type-narrowed [`useAblyMessages`](/docs/ai-transport/api/react/core/use-ably-messages). | Function |
+| useCreateView | Type-narrowed [`useCreateView`](/docs/ai-transport/api/react/core/use-create-view). | Function |
+
+</Table>
+
+## Example <a id="example"/>
+
+Nested providers with distinct channel names and a child component that addresses each session by name.
+
+<Code>
+```javascript
+import * as Ably from 'ably';
+import { AblyProvider } from 'ably/react';
+import { ClientSessionProvider, useClientSession } from '@ably/ai-transport/react';
+import { UIMessageCodec } from '@ably/ai-transport/vercel';
+
+const ably = new Ably.Realtime({ authUrl: '/api/auth/token' });
+
+function App() {
+  return (
+    <AblyProvider client={ably}>
+      <ClientSessionProvider channelName="ai:main" codec={UIMessageCodec}>
+        <ClientSessionProvider channelName="ai:aux" codec={UIMessageCodec}>
+          <Chat />
+        </ClientSessionProvider>
+      </ClientSessionProvider>
+    </AblyProvider>
+  );
+}
+
+function Chat() {
+  const { session: main } = useClientSession({ channelName: 'ai:main' });
+  const { session: aux, sessionError } = useClientSession({ channelName: 'ai:aux' });
+
+  if (sessionError) return <ErrorBanner error={sessionError} />;
+  return <SplitPane mainSession={main} auxSession={aux} />;
+}
+```
+</Code>
diff --git a/src/pages/docs/ai-transport/api/react/core/use-ably-messages.mdx b/src/pages/docs/ai-transport/api/react/core/use-ably-messages.mdx
new file mode 100644
index 0000000000..08bd91a35a
--- /dev/null
+++ b/src/pages/docs/ai-transport/api/react/core/use-ably-messages.mdx
@@ -0,0 +1,82 @@
+---
+title: "useAblyMessages"
+meta_description: "Subscribe to raw Ably InboundMessages on the AI Transport channel from React."
+meta_keywords: "AI Transport, React, useAblyMessages, InboundMessage, raw messages, Ably"
+redirect_from:
+  - /docs/ai-transport/api-reference/use-ably-messages
+  - /docs/ai-transport/api/react/use-ably-messages
+---
+
+`useAblyMessages` returns the accumulated raw `Ably.InboundMessage` objects that the session has observed on its channel, in arrival order. It subscribes to the session's tree `'ably-message'` event and appends every incoming message to internal state.
+
+Use this hook for debugging, inspection panels, or wire-level visualisations that need to see the raw Ably payload rather than the decoded codec events.
+
+<Code>
+```javascript
+import { useAblyMessages } from '@ably/ai-transport/react';
+
+function WireInspector() {
+  const messages = useAblyMessages();
+
+  return (
+    <pre>
+      {messages.map((m) => JSON.stringify(m, null, 2)).join('\n')}
+    </pre>
+  );
+}
+```
+</Code>
+
+This hook must be used within a [`ClientSessionProvider`](/docs/ai-transport/api/react/core/providers#client-session-provider) unless `session` is supplied explicitly.
+
+## Parameters <a id="parameters"/>
+
+<Table id='UseAblyMessagesParameters'>
+
+| Parameter | Required | Description | Type |
+| --- | --- | --- | --- |
+| session | optional | A client session to subscribe to. Defaults to the nearest provider. | `ClientSession<TInput, TOutput, TProjection, TMessage>` |
+| skip | optional | When `true`, skip all subscriptions and return an empty array. | Boolean |
+
+</Table>
+
+## Returns <a id="returns"/>
+
+<MethodSignature>{`Ably.InboundMessage[]`}</MethodSignature>
+
+The accumulated raw Ably messages in chronological order. Resets to an empty array when the resolved session changes.
+
+Each `InboundMessage` carries the wire fields you would see from `channel.subscribe`: `name`, `data`, `serial`, `clientId`, `extras`, `timestamp`, and so on. The full type lives in the [Ably SDK reference](/docs/pub-sub/api/javascript/realtime/messages#message).
+
+## Example <a id="example"/>
+
+A toggleable debug drawer that streams every raw message arriving on the channel alongside the rendered conversation.
+
+<Code>
+```javascript
+import { useState } from 'react';
+import { useAblyMessages, useView } from '@ably/ai-transport/react';
+
+function ChatWithDebug() {
+  const [showDebug, setShowDebug] = useState(false);
+  const { messages } = useView({ limit: 30 });
+  const rawMessages = useAblyMessages({ skip: !showDebug });
+
+  return (
+    <>
+      <ConversationView messages={messages} />
+      <button onClick={() => setShowDebug((s) => !s)}>
+        {showDebug ? 'Hide' : 'Show'} wire log
+      </button>
+      {showDebug && (
+        <aside>
+          {rawMessages.map((m, i) => (
+            <pre key={i}>{JSON.stringify(m, null, 2)}</pre>
+          ))}
+        </aside>
+      )}
+    </>
+  );
+}
+```
+</Code>
diff --git a/src/pages/docs/ai-transport/api/react/core/use-client-session.mdx b/src/pages/docs/ai-transport/api/react/core/use-client-session.mdx
new file mode 100644
index 0000000000..d5838c7061
--- /dev/null
+++ b/src/pages/docs/ai-transport/api/react/core/use-client-session.mdx
@@ -0,0 +1,87 @@
+---
+title: "useClientSession"
+meta_description: "Read a ClientSession from the nearest ClientSessionProvider in the AI Transport React integration."
+meta_keywords: "AI Transport, React, useClientSession, ClientSessionHandle, ClientSession, Ably"
+redirect_from:
+  - /docs/ai-transport/api-reference/use-client-transport
+  - /docs/ai-transport/api/react/use-client-transport
+---
+
+`useClientSession` reads a `ClientSession` from the nearest [`ClientSessionProvider`](/docs/ai-transport/api/react/core/providers#client-session-provider). It is a thin context reader that never throws during render. If no matching provider exists or the session failed to construct, the hook returns a stub session and a populated `sessionError` so the component can render an error state without an error boundary.
+
+<Code>
+```javascript
+import { useClientSession } from '@ably/ai-transport/react';
+
+function Chat() {
+  const { session, sessionError } = useClientSession();
+
+  if (sessionError) return <ErrorBanner error={sessionError} />;
+  return <Conversation session={session} />;
+}
+```
+</Code>
+
+This hook must be used within a [`ClientSessionProvider`](/docs/ai-transport/api/react/core/providers#client-session-provider). When the provider is absent the hook still returns a handle, but `session` is a stub that throws on every access and `sessionError` is set.
+
+## Parameters <a id="parameters"/>
+
+<Table id='UseClientSessionParameters'>
+
+| Parameter | Required | Description | Type |
+| --- | --- | --- | --- |
+| channelName | optional | Look up a specific provider by channel name. Omit to use the innermost provider in the tree. | String |
+| skip | optional | When `true`, skip context lookup and return the stub session immediately. Useful when an auth condition is not yet resolved. | Boolean |
+| onError | optional | Called whenever the resolved session emits an error event. The subscription is established when the session resolves and removed on unmount. | `(error: Ably.ErrorInfo) => void` |
+
+</Table>
+
+## Returns <a id="returns"/>
+
+<Table id='ClientSessionHandle'>
+
+| Property | Description | Type |
+| --- | --- | --- |
+| session | The resolved session. A throwing stub when `skip` is `true`, when no matching provider was found, or when session construction failed. | `ClientSession<TInput, TOutput, TProjection, TMessage>` |
+| sessionError | Set when no matching `ClientSessionProvider` was found or when session construction failed, and `skip` is `false`. `undefined` when the session resolved successfully. | `Ably.ErrorInfo` or Undefined |
+
+</Table>
+
+## Read the session <a id="session"/>
+
+<MethodSignature>{`session: ClientSession<TInput, TOutput, TProjection, TMessage>`}</MethodSignature>
+
+The resolved [`ClientSession`](/docs/ai-transport/api/javascript/core/client-session). All session methods are available, including `view`, `tree`, `connect`, `cancel`, `createView`, `on`, and `close`. The provider already invokes `connect()` once per mount, so application code rarely calls it directly. The hooks `useView`, `useTree`, `useCreateView`, and `useAblyMessages` resolve their session through the same provider, so reach for them whenever you want reactive state rather than the raw session.
+
+## Read the session error <a id="session-error"/>
+
+<MethodSignature>{`sessionError: Ably.ErrorInfo | undefined`}</MethodSignature>
+
+The construction or lookup error, if any. `undefined` when the session is usable. Check `sessionError` before touching `session` to avoid the stub throw.
+
+The post-construction error path is separate. Subscribe to those with the `onError` parameter (or `session.on('error', ...)`) rather than reading them from `sessionError`.
+
+## Example <a id="example"/>
+
+A chat component that subscribes to session errors and renders a fallback while the provider is being looked up.
+
+<Code>
+```javascript
+import { useState } from 'react';
+import { useClientSession } from '@ably/ai-transport/react';
+
+function Chat() {
+  const [runtimeError, setRuntimeError] = useState<Ably.ErrorInfo | undefined>();
+
+  const { session, sessionError } = useClientSession({
+    channelName: 'ai:demo',
+    onError: setRuntimeError,
+  });
+
+  if (sessionError) return <ErrorBanner error={sessionError} />;
+  if (runtimeError) return <ErrorBanner error={runtimeError} />;
+
+  return <Conversation session={session} />;
+}
+```
+</Code>
diff --git a/src/pages/docs/ai-transport/api/react/core/use-create-view.mdx b/src/pages/docs/ai-transport/api/react/core/use-create-view.mdx
new file mode 100644
index 0000000000..6efa1b1ebc
--- /dev/null
+++ b/src/pages/docs/ai-transport/api/react/core/use-create-view.mdx
@@ -0,0 +1,107 @@
+---
+title: "useCreateView"
+meta_description: "Create an independent View over the AI Transport conversation tree from React, with its own branch selections and pagination."
+meta_keywords: "AI Transport, React, useCreateView, ViewHandle, split-pane, comparison, Ably"
+redirect_from:
+  - /docs/ai-transport/api-reference/use-create-view
+  - /docs/ai-transport/api/react/use-create-view
+---
+
+`useCreateView` creates a new [`View`](/docs/ai-transport/api/javascript/core/client-session) over the same conversation tree as the session's default view, then subscribes to it the same way [`useView`](/docs/ai-transport/api/react/core/use-view) does. Each created view has its own branch selections and pagination state. The view is closed automatically on unmount or when the session reference changes.
+
+Use this hook when you need two independent renderings of the same conversation, for example, a split-pane diff between two regenerate siblings, or a secondary panel that pages older history without affecting the main scroll position.
+
+<Code>
+```javascript
+import { useCreateView } from '@ably/ai-transport/react';
+
+function Compare() {
+  const left = useCreateView({ limit: 30 });
+  const right = useCreateView({ limit: 30 });
+
+  return (
+    <SplitPane
+      left={<MessageList messages={left.messages} />}
+      right={<MessageList messages={right.messages} />}
+    />
+  );
+}
+```
+</Code>
+
+This hook must be used within a [`ClientSessionProvider`](/docs/ai-transport/api/react/core/providers#client-session-provider) unless `session` is supplied explicitly.
+
+## Parameters <a id="parameters"/>
+
+<Table id='UseCreateViewParameters'>
+
+| Parameter | Required | Description | Type |
+| --- | --- | --- | --- |
+| session | optional | A client session to create a view from. Defaults to the nearest provider. Pass `null` to defer creation. | `ClientSession<TInput, TOutput, TProjection, TMessage>` |
+| limit | optional | Maximum number of older Runs to reveal per page. When provided, auto-loads the first page on mount. | Number |
+| skip | optional | When `true`, skip view creation and return an empty handle immediately. | Boolean |
+
+</Table>
+
+## Returns <a id="returns"/>
+
+Returns the same [`ViewHandle`](/docs/ai-transport/api/react/core/use-view#returns) shape as [`useView`](/docs/ai-transport/api/react/core/use-view), backed by a freshly created view.
+
+<Table id='ViewHandle'>
+
+| Property | Description | Type |
+| --- | --- | --- |
+| messages | The visible messages along the selected branch, each paired with its `codecMessageId`. Read the domain object from each entry's `message` field. | `CodecMessage<TMessage>[]` |
+| hasOlder | Whether there are older Runs that can be revealed. | Boolean |
+| loading | Whether a page load is currently in progress. | Boolean |
+| loadError | Set when the most recent `loadOlder` call failed. | `Ably.ErrorInfo` or Undefined |
+| loadOlder | Reveal older Runs. | `() => Promise<void>` |
+| runOf | Look up the `RunInfo` for the Run that owns a `codecMessageId`. | `(codecMessageId) => RunInfo \| undefined` |
+| run | Direct lookup by Run id. | `(runId) => RunInfo \| undefined` |
+| runs | Snapshot of the visible Runs along the selected branch, in chronological order. | `() => RunInfo[]` |
+| branchSelection | Resolve the `BranchSelection` bundle anchored at `codecMessageId`. | `(codecMessageId) => BranchSelection<TMessage>` |
+| selectSibling | Select a sibling at the branch point anchored at `codecMessageId`. | `(codecMessageId, index) => void` |
+| send | Send one or more `TInput`s on the channel and fire a POST. Wrap a domain message via `codec.createUserMessage` (or build the `{ kind: 'user-message', message }` literal) to send a fresh user message. | `(events, options?) => Promise<ActiveRun>` |
+| regenerate | Regenerate an assistant message, using this view's branch. | `(messageId, options?) => Promise<ActiveRun>` |
+| edit | Edit a user message, forking from this view's branch. | `(messageId, inputs, options?) => Promise<ActiveRun>` |
+
+</Table>
+
+See [`useView`](/docs/ai-transport/api/react/core/use-view#returns) for the field-by-field behaviour of each property. Every method behaves the same way, scoped to the view this hook created.
+
+## Example <a id="example"/>
+
+A side-by-side comparison panel. Two `useCreateView` calls give the user independent branch selection for each pane while both views observe the same underlying conversation tree.
+
+<Code>
+```javascript
+import { useCreateView } from '@ably/ai-transport/react';
+
+function Compare({ messageId }: { messageId: string }) {
+  const leftView = useCreateView({ limit: 30 });
+  const rightView = useCreateView({ limit: 30 });
+
+  const leftBranch = leftView.branchSelection(messageId);
+  const rightBranch = rightView.branchSelection(messageId);
+
+  return (
+    <div className="grid grid-cols-2">
+      <div>
+        <BranchPicker
+          selection={leftBranch}
+          onSelect={(i) => leftView.selectSibling(messageId, i)}
+        />
+        <MessageList messages={leftView.messages} />
+      </div>
+      <div>
+        <BranchPicker
+          selection={rightBranch}
+          onSelect={(i) => rightView.selectSibling(messageId, i)}
+        />
+        <MessageList messages={rightView.messages} />
+      </div>
+    </div>
+  );
+}
+```
+</Code>
diff --git a/src/pages/docs/ai-transport/api/react/core/use-tree.mdx b/src/pages/docs/ai-transport/api/react/core/use-tree.mdx
new file mode 100644
index 0000000000..6e0d3c7220
--- /dev/null
+++ b/src/pages/docs/ai-transport/api/react/core/use-tree.mdx
@@ -0,0 +1,121 @@
+---
+title: "useTree"
+meta_description: "Stable structural query callbacks for the AI Transport conversation tree from React."
+meta_keywords: "AI Transport, React, useTree, TreeHandle, getRunNode, getNodeByCodecMessageId, getSiblingNodes, Ably"
+redirect_from:
+  - /docs/ai-transport/api-reference/use-tree
+  - /docs/ai-transport/api/react/use-tree
+---
+
+`useTree` exposes stable structural query callbacks backed by a session's [`Tree`](/docs/ai-transport/api/javascript/core/client-session). The returned methods are thin `useCallback` wrappers around `session.tree` and never trigger re-renders on their own.
+
+Use this hook when you need to inspect tree structure outside the visible branch (for example, to count edit or regenerate siblings on a node before showing navigation arrows). Branch navigation for the currently visible chain lives on [`useView`](/docs/ai-transport/api/react/core/use-view).
+
+<Code>
+```javascript
+import { useTree } from '@ably/ai-transport/react';
+
+function SiblingSwitcher({ nodeKey }) {
+  const { getSiblingNodes } = useTree();
+  const siblings = getSiblingNodes(nodeKey);
+
+  if (siblings.length <= 1) return null;
+  return <Siblings nodes={siblings} />;
+}
+```
+</Code>
+
+This hook must be used within a [`ClientSessionProvider`](/docs/ai-transport/api/react/core/providers#client-session-provider) unless `session` is supplied explicitly.
+
+## Parameters <a id="parameters"/>
+
+<Table id='UseTreeParameters'>
+
+| Parameter | Required | Description | Type |
+| --- | --- | --- | --- |
+| session | optional | A client session to read tree structure from. Defaults to the nearest provider. | `ClientSession<TInput, TOutput, TProjection, TMessage>` |
+
+</Table>
+
+## Returns <a id="returns"/>
+
+<Table id='TreeHandle'>
+
+| Property | Description | Type |
+| --- | --- | --- |
+| getRunNode | Get a Run by `runId`, or `undefined` if not found. | <Table id='RunNode'/> |
+| getNodeByCodecMessageId | Get the input or run node that owns a given `codecMessageId`, or `undefined` if not observed. Narrow on `kind` (`'input'` or `'run'`) before reading kind-specific fields. | `(codecMessageId) => ConversationNode \| undefined` |
+| getSiblingNodes | Get the sibling group for a node key (edit versions for an input node, regenerate siblings for a reply run). Ordered oldest-first by serial; single-element array when the node has no siblings; empty when the key is unknown. | `(key) => ConversationNode[]` |
+
+</Table>
+
+<Table id='RunNode' hidden>
+
+| Property | Description | Type |
+| --- | --- | --- |
+| kind | Discriminator. Always `'run'`. | `'run'` |
+| runId | The Run's unique identifier. Minted by the agent. | String |
+| parentCodecMessageId | The codec-message-id of the input node this Run is rooted at (the user prompt the agent replied to). `undefined` for the root Run. | String or Undefined |
+| forkOf | The node key of the node this Run replaces, or `undefined` if this Run is not a fork. | String or Undefined |
+| regeneratesCodecMessageId | The codec-message-id this Run regenerates, or `undefined` for non-regenerate Runs. | String or Undefined |
+| clientId | Identity of the Ably client that started this Run. | String |
+| status | Run lifecycle status. `'active'` while streaming, `'suspended'` while paused awaiting input, otherwise the `RunEndReason`. | `'active' \| 'suspended' \| RunEndReason` |
+| projection | Per-Run codec projection. Folded by the Tree from every event published under this run-id. | `TProjection` |
+| invocationId | The agent-minted `invocationId` observed for this Run, adopted from the `ai-run-start` event. Empty string until run-start arrives, or if the wire didn't carry an invocation-id. | String |
+| startSerial | Ably serial of the first observed message tagged with this run-id. | String or Undefined |
+| endSerial | Ably serial of the run-end lifecycle event. | String or Undefined |
+
+</Table>
+
+## Look up a Run by id <a id="get-run-node"/>
+
+<MethodSignature>{`getRunNode(runId: string): RunNode<TProjection> | undefined`}</MethodSignature>
+
+Return the full [`RunNode`](#returns) record for a given `runId`, or `undefined` if the Run has not been observed. Use this when you need fields the View's [`RunInfo`](/docs/ai-transport/api/react/core/use-view#returns) does not expose (parent / fork relationships, the raw projection, serials).
+
+## Look up a node by codec-message-id <a id="get-node-by-codec-message-id"/>
+
+<MethodSignature>{`getNodeByCodecMessageId(codecMessageId: string): ConversationNode<TProjection> | undefined`}</MethodSignature>
+
+Resolve the node that owns the given `codecMessageId` through the tree's index. The result is a `ConversationNode` union: an `InputNode` (user prompt) or a `RunNode` (agent reply). Narrow on `kind` (`'input'` or `'run'`) before reading kind-specific fields. Returns `undefined` when the message has not been observed.
+
+## Get sibling nodes <a id="get-sibling-nodes"/>
+
+<MethodSignature>{`getSiblingNodes(key: string): ConversationNode<TProjection>[]`}</MethodSignature>
+
+Return the sibling group the node keyed by `key` belongs to. The key is either a `RunNode.runId` or an `InputNode.codecMessageId`. The two sibling-group shapes are: input edits, where input nodes share a parent and chain via `forkOf` (the original user prompt plus every edit of it); and regenerate siblings, where reply runs share an input-node parent (the original reply plus every regenerate of it).
+
+Ordered oldest-first by serial. Returns a single-element array when the node has no siblings, an empty array when the key is unknown. Narrow each node on `kind` before reading kind-specific fields.
+
+## Example <a id="example"/>
+
+A run-history sidebar that lists every observed Run and lights up sibling navigation where alternatives exist.
+
+<Code>
+```javascript
+import { useTree, useView } from '@ably/ai-transport/react';
+
+function RunHistory() {
+  const { messages, runOf } = useView();
+  const { getSiblingNodes } = useTree();
+
+  const runs = messages
+    .map(({ codecMessageId }) => runOf(codecMessageId))
+    .filter((r): r is RunInfo => Boolean(r));
+
+  return (
+    <ul>
+      {runs.map((run) => {
+        const siblings = getSiblingNodes(run.runId);
+        return (
+          <li key={run.runId}>
+            <RunSummary run={run} />
+            {siblings.length > 1 && <SiblingPicker siblings={siblings} />}
+          </li>
+        );
+      })}
+    </ul>
+  );
+}
+```
+</Code>
diff --git a/src/pages/docs/ai-transport/api/react/core/use-view.mdx b/src/pages/docs/ai-transport/api/react/core/use-view.mdx
new file mode 100644
index 0000000000..67701d9c82
--- /dev/null
+++ b/src/pages/docs/ai-transport/api/react/core/use-view.mdx
@@ -0,0 +1,207 @@
+---
+title: "useView"
+meta_description: "Subscribe to a paginated, branch-aware view of the AI Transport conversation tree from React."
+meta_keywords: "AI Transport, React, useView, ViewHandle, send, regenerate, edit, conversation, Ably"
+redirect_from:
+  - /docs/ai-transport/api-reference/use-view
+  - /docs/ai-transport/api/react/use-view
+---
+
+`useView` subscribes to a session's default view and returns the visible messages, branch navigation, write operations, and pagination state. It is the primary hook for rendering a conversation UI.
+
+By default the hook subscribes to the nearest [`ClientSessionProvider`](/docs/ai-transport/api/react/core/providers#client-session-provider)'s default view. Pass `session` to use a different session's default view, or `view` to subscribe to a specific view created with [`useCreateView`](/docs/ai-transport/api/react/core/use-create-view) or [`session.createView()`](/docs/ai-transport/api/javascript/core/client-session#create-view).
+
+<Code>
+```javascript
+import { useView } from '@ably/ai-transport/react';
+
+function Conversation() {
+  const { messages, send } = useView({ limit: 30 });
+
+  return (
+    <>
+      {messages.map(({ codecMessageId, message }) => (
+        <Message key={codecMessageId} message={message} />
+      ))}
+      <Composer
+        onSubmit={(text) =>
+          send({ kind: 'user-message', message: { role: 'user', parts: [{ type: 'text', text }] } })
+        }
+      />
+    </>
+  );
+}
+```
+</Code>
+
+This hook must be used within a [`ClientSessionProvider`](/docs/ai-transport/api/react/core/providers#client-session-provider) unless `session` or `view` is supplied explicitly.
+
+## Parameters <a id="parameters"/>
+
+<Table id='UseViewParameters'>
+
+| Parameter | Required | Description | Type |
+| --- | --- | --- | --- |
+| session | optional | A client session whose default view to subscribe to. Defaults to the nearest provider. | `ClientSession<TInput, TOutput, TProjection, TMessage>` |
+| view | optional | A specific view to subscribe to directly. Takes priority over `session`. | `View<TInput, TMessage>` |
+| limit | optional | Maximum number of older Runs to reveal per page. When provided, auto-loads the first page on mount. | Number |
+| skip | optional | When `true`, skip all subscriptions and return an empty handle immediately. | Boolean |
+
+</Table>
+
+## Returns <a id="returns"/>
+
+<Table id='ViewHandle'>
+
+| Property | Description | Type |
+| --- | --- | --- |
+| messages | The visible messages along the selected branch, each paired with its `codecMessageId`. Read the domain object from each entry's `message` field. | `CodecMessage<TMessage>[]` |
+| hasOlder | Whether there are older Runs that can be revealed via `loadOlder`. | Boolean |
+| loading | Whether a page load is currently in progress. | Boolean |
+| loadError | Set when the most recent `loadOlder` call failed. Cleared automatically on the next successful load. | `Ably.ErrorInfo` or Undefined |
+| loadOlder | Reveal older Runs. No-op if already loading. | `() => Promise<void>` |
+| runOf | Look up the `RunInfo` for the Run that owns the given `codecMessageId`. | <Table id='RunInfo'/> |
+| run | Direct lookup by Run id. | <Table id='RunInfo'/> |
+| runs | Snapshot of the visible Runs along the selected branch, in chronological order. Returns `[]` when the view isn't resolved. | `() => RunInfo[]` |
+| branchSelection | Resolve the `BranchSelection` bundle anchored at `codecMessageId`. Always returns a safe object. | <Table id='BranchSelection'/> |
+| selectSibling | Select a sibling at the branch point anchored at `codecMessageId`. | `(codecMessageId, index) => void` |
+| send | Send one or more `TInput`s on the channel and fire a POST. Wrap a domain message via `codec.createUserMessage` (or build the `{ kind: 'user-message', message }` literal) to send a fresh user message. Takes optional <Table id='SendOptions'/>. | `(events, options?) => Promise<ActiveRun>` |
+| regenerate | Regenerate an assistant message using this view's branch for history. | `(messageId, options?) => Promise<ActiveRun>` |
+| edit | Edit a user message, forking from this view's branch. | `(messageId, inputs, options?) => Promise<ActiveRun>` |
+
+</Table>
+
+<Table id='RunInfo' hidden>
+
+| Property | Description | Type |
+| --- | --- | --- |
+| runId | The Run's unique identifier. | String |
+| clientId | Identity of the Ably client that started this Run. Empty string when the wire didn't carry an owner client id. | String |
+| status | Run lifecycle status. `'active'` while streaming, `'suspended'` while paused awaiting input, otherwise the `RunEndReason` the Run terminated with. | `'active' \| 'suspended' \| RunEndReason` |
+| invocationId | The agent-minted `invocationId` observed for this Run, adopted from `ai-run-start`. Empty string until run-start arrives, or if the wire didn't carry an invocation-id. | String |
+
+</Table>
+
+<Table id='BranchSelection' hidden>
+
+| Property | Description | Type |
+| --- | --- | --- |
+| hasSiblings | True when the anchor has more than one sibling. | Boolean |
+| siblings | The selected sibling and any alternatives in tree-order. Always contains the currently rendered message for known ids. | `TMessage[]` |
+| index | Index of the selected sibling within `siblings`. `0` when there is no real branching. | Number |
+| selected | Convenience reference to `siblings[index]`. `undefined` only when `siblings` is empty. | `TMessage` or Undefined |
+
+</Table>
+
+<Table id='SendOptions' hidden>
+
+| Property | Description | Type |
+| --- | --- | --- |
+| forkOf | The codec-message-id of the message this send replaces (fork). | String |
+| parent | The codec-message-id of the predecessor in the conversation thread. Auto-computed when omitted. | String |
+| runId | Reuse an existing `runId` (for example to resume a suspended run). | String |
+| inputEventId | Override the `inputEventId` for this send. Defaults to `crypto.randomUUID()`. | String |
+
+</Table>
+
+## Reveal older Runs <a id="load-older"/>
+
+<MethodSignature>{`loadOlder(): Promise<void>`}</MethodSignature>
+
+Load older messages into the view by revealing more Runs. When `limit` is set on the hook, the first page auto-loads on mount. Call `loadOlder` again to reveal more. The call is gated so concurrent invocations collapse to one in-flight request.
+
+On failure, `loadError` is set. On the next successful load, `loadError` is cleared automatically.
+
+## Look up a Run by message id <a id="run-of"/>
+
+<MethodSignature>{`runOf(codecMessageId: string): RunInfo | undefined`}</MethodSignature>
+
+Look up the [`RunInfo`](#returns) for the Run that owns the given `codecMessageId`. Returns `undefined` when the codec-message-id has not been observed.
+
+## Look up a Run by id <a id="run"/>
+
+<MethodSignature>{`run(runId: string): RunInfo | undefined`}</MethodSignature>
+
+Direct lookup by Run id. Symmetric with [`runOf`](#run-of) for callers that already hold a `runId`.
+
+## Resolve a branch selection <a id="branch-selection"/>
+
+<MethodSignature>{`branchSelection(codecMessageId: string): BranchSelection<TMessage>`}</MethodSignature>
+
+Resolve the `BranchSelection` bundle anchored at `codecMessageId`. Always returns a safe object: for branch anchors with N siblings, `siblings` carries every sibling Run's view of the anchor slot; for non-anchor messages, `siblings` is `[thisMessage]` and `hasSiblings` is `false`.
+
+## Select a sibling <a id="select-sibling"/>
+
+<MethodSignature>{`selectSibling(codecMessageId: string, index: number): void`}</MethodSignature>
+
+Select a sibling at the branch point anchored at `codecMessageId`. `index` is clamped to `[0, siblings.length - 1]`. Silent no-op when the message is not a branch anchor. Emits `'update'` on the underlying view when the visible output changes.
+
+## Send inputs <a id="send"/>
+
+<MethodSignature>{`send(events: TInput | TInput[], options?: SendOptions): Promise<ActiveRun>`}</MethodSignature>
+
+Send one or more `TInput`s on the channel and fire a POST. Each `TInput` carries its own routing metadata (`parent`, `target`, `codecMessageId`).
+
+To send a fresh user message, build a `UserMessage` input. Use the codec factory (`codec.createUserMessage(message)`) or build the literal directly: `{ kind: 'user-message', message }`. A send containing at least one `UserMessage` mints a fresh Run. A send containing only tool-resolution inputs (`tool-result`, `tool-result-error`, `tool-approval-response`) is a continuation; pair it with `options.runId` to extend a suspended Run.
+
+## Regenerate an assistant message <a id="regenerate"/>
+
+<MethodSignature>{`regenerate(messageId: string, options?: SendOptions): Promise<ActiveRun>`}</MethodSignature>
+
+Regenerate an assistant message. Creates a new Run that targets the message and threads under its parent user message. Both ids are computed automatically from this view's branch.
+
+## Edit a user message <a id="edit"/>
+
+<MethodSignature>{`edit(messageId: string, inputs: TInput | TInput[], options?: SendOptions): Promise<ActiveRun>`}</MethodSignature>
+
+Edit a user message. Creates a new Run that forks the target message with the replacement inputs. `forkOf`, `parent`, and history are computed automatically from this view's branch.
+
+## Example <a id="example"/>
+
+A conversation component that loads older messages on mount, renders branch navigation when a sibling is available, and offers a regenerate button on each assistant turn.
+
+<Code>
+```javascript
+import { useView } from '@ably/ai-transport/react';
+
+function Conversation() {
+  const {
+    messages,
+    hasOlder,
+    loadOlder,
+    branchSelection,
+    selectSibling,
+    send,
+    regenerate,
+  } = useView({ limit: 30 });
+
+  return (
+    <>
+      {hasOlder && <button onClick={() => loadOlder()}>Load older</button>}
+      {messages.map(({ codecMessageId, message }) => {
+        const branch = branchSelection(codecMessageId);
+        return (
+          <div key={codecMessageId}>
+            <Message message={message} />
+            {branch.hasSiblings && (
+              <BranchControls
+                selection={branch}
+                onSelect={(i) => selectSibling(codecMessageId, i)}
+              />
+            )}
+            {message.role === 'assistant' && (
+              <button onClick={() => regenerate(codecMessageId)}>Regenerate</button>
+            )}
+          </div>
+        );
+      })}
+      <Composer
+        onSubmit={(text) =>
+          send({ kind: 'user-message', message: { role: 'user', parts: [{ type: 'text', text }] } })
+        }
+      />
+    </>
+  );
+}
+```
+</Code>
diff --git a/src/pages/docs/ai-transport/api/react/providers.mdx b/src/pages/docs/ai-transport/api/react/providers.mdx
deleted file mode 100644
index c69374a535..0000000000
--- a/src/pages/docs/ai-transport/api/react/providers.mdx
+++ /dev/null
@@ -1,155 +0,0 @@
----
-title: "Providers"
-meta_description: "TransportProvider and ChatTransportProvider for the AI Transport React integration."
-meta_keywords: "AI Transport, React, TransportProvider, ChatTransportProvider, provider, context, Ably"
-redirect_from:
-  - /docs/ai-transport/api-reference/react/providers
----
-
-The React integration is context-based. A provider higher in the tree creates the underlying `ClientTransport` (and, for the Vercel layer, the `ChatTransport` adapter) and exposes them through React context. Every hook in this section reads from the nearest provider.
-
-There are two providers. Use `TransportProvider` from the generic entry point when you build a UI directly against AI Transport's hooks. Use `ChatTransportProvider` from the Vercel entry point when you wire AI Transport into Vercel's `useChat`. `ChatTransportProvider` internally wraps its children with a `TransportProvider`, so both layers' hooks resolve from a single provider.
-
-<Code>
-```react
-import { TransportProvider } from '@ably/ai-transport/react';
-import { ChatTransportProvider } from '@ably/ai-transport/vercel/react';
-```
-</Code>
-
-## TransportProvider <a id="TransportProvider"/>
-
-Creates a `ClientTransport` and makes it available to descendant components. Wraps children with Ably's `ChannelProvider` using the supplied `channelName`. Descendants read the transport with [`useClientTransport`](/docs/ai-transport/api/react/use-client-transport).
-
-<Code>
-```react
-import { TransportProvider } from '@ably/ai-transport/react';
-import { UIMessageCodec } from '@ably/ai-transport/vercel';
-
-<TransportProvider channelName="conversation-42" codec={UIMessageCodec} api="/api/chat">
-  <Chat />
-</TransportProvider>
-```
-</Code>
-
-### Parameters <a id="TransportProvider-params"/>
-
-The provider accepts every `ClientTransportOptions` field except `channel` (managed internally), plus a `channelName`.
-
-<Table id='TransportProviderProps'>
-
-| Prop | Required | Description | Type |
-| --- | --- | --- | --- |
-| channelName | Required | The Ably channel name to subscribe to. Also the context registry key. | String |
-| codec | Required | The codec to use for encoding and decoding messages. | `Codec<TEvent, TMessage>` |
-| api | Required | Server endpoint URL for the HTTP POST that triggers a new turn. | String |
-| clientId | Optional | The client's identity. Sent to the server in the POST body. | String |
-| headers | Optional | Headers for the HTTP POST. Function form for dynamic values. | `Record<string, string>` or `() => Record<string, string>` |
-| body | Optional | Additional body fields merged into the HTTP POST. Function form for dynamic values. | `Record<string, unknown>` or `() => Record<string, unknown>` |
-| credentials | Optional | Fetch credentials mode for the HTTP POST. | `RequestCredentials` |
-| fetch | Optional | Custom fetch implementation. | `typeof fetch` |
-| messages | Optional | Initial messages to seed the conversation tree with. | `TMessage[]` |
-| logger | Optional | Logger instance for diagnostic output. | `Logger` |
-
-</Table>
-
-If `createClientTransport` throws during construction, the error is surfaced through `useClientTransport` as `transportError` — the component tree does not crash and children are still rendered.
-
-For multiple transports, nest providers with distinct `channelName` values. Descendants call `useClientTransport({ channelName })` to disambiguate.
-
-## ChatTransportProvider <a id="ChatTransportProvider"/>
-
-Creates a `ChatTransport` adapter for Vercel's `useChat`, alongside the underlying `ClientTransport`. Wraps children with a `TransportProvider` using `UIMessageCodec`, so the Ably channel lifecycle is managed in one place.
-
-<Code>
-```react
-import { ChatTransportProvider } from '@ably/ai-transport/vercel/react';
-
-<ChatTransportProvider channelName="conversation-42">
-  <Chat />
-</ChatTransportProvider>
-```
-</Code>
-
-### Parameters <a id="ChatTransportProvider-params"/>
-
-The provider accepts every `VercelClientTransportOptions` field (defaulting `api` to `/api/chat`), plus a `channelName`.
-
-<Table id='ChatTransportProviderProps'>
-
-| Prop | Required | Description | Type |
-| --- | --- | --- | --- |
-| channelName | Required | The Ably channel name to subscribe to. Also the context registry key. | String |
-| api | Optional | Server endpoint URL for the HTTP POST. Defaults to `/api/chat`. | String |
-| clientId | Optional | The client's identity. | String |
-| headers | Optional | Headers for the HTTP POST. | `Record<string, string>` or `() => Record<string, string>` |
-| body | Optional | Additional body fields merged into the HTTP POST. | `Record<string, unknown>` or `() => Record<string, unknown>` |
-| credentials | Optional | Fetch credentials mode. | `RequestCredentials` |
-| fetch | Optional | Custom fetch implementation. | `typeof fetch` |
-| messages | Optional | Initial messages to seed the conversation tree with. | `UIMessage[]` |
-| logger | Optional | Logger instance. | `Logger` |
-| chatOptions | Optional | `ChatTransportOptions` for customising the adapter (for example, `prepareSendMessagesRequest`). | <Table id='ChatTransportOptions'/> |
-
-</Table>
-
-<Table id='ChatTransportOptions' hidden>
-
-| Property | Description | Type |
-| --- | --- | --- |
-| prepareSendMessagesRequest | Hook to customise the HTTP POST body and headers before each send. Called with the conversation context (see <Table id='SendMessagesRequestContext'/>); returns the body and headers to use. Default sends all previous messages as `history`. | `(context: SendMessagesRequestContext) => { body?: Record<string, unknown>; headers?: Record<string, string> }` or Undefined |
-
-</Table>
-
-<Table id='SendMessagesRequestContext' hidden>
-
-| Property | Description | Type |
-| --- | --- | --- |
-| chatId | Chat session ID (from `useChat`'s `id`). | String or Undefined |
-| trigger | What triggered the request. | `'submit-message'` or `'regenerate-message'` |
-| messageId | The message ID for edit or regeneration. Undefined when submitting a new message. | String or Undefined |
-| history | Previous messages in the conversation. | `UIMessage[]` |
-| messages | The new messages being sent. Empty for regeneration. | `UIMessage[]` |
-| forkOf | The msg-id of the message being forked. | String or Undefined |
-| parent | The msg-id of the predecessor. | String or Undefined |
-
-</Table>
-
-`ChatTransport` itself is not closed on unmount. The underlying `ClientTransport`'s lifecycle is managed by the wrapping `TransportProvider`. Multiple `ChatTransportProvider`s can be nested using distinct `channelName` values; each merges its transport into the parent registry, so descendants can access multiple transports via `useChatTransport({ channelName })`.
-
-## Example
-
-<Code>
-```react
-'use client';
-
-import { useEffect, useState } from 'react';
-import * as Ably from 'ably';
-import { AblyProvider } from 'ably/react';
-import { ChatTransportProvider } from '@ably/ai-transport/vercel/react';
-import { Chat } from './chat';
-
-function Providers({ children }) {
-  const [client, setClient] = useState(null);
-
-  useEffect(() => {
-    const ably = new Ably.Realtime({ authUrl: '/auth' });
-    setClient(ably);
-    return () => ably.close();
-  }, []);
-
-  if (!client) return null;
-  return <AblyProvider client={client}>{children}</AblyProvider>;
-}
-
-export default function Page() {
-  const chatId = 'conversation-42';
-  return (
-    <Providers>
-      <ChatTransportProvider channelName={chatId}>
-        <Chat chatId={chatId} />
-      </ChatTransportProvider>
-    </Providers>
-  );
-}
-```
-</Code>
diff --git a/src/pages/docs/ai-transport/api/react/use-ably-messages.mdx b/src/pages/docs/ai-transport/api/react/use-ably-messages.mdx
deleted file mode 100644
index a716fdbd01..0000000000
--- a/src/pages/docs/ai-transport/api/react/use-ably-messages.mdx
+++ /dev/null
@@ -1,60 +0,0 @@
----
-title: "useAblyMessages"
-meta_description: "Subscribe to raw Ably InboundMessages on the AI Transport channel from React."
-meta_keywords: "AI Transport, React, useAblyMessages, InboundMessage, raw messages, Ably"
-redirect_from:
-  - /docs/ai-transport/api-reference/react/use-ably-messages
----
-
-Subscribe to the raw `Ably.InboundMessage` stream from the transport's tree. Messages are appended in arrival order. Use when you need to inspect channel-level metadata (serials, raw headers) that the codec layer would otherwise hide. Most applications should use [`useView`](/docs/ai-transport/api/react/use-view) instead, which returns decoded domain messages.
-
-This hook must be used within a [`TransportProvider`](/docs/ai-transport/api/react/providers#TransportProvider) or a [`ChatTransportProvider`](/docs/ai-transport/api/react/providers#ChatTransportProvider).
-
-<Code>
-```react
-import { useAblyMessages } from '@ably/ai-transport/react';
-
-function RawLog() {
-  const messages = useAblyMessages();
-  return <pre>{messages.map((m) => `${m.serial} ${m.name}`).join('\n')}</pre>;
-}
-```
-</Code>
-
-## Parameters
-
-<Table id='UseAblyMessagesProps'>
-
-| Prop | Required | Description | Type |
-| --- | --- | --- | --- |
-| transport | Optional | Transport to subscribe to. Defaults to the nearest provider when omitted. | `ClientTransport<TEvent, TMessage>` |
-| skip | Optional | When `true`, skip all subscriptions and return an empty array. | Boolean |
-
-</Table>
-
-## Returns
-
-`Ably.InboundMessage[]`
-
-The accumulated raw Ably messages in chronological order. The array grows as messages arrive.
-
-## Example
-
-<Code>
-```react
-import { useAblyMessages } from '@ably/ai-transport/react';
-
-function ChannelTrace() {
-  const raw = useAblyMessages();
-  return (
-    <ul>
-      {raw.map((m) => (
-        <li key={m.serial}>
-          <code>{m.serial}</code> {m.name} ({m.action})
-        </li>
-      ))}
-    </ul>
-  );
-}
-```
-</Code>
diff --git a/src/pages/docs/ai-transport/api/react/use-active-turns.mdx b/src/pages/docs/ai-transport/api/react/use-active-turns.mdx
deleted file mode 100644
index 76888b8704..0000000000
--- a/src/pages/docs/ai-transport/api/react/use-active-turns.mdx
+++ /dev/null
@@ -1,80 +0,0 @@
----
-title: "useActiveTurns"
-meta_description: "Subscribe to active turns on the AI Transport channel from React."
-meta_keywords: "AI Transport, React, useActiveTurns, active turns, streaming, Ably"
-redirect_from:
-  - /docs/ai-transport/api-reference/react/use-active-turns
----
-
-Subscribe to the set of active turns on the channel. Returns a reactive `Map` keyed by `clientId`, where each value is a `Set` of `turnId`s for that client. Re-renders when turns start or end. Use it to drive UI such as a send-or-stop button, per-client streaming indicators, or a "wait for all turns to finish" guard.
-
-This hook must be used within a [`TransportProvider`](/docs/ai-transport/api/react/providers#TransportProvider) or a [`ChatTransportProvider`](/docs/ai-transport/api/react/providers#ChatTransportProvider).
-
-<Code>
-```react
-import { useActiveTurns } from '@ably/ai-transport/react';
-
-function SendOrStop({ onSend, onStop }) {
-  const activeTurns = useActiveTurns();
-  return activeTurns.size > 0
-    ? <button onClick={onStop}>Stop</button>
-    : <button onClick={onSend}>Send</button>;
-}
-```
-</Code>
-
-## Parameters
-
-<Table id='UseActiveTurnsProps'>
-
-| Prop | Required | Description | Type |
-| --- | --- | --- | --- |
-| transport | Optional | Transport to track turns for. Defaults to the nearest provider when omitted. | `ClientTransport<TEvent, TMessage>` or Null |
-
-</Table>
-
-## Returns
-
-`Map<string, Set<string>>`
-
-A reactive map. The outer key is the `clientId` that owns the turns. The inner `Set` holds the `turnId`s currently active for that client.
-
-Common patterns:
-
-- `activeTurns.size > 0` — any turn is active anywhere on the channel.
-- `activeTurns.has('agent-1')` — a specific client (typically the agent) has at least one active turn.
-- `activeTurns.get(clientId)?.size ?? 0` — how many turns a specific client has open.
-
-The map updates in real time across every connected client, not just the local one. If another tab on the same session starts a turn, this hook's value updates in this component too.
-
-## Example
-
-<Code>
-```react
-import { useActiveTurns, useView } from '@ably/ai-transport/react';
-import { useState } from 'react';
-
-function Composer() {
-  const { send } = useView();
-  const activeTurns = useActiveTurns();
-  const [input, setInput] = useState('');
-
-  const isStreaming = activeTurns.size > 0;
-
-  const onSend = async () => {
-    const text = input;
-    setInput('');
-    await send({ id: crypto.randomUUID(), role: 'user', parts: [{ type: 'text', text }] });
-  };
-
-  return (
-    <form onSubmit={(e) => { e.preventDefault(); onSend(); }}>
-      <input value={input} onChange={(e) => setInput(e.target.value)} />
-      {isStreaming
-        ? <button type="button" disabled>Streaming…</button>
-        : <button type="submit">Send</button>}
-    </form>
-  );
-}
-```
-</Code>
diff --git a/src/pages/docs/ai-transport/api/react/use-chat-transport.mdx b/src/pages/docs/ai-transport/api/react/use-chat-transport.mdx
deleted file mode 100644
index d5f16303e0..0000000000
--- a/src/pages/docs/ai-transport/api/react/use-chat-transport.mdx
+++ /dev/null
@@ -1,80 +0,0 @@
----
-title: "useChatTransport"
-meta_description: "Read a ChatTransport and its underlying ClientTransport from the nearest ChatTransportProvider in AI Transport."
-meta_keywords: "AI Transport, React, useChatTransport, ChatTransport, Vercel AI SDK, useChat, Ably"
-redirect_from:
-  - /docs/ai-transport/api-reference/react/use-chat-transport
----
-
-Read the `ChatTransport` adapter and its underlying `ClientTransport` from the nearest [`ChatTransportProvider`](/docs/ai-transport/api/react/providers#ChatTransportProvider). The `ChatTransport` is what you pass to Vercel's `useChat` as `transport`.
-
-The hook is a thin context reader; it does not create transport state. Construction happens once inside `ChatTransportProvider`.
-
-This hook must be used within a [`ChatTransportProvider`](/docs/ai-transport/api/react/providers#ChatTransportProvider).
-
-<Code>
-```react
-import { useChatTransport } from '@ably/ai-transport/vercel/react';
-import { useChat } from '@ai-sdk/react';
-
-function Chat({ chatId }) {
-  const { chatTransport } = useChatTransport();
-  const { messages, sendMessage, stop } = useChat({ id: chatId, transport: chatTransport });
-  // ...
-}
-```
-</Code>
-
-## Parameters
-
-<Table id='UseChatTransportProps'>
-
-| Prop | Required | Description | Type |
-| --- | --- | --- | --- |
-| channelName | Optional | The `channelName` of the `ChatTransportProvider` to read from. Omit to use the nearest provider in the tree. | String |
-| skip | Optional | When `true`, returns stub transports that throw on any access. Safe to hold in state before auth or other conditions are ready. | Boolean |
-
-</Table>
-
-## Returns
-
-`ChatTransportHandle`
-
-<Table id='ChatTransportHandle'>
-
-| Property | Description | Type |
-| --- | --- | --- |
-| transport | The underlying client transport. Also available via `useClientTransport()`. A throwing stub when `skip` is `true`, when no matching `TransportProvider` is found, or when transport construction failed. Check `transportError` before use. | `ClientTransport<UIMessageChunk, UIMessage>` |
-| chatTransport | The chat transport adapter for use with Vercel's `useChat` hook. A throwing stub when `skip` is `true`, when no matching `ChatTransportProvider` is found, or when the underlying `ClientTransport` construction failed. Check both `chatTransportError` and `transportError` before use. | `ChatTransport` |
-| transportError | Set when no matching `TransportProvider` is found or transport construction failed and `skip` is `false`. | `Ably.ErrorInfo` or Undefined |
-| chatTransportError | Set when no matching `ChatTransportProvider` is found or transport construction failed and `skip` is `false`. | `Ably.ErrorInfo` or Undefined |
-
-</Table>
-
-See [Vercel AI SDK integration](/docs/ai-transport/api/javascript/vercel#ChatTransport) for the `ChatTransport` surface and [`ClientTransport`](/docs/ai-transport/api/javascript/client-transport) for the underlying transport.
-
-## Example
-
-<Code>
-```react
-import { useChatTransport } from '@ably/ai-transport/vercel/react';
-import { useChat } from '@ai-sdk/react';
-
-function Chat({ chatId }) {
-  const { chatTransport, transport, chatTransportError, transportError } = useChatTransport();
-
-  if (transportError) return <ErrorBanner error={transportError} />;
-  if (chatTransportError) return <ErrorBanner error={chatTransportError} />;
-
-  const { messages, sendMessage, stop } = useChat({ id: chatId, transport: chatTransport });
-
-  return (
-    <div>
-      {messages.map((m) => <Message key={m.id} message={m} />)}
-      <Composer onSend={(text) => sendMessage({ text })} onStop={stop} />
-      <button onClick={() => transport.cancel({ all: true })}>Cancel everyone</button>
-    </div>
-  );
-}
-```
-</Code>
diff --git a/src/pages/docs/ai-transport/api/react/use-client-transport.mdx b/src/pages/docs/ai-transport/api/react/use-client-transport.mdx
deleted file mode 100644
index ff07981a76..0000000000
--- a/src/pages/docs/ai-transport/api/react/use-client-transport.mdx
+++ /dev/null
@@ -1,75 +0,0 @@
----
-title: "useClientTransport"
-meta_description: "Read a ClientTransport from the nearest TransportProvider in the AI Transport React integration."
-meta_keywords: "AI Transport, React, useClientTransport, ClientTransportHandle, transport, Ably"
-redirect_from:
-  - /docs/ai-transport/api-reference/react/use-client-transport
----
-
-Read the `ClientTransport` exposed by the nearest [`TransportProvider`](/docs/ai-transport/api/react/providers#TransportProvider). The hook is a thin context reader; it does not create or own transport state.
-
-This hook must be used within a [`TransportProvider`](/docs/ai-transport/api/react/providers#TransportProvider) or a [`ChatTransportProvider`](/docs/ai-transport/api/react/providers#ChatTransportProvider).
-
-<Code>
-```react
-import { useClientTransport } from '@ably/ai-transport/react';
-
-function Chat() {
-  const { transport, transportError } = useClientTransport();
-  if (transportError) return <ErrorBanner error={transportError} />;
-  // Use transport.view, transport.cancel(), etc.
-}
-```
-</Code>
-
-## Parameters
-
-<Table id='UseClientTransportProps'>
-
-| Prop | Required | Description | Type |
-| --- | --- | --- | --- |
-| channelName | Optional | The `channelName` of the `TransportProvider` to read from. Omit to use the nearest provider in the tree. | String |
-| skip | Optional | When `true`, returns a stub transport that throws on any access. Useful when a condition (auth, feature flag) is not yet resolved. | Boolean |
-| onError | Optional | Called whenever the resolved transport emits a non-fatal error. The subscription is established once the transport resolves and removed on unmount or when the transport changes. | `(error: Ably.ErrorInfo) => void` |
-
-</Table>
-
-## Returns
-
-`ClientTransportHandle<TEvent, TMessage>`
-
-<Table id='ClientTransportHandle'>
-
-| Property | Description | Type |
-| --- | --- | --- |
-| transport | The resolved transport. A throwing stub when `skip` is `true`, when no matching provider is found, or when transport construction failed. Check `transportError` before use. | `ClientTransport<TEvent, TMessage>` |
-| transportError | Set when no matching provider is found or transport construction failed and `skip` is `false`. `undefined` when the transport resolved successfully or `skip` is `true`. | `Ably.ErrorInfo` or Undefined |
-
-</Table>
-
-Check `transportError` before using `transport` to avoid throws from the stub. See [`ClientTransport`](/docs/ai-transport/api/javascript/client-transport) for the full surface the returned transport exposes.
-
-## Example
-
-<Code>
-```react
-import { useClientTransport, useView } from '@ably/ai-transport/react';
-
-function Chat() {
-  const { transport, transportError } = useClientTransport({
-    onError: (error) => console.error(`Transport error ${error.code}:`, error.message),
-  });
-
-  const { messages } = useView({ limit: 30 });
-
-  if (transportError) return <ErrorBanner error={transportError} />;
-
-  return (
-    <div>
-      {messages.map((m) => <Message key={m.id} message={m} />)}
-      <button onClick={() => transport.cancel()}>Stop</button>
-    </div>
-  );
-}
-```
-</Code>
diff --git a/src/pages/docs/ai-transport/api/react/use-create-view.mdx b/src/pages/docs/ai-transport/api/react/use-create-view.mdx
deleted file mode 100644
index 1642033146..0000000000
--- a/src/pages/docs/ai-transport/api/react/use-create-view.mdx
+++ /dev/null
@@ -1,70 +0,0 @@
----
-title: "useCreateView"
-meta_description: "Create an independent View over the AI Transport conversation tree from React, with its own branch selections and pagination."
-meta_keywords: "AI Transport, React, useCreateView, ViewHandle, split-pane, comparison, Ably"
-redirect_from:
-  - /docs/ai-transport/api-reference/react/use-create-view
----
-
-Create an independent `View` and subscribe to it. Returns the same `ViewHandle` as [`useView`](/docs/ai-transport/api/react/use-view), but backed by a newly created view with its own branch selections and pagination state. Use when one component needs a view distinct from the transport's default view — typically a split-pane comparison UI or a sidebar that follows a different branch.
-
-The view is closed on unmount or when the transport changes.
-
-This hook must be used within a [`TransportProvider`](/docs/ai-transport/api/react/providers#TransportProvider) or a [`ChatTransportProvider`](/docs/ai-transport/api/react/providers#ChatTransportProvider).
-
-<Code>
-```react
-import { useCreateView } from '@ably/ai-transport/react';
-
-function ComparisonPane() {
-  const left = useCreateView({ limit: 30 });
-  const right = useCreateView({ limit: 30 });
-  // Each view has its own select() state — render two branches side by side.
-}
-```
-</Code>
-
-## Parameters
-
-<Table id='UseCreateViewProps'>
-
-| Prop | Required | Description | Type |
-| --- | --- | --- | --- |
-| transport | Optional | Transport to create a view from. Defaults to the nearest provider when omitted. | `ClientTransport<TEvent, TMessage>` or Null |
-| limit | Optional | Maximum number of older messages to load per page. When provided, auto-loads the first page on mount. | Number |
-| skip | Optional | When `true`, skip view creation and return an empty handle. | Boolean |
-
-</Table>
-
-## Returns
-
-`ViewHandle<TEvent, TMessage>`
-
-The same shape as [`useView`](/docs/ai-transport/api/react/use-view#useViewReturns). See that page for the full property and method list.
-
-## Example
-
-<Code>
-```react
-import { useCreateView } from '@ably/ai-transport/react';
-
-function SplitPane({ messageId }) {
-  const left = useCreateView({ limit: 30 });
-  const right = useCreateView({ limit: 30 });
-
-  // Show the two siblings of a regenerate side by side.
-  const siblings = left.getSiblings(messageId);
-  if (siblings.length >= 2) {
-    left.select(messageId, 0);
-    right.select(messageId, 1);
-  }
-
-  return (
-    <div className="split">
-      <Pane title="Version A" view={left} />
-      <Pane title="Version B" view={right} />
-    </div>
-  );
-}
-```
-</Code>
diff --git a/src/pages/docs/ai-transport/api/react/use-message-sync.mdx b/src/pages/docs/ai-transport/api/react/use-message-sync.mdx
deleted file mode 100644
index 8b4b0db1b5..0000000000
--- a/src/pages/docs/ai-transport/api/react/use-message-sync.mdx
+++ /dev/null
@@ -1,70 +0,0 @@
----
-title: "useMessageSync"
-meta_description: "Wire AI Transport message updates into Vercel useChat's message state from React."
-meta_keywords: "AI Transport, React, useMessageSync, useChat, Vercel AI SDK, multi-device, Ably"
-redirect_from:
-  - /docs/ai-transport/api-reference/react/use-message-sync
----
-
-Wire AI Transport message updates into Vercel's `useChat` message state. Subscribes to the transport view's `update` event and replaces `useChat`'s messages with the view's authoritative list. Use this when `useChat`'s message array needs to reflect messages from other devices, browser tabs, or observer participants on the same session.
-
-Without `useMessageSync`, `useChat` only renders messages from its own sends. The hook bridges the gap by feeding the view's authoritative list into `useChat`'s state.
-
-This hook must be used within a [`ChatTransportProvider`](/docs/ai-transport/api/react/providers#ChatTransportProvider).
-
-<Code>
-```react
-import { useChatTransport, useMessageSync } from '@ably/ai-transport/vercel/react';
-import { useChat } from '@ai-sdk/react';
-
-function Chat({ chatId }) {
-  const { chatTransport } = useChatTransport();
-  const { messages, setMessages, sendMessage } = useChat({ id: chatId, transport: chatTransport });
-  useMessageSync({ setMessages });
-  // messages now includes sends from other devices.
-}
-```
-</Code>
-
-## Parameters
-
-<Table id='UseMessageSyncProps'>
-
-| Prop | Required | Description | Type |
-| --- | --- | --- | --- |
-| setMessages | Required | The `setMessages` updater from `useChat()`. Called with an updater function that replaces the previous message list with the view's authoritative list. | `(updater: (prev: UIMessage[]) => UIMessage[]) => void` |
-| channelName | Optional | Channel name of the `ChatTransportProvider` to observe. Omit to use the nearest provider in the tree. | String |
-| skip | Optional | When `true`, skip all subscriptions and do nothing. Use when the hook's dependencies are not yet resolved (for example, auth pending). | Boolean |
-
-</Table>
-
-## Returns
-
-The hook returns `void`. The sync is set up as a side-effect inside `useEffect`.
-
-When a `ChatTransport` is provided (resolved from the nearest `ChatTransportProvider`), `setMessages` calls are gated during active own-turn streams. This prevents the push/replace ID mismatch in `useChat`'s internal write function. When the stream finishes, the gate opens and an immediate sync fires to pick up any observer messages that arrived during the stream.
-
-## Example
-
-<Code>
-```react
-import { useChatTransport, useMessageSync } from '@ably/ai-transport/vercel/react';
-import { useChat } from '@ai-sdk/react';
-
-function Chat({ chatId }) {
-  const { chatTransport } = useChatTransport();
-  const { messages, setMessages, sendMessage, stop } = useChat({
-    id: chatId,
-    transport: chatTransport,
-  });
-  useMessageSync({ setMessages });
-
-  return (
-    <div>
-      {messages.map((m) => <Message key={m.id} message={m} />)}
-      <Composer onSend={(text) => sendMessage({ text })} onStop={stop} />
-    </div>
-  );
-}
-```
-</Code>
diff --git a/src/pages/docs/ai-transport/api/react/use-tree.mdx b/src/pages/docs/ai-transport/api/react/use-tree.mdx
deleted file mode 100644
index 6198cfb595..0000000000
--- a/src/pages/docs/ai-transport/api/react/use-tree.mdx
+++ /dev/null
@@ -1,70 +0,0 @@
----
-title: "useTree"
-meta_description: "Stable structural query callbacks for the AI Transport conversation tree from React."
-meta_keywords: "AI Transport, React, useTree, TreeHandle, getSiblings, getNode, Ably"
-redirect_from:
-  - /docs/ai-transport/api-reference/react/use-tree
----
-
-Provide stable structural query callbacks backed by the transport's conversation tree. These are thin `useCallback` wrappers around the tree's query methods. The hook does **not** re-render on tree changes — use [`useView`](/docs/ai-transport/api/react/use-view) when you want a reactive subscription. Reach for `useTree` when you need to query tree structure inside an event handler or a memoised computation without subscribing to every update.
-
-This hook must be used within a [`TransportProvider`](/docs/ai-transport/api/react/providers#TransportProvider) or a [`ChatTransportProvider`](/docs/ai-transport/api/react/providers#ChatTransportProvider).
-
-<Code>
-```react
-import { useTree } from '@ably/ai-transport/react';
-
-function BranchNav({ messageId }) {
-  const { getSiblings, hasSiblings } = useTree();
-  if (!hasSiblings(messageId)) return null;
-  return <Arrows siblings={getSiblings(messageId)} />;
-}
-```
-</Code>
-
-## Parameters
-
-<Table id='UseTreeProps'>
-
-| Prop | Required | Description | Type |
-| --- | --- | --- | --- |
-| transport | Optional | Transport to read tree structure from. Defaults to the nearest provider when omitted. | `ClientTransport<TEvent, TMessage>` |
-
-</Table>
-
-## Returns
-
-`TreeHandle<TMessage>`
-
-<Table id='TreeHandle'>
-
-| Property | Description | Type |
-| --- | --- | --- |
-| getSiblings | `(msgId: string) => TMessage[]`. Get every sibling message at a fork point, ordered chronologically by serial. | Function |
-| hasSiblings | `(msgId: string) => boolean`. Whether a message has sibling alternatives. | Function |
-| getNode | `(msgId: string) => MessageNode<TMessage> \| undefined`. Get a node by message ID. | Function |
-
-</Table>
-
-The returned callbacks are stable across renders (they are `useCallback`-wrapped), so they are safe to use as dependencies in `useEffect` or `useMemo` without triggering rerun loops.
-
-## Example
-
-<Code>
-```react
-import { useTree, useView } from '@ably/ai-transport/react';
-import { useMemo } from 'react';
-
-function ConversationStats() {
-  const { messages } = useView();
-  const { getSiblings } = useTree();
-
-  const branchCount = useMemo(
-    () => messages.reduce((total, m) => total + getSiblings(m.id).length, 0),
-    [messages, getSiblings],
-  );
-
-  return <span>Total branches: {branchCount}</span>;
-}
-```
-</Code>
diff --git a/src/pages/docs/ai-transport/api/react/use-view.mdx b/src/pages/docs/ai-transport/api/react/use-view.mdx
deleted file mode 100644
index 61495ac96a..0000000000
--- a/src/pages/docs/ai-transport/api/react/use-view.mdx
+++ /dev/null
@@ -1,167 +0,0 @@
----
-title: "useView"
-meta_description: "Subscribe to a paginated, branch-aware view of the AI Transport conversation tree from React."
-meta_keywords: "AI Transport, React, useView, ViewHandle, send, regenerate, edit, conversation, Ably"
-redirect_from:
-  - /docs/ai-transport/api-reference/react/use-view
----
-
-Subscribe to a `View` and return the visible node list with pagination, branch navigation, and write operations. The hook re-renders the component on every view update.
-
-This hook must be used within a [`TransportProvider`](/docs/ai-transport/api/react/providers#TransportProvider) or a [`ChatTransportProvider`](/docs/ai-transport/api/react/providers#ChatTransportProvider).
-
-<Code>
-```react
-import { useView } from '@ably/ai-transport/react';
-
-function Chat() {
-  const { messages, send, loadOlder, hasOlder } = useView({ limit: 30 });
-
-  return (
-    <div>
-      {hasOlder && <button onClick={() => loadOlder()}>Load older</button>}
-      {messages.map((m) => <Message key={m.id} message={m} />)}
-    </div>
-  );
-}
-```
-</Code>
-
-## Parameters
-
-<Table id='UseViewProps'>
-
-| Prop | Required | Description | Type |
-| --- | --- | --- | --- |
-| transport | Optional | Client transport whose default view to subscribe to. Defaults to the nearest provider when omitted. | `ClientTransport<TEvent, TMessage>` or Null |
-| view | Optional | A specific `View` to subscribe to directly. Takes priority over `transport`. | `View<TEvent, TMessage>` or Null |
-| limit | Optional | Maximum number of older messages to load per page. When provided, auto-loads the first page on mount (SWR-style). | Number |
-| skip | Optional | When `true`, skip all subscriptions and return an empty handle. | Boolean |
-
-</Table>
-
-## Returns
-
-`ViewHandle<TEvent, TMessage>`
-
-<Table id='ViewHandle'>
-
-| Property | Description | Type |
-| --- | --- | --- |
-| messages | The visible domain messages along the selected branch. | `TMessage[]` |
-| nodes | Visible conversation nodes along the selected branch. | `MessageNode<TMessage>[]` |
-| hasOlder | Whether older messages can be revealed via `loadOlder`. | Boolean |
-| loading | Whether a page load is currently in progress. | Boolean |
-| loadError | Set when the most recent `loadOlder` failed; cleared on the next successful load. | `Ably.ErrorInfo` or Undefined |
-| loadOlder | See [Load older messages](#loadOlder) below. | Function |
-| select | See [Select a sibling](#select). | Function |
-| getSelectedIndex | See [Get the selected sibling index](#getSelectedIndex). | Function |
-| getSiblings | See [Get sibling messages](#getSiblings). | Function |
-| hasSiblings | See [Check for siblings](#hasSiblings). | Function |
-| getNode | See [Get a node by ID](#getNode). | Function |
-| send | See [Send messages](#send). | Function |
-| regenerate | See [Regenerate a response](#regenerate). | Function |
-| edit | See [Edit a user message](#edit). | Function |
-| update | See [Update an existing message](#update). | Function |
-
-</Table>
-
-## Load older messages <a id="loadOlder"/>
-
-<MethodSignature>{`loadOlder: () => Promise<void>`}</MethodSignature>
-
-Load older messages into the view. No-op if already loading. On failure, `loadError` is set; on success, `loadError` is cleared.
-
-## Select a sibling <a id="select"/>
-
-<MethodSignature>{`select: (msgId: string, index: number) => void`}</MethodSignature>
-
-Select a sibling at a fork point by index. Updates this view's branch selection and triggers a re-render with the new branch visible.
-
-## Get the selected sibling index <a id="getSelectedIndex"/>
-
-<MethodSignature>{`getSelectedIndex: (msgId: string) => number`}</MethodSignature>
-
-The index of the currently selected sibling at a fork point.
-
-## Get sibling messages <a id="getSiblings"/>
-
-<MethodSignature>{`getSiblings: (msgId: string) => TMessage[]`}</MethodSignature>
-
-Every sibling message at a fork point, ordered chronologically by serial.
-
-## Check for siblings <a id="hasSiblings"/>
-
-<MethodSignature>{`hasSiblings: (msgId: string) => boolean`}</MethodSignature>
-
-Whether a message has sibling alternatives. Use this to decide whether to render branch-navigation arrows.
-
-## Get a node by ID <a id="getNode"/>
-
-<MethodSignature>{`getNode: (msgId: string) => MessageNode<TMessage> | undefined`}</MethodSignature>
-
-The node for a given message ID, or `undefined` if the tree has no such node.
-
-## Send messages <a id="send"/>
-
-<MethodSignature>{`send: (messages: TMessage | TMessage[], options?: SendOptions) => Promise<ActiveTurn<TEvent>>`}</MethodSignature>
-
-Send one or more user messages and start a new turn. The parent is auto-computed from this view's selected branch unless overridden in `options`.
-
-## Regenerate a response <a id="regenerate"/>
-
-<MethodSignature>{`regenerate: (messageId: string, options?: SendOptions) => Promise<ActiveTurn<TEvent>>`}</MethodSignature>
-
-Regenerate an assistant message. Creates a new turn that forks the target message with no new user messages.
-
-## Edit a user message <a id="edit"/>
-
-<MethodSignature>{`edit: (messageId: string, newMessages: TMessage | TMessage[], options?: SendOptions) => Promise<ActiveTurn<TEvent>>`}</MethodSignature>
-
-Edit a user message and start a new turn from that point. The original message and its descendants remain in the tree as a separate branch.
-
-## Update an existing message <a id="update"/>
-
-<MethodSignature>{`update: (msgId: string, events: TEvent[], options?: SendOptions) => Promise<ActiveTurn<TEvent>>`}</MethodSignature>
-
-Update an existing message in place and start a continuation turn. Commonly used for delivering client-executed tool results.
-
-See [`View`](/docs/ai-transport/api/javascript/client-transport#View) for the full method semantics and the [`ActiveTurn`](/docs/ai-transport/api/javascript/client-transport#ActiveTurn) shape returned by the write operations. Each returned promise rejects with an [`ErrorInfo`](/docs/ai-transport/api/errors#errorinfo) on failure.
-
-## Example
-
-<Code>
-```react
-import { useView } from '@ably/ai-transport/react';
-import { useState } from 'react';
-
-function Chat() {
-  const { messages, hasOlder, loadOlder, send, regenerate } = useView({ limit: 30 });
-  const [input, setInput] = useState('');
-
-  const onSubmit = async (e) => {
-    e.preventDefault();
-    if (!input.trim()) return;
-    const text = input;
-    setInput('');
-    await send({ id: crypto.randomUUID(), role: 'user', parts: [{ type: 'text', text }] });
-  };
-
-  return (
-    <div>
-      {hasOlder && <button onClick={() => loadOlder()}>Load older</button>}
-      {messages.map((m) => (
-        <div key={m.id}>
-          <strong>{m.role}:</strong> <Parts parts={m.parts} />
-          {m.role === 'assistant' && <button onClick={() => regenerate(m.id)}>Regenerate</button>}
-        </div>
-      ))}
-      <form onSubmit={onSubmit}>
-        <input value={input} onChange={(e) => setInput(e.target.value)} />
-        <button type="submit">Send</button>
-      </form>
-    </div>
-  );
-}
-```
-</Code>
diff --git a/src/pages/docs/ai-transport/api/react/vercel/chat-transport-provider.mdx b/src/pages/docs/ai-transport/api/react/vercel/chat-transport-provider.mdx
new file mode 100644
index 0000000000..2d9c5cab5f
--- /dev/null
+++ b/src/pages/docs/ai-transport/api/react/vercel/chat-transport-provider.mdx
@@ -0,0 +1,155 @@
+---
+title: "ChatTransportProvider"
+meta_description: "API reference for ChatTransportProvider: the Vercel React entry point that wraps a ClientSession in a ChatTransport bound to UIMessageCodec."
+meta_keywords: "AI Transport, React, ChatTransportProvider, ChatTransport, ClientSession, useChat, Vercel AI SDK"
+redirect_from:
+  - /docs/ai-transport/api-reference/chat-transport-provider
+  - /docs/ai-transport/api/react/chat-transport-provider
+---
+
+`ChatTransportProvider` is the entry point for the Vercel React integration. It wraps children in a `ClientSessionProvider` bound to `UIMessageCodec`, constructs a [`ChatTransport`](/docs/ai-transport/api/javascript/vercel/chat-transport) over that session, and exposes both through React context. Descendants call [`useChatTransport`](/docs/ai-transport/api/react/vercel/use-chat-transport) to get the transport (and the session) for Vercel `useChat`.
+
+The Realtime client is read from the surrounding `<AblyProvider>`. The session is created once on first render. The chat transport is recreated only when `chatOptions` changes.
+
+<Code>
+```javascript
+import * as Ably from 'ably';
+import { AblyProvider } from 'ably/react';
+import { ChatTransportProvider } from '@ably/ai-transport/vercel/react';
+
+const ably = new Ably.Realtime({ authUrl: '/api/auth/token' });
+
+function App() {
+  return (
+    <AblyProvider client={ably}>
+      <ChatTransportProvider channelName="conversation-42">
+        <Chat />
+      </ChatTransportProvider>
+    </AblyProvider>
+  );
+}
+```
+</Code>
+
+`ChatTransportProvider` also re-exports the Vercel-baked core hooks (`useClientSession`, `useView`, `useTree`, `useCreateView`, `useAblyMessages`, and the underlying `ClientSessionProvider`) from the same entry point, all pre-bound to the Vercel `TInput` / `TOutput` / `TProjection` / `TMessage` types.
+
+## Props <a id="props"/>
+
+`ChatTransportProviderProps` extends [`ClientSessionProviderProps`](/docs/ai-transport/api/react/core/providers#client-session-provider-props) with the `codec` field omitted (always `UIMessageCodec`) and adds four transport-owned options for the agent-invocation POST.
+
+<Table id='ChatTransportProviderProps'>
+
+| Property | Description | Type |
+| --- | --- | --- |
+| channelName | The channel the session subscribes to. Used as the registry key for nested providers. | String |
+| api | Endpoint the chat transport POSTs the invocation to, to wake the agent. Defaults to `/api/chat`. | String |
+| credentials | Fetch credentials mode for the invocation POST. Set to `'include'` for cookie-based cross-origin auth. | `RequestCredentials` |
+| fetch | Custom fetch implementation for the invocation POST. Defaults to `globalThis.fetch`. | `typeof globalThis.fetch` |
+| chatOptions | Hooks for customising chat request construction (for example `prepareSendMessagesRequest`). Must be stable across renders; wrap in `useMemo` or define outside the component. A new object reference recreates the `ChatTransport`. | <Table id='ChatTransportOptions'/> |
+| clientId | The client's identity, used as the Ably publisher `clientId` on everything the session publishes. | String |
+| messages | Initial messages to seed the conversation tree with. | `UIMessage[]` |
+| logger | Logger instance for diagnostic output. | `Logger` |
+| children | Descendant components that consume the chat transport via [`useChatTransport`](/docs/ai-transport/api/react/vercel/use-chat-transport). | `ReactNode` |
+
+</Table>
+
+<Table id='ChatTransportOptions' hidden>
+
+| Property | Description | Type |
+| --- | --- | --- |
+| prepareSendMessagesRequest | Hook called before each `sendMessages` request. Returns `{ body?, headers? }` to merge into the agent-invocation POST. The run's invocation identifiers always take precedence over the returned body. | `(context: SendMessagesRequestContext) => { body?, headers? }` |
+
+</Table>
+
+## Behaviour <a id="behaviour"/>
+
+`useChatTransport` and the re-exported `useClientSession` / `useView` / `useTree` / `useCreateView` / `useAblyMessages` find the nearest provider in the tree. Pass `channelName` to look up a specific provider by name when nesting multiple.
+
+The underlying `ClientSession` is created once on first render via `useRef`, and `connect()` runs from a `useEffect`. The session is closed when the provider truly unmounts.
+
+The `ChatTransport` itself is not closed on unmount: its `close()` delegates to `ClientSession.close()`, which the inner `ClientSessionProvider` already calls. Auto-closing here would double-close in React Strict Mode.
+
+If `createClientSession` throws, the error surfaces via [`useClientSession.sessionError`](/docs/ai-transport/api/react/core/use-client-session#returns) and [`useChatTransport.chatTransportError`](/docs/ai-transport/api/react/vercel/use-chat-transport). The component tree does not crash.
+
+## Nest providers for multiple sessions <a id="nest"/>
+
+Nest providers with distinct `channelName` values to manage more than one chat in the same tree. Each provider merges its slot into the parent record so descendants can address any registered session by name.
+
+<Code>
+```javascript
+<ChatTransportProvider channelName="ai:main">
+  <ChatTransportProvider channelName="ai:aux">
+    <App />
+  </ChatTransportProvider>
+</ChatTransportProvider>
+```
+</Code>
+
+Inside `App`:
+
+<Code>
+```javascript
+import { useChatTransport } from '@ably/ai-transport/vercel/react';
+
+function App() {
+  const main = useChatTransport({ channelName: 'ai:main' });
+  const aux = useChatTransport({ channelName: 'ai:aux' });
+  // ...
+}
+```
+</Code>
+
+## Example <a id="example"/>
+
+Full Vercel chat wiring using `ChatTransportProvider`, `useChatTransport`, and `useChat` from `@ai-sdk/react`.
+
+<Code>
+```javascript
+'use client';
+
+import { useEffect, useState } from 'react';
+import * as Ably from 'ably';
+import { AblyProvider } from 'ably/react';
+import { ChatTransportProvider, useChatTransport } from '@ably/ai-transport/vercel/react';
+import { useChat } from '@ai-sdk/react';
+
+function Providers({ children }) {
+  const [client, setClient] = useState(null);
+
+  useEffect(() => {
+    const ably = new Ably.Realtime({ authUrl: '/api/auth/token', clientId: 'user' });
+    setClient(ably);
+    return () => ably.close();
+  }, []);
+
+  if (!client) return null;
+  return <AblyProvider client={client}>{children}</AblyProvider>;
+}
+
+function Chat() {
+  const { chatTransport } = useChatTransport();
+  const { messages, sendMessage, status, stop } = useChat({ transport: chatTransport });
+
+  return (
+    <div>
+      {messages.map((m) => (
+        <div key={m.id}>{m.role}: {m.parts.map((p) => p.type === 'text' ? p.text : '').join('')}</div>
+      ))}
+      {status === 'streaming'
+        ? <button type="button" onClick={stop}>Stop</button>
+        : <button type="button" onClick={() => sendMessage({ text: 'Hello' })}>Send</button>}
+    </div>
+  );
+}
+
+export default function Page() {
+  return (
+    <Providers>
+      <ChatTransportProvider channelName="my-chat">
+        <Chat />
+      </ChatTransportProvider>
+    </Providers>
+  );
+}
+```
+</Code>
diff --git a/src/pages/docs/ai-transport/api/react/vercel/use-chat-transport.mdx b/src/pages/docs/ai-transport/api/react/vercel/use-chat-transport.mdx
new file mode 100644
index 0000000000..37783206df
--- /dev/null
+++ b/src/pages/docs/ai-transport/api/react/vercel/use-chat-transport.mdx
@@ -0,0 +1,113 @@
+---
+title: "useChatTransport"
+meta_description: "Read a ChatTransport and its underlying ClientSession from the nearest ChatTransportProvider in AI Transport."
+meta_keywords: "AI Transport, React, useChatTransport, ChatTransport, ChatTransportProvider, Vercel AI SDK, useChat, Ably"
+redirect_from:
+  - /docs/ai-transport/api-reference/use-chat-transport
+  - /docs/ai-transport/api/react/use-chat-transport
+---
+
+`useChatTransport` reads a [`ChatTransport`](/docs/ai-transport/api/javascript/vercel/chat-transport#chat-transport) and its underlying [`ClientSession`](/docs/ai-transport/api/javascript/core/client-session) from the nearest `ChatTransportProvider`. Pass the returned `chatTransport` to Vercel AI SDK's `useChat({ transport })` and use `session` for everything else (cancel, tree inspection, raw message access).
+
+The hook is a thin context reader; it does not create or manage any session or transport state. When no provider is found or the session failed to construct, the hook returns stubs along with populated `sessionError` and `chatTransportError` so the component can render an error state without an error boundary.
+
+<Code>
+```javascript
+import { useChat } from '@ai-sdk/react';
+import { useChatTransport } from '@ably/ai-transport/vercel/react';
+
+function Chat() {
+  const { chatTransport, chatTransportError } = useChatTransport();
+  const { messages, sendMessage } = useChat({ transport: chatTransport });
+
+  if (chatTransportError) return <ErrorBanner error={chatTransportError} />;
+  return <Conversation messages={messages} onSend={sendMessage} />;
+}
+```
+</Code>
+
+This hook must be used within a `ChatTransportProvider` (exported from `@ably/ai-transport/vercel/react`). The provider wraps the subtree in a `ClientSessionProvider` baked to the Vercel types, so [`useClientSession`](/docs/ai-transport/api/react/core/use-client-session) and the other core hooks work inside the same subtree.
+
+## Parameters <a id="parameters"/>
+
+<Table id='UseChatTransportParameters'>
+
+| Parameter | Required | Description | Type |
+| --- | --- | --- | --- |
+| channelName | optional | Look up a specific provider by channel name. Omit to use the innermost `ChatTransportProvider` in the tree. | String |
+| skip | optional | When `true`, return stubs that throw on any access instead of reading from context. | Boolean |
+
+</Table>
+
+## Returns <a id="returns"/>
+
+<Table id='ChatTransportHandle'>
+
+| Property | Description | Type |
+| --- | --- | --- |
+| session | The underlying client session. A throwing stub when `skip` is `true`, when no matching provider was found, or when session construction failed. | `ClientSession<VercelInput, VercelOutput, VercelProjection, UIMessage>` |
+| chatTransport | The chat transport adapter to pass to Vercel's `useChat`. A throwing stub in the same conditions as `session`. | `ChatTransport` |
+| sessionError | Set when no matching `ClientSessionProvider` was found or when session construction failed, and `skip` is `false`. | `Ably.ErrorInfo` or Undefined |
+| chatTransportError | Set when no matching `ChatTransportProvider` was found or when session construction failed, and `skip` is `false`. | `Ably.ErrorInfo` or Undefined |
+
+</Table>
+
+## Use the chat transport <a id="chat-transport"/>
+
+<MethodSignature>{`chatTransport: ChatTransport`}</MethodSignature>
+
+The [`ChatTransport`](/docs/ai-transport/api/javascript/vercel/chat-transport#chat-transport) adapter. Pass it to Vercel AI SDK's `useChat({ transport })`. It exposes `sendMessages`, `reconnectToStream`, `close`, `streaming`, and `onStreamingChange`. The companion [`useMessageSync`](/docs/ai-transport/api/react/vercel/use-message-sync) hook uses the streaming flag to gate `setMessages` calls during active own-run streams.
+
+## Use the session <a id="session"/>
+
+<MethodSignature>{`session: ClientSession<VercelInput, VercelOutput, VercelProjection, UIMessage>`}</MethodSignature>
+
+The underlying [`ClientSession`](/docs/ai-transport/api/javascript/core/client-session). Use it for operations the chat transport does not expose, for example `session.cancel(runId)` from a stop button, or `session.tree` for branch inspection. The same session is available via [`useClientSession`](/docs/ai-transport/api/react/core/use-client-session) inside the provider's subtree.
+
+## Read error state <a id="errors"/>
+
+`chatTransportError` is set when no matching `ChatTransportProvider` is found, when session construction failed, and `skip` is `false`. `sessionError` is set under the same conditions. Both are `undefined` when the handle resolved cleanly.
+
+Post-construction errors (for example send failures or channel continuity loss) reach you via `session.on('error', ...)` or via the `onError` parameter on [`useClientSession`](/docs/ai-transport/api/react/core/use-client-session#parameters).
+
+## Example <a id="example"/>
+
+A chat component wired through `useChat` with a stop button that cancels the active Run through the underlying session.
+
+<Code>
+```javascript
+import { useChat } from '@ai-sdk/react';
+import { useChatTransport, useMessageSync } from '@ably/ai-transport/vercel/react';
+
+function Chat() {
+  const { session, chatTransport, chatTransportError } = useChatTransport();
+  const { messages, setMessages, sendMessage, status } = useChat({
+    transport: chatTransport,
+  });
+
+  useMessageSync({ setMessages });
+
+  if (chatTransportError) return <ErrorBanner error={chatTransportError} />;
+
+  return (
+    <>
+      {messages.map((m) => <Message key={m.id} message={m} />)}
+      <Composer
+        disabled={status !== 'ready'}
+        onSubmit={(text) => sendMessage({ role: 'user', parts: [{ type: 'text', text }] })}
+      />
+      {status === 'streaming' && (
+        <button
+          onClick={() => {
+            const activeRun = session.view.runs().find((r) => r.status === 'active');
+            if (activeRun) void session.cancel(activeRun.runId);
+          }}
+        >
+          Stop
+        </button>
+      )}
+    </>
+  );
+}
+```
+</Code>
diff --git a/src/pages/docs/ai-transport/api/react/vercel/use-message-sync.mdx b/src/pages/docs/ai-transport/api/react/vercel/use-message-sync.mdx
new file mode 100644
index 0000000000..487f204005
--- /dev/null
+++ b/src/pages/docs/ai-transport/api/react/vercel/use-message-sync.mdx
@@ -0,0 +1,95 @@
+---
+title: "useMessageSync"
+meta_description: "Wire AI Transport view updates into Vercel useChat's setMessages from React."
+meta_keywords: "AI Transport, React, useMessageSync, useChat, setMessages, Vercel AI SDK, multi-device, Ably"
+redirect_from:
+  - /docs/ai-transport/api-reference/use-message-sync
+  - /docs/ai-transport/api/react/use-message-sync
+---
+
+`useMessageSync` subscribes to view updates and syncs them into Vercel AI SDK's `useChat` overlay through the `setMessages` updater. It is how observer clients (other tabs, other devices) catch up with messages that arrive on the channel rather than from `useChat`'s own `sendMessage` calls.
+
+During an active own-run stream the sync is gated so it does not race the AI SDK's internal `write()` and produce an ID mismatch. When the stream ends, the gate opens and the next view update is merged in. Tool resolutions in the local overlay that have not yet echoed back through the channel are preserved during the merge.
+
+<Code>
+```javascript
+import { useChat } from '@ai-sdk/react';
+import { useChatTransport, useMessageSync } from '@ably/ai-transport/vercel/react';
+
+function Chat() {
+  const { chatTransport } = useChatTransport();
+  const { messages, setMessages, sendMessage } = useChat({ transport: chatTransport });
+
+  useMessageSync({ setMessages });
+
+  return <Conversation messages={messages} onSend={sendMessage} />;
+}
+```
+</Code>
+
+This hook must be used within a `ChatTransportProvider` (exported from `@ably/ai-transport/vercel/react`) unless `channelName` resolves to a different registered provider.
+
+## Parameters <a id="parameters"/>
+
+<Table id='UseMessageSyncParameters'>
+
+| Parameter | Required | Description | Type |
+| --- | --- | --- | --- |
+| setMessages | required | The `setMessages` updater function from `useChat()`. Called with an updater that returns the next overlay. | `(updater: (prev: UIMessage[]) => UIMessage[]) => void` |
+| channelName | optional | Channel name of the `ChatTransportProvider` to observe. Omit to use the nearest provider. | String |
+| skip | optional | When `true`, skip all subscriptions. | Boolean |
+
+</Table>
+
+## Returns <a id="returns"/>
+
+`void`. The hook subscribes for its side effects and cleans up on unmount.
+
+## How the sync works <a id="how"/>
+
+The hook does two things:
+
+- Subscribes to the `ChatTransport`'s `onStreamingChange` event. While `streaming` is `true` (own-run stream consumed by `useChat`), the gate is closed and no `setMessages` calls are made.
+- Subscribes to the underlying `View`'s `'update'` event. When the view changes and the gate is open, the hook calls `setMessages` with an updater that merges the view's messages into the overlay.
+
+The merge is per message, not a wholesale replace. For each assistant message, the merge preserves any `dynamic-tool` part in the overlay whose state is `output-available`, `output-error`, `approval-responded`, or `output-denied` while the tree's part is still in an unresolved state. That keeps local `addToolResult` and `addToolApprovalResponse` actions visible until the channel echo lands.
+
+## When to use it <a id="when-to-use"/>
+
+Use `useMessageSync` whenever you mount a `ChatTransportProvider` and render messages through `useChat`. Without it, observer tabs or devices that did not originate a Run never see its messages because `useChat`'s state is local to each `useChat` instance.
+
+If you render messages directly from [`useView`](/docs/ai-transport/api/react/core/use-view) instead of from `useChat`, you do not need `useMessageSync`; `useView` already reflects the view state.
+
+## Example <a id="example"/>
+
+A complete Vercel-React chat with sync wired in. A second browser tab pointing at the same `channelName` sees every message as soon as it arrives on the channel.
+
+<Code>
+```javascript
+import { useChat } from '@ai-sdk/react';
+import { useChatTransport, useMessageSync } from '@ably/ai-transport/vercel/react';
+
+function Chat() {
+  const { chatTransport, chatTransportError } = useChatTransport();
+  const { messages, setMessages, sendMessage, status } = useChat({
+    transport: chatTransport,
+  });
+
+  useMessageSync({ setMessages });
+
+  if (chatTransportError) return <ErrorBanner error={chatTransportError} />;
+
+  return (
+    <>
+      {messages.map((m) => <Message key={m.id} message={m} />)}
+      <Composer
+        disabled={status !== 'ready'}
+        onSubmit={(text) =>
+          sendMessage({ role: 'user', parts: [{ type: 'text', text }] })
+        }
+      />
+    </>
+  );
+}
+```
+</Code>
diff --git a/src/pages/docs/ai-transport/concepts/authentication.mdx b/src/pages/docs/ai-transport/concepts/authentication.mdx
index 192e139811..f636df4848 100644
--- a/src/pages/docs/ai-transport/concepts/authentication.mdx
+++ b/src/pages/docs/ai-transport/concepts/authentication.mdx
@@ -1,273 +1,107 @@
 ---
 title: "Authentication"
 meta_description: "Understand how authentication works in Ably AI Transport: Ably token auth for channel access, HTTP headers for server endpoints, and cancel authorization."
-meta_keywords: "AI Transport, authentication, token auth, cancel authorization, HTTP headers, credentials"
-intro: "AI Transport authenticates at three layers: an Ably token for the channel, HTTP headers for the server endpoint, and a server-side hook that authorises cancel signals."
+meta_keywords: "AI Transport, authentication, token auth, cancel authorization, HTTP headers, credentials, capabilities"
+intro: "AI Transport authenticates at three layers: an Ably token for the channel, HTTP credentials for the agent endpoint, and a server-side hook that authorises cancel signals."
 redirect_from:
   - /docs/ai-transport/how-it-works/authentication
   - /docs/ai-transport/sessions-identity/identifying-users-and-agents
 ---
 
-Authentication in AI Transport operates at three levels: Ably token authentication for channel access, HTTP headers for server endpoint authorization, and cancel authorization for controlling who can cancel turns.
+Authentication in AI Transport operates at three levels: Ably token authentication for channel access, HTTP credentials for agent endpoint authorisation, and cancel authorisation for controlling who can stop a Run. Each layer is independent and addresses a different trust boundary.
 
-## Authentication flow <a id="auth-flow"/>
-
-1. Your auth server authenticates the user.
-2. Your auth server issues an Ably-compatible token (JWT format is recommended for most apps).
-3. The client SDK fetches tokens with `authCallback` and refreshes them automatically before expiry.
-4. The authenticated Pub/Sub client provides channels to AI Transport via `useChannel` or `channels.get`.
-
-<Aside data-type='important'>
-Never use API keys in client-side code. API keys do not expire and are not suitable for untrusted clients.
-</Aside>
-
-## Server setup <a id="server-setup"/>
-
-Create an endpoint that validates user-provided credentials and returns JWTs with the appropriate AI Transport capabilities:
-
-<Code>
-```javascript
-// Server-side JWT with AI Transport capabilities
-import jwt from 'jsonwebtoken';
-
-const [keyName, keySecret] = process.env.ABLY_API_KEY.split(':');
-
-const ablyJwt = jwt.sign(
-  {
-    'x-ably-capability': JSON.stringify({
-      // Only allow access to a specific conversation channel
-      'your-conversation': ['publish', 'subscribe', 'history'],
-    }),
-    'x-ably-clientId': userId,
-  },
-  keySecret,
-  { algorithm: 'HS256', keyid: keyName, expiresIn: '1h' }
-);
-```
-</Code>
+For the practical setup (signing tokens, wiring `authCallback`, securing the agent POST), see [Set up authentication](/docs/ai-transport/getting-started/authentication).
 
-## Client setup <a id="client-setup"/>
+## The three layers <a id="layers"/>
 
-<Code>
-```javascript
-import * as Ably from 'ably';
-
-const realtimeClient = new Ably.Realtime({
-  authCallback: async (tokenParams, callback) => {
-    try {
-      const response = await fetch('/api/ably-token', { credentials: 'include' });
-      if (!response.ok) throw new Error('Auth failed');
-      const jwt = await response.text();
-      callback(null, jwt);
-    } catch (error) {
-      callback(error, null);
-    }
-  },
-});
-
-const channel = realtimeClient.channels.get('your-conversation');
-```
-
-```react
-'use client'
-
-import { useEffect, useState } from 'react';
-import * as Ably from 'ably';
-import { AblyProvider } from 'ably/react';
-import { TransportProvider, useClientTransport } from '@ably/ai-transport/react';
-import { UIMessageCodec } from '@ably/ai-transport/vercel';
-
-// 1. Create an authenticated Ably client and wrap your app
-export function Providers({ children }) {
-  const [client, setClient] = useState(null);
-
-  useEffect(() => {
-    const ably = new Ably.Realtime({
-      authCallback: async (_tokenParams, callback) => {
-        try {
-          const response = await fetch('/api/ably-token', { credentials: 'include' });
-          callback(null, await response.text());
-        } catch (err) {
-          callback(err instanceof Error ? err.message : String(err), null);
-        }
-      },
-    });
-    setClient(ably);
-    return () => ably.close();
-  }, []);
-
-  if (!client) return null;
-  return <AblyProvider client={client}>{children}</AblyProvider>;
-}
-
-// 2. Wrap with TransportProvider, then access the transport inside
-function App({ conversationId }) {
-  return (
-    <TransportProvider channelName={conversationId} codec={UIMessageCodec}>
-      <Chat conversationId={conversationId} />
-    </TransportProvider>
-  );
-}
-
-function Chat({ conversationId }) {
-  const { transport, transportError } = useClientTransport({ channelName: conversationId });
-  // ...
-}
-```
-</Code>
-
-<Aside data-type='note'>
-AI Transport uses `clientId` throughout the SDK to identify who started a turn, who is sending messages, and who is requesting cancellation. Set the client ID in the Ably token to ensure it is verified by the Ably service and cannot be spoofed.
-</Aside>
+| Layer | What it protects | How it works |
+| --- | --- | --- |
+| Ably token | Channel publish, subscribe, history, presence. | Your server signs a short-lived JWT that names the user's `clientId` and capabilities. The client SDK fetches it via `authCallback` and refreshes before expiry. |
+| Agent endpoint | The HTTP POST that wakes the agent. | Your application's normal endpoint auth: cookies, bearer tokens, signed headers. Carries no AI-Transport-specific semantics. |
+| Cancel authorisation | Who can stop a Run. | An `onCancel` hook on the agent's `RunRuntime`. The agent inspects the cancel sender and accepts or rejects. |
 
-For more details, see [token authentication](/docs/auth/token), [capabilities](/docs/auth/capabilities), and [identified clients](/docs/auth/identified-clients).
+The Ably token controls *what can land on the channel*. The agent endpoint auth controls *who can trigger a Run*. Cancel authorisation controls *who can stop one that's already running*. Different concerns, separately enforced.
 
-## Enable message updates and deletes <a id="enable-updates-deletes"/>
+## Authentication flow <a id="auth-flow"/>
 
-AI Transport requires the *Message annotations, updates, deletes, and appends* channel rule to be enabled on the channel namespace used for conversations. Without this rule, the transport cannot function correctly.
+1. Your auth server authenticates the user.
+2. Your auth server issues an Ably-compatible token (JWT format is recommended for most apps).
+3. The client SDK fetches tokens through `authCallback` and refreshes them automatically before expiry.
+4. The authenticated Ably Realtime client provides channels to AI Transport via the session providers.
 
 <Aside data-type='important'>
-When message updates and deletes are enabled, messages are [persisted](/docs/storage-history/storage#all-message-persistence) regardless of whether or not persistence is enabled, in order to support the feature. This increases your usage, since [Ably charges for persisting messages](https://faqs.ably.com/how-does-ably-count-messages).
+Never use API keys in client-side code. API keys do not expire and are not suitable for untrusted clients.
 </Aside>
 
-<Tabs>
-<Tab value="dashboard" label="Dashboard">
-
-In your app [settings](https://ably.com/accounts/any/apps/any/settings):
-
-1. Click **Add new rule**.
-2. Enter the channel name or namespace on which to enable message updates and deletes.
-3. Check **Message annotations, updates, deletes, and appends**.
-4. Click **Create rule** to save.
-
-</Tab>
-<Tab value="control-api" label="Control API">
-
-Create a rule with updates and deletes enabled using the Control API by sending a `POST` request to [`/apps/{app_id}/namespaces`](/docs/api/control-api):
-
-<Code>
-```shell
-curl -X POST https://control.ably.net/v1/apps/{APP_ID}/namespaces \
-  -H "Authorization: Bearer {ACCESS_TOKEN}" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "id": "my-namespace",
-    "mutableMessages": true
-  }'
-```
-</Code>
-
-</Tab>
-<Tab value="cli" label="Ably CLI">
-
-Use the [Ably CLI](/docs/platform/tools/cli) to create a rule with updates and deletes enabled:
-
-<Code>
-```shell
-ably apps rules create \
-  --name "my-namespace" \
-  --mutable-messages
-```
-</Code>
-
-Run `ably apps rules create --help` for a full list of available options.
-
-</Tab>
-</Tabs>
-
 ## AI Transport capabilities <a id="capabilities"/>
 
-Capabilities are permissions that control what operations a client can perform. When you create a token for an AI Transport user, specify which capabilities they have:
+Capabilities are permissions on the Ably channel. When you issue a token for an AI Transport user, the capability claim names which operations they can perform on which channels.
 
 | Feature | Required capabilities |
 |---------|----------------------|
 | Send user messages to channel | `publish` |
 | Receive streamed tokens | `subscribe` |
 | Replay history on reconnect | `subscribe`, `history` |
-| Cancel a turn | `publish` |
+| Cancel a Run | `publish` |
 | All AI Transport features | `publish`, `subscribe`, `history` |
 
+A token that's missing a capability fails silently at the operation site, not at construction. Capability mismatches are one of the most common setup mistakes; see [troubleshooting: capability or token scope mismatch](/docs/ai-transport/troubleshooting#capability-mismatch).
+
 ## Channel-scoped capabilities <a id="scoped-capabilities"/>
 
-You can scope capabilities to specific conversation channels, a namespace of channels, or all channels:
+Capabilities are keyed by channel name pattern. The same token can grant different operations on different channels:
+
+* `my-conversation`: a specific conversation channel.
+* `conversations:*`: all channels in the `conversations:` namespace.
+* `*`: all channels.
 
-* `my-conversation` - a specific conversation channel
-* `conversations:*` - all channels in the `conversations:` namespace
-* `*` - all channels
+Scope tokens to the smallest channel set the user needs. A user's token granting access to one conversation should name that conversation, not the whole namespace.
 
 ## Token lifecycle and permission updates <a id="token-lifecycle"/>
 
-- With `authCallback` or `authUrl`, token refresh is automatic and handled by the SDK.
-- To change a user's capabilities during an active session, issue a new token from your auth server and re-authenticate:
+- With `authCallback` or `authUrl`, token refresh is automatic. The SDK fetches a new token before the current one expires.
+- To change a user's capabilities mid-session, issue a new token from your auth server and re-authenticate the client:
 
 <Code>
 ```javascript
-// Re-authenticate to pick up updated capabilities
 await realtimeClient.auth.authorize();
 ```
 </Code>
 
 - To immediately remove access, [revoke issued tokens](/docs/auth/revocation).
-- If your capability JSON is too large for JWT or must remain confidential, use native [Ably Tokens](/docs/auth/token/ably-tokens).
+- If your capability JSON is too large for a JWT claim, or must remain confidential, use native [Ably Tokens](/docs/auth/token/ably-tokens) instead.
 
-## Server endpoint authentication <a id="server-auth"/>
+## Agent endpoint authentication <a id="server-auth"/>
 
-When the client sends user messages, it makes an HTTP POST to the server endpoint. `TransportProvider` accepts two props for authenticating these requests:
+The HTTP POST that wakes the agent is a separate request from anything on the Ably channel. It carries application credentials (a session cookie, a bearer token, or whatever your endpoint normally expects). The Ably token does not authenticate this POST; the agent endpoint authenticates it through your own application auth.
 
-Set `headers` to attach static or dynamic HTTP headers to every POST:
+On the core flow, the application owns the POST and sets credentials in its `fetch` call. On the Vercel flow, [`ChatTransportProvider`](/docs/ai-transport/api/react/vercel/chat-transport-provider) accepts a `credentials` prop and a `chatOptions.prepareSendMessagesRequest` hook that returns `{ body?, headers? }` per request, which the transport merges into every invocation POST.
 
-<Code>
-```javascript
-<TransportProvider
-  channelName={conversationId}
-  codec={UIMessageCodec}
-  headers={() => ({
-    'Authorization': `Bearer ${getAuthToken()}`,
-  })}
->
-  <Chat />
-</TransportProvider>
-```
-</Code>
+## Cancel authorisation <a id="cancel-auth"/>
 
-Set `credentials` to control whether cookies are sent with the POST request. This maps directly to the Fetch API `credentials` option. Set to `'include'` if your server uses cookie-based session authentication (for example, NextAuth or `express-session`) and the endpoint is cross-origin. For same-origin requests, the browser sends cookies by default and this option is not needed.
+When a client publishes a cancel signal, the agent decides whether to honour it. The `onCancel` hook on `RunRuntime` receives a `CancelRequest` carrying the raw Ably cancel `message` and the `runId` it targets. Compare the cancel sender's `clientId` against whichever identity your application considers authorised; here, the user identity resolved from the inbound HTTP request:
 
 <Code>
 ```javascript
-<TransportProvider
-  channelName={conversationId}
-  codec={UIMessageCodec}
-  credentials='include'
->
-  <Chat />
-</TransportProvider>
-```
-</Code>
-
-The server endpoint validates these credentials however it normally would: JWT verification, session cookies, or API keys.
-
-## Cancel authorization <a id="cancel-auth"/>
-
-When a client publishes a cancel signal, the server can authorize or reject it. The `onCancel` hook on `NewTurnOptions` receives a `CancelRequest` with the filter, matched turn IDs, and a map of turn owners:
+const userId = await authenticateUser(req);
 
-<Code>
-```javascript
-const turn = transport.newTurn({
-  turnId,
-  clientId,
+const run = session.createRun(invocation, {
+  signal: req.signal,
   onCancel: async (request) => {
-    // Only allow the turn owner to cancel
-    const owner = request.turnOwners.get(request.filter.turnId)
-    return owner === request.message.clientId
+    return request.message.clientId === userId;
   },
-})
+});
 ```
 </Code>
 
-If `onCancel` returns `false`, the cancellation is rejected. If `onCancel` is not provided, all cancel requests are accepted by default.
+Return `true` to allow the cancel (the `abortSignal` fires, the stream closes). Return `false` to reject it (the Run continues). If `onCancel` is not provided, every cancel is accepted.
+
+The Ably token's `clientId` is verified by the Ably service before the cancel reaches the agent, so the `clientId` on the cancel message is trustworthy; the agent can authorise off it without independent verification.
 
 ## Read next <a id="next"/>
 
-- [Getting started with Vercel AI SDK](/docs/ai-transport/getting-started/vercel-ai-sdk): set up authentication in a working app.
-- [Getting started with the Core SDK](/docs/ai-transport/getting-started/core-sdk): set up authentication without a framework wrapper.
-- [Cancellation](/docs/ai-transport/features/cancellation): how cancel signals and authorization work in detail.
+- [Set up authentication](/docs/ai-transport/getting-started/authentication): sign tokens, wire `authCallback`, secure the agent POST.
+- [Enable channel rules](/docs/ai-transport/getting-started/channel-rules): the one-time Ably namespace configuration AI Transport requires.
+- [Cancellation](/docs/ai-transport/features/cancellation): how cancel signals are routed and authorised in detail.
+- [Ably capabilities](/docs/auth/capabilities): the full Ably capability reference.
+- [Identified clients](/docs/auth/identified-clients): how `clientId` is verified by the Ably service.
diff --git a/src/pages/docs/ai-transport/concepts/codecs.mdx b/src/pages/docs/ai-transport/concepts/codecs.mdx
new file mode 100644
index 0000000000..6041871640
--- /dev/null
+++ b/src/pages/docs/ai-transport/concepts/codecs.mdx
@@ -0,0 +1,86 @@
+---
+title: "Codecs"
+meta_description: "Understand codecs in AI Transport: the translation layer between your AI framework's events and Ably's messages."
+meta_keywords: "AI Transport, codec, TInput, TOutput, UserMessage, Regenerate, ToolResult, custom codec, Vercel"
+intro: "A codec translates between your AI framework's events and Ably's messages. The same connection carries a Vercel UIMessage, an OpenAI completion, or a custom domain event without changing the SDK."
+---
+
+A codec is the translation layer between domain-specific message models and Ably's native message primitives. It defines how events in the application's domain (text deltas, tool calls, finish signals, or whatever the domain model requires) are encoded into Ably messages, and how incoming Ably messages are decoded back into domain events.
+
+The codec is an interface, not an implementation. The generic layer of the SDK knows nothing about what the events or messages look like. It operates entirely through the codec contract. A Vercel AI SDK codec translates `UIMessageChunk` events into Ably messages and reassembles them into `UIMessage` objects. A different codec does the same for a different framework, or for a custom domain model.
+
+![Diagram showing the codec encoding and decoding domain events on both sides of the channel](../../../../images/content/diagrams/ait-concepts-codecs.png)
+
+## Understand the codec types <a id="direction"/>
+
+The codec model has two generics that name the direction of travel:
+
+- `TInput extends CodecInputEvent`: anything the client sends to the agent. User messages, regenerate requests, tool results, tool approvals.
+- `TOutput extends CodecOutputEvent`: anything the agent streams back. Text deltas, tool calls, finish signals, framework-specific events.
+
+Each direction has its own wire scope: inputs publish on `ai-input`, outputs publish on `ai-output`. The SDK enforces the distinction at the type level: you can't accidentally publish an output where an input is expected.
+
+The flow on each side is symmetric. The client sends a domain message; the codec wraps it as a `TInput`, encodes it onto the channel, and the agent decodes it back into the same `TInput` shape it can act on. The agent streams `TOutput`s back; the codec encodes each one onto the channel, and the client decodes them and folds them through `codec.fold` into the per-Run `TProjection` that the View renders.
+
+The codec implements the encoder and decoder. The SDK calls them. Custom domain logic (what each event *means*, how to fold them into a projection, how to derive `TMessage[]` from the projection) lives in the codec, not in the SDK.
+
+## Well-known input variants <a id="well-known-variants"/>
+
+The SDK ships a vocabulary of `TInput` variants that show up in every framework. Each variant is a tagged union identified by its `kind` field. A codec must support these so the SDK's higher-level methods (`view.send`, `view.regenerate`, `view.edit`) can call into them without a per-framework adapter:
+
+| Variant | `kind` value | What it triggers |
+| --- | --- | --- |
+| `UserMessage<TMessage>` | `'user-message'` | A fresh user turn. |
+| `Regenerate` | `'regenerate'` | Regenerate an assistant message. |
+| `ToolResult<TPayload>` | `'tool-result'` | Deliver a successful tool result back to the agent. |
+| `ToolResultError<TPayload>` | `'tool-result-error'` | Deliver a tool failure. |
+| `ToolApprovalResponse<TPayload>` | `'tool-approval-response'` | Approve or deny a pending tool call. |
+
+The tool variants carry a codec-defined `payload`; the core knows only the routing (`kind`, `codecMessageId`) and lets the codec own the shape of the payload (for example, the Vercel layer's `{ toolCallId, output }` for `tool-result`).
+
+Codecs implement `createUserMessage(message)` and `createRegenerate(target, parent)` to bridge from the SDK's higher-level methods into well-typed `TInput`s, and optionally `createToolResult`, `createToolResultError`, `createToolApprovalResponse` for the tool variants. Edits go on the wire as a fresh `UserMessage` published with `view.edit` (which routes via the `forkOf` header on the user-message path) rather than a separate variant. Custom codecs can add their own variants on top, picking any `kind` value other than the reserved ones above.
+
+## What the codec layer requires <a id="requires"/>
+
+| Property | Why it matters |
+| --- | --- |
+| Direction-explicit | Inputs and outputs live on separate wire names (`ai-input` / `ai-output`). The type system mirrors this with `TInput` / `TOutput`. Mixing the two would corrupt the stream-append pipeline and the agent's input-event lookup. |
+| Deterministic | Two participants running the same codec over the same channel log produce the same projection. Encoding the same event twice produces equivalent wire messages. Without determinism, multi-device sync wouldn't converge. |
+| Stream-aware | Many `TOutput`s are streamed (token deltas). The encoder must distinguish single-publish messages from append sequences and reconstruct streaming state from Ably's create + append + update lifecycle on decode. |
+| Projection-driven | The codec owns a per-Run `TProjection` (its own opaque state, typically the message list under construction). The SDK folds decoded events through `codec.fold` to keep it up to date; the View materialises rendered messages from each Run's projection via `codec.getMessages(projection)`, which returns `CodecMessage<TMessage>[]` (each pair carries the codec-message-id alongside the domain message). |
+| Header tiering | Codec-specific fields ride under `extras.ai.codec`; transport-level headers (run-id, status, role) ride under `extras.ai.transport`. The codec uses `codecHeaders` and `transportHeaders` on `MessagePayload` / `StreamPayload` to control which tier its fields land in. |
+
+## Write a custom codec <a id="custom"/>
+
+The shape of a minimal custom codec, with full bodies omitted (just the contract):
+
+<Code>
+```javascript
+const myCodec = {
+  init() { return []; },
+  fold(projection, event, meta) {/* ... */},
+  createEncoder(channel, options) {/* ... */},
+  createDecoder() {/* ... */},
+  getMessages(projection) {
+    // Return [{ codecMessageId, message }] pairs so the SDK can correlate
+    // each rendered message back to its wire id.
+    return projection.map((entry) => ({ codecMessageId: entry.codecMessageId, message: entry.message }));
+  },
+  createUserMessage(message) {
+    return { kind: 'user-message', message };
+  },
+  createRegenerate(target, parent) {
+    return { kind: 'regenerate', target, parent };
+  },
+};
+```
+</Code>
+
+Most users don't write a custom codec; the bundled [Vercel `UIMessageCodec`](/docs/ai-transport/api/javascript/vercel/codec) covers the Vercel AI SDK end-to-end. See the [Codec API reference](/docs/ai-transport/api/javascript/core/codec) for the full interface.
+
+## Read next <a id="next"/>
+
+- [Codec API reference](/docs/ai-transport/api/javascript/core/codec): the full `Codec`, `Encoder`, `Decoder` contracts and well-known variant types.
+- [Vercel codec](/docs/ai-transport/api/javascript/vercel/codec): the shipped `UIMessageCodec` for the Vercel AI SDK.
+- [Codec architecture](/docs/ai-transport/internals/codec-architecture): the wire-level encoder/decoder pipeline.
+- [Connections](/docs/ai-transport/concepts/connections): how the codec is bound into every connection.
diff --git a/src/pages/docs/ai-transport/concepts/connections.mdx b/src/pages/docs/ai-transport/concepts/connections.mdx
new file mode 100644
index 0000000000..7fee460c43
--- /dev/null
+++ b/src/pages/docs/ai-transport/concepts/connections.mdx
@@ -0,0 +1,94 @@
+---
+title: "Connections"
+meta_description: "Understand connections in AI Transport: ClientSession and AgentSession instances connect each participant to the shared conversation. Lifecycle, responsibilities, and how multiple participants coexist."
+meta_keywords: "AI Transport, ClientSession, AgentSession, connection, connect, lifecycle, codec, Ably"
+intro: "A connection is one participant's hold on a shared conversation. The SDK names the client-side connection ClientSession and the agent-side AgentSession; both connect, do work, and dispose without owning the conversation itself."
+redirect_from:
+  - /docs/ai-transport/concepts/transport
+  - /docs/ai-transport/how-it-works/transport
+---
+
+A connection handles communication between a participant and the [session](/docs/ai-transport/concepts/sessions). There are two connection types: `ClientSession` for client applications, and `AgentSession` for agent processes. Both subscribe to the channel, encode outgoing events, and decode incoming ones. A pluggable codec bridges your AI framework's events to Ably messages, so the same connection works with any framework without modification.
+
+A connection is not the session. It is one participant's hold on the session. Multiple connections attach to the same session simultaneously, each with its own pagination and branch state, all sharing the same conversation on the channel.
+
+![Diagram showing ClientSession and AgentSession as participant handles on a shared channel](../../../../images/content/diagrams/ait-concepts-connections.png)
+
+## Why connections exist <a id="why-connections"/>
+
+Multiple things need to talk to a session: a user's browser tab, the user's second device, an agent's HTTP handler, an agent's retry process after a serverless cold start. Each one needs to subscribe to the channel, decode messages through the codec, route cancels to the right [Run](/docs/ai-transport/concepts/runs), and tear down cleanly when its work is done, without disrupting the session for anyone else. The connection is the lifecycle-owning object that does all of this.
+
+## Understand the connection types <a id="types"/>
+
+The two connection types differ in what they own and how long they live:
+
+| Connection | Lifetime | Owns | Doesn't own |
+| --- | --- | --- | --- |
+| `ClientSession` | Long-lived (the lifetime of the user's app or tab). | Channel subscription, the read path into the tree, default `view`, cancel publish path. | The channel itself, the Ably client, the conversation state. |
+| `AgentSession` | Typically short-lived (one HTTP handler invocation). | Channel attach for cancel routing, the write path for Run lifecycle events and the streamed response. | Long-lived state, retry coordination across invocations. |
+
+Both expose `connect()`, `close()`, and the SDK's lifecycle gate: methods that publish or subscribe throw `InvalidArgument` until `connect()` resolves.
+
+## What the connection layer requires <a id="requires"/>
+
+| Property | Why it matters |
+| --- | --- |
+| Lifecycle gate | `connect()` separates construction from use. Until it resolves the SDK can't guarantee the channel is attached or that publishes will be delivered. The gate prevents subtle races where a `view.send` lands before the subscription is in place. |
+| Independence | Each connection has its own subscription, branch selections, and pagination window. A second `ClientSession` in another tab doesn't see the first one's branch state. |
+| Cancel routing | Cancels are channel publishes that name a `runId`. Both `ClientSession.cancel(runId)` and the agent's `Run.abortSignal` rely on the connection being attached to the right channel. |
+| Codec binding | The codec is wired into the connection at construction. Switching codecs means a new connection. |
+| Clean teardown | `close()` releases the subscription and clears handlers locally. It does not end Runs on the wire. Active Runs on the channel keep running until the agent ends them. |
+
+## Understand connection lifecycle <a id="lifecycle"/>
+
+A connection moves through four stages. Construct it with `createClientSession` or `createAgentSession`. Call `connect()` to subscribe to the channel. On a `ClientSession`, write through `view.send`, `view.regenerate`, and `view.edit`, cancel through `cancel(runId)`, derive views with `createView()`, and subscribe to non-fatal errors with `on('error', ...)`. Tear it down with `close()`.
+
+`connect()` is the gate. Every operation that touches the channel throws `InvalidArgument` until the connect promise resolves. `connect()` is also idempotent: subsequent calls return the same promise, useful when a component mounts twice or a retry path re-runs initialisation.
+
+## Coexist with other participants <a id="coexist"/>
+
+Several `ClientSession` instances can be open against the same session simultaneously. Each one independently:
+
+- Materialises the tree from the channel (the same tree, on the wire).
+- Selects its own branch via the [`view.selectSibling`](/docs/ai-transport/api/javascript/core/client-session#view) method.
+- Holds its own pagination window over older Runs.
+
+What they share is the channel-backed state. A message one client publishes lands on every other client's tree via the channel subscription. A cancel one client publishes is observed by the agent (and by every other client) through their own subscriptions.
+
+The `AgentSession` is symmetric: an agent process can hold one short-lived `AgentSession` per HTTP invocation, or a long-lived one that serves multiple Runs. Either pattern works because the channel, not the connection, owns the conversation.
+
+## Open a connection <a id="open"/>
+
+A minimal client-side connection:
+
+<Code>
+```javascript
+import * as Ably from 'ably';
+import { createClientSession } from '@ably/ai-transport';
+import { UIMessageCodec } from '@ably/ai-transport/vercel';
+
+const ably = new Ably.Realtime({ authUrl: '/api/auth/token' });
+
+const session = createClientSession({
+  client: ably,
+  channelName: 'conversation-42',
+  codec: UIMessageCodec,
+});
+
+await session.connect();
+// session.view, session.tree, session.cancel(...) are now safe to use
+```
+</Code>
+
+The agent-side mirror. See the [AgentSession reference](/docs/ai-transport/api/javascript/core/agent-session) for the full pattern.
+
+## Bind a codec to the connection <a id="codec"/>
+
+A connection is bound to a codec at construction. The codec is what makes the same connection carry Vercel `UIMessage`, an OpenAI-style payload, or a custom domain shape. See the [Codecs concept](/docs/ai-transport/concepts/codecs) for the model; see the [Codec reference](/docs/ai-transport/api/javascript/core/codec) for the interface.
+
+## Read next <a id="next"/>
+
+- [Sessions](/docs/ai-transport/concepts/sessions): the shared conversation that connections connect to.
+- [Runs](/docs/ai-transport/concepts/runs): the unit of work each connection publishes and observes.
+- [Authentication](/docs/ai-transport/concepts/authentication): how each connection's Ably client gets its credentials.
+- [Codecs](/docs/ai-transport/concepts/codecs): the translation layer bound into every connection.
diff --git a/src/pages/docs/ai-transport/concepts/conversation-tree.mdx b/src/pages/docs/ai-transport/concepts/conversation-tree.mdx
index 872c83a674..8d4e38e332 100644
--- a/src/pages/docs/ai-transport/concepts/conversation-tree.mdx
+++ b/src/pages/docs/ai-transport/concepts/conversation-tree.mdx
@@ -9,6 +9,8 @@ redirect_from:
 
 Every conversation in AI Transport is a tree of messages. Each message has a unique identity and a position in the tree. The tree preserves all paths through the conversation, including edits and regenerations which create a branching tree structure, so that no content is ever lost.
 
+![Diagram showing a branching conversation tree with two independent Views selecting different paths](../../../../images/content/diagrams/ait-concepts-conversation-tree.png)
+
 ## Understand messages <a id="messages"/>
 
 A message is a discrete unit of content in the conversation: a user's input, an assistant's response, a tool call, a tool result. Each message has a unique identity (its message ID) and a position in the tree defined by pointers to parent or sibling messages.
@@ -61,27 +63,27 @@ The view is the surface through which participants interact with the conversatio
 
 ## Work with the tree and views <a id="example"/>
 
-The transport exposes the default view as a property. Iterate the visible messages on the selected branch through `getMessages()`:
+The session exposes the default view as a property. Iterate the visible messages on the selected branch through `getMessages()`; each entry pairs the domain `message` with its `codecMessageId`:
 
 <Code>
 ```javascript
-const view = transport.view;
+const view = session.view;
 
-for (const message of view.getMessages()) {
+for (const { codecMessageId, message } of view.getMessages()) {
   const text = message.parts
     .filter((p) => p.type === 'text')
     .map((p) => p.text)
     .join('');
-  console.log(message.role, text);
+  console.log(codecMessageId, message.role, text);
 }
 ```
 </Code>
 
-Additional views over the same tree are created with `transport.createView()`. The tree behind the view holds every branch; the view selects one path through it. See [conversation branching](/docs/ai-transport/features/branching) for creating branches with edit and regenerate and navigating between siblings.
+Additional views over the same tree are created with `session.createView()`. The tree behind the view holds every branch; the view selects one path through it. See [conversation branching](/docs/ai-transport/features/branching) for creating branches with edit and regenerate and navigating between siblings.
 
 ## Read next <a id="next"/>
 
 - [Sessions](/docs/ai-transport/concepts/sessions): understand the persistent, shared conversation state that the tree belongs to.
-- [Turns](/docs/ai-transport/concepts/turns): understand how agent work is structured within the session.
+- [Runs](/docs/ai-transport/concepts/runs): understand how agent work is structured within the session.
 - [Optimistic updates](/docs/ai-transport/features/optimistic-updates): how messages are inserted locally and reconciled with the published tree.
 - [Conversation branching](/docs/ai-transport/features/branching): understand how branches are created and navigated.
diff --git a/src/pages/docs/ai-transport/concepts/index.mdx b/src/pages/docs/ai-transport/concepts/index.mdx
index 2d0c0d5aae..83139378cb 100644
--- a/src/pages/docs/ai-transport/concepts/index.mdx
+++ b/src/pages/docs/ai-transport/concepts/index.mdx
@@ -1,13 +1,15 @@
 ---
 title: "Concepts"
-meta_description: "Understand the building blocks of AI Transport: sessions, turns, transport, authentication, conversation tree, and infrastructure, and how they relate."
-meta_keywords: "AI Transport, concepts, sessions, turns, transport, codec, conversation tree, infrastructure"
-intro: "These concepts describe how AI Transport works, what the session is and how it's structured."
+meta_description: "Understand the building blocks of AI Transport: sessions, connections, Runs, Invocations, codecs, the conversation tree, authentication, and infrastructure, and how they relate."
+meta_keywords: "AI Transport, concepts, sessions, connections, Runs, Invocations, codec, conversation tree, infrastructure"
+intro: "These concepts describe how AI Transport works, what the session is, and how it's structured."
 ---
 
-AI Transport is built around the following concepts. The session is the durable conversation, the turn is one unit of agent work inside the session, the transport is how a participant connects, the codec translates between your framework and Ably, the conversation tree organises every message and branch, and the infrastructure is the platform that holds it all together at scale.
+AI Transport is built around the following concepts. The session is the durable conversation, connections are how participants attach to it, the Run is one unit of agent work inside the session, the Invocation is the trigger that creates or continues a Run, the codec translates between your framework and Ably, the conversation tree organises every Run and message, and the infrastructure is the platform that holds it all together at scale.
 
-These concepts compose. The session is the anchor: it contains the conversation tree, hosts turns, and is read and written through transports. The transport carries codec-encoded messages over a channel. The infrastructure is what makes any of it reliable across reconnects, regions, and load.
+These concepts compose. The session is the anchor: it contains the conversation tree, hosts Runs, and is read and written through connections. Connections carry codec-encoded messages over a channel. Invocations bridge the client publish and the agent's Run creation. The infrastructure is what makes any of it reliable across reconnects, regions, and load.
+
+![Diagram showing how AI Transport concepts compose around the session, with connections attaching from outside and the conversation tree, Runs, Invocations, codecs, authentication, and infrastructure relating to it](../../../../images/content/diagrams/ait-concepts-overview.png)
 
 ## The session is the state <a id="session"/>
 
@@ -15,33 +17,39 @@ The [session](/docs/ai-transport/concepts/sessions) is the persistent, shared st
 
 Every other concept on this page operates on or within a session.
 
-## A turn is one unit of agent work <a id="turn"/>
+## A connection attaches to the session <a id="connection"/>
+
+A [connection](/docs/ai-transport/concepts/connections) is one participant's hold on the session. `ClientSession` for client applications is long-lived and subscribes to the channel for the duration of the user's app. `AgentSession` for agent processes is typically short-lived and handles one HTTP invocation at a time.
+
+Multiple connections attach to the same session simultaneously and dispose independently.
+
+## A Run is one unit of agent work <a id="run"/>
 
-A [turn](/docs/ai-transport/concepts/turns) is one unit of agent activity inside the session: the user's input, the agent's response, any tool calls, and the final completion. The turn is the level at which you start, observe, and cancel work.
+A [Run](/docs/ai-transport/concepts/runs) is AI Transport's unit of work for one turn: one prompt-response cycle. It has an identity, a lifecycle, and an end reason. The Run is the level at which you start, observe, and cancel work.
 
-A session contains many turns. Turns coexist on the same session and have independent lifecycles.
+A session contains many Runs. Runs coexist on the same session and have independent lifecycles.
 
-## The transport connects you to the session <a id="transport"/>
+## An Invocation triggers a Run <a id="invocation"/>
 
-The [transport](/docs/ai-transport/concepts/transport) is how a participant connects. The client transport is a long-lived object that subscribes to the channel and materialises the session into a tree. The agent transport is short-lived and handles one execution attempt within a turn.
+An [Invocation](/docs/ai-transport/concepts/invocations) is the trigger a client posts to the agent endpoint to start or continue a Run. It carries the `inputEventId` and the session name; run identity is resolved from the triggering input event on the channel.
 
-The transport is not the session. Multiple transports connect to the same session.
+The same Run can be triggered by many Invocations: tool results, regenerates, retries. The agent mints `runId` (for a fresh run) and a fresh `invocationId` per HTTP request, and returns both on the response so the caller can observe them.
 
 ## The codec translates between your framework and Ably <a id="codec"/>
 
-The codec is the boundary between your domain (text deltas, tool calls, finish events for whatever framework you use) and Ably's message primitives. The transport works with any framework that has a codec implementation.
+A [codec](/docs/ai-transport/concepts/codecs) is the boundary between your domain (text deltas, tool calls, finish events for whatever framework you use) and Ably's message primitives. The codec is direction-typed: `TInput` for client-to-agent events, `TOutput` for agent-to-client events.
 
-The codec is documented in detail on the [transport](/docs/ai-transport/concepts/transport#codec) page and in the [codec API reference](/docs/ai-transport/api/javascript/codec).
+The SDK ships a vocabulary of well-known input variants the codec supports so the standard operations (send, regenerate, edit, tool result, tool approval) work across any framework.
 
 ## The conversation tree holds every branch <a id="conversation-tree"/>
 
-The [conversation tree](/docs/ai-transport/concepts/conversation-tree) is how messages are organised inside the session. Every message, including every branch from an edit or regenerate, is preserved as a node in the tree. A view is a linear path through the tree: the conversation as a participant sees it.
+The [conversation tree](/docs/ai-transport/concepts/conversation-tree) is how Runs and messages are organised inside the session. Every Run and every message, including every branch from an edit or regenerate, is preserved as a node in the tree.
 
-The tree is what makes branching, edit, and regenerate work without losing history.
+A view is a linear path through the tree: the conversation as a participant sees it. The tree is what makes branching, edit, and regenerate work without losing history.
 
 ## Authentication runs at three layers <a id="authentication"/>
 
-[Authentication](/docs/ai-transport/concepts/authentication) covers three concerns at once: an Ably token for channel access, HTTP headers for the server endpoint, and a server-side hook that authorises cancel signals.
+[Authentication](/docs/ai-transport/concepts/authentication) covers three concerns at once: an Ably token for channel access, HTTP headers for the agent endpoint, and a server-side hook that authorises cancel signals.
 
 The first two are standard Ably auth; the third is specific to how AI Transport handles cancellation across participants.
 
diff --git a/src/pages/docs/ai-transport/concepts/infrastructure.mdx b/src/pages/docs/ai-transport/concepts/infrastructure.mdx
index 9c4aabe75e..53b6c24b78 100644
--- a/src/pages/docs/ai-transport/concepts/infrastructure.mdx
+++ b/src/pages/docs/ai-transport/concepts/infrastructure.mdx
@@ -58,5 +58,5 @@ See [the SDK directory](/docs/sdks) and [integrations](/docs/integrations) for t
 ## Read next <a id="next"/>
 
 - [Sessions](/docs/ai-transport/concepts/sessions): the durable conversation layer the infrastructure carries.
-- [Transport](/docs/ai-transport/concepts/transport): how the SDK connects your code to a session.
+- [Connections](/docs/ai-transport/concepts/connections): how `ClientSession` and `AgentSession` connect your code to a session.
 - [Going to production](/docs/ai-transport/going-to-production): the production checklist for shipping AI Transport.
diff --git a/src/pages/docs/ai-transport/concepts/invocations.mdx b/src/pages/docs/ai-transport/concepts/invocations.mdx
new file mode 100644
index 0000000000..60367f66de
--- /dev/null
+++ b/src/pages/docs/ai-transport/concepts/invocations.mdx
@@ -0,0 +1,79 @@
+---
+title: "Invocations"
+meta_description: "Understand Invocations in AI Transport: the trigger that mediates between a client publishing input and the agent creating a Run."
+meta_keywords: "AI Transport, Invocation, invocationId, inputEventId, agent endpoint, HTTP POST, durable execution"
+intro: "An Invocation is the trigger a client posts to your agent endpoint to say \"create or continue a Run from this input event.\" Each individual HTTP request is a unique Invocation; one Run can be triggered by many (tool results, regenerates, retries)."
+---
+
+An Invocation is the trigger posted to an agent endpoint to start or continue a [Run](/docs/ai-transport/concepts/runs). It carries the input event identity and the session's channel name in the HTTP POST body so the agent can attach to the right channel and wait for the right input event.
+
+![Diagram showing the channel content path and the HTTP Invocation addressing path converging at the agent](../../../../images/content/diagrams/ait-concepts-invocations.png)
+
+The client SDK mints `inputEventId` (and the input's `codecMessageId`) when you call `view.send()` / `regenerate()` / `edit()` and stamps them on the channel publish. The HTTP POST is owned by your application code (or by the bundled Vercel [`ChatTransport`](/docs/ai-transport/api/javascript/vercel/chat-transport)): call `activeRun.toInvocation().toJSON()` to get the wire body and POST it to the agent. The agent mints the `runId` and `invocationId` when it creates the Run, and returns them on the HTTP response so the caller can observe them.
+
+The same Run can be triggered more than once: a fresh send triggers a fresh Invocation; a tool result follow-up creates another; a retry after a serverless cold start creates another. Each HTTP request produces one agent-minted `invocationId`. The `runId` is fresh on the first invocation and reused on every subsequent continuation.
+
+## Why Invocations exist <a id="why-invocations"/>
+
+The client and the agent are separated by an unreliable network and a stateless HTTP boundary. The client publishes input on the channel and your application code posts to the agent endpoint. The agent receives the POST, possibly minutes later, and needs to know exactly which work to do:
+
+- Which input event triggered the work, so the agent's [`Run.start`](/docs/ai-transport/api/javascript/core/agent-session#run-start) can wait for the exact event on the channel.
+- Which channel, since the agent doesn't know the session's channel name except via the trigger.
+
+These two identifiers are the Invocation's payload (`inputEventId`, `sessionName`). They're carried in the HTTP POST body so the agent has them before the channel is observable. Everything else lives on the channel: run identity is resolved from the triggering input event's wire headers (the agent mints `runId` for a fresh run, or reads the existing `runId` off the input event for a continuation). The `invocationId` is minted by the agent per HTTP request.
+
+## The Invocation model <a id="model"/>
+
+An `InvocationData` is the wire shape: the JSON body in the POST.
+
+| Field | What it carries |
+| --- | --- |
+| `inputEventId` | The input event on the channel that triggered this invocation. The agent's `Run.start()` waits for the channel message carrying this `event-id` (rewind + live). |
+| `sessionName` | The session's logical name, used as the Ably channel name. |
+
+The `Invocation` class is the runtime view of that data. The client side uses `ActiveRun.toInvocation()` to obtain one from a returned `ActiveRun`; the agent side uses `Invocation.fromJSON(data)` to construct one from the parsed POST body, then hands it to `session.createRun(invocation, runtime?)`. `createRun` mints the `invocationId` (one per HTTP request) and, for a fresh run, the `runId`; for a continuation the agent reads the existing `runId` off the triggering input event's wire headers. The application returns `run.runId` and `run.invocationId` on the HTTP response so the caller can observe them.
+
+End-to-end: the client publishes the input event on the channel and gets back an `ActiveRun`. The client knows `inputCodecMessageId` immediately, before the agent has minted the run; the `runId` resolves later, once the agent's `ai-run-start` event lands. The application POSTs `activeRun.toInvocation().toJSON()` to the agent endpoint. The agent rebuilds the Invocation, calls `createRun` (which mints `invocationId` and resolves `runId` either by minting for a fresh run or by reading the input event for a continuation), and `run.start()` waits for the matching input event to arrive on the channel via rewind and live. Output events the agent publishes carry the `run-id`, `invocation-id`, and `input-codec-message-id` headers; the client resolves `ActiveRun.runId` once `ai-run-start` lands. The application returns `run.runId` and `run.invocationId` on the HTTP response so the original caller can observe the agent-minted identifiers directly.
+
+## What the Invocation layer requires <a id="requires"/>
+
+| Property | Why it matters |
+| --- | --- |
+| Stable identity | The triggering input event must be addressable from both sides. The client stamps `event-id` on the channel publish, and your code posts the same `inputEventId` in the body. If they diverged, the agent's lookup would fail. |
+| Deterministic generation | The client mints `inputEventId` and `codecMessageId` inside `view.send()` (and the other write methods). Defaults to `crypto.randomUUID()`; override via [`SendOptions`](/docs/ai-transport/api/javascript/core/client-session#view) for deterministic tests. The agent mints `runId` and `invocationId` per request; supply `RunRuntime.runId` / `RunRuntime.invocationId` to override in tests. |
+| Idempotency | The agent endpoint may receive the same Invocation more than once (network retry, queue redelivery). The agent must treat duplicate Invocations safely, typically by checking whether the input event has already produced a Run on the channel. |
+| Decoupled timing | The POST may arrive before, simultaneously with, or after the input event on the channel. The agent's `Run.start()` waits for the input event with rewind + live lookup, so the order doesn't matter. |
+| Continuation support | A tool-result delivery or a regenerate produces a new Invocation; the client stamps the existing `run-id` on the new input event's wire headers when publishing. The agent's `createRun` reads that `run-id` from the input event instead of minting a fresh one, and the SDK treats it as a continuation. |
+
+## Receive an Invocation <a id="receive"/>
+
+The agent's HTTP handler:
+
+<Code>
+```javascript
+import { Invocation } from '@ably/ai-transport';
+
+export async function POST(req) {
+  const data = await req.json();
+  const invocation = Invocation.fromJSON(data);
+
+  const session = createAgentSession({ /* ... */ });
+  await session.connect();
+
+  const run = session.createRun(invocation, { signal: req.signal });
+  await run.start(); // waits for the input event with id `invocation.inputEventId`
+  // ...
+
+  return Response.json({ runId: run.runId, invocationId: run.invocationId });
+}
+```
+</Code>
+
+On the client, the [`view.send`](/docs/ai-transport/api/javascript/core/client-session#view) call generates the identifiers, stamps them on the channel publish, and returns the `ActiveRun`. Your application code (or the [Vercel `ChatTransport`](/docs/ai-transport/api/javascript/vercel/chat-transport) wrapper) calls `activeRun.toInvocation().toJSON()` to build the POST body and sends it to the agent endpoint.
+
+## Read next <a id="next"/>
+
+- [Runs](/docs/ai-transport/concepts/runs): what an Invocation creates or continues.
+- [Connections](/docs/ai-transport/concepts/connections): `ClientSession` publishes the input; your code POSTs the Invocation; `AgentSession` receives the POST and creates the Run.
+- [AgentSession reference](/docs/ai-transport/api/javascript/core/agent-session): `Invocation.fromJSON` and `createRun` in detail.
+- [Tool calling](/docs/ai-transport/features/tool-calling): tool results produce continuation Invocations.
diff --git a/src/pages/docs/ai-transport/concepts/runs.mdx b/src/pages/docs/ai-transport/concepts/runs.mdx
new file mode 100644
index 0000000000..071273d1c5
--- /dev/null
+++ b/src/pages/docs/ai-transport/concepts/runs.mdx
@@ -0,0 +1,91 @@
+---
+title: "Runs"
+meta_description: "Understand Runs in AI Transport: the SDK primitive that implements a conversation turn with explicit identity, lifecycle, cancel routing, and durable execution semantics."
+meta_keywords: "AI Transport, Run, RunInfo, RunEndReason, turn, cancellation, durable execution, invocation"
+intro: "A Run is AI Transport's unit of work for one prompt-response cycle, with explicit identity, lifecycle, and end reason. Each conversation turn the user sees is implemented as a Run."
+redirect_from:
+  - /docs/ai-transport/concepts/turns
+---
+
+A Run is one unit of agent work, initiated in response to user intent. It encompasses everything that happens in service of that intent: the user's input, the agent's response, any tool calls the agent makes, any intermediate messages required to resolve those tool calls (approvals, tool outputs), the agent's continued work after resolution, and the final completion.
+
+AI Transport implements each user prompt and LLM turn as a Run.
+
+![Diagram showing a Run as a bracketed group of channel messages with lifecycle events and end reason](../../../../images/content/diagrams/ait-concepts-runs.png)
+
+## Why Runs exist <a id="why-runs"/>
+
+An agent's work in response to a single user prompt isn't atomic. It can involve reasoning over time, gathering external information, executing tools, and waiting for humans or other systems to respond. Across that span, multiple participants (multiple devices, multiple browser tabs, a serverless function that restarts mid-execution) need to agree on *which work is which*, *when it started*, *when it ended*, and *whether it was cancelled*. The Run is the SDK primitive that carries this identity end-to-end.
+
+## The Run model <a id="model"/>
+
+A Run has four invariants that the SDK enforces on every channel:
+
+- A unique `runId`.
+- A bracketing pair of lifecycle events on the channel: `ai-run-start` and `ai-run-end`.
+- An owner: the `clientId` of the Ably client that published `ai-run-start`.
+- A terminal `RunEndReason` once it ends: `'complete'`, `'cancelled'`, or `'error'`. (A Run that pauses awaiting input takes `RunInfo.status === 'suspended'` via `Run.suspend()`, which is non-terminal.)
+
+Within those brackets, the Run owns a window of channel messages: the user input that triggered it, the agent's streamed outputs, any tool-call or tool-result messages. The conversation [Tree](/docs/ai-transport/concepts/conversation-tree) groups those messages into a `RunNode`; the [View](/docs/ai-transport/api/javascript/core/client-session#view) surfaces projection-free [`RunInfo`](/docs/ai-transport/api/javascript/core/client-session#view) snapshots for the UI.
+
+A Run is triggered by an [`Invocation`](/docs/ai-transport/concepts/invocations): the trigger the client posts to the agent endpoint that says "create or continue a Run with these identifiers." The Invocation is a separate concept because the same Run can be re-triggered (a tool result, a regenerate request); each trigger is one Invocation.
+
+## What the Run layer requires <a id="requires"/>
+
+| Property | Why it matters |
+| --- | --- |
+| Stable identity | The same `runId` must be readable to every participant: the client that started the Run, every other connected client, the agent process. Without it, cancellation has no target and observation has no scope. |
+| Lifecycle brackets | `ai-run-start`, `ai-run-suspend`, `ai-run-resume`, and `ai-run-end` mark the Run on the wire. A view filtering "active Runs" reads `RunInfo.status === 'active'`; `'suspended'` and the terminal `RunEndReason` values cover the other states. |
+| Cancel routing | A cancel message names a `runId`. The agent's [`Run.abortSignal`](/docs/ai-transport/api/javascript/core/agent-session#run) fires only for matching cancels, so unrelated Runs on the same session continue. |
+| Durable execution | An agent can restart its process mid-Run (serverless cold start, container redeploy). The Run's identity plus the channel's persistence let the new agent rehydrate via [`Run.loadConversation`](/docs/ai-transport/api/javascript/core/agent-session#load-conversation) and continue without the client noticing. |
+| Multiple participants | Several clients may observe the same Run (multi-device, support handover). They all see the lifecycle events; they all hold the same `RunInfo`. |
+
+## Understand the Run lifecycle <a id="lifecycle"/>
+
+A Run progresses from start to terminal end. Along the way it can pause to wait for external input and be resumed when that input arrives. Each phase is reflected on `RunInfo.status`:
+
+- `'active'` while the agent is working. Set when the Run first starts and again whenever a paused Run is resumed.
+- `'suspended'` while the Run is paused awaiting input (a tool approval, a human-in-the-loop response). The Run is not over; a later trigger re-activates it.
+- A terminal `RunEndReason` once the Run finishes:
+  - `'complete'` is the success path.
+  - `'cancelled'` is set when the Run is cancelled.
+  - `'error'` is set when reasoning, output streaming, or a tool execution fails unrecoverably.
+
+A Run is the unit of cancellation. There is no user-facing cancel below the Run level. Internal failures (a stream dying, a model call retrying, a serverless cold start) fail the *execution attempt*, not the Run; the Run stays active and the SDK retries underneath.
+
+## Trigger a Run <a id="trigger"/>
+
+A minimal client-side send returns an `ActiveRun` that exposes the Run's identity and a per-Run cancel. The application then POSTs `activeRun.toInvocation().toJSON()` to its agent endpoint to wake the agent; see [Invocations](/docs/ai-transport/concepts/invocations).
+
+<Code>
+```javascript
+const activeRun = await session.view.send(UIMessageCodec.createUserMessage({
+  id: crypto.randomUUID(),
+  role: 'user',
+  parts: [{ type: 'text', text: 'Plan a 3-day trip to Lisbon.' }],
+}));
+
+// The agent assigns the runId on the server, so activeRun.runId is a
+// Promise. Await it to read the id.
+const runId = await activeRun.runId;
+console.log('Run started:', runId);
+
+// Stop button: activeRun.cancel() works immediately, even before
+// the runId promise resolves.
+await activeRun.cancel();
+```
+</Code>
+
+On the agent side, the symmetric primitive is [`AgentSession.createRun(invocation, runtime?)`](/docs/ai-transport/api/javascript/core/agent-session#create-run). The agent mints `runId` (for a fresh run) or reads the existing `runId` off the triggering input event (for a continuation), and stamps it on every event it publishes; the client observes it via `ActiveRun.runId`.
+
+## Run concurrent Runs <a id="concurrent"/>
+
+A session can hold multiple Runs in flight at the same time. They share the channel; they don't share state. See [concurrent turns](/docs/ai-transport/features/concurrent-turns) for the patterns that arise when more than one Run is `'active'`.
+
+## Read next <a id="next"/>
+
+- [Sessions](/docs/ai-transport/concepts/sessions): the shared conversation state Runs live within.
+- [Invocations](/docs/ai-transport/concepts/invocations): the trigger that creates or continues a Run.
+- [Connections](/docs/ai-transport/concepts/connections): how `ClientSession` and `AgentSession` connect to a session and publish Runs.
+- [Cancellation](/docs/ai-transport/features/cancellation): control who cancels Runs and how cancel signals are routed.
+- [Concurrent turns](/docs/ai-transport/features/concurrent-turns): multiple Runs in flight on the same session.
diff --git a/src/pages/docs/ai-transport/concepts/sessions.mdx b/src/pages/docs/ai-transport/concepts/sessions.mdx
index 7a7d5809cd..9de6fd8288 100644
--- a/src/pages/docs/ai-transport/concepts/sessions.mdx
+++ b/src/pages/docs/ai-transport/concepts/sessions.mdx
@@ -10,7 +10,9 @@ redirect_from:
 
 A session is the complete, persistent state of a conversation. It exists independently of any participant. Clients connect and disconnect, agents spin up and terminate, and the session endures. It is what all participants share, and it is what makes the conversation a first-class resource rather than a side effect of a connection.
 
-The session contains the full branching [tree of messages](/docs/ai-transport/concepts/conversation-tree), the [turn lifecycle](/docs/ai-transport/concepts/turns), and any in-progress streaming state. Two participants that materialise the same session from the same data arrive at the same state.
+The session contains the full branching [tree of messages](/docs/ai-transport/concepts/conversation-tree), the [Run lifecycle](/docs/ai-transport/concepts/runs), and any in-progress streaming state. Two participants that materialise the same session from the same data arrive at the same state.
+
+![Diagram showing the channel as an append-only log and the session as the materialised state above it](../../../../images/content/diagrams/ait-concepts-sessions.png)
 
 ## Understand the session and channel relationship <a id="session-and-channel"/>
 
@@ -51,21 +53,21 @@ These properties enable three capabilities that direct HTTP streaming does not p
 2. Continuity across surfaces. The session follows the user, not the connection. Open a second tab, switch to a phone, come back hours later. Every surface sees the same session state.
 3. Live control. Any participant communicates with any other participant through the session while work is in progress. Cancel a generation from a different device. Steer an agent mid-response. Send a follow-up before the current response finishes.
 
-A session is materialised by attaching a client transport to the channel that backs it:
+A session is materialised by attaching a client session to the channel that backs it:
 
 <Code>
 ```javascript
 import * as Ably from 'ably';
-import { createClientTransport } from '@ably/ai-transport/vercel';
+import { createClientSession } from '@ably/ai-transport/vercel';
 
-const ably = new Ably.Realtime({ authUrl: '/auth' });
-const channel = ably.channels.get('conversation-42');
+const ably = new Ably.Realtime({ authUrl: '/api/auth/token' });
 
-const transport = createClientTransport({ channel });
+const session = createClientSession({ client: ably, channelName: 'conversation-42' });
+await session.connect();
 ```
 </Code>
 
-`createClientTransport` from `@ably/ai-transport/vercel` is pre-bound with the Vercel codec and defaults `api` to `/api/chat`. The core entry point at `@ably/ai-transport` exposes the same factory with `codec` and `api` required. See [authentication](/docs/ai-transport/concepts/authentication) for how `authUrl` is set up.
+`createClientSession` from `@ably/ai-transport/vercel` is pre-bound with the Vercel `UIMessageCodec`. The core entry point at `@ably/ai-transport` exposes the same factory with `codec` required. The core SDK never POSTs; the application wakes its agent by POSTing `run.toInvocation().toJSON()` (or by using `createChatTransport`, which does it for you). See [Set up authentication](/docs/ai-transport/getting-started/authentication) for how `authUrl` is wired up.
 
 ## Share a session across participants <a id="sharing"/>
 
@@ -79,7 +81,7 @@ Clients are resilient to disconnection. A client that drops its connection loses
 
 New participants join at any time. A second client attaching to the channel hydrates the full session from history and receives live updates going forward. No handshake or coordination is required between participants.
 
-## Support different persistence models <a id="persistence"/>
+## Support persistence models <a id="persistence"/>
 
 The channel serves two distinct roles: live delivery and historical persistence. It always serves as the live delivery layer. Whether it also serves as the historical persistence layer depends on the configuration.
 
@@ -92,5 +94,5 @@ In both cases, the channel carries all live activity: in-progress streams, turn
 ## Read next <a id="next"/>
 
 - [Conversation tree](/docs/ai-transport/concepts/conversation-tree): how messages form a branching conversation history.
-- [Turns](/docs/ai-transport/concepts/turns): the unit of agent work within a session.
-- [Transport](/docs/ai-transport/concepts/transport): how clients and agents connect to a session.
+- [Runs](/docs/ai-transport/concepts/runs): the unit of agent work within a session.
+- [Connections](/docs/ai-transport/concepts/connections): how clients and agents connect to a session.
diff --git a/src/pages/docs/ai-transport/concepts/transport.mdx b/src/pages/docs/ai-transport/concepts/transport.mdx
deleted file mode 100644
index 0c0934d33d..0000000000
--- a/src/pages/docs/ai-transport/concepts/transport.mdx
+++ /dev/null
@@ -1,75 +0,0 @@
----
-title: "Transport"
-meta_description: "Understand the transport layer in AI Transport: client transport, agent transport, and the codec that bridges your AI framework to Ably."
-meta_keywords: "AI Transport, client transport, agent transport, codec, streaming, Ably"
-intro: "The transport layer connects each participant to the session and translates between your AI framework's events and Ably's messages."
-redirect_from:
-  - /docs/ai-transport/how-it-works/transport
----
-
-The transport layer handles communication between participants and the [session](/docs/ai-transport/concepts/sessions). There are two transports: the client transport for client applications, and the agent transport for agent processes. A pluggable codec bridges your AI framework's event types to Ably messages, so the transport works with any framework without modification.
-
-## Understand the client transport <a id="client-transport"/>
-
-The client transport is how a client application connects to a session. It is a long-lived object that subscribes to the channel, materialises the session into a [tree](/docs/ai-transport/concepts/conversation-tree), and provides one or more [views](/docs/ai-transport/concepts/conversation-tree#views) for the application to work with.
-
-The client transport owns the read path: decoding incoming channel messages, applying them to the tree, and emitting scoped events through views so the application knows when visible state has changed. It also owns the client's side of the write path. When the application sends a message, the transport publishes turn-start and the user's input messages to the channel, then sends a [poke](/docs/ai-transport/concepts/turns#poke) to the agent endpoint to trigger an execution. The channel publish and the poke are decoupled: the turn is established on the session before the agent is triggered, and the poke is deferred or retried independently. Cancellation is a channel publish: the transport sends a cancel signal targeting a turn, and the agent receives it through its own channel subscription.
-
-The client transport is also responsible for connection resilience. It monitors channel continuity, detects if messages were lost during a disconnection, and keeps the session state consistent after reconnection.
-
-A client transport is not the session. It is one participant's connection to the session. Multiple clients connect to the same session simultaneously, each with their own views and branch selections, all sharing the same underlying conversation state on the channel.
-
-## Understand the agent transport <a id="agent-transport"/>
-
-The agent transport is how an agent connects to a session for a single execution attempt within a [turn](/docs/ai-transport/concepts/turns). It is typically short-lived: created when the agent receives a poke, used for the duration of that execution, then disposed.
-
-The agent transport handles the write path for the agent's contribution: piping model output through the codec encoder to the channel, publishing turn-end when the task completes, and listening for cancel signals that target the active turn. When the agent receives a poke, it uses the transport to hydrate the session from the channel (or from an external store), locate the message the poke references, and begin its work.
-
-The agent is stateless between execution attempts. The agent transport does not maintain long-lived subscriptions or accumulated state. Each execution hydrates what it needs, does its work, publishes its output, and tears down. If the turn spans multiple executions (a human-in-the-loop step, a retry after failure), each execution creates its own agent transport against the same session. The session on the channel provides continuity, not the transport.
-
-## Understand the codec <a id="codec"/>
-
-The codec is the translation layer between domain-specific message models and Ably's native message primitives. It defines how events in the application's domain (text deltas, tool calls, finish signals, or whatever the domain model requires) are encoded into Ably messages for transmission over the channel, and how incoming Ably messages are decoded back into domain events and accumulated into domain messages.
-
-The codec is an interface, not an implementation. The generic layer of the SDK knows nothing about what the events or messages look like. It operates entirely through the codec contract. A Vercel AI SDK codec translates `UIMessageChunk` events into Ably messages and assembles them into `UIMessage` objects. A different codec does the same for a different framework, or for a custom domain model.
-
-The codec has three responsibilities:
-
-| Component | What it does |
-| --- | --- |
-| Encoder | Take domain events and produce Ably message operations: publishes for discrete messages, append sequences for streamed content. |
-| Decoder | Take incoming Ably messages and produce domain events. Handle the reconstruction of streaming state from Ably's message lifecycle (create, append, update). |
-| Accumulator | Take a sequence of decoded events and assemble them into complete domain messages. Track which messages are still streaming and which are complete. |
-
-The codec also determines what constitutes a terminal event: the event that signals a stream is finished. This is domain-specific knowledge (a `finish` chunk in the Vercel model, for example) that the generic transport layer needs in order to close streams at the right time.
-
-The codec is the boundary between transport concerns and application domain concerns. Everything below the codec (headers, serials, channel operations, tree structure) is generic. Everything above (the shape of events, the structure of messages, what a tool call or text delta means) is domain-specific.
-
-## Connect a client transport <a id="connect"/>
-
-A client transport is created with an Ably channel, a codec, and the HTTP endpoint that triggers the agent:
-
-<Code>
-```javascript
-import * as Ably from 'ably';
-import { createClientTransport } from '@ably/ai-transport';
-import { UIMessageCodec } from '@ably/ai-transport/vercel';
-
-const ably = new Ably.Realtime({ authUrl: '/auth' });
-const channel = ably.channels.get('conversation-42');
-
-const transport = createClientTransport({
-  channel,
-  codec: UIMessageCodec,
-  api: '/api/chat',
-});
-```
-</Code>
-
-The codec is what makes the same transport carry a Vercel `UIMessage`, an OpenAI completion, or a custom domain event. `UIMessageCodec` is provided for the Vercel AI SDK; the Vercel entry point also re-exports `createClientTransport` with the codec pre-bound and `api` defaulted to `/api/chat`. See the [codec API reference](/docs/ai-transport/api/javascript/codec) for the full interface.
-
-## Read next <a id="next"/>
-
-- [Authentication](/docs/ai-transport/concepts/authentication): configure authentication for AI Transport sessions.
-- [Sessions](/docs/ai-transport/concepts/sessions): the persistent conversation state that transports connect to.
-- [Codec API reference](/docs/ai-transport/api/javascript/codec): the full codec interface specification.
diff --git a/src/pages/docs/ai-transport/concepts/turns.mdx b/src/pages/docs/ai-transport/concepts/turns.mdx
deleted file mode 100644
index 196f1ab236..0000000000
--- a/src/pages/docs/ai-transport/concepts/turns.mdx
+++ /dev/null
@@ -1,67 +0,0 @@
----
-title: "Turns"
-meta_description: "Understand turns in AI Transport: the logical unit of agent work that structures prompt-response cycles with lifecycle states, cancellation, and execution resilience."
-meta_keywords: "AI Transport, turns, turn lifecycle, cancellation, poke, agent invocation, serverless"
-intro: "A turn is one unit of agent work, from the user's intent to the final response. It is the level at which you start, observe, and cancel a piece of agent activity."
----
-
-A turn is a logical unit of agent work, initiated in response to user intent. It encompasses everything that happens in service of that intent: the user's input, the agent's response, any tool calls the agent makes, any intermediate messages required to resolve those tool calls (approvals, tool outputs), the agent's continued work after resolution, and the final completion. A turn involves one or more participants and one or more exchanges before it finishes.
-
-## Understand turn lifecycle <a id="lifecycle"/>
-
-A turn has a unique identifier and is bracketed by lifecycle events on the channel. The client initiates a turn and passes the prompt for that turn to the server to query the AI model. The user's input messages are part of the turn. The turn is visible on the [session](/docs/ai-transport/concepts/sessions) from the moment the user expresses intent, not from the moment the agent begins processing. The agent publishes turn-end when the task completes, is cancelled, or fails. The turn ID correlates all activity that belongs to the same task.
-
-A turn progresses through a defined set of states:
-
-| State | Meaning |
-| --- | --- |
-| Pending | The turn has been opened. The user's input is on the session; no agent has started yet. |
-| Active | The agent is working. |
-| Suspended | The most recent execution has paused intentionally. The agent is waiting for external input (a human-in-the-loop approval, a tool output) or a durable step handoff. The turn is still open. |
-| Completed | The task finished successfully. |
-| Cancelled | The user, or another participant, stopped the turn. Cancellation is possible from any open state. |
-| Failed | The task could not be completed after exhausting recovery options. |
-
-Multiple turns are active simultaneously on the same session. See [concurrent turns](/docs/ai-transport/features/concurrent-turns) for details.
-
-## Cancel a turn <a id="cancellation"/>
-
-The turn is the unit of cancellation. When a user stops a response, they are cancelling the turn: all work associated with the current task, across all execution attempts. There is no user-facing cancel operation below the turn.
-
-Internal execution failures (a stream dying, a model call erroring, a serverless timeout) fail the execution attempt, not the turn. The turn remains active and is retried. See [cancellation](/docs/ai-transport/features/cancellation) for details on cancel filters and authorization.
-
-## Trigger a turn <a id="poke"/>
-
-When the client sends a message, the client transport sends an HTTP POST to your server endpoint. This request carries the user's messages, the conversation history, the turn ID, the channel name, and branching context (parent and fork-of pointers). The server uses this to create a turn, publish the user's messages to the channel, invoke the AI model, and stream the response back through the channel.
-
-The HTTP response returns immediately. The response stream is decoupled from the HTTP request: tokens flow through the Ably channel, not through the HTTP response. This is what allows the stream to survive independently of the client's connection.
-
-The server receives the turn ID and channel name from the client. Any server process that can reach the channel handles the request. The agent does not need to maintain state between turns. It creates a server transport, processes the turn, and tears down.
-
-A turn is initiated by calling `send` on a view:
-
-<Code>
-```javascript
-const turn = await transport.view.send([
-  {
-    id: crypto.randomUUID(),
-    role: 'user',
-    parts: [{ type: 'text', text: 'What is in this contract?' }],
-  },
-]);
-
-for await (const chunk of turn.stream) {
-  // chunk is one decoded event from the agent for this turn
-}
-```
-</Code>
-
-The returned `ActiveTurn` carries the decoded event `stream`, the `turnId`, and a `cancel()` method, so you observe streamed output or stop the turn without holding the underlying connection.
-
-## Read next <a id="next"/>
-
-- [Sessions](/docs/ai-transport/concepts/sessions): the persistent, shared conversation state that turns operate within.
-- [Transport](/docs/ai-transport/concepts/transport): how clients and agents connect to sessions and publish turns.
-- [Cancellation](/docs/ai-transport/features/cancellation): control who cancels turns and how cancel signals are routed.
-- [Concurrent turns](/docs/ai-transport/features/concurrent-turns): handle multiple active turns on the same session.
-- [Human-in-the-loop](/docs/ai-transport/features/human-in-the-loop): use approval gates that suspend and resume turns.
diff --git a/src/pages/docs/ai-transport/features/agent-presence.mdx b/src/pages/docs/ai-transport/features/agent-presence.mdx
index 62833c3fb8..05194007cc 100644
--- a/src/pages/docs/ai-transport/features/agent-presence.mdx
+++ b/src/pages/docs/ai-transport/features/agent-presence.mdx
@@ -21,25 +21,30 @@ The agent enters presence on the AI Transport session channel with status data.
 
 <Code>
 ```javascript
-// Server: agent enters presence when it connects.
-const channel = ably.channels.get(sessionChannelName);
-await channel.presence.enter({ status: 'idle' });
-
 app.post('/api/chat', async (req, res) => {
-  const { turnId, clientId, messages } = req.body;
-  const turn = transport.newTurn({ turnId, clientId });
+  const invocation = Invocation.fromJSON(await req.json());
+  const session = createAgentSession({ client: ably, channelName: invocation.sessionName, codec: UIMessageCodec });
+  await session.connect();
+  const run = session.createRun(invocation, { signal: req.signal });
+
+  // Enter presence on this invocation's channel so every subscriber sees the agent.
+  const channel = ably.channels.get(invocation.sessionName);
+  await channel.presence.enter({ status: 'thinking' });
 
-  await channel.presence.update({ status: 'thinking' });
+  await run.start();
+  await run.loadConversation();
 
   const result = streamText({
     model: openai('gpt-4o'),
-    messages,
-    abortSignal: turn.abortSignal,
+    messages: run.messages,
+    abortSignal: run.abortSignal,
   });
 
   await channel.presence.update({ status: 'streaming' });
-  await turn.streamResponse(result.toUIMessageStream());
-  await channel.presence.update({ status: 'idle' });
+  const { reason } = await run.pipe(result.toUIMessageStream());
+  await run.end(reason);
+  await channel.presence.leave();
+  session.close();
   res.json({ ok: true });
 });
 ```
@@ -64,16 +69,16 @@ const agent = members.find((m) => m.clientId === 'agent');
 ```
 </Code>
 
-## Combine presence with active turns <a id="combining-with-active-turns"/>
+## Combine presence with active runs <a id="combining-with-active-turns"/>
 
-For richer status indicators, combine presence data with `useActiveTurns`. Presence tells you the agent's self-reported state. Active turns tell you which turns are in progress:
+For richer status indicators, combine presence data with the active Runs on the view. Presence tells you the agent's self-reported state. `session.view.runs()` tells you which Runs are in progress:
 
 <Code>
 ```javascript
-const activeTurns = useActiveTurns({ transport });
+const { session } = useClientSession();
 const agentStatus = useAgentPresence(channel); // your custom hook
 
-const isStreaming = activeTurns.has('agent');
+const isStreaming = session.view.runs().some((r) => r.status === 'active' && r.clientId === 'agent');
 const isIdle = agentStatus === 'idle' && !isStreaming;
 const isOffline = agentStatus === null;
 ```
@@ -85,7 +90,7 @@ This is enough information for the UI to show a typing indicator while the agent
 
 - An agent that exits without calling `presence.leave()` (for example, a crashed process) is automatically removed from presence after a timeout. The agent is treated as present until the timeout fires. Wire a graceful shutdown that calls `leave` for the best user experience.
 - A serverless agent that comes up for one turn and tears down should enter and leave presence per turn; entering once and leaving once at the end is fine for a long-running agent.
-- Presence updates do not guarantee strict ordering with channel messages. A `streaming` presence update sometimes arrives slightly after the first token. Drive the UI off active turns for token-level state and use presence for higher-level status.
+- Presence updates do not guarantee strict ordering with channel messages. A `streaming` presence update sometimes arrives slightly after the first token. Drive the UI off `session.view.runs()` for run-level state (active, suspended, terminal) and use presence for higher-level status the agent self-reports.
 - Multi-agent setups need unique `clientId` per agent. Two agents with the same `clientId` collide in the presence set.
 - A client without `presence` capability cannot subscribe to updates. Capability scoping is part of [authentication](/docs/ai-transport/concepts/authentication).
 
@@ -102,9 +107,9 @@ Yes. Presence is symmetric. A client that enters presence shows up alongside age
 ### How long does presence persist after a disconnect? <a id="faq-timeout"/>
 Until Ably's presence timeout fires (currently around 15 seconds). Active connections are not affected; this is for ungraceful disconnects.
 
-### What is the difference between presence and `useActiveTurns`? <a id="faq-vs-active-turns"/>
+### What is the difference between presence and the view's active runs? <a id="faq-vs-active-runs"/>
 
-Presence is self-reported by the agent. Active turns are observable from the channel by inspecting turn lifecycle events. Presence reports intent; active turns report fact. Both together produce richer status.
+Presence is self-reported by the agent. `session.view.runs()` is observable from the channel by inspecting run lifecycle events. Presence reports intent; active runs report fact. Both together produce richer status.
 
 ### Can I pause inference when no users are connected? <a id="faq-pause"/>
 
diff --git a/src/pages/docs/ai-transport/features/branching.mdx b/src/pages/docs/ai-transport/features/branching.mdx
index a9e747484c..8ffc2085d2 100644
--- a/src/pages/docs/ai-transport/features/branching.mdx
+++ b/src/pages/docs/ai-transport/features/branching.mdx
@@ -1,15 +1,15 @@
 ---
-title: "Conversation branching, edit, and regenerate"
-meta_description: "Edit user messages, regenerate AI responses, and navigate branches with Ably AI Transport. The full history is preserved as a tree."
+title: "Branching, edit, and regenerate"
+meta_description: "Edit user messages, regenerate AI responses, and navigate branches with Ably AI Transport. The full history is preserved in the conversation tree."
 meta_keywords: "conversation branching, edit message, regenerate response, conversation tree, AI Transport, Ably"
-intro: "Your users edit any message or regenerate any response, and the conversation forks instead of overwriting. AI Transport stores every branch in the session tree, with one-line UI hooks for sibling navigation."
+intro: "Your users edit any message or regenerate any response, and the conversation forks instead of overwriting. AI Transport stores every branch in the conversation tree, with one-line UI hooks for sibling navigation."
 redirect_from:
   - /docs/ai-transport/features/edit-and-regenerate
 ---
 
-Modern AI chat experiences let users fork the conversation: edit an earlier prompt, regenerate a response, or branch from any point. AI Transport supports this directly. Edit and regenerate are operations on the [conversation tree](/docs/ai-transport/concepts/conversation-tree); every fork creates a sibling branch and nothing is overwritten.
+Your users can revise the past without losing it. The original message stays, the new content forks alongside, and the UI flips between branches. AI Transport handles the tree shape on the wire; you wire up edit, regenerate, and the navigation arrows.
 
-![Diagram showing session continuity during interruption](../../../../images/content/diagrams/ait-session-continuity.png)
+![Diagram showing a branching conversation tree with edit and regenerate forks creating sibling branches from anchored messages](../../../../images/content/diagrams/ait-concepts-conversation-tree.png)
 
 A minimal regenerate:
 
@@ -21,94 +21,84 @@ await view.regenerate(assistantMessageId);
 
 ## How it works <a id="how-it-works"/>
 
-The conversation is a tree, not a list. Every message is a node with a parent pointer. When a user edits a message or regenerates a response, the SDK creates a new branch instead of overwriting the original.
+Every node on the channel carries `parent` and (optionally) `fork-of` or `msg-regenerate` headers. The [conversation tree](/docs/ai-transport/concepts/conversation-tree) reads these to build the branching structure: an edit produces a sibling `InputNode` whose `forkOf` points at the original user message's `codec-message-id`; a regenerate produces a same-parent sibling `RunNode` whose `regeneratesCodecMessageId` points at the original assistant message.
 
-- `edit()` forks a user message. The original message and its descendants remain intact. A new child is added to the same parent, creating a sibling branch.
-- `regenerate()` forks an assistant message. The original response stays in the tree, and a new sibling is created with a fresh turn.
+Branches are message-anchored: the branch decision lives on a `codecMessageId`, not on a `runId`. UIs render navigation arrows next to the bubble: the user's prompt for edit forks, the assistant slot for regenerate groups.
 
-Each fork carries `forkOf` and `parent` headers that tell the server where the new branch diverges from the existing tree. The view flattens the selected branch into a linear list for rendering.
+The View resolves the branch state on demand. Call `view.branchSelection(codecMessageId)` for any message and get back `{ hasSiblings, siblings, index, selected }`. Call `view.selectSibling(codecMessageId, index)` to switch.
 
-## Regenerate a response <a id="regenerate"/>
+## Regenerate <a id="regenerate"/>
 
-Regenerate creates a sibling of an assistant message and starts a new turn. The original response stays in the tree:
+Regenerate creates a sibling Run of an assistant message and starts a fresh turn from the same user prompt. The original response stays in the tree.
 
 <Code>
 ```javascript
 const { regenerate } = useView();
-await regenerate(messageId);
+await regenerate(assistantMessageId);
 ```
 </Code>
 
-The new turn is sent to the server with `forkOf` set to the original assistant message ID and `parent` set to the user message that preceded it. The server generates a new response from that point in the conversation.
+The SDK publishes a `Regenerate` well-known input variant that points at the assistant `codecMessageId`. The agent receives the [Invocation](/docs/ai-transport/concepts/invocations), creates a new Run with `regeneratesCodecMessageId` set, and streams the alternative response.
 
 ## Edit a user message <a id="edit"/>
 
-Edit replaces a user message and starts a new turn from that point. The original message and its descendants remain in the tree as a separate branch:
+Edit replaces a user message and starts a new turn from that point. The original user message and everything below it stays in the tree as a separate branch.
 
 <Code>
 ```javascript
 const { edit } = useView();
-await edit(messageId, [
-  { role: 'user', content: 'Updated question here' },
-]);
+await edit(messageId, {
+  kind: 'user-message',
+  message: {
+    id: crypto.randomUUID(),
+    role: 'user',
+    parts: [{ type: 'text', text: 'Make it 5 days, focused on food.' }],
+  },
+});
 ```
 </Code>
 
-The edit creates a new user message as a sibling of the original and triggers a new turn so the agent responds to the updated message. Multiple messages in a single edit are inserted as a sequence on the new branch:
+Multiple inputs in a single edit are inserted as a sequence on the new branch:
 
 <Code>
 ```javascript
 await view.edit(messageId, [
-  { role: 'user', content: 'First part of my revised input' },
-  { role: 'user', content: 'Second part with additional context' },
+  { kind: 'user-message', message: { id: crypto.randomUUID(), role: 'user', parts: [{ type: 'text', text: 'Make it 5 days.' }] } },
+  { kind: 'user-message', message: { id: crypto.randomUUID(), role: 'user', parts: [{ type: 'text', text: 'And focus on food.' }] } },
 ]);
 ```
 </Code>
 
-## Navigate between branches <a id="branch-navigation"/>
-
-When a message has siblings (from edits or regenerations), the view exposes methods to navigate between them. This is what drives a "1 of 3" UI pattern.
-
-<Code>
-```javascript
-const hasSiblings = view.hasSiblings(messageId);
-const siblings = view.getSiblings(messageId);
-const index = view.getSelectedIndex(messageId);
+The SDK publishes the replacement inputs as fresh `UserMessage`s with the `forkOf` header pointing at the `codecMessageId` being replaced. The agent forks the Run and starts a fresh response from the edited content.
 
-view.select(messageId, 2); // select the third sibling
-```
-</Code>
+## Navigate between siblings <a id="navigate"/>
 
-A typical branch navigation component:
+When a message has siblings, render arrows that switch between them. `branchSelection` returns a safe bundle for any `codecMessageId`:
 
 <Code>
 ```javascript
-function BranchNav({ messageId, view }) {
-  const siblings = view.getSiblings(messageId);
-  const selected = view.getSelectedIndex(messageId);
-
-  if (siblings.length <= 1) return null;
+function BranchNav({ codecMessageId, view }) {
+  const { hasSiblings, siblings, index } = view.branchSelection(codecMessageId);
+  if (!hasSiblings) return null;
 
   return (
     <div>
-      <button onClick={() => view.select(messageId, selected - 1)} disabled={selected === 0}>
-        ←
-      </button>
-      <span>{selected + 1} of {siblings.length}</span>
-      <button onClick={() => view.select(messageId, selected + 1)} disabled={selected === siblings.length - 1}>
-        →
-      </button>
+      <button onClick={() => view.selectSibling(codecMessageId, index - 1)} disabled={index === 0}>←</button>
+      <span>{index + 1} of {siblings.length}</span>
+      <button onClick={() => view.selectSibling(codecMessageId, index + 1)} disabled={index === siblings.length - 1}>→</button>
     </div>
   );
 }
 ```
 </Code>
 
-When the user selects a different sibling, the view recalculates the flattened branch. Every message below the selection point updates to reflect the chosen branch.
+`branchSelection` always returns a usable object: `hasSiblings: false` for messages that aren't branch anchors, `index: 0` for unknown ids. Safe to call on every rendered bubble without conditionals.
 
-## Show branches side by side <a id="split-pane"/>
+When the user selects a different sibling, the view recomputes the visible branch. Every message below the selection point re-renders to reflect the chosen path.
 
-Multiple views exist over the same conversation tree. Each view has its own branch selection and pagination, so different parts of the UI render different branches at the same time:
+## Side-by-side branches <a id="side-by-side"/>
+
+Multiple views over the same conversation tree have independent branch selections, so different parts of the UI can render different branches simultaneously:
 
 <Code>
 ```javascript
@@ -119,67 +109,73 @@ const view2 = useCreateView();
 ```
 </Code>
 
-This is the pattern for comparison UIs where a user wants to see two regenerated responses side by side without switching back and forth.
+This is the pattern for comparison UIs where the user wants to see two regenerated responses side by side.
 
-## Server handling <a id="server"/>
+## Agent-side handling <a id="agent-side"/>
 
-The server receives `forkOf` and `parent` in the request body. Pass them to `newTurn()` so the transport publishes messages with the correct tree metadata:
+The agent doesn't usually need bespoke branching logic. The Invocation arrives, `createRun` returns a Run with the right identity, and `loadConversation` walks the ancestor chain along the selected branch automatically:
 
 <Code>
 ```javascript
-app.post('/chat', async (req, res) => {
-  const { messages, turnId, clientId, forkOf, parent } = req.body;
+const invocation = Invocation.fromJSON(await req.json());
+const run = session.createRun(invocation, { signal: req.signal });
 
-  const turn = transport.newTurn({ turnId, clientId, forkOf, parent });
-  await turn.start();
+try {
+  await run.start();
+  await run.loadConversation(); // walks ancestor chain along this branch
 
   const result = streamText({
     model: anthropic('claude-sonnet-4-20250514'),
-    messages, // already truncated to the fork point by the client
-    abortSignal: turn.abortSignal,
+    messages: run.messages,
+    abortSignal: run.abortSignal,
   });
 
-  const { reason } = await turn.streamResponse(result.toUIMessageStream());
-  await turn.end(reason);
-});
+  const { reason } = await run.pipe(result.toUIMessageStream());
+  await run.end(reason);
+} catch (err) {
+  await run.end('error');
+  throw err;
+} finally {
+  session.close();
+}
 ```
 </Code>
 
-`forkOf` identifies the message being replaced (the original user message for edit, or the original assistant message for regenerate). `parent` identifies where the new branch connects to the existing tree. The client truncates conversation history to the fork point before sending; the server receives exactly the history the LLM needs.
+`run.messages` after `loadConversation()` returns the complete branch (ancestor turns and the current user input) in order. Pass it straight to the LLM.
 
 ## Edge cases and unhappy paths <a id="edge-cases"/>
 
-- Editing or regenerating mid-stream cancels nothing automatically. Cancel the active turn first if you do not want both to run.
-- A view's branch selection is local to that view. Two devices on the same session see different branches if they have different selections; the tree is shared, the selection is per-view.
-- A deeply nested tree (many edits and regenerations on top of each other) lets the user navigate forever. Cap or hide branch navigation in the UI if your application has a preferred branch.
-- A regenerate against a message whose parent has been edited still works; the new branch attaches at the same `parent` regardless of what siblings exist.
-- The flattened view recomputes when the selection changes. Avoid heavy work in the render path; the tree updates are frequent during streaming.
+- Editing or regenerating mid-stream cancels nothing automatically. Call `session.cancel(runId)` on the active Run first if you do not want both to run.
+- Branch selection is per-view. Two devices on the same session can see different branches simultaneously; the tree is shared, the selection is per-view.
+- Deeply branched trees can have many siblings. A user can navigate forever; cap or hide branch navigation in your UI if your app has a preferred branch.
+- A regenerate against an edited prompt still works. The new branch attaches at the same anchor regardless of what siblings exist.
+- The visible branch recomputes when `selectSibling` is called. Avoid heavy work in the render path; updates are frequent during streaming.
+- An optimistic edit is folded with the published edit. See [optimistic updates](/docs/ai-transport/features/optimistic-updates) for how the SDK reconciles the local insertion with the wire confirmation.
 
 ## FAQ <a id="faq"/>
 
-### Does edit overwrite the original message? <a id="faq-overwrite"/>
+### Does edit overwrite the original message?
 
-No. The original message and its descendants stay in the tree. A new sibling branch is created with the edited content. Users navigate between branches with `view.select()`.
+No. The original stays in the tree. A new sibling branch is created with the edited content. Users navigate between branches with `view.selectSibling()`.
 
-### How is regenerate different from sending a new prompt? <a id="faq-vs-prompt"/>
+### How is regenerate different from sending a new prompt?
 
-Regenerate creates a sibling of an assistant message under the same user prompt. Sending a new prompt adds a new exchange below the current branch. Use regenerate to compare alternative responses; use a new prompt to continue the conversation.
+Regenerate creates a sibling response for the same user prompt. Sending a new prompt adds a new exchange below the current branch. Use regenerate to compare alternative responses to the same question; use a new prompt to continue the conversation.
 
-### Can two clients edit at the same time? <a id="faq-concurrent-edit"/>
+### Can two clients edit at the same time?
 
-Yes. Each edit creates a sibling, so concurrent edits produce two new siblings. The tree merges cleanly; the view's selection determines what each device renders.
+Yes. Each edit creates a sibling, so concurrent edits produce two new siblings. The tree merges cleanly; each device's view selection determines what it renders.
 
-### What if the LLM produces the same response on regenerate? <a id="faq-same-response"/>
+### What if the LLM produces the same response on regenerate?
 
 You get a sibling with the same content. Use temperature or sampling settings to encourage variety, or expose a "regenerate again" affordance.
 
-### How deep does the tree get? <a id="faq-depth"/>
+### How deep can the tree get?
 
-The tree depth is bounded by the conversation length. Branch breadth grows with edits and regenerations. There is no fixed limit; render performance is the practical constraint.
+Tree depth is bounded by the conversation length. Branch breadth grows with edits and regenerations. There's no fixed limit; render performance is the practical constraint.
 
 ## Related features <a id="related"/>
 
-- [History and replay](/docs/ai-transport/features/history): loading conversation history including all branches.
+- [Conversation tree](/docs/ai-transport/concepts/conversation-tree): the data structure branches live in.
 - [Multi-device sessions](/docs/ai-transport/features/multi-device): edits and regenerations sync across devices.
-- [Optimistic updates](/docs/ai-transport/features/optimistic-updates): edits use optimistic insertion for the revised message.
-- [Conversation tree](/docs/ai-transport/concepts/conversation-tree): how forks form the underlying data structure.
+- [Optimistic updates](/docs/ai-transport/features/optimistic-updates): how local-first edits reconcile with the published tree.
diff --git a/src/pages/docs/ai-transport/features/cancellation.mdx b/src/pages/docs/ai-transport/features/cancellation.mdx
index 844c0eaeec..2950aca116 100644
--- a/src/pages/docs/ai-transport/features/cancellation.mdx
+++ b/src/pages/docs/ai-transport/features/cancellation.mdx
@@ -7,75 +7,73 @@ redirect_from:
   - /docs/ai-transport/messaging/completion-and-cancellation
 ---
 
-Cancellation is a turn-level operation. The client publishes a cancel signal on the Ably channel; the server matches it against active turns and fires their abort signals. Unlike closing an HTTP connection, cancellation is an explicit signal: the session remains intact, other turns continue, and both sides handle cleanup gracefully.
+Cancellation is a turn-level operation. The client publishes a cancel signal on the Ably channel; the agent receives it on the run with the matching `runId` and fires its abort signal. Unlike closing an HTTP connection, cancellation is an explicit signal: the session remains intact, other runs continue, and both sides handle cleanup gracefully.
+
+![Diagram showing a cancel signal stopping the in-progress Run](../../../../images/content/diagrams/ait-cancellation.png)
 
 A minimal cancel:
 
 <Code>
 ```javascript
-await transport.cancel();
+await activeRun.cancel();
 ```
 </Code>
 
 ## How it works <a id="how-it-works"/>
 
-Sessions are bidirectional, so a cancel is just a signal on the channel. The client publishes a cancel message with a filter specifying which turns to cancel. The server's transport matches the filter against active turns and fires their abort signals. The LLM stream stops, the turn ends with reason `'cancelled'`, and every subscriber receives the lifecycle update.
+Sessions are bidirectional, so a cancel is just a signal on the channel. The client publishes a cancel message keyed on the triggering input's `codec-message-id` (the synchronous handle the client owns from send time). Once the agent has resolved the cancel to a registered Run, that Run's `abortSignal` fires. The LLM stream stops, the run ends with reason `'cancelled'`, and every subscriber receives the lifecycle update. A cancel published before the agent has minted the run-id is still honoured: the agent buffers it and fires once the input-event lookup resolves.
 
 <Code>
 ```javascript
-// Client: cancel the current turn
-await turn.cancel();
+// Client: cancel the current run.
+// activeRun.cancel() works immediately, even before the runId
+// promise on activeRun has resolved.
+await activeRun.cancel();
+
+// Or, when you already have a resolved runId (for example from a RunInfo
+// in view.runs()):
+await session.cancel(someRunInfo.runId);
 
 // Server: abort signal fires automatically
 const result = streamText({
-  abortSignal: turn.abortSignal,
+  abortSignal: run.abortSignal,
 });
 ```
 </Code>
 
-## Cancel filters <a id="cancel-filters"/>
+## Cancel one run, several, or all <a id="cancel-filters"/>
 
-Cancel signals are scoped. You control which turns are cancelled:
-
-| Filter | Effect | Use case |
-| --- | --- | --- |
-| `{ own: true }` (default) | Cancel all turns started by this client. | Stop button. |
-| `{ turnId: 'abc' }` | Cancel one specific turn. | Cancel a specific generation. |
-| `{ clientId: 'user-1' }` | Cancel all turns by a specific client. | Admin cancellation. |
-| `{ all: true }` | Cancel all turns on the channel. | Emergency stop. |
+`activeRun.cancel()` targets the run the client just kicked off. To cancel several runs, iterate the visible Runs and cancel each by id:
 
 <Code>
 ```javascript
-// Cancel your own turns (default)
-await transport.cancel();
-
-// Cancel a specific turn
-await transport.cancel({ turnId: activeTurn.turnId });
-
-// Cancel all turns on the channel
-await transport.cancel({ all: true });
+// Cancel all active runs in the visible view (Stop button)
+const active = session.view.runs().filter((r) => r.status === 'active');
+await Promise.all(active.map((r) => session.cancel(r.runId)));
 ```
 </Code>
 
+Selecting which runs to cancel is application logic. `RunInfo.clientId` tells you the run owner, so you can scope a cancel to runs started by the current client, a specific user, or all visible runs.
+
 ## Server-side handling <a id="server"/>
 
 ### Abort signal <a id="abort-signal"/>
 
-Every turn exposes an `abortSignal` that fires when the turn is cancelled. Pass it to your LLM call:
+Every run exposes an `abortSignal` that fires when the run is cancelled. Pass it to your LLM call:
 
 <Code>
 ```javascript
-const turn = transport.newTurn({ turnId, clientId });
-await turn.start();
+const run = session.createRun(invocation, { signal: req.signal });
+await run.start();
 
 const result = streamText({
   model: anthropic('claude-sonnet-4-20250514'),
-  messages: history,
-  abortSignal: turn.abortSignal,
+  messages: run.messages,
+  abortSignal: run.abortSignal,
 });
 
-const { reason } = await turn.streamResponse(result.toUIMessageStream());
-await turn.end(reason);
+const { reason } = await run.pipe(result.toUIMessageStream());
+await run.end(reason);
 ```
 </Code>
 
@@ -83,34 +81,31 @@ await turn.end(reason);
 
 ### Authorise the cancel <a id="authorization"/>
 
-The `onCancel` hook authorises or rejects cancel requests:
+The `onCancel` hook on `RunRuntime` authorises or rejects cancel requests:
 
 <Code>
 ```javascript
-const turn = transport.newTurn({
-  turnId,
-  clientId,
-  onCancel: async (request) => {
-    const owner = request.turnOwners.get(request.filter.turnId);
-    return owner === request.message.clientId;
-  },
+const userId = await authenticateUser(req);
+
+const run = session.createRun(invocation, {
+  signal: req.signal,
+  onCancel: async (request) => request.message.clientId === userId,
 });
 ```
 </Code>
 
-The `CancelRequest` includes `message` (the raw cancel message with `clientId`), `filter` (parsed scope), `matchedTurnIds`, and `turnOwners` (map of turn ID to owner client ID). Return `false` to reject. If `onCancel` is not provided, all cancel requests are accepted.
+`CancelRequest` carries the raw cancel `message` (with the requester's `clientId`) and the `runId` it targets. Resolve the authorised identity from the inbound HTTP request and compare against `request.message.clientId`; the Ably service verifies the publisher's `clientId` before the cancel reaches the agent, so the value is trustworthy. Return `false` to reject; the run continues. If `onCancel` is not provided, all cancel requests are accepted.
 
-### Hook into the abort <a id="abort-hook"/>
+### Publish a final note before cancelling <a id="abort-hook"/>
 
-The `onAbort` hook runs after the abort signal fires, giving you a chance to publish final events before the stream closes:
+The `onCancelled` hook runs when the abort signal fires, giving you a chance to publish final events before the stream closes:
 
 <Code>
 ```javascript
-const turn = transport.newTurn({
-  turnId,
-  clientId,
-  onAbort: async (write) => {
-    await write({ type: 'text-delta', textDelta: '\n[Response cancelled]' });
+const run = session.createRun(invocation, {
+  signal: req.signal,
+  onCancelled: async (write) => {
+    await write({ type: 'text-delta', id: 'cancel-note', delta: '\n[Response cancelled]' });
   },
 });
 ```
@@ -118,11 +113,13 @@ const turn = transport.newTurn({
 
 ## Cancel on close <a id="cancel-on-close"/>
 
-When a client transport closes, it optionally cancels its own turns:
+`ClientSession.close()` is local-state-only: it does not cancel runs on the wire. To stop in-progress runs before closing, cancel them explicitly:
 
 <Code>
 ```javascript
-await transport.close({ cancel: { own: true } });
+const active = session.view.runs().filter((r) => r.status === 'active');
+await Promise.all(active.map((r) => session.cancel(r.runId)));
+await session.close();
 ```
 </Code>
 
@@ -148,9 +145,9 @@ Yes, if your `onCancel` hook authorises it. The default accepts all cancel reque
 
 The turn cancels once. Subsequent matching signals are no-ops; the abort signal does not refire.
 
-### How do I tell a cancelled turn apart from one that finished normally? <a id="faq-detect"/>
+### How do I tell a cancelled run apart from one that finished normally? <a id="faq-detect"/>
 
-`turn.end(reason)` reports the reason on the channel. Clients receive it through the view's turn-end event. The reason is `'cancelled'` for a cancel and `'complete'` for a normal finish.
+`run.end(reason)` reports the reason on the channel. Clients receive it through the view's `run` lifecycle event. The reason is `'cancelled'` for a cancel and `'complete'` for a normal finish.
 
 ### Does cancel cost a message? <a id="faq-pricing"/>
 
diff --git a/src/pages/docs/ai-transport/features/chain-of-thought.mdx b/src/pages/docs/ai-transport/features/chain-of-thought.mdx
index 928537c942..3fa5f57f7e 100644
--- a/src/pages/docs/ai-transport/features/chain-of-thought.mdx
+++ b/src/pages/docs/ai-transport/features/chain-of-thought.mdx
@@ -9,6 +9,8 @@ redirect_from:
 
 Chain of thought streams reasoning content alongside the main response text. The codec supports multiple stream types within a single turn. Text and reasoning are delivered as separate streams that render independently in the UI.
 
+![Diagram showing reasoning and response tokens streaming as parallel parts within the same Run](../../../../images/content/diagrams/ait-chain-of-thought.png)
+
 ## How it works <a id="how-it-works"/>
 
 When an LLM produces reasoning or thinking tokens, the codec multiplexes them alongside text tokens on the same Ably channel. Each stream type is tagged so the client routes reasoning content to one part of the UI and response text to another.
@@ -18,23 +20,29 @@ With the Vercel AI SDK integration, reasoning arrives as a separate `reasoning`
 <Code>
 ```javascript
 app.post('/api/chat', async (req, res) => {
-  const { turnId, clientId, messages } = req.body;
-  const turn = transport.newTurn({ turnId, clientId });
+  const invocation = Invocation.fromJSON(await req.json());
+  const session = createAgentSession({ client: ably, channelName: invocation.sessionName, codec: UIMessageCodec });
+  await session.connect();
+  const run = session.createRun(invocation, { signal: req.signal });
+
+  await run.start();
+  await run.loadConversation();
 
   const result = streamText({
     model: anthropic('claude-sonnet-4-20250514'),
-    messages,
-    abortSignal: turn.abortSignal,
+    messages: run.messages,
+    abortSignal: run.abortSignal,
   });
 
-  await turn.streamResponse(result.toUIMessageStream());
-  await turn.end('complete');
+  const { reason } = await run.pipe(result.toUIMessageStream());
+  await run.end(reason);
+  session.close();
   res.json({ ok: true });
 });
 ```
 </Code>
 
-No additional server configuration is needed. If the model produces reasoning tokens, the codec encodes them as a distinct stream within the turn.
+No additional server configuration is needed. If the model produces reasoning tokens, the codec encodes them as a distinct stream within the run.
 
 ## Display reasoning in the UI <a id="displaying-reasoning"/>
 
@@ -42,10 +50,10 @@ On the client, message nodes contain both text and reasoning content. Render the
 
 <Code>
 ```javascript
-const { nodes } = useView({ transport });
+const { messages } = useView();
 
-for (const node of nodes) {
-  for (const part of node.message.parts) {
+for (const { message } of messages) {
+  for (const part of message.parts) {
     if (part.type === 'reasoning') {
       renderThinkingPanel(part.reasoning);
     } else if (part.type === 'text') {
@@ -66,8 +74,8 @@ Chain of thought support depends on the model and the codec. Not all models prod
 
 - A model that produces reasoning but the codec does not surface it folds reasoning into the text stream. Update the codec or the framework integration if you need it separated.
 - Reasoning tokens are often longer than the final response. They count toward the channel's message rate and storage like any other tokens. See [token streaming](/docs/ai-transport/features/token-streaming#rollup) for rollup tuning.
-- A cancelled turn aborts both streams. Partial reasoning content stays with status `aborted`.
-- Two reasoning streams in the same turn are exposed in the same order they were emitted by the model. Multiple distinct reasoning episodes are common with tool-augmented agents.
+- A cancelled run aborts both streams. Partial reasoning content stays with status `cancelled`.
+- Two reasoning streams in the same run are exposed in the same order they were emitted by the model. Multiple distinct reasoning episodes are common with tool-augmented agents.
 - A client that does not render reasoning parts still receives them on the channel. Filter at the render layer if you want to hide them by default.
 
 ## FAQ <a id="faq"/>
diff --git a/src/pages/docs/ai-transport/features/concurrent-turns.mdx b/src/pages/docs/ai-transport/features/concurrent-turns.mdx
index 5139f230b0..c5176ba75d 100644
--- a/src/pages/docs/ai-transport/features/concurrent-turns.mdx
+++ b/src/pages/docs/ai-transport/features/concurrent-turns.mdx
@@ -7,107 +7,130 @@ intro: "Your application runs multiple AI request-response cycles on one session
 
 Concurrent turns let multiple request-response cycles run at the same time on one session. Each turn has its own stream, cancel handle, and lifecycle. This is what makes interruption, multi-user sessions, and multi-agent architectures possible.
 
+![Diagram showing two concurrent Runs multiplexed on a single channel by runId](../../../../images/content/diagrams/ait-concurrent-turns.png)
+
 ## How it works <a id="how-it-works"/>
 
-Turns are multiplexed on the Ably channel via `turnId`. Every message published during a turn (text deltas, tool calls, lifecycle events) carries a header identifying its turn. The client transport reads these headers and routes each message to the correct turn's stream.
+Turns are multiplexed on the Ably channel via `runId`. Every message published during a [Run](/docs/ai-transport/concepts/runs) (text deltas, tool calls, lifecycle events) carries a header identifying its Run. The client session reads these headers and routes each message to the correct Run's stream.
 
 <Code>
 ```javascript
-const turn1 = await view.send([
-  { id: crypto.randomUUID(), role: 'user', parts: [{ type: 'text', text: 'Summarize the report' }] },
-]);
-const turn2 = await view.send([
-  { id: crypto.randomUUID(), role: 'user', parts: [{ type: 'text', text: 'What are the key risks?' }] },
-]);
-
-for await (const chunk of turn1.stream) {
-  renderToPanel('summary', chunk);
-}
-
-for await (const chunk of turn2.stream) {
-  renderToPanel('risks', chunk);
-}
+const run1 = await view.send(UIMessageCodec.createUserMessage({
+  id: crypto.randomUUID(),
+  role: 'user',
+  parts: [{ type: 'text', text: 'Summarize the report' }],
+}));
+const run2 = await view.send(UIMessageCodec.createUserMessage({
+  id: crypto.randomUUID(),
+  role: 'user',
+  parts: [{ type: 'text', text: 'What are the key risks?' }],
+}));
+
+// Subscribe to lifecycle events on the session's tree to observe completion:
+const off = session.tree.on('run', (event) => {
+  if (event.runId === run1.runId && event.type === 'end') renderToPanel('summary', 'done');
+  if (event.runId === run2.runId && event.type === 'end') renderToPanel('risks', 'done');
+});
 ```
 </Code>
 
-On the server, each turn is handled independently. The server transport creates a separate turn object per request, each with its own abort signal and lifecycle:
+On the agent side, each Run is handled independently. The agent session creates a separate `Run` per invocation, each with its own abort signal and lifecycle:
 
 <Code>
 ```javascript
 app.post('/api/chat', async (req, res) => {
-  const { turnId, clientId, messages } = req.body;
-  const turn = transport.newTurn({ turnId, clientId });
+  const invocation = Invocation.fromJSON(await req.json());
+  const session = createAgentSession({ client: ably, channelName: invocation.sessionName, codec: UIMessageCodec });
+  await session.connect();
+  const run = session.createRun(invocation, { signal: req.signal });
 
-  await turn.start();
+  await run.start();
+  await run.loadConversation();
 
   const result = streamText({
     model: anthropic('claude-sonnet-4-20250514'),
-    messages,
-    abortSignal: turn.abortSignal,
+    messages: run.messages,
+    abortSignal: run.abortSignal,
   });
 
-  await turn.streamResponse(result.toUIMessageStream());
-  await turn.end('complete');
+  const { reason } = await run.pipe(result.toUIMessageStream());
+  await run.end(reason);
+  session.close();
   res.json({ ok: true });
 });
 ```
 </Code>
 
-## Track active turns <a id="tracking-active-turns"/>
+## Track active runs <a id="tracking-active-runs"/>
 
-`useActiveTurns` returns a map of which clients have which turns in progress:
+`session.view.runs()` returns the visible Runs as projection-free `RunInfo` snapshots. Filter by status and `clientId`:
 
 <Code>
 ```javascript
-const activeTurns = useActiveTurns({ transport });
+const { session } = useClientSession();
+const runs = session.view.runs();
 
-for (const [clientId, turnIds] of activeTurns) {
-  console.log(`${clientId} has ${turnIds.size} active turn(s)`);
+for (const run of runs.filter((r) => r.status === 'active')) {
+  console.log(`${run.clientId} has active run ${run.runId}`);
 }
 
-const isAgentStreaming = activeTurns.has('agent-1');
+const isAgentStreaming = runs.some((r) => r.status === 'active' && r.clientId === 'agent-1');
 ```
 </Code>
 
-The map updates in real time across every connected client. A turn that starts or ends anywhere on the channel updates every subscriber's `useActiveTurns` immediately.
+The view updates in real time across every connected client. A Run that starts or ends anywhere on the channel updates every subscriber's view immediately.
 
-## Scope cancellation to a turn <a id="scoped-cancellation"/>
+## Cancel one run without touching the others <a id="scoped-cancellation"/>
 
-Cancel one turn without affecting others by passing a `turnId` filter:
+Cancel via the handle the client owns synchronously:
 
 <Code>
 ```javascript
-await transport.cancel({ turnId: turn1.turnId });
-// turn2 continues streaming
+await run1.cancel();
+// run2 continues streaming
 ```
 </Code>
 
-The default cancel (`{ own: true }`) cancels every turn started by this client. For concurrent turns, scoped cancellation is essential.
+To cancel all your active Runs (Stop button), filter `session.view.runs()` first:
 
-| Filter | Effect |
-| --- | --- |
-| `{ turnId }` | Cancel one specific turn. |
-| `{ own: true }` | Cancel every turn started by this client. |
-| `{ clientId }` | Cancel every turn by a specific client. |
-| `{ all: true }` | Cancel every active turn on the channel. |
+<Code>
+```javascript
+const myClientId = ably.auth.clientId;
+const myActive = session.view.runs().filter((r) => r.status === 'active' && r.clientId === myClientId);
+await Promise.all(myActive.map((r) => session.cancel(r.runId)));
+```
+</Code>
 
-See [cancellation](/docs/ai-transport/features/cancellation) for the full cancel API, including server-side authorisation and abort hooks.
+See [cancellation](/docs/ai-transport/features/cancellation) for the full cancel API, including agent-side authorisation hooks.
 
-## Wait for turns to complete <a id="waiting-for-turns"/>
+## Wait for runs to complete <a id="waiting-for-runs"/>
 
-`transport.waitForTurn()` returns a promise that resolves when matching turns complete:
+Each `ActiveRun` exposes `runId: Promise<string>` (resolves with the agent-minted id once `ai-run-start` is observed). To wait for a Run to terminate, await the id and then subscribe to the session tree's `run` events:
 
 <Code>
 ```javascript
-await transport.waitForTurn({ turnId: turn1.turnId });
-
-await transport.waitForTurn({ own: true });
+function whenRunEnds(session, runId) {
+  return new Promise((resolve) => {
+    const off = session.tree.on('run', (event) => {
+      if (event.runId === runId && event.type === 'end') {
+        off();
+        resolve(event.reason);
+      }
+    });
+  });
+}
 
-await transport.waitForTurn({ all: true });
+const run1 = await view.send(UIMessageCodec.createUserMessage({
+  id: crypto.randomUUID(),
+  role: 'user',
+  parts: [{ type: 'text', text: 'Hello' }],
+}));
+const run1Id = await run1.runId;
+await whenRunEnds(session, run1Id);
 ```
 </Code>
 
-Use this to sequence work: send a follow-up only after the first response completes, or disable a submit button until pending turns resolve.
+Use this to sequence work: send a follow-up only after the first response completes, or disable a submit button until the run resolves.
 
 ## Use cases <a id="use-cases"/>
 
@@ -117,10 +140,14 @@ Cancel the current turn and immediately start a new one:
 
 <Code>
 ```javascript
-await transport.cancel({ own: true });
-const newTurn = await view.send([
-  { id: crypto.randomUUID(), role: 'user', parts: [{ type: 'text', text: 'Actually, focus on the budget instead' }] },
-]);
+const active = session.view.runs().filter((r) => r.status === 'active');
+await Promise.all(active.map((r) => session.cancel(r.runId)));
+
+const newRun = await view.send(UIMessageCodec.createUserMessage({
+  id: crypto.randomUUID(),
+  role: 'user',
+  parts: [{ type: 'text', text: 'Actually, focus on the budget instead' }],
+}));
 ```
 </Code>
 
@@ -128,51 +155,57 @@ See [Interruption](/docs/ai-transport/features/interruption) for the full patter
 
 ### Multi-user sessions <a id="multi-user"/>
 
-Two users prompting the same session at the same time. Each user's turn is independent:
+Two users prompting the same session at the same time. Each user's Run is independent:
 
 <Code>
 ```javascript
-const turnA = await viewA.send([
-  { id: crypto.randomUUID(), role: 'user', parts: [{ type: 'text', text: 'What does section 3 mean?' }] },
-]);
-
-const turnB = await viewB.send([
-  { id: crypto.randomUUID(), role: 'user', parts: [{ type: 'text', text: 'Summarize section 5' }] },
-]);
+const runA = await viewA.send(UIMessageCodec.createUserMessage({
+  id: crypto.randomUUID(),
+  role: 'user',
+  parts: [{ type: 'text', text: 'What does section 3 mean?' }],
+}));
+
+const runB = await viewB.send(UIMessageCodec.createUserMessage({
+  id: crypto.randomUUID(),
+  role: 'user',
+  parts: [{ type: 'text', text: 'Summarize section 5' }],
+}));
 ```
 </Code>
 
-Both turns stream concurrently on the shared channel.
+Both Runs stream concurrently on the shared channel.
 
 ### Multi-agent <a id="multi-agent"/>
 
-An orchestrator dispatches work to multiple sub-agents, each streaming concurrently on the same channel:
+An orchestrator dispatches work to multiple sub-agents, each streaming concurrently on the same channel. Each sub-agent receives its own Invocation with a unique `runId`:
 
 <Code>
 ```javascript
 app.post('/api/chat', async (req, res) => {
-  const { messages } = req.body;
-  const researchTurn = transport.newTurn({ turnId: 'research', clientId: 'researcher' });
-  const analysisTurn = transport.newTurn({ turnId: 'analysis', clientId: 'analyst' });
-
-  await Promise.all([
-    runResearchAgent(researchTurn, messages),
-    runAnalysisAgent(analysisTurn, messages),
-  ]);
+  const invocation = Invocation.fromJSON(await req.json());
+  const session = createAgentSession({ client: ably, channelName: invocation.sessionName, codec: UIMessageCodec });
+  await session.connect();
+
+  // The orchestrator creates additional Invocations for sub-agents and POSTs
+  // to their endpoints. Each sub-agent runs its own session.createRun(...)
+  // against the same channel; their messages multiplex by runId.
+  const researchRun = session.createRun(invocation, { signal: req.signal });
+  await researchRun.start();
+  await runResearchAgent(researchRun);
+
   res.json({ ok: true });
 });
 ```
 </Code>
 
-The client sees both agent responses arriving in parallel, each tagged with its own turn ID and client ID.
+The client sees both agent responses arriving in parallel, each tagged with its own `runId` and `clientId`.
 
 ## Edge cases and unhappy paths <a id="edge-cases"/>
 
-- Concurrent turns share the channel's message rate. A burst of parallel streams approaches the per-connection rate limit faster than a single stream. See [token streaming](/docs/ai-transport/features/token-streaming#rollup) for rollup behaviour.
-- A scoped cancel against a `turnId` that no longer matches an active turn is a no-op. Cancellation does not error on absence.
-- `waitForTurn({ all: true })` includes turns started by other clients. If you only want to wait for your own, use `{ own: true }`.
-- A multi-agent setup with the same `turnId` across sub-agents collides on the channel. Generate a unique `turnId` per sub-agent.
-- Two clients sending at the same time produce two turns. The conversation tree shows both as siblings of the same parent message.
+- Concurrent Runs share the channel's message rate. A burst of parallel streams approaches the per-connection rate limit faster than a single stream. See [token streaming](/docs/ai-transport/features/token-streaming#rollup) for rollup behaviour.
+- `session.cancel(runId)` against a `runId` that no longer matches an active Run is a no-op. Cancellation does not error on absence.
+- A multi-agent setup must let each sub-agent's `createRun` mint its own `runId`; do not pass a shared `RunRuntime.runId` across sub-agents or their messages will collide on the channel. The default minting path (one `crypto.randomUUID()` per `createRun`) is already unique.
+- Two clients sending at the same time produce two Runs. The conversation tree shows both as siblings of the same parent message.
 
 ## FAQ <a id="faq"/>
 
@@ -180,21 +213,21 @@ The client sees both agent responses arriving in parallel, each tagged with its
 
 There is no hard limit on the channel side. Practical limits come from your application's concurrency (server compute, model rate limits) and the channel's message rate. Plan for the publish rate, not the turn count.
 
-### Does the client need to track turn IDs? <a id="faq-track-ids"/>
+### Does the client need to track run IDs? <a id="faq-track-ids"/>
 
-The transport tracks turn IDs internally. Hold onto the `turn` handle returned by `send()` only if you need to cancel it specifically or wait for it specifically.
+The session tracks Run identity internally. Hold onto the `ActiveRun` returned by `view.send()` only if you need to cancel it specifically or wait for it specifically.
 
-### How do I tell which turn a message belongs to? <a id="faq-message-turn"/>
+### How do I tell which run a message belongs to? <a id="faq-message-turn"/>
 
-Each message carries its `turnId` in the header. `useView`'s tree exposes the relationship; you do not parse headers manually.
+Each message carries its `run-id` in `extras.ai.transport`. The session's tree exposes the relationship through `view.runOf(codecMessageId)`; you do not parse headers manually.
 
 ### Can two turns run on behalf of the same user? <a id="faq-same-user"/>
 
 Yes. The `clientId` does not constrain how many turns a client has open. Scoped cancellation lets you target one of them.
 
-### Why use turn IDs instead of message IDs? <a id="faq-ids"/>
+### Why use run IDs instead of message IDs? <a id="faq-ids"/>
 
-A turn is one unit of agent work that produces multiple messages. The turn ID groups every message the agent publishes for that work, so cancel and wait operate on the unit a user understands.
+A Run is one unit of agent work that produces multiple messages. The `runId` groups every message the agent publishes for that work, so cancel and wait operate on the unit a user understands.
 
 ## Related features <a id="related"/>
 
diff --git a/src/pages/docs/ai-transport/features/double-texting.mdx b/src/pages/docs/ai-transport/features/double-texting.mdx
index 69219bea1e..f7653c9553 100644
--- a/src/pages/docs/ai-transport/features/double-texting.mdx
+++ b/src/pages/docs/ai-transport/features/double-texting.mdx
@@ -7,18 +7,28 @@ intro: "Your users send a follow-up before the previous response finishes. AI Tr
 
 Double texting is when a user sends a new message while the agent is still streaming a response. AI Transport supports this through [concurrent turns](/docs/ai-transport/features/concurrent-turns). The new message starts a new turn that runs alongside the existing one. Your application chooses between three patterns: concurrent, queued, or cancel-then-send.
 
+![Diagram showing a user sending a follow-up message while the agent is still streaming a response](../../../../images/content/diagrams/ait-double-texting.png)
+
 ## Default behaviour: concurrent <a id="default-behavior"/>
 
 Sending a message while the agent is streaming starts a new concurrent turn. Both the existing response and the new turn run in parallel:
 
 <Code>
 ```javascript
-await send([{ id: crypto.randomUUID(), role: 'user', parts: [{ type: 'text', text: 'Explain quantum computing' }] }]);
+await send(UIMessageCodec.createUserMessage({
+  id: crypto.randomUUID(),
+  role: 'user',
+  parts: [{ type: 'text', text: 'Explain quantum computing' }],
+}));
 
 // Agent starts streaming a response.
 // User sends another message before the response finishes.
 
-await send([{ id: crypto.randomUUID(), role: 'user', parts: [{ type: 'text', text: 'Also, what is superposition?' }] }]);
+await send(UIMessageCodec.createUserMessage({
+  id: crypto.randomUUID(),
+  role: 'user',
+  parts: [{ type: 'text', text: 'Also, what is superposition?' }],
+}));
 
 // Both turns stream concurrently.
 ```
@@ -32,23 +42,33 @@ To prevent concurrent turns and queue messages instead, detect active turns and
 
 <Code>
 ```javascript
-const activeTurns = useActiveTurns({ transport });
+const { session } = useClientSession();
+const view = useView();
+const isStreaming = session.view.runs().some((r) => r.status === 'active');
 
 const handleSend = async (text) => {
-  if (activeTurns.size > 0) {
+  if (isStreaming) {
     addToQueue(text);
     return;
   }
 
-  await send([{ id: crypto.randomUUID(), role: 'user', parts: [{ type: 'text', text }] }]);
+  await view.send(UIMessageCodec.createUserMessage({
+    id: crypto.randomUUID(),
+    role: 'user',
+    parts: [{ type: 'text', text }],
+  }));
 };
 
 useEffect(() => {
-  if (activeTurns.size === 0 && queue.length > 0) {
+  if (!isStreaming && queue.length > 0) {
     const next = queue.shift();
-    send([{ id: crypto.randomUUID(), role: 'user', parts: [{ type: 'text', text: next }] }]);
+    view.send(UIMessageCodec.createUserMessage({
+      id: crypto.randomUUID(),
+      role: 'user',
+      parts: [{ type: 'text', text: next }],
+    }));
   }
-}, [activeTurns.size]);
+}, [isStreaming]);
 ```
 </Code>
 
@@ -56,21 +76,27 @@ This gives users feedback that their message was received and will be processed
 
 ## Cancel and re-prompt <a id="cancel-then-send"/>
 
-To cancel the current turn before sending the new message, use the [interruption](/docs/ai-transport/features/interruption) pattern:
+To cancel the current Run before sending the new message, use the [interruption](/docs/ai-transport/features/interruption) pattern:
 
 <Code>
 ```javascript
-const handleSend = async (text) => {
-  if (activeTurns.size > 0) {
-    await transport.cancel();
-  }
+const { session } = useClientSession();
+const view = useView();
 
-  await send([{ id: crypto.randomUUID(), role: 'user', parts: [{ type: 'text', text }] }]);
+const handleSend = async (text) => {
+  const active = session.view.runs().filter((r) => r.status === 'active');
+  await Promise.all(active.map((r) => session.cancel(r.runId)));
+
+  await view.send(UIMessageCodec.createUserMessage({
+    id: crypto.randomUUID(),
+    role: 'user',
+    parts: [{ type: 'text', text }],
+  }));
 };
 ```
 </Code>
 
-The current response stops, and the new message starts a fresh turn. Use this when the new message supersedes the previous one.
+The current response stops, and the new message starts a fresh Run. Use this when the new message supersedes the previous one.
 
 ## Choose a pattern <a id="choosing-a-pattern"/>
 
diff --git a/src/pages/docs/ai-transport/features/history.mdx b/src/pages/docs/ai-transport/features/history.mdx
index b99b1c0053..88abdb0d7e 100644
--- a/src/pages/docs/ai-transport/features/history.mdx
+++ b/src/pages/docs/ai-transport/features/history.mdx
@@ -7,23 +7,25 @@ intro: "Your users see the conversation when they come back to it. AI Transport
 
 History comes from the Ably channel itself. Every message (user prompts, agent responses, lifecycle events) persists on the channel. Clients load history on connect and paginate backward through the conversation. No separate database is required.
 
+![Diagram showing a client loading conversation history from the channel and paginating older messages on scroll](../../../../images/content/diagrams/ait-history-replay.png)
+
 A minimal history-loading hook:
 
 <Code>
 ```javascript
-const { nodes, hasOlder, loadOlder } = useView({ transport, limit: 30 });
+const { messages, hasOlder, loadOlder } = useView({ limit: 30 });
 ```
 </Code>
 
 ## How it works <a id="how-it-works"/>
 
-The client transport loads history using `view.loadOlder()` with the `untilAttach` parameter. `untilAttach` keeps history and the live subscription gapless: every message between the historical window and the latest live message is accounted for.
+`useView` loads history using `view.loadOlder()` with the `untilAttach` parameter. `untilAttach` keeps history and the live subscription gapless: every message between the historical window and the latest live message is accounted for.
 
-`loadOlder()` returns `Promise<void>`. It expands the view window internally instead of returning a page; the view's `nodes` array updates with the older messages.
+`loadOlder()` returns `Promise<void>`. It expands the view window internally instead of returning a page; the view's `messages` array updates with the older messages.
 
 <Code>
 ```javascript
-const { nodes, hasOlder, loadOlder } = useView({ transport, limit: 30 });
+const { messages, hasOlder, loadOlder } = useView({ limit: 30 });
 
 if (hasOlder) {
   await loadOlder();
@@ -37,7 +39,7 @@ Load more messages when the user scrolls toward the top of the conversation:
 
 <Code>
 ```javascript
-const { nodes, hasOlder, loading, loadOlder } = useView({ transport, limit: 30 });
+const { messages, hasOlder, loading, loadOlder } = useView({ limit: 30 });
 
 function handleScrollToTop() {
   if (hasOlder && !loading) {
@@ -75,11 +77,11 @@ Persist completed turns to your own store as they end. AI Transport supports hyd
 
 ### Why does `loadOlder()` return `Promise<void>` instead of the messages? <a id="faq-loadolder-shape"/>
 
-The view expands its internal window and emits an update. Components subscribed to `nodes` re-render with the older messages. This keeps the view as the single source of truth.
+The view expands its internal window and emits an update. Components subscribed to `messages` re-render with the older messages. This keeps the view as the single source of truth.
 
-### Does history include cancelled or aborted turns? <a id="faq-aborted"/>
+### Does history include cancelled turns? <a id="faq-cancelled"/>
 
-Yes. Aborted messages keep their partial content and a status of `aborted`. The view renders them in place.
+Yes. Cancelled messages keep their partial content with a status of `cancelled`. The view renders them in place.
 
 ### Can I paginate forward as well as backward? <a id="faq-forward"/>
 
diff --git a/src/pages/docs/ai-transport/features/human-in-the-loop.mdx b/src/pages/docs/ai-transport/features/human-in-the-loop.mdx
index e7408f9c1c..5ccb87897a 100644
--- a/src/pages/docs/ai-transport/features/human-in-the-loop.mdx
+++ b/src/pages/docs/ai-transport/features/human-in-the-loop.mdx
@@ -13,19 +13,21 @@ redirect_from:
   - /docs/guides/ai-transport/openai/openai-human-in-the-loop
 ---
 
-Human-in-the-loop uses the tool-calling primitives to create approval gates. The agent requests approval, the turn pauses, and any connected client approves or rejects. Because the session is durable, the approval request reaches the user even after a reconnect or device switch.
+Human-in-the-loop uses the tool-calling primitives to create approval gates. The agent requests approval, the run suspends, and any connected client approves or rejects. Because the session is durable, the approval request reaches the user even after a reconnect or device switch.
+
+![Diagram showing an agent suspending mid-Run for a human approval and resuming when any client responds](../../../../images/content/diagrams/ait-human-in-the-loop.png)
 
 ## How it works <a id="how-it-works"/>
 
-The pattern builds on [tool calling](/docs/ai-transport/features/tool-calling). The agent defines a tool that requires human approval. When the LLM invokes that tool, the turn ends with a pending tool call. The client presents the approval request to the user. When the user approves or rejects, the client submits the result via `view.update()`, which triggers a continuation turn.
+The pattern builds on [tool calling](/docs/ai-transport/features/tool-calling). The agent defines a tool that requires human approval. When the LLM invokes that tool, the agent calls `run.suspend()` instead of `run.end()` so the Run stays live, and the pending tool call is published to the channel. The client presents the approval request to the user. When the user approves or rejects, the client publishes a `tool-approval-response` input addressed to the suspended assistant, and a continuation invocation resumes the Run under the same `runId`.
 
 The flow:
 
 1. The agent streams a response that includes a tool call requiring approval.
-2. The turn ends. The pending tool call is published to the channel.
+2. The LLM's stream finishes with `finishReason: 'tool-calls'`. The agent calls `run.suspend()` and the pending tool call is visible on the channel.
 3. Any connected client renders the pending approval.
-4. The user approves or rejects. The client calls `view.update()` with the result.
-5. A continuation turn starts. The agent receives the approval result and proceeds.
+4. The user approves or rejects. The client publishes a `tool-approval-response` input addressed to the pending message, then POSTs a continuation invocation to the agent.
+5. A continuation invocation enters the same `runId` and the agent picks up the approval result and proceeds.
 
 ## Define an approval tool <a id="approval-tool"/>
 
@@ -53,15 +55,21 @@ const result = streamText({
       },
     },
   },
-  abortSignal: turn.abortSignal,
+  abortSignal: run.abortSignal,
 });
 
-const { reason } = await turn.streamResponse(result.toUIMessageStream());
-await turn.end(reason);
+const pipeResult = await run.pipe(result.toUIMessageStream());
+const outcome = await vercelRunOutcome(pipeResult, result.finishReason);
+
+if (outcome === 'suspend') {
+  await run.suspend();
+} else {
+  await run.end(outcome);
+}
 ```
 </Code>
 
-When the LLM decides an action needs approval, it invokes `requestApproval`. The turn ends with the tool call pending.
+When the LLM decides an action needs approval, it invokes `requestApproval`. `streamText` finishes with `finishReason: 'tool-calls'`; [`vercelRunOutcome`](/docs/ai-transport/api/javascript/vercel/run-outcome) translates that to `'suspend'`, so the agent calls `run.suspend()` and the pending tool call stays on the channel for any connected client to act on.
 
 ## Handle approval on the client <a id="client-approval"/>
 
@@ -69,46 +77,52 @@ On the client, detect pending approval requests and present them to the user:
 
 <Code>
 ```javascript
-const { nodes } = useView({ transport });
+const { messages, runOf, send } = useView();
 
-const pendingNode = nodes.find((n) =>
-  n.message.parts?.some(
-    (p) => p.type === 'dynamic-tool' && p.toolName === 'requestApproval' && p.state === 'input-available',
+const pending = messages.find(({ message }) =>
+  message.parts?.some(
+    (p) => p.type === 'dynamic-tool' && p.toolName === 'requestApproval' && p.state === 'approval-requested',
   ),
 );
 
-const pendingApproval = pendingNode?.message.parts?.find(
-  (p) => p.type === 'dynamic-tool' && p.state === 'input-available',
+const pendingApproval = pending?.message.parts?.find(
+  (p) => p.type === 'dynamic-tool' && p.state === 'approval-requested',
 );
 
-if (pendingNode && pendingApproval) {
-  const { action, details } = pendingApproval.args;
+if (pending && pendingApproval) {
+  const { action, details } = pendingApproval.input;
+  const runId = runOf(pending.codecMessageId).runId;
+
+  const respond = async (approved) => {
+    const run = await send(
+      {
+        kind: 'tool-approval-response',
+        codecMessageId: pending.codecMessageId,
+        payload: { toolCallId: pendingApproval.toolCallId, approved },
+      },
+      { runId },
+    );
+
+    // Wake the agent so it picks up the response and resumes.
+    await fetch('/api/chat', {
+      method: 'POST',
+      body: JSON.stringify(run.toInvocation().toJSON()),
+    });
+  };
 
   return (
     <ApprovalDialog
       action={action}
       details={details}
-      onApprove={() =>
-        view.update(pendingNode.id, [{
-          type: 'tool-output-available',
-          toolCallId: pendingApproval.toolCallId,
-          output: { approved: true },
-        }])
-      }
-      onReject={() =>
-        view.update(pendingNode.id, [{
-          type: 'tool-output-available',
-          toolCallId: pendingApproval.toolCallId,
-          output: { approved: false, reason: 'User declined' },
-        }])
-      }
+      onApprove={() => respond(true)}
+      onReject={() => respond(false)}
     />
   );
 }
 ```
 </Code>
 
-`view.update()` submits the result and triggers a continuation turn. The agent receives `{ approved: true }` as the tool result and proceeds, or receives the rejection and adjusts.
+The response is addressed to the suspended assistant message by `codecMessageId`, and reusing the original `runId` keeps the resume on the same run. The agent sees the approval as the tool result and proceeds.
 
 ## Approve from any device <a id="multi-device"/>
 
@@ -124,10 +138,10 @@ The agent's turn has already ended, so no connection or timeout is at risk. The
 
 ## Edge cases and unhappy paths <a id="edge-cases"/>
 
-- Two devices submitting at the same time race. The first `view.update()` wins; the second submits to an already-resolved tool call and the agent ignores it. Guard against double-submit at the application layer if both devices need to see a consistent decision.
-- A user who rejects must trigger an agent path that handles rejection. The LLM only sees the output you supply; an empty rejection result is ambiguous.
+- Two devices submitting at the same time race. The first response wins; the second submits to an already-resolved tool call and the agent ignores it. Guard against double-submit at the application layer if both devices need to see a consistent decision.
+- A user who rejects must trigger an agent path that handles rejection. The LLM only sees the response you supply; an empty rejection is ambiguous.
 - A pending approval that never receives a response stays pending forever. Add an explicit timeout in your application if you need one; AI Transport does not impose one.
-- The continuation turn runs as a fresh agent invocation. Make sure your server endpoint hydrates the conversation history correctly so the LLM sees the approval result in context.
+- The resume runs as a fresh agent invocation. Make sure your server endpoint hydrates the conversation history correctly so the LLM sees the approval result in context.
 
 ## FAQ <a id="faq"/>
 
diff --git a/src/pages/docs/ai-transport/features/interruption.mdx b/src/pages/docs/ai-transport/features/interruption.mdx
index 1249ff350e..99b8b81bb2 100644
--- a/src/pages/docs/ai-transport/features/interruption.mdx
+++ b/src/pages/docs/ai-transport/features/interruption.mdx
@@ -1,133 +1,133 @@
 ---
 title: "Interruption"
 meta_description: "Let users interrupt AI agents mid-stream with Ably AI Transport. Cancel-then-send and send-alongside patterns for responsive AI interactions."
-meta_keywords: "AI interruption, barge-in, cancel and send, concurrent turns, AI Transport, Ably"
-intro: "Your users can change direction mid-response. AI Transport's session layer lets a client cancel the in-progress turn and start a new one without breaking the stream."
-redirect_from:
-  - /docs/ai-transport/features/barge-in
+meta_keywords: "AI interruption, interrupt, cancel and send, concurrent turns, AI Transport, Ably"
+intro: "Your users can change direction mid-response. AI Transport's session layer lets a client cancel the in-progress Run and start a new one without breaking the stream."
 ---
 
-Interruption lets a user send a new message while the agent is still streaming a response. The new message creates a new [turn](/docs/ai-transport/concepts/turns) on the [session](/docs/ai-transport/concepts/sessions); whether the existing turn is cancelled first or runs in parallel is up to the application. In voice contexts this pattern is also known as barge-in.
+Interruption is the pattern where a user sends a new message while the agent is still streaming a response. The new message creates a new turn on the [session](/docs/ai-transport/concepts/sessions); whether the existing turn is cancelled first or runs in parallel is up to you.
 
 ![Diagram showing session continuity during interruption](../../../../images/content/diagrams/ait-session-continuity.png)
 
-A minimal interruption call cancels the active turn and sends a new message:
+A minimal interruption cancels the active Run and sends a new message:
 
 <Code>
 ```javascript
-await transport.cancel();
-await transport.view.send([{ id: crypto.randomUUID(), role: 'user', parts: [{ type: 'text', text: 'Wait, focus on the budget instead' }] }]);
+const active = session.view.runs().filter((run) => run.status === 'active');
+await Promise.all(active.map((run) => session.cancel(run.runId)));
+
+await session.view.send(UIMessageCodec.createUserMessage({
+  id: crypto.randomUUID(),
+  role: 'user',
+  parts: [{ type: 'text', text: 'Wait, make it 5 days.' }],
+}));
 ```
 </Code>
 
 ## How it works <a id="how-it-works"/>
 
-Turns are independent units of agent work on a session. The session is bidirectional, so the client publishes a cancel signal on the channel at any time, regardless of whether the response is still in flight. A new turn does not have to wait for the previous one to finish.
+Each turn becomes a [Run](/docs/ai-transport/concepts/runs) on the session. The session is bidirectional, so a client can publish a cancel signal at any time, even while the response is mid-flight. A new `send` doesn't have to wait for the previous Run to finish.
 
-There are two patterns for handling interruption:
+Two patterns:
 
-| Pattern | Behaviour | Use case |
+| Pattern | Behaviour | When to use it |
 | --- | --- | --- |
-| Cancel-then-send | Cancel the active turn, then send a new message. | Stop button followed by a new prompt. |
-| Send-alongside | Send a new message while the active turn continues. | Follow-up without waiting. |
+| Cancel-then-send | Cancel the active Run, then send the new message. | A Stop button followed by a new prompt. |
+| Send-alongside | Send the new message while the active Run continues. | Quick follow-up that doesn't invalidate the in-flight response. |
 
-With cancel-then-send, the active turn is aborted before the new message dispatches. The agent stops generating, cleans up, and starts a fresh turn. With send-alongside, both turns run concurrently, each with its own stream and cancel handle.
+With cancel-then-send, the active Run aborts before the new message dispatches. The agent stops generating, ends the Run with reason `'cancelled'`, and the new Run starts clean. With send-alongside, both Runs run concurrently (each with its own stream and its own cancel handle). See [concurrent turns](/docs/ai-transport/features/concurrent-turns) for the multiplexing model.
 
 ## Implement cancel-then-send <a id="cancel-then-send"/>
 
-Detect whether a turn is active, cancel it, then send a new message. This pattern mimics a stop button followed by a re-prompt.
+Detect whether a Run is active, cancel it, then send the new message:
 
 <Code>
 ```javascript
-import { useActiveTurns, useClientTransport, useView } from '@ably/ai-transport/react';
+import { useClientSession, useView } from '@ably/ai-transport/react';
 
-function Chat({ chatId }) {
-  const { transport } = useClientTransport({ channelName: chatId });
-  const { send } = useView();
-  const activeTurns = useActiveTurns();
+function Chat() {
+  const { session } = useClientSession();
+  const view = useView();
 
   const handleSend = async (text) => {
-    if (activeTurns.size > 0) {
-      await transport.cancel();
-    }
-
-    await send([{ id: crypto.randomUUID(), role: 'user', parts: [{ type: 'text', text }] }]);
+    const active = view.runs().filter((run) => run.status === 'active');
+    await Promise.all(active.map((run) => session.cancel(run.runId)));
+
+    await view.send(UIMessageCodec.createUserMessage({
+      id: crypto.randomUUID(),
+      role: 'user',
+      parts: [{ type: 'text', text }],
+    }));
   };
 }
 ```
 </Code>
 
-`transport.cancel()` publishes a cancel signal on the channel. The server's `abortSignal` fires, the LLM stream stops, and the turn ends with reason `'cancelled'`. The new message is then sent on a clean turn.
+`session.cancel(runId)` publishes a cancel signal. The agent's `Run.abortSignal` fires, the LLM stream stops, and the Run ends with reason `'cancelled'`. The new message starts a clean Run.
 
 ## Implement send-alongside <a id="send-alongside"/>
 
-Send a new message without cancelling the active turn. Both turns run concurrently. The agent continues streaming the first response while processing the new input.
+Send a new message without cancelling. Both Runs stream concurrently; each `ActiveRun` carries its own `runId` and `cancel()`, and both Runs' outputs land on the same channel where they fold into the conversation tree by `runId`:
 
 <Code>
 ```javascript
-const handleSend = async (text) => {
-  await send([{ id: crypto.randomUUID(), role: 'user', parts: [{ type: 'text', text }] }]);
-};
+const followUp = await session.view.send(UIMessageCodec.createUserMessage({
+  id: crypto.randomUUID(),
+  role: 'user',
+  parts: [{ type: 'text', text: 'Also include vegan options.' }],
+}));
 ```
 </Code>
 
-Each concurrent turn has its own stream and its own cancel handle. Cancel them independently:
-
-<Code>
-```javascript
-await transport.cancel({ turnId: specificTurnId });
-```
-</Code>
+Cancel them independently with `session.cancel(specificRunId)` or `activeRun.cancel()`.
 
-## Detect active turns <a id="detecting-active-turns"/>
+## Drive the Stop / Send toggle <a id="stop-send-toggle"/>
 
-The `useActiveTurns` hook returns a `Map<clientId, Set<turnId>>` of currently streaming turns. Use it to check whether the agent is mid-response:
+`session.view.runs()` returns the visible `RunInfo` snapshots. Filter by `status === 'active'` to drive the Send / Stop toggle:
 
 <Code>
 ```javascript
-const activeTurns = useActiveTurns({ transport });
+const { session } = useClientSession();
+const isStreaming = session.view.runs().some((run) => run.status === 'active');
 
-const isStreaming = activeTurns.size > 0;
-
-const agentTurns = activeTurns.get('agent-client-id');
-const agentIsStreaming = agentTurns !== undefined && agentTurns.size > 0;
+return isStreaming
+  ? <StopButton onClick={() => cancelAll()} />
+  : <SendButton onClick={handleSend} />;
 ```
 </Code>
 
-This is what drives the toggle between a send button and a stop button, or disables input while a cancellation is in progress.
-
 ## Edge cases and unhappy paths <a id="edge-cases"/>
 
-- The cancel signal is asynchronous. A few more tokens arrive after `transport.cancel()` returns and before the agent's `abortSignal` fires. The view emits them; treat tokens after a cancel as part of the cancelled turn, not the new one.
-- A turn that cancels while waiting for a tool result ends with reason `'cancelled'`. Tool invocations triggered before the cancel still run on the server unless your handler honours the same `abortSignal`.
-- A network drop on the client cancels nothing. The server keeps streaming into the session. When the client reconnects, the response is still there. Use `useActiveTurns` to decide whether to show a stop button on reconnect.
-- Sending alongside an existing turn is rate-limited by your channel and any server-side concurrency you enforce. See [concurrent turns](/docs/ai-transport/features/concurrent-turns) for the multiplexing model.
-- The `'cancelled'` reason is reported through the view's turn events. Do not rely on the absence of further tokens to detect a cancel.
+- Cancel is asynchronous. A small tail of tokens arrives after `session.cancel(runId)` returns and before the agent's `abortSignal` fires. The view emits them on the cancelled Run; treat them as belonging to that Run, not the new one.
+- A Run cancelled while awaiting a tool result ends with `'cancelled'`. Tool calls triggered before the cancel may still run on your server unless your handler honours the same `AbortSignal`.
+- A network drop on the client cancels nothing. The agent keeps streaming into the session. When the client reconnects, the response is still there. Check `session.view.runs()` on reconnect to decide whether to show Stop.
+- Send-alongside is rate-limited by your channel and any server-side concurrency you enforce. See [concurrent turns](/docs/ai-transport/features/concurrent-turns).
+- `'cancelled'` is reported on the Run's terminal `RunEndReason`. Don't infer cancellation from the absence of further tokens; subscribe to `view.on('run', ...)` and read the lifecycle event.
 
 ## FAQ <a id="faq"/>
 
-### What happens to tokens already in flight when I cancel? <a id="faq-tokens-in-flight"/>
+### What happens to tokens already in flight when I cancel?
 
-The agent keeps publishing until its `abortSignal` fires. A small tail of tokens arrives after `cancel()` returns. The view reflects them on the cancelled turn; the new turn is unaffected.
+The agent keeps publishing until its `abortSignal` fires. A small tail of tokens arrives after `cancel()` returns. The view reflects them on the cancelled Run; the new Run is unaffected.
 
-### Can I cancel one of several concurrent turns without touching the others? <a id="faq-cancel-one"/>
+### Can I cancel one of several concurrent Runs without touching the others?
 
-Yes. Pass a `turnId` to `transport.cancel({ turnId })`. Only the matching turn is cancelled.
+Yes. `session.cancel(runId)` only cancels the matching Run. Pull `runId`s from `session.view.runs()` to target the right one.
 
-### Does `transport.cancel()` work from a different device? <a id="faq-cross-device"/>
+### Does cancel work from a different device?
 
-Yes. Any client connected to the same session publishes a cancel signal. The server receives it through its channel subscription, regardless of which client started the turn. See [cancellation](/docs/ai-transport/features/cancellation) for the authorisation model.
+Yes. Any client connected to the same session can publish a cancel. The agent receives it through its own subscription regardless of which client started the Run. See [cancellation](/docs/ai-transport/features/cancellation) for the authorisation model.
 
-### What if the server is down when I send a new message after a cancel? <a id="faq-server-down"/>
+### What if the agent endpoint is down when I send the follow-up?
 
-The cancel signal is delivered when the server reconnects to the channel. The new message creates a new turn as soon as the server's poke endpoint is reachable. The session and existing messages are unaffected.
+The Ably channel publishes still happen (the cancel and the new user message both land on the channel). The new POST retries the agent endpoint; the new Run starts as soon as the endpoint is reachable. The session and existing messages are unaffected.
 
-### How is interruption different from concurrent turns? <a id="faq-vs-concurrent"/>
+### How is interruption different from concurrent turns?
 
-Interruption is the user-facing pattern: stop and re-prompt, or send a follow-up. [Concurrent turns](/docs/ai-transport/features/concurrent-turns) is the underlying mechanism that makes both patterns possible. Multiple turns coexist on the same session.
+Interruption is the user-facing pattern (Stop and re-prompt, or quick follow-up). [Concurrent turns](/docs/ai-transport/features/concurrent-turns) is the underlying mechanism that makes both possible: multiple Runs coexisting on the same session.
 
 ## Related features <a id="related"/>
 
-- [Cancellation](/docs/ai-transport/features/cancellation): cancel signals, filters, and server-side abort handling.
-- [Concurrent turns](/docs/ai-transport/features/concurrent-turns): multiple turns running in parallel.
+- [Cancellation](/docs/ai-transport/features/cancellation): cancel signals and agent-side authorisation.
+- [Concurrent turns](/docs/ai-transport/features/concurrent-turns): multiple Runs in flight on the same session.
 - [Double texting](/docs/ai-transport/features/double-texting): handling multiple user messages in quick succession.
diff --git a/src/pages/docs/ai-transport/features/multi-device.mdx b/src/pages/docs/ai-transport/features/multi-device.mdx
index f8a66d84d1..2d93044ede 100644
--- a/src/pages/docs/ai-transport/features/multi-device.mdx
+++ b/src/pages/docs/ai-transport/features/multi-device.mdx
@@ -7,24 +7,24 @@ intro: "Your users move between devices and the conversation follows them. AI Tr
 
 A multi-device session works because the [session](/docs/ai-transport/concepts/sessions) is backed by a shared Ably channel, not a single client-to-server HTTP connection. Any device that subscribes to the channel sees every message: user prompts, agent responses, and control signals. Open a second tab, switch to a phone, or share a session with a colleague.
 
-![Diagram showing multi-device co-pilots architecture](../../../../images/content/diagrams/ai-transport-multi-device-co-pilots-architecture.png)
+![Diagram showing a user switching from laptop to phone mid-response, with the response continuing uninterrupted on the new device](../../../../images/content/diagrams/ait-multi-device-handover.png)
 
 Fan-out to multiple connected devices is automatic. There's no special configuration:
 
 <Code>
 ```javascript
-// Client A (laptop): wrap with a TransportProvider for chatId.
-<TransportProvider channelName={chatId} codec={UIMessageCodec}>
+// Client A (laptop): wrap with a ClientSessionProvider for chatId.
+<ClientSessionProvider channelName={chatId} codec={UIMessageCodec}>
   <Chat />
-</TransportProvider>
+</ClientSessionProvider>
 
-// Client B (phone): same channel name in its own TransportProvider, different device.
-<TransportProvider channelName={chatId} codec={UIMessageCodec}>
+// Client B (phone): same channel name in its own ClientSessionProvider, different device.
+<ClientSessionProvider channelName={chatId} codec={UIMessageCodec}>
   <Chat />
-</TransportProvider>
+</ClientSessionProvider>
 
-// Inside Chat, read the transport from context.
-const { transport } = useClientTransport();
+// Inside Chat, read the session from context.
+const { session } = useClientSession();
 ```
 </Code>
 
@@ -34,31 +34,32 @@ Every client connected to the same Ably channel shares the same durable session.
 
 The client transport distinguishes between own turns (started by this client) and observer turns (started by someone else). Both types are tracked, decoded, and added to the conversation tree. The UI updates for every client, regardless of who initiated the action.
 
-## Distinguish own and observer turns <a id="own-vs-observer"/>
+## Distinguish own and observer runs <a id="own-vs-observer"/>
 
-The transport separates turns initiated by the current client from those by other participants:
+The client session separates Runs initiated by the current client from those by other participants:
 
 | Type | Origin | Handle |
 | --- | --- | --- |
-| Own turn | This client sent the HTTP POST that created the turn. | An `ActiveTurn` with a `stream` and a `cancel()` method. |
-| Observer turn | Another client or agent created the turn. | Lifecycle events and streamed messages only; no direct stream handle. |
+| Own Run | This client sent the HTTP POST that created the Run. | An `ActiveRun` returned from `view.send`, with `runId`, `inputCodecMessageId`, `cancel()`, and `toInvocation()`. |
+| Observer Run | Another client or agent created the Run. | Lifecycle events and folded outputs through the tree; no per-client handle. |
 
-Both types appear in the conversation tree and the UI. The difference is internal routing: own turns have a dedicated stream, observer turns accumulate from channel messages.
+Both types appear in the conversation tree and the UI. Folded outputs flow through the tree the same way regardless of origin; `RunInfo.clientId` on the view tells you which client started any given Run.
 
-## Track active turns across clients <a id="active-turns"/>
+## Track active runs across clients <a id="active-runs"/>
 
-`useActiveTurns` returns a `Map<clientId, Set<turnId>>` of currently streaming turns:
+The session's default view exposes `runs()`. It returns a snapshot of visible Runs as projection-free `RunInfo`, consistent across every connected client:
 
 <Code>
 ```javascript
-const activeTurns = useActiveTurns();
+const { session } = useClientSession();
 
-const isAnyoneStreaming = activeTurns.size > 0;
-const isAgentWorking = activeTurns.has('agent-1');
+const runs = session.view.runs();
+const isAnyoneStreaming = runs.some((r) => r.status === 'active');
+const isAgentWorking = runs.some((r) => r.status === 'active' && r.clientId === 'agent-1');
 ```
 </Code>
 
-This is consistent across every connected client. If client A starts a turn, client B's `useActiveTurns` updates immediately.
+If client A starts a Run, client B's view updates immediately as the `ai-run-start` lands on the channel.
 
 ## Sync with useChat <a id="syncing"/>
 
@@ -80,11 +81,11 @@ A client that connects after the conversation has started loads the full history
 
 <Code>
 ```javascript
-const { nodes, hasOlder, loadOlder } = useView({ limit: 30 });
+const { messages, hasOlder, loadOlder } = useView({ limit: 30 });
 ```
 </Code>
 
-`useView` loads history on mount. If a response is currently streaming, the late joiner sees it in progress; the lifecycle tracker synthesises missing events so the stream renders correctly.
+`useView` loads history on mount. If a response is currently streaming, the late joiner sees it in progress; the codec's lifecycle tracker synthesises missing events so the stream renders correctly.
 
 ## Identify the client <a id="client-identity"/>
 
@@ -100,11 +101,11 @@ const token = jwt.sign({
 ```
 </Code>
 
-The `clientId` is used throughout: turn ownership, cancel scoping (`{ own: true }` filters by the sender's client ID), and active turn tracking. See [authentication](/docs/ai-transport/concepts/authentication) for the full setup.
+The `clientId` is used throughout: turn ownership, cancel authorisation in the agent's `onCancel` hook, and active turn tracking. Filter `view.runs()` by `clientId === ably.auth.clientId` when you want to act on this client's own Runs only. See [Set up authentication](/docs/ai-transport/getting-started/authentication) for the full setup.
 
 ## Edge cases and unhappy paths <a id="edge-cases"/>
 
-- Two clients sharing the same `clientId` are indistinguishable to the transport. Cancel signals scoped to `{ own: true }` cancel turns from both. Use a unique `clientId` per device when ownership matters.
+- Two clients sharing the same `clientId` are indistinguishable to the transport. A cancel filter that keys on `clientId` (for example "cancel only my own Runs") cancels Runs from both. Use a unique `clientId` per device when ownership matters.
 - A late joiner without channel history capability sees the live stream but not the conversation that came before. Capability scoping is part of [authentication](/docs/ai-transport/concepts/authentication).
 - A client that loses connectivity mid-stream resumes its own view on reconnect. Other clients' views are unaffected.
 - Two devices sending messages at the same time create two separate turns on the same session. See [concurrent turns](/docs/ai-transport/features/concurrent-turns) for the multiplexing model.
diff --git a/src/pages/docs/ai-transport/features/optimistic-updates.mdx b/src/pages/docs/ai-transport/features/optimistic-updates.mdx
index 42eee8104d..c262503b16 100644
--- a/src/pages/docs/ai-transport/features/optimistic-updates.mdx
+++ b/src/pages/docs/ai-transport/features/optimistic-updates.mdx
@@ -7,19 +7,21 @@ intro: "Your users see their messages the instant they hit send. AI Transport in
 
 User messages appear in the conversation immediately, before the server confirms. The client inserts the message into the tree optimistically. When the server publishes it to the channel, the transport reconciles using the message ID. The user sees no flash, no re-render, and no position change.
 
+![Diagram showing the same message id on a local-insert path and a wire-publish path, reconciling by id when the channel echo arrives](../../../../images/content/diagrams/ait-optimistic-update.png)
+
 ## How it works <a id="how-it-works"/>
 
 When a user sends a message, the client inserts it into the conversation tree before the POST request reaches the server. The message appears in the UI immediately.
 
 Behind the scenes:
 
-1. The client generates a message ID and inserts the message into the conversation tree.
-2. The POST request is sent to the server with the message content and the generated ID.
-3. The server processes the message and publishes it to the Ably channel.
-4. The client receives the published message through its channel subscription.
-5. The transport matches the published message to the optimistic insert using the `x-ably-msg-id` header and reconciles them.
+1. The client mints a `codec-message-id` and inserts the message into the conversation tree.
+2. The client publishes the input directly to the Ably channel, stamped with that `codec-message-id`.
+3. The application POSTs the invocation pointer (`inputEventId`, `sessionName`) to the agent endpoint to wake the agent. The POST does not carry the message body; the agent reads the input event off the channel.
+4. The client receives its own publish back through the channel subscription.
+5. The session matches the echo to the optimistic insert by `codec-message-id` and promotes it to a confirmed message.
 
-After reconciliation, the optimistic message is replaced by the server-confirmed version. From the user's perspective, the message was always there.
+After reconciliation, the optimistic message is replaced by the wire-confirmed version. From the user's perspective, the message was always there.
 
 ## Serial promotion <a id="serial-promotion"/>
 
@@ -34,23 +36,26 @@ A single turn includes one or more user messages. When sending more than one, ea
 <Code>
 ```javascript
 await view.edit(messageId, [
-  { role: 'user', content: 'Here is my updated question' },
-  { role: 'user', content: 'And some additional context' },
+  { kind: 'user-message', message: { id: crypto.randomUUID(), role: 'user', parts: [{ type: 'text', text: 'Here is my updated question' }] } },
+  { kind: 'user-message', message: { id: crypto.randomUUID(), role: 'user', parts: [{ type: 'text', text: 'And some additional context' }] } },
 ]);
 ```
 </Code>
 
-Each message in the array is inserted into the tree optimistically. When the server publishes them, they are reconciled individually using their respective message IDs. The order is preserved.
+Each message in the array is inserted into the tree optimistically. When the server publishes them, they are reconciled individually using their respective `codec-message-id`s. The order is preserved.
 
 ## Handle errors <a id="error-handling"/>
 
-If the POST request fails, the optimistic message stays in the conversation tree and the transport emits an `error` event. The message is not removed automatically; `view.send()` is fire-and-forget. The POST happens in the background:
+If the channel publish fails, the SDK removes the optimistic message from the tree automatically and the session emits an `error` event. If the channel publish succeeds but the agent-wake POST fails, the optimistic message stays in the tree (it is a real, published message); your application chooses whether to surface a retry to the user:
 
 <Code>
 ```javascript
-const turn = await view.send([{ role: 'user', content: 'Hello' }]);
+const run = await view.send({
+  kind: 'user-message',
+  message: { id: crypto.randomUUID(), role: 'user', parts: [{ type: 'text', text: 'Hello' }] },
+});
 
-transport.on('error', (error) => {
+session.on('error', (error) => {
   console.error('Send failed:', error.message);
 });
 ```
@@ -60,17 +65,17 @@ Your application decides whether to notify the user, offer a retry, or take othe
 
 ## Reconciliation details <a id="reconciliation"/>
 
-The transport uses the `x-ably-msg-id` header to match published messages to optimistic inserts. When the client generates a message, it assigns an ID. The server includes this ID when publishing to the channel. When the client receives the published message through its subscription, it matches the ID and promotes the optimistic message to a confirmed one.
+The session uses the `codec-message-id` header (under the `extras.ai.codec` tier) to match published messages to optimistic inserts. When the client publishes an input, the SDK mints a client-side codec-message-id and stamps it on the wire. The domain message's own `id` is preserved verbatim from the source stream; correlation does not rely on it. When the client receives the published message through its subscription, the SDK matches on the codec-message-id and promotes the optimistic message to a confirmed one.
 
 A published message that does not match any optimistic insert (for example, a message from another client) is added to the tree normally. The reconciliation logic only applies to messages the current client sent.
 
 ## Edge cases and unhappy paths <a id="edge-cases"/>
 
-- A failed POST leaves the optimistic message in the tree. Your application chooses whether to mark it failed, offer retry, or remove it. The transport does not delete optimistic messages automatically.
+- A failed channel publish is rolled back: the optimistic message is removed from the tree and the session emits an `error` event. A failed agent-wake POST leaves the (published) message in the tree because it is a real conversation entry; your application chooses whether to surface a retry.
 - A message ID collision (the same ID used twice on the same channel) confuses reconciliation. Use `crypto.randomUUID()` to generate IDs.
 - A published message that arrives before the server returns from POST still reconciles correctly. Reconciliation uses the message ID, not request ordering.
 - Two clients sending at the same time produce two distinct optimistic messages and two server publishes. Each client only reconciles its own; the other side appears as a normal observer message.
-- A server that publishes the message without the `x-ably-msg-id` header is treated as a new message, not a reconciliation. Wire the ID through from your route handler.
+- A server that publishes the message without the `codec-message-id` header is treated as a new message, not a reconciliation. The SDK stamps this header automatically; only custom codecs that publish raw need to wire it through.
 
 ## FAQ <a id="faq"/>
 
diff --git a/src/pages/docs/ai-transport/features/push-notifications.mdx b/src/pages/docs/ai-transport/features/push-notifications.mdx
index 0c67377a53..904bc55db4 100644
--- a/src/pages/docs/ai-transport/features/push-notifications.mdx
+++ b/src/pages/docs/ai-transport/features/push-notifications.mdx
@@ -2,16 +2,15 @@
 title: "Push notifications"
 meta_description: "Notify users when AI agents complete background tasks with Ably Push Notifications. Reach users even when they're offline."
 meta_keywords: "push notifications, background tasks, offline notifications, AI Transport, Ably"
+intro: "Your users get notified when a long-running agent finishes, even after they close the app. AI Transport keeps the conversation on the channel, and Ably Push delivers the alert to the device that originally subscribed."
 redirect_from:
   - /docs/ai-transport/sessions-identity/push-notifications
 ---
 
-<Aside data-type='new'>
-The AI Transport docs are being actively written and developed. They are available early to explain how AI Transport functions.
-</Aside>
-
 Push notifications let you notify users when an agent completes a long-running task, even if the user has closed the app. This uses Ably's native [Push Notifications](/docs/push) alongside AI Transport.
 
+![Diagram showing a push notification reaching a device while the agent finishes a long-running task](../../../../images/content/diagrams/ait-push-notifications.png)
+
 <Aside data-type='note'>
 Push notifications are not built into the AI Transport SDK. They use the Ably Push API to deliver notifications to devices that are no longer connected to the session channel.
 </Aside>
@@ -36,25 +35,35 @@ Configure a channel rule in the Ably dashboard to trigger push notifications whe
 ```javascript
 // Server: publish a completion event when the agent finishes
 app.post('/api/chat', async (req, res) => {
-  const { turnId, clientId, userId, sessionId, messages } = req.body
-  const turn = transport.newTurn({ turnId, clientId })
+  const body = await req.json()
+  const { userId } = body
+  const invocation = Invocation.fromJSON(body)
+  const session = createAgentSession({ client: ably, channelName: invocation.sessionName, codec: UIMessageCodec })
+  await session.connect()
+  const run = session.createRun(invocation, { signal: req.signal })
+
+  await run.start()
+  await run.loadConversation()
 
   const result = streamText({
     model: openai('gpt-4o'),
-    messages,
-    abortSignal: turn.abortSignal,
+    messages: run.messages,
+    abortSignal: run.abortSignal,
   })
 
-  await turn.streamResponse(result.toUIMessageStream())
-  await turn.end('complete')
-
-  // Publish a push-eligible event on a notification channel
-  const notificationChannel = ably.channels.get(`notifications:${userId}`)
-  await notificationChannel.publish('agent-complete', {
-    title: 'Your agent has finished',
-    body: 'Tap to view the response',
-    sessionId,
-  })
+  const { reason } = await run.pipe(result.toUIMessageStream())
+  await run.end(reason)
+  session.close()
+
+  if (reason === 'complete') {
+    // Publish a push-eligible event on a notification channel
+    const notificationChannel = ably.channels.get(`notifications:${userId}`)
+    await notificationChannel.publish('agent-complete', {
+      title: 'Your agent has finished',
+      body: 'Tap to view the response',
+      sessionName: invocation.sessionName,
+    })
+  }
   res.json({ ok: true })
 })
 ```
@@ -74,11 +83,39 @@ await notificationChannel.push.subscribeDevice()
 
 The notification payload can include the session ID, so the client opens directly to the right conversation. When the user taps the notification, load the session and use [history and replay](/docs/ai-transport/features/history) to display the full conversation including the completed response.
 
+## Edge cases and unhappy paths <a id="edge-cases"/>
+
+- A run that ends with reason `'cancelled'` or `'error'` does not publish a completion notification. Gate the push publish on `reason === 'complete'`.
+- A device that never registered for push (no `notificationChannel.push.subscribeDevice()` call) does not receive the alert. Register on first launch and after a token refresh.
+- Notification payload limits apply per platform (around 4KB for APNs). Do not embed the full agent response; carry a session pointer and load history when the user returns.
+- A user with several devices receives the notification on every registered device. Deduplicate at the device level if you only want one.
+- The notification channel is a separate Ably channel from the session channel. Capabilities scope independently; the user's token needs `subscribe` on both, plus `push-subscribe` on the notification channel.
+
+## FAQ <a id="faq"/>
+
+### Do I need a separate notification channel? <a id="faq-separate-channel"/>
+
+Yes. The push rule is per-channel; using a dedicated `notifications:{userId}` channel keeps the push policy off the conversation channel and lets you scope capabilities cleanly.
+
+### Does AI Transport publish the notification for me? <a id="faq-sdk"/>
+
+No. The SDK has no built-in push integration. The agent decides when the run is "done enough to notify" and calls `channel.publish` on the notification channel; Ably's push rule converts that publish into a device notification.
+
+### Can I reuse the session channel for push? <a id="faq-reuse-channel"/>
+
+You can, but every streamed message would then trigger the push rule. Publishing one completion event on a separate channel keeps the notification single-shot.
+
+### What happens if the user opens a new device after the run completes? <a id="faq-new-device"/>
+
+The notification fires only on devices that had registered for push before the publish. A new device sees the completed conversation when it loads history through [`useView`](/docs/ai-transport/api/react/core/use-view).
+
+### How do I avoid duplicate notifications across devices? <a id="faq-dedupe"/>
+
+Either subscribe only one device per user, or include a `messageId` in the payload and dedupe on the client. Ably itself does not dedupe across a device fleet.
+
 ## Related features <a id="related"/>
 
-- [Push Notifications](/docs/push) - the Ably Push API used for device notifications
-- [History and replay](/docs/ai-transport/features/history) - loading completed responses after reconnecting
-- [Reconnection and recovery](/docs/ai-transport/features/reconnection-and-recovery) - resuming sessions after disconnection
-- [Ably Push](/docs/push) - full reference for the Push Notifications API.
-- [Sessions](/docs/ai-transport/concepts/sessions) - how durable sessions persist while users are offline.
-- [Get started](/docs/ai-transport/getting-started/vercel-ai-sdk) - build your first AI Transport application.
+- [History and replay](/docs/ai-transport/features/history): loading completed responses after reconnecting.
+- [Reconnection and recovery](/docs/ai-transport/features/reconnection-and-recovery): resuming sessions after disconnection.
+- [Sessions](/docs/ai-transport/concepts/sessions): how durable sessions persist while users are offline.
+- [Ably Push](/docs/push): full reference for the Push Notifications API.
diff --git a/src/pages/docs/ai-transport/features/reconnection-and-recovery.mdx b/src/pages/docs/ai-transport/features/reconnection-and-recovery.mdx
index 491a45a44e..917de5cd9a 100644
--- a/src/pages/docs/ai-transport/features/reconnection-and-recovery.mdx
+++ b/src/pages/docs/ai-transport/features/reconnection-and-recovery.mdx
@@ -11,6 +11,8 @@ Streams survive connection drops automatically. When a client disconnects, the a
 
 This is built into the transport layer. Application code does not need to do anything.
 
+![Diagram showing a client disconnecting mid-stream and resuming from the exact point of disconnection on reconnect](../../../../images/content/diagrams/ait-reconnection-recovery.png)
+
 ## How it works <a id="how-it-works"/>
 
 The durable session on the Ably channel persists independently of any single connection. When a client's connection drops:
@@ -36,7 +38,7 @@ On the server side, the encoder handles transient failures during streaming. If
 2. If the append fails, send a full update with the accumulated content (recovery path).
 3. Continue appending from the recovered state.
 
-This happens inside `turn.streamResponse()`. The accumulated response is never lost, even when individual append operations fail.
+This happens inside `run.pipe()`. The accumulated response is never lost, even when individual append operations fail.
 
 ## Mid-stream joins <a id="mid-stream-joins"/>
 
@@ -46,11 +48,11 @@ A second tab opened during streaming sees the streaming content immediately.
 
 ## Load history on reconnect <a id="loading-history"/>
 
-The client transport loads conversation history using Ably's `untilAttach` parameter:
+`useView` loads conversation history using Ably's `untilAttach` parameter:
 
 <Code>
 ```javascript
-const { nodes, hasOlder, loadOlder } = useView({ transport, limit: 30 });
+const { messages, hasOlder, loadOlder } = useView({ limit: 30 });
 ```
 </Code>
 
@@ -60,7 +62,7 @@ To load older messages beyond the initial window:
 
 <Code>
 ```javascript
-const { nodes, hasOlder, loadOlder } = useView({ transport, limit: 30 });
+const { messages, hasOlder, loadOlder } = useView({ limit: 30 });
 
 if (hasOlder) {
   await loadOlder();
@@ -72,7 +74,7 @@ if (hasOlder) {
 
 - A client that drops mid-stream and reconnects after the live recovery window does not get every individual token replayed. It receives the accumulated content of the message up to the latest append. The user-visible result is the same.
 - A client without channel history capability cannot reconnect after the live recovery window. Capability scoping is part of [authentication](/docs/ai-transport/concepts/authentication).
-- An agent that crashes mid-stream leaves the partial message with status `aborted`. A retry creates a new message, not a continuation of the aborted one.
+- An agent that crashes mid-stream leaves the partial message on the channel. Its `status` header stays at `streaming` because the stream never closed. A retry creates a new message, not a continuation of the partial one.
 - The encoder fallback to a full message update is invisible to subscribers. If you log channel operations, you see periodic updates between appends.
 - A client clock drift does not affect recovery. Reconnection uses the channel's serial, not wall-clock time.
 
@@ -92,7 +94,7 @@ For the channel history retention period. Configure this through the channel's p
 
 ### What if the agent process dies before the stream finishes? <a id="faq-agent-crash"/>
 
-The partial message stays on the channel with status `aborted`. The session is intact. A new turn restarts the work; AI Transport does not automatically retry the LLM call.
+The partial message stays on the channel with its `status` header at `streaming` because the stream never closed. The session is intact. A new turn restarts the work; AI Transport does not automatically retry the LLM call.
 
 ### Does the client need special code to handle reconnection? <a id="faq-app-code"/>
 
diff --git a/src/pages/docs/ai-transport/features/token-streaming.mdx b/src/pages/docs/ai-transport/features/token-streaming.mdx
index 9f50a19e3b..bfc722e490 100644
--- a/src/pages/docs/ai-transport/features/token-streaming.mdx
+++ b/src/pages/docs/ai-transport/features/token-streaming.mdx
@@ -41,13 +41,13 @@ redirect_from:
 
 Tokens stream from the model to every connected client as the LLM generates them. The same response is also available as a single coherent message to any client that reconnects, refreshes, or loads history.
 
-![Diagram showing how AI Transport uses message appends for token streaming](../../../../images/content/diagrams/ait-feature-appends.png)
+![Diagram showing how AI Transport uses message appends for token streaming](../../../../images/content/diagrams/ait-token-streaming.png)
 
 A minimal server-side stream uses one call:
 
 <Code>
 ```javascript
-const { reason } = await turn.streamResponse(result.toUIMessageStream());
+const { reason } = await run.pipe(result.toUIMessageStream());
 ```
 </Code>
 
@@ -62,10 +62,10 @@ A streamed message moves through three states:
 | State | Meaning |
 | --- | --- |
 | `streaming` | Tokens are being appended. The message grows as tokens arrive. |
-| `finished` | The stream completed normally. The message is final. |
-| `aborted` | The stream was cancelled or failed. The partial message is preserved. |
+| `complete` | The stream completed normally. The message is final. |
+| `cancelled` | The stream was cancelled. The partial message is preserved. |
 
-The stream status is carried in the message header (`x-ably-status`). Clients check this to detect whether a message is still streaming.
+The stream status is carried in the message header `status` under the `extras.ai.codec` tier. Clients check this to detect whether a message is still streaming.
 
 ## Implement token streaming <a id="implement"/>
 
@@ -75,26 +75,30 @@ The server creates a turn, invokes the LLM, and streams the response:
 
 <Code>
 ```javascript
-import { createServerTransport } from '@ably/ai-transport/vercel';
+import { Invocation } from '@ably/ai-transport';
+import { createAgentSession } from '@ably/ai-transport/vercel';
 
-const transport = createServerTransport({ channel });
-const turn = transport.newTurn({ turnId, clientId });
+const invocation = Invocation.fromJSON(await req.json());
+const session = createAgentSession({ client: ably, channelName: invocation.sessionName });
+await session.connect();
+const run = session.createRun(invocation, { signal: req.signal });
 
-await turn.start();
-await turn.addMessages(messages, { clientId });
+await run.start();
+await run.loadConversation();
 
 const result = streamText({
   model: anthropic('claude-sonnet-4-20250514'),
-  messages: conversationHistory,
-  abortSignal: turn.abortSignal,
+  messages: run.messages,
+  abortSignal: run.abortSignal,
 });
 
-const { reason } = await turn.streamResponse(result.toUIMessageStream());
-await turn.end(reason);
+const { reason } = await run.pipe(result.toUIMessageStream());
+await run.end(reason);
+session.close();
 ```
 </Code>
 
-`streamResponse` accepts any `ReadableStream`. For Vercel AI SDK, `result.toUIMessageStream()` provides the right format. For other frameworks, produce a `ReadableStream` of your codec's event type.
+`Run.pipe` accepts any `ReadableStream`. For Vercel AI SDK, `result.toUIMessageStream()` provides the right format. For other frameworks, produce a `ReadableStream` of your codec's event type.
 
 ### Client <a id="client"/>
 
@@ -111,8 +115,8 @@ With the generic hooks:
 
 <Code>
 ```javascript
-const { nodes } = useView();
-// Each node.message contains the streamed content, updating in real time.
+const { messages } = useView();
+// Each message updates in real time as tokens are appended on the channel.
 ```
 </Code>
 
@@ -122,7 +126,7 @@ The codec converts domain events to Ably operations:
 
 - Start: create a new Ably message on the channel.
 - Append: append content to the existing message (Ably message append operation).
-- Close: update the message with a terminal status (`finished` or `aborted`).
+- Close: append a terminal status (`complete` or `cancelled`) to the message.
 
 If an append fails, for example due to a transient network issue, the encoder falls back to a full message update operation to recover. The accumulated response is never lost.
 
@@ -151,7 +155,7 @@ Set the rollup window for a connection using the `appendRollupWindow` [transport
 <Code>
 ```javascript
 const ably = new Ably.Realtime({
-  authUrl: '/auth',
+  authUrl: '/api/auth/token',
   transportParams: { appendRollupWindow: 100 },
 });
 ```
@@ -164,10 +168,10 @@ If `appendRollupWindow` allows a single response to exceed your [connection inbo
 ## Edge cases and unhappy paths <a id="edge-cases"/>
 
 - A network drop during streaming pauses delivery to the affected client. The server keeps publishing. On reconnect, the client receives the accumulated content of the message up to the latest append, not a replay of every token. This allows the client to efficiently catchup to the latest response state without replaying the response token-by-token.
-- An aborted stream leaves the partial message on the channel with status `aborted`. Render it the same as a complete message; treat the absence of further tokens as the signal to stop animating.
+- A cancelled stream leaves the partial message on the channel with status `cancelled`. Render it the same as a complete message; treat the absence of further tokens as the signal to stop animating.
 - If `appendRollupWindow` is set to `0ms` to maximise model output rate, you become responsible for keeping the publish rate under your connection limit.
 - An append fallback (full message update) is invisible to subscribers; the message content is consistent. If you log channel operations, you see periodic updates instead of appends.
-- A turn that times out on the server before the stream finishes ends with reason `'error'`. The partial message has status `aborted`.
+- A turn that times out on the server before the stream finishes ends with run reason `'error'`. The partial message is closed with status `cancelled`.
 
 ## FAQ <a id="faq"/>
 
@@ -181,7 +185,7 @@ No. Ably charges per published message, not per token. The append rollup reduces
 
 ### How do I stream more than one message per turn? <a id="faq-multi-message"/>
 
-Use `turn.addMessages()` for discrete messages and `turn.streamResponse()` for streamed ones. Each call creates a separate Ably message; the turn is the unit that groups them.
+A single `run.pipe(stream)` consumes the LLM's output stream and appends each chunk as it arrives. Multiple assistant messages, tool calls, and follow-on text within one stream all flow through the same `pipe` call. If your framework produces several discrete streams in one turn (for example a planner emits a status line, then the responder streams the answer), call `run.pipe` once per stream; the Run is the unit that groups them.
 
 ### Why does my client see fewer tokens than the model emits? <a id="faq-fewer-tokens"/>
 
@@ -189,7 +193,7 @@ The append rollup compacts multiple tokens into single published messages within
 
 ### What status do I see on a cancelled response? <a id="faq-cancel-status"/>
 
-The message keeps the content it had at the time of the cancel and its `x-ably-status` header transitions to `aborted`. Use this to distinguish a partial response from a complete one.
+The message keeps the content it had at the time of the cancel and its `status` header transitions to `cancelled`. Use this to distinguish a partial response from a complete one.
 
 ## Related features <a id="related"/>
 
diff --git a/src/pages/docs/ai-transport/features/tool-calling.mdx b/src/pages/docs/ai-transport/features/tool-calling.mdx
index 30b8241108..bed5759dcc 100644
--- a/src/pages/docs/ai-transport/features/tool-calling.mdx
+++ b/src/pages/docs/ai-transport/features/tool-calling.mdx
@@ -9,9 +9,11 @@ redirect_from:
 
 Tool calling in AI Transport supports both server-executed and client-executed tools. Tool invocations and results are published to the channel, so every client sees tool activity in real time and tool state persists in history.
 
+![Diagram showing tool invocations and results streaming through the channel for server- and client-executed tools](../../../../images/content/diagrams/ait-tool-calling.png)
+
 ## How it works <a id="how-it-works"/>
 
-When the LLM invokes a tool, the invocation is streamed through the channel like any other turn event. Clients see tool calls appear as they are generated. If the tool runs on the server, the result is streamed back in the same turn. If the tool runs on the client, the turn ends; the client submits the result, and a continuation turn starts.
+When the LLM invokes a tool, the invocation is streamed through the channel like any other turn event. Clients see tool calls appear as they are generated. If the tool runs on the server, the result is streamed back in the same run. If the tool runs on the client, the agent calls `run.suspend()` so the Run stays live; the client submits the result, and a continuation invocation resumes the same Run.
 
 Tool state (invocations, arguments, results) is part of the channel's message history. Late joiners and reconnecting clients see the full tool activity, not just the final text.
 
@@ -34,11 +36,11 @@ const result = streamText({
       },
     },
   },
-  abortSignal: turn.abortSignal,
+  abortSignal: run.abortSignal,
 });
 
-const { reason } = await turn.streamResponse(result.toUIMessageStream());
-await turn.end(reason);
+const { reason } = await run.pipe(result.toUIMessageStream());
+await run.end(reason);
 ```
 </Code>
 
@@ -62,65 +64,87 @@ const result = streamText({
       // No execute function: the client handles this.
     },
   },
-  abortSignal: turn.abortSignal,
+  abortSignal: run.abortSignal,
 });
 
-const { reason } = await turn.streamResponse(result.toUIMessageStream());
-await turn.end(reason);
+const pipeResult = await run.pipe(result.toUIMessageStream());
+const outcome = await vercelRunOutcome(pipeResult, result.finishReason);
+
+if (outcome === 'suspend') {
+  await run.suspend();
+} else {
+  await run.end(outcome);
+}
 ```
 </Code>
 
-On the client, detect the pending tool call and submit the result using `view.update()`. The first argument is the Ably message ID of the node containing the tool invocation, not the tool call ID:
+[`vercelRunOutcome`](/docs/ai-transport/api/javascript/vercel/run-outcome) returns `'suspend'` when `streamText` finishes with `finishReason: 'tool-calls'`, so the agent suspends instead of ending. The pending tool call stays on the channel for any connected client to fulfil.
+
+On the client, find the assistant message with the pending tool call and publish a `tool-result` input addressed to its `codecMessageId`. The codec folds the result onto the suspended assistant message, and the agent picks it up to continue the run:
 
 <Code>
 ```javascript
-const { nodes } = useView({ transport });
+const { messages, runOf, send } = useView();
 
-const pendingNode = nodes.find((n) =>
-  n.message.parts?.some((p) => p.type === 'dynamic-tool' && p.state === 'input-available'),
+const pending = messages.find(({ message }) =>
+  message.parts?.some((p) => p.type === 'dynamic-tool' && p.state === 'input-available'),
 );
 
-if (pendingNode) {
-  // navigator.geolocation.getCurrentPosition is callback-based, not a promise.
+if (pending) {
+  const toolCall = pending.message.parts.find(
+    (p) => p.type === 'dynamic-tool' && p.state === 'input-available',
+  );
+
   const location = await new Promise((resolve, reject) => {
     navigator.geolocation.getCurrentPosition(resolve, reject);
   });
 
-  const toolCall = pendingNode.message.parts.find(
-    (p) => p.type === 'dynamic-tool' && p.state === 'input-available',
+  const run = await send(
+    {
+      kind: 'tool-result',
+      codecMessageId: pending.codecMessageId,
+      payload: {
+        toolCallId: toolCall.toolCallId,
+        output: { lat: location.coords.latitude, lng: location.coords.longitude },
+      },
+    },
+    { runId: runOf(pending.codecMessageId).runId },
   );
 
-  await view.update(pendingNode.id, [{
-    type: 'tool-output-available',
-    toolCallId: toolCall.toolCallId,
-    output: { lat: location.coords.latitude, lng: location.coords.longitude },
-  }]);
+  // Wake the agent so it picks up the result and resumes the run.
+  await fetch('/api/chat', {
+    method: 'POST',
+    body: JSON.stringify(run.toInvocation().toJSON()),
+  });
 }
 ```
 </Code>
 
-Calling `view.update()` submits the tool result to the server and triggers a continuation turn. The server receives the result, includes it in the conversation history, and the LLM generates a response that incorporates the tool output.
+The result is addressed to the suspended assistant message by `codecMessageId`. Reusing the original `runId` keeps the resume on the same run instead of starting a fresh one.
 
-## Cross-turn events with EventsNode <a id="events-node"/>
+## Cross-run events with addEvents <a id="add-events"/>
 
-`addEvents()` delivers events to an existing assistant message. A common use is delivering tool results to a message that contains a pending tool call. Target the message by its Ably message ID:
+The agent uses `Run.addEvents` to push events to a message owned by an earlier run. The common case is delivering a late tool result on a continuation run without starting a new assistant message:
 
 <Code>
 ```javascript
-const assistantMsgId = pendingNode.id;
-const toolCallId = pendingToolCall.toolCallId;
-
-await turn.addEvents(assistantMsgId, [
+await run.addEvents([
   {
-    type: 'tool-output-available',
-    toolCallId,
-    output: { temperature: 22, conditions: 'sunny' },
+    kind: 'event',
+    codecMessageId: pendingAssistantCodecMessageId,
+    events: [
+      {
+        type: 'tool-output-available',
+        toolCallId,
+        output: { temperature: 22, conditions: 'sunny' },
+      },
+    ],
   },
 ]);
 ```
 </Code>
 
-Events published through `addEvents()` update the target message in the view. Because they target an existing message by its ID, late joiners and reconnecting clients see the correct state when the conversation replays from history.
+Events published through `addEvents` update the target message in the view. Because they target an existing message by its `codecMessageId`, late joiners and reconnecting clients see the correct state when the conversation replays from history.
 
 ## History persistence <a id="history"/>
 
@@ -130,9 +154,9 @@ A user who starts a tool-assisted workflow on a laptop continues it on a phone w
 
 ## Edge cases and unhappy paths <a id="edge-cases"/>
 
-- A client-executed tool that the user denies (for example a geolocation permission prompt) leaves the tool call pending. Submit a failure result to unblock the LLM, or end the turn explicitly.
-- A tool that takes longer than the agent's runtime budget runs past `turn.end()`. The continuation turn picks up the result through `addEvents` on the original message; do not start a new turn just to deliver a late result.
-- A server-executed tool that does not honour `turn.abortSignal` keeps running after a cancel. Wire the signal into your tool implementation.
+- A client-executed tool that the user denies (for example a geolocation permission prompt) leaves the tool call pending. Submit a failure with `codec.createToolResultError(codecMessageId, { toolCallId, message })` (or the literal `{ kind: 'tool-result-error', ... }`) to unblock the LLM, or end the turn explicitly.
+- A tool that takes longer than the agent's runtime budget runs past `run.end()`. The continuation run picks up the result through `addEvents` on the original message; do not start a new run just to deliver a late result.
+- A server-executed tool that does not honour `run.abortSignal` keeps running after a cancel. Wire the signal into your tool implementation.
 - Two clients submitting the same client-executed tool concurrently produce two continuation turns. Guard against double-submit at the application layer.
 - A failed tool call is delivered with an error result. The view exposes the failure; render it in place rather than silently retrying.
 
diff --git a/src/pages/docs/ai-transport/frameworks/vercel-ai-sdk-core.mdx b/src/pages/docs/ai-transport/frameworks/vercel-ai-sdk-core.mdx
index e945eedac2..44998c7ee1 100644
--- a/src/pages/docs/ai-transport/frameworks/vercel-ai-sdk-core.mdx
+++ b/src/pages/docs/ai-transport/frameworks/vercel-ai-sdk-core.mdx
@@ -28,7 +28,7 @@ AI Transport composes with each of these. It does not replace them. It is the la
 | Durable sessions | Tokens flow through an Ably channel that outlives any single connection. A client reconnects and resumes from where it left off. |
 | Multi-device sync | Every device subscribed to the session sees the same conversation in real time. |
 | Bidirectional control | Cancel, steer, and interrupt the agent from any client. No separate control channel. |
-| Active turn tracking | `useActiveTurns` exposes which clients are streaming and which turns are in progress. |
+| Active run tracking | `view.runs()` exposes which clients have Runs streaming and which Runs are in progress. |
 | Conversation branching | Edit and regenerate create forks in the conversation tree, not destructive replacements. |
 | Approval gates that reach the user anywhere | Pending tool approvals persist on the session until someone acts on them. |
 | History and replay | Load the full conversation on reconnect, page refresh, or new device join. |
@@ -38,7 +38,7 @@ These are the same capability bullets used on the [Vercel AI SDK UI](/docs/ai-tr
 
 ## Where they connect <a id="how-they-connect"/>
 
-On the server, AI Transport replaces `createUIMessageStreamResponse()` with `turn.streamResponse()`. The HTTP response returns immediately; tokens flow to clients through the Ably channel instead of the HTTP body:
+On the server, AI Transport replaces `createUIMessageStreamResponse()` with `Run.pipe()`. The HTTP response returns immediately; tokens flow to clients through the Ably channel instead of the HTTP body:
 
 <Code>
 ```javascript
@@ -46,13 +46,13 @@ On the server, AI Transport replaces `createUIMessageStreamResponse()` with `tur
 return createUIMessageStreamResponse({ stream: result.toUIMessageStream() });
 
 // After: Ably transport
-const { reason } = await turn.streamResponse(result.toUIMessageStream());
-await turn.end(reason);
-return new Response(null, { status: 200 });
+const { reason } = await run.pipe(result.toUIMessageStream());
+await run.end(reason);
+return Response.json({ invocationId: run.invocationId });
 ```
 </Code>
 
-A full server route:
+A full agent route:
 
 <Code>
 ```javascript
@@ -60,49 +60,42 @@ import { after } from 'next/server';
 import { streamText, convertToModelMessages } from 'ai';
 import { anthropic } from '@ai-sdk/anthropic';
 import Ably from 'ably';
-import { createServerTransport } from '@ably/ai-transport/vercel';
+import { Invocation } from '@ably/ai-transport';
+import { createAgentSession } from '@ably/ai-transport/vercel';
 
 const ably = new Ably.Realtime({ key: process.env.ABLY_API_KEY });
 
 export async function POST(req) {
-  const { messages, history, id, turnId, clientId, forkOf, parent } = await req.json();
-  const channel = ably.channels.get(id);
-
-  const transport = createServerTransport({ channel });
-  const turn = transport.newTurn({ turnId, clientId, parent, forkOf });
-
-  await turn.start();
-  if (messages.length > 0) {
-    await turn.addMessages(messages, { clientId });
-  }
-
-  const allMessages = [
-    ...(history ?? []).map((h) => h.message),
-    ...messages.map((m) => m.message),
-  ];
-
-  const result = streamText({
-    model: anthropic('claude-sonnet-4-20250514'),
-    messages: await convertToModelMessages(allMessages),
-    abortSignal: turn.abortSignal,
-  });
+  const invocation = Invocation.fromJSON(await req.json());
+  const session = createAgentSession({ client: ably, channelName: invocation.sessionName });
+  await session.connect();
+  const run = session.createRun(invocation, { signal: req.signal });
 
   after(async () => {
-    const { reason } = await turn.streamResponse(result.toUIMessageStream());
-    await turn.end(reason);
-    transport.close();
+    await run.start();
+    await run.loadConversation();
+
+    const result = streamText({
+      model: anthropic('claude-sonnet-4-20250514'),
+      messages: await convertToModelMessages(run.messages),
+      abortSignal: run.abortSignal,
+    });
+
+    const { reason } = await run.pipe(result.toUIMessageStream());
+    await run.end(reason);
+    session.close();
   });
 
-  return new Response(null, { status: 200 });
+  return Response.json({ invocationId: run.invocationId });
 }
 ```
 </Code>
 
 The integration has three pieces:
 
-1. The `UIMessageCodec` encodes Vercel's `UIMessageChunk` events as Ably messages. Every chunk type maps to an Ably operation with headers that track the metadata. The codec encodes on the server and decodes on the client.
-2. `createServerTransport({ channel })` constructs the server-side transport bound to one channel. The default codec is `UIMessageCodec`.
-3. `turn.streamResponse()` reads the model's `UIMessageChunk` stream, encodes each chunk, and publishes the resulting Ably messages. `turn.abortSignal` wires cancellation through from the client.
+1. The `UIMessageCodec` encodes Vercel's `UIMessageChunk` events as Ably messages. Every chunk type maps to an Ably operation with headers that track the metadata. The codec encodes on the agent and decodes on the client.
+2. `createAgentSession({ client, channelName })` from `@ably/ai-transport/vercel` constructs the agent session bound to the channel from the invocation. The default codec is `UIMessageCodec`.
+3. `run.pipe()` reads the model's `UIMessageChunk` stream, encodes each chunk, and publishes the resulting Ably messages. `run.abortSignal` wires cancellation through from the client.
 
 ## Scope and trade-offs <a id="scope"/>
 
@@ -114,5 +107,5 @@ If you are building the client side, see [Vercel AI SDK UI](/docs/ai-transport/f
 
 - [Get started with Vercel AI SDK](/docs/ai-transport/getting-started/vercel-ai-sdk): build a working app.
 - [Vercel AI SDK UI](/docs/ai-transport/frameworks/vercel-ai-sdk-ui): the client-side integration that pairs with this page.
-- [Server transport API reference](/docs/ai-transport/api/javascript/server-transport): the full API surface for the server transport.
-- [Codec API reference](/docs/ai-transport/api/javascript/codec): the codec interface that `UIMessageCodec` implements.
+- [Agent session API reference](/docs/ai-transport/api/javascript/core/agent-session): the full API surface for the agent session.
+- [Codec API reference](/docs/ai-transport/api/javascript/core/codec): the codec interface that `UIMessageCodec` implements.
diff --git a/src/pages/docs/ai-transport/frameworks/vercel-ai-sdk-ui.mdx b/src/pages/docs/ai-transport/frameworks/vercel-ai-sdk-ui.mdx
index 3a412cf2e7..7571e99ba3 100644
--- a/src/pages/docs/ai-transport/frameworks/vercel-ai-sdk-ui.mdx
+++ b/src/pages/docs/ai-transport/frameworks/vercel-ai-sdk-ui.mdx
@@ -29,7 +29,7 @@ This is what AI Transport composes with. It does not replace any of these. It re
 | Durable sessions | Tokens flow through an Ably channel that outlives any single connection. A client reconnects and resumes from where it left off. |
 | Multi-device sync | Every device subscribed to the session sees the same conversation in real time. |
 | Bidirectional control | Cancel, steer, and interrupt the agent from any client. No separate control channel. |
-| Active turn tracking | `useActiveTurns` exposes which clients are streaming and which turns are in progress. |
+| Active run tracking | `view.runs()` exposes which clients have Runs streaming and which Runs are in progress. |
 | Conversation branching | Edit and regenerate create forks in the conversation tree, not destructive replacements. |
 | Approval gates that reach the user anywhere | Pending tool approvals persist on the session until someone acts on them. |
 | History and replay | Load the full conversation on reconnect, page refresh, or new device join. |
@@ -56,9 +56,9 @@ const { messages } = useChat({ transport: chatTransport });
 The integration has four parts:
 
 1. The `UIMessageCodec` encodes Vercel's `UIMessageChunk` events as Ably messages. Every chunk type (`text-delta`, `tool-input`, `finish`, and others) maps to an Ably message with headers that track its metadata. The codec encodes on the server, decodes on the client, and reassembles chunks into complete `UIMessage` objects.
-2. `ChatTransportProvider` creates the underlying `ClientTransport` and the `ChatTransport` adapter and makes both available through context. `useChatTransport` is a context reader that returns `{ chatTransport, transport }`.
+2. `ChatTransportProvider` creates the underlying `ClientSession` and the `ChatTransport` adapter and makes both available through context. `useChatTransport` is a context reader that returns `{ session, chatTransport }`.
 3. `useMessageSync` subscribes to the transport's conversation tree and pushes updates into `useChat`'s `setMessages`. This is what brings multi-device sync and conversation branching into Vercel's local state without `useChat` natively supporting them.
-4. On the server, `turn.streamResponse(result.toUIMessageStream())` pipes the model's output through the codec encoder to the Ably channel. The HTTP response returns status 200 with an empty body. Tokens reach every connected client through the channel, not through the HTTP response. See [Vercel AI SDK Core](/docs/ai-transport/frameworks/vercel-ai-sdk-core) for the server-side detail.
+4. On the server, `run.pipe(result.toUIMessageStream())` pipes the model's output through the codec encoder to the Ably channel. The HTTP response returns status 200 with an empty body. Tokens reach every connected client through the channel, not through the HTTP response. See [Vercel AI SDK Core](/docs/ai-transport/frameworks/vercel-ai-sdk-core) for the server-side detail.
 
 ## Scope and trade-offs <a id="scope"/>
 
diff --git a/src/pages/docs/ai-transport/getting-started/authentication.mdx b/src/pages/docs/ai-transport/getting-started/authentication.mdx
new file mode 100644
index 0000000000..3b29f98702
--- /dev/null
+++ b/src/pages/docs/ai-transport/getting-started/authentication.mdx
@@ -0,0 +1,146 @@
+---
+title: "Set up authentication"
+meta_description: "Wire AI Transport to your auth: a token-issuing endpoint that signs Ably JWTs, and an authenticated Ably client on the browser."
+meta_keywords: "AI Transport, authentication setup, Ably JWT, authCallback, token endpoint, getting started"
+intro: "AI Transport authenticates through your existing auth: your server validates the user and signs an Ably token, and the browser's Ably client fetches it through `authCallback`and refreshes it before expiry."
+---
+
+This page is the practical setup. For the conceptual model (the three auth layers, capabilities, token lifecycle, cancel authorisation), see the [authentication concept](/docs/ai-transport/concepts/authentication).
+
+<Aside data-type='important'>
+Never embed an Ably API key in client-side code. API keys do not expire and are not suitable for untrusted clients.
+</Aside>
+
+## Sign tokens on the server <a id="server"/>
+
+Create an endpoint that authenticates the user and returns a short-lived Ably JWT with the [capabilities](/docs/ai-transport/concepts/authentication#capabilities) AI Transport needs:
+
+<Code>
+```javascript
+import jwt from 'jsonwebtoken';
+
+const [keyName, keySecret] = process.env.ABLY_API_KEY.split(':');
+
+export async function GET(req) {
+  const userId = await authenticateUser(req);
+
+  const ablyJwt = jwt.sign(
+    {
+      'x-ably-capability': JSON.stringify({
+        [`conversations:${userId}`]: ['publish', 'subscribe', 'history'],
+      }),
+      'x-ably-clientId': userId,
+    },
+    keySecret,
+    { algorithm: 'HS256', keyid: keyName, expiresIn: '1h' },
+  );
+
+  return new Response(ablyJwt, { headers: { 'Content-Type': 'text/plain' } });
+}
+```
+</Code>
+
+Scope the capability to the channel namespace the user is allowed to access, `conversations:${userId}` here. The `x-ably-clientId` claim binds the token to a specific user identity that the Ably service verifies on every publish.
+
+## Fetch tokens from the client <a id="client"/>
+
+Construct an Ably Realtime client with `authCallback`. The SDK calls it on first auth and again whenever a refresh is needed:
+
+<Code>
+```javascript
+import * as Ably from 'ably';
+
+const realtimeClient = new Ably.Realtime({
+  authCallback: async (tokenParams, callback) => {
+    try {
+      const response = await fetch('/api/auth/token', { credentials: 'include' });
+      if (!response.ok) throw new Error('Auth failed');
+      const jwt = await response.text();
+      callback(null, jwt);
+    } catch (error) {
+      callback(error, null);
+    }
+  },
+});
+```
+</Code>
+
+## Wire it into the React provider stack <a id="react"/>
+
+In a React app, hold the client in state, wrap the tree in `AblyProvider`, then in `ClientSessionProvider` for the channel:
+
+<Code>
+```javascript
+'use client'
+
+import { useEffect, useState } from 'react';
+import * as Ably from 'ably';
+import { AblyProvider } from 'ably/react';
+import { ClientSessionProvider, useClientSession } from '@ably/ai-transport/react';
+import { UIMessageCodec } from '@ably/ai-transport/vercel';
+
+export function Providers({ children }) {
+  const [client, setClient] = useState(null);
+
+  useEffect(() => {
+    const ably = new Ably.Realtime({
+      authCallback: async (_tokenParams, callback) => {
+        try {
+          const response = await fetch('/api/auth/token', { credentials: 'include' });
+          callback(null, await response.text());
+        } catch (err) {
+          callback(err instanceof Error ? err.message : String(err), null);
+        }
+      },
+    });
+    setClient(ably);
+    return () => ably.close();
+  }, []);
+
+  if (!client) return null;
+  return <AblyProvider client={client}>{children}</AblyProvider>;
+}
+
+function App({ conversationId }) {
+  return (
+    <ClientSessionProvider channelName={conversationId} codec={UIMessageCodec}>
+      <Chat />
+    </ClientSessionProvider>
+  );
+}
+
+function Chat() {
+  const { session, sessionError } = useClientSession();
+  // ...
+}
+```
+</Code>
+
+## Authenticate the agent POST <a id="agent-post"/>
+
+The application's POST that wakes the agent is a separate HTTP request from the channel auth. Authenticate it however you normally do (session cookie, bearer token, signed header) when you call `fetch` on the core flow:
+
+<Code>
+```javascript
+async function wakeAgent(run) {
+  await fetch('/api/chat', {
+    method: 'POST',
+    credentials: 'include',
+    headers: {
+      'Content-Type': 'application/json',
+      Authorization: `Bearer ${await getAccessToken()}`,
+    },
+    body: JSON.stringify(run.toInvocation().toJSON()),
+  });
+}
+```
+</Code>
+
+For the Vercel flow, [`ChatTransportProvider`](/docs/ai-transport/api/react/vercel/chat-transport-provider) accepts a `credentials` prop and a `chatOptions.prepareSendMessagesRequest` hook that returns `{ body?, headers? }` per request. Use the hook to attach auth headers to every invocation POST it makes for you.
+
+## Read next <a id="next"/>
+
+- [Authentication concept](/docs/ai-transport/concepts/authentication): the three auth layers, capabilities, and token lifecycle.
+- [Enable channel rules](/docs/ai-transport/getting-started/channel-rules): the one-time namespace configuration AI Transport requires.
+- [Core SDK getting started](/docs/ai-transport/getting-started/core-sdk): build a chat app on the auth set up here.
+- [Vercel AI SDK getting started](/docs/ai-transport/getting-started/vercel-ai-sdk): build a chat app using the Vercel wrapper.
diff --git a/src/pages/docs/ai-transport/getting-started/channel-rules.mdx b/src/pages/docs/ai-transport/getting-started/channel-rules.mdx
new file mode 100644
index 0000000000..49717c53f3
--- /dev/null
+++ b/src/pages/docs/ai-transport/getting-started/channel-rules.mdx
@@ -0,0 +1,71 @@
+---
+title: "Enable channel rules"
+meta_description: "Enable the Ably channel rule AI Transport needs: Message annotations, updates, deletes, and appends on the channel namespace your conversations live on."
+meta_keywords: "AI Transport, channel rules, mutableMessages, Ably namespace, message updates, appends, setup"
+intro: "AI Transport streams tokens by appending to a single Ably channel message. That requires one channel rule on the namespace your conversations live on. This is a one-time configuration per Ably app."
+---
+
+The *Message annotations, updates, deletes, and appends* rule (`mutableMessages: true`) is mandatory when using AI Transport. Without it, AI Transport fails on the first token append after a stream starts, with error `93002` `Can only update/delete/append messages on channels with mutableMessages enabled`. See [troubleshooting](/docs/ai-transport/troubleshooting#namespace-not-configured) for the symptom-side detail.
+
+<Aside data-type='important'>
+Enabling this rule causes messages in the namespace to be [persisted](/docs/storage-history/storage#all-message-persistence) regardless of whether persistence is enabled separately. [Ably charges for persisted messages](https://faqs.ably.com/how-does-ably-count-messages); account for this when picking the namespace.
+</Aside>
+
+Pick a namespace prefix that scopes AI Transport conversations away from other channels in the same app (for example `conversations:` or `chat:`). Apply the rule to that namespace.
+
+## Enable the rule <a id="enable"/>
+
+<Tabs>
+<Tab value="dashboard" label="Dashboard">
+
+In your app [settings](https://ably.com/accounts/any/apps/any/settings):
+
+1. Click **Add new rule**.
+2. Enter the channel name or namespace on which to enable message updates and deletes.
+3. Check **Message annotations, updates, deletes, and appends**.
+4. Click **Create rule** to save.
+
+</Tab>
+<Tab value="control-api" label="Control API">
+
+Create a namespace with `mutableMessages` enabled via the [Control API](/docs/api/control-api):
+
+<Code>
+```shell
+curl -X POST https://control.ably.net/v1/apps/{APP_ID}/namespaces \
+  -H "Authorization: Bearer {ACCESS_TOKEN}" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "id": "conversations",
+    "mutableMessages": true
+  }'
+```
+</Code>
+
+</Tab>
+<Tab value="cli" label="Ably CLI">
+
+Use the [Ably CLI](/docs/platform/tools/cli):
+
+<Code>
+```shell
+ably apps rules create "conversations" --mutable-messages
+```
+</Code>
+
+Run `ably apps rules create --help` for the full option list.
+
+</Tab>
+</Tabs>
+
+## Verify the rule applies to your channel names <a id="verify"/>
+
+The namespace matches by prefix. If your conversations live on channel names like `conversations:abc-123`, the namespace `conversations` covers them. A namespace called `conversation` (singular) does **not** match `conversations:*`. Names are matched literally up to the first colon.
+
+The fastest verification is to send one user message through AI Transport and check the agent's logs for `93002`. If no `93002` appears and the first token streams through, the rule is applied correctly.
+
+## Read next <a id="next"/>
+
+- [Set up authentication](/docs/ai-transport/getting-started/authentication): the auth setup AI Transport needs alongside the channel rule.
+- [Troubleshooting: namespace not configured](/docs/ai-transport/troubleshooting#namespace-not-configured): the symptom-side detail.
+- [Core SDK getting started](/docs/ai-transport/getting-started/core-sdk): build a chat app once the namespace is configured.
diff --git a/src/pages/docs/ai-transport/getting-started/core-sdk.mdx b/src/pages/docs/ai-transport/getting-started/core-sdk.mdx
index 2b0ca0d307..56b5da1f5e 100644
--- a/src/pages/docs/ai-transport/getting-started/core-sdk.mdx
+++ b/src/pages/docs/ai-transport/getting-started/core-sdk.mdx
@@ -10,9 +10,9 @@ intro: "Build a chat app using AI Transport's core React hooks directly. You get
 A Next.js chat app where:
 
 - Tokens stream from the model into a durable [session](/docs/ai-transport/concepts/sessions).
-- The client reads the conversation through AI Transport's `useView` hook, with direct access to the [conversation tree](/docs/ai-transport/concepts/conversation-tree).
+- The client reads the conversation through the [`useView`](/docs/ai-transport/api/react/core/use-view) hook, with direct access to the [conversation tree](/docs/ai-transport/concepts/conversation-tree).
 - Branching, edit, regenerate, and pagination are first-class.
-- A stop button cancels the in-progress [turn](/docs/ai-transport/concepts/turns).
+- A Stop button cancels the in-progress [Run](/docs/ai-transport/concepts/runs).
 
 To use AI Transport with Vercel's `useChat` for message management, see [Get started with Vercel AI SDK](/docs/ai-transport/getting-started/vercel-ai-sdk).
 
@@ -32,101 +32,128 @@ npm install @ably/ai-transport ably ai @ai-sdk/anthropic next react react-dom
 
 ## Set up authentication <a id="auth"/>
 
-Create an auth endpoint at `/api/auth` that returns an Ably JWT to the client. The endpoint validates the user and signs a token with their client ID and the channel capabilities they need. See [authentication](/docs/ai-transport/concepts/authentication) for the full setup.
+Create an auth endpoint at `/api/auth/token` that returns an Ably JWT to the client. The endpoint validates the user and signs a token with their client ID and the channel capabilities they need. See [Set up authentication](/docs/ai-transport/getting-started/authentication) for the full setup.
 
-The client below uses `authUrl: '/auth'` to fetch tokens from this endpoint.
+The client below uses `authUrl: '/api/auth/token'` to fetch tokens from this endpoint.
 
-## Create the server route <a id="server"/>
+## Create the agent route <a id="agent-route"/>
 
-Create `app/api/chat/route.ts`. The server creates a turn, publishes the user message, streams the LLM response through the Ably channel, and returns immediately. `streamText` orchestrates the model, and `UIMessageCodec` encodes its output for Ably. Swap either component if your stack is different.
+Create `app/api/chat/route.ts`. The agent receives an [Invocation](/docs/ai-transport/concepts/invocations), creates an [AgentSession](/docs/ai-transport/api/javascript/core/agent-session), starts a [Run](/docs/ai-transport/concepts/runs), hydrates the conversation, pipes the LLM stream, and ends the Run.
 
 <Code>
 ```javascript
 import { after } from 'next/server';
 import { streamText, convertToModelMessages } from 'ai';
 import { anthropic } from '@ai-sdk/anthropic';
-import Ably from 'ably';
-import { createServerTransport } from '@ably/ai-transport';
+import * as Ably from 'ably';
+import { createAgentSession, Invocation } from '@ably/ai-transport';
 import { UIMessageCodec } from '@ably/ai-transport/vercel';
 
 const ably = new Ably.Realtime({ key: process.env.ABLY_API_KEY });
 
 export async function POST(req) {
-  const { messages, history, id, turnId, clientId, forkOf, parent } = await req.json();
-  const channel = ably.channels.get(id);
-
-  const transport = createServerTransport({ channel, codec: UIMessageCodec });
-  const turn = transport.newTurn({ turnId, clientId, parent, forkOf });
+  const invocation = Invocation.fromJSON(await req.json());
 
-  await turn.start();
+  const session = createAgentSession({
+    client: ably,
+    channelName: invocation.sessionName,
+    codec: UIMessageCodec,
+  });
 
-  if (messages.length > 0) {
-    await turn.addMessages(messages, { clientId });
-  }
+  await session.connect();
 
-  const allMessages = [
-    ...(history ?? []).map((h) => h.message),
-    ...messages.map((m) => m.message),
-  ];
-
-  const result = streamText({
-    model: anthropic('claude-sonnet-4-20250514'),
-    system: 'You are a helpful assistant.',
-    messages: await convertToModelMessages(allMessages),
-    abortSignal: turn.abortSignal,
-  });
+  const run = session.createRun(invocation, { signal: req.signal });
 
   after(async () => {
-    const { reason } = await turn.streamResponse(result.toUIMessageStream());
-    await turn.end(reason);
-    transport.close();
+    try {
+      await run.start();
+      await run.loadConversation();
+
+      const result = streamText({
+        model: anthropic('claude-sonnet-4-20250514'),
+        system: 'You are a helpful assistant.',
+        messages: await convertToModelMessages(run.messages),
+        abortSignal: run.abortSignal,
+      });
+
+      const { reason } = await run.pipe(result.toUIMessageStream());
+      await run.end(reason);
+    } catch (err) {
+      await run.end('error');
+      throw err;
+    } finally {
+      session.close();
+    }
   });
 
-  return new Response(null, { status: 200 });
+  return Response.json({ runId: run.runId, invocationId: run.invocationId });
 }
 ```
 </Code>
 
-## Create the chat component <a id="client"/>
+## Create the chat component <a id="chat-component"/>
 
-Create `app/chat.tsx`. The component uses AI Transport's core hooks directly. `useView` returns the visible messages, a `send` function, and pagination:
+Create `app/chat.tsx`. The component uses [`useView`](/docs/ai-transport/api/react/core/use-view) directly. It returns the visible messages, write methods, branch navigation, and pagination. Because the core SDK doesn't POST to the agent endpoint itself, the component does it after `view.send` resolves.
 
 <Code>
 ```javascript
 'use client';
 
-import { useClientTransport, useActiveTurns, useView } from '@ably/ai-transport/react';
 import { useState } from 'react';
+import { useClientSession, useView } from '@ably/ai-transport/react';
+import { UIMessageCodec } from '@ably/ai-transport/vercel';
 
-export function Chat({ chatId }) {
+async function wakeAgent(run) {
+  const res = await fetch('/api/chat', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(run.toInvocation().toJSON()),
+  });
+  return res.json();
+}
+
+export function Chat() {
   const [input, setInput] = useState('');
 
-  const { transport } = useClientTransport();
-  const { messages, send, hasOlder, loadOlder } = useView({ limit: 30 });
-  const activeTurns = useActiveTurns();
-  const isStreaming = activeTurns.size > 0;
+  const { session } = useClientSession();
+  const view = useView({ limit: 30 });
+  const { messages, runOf } = view;
+
+  // `'active'`, `'suspended'`, and `'error'` keep the Stop button visible
+  // so a stuck Run can still be cancelled; `'complete'` and `'cancelled'`
+  // are terminal.
+  const latestRun = runOf(messages.at(-1)?.codecMessageId ?? '');
+  const isStreaming =
+    latestRun !== undefined &&
+    latestRun.status !== 'complete' &&
+    latestRun.status !== 'cancelled';
 
   const handleSubmit = async (e) => {
     e.preventDefault();
     if (!input.trim()) return;
     const text = input;
     setInput('');
-    await send({
+    const run = await view.send(UIMessageCodec.createUserMessage({
       id: crypto.randomUUID(),
       role: 'user',
       parts: [{ type: 'text', text }],
-    });
+    }));
+    await wakeAgent(run);
+  };
+
+  const stop = async () => {
+    if (latestRun) await session.cancel(latestRun.runId);
   };
 
   return (
     <div>
-      {hasOlder && (
-        <button type="button" onClick={loadOlder}>Load older messages</button>
+      {view.hasOlder && (
+        <button type="button" onClick={() => view.loadOlder()}>Load older messages</button>
       )}
-      {messages.map((msg) => (
-        <div key={msg.id}>
-          <strong>{msg.role}:</strong>{' '}
-          {msg.parts.map((part, i) =>
+      {messages.map(({ codecMessageId, message }) => (
+        <div key={codecMessageId}>
+          <strong>{message.role}:</strong>{' '}
+          {message.parts.map((part, i) =>
             part.type === 'text' ? <span key={i}>{part.text}</span> : null,
           )}
         </div>
@@ -134,7 +161,7 @@ export function Chat({ chatId }) {
       <form onSubmit={handleSubmit}>
         <input value={input} onChange={(e) => setInput(e.target.value)} placeholder="Type a message..." />
         {isStreaming ? (
-          <button type="button" onClick={() => transport.cancel()}>Stop</button>
+          <button type="button" onClick={stop}>Stop</button>
         ) : (
           <button type="submit">Send</button>
         )}
@@ -147,7 +174,9 @@ export function Chat({ chatId }) {
 
 ## Wire it together <a id="wire"/>
 
-Create `app/page.tsx`. `Providers` sets up an authenticated Ably client. `TransportProvider` wires the channel and codec into AI Transport. `UIMessageCodec` matches the server's output format; supply a different codec if your model layer produces different events.
+Create `app/page.tsx`. `Providers` sets up an authenticated Ably client. [`ClientSessionProvider`](/docs/ai-transport/api/react/core/providers) wires the channel and codec into AI Transport.
+
+Update `channelName` to match a namespace with the AIT [channel rules](/docs/ai-transport/getting-started/channel-rules) configured.
 
 <Code>
 ```javascript
@@ -156,7 +185,7 @@ Create `app/page.tsx`. `Providers` sets up an authenticated Ably client. `Transp
 import { useEffect, useState } from 'react';
 import * as Ably from 'ably';
 import { AblyProvider } from 'ably/react';
-import { TransportProvider } from '@ably/ai-transport/react';
+import { ClientSessionProvider } from '@ably/ai-transport/react';
 import { UIMessageCodec } from '@ably/ai-transport/vercel';
 import { Chat } from './chat';
 
@@ -164,7 +193,7 @@ function Providers({ children }) {
   const [client, setClient] = useState(null);
 
   useEffect(() => {
-    const ably = new Ably.Realtime({ authUrl: '/auth', clientId: 'user' });
+    const ably = new Ably.Realtime({ authUrl: '/api/auth/token', clientId: 'user' });
     setClient(ably);
     return () => ably.close();
   }, []);
@@ -174,33 +203,35 @@ function Providers({ children }) {
 }
 
 export default function Page() {
-  const chatId = 'my-chat-session';
+  const channelName = 'conversations:my-chat-session';
   return (
     <Providers>
-      <TransportProvider channelName={chatId} codec={UIMessageCodec}>
-        <Chat chatId={chatId} />
-      </TransportProvider>
+      <ClientSessionProvider channelName={channelName} codec={UIMessageCodec}>
+        <Chat />
+      </ClientSessionProvider>
     </Providers>
   );
 }
 ```
 </Code>
 
-Run `npm run dev` and open `http://localhost:3000`. Open a second tab to the same URL to see both tabs share the same durable session.
+Run `npm run dev` and open `http://localhost:3000`. Open a second tab to the same URL to see both tabs share the same session.
 
 ## What is happening <a id="whats-happening"/>
 
-1. The client sends the user message via HTTP POST to your API route.
-2. The server publishes the message to the Ably channel, invokes the LLM, and streams tokens to the channel.
-3. Every client subscribed to the channel receives tokens in real time.
-4. If a client disconnects, it reconnects automatically and resumes from where it left off.
+1. The user types a message. `view.send(...)` mints `inputEventId` and the message's `codecMessageId`, publishes the user input on the channel with those ids stamped under `extras.ai.transport`, and returns an `ActiveRun` carrying the `inputCodecMessageId` the client owns synchronously. The SDK does not POST to your agent endpoint itself.
+2. Your client code calls `activeRun.toInvocation().toJSON()` to get an [`InvocationData`](/docs/ai-transport/concepts/invocations) body (`{ inputEventId, sessionName }`), and POSTs it to your agent endpoint.
+3. The agent endpoint receives the POST, calls `Invocation.fromJSON`, creates an `AgentSession`, and starts a `Run` from the Invocation. `session.createRun(invocation)` mints a fresh `runId` (for a fresh run) and a fresh `invocationId`; the agent returns both on the response so callers can observe them. `Run.start()` waits for the trigger input event on the channel (rewind + live).
+4. The agent streams the LLM response through `run.pipe(...)` to the channel. Every output carries `input-codec-message-id` so the client can correlate by an id it owned at send time.
+5. Every client subscribed to the channel receives the streamed messages in real time. `useView` re-renders as the visible Run's projection updates.
+6. If a client disconnects mid-stream, Ably resumes the subscription from the last serial on reconnect; the SDK rehydrates the view automatically.
 
-`useView` subscribes to the conversation tree and returns the visible messages along the currently selected branch. You have direct access to the tree: branching, pagination, and sibling navigation.
+`useView` subscribes to the conversation tree and returns the visible messages along the currently selected branch. The hook exposes `messages`, `hasOlder`, `loading`, `loadError`, `loadOlder`, `runOf`, `run`, `runs`, `branchSelection`, `selectSibling`, `send`, `regenerate`, and `edit`. It is the reactive mirror of the [`View` interface](/docs/ai-transport/api/javascript/core/client-session#view).
 
 ## Explore next <a id="next"/>
 
-- [Conversation branching](/docs/ai-transport/features/branching): use `useView`'s `getSiblings` and `select` to navigate branches.
-- [Conversation branching](/docs/ai-transport/features/branching): use `useView`'s `edit`, `regenerate`, and `select` to fork and navigate conversations.
+- [Branching, edit, and regenerate](/docs/ai-transport/features/branching): fork the conversation and navigate alternative branches with `view.regenerate`, `view.edit`, and `view.selectSibling`.
 - [History and replay](/docs/ai-transport/features/history): `useView` loads history on mount via the `limit` option.
-- [Sessions](/docs/ai-transport/concepts/sessions): durable sessions and how the conversation persists.
-- [React API reference](/docs/ai-transport/api/react/providers): providers and the per-hook pages.
+- [Cancellation](/docs/ai-transport/features/cancellation): the Stop button pattern and the agent-side `onCancel` authorisation hook.
+- [Concepts: Runs](/docs/ai-transport/concepts/runs): the SDK primitive each turn becomes.
+- [React API reference](/docs/ai-transport/api/react/core/providers): providers and the per-hook pages.
diff --git a/src/pages/docs/ai-transport/getting-started/vercel-ai-sdk.mdx b/src/pages/docs/ai-transport/getting-started/vercel-ai-sdk.mdx
index bf6283bc7d..620e1679e8 100644
--- a/src/pages/docs/ai-transport/getting-started/vercel-ai-sdk.mdx
+++ b/src/pages/docs/ai-transport/getting-started/vercel-ai-sdk.mdx
@@ -1,7 +1,7 @@
 ---
 title: "Get started with Vercel AI SDK"
 meta_description: "Build a streaming AI chat app with Vercel AI SDK and Ably AI Transport in a few minutes. Durable sessions, multi-device sync, and cancellation out of the box."
-meta_keywords: "AI Transport, Vercel AI SDK, Next.js, streaming, realtime, Ably, chat, LLM, durable sessions"
+meta_keywords: "AI Transport, Vercel AI SDK, useChat, Next.js, streaming, realtime, Ably, chat, LLM, durable sessions"
 intro: "Build a working chat app with Vercel AI SDK and AI Transport. Tokens stream over a durable session, so the conversation survives reconnects and syncs across tabs."
 redirect_from:
   - /docs/ai-transport/getting-started
@@ -18,7 +18,9 @@ A Next.js chat app where:
 - Tokens stream from the model into a durable [session](/docs/ai-transport/concepts/sessions), not the HTTP response.
 - Closing a tab and reopening it resumes the in-progress response.
 - A second tab on the same session sees the same conversation in real time.
-- A stop button cancels the in-progress [turn](/docs/ai-transport/concepts/turns).
+- A stop button cancels the in-progress [Run](/docs/ai-transport/concepts/runs).
+
+For direct access to the conversation tree, branching, and pagination, see [Get started with the Core SDK](/docs/ai-transport/getting-started/core-sdk).
 
 ## Prerequisites <a id="prerequisites"/>
 
@@ -26,7 +28,7 @@ A Next.js chat app where:
 - An [Ably account](https://ably.com/sign-up) with an API key.
 - An Anthropic API key, or any other model provider supported by Vercel AI SDK.
 
-## Install dependencies <a id="install"/>
+## Install dependencies <a id="install-dependencies"/>
 
 <Code>
 ```shell
@@ -34,93 +36,100 @@ npm install @ably/ai-transport ably ai @ai-sdk/react @ai-sdk/anthropic next reac
 ```
 </Code>
 
-## Set up authentication <a id="auth"/>
+## Set up authentication <a id="set-up-authentication"/>
 
-Create an auth endpoint at `/api/auth` that returns an Ably JWT to the client. The endpoint validates the user and signs a token with their client ID and the channel capabilities they need. See [authentication](/docs/ai-transport/concepts/authentication) for the full setup, including how to scope capabilities to a single conversation channel.
+Create an auth endpoint at `/api/auth/token` that returns an Ably JWT to the client. The endpoint validates the user and signs a token with their client ID and the channel capabilities they need. See [Set up authentication](/docs/ai-transport/getting-started/authentication) for the full setup.
 
-The client below uses `authUrl: '/auth'` to fetch tokens from this endpoint.
+The client below uses `authUrl: '/api/auth/token'` to fetch tokens from this endpoint.
 
-## Create the server route <a id="server"/>
+## Create the agent route <a id="create-the-agent-route"/>
 
-Create `app/api/chat/route.ts`. The server publishes the user's message to an Ably channel, invokes the LLM, and streams tokens into the channel. The HTTP response returns immediately; tokens flow through the durable session.
+Create `app/api/chat/route.ts`. The agent receives an [Invocation](/docs/ai-transport/concepts/invocations), creates an [AgentSession](/docs/ai-transport/api/javascript/core/agent-session) pre-bound to `UIMessageCodec`, starts a Run, hydrates the conversation, pipes the LLM stream, and ends the Run.
 
 <Code>
 ```javascript
 import { after } from 'next/server';
 import { streamText, convertToModelMessages } from 'ai';
 import { anthropic } from '@ai-sdk/anthropic';
-import Ably from 'ably';
-import { createServerTransport } from '@ably/ai-transport/vercel';
+import * as Ably from 'ably';
+import { Invocation } from '@ably/ai-transport';
+import { createAgentSession, vercelRunOutcome } from '@ably/ai-transport/vercel';
 
 const ably = new Ably.Realtime({ key: process.env.ABLY_API_KEY });
 
 export async function POST(req) {
-  const { messages, history, id, turnId, clientId, forkOf, parent } = await req.json();
-  const channel = ably.channels.get(id);
-
-  const transport = createServerTransport({ channel });
-  const turn = transport.newTurn({ turnId, clientId, parent, forkOf });
+  const invocation = Invocation.fromJSON(await req.json());
 
-  await turn.start();
-
-  if (messages.length > 0) {
-    await turn.addMessages(messages, { clientId });
-  }
+  const session = createAgentSession({
+    client: ably,
+    channelName: invocation.sessionName,
+  });
 
-  const allMessages = [
-    ...(history ?? []).map((h) => h.message),
-    ...messages.map((m) => m.message),
-  ];
+  await session.connect();
 
-  const result = streamText({
-    model: anthropic('claude-sonnet-4-20250514'),
-    system: 'You are a helpful assistant.',
-    messages: await convertToModelMessages(allMessages),
-    abortSignal: turn.abortSignal,
-  });
+  const run = session.createRun(invocation, { signal: req.signal });
 
   after(async () => {
-    const { reason } = await turn.streamResponse(result.toUIMessageStream());
-    await turn.end(reason);
-    transport.close();
+    try {
+      await run.start();
+      await run.loadConversation();
+
+      const result = streamText({
+        model: anthropic('claude-sonnet-4-20250514'),
+        system: 'You are a helpful assistant.',
+        messages: await convertToModelMessages(run.messages),
+        abortSignal: run.abortSignal,
+      });
+
+      const pipeResult = await run.pipe(result.toUIMessageStream());
+      const outcome = await vercelRunOutcome(pipeResult, result.finishReason);
+      if (outcome === 'suspend') {
+        await run.suspend();
+      } else {
+        await run.end(outcome);
+      }
+    } catch (err) {
+      await run.end('error');
+      throw err;
+    } finally {
+      session.close();
+    }
   });
 
-  return new Response(null, { status: 200 });
+  return Response.json({ runId: run.runId, invocationId: run.invocationId });
 }
 ```
 </Code>
 
 <Aside data-type='note'>
-`after()` is a Next.js function that extends the serverless function's lifetime beyond the HTTP response. This is what decouples the response stream from the HTTP request.
+`after()` is a Next.js function that extends the serverless function's lifetime beyond the HTTP response. The HTTP request triggers the agent; tokens reach the client through the Ably channel, not the response body.
 </Aside>
 
-## Create the chat component <a id="client"/>
+## Create the chat component <a id="create-the-chat-component"/>
 
-Create `app/chat.tsx`. The client uses Vercel's `useChat` hook with the AI Transport adapter. The transport subscribes to the Ably channel and syncs messages across every connected client.
+Create `app/chat.tsx`. The component uses Vercel's `useChat` hook with `createChatTransport` from `@ably/ai-transport/vercel`. The Vercel wrapper owns the agent-invocation POST; `useChat` calls into it as if it were the default HTTP transport.
 
 <Code>
 ```javascript
 'use client';
 
+import { useMemo, useState } from 'react';
 import { useChat } from '@ai-sdk/react';
-import { useActiveTurns, useView } from '@ably/ai-transport/react';
-import { useChatTransport, useMessageSync } from '@ably/ai-transport/vercel/react';
-import { useState } from 'react';
+import { useClientSession } from '@ably/ai-transport/react';
+import { createChatTransport } from '@ably/ai-transport/vercel';
 
 export function Chat({ chatId }) {
   const [input, setInput] = useState('');
+  const { session } = useClientSession();
 
-  const { chatTransport } = useChatTransport();
-  const { messages, setMessages, sendMessage, stop } = useChat({
+  const chatTransport = useMemo(() => createChatTransport(session), [session]);
+
+  const { messages, sendMessage, status, stop } = useChat({
     id: chatId,
     transport: chatTransport,
   });
 
-  useMessageSync({ setMessages });
-  useView({ limit: 30 });
-
-  const activeTurns = useActiveTurns();
-  const isStreaming = activeTurns.size > 0;
+  const isStreaming = status === 'submitted' || status === 'streaming';
 
   return (
     <div>
@@ -135,6 +144,7 @@ export function Chat({ chatId }) {
       <form
         onSubmit={(e) => {
           e.preventDefault();
+          if (!input.trim()) return;
           sendMessage({ text: input });
           setInput('');
         }}
@@ -152,9 +162,11 @@ export function Chat({ chatId }) {
 ```
 </Code>
 
-## Wire it together <a id="wire"/>
+## Wire it together <a id="wire-it-together"/>
+
+Create `app/page.tsx`. `Providers` sets up an authenticated Ably client. [`ClientSessionProvider`](/docs/ai-transport/api/react/core/providers) constructs the underlying [`ClientSession`](/docs/ai-transport/api/javascript/core/client-session) bound to the channel.
 
-Create `app/page.tsx`. The `Providers` component sets up an authenticated Ably client using `authUrl: '/auth'`. The `TransportProvider` wires the channel and codec into AI Transport.
+Update `channelName` to match a namespace with the AIT [channel rules](/docs/ai-transport/getting-started/channel-rules) configured.
 
 <Code>
 ```javascript
@@ -163,14 +175,15 @@ Create `app/page.tsx`. The `Providers` component sets up an authenticated Ably c
 import { useEffect, useState } from 'react';
 import * as Ably from 'ably';
 import { AblyProvider } from 'ably/react';
-import { ChatTransportProvider } from '@ably/ai-transport/vercel/react';
+import { ClientSessionProvider } from '@ably/ai-transport/react';
+import { UIMessageCodec } from '@ably/ai-transport/vercel';
 import { Chat } from './chat';
 
 function Providers({ children }) {
   const [client, setClient] = useState(null);
 
   useEffect(() => {
-    const ably = new Ably.Realtime({ authUrl: '/auth' });
+    const ably = new Ably.Realtime({ authUrl: '/api/auth/token', clientId: 'user-abc' });
     setClient(ably);
     return () => ably.close();
   }, []);
@@ -180,12 +193,12 @@ function Providers({ children }) {
 }
 
 export default function Page() {
-  const chatId = 'my-chat-session';
+  const chatId = 'conversations:my-chat-session';
   return (
     <Providers>
-      <ChatTransportProvider channelName={chatId}>
+      <ClientSessionProvider channelName={chatId} codec={UIMessageCodec}>
         <Chat chatId={chatId} />
-      </ChatTransportProvider>
+      </ClientSessionProvider>
     </Providers>
   );
 }
@@ -194,45 +207,22 @@ export default function Page() {
 
 Run `npm run dev` and open `http://localhost:3000`. Open a second tab to the same URL; both tabs share the same durable session.
 
-## What is happening <a id="whats-happening"/>
-
-1. The client sends the user message via HTTP POST to your API route.
-2. The server publishes the message to the Ably channel, invokes the LLM, and streams tokens to the channel.
-3. Every client subscribed to the channel receives tokens in real time.
-4. If a client disconnects, it reconnects automatically and resumes from where it left off.
-
-This is a [durable session](/docs/ai-transport/why#durable-sessions). The HTTP request triggers the agent; all communication flows through the Ably channel.
-
-## Understand the architecture <a id="architecture"/>
-
-Vercel AI SDK handles intelligence and UI. AI Transport handles what happens between the model and every device. See [Vercel AI SDK UI](/docs/ai-transport/frameworks/vercel-ai-sdk-ui) for the client-side integration and [Vercel AI SDK Core](/docs/ai-transport/frameworks/vercel-ai-sdk-core) for the server-side integration.
-
-Vercel built the `ChatTransport` interface as the extension point for custom transports. AI Transport implements `ChatTransport`, so you swap the transport layer without changing your application code:
-
-<Code>
-```javascript
-// Before: default HTTP transport
-const { messages } = useChat();
-
-// After: Ably transport (everything else stays the same)
-// Wrap your tree with <ChatTransportProvider channelName={chatId}> first.
-const { chatTransport } = useChatTransport();
-const { messages } = useChat({ transport: chatTransport });
-```
-</Code>
-
-### Choose an integration path <a id="integration-paths"/>
+## What is happening <a id="what-is-happening"/>
 
-Both paths use the same server code. The difference is client-side only.
+1. `sendMessage({ text })` calls the `ChatTransport`'s `sendMessages`. Under the hood, the AI Transport client SDK mints `inputEventId` and the message's `codecMessageId`, stamps them on the channel publish under `extras.ai.transport`, and returns an `ActiveRun` carrying the synchronous `inputCodecMessageId`. The `ChatTransport` then calls `activeRun.toInvocation().toJSON()` and POSTs the resulting `InvocationData` body (`{ inputEventId, sessionName }`) to your agent endpoint.
+2. The agent route receives the POST, calls `Invocation.fromJSON`, creates an `AgentSession`, and starts a Run. `session.createRun(invocation)` mints `runId` (for a fresh run) and `invocationId` (one per HTTP request); the agent stamps both on every event it publishes and returns them on the response. `run.start()` waits for the trigger input event on the channel (rewind plus live).
+3. The agent streams the LLM response through `run.pipe()` to the channel. Outputs carry `input-codec-message-id` so the client can correlate by an id it owned at send time.
+4. Every client subscribed to the channel decodes the streamed messages in real time. `useChat` re-renders as `UIMessage` parts accumulate.
+5. If a client disconnects mid-stream, Ably resumes the subscription from the last serial on reconnect; the session rehydrates without losing tokens.
 
-The `useChat` path is the simplest. `useChatTransport` wraps the core transport for direct use with Vercel's `useChat` hook. `useMessageSync` pushes other clients' messages into `useChat` state. You get Vercel's message management with AI Transport's durable delivery. Use this path for the standard Vercel `useChat` developer experience with durable sessions added. This is the path the tutorial above follows.
+## Understand the architecture <a id="understand-the-architecture"/>
 
-The [Core SDK](/docs/ai-transport/getting-started/core-sdk) path uses AI Transport's React hooks (`useView`, `useTree`, `useCreateView`) directly instead of `useChat`. The write operations (`send`, `regenerate`, `edit`, `update`) come back as methods on the `ViewHandle` returned by `useView`. This gives you full access to the conversation tree, branch navigation, split-pane views, and custom message construction. Use this path for branching UI, custom message rendering, or direct control over the conversation tree.
+Vercel AI SDK handles model orchestration and UI. AI Transport handles the durable session between agent and devices. See [Vercel AI SDK UI](/docs/ai-transport/frameworks/vercel-ai-sdk-ui) for the client-side integration and [Vercel AI SDK Core](/docs/ai-transport/frameworks/vercel-ai-sdk-core) for the server-side integration.
 
-## Explore next <a id="next"/>
+## Explore next <a id="explore-next"/>
 
 - [Vercel AI SDK UI](/docs/ai-transport/frameworks/vercel-ai-sdk-ui): client-side integration with `useChat`.
-- [Cancellation](/docs/ai-transport/features/cancellation): the stop button already works because `useChat`'s `stop()` calls `transport.cancel()`.
+- [Cancellation](/docs/ai-transport/features/cancellation): the stop button pattern and the agent-side `onCancel` authorisation hook.
 - [Multi-device sessions](/docs/ai-transport/features/multi-device): open another tab to see real-time sync.
-- [History and replay](/docs/ai-transport/features/history): `useView` already loads history on mount.
+- [History and replay](/docs/ai-transport/features/history): load past conversation on mount.
 - [Sessions](/docs/ai-transport/concepts/sessions): durable sessions and how the conversation persists.
diff --git a/src/pages/docs/ai-transport/going-to-production.mdx b/src/pages/docs/ai-transport/going-to-production.mdx
index ef4b9866da..fc5ad42fcb 100644
--- a/src/pages/docs/ai-transport/going-to-production.mdx
+++ b/src/pages/docs/ai-transport/going-to-production.mdx
@@ -49,13 +49,13 @@ The defaults are safe for development. For production:
 - Implement [token revocation](/docs/auth/revocation) for forced sign-out.
 - For cancel authorisation, set the `onCancel` hook on every turn. Reject cancels from clients that do not own the turn unless you specifically want admin-style global cancels.
 
-See [authentication](/docs/ai-transport/concepts/authentication) for the full setup.
+See [Set up authentication](/docs/ai-transport/getting-started/authentication) for the recipes and [authentication concept](/docs/ai-transport/concepts/authentication) for the model.
 
 ## Data shipping and retention <a id="data"/>
 
 If you persist conversations beyond the channel's retention:
 
-- Persist completed turns to your own store on `turn.end()`. Hydrate sessions from the store on demand; the channel handles live activity.
+- Persist completed turns to your own store on `run.end()`. Hydrate sessions from the store on demand; the channel handles live activity.
 - Channel history retention is configured per namespace. Pick a value that matches your live-recovery window, not your total retention target. The external store covers anything longer.
 - For analytics or search, stream channel activity to your data warehouse through [webhooks](/docs/integrations/webhooks) or [Kafka](/docs/integrations/kafka). This is one-way; AI Transport reads from the channel, not the warehouse.
 
@@ -89,5 +89,6 @@ Each feature page has its own edge cases. The cross-cutting items to walk throug
 
 ## Read next <a id="next"/>
 
-- [Authentication](/docs/ai-transport/concepts/authentication): the full auth setup.
+- [Set up authentication](/docs/ai-transport/getting-started/authentication): the practical auth setup.
+- [Authentication concept](/docs/ai-transport/concepts/authentication): the three-layer model and capability reference.
 - [Infrastructure](/docs/ai-transport/concepts/infrastructure): the platform guarantees you are relying on.
diff --git a/src/pages/docs/ai-transport/internals/codec-architecture.mdx b/src/pages/docs/ai-transport/internals/codec-architecture.mdx
index 42fd8abbbb..4cfeca8a8b 100644
--- a/src/pages/docs/ai-transport/internals/codec-architecture.mdx
+++ b/src/pages/docs/ai-transport/internals/codec-architecture.mdx
@@ -1,33 +1,55 @@
 ---
 title: "Codec architecture"
-meta_description: "How the AI Transport codec bridges domain events to Ably messages. Encoder, decoder, accumulator, and lifecycle tracker internals."
-meta_keywords: "codec architecture, AI Transport, encoder, decoder, accumulator, lifecycle tracker, custom codec, Ably"
-intro: "Internal architecture of the codec: encoder, decoder, accumulator, and lifecycle tracker. How each piece fits into the publish-side and subscribe-side pipelines."
+meta_description: "How the AI Transport codec bridges TInput and TOutput events to Ably messages. Encoder, decoder, and the input/output type split."
+meta_keywords: "codec architecture, AI Transport, encoder, decoder, TInput, TOutput, custom codec, Ably"
+intro: "Internal architecture of the codec: the input/output type split, encoder and decoder pipelines, and how the codec composes with the transport layer."
 ---
 
-The codec is the layer that translates between your AI framework's event types and Ably channel messages. This page describes how each part of the codec works internally and how the pieces fit together.
+The codec translates between your AI framework's event types and Ably channel messages. The interface is generic over four type parameters: `TInput` (client-published events), `TOutput` (agent-published events), `TProjection` (the per-Run reduced state), and `TMessage` (the rendered domain message). The two-direction split is type-system-enforced: an encoder can publish a `TInput` (`publishInput`) or a `TOutput` (`publishOutput`), and a decoder returns `{ inputs, outputs }` so the consumer can branch on direction without re-checking each event.
 
 The two pipelines mirror each other:
 
-```
-Publish side (server):
-  framework events
-       v
-  StreamEncoder.appendEvent / writeMessages
-       v
-  ChannelWriter.publish / appendMessage / updateMessage
-       v
-  Ably channel
+```text
+Publish side (agent):
+
+  TOutput events from streamText / your model
+        │
+        ▼
+  Encoder.publishOutput
+        │
+        ▼
+  ChannelWriter ── channel.publish / appendMessage / updateMessage
+        │
+        ▼
+  Ably channel (ai-output)
+
+Publish side (client):
+
+  TInput events from view.send / regenerate / edit
+        │
+        ▼
+  Encoder.publishInput
+        │
+        ▼
+  ChannelWriter ── channel.publish (discrete)
+        │
+        ▼
+  Ably channel (ai-input)
+
+Subscribe side (both):
 
-Subscribe side (client):
   Ably channel
-       v
-  StreamDecoder.decode  -> DecoderOutput[]
-       v
-  MessageAccumulator.processOutputs
-       v
-  framework messages
-       v
+        │
+        ▼
+  Decoder.decode ── DecodedMessage<TInput, TOutput>
+        │
+        ▼
+  Tree ── Codec.fold per node (TProjection on InputNode or RunNode)
+        │
+        ▼
+  Codec.getMessages(projection) ── CodecMessage<TMessage>[]
+        │
+        ▼
   View
 ```
 
@@ -35,145 +57,149 @@ Subscribe side (client):
 
 AI Transport separates concerns into two layers:
 
-- **Transport layer** (generic): manages turns, lifecycle events, cancellation, history, and multi-client sync. It works with any message type.
-- **Domain layer** (codec): maps framework-specific events to Ably publish operations and back. It knows the shape of your events and messages.
-
-The transport layer calls into the codec but never inspects the domain data. The codec calls into the channel writer but never manages turns or lifecycle. This separation is what makes AI Transport framework-agnostic.
-
-## Encoder core <a id="encoder-core"/>
-
-The encoder converts outbound domain events into Ably publish operations. It supports two modes.
-
-### Discrete mode <a id="discrete-mode"/>
+- Transport layer (generic): manages Run identity, lifecycle events, cancellation, input-event lookup, history pagination, and multi-client sync. It works with any `TInput` and `TOutput`.
+- Codec layer (domain): maps framework-specific events to Ably publish operations and back. It knows the shape of your events; it does not manage Run lifecycle.
 
-Discrete mode publishes a complete message in a single operation. The encoder calls `channel.publish()` once with the full message content. User messages and tool results typically use discrete mode.
+The transport layer calls into the codec but never inspects the domain payload. The codec calls into the channel writer but never manages Runs or lifecycle. This separation is what makes AI Transport framework-agnostic; the Vercel `UIMessageCodec` is one implementation, but any framework's event shape can be implemented against the same `Codec` interface.
 
-### Streamed mode <a id="streamed-mode"/>
+## TInput and TOutput <a id="tinput-and-toutput"/>
 
-Streamed mode publishes a message incrementally. `startStream` creates the message with `channel.publish()` and captures the returned serial. Each subsequent `appendStream` call calls `channel.appendMessage()` with that serial. `closeStream` (or `cancelStream`) sends a terminal append with `x-ably-status: finished` or `x-ably-status: cancelled`. This is the mode used for LLM response streaming.
+The codec is bidirectional with separate type bases:
 
-### Awaiting append promises <a id="awaiting-appends"/>
+- `CodecInputEvent` is the base for everything a client publishes. The Vercel codec defines `UserMessage`, `Regenerate`, `ToolResult`, `ToolResultError`, and `ToolApprovalResponse` as well-known input variants on top of this base.
+- `CodecOutputEvent` is the base for everything an agent publishes: text deltas, tool calls, reasoning, file or source parts, data chunks.
 
-Per-token append calls do not block the encoder. Awaiting each one would couple the stream rate to the network round-trip. Instead the encoder collects every append promise and awaits them as a batch when the stream closes or cancels.
+Both bases carry a `kind` discriminator the codec reads to dispatch. Inputs additionally carry routing fields (`codecMessageId`, `parent`, `target`) that the encoder stamps onto the wire as transport headers.
 
-This batched await is what catches failed appends. If any are rejected, the encoder replaces the message in place with the full accumulated content, so subscribers see the intended final state even when intermediate appends were lost. Concurrent closes serialise through a single flush, so closing several streams at once does not race.
+`Decoder.decode(message)` returns a `DecodedMessage<TInput, TOutput>` tagged with which direction the message rode on. Consumers branch on the tag rather than re-classifying.
 
-### Header composition <a id="header-merging"/>
+## Encoder <a id="encoder"/>
 
-Every outbound message carries both transport and domain headers. Append operations overwrite all the headers from previous operations on the same message, preferring the latest write.
-
-## Decoder core <a id="decoder-core"/>
-
-The decoder converts inbound Ably messages back into domain events. It dispatches on the message action to determine how to process each message.
-
-### Action dispatch <a id="action-dispatch"/>
-
-The decoder handles four Ably message actions:
-
-| Action | Meaning | Decoder behavior |
-| --- | --- | --- |
-| `create` | A new message arrived | Start a new message or stream. Emit the initial event. |
-| `append` | A token was appended to a message | Emit a delta event for the matching stream. |
-| `update` | A message was updated in place | Update the message state. If the status is terminal, close the stream. |
-| `delete` | A message was removed | Remove the message from state. |
+The encoder converts outbound events into Ably publish operations. It exposes four methods on the `Encoder` interface:
 
-### Stream tracker <a id="stream-tracker"/>
+| Method | Purpose |
+| --- | --- |
+| `publishInput(input, options?)` | Publish a single `TInput` event on `ai-input`. Stamps the codec-message-id and merges per-write headers under `extras.ai.transport`. |
+| `publishOutput(output, options?)` | Publish a single `TOutput` event on `ai-output`. Streams when the codec marks the event as appendable; otherwise publishes discretely. |
+| `cancel(reason?)` | Close any in-flight streams with `status: 'cancelled'`. |
+| `close()` | Flush pending appends, close active streams, release resources. |
 
-The decoder maintains a stream tracker that maps stream IDs to their current state. When a `create` action arrives with `x-ably-stream: true`, the tracker opens a new stream. Subsequent `append` actions for the same stream ID are routed to that stream. An `update` action with a terminal status closes the stream.
+### Streamed mode
 
-### Joining a stream mid-flight <a id="mid-stream-join"/>
+For events the codec marks as appendable (text deltas, reasoning deltas), the encoder runs a three-step pipeline per stream, exposed through the encoder core as `startStream`, `appendStream`, and `closeStream`:
 
-A client that joins a channel while a streamed message is already in progress sees an `append` or `update` for a stream it has never seen the original `create` for. The decoder treats the incoming content as the current full state of that stream and starts tracking it from there. Later appends are accumulated on top in the usual way. The client ends up in the same state as one that received every operation from the start.
+1. `startStream(streamId, payload)` calls `channel.publish` with `stream: 'true'`, `status: 'streaming'`, and the supplied `stream-id`. The publish returns a serial; the encoder core retains it for subsequent appends.
+2. Each subsequent appendable delta calls `appendStream(streamId, data)`, which fire-and-forgets `channel.appendMessage` with the captured serial.
+3. The terminal event calls `closeStream(streamId, payload)`, which writes a final `channel.appendMessage` with `status: 'complete'` (or `cancelStream(streamId)` writes `status: 'cancelled'`).
 
-## Accumulator <a id="accumulator"/>
+Per-token append calls do not block the encoder. The encoder collects every append promise and awaits them as a batch when the stream closes. If any append rejected, the encoder writes a recovery `channel.updateMessage` containing the full accumulated payload, so subscribers see the intended final state even when intermediate appends were lost.
 
-The accumulator builds complete messages from a sequence of domain events. It is used in two contexts:
+### Discrete mode
 
-### Live stream <a id="live-stream"/>
+Client publishes (`publishInput`) and lifecycle events use discrete mode: one `channel.publish` per event, no appends. Discrete events still carry the codec payload and any per-event headers. Codecs that need to publish several discrete messages atomically use `publishDiscreteBatch` from the encoder core to send them in a single channel publish.
 
-During live streaming, the accumulator processes events as they arrive from the decoder. It maintains a running list of messages, appending tokens to the in-progress message. The `messages` property returns all messages including the one currently being streamed. The `completedMessages` property returns only messages where the stream has ended.
+## Decoder <a id="decoder"/>
 
-### History <a id="history-context"/>
+The decoder converts inbound Ably messages back into `TInput` or `TOutput` events. It dispatches on the inbound message's Ably action.
 
-When loading history, the accumulator replays stored events to reconstruct message state. The `processOutputs` method accepts a batch of events and updates the internal state. This is the same method used during live streaming - the accumulator does not distinguish between live and historical events.
-
-<Code>
-```javascript
-const accumulator = codec.createAccumulator()
+| Action | Meaning | Decoder behaviour |
+| --- | --- | --- |
+| `message.create` | A new message arrived | Begin a new stream (when `stream: 'true'`) or hand the payload to the codec's discrete decode hook. |
+| `message.append` | A token was appended | Emit a delta for the matching `stream-id`; emit end events when the append carries `status: 'complete'`. |
+| `message.update` | A message was replaced | Prefix-match against the tracked stream. If the new data extends the accumulated text, emit the delta; otherwise treat as first-contact and accumulate. |
+| `message.delete` | A message was removed | Clear the stream's tracker state. |
 
-// Process events from history or live stream
-accumulator.processOutputs(events)
+The decoder maintains a stream tracker that maps Ably channel serial to its current state. A subscriber that joins mid-stream sees a `message.update` or `message.append` for a serial it has never seen the `message.create` for; the decoder treats the incoming state as the current full state and accumulates from there. The end state is the same as a subscriber that received every operation.
 
-// Read current state
-accumulator.messages          // all messages (including in-progress)
-accumulator.completedMessages // only completed messages
-accumulator.hasActiveStream   // true if a stream is in progress
-```
-</Code>
+`decode()` returns a `DecodedMessage<TInput, TOutput>`. The Tree feeds each decoded event through `Codec.fold(projection, event)` to update the owning Run's `TProjection`. `Codec.getMessages(projection)` materialises the projection into `CodecMessage<TMessage>[]`: each entry pairs the domain `message` with the SDK's client-minted `codecMessageId`. The View concatenates these across the visible Run chain and exposes the pair list as `getMessages()`. There is no second naked-message accessor; callers that just need the domain objects map `.message`.
 
-## Lifecycle tracker <a id="lifecycle-tracker"/>
+## Header tier story <a id="header-tier-story"/>
 
-The lifecycle tracker ensures clients receive a consistent sequence of lifecycle events, even when joining mid-stream. If a client subscribes to a channel where a turn is already in progress, the tracker synthesizes the missing lifecycle events (like `turn-start` and the stream create) so the client can process the in-progress turn correctly.
+Codec headers (`stream`, `stream-id`, `status`, `discrete`) live under `extras.ai.codec`. Transport headers (`run-id`, `codec-message-id`, `role`, `parent`, `fork-of`, and others) live under `extras.ai.transport`. The codec encoder reads and writes the codec tier; the transport layer reads and writes the transport tier. Neither layer reaches across the boundary, which keeps a custom codec from accidentally writing a `run-id` or a transport router from accidentally truncating a stream.
 
-The tracker maintains configurable phases. Each phase defines a set of events that must be observed before the next phase begins. If the tracker detects a gap (for example, the client received an append without seeing a stream create), it synthesizes the missing events and delivers them in order before the real event.
+`mergeHeaders`, `getTransportHeaders`, and `getCodecHeaders` from `@ably/ai-transport` are utility helpers for working with the tier structure.
 
-## Write a custom codec <a id="custom-codec"/>
+## Write a custom codec <a id="write-a-custom-codec"/>
 
-To build a codec for a framework not covered by the SDK:
+To support a framework not covered by the SDK:
 
-1. Implement the `Codec` interface with your event and message types.
-2. Use `createEncoderCore` and `createDecoderCore` from `@ably/ai-transport` to get the base publish and dispatch logic.
-3. Provide hooks that map your framework's events to the core operations (create, append, update, close).
-4. Implement `isTerminal` to identify events that end a stream.
+1. Define your `TInput` and `TOutput` event shapes as subtypes of `CodecInputEvent` and `CodecOutputEvent`.
+2. Implement the `Codec<TInput, TOutput, TProjection, TMessage>` interface. The required methods are `init` (initial per-Run projection), `fold` (reduce one event into the projection), `createEncoder`, `createDecoder`, `getMessages` (projection to messages), `createUserMessage` (wrap a `TMessage` as a `UserMessage` input), and `createRegenerate` (build a `Regenerate` input). The tool-resolution factories (`createToolResult`, `createToolResultError`, `createToolApprovalResponse`) are optional; implement them only if your `TInput` union includes those variants.
+3. Use `createEncoderCore` and `createDecoderCore` from `@ably/ai-transport` for the base publish and dispatch machinery. The encoder core exposes `publishDiscrete`, `publishDiscreteBatch`, `startStream`, `appendStream`, `closeStream`, `cancelStream`, and `cancelAllStreams`. The decoder core takes a `DecoderCoreHooks<TEvent>` object with `buildStartEvents`, `buildDeltaEvents`, `buildEndEvents`, and `decodeDiscrete` hooks.
 
 <Code>
 ```javascript
-import { createEncoderCore, createDecoderCore } from '@ably/ai-transport'
+import { createEncoderCore, createDecoderCore } from '@ably/ai-transport';
 
-const myCodec: Codec<MyEvent, MyMessage> = {
+const myCodec = {
+  init() {
+    return { messages: [], openStreams: new Map() };
+  },
+  fold(projection, event, meta) {
+    // reduce one event into the per-Run projection, using meta.serial for idempotency
+    return projection;
+  },
   createEncoder(channel, options) {
-    const core = createEncoderCore(channel, options)
+    const core = createEncoderCore(channel, options);
     return {
-      async appendEvent(event) {
-        await core.appendStream(event.messageId, serialize(event))
-      },
-      async writeMessages(messages, opts) {
-        await core.publishDiscreteBatch(messages.map((msg) => serialize(msg)), opts)
+      publishInput: async (input, opts) =>
+        core.publishDiscrete(
+          { name: 'ai-input', data: input, codecHeaders: { 'codec-type': input.kind } },
+          opts,
+        ),
+      publishOutput: async (output, opts) => {
+        if (isStreamStart(output)) {
+          return core.startStream(output.id, { name: 'ai-output', data: output.delta ?? '' }, opts);
+        }
+        if (isStreamDelta(output)) {
+          core.appendStream(output.id, output.delta);
+          return;
+        }
+        if (isStreamEnd(output)) {
+          return core.closeStream(output.id, { name: 'ai-output', data: '' });
+        }
+        return core.publishDiscrete({ name: 'ai-output', data: output }, opts);
       },
-      async writeEvent(event) {
-        await core.publishDiscrete(serialize(event))
-      },
-      async abort() { await core.abortAllStreams() },
-      async close() { await core.close() },
-    }
+      cancel: () => core.cancelAllStreams(),
+      close: () => core.close(),
+    };
   },
   createDecoder() {
     const core = createDecoderCore({
-      onCreate: (msg) => deserialize(msg.data),
-      onAppend: (msg) => deserialize(msg.data),
-      onUpdate: (msg) => deserialize(msg.data),
-    })
+      buildStartEvents: (tracker) => [{ type: 'stream-start', id: tracker.streamId }],
+      buildDeltaEvents: (tracker, delta) => [{ type: 'stream-delta', id: tracker.streamId, delta }],
+      buildEndEvents: (tracker) => [{ type: 'stream-end', id: tracker.streamId }],
+      decodeDiscrete: (payload) => [payload.data],
+    });
     return {
-      decode(message) {
-        return core.decode(message)
+      decode: (message) => {
+        const events = core.decode(message);
+        // Tag each event as TInput or TOutput based on the wire name.
+        return message.name === 'ai-input'
+          ? { inputs: events, outputs: [] }
+          : { inputs: [], outputs: events };
       },
-    }
+    };
+  },
+  getMessages(projection) {
+    // return CodecMessage<TMessage>[] for rendering
+    return projection.messages;
   },
-  createAccumulator() {
-    // Build and return a MessageAccumulator for your types
+  createUserMessage(message) {
+    return { kind: 'user-message', message };
   },
-  isTerminal(event) {
-    return event.type === 'finish' || event.type === 'error'
+  createRegenerate(target, parent) {
+    return { kind: 'regenerate', target, parent };
   },
-}
+};
 ```
 </Code>
 
-See the [Codec API reference](/docs/ai-transport/api/javascript/codec) for the full interface specification.
+See the [Codec API reference](/docs/ai-transport/api/javascript/core/codec) for the full interface and signatures.
 
 ## Related pages <a id="related"/>
 
-- [Wire protocol](/docs/ai-transport/internals/wire-protocol) - the message format the codec reads and writes.
-- [Conversation tree](/docs/ai-transport/internals/conversation-tree) - how decoded messages build the tree.
-- [Transport patterns](/docs/ai-transport/internals/transport-patterns) - how the transport layer drives the codec.
-- [Codec API reference](/docs/ai-transport/api/javascript/codec) - the public codec interface.
+- [Wire protocol](/docs/ai-transport/internals/wire-protocol): the channel format the codec reads and writes.
+- [Conversation tree](/docs/ai-transport/internals/conversation-tree): how decoded events fold into per-Run projections and build the tree.
+- [Transport patterns](/docs/ai-transport/internals/transport-patterns): how the transport layer drives the codec.
+- [Codec API reference](/docs/ai-transport/api/javascript/core/codec): the public codec interface.
diff --git a/src/pages/docs/ai-transport/internals/conversation-tree.mdx b/src/pages/docs/ai-transport/internals/conversation-tree.mdx
index b246f4fc0d..03edbe001d 100644
--- a/src/pages/docs/ai-transport/internals/conversation-tree.mdx
+++ b/src/pages/docs/ai-transport/internals/conversation-tree.mdx
@@ -1,128 +1,128 @@
 ---
 title: "Conversation tree"
-meta_description: "How AI Transport maintains a branching conversation structure. Serial ordering, sibling groups, fork chains, and flatten algorithm."
-meta_keywords: "conversation tree, branching, fork, sibling groups, flatten algorithm, AI Transport, Ably"
-intro: "Internal mechanics of the conversation tree: serial ordering, sibling groups, fork chains, and the flatten algorithm that projects a branch into a list."
+meta_description: "How AI Transport maintains a branching conversation tree. The two-node turn model, sibling resolution, and message-anchored branch selection."
+meta_keywords: "conversation tree, branching, fork, sibling resolution, regenerate group, InputNode, RunNode, AI Transport, Ably"
+intro: "Internal mechanics of the conversation tree: the input-and-run two-node turn model, message-anchored sibling resolution, and how the View walks the tree to produce a flat message list."
 ---
 
-AI Transport maintains conversations as a tree, not a list. Every message is a node with a parent pointer. Edits and regenerations create forks rather than replacements, so the full history is preserved. The tree is projected into a linear list for rendering by selecting one branch at each fork point.
+AI Transport models a conversation as a tree of two node kinds: an `InputNode` for every user prompt and a `RunNode` for every agent reply. Each turn is two nodes joined by a parent edge: the input node hangs off the previous reply, and the reply run hangs off its input. Each node holds a per-node codec projection folded from the events published under its key; the View walks the chosen branch and extracts a flat `CodecMessage<TMessage>[]` from those projections. Each entry pairs the domain message with the codec-message-id the SDK keys on.
 
-A conversation with an edit looks like:
+A conversation with one edit and one regenerate looks like:
 
-```
-root
-  user "What is the budget?"  (M1)
-    assistant "The budget is..."  (M2)
-      user "Now focus on Q4"  (M3)
-        assistant "Q4 specifically..."  (M4)
-      user "Now focus on Q4 only"  (M3', fork-of M3)
-        assistant "Q4 focus..."  (M4')
+```text
+(root)
+└── I1 (user M1: "Plan a trip to Lisbon")
+    └── R1 (agent reply, runId R1, assistant M2: "Here's a 3-day itinerary...")
+        ├── R1' (regenerate sibling of R1, runId R1', regeneratesCodecMessageId M2,
+        │        assistant M2': "Here's an alternative...")
+        ├── I2 (user M3: "Make it 5 days")
+        │   └── R2 (runId R2, assistant M4: "5-day itinerary...")
+        └── I2' (edit sibling of I2, user M3': "Focus on food", forkOf M3)
+            └── R3 (runId R3, assistant M4': "Food-focused itinerary...")
 ```
 
-The view selects one of the sibling pairs at the M3 fork point and flattens the chosen branch into a linear list for rendering.
+Two kinds of sibling groups surface:
 
-## Why a tree, not a list <a id="why-a-tree"/>
+Input edits are sibling input nodes. `I2` and `I2'` share the same parent (`R1`'s `codecMessageId M2`), and `I2'.forkOf = M3` links it to the original prompt.
 
-In a simple chat interface, conversation looks linear. But as soon as a user edits a message or regenerates a response, a single list breaks down. Either you discard the original content (destructive) or you need a structure that can hold multiple versions.
+Regenerate siblings are sibling reply runs. `R1` and `R1'` share the same parent (`I1`'s `codecMessageId M1`), and `R1'.regeneratesCodecMessageId = M2` records the slot it replaces. Reply-run siblings group by shared parent; they carry no Run-level `forkOf`.
 
-The tree solves this. An edit creates a sibling of the original message - both exist in the tree. A regenerate creates a sibling of the original response. Navigation between siblings lets users browse alternative branches. Nothing is ever lost.
+Branch selection is message-anchored: the branch decision lives on a `codec-message-id`, not on a `runId`. The View exposes `branchSelection(codecMessageId)` and `selectSibling(codecMessageId, index)` so a UI renders navigation arrows next to a bubble without knowing whether it is an input or a run.
 
-## Serial-first ordering <a id="serial-ordering"/>
+## Why two node kinds <a id="why-two-node-kinds"/>
 
-Messages in the tree are ordered by their Ably serial. Ably assigns a serial to every message published on a channel, providing a total order that is consistent across all subscribers.
+A run-only tree could not represent an edit cleanly: editing a user prompt is not a different agent run, it is a different user prompt that the agent then replies to. Splitting input and reply into separate nodes lets the tree carry both kinds of branching:
 
-Optimistic messages do not have an Ably serial when first inserted - they exist only in the local tree. They receive a placeholder serial that sorts them after all confirmed messages. When the server publishes the same message to the channel, the client reconciles and promotes the placeholder serial to the real one. This is serial promotion.
+- An edit produces a sibling input node at the parent reply (or root for the first prompt). The new input gets its own subtree of replies underneath.
+- A regenerate produces a sibling reply run at the same input. Both replies attach to the same prompt; the View picks which one to render.
 
-After promotion, the message's position in the sorted list may change to reflect the true publication order. In practice, the change is usually invisible because the optimistic message was published moments before the server confirmation.
+The same parent-edge mechanic handles both. The tree never asks "is this branch an edit or a regenerate?"; it asks "what siblings share this parent?", and the kind of the node tells you what shape of UI to draw.
 
-## Data structures <a id="data-structures"/>
+## InputNode and RunNode <a id="node-types"/>
 
-The conversation tree is maintained with three core structures:
+Every node in the tree is a `ConversationNode = InputNode | RunNode`. Narrow on `kind` (`'input'` or `'run'`) before reading kind-specific fields.
 
-| Structure | Purpose |
+| `InputNode<TProjection>` field | Description |
+| --- | --- |
+| `kind` | `'input'`. |
+| `codecMessageId` | Primary key. The client-owned id minted when the input is published. |
+| `parentCodecMessageId` | The `codec-message-id` of the immediately preceding reply run on this chain, or `undefined` for the first input in a conversation. |
+| `forkOf` | The `codec-message-id` this input forks from when it is an edit, or `undefined` for the first version. Sibling input nodes share the same `forkOf` anchor. |
+| `projection` | The codec's per-input projection, folded from every input event under this `codec-message-id`. |
+| `serial` | Ably serial of the first observed message for this input. Absent for optimistic (locally-created) inputs. |
+
+| `RunNode<TProjection>` field | Description |
 | --- | --- |
-| `nodeIndex` | A map from message ID to node. Each node holds the message, its serial, and its parent ID. This is the primary lookup. |
-| `sortedList` | All nodes sorted by serial. Used for iteration and pagination. |
-| `parentIndex` | A map from parent ID to the list of child node IDs. Used to find sibling groups. |
+| `kind` | `'run'`. |
+| `runId` | Primary key. Agent-minted. |
+| `parentCodecMessageId` | The `codec-message-id` of the input node this Run replies to (the user prompt the agent answered). `undefined` for the root Run. |
+| `forkOf` | The node key of the node this Run replaces, or `undefined` if this Run is not a fork. Reply-run regenerate siblings do not use this; they group by shared parent. |
+| `regeneratesCodecMessageId` | The `codec-message-id` of the assistant message this Run regenerates. Verbatim from the wire's `msg-regenerate`. |
+| `clientId` | The Ably `clientId` of the client that started the Run, from `run-client-id`. |
+| `status` | `'active'` between `ai-run-start` and `ai-run-end`; `'suspended'` after `ai-run-suspend` until `ai-run-resume`; otherwise the terminal `RunEndReason`. |
+| `projection` | The codec's per-Run projection, folded from every event published under this `run-id`. |
+| `invocationId` | The agent-minted invocation id observed from the most recent `ai-run-start` (or `ai-run-resume` for continuations). Empty string until run-start arrives. |
+| `startSerial` / `endSerial` | Ably serials of the lifecycle events. Used for sibling ordering. |
 
-<Aside data-type='note'>
-Branch selection (which sibling is active at each fork point) is managed by the View layer, not the tree itself. The tree is a pure data structure; the View maintains a `selections` map and uses it when flattening.
-</Aside>
+## Run identity is resolved on the channel <a id="run-identity"/>
 
-## Upsert as sole mutation <a id="upsert"/>
+The Tree adopts run identity from the wire, not from the HTTP POST body. A fresh run begins when the client publishes an input event with no `run-id`; the agent's `createRun` mints a `run-id`, stamps it on `ai-run-start` and every output event, and the Tree creates a `RunNode` from the run-start. A continuation begins when the input event carries an existing `run-id` (the client knew it from `ActiveRun.runId` and stamped it on the publish); the agent reads that id from the input event's wire headers, reuses it instead of minting fresh, and publishes `ai-run-resume` so the Tree routes the resume to the existing `RunNode`.
 
-The tree has a single mutation operation: upsert. Every inbound message, whether from a live subscription or history, passes through upsert. The operation either inserts a new node or updates an existing one.
+There is no `run-continue` header: the presence or absence of `run-id` on the input event is the entire signal.
 
-- **Insert**: creates a new node, adds it to `nodeIndex`, inserts it into `sortedList` at the correct position, and updates `parentIndex`.
-- **Update**: replaces the message content and serial on an existing node. If the serial changed (serial promotion), the node's position in `sortedList` is adjusted.
+## Coordination via Run lifecycle events <a id="coordination"/>
 
-Using a single mutation path keeps the tree consistent. There is no separate "insert from history" or "insert from live" path - both go through upsert.
+The Tree does not arbitrate winners. Coordination is explicit:
 
-## Sibling groups <a id="sibling-groups"/>
+- Lifecycle is paired: every Run begins with `ai-run-start` and ends with `ai-run-end`. The View filters active Runs by `status === 'active'`; without an `ai-run-end` the Run stays active.
+- Suspend and resume are distinct events: `ai-run-suspend` parks a Run at `'suspended'` (still live); `ai-run-resume` re-activates it. Both are non-terminal; only `ai-run-end` is terminal.
+- Sibling order is by serial: when more than one node lands at the same parent, they are ordered by serial (oldest first). The default selection at a fork point is the newest sibling.
 
-Messages that share the same parent form a sibling group. In a linear conversation, every parent has exactly one child. When a fork happens (edit or regenerate), the parent gains additional children.
+Earlier versions of the SDK described a "winner / precedence" model on the Tree. That model is gone. The current design relies on `Run.start()` to publish the bracketing events explicitly and on `ai-run-resume` to mark continuations; no implicit precedence is needed.
 
-The `x-ably-fork-of` header marks the message that the new branch diverges from. When the tree receives a message with `fork-of`, it creates a sibling at the fork point:
+## Sibling resolution <a id="sibling-resolution"/>
 
-1. Find the node identified by `fork-of`.
-2. Use that node's parent as the parent for the new message.
-3. Add the new message to the parent's child list in `parentIndex`.
+`tree.getSiblingNodes(key)` returns the sibling group the node keyed by `key` belongs to. The key is either a `RunNode.runId` or an `InputNode.codecMessageId`. The two sibling-group shapes are: input edits, where input nodes share a parent and chain via `forkOf` (the original user prompt plus every edit of it); and regenerate siblings, where reply runs share an input-node parent (the original reply plus every regenerate of it).
 
-The new message becomes a sibling of the forked message. The View layer's `selections` map determines which sibling is active.
+The result is ordered oldest-first by serial. It is a single-element array when the node has no siblings, and an empty array when the key is unknown.
 
-## Flatten algorithm <a id="flatten"/>
+The View consumes this to compute `branchSelection(codecMessageId)`, which returns a `BranchSelection<TMessage>` bundle (`hasSiblings`, `siblings`, `index`, `selected`). The View's per-instance `selections` map records the selected sibling at each anchor; `selectSibling(codecMessageId, index)` updates it and emits an `'update'` event.
 
-The tree is rendered as a linear list by flattening the selected branch. The flatten algorithm walks from the root and at each node with children, follows the selected branch:
+## Walk the tree <a id="walking-the-tree"/>
 
-1. Start at the root node (a node with no parent).
-2. Add the current node to the output list.
-3. Look up the current node's children in `parentIndex`.
-4. If there are children, select the one indicated by the View's `selections` map (default: the last child, which is the most recent).
-5. Repeat from step 2 with the selected child.
-6. Stop when the current node has no children.
+The View walks the tree to produce a flat ordered list of nodes along the currently selected branch:
 
-The result is a linear path through the tree that represents the currently selected conversation. Changing a selection and re-flattening produces a different linear path.
+1. Start at the root. The root is either the first input node (a conversation that opens with a user prompt) or, in rare cases, a Run with no `parentCodecMessageId`.
+2. Add the current node to the visible chain.
+3. If the current node has siblings, select the one indicated by the View's `selections` map (or default to the newest).
+4. Move to the selected node's children: nodes whose `parentCodecMessageId` is the current node's primary key.
+5. Stop when there are no children.
 
-<Aside data-type='note'>
-The following pseudocode shows a simplified top-down tree walk for clarity. The actual implementation is a linear scan of the serial-sorted list with parent-reachability filtering, which avoids recursive traversal and works efficiently with the sorted data structure.
-</Aside>
+The View concatenates each visible node's messages from `codec.getMessages(node.projection)`, then applies regenerate substitution: when the visible chain contains both an original reply and its regenerate sibling, the regenerate's content replaces the original in the rendered message list. The result is a `CodecMessage<TMessage>[]` representing the currently selected conversation. Each pair carries the domain message and its codec-message-id.
 
-<Code>
-```javascript
-// Simplified view - see note above for actual implementation
-function flatten(tree, selections) {
-  const result = []
-  let current = tree.root
+## Serial ordering and optimistic reconciliation <a id="serial-ordering-and-optimistic-reconciliation"/>
 
-  while (current) {
-    result.push(current)
-    const children = tree.parentIndex.get(current.id)
-    if (!children || children.length === 0) break
-    const selectedIndex = selections.get(current.id) ?? children.length - 1
-    current = tree.nodeIndex.get(children[selectedIndex])
-  }
+Messages within a node are ordered by their Ably serial. The serial is the total order Ably assigns on the channel, consistent across all subscribers. Optimistic messages do not have a serial when first inserted; they sort after every confirmed message until the server publish lands. When the published event arrives the Tree promotes the placeholder to the real serial and re-sorts. In practice the change is invisible because the optimistic message was published moments before the confirmation.
 
-  return result
-}
-```
-</Code>
+## Query the tree <a id="querying-the-tree"/>
 
-## Querying the tree <a id="querying"/>
+The `Tree` interface exposes:
 
-The tree exposes several query methods through the view:
-
-| Method | Return type | Description |
-| --- | --- | --- |
-| `getSiblings(messageId)` | `TMessage[]` | Get all sibling messages for a given message, ordered chronologically by serial. |
-| `hasSiblings(messageId)` | `boolean` | Check whether a message has siblings (is at a fork point). |
-| `getNode(messageId)` | `Node` | Get the full node for a message, including parent and serial. |
-| `getSelectedIndex(messageId)` | `number` | Get the currently selected index within a sibling group. |
-| `select(messageId, index)` | `void` | Change the selected sibling at a fork point. Triggers re-flatten. |
+| Method | Description |
+| --- | --- |
+| `getRunNode(runId)` | Look up a Run by id. |
+| `getNodeByCodecMessageId(codecMessageId)` | Find the input or run node that owns a given codec-message-id. Returns a `ConversationNode` union; narrow on `kind` before reading kind-specific fields. |
+| `getSiblingNodes(key)` | The sibling group for a node key (edit siblings for an input, regenerate siblings for a run). Ordered oldest-first; single-element when there are no siblings; empty when the key is unknown. |
+| `on('update', ...)` | Structural changes (node insert, delete, sort). |
+| `on('ably-message', ...)` | Raw inbound channel messages. |
+| `on('run', ...)` | Run lifecycle events. |
+| `on('output', ...)` | Decoded agent outputs folded for a Run, with routing metadata (`runId`, `inputCodecMessageId`, `codecMessageId`, `serial`). Fires once per inbound message after its fold; fires with an empty `events` array for inputs-only folds so it doubles as a projection-changed signal. |
 
-These methods are used by branch navigation UI components to let users browse alternative branches.
+The View consumes these to drive its branch-aware projection. Most application code reaches for the View; the Tree is the lower-level surface for inspection.
 
 ## Related pages <a id="related"/>
 
-- [Conversation branching](/docs/ai-transport/features/branching) - the user-facing edit, regenerate, and branch-navigation feature.
-- [Optimistic updates](/docs/ai-transport/features/optimistic-updates) - how serial promotion works.
-- [Wire protocol](/docs/ai-transport/internals/wire-protocol) - the `x-ably-parent` and `x-ably-fork-of` headers that build the tree.
+- [Branching, edit, and regenerate](/docs/ai-transport/features/branching): the user-facing feature.
+- [Wire protocol](/docs/ai-transport/internals/wire-protocol): the `parent`, `fork-of`, and `msg-regenerate` headers that build the tree.
+- [Codec architecture](/docs/ai-transport/internals/codec-architecture): how decoded events fold into per-node projections.
+- [Optimistic updates](/docs/ai-transport/features/optimistic-updates): how serial promotion works in the View.
diff --git a/src/pages/docs/ai-transport/internals/index.mdx b/src/pages/docs/ai-transport/internals/index.mdx
index 37e245982d..d8d0b351ad 100644
--- a/src/pages/docs/ai-transport/internals/index.mdx
+++ b/src/pages/docs/ai-transport/internals/index.mdx
@@ -2,12 +2,17 @@
 title: "Internals"
 meta_description: "Under the hood of Ably AI Transport. Wire protocol, codec architecture, conversation tree, and transport patterns."
 meta_keywords: "AI Transport internals, wire protocol, codec, conversation tree, transport patterns, Ably"
-intro: "The wire protocol, codec architecture, conversation tree structure, and transport patterns that make up AI Transport under the hood. For curious engineers and codec implementers."
+intro: "The wire protocol, codec architecture, conversation tree, and transport patterns that make up AI Transport under the hood. For senior engineers and codec implementers."
 ---
 
-The internals section covers the wire protocol, codec architecture, conversation tree structure, and transport patterns that make up AI Transport under the hood. The audience is engineers who want to understand the system before betting on it, and contributors building custom codecs.
+The internals section is for engineers who want to understand the system before betting on it, and for anyone building a custom codec. Nothing here is required to use the SDK.
 
-The internals fit together as four layers, from the application-facing model down to the SDK plumbing. The conversation tree is the highest-level structure: sessions are trees of messages joined by parent and fork-of pointers. The codec architecture sits underneath, encoding domain events into Ably operations on the publish side and decoding them back into messages on the subscribe side. The wire protocol defines what those operations look like on the channel: the transport headers, lifecycle events, and message identity that travel over Ably. The transport patterns are the SDK-internal components, including the `StreamRouter`, the `TurnManager`, the `pipeStream` plumbing, and the cancel routing pipeline, that hold it all together.
+Four layers fit together, from the application-facing model down to the SDK plumbing:
+
+- Conversation tree: the highest-level structure. Every session is a tree of `ConversationNode`s (`InputNode`s keyed by `codec-message-id` for user prompts and `RunNode`s keyed by `runId` for agent replies), joined by `parent` and `fork-of` pointers. The View walks the tree to produce a flat message list for rendering.
+- Codec architecture: the encoder converts client-published `TInput`s and agent-published `TOutput`s into Ably publish operations. The decoder converts inbound Ably messages back into typed events. The codec is what makes AI Transport framework-agnostic.
+- Wire protocol: the Ably channel format. Two header tiers (`extras.ai.transport` for run and message identity; `extras.ai.codec` for stream and status metadata), four Run lifecycle event names (`ai-run-start`, `ai-run-suspend`, `ai-run-resume`, `ai-run-end`), one cancel signal (`ai-cancel`), and two content event names (`ai-input` for client publishes, `ai-output` for agent publishes).
+- Transport patterns: the SDK-internal components that drive the codec over the wire: the stream router that fans inbound channel messages out to per-Run streams, the input-event lookup that resolves a POSTed invocation to its channel events, and the cancel-routing pipeline.
 
 ## Topics <a id="topics"/>
 
@@ -15,22 +20,22 @@ The internals fit together as four layers, from the application-facing model dow
 {[
   {
     title: 'Wire protocol',
-    description: 'The Ably channel wire format: transport headers, lifecycle events, content messages, and message identity.',
+    description: 'The Ably channel wire format: header tiers, lifecycle events, content event names, and message identity.',
     link: '/docs/ai-transport/internals/wire-protocol',
   },
   {
     title: 'Codec architecture',
-    description: 'How the codec bridges domain events to Ably messages. Encoder, decoder, accumulator, and lifecycle tracker internals.',
+    description: 'How the codec bridges TInput and TOutput to Ably messages. Encoder, decoder, and the input/output type split.',
     link: '/docs/ai-transport/internals/codec-architecture',
   },
   {
     title: 'Conversation tree',
-    description: 'The branching conversation structure. Serial ordering, sibling groups, fork chains, and the flatten algorithm.',
+    description: 'The branching Run tree. Sibling resolution, regenerate groups, and message-anchored branch selection.',
     link: '/docs/ai-transport/internals/conversation-tree',
   },
   {
     title: 'Transport patterns',
-    description: 'Internal transport components: StreamRouter, TurnManager, pipeStream, and cancel routing.',
+    description: 'Internal transport components: stream router, input-event lookup, and cancel routing.',
     link: '/docs/ai-transport/internals/transport-patterns',
   },
 ]}
diff --git a/src/pages/docs/ai-transport/internals/transport-patterns.mdx b/src/pages/docs/ai-transport/internals/transport-patterns.mdx
index e1109b6129..ae02a71e34 100644
--- a/src/pages/docs/ai-transport/internals/transport-patterns.mdx
+++ b/src/pages/docs/ai-transport/internals/transport-patterns.mdx
@@ -1,142 +1,141 @@
 ---
 title: "Transport patterns"
-meta_description: "Internal transport components in AI Transport. StreamRouter, TurnManager, pipeStream, and cancel routing."
-meta_keywords: "transport patterns, StreamRouter, TurnManager, pipeStream, cancel routing, AI Transport, Ably"
-intro: "Internal transport components: StreamRouter, TurnManager, pipeStream, and the cancel routing pipeline. How the SDK coordinates between codec, channel, and application code."
+meta_description: "Internal transport components in AI Transport. Stream router, input-event lookup, and cancel routing."
+meta_keywords: "transport patterns, stream router, input-event lookup, cancel routing, AI Transport, Ably"
+intro: "Internal transport components: the stream router on the client, the input-event lookup on the agent, and the cancel-routing pipeline. How the SDK coordinates between codec, channel, and application code."
 ---
 
-The transport layer contains several internal components that coordinate between the codec, the Ably channel, and your application code. This page describes the key patterns and what each component is responsible for.
+The transport layer contains several internal components that coordinate between the codec, the Ably channel, and application code. This page describes the key patterns and what each component owns.
 
 Inbound data flow on the client:
 
+```text
+Ably channel
+      │
+      ▼
+Channel subscription
+   (ai-input, ai-output, ai-run-start, ai-run-suspend,
+    ai-run-resume, ai-run-end, ai-cancel)
+      │
+      ▼
+Decoder ── DecodedMessage<TInput, TOutput>
+      │
+      ▼
+Tree ── per-node Codec.fold (TProjection on InputNode or RunNode)
+      │
+      ▼
+Tree emits:  'update'      structural change (node insert / sort / lifecycle)
+             'run'         Run lifecycle event (start / suspend / resume / end)
+             'output'      decoded TOutput events with routing metadata
+                           (runId, inputCodecMessageId, codecMessageId, serial)
+      │
+      ▼
+View ── walks the selected branch, emits 'update' on visible changes
+ActiveRun ── runId Promise resolves on the matching ai-run-start
 ```
-Ably channel -> Subscription -> StreamDecoder -> StreamRouter
-                                                     |
-                                  +------------------+
-                                  v
-                          per-turn ReadableStream
-                                  |
-                                  v
-                          Application code
-```
-
-Outbound data flow on the server:
 
+Outbound data flow on the agent:
+
+```text
+Application code (streamText, your model handler)
+      │
+      ▼
+Run.pipe(stream) ── reads TOutput from ReadableStream
+      │
+      ▼
+Encoder.publishOutput ── stream or discrete via codec rules
+      │
+      ▼
+ChannelWriter ── channel.publish / appendMessage / updateMessage
+      │
+      ▼
+Ably channel (ai-output)
+
+Run.abortSignal ◄── cancel routing fires on matching ai-cancel
 ```
-Application code -> Turn (via TurnManager) -> StreamEncoder -> ChannelWriter -> Ably channel
-                          |
-                          +---> abortSignal (cancel routing)
-```
-
-## StreamRouter <a id="stream-router"/>
-
-The StreamRouter lives on the client side. It routes inbound Ably channel events to the correct stream, turning a flat subscription into per-turn `ReadableStream` instances.
 
-When the client transport subscribes to a channel, all messages arrive through a single callback. The StreamRouter dispatches each message to the appropriate turn based on the `x-ably-turn-id` header:
+## Stream router <a id="stream-router"/>
 
-1. When the client calls `send()` (during `_internalSend`), the router creates a new `ReadableStream` and its controller for that turn.
-2. Content messages are enqueued into the matching stream's controller.
-3. When a terminal event arrives (`turn-end`, `abort`, or `error`), the router closes the stream's controller.
+The stream router lives on the client. It routes inbound channel events to the correct per-Run state, turning a flat channel subscription into per-Run projections that the View exposes as visible messages.
 
-This gives each turn an independent stream that can be consumed, cancelled, or abandoned without affecting other turns.
+The router keys on the triggering input's `codec-message-id`, the synchronous handle the client owns from send time (the agent has not minted the `runId` yet). When the client calls a write method on the View (`send`, `regenerate`, `edit`), the View mints the input's `codec-message-id`, publishes the input on the channel, and registers an optimistic input node in the Tree. The returned `ActiveRun` carries the synchronous `inputCodecMessageId`, the `inputEventId`, and a `runId: Promise<string>` that resolves when the agent's `ai-run-start` for this send lands.
 
-## TurnManager <a id="turn-manager"/>
+When inbound `ai-output` messages decode to `TOutput` events, the router folds them into the matching Run's per-Run projection by reading the output's `input-codec-message-id` header (the agent echoes the triggering input's id on every event it publishes). When `ai-run-end` arrives for the Run, the router marks the Run terminal. The View's `update` event fires; consumers re-read `getMessages()` / `runs()`.
 
-The TurnManager lives on the server side. It tracks active turns and manages their lifecycle events.
+If the channel loses continuity (`ChannelContinuityLost`), the router surfaces the error via the session's `on('error', ...)` and active Runs are marked accordingly.
 
-When the server creates a new turn with `transport.newTurn()`, the TurnManager:
+## Input-event lookup <a id="input-event-lookup"/>
 
-1. Registers the turn with its ID, client ID, and optional fork metadata.
-2. Publishes a `turn-start` lifecycle event to the channel.
-3. Creates an `AbortController` wired to cancel signals for this turn.
-4. Returns a turn handle with `streamResponse()`, `addMessages()`, `end()`, and `abortSignal`.
+The input-event lookup lives on the agent. When `Run.start()` is called, the agent attaches the channel with `rewind` and waits for the triggering `event-id` carried in the invocation body to arrive on the channel.
 
-When the turn ends, the TurnManager publishes a `turn-end` event with the appropriate reason and cleans up internal state. If the turn is cancelled, the abort controller fires before cleanup.
+The sequence:
 
-## pipeStream <a id="pipe-stream"/>
+```text
+1. Client publishes ai-input with event-id=E1 on the channel.
+   Fresh send: no run-id on the input.
+   Continuation: existing run-id stamped on the input from ActiveRun.runId.
+2. Client POSTs InvocationData ({ inputEventId=E1, sessionName }) to the agent.
+3. Agent route receives the POST.
+4. Agent calls session.createRun(invocation, runtime). createRun mints the
+   invocationId and registers the run for cancel routing immediately so
+   early cancels fire.
+5. Agent calls run.start(). The session attaches the channel with the
+   configured rewindWindow and waits for E1 to arrive.
+6. Either:
+   - E1 is already on the channel (rewind) ──► resolves immediately.
+   - E1 arrives live within inputEventLookupTimeoutMs ──► resolves.
+   - inputEventLookupTimeoutMs lapses ──► rejects with InputEventNotFound.
+7. The input event tells the agent which run-id to use: it mints a fresh
+   run-id when the input event omits one, or reuses the run-id stamped on
+   the input event for a continuation.
+8. run.start() resolves, the agent fetches conversation history and pipes
+   the LLM stream. The agent route returns { runId: run.runId,
+   invocationId: run.invocationId } on the HTTP response.
+```
 
-The `pipeStream` function connects a `ReadableStream` (from the LLM) to the encoder. It reads from the stream and writes each chunk through the encoder's `appendEvent` method.
+The buffer that holds pre-`start` events is sized by `inputEventBufferLimit` (default 200 input events). When the buffer is full, the oldest input event is FIFO-evicted; the client whose input was dropped fails its lookup with `InputEventNotFound`.
 
-The key responsibilities are:
+This is the mechanism that lets a serverless agent publish a Run reliably even when the channel publish and the HTTP POST race: the agent waits on the channel until the input event lands, then proceeds. Without it, an agent that attaches after the client published would never see the triggering event.
 
-- **Reading**: pulls chunks from the `ReadableStream` as they become available.
-- **Encoding**: passes each chunk to the encoder, which publishes it to the channel.
-- **Abort handling**: if the turn's abort signal fires, `pipeStream` cancels the reader and calls `encoder.abort()`. This stops the LLM stream and publishes an abort marker to the channel.
-- **Completion**: when the stream ends naturally, `pipeStream` calls `encoder.close()` to finalize the message.
+## Cancel routing <a id="cancel-routing"/>
 
-<Code>
-```javascript
-// Simplified pipeStream flow
-async function pipeStream(stream, encoder, abortSignal) {
-  const reader = stream.getReader()
+Cancel routing connects client cancel signals to the correct agent-side Runs. The flow:
 
-  abortSignal.addEventListener('abort', () => {
-    reader.cancel()
-  })
+1. The client calls `session.cancel(runId)` (when it has the resolved run id from `ActiveRun.runId`) or `activeRun.cancel()` (which keys on the triggering input's `codec-message-id`, the synchronous handle). The session publishes an `ai-cancel` message under `extras.ai.transport`, carrying whichever key the caller used.
+2. The agent session receives the cancel message through its channel subscription.
+3. The agent matches the cancel against its registered Runs. If the cancel arrives before run-start (the client cancelled before the agent minted the run id), the agent buffers it and fires once its input-event lookup resolves the input to the run.
+4. The matched Run's `onCancel` hook (if configured) is invoked. If the hook returns `false`, the cancel is rejected silently and the Run continues.
+5. If the cancel is accepted, the matched Run's `AbortController` fires. `run.abortSignal` flips to aborted; the LLM stream (if it was passed the same signal) stops; `Run.pipe()` resolves with `reason: 'cancelled'`; the encoder closes any in-flight streams with `status: 'cancelled'`.
+6. The agent code, in its `finally` block, calls `run.end('cancelled')`. The agent publishes `ai-run-end` with `run-reason: cancelled`.
 
-  try {
-    while (true) {
-      const { done, value } = await reader.read()
-      if (done) break
-      await encoder.appendEvent(value)
-    }
-    await encoder.close()
-    return 'complete'
-  } catch (error) {
-    if (abortSignal.aborted) {
-      await encoder.abort()
-      return 'cancelled'
-    }
-    throw error
-  }
-}
-```
-</Code>
+Cancel routing is per-Run. A cancel for one Run does not affect other active Runs on the same session; each Run has its own `AbortController`.
 
-The actual implementation includes retry logic for transient errors and coordinates with the encoder's flush-and-recovery mechanism.
+## Pipe stream <a id="pipe-stream"/>
 
-## Cancel routing <a id="cancel-routing"/>
+`Run.pipe(stream, options)` connects a `ReadableStream<TOutput>` (from the LLM) to the encoder. It reads from the stream and writes each chunk through `Encoder.publishOutput`.
 
-Cancel routing connects client cancel signals to the correct server-side turns. The flow is:
+Responsibilities:
 
-1. The client publishes a `cancel` message to the channel with a filter (for example, `{ own: true }` or `{ turnId: 'abc' }`).
-2. The server transport receives the cancel message through its channel subscription.
-3. The transport evaluates the filter against all registered turns. For `{ own: true }`, it matches turns where the owner client ID matches the cancel message's client ID.
-4. Each matched turn's `onCancel` hook is called if one is registered. If the hook returns `false`, that turn is excluded.
-5. For authorized turns, the transport fires their `AbortController`, which triggers `pipeStream` to abort.
+- Reading: pulls chunks from the `ReadableStream` as they become available.
+- Encoding: passes each chunk to the encoder, which writes it to the channel as stream or discrete based on codec rules.
+- Abort handling: if `run.abortSignal` fires, `pipe` cancels the reader and calls `encoder.cancel()`. This stops the LLM stream and publishes a final `updateMessage` with `status: 'cancelled'`.
+- Completion: when the stream ends naturally, `pipe` calls `encoder.close()` to flush any buffered appends and finalise the last stream.
 
-Handler isolation ensures that a cancel for one turn does not affect other active turns. Each turn has its own `AbortController`, so aborting one turn leaves others running.
+`pipe` returns a `StreamResult` with a `reason` field (`'complete'`, `'cancelled'`, or `'error'`) and an optional `error`. The caller passes the `reason` to `Run.end(reason)`. For runs that should pause awaiting input rather than end, use `Run.suspend()` instead of `Run.end(...)`.
 
-## buildTransportHeaders <a id="build-transport-headers"/>
+## Channel continuity <a id="channel-continuity"/>
 
-The `buildTransportHeaders` function constructs the `x-ably-*` headers for outbound messages. It is called by the encoder before every publish operation.
+The session monitors the Ably channel state. If the channel transitions to `FAILED`, `SUSPENDED`, or `DETACHED`, or re-attaches with `resumed: false`, the session emits a `ChannelContinuityLost` error through the session's `on('error', ...)` callback. Active streams on the client are errored with the same `ErrorInfo`; the agent does not see this directly, but its `onError` runtime hook fires for stream failures.
 
-The function takes the current turn state (turn ID, client ID, role, fork metadata) and produces a headers object. The codec can add domain headers, and the encoder merges them using the priority rules described in [codec architecture](/docs/ai-transport/internals/codec-architecture#header-merging).
+A continuity-lost session is still operational for new work after the channel re-attaches; the application decides whether to resume from history or to start a fresh session.
 
-<Aside data-type='note'>
-Stream-related headers (`x-ably-stream`, `x-ably-stream-id`, `x-ably-status`) are set by the codec-layer encoder, not by `buildTransportHeaders`. The transport layer only sets the headers shown below.
-</Aside>
+## Build outbound headers <a id="building-outbound-headers"/>
 
-<Code>
-```javascript
-// Simplified buildTransportHeaders
-function buildTransportHeaders(turn, messageOptions) {
-  return {
-    'x-ably-role': messageOptions.role,
-    'x-ably-turn-id': turn.turnId,
-    'x-ably-msg-id': messageOptions.msgId,
-    ...(turn.clientId && { 'x-ably-turn-client-id': turn.clientId }),
-    ...(messageOptions.parent && { 'x-ably-parent': messageOptions.parent }),
-    ...(messageOptions.forkOf && { 'x-ably-fork-of': messageOptions.forkOf }),
-    ...(messageOptions.amend && { 'x-ably-amend': messageOptions.amend }),
-  }
-}
-```
-</Code>
+The transport layer composes the outbound headers under `extras.ai.transport` for every encoder publish. The encoder reads the per-Run state (`runId`, `clientId`, role defaults) and merges per-event options (`codecMessageId`, `parent`, `forkOf`, `target`). Stream-related headers (`stream`, `stream-id`, `status`) are stamped by the codec-core encoder under `extras.ai.codec`, not by the transport layer. The two tiers never mix; see [Wire protocol](/docs/ai-transport/internals/wire-protocol) for the tier contract.
 
 ## Related pages <a id="related"/>
 
-- [Wire protocol](/docs/ai-transport/internals/wire-protocol) - the headers and message format these components produce and consume.
-- [Codec architecture](/docs/ai-transport/internals/codec-architecture) - the encoder and decoder that `pipeStream` and `StreamRouter` drive.
-- [Cancellation](/docs/ai-transport/features/cancellation) - the user-facing cancel feature.
-- [Token streaming](/docs/ai-transport/features/token-streaming) - the feature that `pipeStream` enables.
+- [Wire protocol](/docs/ai-transport/internals/wire-protocol): the header tiers and event names these components produce and consume.
+- [Codec architecture](/docs/ai-transport/internals/codec-architecture): the encoder and decoder that `pipe` and the stream router drive.
+- [Cancellation](/docs/ai-transport/features/cancellation): the user-facing cancel feature.
+- [Token streaming](/docs/ai-transport/features/token-streaming): the feature that `Run.pipe` enables.
diff --git a/src/pages/docs/ai-transport/internals/wire-protocol.mdx b/src/pages/docs/ai-transport/internals/wire-protocol.mdx
index 6a43677751..9fe71379c3 100644
--- a/src/pages/docs/ai-transport/internals/wire-protocol.mdx
+++ b/src/pages/docs/ai-transport/internals/wire-protocol.mdx
@@ -1,148 +1,180 @@
 ---
 title: "Wire protocol"
-meta_description: "The Ably channel wire format used by AI Transport. Headers, lifecycle events, content messages, and message identity."
-meta_keywords: "wire protocol, AI Transport, transport headers, lifecycle events, message identity, Ably"
-intro: "Wire-format detail for AI Transport over Ably channels. Headers, lifecycle events, content messages, and the turn sequence."
+meta_description: "The Ably channel wire format used by AI Transport. Header tiers, lifecycle events, content event names, and message identity."
+meta_keywords: "wire protocol, AI Transport, extras.ai, transport headers, codec headers, lifecycle events, Ably"
+intro: "Wire-format detail for AI Transport over Ably channels. Header tiers, lifecycle events, content event names, and the Run sequence."
 ---
 
-AI Transport communicates through Ably channel messages. Every message carries headers that describe its role in the conversation: which turn it belongs to, who sent it, what kind of content it carries, and where it fits in the conversation tree. This page describes the wire format at a moderate level of detail.
+AI Transport communicates through Ably channel messages. Every message carries headers under two tiers in the message's `extras.ai` object: `extras.ai.transport` for run identity and routing, and `extras.ai.codec` for stream and status metadata. The tiering isolates the two concerns so the codec layer cannot stamp transport routing headers and the transport layer cannot leak into codec stream state.
 
-A typical turn produces the following sequence on the channel:
+A typical Run produces the following sequence on the channel:
 
-```
-Client publish: turn-start (x-ably-turn-id=T1, x-ably-from=client)
-Client publish: user message (x-ably-msg-id=M1, x-ably-parent=...)
-Server publish: assistant message start (x-ably-msg-id=M2, x-ably-parent=M1)
-Server append:  text delta on M2
-Server append:  text delta on M2
-Server append:  ...
-Server update:  assistant message close (x-ably-msg-id=M2, status=finished)
-Server publish: turn-end (x-ably-turn-id=T1, reason=completed)
-```
+```text
+Client publishes input event (no run-id on a fresh send)
+  name: ai-input
+  extras.ai.transport: { event-id=E1, codec-message-id=M1, role=user, parent=M0 }
+  extras.ai.codec:     { stream=false }
 
-Cancel inserts a cancel message between deltas; abort sets the message status to `aborted` instead of `finished`.
+Agent publishes run-start (run-id and invocation-id minted by createRun)
+  name: ai-run-start
+  extras.ai.transport: { run-id=R1, invocation-id=I1, run-client-id=user-abc, input-client-id=user-abc, input-codec-message-id=M1 }
 
-## Transport headers <a id="transport-headers"/>
+Agent publishes assistant stream create
+  name: ai-output
+  extras.ai.transport: { run-id=R1, invocation-id=I1, codec-message-id=M2, role=assistant, parent=M1, input-codec-message-id=M1 }
+  extras.ai.codec:     { stream=true, stream-id=S1, status=streaming }
 
-Transport headers use the `x-ably-` prefix. They are managed by the SDK and carry the metadata that the transport layer needs to route, order, and reconcile messages.
+Agent appends text deltas to M2
+  channel.appendMessage on the assistant message's serial
+  extras.ai.codec:     { stream-id=S1, status=streaming }
 
-| Header | Description |
-| --- | --- |
-| `x-ably-turn-id` | Identifies the turn this message belongs to. All messages in a turn share the same turn ID. |
-| `x-ably-turn-client-id` | The client ID of the user who initiated the turn. |
-| `x-ably-turn-reason` | The reason a turn ended: `complete`, `cancelled`, or `error`. Present on `x-ably-turn-end` events. |
-| `x-ably-msg-id` | A unique identifier for the message. Used for optimistic update reconciliation and message identity. |
-| `x-ably-role` | The role of the message author: `user`, `assistant`, `system`, or `tool`. |
-| `x-ably-parent` | The message ID of this message's parent in the conversation tree. Establishes the tree structure. |
-| `x-ably-fork-of` | The message ID this message forks from. Present when an edit or regenerate creates a new branch. |
-| `x-ably-stream` | Whether the message is streamed (`true`) or discrete (`false`). |
-| `x-ably-stream-id` | Identifies the stream this message belongs to. All appends for the same streamed message share a stream ID. |
-| `x-ably-status` | The status of a streamed message: `streaming`, `finished`, or `aborted`. |
-| `x-ably-discrete` | Marks a message as a discrete (non-streamed) publish. Present on single-shot messages such as user prompts and tool results. |
-| `x-ably-amend` | Indicates this message amends (replaces) a previous message. Used for edits and regenerations. |
+Agent closes the stream
+  name: ai-output  (channel.appendMessage with status=complete)
+  extras.ai.codec:     { stream-id=S1, status=complete }
+
+Agent publishes run-end
+  name: ai-run-end
+  extras.ai.transport: { run-id=R1, invocation-id=I1, run-reason=complete }
+```
 
-## Domain headers <a id="domain-headers"/>
+A cancel inserts an `ai-cancel` message keyed by the triggering input's `codec-message-id` (which the client owns from send time, before the agent has minted the `run-id`). The agent's per-Run `AbortSignal` fires once the input lookup resolves the input to the run, the stream closes with `status=cancelled`, and the agent publishes `ai-run-end` with `run-reason=cancelled`.
 
-Domain headers use the `x-domain-` prefix. They carry framework-specific metadata that the transport layer passes through without interpreting. A Vercel AI SDK codec might use domain headers to carry tool call IDs, content part indices, or other framework-specific identifiers.
+A continuation (a tool result follow-up, a regenerate, a suspend resume) is different in one wire detail: the client knows the existing `run-id` already, so it stamps it on the continuation input event under `extras.ai.transport.run-id`. The agent reads that header from the input event in its lookup and reuses it as the Run's id; on a fresh send the input event omits `run-id` and the agent mints one in `createRun`.
 
-Domain headers are defined by the codec, not the transport. The transport merges them into the outbound message alongside transport headers.
+## Header tiers <a id="header-tiers"/>
 
-## Lifecycle events <a id="lifecycle-events"/>
+Headers live under `extras.ai.transport` and `extras.ai.codec`. The tier prefix isolates transport-level routing from codec-defined payload metadata.
 
-Lifecycle events signal the start and end of turns. They are published as Ably messages with specific names.
+### Transport headers
 
-| Event | Description |
+Transport headers carry the routing and identity that the transport layer reads. They are stamped under `extras.ai.transport`.
+
+| Header | Description |
+| --- | --- |
+| `run-id` | Run correlation. Minted by the agent inside `session.createRun(invocation)` for a fresh run, and stamped on every event the agent publishes. Continuation client publishes also carry it (the client knows the existing `run-id` from `ActiveRun.runId` and stamps it on the continuation input event); the agent reads it from the input event's wire headers to reuse the existing Run rather than minting a fresh one. Absent on the first `ai-input` of a fresh send. |
+| `invocation-id` | Per-HTTP-request identifier. Minted by the agent inside `session.createRun(invocation)` (one per HTTP request) and stamped on every event the agent publishes for that invocation (lifecycle + outputs). Not present on client `ai-input` events; the application returns it on the HTTP response so the caller can observe it. |
+| `event-id` | Per-event identifier on client publishes. The invocation body carries the triggering `event-id` so the agent's `Run.start()` knows which event to wait for. Distinct from `codec-message-id` so edits and retries that reuse the same `codec-message-id` still carry a fresh per-send identity. |
+| `codec-message-id` | Message identity in the conversation tree. Used for branch anchoring (edit forks at the user's `codec-message-id`, regenerate forks at the assistant's), for optimistic reconciliation, and for stream append targeting. |
+| `run-client-id` | The Ably `clientId` of the client that started the Run. Set on agent-side stream messages. |
+| `input-client-id` | The Ably `clientId` of the input event that drove the current invocation. May differ from `run-client-id` on continuation invocations driven by a non-owner (for example, a tool result from a different device). |
+| `role` | Message role: `user`, `assistant`, `system`, or `tool`. |
+| `parent` | The `codec-message-id` of the immediately preceding message in this branch. |
+| `fork-of` | The `codec-message-id` this message replaces. Present on edits. |
+| `msg-regenerate` | The `codec-message-id` of the assistant message this Run regenerates. Stamped on the regenerate input and echoed on `ai-run-start`. |
+| `run-reason` | The reason a Run ended. Present on `ai-run-end`. One of `complete`, `cancelled`, `error`. A suspended Run uses the `ai-run-suspend` event instead and is not terminal. |
+| `error-code` | Numeric error code on `ai-run-end` with `run-reason: error`. |
+| `error-message` | Human-readable error message on `ai-run-end` with `run-reason: error`. |
+
+### Codec headers
+
+Codec headers carry the stream lifecycle the codec encoder and decoder read. They are stamped under `extras.ai.codec`.
+
+| Header | Description |
 | --- | --- |
-| `x-ably-turn-start` | A new turn has begun. Published before any content messages for the turn. |
-| `x-ably-turn-end` | The turn is complete. Includes `x-ably-turn-reason` to indicate how it ended. |
-| `x-ably-cancel` | A cancel request from a client. Includes a filter specifying which turns to cancel. |
-| `x-ably-abort` | The turn was forcefully terminated. May include partial content from an `onAbort` hook. |
-| `x-ably-error` | An error occurred during the turn. The turn ends with reason `error`. |
+| `stream` | `'true'` if the message uses streaming (appends), `'false'` for a discrete publish. |
+| `stream-id` | Stream identity. Set on every message that participates in a stream so the decoder can correlate appends. |
+| `status` | Lifecycle status of a streamed message. One of `streaming`, `complete`, `cancelled`. Set only when `stream` is `'true'`. |
+| `discrete` | Marks a message as a discrete part. Set by `publishDiscreteBatch`; not set on lifecycle events from `publishDiscrete`. |
 
-A normal turn follows the sequence: `x-ably-turn-start`, content messages, `x-ably-turn-end` with reason `complete`. A cancelled turn follows: `x-ably-turn-start`, content messages, `x-ably-turn-end` with reason `cancelled`.
+The following header constants are exported from `@ably/ai-transport` as `HEADER_*`:
+
+| Constant | Value |
+| --- | --- |
+| `HEADER_RUN_ID` | `'run-id'` |
+| `HEADER_CODEC_MESSAGE_ID` | `'codec-message-id'` |
+| `HEADER_RUN_CLIENT_ID` | `'run-client-id'` |
+| `HEADER_INPUT_CLIENT_ID` | `'input-client-id'` |
+| `HEADER_ROLE` | `'role'` |
+| `HEADER_PARENT` | `'parent'` |
+| `HEADER_FORK_OF` | `'fork-of'` |
+| `HEADER_MSG_REGENERATE` | `'msg-regenerate'` |
+| `HEADER_RUN_REASON` | `'run-reason'` |
+| `HEADER_ERROR_CODE` | `'error-code'` |
+| `HEADER_ERROR_MESSAGE` | `'error-message'` |
+| `HEADER_STREAM` | `'stream'` |
+| `HEADER_STREAM_ID` | `'stream-id'` |
+| `HEADER_STATUS` | `'status'` |
+
+The remaining wire headers (`invocation-id`, `event-id`, `input-codec-message-id`, `discrete`) are SDK internals and not part of the exported constant surface. The SDK reads and writes them through the `getTransportHeaders` and `getCodecHeaders` utilities.
+
+## Event names <a id="event-names"/>
+
+AI Transport uses seven Ably message names. The decoder dispatches on the Ably message `name` (and the `stream` header to distinguish discrete from streamed content), not on a separate codec-type header.
+
+| Event | Direction | Description |
+| --- | --- | --- |
+| `ai-input` | Client | Every client-published codec event (user-message parts, tool-approval responses, regenerate signals, tool results, edits). |
+| `ai-output` | Agent | Every agent-published codec event (text deltas, reasoning, tool calls, file or source parts, data chunks). |
+| `ai-run-start` | Agent | Run lifecycle. The agent publishes this once, for the first start of a Run, before any `ai-output`. |
+| `ai-run-suspend` | Agent | Run lifecycle. The agent pauses the Run pending external input (a tool approval, a human-in-the-loop response). The Run is not terminal; a continuation Invocation resumes it. |
+| `ai-run-resume` | Agent | Run lifecycle. The agent publishes this when a continuation Invocation re-activates a Run (tool-result follow-up, suspended-Run resume), instead of a second `ai-run-start`. The agent detects the continuation by reading the existing `run-id` off the triggering input event's wire headers; a fresh input event omits `run-id` and produces `ai-run-start`. |
+| `ai-run-end` | Agent | Run lifecycle. Closes the Run terminally with one of `complete`, `cancelled`, `error`. |
+| `ai-cancel` | Client | Cancel intent, targeting a specific `run-id`. The agent matches against its registered Runs and fires the matching `AbortSignal`. |
 
 ## Content messages <a id="content-messages"/>
 
-Content messages carry the actual conversation data: user prompts, assistant responses, tool calls, and tool results. They come in two forms.
+Content rides `ai-input` or `ai-output` depending on the publisher. The codec layer is responsible for the payload; the wire layer cares only about whether the message is discrete or streamed.
 
-### Discrete messages <a id="discrete"/>
+### Discrete messages
 
-A discrete message is published as a single Ably message. The entire content is in one publish operation. User messages are typically discrete - the full text is known at publish time.
+A discrete message is published as a single Ably message. The entire content is in one `channel.publish` call. User messages are typically discrete.
 
 <Code>
 ```javascript
-// A discrete user message
-channel.publish('message.create', {
+channel.publish('ai-input', {
   data: { role: 'user', content: 'What is the weather?' },
   extras: {
-    headers: {
-      'x-ably-msg-id': 'msg_001',
-      'x-ably-role': 'user',
-      'x-ably-turn-id': 'turn_001',
-      'x-ably-stream': 'false',
-    }
-  }
-})
+    ai: {
+      transport: {
+        // No run-id on a fresh send (the agent mints it). Continuations stamp the
+        // existing run-id here so the agent reuses it instead of minting fresh.
+        'event-id': 'E1',
+        'codec-message-id': 'M1',
+        role: 'user',
+      },
+      codec: { stream: 'false' },
+    },
+  },
+});
 ```
 </Code>
 
-### Streamed messages <a id="streamed"/>
+### Streamed messages
 
-A streamed message is published incrementally as tokens arrive from the LLM. It uses three operations over its lifecycle:
+A streamed message is published incrementally. It uses three Ably operations:
 
-1. **Create** (`message.create`): starts the streamed message. Sets `x-ably-stream` to `true` and `x-ably-status` to `streaming`.
-2. **Append** (`message.append`): appends a token or chunk to the message. Published for each token in the stream.
-3. **Close** (`message.update`): finalizes the message with a terminal status (`finished` or `aborted`).
+1. `channel.publish('ai-output', ...)` with `stream: 'true'` and `status: 'streaming'`. The publish returns a serial that the encoder captures.
+2. `channel.appendMessage(...)` for each token, using the captured serial. The append carries the codec payload and the `stream-id`.
+3. A final `channel.appendMessage(...)` with `status: 'complete'` (or `'cancelled'`) closes the stream. `channel.updateMessage(...)` is only used as a recovery path when an intermediate append failed and the encoder needs to flush the accumulated payload.
 
-<Code>
-```javascript
-// 1. Create the streamed message
-channel.publish('message.create', {
-  data: { role: 'assistant', content: '' },
-  extras: {
-    headers: {
-      'x-ably-msg-id': 'msg_002',
-      'x-ably-stream': 'true',
-      'x-ably-stream-id': 'stream_001',
-      'x-ably-status': 'streaming',
-    }
-  }
-})
-
-// 2. Append tokens
-channel.appendMessage({ name: 'msg_002', data: 'The weather' })
-channel.appendMessage({ name: 'msg_002', data: ' is sunny.' })
-
-// 3. Close the stream
-channel.updateMessage({
-  name: 'msg_002',
-  extras: {
-    headers: { 'x-ably-status': 'finished' }
-  }
-})
-```
-</Code>
-
-Subscribers accumulate appends locally to build the complete message. If a subscriber joins mid-stream, the Ably message on the channel already contains all previous appends - only future appends arrive as live events.
+A subscriber that joins mid-stream sees the latest accumulated state of the message on attach (Ably stores the rollup) and then live appends after that. The decoder treats the on-attach state as the current full state and accumulates from there.
 
 ## Message identity <a id="message-identity"/>
 
-The `x-ably-msg-id` header is the primary identifier for a message in the conversation tree. It is distinct from the Ably message serial, which is assigned by the channel.
+The `codec-message-id` header is the primary identifier for a message in the conversation tree. It is distinct from the Ably channel serial: the serial is assigned by Ably and totally orders messages on the channel; the `codec-message-id` is assigned by the publisher and identifies the message across edits, retries, and optimistic reconciliation.
+
+Edit and regenerate forks are message-anchored: the new Run's `fork-of` (for an edit) or `msg-regenerate` (for a regenerate) points at the `codec-message-id` being forked, not at the previous Run.
+
+## Input-event lookup <a id="input-event-lookup"/>
+
+When a client sends, the SDK mints two identifiers on the publishing side:
 
-### Generation <a id="id-generation"/>
+- `inputEventId`: one per published input event. The last event in the send becomes the trigger the agent waits on.
+- `codecMessageId`: identity for the new message in the conversation tree. Surfaced on the returned `ActiveRun` as `inputCodecMessageId` so the client can route the agent's outputs back to the input it owned at send time.
 
-Message IDs are generated by the sender. When the client sends a user message optimistically, the client generates the ID. When the server publishes messages from the LLM, the server generates the ID. The codec may generate IDs for streamed messages when the stream starts.
+For continuations only, the client also stamps the existing `run-id` on the input event's wire headers (the client knows it from the previous `ActiveRun.runId`). Fresh sends omit `run-id` and leave the agent to mint it.
 
-### Stamping <a id="stamping"/>
+The SDK does not POST to the agent endpoint itself; the developer (or the bundled [Vercel `ChatTransport`](/docs/ai-transport/api/javascript/vercel/chat-transport)) calls `activeRun.toInvocation().toJSON()` to obtain an [`InvocationData`](/docs/ai-transport/concepts/invocations) body (`{ inputEventId, sessionName }`) and POSTs it to the agent.
 
-The server transport stamps the `x-ably-msg-id` header onto outbound messages. If the codec does not provide an ID, the transport generates one. This ensures every message on the channel has a consistent, unique identifier.
+On the agent side, `session.createRun(invocation)` mints the `invocationId` (one per HTTP request) and either mints a fresh `runId` (no `run-id` on the input event) or reads the existing `runId` off the triggering input event's wire headers (continuation). Both are stamped on every event the agent publishes for this invocation. `Run.start()` attaches the channel with rewind and waits for the trigger `event-id` carried in the invocation body to arrive (live or via rewind). The rewind window is configured by `rewindWindow` on `AgentSessionOptions`; the lookup timeout is `inputEventLookupTimeoutMs`. If the lookup lapses, `Run.start()` rejects with [`InputEventNotFound`](/docs/ai-transport/api/errors).
 
-### Reconciliation <a id="reconciliation"/>
+The agent's outputs carry `input-codec-message-id` (the `codec-message-id` of the triggering input) under `extras.ai.transport`. The client uses this to correlate outputs back to the input it owned at send time, so `ActiveRun.runId` resolves once `ai-run-start` lands. The application returns `run.runId` and `run.invocationId` on the HTTP response so the caller can observe the agent-minted ids directly.
 
-When a client inserts a message optimistically, it assigns an `x-ably-msg-id`. The server publishes the same message with the same ID. When the client receives the published message through its subscription, it matches IDs and promotes the optimistic message to a confirmed one. The message keeps its position in the tree, but gains a real Ably serial for ordering.
+This is the mechanism that lets a serverless agent publish a Run reliably even when the channel publish and the HTTP POST race: the agent waits on the channel until the input event lands, then proceeds.
 
 ## Related pages <a id="related"/>
 
-- [Codec architecture](/docs/ai-transport/internals/codec-architecture) - how the codec uses the wire protocol to encode and decode messages.
-- [Conversation tree](/docs/ai-transport/internals/conversation-tree) - how `x-ably-parent` and `x-ably-fork-of` build the tree structure.
-- [Optimistic updates](/docs/ai-transport/features/optimistic-updates) - reconciliation from the user's perspective.
+- [Codec architecture](/docs/ai-transport/internals/codec-architecture): how the codec uses the wire protocol to encode and decode messages.
+- [Conversation tree](/docs/ai-transport/internals/conversation-tree): how `parent`, `fork-of`, and `msg-regenerate` build the tree.
+- [Transport patterns](/docs/ai-transport/internals/transport-patterns): the stream router, input-event lookup, and cancel routing.
+- [Errors](/docs/ai-transport/api/errors): error codes the wire layer surfaces.
diff --git a/src/pages/docs/ai-transport/troubleshooting.mdx b/src/pages/docs/ai-transport/troubleshooting.mdx
index 9ad507fa8a..afb861f796 100644
--- a/src/pages/docs/ai-transport/troubleshooting.mdx
+++ b/src/pages/docs/ai-transport/troubleshooting.mdx
@@ -20,15 +20,15 @@ Entries are ordered roughly by how often they cause support tickets, with the mo
 
 **Fix:**
 
-- Enable the *Message annotations, updates, deletes, and appends* rule on the namespace. See [enable message updates and deletes](/docs/ai-transport/concepts/authentication#enable-updates-deletes) for the dashboard, Control API, and CLI steps.
+- Enable the *Message annotations, updates, deletes, and appends* rule on the namespace. See [Enable channel rules](/docs/ai-transport/getting-started/channel-rules) for the dashboard, Control API, and CLI steps.
 - Note that enabling this rule causes messages to be [persisted](/docs/storage-history/storage#all-message-persistence) regardless of whether persistence is enabled on the namespace.
 
 ## Capability or token scope mismatch <a id="capability-mismatch"/>
 
 **Symptom:** The token authenticates, but specific operations fail. There are two common shapes:
 
-- **Channel pattern miss:** the channel attach fails, or a publish is rejected. The capability covers `conversations:*` but your app uses `chat:abc`.
-- **Missing operation:** the connection works but a specific operation does not. Clients cannot cancel generation (missing `publish`). Late joiners or reconnects show only live messages and not the prior conversation (missing `history`). Agent presence never updates (missing `presence`).
+- Channel pattern miss: the channel attach fails, or a publish is rejected. The capability covers `conversations:*` but your app uses `chat:abc`.
+- Missing operation: the connection works but a specific operation does not. Clients cannot cancel generation (missing `publish`). Late joiners or reconnects show only live messages and not the prior conversation (missing `history`). Agent presence never updates (missing `presence`).
 
 **Confirm:**
 
@@ -59,20 +59,20 @@ In both cases the cause is the same: the channel namespace is not configured to
 - Enable persistence on the channel namespace and set a retention period that covers your expected scroll-back window. See [history and replay](/docs/ai-transport/features/history#faq-retention) for the persistence options.
 - For conversations that need to be retained for longer than the channel allows, persist completed turns to your own store and hydrate from it on session load. See [reconnection and recovery](/docs/ai-transport/features/reconnection-and-recovery#loading-history) for how reconnect interacts with history.
 
-## Turn never ends <a id="turn-never-ends"/>
+## Run never ends <a id="turn-never-ends"/>
 
-**Symptom:** The streamed message renders with the streaming status forever. `useActiveTurns` shows the turn as active long after the model finished generating.
+**Symptom:** The streamed message renders with the streaming status forever. `session.view.runs()` shows the Run with `status: 'active'` long after the model finished generating.
 
 **Confirm:**
 
-- Check the server logs around the affected turn. Did `turn.end(reason)` execute? If the route handler threw between `streamResponse` and `end`, the turn never closes.
-- Inspect the channel in the Ably dashboard. The turn-end lifecycle message should appear after the streamed message's close event. If it is missing, the encoder did not publish it.
+- Check the server logs around the affected Run. Did `run.end(reason)` execute? If the route handler threw between `run.pipe` and `run.end`, the Run never closes.
+- Inspect the channel in the Ably dashboard. The `ai-run-end` lifecycle message should appear after the streamed message's close event. If it is missing, the encoder did not publish it.
 
 **Fix:**
 
-- Wrap streaming work in `try`/`finally` and always call `turn.end()` in the `finally` block. A turn that errored should end with reason `'error'`.
-- If you use Next.js `after()`, confirm the callback runs to completion. An unhandled promise rejection inside `after()` aborts the rest of the handler, including `turn.end()`.
-- See [turns](/docs/ai-transport/concepts/turns#lifecycle) for the full lifecycle contract.
+- Wrap streaming work in `try`/`finally` and always call `run.end()` in the `finally` block. A Run that errored should end with reason `'error'`.
+- If you use Next.js `after()`, confirm the callback runs to completion. An unhandled promise rejection inside `after()` aborts the rest of the handler, including `run.end()`.
+- See [Runs](/docs/ai-transport/concepts/runs#lifecycle) for the full lifecycle contract.
 
 ## Cancel doesn't stop the agent <a id="cancel-doesnt-stop"/>
 
@@ -80,14 +80,14 @@ In both cases the cause is the same: the channel namespace is not configured to
 
 **Confirm:**
 
-- Check the server handler: is `turn.abortSignal` passed to the LLM call?
-- For long-running tools, check whether the tool implementation reads `turn.abortSignal.aborted` and exits when the signal fires.
+- Check the server handler: is `run.abortSignal` passed to the LLM call?
+- For long-running tools, check whether the tool implementation reads `run.abortSignal.aborted` and exits when the signal fires.
 - If `onCancel` is configured, check that it returns `true` for the cancel request. A hook that returns `false` rejects the cancel silently.
 
 **Fix:**
 
-- Pass `turn.abortSignal` to every LLM call, for example `streamText({ abortSignal: turn.abortSignal, ... })`.
-- In server-executed tools, wire `turn.abortSignal` into long-running operations so they exit promptly when the signal fires.
+- Pass `run.abortSignal` to every LLM call, for example `streamText({ abortSignal: run.abortSignal, ... })`.
+- In server-executed tools, wire `run.abortSignal` into long-running operations so they exit promptly when the signal fires.
 - See [cancellation](/docs/ai-transport/features/cancellation#abort-signal) for the full flow.
 
 ## Duplicate or unexpected turns <a id="duplicate-turns"/>
@@ -99,13 +99,13 @@ In both cases the cause is the same: the channel namespace is not configured to
 
 **Confirm:**
 
-- Inspect the channel for two turn-start events with different `turnId` values for the same user message.
+- Inspect the channel for two `ai-run-start` events with different `runId` values for the same user message.
 - Check whether your send path lives inside a `useEffect`. Imperative event handlers (`onClick`, `onSubmit`) are safer.
 
 **Fix:**
 
-- Guard `send()` so it fires once per user action. Avoid placing it inside an effect without a dependency that prevents re-firing.
-- Before editing or regenerating, cancel the in-flight turn explicitly. AI Transport does not auto-cancel an active turn on edit; see [conversation branching](/docs/ai-transport/features/branching#edit) for the recommended pattern.
+- Guard `view.send()` so it fires once per user action. Avoid placing it inside an effect without a dependency that prevents re-firing.
+- Before editing or regenerating, cancel the in-flight Run explicitly. AI Transport does not auto-cancel an active Run on edit; see [conversation branching](/docs/ai-transport/features/branching#edit) for the recommended pattern.
 
 ## Message too large to publish <a id="message-too-large"/>
 
@@ -139,7 +139,7 @@ In both cases the cause is the same: the channel namespace is not configured to
 
 **Symptom:** Two devices on the same conversation show different responses to the same prompt. Edit history navigation diverges between them.
 
-This is intentional. Branch selection is a per-view, per-device choice — each device navigates the conversation tree independently so a user reviewing alternates on one device does not disrupt another device displaying the same conversation.
+This is intentional. Branch selection is a per-view, per-device choice. Each device navigates the conversation tree independently, so a user reviewing alternates on one device does not disrupt another device displaying the same conversation.
 
 **Fix:**
 
@@ -163,7 +163,7 @@ This is intentional. Branch selection is a per-view, per-device choice — each
 
 ## Agent process crashes mid-stream <a id="agent-crash"/>
 
-**Symptom:** A streamed message stops part-way through and stays in `streaming` status forever. No more tokens arrive and no turn-end event ever fires. From the client's point of view this is indistinguishable from [Turn never ends](#turn-never-ends) — both leave the run in `active` state — but the root cause here is the process dying rather than the handler skipping `turn.end()`.
+**Symptom:** A streamed message stops part-way through and stays in `streaming` status forever. No more tokens arrive and no run-end event ever fires. From the client's point of view this is indistinguishable from [Run never ends](#turn-never-ends): both leave the Run in `active` state. The root cause here is the process dying rather than the handler skipping `run.end()`.
 
 **Confirm:**
 
@@ -190,7 +190,7 @@ This is intentional. Branch selection is a per-view, per-device choice — each
 
 ## When to escalate <a id="escalate"/>
 
-If you have worked through the entries on this page and the symptom does not match — or the fix did not work — capture:
+If you have worked through the entries on this page and the symptom does not match, or the fix did not work, capture:
 
 - The channel name.
 - The date and time of the affected operation.
diff --git a/src/pages/docs/ai-transport/why/http-streaming-and-ai.mdx b/src/pages/docs/ai-transport/why/http-streaming-and-ai.mdx
index f68cc7f262..a70b8e5b25 100644
--- a/src/pages/docs/ai-transport/why/http-streaming-and-ai.mdx
+++ b/src/pages/docs/ai-transport/why/http-streaming-and-ai.mdx
@@ -1,41 +1,116 @@
 ---
 title: "HTTP streaming and AI"
-meta_description: "The four production problems with direct HTTP streaming for AI: streams fail on disconnect, sessions do not span devices, clients cannot reach the agent, multi-agent is complex."
+meta_description: "Why direct HTTP streaming breaks down for production AI: streams fail on disconnect, sessions do not span devices, clients cannot reach the agent, multi-agent routing is complex, and there are no agent health signals."
 meta_keywords: "HTTP streaming, SSE limitations, AI agents, durable sessions, server-sent events, AI production"
-intro: "Direct HTTP streaming is fine for one-off interactions and breaks down everywhere else. These are the four limitations that show up once an AI app is in production."
+intro: "Direct HTTP streaming is fine for one-off interactions and breaks down everywhere else. These are the limitations that show up once an AI app is in production, and what teams end up building on top."
 ---
 
-Most AI frameworks support a simple client-driven interaction: the client makes an HTTP request, an agent handles it, and the response streams back to the client over Server-Sent Events or a similar HTTP stream. The pattern is simple, surprisingly effective for one-shot interactions, and every framework supports it. The simplicity of the pattern is also the source of its limitations.
+Most AI frameworks default to a single pattern: the client makes an HTTP request, the agent handles it, and the response streams back over Server-Sent Events or a similar HTTP stream. It is simple, every framework supports it, and it works for one-shot interactions. The simplicity is also the source of every limitation below.
 
-The limitations below arise from coupling the client-to-agent interaction to the transport that carries it. The connection, the request, and the streamed response are all the same lifetime: they exist for one interaction, between one client and one agent. Anything that requires the interaction to outlive the connection (or be visible to anything other than that one client) requires building new infrastructure on top.
+The limitations all share one cause: the client-to-agent interaction is coupled to the transport that carries it. The connection, the request, and the streamed response have the same lifetime. Anything that needs the interaction to outlive the connection, or to be visible to anything beyond that one client, requires building new infrastructure on top.
 
-## Streams fail on disconnection <a id="handle-disconnection"/>
+## The default pattern <a id="the-default-pattern"/>
 
-The operation of a response stream is tied to the health of the underlying connection. When the connection drops, the response stream fails.
+A typical Vercel AI SDK route returns the model's stream as the HTTP response:
 
-This happens routinely. A phone switches from Wi-Fi to cellular. A user refreshes the page. A laptop lid closes mid-response. The LLM continues to generate tokens, and there is nowhere to deliver them.
+<Code>
+```javascript
+import { streamText } from 'ai';
+import { anthropic } from '@ai-sdk/anthropic';
 
-SSE is the default streaming transport for most AI frameworks. The SSE protocol does include a mechanism for a reconnecting client to specify a position in the stream to resume from. In practice it is rarely supported, because supporting it adds significant backend complexity. To resume an SSE stream you assign sequence numbers to token events for ordering, buffer those events in an external store, and add a new HTTP endpoint to handle resume requests. That is a substantial departure from a stateless request handler. Even with the work done, resume only covers reconnection of an existing client; it does not cover continuity after a page refresh, because SSE has no built-in concept of session identity. Building that is yet another layer on top.
+export async function POST(req) {
+  const { messages } = await req.json();
 
-## Sessions do not span devices <a id="across-device"/>
+  const result = streamText({
+    model: anthropic('claude-sonnet-4-20250514'),
+    messages,
+  });
 
-With HTTP streaming, the connection is exclusive to the requesting client and the agent that handled it. A second tab or a phone has no way into that stream. It only exists for the client that initiated the request.
+  return result.toUIMessageStreamResponse();
+}
+```
+</Code>
 
-In reality, users move between surfaces constantly. A second browser tab. The mobile app. Picking the conversation up later from a different device. Without shared access to the session, each surface is isolated. There is no way for a new client to see the in-progress stream. And sharing the conversation history, or its current state.
+The client opens a fetch with `Accept: text/event-stream` (or equivalent), reads tokens as they arrive, and renders them. The conversation exists in two places: the HTTP request body (what the client sent) and the HTTP response stream (what the model produces). When the response ends, the interaction ends.
 
-## Clients cannot reach the agent <a id="clients-cant-reach"/>
+## Streams fail on disconnect <a id="streams-fail-on-disconnect"/>
 
-An SSE request initiated by the client is one-way: server to client. The client has no way to send a signal to the agent through the same connection once the initial request has been made. The only options the client has are to read the stream to completion or to cancel it by closing the connection.
+The lifetime of the response is the lifetime of the connection. When the connection drops, the response is gone. This happens routinely: a phone switches from Wi-Fi to cellular, a user refreshes the page, a laptop lid closes mid-response. The LLM keeps generating tokens; there is nowhere to deliver them.
 
-Using cancellation as the sole upstream signal creates a fundamental conflict. Consider a stop button that cancels an in-progress stream. The implementation has to choose between two interpretations of a closed connection: either it is a cancel (in which case the LLM should stop), or it is a disconnect (in which case the LLM should keep going so the stream can resume). There is no way to disambiguate.
+![Diagram showing an SSE token stream working, then breaking on connection drop, then the bolt-on infrastructure teams assemble to recover](../../../../images/content/diagrams/ait-sse-stream-failures.png)
+
+SSE includes a `Last-Event-ID` mechanism for a reconnecting client to specify a resume position. In practice almost no AI deployment supports it, because supporting it requires substantial backend work:
+
+- Assign monotonic IDs to every token event.
+- Buffer events in an external store (Redis, Kafka, or similar) keyed by client and conversation.
+- Add an HTTP endpoint that accepts a `Last-Event-ID`, looks up the buffer, and resumes the stream from that position.
+- Decide how long to retain buffered events and how to evict stale entries.
+
+That is a substantial departure from a stateless request handler. Even with the work done, resume only covers reconnection of an existing client. It does not cover continuity after a page refresh, because SSE has no built-in concept of session identity. Building session continuity is yet another layer on top.
+
+## Sessions do not span devices <a id="sessions-do-not-span-devices"/>
+
+With HTTP streaming, the connection is exclusive to the requesting client and the agent that handled it. A second tab or a phone has no way into that stream. It exists only for the client that initiated the request.
+
+In production, users move between surfaces constantly: a second browser tab, the mobile app, picking the conversation up later from a different device. Without shared access to the session, each surface is isolated. There is no way for a new client to see the in-progress stream or even the current state of the conversation.
+
+Building this on top of HTTP streaming requires:
+
+- A server-side session store (database or Redis) that buffers conversation state.
+- A reconcile path on every device join that loads the buffered state and subscribes to live updates.
+- A separate push channel (WebSocket, server-sent events, polling) so the second device sees new tokens.
+
+That is two transports running in parallel: HTTP for one client, push for everyone else. The complexity scales with how many surfaces the session needs to reach.
+
+## Clients cannot reach the agent <a id="clients-cannot-reach-the-agent"/>
+
+An SSE request from the client to the agent is one-way: server to client. The client has no way to send a signal to the agent through the same connection once the initial request has been made. The only upstream action the client has is to close the connection.
+
+Using connection-close as the sole upstream signal creates a fundamental conflict. Consider a Stop button. The implementation has to choose between two interpretations of a closed connection: either it is a cancel (the LLM should stop) or it is a disconnect (the LLM should keep going so the stream can resume). There is no way to disambiguate.
 
 Even with a bidirectional transport like WebSocket, the connection is still an exclusive pipe between one client and one agent. Other devices have no upstream channel, so they cannot interrupt or steer from a second device.
 
-## Multi-agent architectures are complex <a id="multi-agent"/>
+Teams that need bidirectional control build a separate signalling channel: a WebSocket dedicated to control messages, or a queue (Kafka, SQS, Redis pub/sub) the client publishes to and the agent polls. That doubles the operational surface: two transports, two reconnect models, two delivery guarantees to reconcile.
+
+## Multi-agent architectures are complex <a id="multi-agent-architectures-are-complex"/>
+
+In multi-agent systems, an orchestrator handles the client's connection and delegates work to specialised sub-agents. When the client-to-orchestrator connection is exclusive and point-to-point, every sub-agent interaction has to be proxied by the orchestrator. If users need to see intermediate progress from sub-agents, every update is mediated through the orchestrator.
+
+This creates two problems. First, the orchestrator becomes a coupling point: every sub-agent change requires orchestrator changes. Second, observability is mediated: the client cannot directly see sub-agent activity, so dashboards and audit trails have to be reconstructed server-side.
+
+A shared session changes this. Each sub-agent publishes to the same session. The client (and any observer) subscribes once and sees every agent's output as it happens. The orchestrator coordinates work without serialising the output stream.
+
+## No agent health signals <a id="no-agent-health-signals"/>
+
+HTTP streaming does not tell you whether the agent is still working. A stream that pauses for thirty seconds might be a long tool call, might be a model warming up, or might be a crashed process. The client has no way to distinguish.
+
+Teams that need to render agent health build polling layers: a `/status?conversation=...` endpoint that the client hits every few seconds, returning the agent's current state. The endpoint reads from a database the agent updates on every state transition. The polling cadence is a trade-off: too fast and you double your request volume, too slow and the UI lags behind real state by seconds.
+
+A presence-aware transport publishes the agent's state changes to the session. The client sees `agent: thinking`, `agent: streaming`, `agent: idle` as live events, not polled snapshots.
+
+## What you'd have to build <a id="what-youd-build"/>
+
+Teams that ship production AI on direct HTTP streaming end up building the same stack of supporting infrastructure repeatedly:
+
+- Redis (or equivalent) for event buffering and stream resume.
+- A database for conversation persistence and multi-device session state.
+- A queue or WebSocket for bidirectional signalling (cancel, approval, interrupt).
+- A status endpoint and polling client for agent health.
+- A reconciliation layer to merge the persisted state and the live stream when a new client joins.
+- An orchestrator that mediates between the client and sub-agents, with its own visibility model.
+
+All of this infrastructure has nothing to do with the AI product. It is the transport layer being reinvented around the limitations of HTTP streaming.
+
+## The durable session alternative <a id="the-durable-session-alternative"/>
+
+A durable session replaces the ephemeral HTTP stream with a persistent, shared medium that any client or agent connects to. The properties the infrastructure above tries to assemble (persistence, ordering, multi-subscriber fan-out, bidirectional publishing, presence) are properties the session already has.
+
+AI Transport implements durable sessions on Ably channels. See [Why AI Transport](/docs/ai-transport/why) for the positive case, [Sessions](/docs/ai-transport/concepts/sessions) for the model, and [Get started with Vercel AI SDK](/docs/ai-transport/getting-started/vercel-ai-sdk) to build something on top of it.
 
-In multi-agent systems, an orchestrator handles the client's connection and delegates work to specialised sub-agents. When the connection between the client and the orchestrator is exclusive and point-to-point, every interaction with a sub-agent has to be proxied by the orchestrator. If users need to see intermediate progress or responses from sub-agents, every update is mediated by the orchestrator, adding complexity and coupling.
+![Diagram showing how AI Transport concepts compose around the session, with connections attaching from outside and the conversation tree, Runs, Invocations, codecs, authentication, and infrastructure relating to it](../../../../images/content/diagrams/ait-concepts-overview.png)
 
 ## Read next <a id="next"/>
 
 - [Why AI Transport](/docs/ai-transport/why): how a durable session layer solves each of these problems.
 - [Sessions](/docs/ai-transport/concepts/sessions): the persistent, shared conversation state that replaces the ephemeral connection.
+- [Get started with Vercel AI SDK](/docs/ai-transport/getting-started/vercel-ai-sdk): the practical adoption path.
diff --git a/src/pages/docs/ai-transport/why/index.mdx b/src/pages/docs/ai-transport/why/index.mdx
index 821bbb3a85..cfdc495ac9 100644
--- a/src/pages/docs/ai-transport/why/index.mdx
+++ b/src/pages/docs/ai-transport/why/index.mdx
@@ -9,51 +9,96 @@ Most AI frameworks connect a client to an agent over an HTTP request and streame
 
 Streams die with the connection. Sessions cannot span devices. Clients have no mechanism to re-contact the agent once the original request is in flight. Each of these is a real production problem; together they bound the quality of AI experiences you build on direct HTTP streaming. See [HTTP streaming and AI](/docs/ai-transport/why/http-streaming-and-ai) for the detail.
 
-## A durable session changes the model <a id="durable-sessions"/>
+## What breaks without it <a id="what-breaks-without-it"/>
 
-These problems share a root cause. The transport is coupled to the interaction. The connection, the request, and the streamed response are ephemeral: they exist for one interaction, for one client and one agent. Once the HTTP connection is lost, so is the interaction between client and agent.
+The root cause is tight coupling. The client and the agent are connected by a single HTTP request and response, and both sides are locked to that connection for the lifetime of the interaction. Five consequences follow:
 
-The shape that engineering teams are adopting is the durable session: a shared, persistent medium that any client or agent connects to, instead of a single HTTP request between one client and one agent.
+- Streams cannot resume: when the connection drops (network switch, page refresh, laptop lid closes), the response is gone. The agent keeps generating tokens; there is nowhere to deliver them.
+- Sessions do not span devices: the stream exists only for the client that opened it. A second tab or a phone has no way in.
+- No way back to the agent: HTTP streams are server-to-client. The only upstream signal a client has is to close the connection, which is indistinguishable from a disconnect.
+- Agents cannot recover from their own restarts: a serverless agent that restarts mid-stream loses its outbound stream. The client sees a dead response.
+- No stateful capabilities: presence, shared mutable state, multi-participant observation: none of these exist over a one-shot HTTP request.
 
-A durable session provides three capabilities that direct HTTP streaming does not:
+See [HTTP streaming and AI](/docs/ai-transport/why/http-streaming-and-ai) for each consequence in technical detail.
 
-1. Resilient delivery. Streams survive connection drops, device switches, page refreshes, and process restarts. The client resumes from a known position. The agent continues publishing regardless of client connectivity. No events are lost and no events are duplicated.
-2. Continuity across surfaces. The session follows the user, not the connection. Open a second tab, switch to a phone, come back hours later. Every surface sees the same session state. Any client with the session identifier attaches and hydrates the same conversation state.
-3. Live control. Clients have a bi-directional stream to communicate with the agent and steer its processing while work is in progress. Cancel a generation from a different device. Steer an agent mid-response. Send a follow-up before the current response finishes.
+## Durable sessions change the model <a id="durable-sessions"/>
 
-This changes what is buildable:
+A durable session drops in between your agent framework and your users. Persistent, shared, stateful. It handles reconnection, ordering, multi-device sync, presence, and failover so you do not engineer them. It is the layer your AI product runs on; it is not what you build.
+
+![Diagram showing clients and agents attached to a single Ably AI Transport session, with durable-conversation, streaming, multi-device, tool calling, reconnection, history, and presence as the capabilities the session provides](../../../../images/content/diagrams/ait-overview.png)
+
+A minimal adoption surface:
+
+<Code>
+```javascript
+import * as Ably from 'ably';
+import { createClientSession } from '@ably/ai-transport/vercel';
+
+const ably = new Ably.Realtime({ authUrl: '/api/auth/token' });
+const session = createClientSession({
+  client: ably,
+  channelName: 'chat-123',
+});
+
+await session.connect();
+```
+</Code>
+
+Three capabilities define what the layer is for:
+
+- Durable streaming: token streams persist, accumulate, and resume. Reconnecting clients receive assembled state, not a replay of every token. Disconnects become a non-event for your users. See [token streaming](/docs/ai-transport/features/token-streaming) and [reconnection and recovery](/docs/ai-transport/features/reconnection-and-recovery).
+- Session continuity: the session follows the user, not the connection. Multi-device, multi-user, multi-surface. Users switch devices; the session continues with full state. Agents hand off to humans without losing context. See [multi-device sessions](/docs/ai-transport/features/multi-device) and [human-in-the-loop](/docs/ai-transport/features/human-in-the-loop).
+- Visibility and control: bidirectional. Cancel, interrupt, and steer mid-response. Push to users when they are offline. The session is stateful, not just a message pipe. See [agent presence](/docs/ai-transport/features/agent-presence), [interruption](/docs/ai-transport/features/interruption), and [push notifications](/docs/ai-transport/features/push-notifications).
+
+The shape this changes for you:
 
 | Capability | Direct HTTP | Durable session |
 | --- | --- | --- |
-| Resume after disconnect | Build from scratch: buffer, order, and sequence number messages, and add an HTTP endpoint to handle resume. | Automatic. Client reconnects and picks up where it left off. |
+| Resume after disconnect | Build from scratch: buffer, order, sequence-number, and add a resume endpoint. | Automatic. Client reconnects and picks up where it left off. |
 | Multi-device sync | Not possible without custom infrastructure. | Any device subscribes to the same session. |
-| Cancel mid-stream | Close the connection (loses the ability to resume). | Publish a cancel signal. Stream and session survive. |
+| Cancel mid-stream | Close the connection (and lose the ability to resume). | Publish a cancel signal. Stream and session survive. |
 | Steer or interrupt | Requires a separate back channel. | Signal the agent through the session. |
-| Multi-agent visibility | Route all updates through a single HTTP connection orchestrator. | Each agent publishes directly to the session. |
+| Multi-agent visibility | Route all updates through a single HTTP orchestrator. | Each agent publishes directly to the session. |
 
-## How AI Transport implements this <a id="how-ait-implements"/>
+## How AI Transport implements this <a id="how-ai-transport-implements-this"/>
 
-AI Transport implements durable sessions on top of [Ably channels](/docs/channels). Ably channels provide the properties a durable session requires:
+AI Transport is built on [Ably channels](/docs/channels). The properties a durable session requires are properties Ably channels already have:
 
-- Any client or agent connects to the session by specifying a channel name.
-- Messages on the channel outlive any single connection, device, or agent.
-- Events arrive at subscribers in the order they were published, even across disconnections.
-- A client that drops its connection reconnects and picks up where it left off.
-- Any participant publishes to the channel. Cancel, steer, and interrupt all happen through the same session.
-- Multiple participants subscribe to the same channel; every participant sees every event.
+- Any client or agent connects by specifying a channel name.
+- Messages outlive any single connection, device, or agent process.
+- Events arrive at subscribers in publish order, even across disconnects.
+- A client that drops reconnects and picks up where it left off.
+- Any participant publishes. Cancel, steer, and interrupt all happen through the same session.
+- Multiple participants subscribe; every participant sees every event.
 
-No participant is special. A client that drops and reconnects, a serverless agent that spins up for one turn and terminates, a second client joining from another device, and an orchestrator delegating to sub-agents all interact with the same session on equal terms. The session persists independently of any participant's connection lifecycle.
+No participant is special. A client that drops and reconnects, a serverless agent that spins up for one Run and terminates, a second client joining from another device, an orchestrator delegating to sub-agents: all interact with the same session on equal terms.
 
-The AI Transport SDK provides the abstractions that make this model practical:
+The SDK provides the abstractions that make the model practical:
 
-- A [codec layer](/docs/ai-transport/concepts/transport#codec) that bridges domain-specific message models (Vercel AI SDK's `UIMessage`, or any other) and Ably's native message primitives, including support for streamed token-by-token delivery.
-- A [session layer](/docs/ai-transport/concepts/sessions) that materialises conversation state from the channel (or from an external store) into a branching [conversation tree](/docs/ai-transport/concepts/conversation-tree) with views for pagination and branch navigation.
-- A [transport layer](/docs/ai-transport/concepts/transport) that handles communication mechanics: publishing messages, routing streams, managing [turn lifecycle](/docs/ai-transport/concepts/turns), and delivering cancel signals.
+- A [codec layer](/docs/ai-transport/concepts/codecs) that bridges your framework's event types (Vercel `UIMessage`, or your own) and Ably's message primitives, with type-safe `TInput` and `TOutput` directions and stream-append accumulation.
+- A [conversation tree](/docs/ai-transport/concepts/conversation-tree) that materialises session state into a branching structure with views for pagination and branch navigation.
+- [Client and agent sessions](/docs/ai-transport/concepts/connections) that own channel attach, [Run lifecycle](/docs/ai-transport/concepts/runs), and cancel routing.
 - React hooks for building UIs with streaming, pagination, and branch navigation.
-- Adapters that drop into existing frameworks. AI Transport plugs directly into Vercel AI SDK's `useChat`.
+- Adapters that drop into existing frameworks. AI Transport plugs directly into Vercel AI SDK's `useChat` via the `ChatTransport` interface.
+
+## When you don't need this <a id="when-you-dont-need-this"/>
+
+Quick, single-turn chatbots do not need this. AI Transport is for experiences that are long-lived, agentic, and interactive, where sessions span conversations, devices, and time. If your users start and finish in one request, direct HTTP streaming is the simpler choice.
+
+## Why Ably <a id="why-ably"/>
+
+AI Transport runs on infrastructure that has been delivering realtime experiences at scale for over a decade:
+
+- Trillions of realtime transactions monthly.
+- Billions of devices reached.
+- Seven years of zero global downtime.
+- Global edge network, multi-region, SOC 2 Type II, HIPAA-compliant.
+
+The hard problems of running stateful infrastructure (ordering, persistence, replication, presence, failover) are already solved. AI Transport inherits all of it. Your transport layer stops being something you engineer and becomes something you build on. See [Infrastructure](/docs/ai-transport/concepts/infrastructure) for the platform detail.
 
 ## Read next <a id="next"/>
 
-- [HTTP streaming and AI](/docs/ai-transport/why/http-streaming-and-ai): the detailed problem statement that AI Transport solves.
-- [Concepts](/docs/ai-transport/concepts): the building blocks (sessions, turns, transport, codec, conversation tree, infrastructure).
-- [Getting started with Vercel AI SDK](/docs/ai-transport/getting-started/vercel-ai-sdk): build a working app.
+- [HTTP streaming and AI](/docs/ai-transport/why/http-streaming-and-ai): the detailed problem statement.
+- [Get started with Vercel AI SDK](/docs/ai-transport/getting-started/vercel-ai-sdk): build a working app.
+- [Concepts](/docs/ai-transport/concepts): sessions, Runs, invocations, the conversation tree.
+- [Frameworks](/docs/ai-transport/frameworks/vercel-ai-sdk-ui): how AI Transport composes with the framework you already use.
diff --git a/writing-style-guide.md b/writing-style-guide.md
index 87833abf78..9b24eb7764 100644
--- a/writing-style-guide.md
+++ b/writing-style-guide.md
@@ -299,6 +299,8 @@ The additional patterns below have been seen repeatedly in AI-assisted drafts an
 * Audience-aware cuts. Once the audience is established (developers and senior engineers), cut explanations of things they already understand. Restating known concepts to fill space makes the writer look unsure of the reader.
 * Copy-paste metaphors. If the same metaphor or framing phrase appears more than twice, vary it. "Drop-in", "the session as the anchor", and "the layer that fills the gap" each get used once and stay specific.
 * Staccato runs. Avoid stacks of short sentences with no variation (for example, "Sessions are durable. They persist. They survive disconnects. They span devices"). Combine some, let others stretch. Rhythm should follow thinking, not a drumbeat.
+* Abstract actors with generic verbs. Cut collective nouns ("participants", "consumers", "entities", "things") and generic verb pairs ("come and go", "happen at three points") when you can name the specific actors and the action they take. Example to cut: "Participants come and go; the session endures." Becomes: "Clients connect and disconnect, agents spin up and terminate, and the session endures." The specific actor + concrete verb reads as observation; the abstract version reads as filler.
+* Summary scaffolds. Cut sentences that announce what's coming or restate what just happened: "Every other concept on this page operates on or within a session", "These properties combine to give you…", "All of these mean that…", "Putting it together…". If the connection is real, the prose makes it without saying so. Sister to "Gift-wrapped endings" — scaffolds happen mid-page, not just at the end.
 
 ## Patterns to keep