create-qpq-app 0.1.5

package/template/docusaurus/docs/config/webserver/web-entry.md

@@ -0,0 +1,150 @@
+---
+title: defineWebEntry
+description: Host a static web app / SPA — its build output is served from a CDN-backed storage bucket on your domain.
+---
+
+# defineWebEntry
+
+Defines a **web entry**: a hosted static web app (a single-page app or any static site) served on a domain through a CDN. The build output is uploaded to a storage bucket and served through a CDN distribution, with an SPA fallback so client-side routes resolve to your app shell.
+
+- **On AWS:** deploys an S3 bucket (private, versioned, all public access blocked) as the origin and a CloudFront distribution in front of it (`WebQpqWebserverWebEntryConstruct` in `quidproquo-deploy-awscdk`). CloudFront reads the bucket via Origin Access Control, redirects HTTP to HTTPS, optionally compresses responses, and serves the certificate for your domain (an ACM certificate looked up in `us-east-1`). A Route 53 A-record aliases your (sub)domain to the distribution. `404`/`403` responses are rewritten to `200` served from `/` — the **SPA fallback** that lets client-side routing handle deep links. When WAF protection is enabled for the app, the shared CloudFront web ACL is attached. If `autoUpload` is on, the build output is uploaded to the bucket on every deploy.
+
+```typescript
+import { defineWebEntry } from 'quidproquo-webserver';
+
+export default [
+  defineWebEntry('website', {
+    buildPath: './web/dist',
+    domain: {
+      onRootDomain: true,
+      rootDomain: 'example.com',
+    },
+  }),
+];
+```
+
+## Signature
+
+```typescript
+function defineWebEntry(
+  name: string,
+  options: QPQConfigAdvancedWebEntrySettings,
+): WebEntryQPQWebServerConfigSetting;
+```
+
+## Parameters
+
+### `name` — `string` (required)
+
+The web entry's name and `uniqueKey`. This is the name you pass to [askWebEntryInvalidateCache](../../actions/webserver/web-entry/ask-web-entry-invalidate-cache.md), and on AWS it is used to derive the bucket name and the distribution's CloudFormation export.
+
+### `options` — `QPQConfigAdvancedWebEntrySettings` (required)
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `domain` | `WebDomainOptions` | – | **Required.** The domain to serve the app on — see [WebDomainOptions](#webdomainoptions). |
+| `buildPath` | `string` | – | Local path to the built static assets to upload to the origin bucket (used when `storageDrive.autoUpload` is on). |
+| `storageDrive` | `StorageDriveOptions` | `{ autoUpload: true }` | Where the assets live / how they are uploaded — see [StorageDriveOptions](#storagedriveoptions). |
+| `indexRoot` | `string` | `'index.html'` | The default root object served for `/` (CloudFront `defaultRootObject`). |
+| `cacheSettingsName` | `string` | – | Name of a [defineCache](./cache.md) policy to apply to the default behavior. When omitted, caching is disabled at the CDN (every request hits origin). |
+| `ignoreCache` | `string[]` | `[]` | Path patterns that bypass the cache — each becomes a CDN behavior with caching disabled. Use for files that must never be stale, e.g. `['index.html', 'remoteEntry.js', 'mf-manifest.json']`. |
+| `compressFiles` | `boolean` | `true` | Whether the CDN compresses responses (gzip/brotli). |
+| `securityHeaders` | `ResponseSecurityHeaders` | – | Security-related HTTP response headers (CSP, HSTS, frame options, etc.) attached via a CDN response-headers policy — see [ResponseSecurityHeaders](#responsesecurityheaders). |
+| `corsAllowedOrigins` | `string[]` | service's own domain | Browser origins allowed to cross-origin `fetch` this web entry's static assets. Omit to scope to this service's own domain (`https://<domain>` and `https://*.<domain>`); pass `['*']` to allow any origin (e.g. serving assets as a public CDN or cross-origin fonts). |
+| `cloudflareApiKeySecretName` | `string` | – | Name of a [secret](../core/secret.md) holding a Cloudflare API key, for setups whose DNS is managed through Cloudflare rather than Route 53. |
+| `deprecated` | `boolean` | `false` | Standard advanced-settings flag marking the entry as deprecated. |
+
+### `WebDomainOptions`
+
+```typescript
+export interface WebDomainOptions {
+  subDomainName?: string;
+  onRootDomain: boolean;
+  rootDomain: string;
+}
+```
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `rootDomain` | `string` | The apex/root domain to host under, e.g. `'example.com'`. The ACM certificate and Route 53 hosted zone are resolved from this. |
+| `onRootDomain` | `boolean` | Serve on the apex domain itself (`example.com`). |
+| `subDomainName` | `string` (optional) | Serve on a subdomain instead of / in addition to the apex, e.g. `'app'` → `app.example.com`. |
+
+### `StorageDriveOptions`
+
+```typescript
+export interface StorageDriveOptions {
+  sourceStorageDrive?: string;
+  autoUpload: boolean;
+}
+```
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `autoUpload` | `boolean` | When `true`, the assets at `buildPath` are uploaded to the origin bucket on every deploy. Set `false` when something else (e.g. a separate publish step) populates the bucket. |
+| `sourceStorageDrive` | `string` (optional) | Serve the app from an **existing** [storage drive](../core/storage-drive.md) (by name) instead of a dedicated bucket created for this web entry. When set, that drive's bucket is used as the CDN origin. |
+
+### `ResponseSecurityHeaders`
+
+Optional security headers the CDN adds to responses. Every sub-object has an `override` boolean (whether to override the header received from origin). All are optional; anything omitted is simply not sent.
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `contentSecurityPolicy` | `ResponseHeadersContentSecurityPolicy` | `Content-Security-Policy` directives — a `Record<string, ContentSecurityPolicyEntry[]>` where an entry is either a raw string or a `QpqServiceContentSecurityPolicy` describing another service by `{ api, domain?, service?, protocol? }`. |
+| `contentTypeOptions` | `ResponseHeadersContentTypeOptions` | Sends `X-Content-Type-Options: nosniff`. |
+| `frameOptions` | `ResponseHeadersFrameOptions` | `X-Frame-Options` — `frameOption` is `HeadersFrameOption.DENY` or `HeadersFrameOption.SAMEORIGIN`. |
+| `referrerPolicy` | `ResponseHeadersReferrerPolicy` | `Referrer-Policy` — `referrerPolicy` is a `HeadersReferrerPolicy` member (e.g. `SAME_ORIGIN`, `STRICT_ORIGIN_WHEN_CROSS_ORIGIN`). |
+| `strictTransportSecurity` | `ResponseHeadersStrictTransportSecurity` | HSTS — `accessControlMaxAgeInSeconds`, plus optional `includeSubdomains` and `preload`. |
+| `xssProtection` | `ResponseHeadersXSSProtection` | `X-XSS-Protection` — `protection`, optional `modeBlock`, and optional `reportUri`. |
+
+## Examples
+
+```typescript
+import { defineStorageDrive } from 'quidproquo-core';
+import { defineWebEntry, QPQConfigAdvancedWebEntrySettings } from 'quidproquo-webserver';
+
+// Simple SPA on the apex domain, assets uploaded on deploy
+export default [
+  defineWebEntry('website', {
+    buildPath: './web/dist',
+    cacheSettingsName: 'default',
+    // The SPA shell and module-federation manifests must never be served stale
+    ignoreCache: ['index.html', 'remoteEntry.js', 'mf-manifest.json'],
+    domain: {
+      onRootDomain: true,
+      rootDomain: 'example.com',
+    },
+  }),
+];
+```
+
+```typescript
+// Serve a web app from an existing storage drive, populated by a separate step
+const options: QPQConfigAdvancedWebEntrySettings = {
+  buildPath: './web/dist',
+  cacheSettingsName: 'default',
+  domain: {
+    subDomainName: 'views',
+    onRootDomain: false,
+    rootDomain: 'example.com',
+  },
+  storageDrive: {
+    sourceStorageDrive: 'views',
+    autoUpload: false,
+  },
+};
+
+export default [
+  defineStorageDrive('views'),
+  defineWebEntry('views', options),
+];
+```
+
+## Related
+
+- [defineCache](./cache.md) — the CDN cache policy referenced by `cacheSettingsName`.
+- [defineSeo](./seo.md) — server-side (Lambda@Edge) rendering attached to a web entry's paths, for crawlers/social previews.
+- [defineStorageDrive](../core/storage-drive.md) — the drive referenced by `storageDrive.sourceStorageDrive`.
+- [defineStorageDriveCorsSettings](./storage-drive-cors-settings.md) — browser CORS for a storage drive's own objects (as opposed to `corsAllowedOrigins` here, which covers this web entry's assets).
+- [askWebEntryInvalidateCache](../../actions/webserver/web-entry/ask-web-entry-invalidate-cache.md) — drop cached assets after a deploy.
+- **AWS implementation:** `WebQpqWebserverWebEntryConstruct` (S3 origin, CloudFront distribution, OAC, Route 53 alias, security headers, SEO edge lambdas) in `quidproquo-deploy-awscdk`.

package/template/docusaurus/docs/config/webserver/web-socket-queue.md

@@ -0,0 +1,88 @@
+---
+title: defineWebSocketQueue
+description: Define a managed WebSocket messaging layer — connection tracking, auth, and typed client/server messages over a WebSocket API.
+---
+
+# defineWebSocketQueue
+
+Defines a **WebSocket queue**: a batteries-included messaging layer on top of a raw [WebSocket API](./websocket.md). Where [defineWebsocket](./websocket.md) hands you the bare `$connect`/`$disconnect`/`$default` hooks, `defineWebSocketQueue` supplies those handlers for you and wires in a built-in service that tracks live connections, authenticates clients, and exchanges typed client/server messages (ping/pong, authenticate, service request/response, state dispatch). Inbound frames are routed by message type, and outbound messages fan out to the connections registered for a user.
+
+- **On AWS:** this define expands into several config settings, each deploying its own infrastructure:
+  - a [WebSocket API](./websocket.md) (API Gateway v2 WebSocket API + Lambda) whose connect/disconnect/message handlers are the queue's built-in service entry points;
+  - a [key-value store](../core/key-value-store.md) (DynamoDB table) named `qpq-wsq-<apiName>`, keyed by `id` with a `userId` index, that records each live connection so messages can be addressed to a user's connections;
+  - two [globals](../core/global.md) recording the associated event-bus name and user-directory name.
+
+```typescript
+import { defineWebSocketQueue } from 'quidproquo-webserver';
+
+export default [
+  defineWebSocketQueue('my-event-bus', 'api', 'example.com', {
+    userDirectoryName: 'users',
+  }),
+];
+```
+
+## How it relates to defineWebsocket
+
+`defineWebSocketQueue` **calls** [defineWebsocket](./websocket.md) internally — you do not need to declare one yourself. It passes its own service handlers as the `eventProcessors`:
+
+| Route | Handler wired by the queue |
+| --- | --- |
+| `onConnect` | Registers the new `connectionId` in the connection store. |
+| `onDisconnect` | Removes the connection from the store. |
+| `onMessage` | Decodes the JSON frame and dispatches on its message type (authenticate, ping, service request, …). |
+
+Because the underlying WebSocket API is created with `apiName` equal to the `apiName` you pass here, use that same value as the `websocketApiName` argument to [askWebsocketSendMessage](../../actions/webserver/websocket/ask-websocket-send-message.md) when sending raw frames to a connection on this API.
+
+## Signature
+
+```typescript
+function defineWebSocketQueue(
+  eventBusName: string,
+  apiName: string,
+  rootDomain: string,
+  advancedSettings?: QPQConfigAdvancedWebsocketQueueSettings,
+): QPQConfig;
+```
+
+Note the return type is a `QPQConfig` (an **array** of settings), not a single setting — spread it, or return it, alongside your other config.
+
+## Parameters
+
+### `eventBusName` — `string` (required)
+
+Name of the [event bus](../core/event-bus.md) the queue is associated with (stored in a global as `qpq-wsq-eb-name-<apiName>`), used to fan messages out to connections.
+
+### `apiName` — `string` (required)
+
+Logical name of the WebSocket API. Drives the resource names of the deployed API, the connection key-value store (`qpq-wsq-<apiName>`), and the globals — and is the value you pass as `websocketApiName` to send actions. Also used as the API subdomain.
+
+### `rootDomain` — `string` (required)
+
+The registered domain the WebSocket API is served under (passed straight through to the underlying [defineWebsocket](./websocket.md)).
+
+### `advancedSettings` — `QPQConfigAdvancedWebsocketQueueSettings` (optional)
+
+```typescript
+export interface QPQConfigAdvancedWebsocketQueueSettings extends QPQConfigAdvancedSettings {
+  owner?: CrossModuleOwnerWithNoResourceOverride;
+  userDirectoryName?: string;
+}
+```
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `userDirectoryName` | `string` | `''` | Name of the [user directory](../core/user-directory.md) used to authenticate clients (stored in the `qpq-wsq-kvs-name-<apiName>` global). Enables the authenticate client/server message flow. |
+| `owner` | `CrossModuleOwnerWithNoResourceOverride` | – | Declares the queue's resources as owned by another module/service, so this service references them instead of deploying its own. Applied to both the WebSocket API and the connection store. |
+| `deprecated` | `boolean` | `false` | Inherited from `QPQConfigAdvancedSettings`; when set, the underlying WebSocket API is not deployed. |
+
+## Returns
+
+A `QPQConfig` array containing: two globals, the connection [key-value store](../core/key-value-store.md), and the [WebSocket API](./websocket.md) with the queue's built-in handlers.
+
+## Related
+
+- [defineWebsocket](./websocket.md) — the raw WebSocket API this define builds on and configures for you.
+- [defineStateDispatchOverWebsockets](./state-dispatch-over-websockets.md) — routes core State-domain dispatches to clients through this queue.
+- [askWebsocketSendMessage](../../actions/webserver/websocket/ask-websocket-send-message.md) — send a raw message to a connection on the queue's API.
+- [defineEventBus](../core/event-bus.md), [defineKeyValueStore](../core/key-value-store.md), [defineUserDirectory](../core/user-directory.md) — the underlying resources it depends on.

package/template/docusaurus/docs/config/webserver/websocket.md

@@ -0,0 +1,110 @@
+---
+title: defineWebsocket
+description: Define a WebSocket API with connect, disconnect, and message route handlers.
+---
+
+# defineWebsocket
+
+Defines a **WebSocket API**: a persistent, bidirectional connection endpoint served on its own subdomain. You supply story entry points that run when a client connects, disconnects, or sends a message, and the runtime wires them to the platform's WebSocket transport. Stories push messages back to connected clients with [askWebsocketSendMessage](../../actions/webserver/websocket/ask-websocket-send-message.md).
+
+- **On AWS:** deploys an **API Gateway v2 WebSocket API** (`QpqApiWebserverWebsocketConstruct` in `quidproquo-deploy-awscdk`) fronted by a single Lambda proxy integration. Three routes — `$connect`, `$disconnect`, and `$default` — all target that Lambda, which dispatches to the matching handler in `eventProcessors`. The API is mapped to a custom subdomain (`apiSubdomain.rootDomain`) and served from the `prod` stage. Routes use `authorizationType: NONE`; do your own auth inside the `onConnect`/`onMessage` handlers. When `deprecated` is set, nothing is deployed.
+
+```typescript
+import { defineWebsocket } from 'quidproquo-webserver';
+
+export default [
+  defineWebsocket('ws', 'example.com', {
+    onConnect: '/entry/ws/onConnect::onConnect',
+    onDisconnect: '/entry/ws/onDisconnect::onDisconnect',
+    onMessage: '/entry/ws/onMessage::onMessage',
+  }),
+];
+```
+
+## Routing model
+
+API Gateway's WebSocket API has three built-in route keys, and `defineWebsocket` maps each to one of your event processors:
+
+| Route key | Fires when | Handler |
+| --- | --- | --- |
+| `$connect` | A client opens the WebSocket connection (the handshake). | `eventProcessors.onConnect` |
+| `$disconnect` | A client's connection closes (client- or server-initiated). | `eventProcessors.onDisconnect` |
+| `$default` | The client sends any message frame (there are no per-message custom routes — every inbound frame goes here). | `eventProcessors.onMessage` |
+
+Each handler is a story (generator) that receives a `WebsocketEvent` (exported from `quidproquo-webserver`) and returns `void`:
+
+```typescript
+export type WebsocketEvent<T extends string | Blob | ArrayBuffer = string> = {
+  eventType: WebSocketEventType; // Connect | Disconnect | Message
+  messageId: string;
+  connectionId: string;          // identifies the client; pass to askWebsocketSendMessage
+  requestTime: string;
+  requestTimeEpoch: number;
+  userAgent: string;
+  sourceIp: string;
+  apiName: string;
+  body?: T;                      // present on message events
+};
+```
+
+`connectionId` is the handle for a single client connection — store it (e.g. in a key-value store keyed by user) during `onConnect` so later stories can send messages to that client with [askWebsocketSendMessage](../../actions/webserver/websocket/ask-websocket-send-message.md).
+
+## Signature
+
+```typescript
+function defineWebsocket(
+  apiSubdomain: string,
+  rootDomain: string,
+  eventProcessors: QpqWebSocketEventProcessors,
+  options?: QPQConfigAdvancedWebSocketSettings,
+): WebSocketQPQWebServerConfigSetting;
+```
+
+## Parameters
+
+### `apiSubdomain` — `string` (required)
+
+The subdomain the WebSocket API is served on. Combined with `rootDomain` it forms the connection host (`apiSubdomain.rootDomain`) and the setting's `uniqueKey`.
+
+### `rootDomain` — `string` (required)
+
+The registered domain the API lives under. On AWS a custom-domain mapping is created for `apiSubdomain.rootDomain` (or, when `onRootDomain` is set, directly under the base/service domain).
+
+### `eventProcessors` — `QpqWebSocketEventProcessors` (required)
+
+The story entry points for the connection lifecycle. All three are optional — omit any route you don't need to handle.
+
+```typescript
+export interface QpqWebSocketEventProcessors {
+  onConnect?: QpqFunctionRuntime;
+  onDisconnect?: QpqFunctionRuntime;
+  onMessage?: QpqFunctionRuntime;
+}
+```
+
+Each value is a `QpqFunctionRuntime` — a reference to a story entry point, written as a relative path string in the form `'/path/to/file::exportedFunctionName'`.
+
+### `options` — `QPQConfigAdvancedWebSocketSettings` (optional)
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `apiName` | `string` | `'api'` | Logical name for the API. Used to derive the deployed WebSocket API's resource/export names and passed to [askWebsocketSendMessage](../../actions/webserver/websocket/ask-websocket-send-message.md) as `websocketApiName` when sending to connections on this API. |
+| `onRootDomain` | `boolean` | `false` | When `true`, the API's custom domain is built from the base domain rather than the module's service domain. |
+| `cloudflareApiKeySecretName` | `string` | – | Name of the secret holding a Cloudflare API key, for DNS setups fronted by Cloudflare. |
+| `maxConcurrentExecutions` | `number` | – | Reserved concurrency for the API's Lambda. Caps and guarantees concurrent event processing: never throttled below it, never scales above it. One compute unit serves all of the API's event processors (connect/disconnect/message), so this bounds the API as a whole. Carved out of the deploy account's shared concurrency pool. |
+| `deprecated` | `boolean` | `false` | When `true`, the API is not deployed. Use to retire an API without deleting its config. |
+| `owner` | `CrossModuleOwner<'websocketApiName'>` | – | Declares that this WebSocket API is owned by **another** module/service, so this service references it rather than deploying its own. |
+
+## Returns
+
+A `WebSocketQPQWebServerConfigSetting` config setting (`configSettingType: WebSocket`) with `uniqueKey` = `` `${apiSubdomain}.${rootDomain}` ``. Return it (or spread it) from a config array.
+
+## Notes
+
+- `defineWebsocket` gives you the raw connect/disconnect/message hooks. If you want a batteries-included messaging layer — connection tracking, authentication, ping/pong, and typed client/server messages — use [defineWebSocketQueue](./web-socket-queue.md), which wires those three handlers to a built-in service for you.
+
+## Related
+
+- [defineWebSocketQueue](./web-socket-queue.md) — a higher-level WebSocket setup that provides `eventProcessors` for you and manages connections and messaging.
+- [defineStateDispatchOverWebsockets](./state-dispatch-over-websockets.md) — pushes core State-domain dispatches to clients over the WebSocket queue.
+- [askWebsocketSendMessage](../../actions/webserver/websocket/ask-websocket-send-message.md) — send a message to a connected client by `connectionId`.

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

@@ -0,0 +1 @@
+{ "label": "quidproquo-xstate", "position": 4, "link": { "type": "generated-index", "description": "XState state-machine config from quidproquo-xstate." } }

package/template/docusaurus/docs/config/xstate/state-machine.md

@@ -0,0 +1,201 @@
+---
+title: defineStateMachine
+description: Define a persistent XState state machine — a named machine definition, backed by a key-value store, that stories drive with events over time.
+---
+
+# defineStateMachine
+
+Defines a **state machine**: a named [XState](https://stately.ai/docs) machine definition plus the storage and side-effect wiring quidproquo needs to run it. Stories never construct an XState actor themselves — they create machine instances and drive them with events by name using the [State Machine action requesters](../../actions/xstate/ask-state-machine-create.md), and the runtime rehydrates, transitions, and re-persists the machine on every action.
+
+Each instance is a row in a key-value store. Its current XState snapshot is serialized into a field on that row, so a machine created by one story can be advanced and read by later stories, requests, or events — the machine survives between invocations rather than living in memory.
+
+- **On AWS:** `defineStateMachine` expands into **two** config settings — a key-value store named `qpq-sm-<machineName>` (keyed by `id`) and the state-machine setting itself. The key-value store deploys a DynamoDB table (see [defineKeyValueStore](../core/key-value-store.md)) partitioned by `id`; that table is where every instance and its persisted snapshot live. The machine definition itself is not deployed as any dedicated infrastructure — it is evaluated in-process by the action processors whenever an instance is created, read, or advanced.
+
+```typescript
+import { defineStateMachine } from 'quidproquo-xstate';
+
+export default [
+  defineStateMachine('order', {
+    config: {
+      id: 'order',
+      initial: 'pending',
+      states: {
+        pending: {
+          on: { PAY: 'paid', CANCEL: 'cancelled' },
+        },
+        paid: {
+          on: { SHIP: 'shipped' },
+        },
+        shipped: { type: 'final' },
+        cancelled: { type: 'final' },
+      },
+    },
+  }),
+];
+```
+
+## Signature
+
+```typescript
+function defineStateMachine(
+  stateMachineName: string,
+  options: QPQConfigAdvancedStateMachineSettings,
+): QPQConfigSetting[];
+```
+
+`defineStateMachine` returns an **array** of config settings (the derived key-value store plus the state-machine setting). Spread it into your config export, or let the array flatten naturally.
+
+## Parameters
+
+### `stateMachineName` — `string` (required)
+
+The name of the machine. This is the name you pass as the first argument to every state-machine action (e.g. `askStateMachineCreate('order', ...)`). It is also the setting's `uniqueKey`, and it derives the backing key-value store's name: `qpq-sm-<stateMachineName>`.
+
+### `options` — `QPQConfigAdvancedStateMachineSettings` (required)
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `config` | `MachineConfig<MachineContext, EventObject>` | – (required) | The XState machine definition — states, `initial`, and `on` transitions. This is passed straight to XState's `createMachine`. See [XState machine config](https://stately.ai/docs/machines). |
+| `actions` | `StateMachineRuntimeMap` | `{}` | Maps XState action names (referenced from the `config`) to quidproquo stories that run as side effects when that action fires during a transition. See [Actions and guards](#actions-and-guards). |
+| `guards` | `StateMachineRuntimeMap` | `{}` | Maps XState guard names (referenced from the `config`) to quidproquo stories that return a boolean, deciding whether a guarded transition is allowed. See [Actions and guards](#actions-and-guards). |
+| `stateField` | `string` | `'__machineState'` | The property name under which the persisted XState snapshot is stored on each instance row. Change it only if it would collide with a field of your own data. |
+| `owner` | `CrossModuleOwner` | – | Declares that the machine (and its backing store) is owned by another module/service, so this service references it rather than deploying its own. |
+
+### `StateMachineRuntimeMap`
+
+```typescript
+interface StateMachineRuntimeMap {
+  [name: string]: QpqFunctionRuntime;
+}
+```
+
+Each value is a `QpqFunctionRuntime` — a reference to a story entry point, usually written as a relative path string in the form `'/path/to/file::exportedFunctionName'`.
+
+## Actions and guards
+
+XState `actions` and `guards` are named in your `config` but implemented as quidproquo stories:
+
+- **Actions** are side effects. Whenever a transition (or the initial entry) fires an action named in your `config`, the runtime loads the mapped story and runs it. The story receives the current instance entity as its argument (and, for event-driven transitions, the triggering event as a second argument). Its result is not fed back into the machine.
+- **Guards** decide whether a guarded transition may occur. Before an event is applied, the runtime runs **every** mapped guard story, passing `(entity, event)`, and uses each story's boolean result to answer the corresponding guard in the machine. Guards must be side-effect-light — they are evaluated up front to a plain boolean.
+
+```typescript
+import { defineStateMachine } from 'quidproquo-xstate';
+
+export default [
+  defineStateMachine('order', {
+    config: {
+      id: 'order',
+      initial: 'pending',
+      states: {
+        pending: {
+          on: {
+            PAY: {
+              target: 'paid',
+              guard: 'hasValidPayment',
+              actions: 'notifyWarehouse',
+            },
+          },
+        },
+        paid: { on: { SHIP: 'shipped' } },
+        shipped: { type: 'final' },
+      },
+    },
+    guards: {
+      hasValidPayment: '/entry/order/hasValidPayment::hasValidPayment',
+    },
+    actions: {
+      notifyWarehouse: '/entry/order/notifyWarehouse::notifyWarehouse',
+    },
+  }),
+];
+```
+
+## How persistence works
+
+There is no long-lived actor. Every state-machine action follows the same pattern:
+
+1. Look up the machine's config by name and its backing key-value store (`qpq-sm-<name>`).
+2. For reads and transitions, load the instance row by `id` and **rehydrate** a fresh XState actor from the snapshot stored under `stateField`.
+3. Apply the operation (start, send event, read snapshot).
+4. For create and send-event, serialize the new snapshot back onto the row (via `getPersistedSnapshot()`) and upsert it.
+
+Because the snapshot is persisted with XState's own serialization, machine instances are durable across separate requests and deployments — the same instance can be advanced hours or days later.
+
+## Examples
+
+```typescript
+import { defineStateMachine } from 'quidproquo-xstate';
+
+export default [
+  // Minimal machine — no side effects, default state field
+  defineStateMachine('door', {
+    config: {
+      id: 'door',
+      initial: 'closed',
+      states: {
+        closed: { on: { OPEN: 'open' } },
+        open: { on: { CLOSE: 'closed' } },
+      },
+    },
+  }),
+
+  // Machine with guards, actions, and a custom state field
+  defineStateMachine('subscription', {
+    stateField: '__smSnapshot',
+    config: {
+      id: 'subscription',
+      initial: 'trialing',
+      states: {
+        trialing: {
+          on: { ACTIVATE: { target: 'active', guard: 'paymentOnFile' } },
+        },
+        active: {
+          on: { CANCEL: { target: 'cancelled', actions: 'sendCancelEmail' } },
+        },
+        cancelled: { type: 'final' },
+      },
+    },
+    guards: {
+      paymentOnFile: '/entry/subscription/paymentOnFile::paymentOnFile',
+    },
+    actions: {
+      sendCancelEmail: '/entry/subscription/sendCancelEmail::sendCancelEmail',
+    },
+  }),
+];
+```
+
+## Driving an instance from a story
+
+A single config plus the four actions is enough to create a durable instance and move it through its lifecycle across separate invocations:
+
+```typescript
+import { askNewGuid } from 'quidproquo-core';
+import {
+  askStateMachineCreate,
+  askStateMachineSendEvent,
+  askStateMachineGetState,
+} from 'quidproquo-xstate';
+
+export function* processOrder(customerId: string) {
+  const orderId = yield* askNewGuid();
+
+  // 1. Create — starts at the machine's initial state ('pending')
+  yield* askStateMachineCreate('order', orderId, { customerId, total: 4200 });
+
+  // 2. Send an event — drives the transition pending -> paid
+  yield* askStateMachineSendEvent('order', orderId, { type: 'PAY' });
+
+  // 3. Read the current state
+  const state = yield* askStateMachineGetState('order', orderId);
+  return { orderId, state: state.value, done: state.done }; // -> { state: 'paid', done: false }
+}
+```
+
+Each action is a self-contained round-trip to the backing store — nothing is held in memory between them — so the same three steps could just as easily be three separate requests or events days apart.
+
+## Related
+
+- **Action requesters that drive this machine:** [askStateMachineCreate](../../actions/xstate/ask-state-machine-create.md), [askStateMachineGet](../../actions/xstate/ask-state-machine-get.md), [askStateMachineGetState](../../actions/xstate/ask-state-machine-get-state.md), [askStateMachineSendEvent](../../actions/xstate/ask-state-machine-send-event.md).
+- [defineKeyValueStore](../core/key-value-store.md) — the store type `defineStateMachine` provisions under the hood to persist instances.
+- **XState docs:** [Machines](https://stately.ai/docs/machines), [Actions](https://stately.ai/docs/actions), [Guards](https://stately.ai/docs/guards), [Persistence](https://stately.ai/docs/persistence).

package/template/docusaurus/docs/core-concepts.md

@@ -0,0 +1,23 @@
+---
+sidebar_position: 2
+---
+
+# Core Concepts
+
+Quidproquo follows a Redux-like action/processor pattern where business logic is expressed as generator functions ("stories") that yield actions, which are then processed by platform-specific implementations.
+
+## Actions
+
+Type-safe Redux-style actions with a type and optional payload.
+
+## Stories
+
+Generator functions that compose business logic by yielding actions and receiving results.
+
+## Action Processors
+
+Platform-specific implementations that execute actions.
+
+## Runtime
+
+The orchestration layer that executes stories by processing yielded actions through the appropriate processors.