create-qpq-app 0.1.5

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

@@ -0,0 +1,57 @@
+---
+title: askReduce
+description: Fold an array into a single accumulated value, running a story per item.
+---
+
+# askReduce
+
+Iterates an array and folds it into a single accumulated value — the async/story equivalent of `Array.prototype.reduce`. The per-item callback is a generator that receives the running accumulator and the current item and returns the next accumulator. Items are processed **sequentially**, in order, because each step feeds the next.
+
+- **Built from:** a plain `for` loop that `yield*`s the callback for each item, threading the accumulator through.
+
+```typescript
+import { askReduce } from 'quidproquo-core';
+import { askFileReadObjectJson } from 'quidproquo-core';
+
+export function* askSumInvoiceTotals(invoiceIds: string[]) {
+  // Read each invoice and accumulate its total into a running sum.
+  const total = yield* askReduce(invoiceIds, 0, function* (acc, invoiceId) {
+    const invoice = yield* askFileReadObjectJson('invoices', `${invoiceId}.json`);
+    return acc + invoice.total;
+  });
+
+  return total;
+}
+```
+
+## Signature
+
+```typescript
+function* askReduce<T, R>(
+  items: T[],
+  initialValue: R,
+  askCallback: (acc: R, item: T, index: number, srcArray: T[]) => AskResponse<R>,
+): AskResponse<R>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `items` | `T[]` | The array to fold. |
+| `initialValue` | `R` | The starting accumulator value, passed to the callback for the first item. (Unlike `Array.prototype.reduce`, `initialValue` is required.) |
+| `askCallback` | `(acc: R, item: T, index: number, srcArray: T[]) => AskResponse<R>` | A generator called once per item. Receives the running accumulator, the current item, its zero-based index, and the source array. Its return value becomes the accumulator for the next item. |
+
+## Returns
+
+`R` — the final accumulator after every item has been processed. If `items` is empty, `initialValue` is returned unchanged.
+
+## Notes
+
+- **Sequential and stateful.** Each step depends on the previous accumulator, so this helper is inherently ordered and has no parallel variant.
+
+## Related
+
+- [askMap](./ask-map.md) — transform each item into a new array (no accumulator).
+- [askFilter](./ask-filter.md) — select a subset of items.
+- [askArraySome](./ask-array-some.md) — short-circuit boolean test over the array.

package/template/docusaurus/docs/actions/core/binary-data/_category_.json

@@ -0,0 +1,7 @@
+{
+  "label": "Binary Data",
+  "link": {
+    "type": "generated-index",
+    "description": "Create and work with QPQBinaryData, the portable binary wrapper used by file and network actions."
+  }
+}

package/template/docusaurus/docs/actions/core/binary-data/ask-create-text-qpq-binary-data.md

@@ -0,0 +1,86 @@
+---
+title: askCreateTextQpqBinaryData
+description: Wrap a text string as QPQBinaryData with a filename and the correct MIME type.
+---
+
+# askCreateTextQpqBinaryData
+
+Builds a [`QPQBinaryData`](#qpqbinarydata) value from a plain text string — base64-encoding the UTF-8 bytes and stamping it with a filename and a MIME type derived from the text's format. Use it to turn generated text (JSON, CSV, HTML, Markdown, …) into the portable binary payload that file and network actions expect.
+
+- A small composed story that base64-encodes the text and fills in the `QPQBinaryData` fields. It performs no I/O.
+
+```typescript
+import { askCreateTextQpqBinaryData, TextFileType, askFileWriteBinaryContents } from 'quidproquo-core';
+
+export function* askExportReport(rows: object[]) {
+  const csv = toCsv(rows); // your own serialiser
+  const payload = yield* askCreateTextQpqBinaryData(csv, 'report.csv', TextFileType.Csv);
+
+  yield* askFileWriteBinaryContents('exports', 'reports/latest.csv', payload);
+  return payload;
+}
+```
+
+## Signature
+
+```typescript
+function* askCreateTextQpqBinaryData(
+  textData: string,
+  filename: string,
+  fileType: TextFileType,
+): AskResponse<QPQBinaryData>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `textData` | `string` | The text to wrap. It is encoded as UTF-8 and then base64-encoded into `base64Data`. |
+| `filename` | `string` | The filename to record on the payload (used e.g. for downloads and content disposition). |
+| `fileType` | `TextFileType` | The kind of text — selects the `mimetype`. See the table below. |
+
+### `TextFileType`
+
+An enum of supported text formats. Each maps to a MIME type that is stored on the resulting `QPQBinaryData.mimetype`:
+
+| Member | MIME type |
+| --- | --- |
+| `TextFileType.Json` | `application/json` |
+| `TextFileType.Xml` | `application/xml` |
+| `TextFileType.PlainText` | `text/plain` |
+| `TextFileType.Html` | `text/html` |
+| `TextFileType.Css` | `text/css` |
+| `TextFileType.JavaScript` | `application/javascript` |
+| `TextFileType.Csv` | `text/csv` |
+| `TextFileType.Markdown` | `text/markdown` |
+| `TextFileType.Yaml` | `application/x-yaml` |
+| `TextFileType.Rtf` | `application/rtf` |
+
+## Returns
+
+A [`QPQBinaryData`](#qpqbinarydata) value whose `base64Data` is the base64 of the UTF-8 text, `filename` is the supplied name, and `mimetype` is derived from `fileType`. The optional `contentDisposition` field is left unset.
+
+## QPQBinaryData
+
+`QPQBinaryData` is quidproquo's portable, JSON-safe wrapper for binary content. Because the bytes are held as a base64 **string**, the value can be returned from a story, stored in a key-value store, sent over an event bus or queue, or passed to an HTTP response without any platform-specific `Buffer`/`Blob` type leaking through. It is the shape produced and consumed by the file binary actions.
+
+```typescript
+interface QPQBinaryData {
+  base64Data: string;
+  filename: string;
+  mimetype?: string;
+  contentDisposition?: string;
+}
+```
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `base64Data` | `string` | The content's bytes, base64-encoded. Decode with `Buffer.from(base64Data, 'base64')` (or the browser equivalent) to recover the raw bytes. |
+| `filename` | `string` | The logical filename for the content — used when writing to a drive or offering a download. |
+| `mimetype` | `string` (optional) | The content's MIME type, e.g. `text/csv` or `image/png`. |
+| `contentDisposition` | `string` (optional) | An HTTP `Content-Disposition` value (e.g. `attachment; filename="report.csv"`) for when the payload is served directly to a browser. |
+
+## Related
+
+- [askFileWriteBinaryContents](../file/ask-file-write-binary-contents.md) — write a `QPQBinaryData` payload to a storage drive.
+- [askFileReadBinaryContents](../file/ask-file-read-binary-contents.md) — read a file back as `QPQBinaryData`.

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

@@ -0,0 +1,7 @@
+{
+  "label": "Claude AI",
+  "link": {
+    "type": "generated-index",
+    "description": "Low-level actions that call the Anthropic Claude Messages API directly. For the higher-level, provider-agnostic prompt actions see the AI domain."
+  }
+}

package/template/docusaurus/docs/actions/core/claude-ai/ask-claude-ai-messages-api.md

@@ -0,0 +1,70 @@
+---
+title: askClaudeAiMessagesApi
+description: Call the Anthropic Claude Messages API directly from a story, passing a raw request body and API key.
+---
+
+# askClaudeAiMessagesApi
+
+Calls the [Anthropic Claude Messages API](https://docs.anthropic.com/en/api/messages) directly and returns the raw `Anthropic.Message` response. This is a thin, low-level passthrough — you hand it the exact request body the Anthropic SDK expects and an API key, and get the SDK's response back untouched.
+
+Prefer the provider-agnostic [askAiPrompt](../ai/ask-ai-prompt.md) / [askAiPromptStream](../ai/ask-ai-prompt-stream.md) actions for most work; reach for this when you need a Claude-specific feature exposed by the Messages API that the higher-level actions don't surface.
+
+- **Action type:** `ClaudeAiActionType.MessagesApi`
+- **On AWS:** invokes the Anthropic API over the network via the `@anthropic-ai/sdk` client, using the API key you pass.
+
+```typescript
+import { askClaudeAiMessagesApi, askConfigGetSecret } from 'quidproquo-core';
+
+export function* askAskClaude(question: string) {
+  const apiKey = yield* askConfigGetSecret('anthropic-api-key');
+
+  const message = yield* askClaudeAiMessagesApi(
+    {
+      model: 'claude-sonnet-4-6',
+      max_tokens: 1024,
+      messages: [{ role: 'user', content: question }],
+    },
+    apiKey,
+  );
+
+  return message.content;
+}
+```
+
+## Signature
+
+```typescript
+function* askClaudeAiMessagesApi(
+  body: Anthropic.Messages.MessageCreateParamsNonStreaming,
+  apiKey: string,
+): AskResponse<Anthropic.Message>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `body` | `Anthropic.Messages.MessageCreateParamsNonStreaming` | The full Messages API request body — `model`, `max_tokens`, `messages`, and any other Claude parameters. This is the exact type from `@anthropic-ai/sdk`; only the non-streaming form is supported. |
+| `apiKey` | `string` | Your Anthropic API key. Load it from a [secret](../../../config/core/secret.md) with `askConfigGetSecret` rather than hard-coding it. |
+
+## Returns
+
+`Anthropic.Message` — the raw response object from the Anthropic SDK, including `content`, `stop_reason`, `usage`, and the rest.
+
+## Errors
+
+| Error | Meaning |
+| --- | --- |
+| `ClaudeAiMessagesApiErrorTypeEnum.Unauthorized` | The API key is missing or invalid (HTTP 401). |
+| `ClaudeAiMessagesApiErrorTypeEnum.PermissionDenied` | The API key lacks permission for this request (403). |
+| `ClaudeAiMessagesApiErrorTypeEnum.InvalidRequest` | The request body was rejected as malformed or invalid (400 / 422). |
+| `ClaudeAiMessagesApiErrorTypeEnum.RateLimited` | The Anthropic API is rate limiting; back off and retry later (429). |
+| `ClaudeAiMessagesApiErrorTypeEnum.ServerError` | The Anthropic API returned a server error; a retry may succeed (5xx). |
+| `ClaudeAiMessagesApiErrorTypeEnum.ConnectionError` | Could not reach the Anthropic API (network failure or timeout). |
+
+Catch with `askCatch`, and pair `RateLimited` / `ServerError` / `ConnectionError` with [askRetry](../../../actions/core/system/ask-retry.md) since they are often transient.
+
+## Related
+
+- [askAiPrompt](../ai/ask-ai-prompt.md) / [askAiPromptStream](../ai/ask-ai-prompt-stream.md) — higher-level, provider-agnostic prompt actions; prefer these unless you need raw Messages API access.
+- [askConfigGetSecret](../../../actions/core/config/ask-config-get-secret.md) — load the API key from a configured secret.

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

@@ -0,0 +1,7 @@
+{
+  "label": "Config",
+  "link": {
+    "type": "generated-index",
+    "description": "Config actions read secrets, parameters, globals, and application metadata at runtime. They pair with the defineSecret / defineParameter / defineGlobal config settings."
+  }
+}

package/template/docusaurus/docs/actions/core/config/ask-config-get-application-info.md

@@ -0,0 +1,42 @@
+---
+title: askConfigGetApplicationInfo
+description: Read the running service's application, environment, module, and feature identity.
+---
+
+# askConfigGetApplicationInfo
+
+Returns the identity of the currently running service — its application name, deployment environment, module, and optional feature. Use it when a story needs to know *where* it's running, e.g. to build environment-scoped resource names, tag logs, or branch behaviour between `development` and `production`.
+
+- **Action type:** `ConfigActionType.GetApplicationInfo`
+- **Resolution:** derived from the resolved `QPQConfig` — no external call.
+
+```typescript
+import { askConfigGetApplicationInfo } from 'quidproquo-core';
+
+export function* askIsProduction() {
+  const { environment } = yield* askConfigGetApplicationInfo();
+  return environment === 'production';
+}
+```
+
+## Signature
+
+```typescript
+function* askConfigGetApplicationInfo(): AskResponse<ApplicationConfigInfo>;
+```
+
+## Returns
+
+`ApplicationConfigInfo`:
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `name` | `string` | The application name (from `defineApplication`). |
+| `environment` | `string` | The deployment environment, e.g. `development` / `production`. |
+| `module` | `string` | The module name (from `defineModule`). |
+| `feature` | `string?` | The feature branch/name, when the service is deployed as a feature environment. |
+
+## Related
+
+- [defineApplication](../../../config/core/application-name.md) — sets `name` (and `environment`, `feature`).
+- [defineModule](../../../config/core/module-name.md) — sets `module`.

package/template/docusaurus/docs/actions/core/config/ask-config-get-global.md

@@ -0,0 +1,52 @@
+---
+title: askConfigGetGlobal
+description: Read a typed global value baked into the application config at runtime.
+---
+
+# askConfigGetGlobal
+
+Reads a [global](../../../config/core/global.md) config value by name. Globals are typed, constant values declared in config with [defineGlobal](../../../config/core/global.md) and resolved from the config itself at runtime — no external store or network call. Reach for a global when you have a fixed value that belongs in config rather than hard-coded in a story, and that never changes at runtime (unlike a [parameter](../../../config/core/parameter.md)).
+
+- **Action type:** `ConfigActionType.GetGlobal`
+- **Resolution:** the value is read straight from the resolved `QPQConfig`, so it works on every runtime — including local JS execution with no cloud resources.
+
+```typescript
+import { askConfigGetGlobal } from 'quidproquo-core';
+
+interface FeatureLimits {
+  maxUploadsPerDay: number;
+}
+
+export function* askGetUploadLimit() {
+  const limits = yield* askConfigGetGlobal<FeatureLimits>('feature-limits');
+  return limits.maxUploadsPerDay;
+}
+```
+
+## Signature
+
+```typescript
+function* askConfigGetGlobal<T>(
+  globalName: string,
+): AskResponse<T>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `globalName` | `string` | Name of the global — must match one declared with [defineGlobal](../../../config/core/global.md). |
+
+The type parameter `T` is the shape of the stored value; it's up to you to keep it in sync with what [defineGlobal](../../../config/core/global.md) stored.
+
+## Returns
+
+`T` — the global's value, typed as you declared.
+
+## Related
+
+- [defineGlobal](../../../config/core/global.md) — declares the global value this action reads.
+- [askConfigGetParameter](./ask-config-get-parameter.md) — for values that change at runtime.
+- [askConfigGetSecret](./ask-config-get-secret.md) — for sensitive values.
+- [defineApplicationVersion](../../../config/core/application-version.md) — stores a version string as a global read with this action.
+- [askEventDocProvideStoreFromGlobals](../../features/event-doc/ask-event-doc-provide-store.md#askeventdocprovidestorefromglobals) — bridges per-route globals read with this action into the event-doc store context.

package/template/docusaurus/docs/actions/core/config/ask-config-get-parameter.md

@@ -0,0 +1,52 @@
+---
+title: askConfigGetParameter
+description: Read the value of a single configured parameter at runtime.
+---
+
+# askConfigGetParameter
+
+Reads the current value of a [parameter](../../../config/core/parameter.md) by name and returns it as a string. Parameters hold non-secret, mutable configuration — feature flags, external endpoints, tunable limits — that you want to change without redeploying code.
+
+- **Action type:** `ConfigActionType.GetParameter`
+- **On AWS:** reads from AWS Systems Manager Parameter Store (`ssm:GetParameter`). The parameter is provisioned by [defineParameter](../../../config/core/parameter.md).
+
+```typescript
+import { askConfigGetParameter } from 'quidproquo-core';
+
+export function* askGetFeatureFlag() {
+  const flag = yield* askConfigGetParameter('new-checkout-enabled');
+  return flag === 'true';
+}
+```
+
+## Signature
+
+```typescript
+function* askConfigGetParameter(
+  parameterName: string,
+): AskResponse<string>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `parameterName` | `string` | Name of the parameter — must match one declared with [defineParameter](../../../config/core/parameter.md) (or shared via its `owner` option). |
+
+## Returns
+
+`string` — the parameter's current value.
+
+## Errors
+
+| Error | Meaning |
+| --- | --- |
+| `ConfigGetParameterErrorTypeEnum.Throttling` | The request rate exceeded the provider's limit; back off and retry. |
+
+## Related
+
+- [defineParameter](../../../config/core/parameter.md) — declares the parameter this action reads.
+- [askConfigGetParameters](./ask-config-get-parameters.md) — read several parameters in one call.
+- [askConfigSetParameter](./ask-config-set-parameter.md) — update a parameter's value.
+- [askConfigListParameters](./ask-config-list-parameters.md) — list all parameter names.
+- [askConfigGetSecret](./ask-config-get-secret.md) — the equivalent for sensitive values.

package/template/docusaurus/docs/actions/core/config/ask-config-get-parameters.md

@@ -0,0 +1,49 @@
+---
+title: askConfigGetParameters
+description: Read several configured parameters in a single call.
+---
+
+# askConfigGetParameters
+
+Reads several [parameters](../../../config/core/parameter.md) at once, returning their values as a string array in the same order as the names you passed. Prefer this over multiple [askConfigGetParameter](./ask-config-get-parameter.md) calls when you need a handful of values — it's one round-trip.
+
+- **Action type:** `ConfigActionType.GetParameters`
+- **On AWS:** reads from AWS Systems Manager Parameter Store (`ssm:GetParameters`).
+
+```typescript
+import { askConfigGetParameters } from 'quidproquo-core';
+
+export function* askLoadEndpoints() {
+  const [billingUrl, searchUrl] = yield* askConfigGetParameters(['billing-endpoint', 'search-endpoint']);
+  return { billingUrl, searchUrl };
+}
+```
+
+## Signature
+
+```typescript
+function* askConfigGetParameters(
+  parameterNames: string[],
+): AskResponse<string[]>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `parameterNames` | `string[]` | Names of the parameters to read. Each must match one declared with [defineParameter](../../../config/core/parameter.md). |
+
+## Returns
+
+`string[]` — the parameter values, positionally aligned with `parameterNames`.
+
+## Errors
+
+| Error | Meaning |
+| --- | --- |
+| `ConfigGetParametersErrorTypeEnum.Throttling` | The request rate exceeded the provider's limit; back off and retry. |
+
+## Related
+
+- [askConfigGetParameter](./ask-config-get-parameter.md) — read a single parameter.
+- [defineParameter](../../../config/core/parameter.md) — declares the parameters.

package/template/docusaurus/docs/actions/core/config/ask-config-get-secret.md

@@ -0,0 +1,54 @@
+---
+title: askConfigGetSecret
+description: Read the value of a configured secret at runtime.
+---
+
+# askConfigGetSecret
+
+Reads the current value of a [secret](../../../config/core/secret.md) by name and returns it as a string. Use this for credentials, API keys, and other sensitive values that must not live in source or plain config.
+
+- **Action type:** `ConfigActionType.GetSecret`
+- **On AWS:** fetches the value from AWS Secrets Manager (`secretsmanager:GetSecretValue`). The secret itself is provisioned by [defineSecret](../../../config/core/secret.md).
+
+```typescript
+import { askConfigGetSecret, askClaudeAiMessagesApi } from 'quidproquo-core';
+
+export function* askCallExternalApi(prompt: string) {
+  const apiKey = yield* askConfigGetSecret('anthropic-api-key');
+
+  return yield* askClaudeAiMessagesApi(
+    { model: 'claude-sonnet-4-6', max_tokens: 512, messages: [{ role: 'user', content: prompt }] },
+    apiKey,
+  );
+}
+```
+
+## Signature
+
+```typescript
+function* askConfigGetSecret(
+  secretName: string,
+): AskResponse<string>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `secretName` | `string` | Name of the secret — must match a secret declared with [defineSecret](../../../config/core/secret.md) (or one shared via its `owner` option). |
+
+## Returns
+
+`string` — the secret's current value.
+
+## Errors
+
+| Error | Meaning |
+| --- | --- |
+| `ConfigGetSecretErrorTypeEnum.ResourceNotFound` | No secret with that name exists. |
+| `ConfigGetSecretErrorTypeEnum.Throttling` | The request rate exceeded the provider's limit; back off and retry. |
+
+## Related
+
+- [defineSecret](../../../config/core/secret.md) — declares the secret this action reads.
+- [askConfigGetParameter](./ask-config-get-parameter.md) — the equivalent for non-secret configuration values.

package/template/docusaurus/docs/actions/core/config/ask-config-list-parameters.md

@@ -0,0 +1,46 @@
+---
+title: askConfigListParameters
+description: List the names of all configured parameters.
+---
+
+# askConfigListParameters
+
+Returns the names of every [parameter](../../../config/core/parameter.md) available to the service. Useful for discovery or for iterating over a set of parameters whose names you don't know ahead of time.
+
+- **Action type:** `ConfigActionType.ListParameters`
+- **On AWS:** enumerates AWS Systems Manager Parameter Store (`ssm:DescribeParameters`).
+
+```typescript
+import { askConfigListParameters, askConfigGetParameter } from 'quidproquo-core';
+
+export function* askDumpAllParameters() {
+  const names = yield* askConfigListParameters();
+
+  const entries = [];
+  for (const name of names) {
+    entries.push([name, yield* askConfigGetParameter(name)]);
+  }
+  return entries;
+}
+```
+
+## Signature
+
+```typescript
+function* askConfigListParameters(): AskResponse<string[]>;
+```
+
+## Returns
+
+`string[]` — the names of all available parameters.
+
+## Errors
+
+| Error | Meaning |
+| --- | --- |
+| `ConfigListParametersErrorTypeEnum.Throttling` | The request rate exceeded the provider's limit; back off and retry. |
+
+## Related
+
+- [askConfigGetParameter](./ask-config-get-parameter.md) / [askConfigGetParameters](./ask-config-get-parameters.md) — read parameter values.
+- [defineParameter](../../../config/core/parameter.md) — declares a parameter.

package/template/docusaurus/docs/actions/core/config/ask-config-set-parameter.md

@@ -0,0 +1,51 @@
+---
+title: askConfigSetParameter
+description: Write a new value to a configured parameter at runtime.
+---
+
+# askConfigSetParameter
+
+Updates the value of a [parameter](../../../config/core/parameter.md) at runtime. This lets a story change configuration that later runs (or other services) will read with [askConfigGetParameter](./ask-config-get-parameter.md) — without a redeploy.
+
+- **Action type:** `ConfigActionType.SetParameter`
+- **On AWS:** writes to AWS Systems Manager Parameter Store.
+
+```typescript
+import { askConfigSetParameter } from 'quidproquo-core';
+
+export function* askDisableCheckout() {
+  yield* askConfigSetParameter('new-checkout-enabled', 'false');
+}
+```
+
+## Signature
+
+```typescript
+function* askConfigSetParameter(
+  parameterName: string,
+  parameterValue: string,
+): AskResponse<void>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `parameterName` | `string` | Name of the parameter to write — must match one declared with [defineParameter](../../../config/core/parameter.md). |
+| `parameterValue` | `string` | The new value. |
+
+## Returns
+
+`void` — the story resumes once the write has completed.
+
+## Errors
+
+| Error | Meaning |
+| --- | --- |
+| `ConfigSetParameterErrorTypeEnum.Throttling` | The request rate exceeded the provider's limit; back off and retry. |
+| `ConfigSetParameterErrorTypeEnum.QuotaExceeded` | The parameter store's storage limit was hit. |
+
+## Related
+
+- [askConfigGetParameter](./ask-config-get-parameter.md) — read the value back.
+- [defineParameter](../../../config/core/parameter.md) — declares the parameter.

package/template/docusaurus/docs/actions/core/config/ask-get-application-version.md

@@ -0,0 +1,39 @@
+---
+title: askGetApplicationVersion
+description: Read the deployed application version, or null if it isn't set.
+---
+
+# askGetApplicationVersion
+
+Returns the deployed application version — the value stored in the well-known `qpq-application-version` [global](../../../config/core/global.md) — or `null` if it hasn't been set. The version is typically something that identifies the deployed code, like a git SHA or build number, and is most useful in logs to tie a story execution back to the exact code that ran.
+
+- **Built from:** [askConfigGetGlobal](./ask-config-get-global.md), wrapped in [askCatch](../system/ask-catch.md) so a missing/unreadable global resolves to `null` instead of throwing.
+
+```typescript
+import { askGetApplicationVersion } from 'quidproquo-core';
+
+export function* askTagWithVersion(payload: Record<string, unknown>) {
+  const version = yield* askGetApplicationVersion();
+  return { ...payload, appVersion: version ?? 'unknown' };
+}
+```
+
+## Signature
+
+```typescript
+function* askGetApplicationVersion(): AskResponse<string | null>;
+```
+
+## Returns
+
+`string | null` — the application version, or `null` when the `qpq-application-version` global is not set (or can't be read).
+
+## Notes
+
+- The version is read from config as a global, so this works on any runtime with no external call.
+- The event-processing pipeline ([askProcessEvent](../event/ask-process-event.md)) calls this at the start of handling every event, purely so the version lands in the logs.
+
+## Related
+
+- [defineApplicationVersion](../../../config/core/application-version.md) — sets the version this reads.
+- [askConfigGetGlobal](./ask-config-get-global.md) — the underlying global read.

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

@@ -0,0 +1,7 @@
+{
+  "label": "Context",
+  "link": {
+    "type": "generated-index",
+    "description": "Context is ambient, story-scoped state — like React context for stories. Provide a value around a sub-story and read it anywhere inside, without threading it through every call."
+  }
+}