create-qpq-app 0.1.5

package/template/docusaurus/docs/actions/features/event-doc-ai/ask-event-doc-ai-load-chats.md

@@ -0,0 +1,37 @@
+---
+title: askEventDocAiLoadChats
+description: Client story — load the current document's chat list into UI state, with loading and error flags.
+---
+
+# askEventDocAiLoadChats
+
+Client-side story that loads the current document's chats and pushes them into the chat SPA's state. It flips the "loading chats" flag, issues [askEventDocAiChatListRequest](./ask-event-doc-ai-chat-requests.md), and dispatches either the chat list or an error message. The document scope comes from the [eventDocAi context](./ask-event-doc-ai-context-read.md) provided around the chat panel.
+
+This is one of the four client stories also exposed as `sharedEventDocAiApi`. It drives UI state through the `askUIEventDocAi*` actions (documented separately).
+
+- Built from [askCatch](../../core/system/ask-catch.md), [askEventDocAiChatListRequest](./ask-event-doc-ai-chat-requests.md), and the `askUIEventDocAiSetChats` / `askUIEventDocAiSetLoadingChats` / `askUIEventDocAiSetError` UI actions.
+
+```typescript
+import { askEventDocAiLoadChats } from 'quidproquo-features';
+
+export function* askOnChatPanelOpen() {
+  yield* askEventDocAiLoadChats();
+}
+```
+
+## Signature
+
+```typescript
+function* askEventDocAiLoadChats(): AskResponse<void>;
+```
+
+## Returns
+
+`void`. On success the chat list is dispatched to state via `askUIEventDocAiSetChats`; on failure the error text is dispatched via `askUIEventDocAiSetError`. The loading flag is cleared either way (passed as `askCatch`'s finally story).
+
+## Related
+
+- [askEventDocAiChatListRequest](./ask-event-doc-ai-chat-requests.md) — the request it issues.
+- [askEventDocAiNewChat](./ask-event-doc-ai-new-chat.md) / [askEventDocAiSelectChat](./ask-event-doc-ai-select-chat.md) / [askEventDocAiSendMessage](./ask-event-doc-ai-send-message.md) — the sibling client stories.
+- [askEventDocAiContextRead](./ask-event-doc-ai-context-read.md) — supplies the document scope.
+- [defineEventDocAi](../../../config/features/event-doc-ai.md) — the feature these chats belong to.

package/template/docusaurus/docs/actions/features/event-doc-ai/ask-event-doc-ai-new-chat.md

@@ -0,0 +1,43 @@
+---
+title: askEventDocAiNewChat
+description: Client story — create a new chat for the current document and make it the active, empty conversation.
+---
+
+# askEventDocAiNewChat
+
+Client-side story that creates a new chat for the current document and switches the UI to it. It issues [askEventDocAiChatCreateRequest](./ask-event-doc-ai-chat-requests.md), then upserts the new chat into the list, marks it active, clears the message view, and clears any live stream. Returns the created summary (or `null` on failure).
+
+One of the four client stories exposed as `sharedEventDocAiApi`.
+
+- Built from [askCatch](../../core/system/ask-catch.md), [askEventDocAiChatCreateRequest](./ask-event-doc-ai-chat-requests.md), and the `askUIEventDocAiUpsertChat` / `askUIEventDocAiSetActiveChat` / `askUIEventDocAiSetMessages` / `askUIEventDocAiClearStream` / `askUIEventDocAiSetError` UI actions.
+
+```typescript
+import { askEventDocAiNewChat } from 'quidproquo-features';
+
+export function* askOnNewChatClicked() {
+  const chat = yield* askEventDocAiNewChat();
+  if (chat) {
+    // chat.chatId is now the active conversation
+  }
+}
+```
+
+## Signature
+
+```typescript
+function* askEventDocAiNewChat(): AskResponse<Nullable<EventDocAiChatSummary>>;
+```
+
+## Returns
+
+`Nullable<EventDocAiChatSummary>` — the created chat summary, or `null` if creation failed (in which case the error text is dispatched via `askUIEventDocAiSetError`). On success it also dispatches: upsert the chat into the list, set it active, empty the message list, and clear the stream buffer.
+
+## Notes
+
+- [askEventDocAiSendMessage](./ask-event-doc-ai-send-message.md) calls this implicitly when the user sends the first message with no chat selected.
+
+## Related
+
+- [askEventDocAiChatCreateRequest](./ask-event-doc-ai-chat-requests.md) — the request it issues.
+- [askEventDocAiLoadChats](./ask-event-doc-ai-load-chats.md) / [askEventDocAiSelectChat](./ask-event-doc-ai-select-chat.md) / [askEventDocAiSendMessage](./ask-event-doc-ai-send-message.md) — the sibling client stories.
+- [defineEventDocAi](../../../config/features/event-doc-ai.md) — the feature these chats belong to.

package/template/docusaurus/docs/actions/features/event-doc-ai/ask-event-doc-ai-process-send.md

@@ -0,0 +1,70 @@
+---
+title: askEventDocAiProcessSend
+description: The backend chat turn — persist the user message, stream the model's reply to the UI, fold it into durable segments, and save.
+---
+
+# askEventDocAiProcessSend
+
+Runs one conversational turn on the backend. It appends the user's message to the chat history, streams the assistant's reply through [askAiPromptStream](../../core/ai/ask-ai-prompt-stream.md) — dispatching each stream part to the browser live — then folds the completed reply into durable segments, saves it, and bumps the chat to the top of the list. This is the handler behind the `ChatSend` websocket method (`onChatSend`).
+
+- Built from [askConfigGetGlobal](../../core/config/ask-config-get-global.md), [askAiPromptStream](../../core/ai/ask-ai-prompt-stream.md), [askStreamMap](../../core/stream/ask-stream-map.md), the history/list helpers, and the `askUIEventDocAi*` stream dispatches.
+
+```typescript
+import { askEventDocAiProcessSend } from 'quidproquo-features';
+
+// From the ChatSend handler — docId is read from the trusted session context.
+export function* askOnSend(docId: string, chatId: string, message: string) {
+  return yield* askEventDocAiProcessSend(docId, chatId, message);
+}
+```
+
+## Signature
+
+```typescript
+function* askEventDocAiProcessSend(
+  docId: string,
+  chatId: string,
+  message: string,
+  attachments?: EventDocAiAttachment[],
+): AskResponse<EventDocAiChatSendResult>;
+```
+
+## Parameters
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| `docId` | `string` | – | The trusted document the chat is scoped to (from session context). |
+| `chatId` | `string` | – | The chat to append this turn to. |
+| `message` | `string` | – | The user's message text. |
+| `attachments` | `EventDocAiAttachment[]` | `[]` | Document assets to attach — each `{ assetId, filename, mediaType }`. Validated against `docId` before the model sees them. |
+
+## Returns
+
+`EventDocAiChatSendResult` — `{ complete: true }`. The reply content is **not** in the return value; it is delivered to the UI during the turn via state dispatches (see below).
+
+## What one turn does
+
+1. Reads the AI name, model, and reasoning budget from the feature's globals, and resolves the system prompt — freshest source first: the configured `systemPromptGenerator` inline function (run per-turn with `{ docId }` so it can carry live document state), else the static `systemPrompt`, else a built-in default. The prompt is never persisted.
+2. [Validates the attachments](./ask-event-doc-ai-attachments-validate.md) against the document's storage drive and trusted `docId`.
+3. Loads the chat history, appends the new user message (attachments first, then text), and **saves** immediately — so a refresh mid-reply still shows the question.
+4. Streams the reply with [askAiPromptStream](../../core/ai/ask-ai-prompt-stream.md). File segments in the history become drive-referenced file parts (no URLs), which the action processor resolves to contents at prompt time. Tools do **not** receive `docId` from the model — executors inherit the session context and read the trusted id there.
+5. Maps over the stream with [askStreamMap](../../core/stream/ask-stream-map.md), dispatching each part to the UI as it arrives (the live typing view) and collecting the parts.
+6. Folds the collected parts into durable segments (`text`/`reasoning` deltas merged, tool calls paired with results). A stream that produced no content (e.g. it errored before any text) saves no assistant message.
+7. If there are segments, **saves** the finalized assistant message, dispatches it to the UI as the finalized message, then clears the UI's now-superseded live-stream buffer.
+8. Touches the chat (bumps `updatedAt`) and returns `{ complete: true }`.
+
+Steps 5–7 use the `askUIEventDocAiAppendStreamChunk`, `askUIEventDocAiAppendChatMessage`, and `askUIEventDocAiClearStream` UI actions — the client renders the reply from those dispatches while this request is still in flight, then reconciles to the finalized message.
+
+## The chat model
+
+Stream parts are **transport-only** — the raw `AiStreamPart`s dispatched live never persist. Only the folded `EventDocAiMessageSegment[]` are written to the chat's history file. A chat's messages are therefore always in the durable segment form (`text`, `reasoning`, `file`, `tool-use`), while the "typing" experience is a separate stream of parts the UI buffers and then discards once the finalized message arrives.
+
+## Related
+
+- [askAiPromptStream](../../core/ai/ask-ai-prompt-stream.md) — the streamed prompt this drives; [askStreamMap](../../core/stream/ask-stream-map.md) consumes it.
+- [askEventDocAiAttachmentsValidate](./ask-event-doc-ai-attachments-validate.md) — the attachment guard.
+- [askEventDocAiChatHistoryLoad / Save](./ask-event-doc-ai-chat-history-load.md) — the history read/write.
+- [askEventDocAiChatTouch](./ask-event-doc-ai-chat-list.md) — bumps the chat afterwards.
+- [askEventDocAiChatSendRequest](./ask-event-doc-ai-chat-requests.md) — the frontend request this handles.
+- [askEventDocAiSendMessage](./ask-event-doc-ai-send-message.md) — the client story that issues the send.
+- [defineEventDocAi](../../../config/features/event-doc-ai.md) — configures the model, prompt, tools, and reasoning budget this reads.

package/template/docusaurus/docs/actions/features/event-doc-ai/ask-event-doc-ai-select-chat.md

@@ -0,0 +1,42 @@
+---
+title: askEventDocAiSelectChat
+description: Client story — switch the active chat and load its message history into UI state.
+---
+
+# askEventDocAiSelectChat
+
+Client-side story that makes a chat active and loads its history. It immediately marks the chat active and clears the message + stream views (so the UI switches instantly), sets the "loading history" flag, then issues [askEventDocAiChatHistoryRequest](./ask-event-doc-ai-chat-requests.md) and dispatches the loaded messages — or an error.
+
+One of the four client stories exposed as `sharedEventDocAiApi`.
+
+- Built from [askCatch](../../core/system/ask-catch.md), [askEventDocAiChatHistoryRequest](./ask-event-doc-ai-chat-requests.md), and the `askUIEventDocAiSetActiveChat` / `askUIEventDocAiSetMessages` / `askUIEventDocAiClearStream` / `askUIEventDocAiSetLoadingHistory` / `askUIEventDocAiSetError` UI actions.
+
+```typescript
+import { askEventDocAiSelectChat } from 'quidproquo-features';
+
+export function* askOnChatPicked(chatId: string) {
+  yield* askEventDocAiSelectChat(chatId);
+}
+```
+
+## Signature
+
+```typescript
+function* askEventDocAiSelectChat(chatId: string): AskResponse<void>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `chatId` | `string` | The chat to switch to and load history for. |
+
+## Returns
+
+`void`. On success the chat's messages are dispatched via `askUIEventDocAiSetMessages`; on failure the error text is dispatched via `askUIEventDocAiSetError`. The loading flag is cleared either way.
+
+## Related
+
+- [askEventDocAiChatHistoryRequest](./ask-event-doc-ai-chat-requests.md) — the request it issues.
+- [askEventDocAiLoadChats](./ask-event-doc-ai-load-chats.md) / [askEventDocAiNewChat](./ask-event-doc-ai-new-chat.md) / [askEventDocAiSendMessage](./ask-event-doc-ai-send-message.md) — the sibling client stories.
+- [defineEventDocAi](../../../config/features/event-doc-ai.md) — the feature these chats belong to.

package/template/docusaurus/docs/actions/features/event-doc-ai/ask-event-doc-ai-send-message.md

@@ -0,0 +1,52 @@
+---
+title: askEventDocAiSendMessage
+description: Client story — send a chat message and stream the assistant's reply into UI state, creating a chat implicitly if none is active.
+---
+
+# askEventDocAiSendMessage
+
+Client-side story that sends a user message and drives the streamed reply into UI state. If no chat is active it creates one implicitly via [askEventDocAiNewChat](./ask-event-doc-ai-new-chat.md). It optimistically appends the user message, flips the "sending" flag, and issues [askEventDocAiChatSendRequest](./ask-event-doc-ai-chat-requests.md) — the assistant's reply streams in through `askUIEventDocAiAppendStreamChunk` dispatches while the request is in flight, and the finalized message is dispatched by the backend before the request resolves.
+
+The primary entry point a chat composer calls. One of the four client stories exposed as `sharedEventDocAiApi`.
+
+- Built from [askCatch](../../core/system/ask-catch.md), [askStateRead](../../core/state/ask-state-read.md), [askEventDocAiNewChat](./ask-event-doc-ai-new-chat.md), [askEventDocAiChatSendRequest](./ask-event-doc-ai-chat-requests.md), and the `askUIEventDocAiAppendChatMessage` / `askUIEventDocAiClearStream` / `askUIEventDocAiSetSending` / `askUIEventDocAiSetError` UI actions.
+
+```typescript
+import { askEventDocAiSendMessage } from 'quidproquo-features';
+
+export function* askOnComposerSubmit(text: string) {
+  yield* askEventDocAiSendMessage(text);
+}
+```
+
+## Signature
+
+```typescript
+function* askEventDocAiSendMessage(
+  message: string,
+  attachments?: EventDocAiAttachment[],
+): AskResponse<void>;
+```
+
+## Parameters
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| `message` | `string` | – | The user's message text. |
+| `attachments` | `EventDocAiAttachment[]` | `[]` | Document assets to attach — each `{ assetId, filename, mediaType }`. Presented to the model attachments-first, then the text. |
+
+## Returns
+
+`void`. Behaviour:
+
+- Reads `activeChatId` from state ([askStateRead](../../core/state/ask-state-read.md)); if there is none, creates a chat with [askEventDocAiNewChat](./ask-event-doc-ai-new-chat.md) and aborts silently if creation fails.
+- Clears any prior error, optimistically appends the user message, clears the stream buffer, and sets the sending flag.
+- Issues [askEventDocAiChatSendRequest](./ask-event-doc-ai-chat-requests.md); the reply streams in via UI dispatches during the request. On failure the error text is dispatched via `askUIEventDocAiSetError`. The sending flag and stream buffer are cleared afterwards.
+
+## Related
+
+- [askEventDocAiChatSendRequest](./ask-event-doc-ai-chat-requests.md) — the request it issues.
+- [askEventDocAiProcessSend](./ask-event-doc-ai-process-send.md) — the backend turn that produces the streamed reply.
+- [askEventDocAiNewChat](./ask-event-doc-ai-new-chat.md) — created implicitly when no chat is active.
+- [askEventDocAiLoadChats](./ask-event-doc-ai-load-chats.md) / [askEventDocAiSelectChat](./ask-event-doc-ai-select-chat.md) — the sibling client stories.
+- [defineEventDocAi](../../../config/features/event-doc-ai.md) — the feature these chats belong to.

package/template/docusaurus/docs/actions/features/event-doc-ai/ask-event-doc-ai-service-request.md

@@ -0,0 +1,53 @@
+---
+title: askEventDocAiServiceRequest
+description: The frontend transport wrapper for eventDocAi — routes a chat method to the service and relays the trusted docId over the wire.
+---
+
+# askEventDocAiServiceRequest
+
+The caller-side transport wrapper every eventDocAi chat request goes through. It reads the [eventDocAi context](./ask-event-doc-ai-context-read.md) (provided around the chat UI), builds the type-scoped method key, and issues a webserver service request — relaying the `docId` as a payload field so routing and the document id never appear in composites or call sites.
+
+You rarely call this directly; the four chat [request builders](./ask-event-doc-ai-chat-requests.md) wrap it with their own payload/response types. Reach for it only when adding a new eventDocAi method.
+
+- Built from webserver `askServiceRequest`; reads context via [askEventDocAiContextRead](./ask-event-doc-ai-context-read.md).
+
+```typescript
+import { askEventDocAiServiceRequest } from 'quidproquo-features';
+
+// How a request builder uses it (payload/response typed by the caller):
+export function* askMyEventDocAiMethod(payload: MyPayload) {
+  return yield* askEventDocAiServiceRequest<MyPayload, MyResponse>('MyMethod', payload);
+}
+```
+
+## Signature
+
+```typescript
+function* askEventDocAiServiceRequest<TPayload, TResponse>(
+  method: string,
+  payload: TPayload,
+): AskResponse<TResponse>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `method` | `string` | The method verb (e.g. `'ChatSend'`). Combined with the context `type` by `buildEventDocAiMethodName` into `eventDocAi/<type>/<method>` — the same key `defineEventDocAi` registers its queue processors under. |
+| `payload` | `TPayload` | The request payload. The wrapper appends a `docId` field (`EventDocAiDocRef`) read from context before sending, so payload models stay `docId`-free. |
+
+## Returns
+
+`TResponse` — the handler's response, passed straight back.
+
+## Notes
+
+- The `serviceName`, `type`, and `docId` all come from [askEventDocAiContextRead](./ask-event-doc-ai-context-read.md) — the chat UI provides them once around the panel, so no request call site carries them.
+- The backend handler wrapper (`eventDocAiServiceRequest`, internal to the feature) strips the relayed `docId` back off the wire payload and re-provides it as context around the handler, keeping payload models `docId`-free on both sides.
+- Routing uses the webserver `askServiceRequest` over the collection's websocket queue declared by [defineEventDocAi](../../../config/features/event-doc-ai.md).
+
+## Related
+
+- [Chat request builders](./ask-event-doc-ai-chat-requests.md) — the four typed methods that wrap this.
+- [askEventDocAiContextRead](./ask-event-doc-ai-context-read.md) — supplies the routing values and `docId` this relays.
+- [defineEventDocAi](../../../config/features/event-doc-ai.md) — registers the matching queue processors.

package/template/docusaurus/docs/actions/features/event-doc-ai/chat-list-state.md

@@ -0,0 +1,179 @@
+---
+title: Event Doc AI chat list state
+description: UI state setters for the Event Doc AI chat list and active-chat selection.
+---
+
+# Event Doc AI chat list state
+
+These `ask`-generators are **client-side UI state setters** for the Event Doc AI chat feature. They don't touch the network or any backend service — they run inside the browser SPA and mutate the in-memory `EventDocAiState` so the chat UI re-renders. This page covers the four setters that manage the **chat list** (the collection of a user's chats for an eventDoc) and which chat is currently selected.
+
+Each setter dispatches a typed **effect** through the core State action processors: internally it calls `askStateDispatchEffect` → `askStateDispatch`, which the SPA's state runtime folds into `EventDocAiState` via `eventDocAiReducer` (a `buildEffectReducer` over `EventDocAiEffect`). In a browser SPA the State domain is wired through the client state store (see `defineStateDispatchOverWebsockets` / `askStateDispatch` in `quidproquo-core`), so a `yield*` here is a synchronous, local state update — not a round-trip. Every setter returns `AskResponse<void>`.
+
+## State shape
+
+All setters on this page mutate one shared object:
+
+```typescript
+type EventDocAiState = {
+  chats: EventDocAiChatSummary[];
+  activeChatId: Nullable<string>;
+
+  chatMessages: EventDocAiChatMessage[];
+  streamParts: AiStreamPart[];
+
+  isLoadingChats: boolean;
+  isLoadingHistory: boolean;
+  isSending: boolean;
+  error: Nullable<string>;
+};
+```
+
+An `EventDocAiChatSummary` is one row in the chat list:
+
+```typescript
+type EventDocAiChatSummary = {
+  docId: string;
+  chatId: string;
+  name: string;
+  createdAt: QpqIsoDateTime;
+  updatedAt: QpqIsoDateTime;
+  createdByUserId: string;
+};
+```
+
+---
+
+## askUIEventDocAiSetChats
+
+Replaces the entire chat list — typically called after loading the list from the backend.
+
+- **Effect:** `EventDocAiEffect.SetChats`
+- **State change:** sets `chats` to the provided array (wholesale replace).
+
+```typescript
+import { askUIEventDocAiSetChats } from 'quidproquo-features';
+import type { EventDocAiChatSummary } from 'quidproquo-features';
+
+export function* onChatsLoaded(chats: EventDocAiChatSummary[]) {
+  yield* askUIEventDocAiSetChats(chats);
+}
+```
+
+### Signature
+
+```typescript
+function* askUIEventDocAiSetChats(
+  chats: EventDocAiChatSummary[],
+): AskResponse<void>;
+```
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `chats` | `EventDocAiChatSummary[]` | The full chat list to show. Overwrites whatever was in `chats`. |
+
+---
+
+## askUIEventDocAiUpsertChat
+
+Inserts or updates a single chat in the list without replacing the rest — used when a new chat is created or an existing one is renamed/touched.
+
+- **Effect:** `EventDocAiEffect.UpsertChat`
+- **State change:** removes any existing chat with the same `chatId`, then prepends the provided chat — so `chats` stays de-duplicated and the upserted chat moves to the front of the list.
+
+```typescript
+import { askUIEventDocAiUpsertChat } from 'quidproquo-features';
+import type { EventDocAiChatSummary } from 'quidproquo-features';
+
+export function* onChatCreated(chat: EventDocAiChatSummary) {
+  yield* askUIEventDocAiUpsertChat(chat);
+}
+```
+
+### Signature
+
+```typescript
+function* askUIEventDocAiUpsertChat(
+  chat: EventDocAiChatSummary,
+): AskResponse<void>;
+```
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `chat` | `EventDocAiChatSummary` | The chat to insert or update, matched by `chatId`. Lands at the head of `chats`. |
+
+---
+
+## askUIEventDocAiSetActiveChat
+
+Selects (or clears) the currently open chat. This is the value the message pane keys off of.
+
+- **Effect:** `EventDocAiEffect.SetActiveChat`
+- **State change:** sets `activeChatId` to the given id, or `null` to deselect.
+
+```typescript
+import { askUIEventDocAiSetActiveChat } from 'quidproquo-features';
+
+export function* openChat(chatId: string) {
+  yield* askUIEventDocAiSetActiveChat(chatId);
+}
+
+export function* closeChat() {
+  yield* askUIEventDocAiSetActiveChat(null);
+}
+```
+
+### Signature
+
+```typescript
+function* askUIEventDocAiSetActiveChat(
+  chatId: Nullable<string>,
+): AskResponse<void>;
+```
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `chatId` | `Nullable<string>` | The `chatId` to make active, or `null` to clear the selection. |
+
+---
+
+## askUIEventDocAiSetLoadingChats
+
+Toggles the "loading the chat list" flag so the UI can show a spinner while the list is fetched.
+
+- **Effect:** `EventDocAiEffect.SetLoadingChats`
+- **State change:** sets `isLoadingChats`.
+
+```typescript
+import { askUIEventDocAiSetLoadingChats, askUIEventDocAiSetChats } from 'quidproquo-features';
+
+export function* loadChats() {
+  yield* askUIEventDocAiSetLoadingChats(true);
+  // ...fetch the list, then...
+  yield* askUIEventDocAiSetLoadingChats(false);
+}
+```
+
+### Signature
+
+```typescript
+function* askUIEventDocAiSetLoadingChats(
+  isLoading: boolean,
+): AskResponse<void>;
+```
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `isLoading` | `boolean` | `true` while the chat list is being fetched, `false` when done. |
+
+---
+
+## Returns
+
+Every setter on this page returns `AskResponse<void>` — the story resumes once the effect has been dispatched into the SPA's state store. There is no return value.
+
+## Related
+
+- [Event Doc AI active chat state](./active-chat-state.md) — messages of the selected chat.
+- [Event Doc AI streaming & status state](./streaming-and-status-state.md) — in-flight reply, sending, and error flags.
+
+These UI setters build on the core **State** domain (`askStateDispatch`, `askStateDispatchEffect`) and are consumed alongside the Event Doc AI backend stories — `defineEventDocAi` (config), and the chat request stories `askEventDocAiChatListRequest`, `askEventDocAiChatCreateRequest`, `askEventDocAiChatSendRequest`, and `askEventDocAiChatHistoryRequest`.

