@assembly-js/app-foundation 0.0.0 → 0.0.1-rc.1

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

@@ -0,0 +1,69 @@
+---
+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.
+---
+
+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).
+
+## Identify the current viewer
+
+```ts
+const { internalUserId, clientId } = await assembly.getTokenPayload();
+const isInternal = !!internalUserId;
+```
+
+If `internalUserId` is set, the current viewer is staff. (`clientId` is set for client viewers — see `assembly-client-users` skill.)
+
+## SDK methods
+
+- `listInternalUsers({ nextToken, limit })` — paged list of all staff in the workspace
+- `retrieveInternalUser({ id })` — single record by id
+
+## Client Access permissions
+
+Client Access is a **workspace-level** setting (configured in workspace settings, not inside your app). By default every internal user can see all clients and companies. Admins can limit an internal user to specific companies; that limit ripples through the platform.
+
+On `retrieveInternalUser` / `listInternalUsers`, each internal user may carry:
+
+- `isClientAccessLimited` — `false` or `null` ⇒ full access to every client/company; `true` ⇒ limited
+- `companyAccessList` — when limited, the company IDs they can access (empty ⇒ no company access)
+
+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:
+
+```ts
+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);
+}
+
+function canAccessClient(client: { companyIds?: string[] }): boolean {
+  if (!isLimited) return true;
+  return (client.companyIds ?? []).some((id) => accessList.includes(id));
+}
+```
+
+### 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.
+- **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.
+
+Workspace-wide surfaces with no client/company tie (e.g. "all staff" settings) still show all internal users; only **client/company data** is scoped.
+
+## UI guidance
+
+When the viewer is internal, the app is rendered inside the Dashboard. Show the **full-power staff UI** — create/edit/delete, bulk actions, exports, admin views — but **scoped to the viewer's Client Access**:
+
+- Global views list only clients and companies they can access (not "every client in the workspace" unless they have full access).
+- CRM-tab views inherit the tab's `clientId` / `companyId` from the token.
+- Do not strip staff affordances to look like the client portal; do not show clients or companies outside their access list.

package/skills/assembly-mutations/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: assembly-mutations
+description: Use whenever calling updateClient, updateCompany, updateNote, updateTask, or any other patch-style mutation. The requestBody must contain ONLY the fields actually changing — including unchanged fields like the deprecated companyId triggers re-assignment that 403s on client tokens.
+---
+
+Patch-style endpoints (`updateClient`, `updateCompany`, `updateNote`, `updateTask`, etc.) treat **every non-empty top-level field in `requestBody` as "set this to this value."** Including fields you happen to have on hand — from a `retrieve` response, props, or the token payload — re-assigns those fields, even when the user didn't change them.
+
+## The most common bite: `companyId` on `updateClient`
+
+```ts
+// ❌ WRONG — re-assigns the client's company on every save.
+// Client tokens cannot mutate companyId, so the entire call 403s
+// with a permissions error that's confusing to debug.
+await assembly.updateClient({
+  id: clientId,
+  requestBody: {
+    companyId,                                            // ← from earlier retrieveClient
+    customFields: { [fieldKey]: [newValue] },
+  },
+});
+
+// ✅ RIGHT — only the field actually being edited.
+await assembly.updateClient({
+  id: clientId,
+  requestBody: {
+    customFields: { [fieldKey]: [newValue] },
+  },
+});
+```
+
+## The rule
+
+`requestBody` for any patch endpoint should contain **only the fields the user is editing in this UI action.** Don't pass:
+
+- Values from a `retrieve` call you read for display
+- Values from the token payload (`clientId`, `companyId`, `companyIds`)
+- Values you spread from props "for safety"
+
+If the user changed name + email, send `{ givenName, familyName, email }` and nothing else. If they only changed a custom field, send only `customFields`.
+
+## Endpoints this applies to
+
+`updateClient`, `updateCompany`, `updateNote`, `updateTask`, and any other `update*` SDK method with a `requestBody` parameter.
+
+## Bonus: surface the real API error in mutation UIs
+
+When the mutation fails, the route handler returns the SDK's error message in the response body. Display it. Hardcoding `"Failed to save"` hides the actual cause (auth expiry, permission denial, validation, deprecated-field re-assignment, etc.).
+
+```ts
+// ❌ WRONG
+if (!res.ok) setError('Failed to save');
+
+// ✅ RIGHT
+if (!res.ok) {
+  const body = await res.json().catch(() => ({}));
+  setError(body.error ?? `Save failed (HTTP ${res.status})`);
+}
+```

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

