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

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

@@ -0,0 +1,103 @@
+---
+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.
+---
+
+`AvatarSub` renders a single nested sub-avatar overlaid at the bottom-right of the parent avatar. It always contains exactly one `Avatar`.
+
+## Install
+
+```bash
+export PATH="$HOME/.bun/bin:$PATH" && bunx shadcn@latest add @assembly-ui/avatar --yes --overwrite
+```
+
+## Pre-built helper
+
+`@assembly-js/app-foundation/client` exports `expandClientsByCompany` — import it, don't rewrite it. It does the row-duplication transform below, and the `/client` subpath means a `'use client'` list component can call it directly.
+
+## 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.
+
+- **0 or 1 company → no sub-avatar.** No disambiguation needed.
+- **2+ companies → one row per company**, each with a single `AvatarSub`.
+
+## 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.
+
+## Row-duplication pattern
+
+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.
+
+```tsx
+import {
+  Avatar, AvatarImage, AvatarFallback, AvatarSub,
+  type FallbackColorType,
+} from "@/components/ui/avatar";
+import { expandClientsByCompany } from "@assembly-js/app-foundation/client";
+
+// Build a lookup map for companies
+const companiesMap = new Map(companies.map(c => [c.id, c]));
+
+// Expand multi-company clients into one row per company
+const rows = expandClientsByCompany(clients);
+
+// Render
+{rows.map(row => {
+  const company = row.displayCompanyId
+    ? companiesMap.get(row.displayCompanyId)
+    : undefined;
+  const name = `${row.givenName} ${row.familyName}`;
+  const initials = `${row.givenName.charAt(0)}${row.familyName.charAt(0)}`;
+
+  return (
+    <div key={`${row.id}-${row.displayCompanyId ?? "none"}`}>
+      <Avatar>
+        <AvatarImage src={row.avatarImageUrl} alt={name} />
+        <AvatarFallback fallbackColor={row.fallbackColor as FallbackColorType}>
+          {initials}
+        </AvatarFallback>
+        {company && (
+          <AvatarSub>
+            <Avatar variant="square">
+              <AvatarImage src={company.iconImageUrl} alt={company.name} />
+              <AvatarFallback fallbackColor={company.fallbackColor as FallbackColorType}>
+                {company.name.charAt(0)}
+              </AvatarFallback>
+            </Avatar>
+          </AvatarSub>
+        )}
+      </Avatar>
+      <span>{name}</span>
+      {company && <span>{company.name}</span>}
+    </div>
+  );
+})}
+```
+
+## Single avatar (no duplication)
+
+When you just need a client or company avatar without the sub-avatar pattern:
+
+```tsx
+// Person avatar (circle)
+<Avatar>
+  <AvatarImage src={client.avatarImageUrl} alt={name} />
+  <AvatarFallback fallbackColor={client.fallbackColor as FallbackColorType}>
+    {initials}
+  </AvatarFallback>
+</Avatar>
+
+// Company avatar (square)
+<Avatar variant="square">
+  <AvatarImage src={company.iconImageUrl} alt={company.name} />
+  <AvatarFallback fallbackColor={company.fallbackColor as FallbackColorType}>
+    {company.name.charAt(0)}
+  </AvatarFallback>
+</Avatar>
+```

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

