@lotics/app-sdk 0.100.1 → 0.101.0

package/docs/data_fetching.md

@@ -1,104 +1,104 @@
 # Data fetching
 
-How an app reads data: the three read hooks (`useQuery`, `useInfiniteQuery`, `usePaginatedQuery`),
-their caching/revalidation and pagination contracts, the typed cell readers that decode query rows
-(`row.*`, `readSelect`, `readMembers`, `readLinks`, `readFiles`, `readLocked`, `readCreatedAt`/`readUpdatedAt`), `useFieldOptions`
-for complete select option sets, the data-discipline rules, and the two load-bearing read patterns
-(search-as-you-type, browse/record-picker). Authoring the named queries these hooks invoke — the
+How an app reads data: the read hooks, their caching and pagination contracts, counts, the cell
+readers, the data-discipline rules, and the search and record-picker patterns. Authoring the named queries these hooks invoke — the
 AST, params, filter operators, aggregation, performance contract — is [./queries.md](./queries.md);
 every write goes through a workflow — [./mutations.md](./mutations.md). Exact signatures:
-`dist/src/hooks.d.ts`, `dist/src/row.d.ts`, `dist/src/select.d.ts`, `dist/src/members.d.ts`.
+`dist/queries.d.ts`, `dist/row.d.ts`, `dist/select.d.ts`, `dist/members.d.ts`.
 
 The read model in one paragraph: an app never sends a raw query. It invokes a **named query by
-alias** (declared in `package.json#lotics.queries`) and fills the template's declared `{{params.x}}`
+alias** (bound with `set_app_query`) and fills the template's declared `{{params.x}}`
 value holes; the server holds the canonical AST and runs it under the **app owner's** authority
-(per-viewer scoping is a template concern — see [./security.md](./security.md)). Per-app CLI
-codegen augments `AppQueries`, so an undeclared alias is a compile-time error and params are typed
-per the manifest. Each hook is a thin wrapper over the host RPC bridge with an SWR cache in front.
+([./security.md](./security.md)). The generated `.lotics/app_queries.d.ts` augments `AppQueries`,
+so an unbound alias is a compile-time error and params are typed per the binding. It is written
+from the app's live bindings whenever a sandbox session opens on the app; a project on your own
+machine has none, so every alias is accepted there as a plain string, untyped. Every hook reads through the SDK's own cache, over the host RPC bridge.
 
-## Choosing a hook
+## Choosing a read
 
-| Hook | Result shape | Reach for it when |
+| Call | Answers | Reach for it when |
 |---|---|---|
-| `useQuery(alias, params?, opts?)` | one fetch, `rows` | a detail read, a dashboard block, a combobox's top-N — anything that is not a long list |
-| `useInfiniteQuery(alias, params?, opts?)` | accumulated `rows` + `loadMore` | infinite scroll / "load more" feeds |
-| `usePaginatedQuery(alias, params?, opts?)` | one page of `rows` + `total` | numbered, jumpable pages behind `@lotics/ui` `Pagination` |
-| `useCount(alias, params?, opts?)` | `total` only, no rows | a facet chip, a queue badge, an "N awaiting approval" tile — the size of a set you are not listing |
-
-One job each — don't overload one. `useQuery` with a big `pageSize` is not pagination; a
-`usePaginatedQuery` whose pages you concatenate yourself is `useInfiniteQuery` done by hand;
-and a `usePaginatedQuery` with `pageSize: 1` whose rows you drop is `useCount` buying a page
-nobody renders — **two** requests for one integer, since that hook fetches a page AND a count.
-
-`useCount` takes no `sort` and no `pageSize`: a count is a single-row COUNT over the filtered
-set, so ordering and paginating it are meaningless. They are absent from `CountOptions` rather
-than ignored — an option a hook silently drops is worse than one that will not compile.
+| `useQuery(alias, params?, opts?)` | `rows` up to the server's cap, or the first `limit` | a detail read, a dashboard block, a combobox's top-N — anything that is not a long list |
+| `useQuery(alias, params?, { page: n })` | one numbered page of `n` rows, `total`, `pageCount`, `setPage` | numbered, jumpable pages behind `@lotics/ui` `Pagination` |
+| `useQuery(alias, params?, { more: n })` | accumulated `rows` + `loadMore` | infinite scroll / "load more" feeds |
+| `useQuery(alias, params?, { rows: false, total: true })` | `total` only, no rows (`total: { by: column }` adds `counts`) | a facet chip, a queue badge, an "N awaiting approval" tile — the size of a set you are not listing |
+| `useQueries(calls, opts?)` | one state per `{ alias, params?, filter?, sort?, aggregate?, total?, rows? }`, in order — a `sort` orders that call's rows before the cap cuts them | reads that are DATA — a list known only at render, one read per item, or one count per stage (`rows: false, total: true`, each state's `.total`); the deploy's alias scan reads a list as dynamic, so every alias in it is still declared. With `aggregate` a call answers the groups of its filtered rows instead of the rows ([queries](./queries.md)) |
+| `queryAll(alias, params?, { filter, sort })` | a promise of every row | outside React, for a job that must hold the whole narrowed set (an export): it asks page after page until the server says the set ended, never stopping at the 10,000-row cap. The server's rows as stored — no write of this app is drawn over them |
+
+Every hook answers the same `QueryState`: `rows`, `truncated`, `total`, `counts`, `loading`,
+`isValidating`, `error`, `pending`, `refetch`, `page`, `setPage`, `pageCount`, `hasMore`,
+`loadMore`, `loadingMore`. A field the call did not ask for rests at its empty value (`page` 0,
+`total` and `pageCount` undefined, `hasMore` false; `setPage` and `loadMore` do nothing).
+
+`limit`, `page` and `more` are mutually exclusive — a call given two throws. A big `limit` is not
+pagination; a `page` read whose pages you concatenate yourself is `more` done by hand; and a
+`page: 1` read whose row you drop is `rows: false, total: true` buying a page nobody renders.
 
 ### One count per filtered set
 
-`useCount` counts under the SAME cache key `usePaginatedQuery` counts under —
-`(alias, params, filter)`. A table and a badge over the same set therefore issue **one** count
-between them, and page clicks and re-sorts reuse it (a count is page- and sort-independent):
+`total` is a COUNT over the filtered set — `sort`, `limit`, `page` and `more` do not change it
+(per value of `by`, when given). Two reads counting the same `(alias, params, filter, by)` share
+**one** request, and page clicks and re-sorts reuse it. `page` counts by default:
 
 ```tsx
 // One count total, not two — same alias, same params, same filter.
-const { rows, total, setPage } = usePaginatedQuery("orders", { q }, { pageSize: 25 });
-const { total: sameNumber } = useCount("orders", { q });
+const orders = useQuery("orders", { q }, { page: 25 });                 // orders.total, orders.pageCount
+const { total: sameNumber } = useQuery("orders", { q }, { rows: false, total: true });
 ```
 
 **A count is not free, and it is not fast.** It re-executes the whole `from` tree and scans the
