create-qpq-app 0.1.5

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

@@ -0,0 +1,100 @@
+---
+title: defineEventDocRoutes
+description: Mount the built-in HTTP routes for an event-sourced document collection against an already-declared store.
+---
+
+# defineEventDocRoutes
+
+Mounts the built-in REST **routes** for one document `type` in an event-document collection. It returns a `QPQConfig` (an array of route settings). The route controllers ship inside `quidproquo-features` and resolve the store, type, user directory, validator, and renderer from per-route globals — so a service needs no controller wiring of its own: declare the store, add these routes, and the collection is fully served.
+
+`defineEventDocRoutes` defines **only** the routes; it assumes the store already exists (declared with [defineEventDocSummary](./event-doc-summary.md)). Use it directly when **several document types share one store** — call `defineEventDocSummary` once, then `defineEventDocRoutes` per type. For the single-type case, [defineEventDoc](./event-doc.md) does both in one call.
+
+- **On AWS:** deploys the routes below to API Gateway, each backed by a Lambda running the corresponding built-in controller. It creates no data infrastructure — that is [defineEventDocSummary](./event-doc-summary.md)'s job.
+
+```typescript
+import { defineEventDocSummary, defineEventDocRoutes } from 'quidproquo-features';
+
+export default [
+  ...defineEventDocSummary('content'),
+  ...defineEventDocRoutes({
+    storeName: 'content',
+    type: 'article',
+    basePath: '/articles',
+    routeAuthSettings: { userDirectoryName: 'editors' },
+  }),
+];
+```
+
+## Routes mounted
+
+All paths are prefixed with the version segment `/v{version}` (default `/v1`):
+
+| Method | Path | Purpose |
+| --- | --- | --- |
+| `GET` | `{basePath}` | List the collection's documents. |
+| `GET` | `{basePath}/{id}` | Get one document's summary record. |
+| `GET` | `{basePath}/{id}/events` | List a document's event log. |
+| `GET` | `{basePath}/{id}/render` | Render the document to HTML. **Only mounted when `eventRenderer` is set.** |
+| `POST` | `{basePath}` | Create a document. |
+| `POST` | `{basePath}/{id}/events` | Append an event to a document. |
+| `POST` | `{basePath}/{id}/assets` | Request an asset upload URL. |
+| `GET` | `{basePath}/{id}/assets/{assetId}` | Download an asset. |
+| `DELETE` | `{basePath}/{id}` | Remove a document. |
+
+## Signature
+
+```typescript
+function defineEventDocRoutes(options: EventDocRoutesOptions): QPQConfig;
+```
+
+## Parameters
+
+The single `options` argument is an `EventDocRoutesOptions`:
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `storeName` | `string` | – (required) | The store to serve. **Must match a [defineEventDocSummary](./event-doc-summary.md)** in the same service. |
+| `type` | `string` | – (required) | The document type this route set serves. Pins the collection within a store that can hold several types — use a distinct `type` (and `basePath`) per `defineEventDocRoutes` call over a shared store. |
+| `basePath` | `` `/${string}` `` | – (required) | URL prefix the routes mount under. Must start with `/`, e.g. `/articles`. |
+| `routeAuthSettings` | `RouteAuthSettings` | – | Auth settings applied to every mounted route (from quidproquo-webserver — see [route](../webserver/route.md)). When it carries a `userDirectoryName`, that directory is exposed to the controllers so mutations can attribute the acting user. **Omit to leave the routes open** — mutations then have no user to attribute. |
+| `version` | `number` | `1` | Version number for the `/v{version}` path prefix on every route. |
+| `eventValidator` | `string` | – | Name of a registered inline function (see `defineInlineFunction`). When set, every append invokes it with `{ event, events }` to reject lifecycle- or payload-invalid events before they reach the log. The frontend editor runs the same rule for instant feedback. |
+| `eventRenderer` | `string` | – | Name of a registered inline function. When set, a `GET {basePath}/{id}/render` route is mounted; it invokes the renderer with the document's full `{ events }` log, which folds + renders to HTML. |
+
+### `RouteAuthSettings`
+
+`routeAuthSettings` is the standard quidproquo-webserver route auth object (the same one [defineRoute](../webserver/route.md) accepts). Its `userDirectoryName` names the [user directory](../core/key-value-store.md) callers authenticate against; the controllers read it to resolve the acting user for event attribution.
+
+## Examples
+
+```typescript
+import { defineEventDocSummary, defineEventDocRoutes } from 'quidproquo-features';
+
+export default [
+  // One store, two types, each on its own path and route version.
+  ...defineEventDocSummary('content'),
+
+  ...defineEventDocRoutes({
+    storeName: 'content',
+    type: 'article',
+    basePath: '/articles',
+    routeAuthSettings: { userDirectoryName: 'editors' },
+    eventValidator: 'validateArticleEvent',
+    eventRenderer: 'renderArticle',
+  }),
+
+  ...defineEventDocRoutes({
+    storeName: 'content',
+    type: 'page',
+    basePath: '/pages',
+    routeAuthSettings: { userDirectoryName: 'editors' },
+  }),
+];
+```
+
+## Related
+
+- [defineEventDocSummary](./event-doc-summary.md) — declares the store these routes serve (required before mounting routes).
+- [defineEventDoc](./event-doc.md) — declares the store *and* these routes in one call for the single-type case.
+- [defineRoute](../webserver/route.md) — the underlying webserver route config (source of `RouteAuthSettings`).
+- **Custom routes over the same store:** wrap your controllers in `askEventDocProvideStore({ storeName, type }, ...)` (from quidproquo-features) so the generic [reads](../../actions/features/event-doc/ask-event-doc-get-by-id.md) resolve the collection, then compose actions like [askEventDocCreate](../../actions/features/event-doc/ask-event-doc-create.md).

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

