@lotics/app-sdk 0.101.1 → 0.102.0

package/AGENTS.md

@@ -15,7 +15,7 @@ This file is the index. The **exact type** of anything is its shipped declaratio
 
 | Doc | Read it for |
 |---|---|
-| [docs/data_fetching.md](./docs/data_fetching.md) | The reads: `useQuery(alias, params, opts)` — its rows (`limit`), numbered pages (`page`), a keyset feed (`more`), its `total` or the total alone, with `total: { by }` a count per value of one column — `useQueries` for reads known only at render, `queryAll` outside React; every hook answers one `QueryState`. The ROW type (`RowOf` — the alias's projected columns and nothing else), runtime `sort`/`filter` keys, cell readers (`row.*`, `readSelect`, `readMembers`, `readLinks`, `readFiles`, `readLocked`, `readCreatedAt`/`readUpdatedAt`), the SDK's own cache — **arrival revalidates** — **realtime push**, a write drawn on every read from the press, a count as its own full scan, and the search-as-you-type and record-picker patterns. |
+| [docs/data_fetching.md](./docs/data_fetching.md) | The reads: `useQuery(alias, params, opts)` — its rows (`limit`), numbered pages (`page`), a keyset feed (`more`), its `total` or the total alone, with `total: { by }` a count per value of one column — `useQueries` for reads known only at render, `queryAll` outside React, `exportQuery` for a file of them the server makes; every hook answers one `QueryState`. The ROW type (`RowOf` — the alias's projected columns and nothing else), runtime `sort`/`filter` keys, cell readers (`row.*`, `readSelect`, `readMembers`, `readLinks`, `readFiles`, `readLocked`, `readCreatedAt`/`readUpdatedAt`), the SDK's own cache — **arrival revalidates** — **realtime push**, a write drawn on every read from the press, a count as its own full scan, and the search-as-you-type and record-picker patterns. |
 | [docs/queries.md](./docs/queries.md) | **The query engine reference** — AST node kinds, per-field-type operators, filters/params/pruning, free-text search, combining tables, shaping (aggregates, date buckets, windows), runtime refinement bounds, limits and the efficiency playbook. |
 | [docs/mutations.md](./docs/mutations.md) | `useWorkflow` (the ONLY write path; `useWorkflows` for writes that are data), the `WorkflowResult` resolve-never-throw contract (`field_errors`), typed inputs, every write drawn on every read from the press — predicted from the workflow's own steps, taken back on a refusal, `pending` meanwhile — the re-read a successful write triggers over the tables its body names, diff-before-update, locked records, `useNewRecord`, read-after-write ordering (`writesSettled()`), `useRecording`. |
 | [docs/workflows.md](./docs/workflows.md) | **The workflow-BODY reference** — the JS subset a body may use, opaque `fld_*`/`opt_*` keys, every step form, the accepted sugar, helpers, record-write surfaces, the traps and the verify loop. |

package/dist/{chunk-ARV5FAU5.js → chunk-ZOFKWF6V.js}

@@ -898,6 +898,8 @@ function rpcStandalone(op, payload) {
   switch (op) {
     case "query":
       return standaloneQuery(payload);
+    case "export":
+      return standaloneExport(payload);
     case "field_options":
       return standaloneFieldOptions(payload);
     case "workflow":
@@ -1029,6 +1031,10 @@ async function standaloneQuery(payload) {
   const { app_id } = await boot();
   return apiCall("POST", `/v1/apps/${app_id}/query`, payload, { appId: app_id });
 }
+async function standaloneExport(payload) {
+  const { app_id } = await boot();
+  return apiCall("POST", `/v1/apps/${app_id}/export`, payload, { appId: app_id });
+}
 async function standaloneFieldOptions(p) {
   const { app_id } = await boot();
   return apiCall("POST", `/v1/apps/${app_id}/field-options`, { alias: p.alias }, { appId: app_id });

package/dist/hooks.d.ts

@@ -151,6 +151,8 @@ export interface MembersOptions {
      * declares. Omit for the whole roster.
      */
     group?: string;
+    /** `false` reads no roster: `members` stays empty and `loading` false. Default `true`. */
+    enabled?: boolean;
 }
 /**
  * The organization's members, for an assign picker. Member-only, and gated on

package/dist/index.d.ts

@@ -5,8 +5,8 @@ export { reportAppError } from "./error_report.js";
 export type { AppErrorKind } from "./error_report.js";
 export { useWorkflow, useWorkflows, writesSettled, useFileUpload, useAttachments, useAttachmentPiles, useMembers, useAgentRun, useAgentRuns, useAiContext, buildChoiceOutput, } from "./hooks.js";
 export type { UploadedFile, WorkflowResult, MembersOptions, AgentRunOptions, UseAgentRun, AgentRunLanding, AgentRunRecord, AgentRunState, AgentUIPart, PendingChoice, ChoiceQuestion, ChoiceOption, AskUserChoiceOutput, } from "./hooks.js";
-export { useQuery, useQueries, queryAll, useFieldOptions } from "./queries.js";
-export type { QueryRow, QueryCall, QueryState, RowOf, QueryOptions, ColumnKeyOf, QuerySortKey, QueryFilter, QueryFilterCondition, QueryFilterFieldCondition, QueryFilterRecordIdCondition, QueryFilterGroup, FieldOptions, FieldOptionsState, FieldOptionsOptions, FigureUnits, } from "./queries.js";
+export { useQuery, useQueries, queryAll, exportQuery, useFieldOptions } from "./queries.js";
+export type { QueryRow, QueryCall, QueryState, RowOf, QueryOptions, ColumnKeyOf, QuerySortKey, QueryFilter, QueryFilterCondition, QueryFilterFieldCondition, QueryFilterRecordIdCondition, QueryFilterGroup, FieldOptions, FieldOptionsState, FieldOptionsOptions, FigureUnits, ExportCall, ExportFile, ExportReport, } from "./queries.js";
 export type { AttachedFile, AttachmentPiles, AttachmentPilesOptions, AttachmentsOptions, AttachmentsState } from "./attachments.js";
 export { useComments, useCommentCounts } from "./comments.js";
 export type { AppComment, AppCommentAuthor, AppCommentFile, CommentsState, UseCommentsArgs, CommentCountsState, UseCommentCountsArgs, } from "./comments.js";
@@ -27,7 +27,7 @@ export { readMembers } from "./members.js";
 export type { ResolvedMember } from "./members.js";
 export { readSelect } from "./select.js";
 export type { ResolvedOption } from "./select.js";
-export type { AppFixture, MockQuery, MockQueryCall, MockWorkflow } from "./mock.js";
+export type { AppFixture, MockExport, MockQuery, MockQueryCall, MockWorkflow } from "./mock.js";
 export type { AppWorkflows, AppWorkflowResults, AppQueries, AppQueryColumns, AppAgents, AppAgentResults } from "./types.js";
 export { row, readLinks, readFiles, readLocked, readCreatedAt, readUpdatedAt, PENDING } from "./row.js";
 export type { ResolvedLink, AppFile } from "./row.js";

package/dist/index.js

@@ -21,7 +21,7 @@ import {
   subscribeRecordings,
   subscribeUrlParams,
   urlParam
-} from "./chunk-ARV5FAU5.js";
+} from "./chunk-ZOFKWF6V.js";
 
 // src/mount.tsx
 import { createRoot } from "react-dom/client";
@@ -59,6 +59,10 @@ function getMockWorkflow(alias) {
   if (!isMockMode()) return null;
   return registeredFixture?.workflows?.[alias] ?? null;
 }
+function getMockExport(alias) {
+  if (!isMockMode()) return null;
+  return registeredFixture?.exports?.[alias] ?? null;
+}
 function getMockRecordings() {
   if (!isMockMode()) return null;
   return registeredFixture?.recordings ?? null;
@@ -16355,6 +16359,7 @@ function numberUnitRefusal(format2, unit) {
 function effectiveSelectOptions(field) {
   if (field === void 0) return null;
   if (field.type === "select") return field.options ?? null;
+  if (field.type === "formula") return field.formula?.options ?? null;
   if (field.type === "lookup" && field.lookup_field_type === "select") {
     return field.lookup_field_options ?? null;
   }
@@ -19152,6 +19157,9 @@ function resolveFilterType(field) {
           return "date";
         case "boolean":
           return "boolean";
+        // Its cell is a single select's: `[key]`.
+        case "select":
+          return "select";
         default:
           return "text";
       }
@@ -19399,7 +19407,7 @@ var tableLookupFieldSchema = tableFieldBaseSchema.extend({
 var tableFilesFieldSchema = tableFieldBaseSchema.extend({
   type: zod_default.literal("files").describe("Field type for file attachments (images, PDFs, documents)")
 });
-var formulaOutputTypeSchema = zod_default.enum(["number", "text", "date", "datetime", "boolean"]);
+var formulaOutputTypeSchema = zod_default.enum(["number", "text", "date", "datetime", "boolean", "select"]);
 var formulaInputSchema = zod_default.object({
   expression: zod_default.string().describe(
     "JavaScript expression. Uses {Field Name} for field references."
@@ -19410,10 +19418,13 @@ var formulaInputSchema = zod_default.object({
   currency: zod_default.string().optional().describe("ISO 4217 currency code, e.g. USD, VND, EUR"),
   unit: zod_default.string().optional().describe(UNIT_DESCRIPTION),
   unit_field: zod_default.string().optional().describe(UNIT_FIELD_DESCRIPTION),
-  currency_field: zod_default.string().optional().describe(CURRENCY_FIELD_DESCRIPTION)
+  currency_field: zod_default.string().optional().describe(CURRENCY_FIELD_DESCRIPTION),
+  options: zod_default.array(tableSelectFieldOptionSchema).min(1).optional().describe(
+    "The categories the formula yields, drawn as a single select's options are. The expression yields one option's `key` (text) or null; a key it does not declare computes an error. Omit for a formula yielding a plain value."
+  )
 });
 var formulaSchema = formulaInputSchema.extend({
-  output_type: formulaOutputTypeSchema.optional().describe("Output type of the formula. Inferred by the backend from the expression \u2014 read-only on input. `datetime` when the result carries a time of day (references a datetime field or a time-bearing helper)."),
+  output_type: formulaOutputTypeSchema.optional().describe("Output type of the formula. Inferred by the backend from the expression \u2014 read-only on input. `datetime` when the result carries a time of day (references a datetime field or a time-bearing helper); `select` when the formula declares `options`."),
   volatile: zod_default.boolean().optional().describe("Whether the formula's result depends on `now()` or other non-deterministic helpers. Inferred by the backend \u2014 read-only on input.")
 });
 var tableFormulaFieldSchema = tableFieldBaseSchema.extend({
@@ -19490,6 +19501,11 @@ var tableFieldInputSchema = zod_default.discriminatedUnion("type", [
   tableAutonumberFieldSchema
 ]);
 var tableFieldsSchema = zod_default.array(tableFieldSchema);
+function selectOptionsOf(field) {
+  if (field.type === "select") return field.options;
+  if (field.type === "formula") return field.formula.options;
+  return void 0;
+}
 var tableFieldCreateBaseSchema = zod_default.object({
   name: zod_default.string().describe("Display name"),
   description: zod_default.string().describe("Field description"),
@@ -19634,6 +19650,10 @@ function projectCell(field, value) {
     case "select_member":
       if (field.multi === true || !Array.isArray(value)) return value;
       return value.length === 0 ? null : value[0];
+    // A formula yielding one of its options holds a single select's cell.
+    case "formula":
+      if (field.formula.options === void 0 || !Array.isArray(value)) return value;
+      return value.length === 0 ? null : value[0];
     case "select_record_link":
       return Array.isArray(value) ? extractRecordLinkIds(value) : value;
     default:
@@ -24118,6 +24138,7 @@ function appWorkflowOutputDepth(output) {
   if (output.type === "array") return 1 + appWorkflowOutputDepth(output.items);
   return 1;
 }
+var APP_ALIAS_REGEX = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/;
 var MAX_APP_CAPABILITY_DESCRIPTION = 300;
 var APP_ANONYMOUS_REQUEST_MAX_BYTES = 256 * 1024;
 var APP_UPLOAD_MAX_BYTES = 25 * 1024 * 1024;
@@ -24150,6 +24171,13 @@ var appWorkflowContractSchema = zod_default.object({
   inputs: zod_default.record(zod_default.string(), appWorkflowInputSchema).optional(),
   outputs: zod_default.record(zod_default.string(), appWorkflowOutputSchema).optional()
 });
+var APP_EXPORT_REPORT_KEYS = ["title", "lines", "readings"];
+var appExportTemplateSchema = zod_default.object({
+  template_id: zod_default.string().min(1).describe("The document template (`dtl_\u2026`) filled: an Excel workbook, or an HTML page made a PDF."),
+  rows: zod_default.string().regex(APP_ALIAS_REGEX).refine((key) => !APP_EXPORT_REPORT_KEYS.some((taken) => taken === key), {
+    message: `The rows are listed under a key of their own, never ${APP_EXPORT_REPORT_KEYS.join(", ")}.`
+  }).describe(`The key the template lists the rows under, beside ${APP_EXPORT_REPORT_KEYS.join(", ")}.`)
+}).strict();
 var appQueryDeclarationSchema = zod_default.object({
   ast: zod_default.unknown().describe(
     "Query AST template (a QueryNode). Validated server-side via parseQueryNode at deploy. May embed {{params.<name>}} tokens in filter value positions."
@@ -24159,6 +24187,9 @@ var appQueryDeclarationSchema = zod_default.object({
   ),
   description: zod_default.string().optional().describe(
     `What this query returns, in one line \u2014 read by an agent choosing between the app's aliases. An alias is a JS identifier, which names a query without saying what it covers. Capped at ${MAX_APP_CAPABILITY_DESCRIPTION} characters.`
+  ),
+  templates: zod_default.record(zod_default.string().regex(APP_ALIAS_REGEX), appExportTemplateSchema).optional().describe(
+    "Document templates an export of this query's rows may fill, by the name the export asks for. An export names one of these or none; a template it does not declare is refused."
   )
 });
 var appAgentDeclarationSchema = zod_default.object({
@@ -25463,6 +25494,7 @@ async function evaluateRead(source, path, coerce, ctx) {
   return current;
 }
 function isScalarWrappedField(field) {
+  if (field.type === "formula") return field.formula.options !== void 0;
   return (field.type === "select" || field.type === "select_member") && field.multi !== true;
 }
 function unwrapScalarField(value) {
@@ -25485,7 +25517,10 @@ async function coerceFieldDisplay(value, field, ctx) {
   if (value === null || value === void 0) return value;
   switch (field.type) {
     case "select":
-      return coerceSelectDisplay(value, field);
+      return coerceSelectDisplay(value, field.options);
+    // One of its own options, named as a select's is.
+    case "formula":
+      return field.formula.options === void 0 ? value : coerceSelectDisplay(value, field.formula.options);
     case "select_record_link":
       return coerceRecordLinkDisplay(value, field, ctx);
     case "select_member":
@@ -25496,8 +25531,8 @@ async function coerceFieldDisplay(value, field, ctx) {
       return value;
   }
 }
-function coerceSelectDisplay(value, field) {
-  const optionMap = new Map(field.options.map((o) => [o.key, o.name]));
+function coerceSelectDisplay(value, options) {
+  const optionMap = new Map(options.map((o) => [o.key, o.name]));
   const resolve = (key) => {
     if (typeof key !== "string") return "";
     return optionMap.get(key) ?? key;
@@ -27317,6 +27352,10 @@ function getFieldDisplayValue(field, value) {
       return option?.name ?? selectValues[0] ?? "";
     }
     case "formula": {
+      if (field.formula.options !== void 0) {
+        const [key] = Array.isArray(value) ? value : [];
+        return key === void 0 ? "" : field.formula.options.find((option) => option.key === key)?.name ?? key;
+      }
       const formulaVal = getFormulaValue(value);
       return formulaVal !== null ? String(formulaVal) : "";
     }
@@ -27982,7 +28021,7 @@ function useAiContext(slot, context) {
 function useMembers(opts) {
   const group = opts?.group;
   const roster = useKey(
-    JSON.stringify(["members", group ?? null]),
+    opts?.enabled === false ? null : JSON.stringify(["members", group ?? null]),
     async () => {
       const members2 = (await rpc("members", { group })).members ?? [];
       noteMembers(members2);
@@ -29522,11 +29561,10 @@ function compareFieldValues(aValue, bValue, field, blankPosition = "bottom", ord
   if (aValue === bValue) {
     return 0;
   }
-  if (field.type === "select") {
-    const selectField = field;
-    const options = selectField.options || [];
-    const aSelectArray = aValue;
-    const bSelectArray = bValue;
+  const options = selectOptionsOf(field);
+  if (options !== void 0) {
+    const aSelectArray = Array.isArray(aValue) ? aValue : null;
+    const bSelectArray = Array.isArray(bValue) ? bValue : null;
     const aSelectValue = aSelectArray?.[0];
     const bSelectValue = bSelectArray?.[0];
     const aIsEmpty2 = isArrayFieldEmpty(aSelectArray);
@@ -29683,6 +29721,10 @@ function referencedFieldKeys(expression, fields) {
   return prepareFormulaExpression(expression, fields).referencedKeys;
 }
 
+// ../shared/src/formula_language.ts
+var HELPERS2 = new Set(Object.keys(createTimezoneAwareFunctions()));
+var BY_LOWERCASE = new Map([...HELPERS2].map((name) => [name.toLowerCase(), name]));
+
 // ../shared/src/formula.ts
 function prepareFormulaContext(fields) {
   const formulaFields = fields.filter((field) => field.type === "formula");
@@ -29833,12 +29875,13 @@ function computeFormulaFieldsWithContext(row2, fields, context, linkedTableRecor
       continue;
     }
     const everyReferenceEmpty = referencedKeys.length > 0 && referencedKeys.every((fieldKey) => evaluationContext[fieldKey] === null);
-    const formulaResult = evaluateFormulaWithJS(
+    const evaluated2 = evaluateFormulaWithJS(
       prepared.refs.evaluable,
       { data: evaluationContext },
       timezone,
       everyReferenceEmpty
     );
+    const formulaResult = formulaField.formula.options === void 0 ? evaluated2 : selectResult(formulaField.formula.options, evaluated2);
     result[formulaField.key] = formulaResult;
     if (isFormulaError(formulaResult)) {
       erroredFormulaKeys.add(formulaField.key);
@@ -29857,6 +29900,12 @@ function computeFormulaFieldsWithContext(row2, fields, context, linkedTableRecor
   }
   return result;
 }
+function selectResult(options, evaluated2) {
+  if (evaluated2 === null || evaluated2 === "") return null;
+  if (isFormulaError(evaluated2)) return evaluated2;
+  if (typeof evaluated2 === "string" && options.some((option) => option.key === evaluated2)) return [evaluated2];
+  return `${FORMULA_ERROR_PREFIX}yields ${JSON.stringify(evaluated2)}, which is none of its options (${options.map((option) => option.key).join(", ")})`;
+}
 function normalizeEmptyToNull(value) {
   return isEmptyFieldValue(value) ? null : value;
 }
@@ -30615,23 +30664,27 @@ function overlayAsked(alias, params, narrowing, askedAt, totalsOf, rows, back, a
 }
 
 // src/queries.ts
-function mockedRows(alias, call) {
-  const mocked = getMockRows(alias, call);
-  if (mocked === null) return void 0;
+function pageOf(mocked, call) {
   const start = call.keyset === true ? Number(call.cursor ?? 0) : call.offset ?? 0;
   const end = call.limit === void 0 ? mocked.length : start + call.limit;
   const rows = mocked.slice(start, end);
   const more = end < mocked.length;
   return { rows, truncated: call.keyset !== true && more, next_cursor: call.keyset === true && more ? String(end) : null };
 }
-function mockedCount(alias, call) {
+function countOf(mocked, by) {
+  return { total: mocked.length, ...by === void 0 ? {} : { counts: countsOf(mocked, by) } };
+}
+function knownRows(alias, call) {
+  const mocked = getMockRows(alias, call);
+  return Array.isArray(mocked) ? pageOf(mocked, call) : void 0;
+}
+function knownCount(alias, call) {
   const mocked = getMockRows(alias, { params: call.params, filter: call.filter });
-  if (mocked === null) return void 0;
-  return { total: mocked.length, ...call.by === void 0 ? {} : { counts: countsOf(mocked, call.by) } };
+  return Array.isArray(mocked) ? countOf(mocked, call.by) : void 0;
 }
 async function askRows(key, alias, askedAt, call, since = askedAt) {
-  const mocked = mockedRows(alias, call);
-  if (mocked !== void 0) return mocked;
+  const mocked = getMockRows(alias, call);
+  if (mocked !== null) return pageOf(await mocked, call);
   const answer = await rpc("query", {
     alias,
     params: call.params,
@@ -30644,8 +30697,8 @@ async function askRows(key, alias, askedAt, call, since = askedAt) {
   return answer;
 }
 async function askCount(key, alias, askedAt, call) {
-  const mocked = mockedCount(alias, call);
-  if (mocked !== void 0) return mocked;
+  const mocked = getMockRows(alias, { params: call.params, filter: call.filter });
+  if (mocked !== null) return countOf(await mocked, call.by);
   const answer = await rpc("query", {
     alias,
     params: call.params,
@@ -30686,7 +30739,7 @@ function useQuery(alias, params = {}, opts = {}) {
       limit: opts.page ?? opts.limit,
       offset: opts.page === void 0 ? 0 : page * opts.page
     }),
-    { focus, aliases: [alias], known: mocking ? () => mockedRows(alias, { params, filter: filter2, sort, limit: opts.page ?? opts.limit, offset: opts.page === void 0 ? 0 : page * opts.page }) : void 0 }
+    { focus, aliases: [alias], known: mocking ? () => knownRows(alias, { params, filter: filter2, sort, limit: opts.page ?? opts.limit, offset: opts.page === void 0 ? 0 : page * opts.page }) : void 0 }
   );
   const feedKey = !enabled || !wantsRows || opts.more === void 0 ? null : JSON.stringify(["feed", alias, call, opts.more]);
   const feedSize = opts.more ?? 0;
@@ -30727,7 +30780,7 @@ function useQuery(alias, params = {}, opts = {}) {
   const count = useKey(countKey, (askedAt) => askCount(countKey ?? "", alias, askedAt, { params, filter: filter2, by }), {
     focus,
     aliases: [alias],
-    known: mocking ? () => mockedCount(alias, { params, filter: filter2, by }) : void 0
+    known: mocking ? () => knownCount(alias, { params, filter: filter2, by }) : void 0
   });
   const version3 = useWrittenVersion();
   const drawn2 = useMemo3(() => {
@@ -30789,7 +30842,7 @@ async function settle(read2) {
 }
 async function askGroups(key, alias, askedAt, aggregate, call) {
   const mocked = getMockRows(alias, { ...call, aggregate });
-  if (mocked !== null) return { rows: aggregateRows(mocked, aggregate), truncated: false };
+  if (mocked !== null) return { rows: aggregateRows(await mocked, aggregate), truncated: false };
   const answer = await rpc("query", { alias, params: call.params, aggregate, filter: call.filter, sort: call.sort });
   noteAnswer(key, alias, askedAt, []);
   return answer;
@@ -30858,6 +30911,13 @@ async function queryAll(alias, params = {}, opts = {}) {
     if (!page.truncated || page.rows.length === 0) return pages.flat();
   }
 }
+async function exportQuery(alias, call) {
+  const sort = call.sort === void 0 || call.sort.length === 0 ? void 0 : [...call.sort];
+  const body = { alias, params: call.params ?? {}, filter: call.filter, sort, report: call.report, file: call.file };
+  const mocked = getMockExport(alias);
+  if (mocked !== null) return mocked(body);
+  return (await rpc("export", body)).file;
+}
 var NO_UNITS = {};
 function useFieldOptions(alias, opts) {
   const enabled = opts?.enabled ?? true;
@@ -31283,6 +31343,7 @@ export {
   askAi,
   buildChoiceOutput,
   downloadFile,
+  exportQuery,
   isEmbedded,
   isWithinZone,
   mount,

package/dist/mock.d.ts

@@ -6,8 +6,8 @@
  * `useFileUpload` is not mocked.
  */
 import type { QueryAggregate } from "./shared_types.js";
-import type { WorkflowResult } from "./hooks.js";
-import type { QuerySortKey } from "./queries.js";
+import type { UploadedFile, WorkflowResult } from "./hooks.js";
+import type { ExportCall, QuerySortKey } from "./queries.js";
 import type { RecordingState } from "./recording_state.js";
 /** A result, or a function of the inputs — return a slow promise to review the pending state. */
 export type MockWorkflow = WorkflowResult | ((inputs: Record<string, unknown>) => WorkflowResult | Promise<WorkflowResult>);
@@ -19,11 +19,18 @@ export interface MockQueryCall {
     /** The groups the call asks for: a fixture answers the query's rows, and they are folded into these after it. */
     aggregate?: QueryAggregate;
 }
-/** Rows, or a function of the call — the only way to honour `filter`/`sort`/`limit`, which the fixture path has no engine for. */
-export type MockQuery = Array<Record<string, unknown>> | ((call: MockQueryCall) => Array<Record<string, unknown>>);
+/** Rows, or a function of the call — the only way to honour `filter`/`sort`/`limit`, which the fixture path has no
+ *  engine for. Return a promise to hold the read loading until it settles. */
+export type MockQuery = Array<Record<string, unknown>> | ((call: MockQueryCall) => Array<Record<string, unknown>> | Promise<Array<Record<string, unknown>>>);
+/** The file an export of a query makes, as a function of the call — return a slow promise to review the pending state. */
+export type MockExport = (call: ExportCall & {
+    alias: string;
+}) => UploadedFile | Promise<UploadedFile>;
 export interface AppFixture {
     queries?: Record<string, MockQuery>;
     workflows?: Record<string, MockWorkflow>;
+    /** By the query exported. */
+    exports?: Record<string, MockExport>;
     /** `useRecording(alias)` reads as available; `start`/`stop` change nothing. */
     recordings?: Record<string, RecordingState>;
 }
@@ -31,7 +38,9 @@ export declare function registerMockFixture(fixture: AppFixture | undefined): vo
 /** The raw `?__mock=1` flag, fixture or not; false where `window.location` is absent. */
 export declare function hasMockFlag(): boolean;
 /** Null for an unmocked alias, which reads real data. */
-export declare function getMockRows(alias: string, call: MockQueryCall): Array<Record<string, unknown>> | null;
+export declare function getMockRows(alias: string, call: MockQueryCall): Array<Record<string, unknown>> | Promise<Array<Record<string, unknown>>> | null;
 /** Null for an unmocked alias, which executes for real. */
 export declare function getMockWorkflow(alias: string): MockWorkflow | null;
+/** Null for an unmocked alias, which the server exports. */
+export declare function getMockExport(alias: string): MockExport | null;
 export declare function getMockRecordings(): Record<string, RecordingState> | null;

package/dist/queries.d.ts

@@ -1,6 +1,9 @@
 import type { QueryAggregate } from "./shared_types.js";
 import type { AppQueries, AppQueryColumns } from "./types.js";
 import type { ResolvedOption } from "./select.js";
+import type { UploadedFile } from "./hooks.js";
+import type { ReportLanguage } from "./shared_types.js";
+import type { ReportColumn, ReportReading } from "./shared_types.js";
 /**
  * One row of a query whose columns codegen could not read (a dynamic alias, a
  * bare `from_table`). Values stay `unknown` — the cell readers narrow them.
@@ -169,12 +172,44 @@ export interface QueryCall {
 export declare function useQueries(calls: readonly QueryCall[], opts?: Pick<QueryOptions, "enabled" | "revalidateOnFocus">): QueryState<QueryRow>[];
 /**
  * Every row a declared query matches, read a page at a time to the end — for what must hold every row
- * (a saved sheet), never for a screen, which pages. The server's rows as stored: no write is drawn over them.
+ * (an act over every row in view), never for a screen, which pages, nor for a file, which `exportQuery` makes on the
+ * server. The server's rows as stored: no write is drawn over them.
  */
 export declare function queryAll(alias: string, params?: Record<string, unknown>, opts?: {
     filter?: QueryFilter;
     sort?: readonly QuerySortKey[];
 }): Promise<QueryRow[]>;
+/** What an export states of its rows beside them: the page's title, one line per thing narrowing them, and the
+ *  figures over them as the screen drew them. */
+export interface ExportReport {
+    title: string;
+    lines: string[];
+    readings: ReportReading[];
+}
+/** The file an export makes: the default report workbook — its words in `language`, the rows under `columns` on the
+ *  tab `sheet` — or a template the query declares under `templates`, by its name there. */
+export type ExportFile = {
+    kind: "workbook";
+    language: ReportLanguage;
+    sheet: string;
+    columns: ReportColumn[];
+} | {
+    kind: "template";
+    template: string;
+};
+export interface ExportCall {
+    params?: Record<string, unknown>;
+    filter?: QueryFilter;
+    sort?: readonly QuerySortKey[];
+    report: ExportReport;
+    file: ExportFile;
+}
+/**
+ * Every row a declared query matches — narrowed by `filter` and ordered by `sort` as a page of it is — made into one
+ * file by the server, so no row reaches the browser. Past the most rows one export holds it is refused, never cut.
+ * Resolves the stored file, its URL signed for the caller.
+ */
+export declare function exportQuery(alias: string, call: ExportCall): Promise<UploadedFile>;
 /** One select column's full option set. */
 export interface FieldOptions {
     /** The source field's display name. */

package/dist/router.js

@@ -1,7 +1,7 @@
 import {
   isEmbedded,
   setUrlParams
-} from "./chunk-ARV5FAU5.js";
+} from "./chunk-ZOFKWF6V.js";
 
 // src/router.tsx
 import { useEffect } from "react";

package/dist/rpc.d.ts

@@ -8,7 +8,7 @@ import { type UrlParams, type UrlParamsPatch } from "./url_params.js";
  *   app  → host: { id, op, payload }
  *   host → app:  { id, type: "result", data } | { id, type: "error", message }
  */
-export type RpcOp = "query" | "field_options" | "workflow" | "agentRuns" | "agentRun.get" | "agentRun.cancel" | "upload" | "file.rename" | "members" | "context" | "write_model" | "prediction_miss" | "openExternal" | "openApp" | "askAi" | "urlState.get" | "urlState.set" | "folder.get" | "folder.set" | "comments.list" | "comments.create" | "comments.update" | "comments.delete" | "comments.counts" | "recording.start" | "recording.stop";
+export type RpcOp = "query" | "export" | "field_options" | "workflow" | "agentRuns" | "agentRun.get" | "agentRun.cancel" | "upload" | "file.rename" | "members" | "context" | "write_model" | "prediction_miss" | "openExternal" | "openApp" | "askAi" | "urlState.get" | "urlState.set" | "folder.get" | "folder.set" | "comments.list" | "comments.create" | "comments.update" | "comments.delete" | "comments.counts" | "recording.start" | "recording.stop";
 export interface AgentRunPayload {
     alias: string;
     session_id: string;

package/dist/shared_types.d.ts

@@ -4,5 +4,16 @@
  * tarball. Written at every build, never edited.
  */
 export type QueryAggregate = { by?: readonly string[]; day?: string; sum?: string; };
-export type TableField = { key: string; name: string; description: string; type: "number"; format: "number" | "currency" | "percentage"; confirm_before_update?: boolean | undefined; required?: boolean | undefined; currency?: string | null | undefined; unit?: string | null | undefined; unit_field?: string | null | undefined; currency_field?: string | null | undefined; default_value?: number | null | undefined; } | { key: string; name: string; description: string; type: "text"; confirm_before_update?: boolean | undefined; required?: boolean | undefined; unique?: boolean | undefined; format?: "text" | "link" | "markdown" | undefined; default_value?: string | null | undefined; } | { key: string; name: string; description: string; type: "date"; confirm_before_update?: boolean | undefined; required?: boolean | undefined; format?: "date" | "datetime" | "date_range" | "datetime_range" | undefined; timezone?: string | undefined; derive_from?: "created_at" | "updated_at" | undefined; default_value?: string | null | undefined; } | { key: string; name: string; description: string; type: "boolean"; confirm_before_update?: boolean | undefined; required?: boolean | undefined; default_value?: boolean | null | undefined; } | { key: string; name: string; description: string; type: "select"; options: { key: string; name: string; color: "red" | "orange" | "amber" | "yellow" | "lime" | "green" | "emerald" | "teal" | "cyan" | "sky" | "blue" | "indigo" | "violet" | "purple" | "fuchsia" | "pink" | "rose" | "slate" | "gray" | "zinc" | "neutral" | "stone"; mark?: { kind: string; name: string; } | undefined; }[]; confirm_before_update?: boolean | undefined; required?: boolean | undefined; multi?: boolean | undefined; default_value?: string[] | null | undefined; } | { key: string; name: string; description: string; type: "select_member"; confirm_before_update?: boolean | undefined; required?: boolean | undefined; multi?: boolean | undefined; default_value?: string[] | null | undefined; } | { key: string; name: string; description: string; type: "select_record_link"; table_id: string; display_field_keys: string[]; confirm_before_update?: boolean | undefined; required?: boolean | undefined; display_field_widths?: Record<string, number> | undefined; paired_field_key?: string | undefined; cardinality?: "one" | "many" | undefined; } | { key: string; name: string; description: string; type: "rollup"; source_field_key: string; aggregate_option: { operation: "count"; field_key?: string | undefined; } | { operation: "unique" | "empty" | "filled" | "percent_empty" | "percent_filled" | "percent_unique"; field_key: string; } | { operation: "min" | "unique" | "empty" | "filled" | "percent_empty" | "percent_filled" | "percent_unique" | "sum" | "avg" | "median" | "max" | "range"; field_key: string; } | { operation: "unique" | "date_range" | "empty" | "filled" | "percent_empty" | "percent_filled" | "percent_unique" | "earliest" | "latest"; field_key: string; } | { operation: "unique" | "empty" | "filled" | "percent_empty" | "percent_filled" | "percent_unique" | "selected"; field_key: string; } | { operation: "unique" | "empty" | "filled" | "percent_empty" | "percent_filled" | "percent_unique" | "selected"; field_key: string; } | { operation: "empty" | "filled" | "percent_empty" | "percent_filled" | "selected"; field_key: string; } | { operation: "checked" | "unchecked" | "percent_checked" | "percent_unchecked"; field_key: string; } | { operation: "empty" | "filled" | "percent_empty" | "percent_filled" | "selected"; field_key: string; } | { operation: "min" | "unique" | "date_range" | "empty" | "filled" | "percent_empty" | "percent_filled" | "percent_unique" | "sum" | "avg" | "median" | "max" | "range" | "earliest" | "latest" | "checked" | "unchecked" | "percent_checked" | "percent_unchecked"; field_key: string; } | { operation: "min" | "unique" | "date_range" | "empty" | "filled" | "percent_empty" | "percent_filled" | "percent_unique" | "sum" | "avg" | "median" | "max" | "range" | "earliest" | "latest"; field_key: string; }; confirm_before_update?: boolean | undefined; required?: boolean | undefined; filter?: TableRecordFiltersGroupNode | undefined; aggregate_field_type?: "number" | "boolean" | "text" | "date" | "select" | "select_member" | "select_record_link" | "rollup" | "files" | "formula" | "lookup" | "button" | "autonumber" | undefined; aggregate_field_format?: string | undefined; aggregate_field_currency?: string | undefined; aggregate_field_unit?: string | undefined; aggregate_field_unit_field?: string | undefined; aggregate_field_currency_field?: string | undefined; } | { key: string; name: string; description: string; type: "lookup"; source_field_key: string; lookup_field_key: string; confirm_before_update?: boolean | undefined; required?: boolean | undefined; lookup_field_type?: "number" | "boolean" | "text" | "date" | "select" | "select_member" | "select_record_link" | "rollup" | "files" | "formula" | "lookup" | "button" | "autonumber" | undefined; lookup_field_format?: string | undefined; lookup_field_currency?: string | undefined; lookup_field_unit?: string | undefined; lookup_field_options?: { key: string; name: string; color?: string | undefined; mark?: { kind: string; name: string; } | undefined; }[] | undefined; order_by?: { field_key: string; direction: "asc" | "desc"; } | undefined; } | { key: string; name: string; description: string; type: "files"; confirm_before_update?: boolean | undefined; required?: boolean | undefined; } | { key: string; name: string; description: string; type: "formula"; formula: { expression: string; format?: "number" | "currency" | "percentage" | "link" | undefined; currency?: string | undefined; unit?: string | undefined; unit_field?: string | undefined; currency_field?: string | undefined; output_type?: "number" | "boolean" | "text" | "date" | "datetime" | undefined; volatile?: boolean | undefined; }; confirm_before_update?: boolean | undefined; required?: boolean | undefined; } | { key: string; name: string; description: string; type: "button"; text: string; confirm_before_update?: boolean | undefined; required?: boolean | undefined; workflow_id?: string | null | undefined; } | { key: string; name: string; description: string; type: "autonumber"; confirm_before_update?: boolean | undefined; required?: boolean | undefined; prefix?: string | undefined; padding?: number | undefined; template?: string | undefined; };
+export type ReportColumn = { key: string; header: string; type: "number" | "text" | "date"; };
+export type ReportLanguage = "vi" | "en";
+export type ReportPart = { label: string; value: number; share: number | null; };
+export type ReportPivotColumn = { label: string; total: number | null; };
+export type ReportPivotRow = { label: string; values: number[]; total: number | null; };
+export type ReportPoint = { label: string; value: number; partial: boolean; };
+export type ReportReading = (ReportReadingHead & { kind: "metric"; value: number | null; }) | (ReportReadingHead & { kind: "breakdown"; byLabel: string; parts: ReportPart[]; total: number | null; }) | (ReportReadingHead & { kind: "trend"; points: ReportPoint[]; }) | (ReportReadingHead & { kind: "pivot"; rowsLabel: string; columnsLabel: string; columns: ReportPivotColumn[]; rows: ReportPivotRow[]; total: number | null; }) | { kind: "failed"; label: string; };
+export type ReportReadingHead = { label: string; valueLabel: string; unit: string | null; truncated: boolean; };
+export type TableField = { key: string; name: string; description: string; type: "number"; format: "number" | "currency" | "percentage"; confirm_before_update?: boolean | undefined; required?: boolean | undefined; currency?: string | null | undefined; unit?: string | null | undefined; unit_field?: string | null | undefined; currency_field?: string | null | undefined; default_value?: number | null | undefined; } | { key: string; name: string; description: string; type: "text"; confirm_before_update?: boolean | undefined; required?: boolean | undefined; unique?: boolean | undefined; format?: "text" | "link" | "markdown" | undefined; default_value?: string | null | undefined; } | { key: string; name: string; description: string; type: "date"; confirm_before_update?: boolean | undefined; required?: boolean | undefined; format?: "date" | "datetime" | "date_range" | "datetime_range" | undefined; timezone?: string | undefined; derive_from?: "created_at" | "updated_at" | undefined; default_value?: string | null | undefined; } | { key: string; name: string; description: string; type: "boolean"; confirm_before_update?: boolean | undefined; required?: boolean | undefined; default_value?: boolean | null | undefined; } | { key: string; name: string; description: string; type: "select"; options: { key: string; name: string; color: "red" | "orange" | "amber" | "yellow" | "lime" | "green" | "emerald" | "teal" | "cyan" | "sky" | "blue" | "indigo" | "violet" | "purple" | "fuchsia" | "pink" | "rose" | "slate" | "gray" | "zinc" | "neutral" | "stone"; mark?: { kind: string; name: string; } | undefined; }[]; confirm_before_update?: boolean | undefined; required?: boolean | undefined; multi?: boolean | undefined; default_value?: string[] | null | undefined; } | { key: string; name: string; description: string; type: "select_member"; confirm_before_update?: boolean | undefined; required?: boolean | undefined; multi?: boolean | undefined; default_value?: string[] | null | undefined; } | { key: string; name: string; description: string; type: "select_record_link"; table_id: string; display_field_keys: string[]; confirm_before_update?: boolean | undefined; required?: boolean | undefined; display_field_widths?: Record<string, number> | undefined; paired_field_key?: string | undefined; cardinality?: "one" | "many" | undefined; } | { key: string; name: string; description: string; type: "rollup"; source_field_key: string; aggregate_option: { operation: "count"; field_key?: string | undefined; } | { operation: "unique" | "empty" | "filled" | "percent_empty" | "percent_filled" | "percent_unique"; field_key: string; } | { operation: "min" | "unique" | "empty" | "filled" | "percent_empty" | "percent_filled" | "percent_unique" | "sum" | "avg" | "median" | "max" | "range"; field_key: string; } | { operation: "unique" | "date_range" | "empty" | "filled" | "percent_empty" | "percent_filled" | "percent_unique" | "earliest" | "latest"; field_key: string; } | { operation: "unique" | "empty" | "filled" | "percent_empty" | "percent_filled" | "percent_unique" | "selected"; field_key: string; } | { operation: "unique" | "empty" | "filled" | "percent_empty" | "percent_filled" | "percent_unique" | "selected"; field_key: string; } | { operation: "empty" | "filled" | "percent_empty" | "percent_filled" | "selected"; field_key: string; } | { operation: "checked" | "unchecked" | "percent_checked" | "percent_unchecked"; field_key: string; } | { operation: "empty" | "filled" | "percent_empty" | "percent_filled" | "selected"; field_key: string; } | { operation: "min" | "unique" | "date_range" | "empty" | "filled" | "percent_empty" | "percent_filled" | "percent_unique" | "sum" | "avg" | "median" | "max" | "range" | "earliest" | "latest" | "checked" | "unchecked" | "percent_checked" | "percent_unchecked"; field_key: string; } | { operation: "min" | "unique" | "date_range" | "empty" | "filled" | "percent_empty" | "percent_filled" | "percent_unique" | "sum" | "avg" | "median" | "max" | "range" | "earliest" | "latest"; field_key: string; }; confirm_before_update?: boolean | undefined; required?: boolean | undefined; filter?: TableRecordFiltersGroupNode | undefined; aggregate_field_type?: "number" | "boolean" | "text" | "date" | "select" | "select_member" | "select_record_link" | "rollup" | "files" | "formula" | "lookup" | "button" | "autonumber" | undefined; aggregate_field_format?: string | undefined; aggregate_field_currency?: string | undefined; aggregate_field_unit?: string | undefined; aggregate_field_unit_field?: string | undefined; aggregate_field_currency_field?: string | undefined; } | { key: string; name: string; description: string; type: "lookup"; source_field_key: string; lookup_field_key: string; confirm_before_update?: boolean | undefined; required?: boolean | undefined; lookup_field_type?: "number" | "boolean" | "text" | "date" | "select" | "select_member" | "select_record_link" | "rollup" | "files" | "formula" | "lookup" | "button" | "autonumber" | undefined; lookup_field_format?: string | undefined; lookup_field_currency?: string | undefined; lookup_field_unit?: string | undefined; lookup_field_options?: { key: string; name: string; color?: string | undefined; mark?: { kind: string; name: string; } | undefined; }[] | undefined; order_by?: { field_key: string; direction: "asc" | "desc"; } | undefined; } | { key: string; name: string; description: string; type: "files"; confirm_before_update?: boolean | undefined; required?: boolean | undefined; } | { key: string; name: string; description: string; type: "formula"; formula: { expression: string; format?: "number" | "currency" | "percentage" | "link" | undefined; currency?: string | undefined; unit?: string | undefined; unit_field?: string | undefined; currency_field?: string | undefined; options?: { key: string; name: string; color: "red" | "orange" | "amber" | "yellow" | "lime" | "green" | "emerald" | "teal" | "cyan" | "sky" | "blue" | "indigo" | "violet" | "purple" | "fuchsia" | "pink" | "rose" | "slate" | "gray" | "zinc" | "neutral" | "stone"; mark?: { kind: string; name: string; } | undefined; }[] | undefined; output_type?: "number" | "boolean" | "text" | "date" | "datetime" | "select" | undefined; volatile?: boolean | undefined; }; confirm_before_update?: boolean | undefined; required?: boolean | undefined; } | { key: string; name: string; description: string; type: "button"; text: string; confirm_before_update?: boolean | undefined; required?: boolean | undefined; workflow_id?: string | null | undefined; } | { key: string; name: string; description: string; type: "autonumber"; confirm_before_update?: boolean | undefined; required?: boolean | undefined; prefix?: string | undefined; padding?: number | undefined; template?: string | undefined; };
 export type TableRecordFilters = TableRecordFiltersConditionNode | TableRecordFiltersTraversalNode | TableRecordFiltersGroupNode;
+export type TableRecordFiltersConditionNode = { node_type: "condition"; field_key?: string | undefined; type?: string | undefined; operator: string; value?: unknown; unit_option?: string | undefined; };
+export type TableRecordFiltersGroupNode = { node_type: "group"; logic: "and" | "or"; children: (TableRecordFilters)[]; };
+export type TableRecordFiltersTraversalNode = { node_type: "traversal"; path: string[]; condition: TableRecordFiltersConditionNode; };

package/docs/ai.md

@@ -13,7 +13,7 @@ Don't run a structured extraction through `askAi` (the result is stranded in a c
 
 ## Declared agents — what `useAgentRun` runs
 
-An agent is **declared on the app server-side, by alias**, with the `set_app_agent` tool (removed with `remove_app_agent`) — the one way an agent is bound or changed, each write a new version of the app; a deploy never touches it, and `get_app_agent` reads one back. Invoking an alias that isn't bound fails with a "no agent alias" error naming `set_app_agent`, and a deploy warns about any alias the code calls that is not bound.
+An agent is **declared on the app server-side, by alias**, with the `set_app_agent` tool (removed with `remove_app_agent`) — the one way an agent is bound or changed, each write a new version of the app; a deploy never touches it, and `get_app_agent` reads one back. Invoking an alias that isn't bound fails with a "no agent alias" error naming `set_app_agent`, and a sandbox deploy warns about any alias the code calls that is not bound.
 
 A declaration carries:
 
@@ -38,7 +38,7 @@ A declaration carries:
 
 So an agent that reads or writes records needs a named query or workflow for each thing it touches — the same declaration the app's own UI uses. Declare only what that agent needs; a second agent in the same app can declare a narrower set.
 
-**Typing.** `.lotics/app_agents.d.ts`, generated from the app's live bindings whenever a sandbox session opens on the app, augments the SDK's `AppAgents` (alias → input shape) and `AppAgentResults` (alias → declared output shape) interfaces — `useAgentRun("recognize")` then types both `run(input)` and `output`. An alias it does not carry — every alias, in a project on your own machine — falls back to `Record<string, unknown>` input / `unknown` output.
+**Typing.** `.lotics/app_agents.d.ts`, generated from the app's live bindings whenever a sandbox session opens on the app and by `lotics app create --custom` and `lotics app deploy`, augments the SDK's `AppAgents` (alias → input shape) and `AppAgentResults` (alias → declared output shape) interfaces — `useAgentRun("recognize")` then types both `run(input)` and `output`. An alias it does not carry falls back to `Record<string, unknown>` input / `unknown` output.
 
 ---
 

package/docs/data_fetching.md

@@ -10,9 +10,9 @@ The read model in one paragraph: an app never sends a raw query. It invokes a **
 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
 ([./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.
+so params are typed per the binding; an alias it does not carry is accepted as a plain string,
+untyped. It is written from the app's live bindings whenever a sandbox session opens on the app,
+and by `lotics app create --custom` and `lotics app deploy`. Every hook reads through the SDK's own cache, over the host RPC bridge.
 
 ## Choosing a read
 
@@ -23,7 +23,8 @@ machine has none, so every alias is accepted there as a plain string, untyped. E
 | `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 |
+| `queryAll(alias, params?, { filter, sort })` | a promise of every row | outside React, for a job that must hold the whole narrowed set in the browser (the ids an act runs on): 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 |
+| `exportQuery(alias, { params, filter, sort, report, file })` | a promise of the file | every row the narrowed set holds, made into one file by the server — no row reaches the browser. `report` is `{ title, lines, readings }`; `file` is `{ kind: "workbook", language, sheet, columns }` (the default report workbook, each column `{ key, header, type }` an output column of the query — a `number` one on a number column, a `date` one on a date or datetime) or `{ kind: "template", template }`, one the query declares under `templates` by name ([queries](./queries.md)). Past 20,000 rows it rejects, never cuts; each caller makes at most 60 exports a minute. The file's `url` is signed for the caller: open it with `openExternal` |
 
 Every hook answers the same `QueryState`: `rows`, `truncated`, `total`, `counts`, `loading`,
 `isValidating`, `error`, `pending`, `refetch`, `page`, `setPage`, `pageCount`, `hasMore`,

package/docs/members_and_options.md

@@ -170,6 +170,7 @@ in it, while a resolved CELL keeps naming them.
 `image` is the avatar URL (a presigned URL valid 24 hours, or the member's external OAuth photo) and
 may be `null`. `name` may be null/empty for members without a display name — fall back to `email`. On failure the hook does not throw: it
 resolves `{ members: [], loading: false, error }`.
+`{ enabled: false }` reads nothing until the screen needs the roster.
 
 Every hook reading one `group` shares one roster: it is read again when a screen reading it mounts, never on focus.
 

package/docs/mutations.md

@@ -41,12 +41,11 @@ render: one callable per alias, each run exactly as `useWorkflow`'s.
 
 Typing comes from `.lotics/app_workflows.d.ts`, which augments the SDK's `AppWorkflows` and
 `AppWorkflowResults` interfaces from the app's bound declarations. The declarations are generated from the app's live bindings into `.lotics/` whenever a sandbox
-session opens on the app. A project on your own machine has none, so every alias is accepted as a
-plain string there, untyped. The result:
+session opens on the app, and by `lotics app create --custom` and `lotics app deploy`. The result:
 
 | Declaration | Call-site type |
 |---|---|
-| Alias not declared | Compile-time error at `useWorkflow("...")` |
+| Alias not declared | Accepted as a plain string: untyped `Record<string, unknown>` payload, `unknown` result |
 | Declared with `inputs` | `(inputs: <declared shape>) => Promise<WorkflowResult<TData>>` — inputs required and shaped |
 | Declared with an empty `inputs: {}` | `(inputs?: Record<string, never>)` — call with `{}` or nothing |
 | Declared without `inputs` | Untyped `Record<string, unknown>` payload (and unvalidated server-side — declare inputs for any real workflow) |
@@ -273,8 +272,8 @@ When the alias declares `inputs`, the server validates the payload before the wo
 - **`select` names its option set one of two ways — declare exactly one (both or neither is a
   set-time error).** *Inline* `options: [{label, value}]` freezes the set into the generated
   literal union and is **format-only at run time**: any well-formed key is accepted, and an
-  option added to the live field after deploy is valid at run time but fails the compile-time
-  type (widen or redeploy the declaration when the frozen union gets in the way).
+  option added to the live field after binding is valid at run time but fails the compile-time
+  type (widen or rebind the declaration when the frozen union gets in the way).
   *Field-referenced* `field: "fld_…"` (a select field's global key — `fld_…`, no table prefix)
   is **drift-proof**: the union is resolved from the field's *current* options at type-gen, and
   the submitted value is validated against the field's *current* options at run time — an option

package/docs/queries.md

@@ -45,6 +45,14 @@ Queries live on the app, as an alias → declaration map. `set_app_query` binds
 - **`description`** — one line saying what the query returns, capped at 300 characters. No app
   code reads it: it is what the **agents** that reach this app's data (its declared agents, a
   member's chat while the app is open) read to choose between your aliases.
+- **`templates`** — the document templates an `exportQuery` of this alias may fill, by the name
+  the export asks for: `{ "<name>": { "template_id": "dtl_…", "rows": "<key>" } }`. The template
+  is filled with `{ title, lines, readings, <key>: every row }`, each row keyed by output column —
+  a figure, a yes/no, a date or moment as stored (ISO), anything else its words (options,
+  members, linked rows and files by name, comma-joined). An excel template makes a workbook, an
+  html one a PDF. Binding refuses a template that is not a live excel or html template of the
+  app's workspace, one the app's owner may not use, or one reading at its root anything but
+  those keys; `rows` is never `title`, `lines` or `readings`.
 - Aliases must be valid JS identifiers (`useQuery("openOrders")` and the generated types depend on it).
 
 A deploy never touches the bindings; `get_app_query` reads one back. The **server holds the
@@ -54,9 +62,9 @@ query's reach (a token in a `table_id` or field-key position fails validation).
 
 ### What deploy validates
 
-Deploy fails — with the compiler's own message, never raw SQL/Postgres text — when any alias:
+Binding fails — with the compiler's own message, never raw SQL/Postgres text — when any alias:
 
-1. isn't a valid identifier, or the declaration isn't `{ ast, params?, description? }` (a
+1. isn't a valid identifier, or the declaration isn't `{ ast, params?, description?, templates? }` (a
    description over 300 characters is refused here too);
 2. references `{{params.x}}` without declaring param `x` (typos can't silently widen);
 3. doesn't parse as a `QueryNode` **as the raw template** (the runtime parses the stored
@@ -72,12 +80,12 @@ Deploy fails — with the compiler's own message, never raw SQL/Postgres text
    overrides, `writable_target` on a computed column;
 7. fails to **compile to SQL** — several rejections exist only in the compiler (the expression
    allowlist, link extraction over a composed parent, derived-filter operators with no
-   translation). Deploy compiles every query so these fail at deploy, not at first run;
+   translation). Binding compiles every query so these fail at bind, not at first run;
 8. has optional params and the **pruned** shape (all optional params omitted) fails any of the
    above — each omitted optional param executes a pruned variant of the template, and the
-   all-params shape compiling doesn't prove the pruned one does. Deploy validates both.
+   all-params shape compiling doesn't prove the pruned one does. Binding validates both.
 
-What deploy **cannot** catch: data-dependent failures (a statement timeout on a huge unindexed
+What binding **cannot** catch: data-dependent failures (a statement timeout on a huge unindexed
 scan, the file-presign ceiling) — those surface at run time as clean, safe errors (§10).
 
 ### Execution
@@ -162,7 +170,7 @@ only. Read what a row holds through your projection and the `read*` helpers, nev
 ## 2. The AST node reference
 
 Eleven node kinds. Every node except `from_table` wraps one or more child nodes; each subtree
-compiles to a derived `SELECT`. All structural errors below fail at **deploy** (the output
+compiles to a derived `SELECT`. All structural errors below fail at **bind** (the output
 schema + compile passes run there); only data-dependent errors fail at run time.
 
 ### `from_table` — the only leaf
@@ -179,7 +187,7 @@ Scans one table. Output = one column per field on the table (named by field key,
 plus the system columns. `filter`, `search` (AND-ed with `filter`), `sort`, and `limit` apply
 inside the scan — this is the **source layer**, where the richest operator support and all
 indexes live (§10). `sort` entries are `{ field_key, order: "asc"|"desc", blank_position?:
-"top"|"bottom" }` (blanks default to bottom). Unknown filter/sort field keys fail deploy.
+"top"|"bottom" }` (blanks default to bottom). Unknown filter/sort field keys fail binding.
 
 ### `project` — choose and compute columns
 
@@ -200,7 +208,7 @@ indexes live (§10). `sort` entries are `{ field_key, order: "asc"|"desc", blank
   `type`, is always nullable, and is never writable.
 - Output names must be unique and non-reserved.
 - A passthrough may declare a `type` **override** — realized as a *real, guarded SQL cast*
-  (§4), never a relabel. An uncastable combination is rejected at deploy.
+  (§4), never a relabel. An uncastable combination is rejected at bind.
 - **Project only what you render.** A bare `from_table` ships every column — including `files`
   cells with storage keys — to the client (over-exposure + the presign ceiling at scale).
 - **A files column takes `limit` — bound it when the surface renders a THUMBNAIL, not the
@@ -209,7 +217,7 @@ indexes live (§10). `sort` entries are `{ field_key, order: "asc"|"desc", blank
   without it the response pays to resolve every entry toward the presign ceiling (§10). The bound
   is per CELL, caps at `FILES_PROJECTION_MAX_LIMIT` (10), and is a different axis from the
   query's own `limit`, which counts ROWS; `limit` on any non-`files` column or computed source is
-  rejected at deploy. **On a UNION, set it on every arm** — arms align by name and type, not by
+  rejected at bind. **On a UNION, set it on every arm** — arms align by name and type, not by
   `limit`, so an arm that omits it still yields whole cells.
 
 ### `filter` — predicate over derived columns
@@ -238,7 +246,7 @@ source filter automatically (making it index-servable); otherwise it evaluates p
 
 Single **equality** predicate on one output column per side — no multi-column ON, no
 inequality/range joins. The two ON columns must share a SQL value category (text/number/…);
-mismatches are rejected at deploy (cast one side with a projection type override). Column-name
+mismatches are rejected at bind (cast one side with a projection type override). Column-name
 collisions between the sides are rejected — `project`-rename first. A `left` join makes every
 right-side column nullable. Addressing (write-through, `record_id` filtering) follows the
 **left** side only.
@@ -268,7 +276,7 @@ came from.
 ```
 
 Full semantics in §8. `by` may be empty (a single-row aggregate); `aggregates` needs ≥ 1 entry.
-Aggregate operation × input-column type is validated at deploy. Grouping collapses rows —
+Aggregate operation × input-column type is validated at bind. Grouping collapses rows —
 addressing is dropped.
 
 ### `window` — aggregate without collapsing
@@ -414,7 +422,7 @@ must be valid over `field`'s type — a refusal lists the valid ones.
   (`round`/`floor`/`ceil`/`abs` are 1-arg; `round` rounds to an integer.)
 - **Operators**: `+ - * / %`, `== === != !==`, `< > <= >=`, `&& ||`, `??` (→ `COALESCE`),
   unary `- + !`, and the ternary `cond ? a : b`.
-- **Not supported** (rejected at deploy): indexing `[…]`, nested access (`input.a.b`), list/map
+- **Not supported** (rejected at bind): indexing `[…]`, nested access (`input.a.b`), list/map
   literals, arrow functions, method calls, any other function. Project the raw columns and
   compute client-side instead.
 
@@ -424,7 +432,7 @@ must be valid over `field`'s type — a refusal lists the valid ones.
 ```
 
 Prefer the typed variants where one exists — expressions are strings and get less structural
-validation (though they still compile-check at deploy).
+validation (though they still compile-check at bind).
 
 ---
 
@@ -445,7 +453,7 @@ a **real SQL cast**, guarded so malformed values become NULL instead of aborting
 | `text` → `number` / `boolean` / `date` / `datetime` | guarded cast; a non-conforming value → NULL |
 | `json` → any scalar | via the JSON scalar text, guarded the same way |
 | scalar → `text` / `json` | plain cast |
-| array-valued (`select`/`member`/`link`/`files`) ↔ scalar | **impossible — rejected at deploy** |
+| array-valued (`select`/`member`/`link`/`files`) ↔ scalar | **impossible — rejected at bind** |
 
 The guarded-NULL rule means a query never aborts because one row holds `"n/a"` in a text column
 you cast to number — that row's cell is NULL. Use overrides to align UNION arms or to make a
@@ -469,7 +477,7 @@ derived surfaces share one implementation.
 | select_member | `select_member` | select ops + `is_current_member`, `is_not_current_member` (field-scoped, no value; `is_not_current_member` matches every cell not holding the requester, an empty one included) | same — `is_current_member` **works at the runtime layer** too | `unnest` fans member ids. Anonymous public request: current-member binds the app owner (§1). |
 | select_record_link | `select_record_link` | membership by linked-record **id**: `has_any_of`, `has_none_of`, `has_all_of`; text over the cached **display**: `contains`, `not_contains`, `starts_with`, `ends_with`; `is_empty`, `is_not_empty` | same — id-membership works at the runtime layer (converged `[{id}]` containment) | Sorting orders by raw JSON, not display text — project the display (link extraction / `display_output`) and sort that. `unnest` fans link ids (+ display). |
 | files | `files` | `has_filename`, `has_mime_type` (substring), `has_file_count` (exact count), `is_empty`, `is_not_empty` | same | Presign-enriched at delivery (§1); `unnest` fans file ids. Only presence-counting aggregates. |
-| formula | its declared output type (`number`/`text`/`boolean`/`date`/`datetime`; `json` until inferred) | filtered by the output type's operators; `#ERROR:` cells are guarded — they count as empty and never match value operators | same | Extracted as a real scalar, so numeric formulas feed `sum`/`avg`/sorts. A **datetime-output** formula matches day-level date filters (full-day expansion). |
+| formula | its declared output type (`number`/`text`/`boolean`/`date`/`datetime`, or `select` for one stating its own options, its cell a single select's; `json` until inferred) | filtered by the output type's operators; `#ERROR:` cells are guarded — they count as empty and never match value operators | same | Extracted as a real scalar, so numeric formulas feed `sum`/`avg`/sorts. A **datetime-output** formula matches day-level date filters (full-day expansion). |
 | rollup | decided by the OPERATION, never by the aggregated field: `earliest`/`latest` → `date`/`datetime` per that field's format; **every** other op → `number` | number or date operators per output type; text operators route as text | same | Datetime-format rollups match day-level date filters. `date_range` counts DAYS between the extremes, so it is a number despite its date input. A presence count (`filled`/`empty`/`percent_*`) is a number whatever it counts — including over `files`. |
 | lookup | the type of the VALUE the looked-up field yields — a formula's output type, a rollup's operation result, an autonumber's display string (`text`); never the word `formula`/`rollup` | operators of that type, evaluated with ANY-element semantics over the linked values (a row matches if *any* linked value matches) | array-typed lookups follow their column type's rules | **Projection returns the first element only.** Emptiness on a files-lookup checks the inner file arrays (a linked record with zero files counts empty). For all values across links: unnest the link column + join (§8). |
 | autonumber | `text` | text operators — filter by the visible composed string (`"ORD-0042"`) | same | Sorts numerically when the stored value is a bare integer, lexicographically otherwise — so `"ORD-0042"` orders by its padding and an unprefixed `"124"` orders after `"99"`, not before it. |
@@ -554,7 +562,7 @@ stay index-served. Two access classes:
 Tokens interpolate in **value positions**. A string that *is* exactly one token is replaced by
 the param's typed value (an array param yields an array); a token embedded in a larger string
 interpolates as text. Declared-but-unreferenced params are fine; referenced-but-undeclared
-tokens fail deploy.
+tokens fail binding.
 
 **Composable optional filters (one query, many scopes).** Expose several independent filter
 axes from ONE named query — don't shard into a query-per-combination. Mark each scoping param
@@ -653,7 +661,7 @@ anywhere in the record*.
 ### The 21 aggregate operations
 
 `group` and `window` share one operation vocabulary. `count` is `COUNT(*)` (no `input_column`);
-everything else requires an `input_column` whose type must be compatible — checked at deploy:
+everything else requires an `input_column` whose type must be compatible — checked at bind:
 
 | Operation | Valid input column types | Result | Notes |
 | --- | --- | --- | --- |
@@ -680,7 +688,7 @@ sizes on a shipment, the tags on a ticket) without a second query.
   "distinct": true, "separator": ", ", "max_values": 20 }
 ```
 
-- **`type` must be `text`** — declaring anything else is rejected at deploy.
+- **`type` must be `text`** — declaring anything else is rejected at bind.
 - **`distinct`** defaults to **true**: three containers sized 40HC/40HC/20DC give `20DC, 40HC`.
   Pass `false` to keep every occurrence. Values are always sorted, so the column doesn't
   reshuffle between reads.
@@ -713,7 +721,7 @@ over a `link` read of it is `true`.
 { "bucket": { "source": "created", "granularity": "month", "output": "period" } }
 ```
 
-- `source` must be a `date` or `datetime` **column** of the input (deploy-checked).
+- `source` must be a `date` or `datetime` **column** of the input (checked at bind).
 - `granularity`: `day` | `week` | `month` | `quarter` | `year`. **Weeks are ISO — Monday
   start.**
 - Buckets are computed on the stored **wall-clock** value in the field's timezone (a 23:30
@@ -737,7 +745,7 @@ the timeout for nothing.
 legal SQL window call are accepted: **`count`, `sum`, `avg`, `min`, `max`, `earliest`, `latest`,
 `filled`, `checked`, `unchecked`.** The rest cannot take an OVER clause (`median` is an
 ordered-set aggregate; `unique`/`percent_unique`/`string_agg` need DISTINCT;
-`range`/`empty`/`date_range`/`percent_*` compose multiple calls) — rejected at deploy. The optional `frame` applies **only**
+`range`/`empty`/`date_range`/`percent_*` compose multiple calls) — rejected at bind. The optional `frame` applies **only**
 to these; a `frame` on a window with no `aggregates` is rejected as dead config.
 
 **Window `functions` — ranking / navigation.** Each is `{ "output", "fn", … }` (its own arg shape, no
@@ -751,7 +759,7 @@ to these; a `frame` on a window with no `aggregates` is rejected as dead config.
 | `dense_rank` | — | `number`, non-null. Ties share a rank; the next rank does **not** skip (1,2,2,3). |
 | `percent_rank` / `cume_dist` | — | `number`, non-null. Relative position in [0, 1]. |
 | `ntile` | `buckets` (positive int) | `number`, non-null. The row's bucket (1..buckets) splitting the partition into equal groups. |
-| `lag` / `lead` | `input_column`, `offset?` (int ≥ 1, default 1), `default?` (literal) | the input column's type, **nullable**. The value `offset` rows before / after this one; at the partition edge, `default` if given else NULL. `default`'s type must match the input column (checked at deploy). |
+| `lag` / `lead` | `input_column`, `offset?` (int ≥ 1, default 1), `default?` (literal) | the input column's type, **nullable**. The value `offset` rows before / after this one; at the partition edge, `default` if given else NULL. `default`'s type must match the input column (checked at bind). |
 
 **Top-N per group** — rank within each partition, then filter on the derived rank column:
 
@@ -791,7 +799,7 @@ first. For a fixed, small set of columns, N filtered aggregate queries also work
 
 ## 9. Runtime refinement — filter / sort / limit / offset / count
 
-Each query request carries optional refinement the server wraps **around** the deployed
+Each query request carries optional refinement the server wraps **around** the bound
 template as derived nodes, in this order: `filter` (narrow) → `sort` (order) → `limit`+`offset`
 (page):
 
@@ -857,11 +865,11 @@ ordering and scoping into the template or its params.
 | Statement timeout | **15 s** per query execution | 400: `query timed out after 15s — narrow the filter or simplify the query` |
 | Concurrent query executions | server-configured bulkhead (bounded slots + bounded queue wait) | **503**: `The app is handling too many requests right now. Please retry in a moment.` — a distinct busy-retry outcome; back off and retry |
 | Signed file URLs per response | server-configured, default **2,000 file entries** | 400 naming the alias, the count, and the ceiling — project files columns only where rendered, narrow, or paginate |
-| Traversal depth | 3 hops | **silent match-nothing** — a longer path compiles to `FALSE` (deploys green, returns zero rows) |
-| Param schema depth | 8 | deploy reject |
+| Traversal depth | 3 hops | **silent match-nothing** — a longer path compiles to `FALSE` (binds green, returns zero rows) |
+| Param schema depth | 8 | bind reject |
 
 Any other execution failure returns a generic `query execution failed` (the real error — which
-may embed SQL — is server-logged only). Deploy-time and validation errors are always specific.
+may embed SQL — is server-logged only). Bind-time and validation errors are always specific.
 
 ### Index reality, in plain terms
 
@@ -872,20 +880,21 @@ Records are stored partitioned by workspace, so a query reads only its own works
   layer** — `select`/`select_member`/`select_record_link` `has_any_of` / `has_all_of`, and
   `is_current_member`. These compile to containment the JSONB GIN index serves.
 - **Trigram-served:** `from_table.search` (§7).
-- **B-tree-served (automatic for deployed queries):** text `equals`, number and date
-  comparisons (exact and range), and `sort` fields — for fields referenced in a **deployed
-  named query's template**. The platform provisions a partial expression index per referenced
-  field automatically: built online whenever a query is bound (`set_app_query` or `apply_model`), re-synced daily,
+- **B-tree-served (automatic for bound queries):** text `equals`, number and date
+  comparisons (exact and range), `from_table.sort` fields, and a one-key `sort` node over a
+  number or date field the rows pass unchanged — for fields referenced in a **bound named
+  query's template**. The platform provisions a partial expression index per referenced
+  field automatically: built online whenever `set_app_query` or `set_app_queries` binds a query, re-synced daily,
   capped at 8 per table (fields past the cap fall back to the scan tier, with a server WARN).
   A `{{params.…}}` value hole doesn't change this — the field key is static in the template,
   so it still gets its index. Index-seek speed at any table size once provisioned.
 - **Table scan (linear in table size):** everything else — text `contains`, negations
   (`has_none_of`, `is_none_of`, `not_*`), emptiness, files predicates, and predicates/sorts on
-  fields that appear **only** in the runtime `filter`/`sort` options rather than the deployed
+  fields that appear **only** in the runtime `filter`/`sort` options rather than the bound
   template. Fine on thousands of rows; on very large tables these dominate latency and are the
   usual timeout cause.
 
-**Filter shape drives latency.** Equality/range/sort predicates in the deployed template are
+**Filter shape drives latency.** Equality/range/sort predicates in the bound template are
 index-served; lead with those or a GIN-served membership filter / `search`, and let scan-shaped
 predicates refine the already-narrowed set. Derived-layer filters run over the subquery result
 (no index), so **filter at the source layer whenever the field exists there** — the runtime
@@ -893,14 +902,16 @@ filter is for caller-driven refinement, not for the main cut (a runtime-only fie
 managed index). (The engine pushes eligible filter-over-union predicates down automatically,
 but don't rely on that for other shapes.)
 
-**Sorted, paginated unions are index-served — write them plainly.** A `limit(sort(union(project(from_table) …)))`
-register (the "search all three tables, sort by one column, paginate" shape) is compiled to push
-`ORDER BY … LIMIT` into each arm and `MergeAppend` the per-arm sort-index scans — it does **not**
-scan every arm whole and heap-sort the union. So a single-key sort over a union of tables, each
-projecting that key as a direct field passthrough, is fast at any size. Don't hand-split it into
-per-table queries you merge client-side; the merge already happens in the index. (Requires the
-sort key to be a bare field projection — a computed/literal/type-overridden sort column falls back
-to the whole-union sort.)
+**A sorted page reads in its sort index — declare the order it is read in.** A page sorted by one
+column that passes a number or date field unchanged (a bare `project` source with no `type`
+override, an `unpivot` passthrough, or a row column that reads the same field in every row) reads
+the table in that field's sort index and stops at the page, instead of reading every row and
+sorting. Over a `union`, each arm is paged this way on its own and the arms are merged, so a
+register over several tables or `unpivot` sides is fast at any size — don't hand-split it into
+per-table queries you merge client-side. The index exists when a bound template sorts that field
+in the same direction and blank position: give the query its default order as a top-level `sort`,
+and a page the app sorts the same way is served. A text column, a computed, literal or cast column,
+a sort on more than one key, and a cursor (`keyset`) page sort every row.
 
 **An aggregate arm you cannot filter costs its whole table, every execution.** A `join` whose right
 side is a `group` over entire tables, keyed on a value the LEFT side supplies at run time, has no

package/docs/recipes.md

@@ -85,14 +85,14 @@ Filter **server-side** so the app never receives another row.
 ```
 
 - `{{params.<name>}}` resolves **only in value positions**. A token in `table_id` or `field_key` is
-  not a real identifier and fails the deploy.
+  not a real identifier and fails the binding.
 - `useQuery("lookupShipment", { code })` is reactive on `code`. Gate on a *submitted* code — an
   empty one matches nothing, so render a prompt rather than an empty table.
 - An **autonumber** field stores the composed string (`DL-2026-0006`), so `equals` / `contains`
   filter it directly as text. No reverse mapping.
 
 **A code lookup carries no viewer identity, so it is an enumerable IDOR.** Fine for an internal or
-embedded app; never ship it as a public per-user portal — see `lotics docs security`.
+embedded app; never ship it as a public per-user portal — see [security](./security.md).
 
 ## Compose many optional filter axes in one query
 
@@ -103,7 +103,7 @@ whose `{{params.x}}` the caller did not pass, and collapses emptied groups to ma
 So `useQuery("search", { keyword })` filters by keyword alone, and `{}` returns everything. A
 missing *required* param still fails.
 
-Full pattern, including the date-param trick for range filters: `lotics docs queries` →
+Full pattern, including the date-param trick for range filters: [queries](./queries.md) →
 "Composable optional filters".
 
 ## Decode cells with the accessors, never by hand
@@ -128,7 +128,7 @@ 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.
-`update_app` sets both; a deploy warns while they are unset.
+`update_app` sets both.
 
 **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.

package/docs/runtime.md

@@ -62,15 +62,18 @@ 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/mock.d.ts` — `{ queries?, workflows?, recordings? }`).
+   `dist/mock.d.ts` — `{ queries?, workflows?, exports?, 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`); a read with `enabled: false` asks
+instead of making any request (`loading` stays `false`, except for a function fixture that
+returns a promise: the read stays loading until it settles, to review a pending state); 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.
+transport. `fixture.exports[alias]` answers `exportQuery(alias, call)` — a
+function of the call returning the file, or a promise of it to review the
+pending state. Calling `mount` again (HMR) replaces the registration last-write-wins.
 
 - **Fixture rows stand in for wire rows.** They pass through the same code path
   as fetched rows, so shape them exactly like the query's real output — the same
@@ -223,9 +226,9 @@ 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 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
+loading/error state, analytics, and typing from your declared aliases; a file of
+every row of a set is `exportQuery`, made by the server ([data_fetching](./data_fetching.md)).
+`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
@@ -234,6 +237,7 @@ semantics are documented:
 | Op | Payload | Resolves to | Owning doc |
 |---|---|---|---|
 | `query` | `{ alias, params?, limit?, offset?, … }` | `{ rows }` | [queries](./queries.md), [data fetching](./data_fetching.md) |
+| `export` | `{ alias, params?, filter?, sort?, report, file }` | `{ file }` | [data fetching](./data_fetching.md) |
 | `field_options` | `{ alias }` | `{ fields }` | [members & options](./members_and_options.md) |
 | `workflow` | `{ alias, inputs }` | `WorkflowResult` | [mutations](./mutations.md) |
 | `upload` | `{ file: File }` (the `File` crosses the bridge by structured clone) | uploaded-file object | [files](./files.md) |

package/docs/security.md

@@ -22,7 +22,7 @@ Comments are the one deliberate exception: access is app-authority (any member w
 
 ## The caller boundary
 
-Callers never submit query ASTs or workflow definitions — the server holds the canonical, deploy-validated template and the caller supplies only an **alias plus typed values**. Three per-input constraints are enforced server-side on **workflow and agent-run inputs** at invocation time, so a hand-crafted request can't redirect a run executing under owner authority:
+Callers never submit query ASTs or workflow definitions — the server holds the canonical, bind-validated template and the caller supplies only an **alias plus typed values**. Three per-input constraints are enforced server-side on **workflow and agent-run inputs** at invocation time, so a hand-crafted request can't redirect a run executing under owner authority:
 
 | Input type | Server-enforced bound |
 |---|---|

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/app-sdk",
-  "version": "0.101.1",
+  "version": "0.102.0",
   "description": "The SDK a Lotics custom-code app reads and writes through \u2014 typed hooks over the host bridge, cell readers, mount() and AppRouter",
   "type": "module",
   "exports": {