@lotics/cli 0.195.0 → 0.197.0

package/dist/src/cli.js

@@ -15464,6 +15464,15 @@ var LoticsClient = class {
   async getAppWorkflow(app_id, alias) {
     return this.execute("get_app_workflow", { app_id, alias });
   }
+  /**
+   * The app's capability catalog exactly as a chat or MCP caller reads it —
+   * every query, workflow and agent alias the caller's scope reaches, with the
+   * description each is chosen BY. One read for the whole app, so a check over
+   * what those readers see costs one request rather than one per alias.
+   */
+  async getAppCapabilities(app_id) {
+    return this.execute("get_app_capabilities", { app_id });
+  }
   /**
    * Fetch the server-generated workspace `.d.ts` + the wrapper envelope that
    * make a `src/workflows/<alias>.ts` body locally typecheckable (GAP-59).
@@ -15657,6 +15666,21 @@ var LoticsClient = class {
     await fs2.promises.writeFile(absolutePath, buffer);
     return absolutePath;
   }
+  /**
+   * One page of this workspace's stored files, newest first — `GET /v1/files`.
+   *
+   * The only enumeration there is: every other file surface takes an id, so
+   * without this "what is in the store" is answerable from Postgres alone, which
+   * is exactly the escape hatch a CLI-first workflow exists to remove. Paged by a
+   * keyset cursor the server mints; a caller walks until `next_cursor` is null.
+   */
+  async listFiles(opts) {
+    const params = new URLSearchParams();
+    if (opts?.limit !== void 0) params.set("limit", String(opts.limit));
+    if (opts?.cursor !== void 0) params.set("cursor", opts.cursor);
+    const query = params.toString();
+    return this.request("GET", `/v1/files${query ? `?${query}` : ""}`);
+  }
   async downloadFileById(fileId, destination, options) {
     const signedHeaders = this.buildHeaders();
     const signedUrlRes = await fetch(
@@ -33628,19 +33652,7 @@ var queryWindowFrameSchema = zod_default.object({
   following: zod_default.number().int().nonnegative().optional().describe("Rows following current. Omit for unbounded.")
 });
 var queryNodeSchema = zod_default.lazy(
-  () => zod_default.discriminatedUnion("kind", [
-    queryFromTableNodeSchema,
-    queryProjectNodeSchema,
-    queryFilterNodeSchema,
-    queryJoinNodeSchema,
-    queryUnionNodeSchema,
-    queryGroupNodeSchema,
-    queryWindowNodeSchema,
-    querySortNodeSchema,
-    queryLimitNodeSchema,
-    queryUnpivotNodeSchema,
-    queryUnnestNodeSchema
-  ])
+  () => zod_default.discriminatedUnion("kind", queryNodeSchemas)
 );
 var queryFromTableNodeSchema = zod_default.object({
   kind: zod_default.literal("from_table"),
@@ -33770,6 +33782,25 @@ var queryUnnestNodeSchema = zod_default.object({
     "Keep source rows whose cell is NULL / empty as one output row with NULL element columns. Defaults to false (such rows are dropped)."
   )
 });
+var queryNodeSchemas = [
+  queryFromTableNodeSchema,
+  queryProjectNodeSchema,
+  queryFilterNodeSchema,
+  queryJoinNodeSchema,
+  queryUnionNodeSchema,
+  queryGroupNodeSchema,
+  queryWindowNodeSchema,
+  querySortNodeSchema,
+  queryLimitNodeSchema,
+  queryUnpivotNodeSchema,
+  queryUnnestNodeSchema
+];
+var queryNodeKeysByKind = new Map(
+  queryNodeSchemas.map((schema) => [
+    schema.shape.kind.value,
+    new Set(Object.keys(schema.shape))
+  ])
+);
 var appWorkflowInputBaseSchema = zod_default.object({
   description: zod_default.string().optional().describe("Human-readable description of this input \u2014 surfaces in agent + CLI tooling"),
   required: zod_default.boolean().optional().describe("Whether the input must be provided. Defaults to true.")
@@ -36006,6 +36037,7 @@ function resolveScreen(app, screen, entityByAlias, roles) {
   if (findings.length > 0) return { type: "invalid", findings };
   return { type: "resolved", screen: { app, screen, entity, shapeLabel, record: record2, tabs, slots } };
 }
+var RECORD_CHILD_VIA = ["parent", "party"];
 var CHILD_COLUMN_ROLES = [
   "identity",
   "mark",
@@ -36018,9 +36050,9 @@ var CHILD_COLUMN_ROLES = [
   "lifecycle",
   "verdict"
 ];
-function parentLink(child, entity, roles) {
+function childLink(child, entity, roles, via) {
   return child.fields.find(
-    (field) => field.type === "select_record_link" && field.target_entity === entity.alias && roleOf(roles, child.alias, field.alias)?.role === "parent"
+    (field) => field.type === "select_record_link" && field.target_entity === entity.alias && roleOf(roles, child.alias, field.alias)?.role === via
   );
 }
 function fieldsWithRole(entity, roles, role) {
@@ -36077,16 +36109,25 @@ function recordSections(entity, entities, roles, header) {
   const shown = facts.filter((field) => !folded.has(field.alias));
   const sets = ownSets.map((field) => ({ kind: "expected_set", source: "own", field }));
   const children = [];
-  for (const child of entities) {
-    const parentField = parentLink(child, entity, roles);
-    if (parentField === void 0) continue;
-    const setField = fieldsWithRole(child, roles, "expected_set")[0];
-    if (setField !== void 0) {
-      sets.push({ kind: "expected_set", source: "child", child, parentField, setField, filesField: fileFields(child, roles)[0] });
-      continue;
+  const drawn = /* @__PURE__ */ new Set();
+  for (const via of RECORD_CHILD_VIA) {
+    for (const child of entities) {
+      if (drawn.has(child.alias)) continue;
+      const link = childLink(child, entity, roles, via);
+      if (link === void 0) continue;
+      drawn.add(child.alias);
+      const setField = fieldsWithRole(child, roles, "expected_set").find(
+        (field) => field.type === "select" && field.multi !== true
+      );
+      if (setField !== void 0) {
+        sets.push({ kind: "expected_set", source: "child", child, via, link, setField, filesField: fileFields(child, roles)[0] });
+        continue;
+      }
+      const byRole = CHILD_COLUMN_ROLES.flatMap((role) => fieldsWithRole(child, roles, role)).filter(
+        (field) => field.alias !== link.alias
+      );
+      children.push({ kind: "children", child, via, link, fields: byRole });
     }
-    const byRole = CHILD_COLUMN_ROLES.flatMap((role) => fieldsWithRole(child, roles, role));
-    children.push({ kind: "children", child, parentField, fields: byRole });
   }
   return [
     ...shown.length > 0 ? [{ kind: "facts", fields: shown, levels }] : [],
@@ -36674,7 +36715,7 @@ function resultSideEffects(result) {
 }
 
 // src/version.ts
-var VERSION = "0.195.0";
+var VERSION = "0.197.0";
 
 // src/timezone.ts
 function machineTimezone() {
@@ -37103,8 +37144,15 @@ var COMMANDS = [
     help: [
       "  lotics workspace                     List workspaces in the active org (marks current)",
       "  lotics workspace select <id>         Switch to a different workspace",
-      "  lotics workspace create <name>       Create a new workspace (admin only)",
-      "  lotics workspace rename <name>       Rename the current workspace (admin only)",
+      "  lotics workspace create <name> [--timezone <Area/City>] [--currency <ISO>]",
+      "                                       Create a new workspace (admin only). Without them it",
+      "                                       takes the org's oldest workspace's zone and currency \u2014",
+      "                                       which decide how every date buckets and every money",
+      "                                       field renders, and are invisible once wrong",
+      "  lotics workspace settings [--name <n>] [--currency <ISO>] [--timezone <Area/City>]",
+      "                                       Change the current workspace's name, currency or zone",
+      "                                       (admin only). Only what you name changes",
+      "  lotics workspace rename <name>       Rename the current workspace \u2014 settings, by name alone",
       "  lotics workspace delete <id> --yes   Delete a workspace (admin only; soft delete, recoverable)",
       "  lotics workspace doctor              Report dangling schema references (admin only)"
     ]
@@ -37184,7 +37232,9 @@ var COMMANDS = [
     help: [
       "  lotics run <tool> '<json>'           Execute a tool",
       "  lotics run <tool> @args.json         Read JSON args from a file (large payloads)",
-      "  cat args.json | lotics run <tool>    Read JSON args from stdin (large payloads)",
+      "  cat args.json | lotics run <tool> -  Read JSON args from stdin (large payloads).",
+      "                                       The trailing - is required: without it the tool",
+      "                                       runs with no arguments and never waits.",
       "                                       Exits non-zero when the RESULT reports the work",
       "                                       failed (a refused workflow, a failed agent run) \u2014",
       "                                       not only when the call did.",
@@ -37205,9 +37255,14 @@ var COMMANDS = [
       "                                       (-m is required \u2014 it's the version's audit trail;",
       "                                       carries code + queries only \u2014 workflow bindings are",
       "                                       managed by set_app_workflow / remove_app_workflow.",
-      "                                       --prune also UNBINDS aliases this bundle no longer",
-      "                                       names; off by default because `run_app_workflow` and",
-      "                                       chat reach a binding the bundle never calls)",
+      "                                       --prune also UNBINDS what this project retired \u2014 an",
+      "                                       alias this bundle stopped calling, and one whose",
+      "                                       declaration you deleted; off by default because",
+      "                                       `run_app_workflow` and chat reach a binding the",
+      "                                       bundle never calls.",
+      "                                       --prune-invoked <alias> unbinds a workflow the",
+      "                                       workspace has already RUN \u2014 named per alias, only",
+      "                                       when you know that caller is gone)",
       "  lotics app versions [app_id]         Show deploy history newest-first (version,",
       "                                       timestamp, deployer, build status, -m message;",
       "                                       * marks the currently served version)",
@@ -37239,8 +37294,13 @@ var COMMANDS = [
       "  lotics app workflow set <alias>      Push the edited src/workflows/<alias>.ts body",
       "                                       through set_app_workflow (server verifies)",
       "  lotics app workflow pull             Rewrite src/workflows/*.ts from the server",
-      "  lotics app workflow check [alias]    Typecheck src/workflows bodies locally (one",
-      "                                       isolated program per alias; the app's own tsc)",
+      "  lotics app workflow check [alias...] Typecheck src/workflows bodies locally (one",
+      "                                       isolated program per alias; the app's own tsc).",
+      "                                       Name several to check several; none checks all",
+      "  lotics app workflow diff [alias...]  Show how src/workflows/<alias>.ts differs from",
+      "                                       the body the server is running, line by line.",
+      "                                       None named diffs every alias that reads as",
+      "                                       drifted. Exits 1 when anything differs",
       "  lotics app query set <alias>         Push package.json#lotics.queries.<alias> to",
       "                                       apps.queries via set_app_query and regenerate",
       "                                       .lotics/app_queries.d.ts (no deploy; re-synced by",
@@ -37252,7 +37312,12 @@ var COMMANDS = [
       "                                       those with set_app_agent, then pull.",
       "  lotics app subdomain <new-subdomain> Rename the app's public address (its subdomain)",
       `  lotics app rename "<new name>"       Rename the app's display name (launcher title)`,
-      "  lotics app dev [path]                Run the app locally with HMR (RPC forwarded to prod)"
+      "  lotics app dev [path] [--port=<n>] [--vite-port=<n>]",
+      "                                       Run the app locally with HMR (RPC forwarded to prod).",
+      "                                       --port is the wrapper you open, --vite-port the module",
+      "                                       server. Pin both to run several apps at once; with no",
+      "                                       --vite-port, vite.config's server.port is used",
+      "  lotics app dev --view-as <member_id> \u2026 as that member sees it (admin only, reads only)"
     ]
   },
   {
@@ -37284,6 +37349,13 @@ var COMMANDS = [
     verbs: ["file"],
     aliases: ["upload", "download", "preview"],
     help: [
+      "  lotics file list [--limit <n>] [--cursor <token>]",
+      "                                       List this workspace's files newest-first \u2014",
+      "                                       id, date, bytes, type, name. One page; the last",
+      "                                       line prints the command for the next one",
+      "  lotics file delete <file_id>         Archive a stored file. Refused while a record,",
+      "                                       comment, knowledge doc, document template or",
+      "                                       voice session still references it \u2014 it names them",
       "  lotics file upload <file|dir...>     Upload files (alias: lotics upload)",
       "  lotics file upload --stdin --as <name>",
       "                                       Upload bytes you already hold, piped on stdin",
@@ -37305,9 +37377,33 @@ var COMMANDS = [
 function renderCommandsHelp() {
   return COMMANDS.flatMap((group) => group.help).join("\n");
 }
+function helpEntries(help) {
+  const entries2 = [];
+  for (const line of help) {
+    if (line.startsWith("  lotics ") || entries2.length === 0) entries2.push([line]);
+    else entries2[entries2.length - 1].push(line);
+  }
+  return entries2;
+}
+function commandHelp(path15) {
+  const words = path15.filter((word) => word !== "");
+  if (words.length === 0) return null;
+  const group = COMMANDS.find(
+    (g) => g.verbs.includes(words[0]) || (g.aliases ?? []).includes(words[0])
+  );
+  if (!group) return null;
+  if (words.length === 1) return group.help.join("\n");
+  const prefix = `  lotics ${words.join(" ")}`;
+  const matched = helpEntries(group.help).filter((entry) => entry[0].startsWith(prefix));
+  return (matched.length > 0 ? matched.flat() : group.help).join("\n");
+}
 function knownVerbs() {
   return new Set(COMMANDS.flatMap((group) => [...group.verbs, ...group.aliases ?? []]));
 }
+function commandAliases(verb) {
+  const group = COMMANDS.find((g) => g.verbs.includes(verb));
+  return new Set(group?.aliases ?? []);
+}
 
 // src/inputs.ts
 function shellQuotingHint(raw, source) {
@@ -37326,7 +37422,10 @@ function readStdin() {
 async function ingestJsonArgs(opts) {
   let raw = opts.rawArg;
   let source = "inline";
-  if (raw && raw.startsWith("@")) {
+  if (raw === "-") {
+    source = "stdin";
+    raw = await opts.readStdin();
+  } else if (raw && raw.startsWith("@")) {
     source = "file";
     const argsPath = raw.slice(1);
     try {
@@ -37337,9 +37436,6 @@ async function ingestJsonArgs(opts) {
         message: `Cannot read args file "${argsPath}": ${err instanceof Error ? err.message : String(err)}`
       };
     }
-  } else if (!raw && !opts.stdinIsTTY) {
-    source = "stdin";
-    raw = await opts.readStdin();
   }
   if (!raw) return { kind: "ok", args: {} };
   try {
@@ -38511,6 +38607,13 @@ function queryOutputNames(node) {
 }
 
 // ../shared/src/app_dts.ts
+function selectOptionValues(decl, optionsByFieldKey) {
+  const inline = Array.isArray(decl.options) ? decl.options : null;
+  const source = inline ?? (typeof decl.field === "string" ? optionsByFieldKey?.get(decl.field) : void 0) ?? [];
+  return [...source].map(
+    (o) => o !== null && typeof o === "object" && "value" in o && typeof o.value === "string" ? o.value : null
+  ).filter((v) => v !== null);
+}
 var IDENTIFIER_REGEX = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/;
 function isValidIdentifier(name) {
   return IDENTIFIER_REGEX.test(name);
@@ -38521,7 +38624,7 @@ function inputsToType(inputs, opts) {
   for (const [key, decl] of Object.entries(inputs)) {
     if (decl === null || typeof decl !== "object") continue;
     const d = decl;
-    const tsType = inputDeclToTsType(d);
+    const tsType = inputDeclToTsType(d, opts?.optionsByFieldKey);
     const isOptional = d.required === false;
     const fieldType = isOptional && nullableOptional ? `${tsType} | null` : tsType;
     const optional2 = isOptional ? "?" : "";
@@ -38533,7 +38636,7 @@ function inputsToType(inputs, opts) {
 ${fields.join("\n")}
     }`;
 }
-function inputDeclToTsType(decl) {
+function inputDeclToTsType(decl, optionsByFieldKey) {
   const type = decl.type;
   switch (type) {
     case "text":
@@ -38551,13 +38654,7 @@ function inputDeclToTsType(decl) {
       return decl.multi === true ? `ReadonlyArray<${inner}>` : inner;
     }
     case "select": {
-      const options = Array.isArray(decl.options) ? decl.options : [];
-      const literals = options.map((o) => {
-        if (o !== null && typeof o === "object" && "value" in o && typeof o.value === "string") {
-          return JSON.stringify(o.value);
-        }
-        return null;
-      }).filter((v) => v !== null);
+      const literals = selectOptionValues(decl, optionsByFieldKey).map((v) => JSON.stringify(v));
       const inner = literals.length > 0 ? `${literals.join(" | ")} | (string & {})` : "string";
       return decl.multi === true ? `ReadonlyArray<${inner}>` : inner;
     }
@@ -38567,11 +38664,11 @@ function inputDeclToTsType(decl) {
       return decl.multi === true ? "ReadonlyArray<string>" : "string";
     case "object": {
       const fields = decl.fields !== null && typeof decl.fields === "object" ? decl.fields : {};
-      return inputsToType(fields);
+      return inputsToType(fields, { optionsByFieldKey });
     }
     case "array": {
       const items = decl.items !== null && typeof decl.items === "object" ? decl.items : null;
-      return items ? `ReadonlyArray<${inputDeclToTsType(items)}>` : "ReadonlyArray<unknown>";
+      return items ? `ReadonlyArray<${inputDeclToTsType(items, optionsByFieldKey)}>` : "ReadonlyArray<unknown>";
     }
     case "json":
       return "unknown";
@@ -38579,19 +38676,20 @@ function inputDeclToTsType(decl) {
       return "unknown";
   }
 }
-function objectFieldsToType(fields) {
+function objectFieldsToType(fields, optionsByFieldKey) {
   const parts = [];
   for (const [key, decl] of Object.entries(fields)) {
     if (decl === null || typeof decl !== "object") continue;
     const d = decl;
-    const optional2 = d.required === false ? "?" : "";
+    const isOptional = d.required === false;
+    const tsType = outputDeclToTsType(d, optionsByFieldKey);
     const fieldKey = isValidIdentifier(key) ? key : JSON.stringify(key);
-    parts.push(`${fieldKey}${optional2}: ${outputDeclToTsType(d)}`);
+    parts.push(`${fieldKey}${isOptional ? "?" : ""}: ${isOptional ? `${tsType} | null` : tsType}`);
   }
   if (parts.length === 0) return "Record<string, never>";
   return `{ ${parts.join("; ")} }`;
 }
-function outputDeclToTsType(decl) {
+function outputDeclToTsType(decl, optionsByFieldKey) {
   const type = decl.type;
   switch (type) {
     case "text":
@@ -38606,20 +38704,17 @@ function outputDeclToTsType(decl) {
     case "record_link":
       return decl.multi === true ? "ReadonlyArray<string>" : "string";
     case "select": {
-      const options = Array.isArray(decl.options) ? decl.options : [];
-      const literals = options.map(
-        (o) => o !== null && typeof o === "object" && "value" in o && typeof o.value === "string" ? JSON.stringify(o.value) : null
-      ).filter((v) => v !== null);
+      const literals = selectOptionValues(decl, optionsByFieldKey).map((v) => JSON.stringify(v));
       const inner = literals.length > 0 ? `${literals.join(" | ")} | (string & {})` : "string";
       return decl.multi === true ? `ReadonlyArray<${inner}>` : inner;
     }
     case "object": {
       const fields = decl.fields !== null && typeof decl.fields === "object" ? decl.fields : {};
-      return objectFieldsToType(fields);
+      return objectFieldsToType(fields, optionsByFieldKey);
     }
     case "array": {
       const items = decl.items !== null && typeof decl.items === "object" ? decl.items : null;
-      return items ? `ReadonlyArray<${outputDeclToTsType(items)}>` : "ReadonlyArray<unknown>";
+      return items ? `ReadonlyArray<${outputDeclToTsType(items, optionsByFieldKey)}>` : "ReadonlyArray<unknown>";
     }
     case "json":
       return "unknown";
@@ -38635,7 +38730,7 @@ var QUERIES_HEADER = `// Auto-generated by 'lotics app pull/dev/deploy'.
 
 import "@lotics/app-sdk";
 `;
-function generateAppQueriesDts(queries) {
+function generateAppQueriesDts(queries, optionsByFieldKey) {
   const entries2 = Object.entries(queries ?? {});
   if (entries2.length === 0) {
     return `${QUERIES_HEADER}
@@ -38650,7 +38745,7 @@ declare module "@lotics/app-sdk" {
   const lines = [];
   const columnLines = [];
   for (const [alias, declaration] of entries2) {
-    const valueType = inputsToType(declaration.params ?? {});
+    const valueType = inputsToType(declaration.params ?? {}, { optionsByFieldKey });
     const aliasKey = isValidIdentifier(alias) ? alias : JSON.stringify(alias);
     lines.push(`    ${aliasKey}: ${valueType};`);
     const parsed = declaration.ast === void 0 ? void 0 : queryNodeSchema.safeParse(declaration.ast);
@@ -38682,7 +38777,7 @@ var WORKFLOWS_HEADER = `// Auto-generated by 'lotics app pull/dev/deploy'.
 
 import "@lotics/app-sdk";
 `;
-function generateAppWorkflowsDts(workflows) {
+function generateAppWorkflowsDts(workflows, optionsByFieldKey) {
   const entries2 = Object.entries(workflows ?? {});
   if (entries2.length === 0) {
     return `${WORKFLOWS_HEADER}
@@ -38697,11 +38792,13 @@ declare module "@lotics/app-sdk" {
   const inputLines = [];
   const resultLines = [];
   for (const [alias, declaration] of entries2) {
-    const valueType = declaration.inputs ? inputsToType(declaration.inputs, { nullableOptional: true }) : "Record<string, unknown>";
+    const valueType = declaration.inputs ? inputsToType(declaration.inputs, { nullableOptional: true, optionsByFieldKey }) : "Record<string, unknown>";
     const aliasKey = isValidIdentifier(alias) ? alias : JSON.stringify(alias);
     inputLines.push(`    ${aliasKey}: ${valueType};`);
     if (declaration.outputs) {
-      resultLines.push(`    ${aliasKey}: ${objectFieldsToType(declaration.outputs)};`);
+      resultLines.push(
+        `    ${aliasKey}: ${objectFieldsToType(declaration.outputs, optionsByFieldKey)};`
+      );
     }
   }
   const resultsBlock = resultLines.length > 0 ? `
@@ -38724,7 +38821,7 @@ var AGENTS_HEADER = `// Auto-generated by 'lotics app pull/dev/deploy'.
 
 import "@lotics/app-sdk";
 `;
-function generateAppAgentsDts(agents) {
+function generateAppAgentsDts(agents, optionsByFieldKey) {
   const entries2 = Object.entries(agents ?? {});
   if (entries2.length === 0) {
     return `${AGENTS_HEADER}
@@ -38739,11 +38836,13 @@ declare module "@lotics/app-sdk" {
   const inputLines = [];
   const resultLines = [];
   for (const [alias, declaration] of entries2) {
-    const valueType = declaration.inputs ? inputsToType(declaration.inputs) : "Record<string, unknown>";
+    const valueType = declaration.inputs ? inputsToType(declaration.inputs, { optionsByFieldKey }) : "Record<string, unknown>";
     const aliasKey = isValidIdentifier(alias) ? alias : JSON.stringify(alias);
     inputLines.push(`    ${aliasKey}: ${valueType};`);
     if (declaration.outputs) {
-      resultLines.push(`    ${aliasKey}: ${objectFieldsToType(declaration.outputs)};`);
+      resultLines.push(
+        `    ${aliasKey}: ${objectFieldsToType(declaration.outputs, optionsByFieldKey)};`
+      );
     }
   }
   const resultsBlock = resultLines.length > 0 ? `
@@ -39064,6 +39163,20 @@ export type AppFields = typeof F;
 export type AppOptions = typeof OPT;
 `;
 }
+function selectOptionsByFieldKey(tables) {
+  const byKey = /* @__PURE__ */ new Map();
+  for (const table of tables) {
+    for (const field of table.fields) {
+      if (field.options && field.options.length > 0) {
+        byKey.set(
+          field.id,
+          field.options.map((option) => ({ value: option.id }))
+        );
+      }
+    }
+  }
+  return byKey;
+}
 function codegenTableIds(queries, allowlist) {
   const ids = new Set(allowlist);
   for (const declaration of Object.values(queries)) {
@@ -39153,11 +39266,11 @@ function bindScreens(screens, live, roles, entities) {
     if (own === void 0) continue;
     const sections = recordSections(screen.entity, entities, roles, recordHeader(screen));
     const children = /* @__PURE__ */ new Map();
-    const bindChild = (section, child, parentField, drawn, set2, files) => {
-      const found = bindTable(`${at2}.${child.alias}`, child, [parentField, ...drawn], aliased, live, missing);
+    const bindChild = (section, child, via, linkField, drawn, set2, files) => {
+      const found = bindTable(`${at2}.${child.alias}`, child, [linkField, ...drawn], aliased, live, missing);
       if (found === void 0) return;
-      const parent = found.fields.get(parentField.alias);
-      if (parent === void 0) return;
+      const link = found.fields.get(linkField.alias);
+      if (link === void 0) return;
       const drawnRoles = /* @__PURE__ */ new Map();
       const fields = /* @__PURE__ */ new Map();
       for (const field of drawn) {
@@ -39169,6 +39282,7 @@ function bindScreens(screens, live, roles, entities) {
       }
       children.set(child.alias, {
         section,
+        via,
         // Keyed by the ENTITY, not the screen: two screens over one entity read
         // the same rows through the same filter, and a second alias for them is
         // a second manifest entry, a second `.d.ts` entry and a second cache key
@@ -39178,7 +39292,7 @@ function bindScreens(screens, live, roles, entities) {
         entity: child,
         table: found.table,
         tableAlias: found.tableAlias,
-        parent,
+        link,
         fields,
         roles: drawnRoles,
         identity: child.fields.find((field) => roleOf(roles, child.alias, field.alias)?.role === "identity")?.alias,
@@ -39192,7 +39306,7 @@ function bindScreens(screens, live, roles, entities) {
           const role = roleOf(roles, section.child.alias, field.alias)?.role;
           return role !== void 0 && DRAWN_ROLES.includes(role);
         });
-        bindChild("children", section.child, section.parentField, drawn);
+        bindChild("children", section.child, section.via, section.link, drawn);
         continue;
       }
       if (section.kind !== "expected_set" || section.source !== "child") continue;
@@ -39200,7 +39314,8 @@ function bindScreens(screens, live, roles, entities) {
       bindChild(
         "expected_set",
         section.child,
-        section.parentField,
+        section.via,
+        section.link,
         [...name, section.setField, ...section.filesField === void 0 ? [] : [section.filesField]],
         section.setField,
         section.filesField
@@ -39246,7 +39361,7 @@ function planQueries(bound) {
             filter: {
               node_type: "condition",
               type: "select_record_link",
-              field_key: child.parent.id,
+              field_key: child.link.id,
               operator: "has_any_of",
               value: [`{{params.${child.param}}}`]
             }
@@ -39254,7 +39369,7 @@ function planQueries(bound) {
           columns: [...child.fields.values()].map((field) => field.id)
         },
         params: { [child.param]: { type: "record_link", table_id: entry.table.id } },
-        description: `${child.entity.label} \u2014 the rows under one ${entry.screen.entity.label}`
+        description: `${child.entity.label} \u2014 the rows ${child.via === "party" ? "naming" : "under"} one ${entry.screen.entity.label}`
       };
     }
   }
@@ -39568,8 +39683,12 @@ function roleColumn(spec) {
     // the same value reads "—" in the facts beside it.
     case "measure":
       return `${head}, width: 96, align: "right", cell: (${bind}) => { const level = amount(${ref}); return level === null ? null : <NumberCell value={level} />; } }`;
+    // ONE VALUE, ONE READING: the currency is the FIELD's, so a total reads the
+    // same money in the band, in this column and in the facts behind it. Stated
+    // nowhere, the cell falls back to the reader's locale, which is the only
+    // answer a field that names no currency has.
     case "amount":
-      return `${head}, width: 128, align: "right", cell: (${bind}) => { const sum = amount(${ref}); return sum === null ? null : <MoneyCell value={sum} />; } }`;
+      return `${head}, width: 128, align: "right", cell: (${bind}) => { const sum = amount(${ref}); return sum === null ? null : <MoneyCell value={sum}${spec.currency === void 0 ? "" : ` currency=${str(spec.currency)}`} />; } }`;
     case "lifecycle":
       return `${head}, width: 120, cell: (${bind}) => { const held = stageOf(${options}, ${ref}); return held === null ? null : <StageCell stage={held} />; } }`;
     case "verdict":
@@ -39582,11 +39701,13 @@ function childColumn(child, alias) {
   const field = child.fields.get(alias);
   const role = child.roles.get(alias);
   if (field === void 0 || role === void 0) return null;
+  const declared = child.entity.fields.find((candidate) => candidate.alias === alias);
   return roleColumn({
     role,
     key: field.alias,
     label: field.label,
     type: field.type,
+    currency: declared === void 0 ? void 0 : currencyOf(declared),
     bind: "child",
     ref: `child[F.${child.tableAlias}.${field.alias}]`,
     options: `${camel(child.alias)}Fields[F.${child.tableAlias}.${field.alias}]`
@@ -39906,6 +40027,7 @@ ${pageBody}
           key: field.alias,
           label: field.label,
           type: field.type,
+          currency: currencyOf(slot2.field),
           bind: "r",
           ref: `r[T.${field.alias}]`,
           options: `fields[T.${field.alias}]`
@@ -40618,7 +40740,7 @@ Captured ${totalRows} row${totalRows === 1 ? "" : "s"} across ${result.captured.
 }
 
 // src/model_reference.md
-var model_reference_default = '# The Lotics workspace model (`model.json`)\n\nOne JSON file describing the tables, fields, options, views, roles and first rows\na workspace starts with. `lotics scaffold check model.json` proves it offline \u2014\nno account, no network. `lotics setup model.json --email you@company.com` creates\nthe account and applies it. `lotics scaffold apply model.json` applies it again,\ninto the workspace the credential names.\n\n**There are two forms of this file.** The full one, below, spells the model out.\nThe `from` one names a published preset and carries only what this business\ndiffers by \u2014 see \xA7 Starting from a preset, and prefer it whenever a preset fits\nthe trade.\n\nApps are PLANNED here and built afterwards: `apps` names each app\'s screens as a\nshape over an entity, checked against the roles `field_roles` gives its fields,\nso the plan is refused before anyone builds a screen (\xA7 Apps and screens). The\nbuilt app lives in the workspace; publishing that workspace as a package is how\nit ships.\n\n## The rules\n\n- **At least one entity, at most 50.** More tables than that is a data model\n  being designed, not scaffolded \u2014 scaffold the rest in a second call.\n- **Adoption is explicit.** `lotics setup` REFUSES an entity whose `label`\n  already names a table in the workspace, naming every colliding label at once.\n  `lotics scaffold apply` adopts those tables and adds the fields, options and\n  views they are missing. Nothing is ever modified or deleted, so applying the\n  same model twice creates nothing the second time.\n- **Adoption is by LABEL, not alias.** Change an entity\'s `label` and the next\n  run asks for a NEW table beside the old one. Renames and deletions go through\n  `lotics run update_table` / `lotics run delete_table`, never through the file.\n- **Rows land only where every bound table is empty.** One table already holding\n  records and no rows are written anywhere, and the result says\n  `rows_skipped: true`: sample rows landing among a customer\'s real ones cannot\n  be told apart from them.\n- **After the first run the WORKSPACE is the source of truth.** The file is an\n  authoring input, not a mirror \u2014 scaffold never deletes what the file stopped\n  naming.\n- **`lotics scaffold check` decides all of it offline**, and reports every\n  problem in one run rather than the first: an alias that resolves to nothing, a\n  link whose pair is not symmetric, and the rows themselves \u2014 a field the entity\n  does not declare, an option alias the field does not declare, a link naming no\n  row in the file, a `ref` used twice, a date that is not one, a value on a\n  platform-computed field, and a files cell that is neither a relative path\n  beside this file nor a `fil_` id.\n\n## Top level\n\n```jsonc\n{\n  "entities": [ /* the tables */ ],\n  "roles":    [ /* workspace groups to create */ ],    // optional\n  "templates":[ /* inline html / email templates */ ], // optional\n  "rows":     { /* first records, keyed by entity alias */ },  // optional\n  "field_roles": { /* the reporting role each field plays, keyed by entity then field */ }, // optional\n  "apps":     [ /* the screens each app will have, as shapes over entities */ ], // optional\n  "apply":    [ /* published packages to copy in afterwards */ ], // optional\n  "preset":   { /* a trade\'s branches, for a PUBLISHED model */ } // optional\n}\n```\n\nThe other form names a preset instead of restating one:\n\n```jsonc\n{\n  "from":     "field_service",             // the preset this model starts from, by slug\n  "variants": ["crews"],                   // optional \u2014 its branches to merge in, in order\n  "rename":   {                            // optional \u2014 what THIS business calls each table\n    "job": { "label": "\u0110\u01A1n h\xE0ng", "fields": { "code": "M\xE3 \u0111\u01A1n" } }\n  },\n  "entities": [ /* tables the preset does not declare */ ],    // optional\n  "rows":     { /* first records, keyed by entity alias */ },  // optional\n  "field_roles": { /* roles on the preset\'s fields and this business\'s own */ }, // optional\n  "apps":     [ /* the screens each app will have */ ],        // optional\n  "apply":    [ /* published packages to copy in afterwards */ ] // optional\n}\n```\n\n**A model may not carry** `fixtures`, `knowledge` or `knowledge_expects`, and no\n`excel` / `word` / `pdf-form` template: each of those is content that lives in a\npublished bundle, which a model has none of. `apps` here is a plan of screens,\nnever built code. An unknown top-level key is an error, never ignored.\n\n### Aliases\n\nEvery `alias` is a lowercase slug \u2014 a letter, then letters, digits and\nunderscores (`unit_price`, `so_1001`). Aliases are how the file cross-references\nitself; they are never shown to anyone. `label` is what a person sees.\n\nLabels must be unique within their namespace \u2014 two entities, two fields on one\nentity, two options on one field, two views on one entity, two roles or two\ntemplates cannot share a label, because scaffold matches by label.\n\n## Entity\n\n```jsonc\n{\n  "alias": "order",\n  "label": "Orders",            // the table\'s name\n  "description": "\u2026",           // optional\n  "fields": [ /* at least one */ ],\n  "views":  [ /* optional; an entity with none still gets the default grid */ ]\n}\n```\n\n## Field\n\nEvery field carries `alias`, `label`, an optional `description`, and an optional\n`required` \u2014 advisory only, read by app forms and workflows; the table itself has\nno required constraint. `label` may not contain `{` or `}` (formulas reference\nfields by label at the platform level).\n\n`default` is the value pre-filled into a NEW record. It applies on create only;\nexisting records are never backfilled. Only the types listed below accept one.\n\n### `text`\n\n```jsonc\n{ "alias": "name", "label": "Name", "type": "text",\n  "unique": false,              // optional \u2014 require distinct values\n  "format": "text",             // optional \u2014 "text" | "link" | "markdown"\n  "default": "" }               // optional\n```\n\n### `number`\n\n```jsonc\n{ "alias": "amount", "label": "Amount", "type": "number",\n  "format": "currency",         // optional \u2014 "number" | "currency" | "percentage"\n  "currency": "VND",            // optional \u2014 ISO 4217\n  "default": 0 }                // optional\n```\n\n### `date`\n\n```jsonc\n{ "alias": "placed_on", "label": "Placed on", "type": "date",\n  "format": "date",             // optional \u2014 "date" | "datetime" | "date_range" | "datetime_range"\n  "timezone": "Asia/Ho_Chi_Minh",  // optional \u2014 IANA name\n  "derive_from": "created_at",  // optional \u2014 "created_at" | "updated_at"; makes the field read-only\n  "default": "2026-01-01" }     // optional; refused together with derive_from\n```\n\n### `boolean`\n\n```jsonc\n{ "alias": "paid", "label": "Paid", "type": "boolean", "default": false }\n```\n\n### `select`\n\n```jsonc\n{ "alias": "tier", "label": "Tier", "type": "select",\n  "options": [                                     // at least one\n    { "alias": "standard", "label": "Standard", "color": "slate" },\n    { "alias": "gold",     "label": "Gold",     "color": "amber" }\n  ],\n  "multi": false,               // optional\n  "default": ["standard"] }     // optional \u2014 option ALIASES; one unless multi\n```\n\n`color` is one of: `red`, `orange`, `amber`, `yellow`, `lime`, `green`,\n`emerald`, `teal`, `cyan`, `sky`, `blue`, `indigo`, `violet`, `purple`,\n`fuchsia`, `pink`, `rose`, `slate`, `gray`, `zinc`, `neutral`, `stone`.\n\n### `select_member`\n\nA person picker over the workspace\'s members. No default: a model cannot name\nmembers of a workspace that does not exist yet.\n\n```jsonc\n{ "alias": "owner", "label": "Owner", "type": "select_member", "multi": false }\n```\n\n### `select_record_link`\n\n```jsonc\n{ "alias": "customer", "label": "Customer", "type": "select_record_link",\n  "target_entity": "customer",        // an entity alias this model declares\n  "cardinality": "one",               // optional \u2014 "one" | "many" (default "many")\n  "sync_both_ways": true,             // optional \u2014 keep a paired field on the target\n  "paired_field_alias": "orders",     // the partner field ON THE TARGET entity\n  "display_field_aliases": ["name"] } // optional \u2014 what the link shows / the picker\'s columns\n```\n\nA two-way link is declared on BOTH sides, each naming the other as its\n`paired_field_alias`; the pair must be symmetric or the model is refused. Declare\none side only (with no `paired_field_alias`) for a link with no back-reference.\n\n### `files`\n\n```jsonc\n{ "alias": "attachments", "label": "Attachments", "type": "files" }\n```\n\n### `formula`\n\n```jsonc\n{ "alias": "total", "label": "Total", "type": "formula",\n  "formula": {\n    "expression": "{amount} * 1.1",  // fields on THIS entity, by alias, in braces\n    "format": "currency",            // optional \u2014 "number" | "currency" | "percentage" | "link"\n    "currency": "VND"                // optional\n  } }\n```\n\n### `rollup`\n\nAggregates the records reached through a link on this entity.\n\n```jsonc\n{ "alias": "total_ordered", "label": "Total ordered", "type": "rollup",\n  "source_field_alias": "orders",    // a select_record_link field on THIS entity\n  "aggregate_option": {\n    "operation": "sum",              // count | sum | avg | median | min | max | range |\n                                     // empty | filled | percent_empty | percent_filled |\n                                     // unique | percent_unique |\n                                     // earliest | latest | date_range |\n                                     // checked | unchecked | percent_checked |\n                                     // percent_unchecked\n    "field_key": "amount"            // a field ALIAS on the linked entity ("count" may omit it)\n  },\n  "filter": { /* optional \u2014 see Views; every field_key is an alias on the LINKED entity */ } }\n```\n\nThe operation must be one the aggregated field\'s type allows \u2014 `sum` over a\nnumber, `earliest` over a date, `filled` over anything.\n\n### `lookup`\n\nDisplays a field from the linked records.\n\n```jsonc\n{ "alias": "customer_tier", "label": "Customer tier", "type": "lookup",\n  "source_field_alias": "customer",  // a select_record_link field on THIS entity\n  "lookup_field_alias": "tier",      // a field alias on the linked entity\n  "order_by": { "field_key": "placed_on", "direction": "desc" } }  // optional \u2014 pick the single extreme row\n```\n\n### `autonumber`\n\n```jsonc\n{ "alias": "seq", "label": "No.", "type": "autonumber",\n  "prefix": "SO-",     // optional \u2014 ignored when template is set\n  "padding": 4,        // optional \u2014 1..20, zero-pads the integer\n  "template": "SO-{YEAR}-{N:4}" }  // optional \u2014 {N}, {N:W}, {YEAR}, {YEAR:2}, {MONTH}, {DAY}\n```\n\n## Views\n\nSaved views live under the entity they belong to. Every field reference is a\nfield ALIAS on that entity.\n\n```jsonc\n{\n  "alias": "gold",\n  "label": "Gold customers",\n  "description": "\u2026",                       // optional\n  "columns": [                              // optional \u2014 omit to show every field\n    { "field_alias": "name", "visibility": "visible", "width": 240 },\n    { "field_alias": "tier", "visibility": "hidden" }\n  ],\n  "filters": {                              // optional\n    "node_type": "group",\n    "logic": "and",                         // "and" | "or"\n    "children": [\n      { "node_type": "condition", "type": "select", "field_key": "tier",\n        "operator": "has_any_of", "value": ["gold"] }\n    ]\n  },\n  "sort": [ { "field_key": "name", "order": "asc" } ],  // optional; order is "asc" | "desc" | null\n  "summary": { "amount": "sum" },           // optional \u2014 field alias \u2192 footer operation\n  "frozen_columns": 1                       // optional\n}\n```\n\nA condition\'s `type` is the field\'s type and its `operator` is one that type\nadmits \u2014 `has_any_of` / `has_none_of` / `has_all_of` / `is_empty` /\n`is_not_empty` for a select, `equals` / `greater_than` / `less_than` for a\nnumber, `on` / `before` / `after` / `between` for a date, `contains` /\n`is_any_of` for text. A select condition\'s `value` names option ALIASES.\n\n`columns`, when present, is exhaustive and must not be empty: a view renders\nexactly the entries it holds. Omit the key to show every field.\n\n## Roles\n\nA role becomes a workspace group. Members are added afterwards, in the app.\n\n```jsonc\n{ "alias": "sales", "label": "Sales" }\n```\n\n## Templates\n\nOnly inline `html` and `email` templates \u2014 the rest are file-backed and a model\nhas no bytes. An `html` template renders to a PDF when a workflow generates\nfrom it; `{{name}}` is filled from the workflow\'s data.\n\n```jsonc\n{ "alias": "order_ack", "label": "Order acknowledgement", "type": "email",\n  "content": "<p>Hello {{customer}}\u2026</p>" }\n```\n\nA paper that has to look like a counterparty produced it \u2014 an official letter,\nan acceptance minute, a supplier\'s bill \u2014 is the same `html` template with a\nshell around the body: a letterhead, a reference line, a seal and a signature\nblock, and paper grain over everything. One shell, many bodies; the data is the\nonly thing that changes, so a workflow can re-issue it over any record.\n\n```jsonc\n{ "alias": "cong_van", "label": "C\xF4ng v\u0103n", "type": "html",\n  "content": "\u2026the page below, as one JSON string\u2026" }\n```\n\n```html\n<style>\n    .sheet{position:relative;width:718px;padding:44px 58px 30px;background:#fbfaf6;color:#111;font:14.2px/1.5 \'Liberation Serif\',serif}\n    .grain{position:absolute;inset:0;opacity:.34;mix-blend-mode:multiply;background:url("data:image/svg+xml;utf8,<svg xmlns=\'http://www.w3.org/2000/svg\' width=\'140\' height=\'140\'><filter id=\'f\'><feTurbulence baseFrequency=\'.9\' numOctaves=\'2\'/><feColorMatrix values=\'0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 .35 0\'/></filter><rect width=\'140\' height=\'140\' filter=\'url(%23f)\'/></svg>")}\n    .top{display:flex;text-align:center;font-size:13.4px} .top>div{flex:1} .u{display:inline-block;border-bottom:1px solid #111;font-weight:700}\n    .ref{display:flex;text-align:center;font-size:13.4px;margin-top:6px} .ref>div{flex:1} .ref .r{font-style:italic}\n    h1{text-align:center;font-size:15.6px;margin:26px 0 18px} p{text-align:justify;text-indent:26px;margin:0 0 9px}\n    .sig{display:flex;margin-top:20px} .sig .l{flex:1} .sig .r{width:290px;text-align:center;position:relative}\n    .sig .nm{font-weight:700;margin-top:96px} .seal{position:absolute;left:4px;top:8px;width:166px;height:166px;opacity:.66;mix-blend-mode:multiply;transform:rotate(-17deg)}\n  </style>\n  <div class=\'sheet\'><div class=\'grain\'></div>\n    <div class=\'top\'><div><b>{{issuer_parent}}</b><br><span class=\'u\'>{{issuer}}</span></div>\n      <div><b>C\u1ED8NG H\xD2A X\xC3 H\u1ED8I CH\u1EE6 NGH\u0128A VI\u1EC6T NAM</b><br><span class=\'u\'>\u0110\u1ED9c l\u1EADp - T\u1EF1 do - H\u1EA1nh ph\xFAc</span></div></div>\n    <div class=\'ref\'><div>S\u1ED1: {{number}}</div><div class=\'r\'>{{place}}, ng\xE0y {{day}} th\xE1ng {{month}} n\u0103m {{year}}</div></div>\n    <h1>{{title}}</h1>\n    <p>K\xEDnh g\u1EEDi: {{recipient}}.</p>\n    {{{body}}}\n    <div class=\'sig\'><div class=\'l\'><b>N\u01A1i nh\u1EADn:</b><br>- Nh\u01B0 tr\xEAn;<br>- L\u01B0u VT.</div>\n      <div class=\'r\'><img class=\'seal\' src=\'{{seal_url}}\'><b>{{signer_title}}</b><div class=\'nm\'>{{signer}}</div></div></div>\n  </div>\n```\n\n`lotics preview <file.html>` renders any such page to a PNG the way a demo\'s\nprops are made, sized to its content, so a paper can be looked at before it is\nput in a template.\n\n## Rows\n\nFirst records, keyed by entity alias. Up to 200 rows per entity and 2000 across\nthe model, attaching at most 2000 documents between them \u2014 a real data set\nbelongs in an import, not a model.\n\n```jsonc\n"rows": {\n  "customer": [\n    { "ref": "acme", "fields": { "name": "Acme Trading", "tier": "gold" } }\n  ]\n}\n```\n\n`ref` is a local handle (lowercase letters, digits, underscores) that other rows\'\nlink fields address. It is never persisted.\n\nA `files` cell attaches documents: paths relative to this file (no `..`, never\nabsolute), which `check` proves exist and `apply` uploads into the workspace\nbefore any row is written \u2014 a paperwork business seeds its papers with its\nrows. The server accepts only `fil_` ids of files this workspace owns, which is\nwhat the upload leaves behind. After a run that wrote rows, `apply` writes the\nrecord ids beside the file (`<model>.last_run.json`): `delete_records` over\nthem is how a seeded set is reset, and applying again re-dates it.\n\n`fields` is keyed by field alias, and every value is read against the field\'s\nDECLARED type:\n\n| Field type | Value |\n|---|---|\n| `text` / `number` / `boolean` | the value itself |\n| `date` | `"2026-03-14"`, or a relative expression (below) |\n| `select` | the option ALIAS \u2014 `"gold"`, or `["gold","vip"]` for a multi-select |\n| `select_record_link` | `"<entity-alias>:<ref>"` naming another row in this file \u2014 `"customer:acme"`, or an array for several |\n| `select_member` | `"self"` only \u2014 the person applying the model |\n| `files` | paths beside this file \u2014 `["scans/pccc_letter.png"]` \u2014 uploaded by `apply`/`setup` before the rows are posted; or `fil_` ids of files already in this workspace |\n| `formula`, `rollup`, `lookup`, `autonumber` | not allowed \u2014 the platform writes these |\n\n### Relative dates\n\nA date cell holds a literal `YYYY-MM-DD`, or an expression relative to the day\nthe model is applied, so a screen that opens on "this month" is not empty a month\nlater:\n\n- `@today` \u2014 the day of the run, in the workspace\'s timezone\n- `@month-start` \u2014 the 1st of that month\n- either with a whole-day offset: `@today-14`, `@month-start+9`\n\n`@month-start` exists because `@today-N` cannot promise a month: applied on the\n2nd, `@today-3` lands in the previous one.\n\n## Field roles\n\n`field_roles` names the reporting role a field plays on its entity \u2014 keyed by\nentity alias, then field alias \u2014 so every screen over the entity agrees on\nwhich column names the row and which select is the stage. A shape\'s slot binds\nto it (\xA7 Apps and screens). Like `rows` and `apps`, it is this file\'s: `check`\nproves it and the workspace never sees it. Each role sits on the types that can\nanswer it:\n\n| Role | On | Meaning |\n|---|---|---|\n| `identity` | `text`, `autonumber`, `select_record_link` | names the row \u2014 the register\'s first column; a link where the row is "the product, at this branch". One per entity |\n| `mark` | `files` | the row\'s picture. One per entity |\n| `lifecycle` | single `select` | the ordered stages a row walks; option order is the order. One per entity |\n| `measure` | `number`, `formula`, `rollup` | a level read against a limit \u2014 see `against` and `alert` |\n| `expected_set` | `select` | its OPTIONS are the required set (documents, checks, services); an option no row has is a gap to show, not nothing |\n| `amount` | `number`, `formula`, `rollup` | THE signed money of a ledger row. One per entity |\n| `when` | `date` | the ledger or timeline date. One per entity |\n| `party` | `select_record_link` | the counterparty. One per entity |\n| `parent` | `select_record_link` | the record this row belongs to \u2014 a line\'s order, a paper\'s case. The parent\'s record shows these rows; the row shows the parent as a fact. One per entity, and it links to an entity this model declares |\n| `contact` | `text` | the one way to reach a party. One per entity |\n| `verdict` | `boolean`, `formula` | a settled pass/fail \u2014 ticked, or computed. One per entity |\n\nA bare role name is the common form. A `measure` takes the object form to name\nits limit: `against` \u2014 a `number` field on the same entity, by alias, or a\nconstant \u2014 and `alert`, which side of it needs attention, `over` a capacity or\n`under` a minimum. The two come together.\n\n```jsonc\n"field_roles": {\n  "product": { "name": "identity", "photo": "mark" },\n  "stock":   { "on_hand": { "role": "measure", "against": "minimum", "alert": "under" },\n               "uptime":  { "role": "measure", "against": 80, "alert": "under" } }\n}\n```\n\nIn a file that starts from a preset (\xA7 Starting from a preset), `field_roles`\nmay name the preset\'s fields as well as this business\'s own; a role the preset\ndeclares itself is kept unless this file names the same field, and `null`\nclears it.\n\n## Apps and screens\n\n`apps` is the plan: each app the reader will build, and each of its screens as\na SHAPE over an ENTITY. Nothing here is built by the scaffold \u2014 the plan is what\n`lotics scaffold check` prints back, screen by screen with the field in every\nslot, so it is read and corrected before a screen exists.\n\n```jsonc\n"apps": [\n  {\n    "alias": "sales", "name": "Sales",\n    "description": "\u2026", "icon": "briefcase", "theme": { "color": "blue" }, // optional\n    "screens": [\n      { "alias": "customers", "label": "Customers", "shape": "party_register", "entity": "customer" },\n      { "alias": "orders",    "label": "Orders",    "shape": "lifecycle_desk", "entity": "order",\n        "record": "drawer",                  // optional \u2014 "drawer" | "page"; absent, the shape decides\n        "tabs": "stage",                     // optional \u2014 a select on the entity, or null; absent, the shape decides\n        "slots": { "identity": "code" } }    // optional \u2014 slot \u2192 field, where the roles cannot decide alone\n    ]\n  }\n]\n```\n\nA shape is a proven screen with named SLOTS, each filled by a field carrying a\nrole (\xA7 Field roles). A slot with exactly one candidate on the entity binds by itself;\ntwo candidates need naming in `slots`; a field fills one slot; a required slot\nwith none is refused \u2014 a lifecycle desk over an entity with no `lifecycle`\nselect cannot be built.\n\n| Shape | Answers | Required | Also fills | Record | Tabs |\n|---|---|---|---|---|---|\n| `lifecycle_desk` | what is stuck, what do I move next | `lifecycle`, `identity` | `mark`, `party`, `amount`, `when` | drawer | the lifecycle\'s stages |\n| `party_register` | who is this, our history, is there a risk | `identity` | `mark`, `contact`, `measure` (worth), `verdict` (risk) | page | none |\n| `offering_register` | what do we offer, at what price, can I sell it | `identity` | `mark`, `amount` (price), `measure` (availability) | page | none |\n| `transaction_ledger` | does this period reconcile, what is unexplained | `when`, `amount` | `party`, `expected_set` (document) | drawer | none |\n| `monitored_asset_set` | what needs attention, is that number normal | `identity`, `measure` (level) | `mark`, `lifecycle` | drawer | none |\n| `trend_deep_dive` | how did the period go, and why | `when` | `measure`, `amount` | drawer | none |\n\nEach shape is a `@lotics/ui` component of the same name (`LifecycleDesk`,\n`PartyRegister`, \u2026) whose props are these slots, so once the tables exist\n`lotics app create <name> --from <this file>#<app alias>` scaffolds the app with\none screen per entry, each slot reading the field the plan bound.\n\nA screen is that list and the RECORD it opens, and the record comes off the same\nroles \u2014 nothing to declare for it. It opens with a **header**: the `identity` as\nthe record\'s name, and on a `page` also the `when` under it and ONE headline\nfigure (the `amount` the screen reads, else its `measure`); the `lifecycle` is\nnot badged there, because the progress section is the rung it stands\non. Then its sections, in order: the **facts** (every field\nneither the header nor another section owns, the row\'s own `parent` among them),\nthe **progress** (the `lifecycle`\'s stages, and what moves the record on), a\n**required set** (a multi-select `expected_set`, or a child entity whose rows\ncarry one entry of it each \u2014 that child\'s `files` field is what a paper attaches\nto), the record\'s **own rows** (any other child, its role-bound fields as\ncolumns), and its **files** (every `files` field, the `mark` first). A child is\nan entity whose `parent` links here. The name and the figure are the header\'s\nalone \u2014 it states both in full, so a fact for either would be the same sentence\ntwice; a `drawer` has only the name. `check` prints the record under each\nscreen\'s slots:\n\n```\n  Orders \u2014 lifecycle desk over Orders (12 rows) \xB7 drawer \xB7 tabs: Stage (New \u2192 Quoted \u2192 Confirmed \u2192 Shipped \u2192 Done)\n    stage Stage \xB7 identity Order no. \xB7 mark Photo \xB7 party Customer \xB7 amount Total \xB7 when Due\n    record: header (Order no.) \xB7 facts (Customer \xB7 Total \xB7 Due) \xB7 progress: Stage (5 stages) \xB7 documents: Papers (Kind: 4 required) \xB7 lines: Order lines (Product \xB7 Quantity \xB7 Line total) \xB7 files: Photo\n```\n\nIn that line `documents:` is a `RecordExpectedSet` and `lines:` a `RecordChildren`; a required set\nwhose entries are a CHILD entity carrying files takes `kind="files"`, and the entity\'s own\nmulti-select takes `kind="items"`, since nothing attaches to an option.\n\n`"shape": "custom"` is a screen of its own shape: it declares its slots under\n`roles` (slot \u2192 role) and they bind the same way; the scaffold gives it the\nrows and the slot list, and the screen is composed from the kit by hand.\n\n```jsonc\n{ "alias": "readings", "label": "Readings", "shape": "custom", "entity": "reading",\n  "roles": { "subject": "identity", "reading": "measure" } }\n```\n\n## Applying packages\n\n`apply` copies published packages into the workspace AFTER the model\'s own\ntables exist \u2014 apps over the tables you just described, and any tables of their\nown they still need. Ordered, and run by `lotics setup` and `lotics scaffold\napply` alike.\n\n```jsonc\n"apply": [\n  {\n    "package": "apg_k3nf82ldpq",\n    "bind": {                              // optional \u2014 which of YOUR tables each entity is\n      "company": { "label": "Customers", "fields": { "name": "Company name" } }\n    },\n    "no_sample_data": true                 // optional\n  }\n]\n```\n\n`bind` is keyed by the package\'s entity alias and holds the LABELS this\nworkspace uses: scaffold adopts by label, so binding points the package at the\ntables the model created instead of a second set beside them. Only naming\nmoves \u2014 a bound field must be the TYPE the package declares, or the copy is\nrefused. `lotics library list` is the shelf, and `lotics library show <apg_id>`\nlists the aliases to bind.\n\nEntries run in the order they are written, because a later one may bind onto a\ntable an earlier one created. **A refused entry stops the run and the entries\nbefore it stay** \u2014 they are separate copies, committed as they land, so the\nrefusal names them rather than leaving a caller to re-run the file and copy them\ntwice.\n\n## Presets\n\nA preset is a trade\'s model, published to be READ. An assistant reads it, asks\nat most two questions, picks a variant and writes a `model.json` from it \u2014\nnothing is copied, and a preset is a file rather than anything a workspace\ninstalls.\n\n```jsonc\n"preset": {\n  "name": "Field service",\n  "description": "Jobs, the crew that runs them, and what each one billed.",\n  "questions": ["Do you dispatch crews, or one person per job?"],  // at most 2\n  "variants": {\n    "crews": {\n      "when": "work is dispatched to crews rather than to one person",\n      "entities": [ /* tables this branch ADDS */ ],\n      "fields": { "job": [ /* fields this branch ADDS to `job` */ ] }\n    }\n  }\n}\n```\n\nVariants are **additive only**: a branch adds entities and fields and never\nremoves them, so the base is a model in its own right rather than a draft.\n`lotics scaffold check` proves the base AND every variant merged onto it, so a\npreset ships with every branch already proven \u2014 the branch nobody took is the\none that fails in the workspace of whoever takes it.\n\n`preset` is not scaffolded. `lotics setup` and `lotics scaffold apply` ignore\nit and create the base model\'s tables.\n\n`lotics scaffold export` prints a workspace that already works as one of these\nfiles \u2014 the starting point for a preset or for another business\'s model, never a\nsource of truth: it carries one business\'s words and stops describing that\nworkspace the moment either changes.\n\n## Starting from a preset\n\n`lotics library list` is the shelf of them and `lotics library show <slug>`\nprints one whole: its questions, every table as `alias \xB7 label` with each field\nas `alias:type`, and each variant as `slug \xB7 when` followed by the tables and\nfields that branch adds. When one of them is the trade in front of you, do not\ntranscribe it \u2014 name it:\n\n```jsonc\n{\n  "from": "field_service",\n  "variants": ["crews"],\n  "rename": { "job": { "label": "\u0110\u01A1n h\xE0ng", "fields": { "code": "M\xE3 \u0111\u01A1n" } } },\n  "entities": [ /* a table this business has that the preset does not */ ],\n  "rows": { "job": [ { "ref": "j1", "fields": { "code": "J-1" } } ] },\n  "field_roles": { "job": { "code": "identity" } },\n  "apps": [ /* the screens this business\'s apps will have */ ]\n}\n```\n\n- **`from`** is the preset\'s SLUG \u2014 its own file name, a lowercase slug. Naming\n  it is what makes `entities` optional; every other rule on this page is\n  unchanged, because the file is resolved into the full form and then checked and\n  applied exactly as one. A slug nothing serves is refused with the ones there\n  are, never resolved against something else.\n- **`variants`** names the branches to merge onto the base, in order. Pick the\n  one whose `when` describes what the person said; a slug the preset does not\n  declare is refused rather than ignored.\n- **`rename`** is keyed by the preset\'s entity alias and holds the labels this\n  business uses \u2014 the same shape `apply[].bind` takes, and the same rule: only\n  naming moves. An alias the preset does not declare, and a label that is\n  already another table\'s, are both refused.\n- **`entities`** are added after the rename, already in this business\'s own\n  words.\n- **`rows`**, **`field_roles`**, **`apps`** and **`apply`** mean exactly what\n  they mean in the full form \u2014 `"rows"` are this business\'s real first records,\n  `"field_roles"` may name the preset\'s fields as well as its own (a role the\n  preset declares itself is kept unless this file names the same field, or\n  clears it with `null`),\n  `"apps"` the screens it will have (a preset carries none), `"apply"` the\n  packages copied in once its tables exist.\n\nThis is the ONE thing on this page that needs the network: `check` reads the\npreset it names, once. Everything after that read is the same offline check.\n\nWrite the full form when no preset is the trade.\n\n## A complete model\n\n```json\n{\n  "entities": [\n    {\n      "alias": "customer",\n      "label": "Customers",\n      "fields": [\n        { "alias": "name", "label": "Name", "type": "text", "required": true },\n        {\n          "alias": "tier",\n          "label": "Tier",\n          "type": "select",\n          "options": [\n            { "alias": "standard", "label": "Standard", "color": "slate" },\n            { "alias": "gold", "label": "Gold", "color": "amber" }\n          ],\n          "default": ["standard"]\n        },\n        {\n          "alias": "orders",\n          "label": "Orders",\n          "type": "select_record_link",\n          "target_entity": "order",\n          "cardinality": "many",\n          "sync_both_ways": true,\n          "paired_field_alias": "customer",\n          "display_field_aliases": ["code"]\n        },\n        {\n          "alias": "total_ordered",\n          "label": "Total ordered",\n          "type": "rollup",\n          "source_field_alias": "orders",\n          "aggregate_option": { "operation": "sum", "field_key": "amount" }\n        }\n      ],\n      "views": [\n        {\n          "alias": "gold",\n          "label": "Gold customers",\n          "filters": {\n            "node_type": "condition",\n            "type": "select",\n            "field_key": "tier",\n            "operator": "has_any_of",\n            "value": ["gold"]\n          },\n          "sort": [{ "field_key": "name", "order": "asc" }]\n        }\n      ]\n    },\n    {\n      "alias": "order",\n      "label": "Orders",\n      "fields": [\n        { "alias": "code", "label": "Order no.", "type": "text", "unique": true },\n        { "alias": "placed_on", "label": "Placed on", "type": "date", "format": "date" },\n        {\n          "alias": "amount",\n          "label": "Amount",\n          "type": "number",\n          "format": "currency",\n          "currency": "VND"\n        },\n        {\n          "alias": "total",\n          "label": "Total with VAT",\n          "type": "formula",\n          "formula": { "expression": "{amount} * 1.1", "format": "currency", "currency": "VND" }\n        },\n        {\n          "alias": "customer",\n          "label": "Customer",\n          "type": "select_record_link",\n          "target_entity": "customer",\n          "cardinality": "one",\n          "sync_both_ways": true,\n          "paired_field_alias": "orders",\n          "display_field_aliases": ["name"]\n        }\n      ]\n    }\n  ],\n  "roles": [{ "alias": "sales", "label": "Sales" }],\n  "field_roles": {\n    "customer": { "name": "identity" },\n    "order": { "code": "identity", "placed_on": "when", "amount": "amount", "customer": "party" }\n  },\n  "apps": [\n    {\n      "alias": "sales",\n      "name": "Sales",\n      "screens": [\n        { "alias": "customers", "label": "Customers", "shape": "party_register", "entity": "customer" },\n        { "alias": "orders", "label": "Orders", "shape": "transaction_ledger", "entity": "order" }\n      ]\n    }\n  ],\n  "rows": {\n    "customer": [\n      { "ref": "acme", "fields": { "name": "Acme Trading", "tier": "gold" } },\n      { "ref": "bluebird", "fields": { "name": "Bluebird Foods", "tier": "standard" } }\n    ],\n    "order": [\n      {\n        "ref": "so_1001",\n        "fields": {\n          "code": "SO-1001",\n          "placed_on": "@month-start+2",\n          "amount": 4200000,\n          "customer": "customer:acme"\n        }\n      },\n      {\n        "ref": "so_1002",\n        "fields": {\n          "code": "SO-1002",\n          "placed_on": "@today-3",\n          "amount": 1150000,\n          "customer": "customer:bluebird"\n        }\n      }\n    ]\n  }\n}\n```\n\n`lotics scaffold check` on this file reports\n`2 tables, 9 fields, 2 links, 1 view, 1 role, 4 rows, 1 app, 2 screens`, then\nthe plan:\n\n```\nSales\n  Customers \u2014 party register over Customers (2 rows) \xB7 page \xB7 tabs: none\n    identity Name \xB7 mark (none) \xB7 contact (none) \xB7 worth (none) \xB7 risk (none)\n    record: header (Name) \xB7 facts (Tier \xB7 Orders \xB7 Total ordered)\n  Orders \u2014 transaction ledger over Orders (2 rows) \xB7 drawer \xB7 tabs: none\n    when Placed on \xB7 amount Amount \xB7 party Customer \xB7 document (none)\n    record: facts (Order no. \xB7 Placed on \xB7 Amount \xB7 Total with VAT \xB7 Customer)\n```\n\nEvery `(none)` is a slot no field fills \u2014 the picture a register has none of,\nthe contact nobody declared. Read it as the screen a person will see. Each\nrecord is a header and facts here: neither entity carries a stage, a required\nset, files, or rows of its own. The Customers page states its name in the header\nand nowhere else; the Orders drawer has no `identity` to state, so every field\nit reads is a fact.\n';
+var model_reference_default = '# The Lotics workspace model (`model.json`)\n\nOne JSON file describing the tables, fields, options, views, roles and first rows\na workspace starts with. `lotics scaffold check model.json` proves it offline \u2014\nno account, no network. `lotics setup model.json --email you@company.com` creates\nthe account and applies it. `lotics scaffold apply model.json` applies it again,\ninto the workspace the credential names.\n\n**There are two forms of this file.** The full one, below, spells the model out.\nThe `from` one names a published preset and carries only what this business\ndiffers by \u2014 see \xA7 Starting from a preset, and prefer it whenever a preset fits\nthe trade.\n\nApps are PLANNED here and built afterwards: `apps` names each app\'s screens as a\nshape over an entity, checked against the roles `field_roles` gives its fields,\nso the plan is refused before anyone builds a screen (\xA7 Apps and screens). The\nbuilt app lives in the workspace; publishing that workspace as a package is how\nit ships.\n\n## The rules\n\n- **At least one entity, at most 50.** More tables than that is a data model\n  being designed, not scaffolded \u2014 scaffold the rest in a second call.\n- **Adoption is explicit.** `lotics setup` REFUSES an entity whose `label`\n  already names a table in the workspace, naming every colliding label at once.\n  `lotics scaffold apply` adopts those tables and adds the fields, options and\n  views they are missing. Nothing is ever modified or deleted, so applying the\n  same model twice creates nothing the second time.\n- **Adoption is by LABEL, not alias.** Change an entity\'s `label` and the next\n  run asks for a NEW table beside the old one. Renames and deletions go through\n  `lotics run update_table` / `lotics run delete_table`, never through the file.\n- **Rows land only where every bound table is empty.** One table already holding\n  records and no rows are written anywhere, and the result says\n  `rows_skipped: true`: sample rows landing among a customer\'s real ones cannot\n  be told apart from them.\n- **After the first run the WORKSPACE is the source of truth.** The file is an\n  authoring input, not a mirror \u2014 scaffold never deletes what the file stopped\n  naming.\n- **`lotics scaffold check` decides all of it offline**, and reports every\n  problem in one run rather than the first: an alias that resolves to nothing, a\n  link whose pair is not symmetric, and the rows themselves \u2014 a field the entity\n  does not declare, an option alias the field does not declare, a link naming no\n  row in the file, a `ref` used twice, a date that is not one, a value on a\n  platform-computed field, and a files cell that is neither a relative path\n  beside this file nor a `fil_` id.\n\n## Top level\n\n```jsonc\n{\n  "entities": [ /* the tables */ ],\n  "roles":    [ /* workspace groups to create */ ],    // optional\n  "templates":[ /* inline html / email templates */ ], // optional\n  "rows":     { /* first records, keyed by entity alias */ },  // optional\n  "field_roles": { /* the reporting role each field plays, keyed by entity then field */ }, // optional\n  "apps":     [ /* the screens each app will have, as shapes over entities */ ], // optional\n  "apply":    [ /* published packages to copy in afterwards */ ], // optional\n  "preset":   { /* a trade\'s branches, for a PUBLISHED model */ } // optional\n}\n```\n\nThe other form names a preset instead of restating one:\n\n```jsonc\n{\n  "from":     "field_service",             // the preset this model starts from, by slug\n  "variants": ["crews"],                   // optional \u2014 its branches to merge in, in order\n  "rename":   {                            // optional \u2014 what THIS business calls each table\n    "job": { "label": "\u0110\u01A1n h\xE0ng", "fields": { "code": "M\xE3 \u0111\u01A1n" } }\n  },\n  "entities": [ /* tables the preset does not declare */ ],    // optional\n  "rows":     { /* first records, keyed by entity alias */ },  // optional\n  "field_roles": { /* roles on the preset\'s fields and this business\'s own */ }, // optional\n  "apps":     [ /* the screens each app will have */ ],        // optional\n  "apply":    [ /* published packages to copy in afterwards */ ] // optional\n}\n```\n\n**A model may not carry** `fixtures`, `knowledge` or `knowledge_expects`, and no\n`excel` / `word` / `pdf-form` template: each of those is content that lives in a\npublished bundle, which a model has none of. `apps` here is a plan of screens,\nnever built code. An unknown top-level key is an error, never ignored.\n\n### Aliases\n\nEvery `alias` is a lowercase slug \u2014 a letter, then letters, digits and\nunderscores (`unit_price`, `so_1001`). Aliases are how the file cross-references\nitself; they are never shown to anyone. `label` is what a person sees.\n\nLabels must be unique within their namespace \u2014 two entities, two fields on one\nentity, two options on one field, two views on one entity, two roles or two\ntemplates cannot share a label, because scaffold matches by label.\n\n## Entity\n\n```jsonc\n{\n  "alias": "order",\n  "label": "Orders",            // the table\'s name\n  "description": "\u2026",           // optional\n  "fields": [ /* at least one */ ],\n  "views":  [ /* optional; an entity with none still gets the default grid */ ]\n}\n```\n\n## Field\n\nEvery field carries `alias`, `label`, an optional `description`, and an optional\n`required` \u2014 advisory only, read by app forms and workflows; the table itself has\nno required constraint. `label` may not contain `{` or `}` (formulas reference\nfields by label at the platform level).\n\n`default` is the value pre-filled into a NEW record. It applies on create only;\nexisting records are never backfilled. Only the types listed below accept one.\n\n### `text`\n\n```jsonc\n{ "alias": "name", "label": "Name", "type": "text",\n  "unique": false,              // optional \u2014 require distinct values\n  "format": "text",             // optional \u2014 "text" | "link" | "markdown"\n  "default": "" }               // optional\n```\n\n### `number`\n\n```jsonc\n{ "alias": "amount", "label": "Amount", "type": "number",\n  "format": "currency",         // optional \u2014 "number" | "currency" | "percentage"\n  "currency": "VND",            // optional \u2014 ISO 4217\n  "default": 0 }                // optional\n```\n\n### `date`\n\n```jsonc\n{ "alias": "placed_on", "label": "Placed on", "type": "date",\n  "format": "date",             // optional \u2014 "date" | "datetime" | "date_range" | "datetime_range"\n  "timezone": "Asia/Ho_Chi_Minh",  // optional \u2014 IANA name\n  "derive_from": "created_at",  // optional \u2014 "created_at" | "updated_at"; makes the field read-only\n  "default": "2026-01-01" }     // optional; refused together with derive_from\n```\n\n### `boolean`\n\n```jsonc\n{ "alias": "paid", "label": "Paid", "type": "boolean", "default": false }\n```\n\n### `select`\n\n```jsonc\n{ "alias": "tier", "label": "Tier", "type": "select",\n  "options": [                                     // at least one\n    { "alias": "standard", "label": "Standard", "color": "slate" },\n    { "alias": "gold",     "label": "Gold",     "color": "amber" }\n  ],\n  "multi": false,               // optional\n  "default": ["standard"] }     // optional \u2014 option ALIASES; one unless multi\n```\n\n`color` is one of: `red`, `orange`, `amber`, `yellow`, `lime`, `green`,\n`emerald`, `teal`, `cyan`, `sky`, `blue`, `indigo`, `violet`, `purple`,\n`fuchsia`, `pink`, `rose`, `slate`, `gray`, `zinc`, `neutral`, `stone`.\n\n### `select_member`\n\nA person picker over the workspace\'s members. No default: a model cannot name\nmembers of a workspace that does not exist yet.\n\n```jsonc\n{ "alias": "owner", "label": "Owner", "type": "select_member", "multi": false }\n```\n\n### `select_record_link`\n\n```jsonc\n{ "alias": "customer", "label": "Customer", "type": "select_record_link",\n  "target_entity": "customer",        // an entity alias this model declares\n  "cardinality": "one",               // optional \u2014 "one" | "many" (default "many")\n  "sync_both_ways": true,             // optional \u2014 keep a paired field on the target\n  "paired_field_alias": "orders",     // the partner field ON THE TARGET entity\n  "display_field_aliases": ["name"] } // optional \u2014 what the link shows / the picker\'s columns\n```\n\nA two-way link is declared on BOTH sides, each naming the other as its\n`paired_field_alias`; the pair must be symmetric or the model is refused. Declare\none side only (with no `paired_field_alias`) for a link with no back-reference.\n\n### `files`\n\n```jsonc\n{ "alias": "attachments", "label": "Attachments", "type": "files" }\n```\n\n### `formula`\n\n```jsonc\n{ "alias": "total", "label": "Total", "type": "formula",\n  "formula": {\n    "expression": "{amount} * 1.1",  // fields on THIS entity, by alias, in braces\n    "format": "currency",            // optional \u2014 "number" | "currency" | "percentage" | "link"\n    "currency": "VND"                // optional\n  } }\n```\n\n### `rollup`\n\nAggregates the records reached through a link on this entity.\n\n```jsonc\n{ "alias": "total_ordered", "label": "Total ordered", "type": "rollup",\n  "source_field_alias": "orders",    // a select_record_link field on THIS entity\n  "aggregate_option": {\n    "operation": "sum",              // count | sum | avg | median | min | max | range |\n                                     // empty | filled | percent_empty | percent_filled |\n                                     // unique | percent_unique |\n                                     // earliest | latest | date_range |\n                                     // checked | unchecked | percent_checked |\n                                     // percent_unchecked\n    "field_key": "amount"            // a field ALIAS on the linked entity ("count" may omit it)\n  },\n  "filter": { /* optional \u2014 see Views; every field_key is an alias on the LINKED entity */ } }\n```\n\nThe operation must be one the aggregated field\'s type allows \u2014 `sum` over a\nnumber, `earliest` over a date, `filled` over anything.\n\n### `lookup`\n\nDisplays a field from the linked records.\n\n```jsonc\n{ "alias": "customer_tier", "label": "Customer tier", "type": "lookup",\n  "source_field_alias": "customer",  // a select_record_link field on THIS entity\n  "lookup_field_alias": "tier",      // a field alias on the linked entity\n  "order_by": { "field_key": "placed_on", "direction": "desc" } }  // optional \u2014 pick the single extreme row\n```\n\n### `autonumber`\n\n```jsonc\n{ "alias": "seq", "label": "No.", "type": "autonumber",\n  "prefix": "SO-",     // optional \u2014 ignored when template is set\n  "padding": 4,        // optional \u2014 1..20, zero-pads the integer\n  "template": "SO-{YEAR}-{N:4}" }  // optional \u2014 {N}, {N:W}, {YEAR}, {YEAR:2}, {MONTH}, {DAY}\n```\n\n## Views\n\nSaved views live under the entity they belong to. Every field reference is a\nfield ALIAS on that entity.\n\n```jsonc\n{\n  "alias": "gold",\n  "label": "Gold customers",\n  "description": "\u2026",                       // optional\n  "columns": [                              // optional \u2014 omit to show every field\n    { "field_alias": "name", "visibility": "visible", "width": 240 },\n    { "field_alias": "tier", "visibility": "hidden" }\n  ],\n  "filters": {                              // optional\n    "node_type": "group",\n    "logic": "and",                         // "and" | "or"\n    "children": [\n      { "node_type": "condition", "type": "select", "field_key": "tier",\n        "operator": "has_any_of", "value": ["gold"] }\n    ]\n  },\n  "sort": [ { "field_key": "name", "order": "asc" } ],  // optional; order is "asc" | "desc" | null\n  "summary": { "amount": "sum" },           // optional \u2014 field alias \u2192 footer operation\n  "frozen_columns": 1                       // optional\n}\n```\n\nA condition\'s `type` is the field\'s type and its `operator` is one that type\nadmits \u2014 `has_any_of` / `has_none_of` / `has_all_of` / `is_empty` /\n`is_not_empty` for a select, `equals` / `greater_than` / `less_than` for a\nnumber, `on` / `before` / `after` / `between` for a date, `contains` /\n`is_any_of` for text. A select condition\'s `value` names option ALIASES.\n\n`columns`, when present, is exhaustive and must not be empty: a view renders\nexactly the entries it holds. Omit the key to show every field.\n\n## Roles\n\nA role becomes a workspace group. Members are added afterwards, in the app.\n\n```jsonc\n{ "alias": "sales", "label": "Sales" }\n```\n\n## Templates\n\nOnly inline `html` and `email` templates \u2014 the rest are file-backed and a model\nhas no bytes. An `html` template renders to a PDF when a workflow generates\nfrom it; `{{name}}` is filled from the workflow\'s data.\n\n```jsonc\n{ "alias": "order_ack", "label": "Order acknowledgement", "type": "email",\n  "content": "<p>Hello {{customer}}\u2026</p>" }\n```\n\nA paper that has to look like a counterparty produced it \u2014 an official letter,\nan acceptance minute, a supplier\'s bill \u2014 is the same `html` template with a\nshell around the body: a letterhead, a reference line, a seal and a signature\nblock, and paper grain over everything. One shell, many bodies; the data is the\nonly thing that changes, so a workflow can re-issue it over any record.\n\n```jsonc\n{ "alias": "cong_van", "label": "C\xF4ng v\u0103n", "type": "html",\n  "content": "\u2026the page below, as one JSON string\u2026" }\n```\n\n```html\n<style>\n    .sheet{position:relative;width:718px;padding:44px 58px 30px;background:#fbfaf6;color:#111;font:14.2px/1.5 \'Liberation Serif\',serif}\n    .grain{position:absolute;inset:0;opacity:.34;mix-blend-mode:multiply;background:url("data:image/svg+xml;utf8,<svg xmlns=\'http://www.w3.org/2000/svg\' width=\'140\' height=\'140\'><filter id=\'f\'><feTurbulence baseFrequency=\'.9\' numOctaves=\'2\'/><feColorMatrix values=\'0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 .35 0\'/></filter><rect width=\'140\' height=\'140\' filter=\'url(%23f)\'/></svg>")}\n    .top{display:flex;text-align:center;font-size:13.4px} .top>div{flex:1} .u{display:inline-block;border-bottom:1px solid #111;font-weight:700}\n    .ref{display:flex;text-align:center;font-size:13.4px;margin-top:6px} .ref>div{flex:1} .ref .r{font-style:italic}\n    h1{text-align:center;font-size:15.6px;margin:26px 0 18px} p{text-align:justify;text-indent:26px;margin:0 0 9px}\n    .sig{display:flex;margin-top:20px} .sig .l{flex:1} .sig .r{width:290px;text-align:center;position:relative}\n    .sig .nm{font-weight:700;margin-top:96px} .seal{position:absolute;left:4px;top:8px;width:166px;height:166px;opacity:.66;mix-blend-mode:multiply;transform:rotate(-17deg)}\n  </style>\n  <div class=\'sheet\'><div class=\'grain\'></div>\n    <div class=\'top\'><div><b>{{issuer_parent}}</b><br><span class=\'u\'>{{issuer}}</span></div>\n      <div><b>C\u1ED8NG H\xD2A X\xC3 H\u1ED8I CH\u1EE6 NGH\u0128A VI\u1EC6T NAM</b><br><span class=\'u\'>\u0110\u1ED9c l\u1EADp - T\u1EF1 do - H\u1EA1nh ph\xFAc</span></div></div>\n    <div class=\'ref\'><div>S\u1ED1: {{number}}</div><div class=\'r\'>{{place}}, ng\xE0y {{day}} th\xE1ng {{month}} n\u0103m {{year}}</div></div>\n    <h1>{{title}}</h1>\n    <p>K\xEDnh g\u1EEDi: {{recipient}}.</p>\n    {{{body}}}\n    <div class=\'sig\'><div class=\'l\'><b>N\u01A1i nh\u1EADn:</b><br>- Nh\u01B0 tr\xEAn;<br>- L\u01B0u VT.</div>\n      <div class=\'r\'><img class=\'seal\' src=\'{{seal_url}}\'><b>{{signer_title}}</b><div class=\'nm\'>{{signer}}</div></div></div>\n  </div>\n```\n\n`lotics preview <file.html>` renders any such page to a PNG the way a demo\'s\nprops are made, sized to its content, so a paper can be looked at before it is\nput in a template.\n\n## Rows\n\nFirst records, keyed by entity alias. Up to 200 rows per entity and 2000 across\nthe model, attaching at most 2000 documents between them \u2014 a real data set\nbelongs in an import, not a model.\n\n```jsonc\n"rows": {\n  "customer": [\n    { "ref": "acme", "fields": { "name": "Acme Trading", "tier": "gold" } }\n  ]\n}\n```\n\n`ref` is a local handle (lowercase letters, digits, underscores) that other rows\'\nlink fields address. It is never persisted.\n\nA `files` cell attaches documents: paths relative to this file (no `..`, never\nabsolute), which `check` proves exist and `apply` uploads into the workspace\nbefore any row is written \u2014 a paperwork business seeds its papers with its\nrows. The server accepts only `fil_` ids of files this workspace owns, which is\nwhat the upload leaves behind. After a run that wrote rows, `apply` writes the\nrecord ids beside the file (`<model>.last_run.json`): `delete_records` over\nthem is how a seeded set is reset, and applying again re-dates it.\n\n`fields` is keyed by field alias, and every value is read against the field\'s\nDECLARED type:\n\n| Field type | Value |\n|---|---|\n| `text` / `number` / `boolean` | the value itself |\n| `date` | `"2026-03-14"`, or a relative expression (below) |\n| `select` | the option ALIAS \u2014 `"gold"`, or `["gold","vip"]` for a multi-select |\n| `select_record_link` | `"<entity-alias>:<ref>"` naming another row in this file \u2014 `"customer:acme"`, or an array for several |\n| `select_member` | `"self"` only \u2014 the person applying the model |\n| `files` | paths beside this file \u2014 `["scans/pccc_letter.png"]` \u2014 uploaded by `apply`/`setup` before the rows are posted; or `fil_` ids of files already in this workspace |\n| `formula`, `rollup`, `lookup`, `autonumber` | not allowed \u2014 the platform writes these |\n\n### Relative dates\n\nA date cell holds a literal `YYYY-MM-DD`, or an expression relative to the day\nthe model is applied, so a screen that opens on "this month" is not empty a month\nlater:\n\n- `@today` \u2014 the day of the run, in the workspace\'s timezone\n- `@month-start` \u2014 the 1st of that month\n- either with a whole-day offset: `@today-14`, `@month-start+9`\n\n`@month-start` exists because `@today-N` cannot promise a month: applied on the\n2nd, `@today-3` lands in the previous one.\n\n## Field roles\n\n`field_roles` names the reporting role a field plays on its entity \u2014 keyed by\nentity alias, then field alias \u2014 so every screen over the entity agrees on\nwhich column names the row and which select is the stage. A shape\'s slot binds\nto it (\xA7 Apps and screens). Like `rows` and `apps`, it is this file\'s: `check`\nproves it and the workspace never sees it. Each role sits on the types that can\nanswer it:\n\n| Role | On | Meaning |\n|---|---|---|\n| `identity` | `text`, `autonumber`, `select_record_link` | names the row \u2014 the register\'s first column; a link where the row is "the product, at this branch". One per entity |\n| `mark` | `files` | the row\'s picture. One per entity |\n| `lifecycle` | single `select` | the ordered stages a row walks; option order is the order. One per entity |\n| `measure` | `number`, `formula`, `rollup` | a level read against a limit \u2014 see `against` and `alert` |\n| `expected_set` | `select` | its OPTIONS are the required set (documents, checks, services); an option no row has is a gap to show, not nothing |\n| `amount` | `number`, `formula`, `rollup` | THE signed money of a ledger row. One per entity |\n| `when` | `date` | the ledger or timeline date. One per entity |\n| `party` | `select_record_link` | the counterparty. One per entity |\n| `parent` | `select_record_link` | the record this row belongs to \u2014 a line\'s order, a paper\'s case. The parent\'s record shows these rows; the row shows the parent as a fact. One per entity, and it links to an entity this model declares |\n| `contact` | `text` | the one way to reach a party. One per entity |\n| `verdict` | `boolean`, `formula` | a settled pass/fail \u2014 ticked, or computed. One per entity |\n\nA bare role name is the common form. A `measure` takes the object form to name\nits limit: `against` \u2014 a `number` field on the same entity, by alias, or a\nconstant \u2014 and `alert`, which side of it needs attention, `over` a capacity or\n`under` a minimum. The two come together.\n\n```jsonc\n"field_roles": {\n  "product": { "name": "identity", "photo": "mark" },\n  "stock":   { "on_hand": { "role": "measure", "against": "minimum", "alert": "under" },\n               "uptime":  { "role": "measure", "against": 80, "alert": "under" } }\n}\n```\n\nIn a file that starts from a preset (\xA7 Starting from a preset), `field_roles`\nmay name the preset\'s fields as well as this business\'s own; a role the preset\ndeclares itself is kept unless this file names the same field, and `null`\nclears it.\n\n## Apps and screens\n\n`apps` is the plan: each app the reader will build, and each of its screens as\na SHAPE over an ENTITY. Nothing here is built by the scaffold \u2014 the plan is what\n`lotics scaffold check` prints back, screen by screen with the field in every\nslot, so it is read and corrected before a screen exists.\n\n```jsonc\n"apps": [\n  {\n    "alias": "sales", "name": "Sales",\n    "description": "\u2026", "icon": "briefcase", "theme": { "color": "blue" }, // optional\n    "screens": [\n      { "alias": "customers", "label": "Customers", "shape": "party_register", "entity": "customer" },\n      { "alias": "orders",    "label": "Orders",    "shape": "lifecycle_desk", "entity": "order",\n        "record": "drawer",                  // optional \u2014 "drawer" | "page"; absent, the shape decides\n        "tabs": "stage",                     // optional \u2014 a select on the entity, or null; absent, the shape decides\n        "slots": { "identity": "code" } }    // optional \u2014 slot \u2192 field, where the roles cannot decide alone\n    ]\n  }\n]\n```\n\nA shape is a proven screen with named SLOTS, each filled by a field carrying a\nrole (\xA7 Field roles). A slot with exactly one candidate on the entity binds by itself;\ntwo candidates need naming in `slots`; a field fills one slot; a required slot\nwith none is refused \u2014 a lifecycle desk over an entity with no `lifecycle`\nselect cannot be built.\n\n| Shape | Answers | Required | Also fills | Record | Tabs |\n|---|---|---|---|---|---|\n| `lifecycle_desk` | what is stuck, what do I move next | `lifecycle`, `identity` | `mark`, `party`, `amount`, `when` | drawer | the lifecycle\'s stages |\n| `party_register` | who is this, our history, is there a risk | `identity` | `mark`, `contact`, `measure` (worth), `verdict` (risk) | page | none |\n| `offering_register` | what do we offer, at what price, can I sell it | `identity` | `mark`, `amount` (price), `measure` (availability) | page | none |\n| `transaction_ledger` | does this period reconcile, what is unexplained | `when`, `amount` | `party`, `expected_set` (document) | drawer | none |\n| `monitored_asset_set` | what needs attention, is that number normal | `identity`, `measure` (level) | `mark`, `lifecycle` | drawer | none |\n| `trend_deep_dive` | how did the period go, and why | `when` | `measure`, `amount` | drawer | none |\n\nEach shape is a `@lotics/ui` component of the same name (`LifecycleDesk`,\n`PartyRegister`, \u2026) whose props are these slots, so once the tables exist\n`lotics app create <name> --from <this file>#<app alias>` scaffolds the app with\none screen per entry, each slot reading the field the plan bound.\n\nA screen is that list and the RECORD it opens, and the record comes off the same\nroles \u2014 nothing to declare for it. It opens with a **header**: the `identity` as\nthe record\'s name, and on a `page` also the `when` under it and ONE headline\nfigure (the `amount` the screen reads, else its `measure`); the `lifecycle` is\nnot badged there, because the progress section is the rung it stands\non. Then its sections, in order: the **facts** (every field\nneither the header nor another section owns, the row\'s own `parent` among them),\nthe **progress** (the `lifecycle`\'s stages, and what moves the record on), a\n**required set** (a multi-select `expected_set`, or a child entity whose rows\ncarry one entry of it each \u2014 that child\'s `files` field is what a paper attaches\nto), the record\'s **own rows** (any other child, its role-bound fields as\ncolumns), and its **files** (every `files` field, the `mark` first). A child is\nan entity whose `parent` OR `party` links here \u2014 so a party\'s record is its\nhistory, the rows that name it. The name and the figure are the header\'s\nalone \u2014 it states both in full, so a fact for either would be the same sentence\ntwice; a `drawer` has only the name. `check` prints the record under each\nscreen\'s slots:\n\n```\n  Orders \u2014 lifecycle desk over Orders (12 rows) \xB7 drawer \xB7 tabs: Stage (New \u2192 Quoted \u2192 Confirmed \u2192 Shipped \u2192 Done)\n    stage Stage \xB7 identity Order no. \xB7 mark Photo \xB7 party Customer \xB7 amount Total \xB7 when Due\n    record: header (Order no.) \xB7 facts (Customer \xB7 Total \xB7 Due) \xB7 progress: Stage (5 stages) \xB7 documents: Papers (Kind: 4 required) \xB7 lines: Order lines (Product \xB7 Quantity \xB7 Line total) \xB7 files: Photo\n```\n\nIn that line `documents:` is a `RecordExpectedSet`, and `lines:` a `RecordChildren` over the rows\nthis record owns \u2014 `history:` where they name it as their `party` instead; a required set\nwhose entries are a CHILD entity carrying files takes `kind="files"`, and the entity\'s own\nmulti-select takes `kind="items"`, since nothing attaches to an option.\n\n`"shape": "custom"` is a screen of its own shape: it declares its slots under\n`roles` (slot \u2192 role) and they bind the same way; the scaffold gives it the\nrows and the slot list, and the screen is composed from the kit by hand.\n\n```jsonc\n{ "alias": "readings", "label": "Readings", "shape": "custom", "entity": "reading",\n  "roles": { "subject": "identity", "reading": "measure" } }\n```\n\n## Applying packages\n\n`apply` copies published packages into the workspace AFTER the model\'s own\ntables exist \u2014 apps over the tables you just described, and any tables of their\nown they still need. Ordered, and run by `lotics setup` and `lotics scaffold\napply` alike.\n\n```jsonc\n"apply": [\n  {\n    "package": "apg_k3nf82ldpq",\n    "bind": {                              // optional \u2014 which of YOUR tables each entity is\n      "company": { "label": "Customers", "fields": { "name": "Company name" } }\n    },\n    "no_sample_data": true                 // optional\n  }\n]\n```\n\n`bind` is keyed by the package\'s entity alias and holds the LABELS this\nworkspace uses: scaffold adopts by label, so binding points the package at the\ntables the model created instead of a second set beside them. Only naming\nmoves \u2014 a bound field must be the TYPE the package declares, or the copy is\nrefused. `lotics library list` is the shelf, and `lotics library show <apg_id>`\nlists the aliases to bind.\n\nEntries run in the order they are written, because a later one may bind onto a\ntable an earlier one created. **A refused entry stops the run and the entries\nbefore it stay** \u2014 they are separate copies, committed as they land, so the\nrefusal names them rather than leaving a caller to re-run the file and copy them\ntwice.\n\n## Presets\n\nA preset is a trade\'s model, published to be READ. An assistant reads it, asks\nat most two questions, picks a variant and writes a `model.json` from it \u2014\nnothing is copied, and a preset is a file rather than anything a workspace\ninstalls.\n\n```jsonc\n"preset": {\n  "name": "Field service",\n  "description": "Jobs, the crew that runs them, and what each one billed.",\n  "questions": ["Do you dispatch crews, or one person per job?"],  // at most 2\n  "variants": {\n    "crews": {\n      "when": "work is dispatched to crews rather than to one person",\n      "entities": [ /* tables this branch ADDS */ ],\n      "fields": { "job": [ /* fields this branch ADDS to `job` */ ] }\n    }\n  }\n}\n```\n\nVariants are **additive only**: a branch adds entities and fields and never\nremoves them, so the base is a model in its own right rather than a draft.\n`lotics scaffold check` proves the base AND every variant merged onto it, so a\npreset ships with every branch already proven \u2014 the branch nobody took is the\none that fails in the workspace of whoever takes it.\n\n`preset` is not scaffolded. `lotics setup` and `lotics scaffold apply` ignore\nit and create the base model\'s tables.\n\n`lotics scaffold export` prints a workspace that already works as one of these\nfiles \u2014 the starting point for a preset or for another business\'s model, never a\nsource of truth: it carries one business\'s words and stops describing that\nworkspace the moment either changes.\n\n## Starting from a preset\n\n`lotics library list` is the shelf of them and `lotics library show <slug>`\nprints one whole: its questions, every table as `alias \xB7 label` with each field\nas `alias:type`, and each variant as `slug \xB7 when` followed by the tables and\nfields that branch adds. When one of them is the trade in front of you, do not\ntranscribe it \u2014 name it:\n\n```jsonc\n{\n  "from": "field_service",\n  "variants": ["crews"],\n  "rename": { "job": { "label": "\u0110\u01A1n h\xE0ng", "fields": { "code": "M\xE3 \u0111\u01A1n" } } },\n  "entities": [ /* a table this business has that the preset does not */ ],\n  "rows": { "job": [ { "ref": "j1", "fields": { "code": "J-1" } } ] },\n  "field_roles": { "job": { "code": "identity" } },\n  "apps": [ /* the screens this business\'s apps will have */ ]\n}\n```\n\n- **`from`** is the preset\'s SLUG \u2014 its own file name, a lowercase slug. Naming\n  it is what makes `entities` optional; every other rule on this page is\n  unchanged, because the file is resolved into the full form and then checked and\n  applied exactly as one. A slug nothing serves is refused with the ones there\n  are, never resolved against something else.\n- **`variants`** names the branches to merge onto the base, in order. Pick the\n  one whose `when` describes what the person said; a slug the preset does not\n  declare is refused rather than ignored.\n- **`rename`** is keyed by the preset\'s entity alias and holds the labels this\n  business uses \u2014 the same shape `apply[].bind` takes, and the same rule: only\n  naming moves. An alias the preset does not declare, and a label that is\n  already another table\'s, are both refused.\n- **`entities`** are added after the rename, already in this business\'s own\n  words.\n- **`rows`**, **`field_roles`**, **`apps`** and **`apply`** mean exactly what\n  they mean in the full form \u2014 `"rows"` are this business\'s real first records,\n  `"field_roles"` may name the preset\'s fields as well as its own (a role the\n  preset declares itself is kept unless this file names the same field, or\n  clears it with `null`),\n  `"apps"` the screens it will have (a preset carries none), `"apply"` the\n  packages copied in once its tables exist.\n\nThis is the ONE thing on this page that needs the network: `check` reads the\npreset it names, once. Everything after that read is the same offline check.\n\nWrite the full form when no preset is the trade.\n\n## A complete model\n\n```json\n{\n  "entities": [\n    {\n      "alias": "customer",\n      "label": "Customers",\n      "fields": [\n        { "alias": "name", "label": "Name", "type": "text", "required": true },\n        {\n          "alias": "tier",\n          "label": "Tier",\n          "type": "select",\n          "options": [\n            { "alias": "standard", "label": "Standard", "color": "slate" },\n            { "alias": "gold", "label": "Gold", "color": "amber" }\n          ],\n          "default": ["standard"]\n        },\n        {\n          "alias": "orders",\n          "label": "Orders",\n          "type": "select_record_link",\n          "target_entity": "order",\n          "cardinality": "many",\n          "sync_both_ways": true,\n          "paired_field_alias": "customer",\n          "display_field_aliases": ["code"]\n        },\n        {\n          "alias": "total_ordered",\n          "label": "Total ordered",\n          "type": "rollup",\n          "source_field_alias": "orders",\n          "aggregate_option": { "operation": "sum", "field_key": "amount" }\n        }\n      ],\n      "views": [\n        {\n          "alias": "gold",\n          "label": "Gold customers",\n          "filters": {\n            "node_type": "condition",\n            "type": "select",\n            "field_key": "tier",\n            "operator": "has_any_of",\n            "value": ["gold"]\n          },\n          "sort": [{ "field_key": "name", "order": "asc" }]\n        }\n      ]\n    },\n    {\n      "alias": "order",\n      "label": "Orders",\n      "fields": [\n        { "alias": "code", "label": "Order no.", "type": "text", "unique": true },\n        { "alias": "placed_on", "label": "Placed on", "type": "date", "format": "date" },\n        {\n          "alias": "amount",\n          "label": "Amount",\n          "type": "number",\n          "format": "currency",\n          "currency": "VND"\n        },\n        {\n          "alias": "total",\n          "label": "Total with VAT",\n          "type": "formula",\n          "formula": { "expression": "{amount} * 1.1", "format": "currency", "currency": "VND" }\n        },\n        {\n          "alias": "customer",\n          "label": "Customer",\n          "type": "select_record_link",\n          "target_entity": "customer",\n          "cardinality": "one",\n          "sync_both_ways": true,\n          "paired_field_alias": "orders",\n          "display_field_aliases": ["name"]\n        }\n      ]\n    }\n  ],\n  "roles": [{ "alias": "sales", "label": "Sales" }],\n  "field_roles": {\n    "customer": { "name": "identity" },\n    "order": { "code": "identity", "placed_on": "when", "amount": "amount", "customer": "party" }\n  },\n  "apps": [\n    {\n      "alias": "sales",\n      "name": "Sales",\n      "screens": [\n        { "alias": "customers", "label": "Customers", "shape": "party_register", "entity": "customer" },\n        { "alias": "orders", "label": "Orders", "shape": "transaction_ledger", "entity": "order" }\n      ]\n    }\n  ],\n  "rows": {\n    "customer": [\n      { "ref": "acme", "fields": { "name": "Acme Trading", "tier": "gold" } },\n      { "ref": "bluebird", "fields": { "name": "Bluebird Foods", "tier": "standard" } }\n    ],\n    "order": [\n      {\n        "ref": "so_1001",\n        "fields": {\n          "code": "SO-1001",\n          "placed_on": "@month-start+2",\n          "amount": 4200000,\n          "customer": "customer:acme"\n        }\n      },\n      {\n        "ref": "so_1002",\n        "fields": {\n          "code": "SO-1002",\n          "placed_on": "@today-3",\n          "amount": 1150000,\n          "customer": "customer:bluebird"\n        }\n      }\n    ]\n  }\n}\n```\n\n`lotics scaffold check` on this file reports\n`2 tables, 9 fields, 2 links, 1 view, 1 role, 4 rows, 1 app, 2 screens`, then\nthe plan:\n\n```\nSales\n  Customers \u2014 party register over Customers (2 rows) \xB7 page \xB7 tabs: none\n    identity Name \xB7 mark (none) \xB7 contact (none) \xB7 worth (none) \xB7 risk (none)\n    record: header (Name) \xB7 facts (Tier \xB7 Orders \xB7 Total ordered) \xB7 history: Orders (Order no. \xB7 Placed on \xB7 Amount)\n  Orders \u2014 transaction ledger over Orders (2 rows) \xB7 drawer \xB7 tabs: none\n    when Placed on \xB7 amount Amount \xB7 party Customer \xB7 document (none)\n    record: facts (Order no. \xB7 Placed on \xB7 Amount \xB7 Total with VAT \xB7 Customer)\n```\n\nEvery `(none)` is a slot no field fills \u2014 the picture a register has none of,\nthe contact nobody declared. Read it as the screen a person will see. Neither\nentity carries a stage, a required set or files, so the rest is facts \u2014 except\nthe customer\'s `history:`, which is the orders that name it as their party, a\nsection nothing in the file declares. The Customers page states its name in the\nheader and nowhere else; the Orders drawer has no `identity` to state, so every\nfield it reads is a fact.\n';
 
 // src/scaffold_commands.ts
 function printModelReference() {
@@ -40774,8 +40896,10 @@ function describeRecord(model, resolved) {
         const set2 = `${required2.options.length} required`;
         return section.source === "own" ? `documents: ${name} (${set2})` : `documents: ${name} (${required2.label}: ${set2})`;
       }
-      case "children":
-        return `lines: ${section.child.label} (${section.fields.length === 0 ? "none" : labels(section.fields)})`;
+      case "children": {
+        const heading = section.via === "party" ? "history" : "lines";
+        return `${heading}: ${section.child.label} (${section.fields.length === 0 ? "none" : labels(section.fields)})`;
+      }
       case "files":
         return `files: ${labels(section.fields)}`;
     }
@@ -41102,15 +41226,7 @@ async function dispatchRpc(client, body, opts) {
       if (!p || typeof p.alias !== "string") {
         throw new Error("query payload must include `alias`");
       }
-      return client.appQuery(body.app_id, {
-        alias: p.alias,
-        params: p.params,
-        limit: p.limit,
-        offset: p.offset,
-        sort: p.sort,
-        filter: p.filter,
-        count: p.count
-      });
+      return client.appQuery(body.app_id, { ...p, alias: p.alias });
     }
     case "field_options": {
       const p = body.payload;
@@ -41244,6 +41360,12 @@ function openAppTarget(payload) {
 }
 
 // src/dev/wrapper_page.ts
+function deepLinkLoc(pathname, search) {
+  var explicit = new URLSearchParams(search).get("_loc");
+  if (explicit) return explicit;
+  if (pathname === "/" || pathname === "/index.html") return null;
+  return pathname + search;
+}
 function buildWrapperPage(args) {
   const { app_name, app_id, workspace_id, vite_url, api_url, web_app_url } = args;
   return `<!doctype html>
@@ -41301,7 +41423,8 @@ function buildWrapperPage(args) {
       // server (a url param flowing into an iframe src is a redirect vector);
       // anything else falls back to the app root.
       const appSrc = new URL(VITE_URL);
-      const savedLoc = new URLSearchParams(window.location.search).get("_loc");
+      var deepLinkLoc = (${deepLinkLoc.toString()});
+      const savedLoc = deepLinkLoc(window.location.pathname, window.location.search);
       if (savedLoc) {
         try {
           const resolved = new URL(savedLoc, VITE_ORIGIN);
@@ -41661,6 +41784,18 @@ var STOP_DEADLINE_MS = 2e3;
 function serializeRpcResult(result) {
   return JSON.stringify(result ?? null);
 }
+function servesWrapperPage(method, pathname) {
+  return method === "GET" && !pathname.startsWith("/_");
+}
+function viteChildArgs(viteEntry, vitePort, uiSrc) {
+  return [
+    viteEntry,
+    "--port",
+    String(vitePort),
+    "--strictPort",
+    ...uiSrc ? ["--force"] : []
+  ];
+}
 function nodeForChildProcess() {
   return process.versions.bun === void 0 ? process.execPath : "node";
 }
@@ -41684,7 +41819,7 @@ async function startDevServer(args) {
   }
   const viteChild = spawn(
     nodeForChildProcess(),
-    [viteEntry, "--port", String(vitePort), "--strictPort"],
+    viteChildArgs(viteEntry, vitePort, process.env.LOTICS_UI_SRC),
     {
       cwd: args.projectDir,
       stdio: [process.stdin.isTTY ? "inherit" : "ignore", "inherit", "inherit"],
@@ -41733,7 +41868,7 @@ async function startDevServer(args) {
   const server = http.createServer(async (req, res) => {
     const url2 = req.url ?? "/";
     const pathname = url2.split("?")[0];
-    if (req.method === "GET" && (pathname === "/" || pathname === "/index.html")) {
+    if (servesWrapperPage(req.method, pathname)) {
       res.writeHead(200, {
         "Content-Type": "text/html; charset=utf-8",
         "Cache-Control": "no-cache, no-store, must-revalidate"
@@ -43390,6 +43525,7 @@ __export(expression_string_exports, {
   capitalize: () => capitalize,
   contains: () => contains,
   endsWith: () => endsWith,
+  formatDecimal: () => formatDecimal,
   formatNumber: () => formatNumber,
   join: () => join3,
   length: () => length,
@@ -43405,6 +43541,18 @@ __export(expression_string_exports, {
   trim: () => trim,
   upper: () => upper
 });
+
+// ../shared/src/expression_locale.ts
+function isUsableLocale(locale) {
+  try {
+    Intl.NumberFormat.supportedLocalesOf(locale);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// ../shared/src/expression_string.ts
 function join3(arr, separator) {
   if (arr == null) return "";
   if (!Array.isArray(arr)) {
@@ -43637,10 +43785,29 @@ function formatNumber(value, decimals) {
   if (typeof value !== "number" || Number.isNaN(value)) {
     throw new Error("formatNumber: expected number, got " + typeof value);
   }
+  assertDecimals(decimals, "formatNumber");
+  return value.toFixed(decimals);
+}
+function formatDecimal(value, decimals, locale) {
+  if (value == null) return "";
+  if (typeof value !== "number" || Number.isNaN(value)) {
+    throw new Error("formatDecimal: expected number, got " + typeof value);
+  }
+  assertDecimals(decimals, "formatDecimal");
+  if (typeof locale !== "string" || locale === "" || !isUsableLocale(locale)) {
+    throw new Error(
+      `formatDecimal(value, decimals, locale) requires a locale tag. Got ${JSON.stringify(locale)}. Example: formatDecimal(151000, 0, "vi-VN").`
+    );
+  }
+  return new Intl.NumberFormat(locale, {
+    minimumFractionDigits: decimals,
+    maximumFractionDigits: decimals
+  }).format(value);
+}
+function assertDecimals(decimals, funcName) {
   if (!Number.isInteger(decimals) || decimals < 0 || decimals > 100) {
-    throw new Error("formatNumber: decimals must be an integer between 0 and 100");
+    throw new Error(`${funcName}: decimals must be an integer between 0 and 100`);
   }
-  return value.toFixed(decimals);
 }
 
 // ../shared/src/expression_math.ts
@@ -44053,7 +44220,7 @@ function coalesce(...values2) {
   for (const val of values2) {
     if (val != null) return val;
   }
-  return void 0;
+  return null;
 }
 function toNumber(val) {
   if (val == null) return null;
@@ -44122,6 +44289,15 @@ function parseDateStringInTimezone(dateStr, timezone) {
   const zonedDate = new TZDate(year, month, day, hour, minute, second, ms, timezone);
   return new Date(zonedDate.getTime());
 }
+function isDayOnly(date5) {
+  return typeof date5 === "string" && /^\d{4}(?:-\d{2}(?:-\d{2})?)?$/.test(date5);
+}
+function compareCalendarDays(left, right, timezone) {
+  if (timezone) {
+    return differenceInCalendarDays(new TZDate(left, timezone), new TZDate(right, timezone));
+  }
+  return differenceInCalendarDays(left, right);
+}
 function normalizeDate(date5, timezone) {
   if (date5 instanceof Date) {
     return date5;
@@ -44403,6 +44579,13 @@ function getDateExpressionFunctions(defaultTimezone) {
     // ========================================================================
     /**
      * Check if dateLeft is before dateRight. Returns false if either is null.
+     *
+     * A DAY-precision operand (a `date` field, which holds no time) compares at
+     * DAY granularity in the workspace timezone. Resolving the day to midnight
+     * and comparing instants made `isBefore({due}, now())` answer by the
+     * reader's offset: the deadline "had passed" from the first hour of its own
+     * day, and a countdown rendered from the same cell disagreed with the flag
+     * beside it. Two instants still compare as instants.
      */
     isBefore: (dateLeft, dateRight, timezone) => {
       if (dateLeft == null || dateLeft === "" || dateRight == null || dateRight === "") return false;
@@ -44412,10 +44595,14 @@ function getDateExpressionFunctions(defaultTimezone) {
       const tz = getTimezone(timezone);
       const left = normalizeDateWithValidation(dateLeft, tz, "isBefore");
       const right = normalizeDateWithValidation(dateRight, tz, "isBefore");
+      if (isDayOnly(dateLeft) || isDayOnly(dateRight)) {
+        return compareCalendarDays(left, right, tz) < 0;
+      }
       return isBefore(left, right);
     },
     /**
      * Check if dateLeft is after dateRight. Returns false if either is null.
+     * Day-precision operands compare at day granularity — see isBefore.
      */
     isAfter: (dateLeft, dateRight, timezone) => {
       if (dateLeft == null || dateLeft === "" || dateRight == null || dateRight === "") return false;
@@ -44425,6 +44612,9 @@ function getDateExpressionFunctions(defaultTimezone) {
       const tz = getTimezone(timezone);
       const left = normalizeDateWithValidation(dateLeft, tz, "isAfter");
       const right = normalizeDateWithValidation(dateRight, tz, "isAfter");
+      if (isDayOnly(dateLeft) || isDayOnly(dateRight)) {
+        return compareCalendarDays(left, right, tz) > 0;
+      }
       return isAfter(left, right);
     },
     /**
@@ -44465,6 +44655,9 @@ function getDateExpressionFunctions(defaultTimezone) {
     },
     /**
      * Check if a date is within a range (inclusive). Returns false if any input is null.
+     * It is the two comparisons above, so a day-precision operand anywhere in it
+     * puts the whole check at day granularity — otherwise `isWithinRange(d, a, b)`
+     * and `!isBefore(d, a) && !isAfter(d, b)` would answer differently.
      */
     isWithinRange: (date5, startDate, endDate, timezone) => {
       if (date5 == null || date5 === "" || startDate == null || startDate === "" || endDate == null || endDate === "") return false;
@@ -44476,6 +44669,9 @@ function getDateExpressionFunctions(defaultTimezone) {
       const normalizedDate = normalizeDateWithValidation(date5, tz, "isWithinRange");
       const normalizedStart = normalizeDateWithValidation(startDate, tz, "isWithinRange");
       const normalizedEnd = normalizeDateWithValidation(endDate, tz, "isWithinRange");
+      if (isDayOnly(date5) || isDayOnly(startDate) || isDayOnly(endDate)) {
+        return compareCalendarDays(normalizedDate, normalizedStart, tz) >= 0 && compareCalendarDays(normalizedDate, normalizedEnd, tz) <= 0;
+      }
       return isWithinInterval(normalizedDate, {
         start: normalizedStart,
         end: normalizedEnd
@@ -46967,9 +47163,12 @@ function walkToolInvocation(call, scope, opts, allowWaits) {
   const input = walkToolInputObject(arg, scope);
   return { tool_name: name, input };
 }
+var TOOL_INPUT_ARRAY_SPREAD = "Spread is not supported inside a tool input. Write concat(<array>, <array>) here, or bind the merged array first (const xs = [...a, ...b];) and pass xs.";
+var TOOL_INPUT_OBJECT_SPREAD = "Spread is not supported inside a tool input. Bind the merged object first (const x = { ...a, b: 1 };) and pass x.";
 function walkToolInputObject(obj, scope) {
   const out = {};
   for (const p of obj.properties) {
+    if (p.type === "SpreadElement") fail2(p, TOOL_INPUT_OBJECT_SPREAD, "spread_element");
     if (p.type !== "ObjectProperty") fail2(p, "Tool kwargs must be plain key: value pairs.");
     if (p.computed) fail2(p, "Computed property keys are not supported.", "computed_key");
     const key = p.key.type === "StringLiteral" ? p.key.value : p.key.type === "Identifier" ? p.key.name : null;
@@ -46982,6 +47181,7 @@ function walkToolInputValue(node, scope) {
   if (node.type === "ObjectExpression") {
     const inner = {};
     for (const p of node.properties) {
+      if (p.type === "SpreadElement") fail2(p, TOOL_INPUT_OBJECT_SPREAD, "spread_element");
       if (p.type !== "ObjectProperty") fail2(p, "Tool kwargs must be plain key: value pairs.");
       if (p.computed) fail2(p, "Computed property keys are not supported.");
       const key = p.key.type === "StringLiteral" ? p.key.value : p.key.type === "Identifier" ? p.key.name : null;
@@ -46994,7 +47194,7 @@ function walkToolInputValue(node, scope) {
     const arr = [];
     for (const elem of node.elements) {
       if (elem === null) fail2(node, "Sparse arrays are not supported.", "sparse_array");
-      if (elem.type === "SpreadElement") fail2(elem, "Spread/rest is not supported.", "spread_element");
+      if (elem.type === "SpreadElement") fail2(elem, TOOL_INPUT_ARRAY_SPREAD, "spread_element");
       arr.push(walkToolInputValue(elem, scope));
     }
     return arr;
@@ -47504,6 +47704,7 @@ function generatePrefixedId(prefix) {
   return `${prefix}_${nanoid3()}`;
 }
 var RECORD_ID_PATTERN = new RegExp(`^rec_[${ID_ALPHABET}]{${ID_LENGTH}}$`);
+var FILE_ID_PATTERN = new RegExp(`^fil_[${ID_ALPHABET}]{${ID_LENGTH}}$`);
 function generateWorkspaceId() {
   return generatePrefixedId("wsp");
 }
@@ -47676,6 +47877,137 @@ async function requireLatestNpmVersion(packageName, { timeoutMs = 1e4 } = {}) {
   return version2;
 }
 
+// src/line_diff.ts
+function lineDiff(before, after) {
+  const rows = before.length;
+  const cols = after.length;
+  const lcs = Array.from(
+    { length: rows + 1 },
+    () => Array.from({ length: cols + 1 }, () => 0)
+  );
+  for (let i2 = rows - 1; i2 >= 0; i2--) {
+    for (let j2 = cols - 1; j2 >= 0; j2--) {
+      lcs[i2][j2] = before[i2] === after[j2] ? lcs[i2 + 1][j2 + 1] + 1 : Math.max(lcs[i2 + 1][j2], lcs[i2][j2 + 1]);
+    }
+  }
+  const out = [];
+  let i = 0;
+  let j = 0;
+  while (i < rows && j < cols) {
+    if (before[i] === after[j]) {
+      out.push({ kind: "same", text: before[i] });
+      i++;
+      j++;
+    } else if (lcs[i + 1][j] >= lcs[i][j + 1]) {
+      out.push({ kind: "removed", text: before[i] });
+      i++;
+    } else {
+      out.push({ kind: "added", text: after[j] });
+      j++;
+    }
+  }
+  for (; i < rows; i++) out.push({ kind: "removed", text: before[i] });
+  for (; j < cols; j++) out.push({ kind: "added", text: after[j] });
+  return out;
+}
+var MARK = { same: " ", removed: "-", added: "+" };
+function renderLineDiff(before, after, opts = {}) {
+  const context = opts.context ?? 3;
+  const lines = lineDiff(before.split("\n"), after.split("\n"));
+  const changed = lines.map((line) => line.kind !== "same");
+  const keep = lines.map(
+    (_, index) => changed.slice(Math.max(0, index - context), index + context + 1).some(Boolean)
+  );
+  const out = [];
+  let elided = false;
+  for (const [index, line] of lines.entries()) {
+    if (!keep[index]) {
+      elided = true;
+      continue;
+    }
+    if (elided && out.length > 0) out.push("  \u2026");
+    elided = false;
+    out.push(`${MARK[line.kind]} ${line.text}`);
+  }
+  return out.join("\n");
+}
+
+// src/vite_config_text.ts
+var VITE_CONFIG_NAMES = [
+  "vite.config.ts",
+  "vite.config.mts",
+  "vite.config.cts",
+  "vite.config.js",
+  "vite.config.mjs",
+  "vite.config.cjs"
+];
+function codeOnly(source) {
+  let out = "";
+  let i = 0;
+  while (i < source.length) {
+    const two = source.slice(i, i + 2);
+    if (two === "//") {
+      while (i < source.length && source[i] !== "\n") {
+        out += " ";
+        i++;
+      }
+      continue;
+    }
+    if (two === "/*") {
+      while (i < source.length && source.slice(i, i + 2) !== "*/") {
+        out += source[i] === "\n" ? "\n" : " ";
+        i++;
+      }
+      out += "  ";
+      i += 2;
+      continue;
+    }
+    const quote2 = source[i];
+    if (quote2 === '"' || quote2 === "'" || quote2 === "`") {
+      out += " ";
+      i++;
+      while (i < source.length && source[i] !== quote2) {
+        if (source[i] === "\\") {
+          out += "  ";
+          i += 2;
+          continue;
+        }
+        out += source[i] === "\n" ? "\n" : " ";
+        i++;
+      }
+      out += " ";
+      i++;
+      continue;
+    }
+    out += source[i];
+    i++;
+  }
+  return out;
+}
+function objectBlocks(code, key) {
+  const blocks = [];
+  const literal2 = key.replace(/[.*+?^${}()|[\]\\]/g, String.raw`\$&`);
+  for (const opener of code.matchAll(new RegExp(String.raw`\b${literal2}\s*:\s*\{`, "g"))) {
+    let depth = 1;
+    let i = opener.index + opener[0].length;
+    const start = i;
+    while (i < code.length && depth > 0) {
+      if (code[i] === "{") depth++;
+      else if (code[i] === "}") depth--;
+      i++;
+    }
+    blocks.push(code.slice(start, i));
+  }
+  return blocks;
+}
+function declaredVitePort(config2) {
+  for (const block of objectBlocks(codeOnly(config2), "server")) {
+    const found = block.match(/(?:^|[{,;])\s*port\s*:\s*(\d+)\s*(?:[,}]|$)/);
+    if (found) return Number(found[1]);
+  }
+  return null;
+}
+
 // ../shared/src/schemas/workflow_issues.ts
 var issueSchema = external_exports.object({
   source: external_exports.enum(["parse", "typecheck", "resolve", "lint", "structural"]),
@@ -48300,16 +48632,16 @@ function writeAppMeta(projectDir, meta3) {
   pkg.lotics = { ...meta3, ...preserved };
   fs11.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + "\n");
 }
-function writeWorkflowOutputs(projectDir, alias, outputs) {
+function writeWorkflowDeclarationFields(projectDir, alias, fields) {
   const pkgPath = path12.join(projectDir, "package.json");
   const pkg = JSON.parse(fs11.readFileSync(pkgPath, "utf-8"));
   const declaration = pkg.lotics?.workflows?.[alias];
   if (!declaration) {
     throw new Error(
-      `package.json#lotics.workflows.${alias} disappeared before the derived-outputs write-back.`
+      `package.json#lotics.workflows.${alias} disappeared before the post-set write-back.`
     );
   }
-  declaration.outputs = outputs;
+  Object.assign(declaration, fields);
   fs11.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + "\n");
 }
 function workflowBodyDrift(projectDir, workflows, synced = {}) {
@@ -48419,13 +48751,22 @@ function writeAppDtsKitLinks(projectDir) {
   writeDevLinkTsconfig(projectDir);
   writeKitTypeAugmentation(projectDir);
 }
-function writeAppDts(projectDir, manifest) {
+function writeAppDts(projectDir, manifest, optionsByFieldKey) {
   const dotLotics = path12.join(projectDir, ".lotics");
   fs11.mkdirSync(dotLotics, { recursive: true });
   const written = [
-    [path12.join(dotLotics, "app_workflows.d.ts"), generateAppWorkflowsDts(manifest.workflows)],
-    [path12.join(dotLotics, "app_queries.d.ts"), generateAppQueriesDts(manifest.queries)],
-    [path12.join(dotLotics, "app_agents.d.ts"), generateAppAgentsDts(manifest.agents)]
+    [
+      path12.join(dotLotics, "app_workflows.d.ts"),
+      generateAppWorkflowsDts(manifest.workflows, optionsByFieldKey)
+    ],
+    [
+      path12.join(dotLotics, "app_queries.d.ts"),
+      generateAppQueriesDts(manifest.queries, optionsByFieldKey)
+    ],
+    [
+      path12.join(dotLotics, "app_agents.d.ts"),
+      generateAppAgentsDts(manifest.agents, optionsByFieldKey)
+    ]
   ];
   for (const [file2, content] of written) fs11.writeFileSync(file2, content);
   writeAppDtsKitLinks(projectDir);
@@ -48448,34 +48789,36 @@ function writeAppFields(projectDir, tables) {
   fs11.writeFileSync(file2, generateAppFields(tables));
   return file2;
 }
-async function writeGeneratedAppFields(client, projectDir, app, queries) {
+async function writeGeneratedAppFields(client, projectDir, app, manifest) {
+  const queries = manifest.queries ?? {};
   if (client.viewAsMemberId) {
     console.error(
       `\u26A0 Skipped .lotics/app_fields.ts \u2014 running with --view-as ${client.viewAsMemberId}. The schema is read as that member, so any table they cannot see would be silently missing from F/OPT. Re-run without --view-as to regenerate it.`
     );
     return;
   }
+  let tables;
   try {
-    {
-      const tableIds = resolveCodegenTableIds(projectDir, queries);
-      const tables = await client.getWorkspaceSchema(tableIds);
-      const missing = tableIds.filter((id) => !tables.some((t) => t.id === id));
-      if (missing.length > 0) {
-        console.error(
-          `\u26A0 Skipped .lotics/app_fields.ts \u2014 ${missing.length} table(s) the app queries could not be read: ${missing.join(", ")}.
+    const tableIds = resolveCodegenTableIds(projectDir, queries);
+    tables = await client.getWorkspaceSchema(tableIds);
+    const missing = tableIds.filter((id) => !tables.some((t) => t.id === id));
+    if (missing.length > 0) {
+      console.error(
+        `\u26A0 Skipped .lotics/app_fields.ts \u2014 ${missing.length} table(s) the app queries could not be read: ${missing.join(", ")}.
   Writing anyway would bake a narrowed F/OPT map that compiles and then throws at runtime. Check this key's access to those tables.
   An existing app_fields.ts is kept and still works; a project that has none yet will fail to BUILD until this resolves \u2014 which is the loud failure, not a new problem.`
-        );
-        return;
-      }
-      const fieldsPath = writeAppFields(projectDir, tables);
-      note(
-        `Wrote ${fieldsPath} (baked form \u2014 bespoke; ${tables.length} table${tables.length === 1 ? "" : "s"})`
       );
+      return;
     }
+    const fieldsPath = writeAppFields(projectDir, tables);
+    note(
+      `Wrote ${fieldsPath} (baked form \u2014 bespoke; ${tables.length} table${tables.length === 1 ? "" : "s"})`
+    );
   } catch (err) {
     warnAppFieldsUnwritten(projectDir, err);
+    return;
   }
+  writeAppDts(projectDir, manifest, selectOptionsByFieldKey(tables));
 }
 function warnAppFieldsUnwritten(projectDir, err) {
   const reason = err instanceof Error ? err.message : String(err);
@@ -48519,6 +48862,13 @@ function installedKitVersion(projectDir, pkg) {
     return null;
   }
 }
+function installedKitMajorAtLeast(projectDir, pkg, major) {
+  const version2 = installedKitVersion(projectDir, pkg);
+  if (version2 === null) return false;
+  const installedMajor = parseInt(version2.split(".")[0], 10);
+  if (Number.isNaN(installedMajor)) return false;
+  return installedMajor >= major;
+}
 async function publishedKitVersion(pkg) {
   const controller = new AbortController();
   const timeout = setTimeout(() => controller.abort(), 3e3);
@@ -48674,6 +49024,7 @@ async function appCodegen(args) {
   for (const alias of pruneOrphanWorkflowGlobals(projectDir, declared)) {
     console.error(`Removed stale workflow types for ${alias} \u2014 no longer in package.json#lotics.workflows`);
   }
+  reportUndeclaredCalledAliases(calledAppAliases(readAppSourceText(projectDir)), meta3);
   for (const alias of orphanWorkflowBodies(projectDir, declared)) {
     console.error(
       `\u26A0 ${path12.join(WORKFLOWS_DIR, `${alias}.ts`)} is not declared in package.json#lotics.workflows \u2014 'workflow check' and 'workflow set' both skip it. Declare the alias or delete the file.`
@@ -48688,12 +49039,11 @@ async function appCodegen(args) {
   let app = null;
   try {
     app = await args.client.getApp(meta3.app_id);
-    await writeGeneratedAppFields(
-      args.client,
-      projectDir,
-      { app_id: meta3.app_id },
-      meta3.queries ?? {}
-    );
+    await writeGeneratedAppFields(args.client, projectDir, { app_id: meta3.app_id }, {
+      workflows: meta3.workflows,
+      queries: meta3.queries,
+      agents: meta3.agents
+    });
   } catch (err) {
     warnAppFieldsUnwritten(projectDir, err);
   }
@@ -48722,17 +49072,24 @@ async function refreshWorkflowGlobals(client, projectDir, app_id, workflows) {
       alias,
       toWorkflowDtsDeclaration(declaration)
     );
-    if (refreshed) console.error(`Refreshed workflow types for ${alias}`);
+    if (refreshed.kind === "refreshed") {
+      console.error(`Refreshed workflow types for ${alias}`);
+      continue;
+    }
+    console.error(
+      `Wrote workflow types for ${alias} \u2014 ${refreshed.hasFile ? "its body file is empty" : `no body at ${path12.join(WORKFLOWS_DIR, `${alias}.ts`)}`}. Write the body there, then 'lotics app workflow check ${alias}'.`
+    );
   }
 }
 async function refreshWorkflowTypes(client, projectDir, app_id, alias, declaration) {
   const file2 = workflowFilePath(projectDir, alias);
-  if (!fs11.existsSync(file2)) return false;
-  const body = stripWorkflowHeader(fs11.readFileSync(file2, "utf-8"));
-  if (body.trim() === "") return false;
+  const body = fs11.existsSync(file2) ? stripWorkflowHeader(fs11.readFileSync(file2, "utf-8")) : "";
   const envelope2 = await fetchWorkflowGlobals(client, projectDir, app_id, alias, declaration);
+  if (body.trim() === "") {
+    return { kind: "types_only", hasFile: fs11.existsSync(file2) };
+  }
   writeWorkflowFile(projectDir, alias, body, envelope2);
-  return true;
+  return { kind: "refreshed" };
 }
 function readPriorStamp(projectDir) {
   const pkgPath = path12.join(projectDir, "package.json");
@@ -48840,7 +49197,7 @@ async function appCreate(client, args) {
   await materializeScaffold(targetPath, files);
   if (plan !== null) {
     writeAppDts(targetPath, { queries: plan.queries });
-    await writeGeneratedAppFields(client, targetPath, { app_id: app.id }, plan.queries);
+    await writeGeneratedAppFields(client, targetPath, { app_id: app.id }, { queries: plan.queries });
     if (!fs11.existsSync(path12.join(targetPath, ".lotics", "app_fields.ts"))) {
       throw new Error(
         `.lotics/app_fields.ts could not be written (the warning above says why), and every generated screen reads it \u2014 resolve that, then \`cd ${path12.relative(process.cwd(), targetPath) || "."} && lotics app codegen && lotics app deploy\`.`
@@ -49059,12 +49416,11 @@ async function hydrateAppProject(client, targetPath, app, opts) {
     const sha = declarationSha(declaration);
     writeSynced(targetPath, "queries", alias, { content: sha, live: sha });
   }
-  await writeGeneratedAppFields(
-    client,
-    targetPath,
-    { app_id: app.id },
-    app.queries ?? {}
-  );
+  await writeGeneratedAppFields(client, targetPath, { app_id: app.id }, {
+    workflows: toManifestWorkflows(app.workflows ?? {}),
+    queries: app.queries ?? {},
+    agents: toManifestAgents(app.agents ?? {})
+  });
   const workflows = app.workflows ?? {};
   if (Object.keys(workflows).length > 0) {
     const { written, kept, unseenLive } = await writeWorkflowFiles(
@@ -49257,12 +49613,11 @@ async function appDeploy(client, args) {
   warnIfProjectFootguns(projectDir, sourceText);
   writeAppDts(projectDir, { workflows: meta3.workflows, queries: meta3.queries, agents: meta3.agents });
   try {
-    await writeGeneratedAppFields(
-      client,
-      projectDir,
-      { app_id: meta3.app_id },
-      meta3.queries ?? {}
-    );
+    await writeGeneratedAppFields(client, projectDir, { app_id: meta3.app_id }, {
+      workflows: meta3.workflows,
+      queries: meta3.queries,
+      agents: meta3.agents
+    });
   } catch (err) {
     warn(
       `\u26A0 Could not regenerate .lotics/app_fields.ts (${err.message}).
@@ -49336,7 +49691,8 @@ async function appDeploy(client, args) {
       try {
         const drifted = staleWorkflowGlobals(projectDir, meta3.workflows ?? {});
         for (const { alias, declaration } of drifted) {
-          if (await refreshWorkflowTypes(client, projectDir, meta3.app_id, alias, declaration)) {
+          const refreshed = await refreshWorkflowTypes(client, projectDir, meta3.app_id, alias, declaration);
+          if (refreshed.kind === "refreshed") {
             note(`Refreshed workflow types for ${alias} \u2014 this deploy moved its declaration.`);
           }
         }
@@ -49356,10 +49712,16 @@ async function appDeploy(client, args) {
         warnIfInertAgentTools(liveAfter);
       }
       if (liveAfter) {
-        const orphans = orphanedBindings(called, liveAfter, meta3.bundle_calls);
+        const undeclared = undeclaredBindings({
+          meta: meta3,
+          synced: readSynced(projectDir),
+          live: liveAfter
+        });
+        const lostCallSite = orphanedBindings(called, liveAfter, meta3.bundle_calls);
+        const orphans = allOrphans(lostCallSite, undeclared);
         let outstanding = orphans;
         if (args.prune) {
-          if (!meta3.bundle_calls) {
+          if (!meta3.bundle_calls && nothingOrphaned(undeclared)) {
             note(
               "Nothing to prune yet: this project has no record of what the previous bundle called, so there is no way to tell a retired binding from an agent-facing one. This deploy records it; the next can compare."
             );
@@ -49369,12 +49731,14 @@ async function appDeploy(client, args) {
             projectDir,
             { app_id: meta3.app_id },
             orphans,
-            called.dynamic
+            undeclared,
+            called.dynamic,
+            args.pruneInvoked ?? []
           );
         } else {
-          warnAboutOrphanedBindings(called, liveAfter, meta3.bundle_calls);
+          warnAboutOrphanedBindings(called, liveAfter, meta3.bundle_calls, undeclared);
         }
-        const settled = outstanding.queries.length === 0 && outstanding.workflows.length === 0 && outstanding.agents.length === 0;
+        const settled = nothingOrphaned(bothOf(outstanding, lostCallSite));
         if (settled) {
           writeAppMeta(projectDir, {
             ...readAppMeta(projectDir),
@@ -49442,8 +49806,14 @@ async function appCheck(client, args = {}) {
   writeAppDts(projectDir, { workflows: meta3.workflows, queries: meta3.queries, agents: meta3.agents });
   const sourceText = readAppSourceText(projectDir);
   const called = calledAppAliases(sourceText);
+  const undeclaredCalls = reportUndeclaredCalledAliases(called, meta3);
   warnAboutDevLink(projectDir, "deploy");
-  warnAboutOrphanedBindings(called, app, meta3.bundle_calls);
+  warnAboutOrphanedBindings(
+    called,
+    app,
+    meta3.bundle_calls,
+    undeclaredBindings({ meta: meta3, synced: readSynced(projectDir), live: app })
+  );
   const pending = pendingBindings({
     projectDir,
     meta: meta3,
@@ -49459,6 +49829,7 @@ async function appCheck(client, args = {}) {
   warnIfProjectFootguns(projectDir, sourceText);
   warnIfUnbranded(app);
   warnIfUndescribed(app);
+  await warnIfWorkflowsUndescribed(client, meta3);
   const unportable = scanProjectForIds(projectDir);
   reportPortabilityIds(unportable);
   const bodiesFailing = await countFailingWorkflowBodies(client, projectDir, meta3);
@@ -49485,13 +49856,43 @@ async function appCheck(client, args = {}) {
     });
     console.error(formatScreenFindings(report));
   }
-  if (!nothingPending(pending) || unportable.length > 0 || bodiesFailing > 0 || typesFailing || screenFindings > 0) {
+  if (!nothingPending(pending) || unportable.length > 0 || undeclaredCalls > 0 || bodiesFailing > 0 || typesFailing || screenFindings > 0) {
     process.exit(1);
   }
   console.error(
     "Checked the app's types, bindings, capabilities, agent schemas, workflow bodies and id portability" + (args.screens === true ? ", and every screen at 1280 and 375" : "") + " \u2014 nothing blocking."
   );
 }
+var capabilityAliasesSchema = zod_default.object({
+  aliases: zod_default.array(
+    zod_default.object({
+      alias: zod_default.string(),
+      kind: zod_default.string(),
+      description: zod_default.string().nullish()
+    })
+  ).optional()
+});
+async function warnIfWorkflowsUndescribed(client, meta3) {
+  let res;
+  try {
+    res = await client.getAppCapabilities(meta3.app_id);
+  } catch {
+    return;
+  }
+  if (res.error) return;
+  const parsed = capabilityAliasesSchema.safeParse(res.result);
+  if (!parsed.success || parsed.data.aliases === void 0) return;
+  const workflows = parsed.data.aliases.filter((entry) => entry.kind === "workflow");
+  const undescribed = workflows.filter((entry) => entry.description == null || entry.description === "").map((entry) => entry.alias);
+  if (undescribed.length === 0) return;
+  console.error(
+    `
+\u26A0 ${undescribed.length} of ${workflows.length} workflow${workflows.length === 1 ? "" : "s"} are offered with no description: ${undescribed.join(", ")}.
+  That text is what chat and MCP read to choose between aliases; without it they choose by
+  the alias. Write one line per workflow in
+  package.json#lotics.workflows.<alias>.description, then 'lotics app workflow set <alias>'.`
+  );
+}
 async function countFailingWorkflowBodies(client, projectDir, meta3) {
   const bound = Object.keys(meta3.workflows ?? {});
   const typed = bound.filter((alias) => fs11.existsSync(workflowGlobalsPath(projectDir, alias)));
@@ -49511,8 +49912,29 @@ async function countFailingWorkflowBodies(client, projectDir, meta3) {
   }
   const results = checkWorkflowBodies(await loadProjectTypescript(projectDir), toCheck);
   printWorkflowCheckResults(projectDir, results);
+  reportStoredBodiesOwedMigration(
+    projectDir,
+    results.filter((r) => r.issues.length > 0).map((r) => r.alias)
+  );
   return results.filter((r) => r.issues.length > 0).length;
 }
+function reportStoredBodiesOwedMigration(projectDir, failing) {
+  const baselines = readSynced(projectDir).workflows;
+  const unedited = failing.filter((alias) => {
+    const baseline = baselines[alias]?.content;
+    if (baseline === void 0) return false;
+    const file2 = workflowFilePath(projectDir, alias);
+    if (!fs11.existsSync(file2)) return false;
+    return contentSha(stripWorkflowHeader(fs11.readFileSync(file2, "utf-8"))) === baseline;
+  });
+  if (unedited.length === 0) return;
+  console.error(
+    `
+\u26A0 ${unedited.length} of those bod${unedited.length === 1 ? "y is" : "ies are"} unchanged since this checkout pushed or pulled ${unedited.length === 1 ? "it" : "them"} \u2014 ${unedited.join(", ")}. That is the body the server is RUNNING, so this is a migration it is owed, not a stale tree.
+  The usual cause is a grammar move: a link field reads as an id array, so drop '.id' or descend with linked(\u2026).
+  Edit each body, then 'lotics app workflow set <alias>'. Until then the stored body keeps running as it always has.`
+  );
+}
 async function pushPendingBindings(client, projectDir, pending) {
   const plan = [
     ...pending.queries.map((alias) => `query ${alias}`),
@@ -49641,36 +50063,64 @@ function orphanedBindings(called, live, previouslyCalled) {
     referenced
   );
 }
-function warnAboutOrphanedBindings(called, live, previouslyCalled) {
-  const orphans = orphanedBindings(called, live, previouslyCalled);
+function undeclaredBindings(args) {
+  const { meta: meta3, synced, live } = args;
+  const removed = (kind, declared, bound) => Object.keys(bound ?? {}).filter((alias) => synced[kind][alias] !== void 0 && (declared ?? {})[alias] === void 0).sort();
+  return {
+    queries: removed("queries", meta3.queries, live.queries),
+    workflows: removed("workflows", meta3.workflows, live.workflows),
+    agents: removed("agents", meta3.agents, live.agents)
+  };
+}
+function nothingOrphaned(orphans) {
+  return orphans.queries.length === 0 && orphans.workflows.length === 0 && orphans.agents.length === 0;
+}
+function allOrphans(lostCallSite, undeclared) {
+  const merge3 = (a, b) => [.../* @__PURE__ */ new Set([...a, ...b])].sort();
+  return {
+    queries: merge3(lostCallSite.queries, undeclared.queries),
+    workflows: merge3(lostCallSite.workflows, undeclared.workflows),
+    agents: merge3(lostCallSite.agents, undeclared.agents)
+  };
+}
+function bothOf(a, b) {
+  const both = (x, y) => x.filter((alias) => y.includes(alias));
+  return {
+    queries: both(a.queries, b.queries),
+    workflows: both(a.workflows, b.workflows),
+    agents: both(a.agents, b.agents)
+  };
+}
+function warnAboutOrphanedBindings(called, live, previouslyCalled, undeclared) {
+  const lostCallSite = orphanedBindings(called, live, previouslyCalled);
+  const label = (kind, alias, undeclaredOfKind) => `  \u2022 ${kind} ${alias}${undeclaredOfKind.includes(alias) ? " (no longer declared in package.json)" : ""}`;
+  const merged = allOrphans(lostCallSite, undeclared);
   const lines = [
-    ...orphans.queries.map((a) => `  \u2022 query ${a}`),
-    ...orphans.workflows.map((a) => `  \u2022 workflow ${a}`),
-    ...orphans.agents.map((a) => `  \u2022 agent ${a}`)
+    ...merged.queries.map((a) => label("query", a, undeclared.queries)),
+    ...merged.workflows.map((a) => label("workflow", a, undeclared.workflows)),
+    ...merged.agents.map((a) => label("agent", a, undeclared.agents))
   ];
   if (lines.length === 0) return 0;
+  const dynamicCaveat = called.dynamic.length > 0 && !nothingOrphaned(lostCallSite) ? `
+
+  This app computes an alias at runtime, so one of the bindings above still
+  declared in package.json may be called after all \u2014 \`--prune\` leaves those in
+  place. Make those call sites literal to prune them.` + (nothingOrphaned(undeclared) ? `` : ` The ones marked "no longer
+  declared" are unbound anyway.`) : ``;
   console.error(
     `
-\u26A0 ${lines.length} binding(s) still live that this bundle STOPPED calling:
-` + lines.join("\n") + (called.dynamic.length > 0 ? `
-
-  This app computes an alias at runtime, so one of these may be called after
-  all \u2014 and \`--prune\` therefore leaves them ALL in place. Make those call
-  sites literal to prune them.` : `
+\u26A0 ${lines.length} binding(s) still live that this project has retired:
+` + lines.join("\n") + `
 
-  Removing the call site does not unbind it, so it keeps serving. It also
-  stays published to chat and to MCP, which reach an alias with no call
-  site \u2014 so an agent can still invoke what you meant to retire.
-  To unbind: lotics app deploy --prune`)
+  Removing the call site or the declaration does not unbind it, so it keeps
+  serving. It also stays published to chat and to MCP, which reach an alias
+  with no call site \u2014 so an agent can still invoke what you meant to retire.
+  To unbind: lotics app deploy --prune` + dynamicCaveat
   );
   return lines.length;
 }
-async function pruneOrphanedBindings(client, projectDir, app, orphans, dynamic) {
-  const stillBound = {
-    queries: [],
-    workflows: [],
-    agents: []
-  };
+async function pruneOrphanedBindings(client, projectDir, app, orphans, undeclared, dynamic, pruneInvoked) {
+  const stillBound = { queries: [], workflows: [], agents: [] };
   const targets = [
     ...orphans.queries.map((alias) => ({
       tool: "remove_app_query",
@@ -49695,22 +50145,45 @@ async function pruneOrphanedBindings(client, projectDir, app, orphans, dynamic)
     }))
   ];
   if (targets.length === 0) return stillBound;
-  if (dynamic.length > 0) {
+  const deferred = dynamic.length > 0 ? targets.filter((t) => !undeclared[t.kind].includes(t.alias)) : [];
+  if (deferred.length > 0) {
     console.error(
       `
-\u26A0 Left ${targets.length} unused binding(s) in place: this app calls ${dynamic.join(" / ")} with an alias it computes at runtime, and a static scan cannot tell which binding that reaches \u2014 so any of these may be live:
-` + targets.map((t) => `    \u2022 ${t.label}`).join("\n") + `
+\u26A0 Left ${deferred.length} unused binding(s) in place: this app calls ${dynamic.join(" / ")} with an alias it computes at runtime, and a static scan cannot tell which binding that reaches \u2014 so any of these may be live:
+` + deferred.map((t) => `    \u2022 ${t.label}`).join("\n") + `
   Make those call sites literal and the next deploy will clean them up, or remove the ones you know are dead by hand.`
     );
-    for (const t of targets) stillBound[t.kind].push(t.alias);
-    return stillBound;
+    for (const t of deferred) stillBound[t.kind].push(t.alias);
   }
+  const prunable = targets.filter((t) => !deferred.includes(t));
+  if (prunable.length === 0) return stillBound;
   const tablesBefore = new Set(resolveCodegenTableIds(projectDir, readAppMeta(projectDir).queries ?? {}));
+  const notTargeted = pruneInvoked.filter(
+    (alias) => !prunable.some((t) => t.kind === "workflows" && t.alias === alias)
+  );
+  if (notTargeted.length > 0) {
+    console.error(
+      `  \u26A0 --prune-invoked named ${notTargeted.map((a) => `"${a}"`).join(", ")}, which this prune is not removing. The flag applies to a workflow alias this prune is unbinding.`
+    );
+  }
   let removedLocally = false;
-  for (const target of targets) {
-    const res = await client.execute(target.tool, { app_id: app.app_id, alias: target.alias });
+  for (const target of prunable) {
+    const overrideInvocationGuard = target.kind === "workflows" && pruneInvoked.includes(target.alias);
+    const res = await client.execute(target.tool, {
+      app_id: app.app_id,
+      alias: target.alias,
+      // Sent only for the aliases the operator named, so the default stays the
+      // guard: a run recorded against an alias means something outside the
+      // bundle reaches it.
+      ...overrideInvocationGuard ? { even_if_invoked: true } : {}
+    });
     if (res.error) {
       console.error(`  \u2717 could not unbind ${target.label} \u2014 ${res.error}`);
+      if (target.kind === "workflows" && !overrideInvocationGuard) {
+        console.error(
+          `      If nothing outside this bundle calls it: lotics app deploy --prune --prune-invoked ${target.alias} -m "<message>"`
+        );
+      }
       stillBound[target.kind].push(target.alias);
       continue;
     }
@@ -49753,7 +50226,11 @@ async function pruneOrphanedBindings(client, projectDir, app, orphans, dynamic)
             `  \u26A0 .lotics/app_fields.ts no longer covers ${dropped.join(", ")} \u2014 ${dropped.length === 1 ? "that table was" : "those tables were"} named only by the pruned quer${orphans.queries.length === 1 ? "y" : "ies"}. If your source still uses F/OPT for ${dropped.length === 1 ? "it" : "them"}, add ${dropped.map((id) => `"${id}"`).join(", ")} to package.json#lotics.codegen.tables and re-run lotics app codegen.`
           );
         }
-        await writeGeneratedAppFields(client, projectDir, app, meta3.queries ?? {});
+        await writeGeneratedAppFields(client, projectDir, app, {
+          workflows: meta3.workflows,
+          queries: meta3.queries,
+          agents: meta3.agents
+        });
       }
     } catch (err) {
       console.error(
@@ -49859,72 +50336,10 @@ function warnIfUndeclaredCapabilities(sourceText, capabilities) {
   Add to package.json#lotics.capabilities:  ${block}`
   );
 }
-var VITE_CONFIG_NAMES = [
-  "vite.config.ts",
-  "vite.config.mts",
-  "vite.config.cts",
-  "vite.config.js",
-  "vite.config.mjs",
-  "vite.config.cjs"
-];
-function codeOnly(source) {
-  let out = "";
-  let i = 0;
-  while (i < source.length) {
-    const two = source.slice(i, i + 2);
-    if (two === "//") {
-      while (i < source.length && source[i] !== "\n") {
-        out += " ";
-        i++;
-      }
-      continue;
-    }
-    if (two === "/*") {
-      while (i < source.length && source.slice(i, i + 2) !== "*/") {
-        out += source[i] === "\n" ? "\n" : " ";
-        i++;
-      }
-      out += "  ";
-      i += 2;
-      continue;
-    }
-    const quote2 = source[i];
-    if (quote2 === '"' || quote2 === "'" || quote2 === "`") {
-      out += " ";
-      i++;
-      while (i < source.length && source[i] !== quote2) {
-        if (source[i] === "\\") {
-          out += "  ";
-          i += 2;
-          continue;
-        }
-        out += source[i] === "\n" ? "\n" : " ";
-        i++;
-      }
-      out += " ";
-      i++;
-      continue;
-    }
-    out += source[i];
-    i++;
-  }
-  return out;
-}
 function defineBlockKeys(config2) {
-  const code = codeOnly(config2);
   const keys2 = /* @__PURE__ */ new Set();
-  for (const opener of code.matchAll(/\bdefine\s*:\s*\{/g)) {
-    let depth = 1;
-    let i = opener.index + opener[0].length;
-    const start = i;
-    while (i < code.length && depth > 0) {
-      if (code[i] === "{") depth++;
-      else if (code[i] === "}") depth--;
-      i++;
-    }
-    for (const key of code.slice(start, i).matchAll(/(?:^|[{,])\s*([A-Za-z_$][\w$]*)\s*:/g)) {
-      keys2.add(key[1]);
-    }
+  for (const block of objectBlocks(codeOnly(config2), "define")) {
+    for (const key of block.matchAll(/(?:^|[{,])\s*([A-Za-z_$][\w$]*)\s*:/g)) keys2.add(key[1]);
   }
   return keys2;
 }
@@ -49974,6 +50389,22 @@ function warnIfProjectFootguns(projectDir, sourceText) {
       );
     }
   }
+  if (configName !== void 0 && installedKitMajorAtLeast(projectDir, "@lotics/ui", 48)) {
+    const config2 = fs11.readFileSync(path12.join(projectDir, configName), "utf-8");
+    const handWritten = objectBlocks(codeOnly(config2), "optimizeDeps").some(
+      (block) => /(?:^|[{,;])\s*include\s*:/.test(block)
+    );
+    if (handWritten) {
+      lines.push(
+        [
+          `  \u2022 ${configName} sets optimizeDeps.include \u2014 @lotics/ui 48 ships built ESM, so Vite`,
+          "    pre-bundles it unaided. The list cannot help and a stale entry still fails the",
+          "    dev boot ('Failed to resolve dependency: \u2026, present in optimizeDeps.include').",
+          "      delete the optimizeDeps block (and any loticsOptimizeDeps import \u2014 48 has none)"
+        ].join("\n")
+      );
+    }
+  }
   if (/\bwindow\.open\s*\(/.test(sourceText)) {
     lines.push(
       [
@@ -50032,6 +50463,35 @@ function warnIfInertAgentTools(app) {
 function anyToolReaches(tools, field) {
   return DECLARATION_BOUND_TOOLS.some((g) => g.field === field && tools.includes(g.tool));
 }
+function undeclaredCalledAliases(called, meta3) {
+  const declared = {
+    queries: new Set(Object.keys(meta3.queries ?? {})),
+    workflows: new Set(Object.keys(meta3.workflows ?? {}))
+  };
+  return {
+    queries: [...new Set(called.queries)].filter((a) => !declared.queries.has(a)).sort(),
+    workflows: [...new Set(called.workflows)].filter((a) => !declared.workflows.has(a)).sort()
+  };
+}
+function reportUndeclaredCalledAliases(called, meta3) {
+  const undeclared = undeclaredCalledAliases(called, meta3);
+  const lines = [
+    ...undeclared.queries.map((a) => `  \u2022 useQuery("${a}") \u2014 no package.json#lotics.queries.${a}`),
+    ...undeclared.workflows.map(
+      (a) => `  \u2022 useWorkflow("${a}") \u2014 no package.json#lotics.workflows.${a}`
+    )
+  ];
+  if (lines.length === 0) return 0;
+  console.error(
+    `
+\u2717 ${lines.length} call site${lines.length === 1 ? "" : "s"} name${lines.length === 1 ? "s" : ""} an alias this project does not declare:
+` + lines.join("\n") + `
+
+  These COMPILE \u2014 the hooks keep a bare-string overload for a computed alias \u2014 and fail
+  when the screen renders. Declare the alias, or fix the call site.`
+  );
+  return lines.length;
+}
 function warnIfUnboundAliases(app, called) {
   const {
     queries: unboundQueries,
@@ -50055,10 +50515,23 @@ function warnIfUnboundAliases(app, called) {
   for (const alias of unboundAgents) lines.push(`  \u2022 agent "${alias}"  \u2192  bind with set_app_agent (lotics run set_app_agent \u2026)`);
   console.error(lines.join("\n"));
 }
+function resolveDeclaredVitePort(projectDir, flagPort) {
+  const configName = VITE_CONFIG_NAMES.find((name) => fs11.existsSync(path12.join(projectDir, name)));
+  const declared = configName === void 0 ? null : declaredVitePort(fs11.readFileSync(path12.join(projectDir, configName), "utf-8"));
+  if (declared === null) return flagPort;
+  if (flagPort === void 0) return declared;
+  if (flagPort !== declared) {
+    console.error(
+      `\u26A0 --vite-port=${flagPort} overrides ${configName}'s server.port ${declared}. Vite is bound to ${flagPort}; drop the flag to use the config's port.`
+    );
+  }
+  return flagPort;
+}
 async function appDev(client, args) {
   const projectDir = path12.resolve(args.projectDir ?? process.cwd());
   const meta3 = readAppMeta(projectDir);
   warnAboutDevLink(projectDir, "dev");
+  const vitePort = resolveDeclaredVitePort(projectDir, args.vitePort);
   writeAppDts(projectDir, { workflows: meta3.workflows, queries: meta3.queries, agents: meta3.agents });
   const app = await client.getApp(meta3.app_id);
   const handle = await startDevServer({
@@ -50068,7 +50541,7 @@ async function appDev(client, args) {
     workspace_id: meta3.workspace_id,
     api_url: client.baseUrl,
     port: args.port,
-    vitePort: args.vitePort,
+    vitePort,
     client,
     commentsEnabled: meta3.capabilities?.comments
   });
@@ -50329,13 +50802,16 @@ async function appWorkflowSet(client, args) {
     ...typeof declaration.description === "string" ? { description: declaration.description } : {}
   });
   console.error(`Set workflow "${args.alias}" \u2192 ${result.workflow_id}`);
+  if (declaration.workflow_id !== result.workflow_id) {
+    writeWorkflowDeclarationFields(projectDir, args.alias, { workflow_id: result.workflow_id });
+  }
   for (const warning of result.warnings) {
     const issue2 = issueSchema.safeParse(warning);
     console.error(issue2.success ? renderWorkflowIssue(issue2.data) : `  ${JSON.stringify(warning)}`);
   }
   const derivedOutputs = result.outputs;
   if (!declaration.outputs && derivedOutputs && Object.keys(derivedOutputs).length > 0) {
-    writeWorkflowOutputs(projectDir, args.alias, derivedOutputs);
+    writeWorkflowDeclarationFields(projectDir, args.alias, { outputs: derivedOutputs });
     console.error(
       `  Wrote the derived result.data schema into package.json#lotics.workflows.${args.alias}.outputs.`
     );
@@ -50343,7 +50819,7 @@ async function appWorkflowSet(client, args) {
       inputs: declaration.inputs,
       outputs: derivedOutputs
     });
-    if (refreshed) console.error(`  Refreshed workflow types for ${args.alias}.`);
+    if (refreshed.kind === "refreshed") console.error(`  Refreshed workflow types for ${args.alias}.`);
   } else if (derivedOutputs) {
     console.error(`  result.data schema: ${JSON.stringify(derivedOutputs)}`);
   }
@@ -50411,22 +50887,79 @@ async function appWorkflowPull(client, args = {}) {
   reportUnseenLive("workflow body", unseenLive, meta3.app_id);
   ensureAppTsconfig(projectDir);
 }
-async function appWorkflowCheck(args) {
+async function appWorkflowDiff(client, args = {}) {
   const projectDir = process.cwd();
   const meta3 = readAppMeta(projectDir);
   const bound = Object.keys(meta3.workflows ?? {});
-  let aliases;
-  if (args.alias) {
-    if (!bound.includes(args.alias)) {
-      console.error(
-        `No workflow "${args.alias}" in package.json#lotics.workflows. Bound aliases: ${bound.length > 0 ? bound.join(", ") : "(none)"}.`
-      );
-      process.exit(1);
+  const requested = args.aliases ?? [];
+  const unbound = requested.filter((alias) => !bound.includes(alias));
+  if (unbound.length > 0) {
+    fail(
+      `No workflow ${unbound.map((a) => `"${a}"`).join(", ")} in package.json#lotics.workflows. Bound aliases: ${bound.length > 0 ? bound.join(", ") : "(none)"}.`
+    );
+  }
+  const aliases = requested.length > 0 ? [...new Set(requested)] : workflowBodyDrift(projectDir, meta3.workflows, readSynced(projectDir).workflows);
+  if (aliases.length === 0) {
+    console.error("No workflow body differs from the baseline this checkout last pushed or pulled.");
+    return;
+  }
+  let differing = 0;
+  for (const alias of aliases) {
+    const file2 = workflowFilePath(projectDir, alias);
+    if (!fs11.existsSync(file2)) {
+      console.error(`\u26A0 Skipped "${alias}" \u2014 no body at ${path12.relative(projectDir, file2)}.`);
+      continue;
     }
-    aliases = [args.alias];
-  } else {
-    aliases = bound;
+    const res = await client.getAppWorkflow(meta3.app_id, alias);
+    if (res.error) {
+      if (isMissingWorkflowBodyError(res.error)) {
+        console.error(
+          `\u26A0 Skipped "${alias}" \u2014 the server has no rendered body for it (never set, or legacy).`
+        );
+        continue;
+      }
+      fail(`Could not read workflow "${alias}" of ${meta3.app_id}: ${res.error}`);
+    }
+    const parsed = zod_default.object({ source: zod_default.string() }).safeParse(res.result);
+    if (!parsed.success) {
+      console.error(`\u26A0 Skipped "${alias}" \u2014 the server returned no body source.`);
+      continue;
+    }
+    const live = normalizeWorkflowBody(parsed.data.source);
+    const local = stripWorkflowHeader(fs11.readFileSync(file2, "utf-8"));
+    if (live === local) {
+      console.error(`\u2713 ${alias} \u2014 identical to the body the server is running.`);
+      continue;
+    }
+    differing++;
+    console.error(`
+${alias}  (- live, + ${path12.join(WORKFLOWS_DIR, `${alias}.ts`)})`);
+    console.log(renderLineDiff(live, local));
+  }
+  if (differing > 0) {
+    console.error(
+      `
+${differing} workflow ${differing === 1 ? "body differs" : "bodies differ"} from the server. 'lotics app workflow set <alias>' pushes one; 'lotics app workflow pull --force' takes the server's.`
+    );
+    process.exitCode = 1;
+  }
+}
+function resolveCheckAliases(requested, bound) {
+  const unbound = [...new Set(requested)].filter((alias) => !bound.includes(alias));
+  if (unbound.length > 0) return { kind: "unbound", unbound };
+  return { kind: "ok", aliases: requested.length > 0 ? [...new Set(requested)] : [...bound] };
+}
+async function appWorkflowCheck(args) {
+  const projectDir = process.cwd();
+  const meta3 = readAppMeta(projectDir);
+  const bound = Object.keys(meta3.workflows ?? {});
+  const resolved = resolveCheckAliases(args.aliases ?? [], bound);
+  if (resolved.kind === "unbound") {
+    fail(
+      `No workflow ${resolved.unbound.map((a) => `"${a}"`).join(", ")} in package.json#lotics.workflows. Bound aliases: ${bound.length > 0 ? bound.join(", ") : "(none)"}.`
+    );
   }
+  const aliases = resolved.aliases;
   if (aliases.length === 0) {
     console.error(`App ${meta3.app_id} has no bound workflows to check.`);
     return;
@@ -50439,8 +50972,7 @@ async function appWorkflowCheck(args) {
   const tsApi = await loadProjectTypescript(projectDir);
   const results = checkWorkflowBodies(tsApi, toCheck);
   printWorkflowCheckResults(projectDir, results);
-  const failed = results.filter((r) => r.issues.length > 0);
-  if (failed.length > 0) process.exit(1);
+  if (results.some((r) => r.issues.length > 0)) process.exitCode = 1;
 }
 async function collectWorkflowBodyChecks(projectDir, meta3, aliases, client) {
   const toCheck = [];
@@ -50449,15 +50981,14 @@ async function collectWorkflowBodyChecks(projectDir, meta3, aliases, client) {
     const globalsPath = workflowGlobalsPath(projectDir, alias);
     if (!fs11.existsSync(bodyPath)) {
       console.error(
-        `\u26A0 Skipped "${alias}" \u2014 no body at ${path12.relative(projectDir, bodyPath)}. Run 'lotics app workflow pull' to write it.`
+        `\u26A0 Skipped "${alias}" \u2014 no body at ${path12.relative(projectDir, bodyPath)}. Write it there (its types are in ${path12.relative(projectDir, globalsPath)}), or 'lotics app workflow pull' if the server already has one.`
       );
       continue;
     }
     if (!fs11.existsSync(globalsPath)) {
-      console.error(
+      fail(
         `Cannot check "${alias}" \u2014 missing types at ${path12.relative(projectDir, globalsPath)}. Run 'lotics app codegen' to fetch them (it refreshes types WITHOUT touching your body; a pull would overwrite it).`
       );
-      process.exit(1);
     }
     toCheck.push({ alias, input: { bodyPath, globalsPath } });
   }
@@ -50535,6 +51066,7 @@ function parseArgs(argv) {
     remove: void 0,
     includeHidden: false,
     timezone: void 0,
+    currency: void 0,
     email: void 0,
     message: void 0,
     session: void 0,
@@ -50547,11 +51079,13 @@ function parseArgs(argv) {
     printCreated: false,
     cleanup: false,
     prune: false,
+    pruneInvoked: [],
     screens: false,
     noSampleData: false,
     adopt: false,
     entity: [],
     limit: void 0,
+    cursor: void 0,
     tables: [],
     bind: [],
     version: false,
@@ -50649,6 +51183,9 @@ function parseArgs(argv) {
       case "--timezone":
         flags.timezone = takeValue(arg, "<Area/City>");
         break;
+      case "--currency":
+        flags.currency = takeValue(arg, "<ISO code>");
+        break;
       case "-m":
       case "--message":
         flags.message = takeValue(arg, "<message>");
@@ -50690,6 +51227,9 @@ function parseArgs(argv) {
       case "--limit":
         flags.limit = takeValue(arg, "<n>");
         break;
+      case "--cursor":
+        flags.cursor = takeValue(arg, "<token>");
+        break;
       case "--tables":
         flags.tables = [...flags.tables, ...takeList(arg, "<tbl_id,tbl_id>")];
         break;
@@ -50698,6 +51238,9 @@ function parseArgs(argv) {
       case "--bind":
         flags.bind = [...flags.bind, takeValue(arg, "<entity>=<Label>")];
         break;
+      case "--prune-invoked":
+        flags.pruneInvoked = [...flags.pruneInvoked, ...takeList(arg, "<alias>")];
+        break;
       case "--prune":
         flags.prune = true;
         break;
@@ -51154,7 +51697,14 @@ async function runPreviewCommand(filePath, flags) {
   if (!existsSync4(abs2)) fail(`File not found: ${abs2}`);
   const ext = extname(abs2).toLowerCase();
   const type = ext === ".docx" ? "docx" : ext === ".xlsx" || ext === ".xls" || ext === ".csv" ? "xlsx" : ext === ".html" || ext === ".htm" ? "html" : null;
-  if (!type) fail(`Unsupported file type "${ext}" \u2014 preview supports .docx, .xlsx/.csv and .html. (PDFs open directly \u2014 no preview needed.)`);
+  if (!type) {
+    const route = ext === ".pdf" ? `
+  A PDF is rasterised outside this CLI: lotics file download <fil_id>, then
+  'pdftoppm -png -r 150 <file.pdf> <out-prefix>' (poppler-utils) for one PNG per page.` : "";
+    fail(
+      `Unsupported file type "${ext}" \u2014 preview supports .docx, .xlsx/.csv and .html.${route}`
+    );
+  }
   let server;
   let pageUrl;
   if (type === "html") {
@@ -51766,23 +52316,32 @@ async function main() {
     console.error(`${flag} needs a value \u2014 write it as: ${flag} ${expects}`);
     process.exit(1);
   }
-  if (command === "file") {
-    if (!subcommand) {
-      printHelp();
-      return;
-    }
-    command = subcommand;
-    subcommand = toolArgs;
-    toolArgs = restArgs.shift();
-  }
   if (flags.help && command === "report") {
     console.error(REPORT_USAGE);
     return;
   }
   if (flags.help || !command && !flags.version) {
+    const scoped = flags.help ? commandHelp([parsed.command, parsed.subcommand, parsed.toolArgs].filter((w) => w !== void 0)) : null;
+    if (scoped !== null) {
+      console.log(scoped);
+      return;
+    }
     printHelp();
     return;
   }
+  if (command === "file") {
+    if (!subcommand) {
+      const help = commandHelp(["file"]);
+      if (help !== null) console.log(help);
+      else printHelp();
+      return;
+    }
+    if (commandAliases("file").has(subcommand)) {
+      command = subcommand;
+      subcommand = toolArgs;
+      toolArgs = restArgs.shift();
+    }
+  }
   if (flags.version && command !== void 0) {
     console.error(
       `--version prints this CLI's version and takes no argument; it cannot be combined with a command.
@@ -52286,7 +52845,7 @@ async function main() {
       );
       client2 = void 0;
     }
-    await appWorkflowCheck({ alias: restArgs[0], client: client2 });
+    await appWorkflowCheck({ aliases: restArgs, client: client2 });
     return;
   }
   if (command === "app" && subcommand === "codegen") {
@@ -52455,6 +53014,59 @@ async function main() {
     }
     return;
   }
+  if (command === "file") {
+    if (subcommand !== "list" && subcommand !== "delete") {
+      console.error(`Unknown file subcommand: ${subcommand}
+`);
+      console.error(commandHelp(["file"]));
+      process.exit(1);
+    }
+    const { client: client2, ctx: ctx2 } = await requireClient(flags);
+    await resolveWorkspace(client2, ctx2);
+    if (subcommand === "list") {
+      let limit;
+      if (flags.limit !== void 0) {
+        limit = Number(flags.limit);
+        if (!Number.isInteger(limit) || limit < 1) {
+          console.error(`Invalid --limit "${flags.limit}" \u2014 expected a positive integer.`);
+          process.exit(1);
+        }
+      }
+      const page = await client2.listFiles({ limit, cursor: flags.cursor });
+      if (flags.json) {
+        console.log(JSON.stringify(page, null, 2));
+      } else {
+        for (const file2 of page.files) {
+          const size2 = file2.size == null ? "-" : String(file2.size);
+          console.log(`${file2.id}  ${file2.created_at}  ${size2}  ${file2.mime_type}  ${file2.filename}`);
+        }
+        console.error(
+          page.next_cursor === null ? `${page.files.length} file${page.files.length === 1 ? "" : "s"} \u2014 end of the store.` : `${page.files.length} files. Next page: lotics file list --cursor ${page.next_cursor}`
+        );
+      }
+      return;
+    }
+    const fileId = toolArgs;
+    if (!fileId || !isStoredFileId(fileId)) {
+      console.error("Usage: lotics file delete <file_id>");
+      console.error(
+        "Archives a stored file. Refused while a record, comment, knowledge doc, document"
+      );
+      console.error("template or voice session still references it \u2014 those are named back.");
+      process.exit(1);
+    }
+    const deleted = await client2.execute("delete_file", { file_id: fileId }, { format: "text" });
+    if (deleted.error) {
+      console.error(deleted.error);
+      process.exit(1);
+    }
+    if (flags.json) {
+      console.log(JSON.stringify(deleted.result, null, 2));
+    } else {
+      console.log(deleted.model_output ?? JSON.stringify(deleted.result));
+    }
+    return;
+  }
   const appPathArg = subcommand === "dev" ? toolArgs : void 0;
   const { client, ctx } = await requireClient(
     flags,
@@ -52480,6 +53092,22 @@ async function main() {
       process.exitCode = 1;
       return;
     }
+    const settingsName = subcommand === "rename" ? toolArgs : flags.name;
+    if (subcommand === "rename" && !settingsName) {
+      console.error("Usage: lotics workspace rename <new name>");
+      console.error('Renames the CURRENT workspace. Switch first with "lotics workspace select <id>".');
+      process.exit(1);
+    }
+    if (subcommand === "settings" && settingsName === void 0 && flags.currency === void 0 && flags.timezone === void 0) {
+      console.error(
+        "Usage: lotics workspace settings [--name <name>] [--currency <ISO>] [--timezone <Area/City>]"
+      );
+      console.error(
+        "Changes the CURRENT workspace. The currency decides how every money field renders and the"
+      );
+      console.error("zone decides how every date buckets; neither is visible once it is wrong.");
+      process.exit(1);
+    }
     const workspaces = await client.listWorkspaces();
     const currentWorkspaceId = ctx.workspaceId;
     if (subcommand === "select") {
@@ -52505,45 +53133,47 @@ Available workspaces:`);
       console.error(`Switched to workspace: ${target.name} (${target.id})${where}`);
       return;
     }
-    if (subcommand === "create") {
-      const name = toolArgs;
-      if (!name) {
-        console.error("Usage: lotics workspace create <name> [--timezone <tz>]");
+    if (subcommand === "settings" || subcommand === "rename") {
+      const current = workspaces.find((ws) => ws.id === currentWorkspaceId);
+      if (!current) {
+        console.error('No workspace selected. Choose one with "lotics workspace select <id>".');
         process.exit(1);
       }
-      const timezone = flags.timezone;
-      const created = await client.createWorkspace({ name, timezone });
-      setSelectedWorkspace(created.id, ctx.orgId);
-      client.setWorkspaceId(created.id);
+      const updated = await client.updateWorkspace({
+        name: settingsName ?? current.name,
+        default_currency: flags.currency ?? current.default_currency,
+        timezone: flags.timezone ?? current.timezone
+      });
       if (flags.json) {
-        console.log(JSON.stringify(created, null, 2));
+        console.log(JSON.stringify(updated, null, 2));
       } else {
-        console.error(`Created workspace: ${created.name} (${created.id})`);
-        console.error(`Switched to ${created.id}`);
+        console.error(
+          `Workspace ${updated.id}: ${updated.name} \xB7 ${updated.default_currency} \xB7 ${updated.timezone}`
+        );
       }
       return;
     }
-    if (subcommand === "rename") {
+    if (subcommand === "create") {
       const name = toolArgs;
       if (!name) {
-        console.error("Usage: lotics workspace rename <new name>");
-        console.error('Renames the CURRENT workspace. Switch first with "lotics workspace select <id>".');
+        console.error("Usage: lotics workspace create <name> [--timezone <tz>] [--currency <ISO>]");
         process.exit(1);
       }
-      const current = workspaces.find((ws) => ws.id === currentWorkspaceId);
-      if (!current) {
-        console.error('No workspace selected. Choose one with "lotics workspace select <id>".');
-        process.exit(1);
-      }
-      const renamed = await client.updateWorkspace({
+      const timezone = flags.timezone;
+      const created = await client.createWorkspace({
         name,
-        default_currency: current.default_currency,
-        timezone: current.timezone
+        timezone,
+        default_currency: flags.currency
       });
+      setSelectedWorkspace(created.id, ctx.orgId);
+      client.setWorkspaceId(created.id);
       if (flags.json) {
-        console.log(JSON.stringify(renamed, null, 2));
+        console.log(JSON.stringify(created, null, 2));
       } else {
-        console.error(`Renamed "${current.name}" to "${renamed.name}" (${renamed.id})`);
+        console.error(
+          `Created workspace: ${created.name} (${created.id}) \xB7 ${created.default_currency} \xB7 ${created.timezone}`
+        );
+        console.error(`Switched to ${created.id}`);
       }
       return;
     }
@@ -52632,9 +53262,16 @@ Available workspaces:`);
       return;
     }
     if (subcommand === "deploy") {
+      if (flags.pruneInvoked.length > 0 && !flags.prune) {
+        console.error(
+          "--prune-invoked lifts one guard inside --prune; it does nothing on its own. Add --prune."
+        );
+        process.exit(1);
+      }
       await appDeploy(client, {
         message: (flags.message ?? toolArgs)?.trim() || void 0,
-        prune: flags.prune
+        prune: flags.prune,
+        pruneInvoked: flags.pruneInvoked
       });
       return;
     }
@@ -52677,7 +53314,8 @@ Available workspaces:`);
         console.error("Usage:");
         console.error("  lotics app workflow set <alias>            Push src/workflows/<alias>.ts");
         console.error("  lotics app workflow pull                   Rewrite src/workflows/*.ts from the server");
-        console.error("  lotics app workflow check [alias]          Typecheck src/workflows bodies locally");
+        console.error("  lotics app workflow check [alias...]       Typecheck src/workflows bodies locally");
+        console.error("  lotics app workflow diff [alias...]        Show how a body differs from the server's");
         process.exit(1);
       };
       if (action === "set") {
@@ -52694,6 +53332,10 @@ Available workspaces:`);
         await appWorkflowPull(client, { force: flags.force === true });
         return;
       }
+      if (action === "diff") {
+        await appWorkflowDiff(client, { aliases: restArgs });
+        return;
+      }
       workflowUsage();
     }
     if (subcommand === "agent") {
@@ -52838,7 +53480,6 @@ ${JSON.stringify(info.input_schema, null, 2)}`);
     const toolName = subcommand;
     const ingested = await ingestJsonArgs({
       rawArg: toolArgs,
-      stdinIsTTY: process.stdin.isTTY ?? false,
       readFile: (p) => fs14.readFileSync(p, "utf-8"),
       readStdin
     });