create-qpq-app 0.1.5

package/template/docusaurus/docs/actions/core/_category_.json

@@ -0,0 +1,8 @@
+{
+  "label": "quidproquo-core",
+  "position": 1,
+  "link": {
+    "type": "generated-index",
+    "description": "Action requesters (ask* generator functions) exported from quidproquo-core."
+  }
+}

package/template/docusaurus/docs/actions/core/ai/_category_.json

@@ -0,0 +1,7 @@
+{
+  "label": "AI",
+  "link": {
+    "type": "generated-index",
+    "description": "AI actions send prompts to a large language model and stream back the response. On AWS they run through the Vercel AI SDK against Amazon Bedrock."
+  }
+}

package/template/docusaurus/docs/actions/core/ai/ask-ai-prompt-stream.md

@@ -0,0 +1,96 @@
+---
+title: askAiPromptStream
+description: Send a prompt to a large language model and receive the response incrementally as a stream of typed events.
+---
+
+# askAiPromptStream
+
+Sends a prompt to a large language model and resolves immediately with a **stream handle** rather than a finished string. The story then reads events off the stream as the model produces them — text deltas, reasoning, tool calls, usage, and lifecycle markers. Use this when you want to forward tokens to a client in real time (e.g. over a WebSocket) or react to tool calls as they happen. For a simple one-shot answer, use [askAiPrompt](./ask-ai-prompt.md) instead.
+
+- **Action type:** `AiActionType.PromptStream`
+- **On AWS:** runs through the [Vercel AI SDK](https://ai-sdk.dev) (`streamText`) against Amazon Bedrock, registering the SDK's event stream in the runtime's stream registry and handing back a handle to it.
+
+```typescript
+import { askAiPromptStream, askStreamProcess, AiModel, AiStreamPartType } from 'quidproquo-core';
+
+export function* askAnswerStreamed(prompt: string) {
+  const stream = yield* askAiPromptStream(AiModel.ClaudeSonnet46, prompt);
+
+  yield* askStreamProcess(stream, function* (part) {
+    if (part.type === AiStreamPartType.TextDelta) {
+      // forward part.text to the client...
+    }
+  });
+}
+```
+
+## Signature
+
+```typescript
+function* askAiPromptStream(
+  model: AiModel,
+  prompt: string,
+  options?: AskAiPromptStreamOptions,
+): AskResponse<StreamHandle<'json', AiStreamPart>>;
+```
+
+## Parameters
+
+The parameters are identical to [askAiPrompt](./ask-ai-prompt.md) — see there for [`AiModel`](./ask-ai-prompt.md#aimodel), [`AiMessage`](./ask-ai-prompt.md#aimessage), and [`AiReasoningConfig`](./ask-ai-prompt.md#aireasoningconfig).
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `model` | `AiModel` | Which model to prompt. |
+| `prompt` | `string` | The user prompt. Ignored when `options.messages` is set. |
+| `options` | `AskAiPromptStreamOptions` | `{ system?, aiName?, messages?, reasoning? }` — same shape and meaning as [`AskAiPromptOptions`](./ask-ai-prompt.md#askaipromptoptions). |
+
+## Returns
+
+`StreamHandle<'json', AiStreamPart>` — a handle to a JSON-encoded stream whose items are [`AiStreamPart`](#the-stream-aistreampart) events. Read it with the [stream stories](../../../actions/core/stream/ask-stream-read.md): `askStreamProcess` (run a callback per part), `askStreamMap` (collect/transform into an array), or the lower-level `askStreamRead` / `askStreamClose`.
+
+## The stream: `AiStreamPart`
+
+`AiStreamPart` is a discriminated union; narrow on `type` (an `AiStreamPartType` value) to read the per-variant fields. The broad lifecycle is:
+
+```
+Start → (StartStep → step events → FinishStep)+ → Finish
+```
+
+Within a step, text / reasoning / tool-input events arrive as matched `*Start → *Delta… → *End` triples sharing an `id`.
+
+### `AiStreamPartType`
+
+| Member (`type`) | When it fires |
+| --- | --- |
+| `Start` (`start`) | Once, before anything else — the response is starting. |
+| `Finish` (`finish`) | Once, at the very end — includes aggregate usage. |
+| `StartStep` (`start-step`) | A generation step (one round-trip to the model) started. |
+| `FinishStep` (`finish-step`) | The current step ended, with its finish reason and usage. |
+| `TextStart` / `TextDelta` / `TextEnd` | Beginning / incremental chunk / end of a text block. |
+| `ReasoningStart` / `ReasoningDelta` / `ReasoningEnd` | Beginning / chunk / end of an extended-thinking block. |
+| `ToolInputStart` / `ToolInputDelta` / `ToolInputEnd` | The model is streaming a tool call's (JSON) arguments. |
+| `ToolCall` (`tool-call`) | A fully-assembled, parsed tool call. |
+| `ToolResult` (`tool-result`) | A tool finished successfully — carries `input` and `output`. |
+| `ToolError` (`tool-error`) | A tool threw; `message` holds the stringified error. |
+| `ToolApprovalRequest` (`tool-approval-request`) | The model wants permission to run a tool — awaiting approve/deny. |
+| `ToolApprovalResponse` (`tool-approval-response`) | The approve/deny decision for a prior request. |
+| `ToolOutputDenied` (`tool-output-denied`) | The caller denied a tool after an approval request. |
+| `Source` (`source`) | The model cited a source (URL/document) — for grounded / RAG responses. |
+| `File` (`file`) | The model produced a file artifact (e.g. a generated image). |
+| `ReasoningFile` (`reasoning-file`) | A reasoning file artifact (e.g. an encrypted reasoning trace). |
+| `Abort` (`abort`) | The stream was aborted (abort signal, client disconnect). |
+| `Error` (`error`) | A non-fatal streaming error surfaced to the consumer. |
+| `Raw` (`raw`) | A provider-specific raw chunk, passed through for debugging. |
+| `Custom` (`custom`) | A provider-specific custom event identified by `kind`. |
+
+## Errors
+
+Fatal failures throw `ErrorTypeEnum.GenericError`; non-fatal issues that arise mid-stream surface as `Error` (`error`) parts rather than throwing. Wrap the initial call with `askCatch` if the model may be unavailable.
+
+## Related
+
+- [askAiPrompt](./ask-ai-prompt.md) — the buffered, one-shot counterpart.
+- [defineAi](../../../config/core/ai.md) — declares tools the model can call.
+- [askStreamRead](../../../actions/core/stream/ask-stream-read.md) / [askStreamClose](../../../actions/core/stream/ask-stream-close.md) — the low-level stream actions.
+- [askStreamProcess](../../../actions/core/stream/ask-stream-process.md) / [askStreamMap](../../../actions/core/stream/ask-stream-map.md) — consume the returned handle in one call (run a callback per part, or collect the parts into an array).
+- [askEventDocAiProcessSend](../../features/event-doc-ai/ask-event-doc-ai-process-send.md) — the eventDocAi chat turn that drives this stream to the browser.

package/template/docusaurus/docs/actions/core/ai/ask-ai-prompt.md

@@ -0,0 +1,121 @@
+---
+title: askAiPrompt
+description: Send a prompt to a large language model and get the full text response back in one shot.
+---
+
+# askAiPrompt
+
+Sends a prompt to a large language model and resolves with the model's complete text response. This is the buffered, non-streaming call — the story pauses until the model has finished generating, then resumes with the whole answer. If you want to consume tokens as they arrive, use [askAiPromptStream](./ask-ai-prompt-stream.md) instead.
+
+- **Action type:** `AiActionType.Prompt`
+- **On AWS:** runs through the [Vercel AI SDK](https://ai-sdk.dev) (`generateText`) against Amazon Bedrock. Any tools declared on the matching [defineAi](../../../config/core/ai.md) config are made available to the model, and the processor runs up to 10 tool-calling steps before returning.
+
+```typescript
+import { askAiPrompt, AiModel } from 'quidproquo-core';
+
+export function* askSummarize(document: string) {
+  const { text } = yield* askAiPrompt(
+    AiModel.ClaudeSonnet46,
+    `Summarize the following document in three sentences:\n\n${document}`,
+  );
+
+  return text;
+}
+```
+
+## Signature
+
+```typescript
+function* askAiPrompt(
+  model: AiModel,
+  prompt: string,
+  options?: AskAiPromptOptions,
+): AskResponse<AiPromptActionResult>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `model` | [`AiModel`](#aimodel) | Which model to prompt. |
+| `prompt` | `string` | The user prompt. Ignored if you pass `options.messages` — a multi-turn conversation takes precedence over a single prompt string. |
+| `options` | [`AskAiPromptOptions`](#askaipromptoptions) | Optional system prompt, conversation history, named AI config, and reasoning settings. |
+
+### `AskAiPromptOptions`
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `system` | `string` | – | System prompt — high-level instructions that steer the model's behaviour for the whole request. |
+| `aiName` | `string` | – | Name of a [defineAi](../../../config/core/ai.md) config to bind. This is what wires up tool definitions (and their executors) for the model to call. Omit for a plain, tool-less prompt. |
+| `messages` | [`AiMessage[]`](#aimessage) | – | A full conversation history. When present, this is sent instead of `prompt`, letting you carry a multi-turn dialogue (including prior assistant turns and tool results). |
+| `reasoning` | [`AiReasoningConfig`](#aireasoningconfig) | – | Enables extended thinking. Its presence turns reasoning on; `budgetTokens` caps how many tokens the model may spend thinking before it answers (defaults to `4096` on AWS). |
+
+### `AiModel`
+
+The model to run. Values map to the underlying Bedrock model ids.
+
+| Member | Model |
+| --- | --- |
+| `ClaudeHaiku35` | Claude 3.5 Haiku |
+| `ClaudeSonnet35` | Claude 3.5 Sonnet |
+| `ClaudeSonnet4` | Claude Sonnet 4 |
+| `ClaudeOpus4` | Claude Opus 4 |
+| `ClaudeHaiku45` | Claude Haiku 4.5 |
+| `ClaudeSonnet45` | Claude Sonnet 4.5 |
+| `ClaudeOpus45` | Claude Opus 4.5 |
+| `ClaudeSonnet46` | Claude Sonnet 4.6 |
+| `ClaudeOpus46` | Claude Opus 4.6 |
+
+### `AiMessage`
+
+A discriminated union on `role`. Use `messages` when you need multi-turn context instead of a single `prompt`.
+
+```typescript
+type AiMessage = AiUserMessage | AiAssistantMessage | AiToolMessage;
+
+type AiUserMessage      = { role: 'user';      content: string | AiUserMessagePart[] };
+type AiAssistantMessage = { role: 'assistant'; content: string | AiAssistantMessagePart[] };
+type AiToolMessage      = { role: 'tool';      content: AiToolResultPart[] };
+```
+
+`content` can be a plain string or an array of parts. The available parts:
+
+| Part (`type`) | Fields | Notes |
+| --- | --- | --- |
+| `text` | `text` | Plain text. |
+| `file` (URL) | `url`, `mediaType`, `filename?` | Attach a file by URL. |
+| `file` (drive) | `drive`, `filepath`, `mediaType`, `filename?` | Attach a file from a [storage drive](../../../config/core/storage-drive.md). The processor resolves the contents at prompt time, so no presigned URL ever lands in logs or session state. |
+| `tool-call` | `toolCallId`, `toolName`, `input` | An assistant turn's request to call a tool. |
+| `reasoning` | `text`, `providerOptions?` | An assistant turn's thinking block. |
+| `tool-result` | `toolCallId`, `toolName`, `output`, `isError?` | The result you feed back for a tool call (in a `tool` message). |
+
+### `AiReasoningConfig`
+
+```typescript
+interface AiReasoningConfig {
+  budgetTokens?: number;
+}
+```
+
+## Returns
+
+`AiPromptActionResult` — `{ text: string }`, the model's complete response text.
+
+## Errors
+
+On any failure the processor throws `ErrorTypeEnum.GenericError` with the underlying provider message. Catch it with `askCatch`, which returns an `EitherActionResult` — `{ success: true, result }` or `{ success: false, error }`:
+
+```typescript
+import { askCatch, askAiPrompt, AiModel } from 'quidproquo-core';
+
+const outcome = yield* askCatch(askAiPrompt(AiModel.ClaudeHaiku45, prompt));
+if (!outcome.success) {
+  // outcome.error.errorText — fall back
+}
+```
+
+## Related
+
+- [askAiPromptStream](./ask-ai-prompt-stream.md) — stream the response token-by-token instead of waiting for the whole thing.
+- [defineAi](../../../config/core/ai.md) — declares a named AI config with tool definitions the model can call.
+- [defineStorageDrive](../../../config/core/storage-drive.md) — the drive an `AiFileDrivePart` attachment reads from.

package/template/docusaurus/docs/actions/core/array/_category_.json

@@ -0,0 +1,7 @@
+{
+  "label": "Array",
+  "link": {
+    "type": "generated-index",
+    "description": "Story-composition helpers for iterating arrays — map, filter, reduce, flatMap, and their parallel/batched variants — where each item's callback is itself a story."
+  }
+}

package/template/docusaurus/docs/actions/core/array/ask-array-some.md

@@ -0,0 +1,54 @@
+---
+title: askArraySome
+description: Test whether any item's story returns true, short-circuiting on the first match.
+---
+
+# askArraySome
+
+Iterates an array and returns `true` as soon as any item's callback returns `true` — the async/story equivalent of `Array.prototype.some`. The per-item callback is a generator, so the test can `yield*` other actions. Items are tested **sequentially**, and iteration **short-circuits**: the moment a callback returns `true`, `askArraySome` returns `true` without touching the remaining items. If none match, it returns `false`.
+
+- **Built from:** a plain `for` loop that `yield*`s the predicate for each item and returns early on the first `true`.
+
+```typescript
+import { askArraySome } from 'quidproquo-core';
+import { askFileExists } from 'quidproquo-core';
+
+export function* askAnyFileMissing(filepaths: string[]) {
+  // Returns true as soon as one path is missing; stops checking the rest.
+  return yield* askArraySome(filepaths, function* (filepath) {
+    const exists = yield* askFileExists('uploads', filepath);
+    return !exists;
+  });
+}
+```
+
+## Signature
+
+```typescript
+function* askArraySome<T>(
+  items: T[],
+  askCallback: (item: T, index: number, srcArray: T[]) => AskResponse<boolean>,
+): AskResponse<boolean>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `items` | `T[]` | The array to test. |
+| `askCallback` | `(item: T, index: number, srcArray: T[]) => AskResponse<boolean>` | A generator predicate called once per item, in order. Receives the item, its zero-based index, and the source array. Returning `true` stops iteration immediately. |
+
+## Returns
+
+`boolean` — `true` if the predicate returned `true` for any item, otherwise `false`. Returns `false` for an empty array.
+
+## Notes
+
+- **Short-circuits.** Because it stops at the first match, only the items up to and including the matching one have their callbacks run — handy when the test is expensive.
+- **Sequential**, so items are tested one at a time in order.
+
+## Related
+
+- [askFilter](./ask-filter.md) — collect every matching item instead of a single boolean.
+- [askMap](./ask-map.md) — transform each item into a new array.
+- [askReduce](./ask-reduce.md) — fold the array into a single accumulated value.

package/template/docusaurus/docs/actions/core/array/ask-filter.md

@@ -0,0 +1,54 @@
+---
+title: askFilter
+description: Keep only the items whose per-item story returns true.
+---
+
+# askFilter
+
+Iterates an array and returns a new array containing only the items for which the per-item callback returns `true` — the async/story equivalent of `Array.prototype.filter`. Each item's callback is a generator, so the predicate can `yield*` other actions (look up a record, check permissions, etc.). Items are tested **sequentially**, in order.
+
+- **Built from:** a plain `for` loop that `yield*`s the predicate for each item and keeps the item when it returns `true`.
+
+```typescript
+import { askFilter } from 'quidproquo-core';
+import { askFileExists } from 'quidproquo-core';
+
+export function* askKeepExistingFiles(filepaths: string[]) {
+  // Keep only the paths that actually exist on the drive.
+  const existing = yield* askFilter(filepaths, function* (filepath) {
+    return yield* askFileExists('uploads', filepath);
+  });
+
+  return existing;
+}
+```
+
+## Signature
+
+```typescript
+function* askFilter<T>(
+  items: T[],
+  askCallback: (item: T, index: number, srcArray: T[]) => AskResponse<boolean>,
+): AskResponse<T[]>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `items` | `T[]` | The array to iterate. |
+| `askCallback` | `(item: T, index: number, srcArray: T[]) => AskResponse<boolean>` | A generator predicate called once per item. Receives the item, its zero-based index, and the source array. Return `true` to keep the item, `false` to drop it. |
+
+## Returns
+
+`T[]` — a new array holding the original items (not transformed) for which the predicate returned `true`, in their original order.
+
+## Notes
+
+- **Sequential.** Each predicate completes before the next item is tested. There is no parallel variant of `askFilter` — if you need concurrency, map with [askMapParallel](./ask-map-parallel.md) to produce a boolean per item, then filter with a plain synchronous check.
+
+## Related
+
+- [askMap](./ask-map.md) — transform every item instead of selecting a subset.
+- [askArraySome](./ask-array-some.md) — stop early once any item's predicate returns `true`.
+- [askReduce](./ask-reduce.md) — fold the array into a single value.

package/template/docusaurus/docs/actions/core/array/ask-flat-map-parallel-batch.md

@@ -0,0 +1,68 @@
+---
+title: askFlatMapParallelBatch
+description: Batched-parallel map to arrays, then flatten the results one level.
+---
+
+# askFlatMapParallelBatch
+
+Iterates an array with **bounded concurrency**, maps each item to an array via the per-item callback, and concatenates all those arrays into one. It is [askMapParallelBatch](./ask-map-parallel-batch.md) with a flatten on the end — items run `numBatch` at a time, batch by batch, and each callback returns an array whose elements are merged into the final result. Use it when each item expands into several results and you need to cap concurrency against a downstream resource.
+
+- **Built from:** [askMapParallelBatch](./ask-map-parallel-batch.md) followed by a single-level `Array.prototype.flat()`.
+
+```typescript
+import { askFlatMapParallelBatch } from 'quidproquo-core';
+import { askAiPrompt } from 'quidproquo-core';
+
+const EXPAND_BATCH = 4;
+
+export function* askExpandPrompts(prompts: string[]) {
+  // Expand at most 4 prompts at a time; each returns several variations,
+  // all flattened into one array.
+  const variations = yield* askFlatMapParallelBatch(
+    prompts,
+    EXPAND_BATCH,
+    function* (prompt) {
+      const result = yield* askAiPrompt('expander', prompt, []);
+      return result.split('\n');
+    },
+  );
+
+  return variations;
+}
+```
+
+## Signature
+
+```typescript
+function* askFlatMapParallelBatch<T, R>(
+  items: T[],
+  numBatch: number,
+  askCallback: (item: T, index: number, srcArray: T[]) => AskResponse<R[]>,
+  delayAfterEachBatchMs?: number,
+): AskResponse<R[]>;
+```
+
+## Parameters
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| `items` | `T[]` | — | The array to iterate. |
+| `numBatch` | `number` | — | Batch size — the maximum number of items that run **concurrently** at once. |
+| `askCallback` | `(item: T, index: number, srcArray: T[]) => AskResponse<R[]>` | — | A generator called once per item. Receives the item, its zero-based index, and the source array, and returns an **array** of results. |
+| `delayAfterEachBatchMs` | `number` | `0` | Optional pause (in milliseconds) inserted after every batch, including the last — passed straight through to [askMapParallelBatch](./ask-map-parallel-batch.md). |
+
+## Returns
+
+`R[]` — the per-item arrays concatenated into a single array (flattened exactly one level), in order.
+
+## Notes
+
+- **Bounded concurrency**, same as [askMapParallelBatch](./ask-map-parallel-batch.md): peak in-flight work is `numBatch`.
+- Only one level of nesting is removed.
+
+## Related
+
+- [askFlatMap](./ask-flat-map.md) — the sequential version (one item at a time).
+- [askMapParallelBatch](./ask-map-parallel-batch.md) — batched-parallel map without flattening.
+- [askMapParallel](./ask-map-parallel.md) — unbounded parallel map.
+- [askDelay](../platform/ask-delay.md) — the delay yielded between batches.

package/template/docusaurus/docs/actions/core/array/ask-flat-map.md

@@ -0,0 +1,56 @@
+---
+title: askFlatMap
+description: Map each item to an array, then flatten the results one level.
+---
+
+# askFlatMap
+
+Iterates an array, maps each item to an array via the per-item callback, and concatenates all those arrays into one — the async/story equivalent of `Array.prototype.flatMap`. Each item's callback is a generator that returns an array, and the results are flattened one level. Items are processed **sequentially**, in order.
+
+- **Built from:** [askMap](./ask-map.md) followed by a single-level `Array.prototype.flat()`.
+
+```typescript
+import { askFlatMap } from 'quidproquo-core';
+import { askFileListDirectory } from 'quidproquo-core';
+
+export function* askListAllFiles(directories: string[]) {
+  // Map each directory to its file list, then flatten into one array.
+  const allFiles = yield* askFlatMap(directories, function* (dir) {
+    return yield* askFileListDirectory('uploads', dir);
+  });
+
+  return allFiles;
+}
+```
+
+## Signature
+
+```typescript
+function* askFlatMap<T, R>(
+  items: T[],
+  askCallback: (item: T, index: number, srcArray: T[]) => AskResponse<R[]>,
+): AskResponse<R[]>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `items` | `T[]` | The array to iterate. |
+| `askCallback` | `(item: T, index: number, srcArray: T[]) => AskResponse<R[]>` | A generator called once per item. Receives the item, its zero-based index, and the source array, and returns an **array** of results. |
+
+## Returns
+
+`R[]` — the per-item arrays concatenated into a single array (flattened exactly one level), in order.
+
+## Notes
+
+- **Sequential**, because it builds on [askMap](./ask-map.md). For bounded concurrency plus flattening, use [askFlatMapParallelBatch](./ask-flat-map-parallel-batch.md).
+- Only one level of nesting is removed; if a callback returns `R[][]`, the result is `R[][]`, not fully flattened.
+
+## Related
+
+- [askMap](./ask-map.md) — map without flattening (returns `R[][]` if callbacks return arrays).
+- [askFlatMapParallelBatch](./ask-flat-map-parallel-batch.md) — the batched-parallel version of this helper.
+- [askFilter](./ask-filter.md) — select a subset of items.
+- [askReduce](./ask-reduce.md) — fold the array into a single value.

package/template/docusaurus/docs/actions/core/array/ask-map-parallel-batch.md

@@ -0,0 +1,67 @@
+---
+title: askMapParallelBatch
+description: Map an array with bounded concurrency — a fixed number of items run in parallel per batch.
+---
+
+# askMapParallelBatch
+
+Iterates an array and builds a new array from the result of a per-item callback, running a **bounded number of items concurrently at a time**. The array is sliced into batches of `numBatch`; each batch runs fully in parallel (via [askMapParallel](./ask-map-parallel.md)), and only when a batch finishes does the next batch start. This is the safe middle ground between [askMap](./ask-map.md) (one at a time) and [askMapParallel](./ask-map-parallel.md) (all at once) — you get concurrency without overwhelming a rate-limited downstream.
+
+- **Built from:** repeated calls to [askMapParallel](./ask-map-parallel.md) over successive slices of the array, with an optional [askDelay](../platform/ask-delay.md) between batches.
+
+```typescript
+import { askMapParallelBatch } from 'quidproquo-core';
+import { askAiPrompt } from 'quidproquo-core';
+
+const RENDER_BATCH = 5;
+
+export function* askRenderContent(contentIds: string[]) {
+  // Render at most 5 items at a time so we stay under the model rate limit.
+  const renders = yield* askMapParallelBatch(
+    contentIds,
+    RENDER_BATCH,
+    function* (contentId) {
+      return yield* askAiPrompt('renderer', contentId, []);
+    },
+  );
+
+  return renders;
+}
+```
+
+## Signature
+
+```typescript
+function* askMapParallelBatch<T, R>(
+  items: T[],
+  numBatch: number,
+  askCallback: (item: T, index: number, srcArray: T[]) => AskResponse<R>,
+  delayAfterEachBatchMs?: number,
+): AskResponse<R[]>;
+```
+
+## Parameters
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| `items` | `T[]` | — | The array to iterate. |
+| `numBatch` | `number` | — | Batch size — the maximum number of items that run **concurrently** at once. The array is consumed `numBatch` items at a time; each slice runs in parallel and must finish before the next slice begins. |
+| `askCallback` | `(item: T, index: number, srcArray: T[]) => AskResponse<R>` | — | A generator called once per item. Receives the item, its zero-based index, and the source array. |
+| `delayAfterEachBatchMs` | `number` | `0` | Optional pause (in milliseconds) inserted **after every batch**, including the last. When greater than `0`, the helper `yield*`s [askDelay](../platform/ask-delay.md) between batches — useful for spacing out calls to a throttled service. |
+
+## Returns
+
+`R[]` — a new array of the callback's return values, in the same order as `items`.
+
+## Notes
+
+- **Bounded concurrency.** Peak in-flight work is `numBatch`, no matter how large `items` is.
+- Items within a single batch must be independent of one another (same rule as [askMapParallel](./ask-map-parallel.md)). Across batches, later batches do run after earlier ones complete, so batch _n_ can observe batch _n − 1_'s side effects.
+- `delayAfterEachBatchMs` fires after the final batch too, so a non-zero delay adds one extra wait at the end.
+
+## Related
+
+- [askMap](./ask-map.md) — fully sequential (one item at a time).
+- [askMapParallel](./ask-map-parallel.md) — fully parallel (all items at once, unbounded).
+- [askFlatMapParallelBatch](./ask-flat-map-parallel-batch.md) — the same batching, then flatten the results one level.
+- [askDelay](../platform/ask-delay.md) — the delay yielded between batches.

package/template/docusaurus/docs/actions/core/array/ask-map-parallel.md

@@ -0,0 +1,57 @@
+---
+title: askMapParallel
+description: Map an array to a new array, running every item's story concurrently.
+---
+
+# askMapParallel
+
+Iterates an array and builds a new array from the result of a per-item callback, running **all items concurrently**. Like [askMap](./ask-map.md), each item's callback is a generator that can `yield*` other actions — but instead of waiting for one item to finish before starting the next, every item's story is advanced together and their actions are batched each tick. Use it when the per-item work is independent and you want it done as fast as possible.
+
+- **Built from:** `askRunParallel`, which drives every item's story in lockstep and batches their pending actions into a single dispatch per step.
+
+```typescript
+import { askMapParallel } from 'quidproquo-core';
+import { askKeyValueStoreGet } from 'quidproquo-core';
+
+export function* askLoadUsers(userIds: string[]) {
+  // Fetch every user record at the same time.
+  const users = yield* askMapParallel(userIds, function* (userId) {
+    return yield* askKeyValueStoreGet('users', userId);
+  });
+
+  return users;
+}
+```
+
+## Signature
+
+```typescript
+function* askMapParallel<T, R>(
+  items: T[],
+  askCallback: (item: T, index: number, srcArray: T[]) => AskResponse<R>,
+): AskResponse<R[]>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `items` | `T[]` | The array to iterate. |
+| `askCallback` | `(item: T, index: number, srcArray: T[]) => AskResponse<R>` | A generator called once per item. Receives the item, its zero-based index, and the source array. All invocations run concurrently. |
+
+## Returns
+
+`R[]` — a new array of the callback's return values, in the same order as `items` (result order is preserved regardless of completion order).
+
+## Notes
+
+- **Unbounded concurrency.** Every item starts at once. This is ideal for a handful of independent lookups, but for large arrays it can flood downstream resources (rate limits, connection pools) — reach for [askMapParallelBatch](./ask-map-parallel-batch.md) to cap how many run at a time.
+- Because all stories advance together, an item's callback must **not** depend on side effects from another item.
+- This is the helper the event pipeline uses to process a batch of records concurrently — see [askProcessEvent](../event/ask-process-event.md).
+
+## Related
+
+- [askMap](./ask-map.md) — the sequential version (one item at a time, in order).
+- [askMapParallelBatch](./ask-map-parallel-batch.md) — concurrency capped to a fixed batch size, with an optional delay between batches.
+- [askFlatMapParallelBatch](./ask-flat-map-parallel-batch.md) — batched parallel map that flattens the results one level.
+- [askProcessEvent](../event/ask-process-event.md) — the event pipeline that maps over records with this helper.

package/template/docusaurus/docs/actions/core/array/ask-map.md

@@ -0,0 +1,58 @@
+---
+title: askMap
+description: Map an array to a new array, running a story per item, one at a time.
+---
+
+# askMap
+
+Iterates an array and builds a new array from the result of a per-item callback — the async/story equivalent of `Array.prototype.map`. Each item's callback is itself a generator, so it can `yield*` other actions (read a record, call an API, etc.). Items are processed **sequentially**, one after another, in order.
+
+- **Built from:** a plain `for` loop that `yield*`s the callback for each item and collects the results.
+
+```typescript
+import { askMap } from 'quidproquo-core';
+import { askFileReadTextContents } from 'quidproquo-core';
+
+export function* askLoadTemplates(filepaths: string[]) {
+  // Read each template in turn and return the array of contents.
+  const contents = yield* askMap(filepaths, function* (filepath) {
+    return yield* askFileReadTextContents('templates', filepath);
+  });
+
+  return contents;
+}
+```
+
+## Signature
+
+```typescript
+function* askMap<T, R>(
+  items: T[],
+  askCallback: (item: T, index: number, srcArray: T[]) => AskResponse<R>,
+): AskResponse<R[]>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `items` | `T[]` | The array to iterate. |
+| `askCallback` | `(item: T, index: number, srcArray: T[]) => AskResponse<R>` | A generator called once per item. Receives the item, its zero-based index, and the source array. Whatever it returns becomes the corresponding element of the result array. |
+
+## Returns
+
+`R[]` — a new array of the callback's return values, in the same order as `items`.
+
+## Notes
+
+- **Sequential.** Each callback fully completes before the next item starts, so item _n_ can observe side effects of item _n − 1_. Use this when order matters or when you must not overwhelm a downstream resource.
+- For concurrency, use [askMapParallel](./ask-map-parallel.md) (all items at once) or [askMapParallelBatch](./ask-map-parallel-batch.md) (a bounded number at a time).
+
+## Related
+
+- [askMapParallel](./ask-map-parallel.md) — the same mapping, but every item runs concurrently.
+- [askMapParallelBatch](./ask-map-parallel-batch.md) — concurrency capped to a fixed batch size.
+- [askFilter](./ask-filter.md) — keep only items whose story returns `true`.
+- [askFlatMap](./ask-flat-map.md) — map to arrays, then flatten one level.
+- [askReduce](./ask-reduce.md) — fold the array into a single accumulated value.
+- [askArraySome](./ask-array-some.md) — stop early once any item's story returns `true`.