create-qpq-app 0.1.5

package/template/docusaurus/docs/config/core/notify-error.md

@@ -0,0 +1,97 @@
+---
+title: defineNotifyError
+description: Define an error notifier — watches a service's failures via CloudWatch alarms and publishes state changes to event buses so a story can react.
+---
+
+# defineNotifyError
+
+Defines an **error notifier**: it watches the service's Lambda failures and, when they cross a threshold, publishes an alarm-state change to one or more [event buses](./event-bus.md). Subscribe a [queue](./queue.md) to those buses and its consumer story receives a `NotifyErrorQueueEvent` describing the alarm — the mechanism that turns runtime errors and throttles into a reactive notification (page a channel, open a ticket, etc.) processed through the standard [askProcessEvent](../../actions/core/event/ask-process-event.md) pipeline.
+
+- **On AWS:** deploys two **CloudWatch alarms** (`QpqCoreNotifyErrorConstruct` in `quidproquo-deploy-awscdk`) on the `AWS/Lambda` namespace — one on the `Errors` metric and one on the `Throttles` metric, each with a 60-second period and a threshold of 1 (fires when at least one error/throttle occurs in the period). For every event bus named in `onAlarm.publishToEventBus`, an SNS alarm action is added that publishes the alarm-state change to that bus's SNS topic. A queue subscribed to the bus then delivers the message to your handler story.
+
+```typescript
+import { defineNotifyError, defineEventBus, defineQueue } from 'quidproquo-core';
+import { NotifyErrorQueueEvents } from 'quidproquo-core';
+
+export default [
+  defineNotifyError('service-errors', {
+    onAlarm: { publishToEventBus: ['ops-alerts'] },
+  }),
+  defineEventBus('ops-alerts'),
+  defineQueue('ops-alerts-handler', {
+    [NotifyErrorQueueEvents.Error]: '/entry/queue/onServiceError::onServiceError',
+    [NotifyErrorQueueEvents.Throttle]: '/entry/queue/onServiceThrottle::onServiceThrottle',
+  }, {
+    eventBusSubscriptions: ['ops-alerts'],
+  }),
+];
+```
+
+## Signature
+
+```typescript
+function defineNotifyError(
+  name: string,
+  options?: QPQConfigAdvancedNotifyErrorSettings,
+): NotifyErrorQPQConfigSetting;
+```
+
+## Parameters
+
+### `name` — `string` (required)
+
+The name of the error notifier. This is the notifier's `uniqueKey`, and on AWS it derives the alarm names (`<name>-error` and `<name>-throttle`).
+
+### `options` — `QPQConfigAdvancedNotifyErrorSettings` (optional)
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `onAlarm.publishToEventBus` | `string[]` | – | Names of [event buses](./event-bus.md) to publish alarm-state changes to. Each named bus gets an SNS alarm action on both the error and throttle alarms. Subscribe a queue to these buses to run a handler story. |
+
+## The delivered event: `NotifyErrorQueueEvent`
+
+When a subscribed queue delivers the alarm, the consumer story receives a [QueueEvent](./queue.md) whose `message` is one of the notify-error message types, discriminated by `type`:
+
+```typescript
+export enum NotifyErrorQueueEvents {
+  Error = 'Error',
+  Timeout = 'Timeout',
+  Throttle = 'Throttle',
+  Unknown = 'Unknown',
+}
+
+// message.payload (shared across the message types)
+export type NotifyErrorQueueBaseEventPayload = {
+  newStateInAlarm: boolean;  // true when the alarm has just entered the ALARM state
+  newStateReason: string;    // human-readable reason for the new state
+  oldStateInAlarm: boolean;  // whether the alarm was previously in the ALARM state
+};
+```
+
+- `NotifyErrorQueueEvents.Error` (`NotifyErrorQueueErrorEventMessage`) — the error-rate alarm changed state.
+- `NotifyErrorQueueEvents.Throttle` (`NotifyErrorQueueThrottleEventMessage`) — the throttle alarm changed state.
+- `NotifyErrorQueueEvents.Timeout` / `NotifyErrorQueueEvents.Unknown` — additional message types the union defines; the AWS construct currently emits only the error and throttle alarms.
+
+Key each queue processor by the message `type` (using the `NotifyErrorQueueEvents` enum members) to route each alarm to the right handler story.
+
+## Examples
+
+```typescript
+import { defineNotifyError } from 'quidproquo-core';
+
+export default [
+  // Watch this service and fan alarm changes out to two buses
+  defineNotifyError('payments-errors', {
+    onAlarm: { publishToEventBus: ['ops-alerts', 'oncall'] },
+  }),
+];
+```
+
+## Related
+
+- [defineEventBus](./event-bus.md) — the bus alarm-state changes are published to.
+- [defineQueue](./queue.md) — subscribe a queue to the bus (`eventBusSubscriptions`) and key its processors by `NotifyErrorQueueEvents` to handle each alarm.
+- [askProcessEvent](../../actions/core/event/ask-process-event.md) — the pipeline that runs the handler story for the delivered message.
+- [defineAwsAlarm](../config-aws/aws-alarm.md) — declare an additional custom CloudWatch alarm beyond the default per-resource ones.
+- [defineAwsServiceDashboard](../config-aws/aws-service-dashboard.md) — its latency anomaly alarms route via this notify-error configuration.
+- **AWS implementation:** `QpqCoreNotifyErrorConstruct` (CloudWatch alarms + SNS alarm actions) in `quidproquo-deploy-awscdk`.

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

