@lotics/app-sdk 0.100.0 → 0.101.0

package/docs/files.md

@@ -1,11 +1,7 @@
 # Files
 
-Files end to end in a custom-code app: uploading bytes (`useFileUpload`), an add-queue 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
+Files end to end: uploading, the add-queue, `files` cells, generated documents, previewing,
+filtering, and the delivery bounds that decide whether a file-bearing query succeeds. Query mechanics (projection, unnest, aggregates) live in [queries](./queries.md); fetching
 discipline in [data fetching](./data_fetching.md).
 
 ## The lifecycle in one table
@@ -14,18 +10,29 @@ discipline in [data fetching](./data_fetching.md).
 |---|---|---|
 | 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 |
-
-`useAttachments().add(files, { fidelity })` and `.attach(files, { fidelity })` take the same
-`fidelity` as `upload`.
 | 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` / `FileThumbnailGrid` / `FileGalleryDialog` | map to `DisplayFile` (see below) |
 | Save browser-built bytes | `downloadFile(filename, data, mimeType?)` | a client-side download (see [runtime](./runtime.md)) |
+| Rename one a record holds | `renameFile(file_id, filename)` | an `AppFile` — a new, unattached file over the same bytes |
 
 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)).
+belongs to no record ([mutations](./mutations.md)).
+
+## Renaming — `renameFile`
+
+```tsx
+const renamed = await renameFile(file.id, "Invoice 9.pdf");
+await save({ record_id, papers_added: [renamed.id], papers_removed: [file.id] });
+```
+
+A file is never renamed in place: `renameFile` answers a NEW file over the same bytes (same
+storage, size and upload day), which is inert like an upload until a save puts it in the old one's
+place. A save carrying `_added` and `_removed` of one field puts the added file where the removed
+one stood, so a rename or a replace keeps its position. The name keeps the file's extension
+exactly — `"scan.pdf"` → `"Invoice 9.pdf"`; `.html` is refused — and holds no `/`, `\` or control
+character. Offer it only where the app writes that field: the save is what may be refused.
 
 ## Uploading — `useFileUpload`
 
@@ -38,23 +45,21 @@ const surveyPhoto = await upload(file, { fidelity: "standard" }); // bulk captur
 await submit({ ...fields, invoice_file_id: invoiceShot.id });
 ```
 
-Signature: `dist/src/hooks.d.ts`. Returns `{ upload, uploading, error }`:
+Signature: `dist/hooks.d.ts`. Returns `{ upload, uploading, error }`:
 
 - `upload(file: File, options?: { fidelity }): 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.
-- `fidelity` — **how faithful the stored image must be.** The platform owns the pixels behind
-  each step and re-tunes them centrally as model tiers change.
+- `fidelity` — **how faithful the stored image must be**; the platform owns the pixels behind
+  each step. `useAttachments().add` and `.attach` take it too.
 
   Defaults to `"high"` — enough to resolve the text of a photographed document. Drop to
   `"standard"` when collecting in volume.
 
   **This only affects photographs.** A PDF, Word, Excel or CSV file is stored untouched at every
-  step, so `"original"` is not what keeps a document intact — it already is. Note too that HEIC
-  (what an iPhone camera produces) is transcoded to JPEG server-side whatever you choose, because
-  no browser can render it.
+  step, so `"original"` is not what keeps a document intact — it already is.
 
   | `fidelity` | Use it when | Stored at |
   |---|---|---|
@@ -62,10 +67,9 @@ Signature: `dist/src/hooks.d.ts`. Returns `{ upload, uploading, error }`:
   | `"high"` *(default)* | The image is READ — invoices, release orders, screenshots of dense tables — by a model or a person. Near-lossless, because a model's token cost depends on dimension alone, so quality is free accuracy. | 1568 px, q 0.95 |
   | `"original"` | The bytes themselves matter: evidence of record, or anything that may be re-read at a higher fidelity later. | unchanged |
 
-  Getting it wrong is never fatal — too low stores fewer pixels than the reader wanted, it never
-  produces a wrong answer. Rule of thumb: **if text on the image has to be legible, or a person
-  may zoom, use `"high"`.** Reach for `"original"` only when the file IS the record rather than
-  a picture of it — it is the one step whose meaning survives a change to these numbers.
+  **If text on the image has to be legible, or a person may zoom, use `"high"`.** Reach for
+  `"original"` only when the file IS the record rather than a picture of it — it is the one step
+  whose meaning survives a change to these numbers.
 - `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.
 
@@ -77,18 +81,18 @@ use-access to the app itself.
 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 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 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 PNG/WebP ≤1280 px or upload them as non-image MIME types.
