docs(ai-transport): refresh pages against new IA and SDK v0.1.0#3385
Conversation
|
Important Review skippedAuto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the ⚙️ Run configurationConfiguration used: Repository UI Review profile: CHILL Plan: Pro Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
✨ Finishing Touches🧪 Generate unit tests (beta)
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. Comment |
rainbowFi
left a comment
rainbowFi
left a comment
There was a problem hiding this comment.
Some queries inline but none of it is blocking
|
|
||
| ### Getting started page | ||
|
|
||
| A walkthrough that ends with a working app. Walkthrough only — prompts-as-docs is a future enhancement, not in scope yet. |
There was a problem hiding this comment.
Can probably save some context by skipping the prompts-as-docs line
| - Renamed option keys (for example `id` → `chatId`). | ||
| - Renamed enum/literal values (for example `TurnEndReason` going from `'completed' | 'failed' | 'cancelled'` to `'complete' | 'error' | 'cancelled'`). | ||
|
|
||
| ## Writing standards (the parts that catch people out) |
There was a problem hiding this comment.
More for my interest - did you find that this was needed because things in the style guide were being ignored?
There was a problem hiding this comment.
No, I was referencing some local wip docs.. and then gave the instruction to pull stuff into the skill, and it was a bit too aggressive. I've moved all the relevant content over into the writing style guide and updated the skill to reference it.
| 1. Find the latest published version of the SDK you are documenting: `npm view <package>` for `latest` and the repo URL. | ||
| 2. Pull the package: `npm pack <package>@<version>` into a temp dir, extract, read the `.d.ts` files. | ||
| 3. Cross-check the signatures, option shapes, and return types your snippet uses. | ||
| 4. Where the SDK exposes both a core and a framework-bound entry point (for example `@ably/ai-transport` and `@ably/ai-transport/vercel`), pick the entry point your snippet's audience uses and follow its option shape. |
There was a problem hiding this comment.
There's technical docs work to have appropriate selectors for framework/language combinations on feature pages where the audience's stack is unknown. I'm assuming the skill has done something sensible with the new feature pages - used core only?
There was a problem hiding this comment.
Yes, as much as possible. The code examples are all in js (so language is covered) and we don't really have support for other frameworks except for vercel (because we don't have codecs yet). So that's kind of covered too.
We will need to sort these out more when we have different languages and different frameworks, but we don't have the breadth of support to actually have different content yet.
| @@ -0,0 +1,133 @@ | |||
| --- | |||
| title: "Barge-in" | |||
There was a problem hiding this comment.
I'm really sorry for not realising this sooner, but we had a whole argument about barge-in vs interruption and concluded that barge-in is specifically about voice, interruption is the general term. So this page didn't need to be renamed. Sorry...
https://ably.atlassian.net/wiki/spaces/AI/pages/4865097761/AI+Transport+Terminology+Reference#Interruption-%2F-Barge-In
There was a problem hiding this comment.
ok super - fixed, thanks
|
|
||
| ## 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. |
There was a problem hiding this comment.
We should flag the ability to use your own codec/format if a matching codec is not available from Ably
There was a problem hiding this comment.
Good catch. The codec API surface is changing in the upcoming SDK release, so I've parked this as todo later rather than writing a guide that would be re-written the moment the new surface lands. (Because we don't currently have content on writing your own codec, so I'd need to point "you can BYO codec" at some content, and we don't have that content yet)
Once the new SDK is shipped I'll extend the codec paragraph here to make the build-your-own-codec story explicit, and link to either internals/codec-architecture#custom-codec or the codec API reference walkthrough (whichever ends up being the best / most useful).
Rewrite the AI Transport docs against the page-design principles from the April 2026 wireframe workings and align every code snippet with @ably/ai-transport@0.1.0. Structural changes: - Rename features/interruption to features/barge-in and concepts/messages-and-conversation-tree to concepts/conversation-tree, with redirect_from on both renamed pages. - Merge features/edit-and-regenerate into features/branching. - Split framework-guides/vercel-ai-sdk into frameworks/vercel-ai-sdk-ui and frameworks/vercel-ai-sdk-core with verbatim-aligned capability bullets, and retire the framework-guides path. - Convert why.mdx into why/index.mdx plus a why/http-streaming-and-ai subpage that absorbs the HTTP-limitations detail. - Add concepts/index.mdx, concepts/infrastructure.mdx, and going-to-production.mdx as new top-level entries. - Restructure src/data/nav/aitransport.ts to match. Content changes apply across every refreshed page: - Layer-0 hook on every page (intro frontmatter plus two-sentence outcome-then-mechanism opening on feature pages). - JTBD framing on feature pages, edge cases section, FAQ with three to five real entries, and two to three hand-picked related links. - Concept pages tightened to problem -> model -> requirements -> one code-proof sample; API-surface walkthroughs removed. - Remove "docs being actively written" admonitions throughout. - Remove em dashes, bold-prefix bullets, Latin abbreviations, subjective phrases, "we" pronouns; tighten to writing-style-guide. SDK accuracy fixes against @ably/ai-transport@0.1.0: - createTransport -> createClientTransport; vercelCodec() -> UIMessageCodec; remove non-existent transport.attach(). - useClientTransport returns { transport, transportError }; destructure at every call site. - useChatTransport switches from positional ClientTransport argument to context reader returning { chatTransport, transport }. - useMessageSync switches from positional args to options object { setMessages }. - Remove useEdit/useRegenerate/useSend documentation and call sites; surface the same operations as ViewHandle methods returned by useView. - transport.send becomes transport.view.send; transport.view is a property, not a method; messages come from view.getMessages(). - TurnEndReason literals corrected to 'complete' | 'cancelled' | 'error'. - Codec example: decode() returns DecoderOutput[]; createAccumulator returns an accumulator object with seedMessages/completeSeeded. - Token streaming page: drop key in client code, use authUrl: '/auth'. - Tool calling page: fix navigator.geolocation.getCurrentPosition callback wrapping (was incorrectly awaited). - ClientTransportOptions: api is required on the core entry point, defaulted only by the Vercel pre-bound factory. - Codec architecture page: header composition is last-write-wins, not fixed-priority; document append-promise collection and batch flush recovery; remove "first-contact" and "prefix-match" jargon.
Add a project-level skill that distils the page-design principles, per-page-type templates, writing standards, code-accuracy workflow, and verification checks used during the AI Transport docs refresh. Captures decisions made during that refresh so subsequent docs work in this repo stays consistent without re-deriving the rules. The skill references CLAUDE.md and writing-style-guide.md rather than duplicating them, and notes that those sources win when they conflict with the skill.
zknill
force-pushed
the
zak/restructure-ait-docs
branch
from
33d5a26 to
9f885c3
Compare
Apply the resolvable PR #3385 review feedback and consolidate Ably writing standards onto a single source of truth. AIT pages: - Revert barge-in -> interruption rename. Per the internal AI Transport terminology decision, "interruption" is the general term and "barge-in" is reserved for voice contexts. Rename features/barge-in.mdx back to features/interruption.mdx, update the page title, body prose, frontmatter and redirect_from, and update every cross-reference in cancellation, concurrent-turns, double-texting, and the nav. "barge-in" stays only in meta_keywords and a single one-line voice-context note on the page body. write-docs skill: - SKILL.md:62 drop the unactionable "use the canonical wireframe" pointer; the section order below is the structural pattern. - SKILL.md:91 define what counts as a sibling framework page and allow framework-specific rows where the integration shape differs rather than forcing parity. - SKILL.md:109 drop the prompts-as-docs aside on the getting-started template; it was scope-creep noise. - SKILL.md:323 source the SDK version from src/data/languages/languageData.ts (the page-header's own source) instead of npm "latest", and add a "Documenting a pre-release SDK" sub-section covering the case where the version is not yet on npm. Writing-standards consolidation: - Merge net-new writing-standards content from SKILL.md into writing-style-guide.md. Skip the items that were already in the style guide. Net-new additions: ten AI-fingerprint "patterns to strip" (corrective antithesis, dramatic pivot phrases, soft hedging, throat-clearing intros, gift-wrapped endings, generic examples, overexplaining the obvious, audience-aware cuts, copy-paste metaphors, staccato runs), a "patterns to keep" counter-rules section, a "Layer-0 hook for opening prose" section, an MDX "Asides" section, and the "API keys in client code" ban. - Strip the "Writing standards" section from SKILL.md and replace with a two-paragraph pointer to writing-style-guide.md with a "you must read it before making any changes to the docs" instruction. - Consolidate the reviewer checklist's writing-standards block from nine duplicated items to a single pointer plus the deslop item; renumber subsequent items (18-33 -> 11-26). - Update the per-page workflow's "strip AI patterns" step to point at the style-guide section.
4 participants
Rewrite the AI Transport docs against the page-design principles from
the April 2026 wireframe workings and align every code snippet with
@ably/ai-transport@0.1.0.
Structural changes:
Rename features/interruption to features/barge-in and
concepts/messages-and-conversation-tree to concepts/conversation-tree,
with redirect_from on both renamed pages.
Merge features/edit-and-regenerate into features/branching.
Split framework-guides/vercel-ai-sdk into frameworks/vercel-ai-sdk-ui
and frameworks/vercel-ai-sdk-core with verbatim-aligned capability
bullets, and retire the framework-guides path.
Convert why.mdx into why/index.mdx plus a why/http-streaming-and-ai
subpage that absorbs the HTTP-limitations detail.
Add concepts/index.mdx, concepts/infrastructure.mdx, and
going-to-production.mdx as new top-level entries.
Restructure src/data/nav/aitransport.ts to match.
Content changes apply across every refreshed page:
Layer-0 hook on every page (intro frontmatter plus two-sentence
outcome-then-mechanism opening on feature pages).
JTBD framing on feature pages, edge cases section, FAQ with three to
five real entries, and two to three hand-picked related links.
Concept pages tightened to problem -> model -> requirements -> one
code-proof sample; API-surface walkthroughs removed.
Remove "docs being actively written" admonitions throughout.
Remove em dashes, bold-prefix bullets, Latin abbreviations,
subjective phrases, "we" pronouns; tighten to writing-style-guide.
SDK accuracy fixes against @ably/ai-transport@0.1.0:
createTransport -> createClientTransport; vercelCodec() ->
UIMessageCodec; remove non-existent transport.attach().
useClientTransport returns { transport, transportError }; destructure
at every call site.
useChatTransport switches from positional ClientTransport argument to
context reader returning { chatTransport, transport }.
useMessageSync switches from positional args to options object
{ setMessages }.
Remove useEdit/useRegenerate/useSend documentation and call sites;
surface the same operations as ViewHandle methods returned by useView.
transport.send becomes transport.view.send; transport.view is a
property, not a method; messages come from view.getMessages().
TurnEndReason literals corrected to 'complete' | 'cancelled' | 'error'.
Codec example: decode() returns DecoderOutput[]; createAccumulator
returns an accumulator object with seedMessages/completeSeeded.
Token streaming page: drop key in client code, use authUrl: '/auth'.
Tool calling page: fix navigator.geolocation.getCurrentPosition
callback wrapping (was incorrectly awaited).
ClientTransportOptions: api is required on the core entry point,
defaulted only by the Vercel pre-bound factory.
Codec architecture page: header composition is last-write-wins, not
fixed-priority; document append-promise collection and batch flush
recovery.