docs(persistence): reorganize persistence guides

Author: AlemTuzlak

docs/api/ai-angular.md

@@ -386,7 +386,7 @@ export class CustomGenerationComponent {
 **Returns:** `generate`, `result`, `isLoading`, `error`, `status`, `stop`, `reset`, `resume`, `resumeSnapshot`, `resumeState`, `pendingArtifacts`, `resultArtifacts` — all reactive state is a read-only `Signal<T>`.
 
 For the end-to-end persistence setup, see
-[Resumable Generations](../persistence/resumable-generations).
+[Generation Persistence](../persistence/generation-persistence).
 
 ### `injectGenerateImage(options)`
 

docs/api/ai-react.md

@@ -175,7 +175,7 @@ Generation hook returns include `generate`, `result`, `isLoading`, `error`,
 `jobId` and `videoStatus`.
 
 For the end-to-end persistence setup, see
-[Resumable Generations](../persistence/resumable-generations).
+[Generation Persistence](../persistence/generation-persistence).
 
 ## Example: Basic Chat
 

docs/api/ai-solid.md

@@ -138,7 +138,7 @@ so read `resumeState()` and `pendingArtifacts()`. Video generation also returns
 `jobId` and `videoStatus`.
 
 For the end-to-end persistence setup, see
-[Resumable Generations](../persistence/resumable-generations).
+[Generation Persistence](../persistence/generation-persistence).
 
 ## Connection Adapters
 

docs/api/ai-svelte.md

@@ -304,7 +304,7 @@ const gen = createGeneration({
 **Returns:** `generate`, `result`, `isLoading`, `error`, `status`, `stop`, `reset`, `updateBody`, `dispose`, `resume`, `resumeSnapshot`, `resumeState`, `pendingArtifacts`, `resultArtifacts` -- all state properties are reactive getters.
 
 For the end-to-end persistence setup, see
-[Resumable Generations](../persistence/resumable-generations).
+[Generation Persistence](../persistence/generation-persistence).
 
 ### `createGenerateImage(options)`
 

docs/api/ai-vue.md

@@ -321,7 +321,7 @@ const { generate, result, isLoading, error, status, stop, reset } =
 **Returns:** `generate`, `result`, `isLoading`, `error`, `status`, `stop`, `reset`, `resume`, `resumeSnapshot`, `resumeState`, `pendingArtifacts`, `resultArtifacts` -- all reactive state is `DeepReadonly<ShallowRef<T>>`. Read refs with `.value` in `<script setup>`.
 
 For the end-to-end persistence setup, see
-[Resumable Generations](../persistence/resumable-generations).
+[Generation Persistence](../persistence/generation-persistence).
 
 ### `useGenerateImage(options)`
 

docs/chat/connection-adapters.md

@@ -235,7 +235,7 @@ const { messages, sendMessage } = useChat({
 The fetcher receives `{ messages, data, threadId, runId, cursor, resume }` plus an `AbortSignal` (triggered by `stop()` or when a send is superseded). Forward `cursor` when replaying persisted public events, and forward `resume` when responding to pending AG-UI interrupts. Return a `Response` — whose SSE body the chat client parses for you — **or** an `AsyncIterable<StreamChunk>`, which is yielded directly. If your server function returns the stream itself (instead of wrapping it in a `Response`), the fetcher handles that too. Sync and `Promise`-wrapped returns are both accepted.
 
 For the server persistence path that produces those replay cursors, see
-[Resumable Chat](../persistence/resumable-chat).
+[Chat Persistence](../persistence/chat-persistence).
 
 > **Tip:** The choice between `fetcher` and [`stream()`](#server-functions-and-direct-async-iterables) is about **async vs sync**, not `Response`-vs-iterable — both can yield an `AsyncIterable<StreamChunk>`. `stream()`'s factory must return that iterable **synchronously**, so a server-function call (which returns a `Promise`) won't typecheck there — that's the gap `fetcher` fills ([issue #509](https://github.com/TanStack/ai/issues/509)). Use `stream()` when you can hand back an async iterable synchronously (in-process `chat()`, an RPC client, tests); use `fetcher` for anything you have to `await`. Both normalize to the same request-scoped adapter, so `stop()`/abort, error handling, and tool calls behave identically.
 
@@ -441,7 +441,7 @@ const { messages } = useChat({ connection: myAdapter });
 
 If the request-scoped adapter talks to a persisted `chat()` endpoint, those
 fields are the durable replay identity described in
-[Resumable Chat](../persistence/resumable-chat).
+[Chat Persistence](../persistence/chat-persistence).
 
 ## The Adapter Interface
 

docs/chat/persistence.md

@@ -19,8 +19,8 @@ This is especially useful for SPAs, Electron apps, and offline-first setups wher
 
 If your server owns the transcript and you need durable event replay after a
 reconnect or reload, use server-side persistence instead. See
-[Resumable Chat](../persistence/resumable-chat) for the full `withPersistence`
-server/client wiring.
+[Chat Persistence](../persistence/chat-persistence) for the full
+`withPersistence` server/client wiring.
 
 ## The adapter interface
 

docs/config.json

@@ -410,50 +410,63 @@
           "updatedAt": "2026-07-08"
         },
         {
-          "label": "Resumable Chat",
-          "to": "persistence/resumable-chat",
-          "addedAt": "2026-07-03",
-          "updatedAt": "2026-07-08"
+          "label": "Persistence Controls",
+          "to": "persistence/controls",
+          "addedAt": "2026-07-08"
         },
         {
-          "label": "Resumable Generations",
-          "to": "persistence/resumable-generations",
-          "addedAt": "2026-07-07",
-          "updatedAt": "2026-07-08"
+          "label": "Migrations",
+          "to": "persistence/migrations",
+          "addedAt": "2026-07-08"
         },
         {
-          "label": "Interrupts and Approvals",
-          "to": "persistence/interrupts-and-approvals",
+          "label": "Chat Persistence",
+          "to": "persistence/chat-persistence",
           "addedAt": "2026-07-03",
           "updatedAt": "2026-07-08"
         },
         {
-          "label": "SQL Backends",
-          "to": "persistence/sql-backends",
+          "label": "Sandbox Persistence",
+          "to": "persistence/sandbox-persistence",
           "addedAt": "2026-07-03",
           "updatedAt": "2026-07-08"
         },
+        {
+          "label": "Generation Persistence",
+          "to": "persistence/generation-persistence",
+          "addedAt": "2026-07-07",
+          "updatedAt": "2026-07-08"
+        },
+        {
+          "label": "MCP Persistence",
+          "to": "persistence/mcp-persistence",
+          "addedAt": "2026-07-08"
+        },
         {
           "label": "Cloudflare",
           "to": "persistence/cloudflare",
           "addedAt": "2026-07-03",
           "updatedAt": "2026-07-08"
         },
         {
-          "label": "Files and Artifacts",
-          "to": "persistence/files-and-artifacts",
-          "addedAt": "2026-07-06",
-          "updatedAt": "2026-07-08"
+          "label": "Prisma",
+          "to": "persistence/prisma",
+          "addedAt": "2026-07-08"
         },
         {
-          "label": "Custom Stores",
-          "to": "persistence/custom-stores",
+          "label": "Drizzle",
+          "to": "persistence/drizzle",
+          "addedAt": "2026-07-08"
+        },
+        {
+          "label": "SQL Backends",
+          "to": "persistence/sql-backends",
           "addedAt": "2026-07-03",
           "updatedAt": "2026-07-08"
         },
         {
-          "label": "Sandbox Runs",
-          "to": "persistence/sandbox-runs",
+          "label": "Custom Stores",
+          "to": "persistence/custom-stores",
           "addedAt": "2026-07-03",
           "updatedAt": "2026-07-08"
         }

docs/media/generation-hooks.md

@@ -63,7 +63,7 @@ The same pattern applies to all generation types -- swap `generateImage` for `ge
 
 For refresh-safe generation, wrap the server call with `withPersistence(...)`
 and parse hook requests with `generationParamsFromRequest(...)`. See
-[Resumable Generations](../persistence/resumable-generations) for the complete
+[Generation Persistence](../persistence/generation-persistence) for the complete
 server and client flow.
 
 ## useGenerateImage
@@ -434,7 +434,7 @@ Generation hooks do not store generated image, audio, speech, transcription, or
 video bytes in browser persistence. The client snapshot keeps only
 `{ threadId, runId, cursor }` plus lightweight artifact refs. Use server
 persistence artifacts when generated media must survive refresh:
-[Resumable Generations](../persistence/resumable-generations) shows the full
+[Generation Persistence](../persistence/generation-persistence) shows the full
 pattern.
 
 ### Result Transforms
@@ -519,4 +519,4 @@ All framework packages re-export `fetchServerSentEvents`, `fetchHttpStream`, and
 - [Transcription](./transcription) -- File formats, language detection, and word-level timestamps
 - [Video Generation](./video-generation) -- Job lifecycle, polling, and provider setup
 - [Generations Overview](./generations) -- Architecture and server-side streaming patterns
-- [Resumable Generations](../persistence/resumable-generations) -- Refresh-safe generation and persisted artifact refs
+- [Generation Persistence](../persistence/generation-persistence) -- Refresh-safe generation and persisted artifact refs

docs/persistence/resumable-chat.md docs/persistence/chat-persistence.mddocs/persistence/resumable-chat.md renamed to docs/persistence/chat-persistence.md

@@ -1,14 +1,15 @@
 ---
-title: Resumable Chat
-id: resumable-chat
+title: Chat Persistence
+id: chat-persistence
 ---
 
-Use server persistence when the server should be authoritative for a chat
-thread. The client may still keep local UI state, but the durable transcript,
-run status, and replayable event log live behind `withPersistence(...)`.
+Use chat persistence when the server should be authoritative for a thread. The
+client may keep local UI state, but the durable transcript, run status,
+replayable event log, and pending user decisions live behind
+`withPersistence(...)`.
 
 By the end, your endpoint accepts `{ threadId, runId, cursor, resume }`, writes
-each streamed chunk to durable storage, and lets the client resume after an
+streamed chunks to durable storage, and lets the client resume after an
 in-session disconnect or full page reload.
 
 ## Install a backend
@@ -51,17 +52,17 @@ export async function POST(request: Request) {
 }
 ```
 
-`withPersistence` loads the stored thread history, saves the resulting
-transcript, records run status, and appends every public AG-UI event with a
-cursor. When `cursor` is present, the run replays persisted events after that
-cursor instead of re-running the adapter.
+`withPersistence(...)` loads stored thread history, saves the resulting
+transcript, records run status, and appends every public AG-UI event with an
+opaque cursor. When `cursor` is present, the run replays persisted events after
+that cursor instead of re-running the adapter.
 
 ## Wire the client
 
 The chat client forwards the resume fields through its connection adapter. Keep
 a stable `threadId` per conversation so a reload returns to the same server
 thread. Use `persistence.server` to store the client's latest resume snapshot
-under that `threadId` so reloads can continue the same durable run.
+under that `threadId`.
 
 ```tsx
 import { fetchServerSentEvents, useChat } from '@tanstack/ai-react'
@@ -118,26 +119,27 @@ known `{ threadId, runId, cursor }`. Opt out with `autoResume: false`, or call
 `chat.resumeState` contains the active resume identity, or `null` when there is
 nothing to continue. `chat.pendingInterrupts` contains the client-side
 descriptors needed to answer pending user decisions. `persistence.server`
-stores them together and hydrates them on the next client construction. The
-server remains authoritative: the stored snapshot only tells the client which
-durable run to reconnect to and which pending interrupts it can answer.
+stores them together and hydrates them on the next client construction.
 
-## Client message storage is separate
+## Choose the controls you need
 
-Client-side chat persistence stores rendered `UIMessage` history in
-`localStorage`, IndexedDB, or another browser-side adapter. Server persistence
-stores model messages, run records, and replayable public events. You can use
-both with `persistence: { client, server }`, but they solve different problems.
-See [Chat Persistence](../chat/persistence) for client-only message storage.
+Use [Persistence Controls](./controls) when you want the decision table. For
+chat, these are the common combinations:
+
+| Goal | Controls |
+| --- | --- |
+| Browser-only drafts | `persistence.client` on the chat client. |
+| Server-owned transcript | `stores.messages` and `features: ['messages']`. |
+| Reconnect without re-running the model | `stores.runs`, `stores.publicEvents`, and `durable-replay`. |
+| Pending approvals or human input | `interrupts`, which also requires run and public-event stores. |
+| Multi-worker resume safety | Add `stores.locks` when a backend supports it. |
 
 ## Resume pending decisions
 
 If the server finishes with `RUN_FINISHED.outcome.type === 'interrupt'`, the
 thread has a pending user-actionable wait. Resolve those waits with
 `chat.resumeInterrupts(...)`; the client forwards them as AG-UI
-`RunAgentInput.resume[]` entries on the next request. If the page reloads
-before the user answers, `persistence.server` restores the pending interrupts
-the client needs to render and resume.
+`RunAgentInput.resume[]` entries on the next request.
 
 ```ts
 import type { UseChatReturn } from '@tanstack/ai-react'
@@ -153,5 +155,22 @@ await chat.resumeInterrupts([
 ])
 ```
 
-For approval-specific UI and compatibility details, see
-[Interrupts and Approvals](./interrupts-and-approvals).
+Normal new input on the same thread is rejected by default while pending
+interrupts exist. That keeps the server from accidentally creating a second
+conversation branch before the existing decision has been resolved or
+cancelled.
+
+Tool approvals are the common UI shape for interrupts. A tool with
+`needsApproval: true` can pause the run, surface an approval request, and resume
+after the user approves or denies it. For basic approval rendering without
+server persistence, see [Tool Approval Flow](../tools/tool-approval).
+
+## Keep client and server persistence separate
+
+Client-side chat persistence stores rendered `UIMessage` history in
+`localStorage`, IndexedDB, or another browser-side adapter. Server persistence
+stores model messages, run records, interrupts, and replayable public events.
+You can use both with `persistence: { client, server }`, but they solve
+different problems.
+
+For a narrow client-only page, see [Chat & Streaming Persistence](../chat/persistence).