@assembly-js/app-foundation 0.0.52 → 0.0.54

package/CHANGELOG.md

@@ -14,6 +14,14 @@ A foundation update reads the sections between an app's version and the target:
 from every bullet except `[guidance]`, agent work from the check scripts those `[action]`
 bullets ship. Write `[fix]`, `[behavior]` and `[action]` bullets for the app's owner.
 
+## 0.0.54
+- [new] Add `isAppInstalled` and `getInstalledAppIds`, helpers an app can adopt to check which optional modules are installed in its workspace.
+- [guidance] The build agent is taught to check that a module is installed before relying on features that depend on it.
+
+## 0.0.53
+- [action] A page or server action that calls a helper exported from a client-component file errors for every visitor who opens it; the build now reports the call, and the helper moves to a plain module both sides import.
+- [guidance] Tell the build agent that a helper shared between a server-rendered page and a client component belongs in a plain module, not the client component's file.
+
 ## 0.0.52
 - [guidance] The build agent is told that the CRM tab loads the app's client route as staff, with the client or company of that page in the token, so it renders a staff view scoped to that record instead of the client view or an error. It is also told to send notifications for submissions, status changes, approvals and required alerts even when the request does not mention notifications.
 

package/CLAUDE.md

@@ -167,7 +167,9 @@ Before adding a feature, check whether Assembly already covers it. If it does, *
 
 **Always available (every workspace):** Clients, companies, and custom fields — see "The data model" below. Use them; do not rebuild them. Notification infrastructure (`listNotifications`, `createNotification`, `deleteNotification`, `markNotificationRead`, `markNotificationUnread`) is also always available.
 
-**Optional modules (may or may not be installed in this workspace):** Messages, Files, Contracts, Forms, Billing, Knowledge Base, Tasks, and Notes. Before suggesting one or calling its SDK, confirm it is installed — call `listAppInstalls`. If it is installed, use it through the SDK; do not rebuild it. If it is not installed, do not suggest it, do not plan the app around it, and do not ask the user to install it.
+**Optional modules (may or may not be installed in this workspace):** Messages, Files, Contracts, Forms, Billing, Knowledge Base, Tasks, and Notes. Before suggesting one or building on one, confirm it is installed: gate the feature with `isAppInstalled(assembly, <appId>)` from `@assembly-js/app-foundation/server` and render an honest "<app> isn't installed in this workspace" state when it is false; the plan's module list is the build-time source of truth. If it is installed, use it through the SDK; do not rebuild it. If it is not installed, do not suggest it, do not plan the app around it, and do not ask the user to install it.
+
+**Never ask the user to test a client-facing write (a form request, message, invoice, notification) on a real client.** Suggest a throwaway test client instead, and say before the first test that a form request can't be undone from the app — it can only be removed in the dashboard.
 
 - **Messages** — Direct messaging between staff and clients. SDK groups: Messages, MessageChannels.
 - **Files** — Secure file/folder sharing. *For app-private uploads (attachments, exports) use the storage helpers from `@assembly-js/app-foundation/server` (see the `assembly-storage` skill) instead — Files is only for files the user wants in the portal Files tab.* SDK groups: Files, FileChannels.
