create-qpq-app 0.1.8 → 0.1.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-qpq-app",
-  "version": "0.1.8",
+  "version": "0.1.10",
   "description": "Scaffold a new quidproquo app — npx create-qpq-app my-app",
   "main": "./lib/commonjs/index.js",
   "module": "./lib/esm/index.js",
@@ -51,7 +51,7 @@
   },
   "devDependencies": {
     "@types/node": "^22.13.13",
-    "quidproquo-tsconfig": "0.1.8"
+    "quidproquo-tsconfig": "0.1.10"
   },
   "bin": {
     "create-qpq-app": "./lib/commonjs/bin/createQpqApp.js"

package/template/apps/qpqjs/deploy.config.json

@@ -9,13 +9,13 @@
     },
     "staging": {
       "platform": "aws",
-      "accountId": "761018864142",
+      "accountId": "061039804449",
       "region": "us-east-1"
     },
     "production": {
       "platform": "aws",
       "accountId": "761018864142",
-      "region": "us-east-1"
+      "region": "ap-southeast-2"
     },
     "local": {
       "platform": "docker"

package/template/apps/qpqjs/services/design/views/src/components/LandingPage/components/NavBar.tsx

@@ -15,25 +15,13 @@ export function NavBar() {
     <header className="nav">
       <div className="nav__inner">
         <a className="nav__brand" href="#top">
-          <svg aria-hidden="true" className="nav__mark" viewBox="0 0 32 32">
-            <rect
-              fill="rgba(34,211,238,0.08)"
-              height="26"
-              rx="7"
-              stroke="#22d3ee"
-              strokeWidth="1.6"
-              width="26"
-              x="3"
-              y="3"
-            />
+          <svg aria-hidden="true" className="nav__mark" viewBox="24.4 24.4 465.3 465.3">
             <path
-              d="M12 9l-4 7 4 7M20 9l4 7-4 7"
-              fill="none"
-              stroke="#8df6ff"
-              strokeLinecap="round"
-              strokeLinejoin="round"
-              strokeWidth="2.2"
+              d="M271.42,489.64h-10.72c-128.68,0-235.74-102.93-236.29-231.61S128.97,23.86,258.03,24.41c128.68.55,231.6,107.61,231.6,236.29v11.61c0,.09-.07.16-.16.16h-109.69c-.09,0-.16-.07-.16-.16v-12.61c0-65.9-53.82-123.71-119.7-125.24-69.89-1.62-127.08,55.57-125.46,125.46,1.53,65.89,59.34,119.71,125.24,119.71h11.72c.09,0,.16.07.16.16v109.69c0,.09-.07.16-.16.16Z"
+              fill="#22d3ee"
             />
+            <rect fill="#8df6ff" height="106.91" width="106.91" x="268.31" y="273.22" />
+            <rect fill="#8df6ff" height="106.91" width="106.91" x="375.62" y="380.53" />
           </svg>
           <span className="nav__name">
             quid<span className="nav__name-accent">pro</span>quo

package/template/apps/qpqjs/services/design/views/src/components/LandingPage/components/Packages.tsx

@@ -40,8 +40,7 @@ export function Packages() {
       <p className="section__kicker">the grid</p>
       <h2 className="section__title">A package for every layer</h2>
       <p className="section__sub">
-        Core defines the actions. Everything else is an implementation you plug
-        in.
+        Every layer is its own package, so you only pull in what you need.
       </p>
 
       <div className="package-groups">

package/template/apps/qpqjs/services/design/views/src/components/LandingPage/landing.css

@@ -355,6 +355,7 @@ em {
 }
 
 .nav__name {
+  position: relative;
   font-family: var(--font-display);
   font-size: 19px;
   font-weight: 600;
@@ -366,6 +367,49 @@ em {
   color: var(--cyan);
 }
 
+/* Glint overlay: the same glyphs stacked over the title, transparent except
+   for a narrow band clipped to the letterforms. It rests off-canvas, then
+   makes one eased sweep across per cycle. The band is two-tone so it reads
+   on both letter colors: the white half is invisible on the near-white
+   quid/quo but lights up the cyan pro, and the cyan half does the reverse.
+   The "/ ''" marks the duplicated text as decorative; browsers without that
+   syntax skip the overlay entirely, which just means no shimmer. */
+.nav__name::after {
+  content: 'quidproquo' / '';
+  position: absolute;
+  inset: 0;
+  color: transparent;
+  background-image: linear-gradient(
+    105deg,
+    rgba(255, 255, 255, 0) 38%,
+    rgba(255, 255, 255, 0.85) 45%,
+    rgba(34, 211, 238, 0.85) 53%,
+    rgba(34, 211, 238, 0) 60%
+  );
+  background-size: 250% 100%;
+  background-repeat: no-repeat;
+  background-position: 130% 0;
+  -webkit-background-clip: text;
+  background-clip: text;
+  animation: nav-name-shine 7s ease-in-out infinite;
+}
+
+@keyframes nav-name-shine {
+  0%,
+  72% {
+    background-position: 130% 0;
+  }
+  100% {
+    background-position: -130% 0;
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .nav__name::after {
+    animation: none;
+  }
+}
+
 .nav__links {
   display: flex;
   gap: 26px;

package/template/apps/qpqjs/services/shell/views/src/index.html

@@ -4,7 +4,7 @@
     <meta charset="UTF-8" />
     <link
       rel="icon"
-      href="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 32 32'%3E%3Crect x='3' y='3' width='26' height='26' rx='6' fill='%23071018' stroke='%2322d3ee' stroke-width='2'/%3E%3Cpath d='M12 9l-4 7 4 7M20 9l4 7-4 7' stroke='%237ff4ff' stroke-width='2.4' fill='none' stroke-linecap='round' stroke-linejoin='round'/%3E%3C/svg%3E"
+      href="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 32 32'%3E%3Crect x='1' y='1' width='30' height='30' rx='6' fill='%23071018'/%3E%3Cg transform='translate(4.5 4.5) scale(0.0494) translate(-24.4 -24.4)'%3E%3Cpath fill='%2322d3ee' d='M271.42,489.64h-10.72c-128.68,0-235.74-102.93-236.29-231.61S128.97,23.86,258.03,24.41c128.68.55,231.6,107.61,231.6,236.29v11.61c0,.09-.07.16-.16.16h-109.69c-.09,0-.16-.07-.16-.16v-12.61c0-65.9-53.82-123.71-119.7-125.24-69.89-1.62-127.08,55.57-125.46,125.46,1.53,65.89,59.34,119.71,125.24,119.71h11.72c.09,0,.16.07.16.16v109.69c0,.09-.07.16-.16.16Z'/%3E%3Crect fill='%238df6ff' x='268.31' y='273.22' width='106.91' height='106.91'/%3E%3Crect fill='%238df6ff' x='375.62' y='380.53' width='106.91' height='106.91'/%3E%3C/g%3E%3C/svg%3E"
     />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <meta

package/template/docusaurus/docs/actions/core/file/ask-file-generate-temporary-upload-secure-url.md

@@ -8,7 +8,7 @@ description: Generate a time-limited, signed URL that lets a client upload a fil
 Generates a temporary, signed URL that lets a client **upload** a single file directly to a [storage drive](../../../config/core/storage-drive.md). The bytes go straight to storage instead of through your service, which is ideal for large uploads from a browser. The URL grants write access to just that one path and stops working once it expires.
 
 - **Action type:** `FileActionType.GenerateTemporaryUploadSecureUrl`
-- **On AWS:** returns a SigV4 presigned S3 `PutObject` URL for the object. The expiry cannot exceed **7 days** — the maximum lifetime of a SigV4 presigned URL. If `contentType` is supplied it is bound into the signature, so the upload's `Content-Type` header must match.
+- **On AWS:** returns a SigV4 presigned S3 `PutObject` URL for the object. The expiry cannot exceed **7 days** — the maximum lifetime of a SigV4 presigned URL. If `contentType` and/or `contentDisposition` are supplied they are bound into the signature, so the upload's `Content-Type` / `Content-Disposition` headers must match, and S3 stores them so later downloads serve the object with the same headers.
 
 ```typescript
 import { askFileGenerateTemporaryUploadSecureUrl } from 'quidproquo-core';
@@ -34,6 +34,7 @@ function* askFileGenerateTemporaryUploadSecureUrl(
   expirationMs: number,
   advancedOptions?: {
     contentType?: string;
+    contentDisposition?: string;
   },
   scope?: string,
 ): AskResponse<string>;
@@ -54,6 +55,7 @@ function* askFileGenerateTemporaryUploadSecureUrl(
 | Property | Type | Default | Description |
 | --- | --- | --- | --- |
 | `contentType` | `string` | – | Pins the `Content-Type` of the upload into the signature. When set, the client must send a matching `Content-Type` header or the `PUT` is rejected. |
+| `contentDisposition` | `string` | – | Pins the `Content-Disposition` of the upload into the signature (e.g. `inline` so a stored PDF previews in an `<iframe>` instead of force-downloading). When set, the client must send a matching `Content-Disposition` header, and S3 stores it so later downloads serve it back. |
 
 ## Returns
 

package/template/docusaurus/docs/actions/core/user-directory/ask-user-directory-revoke-refresh-token.md

@@ -0,0 +1,56 @@
+---
+title: askUserDirectoryRevokeRefreshToken
+description: Revoke a single refresh token — the "log out this device" primitive.
+---
+
+# askUserDirectoryRevokeRefreshToken
+
+Revokes a single refresh token (and every access token minted from it) against a [user directory](../../../config/core/user-directory.md). This is the "log out this device" primitive: other sessions belonging to the same user, holding different refresh tokens, are unaffected.
+
+- **Action type:** `UserDirectoryActionType.RevokeRefreshToken`
+- **On AWS:** issues Cognito `RevokeToken`. Requires token revocation to be enabled on the app client (the CDK default); a disabled client surfaces as an unmapped error.
+
+```typescript
+import { askUserDirectoryRevokeRefreshToken } from 'quidproquo-core';
+
+export function* askLogOutThisDevice(refreshToken: string) {
+  yield* askUserDirectoryRevokeRefreshToken('app-users', refreshToken);
+}
+```
+
+## Signature
+
+```typescript
+function* askUserDirectoryRevokeRefreshToken(
+  userDirectoryName: string,
+  refreshToken: string,
+): AskResponse<void>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `userDirectoryName` | `string` | Name of the directory — must match a directory declared with [defineUserDirectory](../../../config/core/user-directory.md). |
+| `refreshToken` | `string` | The refresh token to revoke (from `AuthenticationInfo.refreshToken`). |
+
+## Returns
+
+`void` — the story resumes once the token has been revoked.
+
+## Errors
+
+| Error | Meaning |
+| --- | --- |
+| `UserDirectoryRevokeRefreshTokenErrorTypeEnum.Unauthorized` | The refresh token is invalid or already revoked, or revocation is disabled on the app client. |
+| `UserDirectoryRevokeRefreshTokenErrorTypeEnum.LimitExceeded` | Too many attempts; back off and retry later. |
+
+## Notes
+
+Access tokens already minted from the revoked refresh token remain valid until they expire — they're stateless JWTs and can't be individually invalidated. Keep `accessTokenValidityMinutes` (see [defineUserDirectory](../../../config/core/user-directory.md#parameters)) short to shrink that window.
+
+## Related
+
+- [askUserDirectorySignOutUser](./ask-user-directory-sign-out-user.md) — revokes **every** refresh token for the user, not just one.
+- [askUserDirectoryRefreshToken](./ask-user-directory-refresh-token.md) — exchanges a refresh token for fresh tokens.
+- [defineUserDirectory](../../../config/core/user-directory.md) — declares the directory.

package/template/docusaurus/docs/actions/core/user-directory/ask-user-directory-sign-out-user.md

@@ -0,0 +1,52 @@
+---
+title: askUserDirectorySignOutUser
+description: Globally sign a user out by revoking every refresh token issued to them.
+---
+
+# askUserDirectorySignOutUser
+
+Globally signs a user out: revokes **every** refresh token issued to the owner of the supplied access token, against a [user directory](../../../config/core/user-directory.md). Use this for a "sign out of all devices" action or as a compromise response, since a stolen/persisted refresh token stops working for every session at once.
+
+- **Action type:** `UserDirectoryActionType.SignOutUser`
+- **On AWS:** issues Cognito `GlobalSignOut`. Authorized by the access token itself — no user directory name or IAM is needed to identify the user, Cognito resolves it from the token.
+
+```typescript
+import { askUserDirectorySignOutUser } from 'quidproquo-core';
+
+export function* askLogOutEverywhere(accessToken: string) {
+  yield* askUserDirectorySignOutUser(accessToken);
+}
+```
+
+## Signature
+
+```typescript
+function* askUserDirectorySignOutUser(accessToken: string): AskResponse<void>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `accessToken` | `string` | The signed-in user's access token, identifying whose sessions to sign out. |
+
+## Returns
+
+`void` — the story resumes once every session has been revoked.
+
+## Errors
+
+| Error | Meaning |
+| --- | --- |
+| `UserDirectorySignOutUserErrorTypeEnum.Unauthorized` | The access token is missing, invalid, or expired — there is nothing to revoke. |
+| `UserDirectorySignOutUserErrorTypeEnum.LimitExceeded` | Too many attempts; back off and retry later. |
+
+## Notes
+
+Access tokens already minted remain valid until they expire — they're stateless JWTs and can't be individually invalidated. Keep `accessTokenValidityMinutes` (see [defineUserDirectory](../../../config/core/user-directory.md#parameters)) short to shrink that window.
+
+## Related
+
+- [askUserDirectoryRevokeRefreshToken](./ask-user-directory-revoke-refresh-token.md) — revokes only a single session, leaving the user's other devices signed in.
+- [askUserDirectoryReadAccessToken](./ask-user-directory-read-access-token.md) / [askUserDirectoryDecodeAccessToken](./ask-user-directory-decode-access-token.md) — inspect an access token.
+- [defineUserDirectory](../../../config/core/user-directory.md) — declares the directory.

package/template/docusaurus/docs/actions/features/event-doc/ask-apply-event-doc-event.md

@@ -15,22 +15,24 @@ A **purely declarative** way to apply an event-doc event: the story yields an `e
 import { askApplyEventDocEvent } from 'quidproquo-features';
 
 export function* askTenantSetBrand(data: TenantSetBrandData) {
-  yield* askApplyEventDocEvent(TenantEffect.setBrand, data);
+  yield* askApplyEventDocEvent<SetBrandEffect>(TenantEffect.setBrand, data);
 }
 ```
 
 ## Signature
 
 ```typescript
-function* askApplyEventDocEvent(eventType: string, data: unknown): AskResponse<void>;
+function* askApplyEventDocEvent<E extends Effect<string, any>>(eventType: E['type'], data: E['payload']): AskResponse<void>;
 ```
 
+Typed like [askStateDispatchEffect](../../core/state/ask-state-dispatch.md#effect-and-askstatedispatcheffect): an event-doc event IS a special kind of effect (`Effect<type, data>`), so an action creator passes its effect type as `E` and gets `data` checked against it.
+
 ## Parameters
 
 | Parameter | Type | Description |
 | --- | --- | --- |
-| `eventType` | `string` | The effect/event type discriminant, matched by the reducer that folds the document and by the registered processor. |
-| `data` | `unknown` | The typed domain data for the event, opaque to this action itself. |
+| `eventType` | `E['type']` | The effect/event type discriminant, matched by the reducer that folds the document and by the registered processor. |
+| `data` | `E['payload']` | The typed domain data for the event, checked against `E`, opaque to this action itself. |
 
 ## Returns
 

package/template/docusaurus/docs/actions/features/event-doc/ask-apply-transient-event-doc-event.md

@@ -0,0 +1,53 @@
+---
+title: askApplyTransientEventDocEvent
+description: Declaratively apply an event-doc event into a never-saved transient group, dropped wholesale by key instead of persisted.
+---
+
+# askApplyTransientEventDocEvent
+
+The never-saved sibling of [askApplyEventDocEvent](./ask-apply-event-doc-event.md): the story yields an `eventType` and its `data` under a `transientKey`, and the event lands in a transient group that is never persisted, only dropped wholesale by that key. It is the event-sourced way to represent observations that must not survive past their source, such as websocket progress messages, where dropping the key (usually a connection id) reverts the folded view reactively instead of leaving a stuck UI state behind.
+
+- **Action type:** `EventDocActionType.ApplyTransientEvent`
+- Transient applies are client-runtime-only by definition: a server "authors" them only via messages a client story processes, never a backend `ApplyTransientEvent` processor. An unbound or backend apply fails loudly, the same as an unbound `ApplyEvent`.
+- The version stamped on the resulting event is not passed by the caller — the binding that applies it stamps its own configured schema version, the same as `askApplyEventDocEvent`.
+
+```typescript
+import { askApplyTransientEventDocEvent } from 'quidproquo-features';
+
+export function* askZipReportProgress(connectionId: string, data: ZipProgressData) {
+  yield* askApplyTransientEventDocEvent<ZipProgressEffect>(connectionId, ZipEffect.Progress, data);
+}
+```
+
+## Signature
+
+```typescript
+function* askApplyTransientEventDocEvent<E extends Effect<string, any>>(
+  transientKey: string,
+  eventType: E['type'],
+  data: E['payload'],
+): AskResponse<void>;
+```
+
+Typed like [askApplyEventDocEvent](./ask-apply-event-doc-event.md): an event-doc event IS a special kind of effect (`Effect<type, data>`), so an action creator passes its effect type as `E` and gets `data` checked against it.
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `transientKey` | `string` | Names the drop unit for this event, usually a websocket connection id. Dropping a key clears every event committed under it. |
+| `eventType` | `E['type']` | The effect/event type discriminant, matched by the reducer that folds the document. |
+| `data` | `E['payload']` | The typed domain data for the event, checked against `E`, opaque to this action itself. |
+
+## Returns
+
+`AskResponse<void>` — applying a transient event never returns a value; a binding that fails to apply it surfaces the failure as its own runtime's error state rather than throwing back through this call.
+
+## Notes
+
+- This is the contract only — it carries no default behavior on its own. In the event-doc workspace, the binding registered for a slot routes `ApplyTransientEvent` into that slot's transient group under `transientKey`; outside a workspace bind, calling it fails loudly.
+- Transient events never influence the persistable log or validation: they are excluded from the log every save and validator reads, and are dropped wholesale by `transientKey` rather than removed one at a time.
+
+## Related
+
+- [askApplyEventDocEvent](./ask-apply-event-doc-event.md) — the persisted sibling this action mirrors.

package/template/docusaurus/docs/actions/features/event-doc/ask-event-doc-generate-asset-upload-url.md

@@ -14,7 +14,7 @@ These three helpers cover the two flows: presigned URLs for a browser to upload/
 
 ## askEventDocGenerateAssetUploadUrl
 
-Mints a guid and a short-lived presigned `PUT` URL the client uploads the bytes to. Returns the guid (as `assetId`) so the caller can record it in a domain event. This is one complete storage operation — no bytes pass through your service.
+Mints a guid and a short-lived presigned `PUT` URL the client uploads the bytes to. Returns the guid (as `assetId`) so the caller can record it in a domain event. This is one complete storage operation — no bytes pass through your service. An optional `contentDisposition` is baked into the upload (the client must `PUT` the matching header) so the stored object serves with it, e.g. `inline` so a rendered PDF previews in an `<iframe>` instead of downloading.
 
 ```typescript
 import { askEventDocGenerateAssetUploadUrl } from 'quidproquo-features';
@@ -32,6 +32,7 @@ export function* startImageUpload(docId: string) {
 function* askEventDocGenerateAssetUploadUrl(
   docId: string,
   contentType: string,
+  contentDisposition?: string,
 ): AskResponse<EventDocAssetUploadUrl>;
 ```
 
@@ -41,6 +42,7 @@ function* askEventDocGenerateAssetUploadUrl(
 | --- | --- | --- |
 | `docId` | `string` | The document the asset belongs to — determines the `<docId>/assets/<guid>` blob key. |
 | `contentType` | `string` | The MIME type the client will upload; pinned into the presigned `PUT` URL. |
+| `contentDisposition` | `string` | Optional. Pinned into the presigned `PUT` URL so the stored asset serves with it, e.g. `inline` to preview instead of force-download. |
 
 ### Returns
 

package/template/docusaurus/docs/actions/webserver/service-function/ask-service-function-execute.md

@@ -13,14 +13,20 @@ Invokes a [service function](../../../config/webserver/service-function.md) —
 ```typescript
 import { askServiceFunctionExecute } from 'quidproquo-webserver';
 
-interface ResizeRequest { drive: string; filepath: string; width: number; }
-interface ResizeResult { thumbnailPath: string; }
+interface ResizeRequest {
+  drive: string;
+  filepath: string;
+  width: number;
+}
+interface ResizeResult {
+  thumbnailPath: string;
+}
 
 export function* askMakeThumbnail(filepath: string) {
   const result = yield* askServiceFunctionExecute<ResizeResult, ResizeRequest>(
-    'media',        // service name
-    'resizeImage',  // function name
-    { drive: 'uploads', filepath, width: 256 },
+    'media', // service name
+    'resizeImage', // function name
+    { drive: 'uploads', filepath, width: 256 }
   );
 
   return result.thumbnailPath;
@@ -34,18 +40,18 @@ function* askServiceFunctionExecute<R, T>(
   service: string,
   functionName: string,
   payload: T,
-  isAsync?: boolean,
+  isAsync?: boolean
 ): AskResponse<R>;
 ```
 
 ## Parameters
 
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| `service` | `string` | – | Name of the service that owns the target function. |
-| `functionName` | `string` | – | Name of the [service function](../../../config/webserver/service-function.md) to invoke (its `functionName`, which defaults to the story name). |
-| `payload` | `T` | – | The typed payload passed to the function's story. |
-| `isAsync` | `boolean` | `false` | When `false`, wait for and return the result. When `true`, invoke fire-and-forget and resolve without a result. |
+| Parameter      | Type      | Default | Description                                                                                                                                     |
+| -------------- | --------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| `service`      | `string`  | –       | Name of the service that owns the target function.                                                                                              |
+| `functionName` | `string`  | –       | Name of the [service function](../../../config/webserver/service-function.md) to invoke (its `functionName`, which defaults to the story name). |
+| `payload`      | `T`       | –       | The typed payload passed to the function's story.                                                                                               |
+| `isAsync`      | `boolean` | `false` | When `false`, wait for and return the result. When `true`, invoke fire-and-forget and resolve without a result.                                 |
 
 ## Returns
 
@@ -54,5 +60,5 @@ function* askServiceFunctionExecute<R, T>(
 ## Related
 
 - [defineServiceFunction](../../../config/webserver/service-function.md) — declares the function this action invokes.
-- [askServiceRequest](../service/ask-service-request.md) — a related request to another service, dispatched by method name.
+- [askServiceRequest](../../features/web-socket-queue/ask-service-request.md) — a related request to another service, dispatched by method name.
 - [askCatch](../../core/system/ask-catch.md) — catch errors thrown by the invoked function.

package/template/docusaurus/docs/config/core/bundle-options.md

@@ -1,6 +1,6 @@
 ---
 title: defineBackendBundleOptions / defineFrontendBundleOptions
-description: Tune how the service's backend and frontend bundles are built: externals, ignored modules, suppressed warnings, and shared frontend singletons.
+description: "Tune how the service's backend and frontend bundles are built: externals, ignored modules, suppressed warnings, and shared frontend singletons."
 ---
 
 # defineBackendBundleOptions / defineFrontendBundleOptions

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

@@ -43,6 +43,7 @@ The name of the directory. This is the name you pass as the `userDirectoryName`
 | `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). |
+| `accessTokenValidityMinutes` | `number` | `60` (Cognito default) | Access/ID token (JWT) lifetime in minutes (Cognito allows 5–1440). Shorter shrinks the window in which a revoked session's still-valid access token keeps working, since access tokens are stateless and can't be revoked before they expire — see [askUserDirectoryRevokeRefreshToken](../../actions/core/user-directory/ask-user-directory-revoke-refresh-token.md) / [askUserDirectorySignOutUser](../../actions/core/user-directory/ask-user-directory-sign-out-user.md). Keep it comfortably above however long the client waits before refreshing. |
 | `deprecated` | `boolean` | `false` | Inherited from `QPQConfigAdvancedSettings`; marks the setting as deprecated. |
 
 ## MFA
@@ -132,7 +133,7 @@ The `QpqInfCoreUserDirectoryConstruct` deploys:
 - **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.
+- **An app client** with a generated secret, `ADMIN_USER_PASSWORD_AUTH` enabled, `CUSTOM_AUTH` enabled when `customAuthRuntime` is set, and access/ID token validity set from `accessTokenValidityMinutes` (Cognito's 60-minute default when omitted).
 - **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.
@@ -183,6 +184,7 @@ export default [
 - **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).
+- **Signing out:** [askUserDirectoryRevokeRefreshToken](../../actions/core/user-directory/ask-user-directory-revoke-refresh-token.md) (single session), [askUserDirectorySignOutUser](../../actions/core/user-directory/ask-user-directory-sign-out-user.md) (every session).
 - **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.

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

@@ -62,6 +62,7 @@ The single `options` argument is an `EventDocRoutesOptions`:
 | `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. |
 | `onPublish` | `string` | – | Name of a registered inline function. When set, every successful append of a Publish event invokes it with `{ docId, event, summary }`, after the event is durably written and the summary re-derived. This is the seam for syncing a folded document into a materialized read model. Errors propagate to the caller: the event has landed but the side effect did not, so the caller learns the read model may be stale. |
 | `scopeResolver` | `string` | – | Name of a registered inline function. When set, every route invokes it with `{ event }` before running; a non-null result becomes the ambient storage scope for the whole request, transparently partitioning the collection's stores and assets (e.g. per-tenant). Null means unscoped. Omit for collections that never partition. |
+| `excludeRoutes` | `EventDocRouteName[]` | `[]` | Route names to leave unmounted (`'list' \| 'get' \| 'listEvents' \| 'render' \| 'create' \| 'appendEvent' \| 'createAsset' \| 'getAsset' \| 'remove'`). For a collection that must own one of these itself instead of using the stock behavior — e.g. a `create` that must also perform some side effect the stock controller doesn't know about. |
 
 ### `RouteAuthSettings`
 

package/template/docusaurus/docs/config/features/tenant.md

@@ -12,8 +12,8 @@ Wires up **everything for org/tenant support**, declared identically in every se
 - Everything else, gated to the owner's deploy only via [defineServiceSettings](../core/service-settings.md):
   - The tenant stores ([defineTenantStores](./tenant-stores.md)): the tenant event-doc collection plus the materialized record table.
   - The publish-to-record-store sync: an inline function (`askTenantOnPublish`) that runs on every published tenant document, re-folds the full event log, and upserts the resulting `TenantRecord`. It is a plain upsert of the fold result, so publish retries and repair re-runs are safe.
-  - The generic event-doc CRUD under `{basePath}/docs` ([defineEventDocRoutes](./event-doc-routes.md) for the `tenants` store, `tenant` type, with the publish sync wired in as `onPublish`).
-  - The tenant-specific routes at `{basePath}`: list my tenants, create, get record, and get logo.
+  - The stock event-doc CRUD at `{basePath}` ([defineEventDocRoutes](./event-doc-routes.md) for the `tenants` store, `tenant` type, with the publish sync wired in as `onPublish`, and `create` excluded — see below).
+  - The membership-gated routes at `{myTenantsBasePath}`: list my tenants, create, get record, and get logo.
 
 - **On AWS:** on the owner's deploy, this deploys everything [defineTenantStores](./tenant-stores.md) deploys (two DynamoDB tables and an S3 bucket) plus the API Gateway routes and Lambda handlers from [defineEventDocRoutes](./event-doc-routes.md) and the four tenant routes below. On every other service's deploy, only the `userTenantLinks` reference resolves (no new table); the inline functions deploy no infrastructure of their own anywhere.
 
@@ -26,6 +26,7 @@ export default [
   ...defineTenant({
     owner: { module: 'ca' },
     basePath: '/tenants',
+    myTenantsBasePath: '/my-tenants',
     routeAuthSettings: { userDirectoryName: 'users' },
   }),
 ];
@@ -37,12 +38,12 @@ All paths are prefixed with the version segment `/v{version}` (default `/v1`) an
 
 | Method | Path | Purpose |
 | --- | --- | --- |
-| `GET` | `{basePath}` | The authenticated user's tenants, as `EventDocSummary` rows. Runs under the request's scope: memberships homed in the caller's current partition hydrate live (drafts included); the rest hydrate from the published `TenantRecord` registry. |
-| `POST` | `{basePath}` | Create a tenant (body `{ name }`); the caller becomes its first member. Runs under the request's scope, so the new tenant doc lands in the caller's current partition. |
-| `GET` | `{basePath}/{id}` | One tenant's materialized record (the fast path). Members only: non-members get `Forbidden`, a missing record gets `NotFound`. |
-| `GET` | `{basePath}/{id}/logo` | A presigned, short-lived URL for the tenant's logo blob. Members only: non-members get `Forbidden`; a missing record or a tenant with no logo gets `NotFound`. Presigned in the scope the tenant doc was published under (recorded on the `TenantRecord`), not the reader's own scope, since the logo asset lives in the doc's home partition. |
+| `GET` | `{myTenantsBasePath}` | The authenticated user's tenants, as `EventDocSummary` rows. Runs under the request's scope: memberships homed in the caller's current partition hydrate live (drafts included); the rest hydrate from the published `TenantRecord` registry. |
+| `POST` | `{myTenantsBasePath}` | Create a tenant (body `{ name }`); the caller becomes its first member. Runs under the request's scope, so the new tenant doc lands in the caller's current partition. This is the only way to create a tenant — the stock `create` route is excluded at `{basePath}` so a new tenant is never made without also linking its creator. |
+| `GET` | `{myTenantsBasePath}/{id}` | One tenant's materialized record (the fast path). Members only: non-members get `Forbidden`, a missing record gets `NotFound`. |
+| `GET` | `{myTenantsBasePath}/{id}/logo` | A presigned, short-lived URL for the tenant's logo blob. Members only: non-members get `Forbidden`; a missing record or a tenant with no logo gets `NotFound`. Presigned in the scope the tenant doc was published under (recorded on the `TenantRecord`), not the reader's own scope, since the logo asset lives in the doc's home partition. |
 
-On top of these, the full generic event-doc route set (create, append, list, assets, and so on) is mounted under `{basePath}/docs`; see [defineEventDocRoutes](./event-doc-routes.md#routes-mounted) for the list.
+On top of these, the stock event-doc route set (get, append, list events, assets, remove, and so on — everything but `create`) is mounted at `{basePath}`, named after the model type like any other collection; see [defineEventDocRoutes](./event-doc-routes.md#routes-mounted) for the list. `{basePath}` and `{myTenantsBasePath}` must be distinct and neither may be a path segment under the other: `{basePath}/{id}` matches any single segment, so a literal sibling path would be ambiguous with a tenant whose id happens to match it.
 
 ## Signature
 
@@ -57,7 +58,8 @@ The single `options` argument is a `TenantOptions` (a `TenantRoutesOptions` plus
 | Property | Type | Default | Description |
 | --- | --- | --- | --- |
 | `owner` | `CrossModuleOwner & { module: string }` | – (required) | The service that owns the tenant registry, e.g. `{ module: 'ca' }`. Pass the **same** value in every service's `defineTenant` call; the registry (stores, publish sync, management routes) only materializes when the deploying module matches this. |
-| `basePath` | `` `/${string}` `` | – (required) | URL prefix the tenant routes mount under, e.g. `/tenants`. The generic event-doc CRUD mounts under `{basePath}/docs`. Only used on the owner's deploy, but required on every call for type consistency across services. |
+| `basePath` | `` `/${string}` `` | – (required) | The tenant collection root, e.g. `/tenants`. The stock event-doc CRUD (minus `create`) mounts here. Only used on the owner's deploy, but required on every call for type consistency across services. |
+| `myTenantsBasePath` | `` `/${string}` `` | – (required) | URL prefix the membership-gated routes mount under, e.g. `/my-tenants` (list mine, create, get record, get logo). Must not be a child path of `basePath` — see [Routes mounted](#routes-mounted). Only used on the owner's deploy, but required on every call for type consistency across services. |
 | `routeAuthSettings` | `RouteAuthSettings` | – (required) | Auth applied to every mounted route (see [route](../webserver/route.md)). Required here, unlike the generic event-doc routes: tenant routes are meaningless unauthenticated, since membership keys off the user. Only used on the owner's deploy. |
 | `version` | `number` | `1` | Version number for the `/v{version}` path prefix on every route. Only used on the owner's deploy. |
 | `tenantHeaderName` | `string` | `'x-qpq-tenant-id'` | The header the client sends its selected tenant id on. Exposed to the tenant routes as the `tenantHeaderName` global, which the scope resolver reads. |
@@ -65,7 +67,7 @@ The single `options` argument is a `TenantOptions` (a `TenantRoutesOptions` plus
 ## Notes
 
 - Tenant state is event-sourced: the `tenants` event-doc collection is the audit-trailed source of truth, and the `tenantRecords` table is a read model synced on publish. Request handlers never write the record table directly.
-- The `tenants` collection is scope-resolved like any other tenanted collection (see [defineTenantedEventDoc](./tenanted-event-doc.md)): a doc is only visible/editable from the scope that owns it, including through the generic CRUD under `{basePath}/docs`. There is no cross-scope doc read — listing memberships homed in another scope goes through the published `TenantRecord`, not the doc store.
+- The `tenants` collection is scope-resolved like any other tenanted collection (see [defineTenantedEventDoc](./tenanted-event-doc.md)): a doc is only visible/editable from the scope that owns it, including through the stock CRUD at `{basePath}`. There is no cross-scope doc read — listing memberships homed in another scope goes through the published `TenantRecord`, not the doc store.
 - The `TenantRecord` produced by the publish sync carries `tenantId`, `name`, `brandColors`, `logo` (an asset ref, resolved to a URL via the get-logo route above), `scope` (the storage scope the doc was published under, used to presign the logo for cross-scope readers), `createdAt`, `updatedAt`, `createdByUserId`, and a `status` derived from the summary (`deleted` when the summary has a `deletedAt`, otherwise `active`).
 - `defineTenant` registers the scope resolver but does not apply it to anything. To tenant-scope one of your own collections, pass `TENANT_SCOPE_RESOLVER_FN` as that collection's `scopeResolver` option (or use [defineTenantedEventDoc](./tenanted-event-doc.md), which does this for you).
 - The scope resolver always resolves to a typed scope — a membership-checked `TENANT#<id>` for a request that names a tenant, or the caller's own `PERSONAL#<userId>` when it doesn't. A tenant-scoped collection or connection is never left unscoped.
@@ -75,7 +77,7 @@ The single `options` argument is a `TenantOptions` (a `TenantRoutesOptions` plus
 
 - [defineTenantStores](./tenant-stores.md): the store half of this helper (owner-only).
 - [defineTenantedEventDoc](./tenanted-event-doc.md): a `defineEventDoc` with `TENANT_SCOPE_RESOLVER_FN` pre-wired as `scopeResolver`.
-- [defineEventDocRoutes](./event-doc-routes.md): the generic CRUD mounted under `{basePath}/docs`, and home of the `scopeResolver` / `onPublish` options.
+- [defineEventDocRoutes](./event-doc-routes.md): the stock CRUD mounted at `{basePath}`, and home of the `scopeResolver` / `onPublish` / `excludeRoutes` options.
 - [defineWebSocketQueue](./web-socket-queue.md): where the tenant connection-scope resolver plugs in.
 - [defineTenantedWebSocketQueue](./tenanted-web-socket-queue.md): a `defineWebSocketQueue` with that resolver pre-wired.
 - [defineServiceSettings](../core/service-settings.md): the per-module gating mechanism this uses to materialize the registry only on the owner.

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

@@ -80,7 +80,7 @@ export interface QPQConfigAdvancedWebsocketQueueSettings extends QPQConfigAdvanc
 
 ## Returns
 
-A `QPQConfig` array containing: three globals, the connection [key-value store](../core/key-value-store.md), and the [WebSocket API](./websocket.md) with the queue's built-in handlers.
+A `QPQConfig` array containing: three globals, the connection [key-value store](../core/key-value-store.md), and the [WebSocket API](../webserver/websocket.md) with the queue's built-in handlers.
 
 ## Related
 

package/template/docusaurus/docs/config/webserver/auth-system.md

@@ -57,6 +57,7 @@ The name of the [user directory](../../config/core/user-directory.md) to create
 | `mfa` | `UserDirectoryMfaSettings` | – | Forwarded to the user directory: multi-factor authentication configuration. See [MFA](../../config/core/user-directory.md#mfa). |
 | `basePath` | `string` | `''` | A path prefix applied to every auth route. E.g. `'/auth'` produces `/auth/login`, `/auth/refreshToken`, and so on. |
 | `allowedOrigins` | `string[]` | – | Allowed browser origins (CORS) applied to every generated auth route. |
+| `accessTokenValidityMinutes` | `number` | `60` (Cognito default) | Forwarded to the user directory: access/ID token (JWT) lifetime in minutes (Cognito allows 5–1440). Shorter shrinks the window in which a revoked session's access token keeps working. Keep it comfortably above however long the client waits before refreshing (the stock web client refreshes ~10 minutes before expiry). See [defineUserDirectory](../../config/core/user-directory.md#parameters). |
 
 ## Generated routes
 
@@ -66,6 +67,8 @@ With `basePath` = `''` (the default), `defineAuthSystem` registers these `POST`
 | --- | --- | --- |
 | `/login` | `login` | No |
 | `/refreshToken` | `refreshToken` | No |
+| `/logout` | `logout` | No |
+| `/logoutEverywhere` | `logoutEverywhere` | No |
 | `/challenge` | `respondToAuthChallenge` | No |
 | `/associateSoftwareToken` | `associateSoftwareToken` | No |
 | `/forgotPassword` | `forgotPassword` | No |
@@ -74,6 +77,11 @@ With `basePath` = `''` (the default), `defineAuthSystem` registers these `POST`
 
 Each path is prefixed with `basePath` when provided (e.g. `/auth/login`). The handler stories correspond to the [User Directory actions](../../actions/core/user-directory/ask-user-directory-authenticate-user.md) — for example `login` authenticates a user, `refreshToken` refreshes an access token, and `respondToAuthChallenge` completes a challenge/MFA flow.
 
+`/logout` and `/logoutEverywhere` are unauthenticated routes that are each self-authorizing by the token they carry, and both are best-effort — they always respond `{ success: true }` even if the token was already invalid, since a client's local logout must never fail:
+
+- `/logout` takes `{ refreshToken }` in the body and revokes just that one session ([askUserDirectoryRevokeRefreshToken](../../actions/core/user-directory/ask-user-directory-revoke-refresh-token.md)) — "log out this device."
+- `/logoutEverywhere` reads the access token from the request headers and revokes every session for that user ([askUserDirectorySignOutUser](../../actions/core/user-directory/ask-user-directory-sign-out-user.md)) — "sign out of all devices."
+
 ## How auth ties routes to the user directory
 
 A route becomes authenticated by setting `routeAuthSettings.userDirectoryName` (which `defineAuthSystem` does for `/changePassword`). At runtime the webserver validates the caller's access token against that directory before invoking the handler — decoding the token, checking it is valid, and making its claims/roles available. Any route in the application (not just the ones generated here) can opt into the same protection by referencing this directory's name, because the directory is declared ungated at the top level.
@@ -106,5 +114,5 @@ export default [
 
 - [defineUserDirectory](../../config/core/user-directory.md) — the user directory `defineAuthSystem` creates; documents the directory options that `phoneRequired`, `selfSignUpEnabled`, `emailTemplates`, and `mfa` forward to, plus the AWS Cognito infrastructure.
 - [defineApiKey](./api-key.md) — the complementary auth mechanism (shared-secret / machine callers) for routes.
-- **User Directory actions** — the auth operations the generated handlers wrap: [askUserDirectoryAuthenticateUser](../../actions/core/user-directory/ask-user-directory-authenticate-user.md), [askUserDirectoryRefreshToken](../../actions/core/user-directory/ask-user-directory-refresh-token.md), [askUserDirectoryRespondToAuthChallenge](../../actions/core/user-directory/ask-user-directory-respond-to-auth-challenge.md), [askUserDirectoryChangePassword](../../actions/core/user-directory/ask-user-directory-change-password.md), [askUserDirectoryForgotPassword](../../actions/core/user-directory/ask-user-directory-forgot-password.md), [askUserDirectoryConfirmForgotPassword](../../actions/core/user-directory/ask-user-directory-confirm-forgot-password.md), [askUserDirectoryAssociateSoftwareToken](../../actions/core/user-directory/ask-user-directory-associate-software-token.md).
+- **User Directory actions** — the auth operations the generated handlers wrap: [askUserDirectoryAuthenticateUser](../../actions/core/user-directory/ask-user-directory-authenticate-user.md), [askUserDirectoryRefreshToken](../../actions/core/user-directory/ask-user-directory-refresh-token.md), [askUserDirectoryRevokeRefreshToken](../../actions/core/user-directory/ask-user-directory-revoke-refresh-token.md), [askUserDirectorySignOutUser](../../actions/core/user-directory/ask-user-directory-sign-out-user.md), [askUserDirectoryRespondToAuthChallenge](../../actions/core/user-directory/ask-user-directory-respond-to-auth-challenge.md), [askUserDirectoryChangePassword](../../actions/core/user-directory/ask-user-directory-change-password.md), [askUserDirectoryForgotPassword](../../actions/core/user-directory/ask-user-directory-forgot-password.md), [askUserDirectoryConfirmForgotPassword](../../actions/core/user-directory/ask-user-directory-confirm-forgot-password.md), [askUserDirectoryAssociateSoftwareToken](../../actions/core/user-directory/ask-user-directory-associate-software-token.md).
 - **Routes and APIs** — the generated endpoints are `defineRoute` settings; see the route / `defineApi` config settings in quidproquo-webserver to add and protect your own routes with this directory.

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

@@ -20,4 +20,38 @@ Platform-specific implementations that execute actions.
 
 ## Runtime
 
-The orchestration layer that executes stories by processing yielded actions through the appropriate processors.
+The orchestration layer that executes stories by processing yielded actions through the appropriate processors.
+
+## Why every function starts with `ask`
+
+Every quidproquo function you call from a story starts with `ask`: `askDateNow`, `askFileReadTextContents`, `askRunParallel`. That prefix isn't decoration, it tells you exactly what kind of function you're holding. Here's the whole of `askDateNow`:
+
+```typescript
+export function* askDateNow(): DateNowActionRequester {
+  return yield { type: DateActionType.Now };
+}
+```
+
+Notice it never calls `new Date()`. It yields a plain action object and suspends. The runtime catches that action, hands it to the platform's `DateNow` processor (which actually reads the clock), then resumes the generator with the result. The `ask` prefix captures three things about that arrangement:
+
+### 1. It's a request, not an execution
+
+Calling `askDateNow()` does nothing on its own. It builds a generator that *describes* what it wants, and the runtime decides how to fulfil it. That's what keeps stories pure and platform-agnostic: the "what" lives in your story, the "how" lives in the `quidproquo-actionprocessor-*` packages. Your story doesn't know whether the clock is a Lambda, a Node process, or a test fixture.
+
+### 2. It's a question with an answer
+
+The return type is literally `AskResponse<T>`. You ask, the runtime responds, and the response arrives as the generator's return value:
+
+```typescript
+const now = yield* askDateNow(); // now: QpqIsoDateTime
+```
+
+Every action pairs a **requester** (the `ask` function your story calls) with a **processor** (the platform implementation that produces the answer). They're two halves of the same conversation.
+
+### 3. It signals the calling convention
+
+Anything starting with `ask` must be invoked with `yield*` from inside another generator. The prefix works like a syntax marker, the same way `use` marks a React hook: see `ask`, write `yield*`. Higher-level stories that compose other ask functions follow the same rule and get the same prefix (`askGetCurrentEpochMs`, `askRunParallel`, `askCatch`).
+
+The practical payoff is testability and portability. Because `askDateNow` only describes intent, a test can run the same story with a fake processor that returns a fixed timestamp, and the identical story code runs on Lambda, Node, or the browser just by swapping the processor set.
+
+Both halves of this contract (always `yield*` an ask call, never name a plain function `ask*`) are enforced at edit time by the [quidproquo ESLint plugin](./eslint-plugin.md), which ships with the shared lint config and auto-fixes missing `yield*`s.

package/template/docusaurus/docs/eslint-plugin.md

@@ -0,0 +1,86 @@
+---
+sidebar_position: 5
+---
+
+# ESLint Plugin
+
+The `ask` prefix is a contract: [every function that starts with `ask` is a story](./core-concepts.md#why-every-function-starts-with-ask), and every story must be run with `yield*`. Contracts are only useful if something enforces them, so quidproquo ships an ESLint plugin that does. It catches the two mistakes everyone makes at least once:
+
+```typescript
+// error: creates a generator that never runs
+const now = askDateNow();
+
+// error: hands the generator to the runtime as a value instead of running it
+const now = yield askDateNow();
+
+// correct
+const now = yield* askDateNow();
+```
+
+## Setup
+
+If you use the shared config, you already have it. `quidproquo-eslint-config` wires the plugin in, so every `create-qpq-app` project and every package extending that config gets both rules as errors with no extra setup.
+
+To use the plugin on its own, without the rest of the shared config:
+
+```js title="eslint.config.mjs"
+import { qpqPlugin } from 'quidproquo-eslint-config';
+
+export default [
+  qpqPlugin.configs.recommended,
+  // or pick rules individually:
+  // { plugins: { qpq: qpqPlugin }, rules: { 'qpq/require-yield-star': 'error' } },
+];
+```
+
+## `qpq/require-yield-star`
+
+Inside a generator, any call to an `ask*` function (including member calls like `authLogic.askLogin()` and tagged templates like `` askLog`...` ``) must be delegated with `yield*`.
+
+The rule is auto-fixable. Run `eslint --fix` and it will:
+
+- insert `yield*` in front of a bare call
+- upgrade a plain `yield` to `yield*`
+- replace a wrong `await` with `yield*`
+- add parentheses where a bare yield expression is not allowed, for example `!askUserExists(id)` becomes `!(yield* askUserExists(id))`
+
+Two patterns stay legal, because they are how stories are meant to be composed and tested:
+
+```typescript
+// ask calls as arguments build generators for the outer ask to run
+yield* askRunParallel([askRandomNumber(), askDateNow()]);
+
+// outside a generator you cannot yield; tests and forwarding
+// wrappers create generators and hand them off
+const result = runStory(askDateNow(), mocks);
+```
+
+## `qpq/ask-prefix-generator-only`
+
+The reverse direction: `ask` is reserved for stories, the same way `use` is reserved for React hooks. A plain function named `ask*` breaks the contract, because callers will `yield*` something that is not a generator.
+
+```typescript
+// error: not a generator
+function askUserName() {
+  return 'joe';
+}
+
+// correct
+function* askUserName(): AskResponse<string> {
+  return yield* askConfigGetParameter('user-name');
+}
+```
+
+The rule checks every kind of function literal: declarations, arrows, object methods, class methods and class properties. Aliases and factory results are fine, since the right-hand side already is (or produces) a story:
+
+```typescript
+// both legal: not function literals
+const askLog = askLogTemplateLiteral;
+const askActiveTenantRead = createContextReader(tenantContext);
+```
+
+There is no auto-fix for this one. Whether the function should become a generator or lose the prefix is a judgement call.
+
+## Why bother
+
+TypeScript alone cannot catch a missing `yield*`. Calling `askDateNow()` without yielding is perfectly well-typed, it just returns a generator that nobody ever runs, and the action inside it silently never happens. That failure mode produces no error, no log line, and no clue. A lint rule at edit time is the cheapest place to catch it.

package/template/docusaurus/docs/getting-started.md

@@ -96,7 +96,9 @@ export const health = dynamicRoute(
 The story never reads the clock itself — it *asks* for the time by yielding
 an action, and the runtime answers. On your machine that's the dev server;
 in production it's whatever platform the app is deployed to. Same story,
-zero changes.
+zero changes. That's why every quidproquo function starts with `ask`: see
+[why every function starts with ask](./core-concepts.md#why-every-function-starts-with-ask)
+for the full story.
 
 Add your own route by dropping a file next to `health.ts`, exporting it from
 the controller `index.ts`, and saving — the dev server rebuilds and restarts

package/template/docusaurus/sidebars.ts

@@ -7,6 +7,7 @@ const sidebars: SidebarsConfig = {
     'core-concepts',
     'use-cases',
     'architecture-overview',
+    'eslint-plugin',
   ],
   
   apiSidebar: [

package/template/docusaurus/src/css/custom.css

@@ -104,12 +104,56 @@ body {
 }
 
 .navbar__title {
+  position: relative;
   font-family: var(--qpq-font-display);
   font-size: 19px;
   font-weight: 600;
   letter-spacing: 0.02em;
 }
 
+/* Glint overlay: the same glyphs stacked over the title, transparent except
+   for a narrow band clipped to the letterforms. It rests off-canvas, then
+   makes one eased sweep across per cycle. The band is two-tone (white into
+   cyan) so it stays visible whatever the letter color underneath: the cyan
+   half carries the shimmer on this all-light title. The "/ ''" marks the
+   duplicated text as decorative; browsers without that syntax skip the
+   overlay entirely, which just means no shimmer. */
+.navbar__title::after {
+  content: 'quidproquo' / '';
+  position: absolute;
+  inset: 0;
+  color: transparent;
+  background-image: linear-gradient(
+    105deg,
+    rgba(255, 255, 255, 0) 38%,
+    rgba(255, 255, 255, 0.85) 45%,
+    rgba(34, 211, 238, 0.85) 53%,
+    rgba(34, 211, 238, 0) 60%
+  );
+  background-size: 250% 100%;
+  background-repeat: no-repeat;
+  background-position: 130% 0;
+  -webkit-background-clip: text;
+  background-clip: text;
+  animation: qpq-title-shine 7s ease-in-out infinite;
+}
+
+@keyframes qpq-title-shine {
+  0%,
+  72% {
+    background-position: 130% 0;
+  }
+  100% {
+    background-position: -130% 0;
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .navbar__title::after {
+    animation: none;
+  }
+}
+
 .navbar__logo {
   filter: drop-shadow(0 0 10px rgba(34, 211, 238, 0.5));
 }

package/template/docusaurus/static/img/favicon.svg

@@ -1,4 +1,8 @@
 <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32">
-  <rect x="3" y="3" width="26" height="26" rx="6" fill="#071018" stroke="#22d3ee" stroke-width="2"/>
-  <path d="M12 9l-4 7 4 7M20 9l4 7-4 7" stroke="#7ff4ff" stroke-width="2.4" fill="none" stroke-linecap="round" stroke-linejoin="round"/>
+  <rect x="1" y="1" width="30" height="30" rx="6" fill="#071018"/>
+  <g transform="translate(4.5 4.5) scale(0.0494) translate(-24.4 -24.4)">
+    <path fill="#22d3ee" d="M271.42,489.64h-10.72c-128.68,0-235.74-102.93-236.29-231.61S128.97,23.86,258.03,24.41c128.68.55,231.6,107.61,231.6,236.29v11.61c0,.09-.07.16-.16.16h-109.69c-.09,0-.16-.07-.16-.16v-12.61c0-65.9-53.82-123.71-119.7-125.24-69.89-1.62-127.08,55.57-125.46,125.46,1.53,65.89,59.34,119.71,125.24,119.71h11.72c.09,0,.16.07.16.16v109.69c0,.09-.07.16-.16.16Z"/>
+    <rect fill="#8df6ff" x="268.31" y="273.22" width="106.91" height="106.91"/>
+    <rect fill="#8df6ff" x="375.62" y="380.53" width="106.91" height="106.91"/>
+  </g>
 </svg>

package/template/docusaurus/static/img/qpq-logo.svg

@@ -1,4 +1,5 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32">
-  <rect x="3" y="3" width="26" height="26" rx="7" fill="rgba(34,211,238,0.08)" stroke="#22d3ee" stroke-width="1.6"/>
-  <path d="M12 9l-4 7 4 7M20 9l4 7-4 7" stroke="#8df6ff" stroke-width="2.2" fill="none" stroke-linecap="round" stroke-linejoin="round"/>
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="24.4 24.4 465.3 465.3">
+  <path fill="#22d3ee" d="M271.42,489.64h-10.72c-128.68,0-235.74-102.93-236.29-231.61S128.97,23.86,258.03,24.41c128.68.55,231.6,107.61,231.6,236.29v11.61c0,.09-.07.16-.16.16h-109.69c-.09,0-.16-.07-.16-.16v-12.61c0-65.9-53.82-123.71-119.7-125.24-69.89-1.62-127.08,55.57-125.46,125.46,1.53,65.89,59.34,119.71,125.24,119.71h11.72c.09,0,.16.07.16.16v109.69c0,.09-.07.16-.16.16Z"/>
+  <rect fill="#8df6ff" x="268.31" y="273.22" width="106.91" height="106.91"/>
+  <rect fill="#8df6ff" x="375.62" y="380.53" width="106.91" height="106.91"/>
 </svg>