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

package/dist/client-access.d.ts

@@ -0,0 +1,10 @@
+import type { AssemblyAPI } from '@assembly-js/node-sdk';
+export interface ClientAccessScope {
+    isLimited: boolean;
+    allowedCompanyIds: Set<string>;
+}
+export declare function getClientAccessScope(internalUserId: string, tokenOrAssembly?: string | AssemblyAPI): Promise<ClientAccessScope>;
+export declare function canAccessCompanies(scope: ClientAccessScope, companyIds: string[] | null | undefined): boolean;
+export declare function canAccessClient<T extends {
+    companyIds?: string[];
+}>(scope: ClientAccessScope, client: T): boolean;

package/dist/client-access.js

@@ -0,0 +1,62 @@
+import { getAssembly } from './assembly.js';
+const UNRESTRICTED = {
+    isLimited: false,
+    allowedCompanyIds: new Set(),
+};
+// Denies everything: a limited scope with an empty allow-list. Used when the
+// viewer's access can't be resolved.
+const DENY_ALL = {
+    isLimited: true,
+    allowedCompanyIds: new Set(),
+};
+// Resolves the Client Access scope for an internal user.
+//
+// Fails closed: if the lookup fails we return DENY_ALL rather than treating the
+// viewer as unrestricted. An unverified viewer must not be handed the access of
+// a full-access one — the caller sees empty lists (or a 404 via
+// canAccessCompanies) instead of another workspace member's data. Callers that
+// prefer to surface a transient failure should catch it upstream and retry.
+//
+// The session token carries only `internalUserId`, never the access fields, so
+// this costs one `retrieveInternalUser` per request that needs it.
+export async function getClientAccessScope(internalUserId, tokenOrAssembly) {
+    try {
+        // Same narrowing as requireCompanyScope: a session token string on the
+        // legacy path, an already-authenticated instance on the bearer path.
+        const assembly = typeof tokenOrAssembly === 'string' || tokenOrAssembly === undefined
+            ? await getAssembly(tokenOrAssembly)
+            : tokenOrAssembly;
+        const user = await assembly.retrieveInternalUser({ id: internalUserId });
+        if (user.isClientAccessLimited !== true)
+            return UNRESTRICTED;
+        return {
+            isLimited: true,
+            allowedCompanyIds: new Set(user.companyAccessList ?? []),
+        };
+    }
+    catch {
+        return DENY_ALL;
+    }
+}
+// True when the viewer may see a resource belonging to any of `companyIds`.
+//
+// Mirrors the platform's own users.User.IsAccessAllowed: access is company-scoped,
+// so a limited viewer passes iff at least one of the resource's companies is on
+// their allow-list. Every client belongs to at least one company (real or
+// placeholder), which is what makes the company check sufficient for clients too.
+//
+// A resource with no companies is denied to a limited viewer: there is nothing to
+// match against the allow-list, and guessing would leak.
+export function canAccessCompanies(scope, companyIds) {
+    if (!scope.isLimited)
+        return true;
+    if (!companyIds || companyIds.length === 0)
+        return false;
+    return companyIds.some((id) => scope.allowedCompanyIds.has(id));
+}
+// Convenience for the common case of filtering client records. Generic over the
+// caller's row type because apps filter reshaped client objects (joined, picked,
+// extended) rather than raw SDK records; the constraint names the only field read.
+export function canAccessClient(scope, client) {
+    return canAccessCompanies(scope, client.companyIds);
+}

package/dist/client.d.ts

@@ -1,5 +1,6 @@
 export * from './session-exchange.js';
 export * from './network-capture.js';
 export * from './client-companies.js';
+export * from './pagination.js';
 export * from './theme.js';
 export * from './resource-resolution.js';

package/dist/client.js

@@ -8,6 +8,7 @@
 export * from './session-exchange.js';
 export * from './network-capture.js';
 export * from './client-companies.js';
+export * from './pagination.js';
 export * from './theme.js';
 // Pure data-shaping over resolver responses — no imports, no secrets, no
 // next/headers. It lives here rather than in ./server because <ResourcePicker>

package/dist/pagination.d.ts

@@ -0,0 +1,4 @@
+export declare function listAll<T>(fetchPage: (nextToken?: string) => Promise<{
+    data?: T[] | null;
+    nextToken?: string;
+}>): Promise<T[]>;

