create-qpq-app 0.1.5

package/template/docusaurus/docs/config/config-aws/account-budget.md

@@ -0,0 +1,117 @@
+---
+title: defineAccountBudget
+description: Define an AWS Budgets monthly cost budget with email threshold alerts plus Cost Anomaly Detection for an AWS account.
+---
+
+# defineAccountBudget
+
+Defines an **account-level monthly cost budget** with email alerts at configurable spend thresholds, plus AWS Cost Anomaly Detection for spend that deviates from the account's baseline (the slow cost creep that fixed percentage thresholds miss).
+
+This is an **account/organization bootstrap setting**: it does not configure a deployed service — it configures the AWS account itself. It is declared in a dedicated *account config* (an application config with no module, alongside the other `defineAccount*` settings) and deployed by the account stack, once per account.
+
+- **On AWS:** deploys an AWS Budgets `CfnBudget` (a `COST`, `MONTHLY` budget) with one email notification per threshold, and — unless anomaly detection is disabled — an `aws_ce` `CfnAnomalyMonitor` (`DIMENSIONAL` / `SERVICE`) plus a `CfnAnomalySubscription` that emails subscribers daily. Deployed by `QpqAccountBudgetConstruct` in the account stack (`AccountQpqStack`). AWS allows only **one** service-dimension anomaly monitor per account, so if several environments share one account, enable anomaly detection in only one of them (or set `anomalyDetection.disabled` on the extras).
+
+```typescript
+import { defineAccountBudget } from 'quidproquo-config-aws';
+
+export default [
+  defineAccountBudget('primary', 500, ['billing@example.com']),
+];
+```
+
+## Signature
+
+```typescript
+function defineAccountBudget(
+  name: string,
+  monthlyLimitUsd: number,
+  subscriberEmails: string[],
+  options?: {
+    thresholds?: BudgetThreshold[];
+    anomalyDetection?: AccountBudgetAnomalyDetection;
+  },
+): AccountBudgetQPQConfigSetting;
+```
+
+## Parameters
+
+### `name` — `string` (required)
+
+The budget's name. Used as the setting's `uniqueKey` and baked into the physical resource names (e.g. the budget is named `qpq-budget-<accountId>-<name>`, the anomaly monitor `qpq-anomaly-monitor-<accountId>-<name>`).
+
+### `monthlyLimitUsd` — `number` (required)
+
+The monthly cost budget in USD. Threshold alerts are calculated as a percentage of this amount.
+
+### `subscriberEmails` — `string[]` (required)
+
+Email addresses that receive both the budget threshold notifications and the cost anomaly alerts.
+
+### `options` — (optional)
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `thresholds` | `BudgetThreshold[]` | `80%` actual, `100%` forecasted, `100%` actual, `150%` actual | Alert thresholds. Each becomes one budget notification (`GREATER_THAN`, `PERCENTAGE`) emailing all subscribers. See [`BudgetThreshold`](#budgetthreshold). |
+| `anomalyDetection` | `AccountBudgetAnomalyDetection` | anomaly detection enabled, `minimumImpactUsd` `10` | Controls the Cost Anomaly Detection monitor/subscription created alongside the budget. See [`AccountBudgetAnomalyDetection`](#accountbudgetanomalydetection). |
+
+### `BudgetThreshold`
+
+```typescript
+export enum BudgetThresholdType {
+  actual = 'actual',
+  forecasted = 'forecasted',
+}
+
+export interface BudgetThreshold {
+  thresholdPercent: number;
+  type: BudgetThresholdType;
+}
+```
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `thresholdPercent` | `number` | Percentage of `monthlyLimitUsd` at which to alert (e.g. `80` fires at 80% of the budget). |
+| `type` | `BudgetThresholdType` | `actual` alerts on cost already incurred; `forecasted` alerts when the projected month-end cost is expected to cross the threshold. |
+
+### `AccountBudgetAnomalyDetection`
+
+```typescript
+export interface AccountBudgetAnomalyDetection {
+  disabled?: boolean;
+  minimumImpactUsd?: number;
+}
+```
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `disabled` | `boolean` | `false` | Anomaly detection is created alongside the budget by default; set `true` to opt out (e.g. on the extra environments sharing an account, since AWS permits only one service-dimension monitor per account). |
+| `minimumImpactUsd` | `number` | `10` | Minimum total cost impact (USD) before an anomaly alert is sent. Maps to the subscription's `ANOMALY_TOTAL_IMPACT_ABSOLUTE` threshold. |
+
+## Examples
+
+```typescript
+import { defineAccountBudget, BudgetThresholdType } from 'quidproquo-config-aws';
+
+export default [
+  // Custom thresholds, anomaly detection kept on with a higher impact floor
+  defineAccountBudget('primary', 2000, ['billing@example.com', 'cto@example.com'], {
+    thresholds: [
+      { thresholdPercent: 50, type: BudgetThresholdType.actual },
+      { thresholdPercent: 90, type: BudgetThresholdType.forecasted },
+      { thresholdPercent: 100, type: BudgetThresholdType.actual },
+    ],
+    anomalyDetection: { minimumImpactUsd: 50 },
+  }),
+
+  // A second environment sharing the same account: budget only, no anomaly monitor
+  defineAccountBudget('staging', 300, ['billing@example.com'], {
+    anomalyDetection: { disabled: true },
+  }),
+];
+```
+
+## Related
+
+- [defineAccountCloudTrail](./account-cloud-trail.md) — account audit logging, another `defineAccount*` bootstrap setting deployed by the same account stack.
+- [defineAccountSecurityServices](./account-security-services.md) — account threat-detection services deployed by the same account stack.
+- **AWS implementation:** `QpqAccountBudgetConstruct` (AWS Budgets + Cost Explorer anomaly detection) in `quidproquo-deploy-awscdk`.

package/template/docusaurus/docs/config/config-aws/account-cloud-trail.md

@@ -0,0 +1,75 @@
+---
+title: defineAccountCloudTrail
+description: Define an account-level AWS CloudTrail audit trail, with an S3 log bucket and optional CloudWatch Logs delivery.
+---
+
+# defineAccountCloudTrail
+
+Defines an **account-level CloudTrail audit trail** that records AWS API activity for the account into a dedicated, private S3 bucket, with optional delivery to a CloudWatch Logs group.
+
+This is an **account/organization bootstrap setting**: it configures the AWS account, not a deployed service. It is declared in a dedicated *account config* alongside the other `defineAccount*` settings and deployed by the account stack, once per account. One trail per account is the expected usage — additional trails bill a second copy of every management event.
+
+- **On AWS:** deploys an `aws_cloudtrail.Trail` writing to a private, SSE-S3-encrypted, SSL-enforced S3 bucket (`qpq-cloudtrail-<accountId>-<region>-<name>`, retained on teardown, with a lifecycle expiration equal to `retentionDays`). When `cloudWatchLogs` is set, it also creates a CloudWatch Logs group (`/qpq/cloudtrail/<name>`, destroyed on teardown) and sends trail events to it. Deployed by `QpqAccountCloudTrailConstruct` in the account stack (`AccountQpqStack`).
+
+```typescript
+import { defineAccountCloudTrail } from 'quidproquo-config-aws';
+
+export default [
+  defineAccountCloudTrail('audit'),
+];
+```
+
+## Signature
+
+```typescript
+function defineAccountCloudTrail(
+  name: string,
+  options?: {
+    retentionDays?: number;
+    enableLogFileValidation?: boolean;
+    multiRegion?: boolean;
+    includeGlobalServiceEvents?: boolean;
+    cloudWatchLogs?: { retentionDays?: number };
+  },
+): AccountCloudTrailQPQConfigSetting;
+```
+
+## Parameters
+
+### `name` — `string` (required)
+
+The trail's name. Used as the setting's `uniqueKey` and baked into the physical resource names — the trail is named `<name>-trail`, the S3 bucket `qpq-cloudtrail-<accountId>-<region>-<name>`, and (if enabled) the log group `/qpq/cloudtrail/<name>`.
+
+### `options` — (optional)
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `retentionDays` | `number` | `365` | Number of days log objects are retained in the S3 bucket before an S3 lifecycle rule expires them. |
+| `enableLogFileValidation` | `boolean` | `true` | Enables CloudTrail log file integrity validation (digest files that let you detect tampering). |
+| `multiRegion` | `boolean` | `true` | Makes the trail a multi-region trail, capturing events from every AWS Region. |
+| `includeGlobalServiceEvents` | `boolean` | `true` | Includes events from global services (e.g. IAM, CloudFront) in the trail. |
+| `cloudWatchLogs` | `{ retentionDays?: number }` | – (not delivered to CloudWatch) | When set, delivers trail events to a CloudWatch Logs group. `retentionDays` sets the log group's retention (resolved to the nearest supported CloudWatch retention period; omit for the construct default). This log group is what [defineAccountSecurityServices](./account-security-services.md)'s `cognitoAuthFailureAlert` runs its metric filter against. |
+
+## Examples
+
+```typescript
+import { defineAccountCloudTrail } from 'quidproquo-config-aws';
+
+export default [
+  // Audit trail with CloudWatch delivery, so the Cognito auth-failure alarm can attach
+  defineAccountCloudTrail('audit', {
+    retentionDays: 730,
+    cloudWatchLogs: { retentionDays: 90 },
+  }),
+];
+```
+
+## Notes
+
+- The `cloudWatchLogs` option is a prerequisite for the `cognitoAuthFailureAlert` in [defineAccountSecurityServices](./account-security-services.md): that alert's metric filter reads this trail's CloudWatch log group, and the deploy throws if the alert is requested without a trail that publishes to CloudWatch.
+
+## Related
+
+- [defineAccountSecurityServices](./account-security-services.md) — consumes this trail's CloudWatch log group for its Cognito auth-failure alarm.
+- [defineAccountBudget](./account-budget.md) — cost budget & anomaly alerts, another `defineAccount*` bootstrap setting on the same account stack.
+- **AWS implementation:** `QpqAccountCloudTrailConstruct` (CloudTrail trail, S3 log bucket, optional CloudWatch Logs group) in `quidproquo-deploy-awscdk`.

package/template/docusaurus/docs/config/config-aws/account-security-services.md

@@ -0,0 +1,91 @@
+---
+title: defineAccountSecurityServices
+description: Define account-level AWS security services — GuardDuty, Security Hub, and a Cognito auth-failure alarm — for an AWS account.
+---
+
+# defineAccountSecurityServices
+
+Defines **account-level AWS security services**: optionally a GuardDuty threat-detection detector, a Security Hub hub, and an email alarm that fires when Cognito sign-in failures spike (credential stuffing hitting Cognito directly, bypassing your APIs).
+
+This is an **account/organization bootstrap setting**: it configures the AWS account, not a deployed service. It is declared in a dedicated *account config* alongside the other `defineAccount*` settings and deployed by the account stack. Everything here is **opt-in** — creating account singletons should be a deliberate act. GuardDuty detectors and Security Hub hubs are one-per-account+region, so if several environments share one AWS account, enable them in only one environment's account config. There is a single `defineAccountSecurityServices` per account config (its `uniqueKey` is the constant `'accountSecurityServices'`).
+
+- **On AWS:** deployed by `QpqAccountSecurityServicesConstruct` in the account stack (`AccountQpqStack`). When enabled it creates a GuardDuty `CfnDetector` and/or a Security Hub `CfnHub`. When `cognitoAuthFailureAlert` is set it creates a CloudWatch Logs `MetricFilter` (on the account CloudTrail's log group, matching `cognito-idp` `NotAuthorizedException` events), a `qpq/security` metric, an SNS topic (`qpq-account-security-alerts`) with an email subscription per address, and a CloudWatch `Alarm` that notifies the topic.
+
+```typescript
+import { defineAccountSecurityServices } from 'quidproquo-config-aws';
+
+export default [
+  defineAccountSecurityServices({
+    enableGuardDuty: true,
+  }),
+];
+```
+
+## Signature
+
+```typescript
+function defineAccountSecurityServices(
+  options?: {
+    enableGuardDuty?: boolean;
+    enableSecurityHub?: boolean;
+    cognitoAuthFailureAlert?: AccountAuthFailureAlert;
+  },
+): AccountSecurityServicesQPQConfigSetting;
+```
+
+## Parameters
+
+### `options` — (optional)
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `enableGuardDuty` | `boolean` | `false` | Creates a GuardDuty detector (`CfnDetector`, `enable: true`). Opt-in: detectors are one-per-account+region and are often managed outside the stack (e.g. an AWS Organizations delegated admin auto-enables them, and a CloudFormation create would collide with that detector). |
+| `enableSecurityHub` | `boolean` | `false` | Creates a Security Hub hub (`CfnHub`). Opt-in: its compliance standards require AWS Config recording, which bills per configuration item and often outweighs everything else — enable knowingly. |
+| `cognitoAuthFailureAlert` | `AccountAuthFailureAlert` | – | Emails an alert when Cognito sign-in failures spike. **Requires** a [defineAccountCloudTrail](./account-cloud-trail.md) with `cloudWatchLogs` enabled — the deploy throws otherwise. See [`AccountAuthFailureAlert`](#accountauthfailurealert). |
+
+### `AccountAuthFailureAlert`
+
+```typescript
+export interface AccountAuthFailureAlert {
+  emails: string[];
+  thresholdPer5Minutes?: number;
+}
+```
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `emails` | `string[]` | (required) | Addresses subscribed to the SNS alert topic that the alarm notifies. |
+| `thresholdPer5Minutes` | `number` | `10` | Number of failed Cognito sign-ins per 5-minute window before the alarm fires. Missing data is treated as not-breaching (no sign-in attempts is not an alarm state). |
+
+## Notes
+
+- The `cognitoAuthFailureAlert` detects credential stuffing that hits Cognito directly, bypassing your APIs — these show up as `cognito-idp` `NotAuthorizedException` events in CloudTrail. Failed logins through quidproquo routes are covered separately by the per-API 401-rate alarms.
+- Because both GuardDuty and Security Hub are account singletons, they live in the account stack rather than any app's bootstrap — an app teardown must not take the account's threat detection with it.
+
+## Examples
+
+```typescript
+import { defineAccountSecurityServices, defineAccountCloudTrail } from 'quidproquo-config-aws';
+
+export default [
+  // CloudTrail with CloudWatch delivery is required for the auth-failure alarm
+  defineAccountCloudTrail('audit', {
+    cloudWatchLogs: { retentionDays: 90 },
+  }),
+
+  defineAccountSecurityServices({
+    enableGuardDuty: true,
+    enableSecurityHub: true,
+    cognitoAuthFailureAlert: {
+      emails: ['security@example.com'],
+      thresholdPer5Minutes: 25,
+    },
+  }),
+];
+```
+
+## Related
+
+- [defineAccountCloudTrail](./account-cloud-trail.md) — required (with `cloudWatchLogs`) for the Cognito auth-failure alarm's metric filter.
+- [defineAccountBudget](./account-budget.md) — cost budget & anomaly alerts, another `defineAccount*` bootstrap setting on the same account stack.
+- **AWS implementation:** `QpqAccountSecurityServicesConstruct` (GuardDuty detector, Security Hub hub, CloudWatch metric filter/alarm, SNS topic) in `quidproquo-deploy-awscdk`.

package/template/docusaurus/docs/config/config-aws/aws-alarm.md

@@ -0,0 +1,142 @@
+---
+title: defineAwsAlarm
+description: Declare a CloudWatch metric alarm on a Lambda, API Gateway, DynamoDB, or SQS metric, optionally routed to an event bus.
+---
+
+# defineAwsAlarm
+
+Declares a **CloudWatch metric alarm** for this service. You pick a namespace + metric (Lambda, API Gateway, DynamoDB, or SQS), a statistic and period, and the threshold/comparison that trips the alarm, and optionally route the alarm state to one or more [event buses](../core/event-bus.md) so it reaches a human. Use it to watch a specific resource metric that the default per-resource alarms and the service dashboard don't already cover.
+
+- **On AWS:** each declared alarm becomes an `aws_cloudwatch.Alarm` (`QpqConfigAwsAlarmConstruct` in `quidproquo-deploy-awscdk`), built entirely from the shared alarm fields, so it is namespace-agnostic. The metric is a plain `aws_cloudwatch.Metric` (namespace, metric name, statistic, period); the comparison operator maps to the matching CloudWatch `ComparisonOperator`. Each event-bus name in `onAlarm.publishToEventBus` resolves to that bus's SNS topic, and the alarm gets an `SnsAction` publishing state changes to it.
+
+```typescript
+import {
+  defineAwsAlarm,
+  AwsAlarmNamespace,
+  AwsAlarmSqsMetricName,
+  AwsAlarmStatistic,
+  AwsAlarmPeriod,
+  AwsAlarmOperator,
+} from 'quidproquo-config-aws';
+
+export default [
+  // Alert when a queue's oldest message gets too old (a stuck consumer)
+  defineAwsAlarm('orders-queue-backlog', {
+    namespace: AwsAlarmNamespace.Sqs,
+    metricName: AwsAlarmSqsMetricName.ApproximateAgeOfOldestMessage,
+    statistic: AwsAlarmStatistic.Maximum,
+    period: AwsAlarmPeriod.FiveMinutes,
+    operator: AwsAlarmOperator.GreaterThanThreshold,
+    threshold: 300,
+    datapointsToAlarm: 2,
+    evaluationPeriodsToAlarm: 3,
+    onAlarm: {
+      publishToEventBus: ['ops-alerts'],
+    },
+  }),
+];
+```
+
+## Signature
+
+```typescript
+function defineAwsAlarm(
+  name: string,
+  alarmSettings: AwsAlarmNamespaceSpecificSettings,
+  options?: QPQConfigAdvancedAwsAlarmSettings,
+): AwsAlarmQPQConfigSetting;
+```
+
+## Parameters
+
+### `name` — `string` (required)
+
+A unique name for the alarm (its `uniqueKey`). It is prefixed with application/module/environment to form the physical CloudWatch alarm name.
+
+### `alarmSettings` — namespace-specific settings (required)
+
+The alarm definition. It is a discriminated union on `namespace`: the allowed `metricName` values depend on the chosen namespace (see below). All namespaces share these base fields:
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `namespace` | `AwsAlarmNamespace` | The AWS service namespace being watched. Also selects which `metricName` enum is valid. |
+| `metricName` | namespace-specific enum | The metric to alarm on (see the per-namespace tables below). |
+| `statistic` | `AwsAlarmStatistic` | The statistic applied to the metric over each period. |
+| `period` | `AwsAlarmPeriod` | The aggregation period (in seconds). |
+| `operator` | `AwsAlarmOperator` | How `threshold` is compared to the metric value. |
+| `threshold` | `number` | The value the comparison is made against. |
+| `datapointsToAlarm` | `number` | How many datapoints within the evaluation window must breach for the alarm to fire. |
+| `evaluationPeriodsToAlarm` | `number` | The number of periods CloudWatch evaluates (the "M of N" window, with `datapointsToAlarm` as M). |
+| `onAlarm.publishToEventBus` | `string[]` | Optional. Event-bus names to publish alarm-state changes to (via each bus's SNS topic). |
+
+### `options` — `QPQConfigAdvancedAwsAlarmSettings` (optional)
+
+Advanced settings. Currently an empty interface extending the shared `QPQConfigAdvancedSettings`; reserved for future options.
+
+### `AwsAlarmNamespace` and its metric names
+
+The namespace determines which `metricName` enum you use.
+
+| Namespace | Value | Metric-name enum |
+| --- | --- | --- |
+| `Lambda` | `AWS/Lambda` | `AwsAlarmLambdaMetricName` |
+| `ApiGateway` | `AWS/ApiGateway` | `AwsAlarmApiGatewayMetricName` |
+| `DynamoDb` | `AWS/DynamoDB` | `AwsAlarmDynamoDbMetricName` |
+| `Sqs` | `AWS/SQS` | `AwsAlarmSqsMetricName` |
+
+**`AwsAlarmLambdaMetricName`:** `Invocations`, `Errors`, `DeadLetterErrors`, `Duration`, `Throttles`, `IteratorAge`, `ConcurrentExecutions`, `UnreservedConcurrentExecutions`.
+
+**`AwsAlarmApiGatewayMetricName`:** `Count`, `Latency`, `Error4XX` (`4XXError`), `Error5XX` (`5XXError`).
+
+**`AwsAlarmDynamoDbMetricName`:** `ConsumedReadCapacityUnits`, `ConsumedWriteCapacityUnits`, `ProvisionedReadCapacityUnits`, `ProvisionedWriteCapacityUnits`, `ReadThrottleEvents`, `WriteThrottleEvents`, `SuccessfulRequestLatency`, `SystemErrors`, `UserErrors`.
+
+**`AwsAlarmSqsMetricName`:** `NumberOfMessagesSent`, `NumberOfMessagesReceived`, `NumberOfMessagesDeleted`, `NumberOfMessagesReceivedButNotDeleted`, `SentMessageSize`, `ReceiveMessageSize`, `ApproximateNumberOfMessagesDelayed`, `ApproximateNumberOfMessagesVisible`, `ApproximateNumberOfMessagesNotVisible`, `ApproximateAgeOfOldestMessage`, `ApproximateNumberOfMessagesDelayedNotVisible`.
+
+### `AwsAlarmStatistic`
+
+`Minimum`, `Maximum`, `Average`, `Sum`, `SampleCount`, plus the CloudWatch extended-statistic patterns `Percentile` (`pNN.NN`), `TrimmedMean` (`tmNN.NN`), `InterquartileMean` (`iqm`), `WeightedMean` (`wmNN.NN`), `TruncatedCount` (`tcNN.NN`), and `TruncatedSum` (`tsNN.NN`).
+
+### `AwsAlarmPeriod`
+
+The period in seconds: `OneMinute` (60), `FiveMinutes` (300), `FifteenMinutes` (900).
+
+### `AwsAlarmOperator`
+
+How the metric is compared to `threshold`: `GreaterThanThreshold`, `GreaterThanOrEqualToThreshold`, `LessThanOrEqualToThreshold`, `LessThanThreshold`.
+
+## Examples
+
+```typescript
+import {
+  defineAwsAlarm,
+  AwsAlarmNamespace,
+  AwsAlarmLambdaMetricName,
+  AwsAlarmStatistic,
+  AwsAlarmPeriod,
+  AwsAlarmOperator,
+} from 'quidproquo-config-aws';
+
+export default [
+  // Alert when Lambda errors exceed 5 over two of three 1-minute periods
+  defineAwsAlarm('worker-errors', {
+    namespace: AwsAlarmNamespace.Lambda,
+    metricName: AwsAlarmLambdaMetricName.Errors,
+    statistic: AwsAlarmStatistic.Sum,
+    period: AwsAlarmPeriod.OneMinute,
+    operator: AwsAlarmOperator.GreaterThanThreshold,
+    threshold: 5,
+    datapointsToAlarm: 2,
+    evaluationPeriodsToAlarm: 3,
+    onAlarm: {
+      publishToEventBus: ['ops-alerts'],
+    },
+  }),
+];
+```
+
+## Related
+
+- [defineEventBus](../core/event-bus.md) — the bus an alarm publishes state changes to via `onAlarm.publishToEventBus`.
+- [defineEventBusQuickSubscription](./event-bus-quick-subscription.md) — attach email / webhook subscribers to that bus so alerts reach a human out-of-band.
+- [defineNotifyError](../core/notify-error.md) — the default per-resource error/throttle alarms quidproquo creates automatically.
+- [defineAwsServiceDashboard](./aws-service-dashboard.md) — a ready-made operational dashboard covering common metrics.

package/template/docusaurus/docs/config/config-aws/aws-data-store-removal-policy.md

@@ -0,0 +1,68 @@
+---
+title: defineAwsDataStoreRemovalPolicy
+description: Control whether a service's AWS data stores are retained or destroyed when their stack is torn down.
+---
+
+# defineAwsDataStoreRemovalPolicy
+
+Sets the **removal policy** for every persistent data store this service deploys — storage-drive S3 buckets, key-value-store DynamoDB tables, user-directory Cognito user pools, and graph-database Neptune clusters. It decides what happens to that data when the resource is deleted or replaced (a `cdk destroy`, a full teardown, or a change that forces resource replacement). It defaults to **retain**, so production data survives teardown; declare it as **destroy** in dev/ephemeral configs where you want a clean tear-down.
+
+- **On AWS:** a single service-wide setting read by each data-store construct in `quidproquo-deploy-awscdk` (`QpqCoreStorageDriveConstruct`, `QpqCoreKeyValueStoreConstruct`, `QpqInfCoreUserDirectoryConstruct`, `QpqCoreApiGraphDatabaseConstruct`). `destroy` maps to CDK `RemovalPolicy.DESTROY`; `retain` maps to `RemovalPolicy.RETAIN` for buckets, tables, and user pools, and to `RemovalPolicy.SNAPSHOT` for the Neptune cluster — a final snapshot preserves the graph data without leaving an orphaned live cluster running. When the setting is absent, the resolver falls back to `retain`.
+
+```typescript
+import { defineAwsDataStoreRemovalPolicy, AwsDataStoreRemovalPolicy } from 'quidproquo-config-aws';
+
+export default [
+  // Dev config: let a teardown remove the data stores
+  defineAwsDataStoreRemovalPolicy(AwsDataStoreRemovalPolicy.destroy),
+];
+```
+
+## Signature
+
+```typescript
+function defineAwsDataStoreRemovalPolicy(
+  removalPolicy: AwsDataStoreRemovalPolicy,
+): AwsDataStoreRemovalPolicyQPQConfigSetting;
+```
+
+## Parameters
+
+### `removalPolicy` — `AwsDataStoreRemovalPolicy` (required)
+
+Which policy to apply to all of the service's data stores.
+
+### `AwsDataStoreRemovalPolicy`
+
+| Value | Meaning | AWS effect |
+| --- | --- | --- |
+| `retain` | Keep the data when the resource is deleted or replaced (the default when this setting is not declared). | S3 buckets, DynamoDB tables, and Cognito user pools are **retained** (orphaned but preserved); the Neptune cluster is retained via a **final snapshot** rather than a live cluster. |
+| `destroy` | Delete the data on teardown. | All data stores map to CDK `RemovalPolicy.DESTROY` and are removed with the stack. |
+
+:::note
+This is a single, service-wide setting (its `uniqueKey` is fixed) — declaring it more than once in a config is redundant. It applies uniformly to every data store the service owns; there is no per-resource override here.
+:::
+
+## Examples
+
+```typescript
+import { defineAwsDataStoreRemovalPolicy, AwsDataStoreRemovalPolicy } from 'quidproquo-config-aws';
+
+// A shared dev config module: everything is disposable
+export const devDataPolicy = [
+  defineAwsDataStoreRemovalPolicy(AwsDataStoreRemovalPolicy.destroy),
+];
+
+// Production config: omit the setting entirely (retain is the default),
+// or state it explicitly for clarity
+export const prodDataPolicy = [
+  defineAwsDataStoreRemovalPolicy(AwsDataStoreRemovalPolicy.retain),
+];
+```
+
+## Related
+
+- [defineStorageDrive](../core/storage-drive.md) — S3 buckets governed by this policy.
+- [defineKeyValueStore](../core/key-value-store.md) — DynamoDB tables governed by this policy.
+- [defineUserDirectory](../core/user-directory.md) — Cognito user pools governed by this policy.
+- [defineGraphDatabase](../core/graph-database.md) — Neptune clusters, retained via a final snapshot under `retain`.

package/template/docusaurus/docs/config/config-aws/aws-dyanmo-override-for-kvs.md

@@ -0,0 +1,70 @@
+---
+title: defineAwsDyanmoOverrideForKvs
+description: Point a key-value store at a pre-existing DynamoDB table instead of the one quidproquo would create.
+---
+
+# defineAwsDyanmoOverrideForKvs
+
+Overrides the physical **DynamoDB table** backing a [key-value store](../core/key-value-store.md). Normally quidproquo derives the table name from the store name and application/module/environment prefix and creates the table for you. This setting instead binds the store to an **existing** DynamoDB table by name, so the deploy imports that table rather than creating a new one. Use it to adopt a table that already exists (a migration, a manually-managed table, or a table shared across systems).
+
+- **On AWS:** resolved by `getDynamoTableNameOverrride` in `quidproquo-config-aws` and consumed by `QpqCoreKeyValueStoreConstruct` in `quidproquo-deploy-awscdk`. When an override matches the store, the construct calls `aws_dynamodb.Table.fromTableName(...)` to import the named table instead of provisioning one, and the store's action processors read and write that table. Because the table is imported (not owned), its schema, keys, indexes, and removal policy are managed outside this config.
+
+:::note Spelling
+The exported name is spelled **`defineAwsDyanmoOverrideForKvs`** ("Dyanmo", not "Dynamo") in the source, and that is the name you import.
+:::
+
+```typescript
+import { defineAwsDyanmoOverrideForKvs } from 'quidproquo-config-aws';
+
+export default [
+  // Back the 'sessions' key-value store with a pre-existing DynamoDB table
+  defineAwsDyanmoOverrideForKvs('sessions-table-override', { keyValueStoreName: 'sessions' }, 'legacy-sessions-prod'),
+];
+```
+
+## Signature
+
+```typescript
+function defineAwsDyanmoOverrideForKvs(
+  name: string,
+  kvsStore: CustomFullyQualifiedResource<'keyValueStoreName'>,
+  dynamoTableName: string,
+  options?: QPQConfigAdvancedAwsDyanmoOverrideForKvsSettings,
+): AwsDyanmoOverrideForKvsQPQConfigSetting;
+```
+
+## Parameters
+
+### `name` — `string` (required)
+
+A unique name for this override setting (its `uniqueKey` within the config). Purely an identifier for the override entry — it is not the store or table name.
+
+### `kvsStore` — `CustomFullyQualifiedResource<'keyValueStoreName'>` (required)
+
+Identifies which key-value store to override. At minimum provide `{ keyValueStoreName: '<store>' }`; the remaining parts (`module`, `application`, `environment`, `feature`) are optional and default to the current service, letting you target a store owned by another module. It is normalised to a fully-qualified resource and matched against the store at deploy time.
+
+### `dynamoTableName` — `string` (required)
+
+The name of the existing DynamoDB table to bind the store to. This exact table name is imported via `Table.fromTableName` — no application/environment prefixing is applied, so pass the real, deployed table name.
+
+### `options` — `QPQConfigAdvancedAwsDyanmoOverrideForKvsSettings` (optional)
+
+Advanced settings. Currently an empty interface that extends the shared `QPQConfigAdvancedSettings` (e.g. `deprecated`), reserved for future options.
+
+## Examples
+
+```typescript
+import { defineKeyValueStore } from 'quidproquo-core';
+import { defineAwsDyanmoOverrideForKvs } from 'quidproquo-config-aws';
+
+export default [
+  defineKeyValueStore('sessions', 'sessionId'),
+
+  // Instead of creating a fresh table, reuse a table created outside quidproquo
+  defineAwsDyanmoOverrideForKvs('sessions-override', { keyValueStoreName: 'sessions' }, 'legacy-sessions-prod'),
+];
+```
+
+## Related
+
+- [defineKeyValueStore](../core/key-value-store.md) — the store whose backing table this setting overrides.

package/template/docusaurus/docs/config/config-aws/aws-kms-key.md

@@ -0,0 +1,100 @@
+---
+title: defineAwsKmsKey
+description: Register a customer-managed KMS key to encrypt a storage drive or key-value store.
+---
+
+# defineAwsKmsKey
+
+Registers an existing **customer-managed KMS key** (by ARN) and binds it to a specific [storage drive](../core/storage-drive.md) or [key-value store](../core/key-value-store.md). It is the AWS-side companion to the `encryption: true` flag on those resources: when a drive or store opts into customer-managed encryption, this setting tells the deploy which KMS key to use. Without a matching key registered here, the `encryption` flag has no key to reference.
+
+- **On AWS:** looked up by `getAwsKmsKeyForStorageDrive` / `getAwsKmsKeyForKeyValueStore` in `quidproquo-config-aws`, keyed by target type + resource name + owning module. `QpqCoreStorageDriveConstruct` and `QpqCoreKeyValueStoreConstruct` in `quidproquo-deploy-awscdk` resolve the key with `aws_kms.Key.fromKeyArn(...)` and set it as the bucket / table `encryptionKey`. The deploy also grants the service's roles the KMS actions (`kms:Decrypt`, `kms:GenerateDataKey*`, `kms:Encrypt`, `kms:ReEncrypt*`, `kms:DescribeKey`) needed to use the key. The key itself is referenced, not created — you provision and manage the key (and its key policy) separately.
+
+```typescript
+import { defineAwsKmsKey, AwsKmsKeyTargetType } from 'quidproquo-config-aws';
+
+export default [
+  defineAwsKmsKey(
+    'uploads-key',
+    'arn:aws:kms:us-east-1:123456789012:key/abcd-1234-...',
+    AwsKmsKeyTargetType.storageDrive,
+    { name: 'user-uploads', module: 'my-service' },
+  ),
+];
+```
+
+## Signature
+
+```typescript
+function defineAwsKmsKey(
+  keyname: string,
+  arn: string,
+  type: AwsKmsKeyTargetType,
+  owner: AwsKmsKeyOwner,
+): AwsKmsKeyQPQConfigSetting;
+```
+
+## Parameters
+
+### `keyname` — `string` (required)
+
+A unique name for this key registration (its `uniqueKey` within the config). An identifier for the entry — not the AWS key alias.
+
+### `arn` — `string` (required)
+
+The ARN of the existing customer-managed KMS key. This exact ARN is imported via `Key.fromKeyArn`.
+
+### `type` — `AwsKmsKeyTargetType` (required)
+
+Which kind of data store this key encrypts. The lookup matches on this together with the owner, so a store only picks up a key registered for its own resource type.
+
+| Value | Encrypts |
+| --- | --- |
+| `storageDrive` | A [storage drive](../core/storage-drive.md) (S3 bucket) with `encryption: true`. |
+| `keyValueStore` | A [key-value store](../core/key-value-store.md) (DynamoDB table) with `encryption: true`. |
+
+### `owner` — `AwsKmsKeyOwner` (required)
+
+Identifies the resource the key belongs to. Both fields are matched against the target store at deploy time.
+
+```typescript
+type AwsKmsKeyOwner = {
+  name: string;    // the storage-drive / key-value-store name
+  module: string;  // the module that owns that resource
+};
+```
+
+- **`name`** — the storage-drive or key-value-store name (matches the value passed to `defineStorageDrive` / `defineKeyValueStore`).
+- **`module`** — the module that owns that resource. For a store owned by the current service this is the service's own module name; set it to another module to key a foreign resource.
+
+## Examples
+
+```typescript
+import { defineKeyValueStore } from 'quidproquo-core';
+import { defineStorageDrive } from 'quidproquo-core';
+import { defineAwsKmsKey, AwsKmsKeyTargetType } from 'quidproquo-config-aws';
+
+export default [
+  // A drive and a store that both request customer-managed encryption
+  defineStorageDrive('user-uploads', { encryption: true }),
+  defineKeyValueStore('billing', 'invoiceId', { encryption: true }),
+
+  // Bind each to its KMS key
+  defineAwsKmsKey(
+    'uploads-key',
+    'arn:aws:kms:us-east-1:123456789012:key/uploads-...',
+    AwsKmsKeyTargetType.storageDrive,
+    { name: 'user-uploads', module: 'my-service' },
+  ),
+  defineAwsKmsKey(
+    'billing-key',
+    'arn:aws:kms:us-east-1:123456789012:key/billing-...',
+    AwsKmsKeyTargetType.keyValueStore,
+    { name: 'billing', module: 'my-service' },
+  ),
+];
+```
+
+## Related
+
+- [defineStorageDrive](../core/storage-drive.md) — its `encryption` flag selects a key registered here.
+- [defineKeyValueStore](../core/key-value-store.md) — its `encryption` flag selects a key registered here.