@@ -670,6 +672,8 @@ If `tsc --noEmit` is clean and the task says "verify the build", run `bun run bu
 
 `bun run build` also **fails** if any page reads `searchParams.token`. Auth is in the bearer cookie, not the URL — no page (not even a surface entry page) needs it; `getAssembly()` / `getSessionIdentity()` read the bearer. Fix as the error instructs — fetch that page's data via `useServerAction`/`authFetch` instead. Run `bun run check:token-usage` to check it on its own.
 
+`bun run build` also **fails** if server code calls a function it imported from a `'use client'` file — a page, layout, or server action, or any module they import that has no directive, calling a helper that lives next to a client component. The server receives a client reference, not the function, so the page 500s at request time while `tsc` passes. Fix as the error instructs — move the helper to a plain module with no directive that both sides import. Run `bun run check:client-boundary` to check it on its own.
+
 <!-- !feature:app-owned-header -->
 `bun run build` also **fails** if a page route is unreachable — no link, `router.push`, redirect, or header CTA anywhere else points at it. Fix as the error instructs by adding an entry point on a reachable page. Run `bun run check:route-reachability` to check it on its own.
 <!-- /feature:app-owned-header -->
@@ -1474,6 +1478,7 @@ Use `AssemblyBridge.header.*` for breadcrumbs, CTAs, and actions menu. See `.cla
 - ❌ Don't preview a PDF (or any file) in an `<iframe>`, `<embed>` or `<object>` — the portal frame is sandboxed and Chrome won't run its PDF viewer inside it, so the preview renders blank while the build passes. Open the pre-signed URL in a new tab (`assembly-storage` Pattern A) or render pages to a canvas client-side with `next/dynamic` + `ssr: false`.
 - ❌ Don't call a change verified, working, or safe to publish because `tsc --noEmit` and `bun run build` passed — name the checks that ran and the signed-in screens left unopened. See "What a passing build proves" above.
 - ❌ Don't pass a function — or an object that holds one, like a question/field config with `visibleWhen`, `validate`, `render`, or `format` callbacks — as a prop from a server component or page into a `'use client'` component. Props cross that boundary as serialized data, so the render throws `Functions cannot be passed directly to Client Components` and the page 500s for every visitor no matter what the record holds. `tsc --noEmit` and `bun run build` both pass. Keep such a config in a shared module the client component imports itself, or express the logic as data (`{ showWhen: { field: 'entityType', equals: 'llc' } }`) and interpret it client-side.
+- ❌ Don't call a function imported from a `'use client'` file from a server component, layout, or server action — e.g. an answer formatter defined in the client component file that the `/n` notification page also renders. The server gets a client reference, not the function, so the render throws and the route 500s for every visitor; `tsc --noEmit` passes. A `'use client'` file should export only components and hooks; put a shared helper in a plain module (`lib/…`) both sides import. `bun run build` fails on this (`check:client-boundary`).
 - ❌ Don't use `Select` or `Combobox` to pick any Assembly person or organization record (clients, internal users, team members, staff, companies). Always use `UserCompanySelector` — in forms, filters, dropdowns, "assign to" controls, everywhere.
 - ❌ Don't use `Combobox` when the user asks for a "dropdown" or "select" — use `Select`. Only use `Combobox` when the user explicitly needs type-to-search/filter functionality for non-user/non-company data.
 - ❌ Don't manually render the selected value in a `Select` trigger. Use `<SelectValue placeholder="..." />` inside `SelectTrigger` **and** pass `items={options}` to the `<Select>` root — without `items`, Base UI cannot resolve labels and will display raw values (UUIDs) in the trigger. See "Select and Combobox — base-ui differences" for the full pattern.

package/bin/check-client-boundary.mjs