@@ -0,0 +1,45 @@
+---
+name: assembly-client-users
+description: Use when the app needs to read, list, create, or update client users — the customers of the business that owns the Assembly workspace. Clients sign into the branded Client Portal and see only their own data. Detect via tokenPayload.clientId.
+---
+
+Client users are **customers of the business** that owns the Assembly workspace. They sign into the branded Client Portal at the workspace's domain. They see only their own data — their own messages, their own files, their own invoices.
+
+A client belongs to one or more companies (see `assembly-companies` skill — the relationship is many-to-many).
+
+## Identify the current viewer
+
+```ts
+const payload = await assembly.getTokenPayload();
+if (payload.clientId) {
+  const me = await assembly.retrieveClient({ id: payload.clientId });
+  // ...
+}
+```
+
+(`internalUserId` is set instead for staff — see `assembly-internal-users` skill.)
+
+## SDK methods
+
+- `createClient({ sendInvite, requestBody })` — create + optionally email an invite
+- `listClients({ companyId, email, givenName, familyName, nextToken, limit })` — paged list with optional filters
+- `retrieveClient({ id })`
+- `updateClient({ id, sendInvite, requestBody })` — read `assembly-mutations` skill before calling, the requestBody rule is non-obvious
+- `deleteClient({ id })`
+
+## Companies on a client
+
+A client has `companyIds: string[]` (the canonical many-to-many). The `companyId: string` field is **deprecated since SDK v3.15.0** but still present for backward compat — read it as a fallback only:
+
+```ts
+const ids = client.companyIds ?? (client.companyId ? [client.companyId] : []);
+```
+
+## UI guidance
+
+When the viewer is a client, render a stripped-down view:
+
+- **Hide actions clients can't perform.** Don't show "Create new" buttons for things only staff can create (forms, invoices, contracts) — they'll 403 on click.
+- **Don't list other clients' records.** Filter to `payload.clientId` and `payload.companyIds` everywhere.
+- **Multi-company is the default model.** A client can belong to many companies — read the `assembly-clients-companies` skill for all scoping and company-selector patterns.
+- **Don't conflate with internal-user permissions.** A client can edit their own profile, not other profiles.

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