@@ -0,0 +1,53 @@
+---
+title: defineParameter
+description: Define a parameter — a named, non-secret configuration value that can change at runtime (an SSM Parameter Store entry on AWS).
+---
+
+# defineParameter
+
+Declares a **parameter**: a named, non-secret configuration value that can be read — and changed — at runtime without a redeploy. Good for feature flags, external endpoints, and tunable limits. Stories read it with [askConfigGetParameter](../../actions/core/config/ask-config-get-parameter.md) and can update it with [askConfigSetParameter](../../actions/core/config/ask-config-set-parameter.md).
+
+- **On AWS:** provisions an AWS Systems Manager Parameter Store `StringParameter` (Standard tier) and grants the service's role `ssm:GetParameter`, `ssm:GetParameters`, and `ssm:DescribeParameters`. The physical name is derived from application/module/environment.
+
+```typescript
+import { defineParameter } from 'quidproquo-core';
+
+export default [
+  // Seed an initial value; it can be changed later at runtime.
+  defineParameter('new-checkout-enabled', { value: 'false' }),
+];
+```
+
+## Signature
+
+```typescript
+function defineParameter(
+  key: string,
+  options?: QPQConfigAdvancedParameterSettings,
+): ParameterQPQConfigSetting;
+```
+
+## Parameters
+
+### `key` — `string` (required)
+
+The name of the parameter, and its `uniqueKey` within the config. This is the name you pass to the parameter actions.
+
+### `options` — `QPQConfigAdvancedParameterSettings` (optional)
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `value` | `string` | `''` | An initial value provisioned at deploy time. Runtime writes via [askConfigSetParameter](../../actions/core/config/ask-config-set-parameter.md) override it. |
+| `owner` | `CrossModuleOwner<'parameterName'>` | – | Declares that the parameter is owned by **another** module/service, so this service is granted access rather than creating its own. `{ module, application, feature, environment, parameterName }` — all optional; unset parts default to the current service. |
+
+## Notes
+
+- Parameters store **strings** — serialize structured values (e.g. `JSON.stringify`) yourself.
+- For sensitive values use [defineSecret](./secret.md); for fixed typed constants that never change at runtime use [defineGlobal](./global.md).
+
+## Related
+
+- [askConfigGetParameter](../../actions/core/config/ask-config-get-parameter.md) / [askConfigGetParameters](../../actions/core/config/ask-config-get-parameters.md) — read values.
+- [askConfigSetParameter](../../actions/core/config/ask-config-set-parameter.md) — update a value.
+- [askConfigListParameters](../../actions/core/config/ask-config-list-parameters.md) — list names.
+- [defineSecret](./secret.md) — sensitive values. [defineGlobal](./global.md) — fixed constants.

package/template/docusaurus/docs/config/core/promise-mode.md

