create-qpq-app 0.1.5

package/template/docusaurus/docs/actions/core/key-value-store/ask-key-value-store-upsert-with-retry.md

@@ -0,0 +1,65 @@
+---
+title: askKeyValueStoreUpsertWithRetry
+description: Upsert a record into a key-value store, retrying automatically on transient failures.
+---
+
+# askKeyValueStoreUpsertWithRetry
+
+Writes a record with [askKeyValueStoreUpsert](./ask-key-value-store-upsert.md), automatically retrying when the store is temporarily unavailable. Use it for writes that must succeed through transient DynamoDB throttling rather than failing the story on the first hiccup.
+
+- **Built from:** wraps [askKeyValueStoreUpsert](./ask-key-value-store-upsert.md) in `askRetry`, retrying only on `KeyValueStoreUpsertErrorTypeEnum.ServiceUnavailable`. It is a helper story, not a distinct action.
+
+```typescript
+import { askKeyValueStoreUpsertWithRetry } from 'quidproquo-core';
+
+interface User {
+  userId: string;
+  name: string;
+}
+
+export function* askSaveUserReliably(user: User) {
+  yield* askKeyValueStoreUpsertWithRetry('users', user, { maxRetries: 5 });
+}
+```
+
+## Signature
+
+```typescript
+function* askKeyValueStoreUpsertWithRetry<KvsItem>(
+  keyValueStoreName: string,
+  item: KvsItem,
+  options?: KeyValueStoreUpsertWithRetryOptions,
+): AskResponse<void>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `keyValueStoreName` | `string` | Name of the store to write to — must match a store declared with [defineKeyValueStore](../../../config/core/key-value-store.md). |
+| `item` | `KvsItem` | The full record to write (must include the store's key attributes). |
+| `options` | `KeyValueStoreUpsertWithRetryOptions` | Retry settings plus all [askKeyValueStoreUpsert](./ask-key-value-store-upsert.md#keyvaluestoreupsertoptions) options — see below. |
+
+### `KeyValueStoreUpsertWithRetryOptions`
+
+Extends `KeyValueStoreUpsertOptions` (`ttlInSeconds`, `ifNotExists`) with:
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `maxRetries` | `number` | `3` | Maximum retry attempts. Retries are spaced ~250 ms apart. |
+
+## Returns
+
+`void` — the story resumes once the write has committed (or throws after exhausting the retries).
+
+## Notes
+
+- Only `ServiceUnavailable` (throttling / transient DynamoDB errors) is retried. A `Conflict` from an `ifNotExists` write is **not** retried — that's a genuine key collision, not a transient fault. If every attempt fails, the last error is re-thrown.
+- Errors that escape the retries surface the same `KeyValueStoreUpsertErrorTypeEnum` members as the plain upsert; catch them with `askCatch`.
+
+## Related
+
+- [askKeyValueStoreUpsert](./ask-key-value-store-upsert.md) — the single-attempt action this wraps.
+- [askKeyValueStoreUpdate](./ask-key-value-store-update.md) — patch attributes instead of replacing the item.
+- [defineKeyValueStore](../../../config/core/key-value-store.md) — declares the store.
+- [askEventDocEventWrite](../../features/event-doc/ask-event-doc-event-write.md) — uses this with `ifNotExists` to conditionally claim an event's log slot.

package/template/docusaurus/docs/actions/core/key-value-store/ask-key-value-store-upsert.md

@@ -0,0 +1,71 @@
+---
+title: askKeyValueStoreUpsert
+description: Write (insert or replace) a whole record into a key-value store.
+---
+
+# askKeyValueStoreUpsert
+
+Writes a complete record into a [key-value store](../../../config/core/key-value-store.md). If a record with the same key already exists it is replaced; otherwise a new one is created. To patch individual attributes without replacing the whole item, use [askKeyValueStoreUpdate](./ask-key-value-store-update.md) instead.
+
+- **Action type:** `KeyValueStoreActionType.Upsert`
+
+```typescript
+import { askKeyValueStoreUpsert } from 'quidproquo-core';
+
+interface User {
+  userId: string;
+  name: string;
+  email: string;
+}
+
+export function* askSaveUser(user: User) {
+  yield* askKeyValueStoreUpsert('users', user);
+}
+```
+
+## Signature
+
+```typescript
+function* askKeyValueStoreUpsert<KvsItem>(
+  keyValueStoreName: string,
+  item: KvsItem,
+  options?: KeyValueStoreUpsertOptions,
+): AskResponse<void>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `keyValueStoreName` | `string` | Name of the store to write to — must match a store declared with [defineKeyValueStore](../../../config/core/key-value-store.md) (or one shared via its `owner` option). |
+| `item` | `KvsItem` | The full record to write. It must include the store's partition key (and sort key, if any) as attributes. |
+| `options` | `KeyValueStoreUpsertOptions` | Optional write options — see below. |
+
+### `KeyValueStoreUpsertOptions`
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `ttlInSeconds` | `number` | – | Time-to-live in seconds; sets the record's expiry (used with the store's `ttlAttribute`). |
+| `ifNotExists` | `boolean` | `false` | Conditional insert: only write when no item with the same key exists. A losing concurrent writer receives `KeyValueStoreUpsertErrorTypeEnum.Conflict` instead of silently overwriting — the primitive for optimistic-concurrency schemes (e.g. append-only event logs where the sort key is a claimed index). |
+
+## Returns
+
+`void` — the story resumes once the write has committed.
+
+## Errors
+
+| Error | Meaning |
+| --- | --- |
+| `KeyValueStoreUpsertErrorTypeEnum.ServiceUnavailable` | DynamoDB internal error or throttling. |
+| `KeyValueStoreUpsertErrorTypeEnum.ResourceNotFound` | The underlying table does not exist. |
+| `KeyValueStoreUpsertErrorTypeEnum.Conflict` | A conditional (`ifNotExists`) write lost to an existing item. Namespaced — not the generic `ErrorTypeEnum.Conflict` — so retry logic can target the write race specifically without also catching domain-level conflicts. |
+
+Catch errors with `askCatch` — it returns `{ success: true, result }` or `{ success: false, error }`.
+
+## Related
+
+- [defineKeyValueStore](../../../config/core/key-value-store.md) — declares the store, its keys, and its TTL attribute.
+- [askKeyValueStoreUpsertWithRetry](./ask-key-value-store-upsert-with-retry.md) — the same write, retried automatically on transient failures.
+- [askKeyValueStoreUpdate](./ask-key-value-store-update.md) — patch attributes instead of replacing the item.
+- [askKeyValueStoreGet](./ask-key-value-store-get.md) — read the record back.
+- [askKeyValueStoreDelete](./ask-key-value-store-delete.md) — remove the record.

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