-- **HEIC/HEIF always becomes JPEG, regardless of size.** Most browsers cannot decode HEIC
-  (the Samsung/iPhone camera default), so where the browser can't convert it client-side the
-  server converts it at finalize under the same ≤1280 px / q0.75 policy (conversion failure
-  stores the original bytes — never an upload error). Either way the stored file — and the
-  file identity your app gets back — is `name.jpg` with `mime_type: "image/jpeg"`.
+- **Image optimization.** A JPEG/PNG/WebP image longer than its `fidelity`'s ceiling is resized
+  and re-encoded as JPEG at that step's quality before upload; one at or below it, and every
+  `"original"`, is stored untouched. Non-image files pass through unchanged, and so does an image
+  the browser cannot resize (no canvas or decoder, or a canvas that exports nothing). Any other
+  optimization error fails a standalone app's upload; a member-facing app's host uploads the
+  original bytes instead.
+  **Warning:** a resized PNG/WebP is *converted to JPEG* — transparency is lost and the stored
+  filename's extension becomes `.jpg`. For lossless originals, upload at `"original"`.
+- **HEIC/HEIF always becomes JPEG, at every `fidelity`.** Where the browser can't convert it
+  client-side the server converts it at finalize (conversion failure stores the original bytes —
+  never an upload error). Either way the stored file — and the file identity your app gets back —
+  is `name.jpg` with `mime_type: "image/jpeg"`.
 - **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.
@@ -183,11 +187,11 @@ const onAdd = async (picked: File[]) => {
 />
 ```
 
-Contract (`dist/src/attachments.d.ts`):
+Contract (`dist/attachments.d.ts`):
 
 | Member | Behavior |
 |---|---|
-| `files: AttachedFile[]` | Current attachments, in the order added |
+| `files: readonly AttachedFile[]` | Current attachments, in the order added |
 | `add(files: File[])` | Each file shows its local preview at once and uploads in the background. Never rejects — a failure is the entry's `status` |
 | `attach(files: File[])` | The same add, resolved with the stored ids once **every** one is up. Rejects with the first refusal rather than answering short |
 | `remove(id)` | Removes one attachment and revokes its preview object-URL |
@@ -196,6 +200,11 @@ Contract (`dist/src/attachments.d.ts`):
 | `fileIds: string[]` | Stored file ids of the **completed** uploads — the workflow/agent payload |
 | `useAttachments({ landed })` | Stored ids the destination now holds; each matching entry leaves the queue and its preview is revoked |
 
+Several piles from one list — a record's file sections, a form's file inputs — take one
+`useAttachmentPiles({ landed })` rather than a `useAttachments` per pile: a hook called in a loop
+shifts every later hook when the list changes. `of(pile)` is that pile's queue, the contract above
+with verbs stable per pile; `landed` is keyed by pile; `clearAll()` empties every pile.
+
 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
@@ -223,10 +232,15 @@ 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.
+- `size` (bytes), `created_at` (ISO upload timestamp) and `document_template_id` (the template a
+  generated file was made from) — resolved from the file object at serving time, batch-loaded per
+  response.
+
+A caller outside the app's organization receives only `id`, `filename`, `mime_type`, `url`,
+`thumbnail_url`, `preview_url`, `size`, `created_at` and `document_template_id` — never the storage
+address.
 
-Decode with `readFiles(cell)` → `AppFile[]` (`dist/src/row.d.ts`):
+Decode with `readFiles(cell)` → `AppFile[]` (`dist/row.d.ts`):
 
 | Field | Type | Notes |
 |---|---|---|
@@ -237,6 +251,7 @@ Decode with `readFiles(cell)` → `AppFile[]` (`dist/src/row.d.ts`):
 | `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 |
+| `document_template_id` | `string?` | The document template (`dtl_…`) the file was generated from — absent on a file a person uploaded, whatever its name |
 
 `readFiles` skips entries the server didn't presign (no `url`), so you never render an unservable
 file. It is pure and never throws.
@@ -244,9 +259,8 @@ file. It is pure and never throws.
 - **A LOOKUP of a files field is one list per linked row.** The cell holds one entry per linked
   record and each entry is that record's whole files cell, so the value arrives one level deeper
   than a stored column's — exactly as a looked-up link does. `readFiles` opens that level itself,
-  in link order, naming a file two linked rows both carry once, so a picture read through a link
-  needs no unwrapping at the call site. Read entry-by-entry it decodes to nothing, which is a mark
-  falling back to its glyph while the bytes are plainly there.
+  in link order, naming a file two linked rows both carry once; read entry-by-entry it decodes to
+  nothing.
 
 - **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`
@@ -282,8 +296,8 @@ Design around it:
   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.
+  that size is thousands of entries. `useQuery` with a modest `page` or `more` 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`
@@ -319,11 +333,8 @@ if (result.status === "success" && result.files?.length) {
   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).
+- Open one with `openExternal(url)`, never `window.open`; bytes the app builds *in the browser*
+  leave through `downloadFile` — both [runtime](./runtime.md).
 
 ### Naming what goes into a zip
 
@@ -353,8 +364,8 @@ means "no name", and that entry keeps the stored filename.
 
 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:
+not viewing). The kit is installed only in a sandbox session (see [AGENTS.md](../AGENTS.md)); the
+SDK-side contract is only the data mapping:
 
 | `AppFile` (SDK) | `DisplayFile` (`@lotics/ui`) |
 |---|---|