@@ -0,0 +1,117 @@
+---
+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.)
+---
+
+## The non-negotiable
+
+1. **Never hardcode a native resource ID.** A message channel id, form id, file id or file channel id is minted by one workspace and is **only valid in the workspace it came from**. Paste one into source and the app works exactly once — in the workspace you built it in. Anywhere else the lookup returns nothing and the feature silently does nothing, or the call fails. There is no data fix for this: the broken value is in the code.
+
+Discover instead. The pattern is always the same two steps: **list, then match on a stable attribute** the workspace owner controls (a title, a name), or resolve the resource from the current request's identity. Never a literal.
+
+## Discovering a form
+
+A form's display name is on `fields`, not on the form itself:
+
+```ts
+const { data: forms = [] } = await assembly.listForms({});
+const intakeForm = forms.find(
+  (f) => f.fields?.name?.toLowerCase().includes('intake'), // match the user's wording
+);
+if (!intakeForm?.id) {
+  return <div>The intake form hasn&apos;t been set up in this workspace yet.</div>;
+}
+
+// Assign it to one or more clients. Recipients go in clientIds — a bare
+// clientId is not a field on this request and the call 400s without one.
+await assembly.requestFormResponse({
+  requestBody: { formId: intakeForm.id, clientIds: [clientId] },
+});
+```
+
+There is **no** method for a custom app to submit answers to a native form — you can request a response from a client and read `listFormResponses`, nothing more. Build your own form (see `assembly-forms`) if the app needs to collect the answers itself.
+
+## Discovering a message channel
+
+A channel has no name — it is identified by who is in it, so resolve it from the viewer rather than searching by title. `getSessionIdentity()` returns `null` when there is no session, and `clientId` is absent for a staff viewer, so branch before you filter:
+
+```ts
+const identity = await getSessionIdentity();
+// { workspaceId, clientId?, companyId?, internalUserId? } | null
+if (!identity?.clientId) {
+  return <div>Open this from a client&apos;s portal to see their messages.</div>;
+}
+
+// membershipType narrows to the client's own 1:1 channel; without it a client
+// who belongs to a company also matches that company's channel.
+const { data: channels = [] } = await assembly.listMessageChannels({
+  clientId: identity.clientId,
+  membershipType: 'individual',
+});
+
+const channel = channels?.[0];
+if (!channel?.id) {
+  return <div>This client doesn&apos;t have a message channel yet.</div>;
+}
+
+await assembly.sendMessage({
+  requestBody: { channelId: channel.id, text: 'Your report is ready.' },
+});
+```
+
+`retrieveMessageChannel({ id })` is for a channel id you already resolved this request — never for one typed into the source.
+
+## Discovering a file channel
+
+```ts
+const identity = await getSessionIdentity();
+if (!identity?.clientId) {
+  return <div>Open this from a client&apos;s portal to see their files.</div>;
+}
+
+const { data: fileChannels = [] } = await assembly.listFileChannels({
+  clientId: identity.clientId,
+  membershipType: 'individual',
+});
+const channel = fileChannels?.[0];
+if (!channel?.id) {
+  return <div>This client has no portal file channel yet.</div>;
+}
+
+const { data: files = [] } = await assembly.listFiles({ channelId: channel.id });
+```
+
+For files the app itself owns (attachments, exports), don't use the Files module at all — use the storage helpers in `@assembly-js/app-foundation/server` (see `assembly-storage`). Files is only for things the user wants to see in their portal Files tab.
+
+## Storing an ID (this is allowed)
+
+Persisting a native id in the app's **own database** is fine:
+
+```ts
+await db.insert(reports).values({ clientId, fileChannelId: channel.id });
+```
+
+Those rows are workspace-local, and a copy of the app into another workspace starts with an empty database — so nothing stale comes along. The ban is on the **literal in source**, which does travel.
+
+## When the resource isn't there
+
+Render an explicit, honest empty state and stop — "The intake form hasn't been set up in this workspace yet." Do **not** fall back to a hardcoded id, and do not silently render an empty table as though the feature were working. A missing native resource is a real workspace-configuration state, not an error to paper over.
+
+## Symptoms when it goes wrong
+
+| Mistake | What you'll see |
+|---|---|
+| Hardcoded a form / channel / file id | Works in the workspace you built it in; everywhere else the lookup returns nothing and the feature does nothing |
+| Matched on the id instead of a stable attribute | Same — an id is not stable across workspaces, a name is |
+| Matched a form on `form.name` | Always undefined; the display name is `form.fields.name`, so nothing ever matches and the app renders its empty state forever |
+| Fell back to a literal id when discovery found nothing | The feature appears to work and writes into the wrong place, or fails on a resource the workspace can't see |
+| Used the Files module for app-private uploads | Attachments show up in the client's portal Files tab |
+
+## Edge cases
+
+- **Nested SDK calls don't exist.** The SDK is flat: `assembly.listForms({})`, never `assembly.forms.list()`.
+- **Every list method takes an options object**, even when you pass no filters — `listForms({})`, not `listForms()`.
+- **List responses are paginated envelopes**, and `data` is nullable: destructure with a default and still index defensively (`const { data: forms = [] } = …; forms?.[0]`).
+- **Narrow before you index.** Taking `[0]` off an unfiltered list is the same guess as a hardcoded id. Filter by `membershipType` (and `companyId` for a client in multiple companies); if two candidates genuinely remain, surface the choice rather than picking one.
+- **Creating a channel is not a substitute for finding one.** `createMessageChannel` requires a `membershipType`, and its type is a string enum the SDK does not re-export from its package root — you cannot satisfy it with a plain `'individual'` string. Work with the channels the workspace already has; check the SDK types first if you genuinely need to create one.
+- **Ids from the app bridge or a route param** are runtime values, not literals — those are fine to pass straight to `retrieve*`, after the usual auth and scope checks (see `assembly-route-auth`).

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