@@ -0,0 +1,143 @@
+---
+name: assembly-clients-companies
+description: Use when an app stores or scopes data by client or company — record keys, scope filters, company selectors, CRM-tab scoping. Clients belong to MANY companies (client.companyIds[]); a client viewer always carries BOTH a clientId and an active companyId, so scoped tables need both columns and must filter on the intersection; client.companyId (on the client object) is deprecated.
+---
+
+Clients and companies are **many-to-many**: a client belongs to many companies via `client.companyIds: string[]`. In the portal, a client can switch between their companies — the viewer's `companyId` always reflects whichever company they currently have active. Apps that ignore this model show incomplete company pickers, or key and filter records on one dimension and then leak a company-A record into the same client's company-B view. This skill covers how to scope, key, and filter records correctly.
+
+## The viewer identity
+
+```ts
+import { getSessionIdentity } from '@assembly-js/app-foundation/server';
+
+const identity = await getSessionIdentity();
+// → { workspaceId, clientId?, companyId?, internalUserId? } | null
+```
+
+Read identity with `getSessionIdentity()` (server) or `useAssembly()` (client) — see `assembly-session-token`. Never call `assembly.getTokenPayload()` in app code.
+
+**A client viewer always carries both ids.** `identity.clientId` is who they are; `identity.companyId` is the company they currently have active in the portal switcher. The platform guarantees the active company is populated for a client session, so **treat a client viewer with no `companyId` as an error, not as a case to fall back on** — do not widen the query to the client's other companies, and do not substitute `companyIds[0]`.
+
+The three identity combinations an app must handle:
+
+| `clientId` | `companyId` | Who | Scope |
+| --- | --- | --- | --- |
+| set | set | a client in the portal, or a CRM client-record tab | filter on **both** (see Pattern 2) |
+| absent | set | a CRM company-record tab | filter on `companyId` |
+| set | absent | — | error; do not guess a company |
+
+Branching on one id alone mis-reads the viewer: `identity.companyId ? 'company' : 'client'` always takes the company branch for a portal client, because a client carries both.
+
+## The client object
+
+```ts
+const client = await assembly.retrieveClient({ id: identity.clientId });
+client.companyIds; // string[] — full list of companies this client belongs to; use for building the company switcher UI
+client.companyId;  // string — @deprecated since SDK v3.15.0, backward compat only; do not use
+```
+
+`companyIds: string[]` is the authoritative full list. The singular `companyId` on the client object is deprecated and must not be written back in updates (see `assembly-mutations` skill).
+
+## Pattern 1 — company selectors
+
+When the app shows a company picker for the current client, iterate the **full** `client.companyIds[]` — not just the active `companyId`, which is only the currently selected one:
+
+```ts
+const client = await assembly.retrieveClient({ id: identity.clientId });
+const companies = await Promise.all(
+  (client.companyIds ?? []).map((id) => assembly.retrieveCompany({ id }))
+);
+// render ALL of these as picker options; identity.companyId is the currently selected one
+```
+
+Never collapse to `client.companyIds[0]` — this silently hides the client's other companies. And `companyIds[]` is for **rendering the picker only**, never for widening a data query (see Pattern 2).
+
+For the picker UI itself, don't hand-roll a dropdown — use the pre-built `UserCompanySelector` component (see `assembly-user-company-selector` skill) and feed it the companies fetched above.
+
+## Pattern 2 — keying and filtering stored records
+
+**Give every client- or company-scoped table both a `clientId` and a `companyId` column**, nullable, even when a given row populates only one:
+
+```ts
+export const items = pgTable('items', {
+  id: uuid('id').defaultRandom().primaryKey(),
+  clientId: uuid('client_id'),   // null ⇒ the row belongs to the whole company
+  companyId: uuid('company_id'), // the company the row lives under
+  // ...
+});
+```
+
+Two columns is not redundancy — it is what makes scope expressible at all. A row written by a client belongs to *that client within that company*, so both ids are part of its identity. A table with only one of the columns cannot be intersection-filtered later, and there is no way to repair it after the data exists.
+
+How rows are keyed:
+
+- **Client-owned row** — set `clientId` **and** the active `companyId`. Not `clientId` alone: the same client acting under a different company must not see it.
+- **Company-wide row** (shared by everyone in the company) — set `companyId` and leave `clientId` null.
+
+Filter on the **intersection**, never on one dimension:
+
+```ts
+import { and, eq, isNull, or } from 'drizzle-orm';
+
+// identity.companyId is required for a client viewer — see "The viewer identity"
+if (!identity.companyId) throw new Error('Client session has no active company');
+
+const rows = await db
+  .select()
+  .from(items)
+  .where(
+    and(
+      eq(items.companyId, identity.companyId),
+      or(eq(items.clientId, identity.clientId), isNull(items.clientId)),
+    ),
+  );
+```
+
+That reads as: this client's rows **within the active company**, plus the company-wide rows. For an internal user on a company-record surface (`companyId` set, no `clientId`), drop the `clientId` leg and filter on `companyId` alone. For an internal user on the global Dashboard main view (neither id in the token), filter app-owned rows to companies they can access — see `assembly-internal-users` (Client Access). Full-access internal users need no extra company filter on global views.
+
+❌ Wrong — filters on one dimension:
+
+```ts
+// Leaks: a row this client created under company A shows up in their company-B view.
+.where(eq(items.clientId, identity.clientId))
+
+// Leaks: every client in the company sees every other client's rows.
+.where(eq(items.companyId, identity.companyId))
+
+// Leaks: silently scopes to the client's first company, whichever that happens to be.
+.where(eq(items.companyId, client.companyIds[0]))
+```
+
+✅ Right — the `and(company, or(client, isNull(client)))` intersection above.
+
+**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`.
+
+## Pattern 3 — the placeholder pitfall
+
+Assembly **auto-assigns a placeholder company to every client on creation**, so:
+
+```ts
+client.companyIds.length > 0; // ALWAYS true — never a useful signal
+```
+
+You cannot infer "this app should be company-scoped" (or "this client has a real employer") from the presence of `companyIds`. Scope is determined by **explicit app design intent**, never by inspecting `companyIds`. Placeholder companies are excluded from `listCompanies` by default for these apps, so user-facing lists won't show them; pass `isPlaceholder: true` only if you need them (see `assembly-companies` skill).
+
+## Scope-determination rule
+
+1. **Schema:** give the table both a `clientId` and a `companyId` column. Do this even for an app you believe is company-only — it costs one nullable column and is the only decision here that cannot be reversed later.
+2. **Writes:** a client-owned row gets `clientId` + the active `companyId`; a company-wide row gets `companyId` with `clientId` null. Whether a given record is client-owned or company-wide comes from the app's design intent.
+3. **Reads, by viewer identity:**
+   - `clientId` + `companyId` → filter `companyId = identity.companyId AND (clientId = identity.clientId OR clientId IS NULL)`.
+   - `companyId` only → filter on `companyId`.
+   - `clientId` with no `companyId` → error; the platform guarantees an active company for a client session, so do not fall back and do not union across `companyIds[]`.
+4. Never let `companyIds[0]`, `companyIds.length`, or the deprecated `client.companyId` field drive the scope decision **or the filter** — `companyIds[]` builds the picker, nothing more.
+
+## Related skills
+
+- `assembly-companies` — company CRUD, placeholder companies (excluded from `listCompanies` by default for these apps).
+- `assembly-client-users` — identifying the current client viewer and client identity in general.
+- `assembly-session-token` — reading the viewer with `getSessionIdentity()` / `useAssembly()`.
+- `assembly-route-auth` — `requireCompanyScope` for `[id]` route handlers; pass both scope columns there too.
+- `assembly-user-company-selector` — pre-built `UserCompanySelector` component for picker UIs; its `Entity` type still accepts a singular `companyId` for grouping purposes, which is fine for the component API but is not a substitute for `companyIds[]` in scope/storage decisions.

package/skills/assembly-companies/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: assembly-companies
+description: Use when working with Company records — businesses that group Client users. Many-to-many with clients (any number of clients per company; up to ~50 companies per client). Includes placeholder companies that exist for backend logic and should be hidden from end-users by default.
+---
+
+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.
+
+## 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:
+
+```ts
+const ids = client.companyIds ?? (client.companyId ? [client.companyId] : []);
+```
+
+Including the deprecated `companyId` in `updateClient` will trigger a re-assignment that 403s on client tokens — see `assembly-mutations` skill.
+
+## SDK methods
+
+- `createCompany({ requestBody })`
+- `listCompanies({ name, isPlaceholder, nextToken, limit })`
+- `retrieveCompany({ id })`
+- `updateCompany({ id, requestBody })` — see `assembly-mutations` skill
+- `deleteCompany({ id })`
+
+## Placeholder companies — handle deliberately
+
+Some `Company` records have `isPlaceholder: true`. They exist so the platform can attach a company-shaped reference to clients who don't have a real employer (solo customers, individuals). A workspace listing of "Acme Corp, Beta LLC, _placeholder_5fb3a..." — nameless placeholders — is the kind of bug that gets reported by customers as "ghost companies."
+
+**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`.)
+
+### 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:
+
+- Surfacing solo clients (whose only company is a placeholder) — e.g. an app that tracks work against individual customers
+- Admin / reconciliation flows
+- Linking a specific client to their own company record
+
+### Picker / dropdown UIs
+
+When letting a user pick a company (filter, association, etc.), you don't need to filter — `listCompanies` already excludes placeholders for these apps. Don't make the user disambiguate "Real Company" from "Placeholder Company".

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