@@ -0,0 +1,304 @@
+#!/usr/bin/env node
+// Fails the build when server code calls a function it imported from a
+// 'use client' module. Next hands server code a client *reference* for every
+// export of such a module: rendering one as JSX is fine, calling one throws
+// ("Attempted to call X() from the server but X is on the client"), and the
+// route answers 500 for every visitor. tsc and `next build` both pass — the
+// module typechecks, and a dynamic page is never prerendered — so the agent's
+// own build is the only gate that sees it before a user does.
+//
+// Server code is found by walking imports from Next's server entry files under
+// app/ (page, layout, route, …) and from 'use server' modules, stopping at the
+// first 'use client' module; everything reached without crossing that line is
+// evaluated on the server. Parsed with the app's own TypeScript, parse-only
+// like scan-routes.mjs (ts.createSourceFile, no Program, no type check): an
+// import is an edge only when it survives to the emitted module, and a finding
+// is a real call, `new`, or tagged template whose callee is an imported
+// binding — never a name inside a string, a comment, or JSX text. A binding the
+// file also declares locally is left alone rather than guessed at. Known
+// limits: a binding re-exported through a barrel, and a helper in a shared
+// module that only client code ever calls, are reported or missed by shape
+// (the fix — a helper in a plain module — is right either way).
+//
+// A finding is a warning on an ordinary turn and fails the build under
+// --strict (the update acceptance) or when ASSEMBLY_TURN_BASELINE_SHA says this
+// turn changed a file involved: the caller, the client file, or any import on
+// the chain that put the caller on the server — a new page that renders an
+// existing shared component makes that component's call run on the server for
+// the first time. A Vercel build or a template clone has no agent who can act
+// on a failure, and the route was already broken, so neither is failed.
+import { readdirSync, readFileSync, existsSync, statSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { createRequire } from 'node:module';
+import { dirname, join, relative, resolve, sep } from 'node:path';
+
+const ROOT = process.cwd();
+const STRICT = process.argv.includes('--strict');
+const APP_DIR = join(ROOT, 'app');
+const SOURCE_DIRS = ['app', 'components', 'lib'];
+const SOURCE_FILE = /\.(tsx|ts|jsx|js|mjs)$/;
+const RESOLVE_EXTENSIONS = ['.tsx', '.ts', '.jsx', '.js', '.mjs'];
+// Next renders or invokes these on the server unless the file opts into the client.
+const SERVER_ENTRY_FILE = /^(page|layout|template|default|loading|not-found|route)\.(tsx|ts|jsx|js)$/;
+// tsconfig's `@/*` → `./*`, the only alias the scaffold defines.
+const PATH_ALIAS = '@/';
+// The turn program exports the SHA the sandbox started this turn at; a finding
+// is the agent's own when a file it involves changed since then.
+const TURN_BASELINE_ENV = 'ASSEMBLY_TURN_BASELINE_SHA';
+
+// Resolved from this file: inside an app it sits in node_modules/ or
+// .assembly/, so this finds the app's own typescript (the one `next build`
+// uses); in this repo it finds the package's devDependency.
+function loadTypeScript() {
+  try {
+    return createRequire(import.meta.url)('typescript');
+  } catch {
+    return null;
+  }
+}
+
+function sourceFiles(dir) {
+  const out = [];
+  if (!existsSync(dir)) return out;
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (entry.name === 'node_modules' || entry.name === '.next') continue;
+      out.push(...sourceFiles(full));
+    } else if (SOURCE_FILE.test(entry.name) && !/\.test\.\w+$/.test(entry.name)) {
+      out.push(full);
+    }
+  }
+  return out;
+}
+
+const toPosix = (file) => relative(ROOT, file).split(sep).join('/');
+
+function resolveImport(fromFile, specifier) {
+  let base;
+  if (specifier.startsWith(PATH_ALIAS)) base = join(ROOT, specifier.slice(PATH_ALIAS.length));
+  else if (specifier.startsWith('.')) base = resolve(dirname(fromFile), specifier);
+  else return null; // a package: not this app's code
+  const candidates = [
+    base,
+    ...RESOLVE_EXTENSIONS.map((ext) => base + ext),
+    ...RESOLVE_EXTENSIONS.map((ext) => join(base, 'index' + ext)),
+  ];
+  for (const candidate of candidates) {
+    try {
+      if (statSync(candidate).isFile()) return candidate;
+    } catch {
+      // not this candidate
+    }
+  }
+  return null;
+}
+
+// 'client' | 'server' | '' — a directive is the file's first statement, which
+// the parser keeps as an expression statement holding the string.
+function directiveOf(ts, sf) {
+  const first = sf.statements[0];
+  if (!first || !ts.isExpressionStatement(first) || !ts.isStringLiteral(first.expression)) return '';
+  const match = /^use (client|server)$/.exec(first.expression.text);
+  return match ? match[1] : '';
+}
+
+// Static imports as the emitted module keeps them. TypeScript drops
+// `import type`, a clause whose specifiers are all `type X`, and the matching
+// `export type … from` forms, so a module reached only that way never runs.
+function staticImports(ts, sf, file) {
+  const imports = [];
+  const edges = new Set();
+  const edge = (specifier) => {
+    const target = resolveImport(file, specifier);
+    if (target) edges.add(target);
+    return target;
+  };
+  for (const st of sf.statements) {
+    if (ts.isImportDeclaration(st) && ts.isStringLiteral(st.moduleSpecifier)) {
+      const clause = st.importClause;
+      if (!clause) {
+        edge(st.moduleSpecifier.text); // side-effect import
+        continue;
+      }
+      if (clause.isTypeOnly) continue;
+      const bindings = [];
+      if (clause.name) bindings.push({ local: clause.name.text, kind: 'default' });
+      const named = clause.namedBindings;
+      if (named && ts.isNamespaceImport(named)) bindings.push({ local: named.name.text, kind: 'namespace' });
+      if (named && ts.isNamedImports(named)) {
+        for (const el of named.elements) if (!el.isTypeOnly) bindings.push({ local: el.name.text, kind: 'named' });
+      }
+      if (bindings.length === 0) continue;
+      const target = edge(st.moduleSpecifier.text);
+      if (target) imports.push({ target, bindings });
+    } else if (ts.isExportDeclaration(st) && st.moduleSpecifier && ts.isStringLiteral(st.moduleSpecifier)) {
+      if (st.isTypeOnly) continue;
+      const clause = st.exportClause;
+      if (clause && ts.isNamedExports(clause) && clause.elements.every((el) => el.isTypeOnly)) continue;
+      edge(st.moduleSpecifier.text);
+    }
+  }
+  return { imports, edges };
+}
+
+// Every call-like use of an identifier (`name(…)`, `name.member(…)`, `new
+// name(…)`, name`…`), every name the file declares itself, and the targets of
+// dynamic `import('…')` — one walk over the tree.
+function walkUses(ts, sf, file, edges) {
+  const calls = [];
+  const declared = new Set();
+  const lineOf = (node) => sf.getLineAndCharacterOfPosition(node.getStart(sf)).line + 1;
+  const visit = (node) => {
+    if (ts.isCallExpression(node) || ts.isNewExpression(node) || ts.isTaggedTemplateExpression(node)) {
+      const callee = ts.isTaggedTemplateExpression(node) ? node.tag : node.expression;
+      if (callee.kind === ts.SyntaxKind.ImportKeyword) {
+        const arg = node.arguments?.[0];
+        if (arg && ts.isStringLiteral(arg)) {
+          const target = resolveImport(file, arg.text);
+          if (target) edges.add(target);
+        }
+      } else if (ts.isIdentifier(callee)) {
+        calls.push({ name: callee.text, member: '', line: lineOf(callee) });
+      } else if (ts.isPropertyAccessExpression(callee) && ts.isIdentifier(callee.expression)) {
+        calls.push({ name: callee.expression.text, member: callee.name.text, line: lineOf(callee) });
+      }
+    } else if (
+      (ts.isVariableDeclaration(node) || ts.isParameter(node) || ts.isBindingElement(node) ||
+        ts.isFunctionDeclaration(node) || ts.isClassDeclaration(node)) &&
+      node.name && ts.isIdentifier(node.name)
+    ) {
+      declared.add(node.name.text);
+    }
+    ts.forEachChild(node, visit);
+  };
+  visit(sf);
+  return { calls, declared };
+}
+
+function readModule(ts, file) {
+  const text = readFileSync(file, 'utf8');
+  const sf = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, false, file.endsWith('x') ? ts.ScriptKind.TSX : ts.ScriptKind.TS);
+  const { imports, edges } = staticImports(ts, sf, file);
+  const { calls, declared } = walkUses(ts, sf, file, edges);
+  return { file, directive: directiveOf(ts, sf), imports, edges, calls, declared };
+}
+
+function isServerEntry(file) {
+  return file.startsWith(APP_DIR + sep) && SERVER_ENTRY_FILE.test(file.split(sep).pop());
+}
+
+// The repo-relative paths this turn changed: commits since the baseline plus
+// whatever is still uncommitted. No baseline means no turn (a Vercel build, a
+// clone bootstrap), so nothing is the agent's to fix. A git failure with a
+// baseline fails closed by treating every file as changed — the sandbox is the
+// one place a finding can still be acted on.
+const EVERY_FILE = { has: () => true };
+function changedThisTurn() {
+  const baseline = (process.env[TURN_BASELINE_ENV] ?? '').trim();
+  if (!baseline) return new Set();
+  const changed = new Set();
+  const listings = [
+    { args: ['diff', '--name-only', `${baseline}..HEAD`], parse: (line) => line },
+    // Porcelain rows are "XY path", or "XY old -> new" for a rename.
+    { args: ['status', '--porcelain', '--untracked-files=all'], parse: (line) => line.slice(3).split(' -> ').pop() },
+  ];
+  for (const { args, parse } of listings) {
+    const result = spawnSync('git', args, { cwd: ROOT, encoding: 'utf8' });
+    if (result.status !== 0) return EVERY_FILE;
+    for (const line of result.stdout.split('\n')) {
+      const file = parse(line).trim();
+      if (file) changed.add(file);
+    }
+  }
+  return changed;
+}
+
+function report(findings, { fatal }) {
+  console.error('');
+  console.error(
+    fatal
+      ? "Server code calls a function exported from a 'use client' file:"
+      : "Server code calls a function exported from a 'use client' file (pre-existing; this build is not failed for it):",
+  );
+  console.error('');
+  for (const f of findings) console.error(`  - ${f.file}:${f.line} calls ${f.name}() imported from ${f.target}`);
+  console.error('');
+  console.error("A module that starts with 'use client' reaches server code as client references,");
+  console.error('not as functions: rendering one as JSX works, calling one throws, and the page');
+  console.error('answers 500 for every visitor. tsc and next build both pass.');
+  console.error('');
+  console.error('Move the helper into a plain module with no directive (lib/<name>.ts) and import');
+  console.error("it from both sides. A 'use client' file should export only components and hooks.");
+  if (fatal) process.exit(1);
+}
+
+if (!existsSync(APP_DIR)) process.exit(0);
+
+const ts = loadTypeScript();
+if (!ts) {
+  // Every scaffolded app depends on typescript; without it there is no parser
+  // and no `next build` either, so there is nothing for this check to guard.
+  console.error('check-client-boundary: typescript is not installed; skipped.');
+  process.exit(0);
+}
+
+const modules = new Map();
+for (const dir of SOURCE_DIRS) {
+  for (const file of sourceFiles(join(ROOT, dir))) modules.set(file, readModule(ts, file));
+}
+
+// Everything reachable from a server entry without crossing into a client
+// module runs on the server. A client module is a boundary, not a node: what
+// it imports is its own business.
+const serverReachable = new Set();
+const queue = [...modules.values()]
+  .filter((m) => m.directive === 'server' || (m.directive !== 'client' && isServerEntry(m.file)))
+  .map((m) => m.file);
+while (queue.length > 0) {
+  const file = queue.pop();
+  if (serverReachable.has(file)) continue;
+  serverReachable.add(file);
+  for (const target of modules.get(file).edges) {
+    const next = modules.get(target);
+    if (next && next.directive !== 'client' && !serverReachable.has(target)) queue.push(target);
+  }
+}
+
+const findings = [];
+for (const file of serverReachable) {
+  const mod = modules.get(file);
+  for (const { target, bindings } of mod.imports) {
+    if (modules.get(target)?.directive !== 'client') continue;
+    for (const binding of bindings) {
+      if (mod.declared.has(binding.local)) continue; // shadowed somewhere in the file
+      const call = mod.calls.find((c) =>
+        c.name === binding.local && (binding.kind === 'namespace' ? c.member !== '' : c.member === ''),
+      );
+      if (!call) continue;
+      const name = call.member ? `${call.name}.${call.member}` : call.name;
+      findings.push({ file: toPosix(file), line: call.line, target: toPosix(target), name });
+    }
+  }
+}
+
+if (findings.length === 0) process.exit(0);
+
+// A finding is the turn's own when the turn wrote the call, the client file, or
+// any link in the import chain that puts the caller on the server. Walk forward
+// from every server-side file the turn changed; what that reaches is the turn's.
+const changed = STRICT ? EVERY_FILE : changedThisTurn();
+const ownedByTurn = new Set();
+const seeds = [...serverReachable].filter((file) => changed.has(toPosix(file)));
+while (seeds.length > 0) {
+  const file = seeds.pop();
+  if (ownedByTurn.has(toPosix(file))) continue;
+  ownedByTurn.add(toPosix(file));
+  for (const target of modules.get(file).edges) {
+    if (serverReachable.has(target) && !ownedByTurn.has(toPosix(target))) seeds.push(target);
+  }
+}
+const own = findings.filter((f) => ownedByTurn.has(f.file) || changed.has(f.target));
+const preexisting = findings.filter((f) => !own.includes(f));
+if (preexisting.length > 0) report(preexisting, { fatal: false });
+if (own.length > 0) report(own, { fatal: true });

