create-qpq-app 0.1.9 → 0.1.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-qpq-app",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "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.9"
+    "quidproquo-tsconfig": "0.1.11"
   },
   "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/features/event-doc/ask-event-doc-read-identity.md

@@ -0,0 +1,45 @@
+---
+title: askEventDocReadIdentity
+description: Declaratively read where an event-doc's own document lives (serviceName/basePath/id), for verbs that build links relative to their own doc.
+---
+
+# askEventDocReadIdentity
+
+The address sibling of [askEventDocReadState](./ask-event-doc-read-state.md): the story yields no payload at all, and a registered processor answers with the doc's own identity — `serviceName`, `basePath`, and `id`. Verbs written in terms of it (for example, building an `EventDocLink` relative to their own doc) stay workspace-blind, resolving whichever doc the processor is bound to.
+
+- **Action type:** `EventDocActionType.ReadIdentity`
+- **quidproquo-features ships no default processor** for this action. Calling it with no processor registered fails loudly, the same as an unbound [askEventDocReadState](./ask-event-doc-read-state.md).
+- Returns `null` until the doc has an identity to report: before the workspace initializes the slot, and always for an unsaved doc (it has no server-backed identity to resolve).
+
+```typescript
+import { askEventDocReadIdentity } from 'quidproquo-features';
+
+export function* askTemplateBuildSelfLink() {
+  const identity = yield* askEventDocReadIdentity();
+  return identity ? { serviceName: identity.serviceName, basePath: identity.basePath, id: identity.id } : null;
+}
+```
+
+## Signature
+
+```typescript
+function* askEventDocReadIdentity(): AskResponse<Nullable<EventDocWorkspaceDocumentIdentity>>;
+```
+
+## Parameters
+
+None — WHICH doc's identity to read is the answering processor's ambient context, the same as `askEventDocReadState`.
+
+## Returns
+
+`AskResponse<Nullable<EventDocWorkspaceDocumentIdentity>>` — `{ serviceName, basePath, id }`, concretely typed since every doc's identity has the same shape. `null` until the doc is bound to a real document.
+
+## Notes
+
+- This is the contract only — it carries no default behavior. A runtime that answers `askEventDocReadState` for a doc should also answer `askEventDocReadIdentity` for it.
+- In the event-doc workspace, the binding registered for a slot answers with `state.slots[slotKey].documentIdentity`, so this reflects the same identity `askInit` seeded for the slot.
+
+## Related
+
+- [askEventDocReadState](./ask-event-doc-read-state.md) — the content sibling: what the doc currently holds, rather than where it lives.
+- [askApplyEventDocEvent](./ask-apply-event-doc-event.md) — the write action this doc's verbs typically pair with.

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

@@ -0,0 +1,46 @@
+---
+title: askEventDocReadState
+description: Declaratively read an event-doc's current folded state, leaving WHICH doc and HOW it is resolved to a registered processor.
+---
+
+# askEventDocReadState
+
+The read counterpart of [askApplyEventDocEvent](./ask-apply-event-doc-event.md): the story yields no payload at all, and a registered processor answers with the doc's current folded state. Because it has no target of its own, verbs written in terms of it (a domain's read-to-derive-a-write action creators) run unchanged wherever a processor for it is registered, resolving whichever doc the processor is bound to.
+
+- **Action type:** `EventDocActionType.ReadState`
+- **quidproquo-features ships no default processor** for this action. Calling it with no processor registered fails loudly, the same as an unbound [askApplyEventDocEvent](./ask-apply-event-doc-event.md).
+- Returns `unknown` — the raw action can't know a slot's view type. Call it through a per-doc `createEventDocStateReader<TView>()` instead of directly, for a typed result.
+- In the event-doc workspace, the binding registered for a slot answers with the doc's current memoized view (history + pending folded and migrated to latest), so a commit earlier in the same story is visible to a read that follows it.
+
+```typescript
+import { askEventDocReadState } from 'quidproquo-features';
+
+export function* askTemplateAppendLine(line: string) {
+  const template = (yield* askEventDocReadState()) as TemplateState;
+  yield* askApplyEventDocEvent<AppendLineEffect>(TemplateEffect.AppendLine, { line: template.body ? `${template.body}\n${line}` : line });
+}
+```
+
+## Signature
+
+```typescript
+function* askEventDocReadState(): AskResponse<unknown>;
+```
+
+## Parameters
+
+None — WHICH doc to read is the answering processor's ambient context, the same as `askApplyEventDocEvent`'s target.
+
+## Returns
+
+`AskResponse<unknown>` — the doc's current folded state, untyped at this layer. Use `createEventDocStateReader<TView>()` to mint a typed `askRead<Doc>()` for a specific doc instead of casting the result by hand at every call site.
+
+## Notes
+
+- This is the contract only — it carries no default behavior. A runtime that answers `askApplyEventDocEvent` for a doc should also answer `askEventDocReadState` for it, so read-to-derive-a-write verbs work the same way commits do.
+- `createEventDocDefinition` mints the doc's fold config and api together; pair it with a standalone `createEventDocStateReader<TView>()` for the doc's typed read verb.
+
+## Related
+
+- [askApplyEventDocEvent](./ask-apply-event-doc-event.md) — the write counterpart this action mirrors.
+- [askEventDocReadIdentity](./ask-event-doc-read-identity.md) — the address sibling: where the doc lives, rather than what it currently holds.