@@ -0,0 +1,86 @@
+---
+name: assembly-custom-fields
+description: Use any time the app reads or writes a workspace-defined custom field on a Client or Company. Two non-negotiable rules — never hardcode the field key (workspace owners pick their own), and option-bearing values must be arrays (multiSelect is the ONLY option-bearing type, even for single-pick UIs).
+---
+
+## The two non-negotiables
+
+1. **Never hardcode a field `key`.** Workspace owners pick their own keys (`favorite_pizza`, `fav_pizza`, `pizza`, anything). Wrong-guess reads silently return `undefined`; wrong-guess writes silently no-op. Discover dynamically by name.
+2. **Option-bearing values are arrays.** `multiSelect` is the ONLY option-bearing type in Assembly — there's no `singleSelect`, `dropdown`, or `select`. Anything that *looks like* a select is a `multiSelect`. Even single-pick UIs must wrap the value in a one-element array.
+
+## Discovery (server-side)
+
+```ts
+const fieldsRes = await assembly.listCustomFields({ entityType: 'client' });
+const pizzaField = fieldsRes.data?.find(
+  (f) => f.name?.toLowerCase().includes('pizza'), // match user's wording
+);
+if (!pizzaField?.key) {
+  return <div>The "favorite pizza" custom field hasn't been set up yet.</div>;
+}
+
+// For option-bearing fields:
+const optionsRes = await assembly.listCustomFieldOptions({ id: pizzaField.id });
+// optionsRes.data: [{ id, key, label }] — use `key` as the value, `label` for display.
+```
+
+**Match by `name` with a case-insensitive substring of the user's wording.** Don't match on `key` — users know fields by display name, not internal key.
+
+## Read
+
+```ts
+const value = (client.customFields as Record<string, unknown>)?.[pizzaField.key];
+// For multiSelect: value is the option key array, e.g. ['pepperoni'], or undefined / [] if unset.
+```
+
+## Write — value MUST be an array, even single-pick
+
+```ts
+await assembly.updateClient({
+  id: clientId,
+  requestBody: {
+    customFields: {
+      [pizzaField.key]: selectedKey ? [selectedKey] : [],   // ← array, ALWAYS
+    },
+    // ↑ Pass a plain object. Do NOT JSON.stringify() it.
+  },
+});
+```
+
+## Writing an `address` field — structured object, not a flattened string
+
+```ts
+await assembly.updateClient({
+  id: clientId,
+  requestBody: {
+    customFields: {
+      [addressField.key]: {
+        addressLine1: '1 Main St',
+        addressLine2: 'Suite 400',   // optional
+        city: 'Springfield',
+        region: 'IL',
+        postalCode: '62704',
+        country: 'US',
+      },
+    },
+  },
+});
+```
+
+Send the structured object — a bare string is accepted for backwards compatibility with older data, but it collapses to a single `fullAddress` string and loses city/region/postal code/country as separate values. Every property is optional except that the field is only considered set if `country` or `fullAddress` is non-empty; `fullAddress` is derived automatically from the other components if you omit it.
+
+## Symptoms when it goes wrong
+
+| Mistake | What you'll see |
+|---|---|
+| Sent scalar (`'pepperoni'`) for multiSelect | `400 invalid custom field option pepperoni provided for custom field: <key>` |
+| Sent option `label` (`'Pepperoni'`) instead of `key` (`'pepperoni'`) | Same 400 |
+| Hardcoded the wrong field key | Reads return `undefined`; writes silently no-op |
+| `JSON.stringify(customFields)` to satisfy the type | Request silently rejected or field ignored |
+
+## Edge cases
+
+- **Multi-pick UI** (checkbox group): pass full array `[a.key, b.key]`.
+- **Clearing a value**: empty array `[]`, not `null` or `undefined`.
+- **Either `key` or `id` works** as the inner option value — use `key` by convention.
+- Same shape applies to `createClient`, `createCompany`, `updateCompany`.