-entire filtered set, where a page stops at `pageSize` — measured on one register, the COUNT ran
-*longer* than the page beside it. That is why it is a request of its own rather than something
-folded into the page response: rows paint the moment they arrive, and the number fills in
-behind them. Fold the two together and every table waits for its own count before showing a
-single row.
+entire filtered set, where a page stops at its size — so it is a request of its own, sent only when
+`total` is asked, and rows paint without waiting for it.
 
 Do not reach for it N times over one source. Each declared query re-executes its whole `from`
-tree, so four facets mounted as four `useCount`s are four full scans landing in one burst
-against the server's concurrency gate. When the counts differ only by a bucket the rows can be
-grouped on, **one `group` query returns them all in a single scan** and folds client-side
-([queries](./queries.md) §10), and its figure can be handed to `usePaginatedQuery`'s `total` so
-the list stops counting too. `useCount` is for the count with no sibling to group with.
+tree, so four facets mounted as four counts are four full scans landing in one burst against the
+server's concurrency gate. When the counts differ only by the value of one column the query
+projects — a strip of stages, a facet per option — pass it as `by`: **one scan returns every
+value's count as `counts`, beside `total`**. A row holding several values is counted under each; a
+row holding none is in `total` only.
+
+```tsx
+const { total, counts } = useQuery("orders", { q }, { rows: false, total: { by: "stage" } });
+// counts?.["opt_shipped"] — the rows in that stage over the whole set, however few are loaded
+```
+
+A `useQueries` call's `total` is `true` or absent — it takes no `by`.
 
 ### Why not hand-roll it
 
-A direct `rpc("query", { …, count: true })` is one request and looks equivalent. It is not: it
-leaves the cache, so it does not dedupe with the page beside it, does not revalidate on focus,
-and never hears the host's post-write refetch. The number then goes stale over a set that has
-moved while everything around it updates — and a count that is quietly wrong costs more than a
-count that costs a request.
+A direct `rpc("query", { …, count: true })` leaves the cache: it does not dedupe with the page
+beside it, does not revalidate on focus, and never hears the post-write re-read, so the number
+goes stale while everything around it updates.
 
 And never count client-side from `useQuery(...).rows.length`: rows are capped at 10,000 per
 response, so the number is right in development and wrong in production ([queries](./queries.md)
-§10). `useQuery` reports `truncated` when the cap cut the result — read it wherever a figure is
-folded from the rows (below) — but a count over the whole set is `useCount`'s answer, not a length.
+§10). `truncated` says when the cap cut the result — read it wherever a figure is folded from the
+rows (below) — but a count over the whole set is `total`, not a length.
 
-## Shared option surface
+## Options
 
-All three hooks accept these (`BaseQueryOptions`):
+`useQuery` takes these (`QueryOptions`); `useQueries` takes `enabled` and `revalidateOnFocus` for
+all its calls, and each call states its own `filter`, `sort`, `total` and `rows`:
 
 | Option | Type | Default | Effect |
 |---|---|---|---|
-| `enabled` | `boolean` | `true` | `false` = no request is sent, `rows` is `[]`, `loading` is `false`. Flip to `true` to fetch. The gate for search-as-you-type and on-demand detail. Note: disabling also **hides** previously loaded rows (the cache entry survives; it re-renders instantly when re-enabled). |
-| `revalidateOnFocus` | `boolean` | `true` | `false` = no auto-refetch on window focus / tab return / network reconnect (`refetch()` still works). Keep the default for dashboards; turn off for transient queries (a search bound to an ephemeral term) where a refocus re-run is wasted work and a visible reload. |
-| `sort` | `QuerySortKey[]` | — | Runtime sort, applied server-side **after** the named query, over its output columns: `[{ field_key, order: "asc" \| "desc" }]`. An empty/omitted array leaves the query's own order intact. Part of the cache key — changing it re-queries. |
-| `filter` | `QueryFilter` | — | Runtime filter, applied server-side after the named query, over its output columns. A single condition or a recursive `{ node_type: "group", logic: "and" \| "or", children }`. Part of the cache key. Build from per-column UI state with `columnFilterToConditions` (`@lotics/ui/column_filter`). |
-
-Per-hook additions:
-
-| Option | Hook | Meaning |
-|---|---|---|
-| `pageSize?: number` | `useQuery` | a **cap** on the one request, not pagination; omit to fetch up to the server row cap |
-| `pageSize: number` | `useInfiniteQuery` | rows per appended page — the options type requires it, though omitting `opts` entirely type-checks and defaults to 30 |
-| `pageSize?: number` | `usePaginatedQuery` | rows per page, default 25 |
+| `enabled` | `boolean` | `true` | `false` = no request is sent, `rows` is `[]`, `loading` is `false`. Flip to `true` to fetch. The gate for search-as-you-type and on-demand detail. Disabling also **hides** previously loaded rows (the cached answer survives; it re-renders instantly when re-enabled). |
+| `revalidateOnFocus` | `boolean` | `true` | `false` = no re-read on window focus / tab return / network reconnect (`refetch()` still works). Keep the default for dashboards; turn off for transient queries (a search bound to an ephemeral term) where a refocus re-run is wasted work and a visible reload. |
+| `sort` | `QuerySortKey[]` | — | Runtime sort, applied server-side **after** the named query, over its output columns: `[{ field_key, order: "asc" \| "desc", blank_position? }]`. An empty/omitted array leaves the query's own order intact. Part of the read's key — changing it re-queries. |
+| `filter` | `QueryFilter` | — | Runtime filter, applied server-side after the named query, over its output columns. A single condition or a recursive `{ node_type: "group", logic: "and" \| "or", children }`. Part of the read's key. Build from per-column UI state with `columnFilterToConditions` (`@lotics/ui/column_filter`). |
+| `limit` | `number` | — | The first `limit` rows only — a **cap**, not pages; omit to read up to the server's row cap. |
+| `page` | `number` | — | Numbered pages of `page` rows: `page` (from 0), `setPage`, `pageCount`, `hasMore`, and `total`, counted by default. |
+| `pageAt` | `{ at, onChange }` | — | With `page`, the page the screen keeps (its address, so a way back or a reload opens on it): `at` is read, `setPage` calls `onChange`, and nothing resets it — send a changed read back to 0 yourself. |
+| `more` | `number` | — | A keyset feed read `more` rows at a time: `loadMore`, `hasMore`, `loadingMore`. |
+| `total` | `boolean \| { by: column }` | `true` with `page`, else `false` | The whole set's count, its own request (`total`); with `by`, a count per value of that column from the same scan (`counts`). |
+| `rows` | `boolean` | `true` | `false` reads no rows — a total alone. |
 
 Runtime `sort`/`filter` are **bounded to the named query's output columns**, twice over. At
 compile time, `field_key` on a typed alias is the literal union of the columns the query projects —