@@ -0,0 +1,39 @@
+---
+title: definePromiseMode
+description: Switch the story-execution engine to a promise-based executor — an advanced, opt-in runtime mode.
+---
+
+# definePromiseMode
+
+Switches how the runtime **executes stories** from the default generator-driven engine to a promise-based one. It does this by registering an action-processor override (via `defineActionProcessors`) for the `SystemExecuteStory` action, replacing the default executor with the promisified implementation shipped in quidproquo-core.
+
+This is an advanced, opt-in mode. In the default mode, each executed story runs through the full instrumented runtime (its own runtime session, correlation, depth tracking, and event history). In promise mode, the executor drives the story generator directly against promises, and injects an extra trailing argument into every executed story — a `run` function that resolves a sub-story to a plain `Promise` — so stories can `await` other stories instead of relying solely on the generator runtime.
+
+- **Runtime behaviour, not infrastructure:** this deploys no AWS resource. It changes which processor handles `SystemActionType.ExecuteStory` at runtime.
+
+```typescript
+import { definePromiseMode } from 'quidproquo-core';
+
+export default [
+  ...definePromiseMode(),
+];
+```
+
+## Signature
+
+```typescript
+function definePromiseMode(): QPQConfig;
+```
+
+## Parameters
+
+None. `definePromiseMode()` takes no arguments and returns a `QPQConfig` (an array containing a single action-processor override). Spread it (`...definePromiseMode()`) into your config's top-level array.
+
+## Notes
+
+- The override targets the `SystemExecuteStory` action; when active, executed stories receive an additional final `run` argument (`<T>(story) => Promise<T>`) they can use to await sub-stories.
+- This is a low-level execution toggle intended for advanced use — most services do not need it.
+
+## Related
+
+- [defineApplicationModule](./application-module.md) — the identity settings that make up the rest of a config.

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

