@antelopejs/interface-dms 0.10.4 → 0.13.0

package/docs/4.notifications/2.categories-and-subjects.md

@@ -1,21 +1,18 @@
 ---
-title: "Categories and Subjects"
+title: "Categories and subjects"
 description: "Every notification is filed under a subject, and every subject belongs to a category."
+mode: reference
 ---
 
-# Categories and Subjects
-
-## Overview
-
-Every notification is filed under a **subject**, and every subject belongs to a **category**. That two-level taxonomy is what the notification settings screen groups by, and what user preferences are keyed on: a preference entry exists per `categoryId:subjectId` pair.
+Every notification is filed under a **subject**, and every subject belongs to a **category**. The notification settings screen groups by these two levels, and the DMS keys user preferences on them. A preference entry exists per `categoryId:subjectId` pair.
 
 You declare categories and subjects by calling `NotificationCategory()` and `NotificationSubject()`. Both calls register the declaration with the DMS and return the info object, which you keep as a module-level constant. You pass the category constant to `NotificationSubject()`, and the subject constant to the builder's `.subject()` when you send.
 
-Declarations are values, not decorators: they run when the module that contains them is imported. Declare them at the top level of a module that is imported during startup, so the taxonomy is complete before the first notification is sent.
+Declarations are function calls, not decorators. They run when the module that contains them is imported. Declare them at the top level of a module that is imported during startup, so the taxonomy is complete before the first notification is sent.
 