@@ -0,0 +1,59 @@
+---
+title: defineEventDocSummary
+description: Declare the stores for an event-sourced document collection — its summary table, append-only event log, and asset bucket.
+---
+
+# defineEventDocSummary
+
+Declares the **stores** that back an event-document collection, without any routes. It returns a `QPQConfig` (an array of config settings) that expands to three underlying core stores:
+
+1. A **summary key-value store** (partition key `type`, sort key `id`) — the queryable record for each document, derived by folding the identity/lifecycle events of its log. Rows are the [`EventDocSummary`](../../actions/features/event-doc/ask-event-doc-get-by-id.md) shape and carry the version history. A secondary index on `(type, updatedAt)` supports the recently-updated ordering [askEventDocList](../../actions/features/event-doc/ask-event-doc-list.md) returns.
+2. An **append-only events store** (`<storeName>Events`, partition key `pk`, numeric sort key `sk`) — the ordered log every document is folded from. It has **no** secondary index on purpose: the local dev-server query processor can't target one, so all event reads go through the main table.
+3. A **storage drive** (`<storeName>edocs`, lower-cased) — the collection's blob bucket, holding each document's immutable uploaded assets (and later its derived runtime artifacts) under per-document prefixes.
+
+Point-in-time recovery is enabled on both tables.
+
+- **On AWS:** deploys two DynamoDB tables (via [defineKeyValueStore](../core/key-value-store.md)) and one S3 bucket (via [defineStorageDrive](../core/storage-drive.md)). All physical names are derived from `keyValueStoreName`, so a collection needs only that one name.
+
+```typescript
+import { defineEventDocSummary } from 'quidproquo-features';
+
+export default [
+  ...defineEventDocSummary('content'),
+];
+```
+
+Use `defineEventDocSummary` when you want to define the store separately from the routes — most importantly, when **several document types share one store**. Call it once, then call [defineEventDocRoutes](./event-doc-routes.md) per type. For the common single-type case, [defineEventDoc](./event-doc.md) does both in one call.
+
+## Signature
+
+```typescript
+function defineEventDocSummary(keyValueStoreName: string): QPQConfig;
+```
+
+## Parameters
+
+### `keyValueStoreName` — `string` (required)
+
+The collection's base store name. It is used directly as the summary store name and as the `storeName` that route definitions and store-context calls reference. The events table name (`` `${name}Events` ``) and asset bucket name (`` `${name}edocs`.toLowerCase() ``) are both derived from it, so the whole collection is addressed by this single name. It must match the `storeName` passed to any [defineEventDocRoutes](./event-doc-routes.md) (or [askEventDocProvideStore](#related)) for the same collection.
+
+## Examples
+
+```typescript
+import { defineEventDocSummary } from 'quidproquo-features';
+import { defineEventDocRoutes } from 'quidproquo-features';
+
+// One shared store, two document types served on different paths.
+export default [
+  ...defineEventDocSummary('content'),
+  ...defineEventDocRoutes({ storeName: 'content', type: 'article', basePath: '/articles' }),
+  ...defineEventDocRoutes({ storeName: 'content', type: 'page', basePath: '/pages' }),
+];
+```
+
+## Related
+
+- [defineEventDocRoutes](./event-doc-routes.md) — mounts the HTTP routes against a store declared here (one per type).
+- [defineEventDoc](./event-doc.md) — declares this store *and* its routes together for the single-type case.
+- [defineKeyValueStore](../core/key-value-store.md) / [defineStorageDrive](../core/storage-drive.md) — the core config settings this helper composes.
+- **Reading the store from a custom story:** wrap data calls in `askEventDocProvideStore({ storeName, type }, ...)` (from quidproquo-features) so getters like [askEventDocGetById](../../actions/features/event-doc/ask-event-doc-get-by-id.md) resolve the right collection.

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