-codegen writes it into `.lotics/app_queries.d.ts` as `AppQueryColumns[alias]`, read off the query's
+the generated `.lotics/app_queries.d.ts` carries it as `AppQueryColumns[alias]`, read off the query's
 AST by the same naming rule the server applies — so a key the query does not carry fails
-`npm run typecheck` (and therefore `lotics app check` and deploy) at your desk. At request time the
-server checks the same rule again and rejects an un-projected key with an error, so a
-sortable/filterable UI can never widen the app's data exposure even from an untyped call. The full
+`npm run typecheck` (and therefore the build a deploy runs). At request time the server
+rejects an un-projected key again, so even an untyped call cannot widen the app's data exposure. The full
 runtime-refinement contract (which operators are valid per column type, record-link membership
 filtering, and the field-less system conditions — `record_id` works in a runtime filter; `locked` /
 `current_member` are template-only and rejected at the runtime layer) lives in
@@ -107,9 +107,7 @@ filtering, and the field-less system conditions — `record_id` works in a runti
 **A key you compute must be narrowed, not widened.** A register that derives its filter columns
 from a ladder — `` `hs_${step.leaves}` `` — must type `leaves` as the literal union of the stamps
 it can name, so the template literal resolves to members of `AppQueryColumns[alias]`; a `string`
-there is a compile error on a typed alias, and that error is the point. It is exactly the bug the
-type exists to catch: a rung added to the ladder without its column added to the query, which no
-`app dev` session notices until a member scopes to the one project on that ladder. An alias whose
+there is a compile error on a typed alias, and that error is the point. An alias whose
 columns cannot be known from its AST (a bare `from_table`) has no `AppQueryColumns` entry, and its
 key stays `string` — the server's check is then the only one. A helper that builds a filter or
 sort for a typed alias names its keys `ColumnKeyOf<"alias">` — `QueryFilter<ColumnKeyOf<"register">>`,