@@ -365,7 +376,6 @@ not viewing). Component contracts live in the `@lotics/ui` reference
 | `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` takes the queue status and overlays the
   scrim, the spinner or the retry, images fall back from `previewUrl` to `thumbnailUrl` to `url`.

package/docs/members_and_options.md

@@ -1,12 +1,8 @@
 # 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` mark, a per-viewer ("my records") screen, or a
-comment thread. Query mechanics live in [queries](./queries.md); the authority model in
-[security](./security.md).
+How an app renders and picks **people** and **select-field options**, the host context they are
+read from, and **record comments**. Query mechanics live in [queries](./queries.md); the authority
+model in [security](./security.md).
 
 ## Cells vs. catalogs — the model
 
@@ -16,6 +12,7 @@ Every select and member value reaches the app in one of two shapes, and most scr
 | --- | --- | --- |
 | 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 |
+| Filter a number each row reads in its own unit | `useFieldOptions(alias).units` | The units or currencies a range on it compares in — `{ vocabulary, options }` |
 | Render a stored member value | `readMembers(cell)` | The members the record actually holds |
 | Populate a member picker (assign UIs) | `useMembers(opts?)` | The org roster — every member, not only the referenced ones |
 
@@ -36,7 +33,7 @@ projected `select` cell to `Array<{ key, label }>` before the row reaches the ap
   *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[]`:
+Decode with **`readSelect(cell)`** (`dist/select.d.ts`) → `ResolvedOption[]`:
 
 - Returns `[]` for `null`/`undefined`/empty cells and for any unexpected shape — iterate without
   null-checks.
@@ -50,7 +47,7 @@ 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
+The picker companion to `useQuery` (`dist/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.
@@ -70,33 +67,46 @@ const { fields } = useFieldOptions("orders");   // same alias you query
 
 `fields` is keyed by the query's **output column name**, not the field key — and by *that alias's*
 columns: `Partial<Record<ColumnKeyOf<"alias">, FieldOptions>>`. A key the alias does not project is
