create-qpq-app 0.1.5

package/template/docusaurus/docs/config/core/user-directory.md

@@ -0,0 +1,189 @@
+---
+title: defineUserDirectory
+description: Define a user directory — a named authentication & user store (an AWS Cognito user pool) that the User Directory actions authenticate and manage users against.
+---
+
+# defineUserDirectory
+
+Defines a **user directory**: a named store of user accounts with authentication, passwords, MFA, and profile attributes. Stories never talk to Cognito (or any identity provider) directly — they create users, sign them in, respond to auth challenges, and read/write attributes by drive name using the [User Directory action requesters](../../actions/core/user-directory/ask-user-directory-authenticate-user.md), and the runtime maps the directory to real identity infrastructure.
+
+- **On AWS:** deploys an AWS Cognito **user pool** and an app **client** (`QpqInfCoreUserDirectoryConstruct` in `quidproquo-deploy-awscdk`). The pool enforces a fixed password policy (min 12 chars; requires lower- and upper-case, digits, and symbols), makes `email` a required, mutable, auto-verified standard attribute, and configures MFA from the `mfa` option. The app client is generated with a secret and enables the `ADMIN_USER_PASSWORD_AUTH` flow (and `CUSTOM_AUTH` when `customAuthRuntime` is set). The pool is **retained** on stack teardown by default (user accounts are unrecoverable) unless the service opts into destroy via `defineAwsDataStoreRemovalPolicy`. See [On AWS](#on-aws) for the full breakdown.
+
+```typescript
+import { defineUserDirectory } from 'quidproquo-core';
+
+export default [
+  defineUserDirectory('app-users'),
+];
+```
+
+## Signature
+
+```typescript
+function defineUserDirectory(
+  name: string,
+  options?: QPQConfigAdvancedUserDirectorySettings,
+): UserDirectoryQPQConfigSetting;
+```
+
+## Parameters
+
+### `name` — `string` (required)
+
+The name of the directory. This is the name you pass as the `userDirectoryName` argument to every User Directory action (e.g. `askUserDirectoryAuthenticateUser('app-users', ...)`). It is also the directory's `uniqueKey` within the config, and on AWS it is used to derive the physical user pool name (prefixed with application/module/environment, so the same config deploys to multiple environments without collisions).
+
+### `options` — `QPQConfigAdvancedUserDirectorySettings` (optional)
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `phoneRequired` | `boolean` | `false` | Makes `phoneNumber` a required (and auto-verified) standard attribute on the pool in addition to `email`. |
+| `selfSignUpEnabled` | `boolean` | `false` | Allows users to sign themselves up (Cognito `selfSignUpEnabled`). When `false`, accounts must be created administratively via [askUserDirectoryCreateUser](../../actions/core/user-directory/ask-user-directory-create-user.md). |
+| `emailTemplates` | `EmailTemplates` | – | Story functions that customise the emails Cognito sends (verification, password reset). See [Email templates](#email-templates). |
+| `owner` | `CrossModuleOwner<'userDirectoryName'>` | – | Declares that this directory is owned by **another** module/service. Use this to authenticate against / manage a pool deployed elsewhere: the deploy grants this service IAM access to the foreign pool instead of creating a new one. `{ module, application, feature, environment, userDirectoryName }` — all optional; unset parts default to the current service. |
+| `dnsRecord` | `AuthDirectoryDnsRecord` | – | Serves the pool's hosted UI / OAuth endpoints from a custom domain. See [DNS record](#dns-record). |
+| `customAuthRuntime` | `CustomAuthRuntime` | – | Enables Cognito's `CUSTOM_AUTH` flow, wiring story functions to the define/create/verify auth-challenge Lambda triggers. See [Custom auth runtime](#custom-auth-runtime). |
+| `mfa` | `UserDirectoryMfaSettings` | `{ mode: off, secondFactors: [totp] }` | Multi-factor authentication configuration. See [MFA](#mfa). |
+| `deprecated` | `boolean` | `false` | Inherited from `QPQConfigAdvancedSettings`; marks the setting as deprecated. |
+
+## MFA
+
+```typescript
+export enum UserDirectoryMfaMode {
+  off = 'off',
+  optional = 'optional',
+  required = 'required',
+}
+
+export enum UserDirectoryMfaSecondFactor {
+  totp = 'totp',
+}
+
+export interface UserDirectoryMfaSettings {
+  mode: UserDirectoryMfaMode;
+  secondFactors?: UserDirectoryMfaSecondFactor[];
+}
+```
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `mode` | `UserDirectoryMfaMode` | `off` | `off` disables MFA, `optional` lets users enrol, `required` forces every user through MFA. On AWS this maps to Cognito's `Mfa.OFF` / `Mfa.OPTIONAL` / `Mfa.REQUIRED`. |
+| `secondFactors` | `UserDirectoryMfaSecondFactor[]` | `[totp]` | Enabled second factors. Currently only `totp` (authenticator-app / software token) is supported; SMS is not yet available. Defaults to `[totp]` when omitted or empty. |
+
+When MFA is `required` (or `optional` and the user has enrolled), authentication surfaces one of the MFA auth challenges — see [askUserDirectoryAuthenticateUser](../../actions/core/user-directory/ask-user-directory-authenticate-user.md) and [askUserDirectoryAssociateSoftwareToken](../../actions/core/user-directory/ask-user-directory-associate-software-token.md).
+
+## Email templates
+
+```typescript
+export interface EmailTemplates {
+  verifyEmail?: QpqFunctionRuntime;
+  resetPassword?: QpqFunctionRuntime;
+  resetPasswordAdmin?: QpqFunctionRuntime;
+}
+```
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `verifyEmail` | `QpqFunctionRuntime` | Story that renders the email-address verification message. |
+| `resetPassword` | `QpqFunctionRuntime` | Story that renders the user-initiated password-reset (forgot-password) message. |
+| `resetPasswordAdmin` | `QpqFunctionRuntime` | Story that renders the admin-initiated password-reset message. |
+
+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'`. Providing **any** of these installs a Cognito `CUSTOM_MESSAGE` Lambda trigger on the pool.
+
+## DNS record
+
+```typescript
+export type AuthDirectoryDnsRecord = {
+  subdomain: string;
+  rootDomain: string;
+};
+```
+
+Attaches a Cognito custom domain (`subdomain.rootDomain`) to the pool and creates the matching Route 53 alias record. Because Cognito custom domains run on CloudFront, the ACM certificate is looked up in `us-east-1`.
+
+## Custom auth runtime
+
+```typescript
+export interface CustomAuthRuntime {
+  defineAuthChallenge: QpqFunctionRuntime;
+  createAuthChallenge?: QpqFunctionRuntime;
+  verifyAuthChallenge?: QpqFunctionRuntime;
+}
+```
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `defineAuthChallenge` | `QpqFunctionRuntime` | Required. Story wired to Cognito's `DEFINE_AUTH_CHALLENGE` trigger — drives the custom challenge state machine. |
+| `createAuthChallenge` | `QpqFunctionRuntime` | Optional. Story wired to `CREATE_AUTH_CHALLENGE` — produces the challenge presented to the user. |
+| `verifyAuthChallenge` | `QpqFunctionRuntime` | Optional. Story wired to `VERIFY_AUTH_CHALLENGE_RESPONSE` — validates the user's answer. |
+
+Setting `customAuthRuntime` enables the app client's `CUSTOM_AUTH` flow. Authenticate with the `isCustom` flag set (see [askUserDirectoryAuthenticateUser](../../actions/core/user-directory/ask-user-directory-authenticate-user.md)) and answer with the `CUSTOM_CHALLENGE` variant of [askUserDirectoryRespondToAuthChallenge](../../actions/core/user-directory/ask-user-directory-respond-to-auth-challenge.md).
+
+## On AWS
+
+The `QpqInfCoreUserDirectoryConstruct` deploys:
+
+- **A Cognito user pool** with:
+  - **Password policy** (fixed): minimum length 12; requires lowercase, uppercase, digits, and symbols.
+  - **Standard attributes**: `email` (required, mutable) and `phoneNumber` (mutable; required only when `phoneRequired` is `true`).
+  - **Auto-verification**: `email` (and `phone` when `phoneRequired`).
+  - **MFA**: mode and second factors derived from the `mfa` option (TOTP / software token).
+  - **Self sign-up**: from `selfSignUpEnabled`.
+  - **Removal policy**: retained by default (with deletion protection); destroyed only when the service sets `defineAwsDataStoreRemovalPolicy(destroy)`.
+- **Lambda triggers** (only when configured):
+  - `CUSTOM_MESSAGE` — when any `emailTemplates` handler is set.
+  - `DEFINE_AUTH_CHALLENGE`, and optionally `CREATE_AUTH_CHALLENGE` / `VERIFY_AUTH_CHALLENGE_RESPONSE` — when `customAuthRuntime` is set.
+- **An app client** with a generated secret, `ADMIN_USER_PASSWORD_AUTH` enabled, and `CUSTOM_AUTH` enabled when `customAuthRuntime` is set.
+- **A custom domain + Route 53 alias** — when `dnsRecord` is set (certificate from `us-east-1`).
+
+Services that own a directory get IAM for the admin Cognito operations the actions use (create user, initiate/respond to auth, list/get users, update attributes, set password, describe pool/client, etc.). Services that only reference a **foreign** directory (via `owner`) get no Cognito IAM — token validation runs against the pool's public JWKs over HTTPS and needs none.
+
+## Examples
+
+```typescript
+import {
+  defineUserDirectory,
+  UserDirectoryMfaMode,
+  UserDirectoryMfaSecondFactor,
+} from 'quidproquo-core';
+
+export default [
+  // Simple admin-managed directory
+  defineUserDirectory('app-users'),
+
+  // Self sign-up with optional TOTP MFA and a custom verification email
+  defineUserDirectory('customers', {
+    selfSignUpEnabled: true,
+    mfa: {
+      mode: UserDirectoryMfaMode.optional,
+      secondFactors: [UserDirectoryMfaSecondFactor.totp],
+    },
+    emailTemplates: {
+      verifyEmail: '/entry/auth/emails::renderVerifyEmail',
+      resetPassword: '/entry/auth/emails::renderResetPassword',
+    },
+  }),
+
+  // Required MFA served from a custom domain
+  defineUserDirectory('staff', {
+    mfa: { mode: UserDirectoryMfaMode.required },
+    dnsRecord: { subdomain: 'auth', rootDomain: 'example.com' },
+  }),
+
+  // Authenticate against a directory owned by another service
+  defineUserDirectory('shared-identity', {
+    owner: { module: 'identity-service' },
+  }),
+];
+```
+
+## Related
+
+- **Authentication:** [askUserDirectoryAuthenticateUser](../../actions/core/user-directory/ask-user-directory-authenticate-user.md), [askUserDirectoryRespondToAuthChallenge](../../actions/core/user-directory/ask-user-directory-respond-to-auth-challenge.md), [askUserDirectoryRefreshToken](../../actions/core/user-directory/ask-user-directory-refresh-token.md).
+- **Account management:** [askUserDirectoryCreateUser](../../actions/core/user-directory/ask-user-directory-create-user.md), [askUserDirectoryGetUsers](../../actions/core/user-directory/ask-user-directory-get-users.md), [askUserDirectorySetUserAttributes](../../actions/core/user-directory/ask-user-directory-set-user-attributes.md).
+- **Passwords:** [askUserDirectoryChangePassword](../../actions/core/user-directory/ask-user-directory-change-password.md), [askUserDirectoryForgotPassword](../../actions/core/user-directory/ask-user-directory-forgot-password.md), [askUserDirectorySetPassword](../../actions/core/user-directory/ask-user-directory-set-password.md).
+- **MFA:** [askUserDirectoryAssociateSoftwareToken](../../actions/core/user-directory/ask-user-directory-associate-software-token.md).
+- **Tokens:** [askUserDirectoryReadAccessToken](../../actions/core/user-directory/ask-user-directory-read-access-token.md), [askUserDirectoryDecodeAccessToken](../../actions/core/user-directory/ask-user-directory-decode-access-token.md).
+- **All User Directory actions:** see the [User Directory actions](../../actions/core/user-directory/ask-user-directory-authenticate-user.md) group.
+- **Turn-key auth:** [defineAuthSystem](../webserver/auth-system.md) (quidproquo-webserver) creates a user directory and the login / refresh / password-recovery HTTP routes in one call.
+- **AWS tuning:** [defineAwsDataStoreRemovalPolicy](../config-aws/aws-data-store-removal-policy.md) — retain vs destroy the Cognito user pool on teardown.
+- **Admin dashboard:** [defineAdminUserDirectory](../features/admin-user-directory.md) (quidproquo-features) wraps this to declare the `qpq-admin` directory the admin dashboard authenticates against.

package/template/docusaurus/docs/config/core/virtual-network.md

@@ -0,0 +1,60 @@
+---
+title: defineVirtualNetwork
+description: Define a virtual network — a private, isolated network (a VPC on AWS) that services and in-network data stores run inside.
+---
+
+# defineVirtualNetwork
+
+Defines a **virtual network**: a named, private network boundary that a service's compute and in-network data stores run inside. Use it when a service needs network isolation or must reach resources that live only inside a VPC (for example a Neptune graph database). Declaring the network here is the core, platform-agnostic part; the concrete networking knobs (availability zones, NAT gateways, VPC endpoints, flow logs) are configured in the AWS config layer.
+
+- **On AWS:** deploys a **VPC** plus a **workload security group** that every Lambda placed in the network carries (`BootstrapQpqCoreVirtualNetworkConstruct` in `quidproquo-deploy-awscdk`). The security group allows all outbound traffic and no inbound — membership in the group, not mere VPC residency, is the trust boundary that in-VPC data stores allow ingress from. Depending on the AWS-side settings it also adds S3 and DynamoDB gateway endpoints, optional interface endpoints, and VPC flow logs to CloudWatch. AWS-specific tuning (max AZs, NAT gateway count, endpoints, flow-log retention/traffic type) comes from the AWS virtual-network settings in `quidproquo-config-aws`, not from this core define.
+
+```typescript
+import { defineVirtualNetwork } from 'quidproquo-core';
+
+export default [
+  defineVirtualNetwork('private-net'),
+];
+```
+
+## Signature
+
+```typescript
+function defineVirtualNetwork(
+  name: string,
+  options?: QPQConfigAdvancedVirtualNetworkSettings,
+): VirtualNetworkQPQConfigSetting;
+```
+
+## Parameters
+
+### `name` — `string` (required)
+
+The name of the virtual network. This is the network's `uniqueKey`, the name other config (and the AWS networking settings) reference it by, and on AWS it derives the physical VPC name and the workload security group name.
+
+### `options` — `QPQConfigAdvancedVirtualNetworkSettings` (optional)
+
+`QPQConfigAdvancedVirtualNetworkSettings` currently adds no fields of its own beyond the shared base:
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `deprecated` | `boolean` | `false` | Marks the setting as deprecated in the config. |
+
+The networking parameters themselves — number of availability zones, NAT gateways, gateway/interface VPC endpoints, and flow-log configuration — are set through the AWS virtual-network settings in `quidproquo-config-aws` (resolved at deploy time by name), keeping this core define provider-agnostic.
+
+## Examples
+
+```typescript
+import { defineVirtualNetwork } from 'quidproquo-core';
+
+export default [
+  // A private network a graph database (and its clients) can run inside
+  defineVirtualNetwork('data-net'),
+];
+```
+
+## Related
+
+- [defineGraphDatabase](./graph-database.md) — an in-network data store that runs inside a virtual network and trusts its workload security group.
+- [defineAwsVirtualNetworkSettings](../config-aws/aws-virtual-network-settings.md) — the AWS-specific VPC tuning (AZs, NAT, endpoints, flow logs) layered onto this core network.
+- **AWS implementation:** `BootstrapQpqCoreVirtualNetworkConstruct` (VPC, workload security group, endpoints, flow logs) in `quidproquo-deploy-awscdk`; AWS networking settings in `quidproquo-config-aws`.

package/template/docusaurus/docs/config/features/_category_.json

@@ -0,0 +1 @@
+{ "label": "quidproquo-features", "position": 6, "link": { "type": "generated-index", "description": "Config settings from quidproquo-features — ready-made feature modules (event documents, AI chat, admin) you compose into a service." } }

package/template/docusaurus/docs/config/features/admin-session-event-doc.md

@@ -0,0 +1,47 @@
+---
+title: defineAdminSessionEventDoc
+description: Declare the event document that records one audited session per admin dashboard login.
+---
+
+# defineAdminSessionEventDoc
+
+Declares the **admin session event document** — the audit record behind the admin dashboard. It creates one event doc per admin login, appending every user-intent event for that session so operator activity in the dashboard is fully auditable.
+
+It is built on the quidproquo **eventDoc** feature (`defineEventDoc`): an event document is an append-only, per-instance record backed by storage, routes, and a WebSocket feed. This define fixes that eventDoc's store name, type, base path, and auth directory to the admin conventions, so you don't configure them yourself.
+
+`defineAdminSessionEventDoc` returns a `QPQConfig` array. It is spread in automatically by [defineAdminSettings](./admin-settings.md), so you rarely call it directly — but it is exported for services that assemble the admin feature piece by piece.
+
+- **On AWS:** it deploys whatever the underlying eventDoc feature deploys (storage, routes, and WebSocket infrastructure for the session document). The document and its routes are scoped to the log service and never materialise elsewhere.
+
+```typescript
+import { defineAdminSessionEventDoc } from 'quidproquo-features';
+
+export default [
+  // Audit admin sessions in the 'log' service.
+  ...defineAdminSessionEventDoc('log'),
+];
+```
+
+## Signature
+
+```typescript
+function defineAdminSessionEventDoc(
+  logServiceName: string,
+): QPQConfig;
+```
+
+## Parameters
+
+### `logServiceName` — `string` (required)
+
+The name of the service that owns the admin session document. The event doc is wrapped in `defineServiceSettings` keyed on this name, so — like the other admin-only resources declared by [defineAdminSettings](./admin-settings.md) — it only flattens into deployable resources when the deploying service matches. Pass the same `logServiceName` you give [defineAdminSettings](./admin-settings.md).
+
+## Notes
+
+- The event document is created with fixed conventions: store name `qpq-admin-sessions`, doc type `adminSession`, base path `/admin/session`, and `routeAuthSettings.userDirectoryName` set to the admin directory (`qpq-admin`) so only authenticated admins can read or append to it. See [defineAdminUserDirectory](./admin-user-directory.md).
+- Because [defineAdminSettings](./admin-settings.md) already spreads this in, declaring both would register the document twice — use one or the other.
+
+## Related
+
+- [defineAdminSettings](./admin-settings.md) — spreads this define in as part of the admin feature.
+- [defineAdminUserDirectory](./admin-user-directory.md) — the directory the session document is authenticated against.

package/template/docusaurus/docs/config/features/admin-settings.md

@@ -0,0 +1,106 @@
+---
+title: defineAdminSettings
+description: Wire up the quidproquo admin feature — the log-inspection dashboard and its API, WebSocket sync, storage, and alarms — in one call.
+---
+
+# defineAdminSettings
+
+Wires up the **admin feature**: the log-service backend that powers the quidproquo admin dashboard. In a single call it declares the storage, key-value stores, HTTP API routes, WebSocket sync pipeline, error alarms, and globals that let operators authenticate, browse services, and inspect the structured logs (correlations) every quidproquo runtime writes.
+
+`defineAdminSettings` returns a `QPQConfig` — an array of config settings you spread into a service's config. Most of the resources it declares are **owned by the log service** (the `logServiceName` you pass): they only fully materialise when that service deploys, and appear as foreign references everywhere else. This lets many services publish logs into one shared admin service.
+
+- **On AWS:** this define does not deploy infrastructure of its own — it composes other `define*` settings ([defineStorageDrive](../core/storage-drive.md), [defineKeyValueStore](../core/key-value-store.md), [defineQueue](../core/queue.md), [defineEventBus](../core/event-bus.md), routes, and a WebSocket queue), and each of those deploys its usual AWS resources. The reads served over its routes are backed by the [askAdminGetLogs](../../actions/webserver/admin/ask-admin-get-logs.md) family of actions.
+
+```typescript
+import { defineAdminSettings } from 'quidproquo-features';
+import { defineAdminUserDirectory } from 'quidproquo-features';
+
+export default [
+  // The admins' auth directory (see defineAdminUserDirectory)
+  ...defineAdminUserDirectory({ owner: { module: 'log' } }),
+
+  // The admin dashboard backend, owned by the 'log' service
+  ...defineAdminSettings('log', 'example.com', {
+    logRetentionDays: 90,
+    services: ['api', 'workers', 'web'],
+  }),
+];
+```
+
+## Signature
+
+```typescript
+function defineAdminSettings(
+  logServiceName: string,
+  rootDomain: string,
+  advancedSettings?: QPQConfigAdvancedLogSettings,
+): QPQConfig;
+```
+
+## Parameters
+
+### `logServiceName` — `string` (required)
+
+The name of the service that **owns** the admin resources. Owner-stamped settings (the log storage drives, the admin WebSocket event bus/queues, the key-value stores, the auth and log routes, the alarm pipeline, and the [session event doc](./admin-session-event-doc.md)) only flatten into deployable resources when the deploying service matches this name; elsewhere they resolve as foreign references. Owner resolution runs at IAM-scoping time.
+
+### `rootDomain` — `string` (required)
+
+The root domain the admin service is hosted on. Used to stand up the admin WebSocket endpoint (`defineWebSocketQueue`) under the `qpqadmin` subdomain of this domain.
+
+### `advancedSettings` — `QPQConfigAdvancedLogSettings` (optional)
+
+```typescript
+export interface QPQConfigAdvancedLogSettings extends QPQConfigAdvancedSettings {
+  logRetentionDays?: number;
+  coldStorageAfterDays?: number;
+  claudeAiApiKeySecretName?: string;
+  services?: string[];
+}
+```
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `logRetentionDays` | `number` | – (no expiry) | How many days to keep the raw log objects on the logs storage drive before they are deleted. When unset, logs never expire. If `coldStorageAfterDays` is set, the effective retention is padded so that it is at least `coldStorageAfterDays + 180` days — logs always outlive the cold-storage transition window. |
+| `coldStorageAfterDays` | `number` | – (no transition) | When greater than 0, adds a lifecycle rule transitioning log objects to the `DEEP_COLD_STORAGE` tier after this many days, to cut storage cost for old logs. |
+| `claudeAiApiKeySecretName` | `string` | `''` | Name of the secret holding a Claude AI API key, exposed to the admin service as the `claudeAi-api-key` global. Enables the admin dashboard's log-chat feature (asking questions about a log with Claude). |
+| `services` | `string[]` | `[]` | The list of service names the admin dashboard should surface, exposed as the `qpq-serviceNames` global. Returned by the `/admin/services` route. |
+| `deprecated` | `boolean` | `false` | Inherited from `QPQConfigAdvancedSettings`; marks the log storage drives and key-value stores as deprecated. |
+
+## What it declares
+
+`defineAdminSettings` returns a `QPQConfig` array composed of:
+
+- **Log storage** — a `QPQ_LOGS_STORAGE_DRIVE_NAME` storage drive (with an `onCreate` handler and the retention / cold-storage lifecycle rules), plus a `QPQ_LOG_REPORTS_STORAGE_DRIVE_NAME` drive (30-day retention) for generated reports.
+- **Log indexes** — key-value stores for correlations (indexed by `runtimeType` and `fromCorrelation`, both sorted by `startedAt`, with a `ttl` attribute), log messages, and a log list.
+- **Auth routes** — `POST /login`, `POST /refreshToken`, `POST /challenge`, authenticated against the [admin user directory](./admin-user-directory.md).
+- **Log routes** — `GET /admin/services`, `POST /log/list`, `GET /log/{correlationId}`, its `/toggle`, `/children`, `/hierarchies`, `/downloadurl`, the log-log list, and the `/log/chat` message endpoints — all (except the service list) requiring an admin token.
+- **WebSocket sync** — an admin event bus (`qpq-admin-wsq`), a `defineWebSocketQueue`, and queues that fan out client messages (config sync, mark-log-checked, refresh-metadata) using `WebsocketAdminClientMessageEventType`.
+- **Alarms** — a `defineNotifyError` publishing to an `admin-notifier` event bus, with a queue handling its Error / Timeout / Throttle events.
+- **Globals** — `qpq-serviceNames`, `qpq-log-retention-days`, and `claudeAi-api-key`.
+- **Audit sessions** — spreads in [defineAdminSessionEventDoc](./admin-session-event-doc.md) for the admin UI's per-login session document.
+
+## Examples
+
+```typescript
+import { defineAdminSettings, defineAdminUserDirectory } from 'quidproquo-features';
+
+export default [
+  ...defineAdminUserDirectory({ owner: { module: 'log' } }),
+
+  // Retain logs 30 days, move to deep cold storage after 7,
+  // enable the Claude log-chat feature.
+  ...defineAdminSettings('log', 'example.com', {
+    logRetentionDays: 30,
+    coldStorageAfterDays: 7,
+    claudeAiApiKeySecretName: 'claude-api-key',
+    services: ['api', 'workers'],
+  }),
+];
+```
+
+## Related
+
+- [defineAdminUserDirectory](./admin-user-directory.md) — the directory admins authenticate against; declare it alongside these settings.
+- [defineAdminSessionEventDoc](./admin-session-event-doc.md) — the per-login admin session document, spread in by this define.
+- [askAdminGetLogs](../../actions/webserver/admin/ask-admin-get-logs.md), [askAdminGetLog](../../actions/webserver/admin/ask-admin-get-log.md), [askAdminGetLogMetadata](../../actions/webserver/admin/ask-admin-get-log-metadata.md) — the actions the admin log routes are built from.
+- [defineStorageDrive](../core/storage-drive.md), [defineKeyValueStore](../core/key-value-store.md), [defineQueue](../core/queue.md), [defineEventBus](../core/event-bus.md) — the core settings this feature composes.

package/template/docusaurus/docs/config/features/admin-user-directory.md

@@ -0,0 +1,57 @@
+---
+title: defineAdminUserDirectory
+description: Declare the user directory admins authenticate against for the quidproquo admin dashboard.
+---
+
+# defineAdminUserDirectory
+
+Declares the **admin user directory** — the authentication store the quidproquo admin dashboard signs operators in against. It is a thin, opinionated wrapper over the core [defineUserDirectory](../core/user-directory.md): it always registers a directory under the fixed resource name `qpq-admin`, which the [admin settings](./admin-settings.md) routes reference as their `userDirectoryName`.
+
+`defineAdminUserDirectory` returns a `QPQConfig` array. Declare it alongside [defineAdminSettings](./admin-settings.md) so the admin auth routes (`/login`, `/refreshToken`, `/challenge`) have a directory to validate tokens against.
+
+- **On AWS:** because it delegates to [defineUserDirectory](../core/user-directory.md), it deploys a Cognito user pool and app client (or, when `owner` points at another module, a foreign reference to a pool deployed there). See [defineUserDirectory](../core/user-directory.md#on-aws) for the full breakdown.
+
+```typescript
+import { defineAdminUserDirectory } from 'quidproquo-features';
+
+export default [
+  // The admin pool is owned by the 'log' service, alongside the admin settings.
+  ...defineAdminUserDirectory({ owner: { module: 'log' } }),
+];
+```
+
+## Signature
+
+```typescript
+function defineAdminUserDirectory(
+  options?: QPQConfigAdvancedAdminUserDirectorySettings,
+): QPQConfig;
+```
+
+## Parameters
+
+### `options` — `QPQConfigAdvancedAdminUserDirectorySettings` (optional)
+
+```typescript
+type QPQConfigAdvancedAdminUserDirectorySettings =
+  Required<Pick<QPQConfigAdvancedUserDirectorySettings, 'owner'>>;
+```
+
+The options are narrowed from [`QPQConfigAdvancedUserDirectorySettings`](../core/user-directory.md#options--qpqconfigadvanceduserdirectorysettings-optional) to a single **required** property: `owner`. When you pass options, you must supply `owner`.
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `owner` | `CrossModuleOwner<'userDirectoryName'>` | – | Declares which module/service owns the `qpq-admin` pool. Pass the module that hosts your admin settings (the `logServiceName` you give [defineAdminSettings](./admin-settings.md)) so the pool is deployed there and every other service references it as a foreign directory rather than creating its own. `{ module, application, feature, environment, userDirectoryName }` — all parts optional, unset parts default to the current service. |
+
+Omit `options` entirely to deploy the `qpq-admin` directory as owned by the current service.
+
+## Notes
+
+- The directory is always named `qpq-admin`. That name is what the admin auth and log routes declared by [defineAdminSettings](./admin-settings.md) pass as their `routeAuthSettings.userDirectoryName`, and what the [admin session event doc](./admin-session-event-doc.md) authenticates against.
+- All other user-directory options (MFA, self-sign-up, email templates, custom auth) are intentionally not exposed here — the admin directory uses the core defaults.
+
+## Related
+
+- [defineUserDirectory](../core/user-directory.md) — the core directory this wraps; see it for the deployed infrastructure and the full option set.
+- [defineAdminSettings](./admin-settings.md) — declares the admin routes that authenticate against this directory.
+- [defineAdminSessionEventDoc](./admin-session-event-doc.md) — the admin session document, also scoped to this directory.

package/template/docusaurus/docs/config/features/event-doc-ai.md

@@ -0,0 +1,104 @@
+---
+title: defineEventDocAi
+description: Add an AI chat experience to an eventDoc collection — per-document chats, streamed replies, tools, and the websocket handlers that serve them.
+---
+
+# defineEventDocAi
+
+Declares an **AI chat feature** attached to an [eventDoc](./event-doc.md) collection. It is the AI sibling of `defineEventDoc`: every chat is scoped to a single document in the collection, its messages are persisted, and the assistant's reply streams back to the browser token by token over a websocket.
+
+`defineEventDocAi` returns an array of QPQ config settings, so spread it into your service config alongside the collection's own `defineEventDoc*` settings. In one call it:
+
+- provisions a **storage drive** for chat histories (one JSON file per chat) and a **key-value store** listing each document's chats,
+- registers an **AI** (model + tools) the chat turns prompt through, and
+- subscribes a dedicated **queue** of four websocket service-request handlers (`onChatCreate`, `onChatList`, `onChatHistory`, `onChatSend`) that ship inside quidproquo-features.
+
+The handlers and any tool executors read the wiring from per-processor globals, exactly like `defineEventDocRoutes`' controllers — you do not write the backend, only configure it.
+
+- **On AWS:** deploys the union of the four config settings it returns — a DynamoDB table ([defineKeyValueStore](../core/key-value-store.md), partition `docId` / sort `chatId`) for the chat list, an S3 bucket ([defineStorageDrive](../core/storage-drive.md)) for chat-history JSON, the AI registration ([defineAi](../core/ai.md), granting Bedrock model access and registering the `tools`), and an SQS queue ([defineQueue](../core/queue.md)) subscribed to `eventBusName` whose processors are the four chat websocket handlers. Names are derived from `storeName`, so the same config deploys per environment without collisions.
+
+```typescript
+import { defineEventDocAi } from 'quidproquo-features';
+import { AiModel } from 'quidproquo-core';
+
+export default [
+  // ...the collection's own defineEventDoc* settings
+
+  ...defineEventDocAi({
+    storeName: 'project',
+    type: 'project',
+    serviceName: 'app',
+    eventBusName: 'app-ws-events',
+    userDirectoryName: 'users',
+    // optional: model, system prompt, tools, reasoning budget
+  }),
+];
+```
+
+## Signature
+
+```typescript
+function defineEventDocAi(options: EventDocAiOptions): QPQConfig;
+```
+
+`QPQConfig` here is the array of config settings described above.
+
+## Parameters
+
+All options are a single `EventDocAiOptions` object.
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `storeName` | `string` | – (required) | The eventDoc collection these chats attach to. Must match the collection's `defineEventDoc` store name — the same document store the chats are scoped against. Also the seed for the chat drive, chat-list store, and queue names. |
+| `type` | `string` | – (required) | The collection's document type. Combined with each method verb by `buildEventDocAiMethodName` (`eventDocAi/<type>/<method>`) so multiple collections' chats coexist on one service. |
+| `serviceName` | `string` | – (required) | The service the websocket requests route through. Must match the `serviceName` the frontend provides to the chat context (see [askEventDocAiContextProvide](../../actions/features/event-doc-ai/ask-event-doc-ai-context-read.md)). |
+| `eventBusName` | `string` | – (required) | The websocket events bus the chat queue subscribes to (application-specific). |
+| `userDirectoryName` | `string` | – (required) | The user directory used to resolve the acting user (chats record `createdByUserId`; the send handler gates on connection auth). |
+| `aiName` | `string` | `` `${storeName}-ai` `` | Name of the AI registration ([defineAi](../core/ai.md)) the turns prompt through. Override to share or namespace the AI. |
+| `model` | `AiModel` | `AiModel.ClaudeSonnet46` | The model each chat turn is sent to. |
+| `systemPrompt` | `string` | – | A static system prompt for every turn. Used when no `systemPromptGenerator` is set (or the generator returns empty). Falls back to a built-in default (`"You are a helpful assistant. Use tools when appropriate."`) if neither is provided. |
+| `systemPromptGenerator` | `string` | – | Name of a `defineInlineFunction` invoked on **every** turn to build the system prompt. It receives an `EventDocAiSystemPromptInput` (`{ docId }`, the trusted document id) and returns a string — so the prompt can carry live document state. A non-empty result overrides `systemPrompt`; an empty result falls back to it. |
+| `tools` | `AiToolDefinition[]` | `[]` | Tools the model may call, registered on the AI. Executors are `defineInlineFunction` names supplied by the caller. Tool runtimes inherit the chat's session context, so they read the trusted `docId` from context rather than trusting the model to pass it. |
+| `reasoningBudgetTokens` | `number` | `4096` | Extended-thinking token budget. Pass `0` to disable reasoning entirely. Reasoning streams to the chat as `reasoning` segments so the user sees progress instead of a silent wait. |
+
+## The chat model
+
+- A **chat** is scoped to one document (`docId`) in the collection. Its summary — `{ docId, chatId, name, createdAt, updatedAt, createdByUserId }` (`EventDocAiChatSummary`) — is a row in the chat-list key-value store (partition `docId`, sort `chatId`).
+- A chat's **message history** is stored as a single JSON file on the chat drive at `` `${docId}/${chatId}/history.json` ``, holding an array of `EventDocAiChatMessage` (`{ role, segments[] }`). Segments are the durable content format: `text`, `reasoning`, `file` (an attachment), and `tool-use` (tool calls paired with results).
+- **Sending a message** appends the user message to the history, streams the assistant's reply through [askAiPromptStream](../../actions/core/ai/ask-ai-prompt-stream.md), dispatches each stream part to the UI live, then folds the completed reply into durable segments, appends it, and bumps the chat's `updatedAt`. Stream parts are transport-only — they never persist; only the folded segments are saved.
+- **Attachments** are eventDoc assets (uploaded via the collection's asset routes) referenced by bare `assetId`. The send flow validates each id against the session's trusted `docId` before it can reach the model, so a client can never point the AI at another document's files.
+
+The four verbs — chat create, list, history, and send — are exposed to the browser as websocket service requests. See the [Event Doc AI actions](../../actions/features/event-doc-ai/ask-event-doc-ai-process-send.md) for the requesters, and the `askUIEventDocAi*` UI actions for driving the chat SPA's state.
+
+## Examples
+
+```typescript
+import { defineEventDocAi } from 'quidproquo-features';
+import { AiModel } from 'quidproquo-core';
+
+export default [
+  // A per-document assistant with tools and a document-aware system prompt.
+  ...defineEventDocAi({
+    storeName: 'project',
+    type: 'project',
+    serviceName: 'app',
+    eventBusName: 'app-ws-events',
+    userDirectoryName: 'users',
+    model: AiModel.ClaudeSonnet46,
+    systemPromptGenerator: '/entry/ai/buildProjectPrompt::buildProjectPrompt',
+    tools: [
+      /* AiToolDefinition[]; executors registered via defineInlineFunction */
+    ],
+    reasoningBudgetTokens: 8192,
+  }),
+];
+```
+
+## Related
+
+- [defineEventDoc](./event-doc.md) — the collection these chats attach to (`storeName` / `type` must match).
+- [defineAi](../core/ai.md) — the AI registration `aiName`/`tools` map to.
+- [defineKeyValueStore](../core/key-value-store.md) / [defineStorageDrive](../core/storage-drive.md) / [defineQueue](../core/queue.md) — the infrastructure this config composes.
+- [askAiPromptStream](../../actions/core/ai/ask-ai-prompt-stream.md) — the streamed prompt each chat turn runs.
+- [askEventDocAiProcessSend](../../actions/features/event-doc-ai/ask-event-doc-ai-process-send.md) — the backend turn orchestrator.
+- [Event Doc AI actions](../../actions/features/event-doc-ai/ask-event-doc-ai-context-read.md) — the chat requesters and context wrappers.