package/skills/assembly-db-transactions/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: assembly-db-transactions
+description: Use whenever a route handler makes more than one database write. Covers the supported patterns for atomic and non-atomic multi-writes on the neon-http db client.
+---
+
+The `db` exported from `@/lib/db` is a `drizzle-orm/neon-http` client. It is the right driver for this app (stateless HTTP, ideal for Vercel serverless), but it does **not** support interactive transactions.
+
+## Never do this
+
+```ts
+// ❌ WRONG — throws "No transactions support in neon-http driver" and 500s the route.
+await db.transaction(async (tx) => {
+  await tx.update(answers).set({ accepted: false }).where(eq(answers.questionId, questionId));
+  await tx.update(answers).set({ accepted: true }).where(eq(answers.id, answerId));
+});
+```
+
+`db.transaction(...)` is the instinctive reach for "make these writes atomic," but the http driver has no interactive transaction. There is no `tx` object. The call fails deterministically.
+
+## Atomic multi-write → `db.batch([...])`
+
+For "commit A and B together, all-or-nothing," pass an array of statements to `db.batch(...)`. The neon-http driver sends them as a single atomic request — either all succeed or none do.
+
+```ts
+// ✅ RIGHT — atomic accept/unaccept in one round trip.
+await db.batch([
+  db.update(answers).set({ accepted: false }).where(eq(answers.questionId, questionId)),
+  db.update(answers).set({ accepted: true }).where(eq(answers.id, answerId)),
+]);
+```
+
+Each element is an ordinary Drizzle query builder (`db.insert(...)`, `db.update(...)`, `db.delete(...)`) — do **not** `await` them individually; hand the unawaited builders to `db.batch` and await the batch. Anything you'd have put inside a `db.transaction` callback of pure writes goes in the array instead.
+
+## Writes that don't need atomicity → sequential awaits
+
+If the writes are independent and a partial failure is acceptable (e.g. write the row, then bump a counter), plain sequential `await`s are fine — no batch, no transaction:
+
+```ts
+// ✅ RIGHT — no atomicity requirement, just do them in order.
+await db.insert(comments).values({ questionId, body });
+await db.update(questions).set({ lastActivityAt: new Date() }).where(eq(questions.id, questionId));
+```
+
+This is what sibling apps that never hit the transaction footgun do.
+
+## Read-then-conditional-write
+
+`db.batch` cannot branch on a value it reads mid-batch, and there is no interactive transaction to hold a read and a dependent write together. Restructure: **read first, decide in JS, then batch the writes.**
+
+Pass a **tuple literal** to `db.batch([...])` — its type is `[Query, ...Query[]]` (at least one element), so a plain `const writes = []` you `.push()` into does **not** typecheck (`bunx tsc --noEmit` fails). Only reach for `db.batch` when there are genuinely two or more writes; if the branch leaves you with a single write, just `await` it.
+
+```ts
+// ✅ RIGHT — read, compute, then batch (2+ writes) or await (1 write).
+const current = await db.query.answers.findFirst({
+  where: and(eq(answers.questionId, questionId), eq(answers.accepted, true)),
+});
+
+const acceptChosen = db.update(answers).set({ accepted: true }).where(eq(answers.id, answerId));
+
+if (current && current.id !== answerId) {
+  // Two writes must be atomic → batch a tuple literal.
+  await db.batch([
+    db.update(answers).set({ accepted: false }).where(eq(answers.id, current.id)),
+    acceptChosen,
+  ]);
+} else {
+  // Only one write needed → plain await, no batch.
+  await acceptChosen;
+}
+```
+
+The brief window between the read and the batch is acceptable for these apps. **Do not** swap in `drizzle-orm/neon-serverless`, a `Pool`, `pg`, or `postgres.js` to get an interactive transaction — neon-http stays the driver.
+
+## The rule
+
+1. Two or more writes that must be atomic → `db.batch([builder1, builder2, …])` — pass a tuple **literal** (not a pushed-into array), leave the builders unawaited, and await the batch.
+2. Writes with no atomicity requirement → sequential `await`s.
+3. A write that depends on a read → read first, compute in JS, then `db.batch([...])` when the branch yields 2+ writes, or plain `await` when it yields exactly one.
+4. **Never** call `db.transaction(...)` on the `db` from `@/lib/db`, and never switch drivers to get one.