@@ -0,0 +1,223 @@
+---
+name: assembly-route-auth
+description: Use for every app/api/.../[id]/route.ts handler — GET and write alike. Every handler must call requireAuth then requireCompanyScope from @assembly-js/app-foundation/server before returning or mutating data, at parity with the page-level ownership guard.
+---
+
+Every `app/api/.../[id]/route.ts` handler — **GET included** — must call `requireAuth` then `requireCompanyScope` (from `@assembly-js/app-foundation/server`) before returning or mutating data. Skipping either guard on a GET handler is a cross-tenant IDOR: an authenticated user in company A can read company B's records by changing the id in the URL.
+
+```ts
+import { requireAuth, requireCompanyScope, handleRouteError } from '@assembly-js/app-foundation/server';
+```
+
+## How the helpers work
+
+**`requireAuth(req)`** decodes the viewer's identity from the bearer (read from the request cookie — no `x-assembly-token` header) and returns it. Returns a 401 `NextResponse` (with a `{ code: 'token_expired' }` body and an `x-assembly-token-expired: 1` header) when the bearer is missing or 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; 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.
+- 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
+
+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.
+
+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.
+
+## GET example
+
+```ts
+// app/api/items/[id]/route.ts
+import { NextRequest, NextResponse } from 'next/server';
+import {
+  requireAuth,
+  requireCompanyScope,
+  getAssemblyForRequest,
+  handleRouteError,
+  parseUuid,
+} from '@assembly-js/app-foundation/server';
+import { db } from '@/lib/db';
+import { items } from '@/lib/schema';
+import { eq } from 'drizzle-orm';
+
+export async function GET(
+  request: NextRequest,
+  { params }: { params: Promise<{ id: string }> },
+) {
+  const auth = await requireAuth(request);
+  if (auth instanceof NextResponse) return auth;
+
+  const { id: rawId } = await params;
+  // items.id is uuid — validate at the lookup, not because the segment is named [id]
+  const id = parseUuid(rawId);
+  if (id instanceof NextResponse) return id;
+
+  try {
+    const item = await db.query.items.findFirst({ where: eq(items.id, id) });
+    if (!item) return NextResponse.json({ error: 'Not found' }, { status: 404 });
+
+    // Only needed for the multi-company membership check; omit otherwise.
+    const assembly = await getAssemblyForRequest(request);
+    if (assembly instanceof NextResponse) return assembly;
+    // Pass both scope columns — clientId is what lets a client-scoped row
+    // (companyId null) pass for its owning client.
+    const scopeError = await requireCompanyScope(
+      auth,
+      { companyId: item.companyId, clientId: item.clientId },
+      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) {
+    return handleRouteError(err);
+  }
+}
+```
+
+## Write (POST/PATCH) example
+
+Apply the same guard before any mutation. Mutating without it lets an authenticated user from company A modify company B's data.
+
+```ts
+// app/api/items/[id]/route.ts — PATCH handler in the same file
+export async function PATCH(
+  request: NextRequest,
+  { params }: { params: Promise<{ id: string }> },
+) {
+  const auth = await requireAuth(request);
+  if (auth instanceof NextResponse) return auth;
+
+  const { id: rawId } = await params;
+  const id = parseUuid(rawId);
+  if (id instanceof NextResponse) return id;
+
+  try {
+    const item = await db.query.items.findFirst({ where: eq(items.id, id) });
+    if (!item) return NextResponse.json({ error: 'Not found' }, { status: 404 });
+
+    const assembly = await getAssemblyForRequest(request);
+    if (assembly instanceof NextResponse) return assembly;
+    const scopeError = await requireCompanyScope(
+      auth,
+      { companyId: item.companyId, clientId: item.clientId },
+      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
+    // and reparent / re-identify the resource. Extract only mutable fields.
+    const { name, description } = body; // replace with the actual mutable fields
+    await db.update(items).set({ name, description }).where(eq(items.id, id));
+    return NextResponse.json({ ok: true });
+  } catch (err) {
+    return handleRouteError(err, 'Update failed');
+  }
+}
+```
+
+## Sub-resource routes
+
+The same guard applies to **every level of nesting**. If a project has highlights, the highlight handler must scope to the highlight's own owning company or client — not just the parent project.
+
+Load the **sub-resource** from the database first, then call `requireCompanyScope` with the sub-resource's own `companyId` and `clientId`. Do NOT skip the scope check on the assumption that the parent route already guards access.
+
+```ts
+// app/api/projects/[id]/highlights/[highlightId]/route.ts
+import { NextRequest, NextResponse } from 'next/server';
+import {
+  requireAuth,
+  requireCompanyScope,
+  getAssemblyForRequest,
+  handleRouteError,
+  parseUuid,
+} from '@assembly-js/app-foundation/server';
+import { db } from '@/lib/db';
+import { highlights } from '@/lib/schema';
+import { eq } from 'drizzle-orm';
+
+export async function GET(
+  request: NextRequest,
+  { params }: { params: Promise<{ id: string; highlightId: string }> },
+) {
+  const auth = await requireAuth(request);
+  if (auth instanceof NextResponse) return auth;
+
+  const { highlightId: rawHighlightId } = await params;
+  // highlights.id is uuid — validate at the lookup
+  const highlightId = parseUuid(rawHighlightId, 'highlight id');
+  if (highlightId instanceof NextResponse) return highlightId;
+
+  try {
+    const highlight = await db.query.highlights.findFirst({
+      where: eq(highlights.id, highlightId),
+    });
+    if (!highlight) return NextResponse.json({ error: 'Not found' }, { status: 404 });
+
+    const assembly = await getAssemblyForRequest(request);
+    if (assembly instanceof NextResponse) return assembly;
+    const scopeError = await requireCompanyScope(
+      auth,
+      { companyId: highlight.companyId, clientId: highlight.clientId },
+      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) {
+    return handleRouteError(err);
+  }
+}
+```
+
+The same pattern applies to milestones, comments, assets, or any other sub-resource nested under a parent `[id]` route.
+
+## The rule
+
+Every `[id]`-nested route handler — regardless of HTTP method or nesting depth — must follow this sequence:
+
+1. `const auth = await requireAuth(request); if (auth instanceof NextResponse) return auth;`
+2. Load the resource (or sub-resource) from the database inside `try/catch`. If the lookup uses a uuid column, validate with `parseUuid` first (see `assembly-route-errors`). Use `handleRouteError` in the catch — never return `err.message`.
+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.
+
+Never skip steps 1, 5, or 6, even on GET handlers.

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