@@ -0,0 +1,112 @@
+---
+title: defineQueue
+description: Define a queue — a durable message queue whose consumer stories run for each message, driven by the message's type.
+---
+
+# defineQueue
+
+Defines a **queue**: a durable, asynchronous message channel. Stories enqueue messages with [askQueueSendMessages](../../actions/core/queue/ask-queue-send-messages.md), and the runtime delivers each message to a consumer **story** chosen by the message's `type`. A queue can also subscribe to one or more [event buses](./event-bus.md) so bus messages are delivered to it.
+
+- **On AWS:** deploys an **SQS queue** plus a dead-letter queue (`QpqCoreQueueConstruct`), and a consumer Lambda wired to the queue as an SQS event source (`QpqApiCoreQueueConstruct`, both in `quidproquo-deploy-awscdk`). Failed messages are retried up to `maxTries` times before going to the DLQ. Default CloudWatch alarms cover a growing backlog and any message landing in the DLQ. When `isFifo` is `true`, FIFO SQS queues (`.fifo` suffix) are created and the consumer processes messages in group order.
+
+```typescript
+import { defineQueue } from 'quidproquo-core';
+
+export default [
+  defineQueue('emails', {
+    'email.welcome': '/entry/queue/onSendWelcomeEmail::onSendWelcomeEmail',
+  }),
+];
+```
+
+## Signature
+
+```typescript
+function defineQueue(
+  name: string,
+  processors: QpqQueueProcessors,
+  options?: QPQConfigAdvancedQueueSettings,
+): QueueQPQConfigSetting;
+```
+
+## Parameters
+
+### `name` — `string` (required)
+
+The name of the queue. This is the name you pass to [askQueueSendMessages](../../actions/core/queue/ask-queue-send-messages.md) and it is the queue's `uniqueKey`. On AWS it derives the physical queue name (prefixed with application/module/environment).
+
+### `processors` — `QpqQueueProcessors` (required)
+
+A map from a message-**type pattern** to the consumer story that handles it:
+
+```typescript
+export interface QpqQueueProcessors {
+  [type: string]: QpqFunctionRuntime;
+}
+```
+
+Each key is matched against a delivered message's `type` field. The key may be a literal type (`'email.welcome'`) or a template with `{param}` placeholders (e.g. `'user.{userId}.created'`); the most relevant match wins, and any captured placeholder values are passed to the consumer story as its runtime options. Each value is a `QpqFunctionRuntime` — a reference to the consumer story's entry point, usually a relative path string of the form `'/path/to/file::exportedFunctionName'`. If a message's type matches no processor (and the queue has no event-bus subscriptions), that message errors.
+
+### `options` — `QPQConfigAdvancedQueueSettings` (optional)
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `batchSize` | `number` | `0` | Max number of messages delivered to the consumer Lambda per invocation. `0` leaves the SQS default. When set (> 0), the event source uses this batch size. |
+| `batchWindowInSeconds` | `number` | `5` | Max time SQS waits to fill a batch before invoking the consumer. Only applied when `batchSize > 0`, and **not** applied to FIFO queues (which don't support a batching window). |
+| `concurrency` | `number` | `1` | Consumer concurrency hint. |
+| `maxTries` | `number` | `1` | How many times a message is delivered before it is sent to the dead-letter queue (SQS `maxReceiveCount`). |
+| `ttRetryInSeconds` | `number` | `900` | Retry/visibility timeout in seconds — how long a message stays invisible while being processed before it can be redelivered. Also used as the consumer Lambda timeout. Capped at 900 (15 minutes). |
+| `hasDeadLetterQueue` | `boolean` | `true` | Whether a dead-letter queue backs the main queue. |
+| `eventBusSubscriptions` | `string[]` | `[]` | Names of [event buses](./event-bus.md) this queue subscribes to. Each subscribed bus's messages are delivered into this queue. |
+| `maxConcurrentExecutions` | `number` | – | Reserved concurrent executions for the consumer Lambda (caps parallelism). |
+| `isFifo` | `boolean` | `false` | Creates a **FIFO** queue that preserves per-group ordering and supports deduplication. See [FIFO queues](#fifo-queues). |
+| `deprecated` | `boolean` | `false` | Marks the queue as deprecated in the config. |
+
+## FIFO queues
+
+Setting `isFifo: true` deploys FIFO SQS queues (both the main queue and its DLQ). Ordering and deduplication are controlled per message when you enqueue, via the `groupId` and `deduplicationId` fields on each `QueueMessage` (see [askQueueSendMessages](../../actions/core/queue/ask-queue-send-messages.md)):
+
+- Messages with the same `groupId` are processed in order. Unset, it defaults to the queue name (global ordering).
+- `deduplicationId` suppresses duplicates within SQS's 5-minute window. Unset, a unique id is generated per send (no deduplication).
+
+The FIFO consumer processes records one group at a time using [askProcessEventWithGroupOrdering](../../actions/core/event/ask-process-event.md): once a message in a group fails, later messages in that same group are held (not executed) so the group can be redelivered in order, while other groups continue. A FIFO queue may only subscribe to a FIFO event bus (validated at deploy). FIFO event sources also don't support a batching window.
+
+## Examples
+
+```typescript
+import { defineQueue } from 'quidproquo-core';
+
+export default [
+  // Simple queue: one story per message type
+  defineQueue('emails', {
+    'email.welcome': '/entry/queue/onSendWelcomeEmail::onSendWelcomeEmail',
+    'email.receipt': '/entry/queue/onSendReceipt::onSendReceipt',
+  }),
+
+  // Batched work queue with retries
+  defineQueue('image-processing', {
+    'image.uploaded': '/entry/queue/onImageUploaded::onImageUploaded',
+  }, {
+    batchSize: 10,
+    batchWindowInSeconds: 30,
+    maxTries: 3,
+    ttRetryInSeconds: 300,
+  }),
+
+  // Ordered per-account processing, fed from an event bus
+  defineQueue('account-projector', {
+    'account.{accountId}.changed': '/entry/queue/onAccountChanged::onAccountChanged',
+  }, {
+    isFifo: true,
+    eventBusSubscriptions: ['account-events'],
+  }),
+];
+```
+
+## Related
+
+- [askQueueSendMessages](../../actions/core/queue/ask-queue-send-messages.md) — enqueues messages onto a queue declared here.
+- [defineEventBus](./event-bus.md) — a bus a queue can subscribe to via `eventBusSubscriptions`.
+- [askProcessEvent](../../actions/core/event/ask-process-event.md) — the pipeline that matches each delivered message to a consumer story (and preserves FIFO group ordering).
+- [defineNotifyError](./notify-error.md) — subscribe a queue to its bus to handle error/throttle alarms as `NotifyErrorQueueEvent` messages.
+- **AWS implementation:** `QpqCoreQueueConstruct` (SQS queue + DLQ + alarms) and `QpqApiCoreQueueConstruct` (consumer Lambda + SQS event source + bus subscriptions) in `quidproquo-deploy-awscdk`; the send-message processor in `quidproquo-actionprocessor-awslambda`.

package/template/docusaurus/docs/config/core/recurring-schedule.md

@@ -0,0 +1,117 @@
+---
+title: defineRecurringSchedule
+description: Define a recurring schedule — a cron-driven trigger that runs a story on a timetable.
+---
+
+# defineRecurringSchedule
+
+Defines a **recurring schedule**: a time-based trigger that runs a story on a cron timetable, with no incoming request. Use it for periodic work — nightly cleanups, polling, report generation, cache warming. Like a [queue](./queue.md) or [event bus](./event-bus.md), a schedule is an **event source**: each fire delivers a `ScheduledEvent` to the target story through the same [askProcessEvent](../../actions/core/event/ask-process-event.md) pipeline.
+
+- **On AWS:** deploys an **EventBridge rule** with a cron schedule expression and a **consumer Lambda** as its target (`QpqCoreRecurringScheduleConstruct` in `quidproquo-deploy-awscdk`). The rule fires on the cron cadence and invokes the Lambda, passing the schedule's `metadata` as the event `detail`. The Lambda has a 15-minute timeout, and `maxConcurrentExecutions` (when set) becomes the Lambda's reserved concurrent executions.
+
+```typescript
+import { defineRecurringSchedule } from 'quidproquo-core';
+
+export default [
+  // Every day at 3 AM (server time)
+  defineRecurringSchedule('0 0 3 * * ? *', '/entry/schedule/onNightlyCleanup::onNightlyCleanup'),
+];
+```
+
+## Signature
+
+```typescript
+function defineRecurringSchedule(
+  cronExpression: string,
+  runtime: QpqFunctionRuntime,
+  options?: QPQConfigAdvancedScheduleSettings,
+): ScheduleQPQConfigSetting;
+```
+
+## Parameters
+
+### `cronExpression` — `string` (required)
+
+The cron expression that controls when the schedule fires. On AWS this is wrapped as `cron(<cronExpression>)` in the EventBridge rule, so it uses the six-field AWS EventBridge cron syntax:
+
+```
+minutes hours day-of-month month day-of-week year
+```
+
+| Field | Values | Wildcards |
+| --- | --- | --- |
+| Minutes | `0-59` | `,` `-` `*` `/` |
+| Hours | `0-23` | `,` `-` `*` `/` |
+| Day-of-month | `1-31` | `,` `-` `*` `?` `/` `L` `W` |
+| Month | `1-12` or `JAN-DEC` | `,` `-` `*` `/` |
+| Day-of-week | `1-7` or `SUN-SAT` | `,` `-` `*` `?` `L` `#` |
+| Year | `1970-2199` | `,` `-` `*` `/` |
+
+You cannot use `*` in both the day-of-month and day-of-week fields at once — put `?` in the one you don't want to constrain. Examples:
+
+- `'* * * * ? *'` — every minute
+- `'0/10 * * * ? *'` — every 10 minutes
+- `'0 0 3 * * ? *'` — every day at 3 AM
+- `'0 0 3 ? * 1 *'` — every Monday at 3 AM
+
+### `runtime` — `QpqFunctionRuntime` (required)
+
+The story to run each time the schedule fires. Usually a relative path string of the form `'/path/to/file::exportedFunctionName'`. This story's entry point is registered as a build source, and its `uniqueKey` (derived from the runtime) identifies the schedule.
+
+### `options` — `QPQConfigAdvancedScheduleSettings` (optional)
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `metadata` | `Record<string, any>` | `{}` | Arbitrary data attached to the schedule. On AWS it is passed through as the EventBridge target's `detail` and surfaces on the delivered event as `ScheduledEvent.metadata`. |
+| `maxConcurrentExecutions` | `number` | – | Caps (and guarantees) the target Lambda's concurrent executions via reserved concurrency — never throttled below it, never scales above it. Carved out of the deploy account's shared concurrency pool. |
+| `owner` | `CrossModuleOwner<'recurringSchedule'>` | – | Declares the schedule as owned by another module/service (cross-module resource naming). |
+| `deprecated` | `boolean` | `false` | Marks the setting as deprecated in the config. |
+
+## The delivered event: `ScheduledEvent`
+
+Each fire delivers a `ScheduledEventParams` record to the target story:
+
+```typescript
+export interface ScheduledEventParams<T extends Record<string, any> = {}> {
+  time: string;         // ISO time the schedule fired
+  correlation: string;  // correlation id for this invocation
+  metadata: T;          // the `metadata` you set on the schedule
+}
+```
+
+- `time` — the event time reported by EventBridge.
+- `correlation` — a correlation id for the invocation (the AWS request id on Lambda).
+- `metadata` — the `metadata` object you passed to `defineRecurringSchedule`, typed by `T`.
+
+```typescript
+import { ScheduledEventParams } from 'quidproquo-core';
+
+export function* onNightlyCleanup(event: ScheduledEventParams) {
+  // event.time, event.correlation, event.metadata
+  yield* askLogCreate(LogLevelEnum.Info, `cleanup fired at ${event.time}`);
+}
+```
+
+## Examples
+
+```typescript
+import { defineRecurringSchedule } from 'quidproquo-core';
+
+export default [
+  // Poll an upstream every 10 minutes
+  defineRecurringSchedule('0/10 * * * ? *', '/entry/schedule/onPoll::onPoll'),
+
+  // Nightly report, capped to a single concurrent run, with metadata
+  defineRecurringSchedule('0 0 2 * * ? *', '/entry/schedule/onNightlyReport::onNightlyReport', {
+    maxConcurrentExecutions: 1,
+    metadata: { report: 'daily-summary' },
+  }),
+];
+```
+
+## Related
+
+- [askProcessEvent](../../actions/core/event/ask-process-event.md) — the pipeline that runs the target story for each schedule fire.
+- [defineQueue](./queue.md) and [defineEventBus](./event-bus.md) — the other core event sources.
+- [defineDeployEvent](./deploy-event.md) — a related time/lifecycle-based trigger that runs at deploy time rather than on a timetable.
+- **AWS implementation:** `QpqCoreRecurringScheduleConstruct` (EventBridge rule + target Lambda) in `quidproquo-deploy-awscdk`.

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

@@ -0,0 +1,51 @@
+---
+title: defineSecret
+description: Define a secret — a named, encrypted store for a sensitive value (a Secrets Manager secret on AWS).
+---
+
+# defineSecret
+
+Declares a **secret**: a named container for a sensitive value like an API key, database password, or signing key. Stories read the value at runtime with [askConfigGetSecret](../../actions/core/config/ask-config-get-secret.md). The value itself is never in your config or source — it's set out-of-band in the underlying secret store and only its name lives in code.
+
+- **On AWS:** provisions an AWS Secrets Manager secret, and grants the service's role `secretsmanager:GetSecretValue` on it. The physical secret name is derived from application/module/environment so the same config deploys cleanly to multiple environments.
+
+```typescript
+import { defineSecret } from 'quidproquo-core';
+
+export default [
+  defineSecret('anthropic-api-key'),
+];
+```
+
+## Signature
+
+```typescript
+function defineSecret(
+  key: string,
+  options?: QPQConfigAdvancedSecretSettings,
+): SecretQPQConfigSetting;
+```
+
+## Parameters
+
+### `key` — `string` (required)
+
+The name of the secret, and its `uniqueKey` within the config. This is the name you pass to [askConfigGetSecret](../../actions/core/config/ask-config-get-secret.md).
+
+### `options` — `QPQConfigAdvancedSecretSettings` (optional)
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `owner` | `CrossModuleOwner<'secretName'>` | – | Declares that the secret is owned by **another** module/service, so this service is granted read access to it rather than creating its own. `{ module, application, feature, environment, secretName }` — all optional; unset parts default to the current service. |
+
+## Notes
+
+- `defineSecret` only provisions the secret and access to it — populating the value is done separately (e.g. in the AWS console/CLI, or a deploy step), never in config.
+- For non-sensitive but runtime-mutable values, use [defineParameter](./parameter.md); for fixed typed constants, use [defineGlobal](./global.md).
+
+## Related
+
+- [askConfigGetSecret](../../actions/core/config/ask-config-get-secret.md) — reads the secret at runtime.
+- [defineParameter](./parameter.md) — non-secret, mutable configuration.
+- [defineGlobal](./global.md) — fixed, typed config constants.
+- [defineSubdomainRedirect](../webserver/subdomain-redirect.md) — can store a Cloudflare API key in a secret like this.

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

@@ -0,0 +1,49 @@
+---
+title: defineServiceSettings
+description: Apply different config settings per module (service), with a wildcard fallback.
+---
+
+# defineServiceSettings
+
+Applies **different settings depending on the module (service)**. You pass a map from module name to a `QPQConfig`; when the config is resolved, only the block matching the current module (the name given to [defineModule](./module-name.md)) is included. A `'*'` key acts as a fallback for any module not listed explicitly.
+
+Use it when several modules share one config file but each needs its own extra settings.
+
+- **On AWS:** does not deploy a resource of its own. It is resolved during config flattening (`qpqCoreUtils`): the matching module's settings are spliced into the config and then deploy as normal.
+
+```typescript
+import { defineServiceSettings, defineParameter } from 'quidproquo-core';
+
+export default [
+  defineServiceSettings({
+    web: [defineParameter('public-url', 'https://example.com')],
+    worker: [defineParameter('concurrency', '10')],
+    '*': [defineParameter('log-level', 'info')],
+  }),
+];
+```
+
+## Signature
+
+```typescript
+function defineServiceSettings(
+  settingsByService: Record<string, QPQConfig>,
+): ServiceSettingsQPQConfigSetting;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `settingsByService` | `Record<string, QPQConfig>` | A map from module (service) name to the settings to apply for that module. Each value is a `QPQConfig` (an array of `define*` settings). The key `'*'` is used as a fallback when the current module has no explicit entry. |
+
+## Notes
+
+- The module must already be declared via [defineModule](./module-name.md) (usually through [defineApplicationModule](./application-module.md)) before this resolves — otherwise flattening throws, since it has no service name to select on.
+- Selection order: the exact module key wins; otherwise the `'*'` key; otherwise no settings are added for that block.
+- The setting's `uniqueKey` is derived from the sorted list of module keys.
+
+## Related
+
+- [defineEnvironmentSettings](./environment-settings.md) — the same idea, keyed by environment instead of module.
+- [defineModule](./module-name.md) — sets the module name this selects on.

package/template/docusaurus/docs/config/core/storage-drive.md

@@ -0,0 +1,142 @@
+---
+title: defineStorageDrive
+description: Define a storage drive — a logical file container (an S3 bucket on AWS) that file actions read from and write to.
+---
+
+# defineStorageDrive
+
+Defines a **storage drive**: a named, logical container for files. Stories never talk to S3 or a filesystem directly — they read and write files on a drive by name using the [File action requesters](../../actions/core/file/ask-file-read-text-contents.md), and the runtime maps the drive to real storage.
+
+- **On AWS:** deploys an S3 bucket (`QpqCoreStorageDriveConstruct` in `quidproquo-deploy-awscdk`). The bucket is versioned, blocks all public access, and is retained on stack teardown unless the service opts into destroy via `defineAwsDataStoreRemovalPolicy`.
+
+```typescript
+import { defineStorageDrive } from 'quidproquo-core';
+
+export default [
+  defineStorageDrive('user-uploads'),
+];
+```
+
+## Signature
+
+```typescript
+function defineStorageDrive(
+  storageDrive: string,
+  options?: QPQConfigAdvancedStorageDriveSettings,
+): StorageDriveQPQConfigSetting;
+```
+
+## Parameters
+
+### `storageDrive` — `string` (required)
+
+The name of the drive. This is the name you pass as the `drive` argument to every file action (e.g. `askFileReadTextContents('user-uploads', ...)`). It is also the drive's `uniqueKey` within the config, and on AWS it is used to derive the physical bucket name (prefixed with application/module/environment, so the same config deploys to multiple environments without collisions).
+
+### `options` — `QPQConfigAdvancedStorageDriveSettings` (optional)
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `copyPath` | `string` | – | A local directory whose contents are uploaded ("seeded") into the drive on every deploy. Useful for static seed data. On AWS this becomes an S3 `BucketDeployment`. |
+| `global` | `boolean` | `false` | Marks the drive as globally accessible across the account rather than private to the owning module. |
+| `onEvent` | `StorageDriveEvents` | – | Story functions to run when files are created or deleted in the drive. See [File events](#file-events-onevent). |
+| `lifecycleRules` | `StorageDriveLifecycleRule[]` | – | Rules that transition files to cheaper [storage tiers](#storagedrivetier) or delete them after a period. See [Lifecycle rules](#lifecycle-rules). |
+| `encryption` | `boolean` | `false` | Enables customer-managed KMS encryption for the drive (the KMS key comes from the service's AWS config). When `false`, provider-managed encryption still applies (SSE-S3 on AWS) — this flag only controls the KMS upgrade. |
+| `owner` | `CrossModuleOwner<'storageDriveName'>` | – | Declares that this drive is owned by **another** module/service. Use this to read/write a drive deployed elsewhere: the deploy grants this service IAM access to the foreign drive instead of creating a new bucket. `{ module, application, feature, environment, storageDriveName }` — all optional; unset parts default to the current service. |
+
+## File events (`onEvent`)
+
+```typescript
+export interface StorageDriveEvents {
+  create?: QpqFunctionRuntime;
+  delete?: QpqFunctionRuntime;
+}
+```
+
+Each handler is a `QpqFunctionRuntime` — a reference to a story entry point, usually written as a relative path string in the form `'/path/to/file::exportedFunctionName'`:
+
+```typescript
+defineStorageDrive('images', {
+  onEvent: {
+    create: '/entry/storageDrive/onImageCreated::onImageCreated',
+    delete: '/entry/storageDrive/onImageDeleted::onImageDeleted',
+  },
+});
+```
+
+The handler story receives a `StorageDriveEvent` (exported from quidproquo-webserver) describing the drive and filepath that changed.
+
+## Lifecycle rules
+
+```typescript
+export type StorageDriveLifecycleRule = {
+  prefix?: string;              // only apply to files under this path prefix
+  transitions?: StorageDriveTransition[]; // move files to cheaper tiers over time
+  deleteAfterDays?: number;     // permanently delete files after N days
+  fileSizeLessThan?: number;    // only apply to files smaller than N bytes
+  fileSizeGreaterThan?: number; // only apply to files larger than N bytes
+  enabled?: boolean;
+};
+
+export type StorageDriveTransition = { storageDriveTier: StorageDriveTier } & (
+  | { transitionAfterDays: number }   // relative: N days after creation
+  | { transitionDate: string }        // absolute: ISO date
+);
+```
+
+A transition specifies **either** `transitionAfterDays` **or** `transitionDate`, never both (enforced by the type).
+
+### `StorageDriveTier`
+
+| Tier | Use for | AWS equivalent |
+| --- | --- | --- |
+| `REGULAR` | Frequently accessed data (default) | S3 Standard |
+| `OCCASIONAL_ACCESS` | Infrequent access, rapid retrieval | S3 Infrequent Access |
+| `SINGLE_ZONE_OCCASIONAL_ACCESS` | Infrequent access, single AZ, lower availability | S3 One Zone-IA |
+| `COLD_STORAGE` | Archival; retrieval takes minutes–hours | S3 Glacier |
+| `COLD_STORAGE_INSTANT_ACCESS` | Archival with millisecond access | S3 Glacier Instant Retrieval |
+| `DEEP_COLD_STORAGE` | Rarely accessed; retrieval up to 12 hours; cheapest | S3 Glacier Deep Archive |
+| `SMART_TIERING` | Unpredictable access patterns; auto-optimizes | S3 Intelligent Tiering |
+
+## Examples
+
+```typescript
+import { defineStorageDrive, StorageDriveTier } from 'quidproquo-core';
+
+export default [
+  // Simple private drive
+  defineStorageDrive('user-uploads'),
+
+  // Logs: archive after 30 days, delete after a year
+  defineStorageDrive('logs', {
+    lifecycleRules: [
+      {
+        transitions: [{ storageDriveTier: StorageDriveTier.COLD_STORAGE, transitionAfterDays: 30 }],
+        deleteAfterDays: 365,
+      },
+    ],
+  }),
+
+  // Seeded, encrypted drive with a create handler
+  defineStorageDrive('templates', {
+    copyPath: './seed/templates',
+    encryption: true,
+    onEvent: {
+      create: '/entry/storageDrive/onTemplateUploaded::onTemplateUploaded',
+    },
+  }),
+
+  // Use a drive owned by another service
+  defineStorageDrive('shared-assets', {
+    owner: { module: 'asset-service' },
+  }),
+];
+```
+
+## Related
+
+- **Action requesters that use this drive:** [askFileReadTextContents](../../actions/core/file/ask-file-read-text-contents.md), [askFileWriteTextContents](../../actions/core/file/ask-file-write-text-contents.md), and the rest of the File actions (binary/JSON read & write, list, exists, delete, temporary secure URLs, streams).
+- **CORS for browser access:** [defineStorageDriveCorsSettings](../webserver/storage-drive-cors-settings.md) (quidproquo-webserver) controls the allowed browser origins for direct-to-drive uploads/downloads.
+- [defineFederatedModuleStore](./federated-module-store.md) — loads a service's story code from a drive declared here.
+- [defineEventDocSummary](../features/event-doc-summary.md) — declares an event-document collection's asset bucket as a drive of this kind.
+- **AWS tuning:** [defineAwsKmsKey](../config-aws/aws-kms-key.md) (customer-managed encryption key for the `encryption` flag) and [defineAwsDataStoreRemovalPolicy](../config-aws/aws-data-store-removal-policy.md) (retain vs destroy the bucket on teardown).
+- **AWS implementation:** `QpqCoreStorageDriveConstruct` (bucket, lifecycle, KMS, IAM grants) in `quidproquo-deploy-awscdk`; file action processors in `quidproquo-actionprocessor-awslambda`.