@@ -117,16 +115,15 @@ sort for a typed alias names its keys `ColumnKeyOf<"alias">` — `QueryFilter<Co
 check reaches the helper that derives the key, not only the hook call that sends it.
 
 **The option map is keyed the same way.** `useFieldOptions(alias).fields` is keyed by that alias's
-projected columns too — ask the alias that CARRIES the column, because a picker fed from a sibling
-query's map is otherwise a control that renders empty with nothing reporting it. Every key is
-optional: [./members_and_options.md](./members_and_options.md).
+projected columns — ask the alias that CARRIES the column
+([./members_and_options.md](./members_and_options.md)).
 
 `@lotics/ui`'s `columnFilterToConditions` carries the same parameter (`FilterableColumn<C>` →
 `FilterConditionNode<C>`), so a per-column filter UI built over a typed alias composes without a
 cast.
 
 Refinement order is fixed: the runtime **filter narrows** the named query's result, then **sort
-orders** it, then **limit/offset paginate** it. The template's own filters/sort/limit run first,
+orders** it, then **`limit` / `page` / `more` cut** it. The template's own filters/sort/limit run first,
 inside the named query.
 
 The field-less `record_id` system condition documented in [./queries.md](./queries.md) (the one
@@ -135,62 +132,56 @@ write it as `{ node_type: "condition", type: "record_id", operator, value }`.
 
 ## Caching, loading states, and errors
 
-- **Cache identity** is the tuple `(alias, params, pageSize, sort, filter)` (+ the page index for
-  the paged hooks). Object *contents* are hashed, not references — passing a fresh inline
-  `{ status: "open" }` each render is the same key; you never need to memoize params.
-- The cache **survives unmount/remount**, and **arrival is a refresh event**: returning to a screen
-  renders the cached rows instantly *and* revalidates them in the background, so a list reflects what
-  another screen changed while you were away. Identical concurrent reads dedupe to one request.
+- **A read's key** is what it asks: rows by `(alias, params, filter, sort, limit)` (+ the page
+  size and index with `page`), a feed by `(alias, params, filter, sort, more)`, a count by
+  `(alias, params, filter, by)`. Object *contents* make the key, not references — passing a fresh
+  inline `{ status: "open" }` each render is the same key; you never need to memoize params.
+- **The cache survives unmount/remount**, and **arrival is a refresh event**: returning to a screen
+  renders the cached rows instantly *and* re-reads them in the background, so a list reflects what
+  another screen changed while you were away. Identical concurrent reads share one request.
   Freshness comes from four places — arrival, window focus / tab return / network reconnect
-  (`revalidateOnFocus`, default on), a **realtime push**, and **this app's own successful write**,
-  which re-reads every mounted query without being asked (see
-  [./mutations.md](./mutations.md)). `refetch()` covers what none of those can know about.
+  (`revalidateOnFocus`, default on; a read asked within the last few seconds is not asked again),
+  a **realtime push**, and **this app's own successful write**, which re-reads the mounted queries
+  over the tables its body names without being asked (see [./mutations.md](./mutations.md)).
+  `refetch()` covers what none of those can know about.
+- **This app's own writes show from the press.** Every read draws each write this app has made
+  over its rows before the server answers — cells, membership, new rows, `total`, `counts` and
+  groups — and says **`pending`** while what one changes is not all drawn. Nothing to wire: [./mutations.md](./mutations.md)
+  § A write shows from the press.
 - **Realtime push keeps an already-open screen current.** When a table one of your queries reads
   changes — another member, a workflow, the chat agent, or an external agent writing over the CLI or
   MCP — that query refetches within about a second. Nothing to wire: it follows from the query's own
-  declaration. It refetches only the aliases whose tables actually moved, so an expensive aggregate
-  is not re-run by a change to a table it never reads. Two limits worth knowing: it carries RECORD
-  changes only (a schema edit does not push), and a **standalone/public app has no host**, so those
-  apps keep focus/reconnect freshness alone. Treat push as an improvement on pull, never a
-  replacement — it is absent whenever the channel cannot connect.
-- **`useInfiniteQuery` does not arrival-revalidate** — the one exception. A warm feed re-mounted
-  refetches nothing; a cold key still fetches, and focus / reconnect / a realtime push still refresh.
-  Re-fetching page 1 on arrival would cost a request on every `loadMore()` and reshuffle the top of
-  the feed under a reader scrolling further down it, and re-fetching every loaded page grows without
-  bound. **A feed that must be fresh on arrival calls `refetch()`.**
-- **`loading`** is `true` only on the *initial* load of a key — a request is in flight and there
-  are no rows yet. It stays `false` during background revalidation of a key that already has rows,
-  so consumers never blank loaded data to a spinner on refetch. A key *change* (new params, sort,
-  filter, or page) is a fresh load: `loading` goes `true` again unless that key is already cached —
-  but the previous key's rows STAY on screen while it resolves, for every query, so `rows` never
-  empties mid-flight. That is why skeletons gate on `loading && rows.length === 0`, never `loading`
-  alone: a filter derived from what is on screen re-keys on every keystroke, and gating on
-  `loading` swaps the list for a spinner each time — which unmounts everything the rows contained,
-  images included. **`isValidating`** is `true`
-  whenever any request is in flight — use it for a subtle refresh indicator.
+  declaration, and only the aliases whose tables actually moved refetch. It carries RECORD
+  changes only (a schema edit does not push), and a **standalone/public app has no host**, so
+  those apps keep focus/reconnect freshness alone. Push is absent whenever the channel cannot
+  connect, so never treat it as a replacement for pull.
+- **A `more` feed does not re-read on arrival** — the one exception. A warm feed re-mounted
+  reads nothing, because re-reading it would reshuffle the feed under a reader scrolling it; a cold
+  key still reads, and focus / reconnect / a realtime push / this app's own write still refresh.
+  **A feed that must be fresh on arrival calls `refetch()`.**
+- **`loading`** is `true` only while a key's *first* answer is awaited. It stays `false` during a
+  re-read of a key that already has an answer, so consumers never blank loaded data to a spinner
+  on refetch. A key *change* (new params, sort, filter, or page) awaits a first answer: `loading`
+  goes `true` again unless that key is already cached — but the previous key's rows STAY on screen
+  while it resolves, for every read, so `rows` never empties mid-flight. So skeletons gate on
+  `loading && rows.length === 0`, never `loading` alone, or every re-key swaps the list for a
+  spinner. **`isValidating`** is `true` whenever any request of the read is in flight — use it for
+  a subtle refresh indicator.
 - **`error`** is a `string | null`. A failed query surfaces immediately — there is **no automatic
   retry** (no retry loop that masks the error). The last successful rows for the same key stay
-  rendered. The next focus revalidation or an explicit `refetch()` re-runs it.
-- **Never derive a FIGURE from `rows` without gating on `error`.** On a failure `rows` is `[]`,
-  and `[]` is indistinguishable from a genuinely empty result — so `rows.reduce(…)` returns `0`,
-  `rows.length` returns `0`, and a screen states a confident number that no query answered. This
-  is the one place the empty-vs-broken distinction is load-bearing: a list that renders nothing
-  looks obviously wrong, whereas a total that reads `0` looks *fine*. It cost a sales register
-  nine days of showing every rep `0 ₫` of commission, because one query's runtime filter named a
-  column it did not project and nothing read `error`. A count, a sum, a "N of M", a progress
-  meter, a badge — anything a reader would act on — renders a dash and the failure, never a
-  number, while `error !== null`. Note a key CHANGE resets this: a new `params`/`filter`/`sort`
-  is a fresh key with no prior rows, so the "last successful rows stay rendered" behaviour above
-  does not save you.
+  rendered. The next focus re-read or an explicit `refetch()` re-runs it.
+- **Never derive a FIGURE from `rows` without gating on `error`.** A first read that fails leaves
+  `rows` at `[]`, and `[]` is indistinguishable from a genuinely empty result — so `rows.reduce(…)`
+  returns `0`, `rows.length` returns `0`, and a screen states a confident number that no query
+  answered — a list that renders nothing looks wrong, a total that reads `0` looks *fine*. A new
+  key that fails keeps the previous key's rows instead — a number for a question nobody is asking
+  any more. A count, a sum, a "N of M", a progress meter, a badge — anything a reader would act
+  on — renders a dash and the failure, never a number, while `error !== null`.
 - **Never state an ABSENCE from `rows` without gating on `loading`.** The sibling of the rule
   above, and it bites earlier: while the first request is in flight `rows` is `[]`, so
   `rows.find(…)` returns nothing and any code shaped `if (!found) → "there is no X"` prints a
-  confident denial of something that is merely not here yet. It corrects itself when the data
-  lands, which is exactly what makes it ship: the author sees the settled screen, and only a
-  reader opening the surface cold sees the half-second where every requirement reads as missing.
-  A record drawer did this to five document rows at once — each rendering a red "missing" badge
-  and a blocking callout — so the loudest thing on the screen was, briefly, entirely false.
-  Gate the derivation, not the display: compute nothing while `loading`, and reserve the space with
+  confident denial of something that is merely not here yet — and only a reader opening the
+  surface cold sees it. Gate the derivation, not the display: compute nothing while `loading`, and reserve the space with
   a `Skeleton` so the layout does not jump when the answer arrives.
 
   Watch for the second source of a legitimate empty: `enabled: false` never sends a request, so
@@ -199,21 +190,16 @@ write it as `{ node_type: "condition", type: "record_id", operator, value }`.
   fact is that nothing was asked. Read the gate itself — `loading || vehicleId == null` — and say
   what is actually missing, which is the parent, not the children.
 
-- **`refetch()`** re-runs the query. A successful `useWorkflow` call already re-reads the mounted
-  queries on its own (see [./mutations.md](./mutations.md)), so reach for this only where a write
-  cannot have told you: a poll, a value that changes without anything on this screen writing, or a
-  total you supplied yourself. `usePaginatedQuery.refetch()` refreshes the page, and the count when
-  the hook owns it (a caller-supplied `total` is the caller's to refresh).
-- **Ambient-chat mutations refetch automatically.** When the member's ambient chat agent (see
-  [./ai.md](./ai.md#useaicontextslot-context--tell-the-ambient-chat-what-the-member-is-looking-at))
-  finishes a turn that mutated records, the host pushes **every mounted query hook** to re-read —
-  so the screen reflects the change with no `refetch()` call and no reload. It refreshes exactly the
-  queries currently on screen (mounted hooks only); it never reaches into app data, it only tells
-  the app its rendered rows may be stale. Inert standalone and in mock mode.
-- A design-time fixture registered via `mount(<App />, { fixture })` plus the `?__mock=1` URL flag
-  short-circuits all three hooks (rows come from the fixture, no request, `loading` stays `false`).
-  The same fixture mocks `useWorkflow`, so a screen's in-flight / done / error states are
-  reviewable without running anything — see [./runtime.md](./runtime.md).
+- **`refetch()`** re-runs every request of the read — its rows, every page a feed holds, its
+  count — for what no write of this app can have told you
+  ([./mutations.md](./mutations.md#refetch-after-a-mutation)).
+- **`useQueries` is one read.** Its calls share one key, one `loading` and one `refetch`: changing
+  any call re-reads them all. A call that fails carries its own `error`; the others keep their rows.
+- **Ambient-chat mutations refetch automatically** — every mounted query re-reads when the
+  member's chat agent finishes a turn that mutated records ([./ai.md](./ai.md#query-freshness--the-mutation-companion)).
+- A design-time fixture (`mount(…, { fixture })` + `?__mock=1`) answers every read through the same
+  cache; a `useQuery` read shows the fixture's rows from the first render —
+  [./runtime.md](./runtime.md#the-mock-harness-optionsfixture--__mock1).
 
 ### Error messages you will actually see
 
@@ -224,20 +210,17 @@ write it as `{ node_type: "condition", type: "record_id", operator, value }`.
 | `query execution failed` | The query failed at the database. Deliberately generic — database internals are never sent to the client. | The app author diagnoses from the platform's server logs; the app surfaces the message. |
 | A specific validation message | e.g. an un-projected `field_key` in runtime `sort`/`filter`, invalid params, an unknown alias. An unknown column names every column the query DOES project, so the valid set is in the message. | Fix the call site — these are contract violations, not transient. |
 
-**Which message you get is decided by the ENVELOPE, not the status** (SDK 0.85.0 — before it, the
-status alone decided). A failure whose JSON body carries a `code` is one the API authored, so its
-`message` is what `error` holds — including a 5xx, which is why the shed sentence in the table above
-reaches the app at all rather than being replaced by a generic one. Everything else — a gateway's
-HTML page, a proxy's JSON with no `code`, a body with no `message` — is plumbing, and `error` holds
-a fixed sentence derived from the status instead, so a raw HTML body can never become your error
-copy. Practically: for a 5xx you are now showing a sentence the PLATFORM wrote, so treat `error` as
-copy to display, never as a string to branch on.
+**Which message you get is decided by the ENVELOPE, not the status.** A failure whose JSON body
+carries a `code` is one the API authored, so its `message` is what `error` holds — a 5xx included,
+which is how the shed sentence above arrives. Anything else — a gateway's HTML page, a proxy's JSON
+with no `code`, a body with no `message` — becomes a fixed sentence derived from the status. Treat
+`error` as copy to display, never as a string to branch on.
 
 ## Pagination — two models
 
 Reads paginate two different ways, and the difference is load-bearing:
 
-- **`useInfiniteQuery` uses keyset (seek) pagination.** Each page seeks past the previous page's
+- **`more` uses keyset (seek) pagination.** Each page seeks past the previous page's
   opaque cursor instead of counting an offset, so a deep scroll stays O(page) and — the reason it
   matters — **never skips or duplicates a row as the set shifts** under concurrent inserts/deletes.
   The cursor is internal: the hook sends it and reads the next one back; you never see it. The
@@ -245,22 +228,21 @@ Reads paginate two different ways, and the difference is load-bearing:
   column it projects, else the record id) and falls back to offset transparently for a multi-key
   sort it can't seek. So an infinite feed needs **no
   dedupe** — key rows by `__source_record_id` for stable React keys, not to guard against repeats.
-- **`useQuery`, `usePaginatedQuery`, and manual `rpc("query", { limit, offset })` use offset
+- **`page`, `limit`, `queryAll` and manual `rpc("query", { limit, offset })` use offset
   pagination** — count `offset` rows, skip them, return the next page. Two consequences a keyset
   scroll doesn't have: deep pages cost more, and pages shift under concurrent writes.
 
 Shared by both:
 
 - **Row cap: 10,000.** No single query response returns more than 10,000 rows; a larger `limit`
-  (or an omitted `pageSize` on `useQuery`) is clamped to it. To read a bigger result set, page
-  through it. `useQuery` reports `truncated: true` when the limit cut the result, so a screen can
-  say so instead of quietly under-reporting.
+  (or none) is clamped to it. To read a bigger result set, page through it. `truncated: true`
+  says the cap cut the result, so a screen can say so instead of quietly under-reporting.
 - **Always give a paginated query a deterministic order.** With no `ORDER BY` (neither in the
   template nor runtime `sort`), row order is unspecified — offset pages may overlap or skip rows
   even without concurrent writes, and keyset falls back to the record-id order. Sort by a stable
   column (unique where possible).
 
-Offset-only (the `usePaginatedQuery` numbered pages and the `useQuery` / manual `rpc` cap paths):
+Offset-only (`page`, `limit`, and manual `rpc`):
 
 - **Deep pages cost more.** `offset: n` makes the server produce and discard `n` rows before the
   page — page 200 is materially slower than page 2. Prefer narrowing filters over deep paging.
@@ -268,27 +250,21 @@ Offset-only (the `usePaginatedQuery` numbered pages and the `useQuery` / manual
   shifts every later offset — a row can appear on two consecutive pages or fall between them. If
   you concatenate offset pages yourself, key rows by `__source_record_id` (never by array index)
   and dedupe if the list must be exact.
-- **`count: true` counts the filtered set**, ignoring sort/limit/offset — `usePaginatedQuery`
-  issues it automatically. The count and the page are separate requests, so under concurrent
-  writes `total` can briefly disagree with what paging finds.
-- **A count is a full re-execution of the named query, not a cheap lookup.** It costs what the
-  query costs and grows with the filtered set — on a union/unpivot pipeline that is a whole extra
-  scan. When the screen already renders that same number from an aggregate, hand it to
-  `usePaginatedQuery` as `total` rather than paying for it twice (below).
+- **The count and the page are separate requests**, so under concurrent writes `total` can briefly
+  disagree with what paging finds.
 
-### `useQuery`
+### Rows
 
 ```tsx
 const { rows, loading, error, refetch } = useQuery("openOrders", { status: "open" });
 ```
 
-One fetch. `params` is required when the alias declares params, optional otherwise. Returns
-`{ rows, truncated, loading, isValidating, error, refetch }`. `rows` is
-`Array<Record<string, unknown>>` — decode cells with the readers below.
+`params` is required when the alias declares params, optional otherwise. `rows` is typed from the
+alias's projection ([below](#decoding-query-cells)) — decode cells with the readers.
 
 **`truncated` — the one thing a short result cannot tell you itself.** It is `true` when more rows
 matched than arrived, so `rows` is short and anything folded off it (a grouped period × site table,
-a per-carrier ratio, a KPI strip) is under-reported. The limit is your `pageSize` when you set one
+a per-carrier ratio, a KPI strip) is under-reported. The cap is your `limit` when you set one
 and the server's 10,000-row cap otherwise. Nothing else says so — there is no error, no empty state
 and no visual tell — so read it wherever the screen computes a figure from the whole result, and
 say the report is short rather than printing a number that is quietly wrong:
@@ -300,74 +276,50 @@ return <>{truncated && <Callout tone="warning">Số liệu chưa đủ — thu h
         <Stat value={total} /></>;
 ```
 
