create-qpq-app 0.1.5

package/template/docusaurus/docs/config/core/action-processors.md

@@ -0,0 +1,65 @@
+---
+title: defineActionProcessors
+description: Register a service's custom or overriding action processors — the runtime implementations that execute yielded actions.
+---
+
+# defineActionProcessors
+
+Defines a source of **action processors** for a service. Stories yield actions; action processors are the runtime functions that actually execute them (talk to S3, DynamoDB, an API, etc.). `defineActionProcessors` points at a module that returns a map of processors, which the runtime merges into the service's processor list — the mechanism for **registering custom actions** or **overriding** the built-in processor for an existing action type. This is an advanced extension point; most services never need it.
+
+- **On AWS:** no infrastructure of its own. The referenced module is bundled as a build source and loaded inside the service's existing Lambdas at runtime; there is no separate construct or resource.
+
+```typescript
+import { defineActionProcessors } from 'quidproquo-core';
+
+export default [
+  defineActionProcessors('/entry/actionProcessors/getCustomProcessors::getCustomProcessors'),
+];
+```
+
+## Signature
+
+```typescript
+function defineActionProcessors(
+  getActionProcessors: QpqFunctionRuntime,
+): ActionProcessorsQPQConfigSetting;
+```
+
+## Parameters
+
+### `getActionProcessors` — `QpqFunctionRuntime` (required)
+
+A reference (usually a relative path string of the form `'/path/to/file::exportedFunctionName'`) to a module whose export is an `ActionProcessorListResolver` — an async function called with the resolved config and a dynamic module loader that returns an **action processor list**: a map from action type to its processor function.
+
+```typescript
+// getCustomProcessors.ts
+import { ActionProcessorListResolver } from 'quidproquo-core';
+
+export const getCustomProcessors: ActionProcessorListResolver = async (qpqConfig, dynamicModuleLoader) => ({
+  ['MyDomain.DoThing']: async (payload, session, actionProcessors, logger, updateSession, dynamicModuleLoader, streamRegistry) => {
+    // execute the action and return its result
+  },
+});
+```
+
+Each key is an **action type**; each value is the processor that runs when a story yields an action of that type. Because the runtime merges all processor sources into a single map (later sources spread over earlier ones), a source that provides a key matching a built-in action type **overrides** the built-in processor, and a source that provides a new key **registers a custom action**. You can declare `defineActionProcessors` more than once — every declared source is loaded and merged. Each source's `uniqueKey` is derived from its runtime reference.
+
+## Notes
+
+- The resolver is invoked with the service's `QPQConfig` and a `dynamicModuleLoader`, so it can build processors that depend on config or lazily load further modules.
+- A custom action typically pairs with a custom action **requester** (an `ask*` generator) that yields the matching action type, so stories can compose it like any built-in action.
+
+## Examples
+
+```typescript
+import { defineActionProcessors } from 'quidproquo-core';
+
+export default [
+  // Register custom actions and/or override built-in processors
+  defineActionProcessors('/entry/actionProcessors/getCustomProcessors::getCustomProcessors'),
+];
+```
+
+## Related
+
+- **AWS implementation:** no dedicated construct — the resolver module is bundled and loaded inside the service's Lambdas at runtime.

package/template/docusaurus/docs/config/core/ai.md

