create-qpq-app 0.1.5

package/template/docusaurus/docs/actions/core/event/ask-process-event.md

@@ -0,0 +1,77 @@
+---
+title: askProcessEvent
+description: The generic event-processing pipeline that turns a raw platform trigger into matched story executions and a response.
+---
+
+# askProcessEvent
+
+`askProcessEvent` is the **event-processing pipeline** at the heart of every quidproquo service. When a platform trigger arrives — a queue message, an event-bus message, an HTTP request, a scheduled tick — the runtime hands the raw event to `askProcessEvent`, which figures out which story should handle it, runs that story, and shapes the response the platform expects.
+
+You rarely call `askProcessEvent` yourself: the framework's entry points (in the action-processor packages) call it for you, and you write the individual stories it dispatches to. It's documented here so you understand what happens between "a message lands" and "your story runs" — and so you can build custom service types on the same pipeline.
+
+- **Built from:** a sequence of per-service-type event actions — `askEventGetRecords`, `askEventMatchStory`, `askEventAutoRespond`, `askEventGetStorySession`, [askExecuteStory](../system/ask-execute-story.md), and `askEventTransformResponseResult` — each implemented by the action-processor for the platform the service runs on.
+
+## The pipeline
+
+For a given raw event, `askProcessEvent` runs:
+
+1. **`askEventGetRecords(...eventArguments)`** — extract the list of individual records from the raw platform event. One SQS batch, one EventBridge event, or one HTTP request is normalized into an array of records.
+2. For each record (in **parallel** via [askMapParallel](../../../actions/core/array/ask-map-parallel.md)):
+   1. **`askEventMatchStory(record, eventArguments)`** — decide which story runtime should handle this record, returning a `MatchStoryResult` (`{ runtime, runtimeOptions, config }`). No match is an error for that record.
+   2. **`askEventAutoRespond(record, matchResult)`** — an optional early exit. If it returns non-`null`, that value becomes the record's response and the story is **not** executed (used for auth failures, validation, CORS preflight, and similar short-circuits).
+   3. **`askEventGetStorySession(eventArguments, record, matchResult)`** — build the [story session](../../../actions/core/config/ask-config-get-application-info.md) (caller identity, context) the matched story will run under.
+   4. **[askExecuteStory](../system/ask-execute-story.md)`(runtime, [record, runtimeOptions], session)`** — run the matched story with the record as its argument. Each record's result is captured with [askCatch](../system/ask-catch.md), so one failing record doesn't abort the batch.
+3. **`askEventTransformResponseResult(processedRecords, ...eventArguments)`** — fold the per-record results into the single response shape the platform expects (e.g. an HTTP response, or SQS batch-item-failure list). A failure here is logged at `Fatal` and rethrown.
+
+## Signature
+
+```typescript
+function* askProcessEvent<
+  EventParams extends unknown[] = any[],
+  QpqEventRecord = any,
+  QpqEventRecordResponse = any,
+  MSR extends AnyMatchStoryResult = AnyMatchStoryResult,
+  EventResponse = any,
+>(...eventArguments: EventParams): AskResponse<EventResponse>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `...eventArguments` | `EventParams` | The raw event as delivered by the platform (e.g. the Lambda `event` and `context`). The shape is specific to the triggering service type; the matching action-processor's `askEventGetRecords` implementation knows how to read it. |
+
+## Returns
+
+`EventResponse` — the platform-shaped response produced by `askEventTransformResponseResult` (for example, an API Gateway HTTP response object).
+
+## FIFO ordering — `askProcessEventWithGroupOrdering`
+
+`askProcessEventWithGroupOrdering` is the ordered variant, used for FIFO queues and event buses where per-group order must be preserved.
+
+```typescript
+function* askProcessEventWithGroupOrdering<...>(
+  getRecordGroupKey: (record: QpqEventRecord) => string | undefined,
+  ...eventArguments: EventParams
+): AskResponse<EventResponse>;
+```
+
+Instead of processing records in parallel, it walks them **one at a time**. When a record fails, its group key is remembered and every later record in that same group is failed **without executing** — so the platform can redeliver the group in order rather than letting a later message overtake a failed earlier one. Records in other groups are unaffected.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `getRecordGroupKey` | `(record) => string \| undefined` | Returns the ordering group for a record (e.g. the FIFO message group id). Records with `undefined` are not group-ordered. |
+| `...eventArguments` | `EventParams` | The raw event, as with `askProcessEvent`. |
+
+## The pipeline actions
+
+The individual `askEvent*` actions above are **extension points**, not story-author API — each service type implements them in its action-processor package (e.g. the HTTP API event processors in `quidproquo-webserver`). You compose stories that get *matched and executed* by this pipeline; you don't yield these actions directly. Related transform hooks used by specific service types include `askEventTransformEventParams`, `askEventTransformEventRecord`, and `askEventResolveCaughtError`.
+
+## Related
+
+- [askExecuteStory](../system/ask-execute-story.md) — runs the matched story for each record.
+- [askCatch](../system/ask-catch.md) — isolates per-record failures so one bad record doesn't fail the batch.
+- [askMapParallel](../../../actions/core/array/ask-map-parallel.md) — runs the per-record processing concurrently in the non-FIFO pipeline.
+- [defineQueue](../../../config/core/queue.md) / [defineEventBus](../../../config/core/event-bus.md) — declare the FIFO sources this pipeline preserves ordering for.
+- [askQueueSendMessages](../queue/ask-queue-send-messages.md) / [askEventBusSendMessages](../event-bus/ask-event-bus-send-messages.md) — enqueue/publish the messages this pipeline delivers to consumer stories.
+- [defineRecurringSchedule](../../../config/core/recurring-schedule.md), [defineDeployEvent](../../../config/core/deploy-event.md), [defineNotifyError](../../../config/core/notify-error.md) — other event sources whose triggers flow through this pipeline.

package/template/docusaurus/docs/actions/core/event-bus/_category_.json

@@ -0,0 +1 @@
+{ "label": "Event Bus", "link": { "type": "generated-index", "description": "Publish messages to an event bus defined with defineEventBus." } }

package/template/docusaurus/docs/actions/core/event-bus/ask-event-bus-send-messages.md

@@ -0,0 +1,104 @@
+---
+title: askEventBusSendMessages
+description: Publish one or more messages to an event bus for its subscribers to consume.
+---
+
+# askEventBusSendMessages
+
+Publishes one or more messages to an [event bus](../../../config/core/event-bus.md). Every queue subscribed to the bus receives each message and runs its consumer story. Publishing is fire-and-forget — the action returns once the messages are accepted, not when subscribers finish.
+
+- **Action type:** `EventBusActionType.SendMessages`
+
+```typescript
+import { askEventBusSendMessages } from 'quidproquo-core';
+
+export function* onUserRegistered(user: { id: string; email: string }) {
+  yield* askEventBusSendMessages({
+    eventBusName: 'domain-events',
+    eventBusMessages: [
+      { type: 'user.created', payload: { userId: user.id, email: user.email } },
+    ],
+  });
+}
+```
+
+## Signature
+
+```typescript
+function* askEventBusSendMessages<T>(
+  eventBusSendMessageOptions: EventBusSendMessageOptions<T>,
+): AskResponse<void>;
+```
+
+## Parameters
+
+### `eventBusSendMessageOptions` — `EventBusSendMessageOptions<T>` (required)
+
+```typescript
+export interface EventBusSendMessageOptions<T> {
+  eventBusName: string;
+  eventBusMessages: EventBusMessage<T>[];
+}
+```
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `eventBusName` | `string` | Name of the bus to publish to — must match a bus declared with [defineEventBus](../../../config/core/event-bus.md) (or one shared via its `owner` option). |
+| `eventBusMessages` | `EventBusMessage<T>[]` | The messages to publish. |
+
+### `EventBusMessage<T>`
+
+```typescript
+export type EventBusMessage<T> = {
+  type: string;
+  payload: T;
+  groupId?: string;
+  deduplicationId?: string;
+};
+```
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `type` | `string` | The message type. Subscribing queues match this against their processor patterns to pick a consumer story. |
+| `payload` | `T` | The message body, serialized as JSON on the wire. |
+| `groupId` | `string` (optional) | **FIFO buses only.** Messages sharing a group are delivered in order. Defaults to the bus name (global ordering). Ignored on non-FIFO buses. |
+| `deduplicationId` | `string` (optional) | **FIFO buses only.** Suppresses duplicate publishes within SNS's 5-minute window. Defaults to a generated uuid (no deduplication). Ignored on non-FIFO buses. |
+
+## Returns
+
+`void` — the action completes once the messages are accepted by the bus. It does not wait for subscribers.
+
+## Errors
+
+| Error | Meaning |
+| --- | --- |
+| `EventBusSendMessagesErrorTypeEnum.AccessDenied` | The caller lacks permission to publish to the topic. |
+| `EventBusSendMessagesErrorTypeEnum.TopicNotFound` | The underlying topic does not exist. |
+| `EventBusSendMessagesErrorTypeEnum.ServiceUnavailable` | Internal error or throttling from the messaging service. |
+
+Errors thrown by actions can be caught with `askCatch` from quidproquo-core. It returns an `EitherActionResult` — `{ success: true, result }` on success, or `{ success: false, error }` on failure:
+
+```typescript
+const outcome = yield* askCatch(
+  askEventBusSendMessages({
+    eventBusName: 'domain-events',
+    eventBusMessages: [{ type: 'user.created', payload: { userId } }],
+  }),
+);
+
+if (!outcome.success) {
+  // outcome.error.errorType / outcome.error.errorText
+}
+```
+
+## Notes
+
+- On AWS the bus is an SNS topic; messages are published with the caller's story session attached, which the pipeline restores when the subscriber's story runs.
+- For FIFO ordering, set `groupId` per message to control which messages must stay ordered relative to each other.
+
+## Related
+
+- [defineEventBus](../../../config/core/event-bus.md) — declares the bus this action publishes to.
+- [defineQueue](../../../config/core/queue.md) — a queue subscribes to a bus (via `eventBusSubscriptions`) to consume its messages.
+- [askQueueSendMessages](../queue/ask-queue-send-messages.md) — send directly to a specific queue instead of fanning out through a bus.
+- [askProcessEvent](../event/ask-process-event.md) — the pipeline that delivers published messages to consumer stories and preserves FIFO group ordering.

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

@@ -0,0 +1,7 @@
+{
+  "label": "File",
+  "link": {
+    "type": "generated-index",
+    "description": "File actions read and write files on a storage drive defined with defineStorageDrive."
+  }
+}

package/template/docusaurus/docs/actions/core/file/ask-file-delete.md

@@ -0,0 +1,69 @@
+---
+title: askFileDelete
+description: Delete one or more files from a storage drive.
+---
+
+# askFileDelete
+
+Deletes one or more files from a [storage drive](../../../config/core/storage-drive.md). Deleting a file that does not exist is treated as a success, so this action is safe to call idempotently.
+
+- **Action type:** `FileActionType.Delete`
+- **On AWS:** issues a single S3 `DeleteObjects` batch request against the drive's bucket for all of the given paths.
+
+```typescript
+import { askFileDelete } from 'quidproquo-core';
+
+export function* askRemoveOldExports() {
+  yield* askFileDelete('reports', ['exports/january.csv', 'exports/february.csv']);
+}
+```
+
+## Signature
+
+```typescript
+function* askFileDelete(
+  drive: string,
+  filepaths: string[],
+): AskResponse<string[]>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `drive` | `string` | Name of the storage drive to delete from — must match a drive declared with [defineStorageDrive](../../../config/core/storage-drive.md) (or one shared via its `owner` option). |
+| `filepaths` | `string[]` | The paths of the files to delete within the drive, forward-slash delimited. Pass one path or many in a single call. |
+
+## Returns
+
+`string[]` — the paths that **failed** to delete. An empty array means every file was deleted (or did not exist to begin with). A non-empty array is a partial failure you may choose to retry.
+
+## Errors
+
+| Error | Meaning |
+| --- | --- |
+| `FileDeleteErrorTypeEnum.AccessDenied` | The caller lacks permission to delete from this drive (e.g. a foreign drive shared without write access). |
+| `FileDeleteErrorTypeEnum.DriveNotFound` | No storage drive with that name exists in the deployed config. |
+
+Errors thrown by actions can be caught with `askCatch` from quidproquo-core. It returns an `EitherActionResult` — `{ success: true, result }` on success, or `{ success: false, error }` on failure:
+
+```typescript
+const outcome = yield* askCatch(askFileDelete('reports', ['exports/old.csv']));
+
+if (outcome.success) {
+  const failedPaths = outcome.result; // empty if all deleted
+} else {
+  // outcome.error.errorType / outcome.error.errorText
+}
+```
+
+## Notes
+
+- If the drive declares an `onEvent.delete` handler in [defineStorageDrive](../../../config/core/storage-drive.md#file-events-onevent), that story is triggered for the deleted files.
+
+## Related
+
+- [defineStorageDrive](../../../config/core/storage-drive.md) — declares the drive this action deletes from.
+- [askFileExists](./ask-file-exists.md) — check whether a file is present.
+- [askFileListDirectory](./ask-file-list-directory.md) — enumerate files before deleting.
+- [askFileWriteTextContents](./ask-file-write-text-contents.md) — the write counterpart.

package/template/docusaurus/docs/actions/core/file/ask-file-exists.md

@@ -0,0 +1,68 @@
+---
+title: askFileExists
+description: Check whether a file exists on a storage drive.
+---
+
+# askFileExists
+
+Checks whether a file exists on a [storage drive](../../../config/core/storage-drive.md) without reading its contents.
+
+- **Action type:** `FileActionType.Exists`
+- **On AWS:** performs an S3 `HeadObject` on the drive's bucket — a metadata lookup, so no file body is transferred.
+
+```typescript
+import { askFileExists, askFileWriteTextContents } from 'quidproquo-core';
+
+export function* askEnsureSeedFile() {
+  const exists = yield* askFileExists('config', 'seed/defaults.json');
+
+  if (!exists) {
+    yield* askFileWriteTextContents('config', 'seed/defaults.json', '{}');
+  }
+}
+```
+
+## Signature
+
+```typescript
+function* askFileExists(
+  drive: string,
+  filepath: string,
+): AskResponse<boolean>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `drive` | `string` | Name of the storage drive to check — must match a drive declared with [defineStorageDrive](../../../config/core/storage-drive.md) (or one shared via its `owner` option). |
+| `filepath` | `string` | Path of the file within the drive, forward-slash delimited, e.g. `'uploads/avatar.png'`. |
+
+## Returns
+
+`boolean` — `true` if a file exists at the path, `false` otherwise.
+
+## Errors
+
+| Error | Meaning |
+| --- | --- |
+| `FileExistsErrorTypeEnum.AccessDenied` | The caller lacks permission to check existence on this drive. |
+
+Errors thrown by actions can be caught with `askCatch` from quidproquo-core. It returns an `EitherActionResult` — `{ success: true, result }` on success, or `{ success: false, error }` on failure:
+
+```typescript
+const outcome = yield* askCatch(askFileExists('config', 'seed/defaults.json'));
+
+if (outcome.success) {
+  const exists = outcome.result;
+} else {
+  // outcome.error.errorType / outcome.error.errorText
+}
+```
+
+## Related
+
+- [defineStorageDrive](../../../config/core/storage-drive.md) — declares the drive this action checks.
+- [askFileIsColdStorage](./ask-file-is-cold-storage.md) — check whether a file that exists is in a cold (archival) tier before reading it.
+- [askFileReadTextContents](./ask-file-read-text-contents.md) — read the file once you know it exists.
+- [askFileDelete](./ask-file-delete.md) — remove a file.

package/template/docusaurus/docs/actions/core/file/ask-file-generate-temporary-secure-url.md

@@ -0,0 +1,75 @@
+---
+title: askFileGenerateTemporarySecureUrl
+description: Generate a time-limited, signed URL to download a file directly from a storage drive.
+---
+
+# askFileGenerateTemporarySecureUrl
+
+Generates a temporary, signed URL that lets a client **download** a single file directly from a [storage drive](../../../config/core/storage-drive.md) without routing the bytes through your service. The URL grants read access to just that one file and stops working once it expires.
+
+- **Action type:** `FileActionType.GenerateTemporarySecureUrl`
+- **On AWS:** returns a SigV4 presigned S3 `GetObject` URL for the object. The expiry cannot exceed **7 days** — the maximum lifetime of a SigV4 presigned URL.
+
+```typescript
+import { askFileGenerateTemporarySecureUrl } from 'quidproquo-core';
+
+export function* askGetAvatarDownloadUrl(userId: string) {
+  // Valid for 5 minutes
+  const url = yield* askFileGenerateTemporarySecureUrl('user-uploads', `avatars/${userId}.png`, 5 * 60 * 1000);
+  return url;
+}
+```
+
+## Signature
+
+```typescript
+function* askFileGenerateTemporarySecureUrl(
+  drive: string,
+  filepath: string,
+  expirationMs: number,
+): AskResponse<string>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `drive` | `string` | Name of the storage drive the file lives on — must match a drive declared with [defineStorageDrive](../../../config/core/storage-drive.md) (or one shared via its `owner` option). |
+| `filepath` | `string` | Path of the file within the drive, forward-slash delimited. |
+| `expirationMs` | `number` | How long the URL stays valid, in milliseconds. Must not exceed 7 days (`604800000` ms). |
+
+## Returns
+
+`string` — a fully-qualified, signed URL a client can `GET` to download the file until it expires.
+
+## Errors
+
+| Error | Meaning |
+| --- | --- |
+| `FileGenerateTemporarySecureUrlErrorTypeEnum.ExpirationTooLong` | The requested `expirationMs` exceeds the 7 day maximum for signed URLs. |
+
+Errors thrown by actions can be caught with `askCatch` from quidproquo-core. It returns an `EitherActionResult` — `{ success: true, result }` on success, or `{ success: false, error }` on failure:
+
+```typescript
+const outcome = yield* askCatch(
+  askFileGenerateTemporarySecureUrl('user-uploads', 'avatars/42.png', 5 * 60 * 1000),
+);
+
+if (outcome.success) {
+  const url = outcome.result;
+} else {
+  // outcome.error.errorType / outcome.error.errorText
+}
+```
+
+## Notes
+
+- The URL is generated from a signature only — it does not verify that the file exists. Requesting a URL for a missing file succeeds, but the `GET` against it will 404.
+- For browser downloads, allow the client origin with `defineStorageDriveCorsSettings` (quidproquo-webserver).
+
+## Related
+
+- [defineStorageDrive](../../../config/core/storage-drive.md) — declares the drive the URL points into.
+- [askFileGenerateTemporaryUploadSecureUrl](./ask-file-generate-temporary-upload-secure-url.md) — the upload counterpart (signed `PUT`).
+- [askFileReadBinaryContents](./ask-file-read-binary-contents.md) — read bytes through your service instead of handing out a URL.
+- [askEventDocGenerateAssetDownloadUrl](../../features/event-doc/ask-event-doc-generate-asset-upload-url.md#askeventdocgenerateassetdownloadurl) — wraps this to mint a download URL for a document asset.

package/template/docusaurus/docs/actions/core/file/ask-file-generate-temporary-upload-secure-url.md

@@ -0,0 +1,91 @@
+---
+title: askFileGenerateTemporaryUploadSecureUrl
+description: Generate a time-limited, signed URL that lets a client upload a file directly to a storage drive.
+---
+
+# askFileGenerateTemporaryUploadSecureUrl
+
+Generates a temporary, signed URL that lets a client **upload** a single file directly to a [storage drive](../../../config/core/storage-drive.md). The bytes go straight to storage instead of through your service, which is ideal for large uploads from a browser. The URL grants write access to just that one path and stops working once it expires.
+
+- **Action type:** `FileActionType.GenerateTemporaryUploadSecureUrl`
+- **On AWS:** returns a SigV4 presigned S3 `PutObject` URL for the object. The expiry cannot exceed **7 days** — the maximum lifetime of a SigV4 presigned URL. If `contentType` is supplied it is bound into the signature, so the upload's `Content-Type` header must match.
+
+```typescript
+import { askFileGenerateTemporaryUploadSecureUrl } from 'quidproquo-core';
+
+export function* askGetAvatarUploadUrl(userId: string) {
+  // Valid for 15 minutes, pinned to PNG
+  const url = yield* askFileGenerateTemporaryUploadSecureUrl(
+    'user-uploads',
+    `avatars/${userId}.png`,
+    15 * 60 * 1000,
+    { contentType: 'image/png' },
+  );
+  return url;
+}
+```
+
+## Signature
+
+```typescript
+function* askFileGenerateTemporaryUploadSecureUrl(
+  drive: string,
+  filepath: string,
+  expirationMs: number,
+  advancedOptions?: {
+    contentType?: string;
+  },
+): AskResponse<string>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `drive` | `string` | Name of the storage drive to upload to — must match a drive declared with [defineStorageDrive](../../../config/core/storage-drive.md) (or one shared via its `owner` option). |
+| `filepath` | `string` | Destination path within the drive the client is allowed to write to, forward-slash delimited. |
+| `expirationMs` | `number` | How long the URL stays valid, in milliseconds. Must not exceed 7 days (`604800000` ms). |
+| `advancedOptions` | `object` | Optional upload options — see below. |
+
+### `advancedOptions`
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `contentType` | `string` | – | Pins the `Content-Type` of the upload into the signature. When set, the client must send a matching `Content-Type` header or the `PUT` is rejected. |
+
+## Returns
+
+`string` — a fully-qualified, signed URL a client can `PUT` the file to until it expires.
+
+## Errors
+
+| Error | Meaning |
+| --- | --- |
+| `FileGenerateTemporaryUploadSecureUrlErrorTypeEnum.ExpirationTooLong` | The requested `expirationMs` exceeds the 7 day maximum for signed URLs. |
+
+Errors thrown by actions can be caught with `askCatch` from quidproquo-core. It returns an `EitherActionResult` — `{ success: true, result }` on success, or `{ success: false, error }` on failure:
+
+```typescript
+const outcome = yield* askCatch(
+  askFileGenerateTemporaryUploadSecureUrl('user-uploads', 'avatars/42.png', 15 * 60 * 1000),
+);
+
+if (outcome.success) {
+  const url = outcome.result;
+} else {
+  // outcome.error.errorType / outcome.error.errorText
+}
+```
+
+## Notes
+
+- For browser uploads, allow the client origin with `defineStorageDriveCorsSettings` (quidproquo-webserver).
+- If the drive declares an `onEvent.create` handler in [defineStorageDrive](../../../config/core/storage-drive.md#file-events-onevent), it fires when the client completes the upload — a convenient hook for post-processing.
+
+## Related
+
+- [defineStorageDrive](../../../config/core/storage-drive.md) — declares the drive the URL uploads into.
+- [askFileGenerateTemporarySecureUrl](./ask-file-generate-temporary-secure-url.md) — the download counterpart (signed `GET`).
+- [askFileWriteBinaryContents](./ask-file-write-binary-contents.md) — write bytes through your service instead of handing out a URL.
+- [askFileWriteTextContents](./ask-file-write-text-contents.md) — server-side text write.
+- [askEventDocGenerateAssetUploadUrl](../../features/event-doc/ask-event-doc-generate-asset-upload-url.md) — wraps this to mint an upload URL for a document asset.

package/template/docusaurus/docs/actions/core/file/ask-file-is-cold-storage.md

@@ -0,0 +1,72 @@
+---
+title: askFileIsColdStorage
+description: Check whether a file on a storage drive is in a cold (archival) tier.
+---
+
+# askFileIsColdStorage
+
+Reports whether a file on a [storage drive](../../../config/core/storage-drive.md) currently sits in a **cold** (archival) storage tier. Files in cold tiers cannot be read directly — use this check before a read so you can restore or route around them instead of hitting an `InvalidStorageClass` error.
+
+- **Action type:** `FileActionType.IsColdStorage`
+- **On AWS:** reads the object's S3 storage class (via `HeadObject`) and returns `true` when it is an archival class such as Glacier or Glacier Deep Archive.
+
+```typescript
+import { askFileIsColdStorage, askFileReadTextContents } from 'quidproquo-core';
+
+export function* askReadArchivableReport(filepath: string) {
+  const isCold = yield* askFileIsColdStorage('reports', filepath);
+
+  if (isCold) {
+    // File is archived — schedule a restore rather than reading it now.
+    return null;
+  }
+
+  return yield* askFileReadTextContents('reports', filepath);
+}
+```
+
+## Signature
+
+```typescript
+function* askFileIsColdStorage(
+  drive: string,
+  filepath: string,
+): AskResponse<boolean>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `drive` | `string` | Name of the storage drive the file lives on — must match a drive declared with [defineStorageDrive](../../../config/core/storage-drive.md) (or one shared via its `owner` option). |
+| `filepath` | `string` | Path of the file within the drive, forward-slash delimited. |
+
+## Returns
+
+`boolean` — `true` if the file is in a cold/archival [storage tier](../../../config/core/storage-drive.md#storagedrivetier), `false` if it is in a directly-readable tier.
+
+## Errors
+
+| Error | Meaning |
+| --- | --- |
+| `FileIsColdStorageErrorTypeEnum.AccessDenied` | The caller lacks permission to read the file's metadata. |
+| `FileIsColdStorageErrorTypeEnum.FileNotFound` | No file exists at the given path. |
+| `FileIsColdStorageErrorTypeEnum.DriveNotFound` | No storage drive with that name exists in the deployed config. |
+
+Errors thrown by actions can be caught with `askCatch` from quidproquo-core. It returns an `EitherActionResult` — `{ success: true, result }` on success, or `{ success: false, error }` on failure:
+
+```typescript
+const outcome = yield* askCatch(askFileIsColdStorage('reports', 'exports/2020.csv'));
+
+if (outcome.success) {
+  const isCold = outcome.result;
+} else {
+  // outcome.error.errorType / outcome.error.errorText
+}
+```
+
+## Related
+
+- [defineStorageDrive](../../../config/core/storage-drive.md) — declares the drive, its tiers, and lifecycle rules that move files into cold storage.
+- [askFileReadTextContents](./ask-file-read-text-contents.md) / [askFileReadBinaryContents](./ask-file-read-binary-contents.md) — reads that fail with `InvalidStorageClass` on cold files.
+- [askFileExists](./ask-file-exists.md) — check presence without reading.

package/template/docusaurus/docs/actions/core/file/ask-file-list-directory.md

@@ -0,0 +1,97 @@
+---
+title: askFileListDirectory
+description: List the files under a folder path on a storage drive, one page at a time.
+---
+
+# askFileListDirectory
+
+Lists the files under a folder path on a [storage drive](../../../config/core/storage-drive.md). Results are paged — each call returns up to `maxFiles` entries plus a `pageToken` you pass back to fetch the next page.
+
+- **Action type:** `FileActionType.ListDirectory`
+- **On AWS:** performs a paged S3 `ListObjectsV2` under the folder prefix on the drive's bucket, stamping each returned entry with the `drive` name.
+
+```typescript
+import { askFileListDirectory } from 'quidproquo-core';
+
+export function* askListReportPage(pageToken?: string) {
+  const page = yield* askFileListDirectory('reports', 'exports/', 50, pageToken);
+
+  for (const file of page.fileInfos) {
+    // file.filepath, file.isDir, ...
+  }
+
+  return page.pageToken; // undefined when there are no more pages
+}
+```
+
+## Signature
+
+```typescript
+function* askFileListDirectory(
+  drive: string,
+  folderPath: string,
+  maxFiles?: number,
+  pageToken?: string,
+): AskResponse<DirectoryList>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `drive` | `string` | Name of the storage drive to list — must match a drive declared with [defineStorageDrive](../../../config/core/storage-drive.md) (or one shared via its `owner` option). |
+| `folderPath` | `string` | The folder prefix to list under, forward-slash delimited, e.g. `'exports/'`. |
+| `maxFiles` | `number` | Maximum entries to return in this page. Defaults to `1000`. |
+| `pageToken` | `string` | Token returned by a previous call to fetch the next page. Omit for the first page. |
+
+## Returns
+
+`DirectoryList` — a page of results:
+
+```typescript
+interface DirectoryList {
+  fileInfos: FileInfo[];
+  pageToken?: string; // present only when more pages remain
+}
+
+interface FileInfo {
+  filepath: string;
+  drive: string;
+  isDir: boolean;
+  hashMd5?: string;
+}
+```
+
+When `pageToken` is `undefined`, the last page has been returned.
+
+## Errors
+
+| Error | Meaning |
+| --- | --- |
+| `FileListDirectoryErrorTypeEnum.AccessDenied` | The caller lacks permission to list this drive. |
+| `FileListDirectoryErrorTypeEnum.DirectoryNotFound` | No directory exists at the given `folderPath`. |
+| `FileListDirectoryErrorTypeEnum.NotADirectory` | The `folderPath` points at a file rather than a directory. |
+| `FileListDirectoryErrorTypeEnum.DriveNotFound` | No storage drive with that name exists in the deployed config. |
+
+Errors thrown by actions can be caught with `askCatch` from quidproquo-core. It returns an `EitherActionResult` — `{ success: true, result }` on success, or `{ success: false, error }` on failure:
+
+```typescript
+const outcome = yield* askCatch(askFileListDirectory('reports', 'exports/'));
+
+if (outcome.success) {
+  const page = outcome.result;
+} else {
+  // outcome.error.errorType / outcome.error.errorText
+}
+```
+
+## Notes
+
+- To pull **every** page in one call, use `askFileListAllDirectory(drive, folderPath)` — a companion requester exported from quidproquo-core that loops internally and returns a flat `FileInfo[]`. Prefer paging with `askFileListDirectory` for large directories.
+
+## Related
+
+- [defineStorageDrive](../../../config/core/storage-drive.md) — declares the drive this action lists.
+- [askFileExists](./ask-file-exists.md) — check a single path instead of listing.
+- [askFileDelete](./ask-file-delete.md) — delete files discovered by a listing.
+- [askFileReadTextContents](./ask-file-read-text-contents.md) — read a listed file's contents.