@@ -0,0 +1,81 @@
+---
+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).
+---
+
+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.
+
+Pre-built helpers in `@assembly-js/app-foundation/server`:
+
+```ts
+import { badRequest, handleRouteError, internalError, notFound } from '@assembly-js/app-foundation/server';
+```
+
+- **`badRequest(message)`** → 400
+- **`notFound(message?)`** → 404 (default message: `Not found`)
+- **`internalError(message?)`** → 500 (default: `Something went wrong`)
+- **`handleRouteError(err, fallback?)`** → maps known DB input errors to 400, everything else to a safe 500. Logs the real error with `console.error`; never forwards `err.message`.
+
+## The rule
+
+```ts
+export async function POST(request: NextRequest) {
+  try {
+    // ... handler logic ...
+    return NextResponse.json({ ok: true });
+  } catch (err) {
+    return handleRouteError(err, 'Save failed');
+  }
+}
+```
+
+**Wrong** — leaks driver/Postgres strings:
+
+```ts
+} catch (err) {
+  const message = err instanceof Error ? err.message : 'Failed';
+  return NextResponse.json({ error: message }, { status: 500 });
+}
+```
+
+**Right** — safe client message, real error logged server-side:
+
+```ts
+} catch (err) {
+  return handleRouteError(err, 'Save failed');
+}
+```
+
+When you know the failure mode without a catch (validation, missing resource), return the specific helper directly — don't throw just to catch:
+
+```ts
+if (!name?.trim()) return badRequest('Name is required');
+if (!item) return notFound();
+```
+
+## Validate before typed database lookups
+
+Validate a value **when you are about to pass it into a typed Drizzle column** — not because it arrived as a route/query param. Route segments can be slugs, external ids, or other non-uuid strings; those are fine. The failure mode is querying a `uuid` column with a non-uuid value (Postgres throws; a naive catch leaks the string).
+
+`handleRouteError` maps that Postgres error to a safe 400 as a backstop. Prefer validating at the lookup site so you return a clearer message and server components can call `notFound()` instead of throwing.
+
+For uuid columns (the default PK in `lib/schema.ts`), use `isUuid` / `parseUuid` **at the query**:
+
+```ts
+import { isUuid, parseUuid } from '@assembly-js/app-foundation/server';
+import { notFound } from 'next/navigation'; // server components/pages
+
+// Right before eq(items.id, …) when items.id is uuid:
+const id = parseUuid(rawId);
+if (id instanceof NextResponse) return id;
+const item = await db.query.items.findFirst({ where: eq(items.id, id) });
+
+// Server component / page loading a uuid PK:
+if (!isUuid(id)) notFound();
+```
+
+Do **not** blanket-`parseUuid` every route param. Only guard values that will hit a uuid column. For other column types, validate the shape/range yourself before the query (required fields, enums, numeric bounds) — same idea: reject early with `badRequest` / `notFound`, don't let the database be the first validator.
+
+## Mutation UIs still read `{ error }`
+
+Clients should keep surfacing `body.error` from failed responses — `handleRouteError` and the other helpers use the same `{ error: string }` shape. The fix is what the server puts in that string, not hiding errors from the UI.

