ait: improvements to ai transport channel rule page

src/data/nav/aitransport.ts

@@ -34,7 +34,7 @@ export default {
           link: '/docs/ai-transport/getting-started/authentication',
         },
         {
-          name: 'Enable channel rules',
+          name: 'Configure the channel rule',
           link: '/docs/ai-transport/getting-started/channel-rules',
         },
       ],

src/pages/docs/ai-transport/concepts/authentication.mdx

@@ -101,7 +101,7 @@ The Ably token's `clientId` is verified by the Ably service before the cancel re
 ## Read next <a id="next"/>
 
 - [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.
+- [Configure the channel rule](/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.

src/pages/docs/ai-transport/getting-started/authentication.mdx

@@ -141,6 +141,6 @@ For the Vercel flow, [`ChatTransportProvider`](/docs/ai-transport/api/react/verc
 ## 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.
+- [Configure the channel rule](/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.

src/pages/docs/ai-transport/getting-started/channel-rules.mdx

@@ -1,18 +1,20 @@
 ---
-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"
+title: "Configure the AI Transport channel rule"
+meta_description: "Configure the channel rule AI Transport requires as part of getting started: Message annotations, updates, deletes, and appends on the channel namespace your conversations live on."
+meta_keywords: "AI Transport, getting started, 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.
+The **Message annotations, updates, deletes, and appends** channel rule (`mutableMessages: true`) must be enabled on every channel you use with AI Transport. AI Transport streams each response by appending tokens to a single channel message, and this rule is what allows that.
+
+Channel rules are enabled per [namespace](/docs/channels#namespaces), which is the part of a channel name up to the first colon. Enabling the rule on a namespace applies it to every channel in that namespace. Pick a namespace prefix that scopes your conversations away from other channels in the same app, such as `conversations:` or `chat:`, and enable the rule on it.
+
+Without the rule, 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>

src/pages/docs/ai-transport/troubleshooting.mdx

@@ -20,7 +20,7 @@ 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 channel rules](/docs/ai-transport/getting-started/channel-rules) for the dashboard, Control API, and CLI steps.
+- Enable the *Message annotations, updates, deletes, and appends* rule on the namespace. See [Configure the channel rule](/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"/>