package/dist/pagination.js

@@ -0,0 +1,40 @@
+/**
+ * Collects every page of a cursor-paginated SDK list call.
+ *
+ * Every `list*` method returns the same envelope — `{ data, nextToken }` — so one
+ * generic walker covers all of them; the alternative is each app hand-rolling the
+ * same do/while, which is how a first-page-only list ships looking correct.
+ *
+ * `data` is nullable in the SDK's own types, so a null page contributes nothing
+ * rather than throwing on spread. `limit` is the caller's to pass: the documented
+ * range is 1–100 and enforcement varies by endpoint (some reject higher values),
+ * so 100 is the one value that is both safe everywhere and 5x cheaper per walk
+ * than the ~20 default.
+ *
+ * @example
+ *   const companies = await listAll((nextToken) =>
+ *     assembly.listCompanies({ isPlaceholder: false, nextToken, limit: 100 }),
+ *   );
+ */
+// A cursor that never goes absent — an API bug, or a caller ignoring the
+// nextToken argument — would otherwise spin forever. 1000 pages at limit: 100
+// is 100k records, far past any real workspace, so tripping this means the
+// walk is broken. Throwing is deliberate: returning what was collected so far
+// would silently truncate the list, which is the bug this helper exists to
+// prevent.
+const MAX_PAGES = 1000;
+export async function listAll(fetchPage) {
+    const all = [];
+    let cursor;
+    let pages = 0;
+    do {
+        if (++pages > MAX_PAGES) {
+            throw new Error(`listAll walked more than ${MAX_PAGES} pages without the cursor ending — is the nextToken being passed through?`);
+        }
+        const page = await fetchPage(cursor);
+        if (page.data)
+            all.push(...page.data);
+        cursor = page.nextToken || undefined;
+    } while (cursor);
+    return all;
+}

package/dist/server.d.ts

@@ -1,6 +1,7 @@
 import 'server-only';
 export * from './assembly.js';
 export * from './auth.js';
+export * from './client-access.js';
 export * from './mint-bearer.js';
 export * from './nango.js';
 export * from './app-storage.js';

package/dist/server.js

@@ -5,6 +5,7 @@
 import 'server-only';
 export * from './assembly.js';
 export * from './auth.js';
