docs(ai): align rag and client docs

Author: jfarcand

docs/src/content/docs/clients/javascript.md

@@ -5,7 +5,7 @@ description: "TypeScript client with React, Vue, and Svelte hooks"
 
 # atmosphere.js -- TypeScript Client
 
-TypeScript client for the Atmosphere Framework (currently `5.0.22`). Supports WebTransport/HTTP3, WebSocket, SSE, HTTP Streaming, and Long-Polling transports with first-class React, Vue, and Svelte hooks.
+TypeScript client for the Atmosphere Framework (currently `5.0.24`). Supports WebTransport/HTTP3, WebSocket, SSE, HTTP Streaming, and Long-Polling transports with first-class React, Vue, and Svelte hooks.
 
 ## npm Coordinates
 
@@ -35,10 +35,10 @@ The package ships ESM, CommonJS, and TypeScript declarations. Framework integrat
 
 ```typescript
 import { Atmosphere } from 'atmosphere.js';
-import { useAtmosphere, useStreaming, useRoom, usePresence } from 'atmosphere.js/react';
-import { useAtmosphere, useStreaming, useRoom } from 'atmosphere.js/vue';
-import { createAtmosphereStore, createStreamingStore, createRoomStore } from 'atmosphere.js/svelte';
-import { useAtmosphereRN, useStreamingRN, setupReactNative } from 'atmosphere.js/react-native';
+import { useAtmosphere, useStreaming, useChat, useRoom, usePresence } from 'atmosphere.js/react';
+import { useAtmosphere, useStreaming, useChat, useRoom } from 'atmosphere.js/vue';
+import { createAtmosphereStore, createStreamingStore, createChatStore, createRoomStore } from 'atmosphere.js/svelte';
+import { useAtmosphereRN, useStreamingRN, useChatRN, setupReactNative } from 'atmosphere.js/react-native';
 ```
 
 ## Core API
@@ -56,7 +56,7 @@ const atm = new Atmosphere({
   fallbackTransport: 'long-polling',
 });
 
-atm.version;       // '5.0.22'
+atm.version;       // '5.0.24'
 atm.closeAll();    // Close every active subscription
 atm.getSubscriptions();  // Map<string, Subscription>
 ```
@@ -384,6 +384,28 @@ function AiChat() {
 }
 ```
 
+### useChat
+
+AI-SDK-style message/input state layered on `useStreaming`:
+
+```tsx
+import { useChat } from 'atmosphere.js/react';
+
+function AiChatForm() {
+  const { messages, input, setInput, handleSubmit, isLoading } = useChat({
+    request: { url: '/ai/chat', transport: 'websocket' },
+  });
+
+  return (
+    <form onSubmit={handleSubmit}>
+      {messages.map((message) => <p key={message.id}>{message.content}</p>)}
+      <input value={input} onChange={(event) => setInput(event.target.value)} />
+      <button disabled={isLoading}>Send</button>
+    </form>
+  );
+}
+```
+
 ## Vue Composables
 
 Vue composables do not require a provider -- they create or accept an Atmosphere instance directly.