package/skills/assembly-dev-server-logs/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: assembly-dev-server-logs
+description: Use whenever the preview shows a broken page, a 500, or behavior that doesn't match the code — read the dev server's log to see the actual server-side error instead of guessing from the browser.
+---
+
+The `bun dev` process backing the preview has its stdout and stderr redirected to `/tmp/dev-server.log`. This is the only place server-side errors, stack traces, and `console.log`/`console.error` output from route handlers, server actions, and server components show up — none of that reaches the browser.
+
+## When to check it
+
+- The preview shows a blank page, a Next.js error overlay, or a generic 500.
+- A `'use server'` action or route handler isn't behaving as the code suggests it should.
+- Something crashed and you're not sure why before you start changing code.
+
+## How to use it
+
+```bash
+# See recent output
+tail -n 100 /tmp/dev-server.log
+
+# Find the error for a specific route or message
+grep -n "Error" /tmp/dev-server.log
+```
+
+Read or grep the file directly — it's a plain text file on the sandbox's own filesystem, not something fetched over a tool call. The file is truncated and capped automatically, so `tail` always shows recent activity; it does not accumulate forever.
+
+If the log doesn't explain the symptom (e.g. a client-side rendering issue), the problem is likely in the browser, not the server — this file only covers the server side.

package/skills/assembly-forms/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: assembly-forms
+description: Use when the app has multi-field forms that need client-side validation with per-field error messages. Covers react-hook-form + zod + Assembly UI Field component. NOT the Assembly Forms/intake module — for that (surveys, intake) use the SDK's listForms/retrieveForm/requestFormResponse instead.
+---
+
+## Install
+
+```bash
+# Form validation libraries (not in the foundation).
+export PATH="$HOME/.bun/bin:$PATH" && bun add react-hook-form @hookform/resolvers zod
+
+# Assembly UI Field component + Spinner (used in submit button loading state)
+export PATH="$HOME/.bun/bin:$PATH" && bunx shadcn@latest add @assembly-ui/field @assembly-ui/spinner --yes --overwrite
+```
+
+## Field component composition
+
+```tsx
+import { Field, FieldLabel, FieldContent, FieldError, FieldGroup } from "@/components/ui/field";
+```
+
+- `Field` — wrapper for a single form field. Pass `data-invalid={true}` to trigger destructive styling.
+- `FieldLabel` — the label text
+- `FieldContent` — wraps the input element
+- `FieldError` — renders inline validation error text
+- `FieldGroup` — groups multiple fields together
+
+## Example: react-hook-form + zod
+
+```tsx
+'use client';
+
+import { useForm } from 'react-hook-form';
+import { zodResolver } from '@hookform/resolvers/zod';
+import { z } from 'zod';
+import { Field, FieldLabel, FieldContent, FieldError } from "@/components/ui/field";
+import { Input } from "@/components/ui/input";
+import { Button } from "@/components/ui/button";
+import { Spinner } from "@/components/ui/spinner";
+
+const schema = z.object({
+  name: z.string().min(1, 'Name is required'),
+  email: z.email('Invalid email address'),
+  amount: z.number({ error: 'Must be a number' }).positive('Must be positive'),
+});
+
+type FormData = z.infer<typeof schema>;
+
+export function CreateForm({ onSubmit }: { onSubmit: (data: FormData) => Promise<void> }) {
+  const { register, handleSubmit, formState: { errors, isSubmitting } } = useForm<FormData>({
+    resolver: zodResolver(schema),
+  });
+
+  return (
+    <form onSubmit={handleSubmit(onSubmit)} className="space-y-4">
+      <Field data-invalid={!!errors.name}>
+        <FieldLabel>Name</FieldLabel>
+        <FieldContent>
+          <Input {...register('name')} placeholder="Enter name" />
+        </FieldContent>
+        {errors.name && <FieldError>{errors.name.message}</FieldError>}
+      </Field>
+
+      <Field data-invalid={!!errors.email}>
+        <FieldLabel>Email</FieldLabel>
+        <FieldContent>
+          <Input {...register('email')} placeholder="email@example.com" />
+        </FieldContent>
+        {errors.email && <FieldError>{errors.email.message}</FieldError>}
+      </Field>
+
+      <Field data-invalid={!!errors.amount}>
+        <FieldLabel>Amount</FieldLabel>
+        <FieldContent>
+          <Input {...register('amount', { valueAsNumber: true })} type="number" placeholder="0.00" />
+        </FieldContent>
+        {errors.amount && <FieldError>{errors.amount.message}</FieldError>}
+      </Field>
+
+      <Button type="submit" disabled={isSubmitting}>
+        {isSubmitting && <Spinner />}
+        Save
+      </Button>
+    </form>
+  );
+}
+```
+
+## zod v4 — use the v4 API, not v3
+
+The installed zod is v4. Use the v4 idioms below; the v3 forms are deprecated (they still compile but emit warnings and will break on the v5 bump):
+
+- Formats are **top-level**: `z.email()`, `z.url()`, `z.uuid()` — **not** `z.string().email()` / `z.string().url()`.
+- Customize errors with the unified `{ error: '…' }` param — **not** `invalid_type_error` / `required_error` / `{ message: '…' }`.
+- Flatten/format issues with the top-level `z.flattenError(err)` / `z.treeifyError(err)` — **not** `err.flatten()` / `err.format()`. Reading `err.issues` directly is fine.
+- Import from `'zod'` (top-level) — **not** the `'zod/v4'` subpath.
+
+## Key patterns
+
+- `data-invalid={!!errors.fieldName}` on `Field` triggers destructive (red) styling on the label and input border
+- `FieldError` renders the error message text inline below the input
+- Use `zodResolver(schema)` to connect zod validation to react-hook-form
+- Follow the [shadcn react-hook-form pattern](https://ui.shadcn.com/docs/forms/react-hook-form) adapted for Assembly UI's Field components