@lotics/app-sdk 0.46.1 → 0.47.0

package/docs/files.md

@@ -0,0 +1,312 @@
+# Files
+
+Files end to end in a custom-code app: uploading bytes (`useFileUpload`), composer attachments
+with instant previews (`useAttachments`), decoding `files` cells from query results (`readFiles` →
+`AppFile`), documents a workflow generates (`WorkflowResult.files`), previewing with `@lotics/ui`,
+filtering on files fields, and the server-side delivery bounds that decide whether a file-bearing
+query succeeds at all. Read this before building any screen that shows, collects, or generates
+files. Query mechanics (projection, unnest, aggregates) live in [queries](./queries.md); fetching
+discipline in [data fetching](./data_fetching.md).
+
+## The lifecycle in one table
+
+| Stage | Surface | What you hold |
+|---|---|---|
+| Collect bytes from the visitor | `useFileUpload().upload(file)` | `UploadedFile` — a stored, **unattached** file id + presigned serving URLs |
+| Collect several with live previews | `useAttachments()` | `AttachedFile[]` with instant local previews; `fileIds` when done |
+| Attach to a record | a declared workflow with a `{ type: "file" }` input | the workflow writes the id(s) into a `files` field — the **only** write path |
+| Read back from records | `useQuery` + `readFiles(cell)` | `AppFile[]` — presigned `url`/`thumbnail_url` (24 h) + `size`/`created_at` |
+| Receive a generated document | `useWorkflow` → `WorkflowResult.files` | presigned files auto-extracted from the run |
+| Show it | `@lotics/ui` `FileThumbnail` / `FileGrid` / `FileGalleryModal` | map to `DisplayFile` (see below) |
+| Save browser-built bytes | `downloadFile(filename, data, mimeType?)` | a client-side download (see [runtime](./runtime.md)) |
+
+An uploaded file is **inert until a workflow attaches it** — it has an id and serving URLs, but
+belongs to no record. There is no direct-write path from app code; attaching goes through a
+declared workflow (see [mutations](./mutations.md)).
+
+## Uploading — `useFileUpload`
+
+```tsx
+const { upload, uploading, error } = useFileUpload();
+const submit = useWorkflow("submitOrder");
+
+const photo = await upload(file);            // File → UploadedFile
+await submit({ ...fields, photo_file_id: photo.id });
+```
+
+Signature: `dist/src/hooks.d.ts`. Returns `{ upload, uploading, error }`:
+
+- `upload(file: File): Promise<UploadedFile>` — resolves to the stored file; rejects on failure
+  (the file is never partially stored). `UploadedFile` is
+  `{ id, filename, mime_type, url?, thumbnail_url? }` — `url`/`thumbnail_url` are presigned
+  (24 h) and load directly in the sandboxed iframe, so a just-uploaded image previews without a
+  round-trip.
+- `uploading` — true while **any** upload from this hook is in flight.
+- `error` — message of the most recent failed upload; cleared when a new one starts.
+
+Works identically in a member-facing (embedded) app and a public (anonymous) app — the gate is
+use-access to the app itself.
+
+### What `upload` does under the hood
+
+The pipeline is: optimize (images only) → mint a presigned upload URL → `PUT` the bytes straight
+to object storage → finalize. The API server never proxies the bytes.
+
+- **Image optimization.** JPEG/PNG/WebP/HEIC/HEIF images larger than 1280 px on the long edge are
+  resized to ≤1280 px and re-encoded as JPEG at quality 0.75 before upload — phone photos
+  typically shrink 10–20×. Non-image files pass through unchanged, and any optimization failure
+  falls back to uploading the original bytes (never an upload error).
+  **Warning:** PNG/WebP/HEIC/HEIF larger than 1280 px on the long edge are *converted to JPEG* —
+  transparency is lost and the stored filename's extension becomes `.jpg`. If you need lossless
+  originals, keep images ≤1280 px or upload them as non-image MIME types.
+- **Transport resilience.** The storage `PUT` has a 5-minute per-request timeout and retries
+  network errors / timeouts / 5xx up to 3 attempts with 1 s → 2 s backoff between attempts. 4xx
+  responses are terminal (no retry). The presigned upload URL itself is valid for 10 minutes.
+- **Server-side verification.** The finalize step verifies the actually-stored object: an object
+  larger than the limit (or of unverifiable size) is rejected **and its bytes deleted** — the
+  file record is never created.
+
+### Upload limits
+
+| Bound | Value |
+|---|---|
+| Max file size | 25 MiB (26,214,400 bytes) — enforced at URL mint *and* re-verified at finalize |
+| Allowed MIME types | **any** — type is unrestricted at upload |
+| Upload-URL validity | 10 minutes |
+
+Any MIME is safe to accept because serving is hardened downstream: HTML, XHTML, and SVG are always
+served with `Content-Disposition: attachment` (forced download) on every path, so an uploaded file
+can never execute as active content. See [security](./security.md).
+
+### File workflow inputs
+
+Declare the receiving workflow input as `{ type: "file" }` (body receives one `FileId`) or
+`{ type: "file", multi: true }` (body receives `ReadonlyArray<FileId>`, directly assignable to a
+`files` field — the way to attach several uploads to one record). Files cells are arrays, so the
+workflow body writes a single-id input by wrapping it itself — `some_files_field: [inputs.photo]`
+— a bare id is rejected at the write.
+
+File ids are validated at execute time: a `file` input must reference a file in the app's own
+workspace, or the run is rejected — you cannot attach a foreign or fabricated id.
+
+For **agent** aliases the same `file` inputs are materialized into the model's vision: images
+become image parts, PDFs file parts; other types stay an id the agent opens with its own tools.
+Pair `useFileUpload` with `useAgentRun` for photo→extraction flows — see [ai](./ai.md).
+
+## Composer attachments — `useAttachments`
+
+The optimistic-preview UX in one hook: a local object-URL preview shows the *instant* a file is
+added, the upload runs in the background (through the same `useFileUpload` pipeline, image
+optimization included), and the stored `file_id` lands when it completes. Don't hand-roll the
+`createObjectURL` → upload → id → revoke lifecycle per app.
+
+```tsx
+const { files, add, remove, clear, uploading, fileIds } = useAttachments();
+const design = useWorkflow("design");
+
+// attach: picking is the app's choice — button, paste, or drop
+<Button icon="paperclip" onPress={() => pickFiles({ accept: "image/*" }).then(add)} />
+
+// preview: map each AttachedFile to a @lotics/ui DisplayFile (snake → camel)
+{files.map((f) => (
+  <FileThumbnail
+    key={f.id}
+    file={{ id: f.id, filename: f.filename, mimeType: f.mime_type, url: f.preview_url }}
+    uploading={f.status === "uploading"}
+    onRemove={() => remove(f.id)}
+  />
+))}
+
+// send: gate on `uploading`, payload is `fileIds`
+await design({ photos: fileIds });   // multi:true input
+clear();
+```
+
+Contract (`dist/src/hooks.d.ts`):
+
+| Member | Behavior |
+|---|---|
+| `files: AttachedFile[]` | Current attachments, in the order added |
+| `add(files: File[])` | Each file shows its local preview at once and uploads in the background |
+| `remove(id)` | Removes one attachment and revokes its preview object-URL |
+| `clear()` | Removes all and revokes every preview URL |
+| `uploading` | True while any attachment is still uploading — gate Send on it |
+| `fileIds: string[]` | Stored file ids of the **completed** uploads — the workflow/agent payload |
+
+Each `AttachedFile` is `{ id, filename, mime_type, preview_url, status, file_id? }`:
+
+- `id` — a stable *local* id (the React key and the `remove(id)` handle), **not** the stored file
+  id.
+- `preview_url` — a local object-URL, available before the upload finishes. Revoked on
+  remove/clear — don't hold it past the attachment's lifetime.
+- `status` — `"uploading" | "ready" | "error"`. A failed upload stays in `files` with
+  `status: "error"` (and no `file_id`); there is no auto-retry — offer remove + re-add.
+- `file_id` — the stored id, set once `status` is `"ready"`. `fileIds` includes only ready
+  entries, so sending while `uploading` is true would silently drop in-flight files — gate on it.
+
+Wiring to `@lotics/ui`: in a `Composer`, trigger picking from `actionsButton` (via `pickFiles`),
+render the attachment pills with `FileThumbnail` as above, and gate `sendDisabled` on `uploading`.
+For a full add-files *screen* (not a composer pill), map each `AttachedFile` to a `FileGrid`
+`FileUpload` entry — ready → `{ status: "complete", id: file_id, file: <DisplayFile> }`, else
+`{ status, id, filename, mimeType: mime_type, previewUrl: preview_url }` — and `FileGrid` renders
+the uploading/error/retry tiles itself.
+
+## File cells in query results — `readFiles` and `AppFile`
+
+A projected `files` column arrives as an array of file objects, and the server enriches **every
+file-shaped value anywhere in the result rows** at read time:
+
+- `url` — a presigned serving URL, valid **24 hours**, anonymous-fetchable. Loads directly from
+  the sandboxed app iframe and for public-app visitors — no session, no proxy, no URL derivation.
+- `thumbnail_url` — a presigned small-variant URL, emitted for every image.
+- `size` (bytes) and `created_at` (ISO upload timestamp) — resolved from the file object at
+  serving time, batch-loaded per response.
+
+Decode with `readFiles(cell)` → `AppFile[]` (`dist/src/row.d.ts`):
+
+| Field | Type | Notes |
+|---|---|---|
+| `id` | `string` | The stored file id |
+| `filename` | `string` | Original filename (post-optimization name for converted images) |
+| `mime_type` | `string` | |
+| `url` | `string` | Presigned serving URL — render, or pass to `openExternal` |
+| `thumbnail_url` | `string?` | Presigned image thumbnail (see the 404 note below) |
+| `size` | `number?` | Byte size — **absent on older files not yet backfilled**; render only when present |
+| `created_at` | `string?` | ISO upload timestamp |
+
+`readFiles` skips entries the server didn't presign (no `url`), so you never render an unservable
+file. It is pure and never throws.
+
+- **Thumbnails are optimistic.** `thumbnail_url` is emitted for every image without checking that
+  the variant exists; a not-yet-generated variant 404s on fetch. `@lotics/ui`'s `FileThumbnail`
+  falls back to `url` on image error — a hand-rolled `<img src={thumbnail_url}>` must do the same.
+- **Don't persist the URLs.** They expire in 24 h. Apps re-query on load, so the TTL refreshes
+  naturally; store `id`s, never `url`s.
+- **Warning:** SVG, HTML, and XHTML files are presigned with a forced-download disposition — their
+  `url` downloads instead of rendering inline (stored-XSS defense). An SVG in an `<img>` will not
+  display; treat these types as download-only.
+- **Display convention:** surface `size` and `created_at` as dedicated, sortable `Table` columns
+  over the **raw** values (right-aligned Size formatted at display; Added via a date formatter) —
+  not a crammed meta string, which sorts wrong (`"8.4 MB" < "96 KB"` lexically).
+
+## The presign ceiling — project files only where rendered
+
+Every file entry in a query response costs server-side signing work (1–2 signings per entry,
+duplicates included). The server counts file entries **before** signing and fails the whole
+request when the count exceeds the per-response ceiling (**2,000 file entries** by default) with
+an actionable error:
+
+> Query "…" returned N file entries, above the 2000-entry ceiling for signed file URLs per
+> response. Project the files column only in the query that renders it, narrow the result with a
+> filter, or paginate with limit/offset.
+
+The request fails whole — no partial or unsigned rows — and surfaces as the hook's `error`.
+Design around it:
+
+- **Project `files` columns only in the query that renders them.** A bare `from_table` with no
+  `project` ships every column — including `files` — so a wide list query over a file-heavy table
+  hits the ceiling (and over-exposes storage metadata). Keep list queries file-free; fetch files
+  in the detail query for the selected row.
+- **Paginate.** The row `limit` defaults to the server's 10,000-row cap; a files projection at
+  that size is thousands of entries. `usePaginatedQuery`/`useInfiniteQuery` with a modest page
+  size keeps each response far under the ceiling.
+- **Push counts and per-file analysis into the query.** You never need the file *objects* to
+  count them: `has_file_count`/`is_empty` filters, the `filled`/`empty`/`percent_*` aggregates,
+  and the `unnest` node (one output row per file, emitting the file **id** as text; `keep_empty`
+  preserves zero-file rows) are all evaluated server-side without triggering any presigning. See
+  [queries](./queries.md).
+
+**Warning:** an aggregate `unique` over a files column counts distinct whole cells (file *sets*),
+not distinct files — per-file distinct counts go through `unnest` first.
+
+Emptiness is one contract everywhere: a cleared files cell persists as `[]` and counts as empty in
+`is_empty` filters **and** in the `filled`/`empty`/`percent_*` aggregates.
+
+## Workflow-returned files — `WorkflowResult.files`
+
+When a workflow run completes, the platform scans the run's completed tool-call steps and
+auto-extracts every output carrying a string `file_id` (document-generation tools emit these),
+dedupes them, and returns them on the execute response as `WorkflowResult.files?: UploadedFile[]`
+— each presigned with the same 24 h TTL as query file cells. A run that produced no file resolves
+with `files` absent.
+
+```tsx
+const generate = useWorkflow("generateInvoice");
+const result = await generate({ record_id: row.__source_record_id });
+if (result.status === "success" && result.files?.length) {
+  await openExternal(result.files[0].url);
+}
+```
+
+- **Don't hand back a `url` or `file_id` via `return({ data })`** — extraction is automatic, and
+  the extracted entry is presigned while a hand-returned id is not.
+- The presigned URLs work for **anonymous public-app viewers** — a public visitor can download a
+  document the workflow generated for them.
+- `openExternal(url)` is the way to open one: the embedded iframe is sandboxed without popups, so
+  a direct `window.open` is silently dropped; `openExternal` routes the open to the host
+  (scheme-validated, `http`/`https` only).
+- For bytes the app builds *in the browser* (a client-side .xlsx/CSV export), the counterpart is
+  `downloadFile(filename, data, mimeType?)` — see [runtime](./runtime.md).
+
+## Previewing — wiring to `@lotics/ui`
+
+Render any file inline — image, PDF, video, audio, Word, Excel, CSV — with `@lotics/ui`. Never
+hand-roll per-type rendering, and don't use `openExternal` as a preview (that's "open elsewhere",
+not viewing). Component contracts live in the `@lotics/ui` reference
+([`../../ui/AGENTS.md`](../../ui/AGENTS.md)); the SDK-side contract is only the data mapping:
+
+| `AppFile` (SDK) | `DisplayFile` (`@lotics/ui`) |
+|---|---|
+| `id` | `id` |
+| `filename` | `filename` |
+| `mime_type` | `mimeType` |
+| `url` | `url` |
+| `thumbnail_url` | `thumbnailUrl` |
+
+For an `AttachedFile` still uploading, map `preview_url` → `url` (there is no server URL yet).
+The app owns this data→UI adapter — the SDK deliberately never imports `@lotics/ui`.
+
+- **`FileThumbnail`** — one square tile; `uploading` overlays a spinner, images fall back from
+  `thumbnailUrl` to `url` on error.
+- **`FileGrid`** — a grid of completed files plus a live `uploads` queue (it renders
+  uploading/error/retry tiles itself).
+- **`FileGalleryModal`** — the full-screen viewer (filename · counter · actions · close, with
+  prev/next + ESC), delegating per-file to **`FilePreview`**, which dispatches by MIME. Wire
+  `onFilePress` → a `number | null` `activeIndex`.
+- PDF renders **inline to a canvas** (a nested PDF browsing context is blocked in the sandboxed
+  iframe; a canvas isn't). The PDF, Word, and Excel/CSV engines ship as `@lotics/ui`
+  dependencies — no separate install — and are lazy-loaded, so apps that never preview a type pay
+  no bundle cost.
+- The gallery's "open in new tab" action can't pop a window in the sandbox — pass
+  `onOpenExternal` wired to the SDK's `openExternal` (omit it and the action hides).
+
+## Filtering on files fields
+
+Files fields support these operators — in the query template's `from_table.filter` **and** in the
+runtime `filter` option over a projected files output column:
+
+| Operator | Value | Matches records where… |
+|---|---|---|
+| `is_empty` | — | the cell is absent or cleared (`[]`) |
+| `is_not_empty` | — | at least one file is attached |
+| `has_file_count` | numeric string (`"2"`) | **exactly** that many files are attached (no more/fewer-than variants) |
+| `has_filename` | string | any attached file's filename contains the term (case-insensitive substring) |
+| `has_mime_type` | string | any attached file's MIME type contains the term (e.g. `"image/"`, `"pdf"`) |
+
+- Values are **strings at both layers** — a JSON number for `has_file_count` fails validation;
+  send the count as a string. An empty/absent search term or a non-numeric count string makes the
+  condition constrain nothing.
+- Membership operators (`has_any_of`/`has_all_of`/`has_none_of`) are **not** valid on files
+  columns — the runtime layer rejects them explicitly.
+- The emptiness contract is uniform: cleared `[]` cells count empty at both layers (the runtime
+  layer additionally treats a JSON `null` produced by a derived column as empty).
+- **Limitation:** the runtime `filter`/`sort` options reach the server only on the embedded
+  transport; a standalone public app's transport sends only `alias`/`params`/`limit`/`offset`.
+  For public apps, put files predicates in the query template (parameterized where needed). See
+  [data fetching](./data_fetching.md).
+
+## Files and free-text search
+
+`from_table.search` (the record-level free-text search) does **not** match file cells — the
+indexed search document excludes files (and booleans) by design. To find records by an attached
+file's name or type, filter with `has_filename` / `has_mime_type` instead.

package/docs/members_and_options.md

@@ -0,0 +1,307 @@
+# Members & select options
+
+How an app renders and picks **people** and **select-field options**, plus the **record comments**
+surface. Covers the two cell readers (`readSelect`, `readMembers`), the two catalog hooks
+(`useFieldOptions`, `useMembers`), the viewer identity hook (`useViewer`), comments
+(`useComments`, `useCommentCounts`), and the `@lotics/ui` components they feed. Read this before
+building an assign picker, a colored status badge, a per-viewer ("my records") screen, or a
+comment thread. Query mechanics live in [queries](./queries.md); the authority model in
+[security](./security.md).
+
+## Cells vs. catalogs — the model
+
+Every select and member value reaches the app in one of two shapes, and most screens need both:
+
+| You need | Reach for | What it carries |
+| --- | --- | --- |
+| Render a stored select value | `readSelect(cell)` | The options the record actually holds — `{ key, label }`, **no color** |
+| Populate a select picker, or color a stored value | `useFieldOptions(alias)` | Each select column's **complete** option list — `{ key, label, color }` — plus a `byKey` index |
+| Render a stored member value | `readMembers(cell)` | The members the record actually holds — `{ id, name, email? }`, **no avatar** |
+| Populate a member picker (assign UIs) | `useMembers(opts?)` | The org roster — `{ id, name, email, image }` (avatar included) |
+
+Cells are **self-describing**: the server rewrites raw storage shapes into resolved objects before
+rows reach the app, so an app never maintains a hardcoded key→label or id→name map. Catalogs are
+**complete**: they come from live field config / the member directory, so a freshly added option or
+member appears without an app change.
+
+## Select option cells (`readSelect`)
+
+A `select` column's storage shape is a bare array of option keys. The server rewrites every
+projected `select` cell to `Array<{ key, label }>` before the row reaches the app:
+
+- **`label`** comes from the column's source field's option config. An option deleted after the
+  cell was written resolves with `label` equal to the key — the stale state is visible, not hidden.
+- **Heterogeneous UNION outputs still resolve.** When a query UNIONs arms whose select columns come
+  from different tables/fields, each row's labels resolve from that row's own source field. Only a
+  *genuinely computed* select column (no source field at all) keeps bare keys.
+- **Order** is the cell's own stored order.
+
+Decode with **`readSelect(cell)`** (`dist/src/select.d.ts`) → `ResolvedOption[]`:
+
+- Returns `[]` for `null`/`undefined`/empty cells and for any unexpected shape — iterate without
+  null-checks.
+- A bare-string entry (an unresolvable column's key) becomes `{ key, label: key }`, so single-value
+  reads still work.
+- Malformed entries are dropped, never returned partially.
+
+**Limitation:** a cell never carries `color`. `ResolvedOption.color` is optional and populated only
+by `useFieldOptions` — to render a stored value with its configured color, pair the two (idiom
+below).
+
+## The full option set: `useFieldOptions(alias)`
+
+The picker companion to `useQuery` (`dist/src/hooks.d.ts`). Where a cell carries only the options a
+record holds (key + label), this resolves each select **output column's complete option list with
+colors**, straight from field config — so it populates a dropdown, colors stored values, and picks
+up table edits with no app change.
+
+```tsx
+const { fields } = useFieldOptions("orders");   // same alias you query
+// populate + color a picker (Select is @lotics/ui's rich select; its options
+// are { value, label }, so map the option key to `value`):
+<Select
+  options={(fields.status?.options ?? []).map((o) => ({ value: o.key, label: o.label }))}
+  renderOptionContent={(o) => <OptionBadge value={fields.status?.byKey(o.value)} />}
+  value={status} onValueChange={setStatus}
+/>
+```
+
+### What comes back
+
+`fields` is a `Record<outputColumnName, FieldOptions>` — keyed by the query's **output column
+name**, not the field key. Each `FieldOptions`:
+
+| Property | Meaning |
+| --- | --- |
+| `label` | The source field's display name — a ready picker/section label |
+| `options` | Every option of the field — `{ key, label, color }` — in field-config order, **including options not present in any current row** |
+| `byKey(key)` | Resolve one option by key; `undefined` for an unknown key (option removed after the cell was written) |
+
+- `color` is a named palette token (e.g. `"blue"`, `"emerald"`). Pass the option straight to
+  `@lotics/ui`'s `OptionBadge`; a missing/unrecognized token degrades to a neutral badge.
+- **A column the server can't map to a single source select field is simply absent** from
+  `fields` — a UNION output whose arms disagree on the source field, or a computed column. Read
+  defensively: `fields.status?.options ?? []`.
+- Addressed by the same alias you query, and scoped exactly like running that query — it exposes
+  nothing the query itself doesn't. Params are irrelevant (they only fill filter values, never
+  change the projection), so no params argument exists.
+- Works in embedded **and** standalone/public apps.
+
+### Caching & freshness
+
+Field config is slow-changing, so the hook fetches once per alias and does **not** revalidate on
+window focus or reconnect. The option set is resolved live from field config at fetch time — an
+option added, renamed, or recolored in the table flows through on the next fetch (a remount, a full
+reload, or an explicit `refetch()`), with no app redeploy. `opts.enabled` defers the fetch (e.g.
+until an edit drawer opens). State: `{ fields, loading, isValidating, error, refetch }`.
+
+### Coloring a stored value (the `byKey` idiom)
+
+```tsx
+const opt = readSelect(row.status)[0];
+<OptionBadge value={opt ? (fields.status?.byKey(opt.key) ?? opt) : null} />
+```
+
+`byKey` hit → the configured color. `byKey` miss (option removed post-write) → fall back to the
+cell's own `{ key, label }`, which renders as a neutral badge. Never hand-map option key → color.
+
+## Member cells (`readMembers`)
+
+A `select_member` column's storage shape is a bare array of member ids. The server rewrites every
+projected `select_member` cell to `Array<{ id, name, email? }>`:
+
+- **`email` is present only for authenticated members of the app's own organization.** Anonymous
+  visitors to a public app — and members of *other* orgs viewing a publicly shared app — get
+  `{ id, name }` only. No PII crosses to viewers outside the org.
+- **An id that no longer resolves** (removed member, id outside the org) comes back as
+  `{ id, name: null }` — an explicit missing state, never an empty string. Render a placeholder.
+- **Cells never carry the avatar.** `ResolvedMember.image` exists only on the `useMembers` roster;
+  avatar URLs are presigned files and stay in that one bounded list rather than being fattened onto
+  every query cell.
+- Only ids already present in the projected rows are resolved — a member cell never exposes the
+  wider directory.
+
+Decode with **`readMembers(cell)`** (`dist/src/members.d.ts`) → `ResolvedMember[]`. Same defensive
+contract as `readSelect`: `[]` for null/empty/unexpected cells, malformed entries dropped.
+
+## The org roster: `useMembers(opts?)`
+
+The candidate set for an "assign to a member" picker (`dist/src/hooks.d.ts`):
+
+```tsx
+const { members, loading, error } = useMembers({ group: "grp_fulfillment" });
+<MemberSelect members={members} value={assignee} onValueChange={setAssignee} />
+```
+
+Each member is `{ id, name, email, image }`. `image` is the avatar URL (a presigned URL valid 24
+hours, or the member's external OAuth photo) and may be `null`. `name` may be null/empty for
+members without a display name — fall back to `email`. On failure the hook does not throw: it
+resolves `{ members: [], loading: false, error }`.
+
+**Limitation:** `useMembers` is not SWR-cached — every mounted hook instance issues its own
+request. Call it once near the top of the screen and pass the roster down; don't call it per row.
+
+### Access gates (when it errors)
+
+A member roster (with emails) must not leak through an arbitrary app, so the call is gated. All
+three gates are observable as an `error` on the hook:
+
+1. **Members-only, same-org.** The viewer must be an authenticated member of the app's own
+   organization. Anonymous visitors (every standalone/public app view) and members of other orgs
+   get an error. In `lotics app dev` the call runs under the owner's key and succeeds.
+2. **Declared member access.** The app must declare that it works with members: at least one
+   workflow input **or** query param of `{ "type": "member" }` in its manifest. An app with no
+   member declaration gets: *"This app has not declared member access — listing members requires a
+   declared workflow `member` input or query `member` param."* Member access is a declared,
+   auditable surface, like queries and workflows.
+3. **Declared groups only.** `{ group: "grp_…" }` restricts the roster to one member group — but
+   only a group declared on some member input's `group` property. An undeclared group errors; an
+   app can only enumerate groups it actually assigns into. A declared group with no members
+   resolves to `{ members: [] }`.
+
+```jsonc
+// package.json → "lotics" — the declaration that unlocks useMembers
+"workflows": {
+  "assignOrder": {
+    "workflow_id": "wfl_x",
+    "inputs": {
+      "record_id": { "type": "record_link", "table_id": "tbl_orders" },
+      "assignee":  { "type": "member", "group": "grp_fulfillment" }
+    }
+  }
+}
+```
+
+The same `group` declaration also constrains what the workflow **accepts** at execution — a
+submitted member outside the group is rejected server-side (see [mutations](./mutations.md)).
+
+### Per-viewer apps: resolve people from cells, not the roster
+
+A per-viewer app — queries scoped by the `is_current_member` operator, no member inputs — fails
+gate 2 **by design**: its viewer has no business enumerating the whole org. **Do not add a dummy
+member param to unlock `useMembers`.** Resolve people from the viewer's own rows instead: project
+the `select_member` field in the query, and the cell already carries the name.
+
+```tsx
+// No useMembers. The projected cell is the member source.
+{readMembers(row.assignee).map((m) => (
+  <MemberChip key={m.id} name={m.name ?? "—"} />
+))}
+```
+
+Names render; only the avatar photo is unavailable (`MemberChip` falls back to initials). This
+respects the privacy boundary the gate enforces. If a chip renders blank, fix the query projection
+(project the member field) — never widen the manifest to "fix" it.
+
+## `useViewer()` — display-only identity
+
+`useViewer()` (`dist/src/viewer.d.ts`) → `{ memberId, loading }` — the signed-in member currently
+viewing the app. Under an admin's "View as" (product UI or `lotics app dev --view-as`) it returns
+the **view-as target**. It is `null` for a standalone/public visitor, and until the context
+resolves — gate viewer-dependent UI on `loading`.
+
+Use it to **personalize**: greet the member, default an assignment picker to them.
+
+**Never use it as an authorization fact or for data scoping.** Per-row scoping belongs in the query
+template via the `is_current_member` filter operator — the server binds the same viewer (honoring
+view-as) with nothing client-supplied to spoof. Write attribution belongs server-side in the
+workflow body (`runtime.triggered_by_member_id`). Full model: [security](./security.md).
+
+## Comments: `useComments` / `useCommentCounts`
+
+Record comments — member-to-member discussion attached to any record the app reaches
+(`dist/src/comments.d.ts`).
+
+### Enabling comments
+
+Opt in via the manifest; the flag syncs on deploy:
+
+```jsonc
+// package.json → "lotics"
+"capabilities": { "comments": true }
+```
+
+Both hooks expose **`available`** — `true` only when a member is signed in **and** the app declared
+the capability. Gate the composer on it. When `false` (any standalone/public app view, or an app
+that didn't opt in) lists stay empty, `loading` settles to `false`, and every mutation rejects —
+client-side up front, and re-checked server-side.
+
+### Authority & attribution
+
+- **Access runs under the app, not the member's table IAM.** A member who can use the app (and the
+  app declares `comments`) may read/write comments on any record the app's workspace holds,
+  regardless of their own table access. The one floor: the record must live in the app's own
+  workspace — a crafted foreign `record_id` errors.
+- **The author is always the real signed-in member** — correct attribution, enforced server-side.
+  **Warning:** under "View as", comments still author as the real member (the admin), not the
+  view-as target — unlike `useViewer` and `is_current_member` scoping, which follow the target.
+- **Edit and delete are author-only**, checked server-side against the viewer. `CommentList`'s
+  `currentMemberId` prop drives the matching affordance client-side.
+
+### Reading & writing
+
+```tsx
+const { comments, available, createComment } = useComments({
+  record_id: row.__source_record_id,
+});
+```
+
+`record_id` comes from the row's `__source_record_id` addressing column (see
+[queries](./queries.md)). State: `{ comments, loading, error, available, createComment,
+updateComment, deleteComment, refetch }`.
+
+- `comments` — newest first on the wire (server order). Pass the array as-is to `@lotics/ui`'s
+  `CommentList`, which re-sorts oldest-first for display. Each `AppComment`: `{ id, record_id,
+  table_id, member_id, content, files, workspace_id, created_at, updated_at }`. Attachments
+  (`AppCommentFile`) carry `id` / `filename` / `mime_type` plus `file_storage_key` (needed when
+  re-sending files on edit). The `url` / `thumbnail_url` / `preview_url` fields exist on the type
+  but the server does not populate them today — render attachments by name and type (what
+  `CommentList`'s default file row does), never by counting on a fetchable URL.
+- `createComment({ content, file_ids? })` — posts as the viewing member. `file_ids` come from
+  `useFileUpload` / `useAttachments` (see [files](./files.md)). A comment must have content or at
+  least one file (empty input is a client no-op; the server enforces the same rule). Content max
+  10,000 characters.
+- `updateComment(id, { content, files? })` — omit `files` to keep the current attachment set (a
+  text-only edit never drops attachments); pass `files` to replace the whole set.
+- All three mutations apply **optimistically** with rollback on error, then repopulate from the
+  server. **Limitation:** an optimistic create renders a placeholder row (temporary id, empty
+  `table_id`/`workspace_id`, `files: null`) until the refetch lands — don't persist anything keyed
+  on it.
+- **Limitation:** a comment carries `member_id` only — resolving the author's display name needs a
+  member source: the `useMembers` roster (requires the member-access declaration above) or member
+  cells in your own data. An unresolvable id should render a fallback (`CommentList` has an
+  `unknownMember` label for exactly this).
+- **Freshness:** SWR-cached, revalidates on focus/reconnect; there is **no realtime push** to apps,
+  so another viewer's comment appears on the next focus or explicit `refetch()`.
+
+### Counts
+
+`useCommentCounts({ table_id })` → `{ counts, loading, error, available, refetch }` where `counts`
+is `{ record_id: count }` for the whole table — row badges without shipping any comment content
+(one server-side aggregate). Same gate and authority as `useComments`. `table_id` is the source
+table's id — the same id the app's queries are declared over.
+
+## Pairing with `@lotics/ui`
+
+The SDK ships zero components; these `@lotics/ui` components are shaped to accept SDK values
+directly (full props: `node_modules/@lotics/ui/AGENTS.md` and its `docs/`):
+
+| Value | Component | Feed it |
+| --- | --- | --- |
+| A select value (stored or picker option) | `OptionBadge` | A `useFieldOptions` option, or `byKey(readSelect(cell)[0]?.key)`; accepts a single option, an array (multi → one badge each), or null (renders nothing). Missing/unknown color → neutral. |
+| A person, inline | `MemberChip` | `name` / `image` resolved from the roster or a cell; no image → initials |
+| A member picker | `MemberSelect` | `members={useMembers().members}` — renders each option as a `MemberChip`; `MEMBER_UNASSIGNED` marks its optional "unassigned" option |
+| A comment thread | `CommentList` + `CommentComposer` | `useComments` state; `resolveMember` bridges `member_id` → your member source |
+
+The SDK never imports `@lotics/ui` — the app owns the (thin) data→UI adapter in each row above.
+
+## Where each hook works
+
+| Surface | Embedded (signed-in member) | Standalone / public (anonymous) |
+| --- | --- | --- |
+| `readSelect` cell enrichment | ✓ | ✓ |
+| `readMembers` cell enrichment | ✓ (email included, same-org) | ✓ name-only, no email |
+| `useFieldOptions` | ✓ | ✓ |
+| `useMembers` | ✓ (same-org + declaration gates) | ✗ errors |
+| `useViewer` | member id (view-as target) | `null` |
+| `useComments` / `useCommentCounts` | ✓ when capability declared | ✗ `available: false` |