create-qpq-app 0.1.5

package/template/docusaurus/docs/actions/core/user-directory/ask-user-directory-set-user-attributes.md

@@ -0,0 +1,60 @@
+---
+title: askUserDirectorySetUserAttributes
+description: Update a user's profile attributes.
+---
+
+# askUserDirectorySetUserAttributes
+
+Updates a user's profile attributes in a [user directory](../../../config/core/user-directory.md). Only the attributes you pass are written; omitted attributes are left unchanged.
+
+- **Action type:** `UserDirectoryActionType.SetUserAttributes`
+- **On AWS:** issues Cognito `AdminUpdateUserAttributes`.
+
+```typescript
+import { askUserDirectorySetUserAttributes } from 'quidproquo-core';
+
+export function* askUpdateProfile(username: string) {
+  yield* askUserDirectorySetUserAttributes('app-users', username, {
+    givenName: 'Ada',
+    familyName: 'Lovelace',
+    locale: 'en-GB',
+  });
+}
+```
+
+## Signature
+
+```typescript
+function* askUserDirectorySetUserAttributes(
+  userDirectoryName: string,
+  username: string,
+  userAttributes: UserAttributes,
+): AskResponse<void>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `userDirectoryName` | `string` | Name of the directory — must match a directory declared with [defineUserDirectory](../../../config/core/user-directory.md). |
+| `username` | `string` | The user (email) to update. |
+| `userAttributes` | `UserAttributes` | The attributes to set. See [UserAttributes](./ask-user-directory-get-user-attributes.md#userattributes). All properties are optional; only those provided are written. |
+
+## Returns
+
+`void` — the story resumes once the attributes have been updated.
+
+## Errors
+
+| Error | Meaning |
+| --- | --- |
+| `UserDirectorySetUserAttributesErrorTypeEnum.UserNotFound` | No user matches the supplied username. |
+| `UserDirectorySetUserAttributesErrorTypeEnum.InvalidAttributes` | One or more supplied attribute names/values are invalid. |
+| `UserDirectorySetUserAttributesErrorTypeEnum.AliasExists` | An email/phone attribute value is already in use by another account. |
+| `UserDirectorySetUserAttributesErrorTypeEnum.LimitExceeded` | Too many attempts; back off and retry later. |
+
+## Related
+
+- [askUserDirectoryGetUserAttributes](./ask-user-directory-get-user-attributes.md) — read the attributes you are updating.
+- [askUserDirectoryCreateUser](./ask-user-directory-create-user.md) — set initial attributes at creation time.
+- [defineUserDirectory](../../../config/core/user-directory.md) — declares the directory.

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

@@ -0,0 +1 @@
+{ "label": "quidproquo-features", "position": 4, "link": { "type": "generated-index", "description": "Action requesters from quidproquo-features — event-document, AI-chat, admin, and validation stories." } }

package/template/docusaurus/docs/actions/features/event-doc/_category_.json

@@ -0,0 +1 @@
+{ "label": "Event documents", "link": { "type": "generated-index", "description": "Action requesters for event-sourced documents — create, read, delete, and resolve draft/published versions of a document derived by folding its event log." } }

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

@@ -0,0 +1,65 @@
+---
+title: askEventDocAppendServerEvent
+description: Append a server-authored event to a document's log, building the event envelope from a type, typed data, and version.
+---
+
+# askEventDocAppendServerEvent
+
+Appends a **server-authored** event to a document's log. It is the backend analog of the editor's client-side action creators: callers pass the effect `type`, the typed `data`, and the schema `version`, and it builds the `EventDocEventInput` envelope (minting a fresh `clientMessageId` for dedup) before delegating to [askEventDocEventAppend](./ask-event-doc-event-append.md). Use it for the rarer case where the server itself authors an event — for example recording a generated secret or a rendered artifact — rather than a client POSTing one.
+
+- **Built from:** `askNewGuid` + [askEventDocEventAppend](./ask-event-doc-event-append.md). Not a single action.
+- **Requires the store context** — provide it via [askEventDocProvideStore](./ask-event-doc-provide-store.md) or [askEventDocProvideStoreFromGlobals](./ask-event-doc-provide-store.md#askeventdocprovidestorefromglobals).
+
+```typescript
+import { askEventDocAppendServerEvent } from 'quidproquo-features';
+
+export function* recordGeneratedSecret(docId: string, secretRef: string) {
+  const actor = yield* askEventDocResolveActor();
+
+  return yield* askEventDocAppendServerEvent(
+    docId,
+    'SET_SECRET_REF',
+    { secretRef },
+    1, // schema version
+    actor,
+  );
+}
+```
+
+## Signature
+
+```typescript
+function* askEventDocAppendServerEvent<T>(
+  modelId: string,
+  type: string,
+  data: T,
+  version: number,
+  actor: EventDocEventActor,
+): AskResponse<EventDocEvent>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `modelId` | `string` | The document id whose log the event is appended to. |
+| `type` | `string` | The effect/event type discriminant to record. |
+| `data` | `T` | The typed domain data for the event. |
+| `version` | `number` | The schema version this event is authored against (see [askEventDocEventAppend](./ask-event-doc-event-append.md) for version rules). |
+| `actor` | `EventDocEventActor` | Who the event is stamped as authored by — `{ userId, userDisplayName }`. Typically from [askEventDocResolveActor](./ask-event-doc-resolve-actor.md). |
+
+## Returns
+
+`AskResponse<EventDocEvent>` — the appended event with its server-stamped metadata (`index`, `createdAt`, `createdBy`, and the generated `clientMessageId`).
+
+## Notes
+
+- All of [askEventDocEventAppend](./ask-event-doc-event-append.md)'s invariants apply — version monotonicity, lifecycle/payload validation, and optimistic-concurrency retry — since this is a thin envelope-building wrapper over it. It can therefore throw the same `ErrorTypeEnum.NotFound` / `ErrorTypeEnum.Conflict`.
+- A fresh `clientMessageId` is generated on every call, so this path does not participate in client retry dedup — each call is a distinct intended event.
+
+## Related
+
+- [askEventDocEventAppend](./ask-event-doc-event-append.md) — the underlying append this wraps.
+- [askEventDocWriteAsset](./ask-event-doc-generate-asset-upload-url.md#askeventdocwriteasset) — the server-side twin for writing asset bytes (often recorded by a server event).
+- [askEventDocResolveActor](./ask-event-doc-resolve-actor.md) — resolves the `actor` argument.
+- [askEventDocProvideStore](./ask-event-doc-provide-store.md) — provides the required store context.

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

@@ -0,0 +1,112 @@
+---
+title: askEventDocCreate
+description: Create an event-sourced document — seed its INIT_STATE event and derive the summary record.
+---
+
+# askEventDocCreate
+
+Creates a new event document. It seeds the document's log with an `INIT_STATE` event carrying the document's identity (`id`, `code`, `name`), then derives the queryable **summary record** from that event and writes it — the same fold-and-upsert path every later append uses, so create and append can never drift. Returns the new [`EventDocSummary`](./ask-event-doc-get-by-id.md#the-summary-record).
+
+- **Built from:** [askEventDocSeedInitState](#askeventdocseedinitstate) (writes the `INIT_STATE` event) then the summary reducer + [askEventDocUpsert](#askeventdocupsert) (persists the derived record). Requires the store context — call it inside `askEventDocProvideStore({ storeName, type }, ...)`, or from a built-in route where the context is already provided.
+
+```typescript
+import { askEventDocCreate } from 'quidproquo-features';
+
+export function* createArticle(name: string, code: string) {
+  const summary = yield* askEventDocCreate(name, code, {
+    userId: 'user-123',
+    userDisplayName: 'Ada Lovelace',
+  });
+
+  return summary; // EventDocSummary — id, code, name, versions: [...]
+}
+```
+
+## Signature
+
+```typescript
+function* askEventDocCreate(
+  name: string,
+  code: string,
+  actor: EventDocEventActor,
+): AskResponse<EventDocSummary>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `name` | `string` | Human-readable name for the document. Stored on the summary and editable later via a `SET_NAME` event. |
+| `code` | `string` | The document's stable business **code** — a caller-chosen key (e.g. a slug or reference) that stays constant across versions, expected unique within the collection (and any owner scope). Editable later via a `SET_CODE` event. |
+| `actor` | `EventDocEventActor` | Who is creating the document — recorded on the `INIT_STATE` event and as the record's `createdBy`/`updatedBy`. |
+
+### `EventDocEventActor`
+
+```typescript
+type EventDocEventActor = {
+  userId: string;         // stable, authoritative user key
+  userDisplayName: string; // display-only snapshot, as it was at event time
+};
+```
+
+A point-in-time snapshot of who produced an event, captured server-side at append time. Denormalised so history renders without a user lookup.
+
+## Returns
+
+`EventDocSummary` — the freshly derived summary record. Its `versions` array holds the first (draft) version pointer; `status` is `Draft`; `createdAt`/`updatedAt` are the `INIT_STATE` time.
+
+## Notes
+
+- The record is validated against `eventDocSummarySchema` before it is written; a schema violation throws (`ErrorTypeEnum` from quidproquo-core).
+- Not concurrency-safe against duplicate codes on its own. If two callers may create the same `code` at once, prefer [askEventDocGetByCodeOrCreate](./ask-event-doc-get-by-code.md#askeventdocgetbycodeorcreate) and serialise, or add a conditional create.
+
+---
+
+## askEventDocSeedInitState
+
+Seeds a new document's log with its `INIT_STATE` event at index `0`, carrying the identity (`id`/`code`/`name`). This is the create-only primitive `askEventDocCreate` composes; clients never send `INIT_STATE` themselves. It writes the event and returns it.
+
+```typescript
+function* askEventDocSeedInitState(
+  modelId: string,
+  code: string,
+  name: string,
+  actor: EventDocEventActor,
+): AskResponse<EventDocEvent>;
+```
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `modelId` | `string` | The new document's id (the log's partition). Usually a fresh GUID. |
+| `code` | `string` | The document's business code (see above). |
+| `name` | `string` | The document's name. |
+| `actor` | `EventDocEventActor` | Who is creating the document. |
+
+**Returns** `EventDocEvent` — the written `INIT_STATE` event, with `payload.metadata.index === 0` and `version === 1`.
+
+Use `askEventDocCreate` unless you are building a custom create flow that needs the raw event; `askEventDocSeedInitState` alone writes the log but does **not** derive or persist the summary record.
+
+## askEventDocUpsert
+
+The bare storage write for a summary record — a thin wrapper over the key-value store upsert (with retry). Business rules and validation live in the logic layer (e.g. `askEventDocCreate`, [askEventDocSoftDelete](./ask-event-doc-soft-delete.md)); this just persists whatever record you hand it.
+
+```typescript
+function* askEventDocUpsert(model: EventDocSummary): AskResponse<void>;
+```
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `model` | `EventDocSummary` | The full summary record to write (create or overwrite). |
+
+**Returns** `void`.
+
+Prefer the higher-level lifecycle actions over calling `askEventDocUpsert` directly — writing an un-derived record can put the summary out of sync with the event log.
+
+## Related
+
+- [askEventDocGetByCodeOrCreate](./ask-event-doc-get-by-code.md#askeventdocgetbycodeorcreate) — create-on-first-use built on top of this.
+- [askEventDocGetById / askEventDocGetByIdOrThrow](./ask-event-doc-get-by-id.md) — read the record back.
+- [askEventDocSoftDelete](./ask-event-doc-soft-delete.md) — retire a document.
+- **Appending events after create:** `askEventDocEventAppend` (quidproquo-features) applies each later event through the same reducer.
+- [defineEventDocSummary](../../../config/features/event-doc-summary.md) — declares the store this writes to.
+- [askNewGuid](../../core/guid/ask-new-guid.md) / [askDateNow](../../core/date/ask-date-now.md) — the core actions the create path uses for id and timestamps.

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

@@ -0,0 +1,97 @@
+---
+title: askEventDocEventAppend
+description: Append a client-authored event to a document's log with dedup, version and lifecycle validation, and optimistic-concurrency retry.
+---
+
+# askEventDocEventAppend
+
+Appends a single client-authored event to a document's ordered event stream — the write half of the event-sourcing core. This is where the append-time safety invariants live: idempotent dedup, version monotonicity, lifecycle/payload validation, and optimistic-concurrency retry. After the event is written it also re-derives the queryable summary record so the document's status, version, name, and timestamps stay in sync with the log.
+
+- **Built from:** a story composing `askRetry`, `askEventDocEventLast`, `askEventDocEventListAll`, `askEventDocEventWrite`, `askEventDocGetByIdOrThrow`, and (when the collection configures one) an `askInlineFunctionExecute` validator. Not a single action.
+- **Requires the store context** — wrap the call in [askEventDocProvideStore](./ask-event-doc-provide-store.md) (custom routes) or [askEventDocProvideStoreFromGlobals](./ask-event-doc-provide-store.md#askeventdocprovidestorefromglobals) (built-in routes).
+
+```typescript
+import { askEventDocEventAppend } from 'quidproquo-features';
+
+export function* appendTitleChange(docId: string) {
+  const actor = yield* askEventDocResolveActor();
+
+  const event = yield* askEventDocEventAppend(
+    docId,
+    {
+      type: 'SET_NAME',
+      payload: {
+        data: { name: 'Q3 Report' },
+        metadata: { version: 3, clientMessageId: yield* askNewGuid() },
+      },
+    },
+    actor,
+  );
+
+  return event.payload.metadata.index;
+}
+```
+
+## Signature
+
+```typescript
+function* askEventDocEventAppend(
+  modelId: string,
+  input: EventDocEventInput,
+  actor: EventDocEventActor,
+): AskResponse<EventDocEvent>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `modelId` | `string` | The document id whose log the event is appended to. The document must already have an `INIT_STATE` event (created via `askEventDocCreate`), or the append throws `NotFound`. |
+| `input` | `EventDocEventInput` | The client-authored event envelope — see below. |
+| `actor` | `EventDocEventActor` | Who authored the event; stamped onto the event as `createdBy`. Usually obtained from [askEventDocResolveActor](./ask-event-doc-resolve-actor.md). |
+
+### `EventDocEventInput`
+
+What the client POSTs to append an event. `modelId` and the server-stamped provenance (`index`, `createdAt`, `createdBy`) are NOT part of it.
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `type` | `string` | The effect/event type discriminant (e.g. `SET_NAME`). The reducer folds it by this. |
+| `payload.data` | `T` | The typed domain data for the event. |
+| `payload.metadata.version` | `number` | The schema version the client authored against. Must be `>=` the last event's version — an older version throws `Conflict`. |
+| `payload.metadata.clientMessageId` | `string` | A client-generated id used for dedup: if the latest event already carries it, the append is a no-op and returns that event unchanged. |
+
+### `EventDocEventActor`
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `userId` | `string` | The stable, authoritative user key. |
+| `userDisplayName` | `string` | The display name captured at append time (denormalised so history renders without a user lookup). |
+
+## Returns
+
+`AskResponse<EventDocEvent>` — the event that now lives in the log, with server-stamped metadata (`index`, `createdAt`, `createdBy`) filled in. On a deduped retry, the pre-existing event is returned unchanged.
+
+### `EventDocEvent`
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `type` | `string` | The event type discriminant. |
+| `payload.data` | `T` | The typed domain data. |
+| `payload.metadata` | `EventDocEventMetadata` | Full provenance: `version`, `clientMessageId`, `createdBy`, `createdAt`, and `index` (mirrors the storage sort key). |
+
+## Notes
+
+- **Dedup** is best-effort against the latest event only (until a GSI exists): a retry that re-sends the same `clientMessageId` returns the existing tail event without writing.
+- **Validation** always runs against the log folded from prior events. If the collection configured an `eventValidator` inline function it runs that (a complete validator that already composes the reserved lifecycle guard); otherwise it runs `defaultEventDocEventValidator` — the same guard with no domain rules. Exactly one validator runs. A rejected event throws `Conflict` with the validator's reason.
+- **Concurrency:** the underlying write ([askEventDocEventWrite](./ask-event-doc-event-write.md)) claims the `(modelId, index)` slot conditionally. A losing concurrent writer gets a key-value-store upsert conflict — the only error the internal `askRetry` re-laps on — re-reads the tail, and re-runs dedup/validation against fresh state, so concurrent appends serialize onto consecutive indexes. After `MAX_APPEND_ATTEMPTS` (8) lost races it throws `ErrorTypeEnum.Conflict`.
+- **Thrown `ErrorTypeEnum` values:** `NotFound` (no `INIT_STATE`), `Conflict` (stale version, failed validation, or exhausted concurrency retries). These are thrown via `askThrowError`, not a per-action error enum.
+- After writing, it re-derives and upserts the document's summary record (via `applyEventDocSummaryEvent`) so the queryable view stays consistent with the log.
+
+## Related
+
+- [askEventDocAppendServerEvent](./ask-event-doc-append-server-event.md) — the server-authored wrapper that builds the input envelope for you.
+- [askEventDocEventWrite](./ask-event-doc-event-write.md) — the low-level conditional write this composes.
+- [askEventDocEventList / EventListAll / EventLast](./ask-event-doc-event-list.md) — reading the log this appends to.
+- [askEventDocProvideStore](./ask-event-doc-provide-store.md) — provides the store context this requires.
+- [askEventDocResolveActor](./ask-event-doc-resolve-actor.md) — resolves the `actor` argument from the access token.

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

@@ -0,0 +1,116 @@
+---
+title: askEventDocEventList
+description: Read a document's event log — a page of events, the whole log flattened, or just the latest event.
+---
+
+# Reading the event log
+
+Three read helpers over a document's event stream. All three resolve the collection's events store from the store context and query it by `pk = modelId`, ascending by log index (except `askEventDocEventLast`, which reads the tail). They are the read side of the event-sourcing core, feeding the fold that reconstructs a document from its events.
+
+- **Requires the store context** — provide it via [askEventDocProvideStore](./ask-event-doc-provide-store.md) / [askEventDocProvideStoreFromGlobals](./ask-event-doc-provide-store.md#askeventdocprovidestorefromglobals).
+- **Built from:** [askKeyValueStoreQuery](../../core/key-value-store/ask-key-value-store-query.md) against the events store, plus [askEventDocResolveStore](./ask-event-doc-provide-store.md#askeventdocresolvestore). Not single actions.
+
+## askEventDocEventList
+
+Returns one page of events for a document, oldest first. Supports paging and, via `afterIndex`, fetching only the tail since a known index — an incremental refresh.
+
+```typescript
+import { askEventDocEventList } from 'quidproquo-features';
+
+export function* refreshSince(docId: string, lastSeenIndex: number) {
+  const page = yield* askEventDocEventList(docId, { afterIndex: lastSeenIndex });
+  return page.items; // events with index > lastSeenIndex
+}
+```
+
+### Signature
+
+```typescript
+function* askEventDocEventList(
+  modelId: string,
+  options?: EventDocEventListOptions,
+): AskResponse<QpqPagedData<EventDocEvent>>;
+```
+
+### Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `modelId` | `string` | The document id to read events for. |
+| `options` | `EventDocEventListOptions` | Optional paging / range options — see below. |
+
+#### `EventDocEventListOptions`
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `limit` | `number` | (store default) | Max number of events to return in the page. |
+| `nextPageKey` | `string` | — | Continuation token from a previous page's `nextPageKey`. |
+| `afterIndex` | `number` | — | Return only events whose log index is greater than this (exclusive). A sort-key range condition on the events store's primary key — no GSI involved. |
+
+### Returns
+
+`AskResponse<QpqPagedData<EventDocEvent>>` — `{ items: EventDocEvent[]; nextPageKey?: string }`. Events are ordered ascending by index; `nextPageKey` is present when more events remain.
+
+## askEventDocEventListAll
+
+Pages through the **whole** log (ascending) and returns it as a flat array — the complete history a from-scratch fold needs. The append-time validator uses this; until state snapshots exist it re-reads the full log per validated append, so treat it as O(log length).
+
+```typescript
+import { askEventDocEventListAll } from 'quidproquo-features';
+
+export function* fullHistory(docId: string) {
+  return yield* askEventDocEventListAll(docId); // EventDocEvent[]
+}
+```
+
+### Signature
+
+```typescript
+function* askEventDocEventListAll(modelId: string): AskResponse<EventDocEvent[]>;
+```
+
+### Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `modelId` | `string` | The document id to read the full log for. |
+
+### Returns
+
+`AskResponse<EventDocEvent[]>` — every event for the document, ordered ascending by index. Internally loops [askEventDocEventList](#askeventdoceventlist) until there is no `nextPageKey`.
+
+## askEventDocEventLast
+
+Returns the newest event in the log, or `null` if the document has no events. Used to assign the next index, dedup, and validate during an append. Relies on numeric sort-key ordering (the dev server sorts numeric sort keys numerically, matching DynamoDB), so it returns the true latest.
+
+```typescript
+import { askEventDocEventLast } from 'quidproquo-features';
+
+export function* currentVersion(docId: string) {
+  const last = yield* askEventDocEventLast(docId);
+  return last ? last.payload.metadata.version : 0;
+}
+```
+
+### Signature
+
+```typescript
+function* askEventDocEventLast(modelId: string): AskResponse<Nullable<EventDocEvent>>;
+```
+
+### Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `modelId` | `string` | The document id to read the tail of. |
+
+### Returns
+
+`AskResponse<Nullable<EventDocEvent>>` — the latest [EventDocEvent](./ask-event-doc-event-append.md#eventdocevent), or `null` when the log is empty.
+
+## Related
+
+- [askEventDocEventAppend](./ask-event-doc-event-append.md) — the write side; uses `EventLast` and `EventListAll` internally.
+- [askEventDocEventWrite](./ask-event-doc-event-write.md) — the low-level conditional write.
+- [askEventDocProvideStore](./ask-event-doc-provide-store.md) — provides the store context these require.
+- [askKeyValueStoreQuery](../../core/key-value-store/ask-key-value-store-query.md) — the underlying query action.

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

@@ -0,0 +1,50 @@
+---
+title: askEventDocEventWrite
+description: Low-level conditional write of a single event to a document's events store, claiming its (modelId, index) slot atomically.
+---
+
+# askEventDocEventWrite
+
+The low-level write primitive behind the event log. It persists one already-built [EventDocEvent](./ask-event-doc-event-append.md#eventdocevent) into the collection's events store, keyed by `pk = modelId` / `sk = index`. The write is **conditional** (`ifNotExists`): the `(modelId, index)` slot is claimed atomically, so a concurrent writer that computed the same index gets a conflict instead of silently overwriting the event.
+
+Ordering, index assignment, dedup, validation, and the conflict-retry loop all live one layer up in [askEventDocEventAppend](./ask-event-doc-event-append.md) — you almost always want that instead. Call this directly only when you are implementing your own append semantics.
+
+- **Built from:** [askKeyValueStoreUpsertWithRetry](../../core/key-value-store/ask-key-value-store-upsert-with-retry.md) with `{ ifNotExists: true }`, plus [askEventDocResolveStore](./ask-event-doc-provide-store.md#askeventdocresolvestore) to find the events store name. Not a single action.
+- **Requires the store context** — provide it via [askEventDocProvideStore](./ask-event-doc-provide-store.md) / [askEventDocProvideStoreFromGlobals](./ask-event-doc-provide-store.md#askeventdocprovidestorefromglobals).
+
+```typescript
+import { askEventDocEventWrite } from 'quidproquo-features';
+
+export function* persistPrebuiltEvent(docId: string, event: EventDocEvent) {
+  yield* askEventDocEventWrite(docId, event);
+}
+```
+
+## Signature
+
+```typescript
+function* askEventDocEventWrite(modelId: string, event: EventDocEvent): AskResponse<void>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `modelId` | `string` | The document id — becomes the partition key (`pk`) of the stored event. |
+| `event` | `EventDocEvent` | A fully-formed event, including `payload.metadata.index` — the index becomes the sort key (`sk`) and the slot that is claimed conditionally. |
+
+## Returns
+
+`AskResponse<void>` — the story resumes once the event is written.
+
+## Notes
+
+- The stored shape is `{ pk: modelId, sk: index, data: event }`; the `EventDocStoredEvent` mapping is the only place that knows the key layout, keeping the domain event free of storage concerns.
+- Because the write is conditional, a losing concurrent writer surfaces `KeyValueStoreUpsertErrorTypeEnum.Conflict`. [askEventDocEventAppend](./ask-event-doc-event-append.md) is the layer that catches and re-laps on exactly that error.
+
+## Related
+
+- [askEventDocEventAppend](./ask-event-doc-event-append.md) — the high-level append that computes the index, validates, and retries around this write.
+- [askEventDocEventList / EventListAll / EventLast](./ask-event-doc-event-list.md) — reading events back.
+- [askKeyValueStoreUpsertWithRetry](../../core/key-value-store/ask-key-value-store-upsert-with-retry.md) — the underlying conditional upsert.
+- [askEventDocProvideStore](./ask-event-doc-provide-store.md) — provides the required store context.

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

@@ -0,0 +1,127 @@
+---
+title: askEventDocGenerateAssetUploadUrl
+description: Manage a document's immutable assets — mint presigned upload/download URLs, or write server-generated bytes directly.
+---
+
+# Document assets
+
+A document can point at binary **assets** — images, fonts, rendered artifacts — without embedding the bytes. Each asset is stored immutably on the collection's storage drive under `<docId>/assets/<guid>`, and the document records only a reference (the guid) inside a domain event. Because every upload gets a fresh guid, a re-upload is a new blob and prior references stay addressable for history and rollback.
+
+These three helpers cover the two flows: presigned URLs for a browser to upload/download bytes directly, and a server-side write for when the backend already holds the bytes.
+
+- **Requires the store context** — provide it via [askEventDocProvideStore](./ask-event-doc-provide-store.md) / [askEventDocProvideStoreFromGlobals](./ask-event-doc-provide-store.md#askeventdocprovidestorefromglobals). The drive name is resolved from that context.
+- **Built from:** the core file secure-URL / binary-write actions on the collection's storage drive, plus [askEventDocResolveStore](./ask-event-doc-provide-store.md#askeventdocresolvestore). Not single actions.
+
+## 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.
+
+```typescript
+import { askEventDocGenerateAssetUploadUrl } from 'quidproquo-features';
+
+export function* startImageUpload(docId: string) {
+  const { uploadUrl, assetId } = yield* askEventDocGenerateAssetUploadUrl(docId, 'image/png');
+  // client PUTs bytes to uploadUrl, then appends an event recording assetId
+  return { uploadUrl, assetId };
+}
+```
+
+### Signature
+
+```typescript
+function* askEventDocGenerateAssetUploadUrl(
+  docId: string,
+  contentType: string,
+): AskResponse<EventDocAssetUploadUrl>;
+```
+
+### Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `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. |
+
+### Returns
+
+`AskResponse<EventDocAssetUploadUrl>` — `{ uploadUrl: string; assetId: string }`. The URL is valid for 5 minutes; `assetId` is the guid that names the blob, to be recorded in a domain event.
+
+## askEventDocGenerateAssetDownloadUrl
+
+Returns a short-lived presigned `GET` URL the client loads an asset's bytes from — e.g. as an `<img src>` or to build a data URL. Read-only, no mutation.
+
+```typescript
+import { askEventDocGenerateAssetDownloadUrl } from 'quidproquo-features';
+
+export function* imageSrc(docId: string, assetId: string) {
+  const { url } = yield* askEventDocGenerateAssetDownloadUrl(docId, assetId);
+  return url;
+}
+```
+
+### Signature
+
+```typescript
+function* askEventDocGenerateAssetDownloadUrl(
+  docId: string,
+  assetId: string,
+): AskResponse<EventDocAssetDownloadUrl>;
+```
+
+### Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `docId` | `string` | The document the asset belongs to. |
+| `assetId` | `string` | The guid recorded when the asset was uploaded. |
+
+### Returns
+
+`AskResponse<EventDocAssetDownloadUrl>` — `{ url: string }`, a presigned `GET` URL valid for about 15 minutes. Re-request when it expires.
+
+## askEventDocWriteAsset
+
+Writes a server-generated binary as an immutable asset directly on the collection's storage drive (under the same `<docId>/assets/<guid>` scheme) and returns a reference to it. This is the server-side twin of the presigned-upload flow — for when the backend itself holds the bytes (e.g. a rendered PDF) and no client round-trip is needed. The download route can serve it back via the same key.
+
+```typescript
+import { askEventDocWriteAsset } from 'quidproquo-features';
+
+export function* storeRenderedPdf(docId: string, pdf: QPQBinaryData) {
+  const ref = yield* askEventDocWriteAsset(docId, pdf);
+  // record ref.guid in a domain event, e.g. via askEventDocAppendServerEvent
+  return ref;
+}
+```
+
+### Signature
+
+```typescript
+function* askEventDocWriteAsset(
+  docId: string,
+  binary: QPQBinaryData,
+): AskResponse<EventDocAssetRef>;
+```
+
+### Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `docId` | `string` | The document the asset belongs to. |
+| `binary` | `QPQBinaryData` | The bytes to write — `{ base64Data, filename, mimetype?, contentDisposition? }`. A missing `mimetype` falls back to `application/octet-stream`. |
+
+### Returns
+
+`AskResponse<EventDocAssetRef>` — `{ guid, filename, mimetype }`, a first-class reference to record in a domain event so the document points at the bytes without embedding them.
+
+## Notes
+
+- All three resolve the drive from the store context, so a missing context throws (see [askEventDocResolveStore](./ask-event-doc-provide-store.md#askeventdocresolvestore)).
+- Assets are immutable: guid-named so a re-upload is always a fresh blob; the old one stays addressable for history/rollback. Assets live under `<docId>/assets/<guid>`; derived, disposable artifacts use a sibling `<docId>/runtime/<...>` prefix written elsewhere.
+
+## Related
+
+- [askFileGenerateTemporaryUploadSecureUrl](../../core/file/ask-file-generate-temporary-upload-secure-url.md) — the core action behind the upload URL.
+- [askFileGenerateTemporarySecureUrl](../../core/file/ask-file-generate-temporary-secure-url.md) — the core action behind the download URL.
+- [askFileWriteBinaryContents](../../core/file/ask-file-write-binary-contents.md) — the core action behind the server-side write.
+- [askEventDocAppendServerEvent](./ask-event-doc-append-server-event.md) — record an asset reference in the log from server code.
+- [askEventDocProvideStore](./ask-event-doc-provide-store.md) — provides the store context (and drive) these require.