package/dist/app-installs.d.ts

@@ -0,0 +1,17 @@
+import type { AssemblyAPI } from '@assembly-js/node-sdk';
+/**
+ * @deprecated Built-in modules are being replaced by generated apps, so this
+ * map will be removed. Prefer an appId you resolved from the workspace; use
+ * these only to gate a feature on a module that still ships built in.
+ */
+export declare const LEGACY_APP_IDS: {
+    readonly messages: "38323633-6465-6132-3730-383065323230";
+    readonly billing: "64346438-6461-6431-6565-366361383434";
+    readonly files: "33343966-3136-6166-6561-343739303432";
+    readonly contracts: "34633033-3365-6561-6332-386434316430";
+    readonly forms: "66666663-3861-6633-3830-323337613065";
+    readonly helpdesk: "30643961-3563-3361-3035-396231663435";
+    readonly tasks: "0e1dff29-1ce3-40ac-b58d-264097f6b319";
+};
+export declare function getInstalledAppIds(assembly: AssemblyAPI): Promise<Set<string>>;
+export declare function isAppInstalled(assembly: AssemblyAPI, appId: string): Promise<boolean>;

package/dist/app-installs.js

@@ -0,0 +1,34 @@
+// Every node-sdk call for install lookups lives in getInstalledAppIds, so the
+// node-sdk namespace migration is a one-line change here and never reaches
+// generated apps.
+/**
+ * @deprecated Built-in modules are being replaced by generated apps, so this
+ * map will be removed. Prefer an appId you resolved from the workspace; use
+ * these only to gate a feature on a module that still ships built in.
+ */
+export const LEGACY_APP_IDS = {
+    messages: '38323633-6465-6132-3730-383065323230',
+    billing: '64346438-6461-6431-6565-366361383434',
+    files: '33343966-3136-6166-6561-343739303432',
+    contracts: '34633033-3365-6561-6332-386434316430',
+    forms: '66666663-3861-6633-3830-323337613065',
+    helpdesk: '30643961-3563-3361-3035-396231663435',
+    tasks: '0e1dff29-1ce3-40ac-b58d-264097f6b319',
+};
+// A disabled install is dropped: it is present in the list but its surfaces and
+// API behave as if the app were not there.
+export async function getInstalledAppIds(assembly) {
+    try {
+        const installs = await assembly.listAppInstalls({});
+        return new Set(installs.filter((i) => !i.disabled && i.appId).map((i) => i.appId));
+    }
+    catch (err) {
+        // Fails closed so a lookup error renders the "not installed" state instead
+        // of throwing into the page.
+        console.error('getInstalledAppIds: listAppInstalls failed', err);
+        return new Set();
+    }
+}
+export async function isAppInstalled(assembly, appId) {
+    return (await getInstalledAppIds(assembly)).has(appId);
+}

