@assembly-js/app-foundation 0.0.1 → 0.0.2-rc.3

package/skills/assembly-notifications/SKILL.md

@@ -0,0 +1,503 @@
+---
+name: assembly-notifications
+# <!-- !feature:notification-settings -->
+description: Use when the app needs to notify internal users or clients about something that happened. Covers in-product notifications, email, the Notification Center surface, and how to create notifications. Apps call `assembly.createNotification()` — no external services, no custom polling. To clear the client portal badge after sending a client notification, see the `clearing-client-notifications` skill.
+# <!-- /feature:notification-settings -->
+# <!-- feature:notification-settings -->
+description: Use when the app needs to notify internal users or clients about something that happened. Covers in-product notifications, email, the Notification Center surface, and how to create notifications. Apps call `assembly.createNotification()` — no external services, no custom polling. Also covers per-user notification preferences for internal users — declaring toggleable notification categories under `notificationSettings` in `.assembly/app.json` and passing `notificationSettingId` on createNotification so each internal user's Product/Email toggles are honored. To clear the client portal badge after sending a client notification, see the `clearing-client-notifications` skill.
+# <!-- /feature:notification-settings -->
+---
+
+## Mental model
+
+Send a notification when something happens that the recipient should know about and didn't cause themselves — action required (review, approve, respond) or awareness (status changes, completions, new messages). Skip routine reads, navigation, and trivial state changes. Under-send rather than over-send.
+
+Every notification is three decisions: **audience** (internal users and/or clients), **channel** (in-product, email, or both), and **context on arrival** (what the recipient sees and can do). Get those right; the rest is mechanics.
+
+### Internal vs client experience
+
+The audience changes the experience and the code:
+
+- **Internal users** have a Notification Center (a Dashboard sidebar item). Notifications accumulate there, expand in place on click, and auto-clear once viewed. Opening one shows breadcrumbs (app + client/company, both linked) above the notification *surface* (see below).
+- **Clients** have no Notification Center — just a counter badge next to the app in the portal sidebar. There's no per-notification click; the client opens the app and the app decides what to show. **The app must clear the badge** (see "Clearing the client portal badge"). Unhandled client badges stick forever — the most common bug in client-facing apps.
+
+### Choosing the channel
+
+- **In-product only** (default): the Notification Center / badge is the surface, no email noise.
+- **In-product + email**: when the recipient must come back to act but might not check on their own (submissions to review, payment failures, approvals, deliverables ready). The email pulls them in; the in-product notification gives them a place to land. Don't email every notification — reserve it for events that need a pull.
+- **Email only** (omit `inProduct`): when it needn't live in the Notification Center or trigger a badge — receipts to archive, digests, formal comms, or actions that live outside the product.
+
+## Notification surfaces
+
+A surface is the embedded view the Notification Center renders when an internal user opens a notification. It's a route (conventionally `/n`) that reads the notification context — `notificationId` from the token payload plus your `ctaParams` — and renders the most useful thing: a filtered list of the items referenced, a single record with its key actions, or a status summary. When there's nothing more useful than "here's what happened, click to go deeper," skip it — the Notification Center then falls back to the title, body, and CTA from your `createNotification` call.
+
+Surfaces are internal-only. Clients don't render one, but `ctaParams` still travel with the notification and become URL search params on an email CTA click — that's how a client landing from an email gets enough context.
+
+### Declaring a surface
+
+Add it to `.assembly/app.json` (see the `assembly-app-surfaces` skill for all surfaces):
+
+```json
+{
+  "surfaces": {
+    "internal": { "path": "/" },
+    "notification": { "path": "/n" }
+  }
+}
+```
+
+### Reading notification context (Next.js 15)
+
+`headers()` and `searchParams` are async. Branch on your `ctaParams` (the URL search params) to decide what to render — that is what points at the specific record. Branching on `ctaParams` keys is how one surface handles multiple notification types (see "Apps with multiple notification types").
+
+**Render off the `ctaParams`, never gate it on `notificationId`.** Your `ctaParams` always arrive as URL search params, but the `notificationId` token claim is best-effort: under the session-exchange auth flow it can be absent even on a genuine notification open. A page that short-circuits to its fallback when `notificationId` is missing renders "no record to show" for every deep-link under that flow. Treat `notificationId` as an enhancement (e.g. marking the open as read), not the gate for the record itself.
+
+```tsx
+// app/n/page.tsx
+export default async function NotificationSurface({
+  searchParams,
+}: {
+  searchParams: Promise<{ submissionId?: string; taskId?: string }>;
+}) {
+  const { submissionId, taskId } = await searchParams;
+
+  // The record to show comes from the ctaParams, which always arrive on the URL.
+  if (submissionId) return <SubmissionDetail id={submissionId} />;
+  if (taskId) return <TaskDetail id={taskId} />;
+
+  // No record param → nothing specific to deep-link to; show a summary.
+  return <RecentActivity />;
+}
+```
+
+### CTAs on the notification surface — inline buttons, NOT the header
+
+The Notification Center embeds the notification surface (`/n`) in a plain `<iframe>` **without app bridge header support**. `useAssemblyHeader` calls on this surface are silently ignored — `primaryCta`, `secondaryCta`, and `actionsMenu` never render.
+
+**On the notification surface, render primary action buttons (Approve, Reject, Submit, Mark Complete, etc.) as inline `<Button>` elements in the page body.** This is the one exception to the portal-wide rule that CTAs must go in the header. The exception applies ONLY to the `/n` route — all other surfaces must continue using `useAssemblyHeader`.
+
+Detect the notification surface by the route itself — code under `app/n/` IS the surface. For a component shared with other surfaces, pass an explicit `variant="notification"` prop from the `/n` page rather than inferring it from `payload.notificationId`: the claim is best-effort under the session-exchange flow, so a component that keys off it can silently fall back to header CTAs that never render inside the Notification Center iframe.
+
+**Do not reuse a component that calls `useAssemblyHeader` on the notification surface.** A component that calls `useAssemblyHeader` AND renders an inline action button produces duplicate CTAs on non-notification surfaces — the header button and the inline button both appear. Either create a dedicated component for `/n` that uses only inline buttons, or accept a prop that switches between header and inline CTAs.
+
+## Creating a notification
+
+```ts
+const assembly = await getAssembly();
+const id = await getSessionIdentity();
+await assembly.createNotification({
+  requestBody: {
+    senderId: id?.internalUserId ?? id?.clientId,
+    recipientInternalUserId: internalUserId,
+    deliveryTargets: {
+      inProduct: {
+        title: 'New submission received',
+        body: 'Jane Doe submitted their brand questionnaire.',
+        ctaParams: { submissionId: submission.id },
+      },
+      email: {
+        subject: 'New submission to review',
+        header: 'Brand Questionnaire Submitted',
+        htmlBody: '<p><strong>Jane Doe</strong> submitted their brand questionnaire.</p>',
+        title: 'Review submission', // CTA button label
+      },
+    },
+  },
+});
+```
+
+The examples here are **request-scoped** — a user is present, so `getAssembly()` reads the bearer from the request cookie and acts as that viewer. For a **background send with no user in the loop** (a scheduled job or an incoming webhook), there is no bearer cookie: call `getOfflineAssembly()` from `@assembly-js/app-foundation/server`, which mints an app-scoped **offline bearer** from your API key server-side. In that path `getSessionIdentity()` returns `null`, so choose a `senderId` explicitly (e.g. a system/admin internal user) rather than reading it from identity.
+
+```ts
+// app/api/cron/reminders/route.ts — background send, no viewer
+import { getOfflineAssembly } from '@assembly-js/app-foundation/server';
+
+export async function GET() {
+  const assembly = await getOfflineAssembly(); // app-scoped bearer, no cookie
+  await assembly.createNotification({
+    requestBody: {
+      senderId: SYSTEM_INTERNAL_USER_ID, // getSessionIdentity() is null here — pick one explicitly
+      recipientInternalUserId: assignedStaffId,
+      deliveryTargets: { inProduct: { title: 'Reminder', ctaParams: { taskId: task.id } } },
+    },
+  });
+  return Response.json({ ok: true });
+}
+```
+
+### Fields, demystified
+
+- `senderId` — required. The user who caused the notification, from `getSessionIdentity()`. Use `id.internalUserId` for staff-triggered events, `id.clientId` for client-triggered events. The pattern `id?.internalUserId ?? id?.clientId` works for routes that can be hit by either.
+- `recipientInternalUserId` — notify one specific internal user.
+- `recipientClientId` — notify one specific client.
+- `recipientCompanyId` — paired with `recipientClientId`. Scopes which of the recipient's companies the notification is associated with. **Required** when the recipient is a client who belongs to more than one company — omit it and the send fails with `400 "company ID is required when notifying a client"`. Auto-inferred when the client belongs to exactly one company, so you can skip it then. Do not set this when the recipient is an internal user. **It is not a recipient on its own** — see "Notifying a company" below.
+- `senderCompanyId` — scopes the notification to one of the *sender's* companies. **Required** when the sender is a client who belongs to more than one company **and the recipient is an internal user** — omit it and the send fails with `400 "sender company ID is invalid based on sender"`. Auto-inferred when the client sender belongs to exactly one company, so you can skip it then. See "Company scoping, by recipient type" below for why a multi-company sender still has to scope even when notifying staff.
+- `senderType` — read-side only. Automatically populated from `senderId` (client, internal user, or company). You do not set it on create.
+- `deliveryTargets.inProduct` — include to make the notification appear in the Notification Center (for internal users) or trigger the badge (for clients). Requires `title`. `body` and `ctaParams` are optional. Omit entirely for email-only notifications.
+- `deliveryTargets.email` — include to send an email. `subject`, `header`, and `title` (CTA button label) are required, plus one body: `htmlBody` for formatted content (see below) or `body` for plain text. Either `inProduct` or `email` must be present; both is also valid.
+- `ctaParams` — a plain object of string key/value pairs that become URL search params when the user engages with the notification. Pass as an object — never `JSON.stringify()`. **Values must be strings** — stringify numbers and booleans yourself (e.g., `{ count: '3' }`, not `{ count: 3 }`). Nested objects aren't supported. Used by both the email CTA and the Notification Center surface.
+<!-- feature:notification-settings -->
+- `notificationSettingId` — the id of one of the app's declared notification settings (see "Per-user notification settings" below). Pass it on **every** send of a declared category so internal users' Product/Email toggles apply. Omit it for sends with no declared setting.
+<!-- /feature:notification-settings -->
+
+### Formatted email bodies
+
+`htmlBody` replaces `body` when the email reads better with structure — a paragraph plus a list of what changed, one bolded value. It is email-only; the in-product `body` is always plain text. Allowed tags: `p`, `br`, `strong`/`b`, `em`/`i`, `ul`, `ol`, `li`, and `a href` with an `https` URL, e.g. `'<p>Your invoice is ready.</p><ul><li>Amount: <strong>$240.00</strong></li><li>Due Mar 14</li></ul>'`.
+
+Send a fragment, not a document, and don't attempt layout or branding: every tag outside that list — `div`, `table`, headings, `img`, `class`, inline styles, `script` — is stripped server-side with no error, leaving its text run together unformatted, and the platform's email template supplies the frame. The plain-text alternative is derived from `htmlBody` automatically; pass `body` alongside it only to write that text yourself.
+
+### Company scoping, by recipient type
+
+Every notification is scoped to a company, and which field supplies it depends on **who the recipient is** — the part that trips up multi-company clients:
+
+- **Notifying a client** → company comes from `recipientCompanyId` (the recipient's company). E.g. Jane belongs to AcmeCo and BetaCo; notifying her about an AcmeCo submission sets `recipientClientId = Jane` and `recipientCompanyId = AcmeCo`.
+- **Notifying an internal user** → company comes from `senderCompanyId` (the *sender's* company). This is the non-obvious case: when a multi-company **client** triggers an event that notifies staff (a client decision, a client submission), pass `senderCompanyId` even though the recipient is internal — the platform can't guess which of the sender's companies it belongs to.
+
+The field is only *required* when the relevant party belongs to more than one company (single-company members are auto-inferred), but passing the company id when you have it (e.g. `id.companyId` from `getSessionIdentity()`) is always safe.
+
+```ts
+// Multi-company client (sender) notifying internal staff: senderCompanyId required,
+// recipientCompanyId does NOT apply (recipient is internal).
+const id = await getSessionIdentity();
+await assembly.createNotification({
+  requestBody: {
+    senderId: id?.clientId,
+    senderCompanyId: id?.companyId, // the company the client is acting under
+    recipientInternalUserId: assignedStaffId,
+    deliveryTargets: { inProduct: { title: 'Client approved the proposal', ctaParams: { proposalId: proposal.id } } },
+  },
+});
+```
+
+To notify multiple recipients (e.g., several internal users), make one `createNotification` call per recipient. See "Apps with multiple notification types" below.
+
+**`listInternalUsers` / `listClients` are paginated** — one call returns only the first page. To notify *everyone*, page through `nextToken` and collect all recipients before fanning out, or you'll silently skip later-page recipients:
+
+```ts
+const recipients = [];
+let nextToken: string | undefined;
+do {
+  const res = await assembly.listInternalUsers({ nextToken });
+  recipients.push(...(res.data ?? []));
+  nextToken = res.nextToken ?? undefined;
+} while (nextToken);
+await sendThrottled(recipients, (u) =>
+  assembly.createNotification({ /* ...recipientInternalUserId: u.id... */ }),
+);
+```
+
+`sendThrottled` is the fan-out helper from the next section — use it for any recipient list, never a bare `Promise.all`.
+<!-- feature:notification-settings -->
+
+## Per-user notification settings (internal users)
+
+Internal users have a platform notification-settings page that lists each app's declared notification categories with per-category Product and Email toggles. Two pieces make the app's notifications honor those toggles:
+
+1. Declare each category under a top-level `notificationSettings` key in `.assembly/app.json`.
+2. Pass that category's id as `notificationSettingId` on **every** `createNotification` call that sends it. A declared category whose sends omit the id ignores the user's toggles — the settings page then shows a switch that does nothing.
+
+Declare settings when the app sends **recurring internal-user notifications** — repeated events of one kind (task completed, submission received, invoice paid) — and always when the user asks for notifications that can be turned off or configured. One setting per category. Do not declare settings for client recipients: clients have no notification-settings page, so client notifications have no settings dimension. **Never build an in-app notification preferences screen or a preferences table** — the platform page already exists; declaring settings is how the app appears on it.
+
+### Manifest schema
+
+```json
+{
+  "surfaces": { "internal": { "path": "/" }, "notification": { "path": "/n" } },
+  "notificationSettings": {
+    "notifications": [
+      {
+        "id": "74de3985-ac2d-4477-b917-f12c54a0dde7",
+        "label": "Task completed",
+        "surfaces": ["product", "email"],
+        "default": { "product": true, "email": false }
+      }
+    ]
+  }
+}
+```
+
+- `id` — required. Generate a random lowercase UUID per setting when you first declare it (e.g. `crypto.randomUUID()`); never derive it from the label — `"time-entry-logged"` is wrong, `"74de3985-ac2d-4477-b917-f12c54a0dde7"` is right. **Permanent**: the id keys each internal user's saved toggle state, is the value app code passes as `notificationSettingId`, and an unchanged id is what makes an edited entry the same setting when the manifest is re-applied. When updating an app that already declares settings, reuse every existing id exactly and generate fresh UUIDs only for new categories — regenerating an id orphans every user's saved preference and 400s code still sending the old id. Change the `label` freely; never the `id`.
+- `label` — required, ≤100 chars. Shown on the settings page next to the toggles.
+- `surfaces` — required; `"product"` (Notification Center) and/or `"email"`. A surface not declared here can never deliver for this category, even when the send includes it in `deliveryTargets` — declare every surface the code sends.
+- `default` — delivery state before a user touches their toggles. An omitted surface defaults to off, so set it explicitly for each declared surface. Use `true` unless the user asked for opt-in delivery.
+- `notifications` — 1 to 50 settings; ids must be unique.
+- `actionLabel` — an optional sibling key, not a per-setting field, and a different audience entirely: it is client-facing. See "App-level action label (Client Home)" below.
+
+### Sending against a setting
+
+Define each declared id once as a named constant and send with the constant — inline UUID literals are typo-prone:
+
+```ts
+// lib/notification-settings.ts — one constant per declared setting; values must match .assembly/app.json exactly
+export const TASK_COMPLETED_SETTING_ID = '74de3985-ac2d-4477-b917-f12c54a0dde7';
+```
+
+```ts
+await assembly.createNotification({
+  requestBody: {
+    senderId: payload.internalUserId ?? payload.clientId,
+    recipientInternalUserId: u.id,
+    notificationSettingId: TASK_COMPLETED_SETTING_ID,
+    deliveryTargets: {
+      inProduct: { title: 'Task completed', ctaParams: { taskId: task.id } },
+      email: {
+        subject: 'A task was completed',
+        header: 'Task completed',
+        htmlBody: '<p><strong>Design review</strong> is complete.</p>',
+        title: 'Review task',
+      },
+    },
+  },
+});
+```
+
+Include in `deliveryTargets` every surface the setting declares; the platform resolves, per recipient, which of them actually deliver: their stored toggle, else the declared default. The user's global notification preferences still apply on top — a global mute suppresses delivery even when the per-app toggle is on. Resolution outcomes:
+
+- **Some surfaces off** → the notification delivers on the remaining surfaces. Normal success.
+- **All surfaces off** → nothing is created; the API returns 202 with a `message` body instead of a notification. The SDK resolves normally — **treat it as success**. Do not retry, do not log an error, do not fall back to another channel.
+- **Unknown `notificationSettingId`** → 400 for every recipient type. The id must exactly match a declared setting id.
+
+If `tsc` rejects `notificationSettingId` (an older scaffold's SDK version), run `bun add @assembly-js/node-sdk@latest` and re-check — the API accepts the field regardless.
+
+If `bun run build` fails with an unknown-top-level-key error on `notificationSettings`, the repo's scaffold validator predates the key: edit `.assembly/validate-manifest.mjs` and add `'notificationSettings'` to `TOP_LEVEL_KEYS`, then rerun.
+
+## App-level action label (Client Home)
+
+`actionLabel` shares the `notificationSettings` object but is a **client-facing** feature with no relation to the per-user toggles above: it gives the app a row in the client's "Your Actions" card on Client Home, rendered `[verb] [count] [noun]` — "Complete 1 form", "Complete 3 forms". The count is the signed-in client's own *unread* in-product notifications from this app, so it goes stale unless the app clears them (see "Clearing the client portal badge"), and at zero no row renders at all. Internal-user notifications never produce a row, and `notificationSettingId` has no bearing on it. One per app; all three fields non-empty or omit the object entirely, since a partial label fails the build.
+
+Declare it only when both hold:
+
+1. The app sends in-product notifications to **clients** (`recipientClientId`), not only to staff.
+2. What those notifications ask for is work the **client** does — complete, sign, approve, book, upload.
+
+Frequency is not a criterion: a one-time client action is a legitimate fit ("Sign 1 contract" is a shipped built-in row). Word the verb and nouns from the client's side, and keep `actionLabel` beside a non-empty `notifications` array — an app that declares no internal-user categories cannot declare an action label either.
+
+- ❌ `{ "verb": "review", "singularNoun": "intake", "pluralNoun": "intakes" }` on an app where clients submit an intake and **staff** review it. Nothing is sent to a client, so the row can never render — while the App Setup page shows it fully configured.
+- ✅ `{ "verb": "complete", "singularNoun": "intake", "pluralNoun": "intakes" }` on an app that notifies the client when an intake form is waiting for them.
+<!-- /feature:notification-settings -->
+
+## Throttling fan-outs
+
+`createNotification` is a write, and a token's writes are capped at **5 concurrent** (a token-bucket limit shared across *all* the request's writes). `Promise.all(list.map(createNotification))` fires every call at once: past ~5 recipients the overflow returns `429` and is dropped or surfaces as a failed request. It passes a quick test and breaks once a workspace has enough users — so don't wait to see it fail.
+
+Cap concurrency below the bucket (3 leaves headroom) and retry 429s with backoff. No dependency — external libraries are forbidden and a small helper covers it. Define it once and reuse it for every list-sized write fan-out (sends, badge clears, batch updates):
+
+```ts
+// lib/notify.ts — throttle a write fan-out under the 5-concurrent cap, retry 429s.
+const CONCURRENCY = 3;
+const MAX_RETRIES = 4;
+
+async function withRetry<T>(fn: () => Promise<T>): Promise<T> {
+  for (let attempt = 0; ; attempt++) {
+    try {
+      return await fn();
+    } catch (err) {
+      const status = (err as { status?: number })?.status; // SDK throws ApiError with numeric status
+      if (status !== 429 || attempt >= MAX_RETRIES) throw err;
+      await new Promise((r) => setTimeout(r, 200 * 2 ** attempt + Math.random() * 100));
+    }
+  }
+}
+
+// Runs `task` over every item, at most CONCURRENCY in flight, retrying 429s.
+// Settles instead of throwing so one bad item never aborts the rest.
+export async function sendThrottled<T, R>(
+  items: T[],
+  task: (item: T) => Promise<R>,
+): Promise<PromiseSettledResult<R>[]> {
+  const results: PromiseSettledResult<R>[] = [];
+  let cursor = 0;
+  const worker = async () => {
+    while (cursor < items.length) {
+      const i = cursor++;
+      try {
+        results[i] = { status: 'fulfilled', value: await withRetry(() => task(items[i])) };
+      } catch (reason) {
+        results[i] = { status: 'rejected', reason };
+      }
+    }
+  };
+  await Promise.all(Array.from({ length: Math.min(CONCURRENCY, items.length) }, worker));
+  return results;
+}
+
+// Log partial failures; the caller's data write already committed, so don't throw.
+export function logFailures(results: PromiseSettledResult<unknown>[], label: string) {
+  const failed = results.filter((r) => r.status === 'rejected').length;
+  if (failed) console.error(`${failed}/${results.length} ${label} failed`);
+}
+```
+
+Route every recipient-list fan-out through it, then log partial failures:
+
+```ts
+const results = await sendThrottled(recipients, (u) =>
+  assembly.createNotification({ requestBody: { senderId, recipientInternalUserId: u.id, deliveryTargets } }),
+);
+logFailures(results, 'notifications');
+```
+
+A **fixed handful** of calls (two or three for one event) never exceeds the bucket — a plain `Promise.all` is fine there. The cap only bites when the count is driven by a list. The same helper applies to `markNotificationRead` badge clears (see the `clearing-client-notifications` skill).
+
+### Avoiding duplicates
+
+The platform does not dedupe `createNotification` calls. If your trigger can fire more than once — webhook retries, server retries on transient failures, double-clicked form submits — you'll create duplicate notifications. This is the most common bug in webhook-driven flows.
+
+Two ways to guard:
+
+```ts
+// Option 1: check before creating. Pass includeRead so retries after
+// the first notification was viewed still no-op.
+const { data: notifications = [] } = await assembly.listNotifications({
+  recipientInternalUserId: recipientId,
+  includeRead: true,
+});
+if (
+  notifications.some(
+    (n) => n.deliveryTargets?.inProduct?.ctaParams?.submissionId === submission.id,
+  )
+) {
+  return;
+}
+await assembly.createNotification({ /* ... */ });
+```
+
+```ts
+// Option 2: track on the trigger resource.
+if (submission.notified) return;
+await assembly.createNotification({ /* ... */ });
+await markSubmissionNotified(submission.id);
+```
+
+Option 2 is cheaper (no list call) and more reliable. Pick option 1 when you don't control the trigger schema.
+
+## Clearing the client portal badge
+
+Because clients see a badge counter rather than a Notification Center, every `createNotification({ recipientClientId })` is only half the job — the app must `markNotificationRead` at the right moment or the badge sticks forever. Leaving it unhandled is the most common bug in client-facing apps. There are two patterns:
+
+- **Clear on view** — for informational notifications. Mark read when the client opens the corresponding content (a status update, a reply, a ready deliverable).
+- **Clear on action** — for notifications that ask the client to *do* something. Mark read inside the server action that completes the work (filling a form, marking a task done, granting an approval) — clearing on view would drop the prompt before they act.
+
+Either way, list the client's unread notifications and filter in memory by the `ctaParams` you set on create, then clear only those — there is no server-side filter below the recipient level.
+
+**If your app sends any client notification, load the `clearing-client-notifications` skill** for the full pattern, code for both cases, and the pre-ship checklist. Don't consider a client-facing app done until the matching clear is implemented and you can name where it runs.
+
+## Apps with multiple notification types
+
+Each notification type is its own `createNotification` call with its own `ctaParams` shape.
+
+For an event that needs multiple recipients (e.g., a submission notifies the assigned staff member and the requesting client), make one `createNotification` call per recipient. Each call can have different `ctaParams` — internal users typically want a filter scoped to the client; clients want a deep link to their own record. A fixed pair like this stays under the 5-concurrent cap, so a plain `Promise.all` is fine; reach for `sendThrottled` only when the count is driven by a list.
+
+```ts
+await Promise.all([
+  assembly.createNotification({ requestBody: {
+    senderId: clientId, recipientInternalUserId: assignedStaffId,
+    deliveryTargets: { inProduct: {
+      title: 'New submission', body: `${clientName} submitted ${formName}.`,
+      ctaParams: { submissionId: submission.id, view: 'review' },
+    } },
+  } }),
+  assembly.createNotification({ requestBody: {
+    senderId: clientId, recipientClientId: clientId,
+    deliveryTargets: { inProduct: {
+      title: 'Submission received', body: `We've received your ${formName} and will review shortly.`,
+      ctaParams: { submissionId: submission.id },
+    } },
+  } }),
+]);
+```
+
+### Fanning out to internal users with Client Access
+
+For a client- or company-scoped event whose audience is "all internal users with access," filter yourself — notifying a user about a client they can't access violates the permission model and may leak client info. Users with `isClientAccessLimited: false` see everyone; those with `true` see only clients whose company is in their `companyAccessList`. Every client has a company (real or placeholder), so the company check covers all clients.
+
+```ts
+const { companyIds = [] } = await assembly.retrieveClient({ id: clientId });
+
+const internalUsers = [];
+let nextToken: string | undefined;
+do {
+  const page = await assembly.listInternalUsers({ nextToken });
+  internalUsers.push(...(page.data ?? []));
+  nextToken = page.nextToken ?? undefined;
+} while (nextToken);
+
+// Filter to users with access to this client.
+const recipients = internalUsers.filter(
+  (u) =>
+    !u.isClientAccessLimited ||
+    companyIds.some((companyId) => u.companyAccessList?.includes(companyId)),
+);
+// Add `.filter((u) => u.role === 'admin')` when the plan is admins/staff only.
+
+const results = await sendThrottled(recipients, (u) =>
+  assembly.createNotification({
+    requestBody: {
+      senderId: clientId,
+      recipientInternalUserId: u.id,
+      deliveryTargets: { inProduct: { title: 'New submission', ctaParams: { submissionId: submission.id } } },
+    },
+  }),
+);
+logFailures(results, 'notifications');
+```
+
+A company-scoped event uses `companyId` directly — same filter, same shape. Workspace-wide notifications (tied to no client or company) go to all internal users, no filter.
+
+### Notifying a company
+
+"Notify a company" means notify every client at it (the platform semantic for company-assigned invoices and contracts). The API has no company-only recipient — passing just a company id is rejected with `exactly one of recipientClientId or recipientInternalUserId must be provided`. Enumerate the company's clients and send one each.
+
+```ts
+const id = await getSessionIdentity();
+const clients = [];
+let nextToken: string | undefined;
+do {
+  const page = await assembly.listClients({ nextToken });
+  clients.push(
+    ...(page.data ?? []).filter((client) => client.companyIds?.includes(companyId)),
+  );
+  nextToken = page.nextToken ?? undefined;
+} while (nextToken);
+
+const results = await sendThrottled(clients, (c) =>
+  assembly.createNotification({
+    requestBody: {
+      senderId: id?.internalUserId ?? id?.clientId,
+      recipientClientId: c.id,
+      recipientCompanyId: companyId,
+      deliveryTargets: {
+        inProduct: { title: 'Invoice ready', body: 'A new invoice is ready for your review.', ctaParams: { invoiceId: invoice.id } },
+      },
+    },
+  }),
+);
+logFailures(results, 'notifications');
+```
+
+Each client gets their own badge and clears it independently. `recipientCompanyId` is the same value for all of them — it scopes the notification to the company context, not the recipient set.
+
+## What NOT to do
+
+- Do not `Promise.all` a recipient-list fan-out. Writes cap at 5 concurrent; firing a whole list at once 429s and drops notifications. Use `sendThrottled` (see "Throttling fan-outs"). A fixed handful of calls is the only exception.
+- Do not use `recipientId` — deprecated. Use `recipientClientId` or `recipientInternalUserId`.
+- Do not pass `recipientCompanyId` alone as a recipient. The API rejects it. To notify a company, fan out across its clients (see "Notifying a company").
+- Do not omit the company id when a multi-company client is involved. Notifying a multi-company client needs `recipientCompanyId` (`400 "company ID is required when notifying a client"`); a multi-company client *sending* to an internal user needs `senderCompanyId` (`400 "sender company ID is invalid based on sender"`). Single-company members are auto-inferred. See "Company scoping, by recipient type."
+- Do not send notifications from client-side code. Always server actions or server routes.
+- Do not install external notification libraries. The Notification Center handles display.
+- Do not build custom polling. The platform handles delivery.
+- Do not `JSON.stringify(ctaParams)`. Pass it as a plain object.
+- Don't echo every in-product notification with an email. Reserve email for events that need a pull.
+- Do not put HTML in the plain `body` — it is escaped, so the tags arrive as literal text. Use `htmlBody` for formatting.
+- Do not let a literal `{{ … }}` reach an email `body` or `htmlBody`. The platform re-parses the assembled email as a template, so the render fails and the email never sends — strip braces out of any text you interpolate.
+- Do not leave client portal badge counts unhandled. If you send an in-product notification to a client, you must mark it read somewhere in the client flow — on view for awareness notifications, on action for prompts. See the `clearing-client-notifications` skill. Email-only notifications to clients don't create badges, so this rule doesn't apply to them.
+- Do not notify internal users who don't have access to the client or company the notification concerns. Filter by `isClientAccessLimited` and `companyAccessList` before fanning out.
+<!-- feature:notification-settings -->
+- Do not rename or regenerate a declared notification setting `id` — including in later sessions that edit an app already declaring settings: keep every existing id unchanged even when its label changes. Ids key each internal user's saved toggles; a changed id silently resets everyone's preferences and 400s any code still sending the old id. Edit the `label` instead.
+- Do not use label-derived slug ids (`"time-entry-logged"`) for notification settings. Generate a random lowercase UUID per setting and use the same literal in the manifest and the code constant.
+- Do not pass `notificationSettingId` on client sends (`recipientClientId`). Settings gate internal users only; clients receive whatever `deliveryTargets` you populated.
+- Do not treat the 202 "suppressed" response from `createNotification` as a failure. The recipient turned that category off — that is the feature working.
+- Do not build a custom notification-preferences page or store per-user notification preferences in the app database. Declare `notificationSettings` and let the platform settings page own the toggles.
+- Do not send a surface the setting doesn't declare — it is silently dropped for internal users. Keep the setting's `surfaces` in sync with what the code sends.
+- Do not declare an `actionLabel` for an internal-review flow. It renders only in the client's Your Actions card, counted from that client's own unread notifications, so an app whose notifications all go to staff must omit it.
+<!-- /feature:notification-settings -->