create-qpq-app 0.1.5

package/template/docusaurus/docs/actions/features/validation/ask-validate-model-or-throw-error.md

@@ -0,0 +1,73 @@
+---
+title: askValidateModelOrThrowError
+description: Validate a model against a Zod schema and throw a catchable qpq error if it doesn't match.
+---
+
+# askValidateModelOrThrowError
+
+Validates a model against a [Zod](https://zod.dev) schema. If the model matches, the story continues and the (typed) model is returned. If it doesn't, the story throws a catchable qpq error carrying a human-readable description of what was wrong — so you can validate request payloads at the top of a route handler and let the runtime turn a failure into an error response.
+
+- **Built from:** a `schema.safeParse` check followed by [askThrowError](../../core/error/ask-throw-error.md) with `ErrorTypeEnum.Invalid` when parsing fails. It is a composed story, not a single action.
+
+```typescript
+import { askValidateModelOrThrowError } from 'quidproquo-features';
+import { z } from 'zod';
+
+const CreateUserSchema = z.object({
+  email: z.string().email(),
+  age: z.number().int().min(0),
+});
+
+export function* createUser(unvalidated: unknown) {
+  // Throws ErrorTypeEnum.Invalid if the body doesn't match the schema.
+  const body = yield* askValidateModelOrThrowError(unvalidated as any, CreateUserSchema);
+
+  // body is typed as z.infer<typeof CreateUserSchema> from here on.
+  // ...persist the user
+}
+```
+
+## Signature
+
+```typescript
+function* askValidateModelOrThrowError<T extends z.AnyZodObject>(
+  model: z.infer<T>,
+  schema: T,
+): AskResponse<z.infer<T>>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `model` | `z.infer<T>` | The value to validate. Typed as the schema's inferred type — pass the candidate payload (cast it if it arrives as `unknown`). |
+| `schema` | `T` (a `z.AnyZodObject`) | The Zod object schema to validate against. Its `.safeParse` decides success or failure. |
+
+## Returns
+
+`z.infer<T>` — on success the story resumes and returns the original `model`, now carrying the schema's inferred type. On failure the story does not return; it throws (see [Errors](#errors)).
+
+## Errors
+
+This story throws a core qpq error via [askThrowError](../../core/error/ask-throw-error.md) rather than defining its own error enum:
+
+| Error | Meaning |
+| --- | --- |
+| `ErrorTypeEnum.Invalid` | The model failed schema validation. The error text is the message produced by `zod-validation-error`'s `fromZodError` — a readable summary of the failing field(s) — and the error stack is the Zod error's stack. |
+
+Because it is a normal thrown qpq error, wrap the call in [askCatch](../../core/system/ask-catch.md) if you want to handle validation failure inline instead of letting it propagate:
+
+```typescript
+const outcome = yield* askCatch(askValidateModelOrThrowError(body as any, CreateUserSchema));
+if (outcome.success) {
+  // outcome.result is the validated model
+} else {
+  // outcome.error.errorType === ErrorTypeEnum.Invalid
+  // outcome.error.errorText holds the readable validation message
+}
+```
+
+## Related
+
+- [askThrowError](../../core/error/ask-throw-error.md) — the action this story throws with on failure.
+- [askCatch](../../core/system/ask-catch.md) — catch the thrown error to handle invalid input inline.

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

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

package/template/docusaurus/docs/actions/webserver/admin/_category_.json

@@ -0,0 +1 @@
+{ "label": "Admin", "link": { "type": "generated-index", "description": "Admin API for inspecting story execution logs and their metadata." } }

package/template/docusaurus/docs/actions/webserver/admin/ask-admin-get-log-metadata-children.md

@@ -0,0 +1,62 @@
+---
+title: askAdminGetLogMetadataChildren
+description: Page through the direct child stories that a given story triggered, as metadata summaries.
+---
+
+# askAdminGetLogMetadataChildren
+
+Returns a paginated list of the **direct child stories** that a given story triggered — the sub-stories whose `fromCorrelation` equals this story's `correlation`. Stories form a tree: an API request may send a queue message, invoke a service function, or publish an event, each of which runs as its own story. This action walks one level of that tree, letting an admin dashboard expand a log entry to reveal the work it spawned.
+
+- **Action type:** `AdminActionType.GetLogMetadataChildren`
+
+```typescript
+import { askAdminGetLogMetadataChildren } from 'quidproquo-webserver';
+
+export function* walkChildren(correlationId: string) {
+  const allChildren = [];
+  let nextPageKey: string | undefined = undefined;
+
+  do {
+    const page = yield* askAdminGetLogMetadataChildren(correlationId, nextPageKey);
+    allChildren.push(...page.items);
+    nextPageKey = page.nextPageKey;
+  } while (nextPageKey);
+
+  return allChildren; // recurse into each child.correlation to build the full tree
+}
+```
+
+## Signature
+
+```typescript
+function* askAdminGetLogMetadataChildren(
+  correlationId: string,
+  nextPageKey?: string,
+): AskResponse<QpqLogList>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `correlationId` | `string` | The `correlation` of the parent story whose direct children to list. |
+| `nextPageKey` | `string` | Optional. The `nextPageKey` from a previous call, to fetch the next page. Omit for the first page. |
+
+## Returns
+
+`QpqLogList` — a page of child metadata summaries:
+
+```typescript
+export interface QpqLogList {
+  items: StoryResultMetadata[];  // direct children (one level down the tree)
+  nextPageKey?: string;
+}
+```
+
+Each item is a `StoryResultMetadata` (see [askAdminGetLogMetadata](./ask-admin-get-log-metadata.md) for its shape). `nextPageKey` is present when more children remain. To build the full execution tree, recurse: call this action again with each child's `correlation`. The framework also models the fully-expanded tree as `StoryResultMetadataWithChildren` (`StoryResultMetadata` plus a `children` array).
+
+## Related
+
+- [askAdminGetLogMetadata](./ask-admin-get-log-metadata.md) — the summary shape returned in `items`.
+- [askAdminGetLog](./ask-admin-get-log.md) — the full log for any child `correlation`.
+- [askAdminGetLogs](./ask-admin-get-logs.md) — list top-level stories to start from.

package/template/docusaurus/docs/actions/webserver/admin/ask-admin-get-log-metadata.md

@@ -0,0 +1,67 @@
+---
+title: askAdminGetLogMetadata
+description: Fetch the lightweight metadata summary for a single story by its correlation id.
+---
+
+# askAdminGetLogMetadata
+
+Fetches the **metadata summary** for a single story, identified by its correlation id. This is the compact form of a log entry — runtime type, timing, error text, and the `correlation` / `fromCorrelation` links — without the full action history. Use it when you need one story's summary (for example, to resolve a `fromCorrelation` back to its parent); use [askAdminGetLog](./ask-admin-get-log.md) when you need the full detail.
+
+- **Action type:** `AdminActionType.GetLogMetadata`
+
+```typescript
+import { askAdminGetLogMetadata } from 'quidproquo-webserver';
+
+export function* summariseStory(correlationId: string) {
+  const meta = yield* askAdminGetLogMetadata(correlationId);
+  return {
+    runtimeType: meta.runtimeType,
+    tookMs: meta.executionTimeMs,
+    failed: !!meta.error,
+    parent: meta.fromCorrelation,
+  };
+}
+```
+
+## Signature
+
+```typescript
+function* askAdminGetLogMetadata(
+  correlationId: string,
+): AskResponse<StoryResultMetadata>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `correlationId` | `string` | The `correlation` of the story whose summary to fetch. |
+
+## Returns
+
+`StoryResultMetadata` — a compact summary of one story execution (no action history):
+
+```typescript
+export type StoryResultMetadata = {
+  correlation: string;         // unique id for this story execution
+  fromCorrelation?: string;    // correlation of the story that triggered this one
+
+  moduleName: string;
+  runtimeType: QpqRuntimeType;
+
+  startedAt: string;
+
+  generic: string;             // generic label used to search / group logs
+  error?: string;              // error text, if the story failed
+  executionTimeMs: number;
+
+  userInfo?: string;
+  qpqFunctionRuntimeInfo?: QpqFunctionRuntime;
+};
+```
+
+## Related
+
+- [askAdminGetLog](./ask-admin-get-log.md) — the full execution log (with action history) for the same `correlation`.
+- [askAdminGetLogMetadataChildren](./ask-admin-get-log-metadata-children.md) — page through the child stories of this `correlation`.
+- [askAdminGetLogs](./ask-admin-get-logs.md) — list summaries across a runtime type and time window.

package/template/docusaurus/docs/actions/webserver/admin/ask-admin-get-log.md

@@ -0,0 +1,84 @@
+---
+title: askAdminGetLog
+description: Fetch the full execution log — including action history — for a single story by its correlation id.
+---
+
+# askAdminGetLog
+
+Fetches the **full execution log** for a single story, identified by its correlation id. Where [askAdminGetLogMetadata](./ask-admin-get-log-metadata.md) returns just a summary, this returns the complete `StoryResult` — including the entire `history` of actions the story yielded, their results, and timing. This is what an admin dashboard shows when a user opens a single log entry to inspect exactly what happened.
+
+- **Action type:** `AdminActionType.GetLog`
+
+```typescript
+import { askAdminGetLog } from 'quidproquo-webserver';
+
+export function* inspectStory(correlationId: string) {
+  const log = yield* askAdminGetLog(correlationId);
+
+  // log.history is the ordered list of every action the story ran
+  for (const step of log.history) {
+    // step.act (the action), step.res (its result), step.startedAt / step.finishedAt
+  }
+
+  return log.error ?? log.result;
+}
+```
+
+## Signature
+
+```typescript
+function* askAdminGetLog(
+  correlationId: string,
+): AskResponse<StoryResult<any>>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `correlationId` | `string` | The `correlation` of the story to fetch — typically taken from a summary returned by [askAdminGetLogs](./ask-admin-get-logs.md) or [askAdminGetLogMetadata](./ask-admin-get-log-metadata.md). |
+
+## Returns
+
+`StoryResult<any>` — the complete execution record for the story:
+
+```typescript
+export interface StoryResult<TArgs extends Array<any>, TResult = any> {
+  input: TArgs;                 // the arguments the story was called with
+  session: StorySession;        // session data (correlation, context, access token, ...)
+  history: ActionHistory[];     // every action yielded, with result and timing
+
+  startedAt: string;
+  finishedAt: string;
+
+  fromCorrelation?: string;     // the parent story's correlation, if any
+  correlation: string;          // this story's correlation
+
+  tags: string[];
+  moduleName: string;
+
+  result?: TResult;             // the story's return value ...
+  error?: QPQError;             // ... or the error it failed with (never both)
+
+  runtimeType: QpqRuntimeType;
+  logs?: qpqConsoleLog[];       // impure console logs captured during the run
+  qpqFunctionRuntimeInfo?: QpqFunctionRuntime;
+}
+```
+
+Each `history` entry is an `ActionHistory`:
+
+```typescript
+export interface ActionHistory<P = any, R = any> {
+  act: Action<P>;      // the action that was run
+  res: R;              // its result
+  startedAt: string;
+  finishedAt: string;
+}
+```
+
+## Related
+
+- [askAdminGetLogs](./ask-admin-get-logs.md) — list log summaries to find a `correlation` to fetch.
+- [askAdminGetLogMetadata](./ask-admin-get-log-metadata.md) — the lightweight summary for the same `correlation` (no history).
+- [askAdminGetLogMetadataChildren](./ask-admin-get-log-metadata-children.md) — page through the child stories this one triggered.

package/template/docusaurus/docs/actions/webserver/admin/ask-admin-get-logs.md

@@ -0,0 +1,96 @@
+---
+title: askAdminGetLogs
+description: List story-execution log summaries for a runtime type within a time window (paginated).
+---
+
+# askAdminGetLogs
+
+Returns a paginated list of **story-execution log summaries** for a given runtime type within a time window. This is the entry point for an admin dashboard: it lists the top-level story executions (API requests, queue events, scheduled runs, and so on) so a user can pick one to drill into.
+
+Every story that runs in a quidproquo service — an API request, a queue message, a deploy event — produces an execution log. `askAdminGetLogs` returns the lightweight [`StoryResultMetadata`](#the-log-model) summaries for those runs; use [askAdminGetLog](./ask-admin-get-log.md) to fetch the full detail of any one of them.
+
+- **Action type:** `AdminActionType.GetLogs`
+
+```typescript
+import { askAdminGetLogs } from 'quidproquo-webserver';
+import { QpqRuntimeType } from 'quidproquo-core';
+
+export function* listRecentApiCalls() {
+  const page = yield* askAdminGetLogs(
+    QpqRuntimeType.API,
+    '2026-07-01T00:00:00.000Z',
+    '2026-07-07T00:00:00.000Z',
+  );
+
+  for (const entry of page.items) {
+    // entry.correlation, entry.runtimeType, entry.executionTimeMs, entry.error, ...
+  }
+
+  return page.nextPageKey; // pass back in to fetch the next page
+}
+```
+
+## Signature
+
+```typescript
+function* askAdminGetLogs(
+  runtimeType: string,
+  startIsoDateTime: string,
+  endIsoDateTime: string,
+  nextPageKey?: string,
+): AskResponse<QpqLogList>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `runtimeType` | `string` | Which kind of story execution to list — the `QpqRuntimeType` value (e.g. `QpqRuntimeType.API`, `QpqRuntimeType.QUEUE_EVENT`, `QpqRuntimeType.RECURRING_SCHEDULE`). |
+| `startIsoDateTime` | `string` | Start of the time window, as an ISO 8601 timestamp. Only logs at or after this time are returned. |
+| `endIsoDateTime` | `string` | End of the time window, as an ISO 8601 timestamp. |
+| `nextPageKey` | `string` | Optional. The `nextPageKey` returned by a previous call, to fetch the next page. Omit for the first page. |
+
+## Returns
+
+`QpqLogList` — a page of metadata summaries:
+
+```typescript
+export interface QpqLogList {
+  items: StoryResultMetadata[];
+  nextPageKey?: string;
+}
+```
+
+`nextPageKey` is present when more results remain; pass it back in to continue paging. When it is absent, you have reached the end of the window.
+
+## The log model
+
+`items` are `StoryResultMetadata` — a compact summary of one story execution (no action history):
+
+```typescript
+export type StoryResultMetadata = {
+  correlation: string;        // unique id for this story execution
+  fromCorrelation?: string;   // correlation of the story that triggered this one (its parent)
+
+  moduleName: string;
+  runtimeType: QpqRuntimeType; // API / QUEUE_EVENT / DEPLOY_EVENT / ...
+
+  startedAt: string;          // ISO timestamp
+
+  generic: string;            // a generic label used to search / group logs
+  error?: string;             // error text, if the story failed
+  executionTimeMs: number;
+
+  userInfo?: string;
+  qpqFunctionRuntimeInfo?: QpqFunctionRuntime;
+};
+```
+
+The `correlation` / `fromCorrelation` pair is what links stories into a tree: a parent story (say an API call) that triggers a sub-story (a queue message it sends) sets the child's `fromCorrelation` to the parent's `correlation`. Walk that tree with [askAdminGetLogMetadataChildren](./ask-admin-get-log-metadata-children.md).
+
+## Related
+
+- [askAdminGetLog](./ask-admin-get-log.md) — fetch the full execution log (with action history) for one `correlation`.
+- [askAdminGetLogMetadata](./ask-admin-get-log-metadata.md) — fetch the summary for a single `correlation`.
+- [askAdminGetLogMetadataChildren](./ask-admin-get-log-metadata-children.md) — page through the child stories of a `correlation`.
+- [defineAdminSettings](../../../config/features/admin-settings.md) — declares the admin log-service backend these actions read from.

package/template/docusaurus/docs/actions/webserver/api-key-validation/_category_.json

@@ -0,0 +1 @@
+{ "label": "API Key Validation", "link": { "type": "generated-index", "description": "Validate a presented API key value against the keys declared with defineApiKey." } }

package/template/docusaurus/docs/actions/webserver/api-key-validation/ask-api-key-validation-validate.md

@@ -0,0 +1,63 @@
+---
+title: askApiKeyValidationValidate
+description: Validate a provided API key value against a set of declared API keys.
+---
+
+# askApiKeyValidationValidate
+
+Validates a provided API key value against a list of [declared API keys](../../../config/webserver/api-key.md), returning whether it matches any of them. This is the runtime half of API-key auth: the webserver's route-auth flow calls it with the value from the `x-api-key` header and the keys a route references, but you can also call it directly to gate custom logic.
+
+- **Action type:** `ApiKeyValidationActionType.Validate`
+- **On AWS:** for each referenced key the processor resolves the API Gateway key id (from a CloudFormation export), fetches the real key value, and compares it to the presented value using a **constant-time** equality check. Keys are looked up individually (not by listing all keys) so the IAM grant stays per-key.
+
+```typescript
+import { askApiKeyValidationValidate } from 'quidproquo-webserver';
+
+export function* askGuardWebhook(presentedKey: string) {
+  const isValid = yield* askApiKeyValidationValidate(presentedKey, [
+    { name: 'partner-api' },
+  ]);
+
+  if (!isValid) {
+    // reject the request
+  }
+}
+```
+
+## Signature
+
+```typescript
+function* askApiKeyValidationValidate(
+  apiKeyValue: string,
+  apiKeyReferences: ApiKeyReference[],
+): AskResponse<boolean>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `apiKeyValue` | `string` | The key value presented by the caller (e.g. the `x-api-key` header). |
+| `apiKeyReferences` | `ApiKeyReference[]` | The keys to validate against. The presented value matches if it equals **any** of these. |
+
+### `ApiKeyReference`
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `name` | `string` | The key name, matching the `apiKeyName` passed to [defineApiKey](../../../config/webserver/api-key.md). |
+| `applicationName` | `string` | Application that owns the key, when it lives in a different application. Defaults to the current application. |
+| `serviceName` | `string` | Service/module that owns the key, when it lives in a different service. Defaults to the current service. |
+
+## Returns
+
+`boolean` — `true` if the presented value matches at least one of the referenced keys, otherwise `false`. A reference that can't be resolved (unknown key, missing export) simply doesn't match rather than raising; an empty or mismatched value returns `false`.
+
+## Notes
+
+- Comparison is constant-time on AWS to avoid leaking key material through timing.
+- Route auth uses this action automatically when a route declares `routeAuthSettings.apiKeys` — you typically declare the key with [defineApiKey](../../../config/webserver/api-key.md) and reference it from the route rather than calling this action yourself.
+
+## Related
+
+- [defineApiKey](../../../config/webserver/api-key.md) — declares the keys this action validates against.
+- [defineAuthSystem](../../../config/webserver/auth-system.md) — the complementary user-directory / access-token route auth.

package/template/docusaurus/docs/actions/webserver/dns/_category_.json

@@ -0,0 +1 @@
+{ "label": "DNS", "link": { "type": "generated-index", "description": "Actions for inspecting the DNS domains a service declares." } }

package/template/docusaurus/docs/actions/webserver/dns/ask-dns-list.md

@@ -0,0 +1,37 @@
+---
+title: askDnsList
+description: List the base DNS domains a service has declared.
+---
+
+# askDnsList
+
+Returns the list of base DNS domains the service has declared with [defineDns](../../../config/webserver/dns.md). Use it when a story needs to know which root domain(s) the service is served under.
+
+- **Action type:** `DnsActionType.List`
+
+```typescript
+import { askDnsList } from 'quidproquo-webserver';
+
+export function* askPrimaryDomain() {
+  const domains = yield* askDnsList();
+  return domains[0];
+}
+```
+
+## Signature
+
+```typescript
+function* askDnsList(): AskResponse<string[]>;
+```
+
+Takes no arguments.
+
+## Returns
+
+`string[]` — the `dnsBase` values from every [defineDns](../../../config/webserver/dns.md) config in the service. Typically a single entry.
+
+- **On AWS:** this does **not** query Route53. The processor reads the service's own config and maps each DNS config to its `dnsBase`, so the result is exactly what was declared with `defineDns` — no live DNS lookup is performed.
+
+## Related
+
+- [defineDns](../../../config/webserver/dns.md) — declares the domains this action returns.

package/template/docusaurus/docs/actions/webserver/generic-data-resource/_category_.json

@@ -0,0 +1 @@
+{ "label": "Generic Data Resource", "link": { "type": "generated-index", "description": "Generic data-resource operations." } }

package/template/docusaurus/docs/actions/webserver/generic-data-resource/ask-put-generic-data-resource.md

@@ -0,0 +1,48 @@
+---
+title: askPutGenericDataResource
+description: Write a single item into a named data-resource table.
+---
+
+# askPutGenericDataResource
+
+Writes a single item into a **generic data resource** — a named table addressed directly by name. A "generic data resource" is a low-level, schema-agnostic data operation: rather than reading and writing through a typed [key-value store](../../../config/core/key-value-store.md), you pass a raw `tableName` and a raw `item` object. It is a generic building block used by tooling (for example the admin log viewer) that needs to read and write arbitrary tables without a compile-time model of them.
+
+- **Action type:** `GenericDataResourceActionTypeEnum.Put`
+
+```typescript
+import { askPutGenericDataResource } from 'quidproquo-webserver';
+
+export function* saveRecord(tableName: string) {
+  const stored = yield* askPutGenericDataResource(tableName, {
+    id: '123',
+    name: 'Example',
+  });
+
+  return stored;
+}
+```
+
+## Signature
+
+```typescript
+function* askPutGenericDataResource(
+  tableName: string,
+  item: object,
+): AskResponse<object>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `tableName` | `string` | The name of the target data-resource table to write into. |
+| `item` | `object` | The item to store. An arbitrary object — there is no compile-time schema. |
+
+## Returns
+
+`object` — the stored item.
+
+## Related
+
+- [askScanGenericDataResource](./ask-scan-generic-data-resource.md) — read items back out of a data-resource table.
+- [defineKeyValueStore](../../../config/core/key-value-store.md) — the typed, first-class alternative for modelling application data.

package/template/docusaurus/docs/actions/webserver/generic-data-resource/ask-scan-generic-data-resource.md

@@ -0,0 +1,49 @@
+---
+title: askScanGenericDataResource
+description: Scan up to a maximum number of items from a named data-resource table.
+---
+
+# askScanGenericDataResource
+
+Reads items out of a **generic data resource** — a named table addressed directly by name — up to a maximum count. A "generic data resource" is a low-level, schema-agnostic data operation: you pass a raw `tableName` rather than reading through a typed [key-value store](../../../config/core/key-value-store.md). It is a generic building block used by tooling (for example the admin log viewer) that needs to enumerate arbitrary tables without a compile-time model of them.
+
+- **Action type:** `GenericDataResourceActionTypeEnum.Scan`
+
+```typescript
+import { askScanGenericDataResource } from 'quidproquo-webserver';
+
+export function* readRecords(tableName: string) {
+  const items = yield* askScanGenericDataResource(tableName, 100);
+
+  for (const item of items) {
+    // ...
+  }
+
+  return items;
+}
+```
+
+## Signature
+
+```typescript
+function* askScanGenericDataResource(
+  tableName: string,
+  maxItems: number,
+): AskResponse<object[]>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `tableName` | `string` | The name of the data-resource table to scan. |
+| `maxItems` | `number` | The maximum number of items to return. |
+
+## Returns
+
+`object[]` — the scanned items (up to `maxItems`).
+
+## Related
+
+- [askPutGenericDataResource](./ask-put-generic-data-resource.md) — write an item into a data-resource table.
+- [defineKeyValueStore](../../../config/core/key-value-store.md) — the typed, first-class alternative for modelling application data.

package/template/docusaurus/docs/actions/webserver/open-api-spec/_category_.json

@@ -0,0 +1 @@
+{ "label": "OpenAPI Spec", "link": { "type": "generated-index", "description": "Read the service's generated OpenAPI spec from within a story." } }

package/template/docusaurus/docs/actions/webserver/open-api-spec/ask-get-open-api-spec.md

@@ -0,0 +1,43 @@
+---
+title: askGetOpenApiSpec
+description: Return the service's generated OpenAPI spec as a string.
+---
+
+# askGetOpenApiSpec
+
+Returns the service's **OpenAPI spec** as a string. Use it in a route handler to serve the spec (for documentation UIs or client generation) directly from the running service.
+
+- **Action type:** `OpenApiSpecActionType.GetOpenApiSpec`
+
+```typescript
+import { askGetOpenApiSpec } from 'quidproquo-webserver';
+
+export function* getOpenApiRoute() {
+  const spec = yield* askGetOpenApiSpec();
+
+  return {
+    status: 200,
+    headers: { 'content-type': 'application/json' },
+    body: spec,
+  };
+}
+```
+
+## Signature
+
+```typescript
+function* askGetOpenApiSpec(): AskResponse<string>;
+```
+
+## Parameters
+
+None.
+
+## Returns
+
+`string` — the OpenAPI spec. Associate a spec with the service using [defineOpenApi](../../../config/webserver/open-api.md).
+
+## Related
+
+- [defineOpenApi](../../../config/webserver/open-api.md) — declares the spec this action returns.
+- [defineRoute](../../../config/webserver/route.md) — expose the spec at an HTTP path.

package/template/docusaurus/docs/actions/webserver/route-auth-validation/_category_.json

@@ -0,0 +1 @@
+{ "label": "Route Auth Validation", "link": { "type": "generated-index", "description": "Decode and validate a route's incoming auth token." } }