@assembly-js/app-foundation 0.0.4 → 0.0.6

package/CLAUDE.md

@@ -31,7 +31,7 @@ Assembly-specific gotchas live in `.claude/skills/<name>/SKILL.md`. Invoke them
 <!-- /feature:notification-settings -->
 - `clearing-client-notifications` — REQUIRED when the app sends client notifications: clear the portal sidebar badge with markNotificationRead (clear-on-view vs clear-on-action)
 <!-- feature:api-resources -->
-- `assembly-automations` — REQUIRED when the request asks for a platform-side effect in reaction to an in-app event (a message, a CRM field, a contract, a form, a file — not the app's own tables), even if the user never says "automation": declare the app's API contract in `.assembly/api-resources.json` (a separate file from `app.json`) — domain events that become automation triggers + workspace webhooks, and staff-invokable operations that become automation actions. Declared events must also be emitted at runtime, reporting the acting user on the documented headers — declaring alone never fires anything. Read it before adding either.
+- `assembly-automations` — REQUIRED when the request asks for a platform-side effect in reaction to an in-app event (a message, a CRM field, a contract, a form, a file — not the app's own tables), even if the user never says "automation": declare the app's API contract in `.assembly/api-resources.json` (a separate file from `app.json`) — domain events that become automation triggers + workspace webhooks, and staff-invokable operations that become automation actions. Declared events must also be emitted at runtime — inside `after()`, reporting the acting user on the documented headers — declaring alone never fires anything. Read it before adding either.
 <!-- /feature:api-resources -->
 - `assembly-app-surfaces` — REQUIRED before writing `.assembly/app.json`: declare which surfaces (dashboard, client portal, notification) the app exposes; omitting the client surface keeps the app off client portal nav entirely
 - `assembly-app-bridge-header` — breadcrumbs (don't include app name), CTAs
@@ -112,7 +112,7 @@ The app should **detect the viewer type from the token** and render audience-app
 
 **The CRM tab is never the only path to per-client data.** The CRM tab is a shortcut: it renders with a specific `clientId`/`companyId` already in the token. But any client/company-specific data or action it exposes must *also* be reachable from the Dashboard main view — even if it takes a few clicks. Build the main view so an internal user can browse to a specific client/company (a list, or a `UserCompanySelector` that drills into a per-entity detail screen) and reach the same data and actions there. The main-view detail screen doesn't have to match the CRM-tab layout — it can reuse the same components or present them differently — but the main view must never be empty or aggregate-only when the CRM tab has per-client functionality. Don't leave `internalUrl` as a dead end.
 
-**More generally: every page you create needs a click path.** Next.js builds and typechecks a page nothing links to, so an orphaned route ships silently. Before a page is done, something on an already-reachable page must point at it — a `<Link>`, `router.push`, redirect, header CTA, or actions-menu item. `bun run build` enforces this (`.assembly/check-route-reachability.mjs`). When a primary flow depends on managing another resource first (cases need stages, documents need templates), ship that manager's entry point together with the dependent flow — an actions-menu item on the main view plus a link on the empty state that blocks on it.
+**More generally: every page you create needs a click path.** Next.js builds and typechecks a page nothing links to, so an orphaned route ships silently. Before a page is done, something on an already-reachable page must point at it — a `<Link>`, `router.push`, redirect, header CTA, or actions-menu item. `bun run build` enforces this (`bun run check:route-reachability` runs it alone). When a primary flow depends on managing another resource first (cases need stages, documents need templates), ship that manager's entry point together with the dependent flow — an actions-menu item on the main view plus a link on the empty state that blocks on it.
 
 ### Per-client app visibility — platform setting, not the app's job
 
@@ -242,7 +242,7 @@ Two paths, decided by whether an `assembly-integrations` skill is present and, i
 - `label` — short label shown above the input field.
 - `description` — 1–2 sentences telling the user where to obtain the value.
 - `type` — `url | api_key | secret | text`. The platform picks input style from this.
-- `docsUrl` — optional link the platform renders as "Where do I find this?".
+- `docsUrl` — optional link the platform renders as "Where do I find this?". Verify it resolves (`curl -sIL <url>`, expect a 2xx — follow redirects, or a valid redirecting doc URL reads as broken) before including it — vendor docs get restructured and a stale URL renders as a dead link in the setup flow.
 
 <!-- !feature:notification-settings -->
 Valid top-level manifest keys: `surfaces`, `requiredSecrets`, and `requiredIntegrations` (leave it in place if present — it is platform-managed).
@@ -733,7 +733,7 @@ import { requireAuth, requireCompanyScope } from '@assembly-js/app-foundation/se
 
 **`requireAuth(req)`** decodes the viewer's identity from the bearer and returns it. Returns a 401 `NextResponse` with a `{ code: 'token_expired' }` body **and** `x-assembly-token-expired: 1` header when the bearer is missing/expired — `authFetch` detects this and re-exchanges + retries automatically.
 
-**`requireCompanyScope(identity, resource, assembly?)`** asserts the viewer can access a resource scoped to a company **or to a client**. Internal users always pass (client-vs-staff isolation only — not Client Access; filter app-owned data for limited internal users per `assembly-internal-users`). For a company-scoped resource, client access is checked against `identity.companyId`; when that is absent (a multi-company client not loaded in a CRM tab), pass the bearer client from `getAssemblyForRequest` as the third argument and the helper fetches the client's full `companyIds` list to verify membership. For a **client-scoped resource** (`companyId` null), pass the resource's `clientId` too — `{ companyId: item.companyId, clientId: item.clientId }` — so the owning client passes; without it every client gets a 404, including the one the record is assigned to. Returns `null` on success, or a 403/404 `NextResponse` on mismatch. A 403 from `requireCompanyScope` is a permanent authorization failure — a re-exchange will not fix cross-tenant access. **The two legs are either/or:** a non-null `resource.companyId` selects the company check and `clientId` is never compared, so a client-owned row (both columns set) needs an explicit ownership check in the handler after the guard — see `assembly-route-auth`.
+**`requireCompanyScope(identity, resource, assembly?)`** asserts the viewer can access a resource scoped to a company **or to a client**. Internal users always pass (client-vs-staff isolation only — not Client Access; filter app-owned data for limited internal users per `assembly-internal-users`). For a company-scoped resource, client access is checked against `identity.companyId`; when that is absent (a multi-company client not loaded in a CRM tab), pass the bearer client from `getAssemblyForRequest` as the third argument and the helper fetches the client's full `companyIds` list to verify membership. For a **client-scoped resource** (`companyId` null), pass the resource's `clientId` too — `{ companyId: item.companyId, clientId: item.clientId }` — so the owning client passes; without it every client gets a 404, including the one the record is assigned to. Returns `null` on success, or a 403/404 `NextResponse` on mismatch. A 403 from `requireCompanyScope` is a permanent authorization failure — a re-exchange will not fix cross-tenant access. When a row carries **both** scope columns the helper requires both to match, so a client-owned row is never reachable by a sibling client in the same company — see `assembly-route-auth`.
 
 ```ts
 // app/api/items/[id]/route.ts
@@ -776,11 +776,6 @@ export async function GET(
       assembly,
     );
     if (scopeError) return scopeError;
-    // The guard checked the company leg only — a client-owned row must also be
-    // this viewer's, or any client in the company could read it.
-    if (item.clientId && auth.clientId && item.clientId !== auth.clientId) {
-      return NextResponse.json({ error: 'Not found' }, { status: 404 });
-    }
 
     return NextResponse.json(item);
   } catch (err) {

package/dist/assembly.js

@@ -1,7 +1,7 @@
 import { assemblyApi } from '@assembly-js/node-sdk';
 import { cookies, headers } from 'next/headers';
 import { NextResponse } from 'next/server';
-import { BEARER_COOKIE_NAME, BEARER_HEADER_NAME, decodeBearer, isSessionExchangeEnabled, } from './session-exchange.js';
+import { BEARER_COOKIE_NAME, BEARER_HEADER_NAME, decodeBearer, isSessionExchangeEnabled, TOKEN_EXPIRED_HEADER, } from './session-exchange.js';
 import { mintBearerFromAppKey } from './mint-bearer.js';
 // Trusted API origin for this stack, supplied by the build environment — NOT by
 // a token claim. Empty in prod/shared-staging (the SDK's env default is already
@@ -148,7 +148,7 @@ export async function getAssembly(input) {
 }
 // Duplicated from lib/auth.ts to avoid a circular import.
 function tokenExpiredResponse() {
-    return NextResponse.json({ error: 'Unauthorized', code: 'token_expired' }, { status: 401, headers: { 'x-assembly-token-expired': '1' } });
+    return NextResponse.json({ error: 'Unauthorized', code: 'token_expired' }, { status: 401, headers: { [TOKEN_EXPIRED_HEADER]: '1' } });
 }
 // Builds a bearer-only SDK client. The SDK's native `bearer` option sends
 // Authorization: Bearer on every request — generated service methods and fetch

package/dist/auth.js

@@ -1,6 +1,6 @@
 import { NextResponse } from 'next/server';
 import { getAssembly } from './assembly.js';
-import { BEARER_COOKIE_NAME, BEARER_HEADER_NAME, decodeBearer, isSessionExchangeEnabled, } from './session-exchange.js';
+import { BEARER_COOKIE_NAME, BEARER_HEADER_NAME, decodeBearer, isSessionExchangeEnabled, TOKEN_EXPIRED_HEADER, } from './session-exchange.js';
 // Detect an expired/undecryptable-token error from the SDK by shape rather than
 // by importing a concrete class — the foundation builds against whatever SDK
 // version is published, which may not export the error type.
@@ -11,7 +11,7 @@ function isTokenInvalid(err) {
     return e.name === 'TokenInvalidError' || e.code === 'TOKEN_INVALID';
 }
 function tokenExpiredResponse() {
-    return NextResponse.json({ error: 'Unauthorized', code: 'token_expired' }, { status: 401, headers: { 'x-assembly-token-expired': '1' } });
+    return NextResponse.json({ error: 'Unauthorized', code: 'token_expired' }, { status: 401, headers: { [TOKEN_EXPIRED_HEADER]: '1' } });
 }
 // Resolves the current viewer's identity for a route handler.
 // Exchange on: bearer-only — decodes the bearer (proxy-forwarded header on first
@@ -60,13 +60,15 @@ export async function requireAuth(req) {
         return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
     }
 }
-// Asserts the viewer can access a resource scoped to a company OR to a client.
-// Internal users always pass. For a company-scoped resource (companyId set),
-// clients must belong to that company: if payload.companyId is present it must
-// match; otherwise membership is confirmed by fetching the client record.
-// For a client-scoped resource (companyId null), pass the resource's clientId
-// so the owning client can be matched against the viewer — without it a
-// client-scoped record 404s for the very client it is assigned to.
+// Asserts the viewer can access a resource scoped to a company, to a client, or
+// to both. Internal users always pass. For a company-scoped resource (companyId
+// set), clients must belong to that company: if payload.companyId is present it
+// must match; otherwise membership is confirmed by fetching the client record.
+// Whenever the resource names a clientId it must also be the viewer's, so a row
+// carrying both columns is authorized on the intersection rather than on company
+// alone — otherwise any client in the company could reach a sibling's row.
+// Always pass both scope columns: without clientId a client-scoped record
+// (companyId null) 404s for the very client it is assigned to.
 // Pass a session token string (legacy path) or a bearer-authenticated AssemblyAPI
 // instance from getAssemblyForRequest (bearer path) to enable the membership lookup.
 // Returns null on success, or a 403/404 NextResponse on mismatch.
@@ -82,12 +84,20 @@ export async function requireCompanyScope(payload, resource, tokenOrAssembly) {
             ? null
             : NextResponse.json({ error: 'Not found' }, { status: 404 });
     }
+    // A row carrying both columns belongs to one client inside the company, so the
+    // company match alone would let any sibling client in it through.
+    const clientMatches = !resource.clientId || resource.clientId === payload.clientId;
     if (payload.companyId) {
-        return payload.companyId === resource.companyId
+        return payload.companyId === resource.companyId && clientMatches
             ? null
             : NextResponse.json({ error: 'Not found' }, { status: 404 });
     }
     // No companyId in payload: client has multiple companies, verify membership.
+    // Ownership is decided from the token first so a sibling client fails here
+    // rather than after a round-trip that could only widen the answer.
+    if (!clientMatches) {
+        return NextResponse.json({ error: 'Not found' }, { status: 404 });
+    }
     if (!tokenOrAssembly) {
         return NextResponse.json({ error: 'Forbidden' }, { status: 403 });
     }

package/dist/lib-client.d.ts

@@ -0,0 +1,2 @@
+export declare function reexchangeBearer(): Promise<boolean>;
+export declare function authFetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response>;

package/dist/lib-client.js

@@ -0,0 +1,83 @@
+'use client';
+// Browser-side bearer renewal for generated apps. Exported via the dedicated
+// `@assembly-js/app-foundation/lib-client` subpath rather than the ./client
+// barrel: this module imports the app bridge, which is browser-only and must
+// never be dragged into the Edge middleware bundle that imports ./client
+// (proxy.ts pulls constants from that barrel).
+import { AssemblyBridge } from '@assembly-js/app-bridge';
+import { APP_CSRF_HEADER, TOKEN_EXPIRED_HEADER } from './session-exchange.js';
+const REEXCHANGE_PATH = '/api/assembly-reexchange';
+// Single-flight gate for renewals. Session tokens are single-use for exchange:
+// when the 60-minute bearer expires, every in-flight fetch on the page 401s at
+// once, and uncoordinated renewals would race each other for the token — the
+// first mints the bearer and the losers surface their original 401 even though
+// a valid bearer was just installed. All concurrent callers share this one
+// promise instead; it is cleared on settle so a later expiry renews afresh.
+let renewalInFlight = null;
+// Silently renews the bearer cookie after a 60-minute expiry. Asks the bridge
+// for the freshest session token (the parent keeps it alive) and posts it to the
+// re-exchange route, which mints a new bearer and sets the HttpOnly cookie — no
+// page reload. Returns true iff a fresh bearer was set. This is the only place
+// app code touches the raw session token, and only to re-mint; it is never sent
+// to the platform API.
+export function reexchangeBearer() {
+    if (renewalInFlight)
+        return renewalInFlight;
+    const renewal = renewBearer().finally(() => {
+        renewalInFlight = null;
+    });
+    renewalInFlight = renewal;
+    return renewal;
+}
+async function renewBearer() {
+    let token = AssemblyBridge.sessionToken.getCurrent()?.token ?? '';
+    // Proactively refresh: we're recovering from an expiry, so avoid re-minting
+    // from a session token that may itself be stale.
+    try {
+        const refreshed = await AssemblyBridge.sessionToken.refresh();
+        token = refreshed?.token ?? token;
+    }
+    catch {
+        // Ignore: fall back to the current token below.
+    }
+    if (!token)
+        return false;
+    try {
+        const res = await fetch(REEXCHANGE_PATH, {
+            method: 'POST',
+            headers: { 'x-assembly-token': token, [APP_CSRF_HEADER]: '1' },
+        });
+        return res.ok;
+    }
+    catch {
+        return false;
+    }
+}
+// Whether a denial is worth a renew-and-retry. A 401 is an authentication
+// failure — overwhelmingly an expired bearer, and foundation helpers mark
+// theirs with the expiry header — so it always renews; unmarked 401s renew too
+// because deployed apps hand-roll bare 401s on expiry paths, and gating those
+// would hard-fail their users at the 60-minute expiry. A 403 is an
+// authorization denial (requireCompanyScope, admin gates) that a fresh bearer
+// cannot fix, so it renews only when it explicitly carries the expiry marker.
+function shouldRenewBearer(res) {
+    if (res.status === 401)
+        return true;
+    return res.status === 403 && res.headers.has(TOKEN_EXPIRED_HEADER);
+}
+// fetch() for the app's own route handlers. The bearer travels automatically in
+// the HttpOnly cookie (same-origin), so this adds only the CSRF header — never a
+// token. On an expiry-shaped denial (see shouldRenewBearer) it renews the bearer
+// once via reexchangeBearer and retries; a genuine forbidden just returns.
+export async function authFetch(input, init) {
+    const headers = { ...(init?.headers ?? {}), [APP_CSRF_HEADER]: '1' };
+    const res = await fetch(input, { ...init, headers });
+    if (!shouldRenewBearer(res)) {
+        return res;
+    }
+    const renewed = await reexchangeBearer();
+    if (!renewed) {
+        return res;
+    }
+    return fetch(input, { ...init, headers });
+}

package/dist/mint-bearer.d.ts

@@ -1,4 +1,4 @@
-import { type ExchangedSession, type MintFailure } from './session-exchange.js';
+import { type ExchangedSession, type ExchangeRejectedViewer, type MintFailure } from './session-exchange.js';
 export interface MintedBearer {
     bearer: string;
     bearerExpiresAt: number;
@@ -9,8 +9,18 @@ export type MintOutcome = ({
 } & MintedBearer) | {
     ok: false;
     reason: MintFailure;
+    /** On a 'rejected' replay, whether the viewer who consumed the token
+     *  matches the caller's cookie session (only when the caller passed
+     *  cookieSessionId; absent on legacy rejections). */
+    rejectedViewer?: ExchangeRejectedViewer;
 };
-export declare function mintBearerFromSessionToken(token: string): Promise<MintOutcome>;
+export interface MintSessionOptions {
+    /** Session id behind the bearer the caller already holds. Forwarded with the
+     *  exchange so a rejected replay can say whether the consumer was the same
+     *  viewer (see MintOutcome.rejectedViewer). */
+    cookieSessionId?: string;
+}
+export declare function mintBearerFromSessionToken(token: string, options?: MintSessionOptions): Promise<MintOutcome>;
 export interface MintedAppBearer {
     bearer: string;
     bearerExpiresAt: number;

package/dist/mint-bearer.js

@@ -1,5 +1,5 @@
 import { assemblyApi, OpenAPI } from '@assembly-js/node-sdk';
-import { BEARER_TTL_MS, classifyExchangeFailure, } from './session-exchange.js';
+import { BEARER_TTL_MS, classifyExchangeFailure, EXCHANGE_REJECTION_HEADER, parseExchangeRejection, } from './session-exchange.js';
 // Trusted API origin for this stack (build-env supplied); empty in prod where
 // the SDK default is correct.
 const mintBaseUrl = process.env.ASSEMBLY_API_BASE_URL || undefined;
@@ -20,7 +20,7 @@ const EXCHANGE_TIMEOUT_MS = 15_000;
 //
 // On failure returns ok:false with a reason (see MintFailure) so the caller can
 // tell a spent token from an exchange it simply could not complete.
-export async function mintBearerFromSessionToken(token) {
+export async function mintBearerFromSessionToken(token, options) {
     let assembly;
     try {
         assembly = await assemblyApi({
@@ -56,14 +56,22 @@ export async function mintBearerFromSessionToken(token) {
         const resp = await assembly.fetch('/v1/session', {
             method: 'POST',
             headers: { 'Content-Type': 'application/json' },
-            body: JSON.stringify({ sessionId: payload.tokenId }),
+            body: JSON.stringify({
+                sessionId: payload.tokenId,
+                ...(options?.cookieSessionId
+                    ? { cookieSessionId: options.cookieSessionId }
+                    : {}),
+            }),
             signal: controller.signal,
         });
         if (!resp.ok) {
-            return {
-                ok: false,
-                reason: classifyExchangeFailure(resp.status),
-            };
+            const reason = classifyExchangeFailure(resp.status);
+            // Only a definitive rejection can carry a viewer verdict; on
+            // 'unavailable' the token may be unspent and no comparison happened.
+            const rejectedViewer = reason === 'rejected'
+                ? parseExchangeRejection(resp.headers.get(EXCHANGE_REJECTION_HEADER))
+                : undefined;
+            return { ok: false, reason, rejectedViewer };
         }
         // session.* mirrors platform-api's ExchangeResponse.Session — the
         // authoritative server-side record backing the (possibly slim) token, so

package/dist/session-exchange.d.ts

@@ -5,6 +5,10 @@ export declare function classifyExchangeFailure(status: number): MintFailure;
 export declare function serializeBearerCookie(value: string, maxAgeSeconds: number, partitioned: boolean): string;
 export declare const BEARER_HEADER_NAME = "x-assembly-request-bearer";
 export declare const APP_CSRF_HEADER = "x-assembly-app";
+export declare const TOKEN_EXPIRED_HEADER = "x-assembly-token-expired";
+export declare const EXCHANGE_REJECTION_HEADER = "x-assembly-exchange-rejection";
+export type ExchangeRejectedViewer = 'same_viewer' | 'different_viewer';
+export declare function parseExchangeRejection(value: string | null): ExchangeRejectedViewer | undefined;
 export declare function isSessionExchangeEnabled(): boolean;
 export interface ExchangedSession {
     workspaceId: string;

package/dist/session-exchange.js

@@ -47,6 +47,22 @@ export const BEARER_HEADER_NAME = 'x-assembly-request-bearer';
 // presence is sufficient: a cross-site request physically cannot carry a
 // custom header without a CORS preflight, and this app grants none.
 export const APP_CSRF_HEADER = 'x-assembly-app';
+// Marker header on 401s that mean "the bearer expired — re-exchange and retry",
+// emitted by requireAuth / getAssemblyForRequest / the re-exchange route. Its
+// absence on a denial is what lets authFetch skip renewal for genuine
+// authorization failures.
+export const TOKEN_EXPIRED_HEADER = 'x-assembly-token-expired';
+// Response header platform-api sets on a rejected exchange of an
+// already-consumed session token, when the caller supplied its cookie
+// session id for comparison: says whether the consumer was the same viewer.
+export const EXCHANGE_REJECTION_HEADER = 'x-assembly-exchange-rejection';
+// Narrows the raw header value; an absent or unrecognized value yields
+// undefined, which callers treat as the legacy opaque rejection.
+export function parseExchangeRejection(value) {
+    return value === 'same_viewer' || value === 'different_viewer'
+        ? value
+        : undefined;
+}
 // Master switch for the AI-260 server-side token exchange (bearer cookie flow).
 // Defaults OFF so the exchange stays dormant in every foundation snapshot:
 // merging this code — or any coworker rebuilding the snapshot for unrelated

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@assembly-js/app-foundation",
-  "version": "0.0.4",
+  "version": "0.0.6",
   "description": "Versioned foundation helpers and build context for Assembly generated apps",
   "type": "module",
   "files": [
@@ -18,6 +18,10 @@
     "./client": {
       "types": "./dist/client.d.ts",
       "default": "./dist/client.js"
+    },
+    "./lib-client": {
+      "types": "./dist/lib-client.d.ts",
+      "default": "./dist/lib-client.js"
     }
   },
   "scripts": {
@@ -28,11 +32,13 @@
     "verify:bin": "node scripts/verify-bin.mjs"
   },
   "peerDependencies": {
+    "@assembly-js/app-bridge": ">=1.3.0",
     "@assembly-js/node-sdk": ">=4.2.3-beta.2",
     "next": ">=15",
     "server-only": "*"
   },
   "devDependencies": {
+    "@assembly-js/app-bridge": "1.3.0",
     "@assembly-js/node-sdk": "4.2.3-beta.2",
     "@types/bun": "^1.1.0",
     "@types/node": "^22",

package/skills/assembly-app-surfaces/SKILL.md

@@ -30,12 +30,12 @@ If you are unsure, default to **internal-only**. Do not add a client surface unl
 - Generate the corresponding routes in your app code. E.g. if you declare `client.path = "/c"`, you must have a `/c` page in the app.
 
 <!-- !feature:notification-settings -->
-> **Every surface MUST be nested under `surfaces`.** A surface placed at the top level — e.g. `{ "surfaces": {...}, "notification": { "path": "/n" } }` — is silently dropped by the deploy parser, leaving that surface's URL empty and its notification links broken. The only valid top-level keys are `surfaces`, `requiredSecrets`, and `requiredIntegrations` (see below). The build validates this: `bun run build` runs `node .assembly/validate-manifest.mjs` first and **fails with a specific error** if the manifest is malformed or a key is misplaced. Run `bun run validate:manifest` to check it directly.
+> **Every surface MUST be nested under `surfaces`.** A surface placed at the top level — e.g. `{ "surfaces": {...}, "notification": { "path": "/n" } }` — is silently dropped by the deploy parser, leaving that surface's URL empty and its notification links broken. The only valid top-level keys are `surfaces`, `requiredSecrets`, and `requiredIntegrations` (see below). The build validates this: `bun run build` runs the manifest validator first and **fails with a specific error** if the manifest is malformed or a key is misplaced. Run `bun run validate:manifest` to check it directly.
 
 `requiredSecrets` and `requiredIntegrations` are **top-level siblings of `surfaces`**, not surfaces — see the secrets guidance and the `assembly-integrations` skill. The full manifest shape is:
 <!-- /feature:notification-settings -->
 <!-- feature:notification-settings -->
-> **Every surface MUST be nested under `surfaces`.** A surface placed at the top level — e.g. `{ "surfaces": {...}, "notification": { "path": "/n" } }` — is silently dropped by the deploy parser, leaving that surface's URL empty and its notification links broken. The only valid top-level keys are `surfaces`, `requiredSecrets`, `notificationSettings`, and `requiredIntegrations` (see below). The build validates this: `bun run build` runs `node .assembly/validate-manifest.mjs` first and **fails with a specific error** if the manifest is malformed or a key is misplaced. Run `bun run validate:manifest` to check it directly.
+> **Every surface MUST be nested under `surfaces`.** A surface placed at the top level — e.g. `{ "surfaces": {...}, "notification": { "path": "/n" } }` — is silently dropped by the deploy parser, leaving that surface's URL empty and its notification links broken. The only valid top-level keys are `surfaces`, `requiredSecrets`, `notificationSettings`, and `requiredIntegrations` (see below). The build validates this: `bun run build` runs the manifest validator first and **fails with a specific error** if the manifest is malformed or a key is misplaced. Run `bun run validate:manifest` to check it directly.
 
 `requiredSecrets`, `notificationSettings`, and `requiredIntegrations` are **top-level siblings of `surfaces`**, not surfaces — see the `assembly-notifications` skill, the secrets guidance, and the `assembly-integrations` skill. The full manifest shape is:
 <!-- /feature:notification-settings -->

package/skills/assembly-automations/SKILL.md

@@ -1,12 +1,12 @@
 <!-- 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.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.
+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.
 ---
 
 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.
 
-Declaring a webhook only registers the trigger — the running app must also **emit** the event with `assembly.sendWebhook(...)` when it happens, or automations built on it never run. See "Emitting events at runtime" below.
+Declaring a webhook only registers the trigger — the running app must also **emit** the event with `assembly.fetch('/v1/webhooks/<eventName>', …)` when it happens, or automations built on it never run. See "Emitting events at runtime" below.
 
 ## When to declare it
 
@@ -207,27 +207,52 @@ Laptop Desktop Mobile Print Qrcode BarcodeRead Language EarthAmericas
 
 ## Emitting events at runtime
 
-Declaring a webhook only makes the trigger appear in the automations builder — **the platform never fires the event for you**. The app must report each event at the moment it happens, from the server-side code path that performs the state change:
+Declaring a webhook only makes the trigger appear in the automations builder — **the platform never fires the event for you**. The app must report each event at the moment it happens, from the server-side code path that performs the state change — and report **who acted** on the same call, because the platform sees only the app's own credentials and the app is the only thing that knows the person behind the event.
 
 ```ts
-await assembly.sendWebhook('timeEntry.created', {
-  id: entry.id,
-  clientId: entry.clientId,
-  companyId: entry.companyId,
-  minutes: entry.minutes,
-  startedAt: entry.startedAt.toISOString(),
+import { after } from 'next/server';
+
+const viewer = await requireAuth(req);
+if (viewer instanceof NextResponse) return viewer;
+// … the write commits here …
+
+// Read the request values now — after() runs once the response is already sent.
+const actorId = viewer.internalUserId ?? viewer.clientId ?? '';
+const clientIP = req.headers.get('x-forwarded-for') ?? '';
+const userAgent = req.headers.get('user-agent') ?? '';
+
+after(async () => {
+  try {
+    const res = await assembly.fetch('/v1/webhooks/timeEntry.created', {
+      method: 'POST',
+      headers: {
+        'X-Assembly-Actor-Id': actorId,
+        'X-Assembly-Source': 'web',
+        'X-Assembly-Client-IP': clientIP,
+        'X-Assembly-User-Agent': userAgent,
+      },
+      body: JSON.stringify({ id: entry.id, clientId: entry.clientId, minutes: entry.minutes }),
+    });
+    if (!res.ok) {
+      console.error(`timeEntry.created webhook failed: ${res.status} ${await res.text()}`);
+    }
+  } catch (err) {
+    console.error('timeEntry.created webhook failed:', err);
+  }
 });
 ```
 
-- `sendWebhook(eventName, payload)` is on every SDK client — the request-scoped one and `getOfflineAssembly()`. The platform validates the event name and payload against this manifest's registration, then runs matching automations.
-- Call it **after** the database write commits, never before — an event emitted for a rolled-back write is a phantom trigger.
+- **`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.
+- **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.
+- Emit **after** the database write commits, never before — an event emitted for a rolled-back write is a phantom trigger.
 - The payload is the resource's record `schema[]` shape: required fields present, `fieldName`s exact. Always include the recipient fields the record declares (`clientId` / `companyId` / `internalUserId`) — automations resolve who to act on from this payload, and a missing recipient silently skips the run.
-- Emission must never break the user's action: wrap the call in try/catch, log the failure, and continue.
 - **Every webhook declared in this file needs at least one emit call site in the app.** A declared-but-never-emitted event is an incomplete feature: the trigger shows up in the automations UI, workspace admins build automations on it, and nothing ever runs.
 
 ### Reporting who acted
 
-Every event also lands in the workspace's audit log, where a workspace admin reads who did what. The platform only sees the app's own credentials on the call, so **the app is the only thing that knows the person behind the event** — capture the caller in the handler that performs the write and report it on these headers:
+Every event also lands in the workspace's audit log, where a workspace admin reads who did what. The four headers above are what that entry is built from:
 
 | Header | Value |
 |---|---|
@@ -236,28 +261,9 @@ Every event also lands in the workspace's audit log, where a workspace admin rea
 | `X-Assembly-Client-IP` | the request's `x-forwarded-for` |
 | `X-Assembly-User-Agent` | the request's `user-agent` |
 
-`sendWebhook` cannot carry headers, so a user-triggered event is emitted through `assembly.fetch`, which adds the app's auth for you:
-
-```ts
-const viewer = await requireAuth(req);
-if (viewer instanceof NextResponse) return viewer;
-// … the write commits here …
-
-await assembly.fetch('/v1/webhooks/timeEntry.created', {
-  method: 'POST',
-  headers: {
-    'X-Assembly-Actor-Id': viewer.internalUserId ?? viewer.clientId ?? '',
-    'X-Assembly-Source': 'web',
-    'X-Assembly-Client-IP': req.headers.get('x-forwarded-for') ?? '',
-    'X-Assembly-User-Agent': req.headers.get('user-agent') ?? '',
-  },
-  body: JSON.stringify({ id: entry.id, clientId: entry.clientId, minutes: entry.minutes }),
-});
-```
-
 - **Report only what the request actually carries.** The platform records what it is given and infers nothing; an empty header is the same as no header.
 - **Never pass an app-internal id as the actor.** The id is recorded only once it resolves to a user of that workspace, so an app's own row id attributes the event to nobody and loses the actor entirely.
-- A background job has no caller — `getOfflineAssembly()` plus plain `sendWebhook(...)` is right there, and the entry reads as a system event.
+- A background job has no caller and no request scope: emit with `getOfflineAssembly()`, send no actor headers, and `await` the call directly — `after()` is unavailable there. The entry reads as a system event.
 
 ## Serving actions
 
@@ -423,8 +429,10 @@ export const POST = automationActionRoute<{
 
 | Symptom | Cause | Fix |
 | --- | --- | --- |
-| `sendWebhook` rejects with a 400 | The event name isn't registered for this app — a typo, or the manifest hasn't been published since the event was added | Publish, then emit the exact `eventName` from this file |
-| `sendWebhook` 400 on a name that is registered | The payload doesn't satisfy the record's `schema[]` — a required field is absent, or carries `""` / `0` / `false` | Send every required field with a real value; declare zeroable ones `optional: true` |
+| The automation never runs, or runs minutes late | The emit is un-awaited, so the handler returned and the runtime froze it before it left the app | Wrap the emit in `after()` — see "Emitting events at runtime" |
+| The automation never runs and the app logged nothing | The emit came back 4xx and nothing read `res.ok` — `assembly.fetch` resolves on an error status instead of throwing | Log a non-ok response, then fix whichever cause the body names |
+| The emit returns 400 | The event name isn't registered for this app — a typo, or the manifest hasn't been published since the event was added | Publish, then emit the exact `eventName` from this file |
+| 400 on an event name that is registered | The payload doesn't satisfy the record's `schema[]` — a required field is absent, or carries `""` / `0` / `false` | Send every required field with a real value; declare zeroable ones `optional: true` |
 | Action returns 400 naming a field | The helper rejected the body before the handler ran: the automation's config never sends a field this manifest declares required | Make the field `automationSettings.isEnabled` so admins can fill it, or declare it `optional: true` |
 | Action step fails with no app logs at all | The app is unreachable, or nothing serves the record's `baseUrl` | Serve a real route at exactly that path — the platform calls `baseUrl`, not `apis[].path` |
 | Action returns 500 "Action is not registered" | `automationActionRoute`'s first argument doesn't match any `apis[].name` | Copy the name from this file verbatim |

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

@@ -112,7 +112,7 @@ That reads as: this client's rows **within the active company**, plus the compan
 
 **On writes, validate the target company.** Before storing a row under a `companyId` the request supplied rather than the viewer's own, confirm it is actually one of the client's: `client.companyIds.includes(companyId)`. Otherwise a client can write into a company they don't belong to.
 
-**On `[id]` route handlers, `requireCompanyScope` is not enough by itself.** It authorizes the *company* leg; for a row that also has a `clientId`, add the client-ownership check yourself. See `assembly-route-auth`.
+**On `[id]` route handlers, pass both scope columns to `requireCompanyScope`.** It authorizes the intersection, so a row that also carries a `clientId` is reachable only by that client — never by a sibling in the same company. See `assembly-route-auth`.
 
 ## Pattern 3 — the placeholder pitfall
 

package/skills/assembly-notifications/SKILL.md

@@ -257,7 +257,7 @@ Include in `deliveryTargets` every surface the setting declares; the platform re
 
 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.
+If `bun run build` fails with an unknown-top-level-key error on `notificationSettings`, the validator this app runs predates the key. `package.json`'s `validate:manifest` script names the copy it runs: when that is `.assembly/validate-manifest.mjs`, add `'notificationSettings'` to its `TOP_LEVEL_KEYS` and rerun. When it resolves out of `node_modules`, the app's foundation dependency is behind — update it rather than editing an installed file.
 
 ## App-level action label (Client Home)
 

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

@@ -18,33 +18,14 @@ import { requireAuth, requireCompanyScope, handleRouteError } from '@assembly-js
 - Internal users always pass (client-vs-staff isolation only — **not** Client Access; limited internal users can still read another company's row unless you filter app-owned queries and lists yourself; see `assembly-internal-users`).
 - For a **company-scoped** resource (`companyId` set), client access is checked against `identity.companyId`; when that is absent (a multi-company client not loaded in a CRM tab), pass the bearer client from `getAssemblyForRequest` as the third argument and the helper fetches the client's full `companyIds` list to verify membership.
 - For a **client-scoped** resource (`companyId` null), the helper matches `resource.clientId` against `identity.clientId`.
-- Those two are **either/or** — it never checks both, which is why a client-owned row needs the extra check below.
+- When a row carries **both** columns the helper requires both to match, so the company leg alone never admits a sibling client.
 - Returns `null` on success, or a 403/404 `NextResponse` on mismatch. A 403 is a permanent authorization failure — a re-exchange will not fix cross-tenant access.
 
 The `resource` argument is `{ companyId: string | null; clientId?: string | null }` — the same shape you already loaded from the database. **Always select and pass both columns.** Omitting `clientId` makes every client-scoped record 404 for the very client it is assigned to, and a table with no `clientId` column cannot express client scope at all — so give records both a `companyId` and a `clientId` column in the schema, even when only one is populated for a given row (see `assembly-clients-companies`).
 
-### `requireCompanyScope` does not check client ownership on a company-scoped row
+### Client-owned rows are covered by the guard
 
-The two legs are **either/or**, not both: when `resource.companyId` is non-null the helper authorizes on the company match alone and never compares `clientId`. It only compares `clientId` when `resource.companyId` is null.
-
-So for a **client-owned row** — one carrying both a `companyId` and a `clientId`, which is the shape `assembly-clients-companies` prescribes — `requireCompanyScope` alone lets **any client in that company** read or mutate it. Add the ownership check in the handler, right after the scope guard:
-
-```ts
-const scopeError = await requireCompanyScope(
-  auth,
-  { companyId: item.companyId, clientId: item.clientId },
-  assembly,
-);
-if (scopeError) return scopeError;
-
-// requireCompanyScope only checked the company leg. A row owned by a specific
-// client must also belong to this viewer, or any client in the company can read it.
-if (item.clientId && auth.clientId && item.clientId !== auth.clientId) {
-  return NextResponse.json({ error: 'Not found' }, { status: 404 });
-}
-```
-
-Guard on `auth.clientId` being present so internal users (who legitimately see every row in the workspace) still pass. A company-wide row (`clientId` null) skips the check, as it should.
+A **client-owned row** — one carrying both a `companyId` and a `clientId`, the shape `assembly-clients-companies` prescribes — is authorized on the intersection: a sibling client in the same company gets a 404. Pass both columns and add no ownership check of your own. Internal users still pass, and a company-wide row (`clientId` null) is reachable by every client in the company, as it should be.
 
 For safe catch blocks and validating values before typed DB lookups (e.g. `parseUuid` before a uuid-column query), see `assembly-route-errors`. Do not treat every `[id]` route param as a UUID — only validate as UUID when the next step is a uuid-column lookup.
 
@@ -91,11 +72,6 @@ export async function GET(
       assembly,
     );
     if (scopeError) return scopeError;
-    // The guard checked the company leg only — a client-owned row must also be
-    // this viewer's, or any client in the company could read it.
-    if (item.clientId && auth.clientId && item.clientId !== auth.clientId) {
-      return NextResponse.json({ error: 'Not found' }, { status: 404 });
-    }
 
     return NextResponse.json(item);
   } catch (err) {
@@ -133,9 +109,6 @@ export async function PATCH(
       assembly,
     );
     if (scopeError) return scopeError;
-    if (item.clientId && auth.clientId && item.clientId !== auth.clientId) {
-      return NextResponse.json({ error: 'Not found' }, { status: 404 });
-    }
 
     const body = await request.json();
     // Never spread the full body — callers could include companyId or id
@@ -195,9 +168,6 @@ export async function GET(
       assembly,
     );
     if (scopeError) return scopeError;
-    if (highlight.clientId && auth.clientId && highlight.clientId !== auth.clientId) {
-      return NextResponse.json({ error: 'Not found' }, { status: 404 });
-    }
 
     return NextResponse.json(highlight);
   } catch (err) {
@@ -217,7 +187,6 @@ Every `[id]`-nested route handler — regardless of HTTP method or nesting depth
 3. Return 404 if not found.
 4. `const assembly = await getAssemblyForRequest(request); if (assembly instanceof NextResponse) return assembly;`
 5. `const scopeError = await requireCompanyScope(auth, { companyId: resource.companyId, clientId: resource.clientId }, assembly); if (scopeError) return scopeError;`
-6. If the row is client-owned, check ownership — the guard above only covered the company leg: `if (resource.clientId && auth.clientId && resource.clientId !== auth.clientId) return NextResponse.json({ error: 'Not found' }, { status: 404 });`
-7. Return data or perform the mutation.
+6. Return data or perform the mutation.
 
-Never skip steps 1, 5, or 6, even on GET handlers.
+Never skip steps 1 or 5, even on GET handlers.