create-qpq-app 0.1.5

package/template/docusaurus/docs/actions/features/event-doc/ask-event-doc-soft-delete.md

@@ -0,0 +1,69 @@
+---
+title: askEventDocSoftDelete
+description: Soft-delete an event document by stamping deletedAt, keeping its versions and assets intact.
+---
+
+# askEventDocSoftDelete
+
+Soft-deletes an event document by stamping `deletedAt` (and refreshing `updatedAt`/`updatedBy`) on its summary record. The document's versions and blob claims stay intact — nothing is destroyed — and [askEventDocList](./ask-event-doc-list.md) hides it by default. This is the **public** deletion path. Returns the updated [`EventDocSummary`](./ask-event-doc-get-by-id.md#the-summary-record).
+
+- **Built from:** [askEventDocGetByIdOrThrow](./ask-event-doc-get-by-id.md#askeventdocgetbyidorthrow) (loads the record, throwing `NotFound` if missing), then a validated [askEventDocUpsert](./ask-event-doc-create.md#askeventdocupsert). Requires the store context — call it inside `askEventDocProvideStore({ storeName, type }, ...)`.
+
+```typescript
+import { askEventDocSoftDelete } from 'quidproquo-features';
+
+export function* archiveArticle(id: string, userId: string) {
+  const summary = yield* askEventDocSoftDelete(id, userId);
+  return summary; // deletedAt is now set
+}
+```
+
+## Signature
+
+```typescript
+function* askEventDocSoftDelete(
+  id: string,
+  updatedBy: string,
+): AskResponse<EventDocSummary>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `id` | `string` | Id of the document to soft-delete. |
+| `updatedBy` | `string` | User id to record as having performed the deletion (written to `updatedBy`). |
+
+## Returns
+
+`EventDocSummary` — the updated record with `deletedAt` set to the deletion time.
+
+## Notes
+
+- Throws `ErrorTypeEnum.NotFound` (from quidproquo-core) when no document exists for `id`.
+- Soft-deleted rows are still returned by [askEventDocGetById](./ask-event-doc-get-by-id.md) (filtering is the caller's concern) and by [askEventDocList](./ask-event-doc-list.md) only when `includeDeleted: true`.
+
+---
+
+## askEventDocDelete
+
+**Hard delete** — permanently removes the document's summary row from the store. This is for internal cleanup/admin only; the public lifecycle uses soft delete (above). It does not touch the event log or the asset bucket, so a hard delete of the summary alone leaves orphaned events/assets — use deliberately.
+
+```typescript
+function* askEventDocDelete(id: string): AskResponse<void>;
+```
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `id` | `string` | Id of the document whose summary row to delete. |
+
+**Returns** `void`.
+
+Requires the store context. Prefer `askEventDocSoftDelete` for anything user-facing.
+
+## Related
+
+- [askEventDocGetByIdOrThrow](./ask-event-doc-get-by-id.md#askeventdocgetbyidorthrow) — the load-or-throw this composes.
+- [askEventDocList](./ask-event-doc-list.md) — hides soft-deleted documents by default.
+- [askEventDocCreate](./ask-event-doc-create.md) — the create counterpart.
+- [askDateNow](../../core/date/ask-date-now.md) — supplies the `deletedAt` timestamp.

package/template/docusaurus/docs/actions/features/event-doc-ai/_category_.json

@@ -0,0 +1 @@
+{ "label": "Event Doc AI", "link": { "type": "generated-index", "description": "Stories for the Event Doc AI chat feature — backend chat/history requests and the client-side UI state setters that drive the chat SPA." } }

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

@@ -0,0 +1,153 @@
+---
+title: Event Doc AI active chat state
+description: UI state setters for the messages of the currently open Event Doc AI chat.
+---
+
+# Event Doc AI active chat 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 message pane re-renders. This page covers the setters for the **finalized messages** of the active chat (`chatMessages`) and the flag that gates loading a chat's history.
+
+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>`.
+
+`chatMessages` holds only **finalized** turns. The live, in-flight assistant reply lives separately in `streamParts` (see [Event Doc AI streaming & status state](./streaming-and-status-state.md)) and is folded into a finalized message once the reply completes.
+
+## State shape
+
+```typescript
+type EventDocAiState = {
+  chats: EventDocAiChatSummary[];
+  activeChatId: Nullable<string>;
+
+  chatMessages: EventDocAiChatMessage[];
+  streamParts: AiStreamPart[];
+
+  isLoadingChats: boolean;
+  isLoadingHistory: boolean;
+  isSending: boolean;
+  error: Nullable<string>;
+};
+```
+
+An `EventDocAiChatMessage` is a finalized turn made of render-ready segments:
+
+```typescript
+type EventDocAiChatMessage = {
+  role: 'user' | 'assistant';
+  segments: EventDocAiMessageSegment[];
+};
+
+type EventDocAiMessageSegment =
+  | { type: 'text'; text: string }
+  | { type: 'reasoning'; text: string }
+  | { type: 'file'; attachment: EventDocAiAttachment }
+  | { type: 'tool-use'; tools: EventDocAiToolUse[] };
+```
+
+---
+
+## askUIEventDocAiSetMessages
+
+Replaces the active chat's message list wholesale — typically called after loading a chat's history, or when switching chats.
+
+- **Effect:** `EventDocAiEffect.SetMessages`
+- **State change:** sets `chatMessages` to the provided array.
+
+```typescript
+import { askUIEventDocAiSetMessages } from 'quidproquo-features';
+import type { EventDocAiChatMessage } from 'quidproquo-features';
+
+export function* onHistoryLoaded(messages: EventDocAiChatMessage[]) {
+  yield* askUIEventDocAiSetMessages(messages);
+}
+```
+
+### Signature
+
+```typescript
+function* askUIEventDocAiSetMessages(
+  messages: EventDocAiChatMessage[],
+): AskResponse<void>;
+```
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `messages` | `EventDocAiChatMessage[]` | The full set of finalized messages to show. Overwrites `chatMessages`. |
+
+---
+
+## askUIEventDocAiAppendChatMessage
+
+Appends a single finalized message to the end of the current thread — used to add the user's message when they send, and to commit the assistant's reply once its stream finishes.
+
+- **Effect:** `EventDocAiEffect.AppendChatMessage`
+- **State change:** pushes `message` onto the end of `chatMessages`.
+
+```typescript
+import { askUIEventDocAiAppendChatMessage } from 'quidproquo-features';
+import type { EventDocAiChatMessage } from 'quidproquo-features';
+
+export function* addUserTurn(text: string) {
+  const message: EventDocAiChatMessage = {
+    role: 'user',
+    segments: [{ type: 'text', text }],
+  };
+
+  yield* askUIEventDocAiAppendChatMessage(message);
+}
+```
+
+### Signature
+
+```typescript
+function* askUIEventDocAiAppendChatMessage(
+  message: EventDocAiChatMessage,
+): AskResponse<void>;
+```
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `message` | `EventDocAiChatMessage` | The finalized turn to append. Its `segments` are already render-ready (raw stream parts are folded into segments before this point). |
+
+---
+
+## askUIEventDocAiSetLoadingHistory
+
+Toggles the "loading this chat's history" flag so the message pane can show a spinner while a chat's messages are fetched.
+
+- **Effect:** `EventDocAiEffect.SetLoadingHistory`
+- **State change:** sets `isLoadingHistory`.
+
+```typescript
+import { askUIEventDocAiSetLoadingHistory, askUIEventDocAiSetMessages } from 'quidproquo-features';
+
+export function* openChatHistory() {
+  yield* askUIEventDocAiSetLoadingHistory(true);
+  // ...fetch this chat's messages, then...
+  yield* askUIEventDocAiSetLoadingHistory(false);
+}
+```
+
+### Signature
+
+```typescript
+function* askUIEventDocAiSetLoadingHistory(
+  isLoading: boolean,
+): AskResponse<void>;
+```
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `isLoading` | `boolean` | `true` while the active chat's history 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 chat list state](./chat-list-state.md) — the chat list and active-chat selection.
+- [Event Doc AI streaming & status state](./streaming-and-status-state.md) — the in-flight assistant reply that becomes a finalized message here.
+
+These UI setters build on the core **State** domain (`askStateDispatch`, `askStateDispatchEffect`) and are consumed alongside the Event Doc AI backend stories — `defineEventDocAi` (config) and `askEventDocAiChatHistoryRequest` / `askEventDocAiChatSendRequest`.

package/template/docusaurus/docs/actions/features/event-doc-ai/ask-event-doc-ai-attachments-validate.md

@@ -0,0 +1,63 @@
+---
+title: askEventDocAiAttachmentsValidate
+description: Validate chat attachments — ensure each assetId is well-formed and resolves to a real asset under the trusted document.
+---
+
+# askEventDocAiAttachmentsValidate
+
+Validates the attachments on a chat message before they reach the model. Attachments arrive from the client as bare `assetId`s; this story rejects any id that isn't guid-shaped (which could path-traverse the drive) and any id that doesn't resolve to a real asset under the session's **trusted** `docId`. This is the guard that stops a client pointing the AI at another document's — or another drive's — files.
+
+It runs inside [askEventDocAiProcessSend](./ask-event-doc-ai-process-send.md) before the prompt stream starts.
+
+- Built from [askFileExists](../../core/file/ask-file-exists.md) and `askThrowError`.
+
+```typescript
+import { askEventDocAiAttachmentsValidate } from 'quidproquo-features';
+
+export function* askGuardAttachments(drive: string, docId: string, attachments) {
+  // throws if any attachment is malformed or missing
+  yield* askEventDocAiAttachmentsValidate(drive, docId, attachments);
+}
+```
+
+## Signature
+
+```typescript
+function* askEventDocAiAttachmentsValidate(
+  docStorageDrive: string,
+  docId: string,
+  attachments: EventDocAiAttachment[],
+): AskResponse<void>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `docStorageDrive` | `string` | The collection's document storage drive — where assets uploaded via the eventDoc asset routes live (not the chat-history drive). |
+| `docId` | `string` | The trusted document id the attachments must belong to. Comes from the session context, never the client or model. |
+| `attachments` | `EventDocAiAttachment[]` | The attachments to check — each `{ assetId, filename, mediaType }`. Only `assetId` is validated; the asset path is derived as `eventDocAssetPath(docId, assetId)`. |
+
+## Returns
+
+`void` — resolves if every attachment is valid; throws on the first invalid one.
+
+## Errors
+
+The story throws standard core errors (catch with [askCatch](../../core/system/ask-catch.md)):
+
+| Thrown error | When |
+| --- | --- |
+| `ErrorTypeEnum.Invalid` | An `assetId` is not guid-shaped (only `A–Z`, `a–z`, `0–9`, `-` allowed) — anything with slashes or dots that could traverse the drive. |
+| `ErrorTypeEnum.NotFound` | The `assetId` is well-formed but no asset exists at its path under `docId` on the document drive. |
+
+## Notes
+
+- Only the `assetId` is trusted from the client. The drive and file path are derived server-side from the trusted `docId` (via the eventDoc `eventDocAssetPath` helper), so an attachment can never reference another document's or another drive's files.
+- `filename` and `mediaType` are display / content-type hints from the uploader; they are not validated here — the bytes are whatever the asset holds.
+
+## Related
+
+- [askEventDocAiProcessSend](./ask-event-doc-ai-process-send.md) — calls this before streaming the reply.
+- [askFileExists](../../core/file/ask-file-exists.md) — the underlying existence check.
+- [defineEventDocAi](../../../config/features/event-doc-ai.md) — the feature whose chats carry attachments.

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

@@ -0,0 +1,95 @@
+---
+title: askEventDocAiChatHistoryLoad / askEventDocAiChatHistorySave
+description: Load and save a chat's message history — the JSON file on the chat drive that holds one chat's messages.
+---
+
+# askEventDocAiChatHistoryLoad & askEventDocAiChatHistorySave
+
+Backend helpers that read and write one chat's message history. A chat's history lives as a single JSON file on the chat storage drive at `` `${docId}/${chatId}/history.json` `` (an `EventDocAiChatHistoryFile`, `{ messages }`). Load returns the messages; save overwrites the whole file.
+
+These run inside the `onChatHistory` and `onChatSend` handlers — the drive name comes from the processor globals set by [defineEventDocAi](../../../config/features/event-doc-ai.md), so both must run under that feature's runtime.
+
+- `Load` built from [askConfigGetGlobal](../../core/config/ask-config-get-global.md), [askFileExists](../../core/file/ask-file-exists.md), and [askFileReadObjectJson](../../core/file/ask-file-read-object-json.md).
+- `Save` built from [askConfigGetGlobal](../../core/config/ask-config-get-global.md) and [askFileWriteObjectJson](../../core/file/ask-file-write-object-json.md).
+
+```typescript
+import { askEventDocAiChatHistoryLoad, askEventDocAiChatHistorySave } from 'quidproquo-features';
+
+export function* askAppendSystemNote(docId: string, chatId: string) {
+  const history = yield* askEventDocAiChatHistoryLoad(docId, chatId);
+  yield* askEventDocAiChatHistorySave(docId, chatId, [
+    ...history,
+    { role: 'assistant', segments: [{ type: 'text', text: 'Note added.' }] },
+  ]);
+}
+```
+
+## askEventDocAiChatHistoryLoad
+
+Reads a chat's saved messages. A chat with no history file yet returns an empty array (not an error).
+
+### Signature
+
+```typescript
+function* askEventDocAiChatHistoryLoad(
+  docId: string,
+  chatId: string,
+): AskResponse<EventDocAiChatMessage[]>;
+```
+
+### Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `docId` | `string` | The document the chat is scoped to. |
+| `chatId` | `string` | The chat whose history to load. |
+
+### Returns
+
+`EventDocAiChatMessage[]` — the persisted messages, or `[]` if the history file does not exist.
+
+## askEventDocAiChatHistorySave
+
+Writes the full message list to the chat's history file, replacing any existing content.
+
+### Signature
+
+```typescript
+function* askEventDocAiChatHistorySave(
+  docId: string,
+  chatId: string,
+  messages: EventDocAiChatMessage[],
+): AskResponse<void>;
+```
+
+### Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `docId` | `string` | The document the chat is scoped to. |
+| `chatId` | `string` | The chat whose history to overwrite. |
+| `messages` | `EventDocAiChatMessage[]` | The complete message list to persist. Save is a full overwrite — pass the whole history, not a delta. |
+
+### Returns
+
+`void`.
+
+## The message format
+
+Each `EventDocAiChatMessage` is `{ role: 'user' | 'assistant'; segments: EventDocAiMessageSegment[] }`. A segment is one of:
+
+| Segment | Shape | Meaning |
+| --- | --- | --- |
+| `text` | `{ type: 'text'; text: string }` | Plain message text. |
+| `reasoning` | `{ type: 'reasoning'; text: string }` | An extended-thinking block. |
+| `file` | `{ type: 'file'; attachment: EventDocAiAttachment }` | A referenced document asset (`{ assetId, filename, mediaType }`). |
+| `tool-use` | `{ type: 'tool-use'; tools: EventDocAiToolUse[] }` | Tool calls, each `{ toolName, input, output? }` (output absent while still running). |
+
+Streaming `AiStreamPart`s are never persisted — they are folded into these segments before saving (see [askEventDocAiProcessSend](./ask-event-doc-ai-process-send.md)).
+
+## Related
+
+- [askEventDocAiProcessSend](./ask-event-doc-ai-process-send.md) — appends to and saves the history each turn.
+- [askEventDocAiChatHistoryRequest](./ask-event-doc-ai-chat-requests.md) — the frontend request that returns this history.
+- [askFileReadObjectJson](../../core/file/ask-file-read-object-json.md) / [askFileWriteObjectJson](../../core/file/ask-file-write-object-json.md) — the underlying file actions.
+- [defineEventDocAi](../../../config/features/event-doc-ai.md) — declares the chat drive these read/write.

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

@@ -0,0 +1,91 @@
+---
+title: askEventDocAiChatList / askEventDocAiChatTouch / askEventDocAiChatUpsert
+description: The chat-list store helpers — list a document's chats, bump a chat to the top, and upsert a chat summary row.
+---
+
+# Chat-list store helpers
+
+Backend helpers over the chat-list key-value store — the table [defineEventDocAi](../../../config/features/event-doc-ai.md) provisions with partition `docId` and sort `chatId`, one row per chat (`EventDocAiChatSummary`). Each reads the store name from the processor globals, so all three run under the eventDocAi feature's runtime.
+
+- `List` built from [askConfigGetGlobal](../../core/config/ask-config-get-global.md) and [askKeyValueStoreQuery](../../core/key-value-store/ask-key-value-store-query.md).
+- `Upsert` built from [askConfigGetGlobal](../../core/config/ask-config-get-global.md) and [askKeyValueStoreUpsert](../../core/key-value-store/ask-key-value-store-upsert.md).
+- `Touch` built from [askKeyValueStoreQuery](../../core/key-value-store/ask-key-value-store-query.md), [askDateNow](../../core/date/ask-date-now.md), and `askEventDocAiChatUpsert`.
+
+```typescript
+import { askEventDocAiChatList, askEventDocAiChatTouch } from 'quidproquo-features';
+
+export function* askMostRecentChat(docId: string) {
+  const chats = yield* askEventDocAiChatList(docId);
+  if (chats[0]) {
+    yield* askEventDocAiChatTouch(docId, chats[0].chatId);
+  }
+  return chats[0] ?? null;
+}
+```
+
+## askEventDocAiChatList
+
+Returns all chats for one document, most recently updated first. Sorting is done in-story (by `updatedAt` descending) rather than via a GSI — per-document chat counts are small and the dev-server query processor can't target a secondary index.
+
+### Signature
+
+```typescript
+function* askEventDocAiChatList(docId: string): AskResponse<EventDocAiChatSummary[]>;
+```
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `docId` | `string` | The document whose chats to list. |
+
+**Returns** `EventDocAiChatSummary[]` — the document's chats sorted newest-updated first.
+
+## askEventDocAiChatUpsert
+
+Writes (inserts or replaces) a chat summary row.
+
+### Signature
+
+```typescript
+function* askEventDocAiChatUpsert(chat: EventDocAiChatSummary): AskResponse<void>;
+```
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `chat` | `EventDocAiChatSummary` | The full summary row (`{ docId, chatId, name, createdAt, updatedAt, createdByUserId }`) to store. |
+
+**Returns** `void`.
+
+## askEventDocAiChatTouch
+
+Bumps a chat's `updatedAt` to now so it sorts to the top of the list. A missing record — e.g. a chat deleted mid-conversation — is a no-op, not an error.
+
+### Signature
+
+```typescript
+function* askEventDocAiChatTouch(docId: string, chatId: string): AskResponse<void>;
+```
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `docId` | `string` | The document the chat belongs to. |
+| `chatId` | `string` | The chat to bump. |
+
+**Returns** `void`. Looks the row up, sets `updatedAt` to [askDateNow](../../core/date/ask-date-now.md), and re-upserts it; does nothing if no such row exists.
+
+## EventDocAiChatSummary
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `docId` | `string` | The document the chat is scoped to (partition key). |
+| `chatId` | `string` | The chat's id (sort key). |
+| `name` | `string` | Display name. |
+| `createdAt` | `QpqIsoDateTime` | Creation timestamp. |
+| `updatedAt` | `QpqIsoDateTime` | Last-activity timestamp; drives list ordering. |
+| `createdByUserId` | `string` | The user who created the chat. |
+
+## Related
+
+- [askEventDocAiChatListRequest](./ask-event-doc-ai-chat-requests.md) — the frontend request backed by `askEventDocAiChatList`.
+- [askEventDocAiProcessSend](./ask-event-doc-ai-process-send.md) — calls `askEventDocAiChatTouch` at the end of each turn.
+- [askKeyValueStoreQuery](../../core/key-value-store/ask-key-value-store-query.md) / [askKeyValueStoreUpsert](../../core/key-value-store/ask-key-value-store-upsert.md) — the underlying store actions.
+- [defineEventDocAi](../../../config/features/event-doc-ai.md) — declares the chat-list store.

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

@@ -0,0 +1,93 @@
+---
+title: askEventDocAiChat*Request
+description: The four typed eventDocAi chat request builders — create, list, history, and send — issued from the browser over the websocket transport.
+---
+
+# Chat request builders
+
+The four typed request builders a chat frontend calls to reach the backend. Each wraps [askEventDocAiServiceRequest](./ask-event-doc-ai-service-request.md) with a specific method verb and payload/response type; the transport wrapper reads the [eventDocAi context](./ask-event-doc-ai-context-read.md) and relays the trusted `docId`, so none of these takes a `docId` argument. They correspond one-to-one with the queue processors [defineEventDocAi](../../../config/features/event-doc-ai.md) registers (`onChatCreate`, `onChatList`, `onChatHistory`, `onChatSend`).
+
+These are the low-level requests. For the client stories that call them and update UI state, see [askEventDocAiNewChat](./ask-event-doc-ai-new-chat.md), [askEventDocAiLoadChats](./ask-event-doc-ai-load-chats.md), [askEventDocAiSelectChat](./ask-event-doc-ai-select-chat.md), and [askEventDocAiSendMessage](./ask-event-doc-ai-send-message.md).
+
+- Each built from [askEventDocAiServiceRequest](./ask-event-doc-ai-service-request.md) (method key `eventDocAi/<type>/<Verb>`).
+
+```typescript
+import { askEventDocAiChatCreateRequest, askEventDocAiChatSendRequest } from 'quidproquo-features';
+
+export function* askStartAndAsk(question: string) {
+  const chat = yield* askEventDocAiChatCreateRequest({ name: 'Untitled' });
+  return yield* askEventDocAiChatSendRequest({ chatId: chat.chatId, message: question });
+}
+```
+
+## askEventDocAiChatCreateRequest
+
+Creates a new chat for the context's document and returns its summary row.
+
+```typescript
+function* askEventDocAiChatCreateRequest(
+  payload?: EventDocAiChatCreatePayload,
+): AskResponse<EventDocAiChatSummary>;
+```
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| `payload.name` | `string` | `'New chat'` | Display name for the chat. Omitted → the backend defaults to `'New chat'`. |
+
+**Returns** `EventDocAiChatSummary` — `{ docId, chatId, name, createdAt, updatedAt, createdByUserId }`, the freshly created chat.
+
+## askEventDocAiChatListRequest
+
+Lists all chats for the context's document, most recently updated first. Takes no arguments (the document comes from context).
+
+```typescript
+function* askEventDocAiChatListRequest(): AskResponse<EventDocAiChatSummary[]>;
+```
+
+**Returns** `EventDocAiChatSummary[]` — the document's chats, sorted by `updatedAt` descending.
+
+## askEventDocAiChatHistoryRequest
+
+Loads the full message history of one chat.
+
+```typescript
+function* askEventDocAiChatHistoryRequest(
+  payload: EventDocAiChatHistoryPayload,
+): AskResponse<EventDocAiChatMessage[]>;
+```
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `payload.chatId` | `string` | The chat to load history for. |
+
+**Returns** `EventDocAiChatMessage[]` — every persisted message (`{ role, segments[] }`); an empty array if the chat has no saved history.
+
+## askEventDocAiChatSendRequest
+
+Sends a user message to a chat and streams the assistant's reply. The response only signals completion — the reply content arrives via `askUIEventDocAi*` state dispatches while the request is in flight.
+
+```typescript
+function* askEventDocAiChatSendRequest(
+  payload: EventDocAiChatSendPayload,
+): AskResponse<EventDocAiChatSendResult>;
+```
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `payload.chatId` | `string` | The chat to append to. |
+| `payload.message` | `string` | The user's message text. |
+| `payload.attachments` | `EventDocAiAttachment[]` (optional) | Document assets to attach — each `{ assetId, filename, mediaType }`. Only the `assetId` crosses the wire; the server resolves the file from the trusted `docId`. |
+
+**Returns** `EventDocAiChatSendResult` — `{ complete: boolean }`. The streamed content is delivered separately via UI state dispatches (see [askEventDocAiProcessSend](./ask-event-doc-ai-process-send.md)).
+
+## Notes
+
+- None of these take a `docId` — it is relayed from context by [askEventDocAiServiceRequest](./ask-event-doc-ai-service-request.md).
+- Failures surface through the wrapping client stories, which catch them with `askCatch` and dispatch the error text to UI state.
+
+## Related
+
+- [askEventDocAiServiceRequest](./ask-event-doc-ai-service-request.md) — the transport wrapper these share.
+- [askEventDocAiNewChat](./ask-event-doc-ai-new-chat.md) / [askEventDocAiLoadChats](./ask-event-doc-ai-load-chats.md) / [askEventDocAiSelectChat](./ask-event-doc-ai-select-chat.md) / [askEventDocAiSendMessage](./ask-event-doc-ai-send-message.md) — client stories that call these and update state.
+- [askEventDocAiProcessSend](./ask-event-doc-ai-process-send.md) — the backend handler behind `ChatSend`.
+- [defineEventDocAi](../../../config/features/event-doc-ai.md) — registers the matching backend handlers.

package/template/docusaurus/docs/actions/features/event-doc-ai/ask-event-doc-ai-context-read.md

@@ -0,0 +1,84 @@
+---
+title: askEventDocAiContextRead / askEventDocAiContextProvide
+description: Read and provide the eventDocAi session context — the service, document type, and trusted docId a chat turn is scoped to.
+---
+
+# askEventDocAiContextRead & askEventDocAiContextProvide
+
+The eventDocAi **session context** carries the three values every chat operation is scoped to: the `serviceName` requests route through, the collection `type`, and the **trusted** `docId` the chat belongs to. Both stories are built from the core [context actions](../../core/context/ask-context-read.md) over a single shared context identifier (`event-doc-ai-context`).
+
+Read the context anywhere inside a story that runs under it; provide it to establish the scope around a nested story. On the frontend the chat UI provides it around the chat panel; on the backend the handler wrapper re-provides it around each handler (and tool runtimes inherit it), so nested logic and tools read the trusted `docId` from context instead of trusting anything the caller or the model sent.
+
+- Built from core [askContextRead](../../core/context/ask-context-read.md) and [askContextProvideValue](../../core/context/ask-context-provide-value.md).
+
+```typescript
+import { askEventDocAiContextProvide, askEventDocAiContextRead } from 'quidproquo-features';
+
+// Provide the scope around a story, then any nested read sees it.
+export function* askScopedChatWork() {
+  return yield* askEventDocAiContextProvide(
+    { serviceName: 'app', type: 'project', docId: 'doc-123' },
+    function* () {
+      const { docId } = yield* askEventDocAiContextRead();
+      // docId === 'doc-123' — the trusted document this turn is scoped to
+      return docId;
+    },
+  );
+}
+```
+
+## askEventDocAiContextRead
+
+Reads the current `EventDocAiContext`. If no provider is above it in the story, the context identifier's default is returned (`{ serviceName: '', type: '', docId: '' }`).
+
+### Signature
+
+```typescript
+function* askEventDocAiContextRead(): AskResponse<EventDocAiContext>;
+```
+
+### Returns
+
+`EventDocAiContext` — the scope the surrounding story runs under.
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `serviceName` | `string` | The service the eventDocAi websocket requests route through. |
+| `type` | `string` | The eventDoc collection's document type. |
+| `docId` | `string` | The trusted id of the document the chat is scoped to. |
+
+## askEventDocAiContextProvide
+
+Provides an `EventDocAiContext` around a nested story and returns that story's result. Everything the story yields — including tool executors, which inherit the session context — reads the same trusted values.
+
+### Signature
+
+```typescript
+function* askEventDocAiContextProvide<T>(
+  context: EventDocAiContext,
+  story: AskResponse<T>,
+): AskResponse<T>;
+```
+
+### Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `context` | `EventDocAiContext` | The scope to establish (`{ serviceName, type, docId }`). |
+| `story` | `AskResponse<T>` | The story to run under that context. Its return value is passed straight back through. |
+
+### Returns
+
+`T` — the wrapped story's result, unchanged.
+
+## Notes
+
+- The `docId` here is **trusted**: on the backend it is derived from the wire payload's relay field and re-provided by the handler wrapper, never taken from a tool's arguments. This is why tools read it from context — see [askEventDocAiProcessSend](./ask-event-doc-ai-process-send.md).
+- The frontend transport wrapper [askEventDocAiServiceRequest](./ask-event-doc-ai-service-request.md) reads this context to relay the `serviceName`/`type`/`docId` over the wire.
+
+## Related
+
+- [askEventDocAiServiceRequest](./ask-event-doc-ai-service-request.md) — reads this context to route and relay requests.
+- [askEventDocAiProcessSend](./ask-event-doc-ai-process-send.md) — runs under a provided context so tools inherit the trusted `docId`.
+- [askContextRead](../../core/context/ask-context-read.md) / [askContextProvideValue](../../core/context/ask-context-provide-value.md) — the core actions these wrap.
+- [defineEventDocAi](../../../config/features/event-doc-ai.md) — the feature these chats belong to.