-The [notification preferences walkthrough](/docs/auth-and-tenancy/authentication#notification-preferences) shows the System category expanded, its locked General subject, and the Playground category and subject switched off. The Email column is marked Soon: these controls currently manage in-app delivery, not transactional authentication emails.
+The [Notification preferences](/docs/auth-and-tenancy/authentication#notification-preferences) walkthrough shows the System category expanded to its subjects, and describes the locked General subject in prose. Its Email column is marked **Soon**. These switches control in-app delivery, not the transactional authentication emails.
 
-## Declaring a Category
+## Declaring a category
 
 `NotificationCategory(id, category)` registers a category and returns the resulting `NotificationCategoryInfo`.
 
@@ -31,25 +28,25 @@ export const shopCategory = NotificationCategory("shop", {
 
 | Parameter | Description |
 | --------- | ----------- |
-| `id` | Identifier of the category. It becomes the first half of every preference key under this category. |
-| `category` | The rest of the `NotificationCategoryInfo` object — every field except `id`. |
+| `id` | Identifier of the category. It is the first half of every preference key under this category. |
+| `category` | Every field of `NotificationCategoryInfo` except `id`. |
 
-### NotificationCategoryInfo
+### `NotificationCategoryInfo`
 
 | Option | Type | Description |
 | ------ | ---- | ----------- |
 | `id` | `string` | Category identifier. Supplied through the first argument of `NotificationCategory()`. |
 | `labelKey` | `string` | Translation key for the category name. |
 | `descriptionKey` | `string` (optional) | Translation key for a longer description. |
-| `icon` | `string` | Icon name, in the icon syntax used across the dashboard (for example `i-ph-shopping-cart`). |
-| `togglePermission` | [`TogglePermission`](#toggle-permissions) (optional) | Parent toggle stance applied when evaluating this category's subjects. It does not lock the category's own switch. |
-| `tagKey` | `string` (optional) | Translation key of a short module tag (for example `SaaS`) shown next to the category in the settings screen and on each of its notifications in the inbox. Without it, the inbox tags a notification with its subject's label. |
+| `icon` | `string` | Icon name, in the icon syntax the dashboard uses, for example `i-ph-shopping-cart`. |
+| `togglePermission` | [`TogglePermission`](#toggle-permissions) (optional) | The parent stance the DMS reads when it decides whether a subject of this category is locked. It does not lock the category's own switch by itself. |
+| `tagKey` | `string` (optional) | Translation key of a short module tag, for example `SaaS`. The settings screen shows it next to the category, and the inbox shows it on each notification of the category. Without it, the inbox tags a notification with its subject's label. |
 
-Registering a second category with an `id` that is already taken is ignored: the first declaration wins.
+The DMS ignores a second category registered with an `id` that is already taken. The first declaration wins.
 
-## Declaring a Subject
+## Declaring a subject
 
-`NotificationSubject(id, subject)` registers a subject under an already-declared category and returns the resulting `NotificationSubjectInfo`.
+`NotificationSubject(id, subject)` registers a subject under an already registered category and returns the resulting `NotificationSubjectInfo`.
 
 ```typescript
 import {
@@ -78,52 +75,58 @@ export const stockSubject = NotificationSubject("stock", {
 
 | Parameter | Description |
 | --------- | ----------- |
-| `id` | Identifier of the subject. It is unique within its category, not globally: the preference key is `categoryId:subjectId`. |
-| `subject` | The rest of the `NotificationSubjectInfo` object — every field except `id`. |
+| `id` | Identifier of the subject. It is unique within its category, not across categories, because the preference key is `categoryId:subjectId`. |
+| `subject` | Every field of `NotificationSubjectInfo` except `id`. |
 
-### NotificationSubjectInfo
+### `NotificationSubjectInfo`
 
 | Option | Type | Description |
 | ------ | ---- | ----------- |
 | `id` | `string` | Subject identifier, unique within the category. Supplied through the first argument of `NotificationSubject()`. |
-| `category` | `NotificationCategoryInfo` | The category this subject belongs to — the value returned by `NotificationCategory()`. |
+| `category` | `NotificationCategoryInfo` | The category this subject belongs to, as returned by `NotificationCategory()`. |
 | `labelKey` | `string` | Translation key for the subject name. |
 | `descriptionKey` | `string` (optional) | Translation key for a longer description. |
-| `togglePermission` | [`TogglePermission`](#toggle-permissions) (optional) | Whether users may turn this subject off, read together with the category's value. |
-| `badgeKey` | `string` (optional) | Translation key of a badge shown next to the subject label in the settings screen (for example `Developer mode`). |
+| `togglePermission` | [`TogglePermission`](#toggle-permissions) (optional) | Whether users may turn this subject off. The DMS reads it together with the category's value. |
+| `badgeKey` | `string` (optional) | Translation key of a badge that the settings screen shows next to the subject label, for example `Developer mode`. |
 
-A subject carries the whole category object, not just its id, so `subject.category.id` is always reachable from a subject you hold. That is how a send resolves the preference key from nothing but the subject you passed to the builder.
+A subject carries the whole category object, not only its id, so `subject.category.id` is always available from a subject you hold. A send uses it to build the preference key from the subject you passed to the builder.
 
-Registering a second subject with an `id` already taken inside the same category is ignored, the same way categories are.
+The DMS ignores a second subject registered with an `id` already taken inside the same category, as it does for categories.
 
-### Declaration Order
+### Declaration order
 
-The category has to be registered before any of its subjects: a subject whose category is not registered yet is rejected and never enters the registry, so nothing sent against it is delivered. Registrations run in call order, so declaring the category above its subjects in the same file — as in the example above — is enough.
+The DMS must have the category registered before any of its subjects. It refuses a subject whose category is not registered yet with the error `Category "<id>" is not registered. Register the category before its subjects.` The subject never enters the registry, so the DMS drops everything sent under it. Registrations run in call order, so declaring the category above its subjects in the same file is enough, as in the example above.
 
-Registrations are scoped to the module that made them: when that module is unloaded, its categories and subjects are unregistered.
+Registrations belong to the module that made them. When that module is unloaded, the DMS unregisters its categories and subjects.
 
-## Toggle Permissions
+## Toggle permissions
 
-`TogglePermission` controls whether a user is allowed to opt out of a subject from the notification settings screen.
+`TogglePermission` controls whether a user may opt out of a subject.
 
 ```typescript
 type TogglePermission = "allowed" | "forbidden" | "default";
 ```
 
-The field is optional on both `NotificationCategoryInfo` and `NotificationSubjectInfo`, and the settings screen locks a subject's switch only when both of these hold:
+The field is optional on both `NotificationCategoryInfo` and `NotificationSubjectInfo`. A subject is locked only when both of these conditions hold:
 
-- the subject declares `togglePermission: "forbidden"`, and
+- the subject declares `togglePermission: "forbidden"`;
 - its category declares `togglePermission` as `"default"` or `"forbidden"`.
 
-Every other combination leaves the subject toggleable. A category's own switch is never locked: the value you put on a category acts as the parent half of the rule above and nothing else.
+Every other combination leaves the subject toggleable. The value on a category acts only as the parent half of this rule. The settings screen disables a category's own switch only when every subject in it is locked, because the switch then has nothing to change.
 
 | Value | Meaning on a subject | Meaning on a category |
 | ----- | -------------------- | --------------------- |
-| `"forbidden"` | The user may not turn the subject off, provided the category declares `"default"` or `"forbidden"`. | Enables the subject-side lock. The category itself stays toggleable. |
-| `"default"` | The subject stays toggleable. | Enables the subject-side lock, same as `"forbidden"`. |
-| `"allowed"` | The subject stays toggleable, same as `"default"`. | Leaves every subject toggleable, same as omitting the field. |
+| `"forbidden"` | The subject is locked, provided the category declares `"default"` or `"forbidden"`. | Allows the subject-side lock. |
+| `"default"` | The subject stays toggleable. | Allows the subject-side lock, the same as `"forbidden"`. |
+| `"allowed"` | The subject stays toggleable, the same as `"default"`. | Leaves every subject toggleable, the same as omitting the field. |
+
+A locked subject behaves the same way everywhere:
 
-So for a notification a user must always receive, declare `togglePermission: "forbidden"` on the subject **and** `togglePermission: "default"` on the category that holds it. `SystemCategory` declares `"default"`, which is what makes `GeneralSubject` mandatory.
+- The settings screen shows its switch disabled, with a hint.
+- The preferences route refuses a change that turns it off, with HTTP 403.
+- Every dispatch method delivers it whatever preference the user has stored for it.
+
+For a notification a user must always receive, declare `togglePermission: "forbidden"` on the subject **and** `togglePermission: "default"` on its category. `SystemCategory` declares `"default"`, which is what makes `GeneralSubject` mandatory.
 
 ```typescript
 import {
@@ -134,7 +137,7 @@ import {
 export const alertCategory = NotificationCategory("alerts", {
   labelKey: "shop.notifications.categories.alerts",
   icon: "i-ph-warning",
-  togglePermission: "default", // required for the forbidden subject below to lock
+  togglePermission: "default",
 });
 
 export const outageSubject = NotificationSubject("outage", {
@@ -144,9 +147,9 @@ export const outageSubject = NotificationSubject("outage", {
 });
 ```
 
-`togglePermission` only governs what the settings screen offers. It does not change what `.toUser()` and the other dispatch methods do with a preference the user has already stored — see [Delivery Rules](/docs/interfaces/notifications/sending#delivery-rules).
+Without `togglePermission: "default"` on `alertCategory`, `outageSubject` would stay toggleable. See [Delivery rules](/docs/interfaces/notifications/sending#delivery-rules) for how a send reads the user's preference.
 
-## Read Scope
+## Read scope
 
 `ReadScope` describes how the read state of a multi-recipient notification behaves.
 
@@ -157,13 +160,13 @@ type ReadScope = "individual" | "shared";
 | Value | Meaning |
 | ----- | ------- |
 | `"individual"` | Each recipient gets their own copy with its own read state. This is the default. |
-| `"shared"` | The copies are grouped: once one recipient reads the notification, it counts as read for the whole group. |
+| `"shared"` | The DMS groups the copies. Once one recipient reads the notification, it counts as read for the whole group. |
 
-The scope is chosen per send, not per subject; you pass it through `SendOptions` on the multi-recipient dispatch methods. See [Send Options](/docs/interfaces/notifications/sending#send-options).
+You choose the scope per send, not per subject. You pass it through `SendOptions` on the multi-recipient dispatch methods. See [Send options](/docs/interfaces/notifications/sending#send-options).
 
-## Built-in Categories and Subjects
+## Built-in categories and subjects
 
-The DMS declares one category and five subjects of its own. Import them and pass them to `.subject()` when your notification fits one of them, instead of declaring a near-duplicate.
+The DMS declares one category and five subjects of its own. When your notification fits one of them, import it and pass it to `.subject()` instead of declaring a near-duplicate.
 
 ```typescript
 import {
@@ -176,7 +179,7 @@ import {
 } from "@antelopejs/interface-dms/notifications";
 ```
 
-`SystemCategory` is the category all five subjects belong to. Its id is `system`, its icon is `i-ph-gear`, and its `togglePermission` is `"default"` — the parent value that lets `GeneralSubject`'s `"forbidden"` take effect.
+`SystemCategory` is the category of all five subjects. Its id is `system`, its icon is `i-ph-gear`, and its `togglePermission` is `"default"`. That parent value lets the `"forbidden"` on `GeneralSubject` take effect.
 
 | Constant | Id | Toggle permission | Used for |
 | -------- | -- | ----------------- | -------- |
@@ -184,18 +187,18 @@ import {
 | `SecuritySubject` | `security` | `"default"` | Sign-ins, password and email changes, two-factor changes, backup-code regeneration. |
 | `AccountSubject` | `account` | `"default"` | Account lifecycle messages, such as the welcome notification. |
 | `CollaborationSubject` | `collaboration` | `"default"` | Messages about other people in the workspace, such as a collaborator joining. |
-| `AutomationSubject` | `automation` | `"default"` | Messages emitted by automations. |
+| `AutomationSubject` | `automation` | `"default"` | Messages that automations send. |
 
-Their labels and descriptions use the `dms.notifications.*` translation keys shipped with the DMS.
+Their labels and descriptions use the `dms.notifications.*` translation keys that ship with the DMS.
 
-## Importing the Types
+## Importing the types
 
-The declaration functions and the built-in constants are exported from the interface root. The type definitions live in the `types` subpath:
+The interface root exports the declaration functions, the built-in constants and every type of the domain. The `types` subpath exports the types alone.
 
 | Symbol | Import from |
 | ------ | ----------- |
-| `NotificationCategory`, `NotificationSubject`, `SystemCategory`, `GeneralSubject`, `SecuritySubject`, `AccountSubject`, `CollaborationSubject`, `AutomationSubject`, `NotificationTone` | `@antelopejs/interface-dms/notifications` |
-| `NotificationCategoryInfo`, `NotificationSubjectInfo`, `NotificationTone`, `TogglePermission`, `ReadScope` | `@antelopejs/interface-dms/notifications/types` |
+| `NotificationCategory`, `NotificationSubject`, `SystemCategory`, `GeneralSubject`, `SecuritySubject`, `AccountSubject`, `CollaborationSubject`, `AutomationSubject` | `@antelopejs/interface-dms/notifications` |
+| `NotificationCategoryInfo`, `NotificationSubjectInfo`, `NotificationTone`, `TogglePermission`, `ReadScope` | `@antelopejs/interface-dms/notifications` or `@antelopejs/interface-dms/notifications/types` |
 
 ```typescript
 import type { NotificationSubjectInfo } from "@antelopejs/interface-dms/notifications/types";
@@ -207,8 +210,8 @@ interface NotificationTemplate {
 }
 ```
 
-Typing your own helpers against `NotificationSubjectInfo` is the usual reason to reach for the `types` subpath: it lets a template table or a helper function accept any subject, built-in or your own.
+A type such as `NotificationSubjectInfo` lets a template table or a helper function accept any subject, built-in or your own.
 
-## Next Steps
+## Next steps
 
-- [Sending Notifications](/docs/interfaces/notifications/sending) - Build a notification against a subject and dispatch it to users, roles, or everyone
+- [Sending notifications](/docs/interfaces/notifications/sending) covers building a notification under a subject and dispatching it to users, roles, or everyone.

package/docs/4.notifications/3.sending.md

@@ -1,17 +1,14 @@
 ---
-title: "Sending Notifications"
+title: "Sending notifications"
 description: "Build a notification, then send it to users, roles or everyone, with delivery rules and send options."
+mode: reference
 ---
 
-# Sending Notifications
+Sending takes two steps. `Notification()` starts a builder that you fill field by field. `.build()` closes it and returns a `SendableNotification`, which carries the dispatch methods.
 
-## Overview
+The [Read notifications](/docs/auth-and-tenancy/authentication#read-notifications) walkthrough shows the open bell with one unread message. It describes in prose how a message reaches every open session of its recipient without a reload, and no other account. The [Notification preferences](/docs/auth-and-tenancy/authentication#notification-preferences) walkthrough explains that turning a subject off stops new notifications of that subject while the messages already in the inbox stay.
 
-Sending happens in two steps. `Notification()` starts a builder you fill field by field; `.build()` closes it and gives you a `SendableNotification`, which carries the dispatch methods.
-
-For the visible result, see the [single-recipient notification and second-session update](/docs/auth-and-tenancy/authentication#read-notifications). The walkthrough distinguishes delivery from read state and shows [a disabled subject preventing a new delivery](/docs/auth-and-tenancy/authentication#notification-preferences).
-
-```typescript
+```typescript fragment
 import {
   GeneralSubject,
   Notification,
@@ -36,11 +33,11 @@ A `SendableNotification` is immutable and holds no recipient, so you can build o
 | `toRoles` | `(roleIds: string[], options?: RoleSendOptions) => Promise<void>` | Send to every user holding at least one of the roles, in `options.tenantId` when set. |
 | `broadcast` | `(options?: SendOptions) => Promise<void>` | Send to every user. |
 
-## Building a Notification
+## Building a notification
 
 `Notification()` takes no arguments and returns a fresh `NotificationBuilder`. Every setter stores its value and returns the builder, so calls chain in any order.
 
-```typescript
+```typescript fragment
 import { Notification } from "@antelopejs/interface-dms/notifications";
 import { orderSubject } from "./notifications";
 
@@ -56,19 +53,19 @@ const shipped = Notification()
 
 | Method | Type | Description |
 | ------ | ---- | ----------- |
-| `.icon(value)` | `string` | Icon shown next to the notification, in the dashboard icon syntax (for example `i-ph-truck`). Required. |
+| `.icon(value)` | `string` | Icon shown next to the notification, in the dashboard icon syntax, for example `i-ph-truck`. Required. |
 | `.title(value)` | `string` | Title line. Required. |
 | `.description(value)` | `string` | Body line. Required. |
-| `.subject(subject)` | `NotificationSubjectInfo` | The subject the notification is filed under, which decides the category and the user preference it is gated on. Required. |
+| `.subject(subject)` | `NotificationSubjectInfo` | The subject the notification is filed under. It decides the category and the user preference that gates delivery. Required. |
 | `.linkTo(value)` | `string` | Destination the notification links to, such as `/settings/user/profile`. Optional. |
-| `.params(value)` | `Record<string, string \| number>` | Interpolation values carried alongside the notification. Optional. |
-| `.tone(value)` | `NotificationTone` (`"neutral"`, `"primary"`, `"success"`, `"warning"`, `"error"`) | Colour of the icon well the inbox lists the notification with. Optional: without it the well is `primary` while unread and neutral once read. |
+| `.params(value)` | `Record<string, string \| number>` | Interpolation values stored with the notification. Optional. |
+| `.tone(value)` | `NotificationTone` (`"neutral"`, `"primary"`, `"success"`, `"warning"`, `"error"`) | Colour of the icon well that the inbox lists the notification with. Optional. Without it, the well is `primary` while unread and neutral once read. |
 
-The subject comes from [Categories and Subjects](/docs/interfaces/notifications/categories-and-subjects) — either one you declared with `NotificationSubject()` or one of the built-in constants.
+The subject comes from [Categories and subjects](/docs/interfaces/notifications/categories-and-subjects). It is either one you declared with `NotificationSubject()` or one of the built-in constants.
 
-Titles and descriptions can be literal text or, following the DMS translation convention, a `$`-prefixed translation key; in the latter case the values passed to `.params()` are the interpolation values for that key. The DMS's own account notifications are written that way:
+A title or a description is either literal text or a `$`-prefixed translation key, following the DMS translation convention. With a key, the values passed to `.params()` are the interpolation values for that key. The DMS writes its own account notifications that way:
 
-```typescript
+```typescript fragment
 import {
   Notification,
   SecuritySubject,
@@ -78,35 +75,34 @@ await Notification()
   .icon("i-ph-sign-in")
   .title("$dms.notifications.messages.new_login.title")
   .description("$dms.notifications.messages.new_login.description")
-  .params({ device: "Firefox on Linux", origin: " (203.0.113.4)" })
+  .params({ device: "Firefox on Linux", country: "France" })
   .subject(SecuritySubject)
-  .linkTo("/settings/user/profile")
+  .linkTo("/settings/user/security")
   .build()
   .toUser(userId);
 ```
 
-### Required Fields Are Checked by the Type System
+### Required fields are checked by the type system
 
-`NotificationBuilder<Set>` tracks in its type parameter which fields you have supplied: `.icon()` returns `NotificationBuilder<Set | "icon">`, `.title()` adds `"title"`, and so on. `build()` is declared with a `this` parameter that only accepts a builder whose `Set` covers `RequiredFields`:
+`NotificationBuilder<Set>` tracks in its type parameter which fields you have supplied. `.icon()` returns `NotificationBuilder<Set | "icon">`, `.title()` adds `"title"`, and the other setters add their own names. `build()` declares a `this` parameter that only accepts a builder whose `Set` covers `RequiredFields`:
 
 ```typescript
 type RequiredFields = "icon" | "title" | "description" | "subject";
 ```
 
-So a chain that skips one of the four does not compile — `this` is typed `never` at the `build()` call:
+A chain that skips one of the four does not compile, because `this` is typed `never` at the `build()` call:
 
-```typescript
-// Compile error: description and subject were never supplied
+```typescript fragment
 const broken = Notification().icon("i-ph-bell").title("Hello").build();
 ```
 
-The check happens at the call site. `build()` also checks at runtime, for builders whose type parameter was supplied by hand or whose chain went through `any`: it throws `Notification is missing required fields: description, subject` naming the fields still missing. A field set to `undefined` counts as missing. `.linkTo()`, `.params()` and `.tone()` never affect the check.
+That chain fails because it never supplies the description and the subject. The type check happens at the call site. `build()` also checks at runtime, for builders whose type parameter was written by hand or whose chain went through `any`. It throws `Notification is missing required fields: description, subject`, naming the fields still missing. A field set to `undefined` counts as missing. `.linkTo()`, `.params()` and `.tone()` never affect the check.
 
-`build()` returns a `SendableNotification` holding a frozen copy of the data, so reusing the builder afterwards cannot change a notification you already built.
+`build()` returns a `SendableNotification` that holds a frozen copy of the data, so reusing the builder afterwards cannot change a notification you already built.
 
-## Sending to a Single User
+## Sending to a single user
 
-`toUser(userId, options?)` sends one copy to one user. It accepts an idempotency key; `readScope` has no effect for this method.
+`toUser(userId, options?)` sends one copy to one user. It accepts an idempotency key. `readScope` has no effect for this method.
 
 ```typescript
 import { Controller, Post } from "@antelopejs/interface-api";
@@ -133,44 +129,44 @@ export class NotificationDemoController extends Controller("/api/notification")
 }
 ```
 
-## Sending to Several Users
+## Sending to several users
 
-`toUsers(userIds, options?)` sends to a list of user ids. Duplicate ids in the list produce a single notification per user. The examples in this section and the two below dispatch the `shipped` notification built earlier on this page.
+`toUsers(userIds, options?)` sends to a list of user ids. A duplicate id in the list still produces one notification for that user. The examples in this section and the two after it dispatch the `shipped` notification built earlier on this page.
 
-```typescript
+```typescript fragment
 await shipped.toUsers([ownerId, managerId], { readScope: "shared" });
 ```
 
-## Sending to Roles
+## Sending to roles
 
-`toRoles(roleIds, options?)` resolves the users that hold any of the given roles and sends to them. An empty `roleIds` array sends nothing, and so does a set of roles nobody holds.
+`toRoles(roleIds, options?)` finds the users that hold any of the given roles and sends to them. An empty `roleIds` array sends nothing, and so does a set of roles that nobody holds.
 
-```typescript
+```typescript fragment
 await shipped.toRoles([adminRoleId], { readScope: "shared", tenantId });
 ```
 
-Role ids are the DMS role identifiers described in the DMS tenancy and permissions guide, and they belong to a tenant. `tenantId` (`RoleSendOptions`) restricts the recipients to that tenant's members; without it, membership is resolved across tenants, so a user holding the role in any tenant is included.
+Role ids are the DMS role identifiers that the DMS tenancy and permissions guide describes, and each one belongs to a tenant. `tenantId` (`RoleSendOptions`) limits the recipients to that tenant's members. Without it, the DMS looks up the role holders in every tenant, so a user holding the role in any tenant is included.
 
 ## Broadcasting
 
 `broadcast(options?)` sends to every user.
 
-```typescript
+```typescript fragment
 await shipped.broadcast();
 ```
 
-## Send Options
+## Send options
 
 Every dispatch method accepts an optional `SendOptions` object.
 
 | Option | Type | Description |
 | ------ | ---- | ----------- |
-| `readScope` | `ReadScope` (optional) | Read-state grouping for a multi-recipient send. Defaults to `"individual"` — see [Read Scope](/docs/interfaces/notifications/categories-and-subjects#read-scope). |
-| `idempotencyKey` | `string` (optional) | Stable event key, unique across producers: prefix it with your module ID. Reusing it for a recipient preserves the original notification and dismissal state. |
-| `dedupe` | `boolean` (optional) | `false` stores every unkeyed send, even one identical to a notification the recipient got less than 10 seconds earlier. Defaults to `true`; see below. |
-| `tenantId` | `string` (optional, `toRoles` only: `RoleSendOptions`) | Only the members of this tenant holding the roles; every tenant when unset. |
+| `readScope` | `ReadScope` (optional) | Read-state grouping for a multi-recipient send. Defaults to `"individual"`. See [Read scope](/docs/interfaces/notifications/categories-and-subjects#read-scope). |
+| `idempotencyKey` | `string` (optional) | Stable event key, unique across producers. Prefix it with your module ID. Reusing it for a recipient preserves the original notification and its dismissal state. |
+| `dedupe` | `boolean` (optional) | With `false`, the DMS stores every unkeyed send, even one identical to a notification the recipient got less than 10 seconds earlier. Defaults to `true`. See [Repeated sends](#repeated-sends). |
+| `tenantId` | `string` (optional, `toRoles` only through `RoleSendOptions`) | Only the members of this tenant holding the roles. Every tenant when unset. |
 
-Pick `"shared"` for alerts that only need one person to act on them, and `"individual"` for anything each recipient has to see for themselves.
+Pick `"shared"` for an alert that only needs one person to act on it, and `"individual"` for anything each recipient has to see.
 
 ```typescript
 import type { SendOptions } from "@antelopejs/interface-dms/notifications/types";
@@ -179,51 +175,56 @@ const forEveryone: SendOptions = { readScope: "individual" };
 const handleOnce: SendOptions = { readScope: "shared" };
 ```
 
-## Repeated Sends
+## Repeated sends
 
-An unkeyed notification identical to one the same user received less than 10 seconds earlier is dropped: same recipient, title, description, params, link, category, subject, tone and icon. A form submitted twice, or a hook firing on every instance, leaves one row; two notices worded alike but filed under different subjects, or drawn with a different tone or icon, are two notices. A sender whose repeats are all meant to arrive (a counter ticking, a chat) passes `{ dedupe: false }` to any send method. The check holds across instances: the row ID derives from the recipient, the content and a 10-second window, so the database refuses the second insert, and a copy from the window before also counts. The same notification sent again later arrives as usual, and so does one whose params differ (a count, a timestamp). Keyed sends are deduplicated by their key instead, as described below.
+The DMS drops an unkeyed notification identical to one the same user received less than 10 seconds earlier. Identical means the same recipient, title, description, params, link, category, subject, tone and icon. A form submitted twice, or a hook firing on every instance, leaves one row. Two notices worded alike but filed under different subjects, or drawn with a different tone or icon, are two notices.
 
-## Retrying Durable Events
+A sender whose repeats must all arrive, such as a counter or a chat, passes `{ dedupe: false }` to any send method.
 
-Use the same event key on every outbox retry. The first delivery stored under a key wins: a later send under the same key returns without storing anything, even when its content differs (a count recomputed on retry, a timestamp), so a producer that keys a notification per period does not have to guard against a duplicate-key error. The explicit method is equivalent to passing `idempotencyKey` to `toUsers`; its key argument takes precedence over a key in `options`.
+The check holds across instances. The row ID derives from the recipient, the content and a 10-second window, so the database refuses the second insert. A copy stored in the previous window also counts. The same notification sent again later arrives as usual, and so does one whose params differ, such as a count or a timestamp. The DMS deduplicates keyed sends by their key instead, as the next section describes.
 
-The key is shared by every module of the deployment: the DMS stores one row per key and recipient, whatever module or category sent it. Because a reused key counts as already delivered, two modules that happen to build the same key for the same user would lose the second notification without any error. Namespace your keys with your module ID (`mailing:digest:2026-10-13T09`, not `digest:2026-10-13T09`).
+## Retrying durable events
 
-```typescript
+Use the same event key on every outbox retry. The first delivery stored under a key wins. A later send under the same key returns without storing anything, even when its content differs, such as a count recomputed on retry. A producer that keys a notification per period therefore needs no guard against a duplicate-key error. `toUsersIdempotently` is equivalent to passing `idempotencyKey` to `toUsers`. Its key argument takes precedence over a key in `options`.
+
+Every module of the deployment shares the key space. The DMS stores one row per key and recipient, whatever module or category sent it. A reused key counts as already delivered, so when two modules build the same key for the same user, the second notification is lost without any error. Namespace your keys with your module ID, as in `mailing:digest:2026-10-13T09` rather than `digest:2026-10-13T09`.
+
+```typescript fragment
 await shipped.toUsers([ownerId, managerId], { idempotencyKey: event.id });
 await shipped.toUsersIdempotently([ownerId, managerId], event.id);
 ```
 
-The DMS derives a namespaced SHA-256 row ID from the event key and recipient ID and performs a plain atomic insert. After an insert error, it reads that exact ID and accepts only a matching stored delivery, including its subject, content, and read group. Other errors propagate so an outbox can retry; duplicate attempts never replace the row or reset its timestamps or read state.
+The DMS derives a SHA-256 row ID from the event key and the recipient ID, and performs a plain insert. If the insert fails, it reads the row under that ID. When that row is a keyed delivery to the same recipient, the send returns without an error. Otherwise the DMS rethrows the insert error, so an outbox can retry. A repeated attempt never replaces the row or resets its timestamps or read state.
 
-Single and bulk dismissal retain keyed rows as hidden delivery receipts. Lists, previews, counts, individual lookups, and read operations exclude these rows; retries do not recreate them. Unkeyed notifications retain physical deletion and fresh delivery on every send outside the 10-second [repeat window](#repeated-sends). Receipts retain notification content indefinitely: do not hard-delete or expire these rows while their event keys can still be retried, and account for this retention when designing data-erasure policies.
+Single and bulk dismissal keep keyed rows as hidden delivery receipts. Lists, previews, counts, single lookups and read operations exclude these rows, and retries do not recreate them. The DMS still deletes a dismissed unkeyed notification, and delivers an unkeyed send again outside the 10-second [repeat window](#repeated-sends). Receipts keep the notification content with no expiry. Do not delete or expire these rows while their event keys can still be retried, and account for this retention in your data-erasure policies.
 
-Shared-read sends derive a stable group ID from the event key. Recipient membership and preferences are evaluated again on each attempt, so a retry can add previously missing recipients without duplicating successful deliveries. A recipient added after another recipient has already marked the group read starts unread; retries preserve existing recipients' state rather than replaying past read actions.
+A shared-read send derives a stable group ID from the event key. The DMS checks recipient membership and preferences again on each attempt, so a retry can add recipients that were missing before without duplicating the deliveries that succeeded. A recipient added after another recipient has marked the group read starts unread. Retries keep the state of the existing recipients and do not replay past read actions.
 
-Realtime publishing remains best-effort and occurs only after a newly inserted delivery. A crash or lost acknowledgement can leave a stored notification without a realtime event; retrying does not replay realtime. Delivery gates still apply, and skipped recipients do not receive receipts.
+Realtime publishing is best-effort and happens only after a newly inserted delivery. A crash or a lost acknowledgement can leave a stored notification without a realtime event, and a retry does not replay it. The delivery rules still apply, and a skipped recipient gets no receipt.
 
-Consumers that support older DMS packages must fail closed instead of passing an option an old runtime silently ignores. Feature-detect the explicit method and retain pending outbox work until the DMS package and runtime are upgraded together to a version containing it:
+Before it sends, every keyed dispatch asks the DMS implementation, through `SupportsIdempotency`, whether it supports keyed delivery. If the implementation does not answer `true`, the dispatch throws `DMS idempotent notification delivery is unavailable` and sends nothing, rather than delivering without deduplication.
 
-```typescript
+If your module can load against a DMS implementation that has no `toUsersIdempotently` method, check for the method and fail closed. Keep the pending outbox work until the DMS packages provide it:
+
+```typescript fragment
 if (!("toUsersIdempotently" in shipped) || typeof shipped.toUsersIdempotently !== "function") {
   throw new Error("DMS idempotent notification delivery is unavailable");
 }
 await shipped.toUsersIdempotently([ownerId, managerId], event.id);
 ```
 
-Every keyed dispatch also checks the implementation's `SupportsIdempotency` interface capability before sending. A new local builder paired with an old DMS implementation therefore rejects rather than silently delivering without deduplication.
+## Delivery rules
 
-## Delivery Rules
+Every dispatch method resolves to one delivery per user, so the DMS applies the same rules to each of them:
 
-The DMS applies the same rules to every dispatch method, since `toUsers`, `toRoles` and `broadcast` all resolve to per-user deliveries:
+- **The subject must be registered.** The DMS drops a notification whose subject was never registered through `NotificationSubject()`. See [Declaration order](/docs/interfaces/notifications/categories-and-subjects#declaration-order).
+- **The title must not be empty.** The DMS drops a notification whose title is empty or only whitespace, and logs `[DMS] Notification without a title not delivered`.
+- **The user preference decides.** The DMS skips a delivery when the recipient has turned off the `categoryId:subjectId` pair in their notification settings. Preferences default to enabled, so a subject a user has never touched is delivered. A [locked subject](/docs/interfaces/notifications/categories-and-subjects#toggle-permissions) is delivered whatever the stored preference.
+- **Skipping is silent.** A skipped delivery is not an error. The promise resolves normally, and there is no per-recipient result to inspect.
+- **Each recipient gets a row.** Each recipient gets their own stored notification. With `readScope: "shared"`, the DMS ties those copies together for read state, and they stay separate rows.
+- **Stored notifications are pushed live.** The DMS also publishes each new delivery on the recipient's realtime stream, so the dashboard's badge and preview update without a reload.
 
-- **The subject must be registered.** A notification whose subject was never declared through `NotificationSubject()` is dropped. This is what makes registration order matter — see [Declaration Order](/docs/interfaces/notifications/categories-and-subjects#declaration-order).
-- **The user preference is honored.** Delivery is skipped when the recipient has turned off the `categoryId:subjectId` pair in their notification settings. Preferences default to enabled, so a subject a user has never touched is delivered.
-- **Skipping is silent.** A gated-out delivery is not an error: the promise resolves normally, and there is no per-recipient result to inspect.
-- **Delivery is per recipient.** Each recipient gets their own stored notification. With `readScope: "shared"` those copies are tied together for read state; they are still separate rows.
-- **Stored notifications are pushed live.** Each delivery is also published on the recipient's realtime stream, so the dashboard's badge and preview update without a reload.
-
-Because a send can be skipped for reasons outside your control, treat notifications as best-effort: do not make a workflow depend on one having been stored. Wrapping the call so a failure cannot break the operation that triggered it is a common pattern:
+A send can be skipped for reasons outside your control, so treat notifications as best-effort and do not make a workflow depend on one having been stored. To keep a failed send from breaking the operation that triggered it, wrap the call:
 
 ```typescript
 import { Logging } from "@antelopejs/interface-core/logging";
@@ -249,18 +250,18 @@ export async function notifyWelcome(userId: string, name: string) {
 }
 ```
 
-## Importing the Types
+## Importing the types
 
-`Notification()` is exported from the interface root, and the data types from the `types` subpath. The two classes are exported from the modules that define them, which you only need when you want to name them explicitly:
+The interface root exports `Notification()` and the data types. The `types` subpath exports the data types alone. The two classes come from the modules that define them, which you need only to name them explicitly:
 
 | Symbol | Import from |
 | ------ | ----------- |
 | `Notification` | `@antelopejs/interface-dms/notifications` |
-| `NotificationData`, `SendOptions`, `RequiredFields` | `@antelopejs/interface-dms/notifications/types` |
+| `NotificationData`, `SendOptions`, `RoleSendOptions`, `RequiredFields` | `@antelopejs/interface-dms/notifications` or `@antelopejs/interface-dms/notifications/types` |
 | `NotificationBuilder` | `@antelopejs/interface-dms/notifications/builder` |
 | `SendableNotification` | `@antelopejs/interface-dms/notifications/sendable` |
 
-`NotificationData` is the shape the builder assembles — `icon`, `title`, `description` and `subject`, plus the optional `linkTo` and `params`. Naming it is useful when you carry notification content around before building it:
+`NotificationData` is the shape the builder assembles. It holds `icon`, `title`, `description` and `subject`, plus the optional `linkTo`, `params` and `tone`. Name it when you carry notification content around before you build it:
 
 ```typescript
 import { Notification } from "@antelopejs/interface-dms/notifications";
@@ -280,6 +281,9 @@ function fromData(data: NotificationData): SendableNotification {
   if (data.params) {
     builder.params(data.params);
   }
+  if (data.tone) {
+    builder.tone(data.tone);
+  }
 
   return builder.build();
 }