docs(ai-transport): rewrite Vercel AI SDK framework guide to match Matt's wireframe (non-WDK pass)

[rainbowFi]

What this changes

Replaces the existing Vercel AI SDK framework guide end-to-end with the eight-section structure from Matt O'Riordan's wireframe (framework-vercel-ai-sdk-ui.md): drop-in opening, what each layer covers, how they fit together (architecture + code swap), try it, six capability sections, what developers build around, when you need AI Transport, and a read-next list.

Targets developers using Vercel AI SDK without the Workflow Dev Kit. A WDK-aware pass is a separate change.

Source

• Wireframe: framework-vercel-ai-sdk-ui.md (Drive ID 1-fXntKfEfIh8DOhefc-r9t33SS51nMu1)
• Cross-cutting conventions: CROSS-CUTTING-CONVENTIONS.md (Drive ID 17jXq4Z2eSuigLcfT-jvK2wV9Q0R-4QjM)
• Principles: PRINCIPLES.md (Drive ID 1-1LUmRGc4A5npSl0vMhzeOP7orTzoYQ9)
• Recommendations: fiona-notes/ait-docs/vercel-ai-sdk-guide-edits.md

Style adjustments applied to the lifted prose

• All em dashes from the wireframe removed; rewritten with commas, semicolons, colons, or full stops.
• "Real-time" rewritten as "Realtime" in the Agent presence card.
• "recognised" rewritten as "recognized" (US English, per Ably style guide).
• "behaviour" rewritten as "behavior" in the Try it section.
• Sentence-case headings throughout.
• Inline code preserved: useChat, ChatTransport, useClientTransport, useChatTransport, useCompletion, streamText, generateText.
• Auth placeholder in the architecture code uses useClientTransport({ channelName: 'my-session' }) plus a token-endpoint cross-link, never an embedded API key (per CROSS-CUTTING-CONVENTIONS.md and PRINCIPLES.md §18).

Decisions deferred to reviewer

1. Card 2 in section 5: kept Matt's combined "Session continuity" form. Alternative split into multi-device + multi-participant cards (Fiona's positioning treats them as two distinct axes). Suggested split if you want to apply it (em dashes already removed):

   Card 2a: Sessions across a user's devices. Same user, multiple screens (phone, laptop, tablet). Switch devices, close tabs, go offline; the session follows.

   Card 2b: Sessions across multiple participants. Different people in the same session: customer plus support agent, observer, or second viewer. The session is shared, not per-connection.

2. Card 1 in section 5: kept Matt's "Durable streaming" title. Alternative: "Resumable streams" to match Fiona's demo intro positioning. Trivial swap if preferred.

3. Code form: kept the three-line form. The Vercel integration API reference (/docs/ai-transport/api-reference/vercel) confirms the canonical surface is useClientTransport then useChatTransport then useChat. The wireframe's one-line useChat({ transport: ablyTransport({...}) }) is aspirational and does not reflect what @ably/ai-transport/vercel/react exposes. Action needed: SDK-or-docs reconciliation. The wireframe's "One line." framing was dropped from the prose so the page does not claim something the SDK does not deliver. If product wants to keep the "one line" story, the SDK needs a single combined factory; if not, the canonical drop-in framing on this page, the demo intro, and the canonical positioning should all settle on "only the transport changes" (no line count).

4. Live demo URL: placeholder. "Try it" links to #live-example-placeholder with a TODO comment in the MDX source. Launch blocker. Before publish: confirm a public demo URL with the demo team and replace.

5. Architecture diagram: ASCII in a <Code> block. The repo uses PNG images for diagrams (e.g. images/content/diagrams/ai-transport-before-and-after.png); no Mermaid usage detected. ASCII is the lowest-friction placeholder. Recommend the design team produces a functional, annotated illustration matching PRINCIPLES.md §16 before publish.

6. Capability card link targets. Mapped to existing feature pages where possible:

   Card	Target	Notes
   Durable streaming	/docs/ai-transport/features/reconnection-and-recovery	Closer fit than token-streaming.
   Session continuity	/docs/ai-transport/features/multi-device	Direct match.
   Bidirectional control	/docs/ai-transport/features/interruption	Card text mentions barge-in; interruption.mdx is the closest. cancellation.mdx is the alternative.
   Agent presence	/docs/ai-transport/features/agent-presence	Direct match.
   Human handover	/docs/ai-transport/features/human-in-the-loop	Direct match.
   Shared live state	/docs/ai-transport/concepts/sessions	No dedicated feature page exists. Falls back to the concept page. Consider creating a feature page for shared live state, or accept the concept-page link as the canonical home.

7. Read-next 2x2. No sibling Vercel AI SDK Core framework guide exists yet (only a Core SDK getting-started page), so there is no peer page to align verbatim against. The four targets picked: Get started, How it works (concepts/sessions), Browse features (token-streaming as the entry point), API reference. The wireframe's fourth card was "Guides"; AI Transport has no guides/ section in nav/aitransport.ts, so this substitutes "API reference". Swap to a guides/ link once that section exists.

Out of scope

• WDK-aware framing (separate pass).
• Creating new feature pages for cards that don't have existing targets ("Shared live state").
• The proposed SDK auth-detection error and ably ai-transport session inspect CLI command from CROSS-CUTTING-CONVENTIONS.md. Both are unbuilt; referencing them on this page would be premature.
• Sourcing community evidence URLs for "What developers are building around". The four pattern descriptions stay as the wireframe has them.
• The "Copy + AI-icon row" and "session inspector" UI affordances on the implementation code block. These are design-team deliverables; the wireframe reserves the affordances rather than specifying them.

How to review

Compare side-by-side with the wireframe in Drive (framework-vercel-ai-sdk-ui.md). The structural shape matches exactly; the prose matches the wireframe with em dashes removed and the style adjustments listed above.

Then check the deferred decisions and confirm the route on each before this leaves draft.

Things in the wireframe that didn't translate cleanly

• Card grid layout for the six capabilities. The wireframe shows two rows of three cards with visual weight. The docs repo's only generic grid component is <Tiles>, which expects icons and is built for nav (e.g. tech-stack tiles on getting-started/index.mdx). I used H3 + paragraph + "Learn more" link, matching the "Features" pattern in ai-transport/index.mdx. A proper card grid is a design + components task, not content.
• Live example card. Same issue: the wireframe shows a thumbnail + "Open live example" button card. The closest existing pattern is plain prose + link, which is what I used. Worth a small LiveExampleCard MDX component if other framework pages will use it.
• 2x2 read-next grid. Same again. Used a markdown bullet list; consistent with the repo's existing "Read next" style, but visually flatter than the wireframe.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 3d6772e7-81ac-427a-a8ab-43a51078ae44

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch vercel-ai-sdk-guide-rewrite-non-wdk

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}