-### `useInfiniteQuery`
+### A feed — `more`
 
 ```tsx
-const { rows, loadMore, hasMore, loadingMore } = useInfiniteQuery("feed", {}, { pageSize: 30 });
+const { rows, loadMore, hasMore, loadingMore } = useQuery("feed", {}, { more: 30 });
 ```
 
-The first render loads one page; `loadMore()` appends the next, accumulating into `rows`. Paging is
+The first render reads one page; `loadMore()` appends the next, accumulating into `rows`. Paging is
 **keyset (seek)** (the pagination models above).
 
-- `hasMore` is `true` while the last page came back **full** (a non-null cursor came back) — so a
-  total that is an exact multiple of `pageSize` costs one final short fetch before `hasMore` turns
-  `false`.
+- `hasMore` is `true` while the last page came back with a next cursor — so a set that is an exact
+  multiple of `more` costs one final short read before `hasMore` turns `false`.
 - `loadMore()` is a no-op while `loadingMore` is `true` or when `hasMore` is `false` — safe to wire
   directly to a scroll sentinel.
-- Changing any part of the result-set identity (`params`, `sort`, `filter`, `pageSize`) starts a
-  fresh accumulation from the first page.
-- `refetch()` revalidates every loaded page. Appending a page does **not** re-fetch earlier pages,
-  so a long-lived list still mixes page snapshots taken at different times (an edit between two
-  page loads shows old and new side by side) — but keyset guarantees no row is skipped or repeated.
+- Changing any part of the result-set identity (`params`, `sort`, `filter`, `more`) is a new feed.
+- `refetch()` re-reads every loaded page. Appending a page does **not** re-read earlier pages,
+  so a long-lived list still mixes page snapshots taken at different times — but keyset guarantees
+  no row is skipped or repeated, and this app's own writes are drawn over every page.
 - **Standalone (public) apps:** `loadMore()` can't advance past page one — the cursor is dropped in
   transit (see [Standalone transport](#standalone-public-transport)).
 
-### `usePaginatedQuery`
+### Numbered pages — `page`
 
 ```tsx
-const { rows, total, totalPages, page, setPage, hasMore } =
-  usePaginatedQuery("orders", { q }, { pageSize: 25, sort, filter });
+const { rows, total, pageCount, page, setPage, hasMore } =
+  useQuery("orders", { q }, { page: 25, sort, filter });
 ```
 
-The page-model hook behind a numbered table (pairs with `@lotics/ui` `Pagination`). It owns the
-page cursor and fetches two things: the current page, and a `count` over the filtered set — unless
-you supply the total yourself.
+The page model behind a numbered table (pairs with `@lotics/ui` `Pagination`). It owns the page
+index and reads two things: the current page, and a count over the filtered set.
 
-- **Result-set identity is `(params, filter)`.** Changing either resets to page 0 and recounts.
-  Changing only `sort` does **neither** — the count is sort-independent and you stay on the same
-  page number of the new order (re-sorting never recounts, and never jumps you back to page 0).
-- The count is keyed on `(alias, params, filter)` — page clicks and re-sorts reuse it.
+- **Result-set identity is `(params, filter, sort)`.** Changing any of them resets to page 0.
+  Changing `sort` does not recount: the count does not depend on the order.
 - `page` is 0-indexed. `setPage` clamps at 0 but has **no upper clamp** — a page past the end
   returns empty rows.
-- `total` and `totalPages` are `undefined` until the count resolves — render pagination controls
-  defensively. `totalPages` is `max(1, ceil(total / pageSize))`. Until the count lands, `hasMore`
+- `total` and `pageCount` are `undefined` until the count answers — render pagination controls
+  defensively. `pageCount` is `max(1, ceil(total / page size))`. Until the count lands, `hasMore`
   falls back to "the current page came back full".
-- A page change **keeps the previous rows on screen** while the next page loads (built-in
-  `keepPreviousData`) — gate any skeleton on `loading && rows.length === 0`, never on `loading`
-  alone, or every page click collapses the table.
-- **`total` in the options suppresses the count request entirely.** Reach for it when the screen
-  already has that figure — a summary reading "N items" beside a table of those N rows is
-  otherwise executing the same query twice, and both executions grow with the set.
-
-  ```tsx
-  const summary = useQuery("orderStats", params);        // one ungrouped aggregate
-  const rows = usePaginatedQuery("orders", params, {
-    pageSize: 100,
-    total: (summary.rows[0]?.row_count as number | undefined) ?? null,
-  });
-  ```
-
-  **Three states, all of them in the type**: omitted → the hook counts; `null` → yours, not
-  resolved yet; a number → yours, use it. The `?? null` is what makes it work — the natural source
-  is an aggregate still loading on the first render, and without a way to say "mine, pending" the
-  hook would fire the very count it exists to avoid and discard it a moment later. Until the number
-  arrives the hook reports `total: undefined` and `hasMore` falls back to "the page came back
-  full", exactly as while a count is in flight.
-
-  `refetch()` does not refresh a supplied total — it is yours, so refresh its source.
-
-  The number must count the **same set** the query returns — `totalPages` and `hasMore` derive
-  from it and the hook cannot tell that it doesn't.
+- A page change **keeps the previous rows on screen** while the next page loads — gate any skeleton
+  on `loading && rows.length === 0`, never on `loading` alone, or every page click collapses the
+  table.
+- **`total: false` sends no count.** Reach for it when "of N" earns less than a second full
+  execution of the query; `pageCount` then stays `undefined` and `hasMore` reads "the page came
+  back full". A summary showing "N items" beside the table reads this read's `total` rather than
+  counting again.
 
 ## Standalone (public) transport
 
@@ -376,20 +328,18 @@ An app served standalone on its own origin (a public share with no Lotics host
 `alias`, `params`, `limit`, and `offset`. It **silently drops** `sort`, `filter`, `count`, and the
 keyset `cursor`. Design a public app around this:
 
-- **Runtime `sort` / `filter` are ignored** — every hook's `opts.sort` / `opts.filter` is dropped,
+- **Runtime `sort` / `filter` are ignored** — every read's `sort` / `filter` is dropped,
   so a standalone app can't order or narrow a query at the call site. Bake ordering and scoping
   into the query **template** (or drive them through declared `params`), not the refinement options.
-- **`usePaginatedQuery` gets no count** — the `count` request is dropped in transit, so a numbered
-  "Page 1 of N" control has no N unless you supply one. Pass `total` from a figure the app already
-  reads (an aggregate query survives the thin transport fine); with neither, `totalPages` never
-  lands, `hasMore` falls back to "the current page came back full", and `useInfiniteQuery` is the
-  better shape.
-- **`useInfiniteQuery.loadMore()` never advances past the first page** — with the cursor dropped,
-  no `next_cursor` comes back, so `hasMore` is `false` after page one. For a standalone browse,
-  size the template `limit` (or a `params`-driven page) to return the whole set in one fetch.
-
-The embedded product host and the `lotics app dev` forwarder pass all of these through — this
-caveat is standalone-only.
+- **`total` gets no count** — the `count` request is dropped in transit, so a numbered
+  "Page 1 of N" control has no N: `pageCount` never lands and `hasMore` falls back to "the current
+  page came back full". A figure the app needs comes from an aggregate query, which survives the
+  thin transport fine.
+- **A `more` feed never advances past the first page** — with the cursor dropped, no
+  `next_cursor` comes back, so `hasMore` is `false` after page one. For a standalone browse, size
+  the template `limit` (or a `params`-driven page) to return the whole set in one read.
+
+The embedded product host passes all of these through — this caveat is standalone-only.
 
 ## Decoding query cells
 
@@ -409,7 +359,7 @@ Wire shapes per output column type:
 | `select` | `Array<{ key, label }>` — one entry per selected option |
 | `select_member` | `Array<{ id, name, email?, image?, groups? }>` — the last three only for authenticated viewers of the app's own org; `image` presigned |
 | `select_record_link` | `Array<{ id, display }>` — target record id + its display text |
-| `files` | `Array<{ id, filename, mime_type, url, thumbnail_url?, size?, created_at? }>` — presigned |
+| `files` | `Array<{ id, filename, mime_type, url, thumbnail_url?, size?, created_at?, document_template_id? }>` — presigned |
 
 Row-level (non-grouped) queries additionally carry system columns: `__source_record_id` /
 `__source_table_id` / `__source_locked` (source addressing — pass `__source_record_id` to
@@ -417,15 +367,11 @@ workflows), `__created_at` / `__updated_at` (record timestamps), and per-project
 metadata. A grouped query collapses rows and emits none of these. Details:
 [./queries.md](./queries.md).
 
-A row is typed from the alias's own projection. Codegen names the columns each query carries
-(`AppQueryColumns` in `.lotics/app_queries.d.ts`) and a row read is bounded to them, so a misspelt
-column, a renamed field and a projection moved to a sibling alias are one `tsc` error rather than a
-blank cell — the server answers an unprojected column with `undefined`, and every reader below
-answers `undefined` with its empty value, so nothing else reports it. The values stay `unknown` (a
-column's TYPE is the field's, which the manifest does not carry, so the readers are the narrowing),
-while `__source_record_id` / `__source_table_id` are typed `string | undefined` — reachable without
-a cast, but only after narrowing, because "a grouped query emits none of these" is a fact the type
-states rather than one you have to remember. Write the row type down as `RowOf<"alias">`; an alias
+A row is typed from the alias's own projection (`AppQueryColumns` in `.lotics/app_queries.d.ts`),
+so a misspelt column is a `tsc` error rather than a blank cell — the server answers an unprojected
+column with `undefined`, which every reader draws as its empty value. The values stay `unknown`
+(the readers are the narrowing), and `__source_record_id` / `__source_table_id` are
+`string | undefined`, narrowed before use. Write the row type down as `RowOf<"alias">`; an alias
 whose columns cannot be read off its AST keeps the open `QueryRow`, where any column compiles and
 the server's answer is the only check — the rule the filter keys follow too.
 
@@ -478,73 +424,47 @@ a partial as its period start.
 `label === key` (the stale state is explicit, never hidden). Render with `@lotics/ui` `Status`
 — see [./members_and_options.md](./members_and_options.md).
 
-**`readMembers`.** `name` is `null` when the id doesn't resolve in the app's org (e.g. a removed
-member) — fall back explicitly. `email` is present only on authenticated responses from the app's
-own org; anonymous public visitors and cross-org viewers get name only (no PII exposure). Cells
-never carry avatar images — the avatar lives on the `useMembers` roster
-([./members_and_options.md](./members_and_options.md)).
+**`readMembers`.** The member shape, its gates and its `null` name:
+[./members_and_options.md](./members_and_options.md#member-cells-readmembers).
 
 **`readLinks` / `row.link`.** `display` is the linked record's primary-field text — render it;
 use `id` to correlate, filter (link `has_any_of`), or fetch detail. `row.link` is the first of
 `readLinks` — on a multi-link field use `readLinks`. An entry carrying an `id` and **no
-`display` key** is not a link and is skipped: a member cell has that shape, so reading one as a
-link would otherwise render every assignee under a blank name. Read a member cell with
-`readMembers`. **A LOOKUP of a link field arrives one level deeper** — one entry per linked
-record, each entry that record's whole link cell — and both readers open it, in order and with a
-record two linked rows point at named once, so a looked-up link needs no unwrapping of its own.
-
-**`readFiles`.** Each entry's `url` (and `thumbnail_url` for images) is **presigned with a 24-hour
-TTL** — it renders directly in an `<Image>`/preview and works from the sandboxed iframe and for
-anonymous public-app visitors; re-querying refreshes the TTL naturally. Entries the server didn't
-presign (no `url`) are skipped, so you never render an unservable file. `size` (bytes) and
-`created_at` (ISO upload timestamp) are resolved at serving time; `size` is absent for older files
-not yet backfilled — render it only when present, and surface both as dedicated sortable columns
-over the raw values (a formatted "8.4 MB" string sorts wrong). **A LOOKUP of a files field arrives
-one level deeper**, exactly as a looked-up link does — one entry per linked record, each entry that
-record's whole files cell — and `readFiles` opens it, in link order and with a file two linked rows
-both carry named once, so a looked-up picture needs no unwrapping of its own. Previewing and
-uploading files: [./files.md](./files.md).
-
-**Warning — the presign ceiling:** signing file URLs is per-entry server work, so a response is
-capped at **2,000 file entries** (server default). A query over the cap **fails** with an error
-naming the count and the remedies — it never silently returns unsigned cells. Project `files`
-columns **only in the query that renders them**, narrow with a filter, or paginate. A bare
-`from_table` with no projection ships every column — including `files` — and is how you hit this.
+`display` key** is not a link and is skipped (a member cell has that shape — read it with
+`readMembers`). **A LOOKUP of a link field arrives one level deeper** — one entry per linked
+record, each that record's whole link cell — and both readers open it, in order, naming a record
+two linked rows point at once.
+
+**`readFiles`.** Presigned 24-hour URLs, lookups opened like `readLinks`, and the 2,000-entry
+presign ceiling that fails a file-heavy query whole:
+[./files.md](./files.md#file-cells-in-query-results--readfiles-and-appfile).
 
 **`readLocked`.** Takes the whole row object, not a cell. A locked record rejects direct writes —
 show the locked state and route edits through the locked-change request flow
 ([./mutations.md](./mutations.md)).
 
-**`readCreatedAt` / `readUpdatedAt`.** Take the whole row object, not a cell. They give a table with
-no date field of its own a chronological anchor — a kardex/statement date, an "as of" caption —
-without adding a field or a stamping workflow. Unlike a `date`/`datetime` CELL (a timezone-less
+**`readCreatedAt` / `readUpdatedAt`.** Take the whole row object, not a cell. Unlike a `date`/`datetime` CELL (a timezone-less
 workspace wall-clock at minute precision), these are true **instants**: ISO-8601 with an offset on
-the wire, parsed as instants, rendered in the viewer's zone. `null` on a grouped row, which has no
+the wire, parsed as instants, dated in the workspace's zone — `useWorkspaceTimezone()`, which
+the app's root hands the kit's locale ([members & options](./members_and_options.md)). `null` on a grouped row, which has no
 originating record.
 
 ## Complete select option sets
 
-A query cell carries only the options a record actually holds (key + label, no color). For the
-**complete** option list of a select column — every option including those in no current row, with
-colors — use **`useFieldOptions`**, and prefer it over deriving options from loaded rows
-(row-derived sets are incomplete until every page loads and carry no colors). Its full contract
-(return shape, `byKey`, `opts.enabled`, freshness), rendering the values (`Status`,
-`MemberChip`, `MemberSelect`), and the member roster (`useMembers`) live in
-[./members_and_options.md](./members_and_options.md).
+For the **complete** option list of a select column, with colors, use **`useFieldOptions`** —
+never options derived from loaded rows, which are incomplete until every page loads
+([./members_and_options.md](./members_and_options.md)).
 
 ## Data discipline
 
-These rules prevent whole bug classes; every app follows them.
-
 - **Server data is never copied into `useState`.** `useQuery` / `useWorkflow` results are the
-  source of truth — derive everything else with `useMemo`. A second copy drifts and serves stale
-  values.
+  source of truth — derive everything else with `useMemo`.
 - **Prefer derivation + callbacks over `useEffect`.** A derived value is `useMemo`; "state A
   changed → set state B" is both set in the one triggering callback. `useEffect` is for genuine
   external subscriptions (timers, DOM listeners, storage) — fetching is `useQuery`, not an effect.
 - **No layout shift on load or paging — the UX bar, not a nicety.** (1) First load renders
   `Skeleton` placeholders that mirror the final layout, not a bare spinner; (2) a page change keeps
-  the previous rows (`usePaginatedQuery` does this for you) — gate the skeleton on
+  the previous rows (every read does this for you) — gate the skeleton on
   `loading && rows.length === 0`, never `loading` alone; (3) a view↔edit toggle reserves the
   input's height so pressing Edit never reflows.
 - **Diff before update.** An edit form snapshots the record at load and sends only the CHANGED
@@ -565,23 +485,20 @@ pieces. Compose these — don't hand-roll search:
 - **A parameterized `search` query** — a `from_table` with `search: "{{params.q}}"` over the
   maintained search document: **diacritics- and case-insensitive**, trigram-indexed, and AND-ed
   with the template's `filter` (search within a scope). The full `search` contract is in
-  [./queries.md](./queries.md). Reserve an OR-group of per-field `contains` only when you must
-  bound exactly which fields match — `contains` is **unindexed**, so a zero-match keystroke
-  forces a full table-partition scan. **Search-as-you-type uses `search`, never a `contains`
-  OR-group.**
+  [./queries.md](./queries.md). To bound exactly which fields match, AND an OR-group of per-field
+  `contains` with the same `search`: alone, `contains` is **unindexed**, so a zero-match keystroke
+  forces a full-table scan. **Search-as-you-type uses `search`, never a `contains`
+  OR-group alone.**
 - **`useQuery(alias, { q }, { enabled })`** — gate on a non-empty term: an empty term applies no
   search constraint and would dump the table on first paint. `enabled` makes "nothing loads until
   you type" true. Add `revalidateOnFocus: false` — re-running an ephemeral search on refocus is
   wasted work.
 - **Debounce the term — `enabled` is not a substitute.** `enabled` decides *whether* to ask, not
   *how often*: wire an input's own state into `params` and every keystroke past the first is a
-  fresh cache key and a fresh request. A six-letter name costs six, and on a list screen each one
-  is several — `usePaginatedQuery` re-counts whenever `params` change, and any sibling query
-  taking the same term goes with it. Keep the input's value in one state and debounce the COMMIT
-  into a second (`useDebouncedCallback` from `@lotics/ui/use_debounced_callback`, ~250 ms). The
-  two values are genuinely different — what is being typed, and what the rows on screen answer —
-  and anything reporting on the results (an empty state, a count, a "showing N for X" line) reads
-  the committed one, or it describes a set the server was never asked for. `Combobox` already
+  fresh cache key and a fresh request (and a re-count, where `total` is asked). Keep the input's
+  value in one state and debounce the COMMIT into a second (`useDebouncedCallback` from
+  `@lotics/ui/use_debounced_callback`, ~250 ms); anything reporting on the results (an empty state,
+  a count) reads the committed one. `Combobox` already
   debounces its own `onSearchChange`; this is for a search box you built yourself.
 - **`useRecents(key, { max })`** — persist the picked option locally; pass its list as
   `recentOptions` ([./navigation_and_state.md](./navigation_and_state.md)).
@@ -615,14 +532,16 @@ they can browse (numbered pages), search, sort, and filter:
   pills (`FilterChip column=`) + `Table` + `Pagination`. It needs both `@lotics/ui` and the SDK (which is
   UI-free), so it lives in the app (e.g. a `record_picker.tsx`) — reuse it for any table by passing
   a different `alias` + column config.
-- **`usePaginatedQuery`** drives it: the page of rows, the `total` for "Page 1 of N" (the built-in
-  `count` request), and the page cursor.
+- **`useQuery(alias, params, { page: n, sort, filter })`** drives it: the page of rows, the
+  `total` and `pageCount` for "Page 1 of N" (counted by default with `page`), and `setPage`.
 - **Filter pills → runtime `filter`** via `columnFilterToConditions` (`@lotics/ui/column_filter`);
   **column-header sort → runtime `sort`** by mapping the table's `{ key, order }` to
   `[{ field_key: key, order }]`. Both are server-bounded to the query's output columns — the picker
   can't widen exposure ([./queries.md](./queries.md)).
 - **Browse needs an unbounded query.** A `limit` baked into the query template caps the *total*
-  browsable set — paging then pages within that cap. Drop the template limit and let `pageSize`
+  browsable set — paging then pages within that cap. Drop the template limit and let `page`
   drive (the server row cap still bounds any single page).
 - **Select filter options come from `useFieldOptions`** — the complete set, not options derived
-  from loaded rows.
+  from loaded rows — and so does a number column's `units`, where each row reads it in its own:
+  a range on it names one, or the server refuses it
+  ([./members_and_options.md](./members_and_options.md)).