@@ -0,0 +1,80 @@
+---
+title: defineAi
+description: Define a named AI configuration — a set of tools a large language model can call while answering a prompt.
+---
+
+# defineAi
+
+Declares a named **AI config**: a bundle of tool definitions that a large language model is allowed to call while it answers. Bind it to a prompt by passing its name as the `aiName` option to [askAiPrompt](../../actions/core/ai/ask-ai-prompt.md) or [askAiPromptStream](../../actions/core/ai/ask-ai-prompt-stream.md). Without an `aiName`, prompts run tool-less; with one, the model can invoke the declared tools and the runtime executes them and feeds the results back.
+
+```typescript
+import { defineAi } from 'quidproquo-core';
+
+export default [
+  defineAi('support-agent', {
+    tools: [
+      {
+        name: 'lookupOrder',
+        description: 'Look up an order by its id and return its current status.',
+        executor: '/entry/ai/lookupOrder::lookupOrder',
+        inputSchema: {
+          type: 'object',
+          properties: { orderId: { type: 'string' } },
+          required: ['orderId'],
+        },
+      },
+    ],
+  }),
+];
+```
+
+## Signature
+
+```typescript
+function defineAi(
+  aiName: string,
+  options: QPQConfigAdvancedAiSettings,
+): AiQPQConfigSetting;
+```
+
+## Parameters
+
+### `aiName` — `string` (required)
+
+The name of the AI config, and its `uniqueKey` within the config. This is the value you pass as the `aiName` option to the AI prompt actions to bind these tools to a request.
+
+### `options` — `QPQConfigAdvancedAiSettings` (required)
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `tools` | [`AiToolDefinition[]`](#aitooldefinition) | `[]` | The tools the model may call while answering. |
+| `owner` | `CrossModuleOwner<'aiName'>` | – | Declares that this AI config is owned by **another** module/service, so this service binds to it rather than defining its own. `{ module, application, feature, environment, aiName }` — all optional; unset parts default to the current service. |
+
+### `AiToolDefinition`
+
+```typescript
+interface AiToolDefinition {
+  name: string;
+  description: string;
+  executor: string;
+  inputSchema: Record<string, unknown>;
+}
+```
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `name` | `string` | Tool name the model uses to call it. |
+| `description` | `string` | Natural-language description of what the tool does — the model reads this to decide when to call it, so make it precise. |
+| `executor` | `string` | A `QpqFunctionRuntime` reference (`'/path/to/file::exportedFunction'`) to the story that runs when the model calls the tool. It receives the tool input (validated against `inputSchema`) and returns the tool output. |
+| `inputSchema` | `Record<string, unknown>` | A JSON Schema describing the tool's input. The model is constrained to produce arguments matching this schema. |
+
+## Notes
+
+- When a bound prompt triggers a tool call, the AI action processor runs the tool's `executor` story and returns its result to the model, looping up to 10 tool-calling steps before finishing.
+- Streaming prompts surface each tool call, result, and approval request as `ToolCall` / `ToolResult` / `ToolApprovalRequest` parts on the stream — see [askAiPromptStream](../../actions/core/ai/ask-ai-prompt-stream.md#aistreamparttype).
+
+## Related
+
+- [askAiPrompt](../../actions/core/ai/ask-ai-prompt.md) — one-shot prompt; pass `aiName` to enable these tools.
+- [askAiPromptStream](../../actions/core/ai/ask-ai-prompt-stream.md) — streaming prompt with the same `aiName` binding.
+- [defineEventDocAi](../features/event-doc-ai.md) — registers an AI (name + tools) for a per-document chat feature.

package/template/docusaurus/docs/config/core/api-build-path.md

@@ -0,0 +1,40 @@
+---
+title: defineApiBuildPath
+description: Set the directory that holds the service's compiled API bundle, packaged and deployed as the runtime code.
+---
+
+# defineApiBuildPath
+
+Declares the **API build path**: the directory (relative to the [config root](./application-name.md)) that contains the service's compiled/bundled backend code. The deploy layer packages this directory as the code artifact for the service's functions.
+
+It is normally set for you by [defineApplicationModule](./application-module.md); declare it directly only when composing the identity settings by hand.
+
+- **On AWS:** does not deploy a resource of its own. The deploy layer resolves the full path by joining the config root with this value (`qpqCoreUtils.getApiBuildPath` → `getApiBuildPathFullPath`), then uses that directory as the Lambda function code asset.
+
+```typescript
+import { defineApiBuildPath } from 'quidproquo-core';
+
+export default [
+  defineApiBuildPath('./build/api'),
+];
+```
+
+## Signature
+
+```typescript
+function defineApiBuildPath(
+  apiBuildPath: string,
+): ApiBuildPathQPQConfigSetting;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `apiBuildPath` | `string` | Path to the compiled API bundle, relative to the config root (the `configRoot` passed to [defineApplication](./application-name.md)). Also the setting's `uniqueKey`. Resolved at deploy time with `qpqCoreUtils.getApiBuildPath` and joined against the config root to locate the code to package. |
+
+## Related
+
+- [defineApplicationModule](./application-module.md) — declares this alongside the application and module identity.
+- [defineApplication](./application-name.md) — provides the config root this path is resolved against.
+- [defineJavascriptRuntime](./javascript-runtime.md) — selects the runtime the packaged code executes on.

package/template/docusaurus/docs/config/core/application-module.md

@@ -0,0 +1,58 @@
+---
+title: defineApplicationModule
+description: Declare a service's application, module, and API build path in one call — the standard entry point at the top of a QPQ config.
+---
+
+# defineApplicationModule
+
+The standard way to declare a service's identity. `defineApplicationModule` is a convenience that expands into three settings at once — [defineApplication](./application-name.md), [defineModule](./module-name.md), and [defineApiBuildPath](./api-build-path.md) — so a config's opening line establishes the application, module, environment, config root, and build output path together.
+
+It returns a `QPQConfig` (an array of settings), which you spread into your config alongside the rest of your `define*` calls.
+
+- **On AWS:** does not deploy a resource of its own. It contributes the identity and build-path values that the deploy layer uses to name and package every other resource.
+
+```typescript
+import { defineApplicationModule } from 'quidproquo-core';
+
+export default [
+  ...defineApplicationModule('my-app', 'web', 'production', __dirname, './build/api'),
+
+  // ...the rest of your settings
+];
+```
+
+## Signature
+
+```typescript
+function defineApplicationModule(
+  applicationName: string,
+  moduleName: string,
+  environment: string,
+  configRoot: string,
+  apiBuildPath: string,
+  feature?: string,
+): QPQConfig;
+```
+
+## Parameters
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| `applicationName` | `string` | – (required) | Passed to [defineApplication](./application-name.md) as the application name. |
+| `moduleName` | `string` | – (required) | Passed to [defineModule](./module-name.md) as the module name. |
+| `environment` | `string` | – (required) | Passed to [defineApplication](./application-name.md) as the deployment environment. |
+| `configRoot` | `string` | – (required) | Passed to [defineApplication](./application-name.md) as the config root — almost always `__dirname`. |
+| `apiBuildPath` | `string` | – (required) | Passed to [defineApiBuildPath](./api-build-path.md) as the compiled-API output directory. |
+| `feature` | `string` | `undefined` | Optional feature name, forwarded to [defineApplication](./application-name.md). Set it to deploy an isolated feature environment. |
+
+## Notes
+
+- The call returns an array of settings. Spread it (`...defineApplicationModule(...)`) into your config's top-level array.
+- For the meaning of each underlying value and how it is consumed at deploy/runtime, see the individual pages linked below.
+
+## Related
+
+- [defineApplication](./application-name.md) — application name, environment, config root, feature.
+- [defineModule](./module-name.md) — module name.
+- [defineApiBuildPath](./api-build-path.md) — compiled-API output directory.
+- [defineApplicationVersion](./application-version.md) — records a deployable version string.

package/template/docusaurus/docs/config/core/application-name.md

@@ -0,0 +1,66 @@
+---
+title: defineApplication
+description: Define the application identity — application name, environment, config root, and optional feature — that scopes every deployed resource.
+---
+
+# defineApplication
+
+Declares the **application identity** for a service: its application name, deployment environment, config root directory, and optional feature name. Together with [defineModule](./module-name.md), these values form the prefix used to name every resource the service deploys, so the same config can deploy independently to multiple environments (and feature branches) without collisions.
+
+Most services do not call `defineApplication` directly — [defineApplicationModule](./application-module.md) is the usual entry point, which calls `defineApplication`, `defineModule`, and [defineApiBuildPath](./api-build-path.md) in one step.
+
+- **On AWS:** does not deploy a resource of its own. Its values are read by the deploy layer (`qpqCoreUtils.getFullyQualifiedResourceName`) to derive the physical name of every construct — buckets, tables, queues, functions, etc. — as `application / module / environment / feature / resourceName`.
+
+```typescript
+import { defineApplication } from 'quidproquo-core';
+
+export default [
+  defineApplication('my-app', 'production', __dirname),
+];
+```
+
+## Signature
+
+```typescript
+function defineApplication(
+  applicationName: string,
+  environment: string,
+  configRoot: string,
+  feature?: string,
+): ApplicationQPQConfigSetting;
+```
+
+## Parameters
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| `applicationName` | `string` | – (required) | The application name, and this setting's `uniqueKey`. Prefixes every physical resource name and is surfaced to stories via [askConfigGetApplicationInfo](../../actions/core/config/ask-config-get-application-info.md) (`name`). Resolved internally with `qpqCoreUtils.getApplicationName`. |
+| `environment` | `string` | – (required) | The deployment environment (e.g. `development`, `production`). Part of the resource-name prefix and the key that [defineEnvironmentSettings](./environment-settings.md) branches on. Resolved with `qpqCoreUtils.getApplicationModuleEnvironment` (falls back to `production` if unset at read time). Surfaced to stories as `environment`. |
+| `configRoot` | `string` | – (required) | The absolute root directory of the service config, almost always `__dirname`. The deploy layer joins paths such as the [API build path](./api-build-path.md) against this root. Resolved with `qpqCoreUtils.getConfigRoot`. |
+| `feature` | `string` | `undefined` | Optional feature name. When set, the service deploys as an isolated feature environment — `feature` becomes part of the resource-name prefix, keeping a feature branch's resources separate from the main environment. Surfaced to stories as `feature`. |
+
+## Notes
+
+- The `environment` value also drives config flattening: [defineEnvironmentSettings](./environment-settings.md) selects the child settings whose key matches the current environment.
+- Because `applicationName` is the setting's `uniqueKey`, a config should declare exactly one application identity.
+
+## Examples
+
+```typescript
+import { defineApplication } from 'quidproquo-core';
+
+export default [
+  // Standard production identity
+  defineApplication('billing', 'production', __dirname),
+
+  // A feature environment — isolates this branch's resources
+  defineApplication('billing', 'development', __dirname, 'checkout-redesign'),
+];
+```
+
+## Related
+
+- [defineModule](./module-name.md) — the module half of the service identity.
+- [defineApplicationModule](./application-module.md) — the convenience that declares application, module, and API build path together.
+- [defineApplicationVersion](./application-version.md) — records a deployable version string.
+- [askConfigGetApplicationInfo](../../actions/core/config/ask-config-get-application-info.md) — reads this identity (name, environment, module, feature) from a story.

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

@@ -0,0 +1,58 @@
+---
+title: defineApplicationVersion
+description: Record a deployable version string for the service, readable at runtime as a global.
+---
+
+# defineApplicationVersion
+
+Records a **version string** for the service. It is a thin convenience over [defineGlobal](./global.md): it stores the value under the reserved global key `qpq-application-version`, so the running application can report which version it is.
+
+Use it to stamp a build number, git SHA, or semver into a deployment and surface it later (for a health/version endpoint, log tagging, or cache-busting).
+
+- **On AWS:** does not deploy a resource of its own — the version is baked into the resolved config as a [global](./global.md), so reading it at runtime involves no network call.
+
+```typescript
+import { defineApplicationVersion } from 'quidproquo-core';
+
+export default [
+  ...defineApplicationVersion('1.4.2'),
+];
+```
+
+## Signature
+
+```typescript
+function defineApplicationVersion(
+  version: string,
+): QPQConfig;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `version` | `string` | The version string to record. Stored as a global under the reserved key `qpq-application-version`. |
+
+## Reading the version at runtime
+
+The value is stored as a global, so a story can read it with [askConfigGetGlobal](../../actions/core/config/ask-config-get-global.md) using the same reserved key, or via the `askGetApplicationVersion` story, which wraps that read and returns `null` when no version has been defined:
+
+```typescript
+import { askGetApplicationVersion } from 'quidproquo-core';
+
+export function* reportVersion() {
+  const version = yield* askGetApplicationVersion(); // string | null
+  return version ?? 'unknown';
+}
+```
+
+## Notes
+
+- The call returns an array of settings — spread it (`...defineApplicationVersion(...)`) into your config's top-level array.
+- The reserved key is exported as the constant `qpqApplicationVersionGlobal` (`'qpq-application-version'`).
+
+## Related
+
+- [defineGlobal](./global.md) — the underlying mechanism; `defineApplicationVersion` is a specialised global.
+- [askConfigGetGlobal](../../actions/core/config/ask-config-get-global.md) — reads any global, including the version key.
+- [defineApplication](./application-name.md) / [defineModule](./module-name.md) — the rest of the service identity.

package/template/docusaurus/docs/config/core/claude-ai.md

@@ -0,0 +1,52 @@
+---
+title: defineClaudeAI
+description: Define a named Claude AI configuration with a preferred model size.
+---
+
+# defineClaudeAI
+
+Declares a named **Claude AI config** carrying a preferred model size. It is a lightweight, Claude-specific config; most applications reach for [defineAi](./ai.md) (with the provider-agnostic [askAiPrompt](../../actions/core/ai/ask-ai-prompt.md) actions) or call the [Messages API directly](../../actions/core/claude-ai/ask-claude-ai-messages-api.md) with an explicit API key instead.
+
+```typescript
+import { defineClaudeAI, ClaudeAIModelSize } from 'quidproquo-core';
+
+export default [
+  defineClaudeAI('assistant', {
+    modelSize: ClaudeAIModelSize.Large,
+  }),
+];
+```
+
+## Signature
+
+```typescript
+function defineClaudeAI(
+  name: string,
+  options?: QPQConfigAdvancedClaudeAISettings,
+): ClaudeAIQPQConfigSetting;
+```
+
+## Parameters
+
+### `name` — `string` (required)
+
+The name of the config, and its `uniqueKey` within the config.
+
+### `options` — `QPQConfigAdvancedClaudeAISettings` (optional)
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `modelSize` | [`ClaudeAIModelSize`](#claudeaimodelsize) | `ClaudeAIModelSize.Medium` | The preferred model tier for this config. |
+
+### `ClaudeAIModelSize`
+
+| Member | Value |
+| --- | --- |
+| `Small` | `'small'` |
+| `Medium` | `'medium'` (default) |
+| `Large` | `'large'` |
+
+## Related
+
+- [defineAi](./ai.md) — the general AI config with tool definitions, used by the provider-agnostic prompt actions.
+- [askClaudeAiMessagesApi](../../actions/core/claude-ai/ask-claude-ai-messages-api.md) — call the Anthropic Messages API directly.

package/template/docusaurus/docs/config/core/config-value.md

@@ -0,0 +1,38 @@
+---
+title: defineConfigValue
+description: Define a generic named, typed value in the application config.
+---
+
+# defineConfigValue
+
+Declares a generic **config value**: a named, typed entry stored in the application config. It's the most primitive config setting — just a name and a value of any type — and is resolved from the config settings list rather than through a dedicated action.
+
+For most use cases prefer [defineGlobal](./global.md), which stores a value the same way but comes with a first-class read action ([askConfigGetGlobal](../../actions/core/config/ask-config-get-global.md)). Reach for `defineConfigValue` when you're building tooling that scans config settings by type and wants a plain typed value entry.
+
+```typescript
+import { defineConfigValue } from 'quidproquo-core';
+
+export default [
+  defineConfigValue('maxItems', 10),
+];
+```
+
+## Signature
+
+```typescript
+function defineConfigValue<T>(
+  configValueName: string,
+  configValue: T,
+): ConfigValueQPQConfigSetting<T>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `configValueName` | `string` | The name of the value, and its `uniqueKey` within the config. |
+| `configValue` | `T` | The value to store. `T` is inferred from what you pass. |
+
+## Related
+
+- [defineGlobal](./global.md) — the same idea with a dedicated read action; prefer it in stories.

package/template/docusaurus/docs/config/core/deploy-event.md

@@ -0,0 +1,94 @@
+---
+title: defineDeployEvent
+description: Define a deploy event — a hook story that runs at deploy time when the service's CloudFormation stacks change state.
+---
+
+# defineDeployEvent
+
+Defines a **deploy event**: a lifecycle hook story that runs at **deploy time** rather than in response to a request. It fires when the service's infrastructure stacks finish creating, updating, or deleting — the place for deploy-time work like seeding data, running migrations, warming caches, or notifying an external system that a new version is live. Like the other event sources it delivers its event through the [askProcessEvent](../../actions/core/event/ask-process-event.md) pipeline.
+
+- **On AWS:** deploys a **Lambda** plus an **EventBridge rule** matching `aws.cloudformation` "CloudFormation Stack Status Change" events (`QpqCoreDeployEventConstruct` in `quidproquo-deploy-awscdk`). On every stack status change the rule invokes the Lambda; the processor resolves which of the service's stacks changed (mapping it to `Api`, `Web`, or `Unknown`) and the completion status (`Create`, `Update`, `Delete`, or `Unknown`), then runs your story with that `DeployEvent`. The Lambda has a 15-minute timeout.
+
+```typescript
+import { defineDeployEvent } from 'quidproquo-core';
+
+export default [
+  defineDeployEvent('on-deploy', '/entry/deploy/onDeploy::onDeploy'),
+];
+```
+
+## Signature
+
+```typescript
+function defineDeployEvent(
+  name: string,
+  runtime: QpqFunctionRuntime,
+): DeployEventsQPQConfigSetting;
+```
+
+## Parameters
+
+### `name` — `string` (required)
+
+The name of the deploy event. This is its `uniqueKey`, and on AWS it derives the handler Lambda's name. It is also passed to the handler Lambda (as `deployEventConfigName`) so the runtime can resolve which deploy-event config it belongs to.
+
+### `runtime` — `QpqFunctionRuntime` (required)
+
+The story to run on each qualifying stack status change. Usually a relative path string of the form `'/path/to/file::exportedFunctionName'`. This story's entry point is registered as a build source.
+
+## The delivered event: `DeployEvent`
+
+The handler story receives a `DeployEvent` describing what changed:
+
+```typescript
+export enum DeployEventType {
+  Unknown = 'Unknown',
+  Api = 'Api',
+  Web = 'Web',
+}
+
+export enum DeployEventStatusType {
+  Unknown = 'Unknown',
+  Update = 'Update',
+  Create = 'Create',
+  Delete = 'Delete',
+}
+
+export type DeployEvent = {
+  deployEventType: DeployEventType;      // which stack changed (Api / Web / Unknown)
+  deployEventStatusType: DeployEventStatusType; // Create / Update / Delete / Unknown
+};
+
+export type DeployEventResponse = void;
+```
+
+Because the underlying rule fires on **every** stack status change, guard your logic on these fields — for example, only seed data when `deployEventType === DeployEventType.Api` and `deployEventStatusType === DeployEventStatusType.Create`.
+
+```typescript
+import { DeployEvent, DeployEventType, DeployEventStatusType } from 'quidproquo-core';
+
+export function* onDeploy(event: DeployEvent) {
+  if (event.deployEventType === DeployEventType.Api && event.deployEventStatusType === DeployEventStatusType.Create) {
+    // first-time API deploy: seed reference data
+  }
+}
+```
+
+## Examples
+
+```typescript
+import { defineDeployEvent } from 'quidproquo-core';
+
+export default [
+  // Run migrations / seeding after each deploy
+  defineDeployEvent('post-deploy-migrations', '/entry/deploy/onDeployMigrate::onDeployMigrate'),
+];
+```
+
+## Related
+
+- [askProcessEvent](../../actions/core/event/ask-process-event.md) — the pipeline that runs the handler story for the delivered `DeployEvent`.
+- [defineRecurringSchedule](./recurring-schedule.md) — a related time-based trigger that runs a story on a cron timetable rather than at deploy time.
+- [defineMigration](../webserver/migration.md) — a webserver helper built on this hook that runs data migrations once per deploy.
+- [defineSeed](../webserver/seed.md) — a webserver helper built on this hook that seeds initial data on the first deploy.
+- **AWS implementation:** `QpqCoreDeployEventConstruct` (handler Lambda + CloudFormation EventBridge rule) in `quidproquo-deploy-awscdk`.

package/template/docusaurus/docs/config/core/environment-settings.md

@@ -0,0 +1,67 @@
+---
+title: defineEnvironmentSettings
+description: Apply different config settings per deployment environment, with a wildcard fallback.
+---
+
+# defineEnvironmentSettings
+
+Applies **different settings depending on the deployment environment**. You pass a map from environment name to a `QPQConfig`; when the config is resolved, only the block matching the current environment (the `environment` given to [defineApplication](./application-name.md)) is included. A `'*'` key acts as a fallback for any environment not listed explicitly.
+
+Use it to vary a value between `development` and `production` — a different parameter, an extra drive in production, tighter limits per environment, and so on — without maintaining separate config files.
+
+- **On AWS:** does not deploy a resource of its own. It is resolved during config flattening (`qpqCoreUtils`): the matching environment's settings are spliced into the config and then deploy as normal, so whatever you put inside deploys only in that environment.
+
+```typescript
+import { defineEnvironmentSettings, defineParameter } from 'quidproquo-core';
+
+export default [
+  defineEnvironmentSettings({
+    production: [defineParameter('log-level', 'warn')],
+    '*': [defineParameter('log-level', 'debug')],
+  }),
+];
+```
+
+## Signature
+
+```typescript
+function defineEnvironmentSettings(
+  settingsByEnvironment: Record<string, QPQConfig>,
+): EnvironmentSettingsQPQConfigSetting;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `settingsByEnvironment` | `Record<string, QPQConfig>` | A map from environment name to the settings to apply for that environment. Each value is a `QPQConfig` (an array of `define*` settings). The key `'*'` is used as a fallback when the current environment has no explicit entry. |
+
+## Notes
+
+- The current environment comes from [defineApplication](./application-name.md); resolution defaults the environment to `development` during flattening if none is set.
+- Selection order: the exact environment key wins; otherwise the `'*'` key; otherwise no settings are added for that block.
+- The setting's `uniqueKey` is derived from the sorted list of environment keys.
+
+## Examples
+
+```typescript
+import { defineEnvironmentSettings, defineStorageDrive, defineParameter } from 'quidproquo-core';
+
+export default [
+  defineEnvironmentSettings({
+    // Only production gets an archive drive
+    production: [
+      defineStorageDrive('archive'),
+      defineParameter('rate-limit', '1000'),
+    ],
+
+    // Everything else (development, feature envs, ...) shares this
+    '*': [defineParameter('rate-limit', '100')],
+  }),
+];
+```
+
+## Related
+
+- [defineServiceSettings](./service-settings.md) — the same idea, keyed by module (service) name instead of environment.
+- [defineApplication](./application-name.md) — sets the environment this selects on.