-a compile error, so a picker fed from a sibling query's option map fails at your desk instead of
-rendering with no options; and every key is optional, so the read is through `?.` and never a bare
-`.options`. Each `FieldOptions`:
+a compile error, and every key is optional. 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** |
+| `options` | Every option of the field — `{ key, label, color, mark? }` (the option's own brand or glyph, where the field marks every option) — 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 `Status`; 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. That is
-  why the type makes every key optional: `fields.status?.options ?? []`.
+  `fields` — a UNION output whose arms disagree on the source field, or a computed column:
+  `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.
 
+### A figure read in each row's own unit: `units`
+
+A number whose field names a `unit_field` or `currency_field` reads each row in the option a select
+on that row holds, so a comparison on it states which one as `unit_option` — the server refuses one
+that does not, and keeps only the rows in that unit (a measured unit's kin, `kg` beside `t`,
+converted). `units` is keyed like `fields`: `{ vocabulary: "unit" | "currency", options: { key, label }[] }`
+per such column, whether or not the query projects the select. Pass it whole to a range filter:
+
+```tsx
+const { units } = useFieldOptions("loads");
+<FilterChip column={{ key: "weight", label: "Weight", type: "number", units: units.weight }}
+  value={weight} onChange={setWeight} />
+// columnFilterToConditions puts the picked unit on each condition as `unit_option`
+```
+
 ### Caching & freshness
 
 Field config is slow-changing, so the hook does **not** revalidate on window focus or reconnect — it
 re-reads on arrival (a remount) like the query hooks, and on an explicit `refetch()`. The option set
 is resolved live from field config at fetch time, so an option added, renamed, or recolored in the
 table flows through on the next fetch, with no app redeploy. `opts.enabled` defers the fetch (e.g.
-until an edit drawer opens). State: `{ fields, loading, isValidating, error, refetch }`.
+until an edit drawer opens). State: `{ fields, units, loading, isValidating, error, refetch }`.
 
 ### Coloring a stored value (the `byKey` idiom)
 
@@ -142,12 +152,12 @@ projected `select_member` cell to `Array<{ id, name, email?, image?, groups?, ro
 - Only ids already present in the projected rows are resolved — a member cell never exposes the
   wider directory, and only their avatars are signed.
 
-Decode with **`readMembers(cell)`** (`dist/src/members.d.ts`) → `ResolvedMember[]`. Same defensive
+Decode with **`readMembers(cell)`** (`dist/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`):
+The candidate set for an "assign to a member" picker (`dist/hooks.d.ts`):
 
 ```tsx
 const { members, loading, error } = useMembers({ group: GRP.fulfillment });
@@ -155,15 +165,13 @@ const { members, loading, error } = useMembers({ group: GRP.fulfillment });
 ```
 
 Each member is the same `ResolvedMember` a cell carries — `{ id, name, email, image, groups, role, joined }`.
-The one field it never carries is `archived`, and that is the answer rather than a gap: this roster
-answers "who may I ASSIGN?", and a departed member is not a candidate, so it never returns one. A
-resolved CELL is the display door and keeps naming them.
+It never carries `archived`: this roster answers "who may I ASSIGN?", so a departed member is not
+in it, while a resolved CELL keeps naming them.
 `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.
+Every hook reading one `group` shares one roster: it is read again when a screen reading it mounts, never on focus.
 
 ### Access gates (when it errors)
 
@@ -172,9 +180,9 @@ 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.
+   get an error.
 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
+   workflow input **or** query param of `{ "type": "member" }` in its bindings. 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.
@@ -183,21 +191,16 @@ three gates are observable as an `error` on the hook:
    app can only enumerate groups it actually assigns into. A declared group with no members
    resolves to `{ members: [] }`.
 
-Name the group `GRP.<group>`, from the generated `.lotics/app_fields.ts` — `GRP` is that workspace's
-group directory keyed by slugified display name, so the same source resolves in every copy of the
-app. A pasted `grp_…` id is an id one workspace minted: it resolves to nothing anywhere else, and
-`lotics app check` refuses it. (The manifest DECLARATION below is the exception — it carries the
-concrete id, and publish inverts it.)
+Name the group by the `grp_…` id the workflow input's `group` declares — the binding below, set
+with `set_app_workflow`:
 
 ```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" }
-    }
+// set_app_workflow — the declaration that unlocks useMembers
+{
+  "alias": "assignOrder",
+  "inputs": {
+    "record_id": { "type": "record_link", "table_id": "tbl_orders" },
+    "assignee":  { "type": "member", "group": "grp_fulfillment" }
   }
 }
 ```
@@ -219,36 +222,66 @@ the `select_member` field in the query, and the cell already carries the 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.
+Names render; only the avatar photo is unavailable (`MemberChip` falls back to initials). If a chip
+renders blank, fix the query projection — never widen the bindings.
 
 ## `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
+`useViewer()` (`dist/viewer.d.ts`) → `{ memberId, loading }` — the signed-in member currently
+viewing the app. Under an admin's "View as" in the product 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).
+**Never an authorization fact or a scoping mechanism** —
+[security](./security.md#useviewer-is-display-only).
+
+`loading` settles to `false` when the context read fails too: `memberId` is then `null`, and the
+failure is logged to the console.
+
+## `useAppContext()` — the host's context, and whether it could be read
+
+`useAppContext()` (`dist/viewer.d.ts`) is the one read every hook above is a view of: the
+signed-in member, whether comments are enabled, the workspace's zone and currency, and three
+states — `resolved` once it answered, `settled` once it answered OR failed, and `failure` —
+`{ message, retry }`, `null` unless the read failed. Where it failed every fact is unknown, so a
+surface that dates or counts by them draws the failure rather than guessing the reader's zone.
+
+## The workspace's zone at the root
+
+An app that draws with `@lotics/ui` mounts the kit's `LoticsLocaleProvider` at the root of
+`src/main.tsx` with `zone` set to `useAppContext().timezone`, and draws nothing until the context
+has `settled` — where it failed, it draws `failure` with its `retry` in place of the app. Then every
+instant the kit prints (`useFormatDate`) and every day it files by or counts to (`useCalendarDay`)
+is the workspace's, never the browser's. The sandbox starter's `src/main.tsx` does exactly this.
+
+## `useWorkspaceTimezone()` / `useWorkspaceCurrency()` — what the workspace states
+
+Both read the same context as `useViewer()` (`dist/viewer.d.ts`), and both are `undefined`
+until it resolves, where it failed, and from a host that predates them.
+
+- **`useWorkspaceTimezone()`** → the workspace's IANA zone (`Asia/Ho_Chi_Minh`). It dates an
+  INSTANT — a record's own `__created_at`, a comment's time. A stored `date`/`datetime` cell is a
+  wall clock and needs none. The kit reads it through the root locale provider (above) — never
+  passed to a date call by hand.
+- **`useWorkspaceCurrency()`** → the workspace's ISO 4217 code (`VND`), what money is counted in
+  where the field states no code of its own. Pass it as the money's `currency`: a money format
+  given no code prints the kit's home market, which says nothing about this workspace.
 
 ## Comments: `useComments` / `useCommentCounts`
 
 Record comments — member-to-member discussion attached to any record the app reaches
-(`dist/src/comments.d.ts`).
+(`dist/comments.d.ts`).
 
 ### Enabling comments
 
-Opt in via the manifest; the flag syncs on deploy:
+Opt in on the app — a JSON app states it in its model; a custom-code app sets it live, as a new
+version:
 
 ```jsonc
-// package.json → "lotics"
-"capabilities": { "comments": true }
+// update_app
+{ "app_id": "app_…", "capabilities": { "comments": true } }
 ```
 
 Both hooks expose **`available`** — `true` only when a member is signed in **and** the app declared
@@ -305,17 +338,15 @@ updateComment, deleteComment, refetch }`.
   on it.
 - **The author names itself.** `author` carries `{ name, image? }`, resolved server-side on every
   comment the server returns — list, create and update alike — including one written from another
-  app by someone the record references nowhere. So a thread that crosses a role boundary is legible without the app declaring member
-  access it does not otherwise need, and a per-viewer app never widens its reach for a display
-  string. `name` is `null` when the id no longer resolves in the org (a removed member) — render a
+  app by someone the record references nowhere, so a thread needs no declared member access.
+  `name` is `null` when the id no longer resolves in the org (a removed member) — render a
   fallback (`Timeline` has an `unknownMember` label for exactly this). The one comment with no
   `author` is the optimistic row `createComment` renders locally: the SDK knows the viewer's id and
   not their name, and it will not invent one. The server's row replaces it when the refetch lands.
-- **Freshness:** SWR-cached, revalidates on focus/reconnect, so another viewer's comment appears on
-  the next focus or explicit `refetch()` — not on its own. Comments are the one read that does not
-  keep itself current, and not because apps lack realtime: the channel carries **record** changes,
-  and a comment is its own entity that emits no record event. Your queries DO get pushed
-  ([data_fetching.md](./data_fetching.md)) — don't read this line as "no push" and build a poll.
+- **Freshness:** cached like a query — re-read on arrival and on focus/reconnect, so another
+  viewer's comment appears on the next arrival, focus or explicit `refetch()` — not on its own: the realtime channel carries **record**
+  changes, and a comment emits no record event. Your queries DO get pushed
+  ([data_fetching.md](./data_fetching.md)).
 
 ### Counts
 
@@ -328,8 +359,8 @@ row is on screen — no request is sent and `counts` is `{}`.
 
 ## 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/`):