@@ -0,0 +1,75 @@
+---
+title: defineEventDoc
+description: Define an event-sourced document collection — its stores plus its HTTP routes — in one call.
+---
+
+# defineEventDoc
+
+Defines a complete **event-document collection**: the data stores that hold it *and* the HTTP routes that serve it, in a single call. This is the all-in-one helper for the common **one-store-one-type** case. It returns a `QPQConfig` (an array of config settings) that you spread into a service's infrastructure default export.
+
+An event document is not stored as a mutable row. It is derived by folding an ordered, append-only log of events. `defineEventDoc` provisions that log (plus a queryable summary table and a blob bucket) and mounts the REST routes that create documents, append events, read them back, and resolve their draft/published versions.
+
+- **On AWS:** deploys everything [defineEventDocSummary](./event-doc-summary.md) deploys (two DynamoDB tables — a summary table and an append-only events table — plus an S3 bucket for assets) and everything [defineEventDocRoutes](./event-doc-routes.md) deploys (the API Gateway routes and their Lambda handlers). It creates no infrastructure of its own; it is exactly `[defineEventDocSummary(options.storeName), defineEventDocRoutes(options)]`.
+
+```typescript
+import { defineEventDoc } from 'quidproquo-features';
+
+export default [
+  ...defineEventDoc({
+    storeName: 'content',
+    type: 'article',
+    basePath: '/articles',
+    routeAuthSettings: { userDirectoryName: 'editors' },
+  }),
+];
+```
+
+## When to use `defineEventDoc` vs `defineEventDocSummary` + `defineEventDocRoutes`
+
+`defineEventDoc` defines the store **and** the routes together, so it assumes exactly one document `type` per store. If you want several document types to share one physical store (one summary table, one events table, one bucket), you must not define the store more than once. In that case, call [defineEventDocSummary](./event-doc-summary.md) **once** for the shared store, then [defineEventDocRoutes](./event-doc-routes.md) **per type** — each with the same `storeName` but a different `type` and `basePath`. Use `defineEventDoc` whenever the store backs a single type.
+
+## Signature
+
+```typescript
+function defineEventDoc(options: EventDocRoutesOptions): QPQConfig;
+```
+
+## Parameters
+
+`defineEventDoc` takes the same `EventDocRoutesOptions` object as [defineEventDocRoutes](./event-doc-routes.md); `options.storeName` is also passed straight through to [defineEventDocSummary](./event-doc-summary.md). See the [defineEventDocRoutes parameter reference](./event-doc-routes.md#parameters) for every field.
+
+| Property | Type | Required | Description |
+| --- | --- | --- | --- |
+| `storeName` | `string` | yes | Name of the summary store to create and serve. Also derives the events table and asset bucket names. |
+| `type` | `string` | yes | The document type this collection holds — the store's partition value, so one store can (via the split helpers) hold several types. |
+| `basePath` | `` `/${string}` `` | yes | URL prefix the routes mount under, e.g. `/articles`. |
+| `routeAuthSettings` | `RouteAuthSettings` | no | Auth for the mounted routes. Omit to leave them open — mutations then have no user to attribute. |
+| `version` | `number` | no | Route version prefix (`/v{version}`), default `1`. |
+| `eventValidator` | `string` | no | Inline-function name run on every append to reject invalid events. |
+| `eventRenderer` | `string` | no | Inline-function name that folds + renders the log to HTML; mounting it adds a `GET {basePath}/{id}/render` route. |
+
+## Examples
+
+```typescript
+import { defineEventDoc } from 'quidproquo-features';
+
+export default [
+  // A single "article" collection with authenticated mutations.
+  ...defineEventDoc({
+    storeName: 'content',
+    type: 'article',
+    basePath: '/articles',
+    routeAuthSettings: { userDirectoryName: 'editors' },
+    eventValidator: 'validateArticleEvent',
+    eventRenderer: 'renderArticle',
+  }),
+];
+```
+
+## Related
+
+- [defineEventDocSummary](./event-doc-summary.md) — the store half of this helper; call it directly when several types share one store.
+- [defineEventDocRoutes](./event-doc-routes.md) — the routes half; call it per type in the split setup.
+- [defineKeyValueStore](../core/key-value-store.md) / [defineStorageDrive](../core/storage-drive.md) — the underlying core config the summary helper composes.
+- **Reading a document in your own stories:** [askEventDocGetByIdOrThrow](../../actions/features/event-doc/ask-event-doc-get-by-id.md), [askEventDocList](../../actions/features/event-doc/ask-event-doc-list.md), and the [version reads](../../actions/features/event-doc/ask-event-doc-get-draft.md).
+- **Creating a document in your own stories:** [askEventDocCreate](../../actions/features/event-doc/ask-event-doc-create.md).

package/template/docusaurus/docs/config/features/versioned-route.md

@@ -0,0 +1,85 @@
+---
+title: defineVersionedRoute
+description: Define an HTTP route under a versioned path prefix (/v1, /v2, …) for API versioning.
+---
+
+# defineVersionedRoute
+
+Defines an HTTP route whose path is prefixed with an API version segment (`/v1`, `/v2`, …). It is a thin wrapper over the webserver [defineRoute](../webserver/route.md): the only difference is that it prepends `/v{version}` to the path before delegating, so you can publish multiple concurrent versions of an endpoint without repeating the prefix at every call site.
+
+Versioning here is purely **path-based** — there is no content negotiation or header inspection. `defineVersionedRoute('GET', '/users', runtime, {}, 2)` is exactly `defineRoute('GET', '/v2/users', runtime, {})`. Callers select a version by the URL they request; you ship a new version by declaring the same route with a higher `version` (and a new runtime), and retire an old one by removing its declaration.
+
+`defineVersionedRoute` returns an **array** containing the single `defineRoute` setting — spread it into your service's route config.
+
+- **On AWS:** identical to [defineRoute](../webserver/route.md) — routes are not individual infrastructure; API Gateway proxies every request to the API Lambda, which matches the full (version-prefixed) path at runtime.
+
+```typescript
+import { defineVersionedRoute } from 'quidproquo-features';
+
+export default [
+  // Served at GET /v1/users/{userId}
+  ...defineVersionedRoute('GET', '/users/{userId}', '/src/routes/users/getUser::getUser'),
+];
+```
+
+## Signature
+
+```typescript
+function defineVersionedRoute(
+  method: HTTPMethod,
+  path: string,
+  runtime: QpqFunctionRuntime,
+  options?: RouteOptions,
+  version?: number,
+): RouteQPQWebServerConfigSetting[];
+```
+
+## Parameters
+
+### `method` — `HTTPMethod` (required)
+
+The HTTP method to match — `'GET' | 'HEAD' | 'POST' | 'PUT' | 'DELETE' | 'CONNECT' | 'OPTIONS' | 'PATCH'`.
+
+### `path` — `string` (required)
+
+The URL path **without** the version prefix, e.g. `'/users/{userId}'`. The `/v{version}` segment is prepended for you. Path parameters are written with braces (`{userId}`).
+
+### `runtime` — `QpqFunctionRuntime` (required)
+
+A reference to the story that handles the request, usually a relative path string of the form `'/path/to/file::exportedFunctionName'`. Passed straight through to [defineRoute](../webserver/route.md).
+
+### `options` — `RouteOptions` (optional, default `{}`)
+
+Per-route CORS and auth options, forwarded unchanged to [defineRoute](../webserver/route.md) — `allowedOrigins`, `routeAuthSettings` (user directory, scopes, api keys). See [defineRoute](../webserver/route.md#options--genericrouteoptionsapikeyreference--string-optional) for the full shape.
+
+### `version` — `number` (optional, default `1`)
+
+The version number used to build the path prefix. `1` produces `/v1…`, `2` produces `/v2…`, and so on.
+
+## Examples
+
+```typescript
+import { defineVersionedRoute } from 'quidproquo-features';
+
+export default [
+  // v1 — the original handler
+  ...defineVersionedRoute('GET', '/users/{userId}', '/src/routes/users/v1/getUser::getUser'),
+
+  // v2 — a new handler at /v2/users/{userId}, kept side-by-side with v1
+  ...defineVersionedRoute('GET', '/users/{userId}', '/src/routes/users/v2/getUser::getUser', {}, 2),
+
+  // Authenticated v2 write endpoint
+  ...defineVersionedRoute(
+    'POST',
+    '/users',
+    '/src/routes/users/v2/create::createUser',
+    { routeAuthSettings: { userDirectoryName: 'users', scopes: ['users:write'] } },
+    2,
+  ),
+];
+```
+
+## Related
+
+- [defineRoute](../webserver/route.md) — the underlying route setting this wraps; see it for how routes are matched and served.
+- [defineDefaultRouteOptions](../webserver/default-route-options.md) — service-wide CORS/auth defaults merged into each route.

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

@@ -0,0 +1 @@
+{ "label": "quidproquo-neo4j", "position": 5, "link": { "type": "generated-index", "description": "Neo4j graph database config from quidproquo-neo4j." } }

package/template/docusaurus/docs/config/neo4j/graph-database-neo4j.md

@@ -0,0 +1,122 @@
+---
+title: defineGraphDatabaseNeo4j
+description: Define a Neo4j-backed graph database that the core graph-database action queries with openCypher.
+---
+
+# defineGraphDatabaseNeo4j
+
+Defines a **Neo4j-backed graph database**. It registers everything a service needs to run [openCypher](https://opencypher.org/) queries against a [Neo4j Aura](https://neo4j.com/cloud/aura/) instance while keeping the same story-facing API as a core graph database.
+
+Stories still query the database by name with [askGraphDatabaseExecuteOpenCypherQuery](../../actions/core/graph-database/ask-graph-database-execute-open-cypher-query.md), and they receive the exact same [`GraphCypherResponse`](../../actions/core/graph-database/ask-graph-database-execute-open-cypher-query.md#returns) result shape — nodes, relationships, and scalars. The only difference from the core [defineGraphDatabase](../core/graph-database.md) is the backing engine: `defineGraphDatabase` deploys an Amazon Neptune cluster, whereas `defineGraphDatabaseNeo4j` points the same action at a hosted Neo4j instance. You choose one or the other per database name; the story code that queries it is identical either way.
+
+It ships as a separate package. Import it from `quidproquo-neo4j`:
+
+```typescript
+import { defineGraphDatabaseNeo4j } from 'quidproquo-neo4j';
+
+export default [
+  defineGraphDatabaseNeo4j('social-graph'),
+];
+```
+
+- **On AWS:** this define does **not** deploy a database cluster. Neo4j is hosted externally (Neo4j Aura); the define instead wires up the pieces that let stories reach it. It contributes:
+  - a [parameter](../core/parameter.md) named `neo4j-<databaseName>-instance` holding the Aura instance id,
+  - a [secret](../core/secret.md) named `neo4j-<databaseName>-password` holding the database password,
+  - an **action-processor override** that replaces the core graph-database processor so `askGraphDatabaseExecuteOpenCypherQuery` runs against Neo4j instead of Neptune, and
+  - a daily [recurring schedule](../core/recurring-schedule.md) (`keepAlive`, `0 0 * * ? *` — midnight UTC) that runs a trivial `RETURN 1` query to keep the instance warm.
+
+## How it connects
+
+The action-processor override resolves the connection at query time rather than at deploy time. When a story runs [askGraphDatabaseExecuteOpenCypherQuery](../../actions/core/graph-database/ask-graph-database-execute-open-cypher-query.md), the Neo4j processor:
+
+1. reads the instance id from the `neo4j-<databaseName>-instance` parameter and the password from the `neo4j-<databaseName>-password` secret;
+2. rewrites the portable `qpqElementId(...)` helper in the query to Neo4j's native `elementId(...)` function;
+3. POSTs the query and its `params` to the Aura Query API at `https://<instance>.databases.neo4j.io:443/db/neo4j/query/v2`, authenticating with HTTP Basic auth as user `neo4j`;
+4. converts the raw Neo4j response back into the engine-agnostic [`GraphCypherResponse`](../../actions/core/graph-database/ask-graph-database-execute-open-cypher-query.md#returns) — mapping Neo4j nodes, relationships, and scalars onto the same `GraphNodeResult` / `GraphRelationshipResult` / `GraphScalarResult` kinds the core action returns.
+
+Because the result normalisation matches the core engine, switching a database between Neptune and Neo4j requires no change to the querying stories.
+
+## Signature
+
+```typescript
+function defineGraphDatabaseNeo4j(
+  databaseName: string,
+  options?: QPQConfigAdvancedGraphDatabaseNeo4jSettings,
+): QPQConfig;
+```
+
+Unlike the core `defineGraphDatabase` (which returns a single `GraphDatabaseQPQConfigSetting`), this returns a `QPQConfig` — the array of underlying settings described in the **On AWS** section above. Spread or nest it directly in a service's config array.
+
+## Parameters
+
+### `databaseName` — `string` (required)
+
+The name of the graph database. This is the name stories pass as the first argument to [askGraphDatabaseExecuteOpenCypherQuery](../../actions/core/graph-database/ask-graph-database-execute-open-cypher-query.md). It also derives the names of the generated parameter (`neo4j-<databaseName>-instance`) and secret (`neo4j-<databaseName>-password`).
+
+### `options` — `QPQConfigAdvancedGraphDatabaseNeo4jSettings` (optional)
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `owner` | `CrossModuleOwner<'graphDatabaseName'>` | – | Declares that this database is owned by **another** module/service, so the generated parameter, secret, and schedule resolve against that owner instead of creating local ones. `{ module, application, feature, environment, graphDatabaseName }` — all optional; unset parts default to the current service. |
+| `version` | `Neo4jVersion` | `Neo4jVersion.Version5` | Which Neo4j processor implementation to bind. Selects the action-processor override under `graphDatabaseOverride/<version>`. |
+
+### `Neo4jVersion`
+
+Selects the Neo4j processor version to wire up.
+
+| Member | Value | Description |
+| --- | --- | --- |
+| `Neo4jVersion.Version5` | `'version5'` | Targets Neo4j 5.x via the Aura Query API v2 (the default). |
+
+## Configuring the instance and password
+
+`defineGraphDatabaseNeo4j` declares the parameter and secret but does not set their values — you supply those where you'd normally set a parameter and a secret for the service:
+
+- **`neo4j-<databaseName>-instance`** — the Aura instance id used to build the endpoint host `<instance>.databases.neo4j.io`. See [defineParameter](../core/parameter.md).
+- **`neo4j-<databaseName>-password`** — the password for the `neo4j` user, stored as a [secret](../core/secret.md).
+
+## Examples
+
+```typescript
+import { defineGraphDatabaseNeo4j, Neo4jVersion } from 'quidproquo-neo4j';
+
+export default [
+  // A Neo4j-backed graph database for this service
+  defineGraphDatabaseNeo4j('social-graph'),
+
+  // Pin the processor version explicitly
+  defineGraphDatabaseNeo4j('analytics-graph', {
+    version: Neo4jVersion.Version5,
+  }),
+
+  // Use a database whose parameter/secret are owned by another module
+  defineGraphDatabaseNeo4j('shared-graph', {
+    owner: { module: 'graph-service' },
+  }),
+];
+```
+
+Query it exactly as you would a core graph database — the story code doesn't know or care that Neo4j backs it:
+
+```typescript
+import { askGraphDatabaseExecuteOpenCypherQuery, GraphDatabaseInstanceType } from 'quidproquo-core';
+
+export function* askFindFriends(userId: string) {
+  const response = yield* askGraphDatabaseExecuteOpenCypherQuery(
+    'social-graph',
+    GraphDatabaseInstanceType.Read,
+    'MATCH (u:User { id: $userId })-[:FOLLOWS]->(f:User) RETURN f',
+    { userId },
+  );
+
+  return response.results.map((row) => row.f);
+}
+```
+
+## Related
+
+- [defineGraphDatabase](../core/graph-database.md) — the core (Neptune-backed) graph database; same query API, different backing engine.
+- [askGraphDatabaseExecuteOpenCypherQuery](../../actions/core/graph-database/ask-graph-database-execute-open-cypher-query.md) — run an openCypher query against a database defined here; documents the shared result shape.
+- [defineSecret](../core/secret.md) — where the `neo4j-<databaseName>-password` secret's value is supplied.
+- [defineParameter](../core/parameter.md) — where the `neo4j-<databaseName>-instance` value is supplied.
+- [defineRecurringSchedule](../core/recurring-schedule.md) — the mechanism behind the daily keep-alive.

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

@@ -0,0 +1,8 @@
+{
+  "label": "quidproquo-webserver",
+  "position": 2,
+  "link": {
+    "type": "generated-index",
+    "description": "Config settings (define* functions) exported from quidproquo-webserver — APIs, routes, websockets, auth, DNS, and web hosting."
+  }
+}

package/template/docusaurus/docs/config/webserver/api-key.md

@@ -0,0 +1,87 @@
+---
+title: defineApiKey
+description: Declare an API key — a shared secret (an AWS API Gateway API key) used to authenticate requests to a route.
+---
+
+# defineApiKey
+
+Declares an **API key**: a named shared secret that callers present in the `x-api-key` request header to authenticate against a route. Unlike user-directory auth (which identifies a *user* via an access token), an API key identifies a *caller* — typically a machine, service, or third party. You declare the key here, reference it from a route's `routeAuthSettings.apiKeys`, and the runtime validates the presented header against the real key value.
+
+- **On AWS:** deploys an **API Gateway API key** (`aws_apigateway.ApiKey` via `QpqWebserverApiKeyConstruct` in `quidproquo-deploy-awscdk`). The key is created with `enabled: true`, its physical name is derived from the config (prefixed with application/module/environment), and its CloudFormation-exported id is what the runtime resolves to fetch the real key value during validation. If `value` is omitted, AWS generates the key value automatically.
+
+```typescript
+import { defineApiKey } from 'quidproquo-webserver';
+
+export default [
+  // AWS generates the key value
+  defineApiKey('partner-api'),
+];
+```
+
+## Signature
+
+```typescript
+function defineApiKey(
+  apiKeyName: string,
+  options?: QPQConfigAdvancedApiKeySettings,
+): ApiKeyQPQWebServerConfigSetting;
+```
+
+## Parameters
+
+### `apiKeyName` — `string` (required)
+
+The name of the key. This is the `name` you reference from a route (`routeAuthSettings.apiKeys: ['partner-api']`) and the key's `uniqueKey` within the config. On AWS it is used to derive the physical API Gateway key name.
+
+### `options` — `QPQConfigAdvancedApiKeySettings` (optional)
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `value` | `string` | – | The explicit key value (the secret string callers present). When omitted, AWS generates the value automatically — retrieve it from the API Gateway console/API after deploy. Provide a value when you need to pin a known secret. |
+| `description` | `string` | – | Human-readable description attached to the API Gateway key. |
+| `deprecated` | `boolean` | `false` | Inherited from `QPQConfigAdvancedSettings`; marks the setting as deprecated. |
+
+## Referencing a key from a route
+
+A key does nothing on its own — a route opts into it via `routeAuthSettings.apiKeys`, which accepts either a plain key name or an `ApiKeyReference` object (used to reference a key owned by another application/service):
+
+```typescript
+export interface ApiKeyReference {
+  name: string;
+  applicationName?: string;
+  serviceName?: string;
+}
+```
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `name` | `string` | The key name, matching the `apiKeyName` passed to `defineApiKey`. |
+| `applicationName` | `string` | Application that owns the key, when it lives in a different application. Defaults to the current application. |
+| `serviceName` | `string` | Service/module that owns the key, when it lives in a different service. Defaults to the current service. |
+
+When a route lists `apiKeys`, the runtime reads the `x-api-key` header from the incoming request and validates it with [askApiKeyValidationValidate](../../actions/webserver/api-key-validation/ask-api-key-validation-validate.md). A request missing the header, or presenting a value that matches none of the referenced keys, is rejected.
+
+## Examples
+
+```typescript
+import { defineApiKey } from 'quidproquo-webserver';
+
+export default [
+  // Let AWS generate the secret
+  defineApiKey('partner-api', {
+    description: 'Key issued to the partner integration',
+  }),
+
+  // Pin a known value (e.g. seeded from a secret at deploy time)
+  defineApiKey('internal-cron', {
+    value: process.env.CRON_API_KEY,
+    description: 'Used by the scheduled internal caller',
+  }),
+];
+```
+
+## Related
+
+- [askApiKeyValidationValidate](../../actions/webserver/api-key-validation/ask-api-key-validation-validate.md) — the action that validates a presented key value against declared keys at runtime.
+- **Routes and APIs** reference a key through `routeAuthSettings.apiKeys` (see the `defineRoute` / `defineApi` config settings in quidproquo-webserver).
+- [defineAuthSystem](./auth-system.md) — the other half of route auth: user-directory / access-token authentication.

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

@@ -0,0 +1,75 @@
+---
+title: defineApi
+description: Define an HTTP API — the public web endpoint (a custom subdomain fronting an API Gateway REST API on AWS) that a service's routes are served under.
+---
+
+# defineApi
+
+Defines an **API**: the public HTTP endpoint for a service. An API declares the subdomain and root domain the service is reachable on; every [route](./route.md) you declare in the same service is served under it. A service typically declares exactly one API.
+
+- **On AWS:** deploys a **regional API Gateway REST API** (`LambdaRestApi`, proxy mode, binary media types `*/*`) backed by a single Lambda that handles every route (`ApiQpqWebserverApiConstruct` in `quidproquo-deploy-awscdk`). The API is attached to a custom domain (`apiSubdomain.rootDomain`) via a base-path mapping keyed on the module name, so multiple modules can share one domain. Access logs (JSON, one-year retention) and CloudWatch metrics are enabled; a 5XX alarm is wired by default, plus 401/403 rate alarms when error notifications are configured. When WAF protection is enabled for the deploy, the shared regional Web ACL is associated with the stage.
+
+```typescript
+import { defineApi } from 'quidproquo-webserver';
+
+export default [
+  defineApi('api', 'example.com'),
+];
+```
+
+This serves the service's routes at `https://api.<module-base>.example.com/<module>/...`.
+
+## Signature
+
+```typescript
+function defineApi(
+  apiName: string,
+  rootDomain: string,
+  options?: QPQConfigAdvancedApiSettings,
+): ApiQPQWebServerConfigSetting;
+```
+
+## Parameters
+
+### `apiName` — `string` (required)
+
+The API's name and its `uniqueKey` within the config. Unless overridden by `options.subDomain`, it is also the **subdomain** the API is served on (so `defineApi('api', 'example.com')` serves on `api.<...>.example.com`).
+
+### `rootDomain` — `string` (required)
+
+The root domain the API is hosted under, e.g. `'example.com'`. The deploy derives the full hostname from this plus the environment/feature and the API subdomain, so the same config deploys to multiple environments without collisions.
+
+### `options` — `QPQConfigAdvancedApiSettings` (optional)
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `subDomain` | `string` | `apiName` | Override the subdomain the API is served on. Use it when the API name and the public subdomain should differ. |
+| `cloudflareApiKeySecretName` | `string` | – | Name of the secret holding the Cloudflare API key, used when DNS/records for the API are managed through Cloudflare. |
+| `virtualNetworkName` | `string` | – | Name of a `defineVirtualNetwork` (VPC) to place the API's Lambda in. Required to reach in-VPC data stores; the Lambda joins that network's bootstrap-created workload security group. |
+| `maxConcurrentExecutions` | `number` | – | Reserved concurrency for the API's Lambda — a cap **and** a guarantee on concurrent requests across all routes (one compute unit serves every route). Carved out of the account's shared concurrency pool. |
+| `deprecated` | `boolean` | `false` | Marks the API as deprecated. Inherited from `QPQConfigAdvancedSettings`. |
+
+## Examples
+
+```typescript
+import { defineApi, defineRoute } from 'quidproquo-webserver';
+
+export default [
+  // Serve on a custom subdomain, capped at 50 concurrent requests
+  defineApi('public', 'example.com', {
+    subDomain: 'api',
+    maxConcurrentExecutions: 50,
+  }),
+
+  // Routes declared in the same service are served under the API
+  defineRoute('GET', '/health', '/src/routes/health::getHealth'),
+];
+```
+
+## Related
+
+- [defineRoute](./route.md) — declares the individual method+path endpoints served under the API.
+- [defineDefaultRouteOptions](./default-route-options.md) — service-wide defaults (CORS, auth) merged into every route.
+- [defineServiceFunction](./service-function.md) — RPC-style callable functions, deployed as their own Lambdas rather than under the API.
+- [defineDomainCertificate](../config-aws/domain-certificate.md) — the ACM certificate for the API's domain (resolved with the same `rootDomain` prefixing).
+- [defineWafProtection](../config-aws/waf-protection.md) — opt the API Gateway stage into the app's WAF web ACL.