@lotics/app-sdk 0.100.1 → 0.101.0

package/docs/recipes.md

@@ -1,7 +1,7 @@
 # Recipes — the app actions that are not obvious
 
-The other area docs describe contracts. This one is task-shaped: **"how do I do X"**, for the
-handful of actions whose mechanism is not guessable from the hooks alone.
+Task-shaped: **"how do I do X"**, for the actions whose mechanism is not guessable from the
+hooks. Each contract is its area doc's.
 
 ---
 
@@ -15,9 +15,8 @@ whose step output carries a `file_id` (`generate_pdf_from_template`, `generate_e
 `generate_word_from_template`) is auto-collected by the execute endpoint and comes back in
 **`result.files[]`**, each with a servable `url`.
 
-So the workflow only *generates*. It does not `update_records` — attaching the file to a record is a
-separate, optional step. And you cannot hand the file back through `return({...})`; that channel is
-for values, not files.
+So the workflow only *generates*; attaching the file to a record is a separate, optional step, and
+`return({...})` carries values, not files.
 
 ```js
 // workflow body — alias `genDebit`, input `record_id`
@@ -42,20 +41,16 @@ The `dtl_…` is a template you registered **once**, ahead of the app, through t
 `lotics docs document_templates` for the five types and how each is created. An app fills
 templates; it never authors them.
 
-**`openExternal` is the download primitive, not `window.open`.** The app runs in a sandboxed iframe
-with no `allow-popups`, so a bare `window.open` is dropped — no error, no navigation, nothing to
-debug. `openExternal` routes the open through the host frame.
+**`openExternal` is the download primitive, not `window.open`**, which the sandbox drops silently
+([runtime](./runtime.md)).
 
 ## Return structured data from a workflow
 
 A workflow can hand back a computed total, a list of rows, a status object — read by the app as a
 typed `result.data`, validated server-side against the alias's `outputs`.
 
-**You usually declare nothing.** `outputs` are derived at save time from the inferred type of your
-`return({ data })`, and `lotics app workflow set` writes that derived schema back into the manifest
-and refreshes the types in place — so `result.data` is typed immediately, with no hand-copy and no
-second `codegen`. Declare an explicit `outputs` only to narrow beyond what is inferred; it is then
-authoritative and never overwritten.
+**You usually declare nothing**: `outputs` are derived at save time from your `return({ data })`
+([mutations](./mutations.md)). Declare `outputs` only to narrow beyond what is inferred.
 
 ```js
 const rows = await query_records({ table_id: "tbl_x", filters: { /* … */ } });
@@ -76,8 +71,7 @@ literal enough to infer. Files still travel via `result.files`.
 
 ## Look up one record by a code the user types
 
-Filter **server-side** so the app never receives another row. A full-table query loaded and filtered
-in JS ships every record to the client.
+Filter **server-side** so the app never receives another row.
 
 ```jsonc
 "lookupShipment": {
@@ -114,26 +108,11 @@ Full pattern, including the date-param trick for range filters: `lotics docs que
 
 ## Decode cells with the accessors, never by hand
 
-A query cell is `unknown` with a per-type serialized shape:
-
-- `row.opt` / `row.text` / `row.num` / `row.bool` / `row.date` — scalars and the first value of a
-  select. `row.date` keeps only the calendar day; use **`row.datetime`** when the time matters.
-  `row.num` and `row.bool` answer `null` for an empty cell — an unanswered checkbox is not a "no"
-  any more than an empty number cell is a 0. Write `=== true` where only the affirmative acts, and
-  `?? 0` / `?? false` only where that side is the cell's correct reading.
-- `readSelect` — the full `{ key, label }[]` of a multi-select.
-- `readMembers` — `select_member` cells.
-- `row.link` / `readLinks` — `select_record_link` → `{ id, display }`. Read `.display` to render,
-  `.id` to correlate or filter.
-
-A hand-rolled `firstOpt` / `linkDisplay` is the most common drift in app code: it re-implements the
-serialization contract and rots silently when that changes. A select cell is `[{key,label}]`, so a
-reader that grabs the wrong half is *plausible and wrong* rather than broken.
-
-**Project what you render.** A bare `{ kind: "from_table", table_id }` with no `project` ships every
-column of every row — including `files` fields and any cost or PII column the UI never shows.
-Projecting file fields also mass-presigns, which 500s on a large result and survives only on tiny
-tables.
+A query cell is `unknown` with a per-type serialized shape, and the readers own it: `row.opt` /
+`row.text` / `row.num` / `row.bool` / `row.date` / `row.datetime`, `readSelect`, `readMembers`,
+`row.link` / `readLinks` ([data fetching](./data_fetching.md#the-readers)). A hand-rolled `firstOpt` /
+`linkDisplay` re-implements that contract: a select cell is `[{key,label}]`, so a reader that grabs
+the wrong half is *plausible and wrong* rather than broken.
 
 ## Set the icon and colour
 
@@ -149,17 +128,15 @@ lotics run search_app_icons '{"query":"shipping"}'   → ["truck","ship","packag
 
 `theme.color` is a named palette colour: `red orange amber yellow lime green emerald teal cyan sky
 blue indigo violet purple fuchsia pink rose slate gray zinc neutral stone`. `null` clears either.
-There is no `lotics app icon` subcommand; a deploy warns while they are unset.
+`update_app` sets both; a deploy warns while they are unset.
 
 **In-app palette** — the app's own `src/theme.ts`, exact hex. This is what the app *renders* with;
 the launcher colour does not feed it. Pick the named colour closest to your brand hex.
 
 ## Test an AI action without spending credits
 
-An app's `useAgentRun` runs the **real** agent even under `lotics app dev` — the dev harness proxies
-to the production endpoint, so every dev click spends the app org's credits. The SDK's fixture mode
-(`?__mock=1`) covers `useQuery` only; it does not mock an agent run. Iterating on a review screen
-would re-bill on every reload.
+An app's `useAgentRun` runs the **real** agent wherever the app runs, so every click spends the app
+org's credits, and the fixture mode (`?__mock=1`) does not mock an agent run.
 
 **Replay one captured run.** Capture a real `run.output` once, paste it as a constant, and gate on
 the same `?__mock=1` flag — so mocked rows and a mocked run activate together and dev is one
@@ -175,17 +152,16 @@ function Action({ input }: { input: AgentInput }) {
 
   async function propose() {
     if (MOCK) { setProposal(OUTPUT_FIXTURE); return; }   // no run, no credits
-    const output = await agent.run(input, { sessionId: mySessionKey });
-    if (agent.status === "error" || output === undefined) return;
-    setProposal(output);
+    const landing = await agent.run(input, { sessionId: mySessionKey });
+    if (landing.kind !== "settled" || landing.output === undefined) return;
+    setProposal(landing.output);
   }
   return proposal ? <ChangeReview /* … */ /> : /* trigger propose */;
 }
 ```
 
 Hold the proposal in local state rather than reading `agent.output`, since `run()` never fires in
-mock mode. Capture the fixture with
-`run(input, { sessionId }).then((o) => console.log(JSON.stringify(o)))`.
+mock mode. Capture the fixture by logging `JSON.stringify(landing.output)` from one real run.
 
 **This is not a substitute for one real end-to-end run before shipping.** The fixture exercises the
 UI downstream of the model and nothing else — not the agent, not its tools, not the server-side

package/docs/runtime.md

@@ -1,15 +1,9 @@
 # The app runtime
 
-How a custom-code app boots and talks to the platform: **`mount()`** (the entry
-point, including the design-time mock harness),
-the **two transports** the SDK switches between (embedded postMessage bridge vs.
-standalone direct API — app code never branches), the raw **`rpc()`** escape
-hatch, and the browser capabilities the sandbox would otherwise block —
-**`openExternal`**, **`downloadFile`**, and **`requestGeofencedLocation`** /
-**`isWithinZone`**. Ends with the contribution contract for the package itself
-(publish chain, wiring a new RPC op, bundler constraints). Read this when wiring
-an app's entry file, when a browser capability misbehaves inside the iframe,
-when you need to drop below the hooks, or when changing the SDK.
+How an app boots and talks to the platform: **`mount()`** (with the design-time mock harness),
+the **two transports** the SDK switches between (app code never branches), the raw **`rpc()`**
+escape hatch, and the browser capabilities the sandbox would otherwise block — **`openExternal`**,
+**`openApp`**, **`downloadFile`**, and **`requestGeofencedLocation`** / **`isWithinZone`**.
 
 ## `mount()` — the entry point
 
@@ -21,7 +15,7 @@ mount(<App />);
 ```
 
 `mount(element: ReactNode, options?: MountOptions): void` (exact signature:
-`dist/src/mount.d.ts`) is called **once** from the app's entry file. It:
+`dist/mount.d.ts`) is called **once** from the app's entry file. It:
 
 1. **Registers the mock fixture**, if `options.fixture` was passed (below).
 2. **Finds or creates `#root`.** Uses the `<div id="root">` from the scaffold's
@@ -29,7 +23,9 @@ mount(<App />);
 3. **Installs visible error handlers.** `window` `error` and
    `unhandledrejection` listeners render a fixed red monospace banner (message +
    stack) above the app — a render crash or an unhandled promise rejection is
-   visible in the iframe itself, even before any host telemetry is wired up.
+   visible in the iframe itself. Embedded, each also reaches Lotics through the
+   host (`reportAppError`: the error's class, a bounded message and its first
+   frame, with no origin, query or fragment; the first five per page load).
    Banners are informational only; they are not removed automatically.
 4. **Renders the tree** with React 19's `createRoot`.
 
@@ -41,7 +37,7 @@ The optional second argument registers a demo/design-time fixture:
 mount(<App />, {
   fixture: {
     queries: {
-      orders: MOCK_ORDERS,       // alias → rows, same aliases as package.json#lotics.queries
+      orders: MOCK_ORDERS,       // alias → rows, same aliases the app binds
       customers: MOCK_CUSTOMERS,
       // Or a FUNCTION of the call — how a surface that narrows per call
       // (a master/detail drawer) renders what production would.
@@ -66,12 +62,13 @@ Activation is a **two-step gate** — both must hold, so demo data shipping in t
 bundle never leaks into normal traffic:
 
 1. A fixture is registered via `mount({ fixture })` (`AppFixture` type:
-   `dist/src/mock.d.ts` — `{ queries?, workflows?, recordings? }`).
+   `dist/mock.d.ts` — `{ queries?, workflows?, recordings? }`).
 2. The page URL carries `?__mock=1` (exactly `1`). Without the flag the fixture
    is completely inert.
 
 When active, the [query hooks](./data_fetching.md) return `fixture.queries[alias]`
-instead of making any request (`loading` stays `false`). **Partial mocking is
+instead of making any request (`loading` stays `false`); a read with `enabled: false` asks
+the fixture nothing, as it asks the server nothing. **Partial mocking is
 supported**: an alias absent from the fixture still flows through the real
 transport. Calling `mount` again (HMR) replaces the registration last-write-wins.
 
@@ -80,11 +77,10 @@ transport. Calling `mount` again (HMR) replaces the registration last-write-wins
   serialized cells your `row.*` / `readSelect` / `readFiles` readers decode —
   or the readers will decode nothing.
 - **A ROW ARRAY answers every call to its alias identically.** The server applies
-  the per-call `filter` / `sort` / `pageSize` *after* the named query; a static
+  the per-call `filter` / `sort` / `limit` *after* the named query; a static
   array cannot, so a drawer narrowed with
   `useQuery("orderLines", {}, { filter: byOpenOrder })` shows every parent's
-  children under every parent — a screen that looks right and is wrong, which
-  defeats the review the mock path exists for. **Make such a fixture a function
+  children under every parent. **Make such a fixture a function
   of the call** (`({ params, filter, sort, limit }) => rows`) and narrow it
   there; a filtered call against a row array warns once per alias in the
   console. Do NOT compensate with a client-side re-filter in the app — that
@@ -92,13 +88,14 @@ transport. Calling `mount` again (HMR) replaces the registration last-write-wins
   look right.
 - **A mocked workflow does not RUN.** `useWorkflow(alias)` resolves the fixture
   entry and sends nothing, so there is no notification, no audit trail and no
-  spend — the side-effect argument is the reason to mock it, not a reason not
-  to. What a mock cannot produce is the followup state a later query would read;
-  that is yours to fixture too, exactly as it already is for queries.
+  spend. What a mock cannot produce is the followup state a later query would read;
+  that is yours to fixture too, exactly as it already is for queries. A settled
+  call re-asks every query fixture, so a workflow function that writes into what
+  a query function reads shows its effect with no reload — the same re-read a
+  deployed app makes against the server.
   **Reach the in-flight state with a function** that resolves on a timer: an app
   whose only AI surface is a workflow calling `agent(...)` otherwise has no
-  non-billing path to its own thinking / done / error screens, which is how
-  those three ship unreviewed.
+  non-billing path to its own thinking / done / error screens.
 - **A mocked recording is a canned state.** `recordings: { log_visit: { phase:
   "live", elapsed_seconds: 754, inputs: { site: "rec_1" } } }` makes
   `useRecording("log_visit")` available with that `state`; `start` and `stop`
@@ -122,15 +119,15 @@ at each call from the iframe URL: the embedding host passes its origin via the
 reserved `?lotics_host=` query param — present (non-empty) means **embedded**,
 absent means **standalone**. App code never branches on the mode; every hook and
 helper works identically in both. `isEmbedded(): boolean` is exported
-(`dist/src/rpc.d.ts`) for the rare display-level need, and the
+(`dist/rpc.d.ts`) for the rare display-level need, and the
 [security doc](./security.md) explains what mode implies for identity.
 
 | | **Embedded (bridged)** | **Standalone (direct)** |
 |---|---|---|
-| Where | Iframe inside the Lotics product, or the `lotics app dev` wrapper page | The app's own top-level page, on its own origin |
+| Where | Iframe inside the Lotics product | The app's own top-level page, on its own origin |
 | Who holds credentials | The **host** — the member's session never reaches the app | Nobody — the visitor is anonymous (an optional app password gates access, not identity) |
 | How ops travel | `postMessage` to the parent frame; the host makes the API call with its session | `fetch` to the public `/v1/apps/{id}/*` endpoints, at the API address the serving host declared in the page |
-| Which API | The host's, implicitly — it makes the call | `<meta name="lotics-api-base" content="…">` in the served document, read on the first call. **No address is compiled in**: one bundle runs on any Lotics, and a page that declares none makes the SDK refuse rather than address an instance nobody named. Every serving host injects it (the app host and `lotics app dev`), so there is nothing for an app to set |
+| Which API | The host's, implicitly — it makes the call | `<meta name="lotics-api-base" content="…">` in the served document, read on the first call. **No address is compiled in**: one bundle runs on any Lotics, and a page that declares none makes the SDK refuse rather than address an instance nobody named. The app host injects it, so there is nothing for an app to set |
 | Viewer identity | The signed-in member (`useViewer`, comments, agent runs available) | `member_id` is `null`; members-only surfaces reject |
 
 ### Embedded: the postMessage bridge
@@ -152,12 +149,10 @@ promise pending forever. Don't build UI that deadlocks awaiting an op you
 haven't verified exists in the host (see
 [op availability](#op-availability-by-transport)).
 
-**Warning (dev loop):** `lotics app dev` prints a wrapper URL — always drive
-*that* page. The wrapper embeds the app iframe with `?lotics_host=` and bridges
-ops to the API; the bare Vite origin has no host param, so the SDK falls into
+**Warning:** a bare Vite dev server has no host param, so the SDK falls into
 standalone mode, tries to resolve an app from the hostname, and every data call
-fails. Dev apps are always bridged; standalone mode exists only on the deployed
-app host.
+fails. Try an app by deploying it and opening it in the product; standalone mode
+exists only on the deployed app host.
 
 ### Standalone: direct public API
 
@@ -197,21 +192,19 @@ that is safe to render:
 Most ops work everywhere; the exceptions are members-only or host-only
 surfaces:
 
-| Op | Embedded (product) | `lotics app dev` | Standalone |
-|---|---|---|---|
-| `query`, `field_options`, `workflow`, `members`, `context`, `upload`, `urlState.get/set`, `openExternal` | yes | yes | yes |
-| `comments.*` | yes | yes | rejects — `"Comments are available only in embedded apps — a signed-in member is required."` |
-| `agentRun` (streaming, internal to `useAgentRun`) | yes | yes | yes |
-| `agentRun.get`, `agentRun.cancel` | yes | **no** — the dev forwarder doesn't implement them (`"Unknown RPC op: …"`) | yes |
-| `agentRuns` (session history) | **no** — the product host doesn't implement it either (`"Unknown RPC op: agentRuns"`) | **no** | yes |
-| `askAi` | yes | **no** — `"Unknown RPC op: askAi"` | rejects — `"askAi is only available when the app runs inside Lotics"` |
-| `openApp` | yes — routes to the sibling in the same tab | yes — opens the sibling on the web app in a new tab (one app is served locally) | rejects — `"openApp needs the Lotics host …"` |
-| `recording.start`, `recording.stop` | yes, when the context states `recording_enabled` | **no** — `"Unknown RPC op: …"`; the context omits `recording_enabled` | rejects — `"Recording needs the Lotics host and a signed-in member …"` |
+| Op | Embedded (product) | Standalone |
+|---|---|---|
+| `query`, `field_options`, `workflow`, `members`, `context`, `upload`, `urlState.get/set`, `openExternal` | yes | yes |
+| `comments.*` | yes | rejects — `"Comments are available only in embedded apps — a signed-in member is required."` |
+| `agentRun` (streaming, internal to `useAgentRun`) | yes | yes |
+| `agentRun.get`, `agentRun.cancel` | yes | yes |
+| `agentRuns` (session history) | **no** — the product host doesn't implement it either (`"Unknown RPC op: agentRuns"`) | rejects — a standalone caller is anonymous, and a history is its member's (`"App agent runs require an authenticated member …"`) |
+| `askAi` | yes | rejects — `"askAi is only available when the app runs inside Lotics"` |
+| `openApp` | yes — routes to the sibling in the same tab | rejects — `"openApp needs the Lotics host …"` |
+| `recording.start`, `recording.stop` | yes, when the context states `recording_enabled` | rejects — `"Recording needs the Lotics host and a signed-in member …"` |
 
 **Limitation:** Don't build a session-log UI on `useAgentRuns`; keep the log in app
-state from live `useAgentRun` results (see [ai](./ai.md)). Server-side *cancel*
-also errors in the dev loop (the local abort of a live stream still works) —
-verify cancel on a deployed app. The standalone `query` transport forwards only
+state from live `useAgentRun` results (see [ai](./ai.md)). The standalone `query` transport forwards only
 `alias`/`params`/`limit`/`offset` — runtime `sort`/`filter`/`count` refinement
 is embedded-only (see [data fetching](./data_fetching.md)).
 
@@ -229,14 +222,13 @@ const { rows } = await rpc<{ rows: Record<string, unknown>[] }>("query", {
 ```
 
 `rpc<T = unknown>(op: RpcOp, payload: unknown): Promise<T>` sends one op over
-whichever transport is active. **Prefer the hooks** — they add SWR caching,
-loading/error state, analytics, and typing from your declared aliases. `rpc()`
-exists for the imperative cases the hooks don't model, chiefly paging a query to
-exhaustion for a full export — `rpc("query", { alias, params, limit, offset })`
-until a short page, then feed the rows to `downloadFile` (below). `T` is *your*
-assertion — the SDK does not validate the result shape.
-
-The full `RpcOp` union (`dist/src/rpc.d.ts`), each op's payload, and where its
+whichever transport is active. **Prefer the hooks** — they add the SDK's cache,
+loading/error state, analytics, and typing from your declared aliases; every row
+of a set for a full export is `queryAll` ([data_fetching](./data_fetching.md)), fed
+to `downloadFile` (below). `rpc()` exists for the imperative cases neither
+models. `T` is *your* assertion — the SDK does not validate the result shape.
+
+The full `RpcOp` union (`dist/rpc.d.ts`), each op's payload, and where its
 semantics are documented:
 
 | Op | Payload | Resolves to | Owning doc |
@@ -260,12 +252,23 @@ semantics are documented:
 The **streaming** agent-run op is *not* reachable through `rpc()` — its
 response is a chunk stream, not a single value; it's internal to `useAgentRun`.
 
-`rpc("context", {})` resolves the viewer: `{ member_id, comments_enabled,
-recording_enabled?, recordings? }`. `member_id` is the signed-in member when
-embedded, `null` standalone — read it through `useViewer()` rather than this op;
-the recording fields are `useRecording`'s. **Limitation:** the context type is
-not exported from the package root, so type the result yourself via the `rpc<T>`
-generic.
+`rpc("context", {})` resolves the viewer and the workspace:
+`{ member_id, comments_enabled, timezone, default_currency, recording_enabled?, recordings? }`. `member_id` is the
+signed-in member when embedded, `null` standalone; `timezone` is the workspace's
+IANA zone and `default_currency` its ISO 4217 code, from the host when embedded
+and from `/v1/apps/by-subdomain/{subdomain}` standalone. Read them through
+`useViewer()`, `useWorkspaceTimezone()` and `useWorkspaceCurrency()`
+([members & options](./members_and_options.md)) rather than this op. A host that
+predates the two workspace facts answers without them; the recording fields are
+`useRecording`'s. **Limitation:** the
+context type is not exported from the package root, so type the result yourself
+via the `rpc<T>` generic.
+
+An app's root draws nothing until this op has answered or failed, then hands
+the zone to the kit's locale, so every instant the kit formats is dated in the
+workspace's zone ([members & options](./members_and_options.md)); money whose
+field states no code is counted in the workspace's currency. Where neither the field nor the host names a
+currency, the screen refuses by name rather than printing one nobody stated.
 
 ## `openExternal()` — open a link in a new tab
 
@@ -274,11 +277,11 @@ import { openExternal } from "@lotics/app-sdk";
 await openExternal(result.files[0].url);
 ```
 
-`openExternal(url: string): Promise<void>` (`dist/src/open_external.d.ts`). The
+`openExternal(url: string): Promise<void>` (`dist/open_external.d.ts`). The
 embedded app iframe is sandboxed **without `allow-popups`**, so a direct
 `window.open` from app code is *silently dropped* — no error, nothing happens.
 `openExternal` routes the URL to whoever can actually open it: the un-sandboxed
-host frame (embedded — including the dev wrapper) or the app's own top-level
+host frame (embedded) or the app's own top-level
 page (standalone). Opens in a new tab with `noopener,noreferrer`.
 
 - **Scheme validation at the point of open**: only `http:` and `https:` are
@@ -289,7 +292,7 @@ page (standalone). Opens in a new tab with `noopener,noreferrer`.
 - Typical use: opening a workflow-generated file's `url` from
   `WorkflowResult.files[]` (see [mutations](./mutations.md)).
 - **Not a preview mechanism.** To *view* a file inline, use `@lotics/ui`'s
-  `FilePreview`/`FileGalleryDialog` (`@lotics/ui` ≥ 48 — see [files](./files.md)); `openExternal` is
+  `FilePreview`/`FileGalleryDialog` (see [files](./files.md)); `openExternal` is
   "leave the app".
 
 ## `openApp()` — the cross-app hop
@@ -299,7 +302,7 @@ import { openApp, isEmbedded } from "@lotics/app-sdk";
 await openApp(PLANNING_APP_ID, `/plan/${record.id}`);
 ```
 
-`openApp(appId: string, route?: string): Promise<void>` (`dist/src/open_app.d.ts`).
+`openApp(appId: string, route?: string): Promise<void>` (`dist/open_app.d.ts`).
 A workspace built as several apps around one spine shows another app's record
 read-only with a way THROUGH to the app that owns it; this is the way through.
 The host owns app routing, so it lands the viewer on `route` inside `appId` in
@@ -311,9 +314,7 @@ declares it (`/` for its register); it is the target's to define.
 - **Checked at the bridge, host-side**: the id by shape (`app_…`), the route as
   an in-app path — starts with `/`, never `//` or a scheme. An app never
   assembles the host's URL itself.
-- **By transport**: embedded routes in place; `lotics app dev` serves one app
-  and has no shell to route inside, so it opens the sibling on the web app in a
-  new tab; standalone rejects (`openApp needs the Lotics host …`) — gate the
+- **By transport**: embedded routes in place; standalone rejects (`openApp needs the Lotics host …`) — gate the
   control on `isEmbedded()`.
 - A sibling's id is this workspace's: a copy of the suite has different ones,
   and the portability gate refuses a concrete `app_` in `src/` and in every
@@ -328,20 +329,14 @@ declares it (`/` for its register); it is the target's to define.
 
 ```tsx
 import { downloadFile } from "@lotics/app-sdk";
-import { buildDataWorkbook, exportWorkbook } from "@lotics/xlsx";
 
 function onExportClick() {
-  const wb = buildDataWorkbook({ columns, rows });
-  downloadFile(
-    "report.xlsx",
-    exportWorkbook(wb),
-    "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
-  );
+  downloadFile("report.csv", rows.map((r) => r.join(",")).join("\n"), "text/csv");
 }
 ```
 
 `downloadFile(filename: string, data: Uint8Array | Blob | string, mimeType?:
-string): void` (`dist/src/download.d.ts`) saves bytes the app generated **in the
+string): void` (`dist/download.d.ts`) saves bytes the app generated **in the
 browser** (an exported .xlsx, a CSV, generated text) to the visitor's device.
 It is the client-side counterpart to the server path (workflow generates a file
 → `WorkflowResult.files[].url` → `openExternal`).
@@ -372,7 +367,7 @@ It is the client-side counterpart to the server path (workflow generates a file
 The host grants the app iframe the `geolocation` Permissions-Policy, so app code
 reads the device position **directly through the browser** — no RPC. The browser
 permission prompt appears as usual (attributed to the embedding site when
-embedded). Exact signatures: `dist/src/geolocation.d.ts`.
+embedded). Exact signatures: `dist/geolocation.d.ts`.
 
 **`isWithinZone(latitude, longitude, zone): boolean`** — pure great-circle
 (haversine) check: is the point within `zone.radius` meters of
@@ -424,66 +419,8 @@ a user's Stop (`cancel_requested_at`), lands in `app_agent_runs`. App opens are
 counted at the serving edge. If a funnel needs something those cannot answer,
 request it as a platform change.
 
-## For SDK contributors
-
-Everything below concerns changing `@lotics/app-sdk` itself (in the Lotics
-monorepo), not building apps with it.
-
-### The publish chain — nothing reaches apps without a version bump
-
-Apps install the SDK from **npm**. Publish CI runs on pushes to `main` touching
-the package and publishes **only when `package.json#version` differs from the
-version on npm** — nothing else triggers it. `dist/`, `AGENTS.md`, and `docs/`
-(this file) are what ship (`package.json#files`), so a docs-only fix needs the
-same chain. A source or doc change reaches zero apps until:
-
-1. the version is bumped and the change merges to `main` (publish CI builds and
-   publishes),
-2. each app widens/updates its dependency range and reinstalls,
-3. the app redeploys.
-
-### Wiring a new RPC op — all four transports, or it 404s somewhere
-
-A new bridge op must be implemented in every transport, or it works in one place
-and breaks in another:
-
-1. `packages/app-sdk/src/rpc.ts` — the `RpcOp` union **and** the standalone
-   (direct-API) implementation,
-2. `frontend/features/app_ui/app_iframe_host.tsx` — the product host's bridge
-   handler,
-3. `packages/sdk/src/dev/` — the `lotics app dev` wrapper page and its Node
-   forwarder (`rpc_handler.ts`),
-4. the `LoticsClient` method (`packages/sdk/src/client.ts`) that forwarder
-   calls.
-
-The backend endpoint deploys with the PR, but `lotics app dev` forwards to the
-**production** API — a new op is not usable in the dev loop until the backend
-has deployed. Skipping a transport produces exactly the gaps in the
-[op availability table](#op-availability-by-transport) above — every "no" there
-is a transport that wasn't wired.
-
-### Bundler & dependency constraints
-
-- **Pure ESM, browser-only.** Apps bundle the SDK with Vite. No `require()`,
-  no dynamic `import()`, no Node built-ins. Don't touch `window` at module top
-  level — resolve lazily (test environments import modules before `jsdom` is
-  ready).
-- **One module per entry.** A package apps share with the Lotics product
-  (`@lotics/ui`, `@lotics/xlsx`, `@lotics/docx`) ships ONE module per entry: no
-  platform twins, no per-target `exports` condition. The SDK itself is never
-  bundled by the product at all — the host frontend is forbidden from importing
-  `@lotics/app-sdk`, enforced by a dependency-direction test.
-- **Self-contained on npm.** The SDK cannot import workspace-private or
-  host-only packages (`@lotics/shared`, `@lotics/ui-internal`, the frontend's
-  `@/` alias) or any React Native / Expo module — also test-enforced. A helper
-  that exists privately elsewhere gets a local copy here, with a comment saying
-  why.
-- **Data + RPC only — zero UI.** Never re-export a `@lotics/ui` component; the
-  SDK stays off the React-Native-Web dependency tree. Apps import `@lotics/ui`
-  directly.
-- **Keep the dependency set minimal.** Runtime deps are `ai` and `swr`;
-  `react`/`react-dom` are peers. `react-router` is an **optional** peer
-  pulled in only by the `@lotics/app-sdk/router` subpath export — the root entry
-  must never import it. (`react-router` is the canonical package; the
-  `react-router-dom` shim also satisfies the peer, since it carries
-  `react-router` in its own tree.)
+## Dependencies
+
+The SDK's own dependency is `ai` (types only); `react`, `react-dom` and `react-router`
+are peers, and only the `@lotics/app-sdk/router` entry imports `react-router` (the
+`react-router-dom` shim also satisfies the peer, since it carries `react-router` in its own tree).

package/docs/security.md

@@ -1,6 +1,6 @@
 # Security: authority & scoping
 
-Every data operation an app performs — queries, workflows, agent runs — executes under the **app owner's** IAM principal, not the viewing member's. That single fact drives the whole author-facing security contract: the platform decides *what the app can reach* (the owner's access), and **you** decide *what each caller gets* — per-user scoping, write attribution, and privilege gates are authored into query templates and workflow bodies, never inferred from the client. Read this before shipping any app that shows per-user data, performs writes on behalf of a member, gates an action to a role, or is shared publicly. Related: [queries](./queries.md) (the read surface these rules apply to), [mutations](./mutations.md) (workflows), [ai](./ai.md) (agent runs), [files](./files.md) (presigned URLs).
+Every data operation an app performs — queries, workflows, agent runs — executes under the **app owner's** IAM principal, not the viewing member's. The platform decides *what the app can reach* (the owner's access); **you** decide *what each caller gets* — per-user scoping, write attribution, and privilege gates are authored into query templates and workflow bodies, never inferred from the client. Related: [queries](./queries.md) (the read surface these rules apply to), [mutations](./mutations.md) (workflows), [ai](./ai.md) (agent runs), [files](./files.md) (presigned URLs).
 
 ## The owner-principal model
 
@@ -16,7 +16,7 @@ Consequences of owner authority:
 - **Data reach is the owner's.** A query reaches exactly the tables the owner can access; referencing a table the owner cannot reach fails with an "inaccessible tables" error.
 - **Row security evaluates against the owner, not the viewer.** Table-level row scoping (private filters) is applied for the *owner's* identity. If the owner is an org admin/owner, no row scope applies at all — the query sees every row of every table it references. An app can therefore surface rows the viewing member's own table permissions would hide. That is the design: the owner *chose* to expose those columns and rows by declaring the query.
 - **The viewer never widens or narrows a data op by existing.** A member with zero table access sees whatever the app's queries project, and a member with admin table access sees no more than that. `app:use` (or the public grant, below) is the only gate on invoking the app's declared surface.
-- **Who the model protects against.** The boundary is not "what the owner can do" — the owner declared the queries and workflows, so their authority is intentional. The boundary is **what a caller can do**: any caller, including an anonymous public visitor, can only invoke the declared aliases with typed, per-input-constrained values. An owner weakening their own declared constraint is a footgun, not an escalation — but a *caller* gaining data or capability the aliases don't declare is a real vulnerability, and the sections below are how you prevent the ones the platform cannot detect for you.
+- **The boundary is what a CALLER can do**, not what the owner can: any caller, including an anonymous public visitor, can only invoke the declared aliases with typed, per-input-constrained values. A caller gaining data or capability the aliases don't declare is a vulnerability; the sections below prevent the ones the platform cannot detect for you.
 
 Comments are the one deliberate exception: access is app-authority (any member with `app:use` + the app's declared `comments` capability may read/post on any record in the app's workspace, regardless of their own table access — a tenant floor rejects record ids outside the app's workspace), but the **author is always the real authenticated member** — never the app owner, never a "View as" subject — and edit/delete are author-only. Anonymous visitors cannot comment: the comment endpoints require an authenticated member.
 
@@ -52,14 +52,14 @@ Before shipping any query or workflow, ask: **could a member open the browser de
 
 ## Scoping reads: `is_current_member` in the template
 
-To show a member only their own rows, put the scoping in the query template itself — a filter condition with the `is_current_member` operator on a member field (or `is_not_current_member` for the inverse). The server binds the predicate to the signed-in viewer at execution time and the client receives only the surviving rows. A client-supplied `member_id` param achieves the same UI with none of the security: any member can replay the query with a different id and read that member's rows (the devtools test fails).
+To show a member only their own rows, put the scoping in the query template itself — a filter condition with the `is_current_member` operator on a member field (or `is_not_current_member` for the inverse). The server binds the predicate to the signed-in viewer at execution time and the client receives only the surviving rows. A client-supplied `member_id` param draws the same UI and fails the devtools test.
 
 Who the server binds `is_current_member` to:
 
 | Caller | Binds to |
 |---|---|
 | Authenticated member of the app's org | That member |
-| Admin using "View as" (product UI, or `lotics app dev --view-as <member_id>`) | The **viewed** member — so an admin previews exactly what the member sees |
+| Admin using "View as" in the product | The **viewed** member — so an admin previews exactly what the member sees |
 | Authenticated member of a *different* org (public app, cross-org) | Their own member id — which matches no member cells in the app's workspace, so self-scoped queries return no rows |
 | Anonymous visitor (public app) | **The app owner** — see the public-app warning below |
 
@@ -107,18 +107,15 @@ A publicly-shared app (its own origin, or its public link) is reachable by **any
 
 ### Member roster access
 
-Listing members (`useMembers`) is deliberately narrow, because an org roster with emails must not leak through an arbitrary app. Three gates, all server-enforced: (1) the caller must be an **authenticated member of the app's own org** with `app:use` — anonymous and cross-org callers get 403; (2) the app must have **declared member access** — at least one workflow input or query param of type `member`; an app that never works with members cannot enumerate the roster; (3) a `group_id` filter is honored only for a group **declared** on one of those member inputs — an app cannot enumerate groups it never uses. In query *results*, projected member cells resolve to `{ id, name }` for everyone; `email` is included only for authenticated members of the app's own org. See [members_and_options](./members_and_options.md).
+Listing members (`useMembers`) takes an authenticated member of the app's own org, a declared `member` input or param, and a group only where one is declared; in query results a member cell carries `email` only for that same-org member. The gates and their errors: [members_and_options](./members_and_options.md#access-gates-when-it-errors).
 
 ## What runtime refinement cannot widen
 
-The query RPC accepts runtime `filter` and `sort` (for search boxes, sortable tables, pickers) — but these are **bounded to the named query's output columns**. A `field_key` naming a column the query does not project is rejected, so a caller can never filter or sort by — and thereby probe — a field the author didn't expose. The caller's `limit` is clamped to the server row cap, params fill the template's *value holes* only — filter values and the search term; tables, joins, and projections are author-fixed — and `count` mode returns a single total over the same bounded filter. Full mechanics in [queries](./queries.md).
+The query RPC accepts runtime `filter` and `sort` (for search boxes, sortable tables, pickers) — but these are **bounded to the named query's output columns**. A `field_key` naming a column the query does not project is rejected, so a caller can never filter or sort by — and thereby probe — a field the author didn't expose. The caller's `limit` is clamped to the server row cap, params fill the template's *value holes* only — filter values and the search term; tables, joins, and projections are author-fixed — and `count` mode returns a total — with `count_by`, one per value of a projected column — over the same bounded filter. Full mechanics in [queries](./queries.md).
 
-**Warning — templated free-text search is not output-bounded.** A `search` term in the query template (typically a `{{params.q}}` hole) matches against the record's **whole search document**: every searchable field of the table — text, numbers, dates (in three formats), select option names, member names, linked-record display text, formula/rollup/lookup values, and autonumbers (only booleans, buttons, and file fields are excluded). It is *not* restricted to the columns the query projects. A caller who controls the search term can therefore probe the *contents* of unprojected fields by watching which rows match — a row-membership oracle. Put a `search` hole only in queries over tables where every searchable field is acceptable to probe for that audience; for a search box over a table with sensitive unprojected fields, use runtime `filter` with `contains` on the projected columns instead.
+**Warning — templated free-text search is not output-bounded.** A `search` term in the query template (typically a `{{params.q}}` hole) matches against the record's **whole search document**: every searchable field of the table — text, numbers, dates (in three formats), select option names, member names, linked-record display text, formula/rollup/lookup values, and autonumbers (only booleans, buttons, and file fields are excluded). It is *not* restricted to the columns the query projects. A caller who controls the search term can therefore probe the *contents* of unprojected fields by watching which rows match — a row-membership oracle. Put a `search` hole only in queries over tables where every searchable field is acceptable to probe for that audience; for a search box over a table with sensitive unprojected fields, use runtime `filter` with `contains` on the projected columns instead, or AND the `search` with a template `contains` OR-group over the fields that may be probed — every row that group matches also matches the search, so the pair answers only for those fields.
 
 ## `useViewer` is display-only
 
-`useViewer()` returns the signed-in member currently viewing the app — the view-as target under "View as", `null` for an anonymous public visitor or while the context loads. It exists to **personalize and prefill**: greet the member, default an assignment to them, pass them into a picker. It is **never an authorization fact and never a scoping mechanism** — anything the client sends, including a `useViewer`-derived id, is replayable with a different value. Row scoping belongs in the query template (`is_current_member`, which the server resolves to the same person `useViewer` reports, view-as included); actor identity belongs in the workflow body (`runtime.triggered_by_member_id`); privilege belongs in the workflow gate (`current_member_in_any_group`). Signature: `dist/src/viewer.d.ts`.
+`useViewer()` returns the signed-in member currently viewing the app — the view-as target under "View as", `null` for an anonymous public visitor or while the context loads. It exists to **personalize and prefill**: greet the member, default an assignment to them, pass them into a picker. It is **never an authorization fact and never a scoping mechanism** — a `useViewer`-derived id the client sends is replayable with a different value ([the devtools test](#the-devtools-test)); `is_current_member` resolves server-side to the same person `useViewer` reports, view-as included. Signature: `dist/viewer.d.ts`.
 
----
-
-*For platform maintainers*: the full IAM model, the public-access grant mechanics, and the rationale behind owner authority live in the monorepo's `docs/apps.md` and `docs/iam.md` (not shipped with this package).