package/skills/assembly-semantic-colors/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: assembly-semantic-colors
+description: Use when displaying status badges, alerts, or any UI that communicates state to users. Covers the semantic color variants for Badge and Alert components.
+---
+
+## Semantic color variants
+
+Assembly UI provides four semantic color variants for Badge and Alert: `destructive`, `success`, `warning`, and `info`. Each has a purpose-built background and foreground color pair.
+
+### When to use each variant
+
+| Variant | Meaning | When to use | Example labels |
+|---|---|---|---|
+| `info` | Important information that needs attention | Default choice for status badges — use instead of `default` variant for most status indicators | Running, Open, In transit, Pending, Active |
+| `success` | Positive outcome, no action required | Completed actions, successful states | Success, Paid, Signed, Complete, Verified |
+| `warning` | Something needs attention or action | Problems that require user intervention | Overdue, Inactive, Expiring, At risk |
+| `destructive` | Error or failure state | Errors, failed operations, critical issues | Failed, Rejected, Cancelled, Error |
+
+### Badge
+
+```bash
+export PATH="$HOME/.bun/bin:$PATH" && bunx shadcn@latest add @assembly-ui/badge --yes --overwrite
+```
+
+```tsx
+import { Badge } from "@/components/ui/badge";
+
+<Badge variant="info">Open</Badge>
+<Badge variant="success">Paid</Badge>
+<Badge variant="warning">Overdue</Badge>
+<Badge variant="destructive">Failed</Badge>
+```
+
+Prefer `variant="info"` over `variant="default"` for status badges. The `default` variant (dark background) is for non-semantic labels like categories or tags. Use `secondary` for neutral metadata.
+
+### Alert
+
+```bash
+export PATH="$HOME/.bun/bin:$PATH" && bunx shadcn@latest add @assembly-ui/alert --yes --overwrite
+```
+
+```tsx
+import { Alert, AlertTitle, AlertDescription } from "@/components/ui/alert";
+import { CircleCheck, TriangleAlert, Info, CircleX } from "lucide-react";
+
+<Alert variant="info">
+  <Info />
+  <AlertTitle>New feature available</AlertTitle>
+  <AlertDescription>Dark mode support has been added to your account settings.</AlertDescription>
+</Alert>
+
+<Alert variant="success">
+  <CircleCheck />
+  <AlertTitle>Payment processed</AlertTitle>
+  <AlertDescription>Your payment of $29.99 has been confirmed.</AlertDescription>
+</Alert>
+
+<Alert variant="warning">
+  <TriangleAlert />
+  <AlertTitle>Storage almost full</AlertTitle>
+  <AlertDescription>You have used 90% of your storage. Consider upgrading.</AlertDescription>
+</Alert>
+
+<Alert variant="destructive">
+  <CircleX />
+  <AlertTitle>Payment failed</AlertTitle>
+  <AlertDescription>Please check your payment method and try again.</AlertDescription>
+</Alert>
+```
+
+Match the icon to the variant: `Info` for info, `CircleCheck` for success, `TriangleAlert` for warning, `CircleX` for destructive.
+
+### Key rules
+
+- Status indicators should almost always use a semantic variant — avoid plain `default` badges for statuses
+- Don't use `warning` for informational states or `info` for error states — respect the semantic meaning