package/template/docusaurus/docs/actions/features/web-socket-queue/ask-web-socket-queue-broadcast-message.md

@@ -0,0 +1,50 @@
+---
+title: askWebSocketQueueBroadcastMessage
+description: Push a server-initiated message to every live connection on a WebSocket queue's API.
+---
+
+# askWebSocketQueueBroadcastMessage
+
+Sends a message to **every live connection** on a named [WebSocket queue](../../../config/features/web-socket-queue.md) API. Unlike a connection-scoped send, this does not need a websocket-triggered context — the caller names the `apiName` explicitly, so any story (a storage event, a queue handler, a cron job) can push to every connected frontend. Connections whose socket died without their `onDisconnect` firing are skipped and their stale record is cleaned up automatically; a single dead connection never aborts the broadcast.
+
+```typescript
+import { askWebSocketQueueBroadcastMessage } from 'quidproquo-features';
+
+interface Announcement {
+  type: 'Announcement';
+  payload: { text: string };
+}
+
+export function* askAnnounce(text: string) {
+  yield* askWebSocketQueueBroadcastMessage<Announcement>('api', {
+    type: 'Announcement',
+    payload: { text },
+  });
+}
+```
+
+## Signature
+
+```typescript
+function* askWebSocketQueueBroadcastMessage<E extends AnyWebSocketQueueEventMessage>(
+  websocketApiName: string,
+  message: E,
+): AskResponse<void>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `websocketApiName` | `string` | The `apiName` of the target [defineWebSocketQueue](../../../config/features/web-socket-queue.md) — every connection currently registered against this API receives the message. |
+| `message` | `E extends AnyWebSocketQueueEventMessage` | The typed event message to send, e.g. `{ type, payload }`. |
+
+## Returns
+
+`void`
+
+## Related
+
+- [askWebSocketQueueBroadcastServiceUpdated](./ask-web-socket-queue-broadcast-service-updated.md) — a typed wrapper around this for the built-in `ServiceUpdated` message.
+- [defineWebSocketQueue](../../../config/features/web-socket-queue.md) — declares the WebSocket queue API this broadcasts on.
+- [askServiceRequest](./ask-service-request.md) — an RPC-style request/response over the same queue, addressed to one service rather than broadcast to every connection.

package/template/docusaurus/docs/actions/features/web-socket-queue/ask-web-socket-queue-broadcast-service-updated.md

@@ -0,0 +1,41 @@
+---
+title: askWebSocketQueueBroadcastServiceUpdated
+description: Tell every connected frontend that a service's deployed artifacts changed, so it can offer a module reload.
+---
+
+# askWebSocketQueueBroadcastServiceUpdated
+
+Broadcasts a `ServiceUpdated` message to every live connection on a [WebSocket queue](../../../config/features/web-socket-queue.md) API, naming the service whose deployed artifacts changed (for example, a new views bundle going live). A typed wrapper around [askWebSocketQueueBroadcastMessage](./ask-web-socket-queue-broadcast-message.md) for this one built-in message type.
+
+```typescript
+import { askWebSocketQueueBroadcastServiceUpdated } from 'quidproquo-features';
+
+export function* askNotifyDeploy(serviceName: string) {
+  yield* askWebSocketQueueBroadcastServiceUpdated('api', serviceName);
+}
+```
+
+## Signature
+
+```typescript
+function* askWebSocketQueueBroadcastServiceUpdated(
+  websocketApiName: string,
+  serviceName: string,
+): AskResponse<void>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `websocketApiName` | `string` | The `apiName` of the target [defineWebSocketQueue](../../../config/features/web-socket-queue.md) — every connection currently registered against this API receives the message. |
+| `serviceName` | `string` | The qpq service (module) whose deployed artifacts changed. Sent as `payload.serviceName` on a `WebSocketQueueServerMessageEventType.ServiceUpdated` message. |
+
+## Returns
+
+`void`
+
+## Related
+
+- [askWebSocketQueueBroadcastMessage](./ask-web-socket-queue-broadcast-message.md) — the untyped broadcast this wraps.
+- [defineWebSocketQueue](../../../config/features/web-socket-queue.md) — declares the WebSocket queue API this broadcasts on.

package/template/docusaurus/docs/actions/webserver/email/_category_.json

@@ -0,0 +1 @@
+{ "label": "Email", "link": { "type": "generated-index", "description": "Actions for sending email from a service." } }