@lotics/app-sdk 0.46.1 → 0.47.0

package/AGENTS.md

@@ -1,397 +1,49 @@
-# @lotics/app-sdk — the SDK reference
-
-The **data + RPC** runtime for Lotics custom-code apps: typed React hooks over an
-origin-locked postMessage bridge, plus cell decoders and the `mount()` entry point. This
-file is the SDK reference — the "reach for what" guide + the load-bearing patterns. The
-**exact signature** of any hook or reader is its source, which ships with the package: read
-`node_modules/@lotics/app-sdk/dist/src/<name>.d.ts`. **Never guess a signature — open the
-file.**
-
-- Import from the package root: `import { useQuery, useWorkflow, row } from "@lotics/app-sdk"`.
-- **Data + RPC only — no UI.** The SDK ships zero components (keeps it off the React-Native-Web
-  tree). Render with **`@lotics/ui`** (read its `node_modules/@lotics/ui/AGENTS.md`); the two
-  pair — SDK fetches/mutates, `@lotics/ui` draws.
-- **Two transports, picked automatically.** Embedded (the authenticated product host bridges
-  RPC over postMessage) vs. standalone (`<slug>.lotics.app`, public, calls the API directly).
-  App code never branches on it; the SDK does.
-- **The app holds no credentials and writes nothing directly.** Every read is a declared named
-  query; every write is a declared workflow. The model, the IAM/auth rules, and the security
-  rationale live in **`docs/apps.md`** — read it for *why*; this file is *how*.
-
----
-
-## Reach by role — the surface
-
-Pick by intent. (→ open the `.d.ts` for the exact signature.)
-
-- **Read rows** — three hooks, one job each; don't overload one:
-  - **`useQuery(alias, params?, opts?)`** — a single fetch (`pageSize` is a cap, not pagination).
-    For a detail read or a combobox's top-N. `opts.enabled` gates the fetch (nothing loads until
-    true); `opts.sort` / `opts.filter` refine over the query's OUTPUT columns.
-  - **`useInfiniteQuery`** — append / load-more (`loadMore`, accumulating `rows`). Infinite scroll.
-  - **`usePaginatedQuery(alias, params?, { pageSize, sort, filter })`** — page-model with a
-    `total`, behind `Pagination`. Owns the page cursor; fetches the page AND a `count` keyed on
-    `(alias, params, filter)` (independent of page+sort, so paging/re-sorting never recount).
-    `(params, filter)` is the result-set identity — changing it resets to page 0 and recounts.
-- **A select field's options** — **`useFieldOptions(alias)`** → per select OUTPUT column, its FULL
-  `{ key, label, color }` list (incl. options not in any current row) + a `byKey` lookup. Populates
-  + colors pickers and stored values; tracks the table (a newly added/renamed option just renders).
-- **Mutate (the ONLY write path)** — **`useWorkflow(alias)`** → an async fn returning a typed
-  `WorkflowResult` `{ status, message?, files?, data? }`. `data` is whatever the workflow
-  `return({ data })`'d (typed automatically from the alias contract). After a known mutation,
-  call the owning query's `refetch()`. Handle failures by checking `result.status === "error"`,
-  not just `try/catch`: a transport/gateway failure (a 524 timeout on a long run, any 5xx, a
-  non-JSON error page) **resolves** with `{ status: "error", message }` (a friendly, body-free
-  message) — it does not throw an HTML body.
-- **Upload a file** — **`useFileUpload()`** → `{ upload, uploading, error }`. Mints a presigned URL
-  and PUTs the bytes straight to storage; the file is inert until a workflow attaches it to a
-  `files` field. Emits `app_file_uploaded`.
-- **Composer attachments (with instant preview)** — **`useAttachments()`** → `{ files, add, remove,
-  clear, uploading, fileIds }`. The chat's optimistic-preview UX in one hook: `add(File[])` shows a
-  local object-URL preview AT ONCE and uploads in the background; each `files[]` entry carries
-  `{ id, filename, mime_type, preview_url, status, file_id? }`; previews are revoked on remove/clear.
-  Picking is yours (button → `@lotics/ui` `pickFiles`, or paste/drop) — pass the `File[]` to `add`.
-  Wire to `@lotics/ui` `Composer`: `actionsButton` triggers the pick, then map each `AttachedFile`
-  to a `DisplayFile` (snake → camel — `mime_type`→`mimeType`, `preview_url`→`url` — the app owns this
-  data→UI adapter; the SDK never imports `@lotics/ui`) for
-  `<FileThumbnail file={{ id, filename, mimeType, url }} uploading={f.status === "uploading"} />`;
-  `sendDisabled` gates on `uploading` and the send payload is `fileIds`. To persist several files into ONE
-  record, declare the workflow input `{ type: "file", multi: true }` — the body receives `fileIds` as
-  `ReadonlyArray<FileId>` and writes it straight to a `files` field (a single `file` input is one id → wrap `[id]`).
-  Don't hand-roll
-  `createObjectURL`/upload/revoke per app. For a full add-files SCREEN (not the composer pill), map
-  each `AttachedFile` to a `FileUpload` (ready → `{ status: "complete", id, file }`, else
-  `{ status, id, filename, mimeType: mime_type, previewUrl: preview_url }`) and feed `@lotics/ui`
-  `FileGrid`'s `uploads` — it renders the uploading/error/retry tiles itself (see the kit AGENTS.md
-  Attachments recipe).
-- **List members** — **`useMembers(opts?)`** → `{ members: {id,name,email,image}[], loading, error }`
-  — the candidate set for an assign/picker. Gated: the app must declare a `member`-typed input
-  (`opts.group` restricts to a declared group). Render with `@lotics/ui` `MemberSelect` / `MemberChip`.
-- **Comments on a record** — **`useComments({ record_id })`** / **`useCommentCounts({ table_id })`**.
-  Capability-gated (`"capabilities": { "comments": true }` in the manifest) AND members-only — check
-  `available` before showing a composer. Runs under the VIEWING member's authority (author = the
-  viewer), unlike queries/workflows (owner authority). Render with `@lotics/ui` `comments_thread`.
-- **Who's viewing** — **`useViewer()`** → the signed-in member (the *viewed* member under "View as").
-  Display-only — personalize or attribute; **never** scope rows by it (use an `is_current_member`
-  query filter server-side). Returns null for an anonymous public visitor.
-- **Run an AI agent** — **`useAgentRun(alias)`** → `{ run, cancel, abort, status, items, text, steps,
-  output, error }` (agent declared in `package.json#lotics.agents`, authored via `set_app_agent`).
-  `run(input, { sessionId })` streams it. TWO kinds, both first-class: a **structured** agent (declares
-  `outputs`) lands its typed result in **`output`** (the `submit_result` shape) — `undefined` if the run
-  produced none, **never a stray string** (so a present `output` is the declared shape; still validate
-  untrusted INNER fields the model authored, e.g. an array that may be missing/mistyped); a **free-text**
-  agent's answer is the transcript prose (**`text`**). Feed the live **`items`** transcript straight to
-  `@lotics/ui` `AgentRun` — `<AgentRun items={run.items} state={run.status === "streaming" ? "streaming"
-  : run.status === "error" ? "error" : "done"} labelForTool={…} />` — NO hand-assembly (`text`/`steps`
-  are backward-compat views of `items`). The transcript carries the agent's **thinking** (a distinct
-  `reasoning` segment, kept OUT of `text`) and each tool's **input / output / running→done→error state**;
-  `AgentRun` shows thinking collapsed and tool I/O in a press-to-open peek (revealed on demand, not in the
-  feed) — all for free, no extra wiring. Wire a Stop button to **`cancel()`** (stops the run server-side,
-  saves tokens; `abort()` is local-only, for unmount). `run()` THROWS on quota/network — try/catch +
-  surface. Needs an authenticated member (embedded apps only, no anonymous runs). Image/PDF `file`
-  inputs are materialized into the agent's vision — pair with `useFileUpload`. `items`/`cancel` need
-  `@lotics/app-sdk` ≥ 0.43; the reasoning + per-tool I/O reveal needs `@lotics/ui` ≥ 7.13.
-- **Device location** — **`requestGeofencedLocation(zones)`** → a structured outcome
-  `{ ok:true, coords } | { ok:false, reason:"denied"|"unavailable"|"outside" }`; **`isWithinZone`**
-  is the pure check. Read directly in the iframe (host delegates the permission); the gate is
-  client-side advisory — pass `coords` to a workflow to record where an action happened.
-- **Recents** — **`useRecents(key, max)`** → most-recent-first, deduped, capped, `localStorage`-backed
-  (web-only, which is why it's here, not in `@lotics/ui`). Feeds a `Combobox`'s `recentOptions`.
-- **Shareable view-state (filters in the URL)** — **`useUrlState(shape)`** → `[values, setValues]`,
-  keeping a declared slice of state (filters, search, sort, the active tab) in the **address bar** so a
-  view survives refresh and is shareable/bookmarkable. `setValues` replaces in place. Build `shape` from
-  **`urlParam`** codecs. See *Save view-state to the URL*.
-- **In-app routing** — **`AppRouter`** (from `@lotics/app-sdk/router`) → wrap a react-router route config;
-  the app owns its own url (embedded, that's the iframe's own url — never the host's), so navigation never
-  reloads the app, browser back/forward walk app screens, and screens stay shareable + refresh-survivable.
-  See *In-app navigation*.
-- **Optimistic mutation glue** — **`useOptimistic()`** → reconcile a workflow mutation against the
-  query cache for an interactive (calendar/kanban/grid) app. See the data-bound recipe.
-- **Infra** — **`mount(opts?)`** boots the app + analytics (call once at entry; PostHog is automatic,
-  no per-app wiring). **`rpc(op, payload)`** is the raw bridge (escape hatch; prefer the hooks).
-  **`openExternal(url)`** opens a link in a new tab (scheme-validated; host-mediated in the embed).
-  **`downloadFile(name, data, mime?)`** saves browser-built bytes (a `Uint8Array | Blob | string`) —
-  call it synchronously from the click that produced them.
-- **Chat handoff** — **`askAi({ prompt?, file_ids?, record_ids?, context? })`** opens the Lotics
-  messenger on a FRESH chat seeded with the given files (attached + previewed beside the chat),
-  records (the agent can read/act on them under the viewer's authority), a prefilled *editable*
-  prompt, and free-text grounding; the host stamps the app's identity automatically. Nothing runs
-  until the user presses send. **The razor**: outcome lands in *fields* → `useAgentRun` + a
-  review surface (the app's own structured commit path); outcome is a *file or an open-ended
-  answer* (edit this invoice, draft an email about this shipment) → `askAi`. Embedded-only —
-  rejects in standalone/dev. Name the task in `prompt` (Word/Excel bytes aren't inlined; a clear
-  brief makes the agent read the file first).
-
-### Decoding query cells — never hand-roll the serialization contract
-
-`useQuery` rows are `Record<string, unknown>`. Coerce each cell with a typed reader (`row.ts` /
-`select.ts` / `members.ts`); never re-implement `firstOpt`/`linkId`/`linkDisplay` — they rot.
-
-- **`row.opt/text/num/bool/date/datetime/link`** — scalar coercion. `row.date` = calendar day
-  (LOCAL midnight, time stripped); **`row.datetime`** keeps the wall-clock — use it (and project the
-  column `type:"datetime"`) when you need the time, or it prints `00:00`.
-- **`readSelect(cell)`** → `ResolvedOption[]` `{ key, label, color? }` (a cell carries key+label; the
-  `color` is populated by `useFieldOptions`, not the cell). **`readMembers(cell)`** → `{ id, name,
-  email? }[]`. **`readLinks(cell)` / `row.link`** → `{ id, display }`. **`readFiles(cell)`** →
-  `AppFile[]` with presigned `url` + `thumbnail_url` (24 h) **+ `size` (bytes) + `created_at` (ISO
-  date-added), resolved from the file object at read**. Surface size/date as **dedicated sortable
-  `Table` columns over the RAW numeric** — the `tpl_documents` document-register pattern (a `Size`
-  column `align:"right"` + an `Added` column, formatted only at display; NOT a crammed `FileRow` `meta`
-  string, which sorts wrong — "8.4 MB" < "96 KB"). `size` is absent for older files until backfilled —
-  render it only when present. **`readLocked(row)`** → `boolean` from the
-  `__source_locked` addressing column.
-- **`project` only what you render** and `filter` server-side: a bare `from_table` ships every column
-  — incl. `files` with storage keys — to the client (over-exposure + presign-500 at scale). A code
-  lookup is a parameterized `filter`, not load-all-then-filter-in-JS.
-
----
-
-## Data discipline (every app, prevents whole bug classes)
-
-- **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.
-- **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.** Reserve space while data loads:
-  (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 via `keepPreviousData`) —
-  gate the skeleton on `loading && rows.length === 0`, never `loading` alone, or every "next page"
-  collapses the table; (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 fields
-  to its update workflow (declare those inputs optional; an omitted input = not written). A full-form
-  snapshot re-writes locked fields (blocked even if unchanged), fires `before_update` autofills
-  spuriously, and clobbers concurrent edits. For a locked record (`readLocked`), the save becomes one
-  `request_locked_record_change` carrying the diffed `changes` + a reason.
-- **Reuse the kit's utilities** — `@lotics/ui` ships the formatters (`formatMoney`, `formatDate`/
-  `parseDate`/`toISODate`); never hand-roll `dd/MM` or `₫`. Grep `@lotics/ui` exports before writing one.
-
----
-
-## Search-as-you-type
-
-A search-first picker (type → ranked results → pick) is one `@lotics/ui` component + three SDK pieces;
-compose these, don't hand-roll search:
-
-- **`Combobox`** (`@lotics/ui`) owns the interaction — debounced `onSearchChange`, a popover listbox
-  with rich rows (`renderOptionContent` reading `PickerOption.data`), keyboard nav, `recentOptions`,
-  `allowCustom`. (For a known small list with no search box, `Picker`.)
-- **A parameterized `search` query** — a `from_table` with `search: "{{params.q}}"` over the maintained
-  `search_document`: **diacritics- & case-insensitive** (`"da nang"` matches `"Đà Nẵng"`), trigram-
-  indexed (scales), privacy-aware. AND-s with `filter` (search within a scope). Reserve an OR-group of
-  per-field `contains` (accent-*sensitive*, unindexed) only when you must bound exactly which fields
-  match. **Search-as-you-type uses `search`, never a `contains` OR-group** — a zero-match keystroke on
-  `contains` forces a full-table scan that hangs the picker.
-- **`useQuery(alias, params, { enabled })`** — gate on a non-empty term; an empty term matches
-  everything (`ILIKE '%%'`) and dumps the table on first paint. `enabled` makes "nothing loads until
-  you type" true.
-- **`useRecents`** — persist the picked option; pass its list as `recentOptions`.
-
-Fetch detail on select with a SECOND parameterized query (a unique-code `equals`, or a link
-`has_any_of [record_id]`) — never a bare full-table load. To fetch a record by its **own id**, use the
-field-less **`record_id` system condition** (a sibling of `locked`/`current_member`, NOT a `field_key`):
-`useQuery(alias, {}, { filter: { node_type: "condition", type: "record_id", operator: "is_any_of", value:
-[id] } })` (`is_none_of` excludes). Works on any row-level query; a *grouped* query collapses rows so it's
-rejected there. A link `has_any_of [record_id]` matches a *related* record; `record_id` matches the row's
-own id — the only way, since a record has no field holding its own id. **Prefer a link/join when an actual
-relationship exists**; reach for `record_id` only when your starting point is a bare id (e.g. a drill row).
-
-## Browse + sort + filter (the record picker)
-
-When the user doesn't know the term — "show me everything, let me narrow it" — a modal table you can
-browse (numbered pages), search, sort, and filter:
-
-- **`TablePicker`** (`@lotics/ui`) is the data-agnostic base (a `Dialog` over `SearchInput` + filter
-  pills + `Table` + `Pagination`); it owns nothing about records — the consumer passes `columns` + one
-  page of `rows` and owns the search/sort/filter/page state. Filter pills are `ColumnFilter` +
-  `columnFilterToConditions`.
-- **A records wrapper lives in the app** (e.g. `record_picker.tsx`) — it needs BOTH `@lotics/ui` and
-  the SDK (which is UI-free), so it can't be a package. It runs a named query via `usePaginatedQuery`
-  and feeds the page into `TablePicker`. Reuse it for any table by passing a different `alias` + `columns`.
-
-The pieces that make it work:
-- **Runtime `sort`/`filter` are server-bounded to the query's OUTPUT columns** (an un-projected
-  `field_key` → 400) — the picker can't widen exposure. Build `filter` with `columnFilterToConditions`;
-  map sort `{key,order}` → `[{field_key, order}]`.
-- **The total comes from `count: true`** — a single-row COUNT over the filtered set (ignores
-  sort/limit/offset), driving "Page 1 of N".
-- **Browse needs an unbounded query** — a baked-in AST `limit` caps the *total*; drop it and let
-  `pageSize` drive.
-- **Select filter options:** prefer `useFieldOptions` for the COMPLETE set (not options derived from
-  loaded rows, which are incomplete until every page loads).
-
-## Rendering table primitives — select colors & members
-
-Two of the most common cells render the platform way with zero hand-rolling; hand the value to its
-`@lotics/ui` component — never re-derive an option→color map or a hand-built avatar (both rot):
-
-- **Select value** → `OptionBadge` (`@lotics/ui`) with its CONFIGURED color. Stored value:
-  `byKey(readSelect(cell)[0]?.key)` from `useFieldOptions`; picker option: a `useFieldOptions` option.
-  Multi wraps; a missing/unknown color degrades to neutral.
-- **Member** → `MemberChip` (avatar + name; the universal person render) and `MemberSelect` (the ready
-  picker — a `Picker` of `MemberChip`s). Feed from `useMembers`. (Avatars stay in the bounded, cached
-  roster — presigned files, never fattened onto every query cell; select color is a cheap token, so it
-  rides in `useFieldOptions`.) Full props: `@lotics/ui/AGENTS.md`.
-
-## Previewing files
-
-Render any uploaded file inline — image, PDF, video, audio, Word, Excel, CSV — with `@lotics/ui`; never
-hand-roll per-type rendering, and don't fall back to `openExternal` for a preview (that's "download /
-open elsewhere", not viewing).
-
-- **`FileGalleryModal`** (full-screen viewer: toolbar = filename · counter · ⋯actions · close-✕, plus
-  prev/next + ESC) delegates to **`FilePreview`** (single-file), dispatching by MIME; the frontend
-  gallery uses the same renderer. Wire `onFilePress` → a `number|null` `activeIndex`.
-- **PDF renders INLINE** — bytes fetched and painted to a canvas (with a selectable text layer) via
-  `pdfjs-dist`, NOT a native `<iframe>` viewer: a nested PDF browsing context is blocked inside the
-  sandboxed, cross-origin app iframe; a canvas isn't, so preview works. `pdfjs-dist` ships in the app
-  starter (lazy-loaded — non-PDF apps pay no bundle cost).
-- File cells already carry presigned URLs — decode with **`readFiles`** → `AppFile[]`, map to
-  `DisplayFile` (`mime_type`→`mimeType`, `thumbnail_url`→`thumbnailUrl`). No round-trip, no URL
-  derivation, no server-side doc→PDF (rendering is client-side).
-- PDF (`pdfjs-dist`), Word (`@lotics/docx`), and Excel/CSV (`@lotics/xlsx`) all ship in the app starter,
-  lazy-imported — an app that never previews a type pays no bundle cost. Excel renders to a canvas with
-  live formula recalc; Word renders OOXML to the DOM. `@lotics/ui` is i18n/analytics-free: pass `labels`
-  + an `onError`. The toolbar's "open in new tab" can't pop a window in the sandbox — pass `onOpenExternal`
-  wired to the SDK's `openExternal` (omit it and the action hides).
-
-## Composable optional filters (one query, many scopes)
-
-Expose several INDEPENDENT filter axes the caller mixes freely from ONE named query — don't shard into
-a query-per-combination. Mark each scoping param `required: false`; the server **prunes every filter
-condition whose `{{params.x}}` the caller didn't pass** (then collapses empty groups), so an unset axis
-stops constraining instead of erroring (no-op for all-required queries).
-
-```jsonc
-"search": {
-  "ast": { "kind": "project", "from": { "kind": "from_table", "table_id": "tbl_items", "filter": {
-    "node_type": "group", "logic": "and", "children": [
-      { "node_type": "condition", "field_key": "status", "operator": "has_any_of", "value": ["{{params.status}}"] },
-      // keyword over two fields — the whole OR-group prunes when `keyword` is absent
-      { "node_type": "group", "logic": "or", "children": [
-        { "node_type": "condition", "field_key": "title", "operator": "contains", "value": "{{params.keyword}}" },
-        { "node_type": "condition", "field_key": "notes", "operator": "contains", "value": "{{params.keyword}}" } ] },
-      // date range — each bound is its OWN single-param condition, so an open-ended range prunes one side
-      { "node_type": "condition", "field_key": "created", "operator": "on_or_after",
-        "value": { "type": "exact", "date": "{{params.from}}", "time": null } },
-      { "node_type": "condition", "field_key": "created", "operator": "on_or_before",
-        "value": { "type": "exact", "date": "{{params.to}}", "time": null } } ] } }, "columns": [ /* … */ ] },
-  "params": {
-    "status":  { "type": "select", "options": [ /* … */ ], "required": false },
-    "keyword": { "type": "text", "required": false },
-    "from":    { "type": "date", "required": false },
-    "to":      { "type": "date", "required": false } }
-}
-```
-
-`useQuery("search", { keyword })` filters by keyword only; `{}` returns everything. **Dates:** there's no
-`date_range` param — embed a `date`/`text` param in a hand-built `DateTimePoint`
-(`{type:"exact", date:"{{params.from}}", time:null}`), one condition per bound so each prunes
-independently. Keep a scope that must always apply `required` (a missing required param 400s). Typos
-can't widen — deploy rejects a `{{params.x}}` with no declared param.
-
-## Save view-state to the URL (`useUrlState`)
-
-The filters above are the query's *server* params; **`useUrlState`** is their *client* home — save them to
-the host's address bar and a filtered view survives refresh and is shareable/bookmarkable as a link. Writes
-always **replace** in place (filter changes shouldn't add history entries); screen-to-screen navigation and
-history are the router's job (next section). The hook drives the host's URL over the bridge; the app can't
-touch the cross-origin host URL itself. Standalone apps drive their own URL — same code.
-
-```tsx
-const [filters, setFilters] = useUrlState({
-  q:      urlParam.string.withDefault(""),
-  status: urlParam.enum(["open", "won", "lost"]),         // optional → omitted when unset
-  tags:   urlParam.arrayOf(urlParam.string).withDefault([]),
-  page:   urlParam.number.withDefault(1),
-});
-// filters → { q: string; status?: "open"|"won"|"lost"; tags: string[]; page: number }
-const { rows } = usePaginatedQuery("search", { keyword: filters.q, status: filters.status }, { pageSize: 50 });
-setFilters({ status: "won" });                  // merge into the address bar → ?status=won
-setFilters({ page: 2 });                        // merge (replace; no history entry)
-```
-
-- **`urlParam`** codecs: `string` / `number` / `boolean` / `isoDate` / `enum([...])` / `arrayOf(inner)`,
-  each `.withDefault(v)` to make it required. **Defaults are omitted from the URL** (`page=1` never
-  appears) — links carry only what changed.
-- **The URL is the only store** — `filters` is decoded fresh each render; don't mirror it into `useState`.
-- **Declared keys only.** The app touches just the keys in `shape`; every other param (a second
-  `useUrlState`, the framework's own) is preserved on write — no namespace rule to remember.
-- **Search box:** keep the live input in local `useState` and commit to `setFilters` on a **debounce** —
-  in an embedded app each `setFilters` is a cross-frame write.
-
-## In-app navigation (`AppRouter`)
-
-For a multi-screen app, write plain react-router and wrap your routes in **`AppRouter`** (from
-`@lotics/app-sdk/router`) — it makes screens real, addressable URLs in both modes, with no per-mode code:
-
-```tsx
-import { AppRouter } from "@lotics/app-sdk/router";
-
-export default function App() {
-  return <AppRouter routes={[
-    { path: "/", element: <List /> },
-    { path: "/item/:id", element: <Detail /> },
-  ]} />;
-}
-```
-
-Inside, use react-router normally — `useNavigate`, `useParams`, `<Link>`.
-
-- **Embedded** (in the Lotics host): the app drives the **iframe's own url** (same-origin to itself) via
-  `pushState`. The user sees the host's address bar, never the iframe's, so the screen url is invisible — and
-  the host never sees it, so navigation never reloads the app. The iframe's history participates in the
-  session history, so the **browser Back/Forward buttons walk app screens** (then leave the app). `AppRouter`
-  also mirrors the current screen into the host url (a non-remounting write) and the host bakes it back into
-  the iframe src on load, so a screen is **shareable and survives a full refresh** — no reload, no extra code.
-- **Standalone** (`<slug>.lotics.app`): a normal browser router — real path URLs, native browser back/forward,
-  refresh-survivable.
-
-`useUrlState` is the complement: in-app *routing* (screens) is automatic via `AppRouter`; reach for
-`useUrlState` for *filters/search* you want as first-class, typed, shareable query keys. `react-router-dom` is
-an optional peer — only apps that import `@lotics/app-sdk/router` pull it in.
-
----
-
-## Recipes (app actions beyond the hooks)
-
-Reverse-engineered once; full code in the `/app` skill's `references/recipes.md`.
-
-- **Generate a document → download** — the file returns in `WorkflowResult.files[]` (auto-extracted from
-  any step's `file_id`); open via `openExternal(files[0].url)`. Don't hand back a `url`/`file_id` from
-  `return()`.
-- **Export displayed data → .xlsx (client-side)** — `buildDataWorkbook({columns, rows})` (`@lotics/xlsx`)
-  → `exportWorkbook` → `downloadFile`. To export the WHOLE result (not one page), page the query
-  imperatively with `rpc("query", { alias, params, limit, offset })` to exhaustion (embedded-app only —
-  the public transport drops `sort`/`filter`).
-- **Workflow returns data → fill the UI** — `return({ data })` hands back any structured result, read as
-  a typed `result.data` (no schema needed; narrow before use — a fall-through completion returns none).
-- **Look up one record by a typed code** — a parameterized `{{params.x}}` filter + `useQuery(alias, {...})`,
-  so the client never receives other rows. Autonumber fields filter as text. (Public-app IDOR caveat:
-  `docs/apps.md`.)
-- **Interactive (read + mutate) app** — `row.*` to coerce + `useOptimistic` to reconcile; `@lotics/ui`
-  provides the drag-enabled calendar/gantt/kanban/grid.
-
----
-
-## Authority & scoping (the one-paragraph rule — full model in `docs/apps.md`)
-
-App data ops run under the **app owner's** principal, not the viewer's — so who-is-acting and per-user
-scoping are the author's job, never inferred. **Reads:** scope "my X" with the `is_current_member`
-operator in the query TEMPLATE (the server binds the signed-in viewer / the view-as subject) — never a
-client-supplied `member_id` (that's an IDOR; per-user data must not ship in a *public* app). **Writes:**
-derive the actor server-side — read `runtime.triggered_by_member_id` in the workflow body; a client
-`member` input is spoofable. **Privileged writes** (a role/group gate) authorize the caller in the
-workflow with `current_member_in_any_group(...)`, paired with a manager-only read. `useViewer()` is
-display-only, not an authorization fact. The full IAM model, public-access bounds, and the security
-rationale: **`docs/apps.md`**.
-
----
-
-## Keeping this file current
-
-This is the published SDK reference — agents read `node_modules/@lotics/app-sdk/AGENTS.md` when building
-apps. **Codify every new hook, reader, and load-bearing pattern here** in the same change that adds it
-(and bump the package version so it ships). Keep it tight: the catalog points at the `.d.ts` for exact
-signatures; the model/IAM/security rationale stays in `docs/apps.md` — link, don't duplicate.
+# @lotics/app-sdk — the SDK reference index
+
+The **data + RPC** runtime for Lotics custom-code apps: typed React hooks over an origin-locked
+postMessage bridge, cell decoders, and the `mount()` entry point. **Data + RPC only — no UI.**
+Render with **`@lotics/ui`** (read `node_modules/@lotics/ui/AGENTS.md`); the two pair — the SDK
+fetches/mutates, `@lotics/ui` draws.
+
+This file is the index. The comprehensive contract references live in **`docs/`** — read the
+owning area doc before building; it is the contract for a backend you cannot see. The **exact
+signature** of any hook or reader is its shipped source: `dist/src/<name>.d.ts` — **never guess a
+signature; open the file.**
+
+## The area references
+
+| Doc | Read it for |
+|---|---|
+| [docs/queries.md](./docs/queries.md) | **The query engine authoring reference** — AST node kinds, per-field-type operator support, filters/params/pruning, free-text search, combining tables (join/union/link/`unnest`/`record_id`), shaping (aggregates, date buckets, windows), runtime refinement bounds, limits & the efficiency playbook. |
+| [docs/data_fetching.md](./docs/data_fetching.md) | The three read hooks (`useQuery`/`useInfiniteQuery`/`usePaginatedQuery`), cell readers (`row.*`, `readSelect`, `readMembers`, `readLinks`, `readFiles`, `readLocked`), `useFieldOptions`, data discipline, the search-as-you-type + record-picker patterns. |
+| [docs/mutations.md](./docs/mutations.md) | `useWorkflow` (the ONLY write path), the `WorkflowResult` resolve-never-throw contract, typed inputs, diff-before-update, locked records, `useOptimistic`. |
+| [docs/files.md](./docs/files.md) | Files end to end — `useFileUpload`, `useAttachments`, `readFiles`/presigned URLs, workflow-generated files, preview pairing, filter operators, the server-side delivery bounds. |
+| [docs/members_and_options.md](./docs/members_and_options.md) | People + select options + comments — `useMembers`, `useFieldOptions`, `useViewer`, `useComments`, and the `@lotics/ui` components they feed. |
+| [docs/navigation_and_state.md](./docs/navigation_and_state.md) | `AppRouter` (embedded/standalone URL model), `useUrlState` + `urlParam` codecs, `useRecents`. |
+| [docs/ai.md](./docs/ai.md) | `useAgentRun` (structured vs free-text, streaming `items` → `AgentRun`) and `askAi` — plus the fields-vs-file razor for choosing between them. |
+| [docs/security.md](./docs/security.md) | **Read before shipping** — the owner-principal model, `is_current_member` scoping, write attribution, group gates, public-app bounds, what runtime refinement cannot widen. |
+| [docs/runtime.md](./docs/runtime.md) | `mount()`, the two transports, `rpc()`, `openExternal`/`downloadFile`, geofencing, analytics, and the publish chain for package contributors. |
+
+## Non-negotiables (each detailed in its doc)
+
+- **Authorization is server-side, on every path.** Apps run under the OWNER principal — scope
+  per-user reads with `is_current_member` in the query template, attribute writes from
+  `runtime.triggered_by_member_id`, gate privileged writes with `current_member_in_any_group`.
+  A client-supplied member id is an IDOR. → [security](./docs/security.md)
+- **Server data is never copied into `useState`** — hooks are the source of truth; derive with
+  `useMemo`. → [data_fetching](./docs/data_fetching.md)
+- **Update writes are diffs** — send only changed fields. → [mutations](./docs/mutations.md)
+- **`project` only what you render; filter server-side.** A bare `from_table` over-ships every
+  column, including files. → [queries](./docs/queries.md)
+- **Never hand-roll the serialization contract** — decode cells with the typed readers.
+  → [data_fetching](./docs/data_fetching.md)
+- **Errors fail loud** — no swallowed catches, no silent fallbacks.
+
+## Keeping this reference current
+
+These docs are the published contract — agents build apps from `node_modules` and cannot read the
+platform source, so a wrong or missing claim here becomes their bug. **Codify every new hook,
+reader, pattern, or contract change into its OWNING area doc + the index line above in the same
+change that adds it, and bump the package version** (publish CI fires on a version diff; `files`
+ships only on publish). Each fact lives in exactly one doc — link, never duplicate. The
+platform-internal model/IAM rationale stays in the repo's `docs/apps.md`.