+The SDK ships zero components; these `@lotics/ui` components (a sandbox session's kit, see
+[AGENTS.md](../AGENTS.md)) are shaped to accept SDK values directly:
 
 | Value | Component | Feed it |
 | --- | --- | --- |
@@ -338,8 +369,6 @@ directly (full props: `node_modules/@lotics/ui/AGENTS.md` and its `docs/`):
 | A member picker | `MemberSelect` | `members={useMembers().members}` — renders each option as a `MemberChip`; `MEMBER_UNASSIGNED` marks its optional "unassigned" option |
 | A comment thread | `Timeline` + `Composer` (`@lotics/ui/composer`) | `useComments` state; `resolveMember` reads each comment's own `author` (`{ name, image }`) — no roster needed |
 
-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) |
@@ -349,4 +378,5 @@ The SDK never imports `@lotics/ui` — the app owns the (thin) data→UI adapter
 | `useFieldOptions` | ✓ | ✓ |
 | `useMembers` | ✓ (same-org + declaration gates) | ✗ errors |
 | `useViewer` | member id (view-as target) | `null` |
+| `useWorkspaceTimezone` / `useWorkspaceCurrency` | ✓ | ✓ |
 | `useComments` / `useCommentCounts` | ✓ when capability declared | ✗ `available: false` |