create-qpq-app 0.1.5

package/template/docusaurus/docs/actions/core/system/ask-run-parallel.md

@@ -0,0 +1,62 @@
+---
+title: askRunParallel
+description: Run several stories concurrently and get a typed tuple of their results.
+---
+
+# askRunParallel
+
+Runs a tuple of stories in parallel and returns their results as a matching tuple. On each step it collects every still-running story's next action and processes them together, so independent stories advance concurrently instead of one after another. This is the ergonomic, type-safe way to fan out work.
+
+- **Built from:** [askBatch](./ask-batch.md) — it drives each story's generator and batches their outstanding actions on every step, feeding each result back into the right story.
+
+```typescript
+import { askRunParallel } from 'quidproquo-core';
+
+export function* askLoadDashboard(userId: string) {
+  const [profile, orders, settings] = yield* askRunParallel([
+    askGetProfile(userId),
+    askListOrders(userId),
+    askGetSettings(userId),
+  ]);
+
+  return { profile, orders, settings };
+}
+```
+
+## Signature
+
+```typescript
+function* askRunParallel<T extends Array<AskResponse<any>>>(
+  storyRuntimes: [...T],
+): AskResponse<{ [K in keyof T]: AskResponseReturnType<T[K]> }>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `storyRuntimes` | `[...T]` | A tuple of already-invoked stories (generators), e.g. `[askGetProfile(userId), askListOrders(userId)]`. Pass the stories **called** — not `[fn, ...args]` tuples. |
+
+## Returns
+
+A tuple of each story's return value, positionally matching the input: `{ [K in keyof T]: AskResponseReturnType<T[K]> }`. Because the mapping is over the input tuple, each result keeps its own precise type.
+
+## `askRunParallel` vs. the `askBatch` action
+
+They operate at different levels:
+
+- [askBatch](./ask-batch.md) batches raw **actions** — the individual values a story yields.
+- `askRunParallel` runs whole **stories**. It steps each generator and uses `askBatch` under the hood to process their actions together, so multi-action stories interleave correctly.
+
+Reach for `askRunParallel` when you have several stories to run at once; reach for `askBatch` when you specifically have a list of independent actions.
+
+## Notes
+
+- Stories advance in lockstep by step count: each round processes one outstanding action per still-running story, repeating until all stories are done.
+- A story with no actions simply returns immediately; it doesn't hold up the others.
+
+## Related
+
+- [askBatch](./ask-batch.md) — the action-level batching primitive this is built on.
+- [askParallelDEPRECATED](./ask-parallel-deprecated.md) — the older, untyped predecessor (deprecated).
+- [askCatch](./ask-catch.md) — wrap a parallel story to capture its errors as a value.

package/template/docusaurus/docs/actions/core/user-directory/_category_.json

@@ -0,0 +1 @@
+{ "label": "User Directory", "link": { "type": "generated-index", "description": "Authentication and user management: create users, authenticate, handle auth challenges & MFA, manage passwords, tokens, attributes, and email verification against a directory defined with defineUserDirectory." } }

package/template/docusaurus/docs/actions/core/user-directory/ask-user-directory-associate-software-token.md

@@ -0,0 +1,73 @@
+---
+title: askUserDirectoryAssociateSoftwareToken
+description: Begin TOTP MFA enrolment — get the authenticator secret and a refreshed session.
+---
+
+# askUserDirectoryAssociateSoftwareToken
+
+Starts first-time TOTP (authenticator-app) MFA enrolment for a user against a [user directory](../../../config/core/user-directory.md). It returns the shared secret to display to the user (as text or a QR code) and a refreshed session to carry into the challenge response.
+
+- **Action type:** `UserDirectoryActionType.AssociateSoftwareToken`
+- **On AWS:** issues Cognito `AssociateSoftwareToken`.
+
+```typescript
+import {
+  askUserDirectoryAssociateSoftwareToken,
+  askUserDirectoryRespondToAuthChallenge,
+  AuthenticateUserChallenge,
+} from 'quidproquo-core';
+
+export function* askEnrolMfa(username: string, session: string, mfaCode: string) {
+  // 1. Get the secret + a fresh session (show secretCode to the user as a QR code)
+  const { secretCode, session: mfaSession } =
+    yield* askUserDirectoryAssociateSoftwareToken('app-users', session);
+
+  // 2. The user scans secretCode and enters the first code; complete MFA_SETUP
+  return yield* askUserDirectoryRespondToAuthChallenge('app-users', {
+    challenge: AuthenticateUserChallenge.MFA_SETUP,
+    username,
+    session: mfaSession,
+    mfaCode,
+  });
+}
+```
+
+## When to use it
+
+When [askUserDirectoryAuthenticateUser](./ask-user-directory-authenticate-user.md) returns the `MFA_SETUP` challenge — the pool requires MFA but the user has not enrolled an authenticator yet. Call this action with the challenge's `session`, present `secretCode` to the user, then complete the `MFA_SETUP` variant of [askUserDirectoryRespondToAuthChallenge](./ask-user-directory-respond-to-auth-challenge.md#mfa_setup) with the first code from their authenticator.
+
+## Signature
+
+```typescript
+function* askUserDirectoryAssociateSoftwareToken(
+  userDirectoryName: string,
+  session: string,
+): AskResponse<AssociateSoftwareTokenResult>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `userDirectoryName` | `string` | Name of the directory — must match a directory declared with [defineUserDirectory](../../../config/core/user-directory.md). |
+| `session` | `string` | The session from the `MFA_SETUP` challenge returned by authentication. |
+
+## Returns
+
+`AssociateSoftwareTokenResult`:
+
+```typescript
+interface AssociateSoftwareTokenResult {
+  secretCode: string;
+  session: string;
+}
+```
+
+- `secretCode` — the Base32 secret used to seed the authenticator app (and to build the `otpauth://` URI / QR code shown to the user).
+- `session` — a refreshed session to carry into the [MFA_SETUP challenge response](./ask-user-directory-respond-to-auth-challenge.md#mfa_setup).
+
+## Related
+
+- [askUserDirectoryRespondToAuthChallenge](./ask-user-directory-respond-to-auth-challenge.md) — complete the `MFA_SETUP` challenge with the secret you associate here.
+- [askUserDirectoryAuthenticateUser](./ask-user-directory-authenticate-user.md) — raises the `MFA_SETUP` challenge.
+- [defineUserDirectory](../../../config/core/user-directory.md) — the `mfa` option that enables TOTP enrolment.

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

@@ -0,0 +1,124 @@
+---
+title: askUserDirectoryAuthenticateUser
+description: Sign a user in against a user directory, returning tokens or an auth challenge to complete.
+---
+
+# askUserDirectoryAuthenticateUser
+
+Signs a user in against a [user directory](../../../config/core/user-directory.md). On success it returns either the issued tokens or an **auth challenge** the caller must complete (new password, MFA, or a custom challenge) before tokens are issued.
+
+- **Action type:** `UserDirectoryActionType.AuthenticateUser`
+- **On AWS:** issues Cognito `AdminInitiateAuth` — `ADMIN_USER_PASSWORD_AUTH` for a normal sign-in, or `CUSTOM_AUTH` when `isCustom` is `true` (requires a [customAuthRuntime](../../../config/core/user-directory.md#custom-auth-runtime)).
+
+```typescript
+import { askUserDirectoryAuthenticateUser, AuthenticateUserChallenge } from 'quidproquo-core';
+
+export function* askSignIn(email: string, password: string) {
+  const result = yield* askUserDirectoryAuthenticateUser('app-users', false, email, password);
+
+  if (result.challenge === AuthenticateUserChallenge.NONE) {
+    return result.authenticationInfo; // signed in — tokens are ready
+  }
+
+  // A challenge must be answered first — see askUserDirectoryRespondToAuthChallenge
+  return result;
+}
+```
+
+## The auth flow
+
+Authentication is a two-step handshake:
+
+1. **Authenticate** with `askUserDirectoryAuthenticateUser`. The response's `challenge` field says what happens next.
+2. If `challenge` is `NONE`, `authenticationInfo` holds the tokens and you are done. Otherwise the response carries a `session` (and `challengeParameters`) that you pass into [askUserDirectoryRespondToAuthChallenge](./ask-user-directory-respond-to-auth-challenge.md) to complete the challenge and obtain tokens.
+
+### `AuthenticateUserChallenge`
+
+The `challenge` field is one of:
+
+| Value | Meaning | Next step |
+| --- | --- | --- |
+| `NONE` | No challenge — sign-in is complete and `authenticationInfo` is populated. | Done. |
+| `NEW_PASSWORD_REQUIRED` | The user must set a new password (e.g. an admin-created account with a temporary password). | Respond with the `NEW_PASSWORD_REQUIRED` challenge. |
+| `SOFTWARE_TOKEN_MFA` | The user is enrolled in TOTP MFA and must supply a current authenticator code. | Respond with the `SOFTWARE_TOKEN_MFA` challenge. |
+| `MFA_SETUP` | The pool requires MFA but the user has no authenticator enrolled yet. | [Associate a software token](./ask-user-directory-associate-software-token.md), then respond with the `MFA_SETUP` challenge. |
+| `CUSTOM_CHALLENGE` | A custom auth flow is presenting a challenge. | Respond with the `CUSTOM_CHALLENGE` challenge. |
+| `RESET_PASSWORD` | The user must reset their password out of band. | Use [forgot password](./ask-user-directory-forgot-password.md). |
+
+The concrete challenge payloads you build in response are documented on [askUserDirectoryRespondToAuthChallenge](./ask-user-directory-respond-to-auth-challenge.md).
+
+## Signature
+
+```typescript
+function* askUserDirectoryAuthenticateUser(
+  userDirectoryName: string,
+  isCustom: boolean,
+  email: string,
+  password?: string,
+): AskResponse<AuthenticateUserResponse>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `userDirectoryName` | `string` | Name of the directory to authenticate against — must match a directory declared with [defineUserDirectory](../../../config/core/user-directory.md) (or one shared via its `owner` option). |
+| `isCustom` | `boolean` | `false` for a standard email + password sign-in; `true` to start Cognito's custom auth flow (requires a [customAuthRuntime](../../../config/core/user-directory.md#custom-auth-runtime)). When `true`, `password` is not used. |
+| `email` | `string` | The user's email / username. |
+| `password` | `string` | The user's password. Required for a standard (`isCustom: false`) sign-in; omitted for custom auth. |
+
+## Returns
+
+`AuthenticateUserResponse`:
+
+```typescript
+interface AuthenticateUserResponse {
+  challenge: AuthenticateUserChallenge;
+  challengeParameters?: Record<string, string>;
+  session?: string;
+  authenticationInfo?: AuthenticationInfo;
+}
+
+interface AuthenticationInfo {
+  accessToken?: string;
+  expirationDurationInSeconds?: number;
+  expiresAt?: QpqIsoDateTime;
+  idToken?: string;
+  refreshToken?: string;
+  tokenType?: string;
+}
+```
+
+- `challenge` — which [challenge](#authenticateuserchallenge), if any, must be answered next.
+- `challengeParameters` — extra parameters from the provider describing the pending challenge.
+- `session` — an opaque session token to carry into [askUserDirectoryRespondToAuthChallenge](./ask-user-directory-respond-to-auth-challenge.md) (present when a challenge is pending).
+- `authenticationInfo` — the issued tokens (access, id, refresh) plus expiry, present when `challenge` is `NONE`.
+
+## Errors
+
+| Error | Meaning |
+| --- | --- |
+| `UserDirectoryAuthenticateUserErrorTypeEnum.UserNotFound` | No user matches the supplied email. |
+| `UserDirectoryAuthenticateUserErrorTypeEnum.InvalidPassword` | The supplied password is incorrect. |
+
+Errors thrown by actions can be caught with `askCatch` from quidproquo-core. It returns an `EitherActionResult` — `{ success: true, result }` on success, or `{ success: false, error }` on failure:
+
+```typescript
+const outcome = yield* askCatch(askUserDirectoryAuthenticateUser('app-users', false, email, password));
+
+if (outcome.success) {
+  const result = outcome.result;
+  // ...
+} else {
+  // outcome.error.errorType / outcome.error.errorText
+}
+```
+
+## Related
+
+- [defineUserDirectory](../../../config/core/user-directory.md) — declares the directory this action authenticates against.
+- [askUserDirectoryRespondToAuthChallenge](./ask-user-directory-respond-to-auth-challenge.md) — answer the challenge this action can return.
+- [askUserDirectoryRefreshToken](./ask-user-directory-refresh-token.md) — exchange a refresh token for fresh access tokens later.
+- [askUserDirectoryAssociateSoftwareToken](./ask-user-directory-associate-software-token.md) — enrol an authenticator when the `MFA_SETUP` challenge is returned.
+- [askUserDirectoryCreateUser](./ask-user-directory-create-user.md) — create the accounts you authenticate here.
+- [askUserDirectorySetAccessToken](./ask-user-directory-set-access-token.md) — load the returned access token into the current story session.

package/template/docusaurus/docs/actions/core/user-directory/ask-user-directory-change-password.md

@@ -0,0 +1,55 @@
+---
+title: askUserDirectoryChangePassword
+description: Let a signed-in user change their own password using their current password.
+---
+
+# askUserDirectoryChangePassword
+
+Changes a signed-in user's password. The caller proves ownership with the user's current password and a valid access token — this is the self-service "change my password" path (not an admin reset).
+
+- **Action type:** `UserDirectoryActionType.ChangePassword`
+- **On AWS:** issues Cognito `ChangePassword` using the supplied access token.
+
+```typescript
+import { askUserDirectoryChangePassword } from 'quidproquo-core';
+
+export function* askUpdateMyPassword(oldPassword: string, newPassword: string, accessToken: string) {
+  yield* askUserDirectoryChangePassword(oldPassword, newPassword, accessToken);
+}
+```
+
+## Signature
+
+```typescript
+function* askUserDirectoryChangePassword(
+  oldPassword: string,
+  newPassword: string,
+  accessToken: string,
+): AskResponse<void>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `oldPassword` | `string` | The user's current password. |
+| `newPassword` | `string` | The new password; must satisfy the pool's password policy. |
+| `accessToken` | `string` | The signed-in user's access token, identifying whose password to change. |
+
+## Returns
+
+`void` — the story resumes once the password has been changed.
+
+## Errors
+
+| Error | Meaning |
+| --- | --- |
+| `UserDirectoryChangePasswordErrorTypeEnum.IncorrectPassword` | The supplied current password was wrong (or the access token was invalid). |
+| `UserDirectoryChangePasswordErrorTypeEnum.InvalidNewPassword` | The proposed new password does not meet the pool's password policy. |
+| `UserDirectoryChangePasswordErrorTypeEnum.LimitExceeded` | Too many password-change attempts; back off and retry later. |
+
+## Related
+
+- [askUserDirectoryForgotPassword](./ask-user-directory-forgot-password.md) / [askUserDirectoryConfirmForgotPassword](./ask-user-directory-confirm-forgot-password.md) — reset a password the user has forgotten.
+- [askUserDirectorySetPassword](./ask-user-directory-set-password.md) — administratively set a user's password.
+- [defineUserDirectory](../../../config/core/user-directory.md) — declares the directory and its password policy.

package/template/docusaurus/docs/actions/core/user-directory/ask-user-directory-confirm-email-verification.md

@@ -0,0 +1,52 @@
+---
+title: askUserDirectoryConfirmEmailVerification
+description: Confirm a user's email address with the verification code they received.
+---
+
+# askUserDirectoryConfirmEmailVerification
+
+Confirms a signed-in user's email address using the code sent by [askUserDirectoryRequestEmailVerification](./ask-user-directory-request-email-verification.md), marking the email as verified.
+
+- **Action type:** `UserDirectoryActionType.ConfirmEmailVerification`
+- **On AWS:** issues Cognito `VerifyUserAttribute` for the `email` attribute using the supplied access token.
+
+```typescript
+import { askUserDirectoryConfirmEmailVerification } from 'quidproquo-core';
+
+export function* askFinishEmailVerification(code: string, accessToken: string) {
+  yield* askUserDirectoryConfirmEmailVerification(code, accessToken);
+}
+```
+
+## Signature
+
+```typescript
+function* askUserDirectoryConfirmEmailVerification(
+  code: string,
+  accessToken: string,
+): AskResponse<void>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `code` | `string` | The verification code delivered by [askUserDirectoryRequestEmailVerification](./ask-user-directory-request-email-verification.md). |
+| `accessToken` | `string` | The signed-in user's access token, identifying whose email to verify. |
+
+## Returns
+
+`void` — the story resumes once the email has been verified.
+
+## Errors
+
+| Error | Meaning |
+| --- | --- |
+| `UserDirectoryConfirmEmailVerificationErrorTypeEnum.InvalidCode` | The supplied verification code does not match. |
+| `UserDirectoryConfirmEmailVerificationErrorTypeEnum.ExpiredCode` | The verification code has expired; request a new one. |
+| `UserDirectoryConfirmEmailVerificationErrorTypeEnum.LimitExceeded` | Too many verification attempts; back off and retry later. |
+
+## Related
+
+- [askUserDirectoryRequestEmailVerification](./ask-user-directory-request-email-verification.md) — sends the code this action confirms.
+- [defineUserDirectory](../../../config/core/user-directory.md) — declares the directory.

package/template/docusaurus/docs/actions/core/user-directory/ask-user-directory-confirm-forgot-password.md

@@ -0,0 +1,58 @@
+---
+title: askUserDirectoryConfirmForgotPassword
+description: Complete a password reset with the confirmation code and a new password.
+---
+
+# askUserDirectoryConfirmForgotPassword
+
+Completes the password-reset flow started by [askUserDirectoryForgotPassword](./ask-user-directory-forgot-password.md): the user supplies the confirmation code they received and their chosen new password.
+
+- **Action type:** `UserDirectoryActionType.ConfirmForgotPassword`
+- **On AWS:** issues Cognito `ConfirmForgotPassword`.
+
+```typescript
+import { askUserDirectoryConfirmForgotPassword } from 'quidproquo-core';
+
+export function* askFinishPasswordReset(code: string, username: string, newPassword: string) {
+  yield* askUserDirectoryConfirmForgotPassword('app-users', code, username, newPassword);
+}
+```
+
+## Signature
+
+```typescript
+function* askUserDirectoryConfirmForgotPassword(
+  userDirectoryName: string,
+  code: string,
+  username: string,
+  password: string,
+): AskResponse<AuthenticateUserResponse>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `userDirectoryName` | `string` | Name of the directory — must match a directory declared with [defineUserDirectory](../../../config/core/user-directory.md). |
+| `code` | `string` | The confirmation code delivered by [askUserDirectoryForgotPassword](./ask-user-directory-forgot-password.md). |
+| `username` | `string` | The user (email) resetting their password. |
+| `password` | `string` | The new password; must satisfy the pool's password policy. |
+
+## Returns
+
+`AuthenticateUserResponse` — the same shape returned by [askUserDirectoryAuthenticateUser](./ask-user-directory-authenticate-user.md#returns).
+
+## Errors
+
+| Error | Meaning |
+| --- | --- |
+| `UserDirectoryConfirmForgotPasswordErrorTypeEnum.InvalidCode` | The supplied confirmation code does not match. |
+| `UserDirectoryConfirmForgotPasswordErrorTypeEnum.ExpiredCode` | The confirmation code has expired; request a new one. |
+| `UserDirectoryConfirmForgotPasswordErrorTypeEnum.InvalidNewPassword` | The proposed new password does not meet the pool's password policy. |
+| `UserDirectoryConfirmForgotPasswordErrorTypeEnum.LimitExceeded` | Too many attempts; back off and retry later. |
+
+## Related
+
+- [askUserDirectoryForgotPassword](./ask-user-directory-forgot-password.md) — starts the reset and sends the code.
+- [askUserDirectoryChangePassword](./ask-user-directory-change-password.md) — change a password when the current one is known.
+- [defineUserDirectory](../../../config/core/user-directory.md) — declares the directory and its password policy.

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

@@ -0,0 +1,72 @@
+---
+title: askUserDirectoryCreateUser
+description: Administratively create a user account in a user directory.
+---
+
+# askUserDirectoryCreateUser
+
+Creates a user account in a [user directory](../../../config/core/user-directory.md) with an email, a password, and any additional profile attributes. This is the administrative create path — use it when `selfSignUpEnabled` is off, or whenever your service provisions accounts itself.
+
+- **Action type:** `UserDirectoryActionType.CreateUser`
+- **On AWS:** issues Cognito `AdminCreateUser` against the pool.
+
+```typescript
+import { askUserDirectoryCreateUser } from 'quidproquo-core';
+
+export function* askInviteUser(email: string, temporaryPassword: string) {
+  yield* askUserDirectoryCreateUser('app-users', {
+    email,
+    emailVerified: true,
+    password: temporaryPassword,
+    givenName: 'New',
+    familyName: 'User',
+  });
+}
+```
+
+## Signature
+
+```typescript
+function* askUserDirectoryCreateUser(
+  userDirectoryName: string,
+  createUserRequest: CreateUserRequest,
+): AskResponse<AuthenticateUserResponse>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `userDirectoryName` | `string` | Name of the directory to create the user in — must match a directory declared with [defineUserDirectory](../../../config/core/user-directory.md). |
+| `createUserRequest` | `CreateUserRequest` | The new user's details — see below. |
+
+### `CreateUserRequest`
+
+Extends `UserAttributes` (minus `userId`) with the required fields for creation:
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `email` | `string` | The user's email address (also the username). Required. |
+| `emailVerified` | `boolean` | Whether to mark the email as already verified. Required. |
+| `password` | `string` | The initial password; must satisfy the pool's password policy. Required. |
+| *(other attributes)* | `UserAttributes` | Any other standard profile attributes (`givenName`, `familyName`, `phoneNumber`, `locale`, …) may be supplied. See [UserAttributes](./ask-user-directory-get-user-attributes.md#userattributes). |
+
+## Returns
+
+`AuthenticateUserResponse` — the same shape returned by [askUserDirectoryAuthenticateUser](./ask-user-directory-authenticate-user.md#returns).
+
+## Errors
+
+| Error | Meaning |
+| --- | --- |
+| `UserDirectoryCreateUserErrorTypeEnum.Conflict` | An account with this email already exists. |
+| `UserDirectoryCreateUserErrorTypeEnum.InvalidPassword` | The supplied password does not meet the pool's password policy. |
+| `UserDirectoryCreateUserErrorTypeEnum.LimitExceeded` | Too many create-user attempts; back off and retry later. |
+
+## Related
+
+- [defineUserDirectory](../../../config/core/user-directory.md) — declares the directory this action creates users in.
+- [askUserDirectoryAuthenticateUser](./ask-user-directory-authenticate-user.md) — sign the new user in.
+- [askUserDirectorySetUserAttributes](./ask-user-directory-set-user-attributes.md) — update profile attributes after creation.
+- [askUserDirectorySetPassword](./ask-user-directory-set-password.md) — administratively (re)set a user's password.
+- [askUserDirectoryGetUsers](./ask-user-directory-get-users.md) — list the accounts in the directory.

package/template/docusaurus/docs/actions/core/user-directory/ask-user-directory-decode-access-token.md

@@ -0,0 +1,73 @@
+---
+title: askUserDirectoryDecodeAccessToken
+description: Verify and decode an access token into its claims.
+---
+
+# askUserDirectoryDecodeAccessToken
+
+Verifies and decodes an access token issued by a [user directory](../../../config/core/user-directory.md), returning the identity claims it carries. Use it to validate a token you have been handed (e.g. a bearer token on an incoming request) and read who it belongs to.
+
+- **Action type:** `UserDirectoryActionType.DecodeAccessToken`
+- **On AWS:** verifies the JWT signature against the pool's public JWKs over HTTPS — no Cognito API call and no IAM required, so it works against foreign directories too.
+
+```typescript
+import { askUserDirectoryDecodeAccessToken } from 'quidproquo-core';
+
+export function* askWhoIs(accessToken: string) {
+  const decoded = yield* askUserDirectoryDecodeAccessToken('app-users', false, accessToken);
+  return decoded.userId;
+}
+```
+
+## Signature
+
+```typescript
+function* askUserDirectoryDecodeAccessToken(
+  userDirectoryName: string,
+  ignoreExpiration: boolean,
+  accessToken: string,
+): AskResponse<DecodedAccessToken>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `userDirectoryName` | `string` | Name of the directory that issued the token — must match a directory declared with [defineUserDirectory](../../../config/core/user-directory.md). |
+| `ignoreExpiration` | `boolean` | When `true`, an expired token is still decoded rather than rejected. |
+| `accessToken` | `string` | The access token to verify and decode. |
+
+## Returns
+
+`DecodedAccessToken`:
+
+```typescript
+interface DecodedAccessToken {
+  userId: string;
+  username: string;
+  exp: number;
+  roles?: string[];
+  userDirectory: string;
+  wasValid: boolean;
+}
+```
+
+- `userId` — the user's unique identifier (the Cognito `sub`).
+- `username` — the user's username.
+- `exp` — expiry as a Unix timestamp (seconds since 1970-01-01 UTC).
+- `roles` — the user's roles, if any.
+- `userDirectory` — the directory the token belongs to.
+- `wasValid` — whether the token's signature/expiry validated.
+
+## Errors
+
+| Error | Meaning |
+| --- | --- |
+| `UserDirectoryDecodeAccessTokenErrorTypeEnum.Unauthorized` | The access token is missing, malformed, expired, or its signature could not be verified. |
+
+## Related
+
+- [askUserDirectoryReadAccessToken](./ask-user-directory-read-access-token.md) — decode the token already on the current story session.
+- [askUserDirectorySetAccessToken](./ask-user-directory-set-access-token.md) — load and decode a token into the session.
+- [defineUserDirectory](../../../config/core/user-directory.md) — declares the directory.
+- [askRouteAuthValidationDecode](../../webserver/route-auth-validation/ask-route-auth-validation-decode.md) — the webserver route-auth wrapper that decodes an incoming request's token.

package/template/docusaurus/docs/actions/core/user-directory/ask-user-directory-forgot-password.md

@@ -0,0 +1,66 @@
+---
+title: askUserDirectoryForgotPassword
+description: Start a password reset by sending the user a confirmation code.
+---
+
+# askUserDirectoryForgotPassword
+
+Starts the self-service password-reset flow for a user in a [user directory](../../../config/core/user-directory.md). It sends the user a confirmation code (by email) and returns where the code was delivered. Complete the reset with [askUserDirectoryConfirmForgotPassword](./ask-user-directory-confirm-forgot-password.md).
+
+- **Action type:** `UserDirectoryActionType.ForgotPassword`
+- **On AWS:** issues Cognito `ForgotPassword`. The message can be customised via the [emailTemplates.resetPassword](../../../config/core/user-directory.md#email-templates) handler.
+
+```typescript
+import { askUserDirectoryForgotPassword } from 'quidproquo-core';
+
+export function* askStartPasswordReset(username: string) {
+  const delivery = yield* askUserDirectoryForgotPassword('app-users', username);
+  return delivery; // e.g. { deliveryMedium: 'EMAIL', destination: 'a***@example.com', ... }
+}
+```
+
+## Signature
+
+```typescript
+function* askUserDirectoryForgotPassword(
+  userDirectoryName: string,
+  username: string,
+): AskResponse<AuthenticationDeliveryDetails>;
+```
+
+## 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) requesting the reset. |
+
+## Returns
+
+`AuthenticationDeliveryDetails` — where the confirmation code was sent:
+
+```typescript
+interface AuthenticationDeliveryDetails {
+  attributeName: string;
+  deliveryMedium: 'EMAIL' | 'SMS';
+  destination: string;
+}
+```
+
+- `attributeName` — the attribute the code was sent to (e.g. `email`).
+- `deliveryMedium` — `EMAIL` or `SMS`.
+- `destination` — the masked destination the code was delivered to.
+
+## Errors
+
+| Error | Meaning |
+| --- | --- |
+| `UserDirectoryForgotPasswordErrorTypeEnum.UserNotFound` | No user matches the supplied username. |
+| `UserDirectoryForgotPasswordErrorTypeEnum.LimitExceeded` | Too many forgot-password attempts; back off and retry later. |
+
+## Related
+
+- [askUserDirectoryConfirmForgotPassword](./ask-user-directory-confirm-forgot-password.md) — finish the reset with the code and a new password.
+- [askUserDirectoryChangePassword](./ask-user-directory-change-password.md) — change a password when the user knows their current one.
+- [askUserDirectorySetPassword](./ask-user-directory-set-password.md) — administratively set a password without a code.
+- [defineUserDirectory](../../../config/core/user-directory.md) — declares the directory and the reset email template.