@@ -0,0 +1,7 @@
+{
+  "label": "Log",
+  "link": {
+    "type": "generated-index",
+    "description": "Structured logging from within a story."
+  }
+}

package/template/docusaurus/docs/actions/core/log/ask-log-create.md

@@ -0,0 +1,64 @@
+---
+title: askLogCreate
+description: Write a structured log line at a given log level from within a story.
+---
+
+# askLogCreate
+
+Writes a log entry at a specified [log level](#loglevelenum), with a message and optional structured data.
+
+- **Action type:** `LogActionType.Create`
+- **On AWS:** the line is written to the function's stdout (`console.log`), formatted as `` `${logLevel}: ${msg}` ``, with any `data` passed through as a second argument. It flows to CloudWatch Logs like any other Lambda output. This is separate from the story's replayable event history — see [askLogDisableEventHistory](./ask-log-disable-event-history.md).
+
+```typescript
+import { askLogCreate, LogLevelEnum } from 'quidproquo-core';
+
+export function* askProcessOrder(orderId: string) {
+  yield* askLogCreate(LogLevelEnum.Info, 'Processing order', { orderId });
+  // ...
+}
+```
+
+## Signature
+
+```typescript
+function* askLogCreate(
+  logLevel: LogLevelEnum,
+  msg: string,
+  data?: any,
+): AskResponse<void>;
+```
+
+## Parameters
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| `logLevel` | `LogLevelEnum` | – | Severity of the entry. See [`LogLevelEnum`](#loglevelenum). |
+| `msg` | `string` | – | The log message. |
+| `data` | `any` | – | Optional structured payload logged alongside the message. Omitted from output entirely when not provided. |
+
+### `LogLevelEnum`
+
+Numeric enum ordered from most to least severe (the value is the number shown before the message).
+
+| Member | Value | Meaning |
+| --- | --- | --- |
+| `LogLevelEnum.Fatal` | `0` | The application encountered an event or state in which a crucial business function is no longer working — e.g. it cannot reach a critical data store, or every payment system is down so users cannot check out. |
+| `LogLevelEnum.Error` | `1` | The application hit an issue preventing one or more functions from working properly, but other paths still work — e.g. one payment provider is unavailable while checkout still succeeds through another. |
+| `LogLevelEnum.Warn` | `2` | Something unexpected happened that might disturb a process, but the code can continue — e.g. a parsing error that left a single document unprocessed. |
+| `LogLevelEnum.Info` | `3` | The standard level: something happened or the application entered a certain state. Purely informative — e.g. recording which user requested authorization and whether it succeeded. |
+| `LogLevelEnum.Debug` | `4` | Diagnostic information for troubleshooting or for verifying behaviour in a test environment. Less granular than `Trace`, but more than you need day to day. |
+| `LogLevelEnum.Trace` | `5` | The most fine-grained level, for rare cases needing full visibility into what the application and its third-party libraries are doing. Expect it to be very verbose. |
+
+## Returns
+
+`void` — the story resumes once the entry has been logged.
+
+## Notes
+
+- For interpolated messages where you also want the individual values captured structurally, use [askLogTemplateLiteral](./ask-log-template-literal.md).
+
+## Related
+
+- [askLogTemplateLiteral](./ask-log-template-literal.md) — log an interpolated message as a tagged template.
+- [askLogDisableEventHistory](./ask-log-disable-event-history.md) — control whether the story's full action history is persisted.

package/template/docusaurus/docs/actions/core/log/ask-log-disable-event-history.md

@@ -0,0 +1,53 @@
+---
+title: askLogDisableEventHistory
+description: Stop the current story's full action-by-action event history from being persisted.
+---
+
+# askLogDisableEventHistory
+
+Controls whether the **event history** — the recorded, replayable log of every action a story yielded — is persisted for the current execution.
+
+- **Action type:** `LogActionType.DisableEventHistory`
+- **On AWS:** when a story finishes, the runtime writes a `StoryResult` (including its `history` of processed actions) to the log storage drive (an S3 bucket) keyed by correlation id. Disabling event history for a correlation strips that `history` down to only the log entries (`Create`, `TemplateLiteral`, and `DisableEventHistory` actions) before it is written; all other actions are filtered out.
+
+Every action a story runs — config reads, key-value lookups, network calls, and their inputs/outputs — is normally captured in this history so a run can be inspected or replayed. Disable it when a story handles **sensitive data** you do not want persisted (secrets, PII, payment details) or when the history would be **prohibitively large**. Your explicit log lines are still kept.
+
+```typescript
+import { askLogDisableEventHistory } from 'quidproquo-core';
+
+export function* askHandlePayment(cardNumber: string) {
+  // Don't persist the full action history for this run — it touches card data.
+  yield* askLogDisableEventHistory(false, 'Handles raw card data');
+  // ...
+}
+```
+
+## Signature
+
+```typescript
+function* askLogDisableEventHistory(
+  enable: boolean,
+  reason: string,
+): AskResponse<void>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `enable` | `boolean` | Whether event history is **enabled** for this correlation. Pass `false` to disable it (strip the history to log entries only); pass `true` to re-enable it. |
+| `reason` | `string` | A human-readable note explaining why history was disabled or re-enabled. Recorded for audit purposes. |
+
+## Returns
+
+`void` — the story resumes once the setting has been applied.
+
+## Notes
+
+- The setting is scoped to the current execution's correlation id, not global.
+- Log entries created with [askLogCreate](./ask-log-create.md) and [askLogTemplateLiteral](./ask-log-template-literal.md) are always retained even when event history is disabled.
+
+## Related
+
+- [askLogCreate](./ask-log-create.md) — write a log line that is kept regardless of this setting.
+- [askLogTemplateLiteral](./ask-log-template-literal.md) — log an interpolated message.

package/template/docusaurus/docs/actions/core/log/ask-log-template-literal.md

@@ -0,0 +1,55 @@
+---
+title: askLogTemplateLiteral
+description: Log an interpolated message written as a tagged template literal.
+---
+
+# askLogTemplateLiteral
+
+Logs a message written as a [tagged template literal](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals#tagged_templates), keeping the literal string parts and the interpolated values separate so both the reconstructed message and the individual values are captured.
+
+- **Action type:** `LogActionType.TemplateLiteral`
+- **On AWS:** the string parts and values are recombined into the final message and written to stdout (`console.log`), flowing to CloudWatch Logs.
+
+Because it is a tag function, you call it by placing the template literal directly after it — no parentheses:
+
+```typescript
+import { askLogTemplateLiteral } from 'quidproquo-core';
+
+export function* askGreetUser(userId: string, age: number) {
+  yield* askLogTemplateLiteral`User ${userId} is ${age} years old`;
+}
+```
+
+## Signature
+
+```typescript
+function* askLogTemplateLiteral(
+  strings: TemplateStringsArray,
+  ...variables: DecomposedStringPrimitive[]
+): AskResponse<void>;
+```
+
+## Parameters
+
+These arguments are supplied automatically by the JavaScript tagged-template mechanism — you do not pass them by hand.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `strings` | `TemplateStringsArray` | The literal (non-interpolated) string segments of the template. |
+| `variables` | `DecomposedStringPrimitive[]` | The interpolated `${...}` values, in order. `DecomposedStringPrimitive` is `string \| number \| boolean \| symbol \| null \| undefined \| object`. |
+
+Internally these are stored as a `DecomposedString` — a `[strings, variables]` tuple — so the message can be reconstructed while keeping each interpolated value addressable on its own.
+
+## Returns
+
+`void` — the story resumes once the entry has been logged.
+
+## Notes
+
+- `askLog` is exported from quidproquo-core as an alias for `askLogTemplateLiteral`; the two are identical.
+- Unlike [askLogCreate](./ask-log-create.md), this requester takes no log level.
+
+## Related
+
+- [askLogCreate](./ask-log-create.md) — log a message (with optional structured data) at an explicit log level.
+- [askLogDisableEventHistory](./ask-log-disable-event-history.md) — control whether the story's full action history is persisted.

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

@@ -0,0 +1,7 @@
+{
+  "label": "Math",
+  "link": {
+    "type": "generated-index",
+    "description": "Non-deterministic math done as actions so stories stay pure and replayable."
+  }
+}

package/template/docusaurus/docs/actions/core/math/ask-random-number.md

@@ -0,0 +1,46 @@
+---
+title: askRandomNumber
+description: Get a non-deterministic random number as an action so stories stay pure.
+---
+
+# askRandomNumber
+
+Returns a random floating-point number.
+
+- **Action type:** `MathActionType.RandomNumber`
+- **At runtime:** resolves to `Math.random()` — a floating-point number in the range `[0, 1)` (0 inclusive, 1 exclusive).
+
+Randomness is the classic source of non-determinism, so a story never calls `Math.random()` inline. It `yield*`s this action and the runtime supplies the value, recording it in the execution log. That keeps the story a pure generator that can be inspected, tested, and replayed — a replay reuses the exact number the original run drew rather than rolling a fresh one.
+
+```typescript
+import { askRandomNumber } from 'quidproquo-core';
+
+export function* askRollDice() {
+  const r = yield* askRandomNumber();
+  // Scale the [0, 1) value into 1..6
+  return Math.floor(r * 6) + 1;
+}
+```
+
+## Signature
+
+```typescript
+function* askRandomNumber(): AskResponse<number>;
+```
+
+## Parameters
+
+None. There are no bounds arguments — scale or offset the result yourself, as in the example above.
+
+## Returns
+
+`number` — a floating-point value in `[0, 1)`: greater than or equal to `0` and strictly less than `1`.
+
+## Notes
+
+- To get an integer in a range, use the usual arithmetic on the `[0, 1)` value, e.g. `Math.floor(r * (max - min + 1)) + min`.
+- The value is not cryptographically secure — it is intended for general-purpose randomness (sampling, jitter, dice), not for keys or tokens.
+
+## Related
+
+- [askNewGuid](../guid/ask-new-guid.md) — for a unique identifier rather than a raw random number.

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

@@ -0,0 +1,7 @@
+{
+  "label": "Metric",
+  "link": {
+    "type": "generated-index",
+    "description": "Emit custom metrics from a story (CloudWatch metrics on AWS)."
+  }
+}

package/template/docusaurus/docs/actions/core/metric/ask-metric-put.md

@@ -0,0 +1,67 @@
+---
+title: askMetricPut
+description: Emit a custom metric data point from a story (a CloudWatch metric on AWS).
+---
+
+# askMetricPut
+
+Emits a single custom metric data point — a named value, with an optional unit and dimensions.
+
+- **Action type:** `MetricActionType.Put`
+- **On AWS:** the metric is written to **CloudWatch** as an [Embedded Metric Format](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Embedded_Metric_Format.html) (EMF) log line, from which CloudWatch extracts the metric — no API call, no extra IAM, and no latency added to the story. The namespace is `qpq/<application>/<environment>[/<feature>]` and a `service` dimension is always included alongside any dimensions you supply.
+
+```typescript
+import { askMetricPut, MetricUnit } from 'quidproquo-core';
+
+export function* askCompleteCheckout(amountMs: number) {
+  yield* askMetricPut('CheckoutsCompleted');
+  yield* askMetricPut('CheckoutDuration', amountMs, { unit: MetricUnit.milliseconds });
+}
+```
+
+## Signature
+
+```typescript
+function* askMetricPut(
+  metricName: string,
+  value?: number,
+  options?: AskMetricPutOptions,
+): AskResponse<void>;
+```
+
+## Parameters
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| `metricName` | `string` | – | Name of the metric. |
+| `value` | `number` | `1` | The value to record for this data point. |
+| `options` | `AskMetricPutOptions` | – | Optional unit and dimensions — see below. |
+
+### `AskMetricPutOptions`
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `unit` | `MetricUnit` | `MetricUnit.count` | The unit the value is measured in. See [`MetricUnit`](#metricunit). |
+| `dimensions` | `Record<string, string>` | – | Extra dimensions on top of the standard `service` dimension. Each unique dimension combination is its own metric (and its own cost) — keep these **low-cardinality**: never per-user or per-request identifiers. |
+
+### `MetricUnit`
+
+The enum values are the CloudWatch unit strings.
+
+| Member | CloudWatch unit |
+| --- | --- |
+| `MetricUnit.count` | `Count` |
+| `MetricUnit.milliseconds` | `Milliseconds` |
+| `MetricUnit.seconds` | `Seconds` |
+| `MetricUnit.bytes` | `Bytes` |
+| `MetricUnit.percent` | `Percent` |
+| `MetricUnit.none` | `None` |
+
+## Returns
+
+`void` — the story resumes once the metric has been emitted.
+
+## Notes
+
+- When `unit` is omitted the metric is recorded as `Count`.
+- The namespace embeds the full deployment identity (application / environment / feature), so per-developer feature sandboxes never pollute mainline metrics and apps sharing an account cannot merge same-named metrics.

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

@@ -0,0 +1,7 @@
+{
+  "label": "Network",
+  "link": {
+    "type": "generated-index",
+    "description": "Make outbound HTTP requests from a story."
+  }
+}

package/template/docusaurus/docs/actions/core/network/ask-network-request.md

@@ -0,0 +1,95 @@
+---
+title: askNetworkRequest
+description: Make an outbound HTTP request from a story.
+---
+
+# askNetworkRequest
+
+Makes an outbound HTTP request and returns the response. Doing this as an action — rather than calling `fetch` directly — keeps stories pure and replayable: the request and its result are captured in the runtime's action history.
+
+- **Action type:** `NetworkActionType.Request`
+
+```typescript
+import { askNetworkRequest } from 'quidproquo-core';
+
+interface Todo {
+  id: number;
+  title: string;
+}
+
+export function* askGetTodo(id: string) {
+  const response = yield* askNetworkRequest<undefined, Todo>('GET', `https://example.com/todos/${id}`);
+
+  return response.data;
+}
+```
+
+## Signature
+
+```typescript
+function* askNetworkRequest<T, R>(
+  method: HTTPMethod,
+  url: string,
+  httpRequestOptions?: HTTPRequestOptions<T>,
+): AskResponse<HTTPNetworkResponse<R>>;
+```
+
+`T` is the request body type; `R` is the expected response `data` type.
+
+## Parameters
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| `method` | `HTTPMethod` | – | The HTTP method: `'GET' \| 'HEAD' \| 'POST' \| 'PUT' \| 'DELETE' \| 'CONNECT' \| 'OPTIONS' \| 'PATCH'`. (`CONNECT` is not supported and throws.) |
+| `url` | `string` | – | The request URL. If `basePath` is set and this is not an absolute URL, it is appended to `basePath`. |
+| `httpRequestOptions` | `HTTPRequestOptions<T>` | – | Optional request options — see below. |
+
+### `HTTPRequestOptions<T>`
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `basePath` | `string` | – | A base URL that `url` is joined onto (path concatenation) when `url` is not already absolute. |
+| `params` | `Record<string, string>` | – | Query-string parameters appended to the URL. |
+| `headers` | `Record<string, string>` | – | Request headers. A `Content-Type` is set automatically for object, JSON, and URL-encoded bodies when you don't provide one. |
+| `body` | `T` | – | The request body. Objects/arrays are JSON-serialised; strings, `ArrayBuffer`, typed arrays, `Blob`, `FormData`, `URLSearchParams`, and `ReadableStream` are sent as-is. Ignored for `GET` and `HEAD`. |
+| `responseType` | `ResponseType` | `'json'` | How to interpret the response body: `'json'`, `'text'`, or `'binary'`. See [Returns](#returns). |
+
+## Returns
+
+`HTTPNetworkResponse<R>`:
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `data` | `R` | The parsed response body. For `responseType: 'json'` this is the parsed JSON (falling back to raw text if the body isn't valid JSON, or `undefined` for an empty body); for `'text'` it is the raw string; for `'binary'` it is a `QPQBinaryData` object (`{ base64Data, mimetype, filename }`). |
+| `status` | `number` | The HTTP status code. |
+| `statusText` | `string` | The HTTP status text. |
+| `headers` | `Record<string, string>` | The response headers. |
+
+The response is returned for any completed HTTP exchange, including non-2xx statuses — inspect `status` yourself; a `404` or `500` does not throw.
+
+## Errors
+
+| Error | Meaning |
+| --- | --- |
+| `NetworkRequestErrorTypeEnum.Timeout` | The request exceeded the request timeout and was aborted. |
+
+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(askNetworkRequest('GET', 'https://example.com/slow'));
+
+if (outcome.success) {
+  const response = outcome.result;
+  // response.status, response.data, ...
+} else {
+  // outcome.error.errorType / outcome.error.errorText
+}
+```
+
+## Notes
+
+- Requests abort after 25 seconds, surfacing as `NetworkRequestErrorTypeEnum.Timeout`.
+
+## Related
+
+- [askAiPrompt](../ai/ask-ai-prompt.md) and [askClaudeAiMessagesApi](../claude-ai/ask-claude-ai-messages-api.md) — call model providers without hand-rolling the HTTP request.

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

@@ -0,0 +1,7 @@
+{
+  "label": "Platform",
+  "link": {
+    "type": "generated-index",
+    "description": "Platform utilities like delaying/sleeping within a story."
+  }
+}

package/template/docusaurus/docs/actions/core/platform/ask-delay.md

@@ -0,0 +1,48 @@
+---
+title: askDelay
+description: Pause a story for a number of milliseconds.
+---
+
+# askDelay
+
+Pauses the story for the given number of milliseconds before resuming.
+
+- **Action type:** `PlatformActionType.Delay`
+- **At runtime:** waits via `setTimeout` for `timeMs` milliseconds, then resolves with nothing.
+
+Sleeping is a side effect tied to real wall-clock time, so a story never calls `setTimeout` itself. It `yield*`s this action and lets the runtime perform (and record) the wait, keeping the story a pure generator that can be inspected, tested, and replayed.
+
+```typescript
+import { askDelay } from 'quidproquo-core';
+
+export function* askPollWithBackoff() {
+  // Wait 500ms between attempts
+  yield* askDelay(500);
+}
+```
+
+## Signature
+
+```typescript
+function* askDelay(
+  timeMs: number,
+): AskResponse<void>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `timeMs` | `number` | How long to pause, in **milliseconds**. |
+
+## Returns
+
+`void` — the story resumes once the delay has elapsed.
+
+## Notes
+
+- The delay holds the running story open for its whole duration. In a metered runtime (e.g. an AWS Lambda invocation) that time still counts toward execution/billing, so prefer it for short waits — retry backoff, gentle rate-limiting — rather than long sleeps.
+
+## Related
+
+- [askDateNow](../date/ask-date-now.md) — read the current time, e.g. to decide how long to wait.

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

@@ -0,0 +1 @@
+{ "label": "Queue", "link": { "type": "generated-index", "description": "Send messages to a queue defined with defineQueue." } }