docs

name	docs
description	Write or improve markdown documentation for the AI Transport SDK. Follows the project's doc principles (atomic pages, problem-first framing, one path then depth) and the established style from the docs that received positive feedback.

Writing Documentation

Write markdown documentation for the AI Transport SDK. This skill covers creating new doc pages, improving existing ones, and reviewing docs for consistency with the project's principles and voice.

Before writing

1. Read the source code for whatever you're documenting. Never document from memory or assumption - read the implementation, the types, and the tests. The code is the source of truth.

2. Read related existing docs in docs/ to understand what's already covered and avoid contradictions. Check for pages that should cross-reference the new content.

3. Identify the single intent of the page. Each page answers one question or enables one task. If the page covers two distinct developer intents, it should be two pages.

4. Read docs/internals/glossary.md before writing any internals page. Use glossary links for Ably-specific or architecture terms at first mention rather than re-explaining them inline.

Doc principles

These principles come from the project's documentation strategy. Follow them in every page you write.

Problem recognition is the entry point

Open feature pages with brief problem framing - "without a durable session layer, this is hard because..." This is not marketing. It orients the developer and explains why the capability exists. Keep it to 1-2 sentences.

One path, then depth

Default to the most common choice at every decision point. Don't present two equal options where one should be the default. Show the recommended approach first, then mention alternatives below. The developer who just wants to get it working should never have to choose between equal-looking options.

Atomic pages, duplication is fine

Each page has one clear focus. Cancel, interruption, steer, and double-text are separate pages even though they share underlying technology. Duplication across pages is preferred over forcing developers to mentally unpack a page covering multiple concepts. When you duplicate, keep the duplicated content minimal and focused on the current page's intent.

Client and server are distinct concerns

Feature pages should show code for both sides. Use clear section headers (not tabs - this is markdown). Server code and client code are separate concerns and should be presented separately with their own context.

Honest about status

Be explicit about what's supported, what's partial, and what's planned. Never claim a feature works if the implementation is incomplete. Mark unimplemented features clearly.

It's a tool, not a task

Frame everything as "you have this problem, and it disappears." The developer is not learning a new thing - they're solving a problem they already have. AI Transport is infrastructure you don't want to think about.

Voice and style

These patterns are derived from the documentation that received positive feedback. They are not guidelines - they are the voice of this project's docs.

Opening sentence

The first sentence of every page defines the concept or capability in one direct, declarative statement. No preamble, no "In this guide, we'll..."

<!-- Good -->

Cancellation in `@ably/ai` is a channel-level operation - the client publishes
a cancel signal on the Ably channel, the server receives it and aborts the
matching runs.

<!-- Good -->

Interruption is when a user sends a new message while the AI is still streaming
a response.

<!-- Bad -->

In this guide, we'll explore how to cancel streaming responses in your
AI application.

<!-- Bad -->

This page covers the cancellation feature of the AI Transport SDK.

Tone

• Confident and direct. State what happens, not what "should" or "might" happen. "The stream closes" not "the stream should close."
• Technical but accessible. Assume the reader is a competent developer but not an Ably expert. Explain Ably-specific concepts briefly on first use.
• No marketing language. No "powerful", "seamless", "easy-to-use", "robust." The technical explanation IS the value proposition.
• No hedging. Don't say "you may want to" or "consider using." Say "use X when Y."
• Use hyphens, not em-dashes. Use - (space-hyphen-space) for parenthetical asides, not —. This applies to prose, code comments, and table cells.

Inline code formatting

Use backticks for anything that references code - variable names, function names, header names, enum values, type names, file paths. Do not use backticks for plain-English concept names.

• Concept names are plain text: "message ID", "run", "cancel signal"
• Variable/field names are backticked: msgId, runId, serial
• Header names are backticked: x-ably-msg-id, x-ably-run-id
• Functions always include parentheses: send(), cancel(), not send or cancel
• Types and interfaces are backticked: ClientSession, Codec<TEvent, TMessage>
• Enum values are backticked: streaming, finished, aborted

<!-- Good -->

The message ID is available as `msg.id`. Call `transport.send()` to publish,
which sets the `x-ably-msg-id` header.

<!-- Bad: concept name backticked, function missing parens -->

The `message ID` is available as `msg.id`. Call `transport.send` to publish.

Define jargon on first use

Every technical term that a reader might not know needs either an inline definition or a link to the glossary at its first mention within a page. This applies to:

• Ably-specific terms: serial, message actions, channel attach, untilAttach, message appends, extras.headers
• Architecture terms: transport layer vs domain layer, own run vs observer run, run IDs vs message ID
• Protocol jargon: terminal event, fire-and-forget, prefix-match, first-contact, optimistic reconciliation, serial promotion, codec key