package/template/docusaurus/docs/actions/features/event-doc-ai/streaming-and-status-state.md

@@ -0,0 +1,168 @@
+---
+title: Event Doc AI streaming & status state
+description: UI state setters for the in-flight assistant stream, the sending flag, and errors.
+---
+
+# Event Doc AI streaming & status state
+
+These `ask`-generators are **client-side UI state setters** for the Event Doc AI chat feature. They run inside the browser SPA and mutate the in-memory `EventDocAiState` so the chat UI re-renders. This page covers the setters that drive the **live assistant reply** (`streamParts`), the **sending** flag, and the surfaced **error** message.
+
+Each setter dispatches a typed **effect** through the core State action processors: internally it calls `askStateDispatchEffect` → `askStateDispatch`, which the SPA's state runtime folds into `EventDocAiState` via `eventDocAiReducer` (a `buildEffectReducer` over `EventDocAiEffect`). In a browser SPA the State domain is wired through the client state store (see `defineStateDispatchOverWebsockets` / `askStateDispatch` in `quidproquo-core`), so a `yield*` here is a synchronous, local state update. Every setter returns `AskResponse<void>`.
+
+`streamParts` is the streaming-only buffer for the reply currently in flight. As `AiStreamPart`s arrive over the socket they're appended one by one; when the reply finishes, the client folds them into a finalized `EventDocAiChatMessage` (appended via [`askUIEventDocAiAppendChatMessage`](./active-chat-state.md)) and clears the buffer.
+
+## State shape
+
+```typescript
+type EventDocAiState = {
+  chats: EventDocAiChatSummary[];
+  activeChatId: Nullable<string>;
+
+  chatMessages: EventDocAiChatMessage[];
+  streamParts: AiStreamPart[];
+
+  isLoadingChats: boolean;
+  isLoadingHistory: boolean;
+  isSending: boolean;
+  error: Nullable<string>;
+};
+```
+
+`AiStreamPart` is the streaming-chunk union from `quidproquo-core` (text/reasoning deltas, file parts, tool-use events, finish markers, etc.).
+
+---
+
+## askUIEventDocAiAppendStreamChunk
+
+Appends one streaming chunk to the in-flight assistant reply. Called for each part received while a reply streams in.
+
+- **Effect:** `EventDocAiEffect.AppendStreamChunk`
+- **State change:** pushes `part` onto the end of `streamParts`.
+
+```typescript
+import { askUIEventDocAiAppendStreamChunk } from 'quidproquo-features';
+import type { AiStreamPart } from 'quidproquo-core';
+
+export function* onStreamPart(part: AiStreamPart) {
+  yield* askUIEventDocAiAppendStreamChunk(part);
+}
+```
+
+### Signature
+
+```typescript
+function* askUIEventDocAiAppendStreamChunk(
+  part: AiStreamPart,
+): AskResponse<void>;
+```
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `part` | `AiStreamPart` | A single streaming chunk of the in-flight reply, appended to `streamParts`. |
+
+---
+
+## askUIEventDocAiClearStream
+
+Clears the in-flight stream buffer — call this once the reply has been finalized into a chat message, or to discard a stream on error/cancel.
+
+- **Effect:** `EventDocAiEffect.ClearStream`
+- **State change:** resets `streamParts` to `[]`. Takes no arguments.
+
+```typescript
+import {
+  askUIEventDocAiAppendChatMessage,
+  askUIEventDocAiClearStream,
+} from 'quidproquo-features';
+import type { EventDocAiChatMessage } from 'quidproquo-features';
+
+export function* finalizeReply(reply: EventDocAiChatMessage) {
+  yield* askUIEventDocAiAppendChatMessage(reply);
+  yield* askUIEventDocAiClearStream();
+}
+```
+
+### Signature
+
+```typescript
+function* askUIEventDocAiClearStream(): AskResponse<void>;
+```
+
+Takes no parameters.
+
+---
+
+## askUIEventDocAiSetSending
+
+Toggles the "sending a message" flag so the composer can disable input and show a busy state while a turn is in flight.
+
+- **Effect:** `EventDocAiEffect.SetSending`
+- **State change:** sets `isSending`.
+
+```typescript
+import { askUIEventDocAiSetSending } from 'quidproquo-features';
+
+export function* sendTurn() {
+  yield* askUIEventDocAiSetSending(true);
+  // ...dispatch the send and await the reply, then...
+  yield* askUIEventDocAiSetSending(false);
+}
+```
+
+### Signature
+
+```typescript
+function* askUIEventDocAiSetSending(
+  isSending: boolean,
+): AskResponse<void>;
+```
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `isSending` | `boolean` | `true` while a message is being sent / a reply is streaming, `false` when idle. |
+
+---
+
+## askUIEventDocAiSetError
+
+Sets or clears the error message surfaced to the user (e.g. a failed send or load).
+
+- **Effect:** `EventDocAiEffect.SetError`
+- **State change:** sets `error` to the message, or `null` to clear it.
+
+```typescript
+import { askUIEventDocAiSetError } from 'quidproquo-features';
+
+export function* showError() {
+  yield* askUIEventDocAiSetError('Failed to send message. Please try again.');
+}
+
+export function* clearError() {
+  yield* askUIEventDocAiSetError(null);
+}
+```
+
+### Signature
+
+```typescript
+function* askUIEventDocAiSetError(
+  error: Nullable<string>,
+): AskResponse<void>;
+```
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `error` | `Nullable<string>` | The error text to display, or `null` to clear the current error. |
+
+---
+
+## Returns
+
+Every setter on this page returns `AskResponse<void>` — the story resumes once the effect has been dispatched into the SPA's state store. There is no return value.
+
+## Related
+
+- [Event Doc AI active chat state](./active-chat-state.md) — where a finished stream lands as a finalized message.
+- [Event Doc AI chat list state](./chat-list-state.md) — the chat list and active-chat selection.
+
+These UI setters build on the core **State** domain (`askStateDispatch`, `askStateDispatchEffect`) and are consumed alongside the Event Doc AI backend stories — `defineEventDocAi` (config) and `askEventDocAiChatSendRequest`. `AiStreamPart` comes from the core AI streaming domain (`askAiPromptStream`).

package/template/docusaurus/docs/actions/features/validation/_category_.json

@@ -0,0 +1 @@
+{ "label": "Validation", "link": { "type": "generated-index", "description": "Validation stories from quidproquo-features — validate models against a schema and fail with a catchable qpq error." } }