@assembly-js/app-foundation 0.0.10 → 0.0.12-rc.1

package/bin/validate-manifest.mjs

@@ -310,7 +310,8 @@ const MAX_ACTION_DESC_LENGTH = 40;
 const MAX_PATH_LENGTH = 512;
 
 const RESOURCE_NAME_RE = /^[a-z][a-zA-Z0-9]{1,63}$/;
-const EVENT_NAME_RE = /^[a-zA-Z0-9]+\.[a-zA-Z0-9]+$/;
+const EVENT_NAME_RE = /^(~app-[a-z0-9]+\.)?[a-zA-Z0-9]+\.[a-zA-Z0-9]+$/;
+const APP_EVENT_MARKER_RE = /^~app-[a-z0-9]+\./;
 const API_PATH_RE = /^(\/[a-z0-9\-_]+)+(\/:id)?$/;
 
 const ALLOWED_METHODS = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'];
@@ -530,22 +531,33 @@ function camelCaseAlnum(s) {
   return out;
 }
 
+// Mirrors marketplace_application.PeelAppEventMarker: splits a possibly-namespaced
+// event name into its "~<appId>." marker (empty when absent) and the bare
+// {resourceName}.{verb} remainder.
+function peelAppEventMarker(eventName) {
+  const m = APP_EVENT_MARKER_RE.exec(eventName);
+  const marker = m ? m[0] : '';
+  return { marker, bare: eventName.slice(marker.length) };
+}
+
 // Mirrors normalizeAppApiEventName in app_api_resources.go: the publish gate
 // coerces an authored eventName toward the canonical {resourceName}.{verb}
 // form instead of rejecting it ("intake.review_status_changed" →
 // "intake.reviewStatusChanged"; a bare verb gains the record's resourceName;
-// an empty verb becomes "triggered"). Returns the input unchanged when
-// nothing salvageable remains, so the format error still fires.
+// an empty verb becomes "triggered"). Any leading "~<appId>." marker is peeled
+// off, normalized around, and re-attached verbatim. Returns the input unchanged
+// when nothing salvageable remains, so the format error still fires.
 function normalizeEventName(resourceName, eventName) {
+  const { marker, bare } = peelAppEventMarker(eventName);
   let prefix = resourceName;
-  let verb = eventName;
-  const dot = eventName.indexOf('.');
+  let verb = bare;
+  const dot = bare.indexOf('.');
   if (dot >= 0) {
-    prefix = camelCaseAlnum(eventName.slice(0, dot)) || resourceName;
-    verb = eventName.slice(dot + 1);
+    prefix = camelCaseAlnum(bare.slice(0, dot)) || resourceName;
+    verb = bare.slice(dot + 1);
   }
   verb = camelCaseAlnum(verb) || 'triggered';
-  const normalized = prefix + '.' + verb;
+  const normalized = marker + prefix + '.' + verb;
   return EVENT_NAME_RE.test(normalized) ? normalized : eventName;
 }
 