@@ -453,6 +475,26 @@ const { fullText, isStreaming, send, reset } = useStreaming({
 </template>
 ```
 
+### useChat
+
+```vue
+<script setup lang="ts">
+import { useChat } from 'atmosphere.js/vue';
+
+const { messages, input, handleSubmit, isLoading } = useChat({
+  request: { url: '/ai/chat', transport: 'websocket' },
+});
+</script>
+
+<template>
+  <form @submit="handleSubmit">
+    <p v-for="message in messages" :key="message.id">{{ message.content }}</p>
+    <input v-model="input" />
+    <button :disabled="isLoading">Send</button>
+  </form>
+</template>
+```
+
 ## Svelte Stores
 
 Svelte integrations use the store pattern -- each factory returns a Svelte-compatible readable store plus action functions.
@@ -520,6 +562,24 @@ Svelte integrations use the store pattern -- each factory returns a Svelte-compa
 {#if $store.isStreaming}<span>Generating...</span>{/if}
 ```
 
+### createChatStore
+
+```svelte
+<script>
+  import { createChatStore } from 'atmosphere.js/svelte';
+
+  const { store: chat, append, reset } = createChatStore({
+    request: { url: '/ai/chat', transport: 'websocket' },
+  });
+</script>
+
+{#each $chat.messages as message}
+  <p>{message.content}</p>
+{/each}
+<button on:click={() => append('What is Atmosphere?')}>Ask</button>
+<button on:click={reset}>Reset</button>
+```
+
 ## AI Streaming Wire Protocol
 
 The server sends JSON messages using the Atmosphere AI streaming protocol:
@@ -532,7 +592,9 @@ The server sends JSON messages using the Atmosphere AI streaming protocol:
 {"type": "error",    "data": "Rate limited","sessionId": "abc-123", "seq": 11}
 ```
 
-Use `subscribeStreaming` for framework-agnostic streaming, or the hooks above for React/Vue/Svelte.
+Use `subscribeStreaming` for framework-agnostic streaming, `useStreaming` /
+`createStreamingStore` for raw text accumulation, or `useChat` /
+`createChatStore` for message/input state.
 
 ## Request Options
 
@@ -647,7 +709,7 @@ Complete TypeScript type reference for the public surface.
 
 ```typescript
 class Atmosphere {
-  readonly version: string;  // '5.0.22'
+  readonly version: string;  // '5.0.24'
 
   constructor(config?: {
     logLevel?: 'debug' | 'info' | 'warn' | 'error' | 'silent';

docs/src/content/docs/clients/react-native.md

@@ -5,7 +5,7 @@ description: "React Native hooks with EventSource polyfill"
 
 # React Native / Expo Guide
 
-atmosphere.js `5.0.22` supports React Native and Expo via the `atmosphere.js/react-native` subpath export. Tested baseline: Expo SDK 55, React Native 0.83, React 19.2 (see `samples/spring-boot-ai-classroom/expo-client/package.json`).
+atmosphere.js `5.0.24` supports React Native and Expo via the `atmosphere.js/react-native` subpath export. Tested baseline: Expo SDK 55, React Native 0.83, React 19.2 (see `samples/spring-boot-ai-classroom/expo-client/package.json`).
 
 ## Installation
 
@@ -132,6 +132,19 @@ const { fullText, isStreaming, isConnected, send, reset, close } = useStreamingR
 
 Sends are suppressed when the device is offline.
 
+### `useChatRN`
+
+AI-SDK-style message/input state layered on `useStreamingRN`.
+
+```typescript
+const { messages, input, setInput, handleSubmit, isLoading } = useChatRN({
+  request: { url: 'https://example.com/ai/chat', transport: 'websocket' },
+});
+```
+
+`append()`, `reload()`, `stop()`, and `reset()` are also available for custom
+chat UIs.
+
 ### `useAtmosphereCore`
 
 Shared low-level hook exported from `atmosphere.js/react-native` for building custom hooks. It manages subscription lifecycle, state, and cleanup — the RN-aware `useAtmosphereRN` and `useStreamingRN` hooks are built on top of it. Use it when the built-in hooks don't fit your use case.

docs/src/content/docs/reference/ai.md

@@ -621,41 +621,44 @@ The `AiEvent` sealed interface provides 15 structured event types emitted via `s
 
 ## Capability Matrix
 
-Each runtime declares capabilities via `AiCapability`. The framework uses these for model routing, tool negotiation, and feature discovery.
-
-### Guaranteed by Core
-
-Available on **all** runtimes:
-
-| Capability | Description |
-|-----------|-------------|
-| `TEXT_STREAMING` | Basic text streaming |
-| `SYSTEM_PROMPT` | System prompt support |
-
-### Runtime-Dependent
-
-| Capability | Built-in | LangChain4j | Spring AI | ADK | Embabel | Koog | SK |
-|-----------|----------|-------------|-----------|-----|---------|------|----|
-| `TOOL_CALLING` | Y | Y | Y | Y | | Y | |
-| `STRUCTURED_OUTPUT` | Y | Y | Y | Y | Y | Y | Y |
-| `CONVERSATION_MEMORY` | | | | Y | | Y | Y |
-| `TOOL_APPROVAL` | Y | Y | Y | Y | | Y | |
-| `VISION` | Y | Y | Y | Y | | | |
-| `AUDIO` | | Y | Y | Y | | | |
-| `MULTI_MODAL` | Y | Y | Y | Y | | | |
-| `PROMPT_CACHING` | Y | Y | Y | | | | |
-| `TOKEN_USAGE` | Y | Y | Y | Y | Y | Y | Y |
+Each runtime declares capabilities via `AiCapability`. The framework uses
+these flags for model routing, tool negotiation, and feature discovery. The
+table below mirrors the nine-runtime snapshot pinned by each runtime's
+`expectedCapabilities()` contract test; `Y` means the runtime declares the
+capability and the contract tests assert it.
+
+Legend: TS=TEXT_STREAMING, TC=TOOL_CALLING, SO=STRUCTURED_OUTPUT,
+SP=SYSTEM_PROMPT, AO=AGENT_ORCHESTRATION, CM=CONVERSATION_MEMORY,
+TA=TOOL_APPROVAL, V=VISION, A=AUDIO, MM=MULTI_MODAL, PC=PROMPT_CACHING,
+TU=TOKEN_USAGE, PRR=PER_REQUEST_RETRY, TCD=TOOL_CALL_DELTA,
+BE=BUDGET_ENFORCEMENT, CS=CONFIDENCE_SCORES, PSV=PASSIVATION.
+
+| Runtime | Priority | TS | TC | SO | SP | AO | CM | TA | V | A | MM | PC | TU | PRR | TCD | BE | CS | PSV |
+|---------|---------:|:--:|:--:|:--:|:--:|:--:|:--:|:--:|:-:|:-:|:--:|:--:|:--:|:--:|:--:|:--:|:--:|:--:|
+| Built-in | 0 | Y | Y | Y | Y |  | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y |
+| Spring AI | 100 | Y | Y | Y | Y |  | Y | Y | Y | Y | Y | Y | Y | Y |  | Y | Y | Y |
+| LangChain4j | 100 | Y | Y | Y | Y |  | Y | Y | Y | Y | Y | Y | Y | Y |  | Y | Y | Y |
+| Google ADK | 100 | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y |  | Y | Y | Y |
+| Embabel | 100 | Y | Y | Y | Y | Y | Y | Y | Y |  | Y |  | Y | Y |  | Y | Y | Y |
+| JetBrains Koog | 100 | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y |  | Y | Y | Y |
+| Alibaba AgentScope | 100 | Y |  | Y | Y |  | Y |  |  |  |  |  | Y | Y |  | Y | Y | Y |
+| Spring AI Alibaba | 100 | Y¹ |  | Y | Y |  | Y |  |  |  |  |  |  | Y |  | Y² | Y | Y |
+| Microsoft Semantic Kernel | 100 | Y | Y | Y | Y |  | Y | Y |  |  |  |  | Y | Y |  | Y | Y | Y |
+
+¹ Spring AI Alibaba emits its final reply as one Atmosphere stream chunk, but
+the upstream `ReactAgent.call()` path is buffered rather than token-by-token.
+
+² Spring AI Alibaba participates in wall-clock budget enforcement. Token and
+step budget breaches require token-usage metadata, which that SDK path does not
+surface today.
 
 **How structured output works:** `AiPipeline` wraps the streaming session with `StructuredOutputCapturingSession` and augments the system prompt with JSON-schema instructions before the runtime runs. Any runtime that honors `SYSTEM_PROMPT` therefore gets `STRUCTURED_OUTPUT` automatically via the pipeline — no per-runtime adapter code required. `BuiltInAgentRuntime` additionally enables native `jsonMode` on the OpenAI-compatible client for provider-level JSON enforcement on top of the pipeline wrap. Source: `modules/ai/src/main/java/org/atmosphere/ai/pipeline/AiPipeline.java:128-135`, `modules/ai/src/main/java/org/atmosphere/ai/llm/BuiltInAgentRuntime.java:72-74`.
 
-**Capability gaps:**
-- `EmbabelAgentRuntime` does not advertise `TOOL_CALLING`: Embabel agents expose skills via their own `@Agent` API, not free-form tool calling. Source: `modules/embabel/src/main/kotlin/org/atmosphere/embabel/EmbabelAgentRuntime.kt`.
-
-### Experimental
-
-| Capability | Built-in | LangChain4j | Spring AI | ADK | Embabel | Koog | SK |
-|-----------|----------|-------------|-----------|-----|---------|------|----|
-| `AGENT_ORCHESTRATION` | | | | Y | Y | Y | |
+**Capability gaps:** AgentScope and Spring AI Alibaba do not declare
+`TOOL_CALLING` or `TOOL_APPROVAL` because their current SDK surfaces do not
+provide a native tool-dispatch loop that maps cleanly to Atmosphere's
+`@AiTool` protocol. Spring AI Alibaba also omits `TOKEN_USAGE` because
+`ReactAgent.call()` returns an `AssistantMessage` without usage metadata.
 
 ## Cross-Runtime Contract Tests (TCK)
 
@@ -688,7 +691,7 @@ Add `atmosphere-ai-test` as a test dependency and extend the base class:
 </dependency>
 ```
 
-The `RecordingSession` test double captures all events, text chunks, metadata, and errors for assertion. Currently enforced on: ADK, LangChain4j, Spring AI.
+The `RecordingSession` test double captures all events, text chunks, metadata, and errors for assertion. The contract suite is implemented for all nine runtime adapters.
 
 ## Samples
 

docs/src/content/docs/tutorial/04-transports.md

@@ -204,7 +204,7 @@ The client attaches the following headers (or query parameters) to every request
 
 | Header / Query Param | Description |
 |----------------------|-------------|
-| `X-Atmosphere-Framework` | The Atmosphere client version (e.g., `5.0.22`) |
+| `X-Atmosphere-Framework` | The Atmosphere client version (e.g., `5.0.24`) |
 | `X-Atmosphere-Transport` | The transport in use: `webtransport`, `websocket`, `sse`, `long-polling`, `streaming`, or `close` |
 | `X-Atmosphere-tracking-id` | A UUID that uniquely identifies this client. Initially `0`; the server assigns the real value on first response |
 | `X-Cache-Date` | Timestamp for cache coordination |
@@ -220,7 +220,7 @@ The client attaches the following headers (or query parameters) to every request
 A typical first request on the wire looks like:
 
 ```
-GET /chat?X-Atmosphere-tracking-id=0&X-Atmosphere-Framework=5.0.22
+GET /chat?X-Atmosphere-tracking-id=0&X-Atmosphere-Framework=5.0.24
     &X-Atmosphere-Transport=websocket&X-atmo-protocol=true HTTP/1.1
 Host: localhost:8080
 ```

docs/src/content/docs/tutorial/09-ai-endpoint.md

@@ -617,17 +617,30 @@ Three built-in providers are available:
 | `SpringAiVectorStoreContextProvider` | `atmosphere-rag` | Bridges Spring AI vector stores |
 | `LangChain4jEmbeddingStoreContextProvider` | `atmosphere-rag` | Bridges LangChain4j retrievers |
 
-The `ContextProvider` SPI supports query transformation and reranking:
+The `ContextProvider` SPI supports the full RAG shaping pipeline:
 
 ```java
 public interface ContextProvider {
     List<Document> retrieve(String query, int maxResults);
+
     default String transformQuery(String originalQuery) { return originalQuery; }
+    default List<Document> filter(String query, List<Document> documents) { return documents; }
     default List<Document> rerank(String query, List<Document> documents) { return documents; }
+    default List<Document> postProcess(String query, List<Document> documents) { return documents; }
+
+    static String formatCitation(Document document) { ... }
 }
 ```
 
-Execution order: `transformQuery()` -> `retrieve()` -> `rerank()` -> inject into `AiRequest.message`.
+Execution order: `transformQuery()` -> normalize/blank-query guard ->
+`retrieve()` -> `filter()` -> `rerank()` -> `postProcess()` ->
+`formatCitation()` -> inject into `AiRequest.message`.
+
+`formatCitation()` includes source and chunk metadata when present:
+`source_document`, `chunk_index`, `chunk_count`, `chunk_start`, and
+`chunk_end`. The Spring Boot RAG Chat sample preserves that metadata when it
+chunks its Markdown knowledge base, so citations point to a source passage
+instead of only naming the whole file.
 
 ## Client Integration
 

docs/src/content/docs/tutorial/26-foundation-primitives.md

@@ -163,5 +163,5 @@ HTTP request ─► AiEndpointHandler ─► AiStreamingSession ─► AgentRunt
   autonomous ramp.
 - [Durable HITL Workflows](./24-durable-hitl) — @RequiresApproval that
   survives a process restart.
-- [AI Adapters](./11-ai-adapters) — the seven `AgentRuntime`
+- [AI Adapters](./11-ai-adapters) — the nine `AgentRuntime`
   implementations and their capability matrix.

docs/src/content/docs/whats-new.md

@@ -13,7 +13,7 @@ pluggable AI runtimes, orchestration primitives, WebTransport/HTTP3, React Nativ
 support, and major compatibility refreshes.
 
 The latest build tracks **Spring Boot 4.0.6**, **Quarkus 3.35.2**,
-**Jackson 3.1.1**, and **atmosphere.js 5.0.22**, and requires **JDK 21** as a minimum.
+**Jackson 3.1.1**, and **atmosphere.js 5.0.24**, and requires **JDK 21** as a minimum.
 
 This page is a highlights reel. For the per-patch history, see the
 [CHANGELOG](https://github.com/Atmosphere/atmosphere/blob/main/CHANGELOG.md).
@@ -133,9 +133,13 @@ This page is a highlights reel. For the per-patch history, see the
 - **`StructuredOutputParser` SPI** — generate JSON Schema instructions from Java
   classes, parse LLM output into typed objects. `JacksonStructuredOutputParser`
   works with any model.
-- **Enhanced RAG** — `ContextProvider.transformQuery()` and `rerank()` enable
-  query rewriting and result re-ranking without a custom pipeline;
-  `InMemoryContextProvider` gives a zero-dependency provider for development.
+- **Enhanced RAG** — `ContextProvider.transformQuery()`, `filter()`,
+  `rerank()`, and `postProcess()` cover query rewriting, metadata/tenant
+  filtering, result re-ranking, and final context shaping without a custom
+  pipeline. Prompt injection uses `ContextProvider.formatCitation()` so chunk
+  metadata (`source_document`, `chunk_index`, `chunk_start`, `chunk_end`) is
+  visible to the model; `InMemoryContextProvider` gives a zero-dependency
+  provider for development.
 - **First-class identity fields** — `AiRequest` carries `userId`, `sessionId`,
   `agentId`, and `conversationId` as explicit fields instead of an untyped
   `hints()` map.
@@ -400,15 +404,15 @@ the wire surfaces, samples, and CI gates that make it adoptable. See the
 
 ## Client Libraries
 
-- **atmosphere.js 5.0.22** — TypeScript client with no runtime dependencies.
+- **atmosphere.js 5.0.24** — TypeScript client with no runtime dependencies.
   ESM + CJS + IIFE bundles, WebSocket with configurable fallback to SSE, HTTP
   streaming, or long-polling. See [atmosphere.js](/docs/clients/javascript/).
 - **React, Vue, Svelte hooks** — `useAtmosphere`, `useRoom`, `usePresence`,
-  `useStreaming` via `atmosphere.js/react`, `/vue`, and `/svelte`. Shared chat
-  components via `atmosphere.js/chat`.
-- **React Native / Expo** — `useAtmosphere` React Native hook with an
-  `EventSource` polyfill, NetInfo injection, and markdown rendering for mobile
-  AI chat. See [React Native](/docs/clients/react-native/).
+  `useStreaming`, and AI-SDK-style chat state via `useChat` /
+  `createChatStore`. Shared chat components ship through `atmosphere.js/chat`.
+- **React Native / Expo** — `useAtmosphereRN`, `useStreamingRN`, and
+  `useChatRN` with an `EventSource` polyfill, NetInfo injection, and markdown
+  rendering for mobile AI chat. See [React Native](/docs/clients/react-native/).
 - **wAsync 4.0** — the Java client rewritten on `java.net.http` with gRPC
   support. See [Java Client](/docs/clients/java/).