create-qpq-app 0.1.5

package/template/docusaurus/docs/actions/core/context/ask-context-provide-value.md

@@ -0,0 +1,78 @@
+---
+title: askContextProvideValue
+description: Provide a context value for the duration of a wrapped sub-story, visible to every action inside it.
+---
+
+# askContextProvideValue
+
+Runs a wrapped sub-story with a **context** value set, making that value visible to every [askContextRead](./ask-context-read.md) beneath it. This is the "provider" half of story context (the React-context analogy: `askContextProvideValue` is the `<Provider>`, `askContextRead` is `useContext`). The value applies only for the duration of the wrapped story; once it returns, the context reverts.
+
+The wrapped story's return value is passed straight back out, so you can wrap any sub-story transparently.
+
+- **Action type:** implemented on top of [askOverrideActions](../system/ask-override-actions.md) — it intercepts `Context/Read` (and the internal `Context/List`) for the matching identifier while the sub-story runs, and injects the value onto every relayed action so it survives into nested runtimes.
+
+```typescript
+import { askContextProvideValue, askContextRead, createContextIdentifier } from 'quidproquo-core';
+
+export const CurrentTenantContext = createContextIdentifier<string>('current-tenant', 'public');
+
+export function* askHandleRequest(tenant: string) {
+  // Everything inside askProcessOrder can read CurrentTenantContext and see `tenant`.
+  return yield* askContextProvideValue(CurrentTenantContext, tenant, askProcessOrder());
+}
+
+function* askProcessOrder() {
+  const tenant = yield* askContextRead(CurrentTenantContext); // -> the provided tenant
+  // ...
+}
+```
+
+## Signature
+
+```typescript
+function* askContextProvideValue<R, T extends AskResponse<any>>(
+  contextIdentifier: QpqContextIdentifier<R>,
+  value: R,
+  storyIterator: T,
+): AskResponse<AskResponseReturnType<T>>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `contextIdentifier` | `QpqContextIdentifier<R>` | The identifier to provide a value for — see [askContextRead](./ask-context-read.md#qpqcontextidentifiert). The value's type `R` must match the identifier's type. |
+| `value` | `R` | The value to expose to reads of this identifier inside `storyIterator`. |
+| `storyIterator` | `AskResponse<...>` | The sub-story to run with the context in effect, e.g. `askProcessOrder()`. |
+
+## Returns
+
+The value returned by `storyIterator` — its type is inferred, so wrapping a story doesn't change what it returns.
+
+## Reusable providers with `createContextProvider`
+
+When you provide the same context in many places, `createContextProvider` builds a typed wrapper so you don't repeat the identifier at every call site. You give it the identifier and a mapper from your own arguments to the context value; it returns a generator you call with those arguments plus the sub-story:
+
+```typescript
+import { createContextProvider, createContextIdentifier } from 'quidproquo-core';
+
+const CurrentUserContext = createContextIdentifier<{ id: string } | null>('current-user', null);
+
+// Maps a userId argument into the stored context value.
+export const askProvideCurrentUser = createContextProvider(CurrentUserContext, (userId: string) => ({ id: userId }));
+
+export function* askHandle(userId: string) {
+  return yield* askProvideCurrentUser(userId, askDoWork());
+}
+```
+
+## Notes
+
+- Nesting is supported: an inner provider for the same identifier shadows an outer one for the extent of its sub-story.
+- For a value that must not cross service boundaries, create the identifier with `createLocalContextIdentifier` — see [Local context](./ask-context-read.md#local-context).
+
+## Related
+
+- [askContextRead](./ask-context-read.md) — reads the value provided here.
+- [askOverrideActions](../system/ask-override-actions.md) — the lower-level action-interception primitive this is built on.
+- [askEventDocProvideStore](../../features/event-doc/ask-event-doc-provide-store.md) — the event-doc store context, built on this pattern.

package/template/docusaurus/docs/actions/core/context/ask-context-read.md

@@ -0,0 +1,96 @@
+---
+title: askContextRead
+description: Read the current value of a story context by its identifier, falling back to the identifier's default.
+---
+
+# askContextRead
+
+Reads the current value of a **context** for the running story. Context is ambient, story-scoped state — think of it as React context for stories: a value provided higher up the story tree with [askContextProvideValue](./ask-context-provide-value.md) is visible to every action beneath it, without being threaded through each function call.
+
+If no provider up the tree has set a value for the identifier, the identifier's `defaultValue` is returned.
+
+- **Action type:** `ContextActionType.Read`
+- **Resolution:** read from the story session's context bag (or the separate local-context bag for a [local identifier](#local-context)); no external call.
+
+```typescript
+import { askContextRead, createContextIdentifier } from 'quidproquo-core';
+
+// Declare an identifier once, export it, and share it between reader and provider.
+export const CurrentTenantContext = createContextIdentifier<string>('current-tenant', 'public');
+
+export function* askGetTenantScopedKey(key: string) {
+  const tenant = yield* askContextRead(CurrentTenantContext);
+  return `${tenant}/${key}`;
+}
+```
+
+## Signature
+
+```typescript
+function* askContextRead<T>(
+  contextIdentifier: QpqContextIdentifier<T>,
+): AskResponse<T>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `contextIdentifier` | `QpqContextIdentifier<T>` | The identifier to read, created with [createContextIdentifier](#creating-an-identifier) (or `createLocalContextIdentifier`). Its type parameter `T` determines the return type. |
+
+### `QpqContextIdentifier<T>`
+
+```typescript
+interface QpqContextIdentifier<T> {
+  uniqueName: string;
+  defaultValue: T;
+  local?: boolean;
+}
+```
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `uniqueName` | `string` | Globally unique name that ties a reader to the matching provider. |
+| `defaultValue` | `T` | Returned by `askContextRead` when no provider has set a value. |
+| `local` | `boolean?` | When `true`, the value lives in a separate bag that never crosses a service boundary — see [Local context](#local-context). |
+
+## Creating an identifier
+
+Use `createContextIdentifier<T>(uniqueName, defaultValue)` to make an identifier, and share the same instance between the code that provides the value and the code that reads it:
+
+```typescript
+import { createContextIdentifier } from 'quidproquo-core';
+
+export const RequestIdContext = createContextIdentifier<string>('request-id', '');
+```
+
+## Reusable readers with `createContextReader`
+
+If you read the same context in many places, `createContextReader(identifier)` returns a zero-argument generator bound to that identifier, so call sites don't repeat it:
+
+```typescript
+import { createContextReader, createContextIdentifier } from 'quidproquo-core';
+
+const CurrentTenantContext = createContextIdentifier<string>('current-tenant', 'public');
+export const askCurrentTenant = createContextReader(CurrentTenantContext);
+
+export function* askDoWork() {
+  const tenant = yield* askCurrentTenant();
+  // ...
+}
+```
+
+## Returns
+
+`T` — the current context value, or the identifier's `defaultValue` if none was provided.
+
+## Local context
+
+A context created with `createLocalContextIdentifier<T>(uniqueName, defaultValue)` behaves exactly like a normal one within the service — it flows down the story tree and into in-process sub-runtimes — but its value is **never serialized across a service boundary** (queue, event bus, or cross-service call). Use it for values that are only meaningful in the current process, like an in-memory cache handle or a request-local flag.
+
+> There is also an internal `Context/List` action that gathers the full context bag for propagation across service boundaries; it isn't part of the public story API — use `askContextRead` to read individual values.
+
+## Related
+
+- [askContextProvideValue](./ask-context-provide-value.md) — provides the value this action reads.
+- [askEventDocStoreRead](../../features/event-doc/ask-event-doc-provide-store.md#askeventdocstoreread) — the event-doc store reader, built on this pattern.

package/template/docusaurus/docs/actions/core/date/_category_.json

@@ -0,0 +1,7 @@
+{
+  "label": "Date",
+  "link": {
+    "type": "generated-index",
+    "description": "Read the current date/time from the runtime."
+  }
+}

package/template/docusaurus/docs/actions/core/date/ask-date-now.md

@@ -0,0 +1,50 @@
+---
+title: askDateNow
+description: Read the current date and time from the runtime as an ISO-8601 timestamp.
+---
+
+# askDateNow
+
+Reads the current wall-clock time from the runtime and returns it as an ISO-8601 timestamp string.
+
+- **Action type:** `DateActionType.Now`
+- **At runtime:** resolves to `new Date()` formatted as a UTC ISO-8601 string (e.g. `2026-06-26T00:00:00.000Z`).
+
+Reading the clock is a source of non-determinism, so a story never calls `new Date()` directly. Instead it `yield*`s this action and lets the runtime supply the value. Because the runtime resolves the action, the resolved timestamp is recorded in the execution log — the story stays a pure generator that can be inspected, tested, and replayed with the exact same "now" it saw on the original run.
+
+```typescript
+import { askDateNow } from 'quidproquo-core';
+
+export function* askStampRecord() {
+  const createdAt = yield* askDateNow();
+  return { createdAt };
+}
+```
+
+## Signature
+
+```typescript
+function* askDateNow(): AskResponse<QpqIsoDateTime>;
+```
+
+## Parameters
+
+None.
+
+## Returns
+
+`QpqIsoDateTime` — the current time as a UTC ISO-8601 string of the form `YYYY-MM-DDTHH:mm:ss.sssZ` (e.g. `2026-06-26T00:00:00.000Z`). `QpqIsoDateTime` is a template-literal string type exported from quidproquo-core, so it is a plain `string` at runtime with extra compile-time shape checking.
+
+## Notes
+
+- The timestamp is always in UTC (trailing `Z`) with millisecond precision.
+- Being a string, the value is safe to store in a key-value store, return from an API, or compare lexicographically (ISO-8601 sorts chronologically as text).
+
+## Related
+
+- [askGuidNewSortable](../guid/ask-new-sortable-guid.md) — for a time-ordered identifier, generated as a single sortable id rather than a timestamp.
+- [askGetCurrentEpoch](./ask-get-current-epoch.md) / [askGetCurrentEpochMs](./ask-get-current-epoch-ms.md) — the current time as seconds / milliseconds since the Unix epoch.
+- [askGetEpochStartTime](./ask-get-epoch-start-time.md) — the Unix epoch as an ISO-8601 string.
+- [askSecondsElapsedFrom](./ask-seconds-elapsed-from.md) — seconds between two ISO-8601 timestamps.
+- [Date/time math helpers](./date-time-math.md) — shift an ISO-8601 timestamp by days, months, or years.
+- [askEventDocCreate](../../features/event-doc/ask-event-doc-create.md) / [askEventDocSoftDelete](../../features/event-doc/ask-event-doc-soft-delete.md) — stamp event-document timestamps with this.

package/template/docusaurus/docs/actions/core/date/ask-get-current-epoch-ms.md

@@ -0,0 +1,45 @@
+---
+title: askGetCurrentEpochMs
+description: Read the current time as milliseconds since the Unix epoch.
+---
+
+# askGetCurrentEpochMs
+
+Reads the current wall-clock time and returns it as the number of **milliseconds** elapsed since the Unix epoch (`1970-01-01T00:00:00.000Z`).
+
+- Built from [askDateNow](./ask-date-now.md): it reads the runtime clock and converts the ISO-8601 timestamp to a millisecond count with `new Date(...).getTime()`.
+
+```typescript
+import { askGetCurrentEpochMs } from 'quidproquo-core';
+
+export function* askStampMillis() {
+  const nowMs = yield* askGetCurrentEpochMs();
+  return { nowMs };
+}
+```
+
+## Signature
+
+```typescript
+function* askGetCurrentEpochMs(): AskResponse<number>;
+```
+
+## Parameters
+
+None.
+
+## Returns
+
+`number` — milliseconds since the Unix epoch, e.g. `1782518400000`. This matches JavaScript's native `Date.getTime()` / `Date.now()` unit.
+
+## Notes
+
+- Because the value comes from [askDateNow](./ask-date-now.md), the reading is resolved by the runtime and recorded in the execution log, keeping the story deterministic and replayable.
+- For a whole-second count (the usual "Unix timestamp"), use [askGetCurrentEpoch](./ask-get-current-epoch.md) instead.
+
+## Related
+
+- [askGetCurrentEpoch](./ask-get-current-epoch.md) — the same reading truncated to whole seconds.
+- [askDateNow](./ask-date-now.md) — the underlying clock read, as an ISO-8601 string.
+- [askGetEpochStartTime](./ask-get-epoch-start-time.md) — the epoch itself as an ISO-8601 string.
+- [askSecondsElapsedFrom](./ask-seconds-elapsed-from.md) — seconds between two timestamps.

package/template/docusaurus/docs/actions/core/date/ask-get-current-epoch.md

@@ -0,0 +1,45 @@
+---
+title: askGetCurrentEpoch
+description: Read the current time as whole seconds since the Unix epoch.
+---
+
+# askGetCurrentEpoch
+
+Reads the current wall-clock time and returns it as the number of whole **seconds** elapsed since the Unix epoch (`1970-01-01T00:00:00.000Z`) — the conventional "Unix timestamp".
+
+- Built from [askGetCurrentEpochMs](./ask-get-current-epoch-ms.md): it takes the millisecond epoch and floors it to whole seconds (`Math.floor(ms / 1000)`).
+
+```typescript
+import { askGetCurrentEpoch } from 'quidproquo-core';
+
+export function* askBuildJwtClaims() {
+  const iat = yield* askGetCurrentEpoch();
+  return { iat, exp: iat + 3600 };
+}
+```
+
+## Signature
+
+```typescript
+function* askGetCurrentEpoch(): AskResponse<number>;
+```
+
+## Parameters
+
+None.
+
+## Returns
+
+`number` — whole seconds since the Unix epoch, e.g. `1782518400`. Any sub-second remainder is discarded (floored toward zero), so this is always an integer. Useful anywhere a second-precision Unix timestamp is expected, such as JWT `iat`/`exp` claims.
+
+## Notes
+
+- The underlying reading comes from [askDateNow](./ask-date-now.md) via [askGetCurrentEpochMs](./ask-get-current-epoch-ms.md), so the value is resolved by the runtime and recorded in the execution log — the story stays deterministic and replayable.
+- For millisecond precision, use [askGetCurrentEpochMs](./ask-get-current-epoch-ms.md).
+
+## Related
+
+- [askGetCurrentEpochMs](./ask-get-current-epoch-ms.md) — the same reading with millisecond precision.
+- [askDateNow](./ask-date-now.md) — the underlying clock read, as an ISO-8601 string.
+- [askGetEpochStartTime](./ask-get-epoch-start-time.md) — the epoch itself as an ISO-8601 string.
+- [askSecondsElapsedFrom](./ask-seconds-elapsed-from.md) — seconds between two timestamps.

package/template/docusaurus/docs/actions/core/date/ask-get-epoch-start-time.md

@@ -0,0 +1,40 @@
+---
+title: askGetEpochStartTime
+description: Get the Unix epoch start as an ISO-8601 timestamp string.
+---
+
+# askGetEpochStartTime
+
+Returns the start of the Unix epoch — `1970-01-01T00:00:00.000Z` — as an ISO-8601 timestamp. Handy as a "zero" / earliest-possible date when seeding comparisons, default `since` cursors, or age calculations.
+
+- A small composed story that returns the epoch constant as a `QpqIsoDateTime`. It performs no clock read, so it always resolves to the same value.
+
+```typescript
+import { askGetEpochStartTime, askSecondsElapsedFrom } from 'quidproquo-core';
+
+export function* askAgeInSeconds(createdAt: string) {
+  const epoch = yield* askGetEpochStartTime();
+  // e.g. compare against the epoch as a lower bound
+  return yield* askSecondsElapsedFrom(epoch, createdAt);
+}
+```
+
+## Signature
+
+```typescript
+function* askGetEpochStartTime(): AskResponse<QpqIsoDateTime>;
+```
+
+## Parameters
+
+None.
+
+## Returns
+
+`QpqIsoDateTime` — the fixed string `'1970-01-01T00:00:00.000Z'`. `QpqIsoDateTime` is a template-literal string type exported from quidproquo-core, so it is a plain `string` at runtime with extra compile-time shape checking (see [askDateNow](./ask-date-now.md)).
+
+## Related
+
+- [askDateNow](./ask-date-now.md) — the current time as an ISO-8601 string.
+- [askGetCurrentEpoch](./ask-get-current-epoch.md) / [askGetCurrentEpochMs](./ask-get-current-epoch-ms.md) — the current time as a number of seconds / milliseconds since this epoch.
+- [askSecondsElapsedFrom](./ask-seconds-elapsed-from.md) — seconds between two ISO-8601 timestamps.

package/template/docusaurus/docs/actions/core/date/ask-seconds-elapsed-from.md

@@ -0,0 +1,52 @@
+---
+title: askSecondsElapsedFrom
+description: Compute the number of seconds between two ISO-8601 timestamps.
+---
+
+# askSecondsElapsedFrom
+
+Computes the number of seconds elapsed from a `startTime` to an `endTime`. If `endTime` is omitted, the current time is read from the runtime, so `askSecondsElapsedFrom(someTimestamp)` answers "how many seconds ago was this?".
+
+- Built from [askDateNow](./ask-date-now.md): when `endTime` is not supplied it reads the runtime clock; otherwise it does no I/O and simply subtracts the two timestamps.
+
+```typescript
+import { askSecondsElapsedFrom } from 'quidproquo-core';
+
+export function* askIsTokenExpired(issuedAt: string) {
+  const age = yield* askSecondsElapsedFrom(issuedAt);
+  return age > 3600; // older than one hour
+}
+```
+
+## Signature
+
+```typescript
+function* askSecondsElapsedFrom(
+  startTime: QpqIsoDateTime,
+  endTime?: QpqIsoDateTime,
+): AskResponse<number>;
+```
+
+## Parameters
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| `startTime` | `QpqIsoDateTime` | — | The earlier ISO-8601 timestamp to measure from, e.g. a value produced by [askDateNow](./ask-date-now.md). |
+| `endTime` | `QpqIsoDateTime` | current time | The later ISO-8601 timestamp to measure to. When omitted, the current time is read via [askDateNow](./ask-date-now.md). |
+
+`QpqIsoDateTime` is a template-literal string type exported from quidproquo-core (a plain `string` at runtime; see [askDateNow](./ask-date-now.md)).
+
+## Returns
+
+`number` — the difference `endTime − startTime` in seconds. The result is a floating-point value (sub-second differences are preserved, not floored) and is **negative** if `startTime` is later than `endTime`.
+
+## Notes
+
+- Only the two-argument form is deterministic on its own. When `endTime` is omitted the value depends on the runtime clock — resolved through [askDateNow](./ask-date-now.md) and recorded in the execution log, so the story still replays consistently.
+
+## Related
+
+- [askDateNow](./ask-date-now.md) — produces the ISO-8601 timestamps this compares.
+- [askGetEpochStartTime](./ask-get-epoch-start-time.md) — the Unix epoch as an ISO-8601 string, useful as a lower bound.
+- [askGetCurrentEpoch](./ask-get-current-epoch.md) / [askGetCurrentEpochMs](./ask-get-current-epoch-ms.md) — the current time as a numeric epoch.
+- [Date/time math helpers](./date-time-math.md) — shift an ISO-8601 timestamp by days, months, or years.

package/template/docusaurus/docs/actions/core/date/date-time-math.md

@@ -0,0 +1,112 @@
+---
+title: Date/time math helpers
+description: Pure helpers that shift an ISO-8601 date-time string by days, months, or years.
+---
+
+# Date/time math helpers
+
+A small set of **pure** helper functions for shifting an ISO-8601 date-time string forward (or backward, with a negative amount) by days, months, years, or milliseconds. They are ordinary functions — not stories — so you call them directly, without `yield*`.
+
+Each helper takes an ISO-8601 timestamp string (such as the value returned by [askDateNow](./ask-date-now.md)), parses it with `new Date(...)`, applies the shift, and returns the result as a UTC ISO-8601 string via `Date.prototype.toISOString()`. Because they are deterministic pure functions, they can be used freely inside a story (compute the shift on a timestamp you obtained from [askDateNow](./ask-date-now.md)) or anywhere in plain code.
+
+```typescript
+import { askDateNow, addDaysToTDateIso } from 'quidproquo-core';
+
+export function* askSevenDaysFromNow() {
+  const now = yield* askDateNow();
+  // pure call — no yield*
+  return addDaysToTDateIso(now, 7);
+}
+```
+
+:::note
+Pass a negative amount to move backward in time, e.g. `addDaysToTDateIso(now, -7)` returns the timestamp seven days ago. All helpers accept and return a plain `string`; the returned value is always normalised to UTC (`...Z`) by `toISOString()`.
+:::
+
+## addMillisecondsToTDateIso
+
+Shifts a timestamp by a number of milliseconds.
+
+```typescript
+function addMillisecondsToTDateIso(startDate: string, numMilliseconds: number): string;
+```
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `startDate` | `string` | The ISO-8601 timestamp to shift from. |
+| `numMilliseconds` | `number` | Milliseconds to add (negative to subtract). |
+
+Returns a `string` — the shifted timestamp in UTC ISO-8601 form.
+
+## addDaysToTDateIso
+
+Shifts a timestamp by a number of days.
+
+```typescript
+function addDaysToTDateIso(startDate: string, numDays: number): string;
+```
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `startDate` | `string` | The ISO-8601 timestamp to shift from. |
+| `numDays` | `number` | Days to add (negative to subtract). |
+
+Returns a `string` — the shifted timestamp in UTC ISO-8601 form.
+
+## addMonthsToTDateIso
+
+Shifts a timestamp by a number of calendar months.
+
+```typescript
+function addMonthsToTDateIso(startDate: string, numMonths: number): string;
+```
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `startDate` | `string` | The ISO-8601 timestamp to shift from. |
+| `numMonths` | `number` | Months to add (negative to subtract). |
+
+Returns a `string` — the shifted timestamp in UTC ISO-8601 form. Uses JavaScript's `Date.setMonth`, so day-of-month overflow rolls over: adding one month to `2026-01-31` yields early March, since February has no 31st.
+
+## addYearsToTDateIso
+
+Shifts a timestamp by a number of calendar years.
+
+```typescript
+function addYearsToTDateIso(startDate: string, numYears: number): string;
+```
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `startDate` | `string` | The ISO-8601 timestamp to shift from. |
+| `numYears` | `number` | Years to add (negative to subtract). |
+
+Returns a `string` — the shifted timestamp in UTC ISO-8601 form.
+
+## addDayMonthYearToTDateIso
+
+Shifts a timestamp by a combination of days, months, and years in a single call.
+
+```typescript
+function addDayMonthYearToTDateIso(
+  startDate: string,
+  numDays: number,
+  numMonths: number,
+  numYears: number,
+): string;
+```
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `startDate` | `string` | The ISO-8601 timestamp to shift from. |
+| `numDays` | `number` | Days to add (negative to subtract). |
+| `numMonths` | `number` | Months to add (negative to subtract). |
+| `numYears` | `number` | Years to add (negative to subtract). |
+
+Returns a `string` — the shifted timestamp in UTC ISO-8601 form. The shifts are applied in order: days, then months, then years. As with `addMonthsToTDateIso`, month/year shifts follow JavaScript's `Date` rollover rules.
+
+## Related
+
+- [askDateNow](./ask-date-now.md) — produces the ISO-8601 timestamps these helpers operate on.
+- [askSecondsElapsedFrom](./ask-seconds-elapsed-from.md) — measure the gap between two timestamps.
+- [askGetCurrentEpoch](./ask-get-current-epoch.md) / [askGetCurrentEpochMs](./ask-get-current-epoch-ms.md) — the current time as a numeric epoch.

package/template/docusaurus/docs/actions/core/error/_category_.json

@@ -0,0 +1,7 @@
+{
+  "label": "Error",
+  "link": {
+    "type": "generated-index",
+    "description": "Throw structured, catchable errors from a story."
+  }
+}

package/template/docusaurus/docs/actions/core/error/ask-throw-error.md

@@ -0,0 +1,115 @@
+---
+title: askThrowError
+description: Throw a structured, catchable QPQError from a story.
+---
+
+# askThrowError
+
+Throws a structured error out of a story. Execution of the current story stops at the `yield*`, and the error propagates up until something catches it — either an enclosing [askCatch](../system/ask-catch.md) or the runtime itself (which turns it into the story's failed result).
+
+- **Action type:** `ErrorActionType.ThrowError`
+
+```typescript
+import { askThrowError, ErrorTypeEnum } from 'quidproquo-core';
+
+export function* askGetUser(userId: string) {
+  const user = yield* askKvsGet('users', userId);
+
+  if (!user) {
+    yield* askThrowError(ErrorTypeEnum.NotFound, `No user with id ${userId}`);
+  }
+
+  return user;
+}
+```
+
+## Signature
+
+```typescript
+function* askThrowError<T>(
+  errorType: ErrorTypeEnum | string,
+  errorText: string,
+  errorStack?: string,
+): AskResponse<T>;
+```
+
+The generic `T` is the type the call is typed to "return". Because the action always throws, the story never actually resumes past it — `T` exists only so `askThrowError` can stand in for a value in a type-checked expression (e.g. `return user ?? (yield* askThrowError(...))`).
+
+## Parameters
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| `errorType` | `ErrorTypeEnum \| string` | – | A category for the error. Prefer a member of [`ErrorTypeEnum`](#errortypeenum); a custom string is also allowed (e.g. a domain-specific error code). |
+| `errorText` | `string` | – | A human-readable message. This text may be surfaced to the user, so keep it meaningful. |
+| `errorStack` | `string` | – | Optional stack trace string. Usually omitted — leave it unset and the runtime supplies context. |
+
+The three arguments together form a `QPQError`:
+
+```typescript
+export interface QPQError {
+  errorType: ErrorTypeEnum | string;
+  errorText: string;
+  errorStack?: string;
+}
+```
+
+### `ErrorTypeEnum`
+
+The standard error categories. Their names deliberately echo HTTP-style semantics; the webserver maps them to status codes when an error reaches an API boundary.
+
+| Member | Meaning |
+| --- | --- |
+| `Unauthorized` | The caller failed to provide valid credentials (typically not authenticated). |
+| `PaymentRequired` | Payment is required to access this resource or perform this action. |
+| `Forbidden` | The caller is authenticated but lacks sufficient privileges. |
+| `NotFound` | The requested resource does not exist. |
+| `TimeOut` | Timed out waiting for a downstream resource. |
+| `UnsupportedMediaType` | The request used an unsupported media type or format. |
+| `OutOfResources` | The system or a downstream resource is out of capacity. |
+| `GenericError` | A generic failure that fits no more specific category (think "500 Internal Server Error"). |
+| `NotImplemented` | The resource or action has not been implemented yet. |
+| `NoContent` | The action succeeded but there is no content to return. |
+| `BadRequest` | The request included invalid data or parameters. |
+| `Invalid` | The request payload was invalid or in an unsupported format. |
+| `Conflict` | The request conflicts with existing state (e.g. creating something that already exists). |
+
+## Returns
+
+Never returns normally — the action always throws. In types it resolves to `T` so it can be used in value position, but no value ever comes back.
+
+## Interaction with `askCatch`
+
+A thrown error does not have to crash the story. When the throwing story is wrapped in [askCatch](../system/ask-catch.md), the error is captured and returned as an `EitherActionResult` value instead of propagating:
+
+```typescript
+import { askCatch, askThrowError, ErrorTypeEnum } from 'quidproquo-core';
+
+export function* askTryGetUser(userId: string) {
+  const outcome = yield* askCatch(askGetUser(userId));
+
+  if (outcome.success) {
+    return outcome.result;
+  }
+
+  // outcome.error is the QPQError thrown above
+  if (outcome.error.errorType === ErrorTypeEnum.NotFound) {
+    return null;
+  }
+
+  // rethrow anything we don't want to handle
+  return yield* askThrowError(outcome.error.errorType, outcome.error.errorText, outcome.error.errorStack);
+}
+```
+
+The failure branch is `{ success: false, error }`, where `error` is exactly the `{ errorType, errorText, errorStack? }` you threw.
+
+## Notes
+
+- If nothing catches the error, the runtime records it as the story's `error` result. At an API boundary the webserver translates the `errorType` into an HTTP response.
+- This is the idiomatic way to fail a story — throwing a plain JavaScript `Error` is caught by the runtime too, but it is always reported as `GenericError` with no chance to set a meaningful `errorType`.
+
+## Related
+
+- [askCatch](../system/ask-catch.md) — catch errors thrown here and handle them as values.
+- [askRetry](../system/ask-retry.md) — retry a story whose actions throw, optionally filtered by `errorType`.
+- [askValidateModelOrThrowError](../../features/validation/ask-validate-model-or-throw-error.md) — validates a model and throws `ErrorTypeEnum.Invalid` through this action.

package/template/docusaurus/docs/actions/core/event/_category_.json

@@ -0,0 +1,7 @@
+{
+  "label": "Event",
+  "link": {
+    "type": "generated-index",
+    "description": "The event-processing pipeline that turns a raw platform trigger (queue message, event-bus message, HTTP request, schedule) into matched story executions and a response."
+  }
+}