@@ -1025,16 +1037,21 @@ if (existsSync(API_RESOURCES)) {
             if (!EVENT_NAME_RE.test(eventName)) {
               apiErrors.push(webhookWhere + ': eventName "' + eventName + '" must be {resourceName}.{verb}.');
             } else {
-              const prefix = eventName.slice(0, eventName.indexOf('.'));
+              // A namespaced app event carries a "~<appId>." marker that is opaque
+              // to the resourceName and native-collision checks; validate the bare
+              // {resourceName}.{verb} remainder.
+              const bare = peelAppEventMarker(eventName).bare;
+              const prefix = bare.slice(0, bare.indexOf('.'));
               if (!resourceNames.has(prefix)) {
                 apiErrors.push(webhookWhere + ': eventName "' + eventName + '" must be prefixed by one of the manifest\'s resourceNames.');
               }
-              const lowerEventName = eventName.toLowerCase();
-              if (NATIVE_EVENTS_LOWER.has(lowerEventName)) {
+              const lowerBare = bare.toLowerCase();
+              if (NATIVE_EVENTS_LOWER.has(lowerBare)) {
                 apiErrors.push(webhookWhere + ': eventName "' + eventName + '" is a native platform event name.');
               } else if (NATIVE_NAMESPACES_LOWER.has(prefix.toLowerCase())) {
                 apiErrors.push(webhookWhere + ': eventName "' + eventName + '" uses the native "' + prefix + '" event namespace; pick a distinct resourceName.');
               }
+              const lowerEventName = eventName.toLowerCase();
               if (seenEventNames.has(lowerEventName)) {
                 apiErrors.push(webhookWhere + ': eventName "' + eventName + '" is already declared by ' + seenEventNames.get(lowerEventName) + ' (event names are matched case-insensitively).');
               } else {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@assembly-js/app-foundation",
-  "version": "0.0.10",
+  "version": "0.0.12-rc.1",
   "description": "Versioned foundation helpers and build context for Assembly generated apps",
   "type": "module",
   "files": [

package/skills/assembly-app-bridge-header/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: assembly-app-bridge-header
-description: Use any time the app sets breadcrumbs, primary CTA, secondary CTA, or actions menu in the Assembly header chrome. Always drive the header through the useAssemblyHeader hook — never call AssemblyBridge.header.set* from your own useEffect. Critical — the parent automatically prepends the app's name as breadcrumb 0; never include it yourself, or it renders twice.
+description: Use any time the app sets breadcrumbs, primary/secondary CTA, or actions menu in the header chrome. Always drive it via useAssemblyHeader — never call AssemblyBridge.header.set* from your own useEffect. The parent auto-prepends the app name as breadcrumb 0 — never include it yourself.
 ---
 
 The Assembly header (breadcrumbs, primary/secondary CTA buttons, overflow actions menu) is controlled from your app. **Drive it with the `useAssemblyHeader` hook** — it ships in the foundation at `app/components/use-assembly-header.ts`.
@@ -70,6 +70,20 @@ useAssemblyHeader({ onRootClick: goHome, breadcrumbs: [{ label: 'Reports' }] });
 
 Use breadcrumbs only for hierarchical navigation, not branding. A flat one-page app omits `breadcrumbs` (or passes `[]`). A multi-level app uses one entry per level: `[{ label: 'Reports' }, { label: 'Q4 2026' }]`. A breadcrumb's `onClick` makes it clickable; omit it for the current/leaf level.
 
+## Loading state on a `primaryCta` — no `disabled`/`loading` prop
+
+Header CTAs have no `disabled` or `loading` prop. Indicate progress by changing the `primaryCta` value itself — swap the label and replace `onClick` with a no-op while the action runs, then restore both when it completes:
+
+```tsx
+useAssemblyHeader({
+  primaryCta: isSaving
+    ? { label: 'Saving…', icon: 'Check', onClick: () => {} }
+    : { label: 'Save', icon: 'Check', onClick: save },
+});
+```
+
+Because the hook re-applies whatever value you pass on every render, this is just a state change — no imperative set/clear needed. Don't let the user click a button and see nothing happen.
+
 ## Icon and color constraints
 
 - **`icon` must be a `CtaIcon`** — the only valid values are `'Archive' | 'Plus' | 'Templates' | 'Trash' | 'Check'`. Any other string (e.g. `'Download'`, `'Settings'`, `'Edit'`) is a type error — omit the icon (it's optional) when none fit.

package/skills/assembly-automations/SKILL.md

@@ -1,7 +1,7 @@
 <!-- feature:api-resources -->
 ---
 name: assembly-automations
-description: Use when the request describes a workflow that integrates with the Assembly platform — messaging a client, updating a CRM custom field, sending a contract or form, sharing a file, anything landing on Assembly's own data rather than only the app's tables — and it should happen in reaction to something happening in the app rather than because the user pressed a button. "When a time entry is logged, message the contact" and "completing a project should update the client's status field" both qualify. Both halves are required, and the word "automation" is not — a reaction that only writes the app's own tables is ordinary app code, and so is a platform write the user triggers directly in the app UI. Also use when the request asks the app to fire webhooks, drive or react to another tool, or expose operations others can invoke. Declare those events and operations in .assembly/api-resources.json so they appear as automation triggers and actions, emit each declared event at runtime with assembly.fetch, and serve each exposed operation with automationActionRoute. Covers the manifest schema, the two field shapes, event naming, the recipient-id contract, trigger configuration, dropdown option sources for action inputs, runtime event emission, and the action route contract.
+description: REQUIRED when a request should react to an in-app event AND write to the Assembly platform (message a client, set a CRM field, send a contract/form, share a file) — not just the app's tables. Covers api-resources.json schema, event naming, triggers/actions, webhooks, automationActionRoute.
 ---
 
 An app's API contract — the events it emits and the operations workspace automations can invoke — is declared in **`.assembly/api-resources.json`** at the repo root. The platform reads it at publish and registers the app's triggers and actions. Which file owns what: `.assembly/app.json` = how the platform runs the app (surfaces, secrets, integrations); `.assembly/api-resources.json` = the API contract the app exposes. Never mix their keys.
@@ -63,7 +63,7 @@ The entire file is one top-level key. Unknown keys anywhere are publish errors,
       ],
       "apis": [
         {
-          "name": "Create time entry",
+          "name": "~app-43574726.Create time entry",
           "description": "Log a time entry",
           "method": "POST",
           "path": "/time-entries",
@@ -84,7 +84,7 @@ The entire file is one top-level key. Unknown keys anywhere are publish errors,
       ],
       "webhooks": [
         {
-          "eventName": "timeEntry.created",
+          "eventName": "~app-43574726.timeEntry.created",
           "eventDescription": "Fires when a time entry is logged",
           "trigger": {
             "name": "Time entry logged",
@@ -94,7 +94,7 @@ The entire file is one top-level key. Unknown keys anywhere are publish errors,
           }
         },
         {
-          "eventName": "timeEntry.approved",
+          "eventName": "~app-43574726.timeEntry.approved",
           "eventDescription": "Fires when a time entry is approved",
           "trigger": {
             "name": "Time entry approved",
@@ -223,7 +223,7 @@ const userAgent = req.headers.get('user-agent') ?? '';
 
 after(async () => {
   try {
-    const res = await assembly.fetch('/v1/webhooks/timeEntry.created', {
+    const res = await assembly.fetch('/v1/webhooks/~app-43574726.timeEntry.created', {
       method: 'POST',
       headers: {
         'X-Assembly-Actor-Id': actorId,
@@ -242,7 +242,7 @@ after(async () => {
 });
 ```
 
-- **`assembly.fetch` is how an event is emitted** — it adds the app's auth and the JSON content type for you. The path is `/v1/webhooks/<eventName>` using the exact `eventName` from this file; the platform validates the name and payload against this manifest's registration, then runs matching automations.
+- **`assembly.fetch` is how an event is emitted** — it adds the app's auth and the JSON content type for you. The path is `/v1/webhooks/<eventName>` using the **exact** `eventName` from this file, `~<appId>.` prefix and all (the `~` is URL-safe, so the path needs no encoding); the platform validates the name and payload against this manifest's registration, then runs matching automations.
 - **Check `res.ok`.** `assembly.fetch` resolves on a 4xx instead of throwing, so an unregistered event name or an invalid payload is a silent no-op unless you read the status — the easiest way there is to ship a trigger that never fires.
 - **Emit inside `after()`, and never leave the call un-awaited.** `after()` runs the emit once the response is sent, so it never delays or breaks the user's action — log the failure there and continue. Dropping the `await` to keep the handler fast looks equivalent and is not: a floating promise is frozen when the handler returns, so the event arrives minutes late or never, and which one you get is luck.
 - **Capture the request values in the handler, not inside the callback.** `after()` runs past the response, so read `actorId` / IP / user-agent before it and close over them.
@@ -471,14 +471,15 @@ export const GET = automationActionRoute(async (_input, { workspaceId }) => {
 
 ## Rules the publish gate enforces
 
-- **Event names are `{resourceName}.{verb}`** — `timeEntry.created`, never a bare `created` and never a native platform event name (`task.completed`, `client.created`, …). Unique within the app, case-insensitively. Both segments are single alphanumeric camelCase tokens — no underscores, hyphens, or extra dots: `intake.reviewStatusChanged`, never `intake.review_status_changed`. The publish gate auto-normalizes non-conforming names to camelCase, so the event name your runtime code emits must be the canonical form — write camelCase everywhere.
+- **Namespace every event name and exposed action with your app id.** Prefix each `eventName`, and the `name` of every api you set `exposeToAutomations: true` on, with `~$ASSEMBLY_APP_ID.` — read the id from the `ASSEMBLY_APP_ID` environment variable (`echo $ASSEMBLY_APP_ID`, it looks like `app-43574726`) and write the literal value in. This is what keeps your triggers and actions from colliding with another app installed in the same workspace, and the prefix is stripped before the user ever sees it. Prefix only **new** events/actions — never re-prefix or rename one you already shipped (see the renaming rule below).
+- **Event names are `~<appId>.{resourceName}.{verb}`** — e.g. `~app-43574726.timeEntry.created`. The `{resourceName}.{verb}` remainder is still exactly two single alphanumeric camelCase tokens: no bare `created`, no native platform event name (`task.completed`, `client.created`, …), and no underscores, hyphens, or extra dots inside the remainder — `~app-43574726.intake.reviewStatusChanged`, never `intake.review_status_changed`. The publish gate normalizes only the remainder to camelCase and carries the `~<appId>.` prefix through untouched, so the event name your runtime code emits must be byte-identical to what you declare — write it the same in both places.
 - **One action = one record + method.** `exposeToAutomations: true` requires an `input` with at least one field where `automationSettings.isEnabled` is true. `(method, path)` pairs must be unique across the whole file.
 - **The zero-value rule**: the platform treats a zero value (`0`, `""`, `false`) on a required field as missing. Declare booleans and legitimately-zeroable numbers `optional: true`; a required `bool` field is rejected outright.
 - **`dynamicOptions`** on action fields (`{ "requestUrl": "/projects", "nameField": "name" }`) points a dropdown at a **GET api registered by any record in this manifest** — cross-resource references are normal (a `feedbackItem` input listing categories points at the `category` record's GET api). The `requestUrl` must equal that api's `path`; `/:id` forms don't qualify. The endpoint must return `{ "data": [ { "id": "...", "name": "..." } ] }` — `nameField` may be nested/composite (`name.first|name.last`). The referenced api must live in a record whose `baseUrl` actually serves it and whose `schema[]` the response satisfies — see "Serving dynamic options". Use `dropdownSource` instead when the choice is an Assembly client/company/internal user.
 - Paths are lowercase `[a-z0-9-_]` segments with an optional trailing `/:id`, and must not contain `tasks`, `task-templates`, or `comments` — those route to the platform's Tasks app.
 - **`apis[].description` max 40 characters** (all apis). It becomes the action's label — see above.
 - **`trigger.icon`, when set, must be one of the names in the icon list above.** Unknown names fail the publish; an omitted icon renders a generic default.
-- **Renaming breaks saved automations.** An action's identity derives from the api's `name` and a trigger's from `eventName`; renaming either orphans every automation a workspace built on it. Pick names as if they're permanent.
+- **Renaming breaks saved automations.** An action's identity derives from the api's `name` and a trigger's from `eventName` — including the `~<appId>.` prefix, which is part of that identity. Renaming either, or adding/removing the prefix on one you already shipped, orphans every automation a workspace built on it. Pick names as if they're permanent.
 
 ## Telling the user
 

package/skills/assembly-avatar-sub/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: assembly-avatar-sub
-description: Use whenever a client's name or avatar is rendered in a list, table, card, or detail header — including a table of the app's own records (reports, requests, tasks, invoices) that merely reference a client, not just a client directory. Clients belong to many companies, so a client shown without its company is ambiguous. Covers the AvatarSub company badge and the row-duplication pattern via expandClientsByCompany.
+description: Use whenever a client's name or avatar renders in a list, table, card, or detail header — including tables of app records that reference a client. Clients belong to many companies, so an avatar without its company is ambiguous. Covers AvatarSub + expandClientsByCompany row-duplication.
 ---
 
 `AvatarSub` renders a single nested sub-avatar overlaid at the bottom-right of the parent avatar. It always contains exactly one `Avatar`.

package/skills/assembly-clients-companies/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: assembly-clients-companies
-description: Use when an app stores or scopes data by client or company — record keys, scope filters, company selectors, CRM-tab scoping. Clients belong to MANY companies (client.companyIds[]); a client viewer always carries BOTH a clientId and an active companyId, so scoped tables need both columns and must filter on the intersection; client.companyId (on the client object) is deprecated.
+description: Use when an app stores or scopes data by client or company — record keys, scope filters, company selectors, CRM-tab scoping. Clients belong to MANY companies (companyIds[]); a client viewer carries both clientId and active companyId. client.companyId is deprecated.
 ---
 
 Clients and companies are **many-to-many**: a client belongs to many companies via `client.companyIds: string[]`. In the portal, a client can switch between their companies — the viewer's `companyId` always reflects whichever company they currently have active. Apps that ignore this model show incomplete company pickers, or key and filter records on one dimension and then leak a company-A record into the same client's company-B view. This skill covers how to scope, key, and filter records correctly.

package/skills/assembly-custom-fields/SKILL.md

@@ -69,6 +69,10 @@ await assembly.updateClient({
 
 Send the structured object — a bare string is accepted for backwards compatibility with older data, but it collapses to a single `fullAddress` string and loses city/region/postal code/country as separate values. Every property is optional except that the field is only considered set if `country` or `fullAddress` is non-empty; `fullAddress` is derived automatically from the other components if you omit it.
 
+## Every other field type
+
+Non-option, non-address fields take a direct string value — stringify numbers and booleans yourself: `{ mrr: '5000' }`, not `{ mrr: 5000 }`.
+
 ## Symptoms when it goes wrong
 
 | Mistake | What you'll see |

package/skills/assembly-integrations/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: assembly-integrations
-description: Use BEFORE declaring requiredIntegrations in .assembly/app.json and before writing any call through getIntegration() from @assembly-js/app-foundation/server (Slack and other OAuth providers — supported list inside). Covers manifest declaration, the broker client, per-provider gotchas (pagination, IDs vs names, membership/join), and ConnectorError handling.
+description: Use BEFORE declaring requiredIntegrations in .assembly/app.json or calling getIntegration() from @assembly-js/app-foundation/server (Slack + other providers). Covers manifest declaration, the broker client, per-provider gotchas (pagination, IDs vs names, membership), ConnectorError handling.
 ---
 
 ## How it works

package/skills/assembly-internal-users/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: assembly-internal-users
-description: Use when the app needs to read or list internal users, or when an internal viewer browses clients/companies in the Dashboard — staff (admins, agents, accountants, lawyers) running the Assembly workspace. Covers Client Access permissions (isClientAccessLimited, companyAccessList) and scoping internal views to the viewer's allowed companies. Internal users sign in to the Dashboard, never to the Client Portal. Detect via tokenPayload.internalUserId.
+description: Use when the app reads/lists internal users, or an internal viewer browses clients/companies in the Dashboard. Covers Client Access (isClientAccessLimited, companyAccessList) scoping. Internal users sign into the Dashboard only. Detect via tokenPayload.internalUserId.
 ---
 
 Internal users are the **business team** running the Assembly workspace. They sign into the Dashboard at the workspace's domain, never the branded Client Portal. They have full read/write power over clients, companies, files, etc. — **within their Client Access scope** (see below).

package/skills/assembly-native-resources/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: assembly-native-resources
-description: Use any time the app references a native Assembly message channel, form, or portal file/file channel. One non-negotiable rule — never hardcode a native resource ID; discover it at runtime. These IDs are workspace-scoped, so a hardcoded one is only valid in the workspace it came from and breaks the moment the app runs anywhere else. (Not react-hook-form validation — that's assembly-forms. Not app-private uploads — that's assembly-storage. This IS the skill for the native Messages, Forms and Files modules.)
+description: Use any time the app references a native Assembly message channel, form, or portal file/file-channel. Never hardcode the ID — discover it at runtime; IDs are workspace-scoped. Not assembly-forms (validation) or assembly-storage (app-private uploads).
 ---
 
 ## The non-negotiable

package/skills/assembly-notifications/SKILL.md

@@ -1,10 +1,10 @@
 ---
 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.
+description: Use when the app must notify internal users or clients about something that happened — in-product, email, or both. Covers createNotification, the Notification Center /n surface, and clearing the client badge (see clearing-client-notifications).
 # <!-- /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.
+description: Use when the app must notify internal users or clients, or needs per-user notification preferences (Product/Email toggles). Covers createNotification, the /n surface, notificationSettings + notificationSettingId, and clearing the client badge (see clearing-client-notifications).
 # <!-- /feature:notification-settings -->
 ---
 

package/skills/assembly-platform-mcp/SKILL.md

@@ -1,7 +1,7 @@
 <!-- feature:platform-mcp -->
 ---
 name: assembly-platform-mcp
-description: Use when the app you are building depends on workspace configuration that does not exist yet — most commonly a custom field on clients or companies (the user asked for "call clients at their phone number" and no Phone-type client field exists). You have a scoped platform MCP server (tool prefix mcp__platform__) for provisioning that configuration at build time instead of shipping an app that gates on missing workspace setup. Workspace configuration only — never client-facing data (no creating clients, sending messages, notifications, or invoices).
+description: Use when the app depends on missing workspace config — e.g. no Phone-type client custom field exists yet. Provision it at build time via the scoped platform MCP server (mcp__platform__). Workspace config only — never client-facing data (no clients, messages, notifications, invoices).
 ---
 
 ## Provisioning custom fields at build time

package/skills/assembly-route-errors/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: assembly-route-errors
-description: Use in every app/api/**/route.ts handler. Return user-friendly { error } JSON with the right status; never return err.message from catch blocks — Postgres and driver strings leak to the UI. Import handleRouteError, badRequest, notFound, and internalError from @assembly-js/app-foundation/server. Validate values before they hit typed DB columns (e.g. parseUuid before a uuid-column lookup).
+description: REQUIRED in every app/api/**/route.ts handler. Return { error } JSON with the right status; never return err.message — Postgres/driver strings leak. Use handleRouteError/badRequest/notFound/internalError from @assembly-js/app-foundation/server. Validate before hitting DB columns (e.g. parseUuid).
 ---
 
 Route handlers must return safe, user-facing error messages. A `catch` that does `NextResponse.json({ error: err.message }, { status: 500 })` leaks raw Postgres errors (`invalid input syntax for type uuid: "…"`) and other driver internals to the client.

package/skills/assembly-session-token/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: assembly-session-token
-description: Use any time an app reads identity, fetches data, or wonders about auth/token handling. Covers the bearer lifecycle (session token exchanged once by the middleware → bearer cookie → getAssembly() → silent re-exchange on expiry), getSessionIdentity/useAssembly for identity, useServerAction/callAction for SDK-method data fetching, and authFetch for route handlers. Cross-references assembly-route-auth for requireAuth/requireCompanyScope.
+description: Use any time the app reads identity, fetches data, or touches auth/token handling. Covers the bearer lifecycle (session token, bearer cookie, getAssembly(), silent re-exchange), getSessionIdentity/useAssembly, useServerAction, authFetch. See assembly-route-auth for requireAuth/requireCompanyScope.
 ---
 
 Auth is **cookie-borne and automatic** — you never handle the session token and you never pass a token to anything. On the first load only, the parent opens your app at `…/?token=<session-token>`. The foundation middleware (`proxy.ts`) exchanges that session token exactly once (server-side, via `POST /v1/session`) for a short-lived **user-scoped bearer** and stores it in an HttpOnly, `SameSite=None` cookie. That mint is the only time the session token is ever used. Every server call your app makes reads the bearer from that cookie — `getAssembly()` returns an authenticated client with no token argument. The bearer lasts 60 minutes; when it expires, `authFetch` and `useServerAction` silently re-exchange (mint a fresh bearer from the parent's current session token via `/api/assembly-reexchange`) and retry — no reload, no code from you.
@@ -130,17 +130,18 @@ Everything above is **request-scoped**: a user is in the loop and `getAssembly()
 
 ```ts
 // app/api/cron/sync/route.ts — no viewer, no cookie
-import { getOfflineAssembly } from '@assembly-js/app-foundation/server';
+import { getOfflineAssembly, listAll } from '@assembly-js/app-foundation/server';
 
 export async function GET() {
   const assembly = await getOfflineAssembly();
-  const { data: clients = [] } = await assembly.listClients();
+  // Background work must cover everyone — walk every page, not just the first.
+  const clients = await listAll((nextToken) => assembly.listClients({ nextToken, limit: 100 }));
   // …background work…
   return Response.json({ ok: true });
 }
 ```
 
-It **throws** (not returns null) if `ASSEMBLY_API_KEY` is missing or the mint fails — there's no client to re-exchange in the background, so let it propagate. `getSessionIdentity()` returns `null` on this path (the bearer is the app, not a person). Only reach for this outside a request; ignore it for normal UI work.
+It **throws** (not returns null) if `ASSEMBLY_API_KEY` is missing or the mint fails — there's no client to re-exchange in the background, so let it propagate. `getSessionIdentity()` returns `null` on this path (the bearer is the app, not a person). Only reach for this outside a request — using it inside a user request bypasses that viewer's own scope; ignore it for normal UI work.
 
 ## What NOT to do
 

package/skills/assembly-storage/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: assembly-storage
-description: Stores and serves app-private files (attachments, exports, uploads only the app reads) via pre-signed S3 URLs. The client PUTs bytes directly to S3 — never proxy them through an API route. Use when an app uploads or downloads its own files; NOT for files the user wants in the portal Files tab (use the Files module / createFile for those).
+description: Use when an app uploads/downloads its own private files (attachments, exports) via pre-signed S3 URLs — the client PUTs bytes directly to S3, never proxied through an API route. NOT for files the user wants in the portal Files tab (use the Files module / createFile).
 ---
 
 ## How it works

package/skills/clearing-client-notifications/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: clearing-client-notifications
-description: REQUIRED whenever the app calls createNotification with recipientClientId. Use when building any client-facing view that shows content a client was notified about, or any client action that completes something a notification prompted — so the portal sidebar badge clears. Covers the two clearing patterns (clear-on-view vs clear-on-action) with the foundation's clearClientNotifications helper.
+description: REQUIRED whenever createNotification is called with recipientClientId. Use when building a client-facing view showing notified content, or a client action completing what a notification prompted — so the sidebar badge clears. Covers clear-on-view vs clear-on-action via clearClientNotifications.
 ---
 
 ## Why this exists