package/dist/server.d.ts

@@ -3,6 +3,7 @@ export * from './assembly.js';
 export * from './action-route.js';
 export * from './auth.js';
 export * from './client-access.js';
+export * from './app-installs.js';
 export * from './mint-bearer.js';
 export * from './verify-bearer.js';
 export * from './nango.js';

package/dist/server.js

@@ -7,6 +7,7 @@ export * from './assembly.js';
 export * from './action-route.js';
 export * from './auth.js';
 export * from './client-access.js';
+export * from './app-installs.js';
 export * from './mint-bearer.js';
 export * from './verify-bearer.js';
 export * from './nango.js';

package/package.json

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

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

@@ -9,6 +9,10 @@ description: Use any time the app references a native Assembly message channel,
 
 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.
 
+## Check the app is installed first
+
+Gate any feature that depends on another app with `isAppInstalled(assembly, <appId>)` from `@assembly-js/app-foundation/server`, and show an honest "<app> isn't installed in this workspace" state when it is false. It works the same for core, marketplace and custom apps.
+
 ## Discovering a form
 
 A form's display name is on `fields`, not on the form itself. Walk every page — matching by name against only the first page reports the form as missing once the workspace has more than a page of forms:
@@ -31,6 +35,8 @@ await assembly.requestFormResponse({
 });
 ```
 
+**Testing a form request:** never ask the user to send one to a real client. Suggest a throwaway test client, and say before the first test that a request can't be undone from the app — it can only be removed in the dashboard.
+
 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