For internals pages, prefer linking to the glossary ([serial](glossary.md#serial-ably)) over repeating the definition. For feature and concept pages aimed at external developers, prefer a brief inline explanation on first use - don't force readers to click away.

After writing a page, audit it for unexplained terms. Read each paragraph as if you don't know the codebase. Any term that would make you pause and think "what does that mean?" needs a definition or a link.

Structure patterns

Feature pages follow this flow:

1. Opening definition - one sentence that defines what this is
2. Problem framing - 1-2 sentences: "without X, this is hard because..."
3. Mechanism - how it works (brief, conceptual)
4. Server code - complete but minimal, under a "Server" or "Server side" header
5. Client code - complete but minimal, under a "Client" or "Client side" header
6. Variants/options - alternative approaches, configuration options
7. Edge cases - what happens in non-obvious situations
8. Wire sequence (if applicable) - ASCII diagram showing the message flow
9. Cross-references - inline links to related feature pages and the reference

Concept pages follow this flow:

1. Opening definition - what this abstraction is and why it exists
2. Architecture - how the pieces fit together (ASCII diagrams)
3. Data flow - what happens when, step by step
4. Key details - the things developers need to know to use it correctly

Quickstart pages follow this flow:

1. Opening sentence - what you'll build and which integration path
2. Prerequisites - what you need before starting
3. Numbered steps - each step is a file to create, with complete code
4. "What's happening" - brief explanation linking to concept pages
5. Next steps - links to feature pages for adding capabilities

Framework guide pages follow this flow:

1. Opening sentence - what the framework provides and what AIT adds
2. Comparison table - capabilities with and without AIT
3. Integration paths - recommended approach first, alternatives below
4. When to use which - decision table for choosing between paths
5. Server side - server code is the same for all client paths
6. Codec details - how the codec maps between framework types and Ably

Reference pages follow this flow:

1. One section per API item - hook, method, or error code
2. Signature - the TypeScript call signature
3. Parameters table - name, type, description for each parameter
4. Return type - what comes back, with property/method tables for complex returns
5. Behavior notes - brief description of what it does, when it updates
6. Code example - minimal usage (only where the signature isn't self-evident)

Internals pages follow this flow:

1. Opening definition - what this component is and what problem it solves
2. Key concepts - the mental model (data structures, state machines, lifecycles) needed to understand the component
3. Operations/methods - what you can do with it, typically as a table
4. Algorithms/flows - step-by-step or pseudocode for non-trivial processes (flatten, flush/recovery, prefix-match, etc.)
5. Edge cases and recovery - what happens when things go wrong
6. Cross-references - inline links to related internals pages, the glossary, and the corresponding feature/concept pages

Internals pages differ from concept pages: concept pages explain what developers need to know to use the SDK. Internals pages explain how the SDK works internally for contributors and curious engineers. Internals pages can reference source file paths and internal class names.

Tables

Use tables for structured comparisons - filter options, event types, error codes, phase behaviors. Tables are scannable and dense. Prefer a table over a bullet list when comparing properties across items.

| Filter                    | Effect                                 | Use case                     |
| ------------------------- | -------------------------------------- | ---------------------------- |
| `{ own: true }` (default) | Cancel all runs started by this client | Stop button                  |
| `{ runId: "abc" }`        | Cancel one specific run                | Cancel a specific generation |

Diagrams

Use Mermaid diagrams (```mermaid) for sequence diagrams, flowcharts, and any multi-column or multi-participant interactions. Mermaid is rendered by GitHub and most doc tooling, so alignment is never an issue.

````mermaid
sequenceDiagram
    participant C as Client
    participant Ch as Channel
    participant S as Server

    C->>Ch: publish(ai-cancel)
    Note left of C: close local stream(s)
    Ch->>S: deliver to cancel listener
```                                        (close the code fence)
````

When to use Mermaid vs plain text:

• Mermaid sequenceDiagram - wire sequences, request-response flows, anything with multiple participants exchanging messages over time.
• Mermaid flowchart - data flow diagrams, architecture layers, routing logic with branching paths.
• Plain text - simple hierarchical trees (2-3 levels, e.g. class composition), pseudocode algorithms, data structure layouts. These are small enough that alignment is trivial.

Do not use hand-drawn ASCII art for multi-column sequence diagrams. Column alignment is error-prone and breaks silently when edited. Mermaid eliminates this class of bugs entirely.

Code examples

• Complete but minimal. Every example should be copy-pasteable and make sense on its own. Include imports when the import path matters.
• Show the recommended approach first. The first code block on the page should be the thing most developers will actually write.
• Real types, real methods. Use the actual API - transport.send(), run.cancel(), not pseudocode.
• Comments explain the non-obvious. Don't comment // cancel the run above run.cancel(). Do comment // fire-and-forget - POST doesn't block the stream return.
• TypeScript only for now (the SDK is TypeScript).
• Both sides. Feature pages show client and server code. Use section headers to separate them.

Cross-references

Link to related pages with relative markdown links. Every feature page should link to at least the relevant reference page. Use inline links, not a "See also" section at the bottom.

Link densely, not just at the end. Every mention of a concept that is explained in detail on another page should be an inline link at first mention within the current section. Don't rely on a trailing "See also" paragraph - readers skim, and the link needs to be where the concept appears.

<!-- Good: inline link where the concept is mentioned -->

The [decoder](decoder.md) accumulates deltas via string concatenation and
uses [prefix-matching](decoder.md#known-serial-prefix-match) to detect
whether an update is incremental or a replacement.

<!-- Bad: concept mentioned without link, with "See also" at the bottom -->

The decoder accumulates deltas via string concatenation and uses
prefix-matching to detect whether an update is incremental or a replacement.
...
See [Decoder](decoder.md) for details.

For internals pages, link to specific heading anchors (e.g. encoder.md#recovery-mechanism) rather than just the page. This lets readers jump directly to the relevant section.

Feature/concept pages should link to the corresponding internals page at the end for readers who want to go deeper (e.g. "For the internal mechanics, see Conversation tree.").

Section headers

Use short, descriptive headers. Prefer "What happens when you cancel" over "Cancellation behavior." Use the developer's language, not internal jargon.

Headers should work as a table of contents - a developer scanning the headers should understand what the page covers without reading the body.

What NOT to do

• Don't write "Introduction" sections. The opening paragraph IS the introduction.
• Don't summarize at the end. The page is short enough to not need it.
• Don't explain what markdown formatting means. No "the table below shows..." - just put the table there.
• Don't add meta-commentary. No "This is an advanced topic" or "This section assumes you've read X." If there's a prerequisite, link to it inline.
• Don't use admonitions excessively. A page with five "Note:" callouts is a page with poor structure. Restructure so the information flows naturally.
• Don't document internal implementation details unless the page is explicitly in the "Under the Hood" / internals section. Feature pages explain what happens and how to use it, not how the code is structured internally.
• Don't invent API surface. Only document methods, options, and behaviors that exist in the source code. Read the code first.
• Don't simplify interface signatures. When showing a TypeScript interface or method signature, include all parameters (even optional ones) and mark optional fields with ?. Omitting a parameter or showing a required field as optional leads to incorrect mental models.
• Don't describe behavior without verifying the code path. Common mistakes: describing which method is called in error vs success paths incorrectly, getting the priority order of layered operations wrong (e.g. header merge order), or confusing close() with abort(). Verify each claim against the actual implementation.
• Don't use concepts without explaining or linking them. Every technical term - Ably-specific, architecture-specific, or protocol jargon - must be either defined inline or linked to the glossary at its first mention on the page.

File placement

Follow the existing directory structure:

docs/
├── index.md          # Overview - orients the developer, routes to next step
├── concepts/         # Mental models: transport architecture, runs, codec
├── get-started/      # Quickstarts - working app in minutes, per integration path
├── frameworks/       # Framework guides - why AIT + framework X, integration paths
├── features/         # Feature pages - one developer intent per page, atomic
├── reference/        # API reference - signatures, params, return types
└── internals/        # Under the hood - wire protocol, encoder, decoder, tree, etc.
    └── glossary.md   # Definitions for Ably-specific and architecture terms

Page type by directory:

Directory	Page type	Pattern
concepts/	Concept page	Definition → architecture → data flow → key details
get-started/	Quickstart	Prerequisites → step-by-step → "what's happening" → next steps
frameworks/	Framework guide	What the framework provides → what's missing → how AIT fills gaps → integration paths
features/	Feature page	Definition → problem framing → mechanism → client code → server code → edge cases
reference/	Reference page	One section per API item: signature, params table, return type, example
internals/	Internals page	Definition → concepts → operations → algorithms → edge cases → cross-refs

If a page doesn't fit these categories, discuss placement before writing.

Verifying a page

Verification is owned by the code-review-docs skill - the review half of the docs writing loop. After writing or editing a page, run code-review-docs (or let the loop run it) to audit accuracy, coverage, structure and voice, cross-references, and concept coverage, then fix what it reports and repeat until it passes.