+export * from './client-access.js';
 export * from './mint-bearer.js';
 export * from './nango.js';
 export * from './app-storage.js';

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@assembly-js/app-foundation",
-  "version": "0.0.2-rc.3",
+  "version": "0.0.4",
   "description": "Versioned foundation helpers and build context for Assembly generated apps",
   "type": "module",
   "files": [
     "dist",
+    "bin",
     "skills",
     "CLAUDE.md",
     "render-context.mjs"
@@ -22,8 +23,9 @@
   "scripts": {
     "build": "tsc && tsc-alias",
     "test": "bun test",
-    "prepublishOnly": "npm run build && npm run verify:dist",
-    "verify:dist": "node scripts/verify-dist-resolves.mjs"
+    "prepublishOnly": "npm run build && npm run verify:dist && npm run verify:bin",
+    "verify:dist": "node scripts/verify-dist-resolves.mjs",
+    "verify:bin": "node scripts/verify-bin.mjs"
   },
   "peerDependencies": {
     "@assembly-js/node-sdk": ">=4.2.3-beta.2",

package/skills/assembly-ai/SKILL.md

@@ -16,7 +16,7 @@ The proxy mirrors OpenAI's API shape. Call any OpenAI endpoint path via:
 Create a helper in `lib/ai.ts` that uses the existing Assembly SDK instance:
 
 ```typescript
-import { getAssembly } from './assembly';
+import { getAssembly } from '@assembly-js/app-foundation/server';
 
 export async function chatCompletion(messages: Array<{ role: string; content: string }>, options?: { model?: string; stream?: boolean }) {
   const assembly = await getAssembly();

package/skills/assembly-automations/SKILL.md

@@ -1,7 +1,7 @@
 <!-- feature:api-resources -->
 ---
 name: assembly-automations
-description: Use when the request asks the app to automate something, 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.sendWebhook, and serve each exposed operation with automationActionRoute. Not for an app that merely happens to have automatable mutations; if nobody asked, the file should not exist. 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: 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.sendWebhook, 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.
 ---
 
 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.
@@ -10,14 +10,38 @@ Declaring a webhook only registers the trigger — the running app must also **e
 
 ## When to declare it
 
-**Only when the request asked for it.** Nearly every app that writes anything has mutations that *could* be automated, so an automatable domain is not the test — someone has to have asked. What counts as asking: automate something, fire webhooks, notify or update another tool, react to something happening elsewhere, or expose operations other tools or staff workflows can invoke.
+Two things have to be true at once. Neither one alone is the test, and the word "automation" is not the test either:
+
+1. **The request is reactive** — something should happen *because* an in-app event happened, not because the user pressed a button and is watching.
+2. **The effect lands on the Assembly platform** — a message, a client or company custom field, a contract, a form, a file. Not the app's own tables.
+
+Both hold, so both of these qualify:
+
+- "when i log a time entry, send a message to the relevant contact"
+- "completing a project should message the client and update their status field"
+
+**Only the first holds here, so declare nothing:** "when a task is marked done, move it to the archive column and recalculate the totals." It is reactive and it is shaped like a workflow, but every effect is in the app's own database. That is ordinary app code — write it at the mutation site.
+
+**Only the second holds here, so declare nothing:** a "Message client" button in the app. The effect is a platform write, but the user pressed it and is watching it happen. Call the SDK and be done.
+
+Also use this skill when the request asks the app to fire webhooks, drive or react to another tool, or expose operations other tools or staff workflows can invoke.
 
 Given that, declare whichever of these the request implies:
 
-- **Domain events**: state changes other tools should react to ("time entry logged", "request approved"). Each becomes an automation trigger and a workspace webhook event.
+- **Domain events**: state changes something should react to ("time entry logged", "request approved"). Each becomes an automation trigger and a workspace webhook event.
 - **Staff-invokable operations**: writes an automation should be able to perform ("create a time entry", "assign a task"). Each becomes an automation action.
 
-**If nobody asked, the file must not exist** — its absence means "this app registers no API", which is the right answer for a dashboard, a viewer, a report, and for any ordinary app whose owner never mentioned automation. Declaring anyway is not free: every exposed operation shows up as an action in front of every workspace admin in the automation builder, and every declared event has to be emitted at runtime or automations built on it silently never run.
+**Absent both conditions, the file must not exist** — its absence means "this app registers no API", which is the right answer for a dashboard, a viewer, a report, and any app nobody asked to react to anything. Declaring anyway is not free: every exposed operation shows up as an action in front of every workspace admin in the automation builder, and every declared event has to be emitted at runtime or automations built on it silently never run.
+
+### Let the automation perform the "then"
+
+The automation builder offers native actions over Assembly's own modules — messaging, client and company custom fields, contracts, forms, files — alongside any actions apps in the workspace have declared. Treat that set as growing, not fixed: don't assume an effect is impossible because you can't name the action.
+
+**When the "then" is one of Assembly's own module effects, declare and emit the trigger and do not hand-roll the SDK call at the mutation site.** The platform owns retry, run history, and the workspace's ability to change the behaviour later without a rebuild; a hard-coded call has none of that, and a user who then builds the automation gets the effect twice. Most workflows in this bucket need **no `apis[]` at all** — the trigger is the app's whole job. Declare an api only when something should be able to invoke *the app*.
+
+**When the "then" is a notification, the app sends it.** `createNotification` is not an automation action. Call it directly and see the `assembly-notifications` skill; that skill owns notifications end to end, and there is nothing to defer here.
+
+**When you can't tell whether an action exists for the "then" — creating a task is the common case — ask before you build.** Neither answer is yours to pick: declaring a trigger nobody can attach an action to leaves the user staring at an empty automation builder, and hard-coding it silently forecloses the automation they asked for. They can see the current action list and you can't, so put the fork to them in one question, in their terms — whether the app should do this itself now, or you declare the trigger for them to wire up in Automations. Ask *that*; do not spend the question on a field name you can discover at runtime or on message copy you can draft.
 
 ## File format
 
@@ -355,7 +379,7 @@ Each action route is then just the handler, served at the record's `baseUrl`:
 
 ```ts
 // app/api/assembly/time-entries/route.ts — the record's baseUrl
-import { automationActionRoute, ActionError } from '@assembly-js/app-foundation/server-actions';
+import { automationActionRoute, ActionError } from '@/lib/assembly-actions';
 import { db } from '@/lib/db';
 import { timeEntries } from '@/lib/schema';
 
@@ -423,7 +447,7 @@ Serve the route with the same wrapper as actions — its token check is what aut
 
 ```ts
 // app/api/assembly/projects/route.ts — the options record's baseUrl
-import { automationActionRoute } from '@assembly-js/app-foundation/server-actions';
+import { automationActionRoute } from '@/lib/assembly-actions';
 import { db } from '@/lib/db';
 import { projects } from '@/lib/schema';
 import { eq } from 'drizzle-orm';
@@ -448,6 +472,12 @@ export const GET = automationActionRoute(async (_input, { workspaceId }) => {
 - **`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.
 
+## Telling the user
+
+**Call it an automation, not a webhook.** In the product this feature is Automations; "webhook" is the wire format underneath it. `sendWebhook` and the `webhooks` manifest key keep their names in code — this is about what you say in chat. "I added a *Time entry logged* trigger you can build automations on" lands; "I set up a webhook" reads as plumbing nobody asked for.
+
+**Say what is left for them to do.** Declaring a trigger does not create the automation — the workspace still has to build it. When you finish, name the trigger you registered, name **each** automation they need to build, and point them at the **Automations** module (`/automations` in the dashboard). Count the actions the request asked for, not the triggers: "completing a project should message the client and update their status field" is one trigger and two actions, so say both. Skip this and the app looks like it ignored the request: the trigger exists, nothing is wired to it, and nothing happens.
+
 ## Validation
 
 **Run `bun run validate:manifest` after every edit to this file, and never finish the task on a failing run.** It applies the same rules as the publish gate and names the exact field and problem; skip it and the first signal is a failed publish the user has to bring back to you. `bun run build` runs it first for the same reason.

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

@@ -1,6 +1,6 @@
 ---
 name: assembly-avatar-sub
-description: Use when building a list or table that shows clients alongside their companies and a client can belong to multiple companies. Covers the row-duplication + AvatarSub pattern for disambiguating which company a row represents.
+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.
 ---
 
 `AvatarSub` renders a single nested sub-avatar overlaid at the bottom-right of the parent avatar. It always contains exactly one `Avatar`.
@@ -17,20 +17,33 @@ export PATH="$HOME/.bun/bin:$PATH" && bunx shadcn@latest add @assembly-ui/avatar
 
 ## When to use
 
-A client belongs to 2+ companies and the list needs to show which company each row represents. The pattern is **row duplication** — show the client once per company, each row with a single `AvatarSub` for that company.
+Anywhere a client's name or avatar appears, the company it belongs to is part of its identity — a client can belong to many companies, so a bare name is ambiguous. Two different situations, and picking the wrong one is the usual mistake:
+
+**Case A — a list OF clients** (a client directory, a picker, a "who has access" table). One client can legitimately occupy several rows, so use **row duplication**: one row per company, each with a single `AvatarSub`.
 
 - **0 or 1 company → no sub-avatar.** No disambiguation needed.
 - **2+ companies → one row per company**, each with a single `AvatarSub`.
 
+**Case B — a list of the app's own records that reference a client** (reports, requests, tasks, invoices, documents — the far more common table). **Do NOT duplicate rows**: a record belongs to exactly one client-and-company pair, so duplicating it would invent records that don't exist. Instead render a single `AvatarSub` for the company the record is scoped to, read from the record's own `companyId`:
+
+```tsx
+const company = row.companyId ? companiesMap.get(row.companyId) : undefined;
+// …render the client avatar with a single AvatarSub for `company`
+```
+
+If a record's rows are scoped to a company in some cases and to a client in others, badge the client-scoped ones with their `companyId` and leave a company-scoped row's own avatar unbadged — it is already unambiguous.
+
+Skipping the badge in Case B is the most common miss: the table looks fine until two clients share a name, or the same client appears under two companies, and staff cannot tell the rows apart.
+
 ## Anti-patterns — never do any of these
 
 - Do NOT render multiple `AvatarSub` elements on the same avatar.
 - Do NOT use `AvatarGroup` of small company avatars next to or on top of a client avatar.
 - Do NOT show all of a client's companies on a single row with stacked badges.
 
-The sub-avatar disambiguates *which* company a row represents, not *how many* companies a client has. The only correct multi-company pattern is row duplication.
+The sub-avatar disambiguates *which* company a row represents, not *how many* companies a client has. In Case A, row duplication is the only correct way to show a multi-company client; in Case B the record already names its company, so one badge per row is correct and duplication is wrong.
 
-## Row-duplication pattern
+## Row-duplication pattern (Case A)
 
 Use `expandClientsByCompany` — do NOT hand-roll the expansion. It returns one row per company for multi-company clients (each with its own `displayCompanyId`) and a single `displayCompanyId: null` row for clients with 0 or 1 companies.
 

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

@@ -10,13 +10,17 @@ A client belongs to one or more companies (see `assembly-companies` skill — th
 ## Identify the current viewer
 
 ```ts
-const payload = await assembly.getTokenPayload();
-if (payload.clientId) {
-  const me = await assembly.retrieveClient({ id: payload.clientId });
+import { getSessionIdentity } from '@assembly-js/app-foundation/server';
+
+const identity = await getSessionIdentity();
+if (identity?.clientId) {
+  const me = await assembly.retrieveClient({ id: identity.clientId });
   // ...
 }
 ```
 
+Never call `assembly.getTokenPayload()` for this — see `assembly-session-token`.
+
 (`internalUserId` is set instead for staff — see `assembly-internal-users` skill.)
 
 ## SDK methods

package/skills/assembly-companies/SKILL.md

@@ -8,6 +8,35 @@ Companies group `Client` users. The relationship is **many-to-many**:
 - A company can have an unlimited number of clients (no enforced cap).
 - A client can belong to many companies — typically up to ~50 in practice.
 
+## Companies are a first-class entity
+
+A company exists independently of its clients. **A company with zero clients is a real company and must appear in any list of companies** — workspaces routinely create a company before inviting anyone into it, and that company is not a draft or a stub.
+
+So always fetch companies directly, and **page all the way through** — `listCompanies` is cursor-paginated, so treating the first response as the whole set drops companies for exactly the same reason deriving from clients does. `@assembly-js/app-foundation/client` exports `listAll` for that walk — import it, don't rewrite it. Pass `isPlaceholder: false` explicitly: it's the app-builder default, but stating it keeps the intent readable and survives the app being pointed at a non-app-builder token.
+
+```ts
+import { listAll } from '@assembly-js/app-foundation/client';
+
+const companies = await listAll((nextToken) =>
+  assembly.listCompanies({ isPlaceholder: false, nextToken, limit: 100 }),
+);
+```
+
+`listAll` works for any `list*` method — they all return the same `{ data, nextToken }` envelope — so use it wherever a complete list matters rather than hand-rolling a `do/while` per call site.
+
+**Never derive the company set from clients.** Mapping `client.companyIds` through `retrieveCompany` and treating the result as "the companies" silently drops every company nobody is assigned to yet, which users report as "my company disappeared." Fetch clients and companies as two independent paginated calls — in parallel — and don't intersect one against the other:
+
+```ts
+import { listAll } from '@assembly-js/app-foundation/client';
+
+const [clients, companies] = await Promise.all([
+  listAll((nextToken) => assembly.listClients({ nextToken, limit: 100 })),
+  listAll((nextToken) => assembly.listCompanies({ isPlaceholder: false, nextToken, limit: 100 })),
+]);
+```
+
+Fetching a *specific* client's companies via `client.companyIds` is still correct when the UI is scoped to that one client (e.g. a company switcher for the signed-in client) — see `assembly-clients-companies` skill. That is a different question from "what companies exist."
+
 ## Use `companyIds`, not `companyId`
 
 The canonical relationship is the `companyIds: string[]` array on a Client. The singular `companyId` field is **deprecated since SDK v3.15.0** and exists only for backward compat. Always prefer the array:
@@ -21,7 +50,7 @@ Including the deprecated `companyId` in `updateClient` will trigger a re-assignm
 ## SDK methods
 
 - `createCompany({ requestBody })`
-- `listCompanies({ name, isPlaceholder, nextToken, limit })`
+- `listCompanies({ name, isPlaceholder, nextToken, limit })` — cursor-paginated; walk it with `listAll` for a complete list
 - `retrieveCompany({ id })`
 - `updateCompany({ id, requestBody })` — see `assembly-mutations` skill
 - `deleteCompany({ id })`
@@ -32,6 +61,17 @@ Some `Company` records have `isPlaceholder: true`. They exist so the platform ca
 
 **For app-builder apps the platform API excludes placeholders from `listCompanies` by default**, so you don't need to filter them yourself — a plain `listCompanies()` already returns only real companies. (Outside the app builder, the public API still returns all companies unless you pass `isPlaceholder: false`.)
 
+### Placeholder is the only company filter — never filter by client count
+
+These two are opposites and are easy to conflate:
+
+| | Show it? |
+|---|---|
+| Real, named company with **zero clients** | **Yes** — it's a real company (see "Companies are a first-class entity") |
+| **Placeholder** company (stand-in for a client with no employer) | No — `isPlaceholder: false` already excludes it |
+
+A placeholder is not "an empty company." It's the reverse: it exists *because* a client needed a company-shaped reference. So `isPlaceholder: false` is the right and only filter — do not additionally drop companies for having no clients, no members, or no associated records.
+
 ### When to include placeholders
 
 Pass `isPlaceholder: true` explicitly to fetch placeholders (this returns *only* placeholders, so merge with the default list if you need both). Useful for:

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

@@ -8,10 +8,14 @@ Internal users are the **business team** running the Assembly workspace. They si
 ## Identify the current viewer
 
 ```ts
-const { internalUserId, clientId } = await assembly.getTokenPayload();
-const isInternal = !!internalUserId;
+import { getSessionIdentity } from '@assembly-js/app-foundation/server';
+
+const identity = await getSessionIdentity();
+const isInternal = !!identity?.internalUserId;
 ```
 
+Never call `assembly.getTokenPayload()` for this — see `assembly-session-token`.
+
 If `internalUserId` is set, the current viewer is staff. (`clientId` is set for client viewers — see `assembly-client-users` skill.)
 
 ## SDK methods
@@ -30,30 +34,36 @@ On `retrieveInternalUser` / `listInternalUsers`, each internal user may carry:
 
 Access is **company-scoped**: a limited user can see a client iff **any** of the client's `companyIds` is in their `companyAccessList`. Every client belongs to at least one company (real or placeholder), so the company check covers all clients. This matches `users.User.IsAccessAllowed` in the backend.
 
-The session token carries only `internalUserId` — not the access fields. Load the viewer's scope once per request when you need it:
+## Pre-built helpers
+
+`@assembly-js/app-foundation/server` exports these — import them, do not rewrite the check.
 
 ```ts
+import {
+  getSessionIdentity,
+  getClientAccessScope,
+  canAccessCompanies,
+  canAccessClient,
+} from '@assembly-js/app-foundation/server';
+
 const identity = await getSessionIdentity();
 if (!identity?.internalUserId) return; // not an internal viewer
 
-const viewer = await assembly.retrieveInternalUser({ id: identity.internalUserId });
-const isLimited = viewer.isClientAccessLimited === true;
-const accessList = viewer.companyAccessList ?? [];
-
-function canAccessCompany(companyId: string): boolean {
-  if (!isLimited) return true;
-  return accessList.includes(companyId);
-}
+// The session token carries only internalUserId, never the access fields, so
+// resolve the scope once per request and reuse it.
+const scope = await getClientAccessScope(identity.internalUserId);
 
-function canAccessClient(client: { companyIds?: string[] }): boolean {
-  if (!isLimited) return true;
-  return (client.companyIds ?? []).some((id) => accessList.includes(id));
-}
+canAccessClient(scope, client);          // a client row (reads client.companyIds)
+canAccessCompanies(scope, [company.id]); // any company-scoped resource
 ```
 
+`getClientAccessScope` **fails closed**: if the viewer's access can't be resolved it denies
+everything rather than falling back to full access. Do not catch and widen that to
+"unrestricted" — an unverified viewer must never receive a full-access user's visibility.
+
 ### What to scope
 
-- **SDK lists and pickers** — `listClients`, `listCompanies`, and any UI built from them (tables, `UserCompanySelector` options) must only include clients/companies the viewer can access. Filter each page after fetch, or skip rows that fail `canAccessClient` / `canAccessCompany`. Do not assume the platform API filtered the list for you.
+- **SDK lists and pickers** — `listClients`, `listCompanies`, and any UI built from them (tables, `UserCompanySelector` options) must only include clients/companies the viewer can access. Filter each page after fetch, or skip rows that fail `canAccessClient` / `canAccessCompanies`. Do not assume the platform API filtered the list for you.
 - **App-owned data** — queries against your Postgres tables must apply the same rule: when the viewer is limited, restrict rows to `companyId IN companyAccessList` (and for client-owned rows, ensure the client is accessible). `requireCompanyScope` lets every internal user through — it enforces client-vs-staff isolation, not Client Access. See `assembly-route-auth` and `assembly-clients-companies`.
 - **CRM-tab context** — when the token already carries a `clientId` or `companyId`, the viewer was routed to a record they can access; scope to that tab as usual. The global Dashboard main view still needs the filters above.
 - **Fan-out to other internal users** (notifications, assignments) — filter recipients by their access to the relevant client/company.

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

@@ -11,10 +11,12 @@ Discover instead. The pattern is always the same two steps: **list, then match o
 
 ## Discovering a form
 
-A form's display name is on `fields`, not on the form itself:
+A form's display name is on `fields`, not on the form itself. Walk every page — matching by name against only the first page reports the form as missing once the workspace has more than a page of forms:
 
 ```ts
-const { data: forms = [] } = await assembly.listForms({});
+import { listAll } from '@assembly-js/app-foundation/client';
+
+const forms = await listAll((nextToken) => assembly.listForms({ nextToken, limit: 100 }));
 const intakeForm = forms.find(
   (f) => f.fields?.name?.toLowerCase().includes('intake'), // match the user's wording
 );

package/skills/assembly-notifications/SKILL.md

@@ -171,16 +171,14 @@ await assembly.createNotification({
 
 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:
+**`listInternalUsers` / `listClients` are paginated** — one call returns only the first page. To notify *everyone*, collect all recipients before fanning out, or you'll silently skip later-page recipients. `listAll` from `@assembly-js/app-foundation/client` does the walk — import it, don't rewrite it:
 
 ```ts
-const recipients = [];
-let nextToken: string | undefined;
-do {
-  const res = await assembly.listInternalUsers({ nextToken });
-  recipients.push(...(res.data ?? []));
-  nextToken = res.nextToken ?? undefined;
-} while (nextToken);
+import { listAll } from '@assembly-js/app-foundation/client';
+
+const recipients = await listAll((nextToken) =>
+  assembly.listInternalUsers({ nextToken, limit: 100 }),
+);
 await sendThrottled(recipients, (u) =>
   assembly.createNotification({ /* ...recipientInternalUserId: u.id... */ }),
 );

package/skills/assembly-user-company-selector/SKILL.md

@@ -49,7 +49,9 @@ const internalUserEntities: Entity[] = internalUsers.map(u => ({
 }));
 ```
 
-**Every company referenced by a client's `companyIds` must have a matching entry in the `companies` prop.** The component uses `companyIds` to expand a client into one selectable entry per company and renders the company's avatar badge next to each entry. If the company object is missing from `companies`, the badge cannot render and the user sees duplicate, indistinguishable client rows. Whenever clients have `companyIds`, fetch the companies with `listCompanies({ isPlaceholder: false })` (see `assembly-companies` skill) and map them to `Entity` objects as shown above — do not pass `companies={[]}` unless no client has any `companyIds`.
+**Pass every company, fetched with `listCompanies({ isPlaceholder: false })` and paged in full via `listAll`** — see `assembly-companies` skill for the fetch and why the complete list matters. Never pass `companies={[]}`, and never build the prop from clients' `companyIds`.
+
+Every company a client's `companyIds` references must be in the prop, or its badge can't render: the component expands a client into one entry per company and shows the company avatar beside each, so a missing company object leaves duplicate, indistinguishable client rows. That's a floor, not the set — the prop takes all companies, not just the referenced ones.
 
 Always include `avatarFallbackColor` from the SDK's `fallbackColor` field — without it, avatar fallbacks render as plain gray instead of the user's assigned color.