@lotics/cli 0.192.0 → 0.194.0

package/dist/src/cli.js

@@ -44372,10 +44372,9 @@ var LoticsRequestError = class extends Error {
   status;
   body;
 };
-var API_BASE_URL = process.env.LOTICS_API_URL ?? "https://api.lotics.ai";
 var WEB_APP_URL = process.env.LOTICS_WEB_URL ?? "https://lotics.ai";
-async function fetchOfficialStarters() {
-  const read = await getPublicJson(`${API_BASE_URL}/v1/starters/official`, "list the packages");
+async function fetchOfficialStarters(apiUrl) {
+  const read = await getPublicJson(`${apiUrl}/v1/starters/official`, "list the packages");
   if (!read.ok) {
     throw new Error(
       `Lotics answered ${read.status} listing the packages. If this keeps happening, browse ${WEB_APP_URL}/docs/cli.`
@@ -44395,16 +44394,16 @@ async function getPublicJson(url2, what) {
   if (!response.ok) return { ok: false, status: response.status };
   return { ok: true, body: await response.json() };
 }
-async function readOfficialStarter(starter_id) {
+async function readOfficialStarter(apiUrl, starter_id) {
   const read = await getPublicJson(
-    `${API_BASE_URL}/v1/starters/official/${encodeURIComponent(starter_id)}`,
+    `${apiUrl}/v1/starters/official/${encodeURIComponent(starter_id)}`,
     `read ${starter_id}`
   );
   if (!read.ok) return read;
   return { ok: true, package: read.body };
 }
-async function getOfficialStarter(starter_id) {
-  const read = await readOfficialStarter(starter_id);
+async function getOfficialStarter(apiUrl, starter_id) {
+  const read = await readOfficialStarter(apiUrl, starter_id);
   if (!read.ok) {
     throw new Error(
       `Lotics answered ${read.status} reading ${starter_id}. Only packages Lotics publishes can be read without an account.`
@@ -44413,10 +44412,10 @@ async function getOfficialStarter(starter_id) {
   return read.package;
 }
 var PUBLIC_FETCH_TIMEOUT_MS = 1e4;
-async function startCliLogin(email3) {
+async function startCliLogin(apiUrl, email3) {
   let response;
   try {
-    response = await fetch(`${API_BASE_URL}/v1/cli/login_requests`, {
+    response = await fetch(`${apiUrl}/v1/cli/login_requests`, {
       method: "POST",
       headers: { "Content-Type": "application/json" },
       body: JSON.stringify({ email: email3 }),
@@ -44432,8 +44431,8 @@ async function startCliLogin(email3) {
   }
   return await response.json();
 }
-async function pollCliLogin(request_id, secret) {
-  const url2 = `${API_BASE_URL}/v1/cli/login_requests/${encodeURIComponent(request_id)}`;
+async function pollCliLogin(apiUrl, request_id, secret) {
+  const url2 = `${apiUrl}/v1/cli/login_requests/${encodeURIComponent(request_id)}`;
   let response;
   try {
     response = await fetch(url2, {
@@ -44460,14 +44459,14 @@ var LoticsClient = class {
    *  construction — surfaced so `lotics app dev` can show it in the banner. */
   viewAsMemberId;
   /** API URL the client is configured against. Read-only after construction.
-   *  Surfaced for callers that need to display or log it (e.g., `lotics app dev`
-   *  shows it in the banner). */
+   *  Surfaced for callers that need to display it (`lotics app dev`'s banner) or
+   *  to hand it on (the wrapper page's RPC target, the scaffold's font proxy). */
   baseUrl;
   constructor(options) {
     this.apiKey = options.apiKey;
     this.workspaceId = options.workspaceId;
     this.viewAsMemberId = options.viewAsMemberId;
-    this.baseUrl = API_BASE_URL;
+    this.baseUrl = options.apiUrl;
   }
   /**
    * The id is appended to the MESSAGE rather than carried on a field, because
@@ -44870,9 +44869,10 @@ var LoticsClient = class {
     return tables.filter((t) => t !== null);
   }
   /**
-   * Rename an app's public subdomain — its `<slug>.lotics.app` address.
-   * Mirrors PUT /v1/apps/{app_id}/subdomain. The old subdomain stops
-   * resolving once the change lands.
+   * Rename an app's public subdomain — the label its origin is built on.
+   * Mirrors PUT /v1/apps/{app_id}/subdomain, and returns the finished `origin`
+   * because only the instance knows the domain and scheme it serves apps on.
+   * The old subdomain stops resolving once the change lands.
    */
   async setAppSubdomain(app_id, public_subdomain) {
     return this.request(
@@ -45500,8 +45500,16 @@ function canonicalize(value2) {
 var MAX_ERROR_CHARS = 2e3;
 var MAX_SPOOL_BYTES = 1024 * 1024;
 var MAX_FLUSH_EVENTS = 500;
-function spoolPath() {
-  return path3.join(os2.homedir(), ".lotics", "telemetry.ndjson");
+function spoolPath(apiUrl) {
+  const shard = crypto2.createHash("sha256").update(apiUrl).digest("hex").slice(0, 12);
+  return path3.join(os2.homedir(), ".lotics", `telemetry-${shard}.ndjson`);
+}
+var targetApiUrl = "";
+function noteTarget(apiUrl) {
+  targetApiUrl = apiUrl;
+}
+function invocationTarget() {
+  return targetApiUrl;
 }
 var stderrTail = "";
 function recordStderr(text) {
@@ -45561,8 +45569,8 @@ function buildEvent(exitCode, durationMs, now) {
     ...pendingScope
   };
 }
-function appendEvent(event) {
-  const file2 = spoolPath();
+function appendEvent(event, apiUrl) {
+  const file2 = spoolPath(apiUrl);
   try {
     fs3.mkdirSync(path3.dirname(file2), { recursive: true });
     if ((fs3.statSync(file2, { throwIfNoEntry: false })?.size ?? 0) > MAX_SPOOL_BYTES) {
@@ -45573,11 +45581,11 @@ function appendEvent(event) {
   } catch {
   }
 }
-function readSpool() {
+function readSpool(apiUrl) {
   try {
     const events = [];
     const lines = [];
-    for (const line of fs3.readFileSync(spoolPath(), "utf-8").split("\n")) {
+    for (const line of fs3.readFileSync(spoolPath(apiUrl), "utf-8").split("\n")) {
       if (line.trim() === "") continue;
       try {
         events.push(JSON.parse(line));
@@ -45590,32 +45598,34 @@ function readSpool() {
     return { events: [], lines: [] };
   }
 }
-function clearSpool(sent) {
+function clearSpool(apiUrl, sent) {
   try {
-    const current = fs3.readFileSync(spoolPath(), "utf-8");
-    fs3.writeFileSync(spoolPath(), current.startsWith(sent) ? current.slice(sent.length) : "", {
+    const file2 = spoolPath(apiUrl);
+    const current = fs3.readFileSync(file2, "utf-8");
+    fs3.writeFileSync(file2, current.startsWith(sent) ? current.slice(sent.length) : "", {
       mode: 384
     });
   } catch {
   }
 }
-function installTelemetry(startedAt2 = Date.now()) {
+function installTelemetry(target, startedAt2 = Date.now()) {
   if (!telemetryEnabled()) return;
+  noteTarget(target);
   installStderrCapture();
   process.on("exit", (code) => {
     const event = buildEvent(code, Date.now() - startedAt2, /* @__PURE__ */ new Date());
-    if (event !== null) appendEvent(event);
+    if (event !== null) appendEvent(event, invocationTarget());
   });
 }
-function flushSpool(post, minEvents = 5) {
+function flushSpool(apiUrl, post, minEvents = 5) {
   if (!telemetryEnabled()) return;
-  const { events, lines } = readSpool();
+  const { events, lines } = readSpool(apiUrl);
   if (events.length < minEvents) return;
   const batch = events.slice(0, MAX_FLUSH_EVENTS);
   const sent = `${lines.slice(0, batch.length).join("\n")}
 `;
   void post(batch).then((outcome) => {
-    if (outcome !== "retry") clearSpool(sent);
+    if (outcome !== "retry") clearSpool(apiUrl, sent);
   }).catch(() => {
   });
 }
@@ -45641,6 +45651,10 @@ async function postEvents(baseUrl, apiKey, events, timeoutMs = 5e3) {
 import fs4 from "node:fs";
 import path4 from "node:path";
 import os3 from "node:os";
+var HOSTED_API_URL = "https://api.lotics.ai";
+function envApiUrl() {
+  return process.env.LOTICS_API_URL ?? HOSTED_API_URL;
+}
 function globalConfigFile() {
   return path4.join(os3.homedir(), ".lotics", "config.json");
 }
@@ -45663,12 +45677,34 @@ function configFileForScope(scope) {
   return globalConfigFile();
 }
 function readConfigFile(file2) {
+  let parsed;
   try {
     const raw = fs4.readFileSync(file2, "utf-8");
-    return JSON.parse(raw);
+    parsed = JSON.parse(raw);
   } catch {
     return null;
   }
+  return upgradeProfileApiUrls(file2, parsed);
+}
+function upgradeProfileApiUrls(file2, config2) {
+  const profiles = config2.profiles;
+  if (!profiles) return config2;
+  const entries2 = Object.entries(profiles);
+  if (!entries2.some(([, profile]) => !profile.api_url)) return config2;
+  const upgraded = {
+    ...config2,
+    profiles: Object.fromEntries(
+      entries2.map(([orgId, profile]) => [
+        orgId,
+        { ...profile, api_url: profile.api_url || HOSTED_API_URL }
+      ])
+    )
+  };
+  try {
+    writeConfigFile(file2, upgraded);
+  } catch {
+  }
+  return upgraded;
 }
 function writeConfigFile(file2, config2) {
   fs4.mkdirSync(path4.dirname(file2), { recursive: true, mode: 448 });
@@ -45715,6 +45751,11 @@ function resolveProfileByNameOrId(profiles, nameOrId) {
   return null;
 }
 function resolveContext(flags, appWorkspaceId) {
+  const resolved = resolveCredential(flags, appWorkspaceId);
+  if (resolved) noteTarget(resolved.apiUrl);
+  return resolved;
+}
+function resolveCredential(flags, appWorkspaceId) {
   const envKey = process.env.LOTICS_API_KEY;
   const envOrg = process.env.LOTICS_ORG;
   const envWorkspace = process.env.LOTICS_WORKSPACE;
@@ -45732,6 +45773,7 @@ function resolveContext(flags, appWorkspaceId) {
     const [orgId, profile] = resolved;
     return {
       apiKey: profile.api_key,
+      apiUrl: profile.api_url,
       orgId,
       orgName: profile.org_name,
       workspaceId: wsOverride ?? profile.workspace_id,
@@ -45739,10 +45781,10 @@ function resolveContext(flags, appWorkspaceId) {
     };
   }
   if (flags.apiKey) {
-    return { apiKey: flags.apiKey, workspaceId: wsOverride, source: "flag" };
+    return { apiKey: flags.apiKey, apiUrl: envApiUrl(), workspaceId: wsOverride, source: "flag" };
   }
   if (envKey) {
-    return { apiKey: envKey, workspaceId: wsOverride, source: "env_key" };
+    return { apiKey: envKey, apiUrl: envApiUrl(), workspaceId: wsOverride, source: "env_key" };
   }
   const global2 = loadGlobalConfig();
   const profiles = global2?.profiles ?? {};
@@ -45756,6 +45798,7 @@ function resolveContext(flags, appWorkspaceId) {
     const [orgId, profile] = resolved;
     return {
       apiKey: profile.api_key,
+      apiUrl: profile.api_url,
       orgId,
       orgName: profile.org_name,
       workspaceId: wsOverride ?? profile.workspace_id,
@@ -45772,6 +45815,7 @@ function resolveContext(flags, appWorkspaceId) {
     }
     return {
       apiKey: profile.api_key,
+      apiUrl: profile.api_url,
       orgId: local.active_org,
       orgName: profile.org_name,
       workspaceId: wsOverride ?? local.workspace_id ?? profile.workspace_id,
@@ -45789,6 +45833,7 @@ function resolveContext(flags, appWorkspaceId) {
       const [orgId, profile] = matches[0];
       return {
         apiKey: profile.api_key,
+        apiUrl: profile.api_url,
         orgId,
         orgName: profile.org_name,
         workspaceId: appWorkspaceId,
@@ -45805,6 +45850,7 @@ function resolveContext(flags, appWorkspaceId) {
     }
     return {
       apiKey: profile.api_key,
+      apiUrl: profile.api_url,
       orgId: global2.active_org,
       orgName: profile.org_name,
       workspaceId: wsOverride ?? profile.workspace_id,
@@ -45819,6 +45865,7 @@ function upsertProfile(orgId, fields) {
   const profile = {
     api_key: fields.api_key,
     org_name: fields.org_name,
+    api_url: fields.api_url,
     workspace_id: fields.workspace_id ?? existing?.workspace_id
   };
   saveGlobalConfig({
@@ -46001,7 +46048,7 @@ function resultSideEffects(result) {
 }
 
 // src/version.ts
-var VERSION = "0.192.0";
+var VERSION = "0.194.0";
 
 // src/timezone.ts
 function machineTimezone() {
@@ -46562,7 +46609,7 @@ var COMMANDS = [
       "                                       fields keep whatever is bound (a manifest is a",
       "                                       snapshot; replaying it would revert them). Change",
       "                                       those with set_app_agent, then pull.",
-      "  lotics app subdomain <new-subdomain> Rename the app's public <slug>.lotics.app address",
+      "  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)"
     ]
@@ -46997,8 +47044,8 @@ export default defineConfig({
   server: {
     // Allow the sandboxed null-origin iframe used by \`lotics app dev\` to
     // fetch HMR client + source modules from the dev server. Production
-    // iframe loads modules from api.lotics.ai which already permits null
-    // origin via CORS.
+    // iframe loads modules from the API, which already permits null origin
+    // via CORS.
     cors: { origin: "*" },
     // Chat-authoring previews reach this dev server through the sandbox proxy
     // at \`5173-<id>-<token>.lotics-sandbox.app\`. Vite \u22655.4.12 rejects HMR
@@ -65067,7 +65114,7 @@ var appSchema = zod_default.object({
     "Pointer to the currently-published app_versions row in R2. Set once the app has been deployed at least once via `lotics app deploy`; null before the first deploy."
   ),
   public_subdomain: zod_default.string().describe(
-    "DNS label for the app's public origin: `<public_subdomain>.lotics.app`. Server-generated, high-entropy, and distinct from `id` (app_ids are not valid DNS labels). Assigned at creation for every app."
+    "DNS label for the app's public origin, under the instance's apps domain. Server-generated, high-entropy, and distinct from `id` (app_ids are not valid DNS labels). Assigned at creation for every app."
   ),
   public_password_set: zod_default.boolean().optional().describe(
     "Whether a shared password gates the public binding. True \u2192 anonymous visitors must authenticate at `/v1/apps/{app_id}/public/authenticate` before any publicAppAccess endpoint resolves. The hash itself is never sent over the wire; only this flag is exposed (and only on authenticated owner-side reads \u2014 the public by-subdomain response surfaces the same fact as `requires_password`)."
@@ -67683,6 +67730,7 @@ var fieldRoleSchema = zod_default.enum([
   "amount",
   "when",
   "party",
+  "parent",
   "contact",
   "verdict"
 ]);
@@ -67695,6 +67743,7 @@ var FIELD_ROLE_TYPES = {
   amount: ["number", "formula", "rollup"],
   when: ["date"],
   party: ["select_record_link"],
+  parent: ["select_record_link"],
   contact: ["text"],
   verdict: ["boolean", "formula"]
 };
@@ -67705,6 +67754,7 @@ var SINGLE_FIELD_ROLES = [
   "amount",
   "when",
   "party",
+  "parent",
   "contact",
   "verdict"
 ];
@@ -67796,7 +67846,7 @@ var slot = (role, required2 = false) => ({ role, required: required2 });
 var SHAPE_REGISTRY = {
   lifecycle_desk: {
     label: "lifecycle desk",
-    slots: { stage: slot("lifecycle", true), identity: slot("identity", true), party: slot("party"), amount: slot("amount"), when: slot("when") },
+    slots: { stage: slot("lifecycle", true), identity: slot("identity", true), mark: slot("mark"), party: slot("party"), amount: slot("amount"), when: slot("when") },
     record: "drawer",
     tabs: "lifecycle"
   },
@@ -67820,7 +67870,7 @@ var SHAPE_REGISTRY = {
   },
   monitored_asset_set: {
     label: "monitored-asset set",
-    slots: { identity: slot("identity", true), level: slot("measure", true), stage: slot("lifecycle") },
+    slots: { identity: slot("identity", true), mark: slot("mark"), level: slot("measure", true), stage: slot("lifecycle") },
     record: "drawer",
     tabs: "none"
   },
@@ -67941,6 +67991,96 @@ 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 CHILD_COLUMN_ROLES = [
+  "identity",
+  "mark",
+  "party",
+  "contact",
+  "when",
+  "expected_set",
+  "measure",
+  "amount",
+  "lifecycle",
+  "verdict"
+];
+function parentLink(child, entity, roles) {
+  return child.fields.find(
+    (field) => field.type === "select_record_link" && field.target_entity === entity.alias && roleOf(roles, child.alias, field.alias)?.role === "parent"
+  );
+}
+function fieldsWithRole(entity, roles, role) {
+  return entity.fields.filter((field) => roleOf(roles, entity.alias, field.alias)?.role === role);
+}
+function fileFields(entity, roles) {
+  const files = entity.fields.filter((field) => field.type === "files");
+  const mark = fieldsWithRole(entity, roles, "mark")[0];
+  return mark === void 0 ? files : [mark, ...files.filter((field) => field.alias !== mark.alias)];
+}
+function recordHeader(screen) {
+  const bound = (role) => screen.slots.find((entry) => entry.role === role && entry.field !== null)?.field ?? void 0;
+  const title = bound("identity");
+  if (screen.record === "drawer") return { title };
+  return {
+    title,
+    subtitle: bound("when"),
+    // Which number is THE figure is the screen's choice among the ones it
+    // reads, so it comes off the slots — an amount the shape has no slot for
+    // is not on the header and stays a fact.
+    figure: bound("amount") ?? bound("measure")
+  };
+}
+function recordSections(entity, entities, roles, header) {
+  const lifecycle = fieldsWithRole(entity, roles, "lifecycle")[0];
+  const ownSets = fieldsWithRole(entity, roles, "expected_set").filter(
+    (field) => field.type === "select" && field.multi === true
+  );
+  const files = fileFields(entity, roles);
+  const owned = new Set(
+    [
+      ...lifecycle === void 0 ? [] : [lifecycle],
+      ...ownSets,
+      ...files,
+      ...header.title === void 0 ? [] : [header.title],
+      ...header.figure === void 0 ? [] : [header.figure]
+    ].map((field) => field.alias)
+  );
+  const facts = entity.fields.filter((field) => !owned.has(field.alias));
+  const levels = {};
+  for (const field of facts) {
+    const decl = roleOf(roles, entity.alias, field.alias);
+    if (decl?.role !== "measure" || decl.alert === void 0) continue;
+    if (typeof decl.against === "number") {
+      levels[field.alias] = { limit: decl.against, alert: decl.alert };
+      continue;
+    }
+    const limit = entity.fields.find((candidate) => candidate.alias === decl.against);
+    if (limit !== void 0) levels[field.alias] = { limit, alert: decl.alert };
+  }
+  const folded = new Set(
+    Object.values(levels).flatMap((level) => typeof level.limit === "number" ? [] : [level.limit.alias])
+  );
+  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 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 }] : [],
+    ...lifecycle === void 0 ? [] : [{ kind: "progress", field: lifecycle }],
+    ...sets,
+    ...children,
+    ...files.length > 0 ? [{ kind: "files", fields: files }] : []
+  ];
+}
 function validateWorkspacePlan(model, roles, apps) {
   const findings = [];
   for (const dup of findDuplicates(apps.map((app) => app.alias))) {
@@ -68021,28 +68161,83 @@ function roleCoverage(model, roles, rows) {
       }
     }
   }
+  for (const entity of model.entities) {
+    for (const section of recordSections(entity, model.entities, roles, {})) {
+      if (section.kind === "children" && fieldsWithRole(section.child, roles, "identity").length === 0) {
+        notes.push({
+          path: `field_roles.${section.child.alias}`,
+          message: `${section.child.label} hangs under ${entity.label} and declares no identity \u2014 its rows on the record have no name`
+        });
+      }
+      if (section.kind === "expected_set" && section.source === "child" && section.filesField === void 0) {
+        notes.push({
+          path: `field_roles.${section.child.alias}.${section.setField.alias}`,
+          message: `${section.child.label} is the required set of ${entity.label} and carries no files field \u2014 the desk names what is missing with nothing to attach`
+        });
+      }
+    }
+  }
   return notes;
 }
 
 // src/plan_starter.ts
-function bindScreens(screens, live, roles) {
+function sectionChild(section) {
+  if (section.kind === "children") return section.child;
+  if (section.kind === "expected_set" && section.source === "child") return section.child;
+  return void 0;
+}
+var DRAWN_ROLES = [
+  "identity",
+  "amount",
+  "measure",
+  "lifecycle",
+  "when",
+  "expected_set",
+  "party",
+  "contact",
+  "verdict"
+];
+var columnPriority = (role) => DRAWN_ROLES.indexOf(role) + 1;
+var CHILD_COLUMNS_SHOWN = 5;
+function bindTable(at2, entity, wanted, aliased, live, missing) {
+  const tables = aliased.filter((candidate) => candidate.table.name === entity.label);
+  if (tables.length !== 1) {
+    missing.push(
+      tables.length === 0 ? `${at2}: no table is labelled "${entity.label}" (entity "${entity.alias}")` : `${at2}: ${tables.length} tables are labelled "${entity.label}" (${tables.map((candidate) => candidate.table.id).join(", ")}) \u2014 a label binds one`
+    );
+    return void 0;
+  }
+  const table = tables[0];
+  const liveType = new Map(live.find((candidate) => candidate.id === table.table.id)?.fields.map((field) => [field.id, field.type]) ?? []);
+  const fields = /* @__PURE__ */ new Map();
+  const seen = /* @__PURE__ */ new Set();
+  for (const field of wanted) {
+    if (seen.has(field.alias)) continue;
+    seen.add(field.alias);
+    const found = table.fields.filter((candidate) => candidate.field.name === field.label);
+    if (found.length !== 1) {
+      missing.push(
+        found.length === 0 ? `${at2}: table "${table.table.name}" has no field labelled "${field.label}" (field "${field.alias}")` : `${at2}: table "${table.table.name}" has ${found.length} fields labelled "${field.label}" (${found.map((candidate) => candidate.field.id).join(", ")}) \u2014 a label binds one`
+      );
+      continue;
+    }
+    const type = liveType.get(found[0].field.id);
+    if (type !== field.type) {
+      missing.push(`${at2}: field "${field.label}" is a ${type ?? "field of unknown type"} in this workspace and a ${field.type} in the model`);
+      continue;
+    }
+    fields.set(field.alias, { alias: found[0].alias, id: found[0].field.id, type: field.type, label: field.label });
+  }
+  return { table: table.table, tableAlias: table.alias, fields };
+}
+function bindScreens(screens, live, roles, entities) {
   const aliased = aliasTables([...live]);
   const bound = [];
   const missing = [];
   for (const screen of screens) {
     const at2 = `${screen.app.alias}.${screen.screen.alias}`;
-    const tables = aliased.filter((candidate) => candidate.table.name === screen.entity.label);
-    if (tables.length !== 1) {
-      missing.push(
-        tables.length === 0 ? `${at2}: no table is labelled "${screen.entity.label}" (entity "${screen.entity.alias}")` : `${at2}: ${tables.length} tables are labelled "${screen.entity.label}" (${tables.map((candidate) => candidate.table.id).join(", ")}) \u2014 a label binds one`
-      );
-      continue;
-    }
-    const table = tables[0];
-    const liveType = new Map(live.find((candidate) => candidate.id === table.table.id)?.fields.map((field) => [field.id, field.type]) ?? []);
-    const fields = /* @__PURE__ */ new Map();
-    const limits = /* @__PURE__ */ new Map();
     const identity = screen.slots.find((slot2) => slot2.role === "identity" && slot2.field !== null)?.field ?? null;
+    const limits = /* @__PURE__ */ new Map();
     const wanted = [
       ...identity === null ? [] : [identity],
       ...screen.slots.flatMap((slot2) => slot2.field === null || slot2.field === identity ? [] : [slot2.field]),
@@ -68057,36 +68252,82 @@ function bindScreens(screens, live, roles) {
       wanted.push(limit);
       limits.set(slot2.field.alias, limit.alias);
     }
-    for (const field of wanted) {
-      if (fields.has(field.alias)) continue;
-      const found = table.fields.filter((candidate) => candidate.field.name === field.label);
-      if (found.length !== 1) {
-        missing.push(
-          found.length === 0 ? `${at2}: table "${table.table.name}" has no field labelled "${field.label}" (field "${field.alias}")` : `${at2}: table "${table.table.name}" has ${found.length} fields labelled "${field.label}" (${found.map((candidate) => candidate.field.id).join(", ")}) \u2014 a label binds one`
-        );
-        continue;
-      }
-      const type = liveType.get(found[0].field.id);
-      if (type !== field.type) {
-        missing.push(`${at2}: field "${field.label}" is a ${type ?? "field of unknown type"} in this workspace and a ${field.type} in the model`);
+    wanted.push(...screen.entity.fields);
+    const own = bindTable(at2, screen.entity, wanted, aliased, live, missing);
+    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);
+      if (found === void 0) return;
+      const parent = found.fields.get(parentField.alias);
+      if (parent === void 0) return;
+      const drawnRoles = /* @__PURE__ */ new Map();
+      const fields = /* @__PURE__ */ new Map();
+      for (const field of drawn) {
+        const boundField = found.fields.get(field.alias);
+        if (boundField === void 0) continue;
+        fields.set(field.alias, boundField);
+        const role = roleOf(roles, child.alias, field.alias)?.role;
+        if (role !== void 0) drawnRoles.set(field.alias, role);
+      }
+      children.set(child.alias, {
+        section,
+        // 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
+        // for one query.
+        alias: `${screen.entity.alias}_${child.alias}`,
+        param: `${screen.entity.alias}_id`,
+        entity: child,
+        table: found.table,
+        tableAlias: found.tableAlias,
+        parent,
+        fields,
+        roles: drawnRoles,
+        identity: child.fields.find((field) => roleOf(roles, child.alias, field.alias)?.role === "identity")?.alias,
+        set: set2?.alias,
+        files: files?.alias
+      });
+    };
+    for (const section of sections) {
+      if (section.kind === "children") {
+        const drawn = section.fields.filter((field) => {
+          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);
         continue;
       }
-      fields.set(field.alias, { alias: found[0].alias, id: found[0].field.id, type: field.type, label: field.label });
+      if (section.kind !== "expected_set" || section.source !== "child") continue;
+      const name2 = section.child.fields.filter((field) => roleOf(roles, section.child.alias, field.alias)?.role === "identity");
+      bindChild(
+        "expected_set",
+        section.child,
+        section.parentField,
+        [...name2, section.setField, ...section.filesField === void 0 ? [] : [section.filesField]],
+        section.setField,
+        section.filesField
+      );
     }
-    bound.push({ screen, table: table.table, tableAlias: table.alias, fields, limits });
+    bound.push({ screen, table: own.table, tableAlias: own.tableAlias, fields: own.fields, limits, sections, children });
   }
   return { bound, missing };
 }
-function planTableNames(screens) {
-  return [...new Set(screens.map((screen) => screen.entity.label))];
+function planTableNames(screens, entities, roles) {
+  const names = [];
+  for (const screen of screens) {
+    names.push(screen.entity.label);
+    for (const section of recordSections(screen.entity, entities, roles, recordHeader(screen))) {
+      const child = sectionChild(section);
+      if (child !== void 0) names.push(child.label);
+    }
+  }
+  return [...new Set(names)];
 }
 function planQueries(bound) {
   const queries = {};
   for (const entry of bound) {
-    const columns = [];
-    for (const field of entry.fields.values()) {
-      columns.push(field.type === "files" ? { output: field.id, type: "files", source: field.id, limit: 1 } : field.id);
-    }
     const when = entry.screen.slots.find((slot2) => slot2.role === "when" && slot2.field !== null);
     const whenId = when?.field == null ? void 0 : entry.fields.get(when.field.alias)?.id;
     const sort = whenId === void 0 ? void 0 : [{ field_key: whenId, order: entry.screen.screen.shape === "lifecycle_desk" ? "asc" : "desc" }];
@@ -68094,10 +68335,32 @@ function planQueries(bound) {
       ast: {
         kind: "project",
         from: { kind: "from_table", table_id: entry.table.id, ...sort === void 0 ? {} : { sort } },
-        columns
+        columns: [...entry.fields.values()].map((field) => field.id)
       },
       description: `${entry.screen.screen.label} \u2014 ${entry.screen.shapeLabel} over ${entry.screen.entity.label}`
     };
+    for (const child of entry.children.values()) {
+      if (queries[child.alias] !== void 0) continue;
+      queries[child.alias] = {
+        ast: {
+          kind: "project",
+          from: {
+            kind: "from_table",
+            table_id: child.table.id,
+            filter: {
+              node_type: "condition",
+              type: "select_record_link",
+              field_key: child.parent.id,
+              operator: "has_any_of",
+              value: [`{{params.${child.param}}}`]
+            }
+          },
+          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}`
+      };
+    }
   }
   return queries;
 }
@@ -68109,10 +68372,36 @@ var SHAPE_MODULE = {
   monitored_asset_set: { module: "@lotics/ui/monitored_asset_set", component: "MonitoredAssetSet" },
   trend_deep_dive: { module: "@lotics/ui/trend_deep_dive", component: "TrendDeepDive" }
 };
+var RECORD_MODULES = {
+  RecordPage: "@lotics/ui/record_page",
+  RecordFacts: "@lotics/ui/record_facts",
+  RecordProgress: "@lotics/ui/record_progress",
+  RecordExpectedSet: "@lotics/ui/record_expected_set",
+  RecordChildren: "@lotics/ui/record_children",
+  RecordFiles: "@lotics/ui/record_files"
+};
+var SHAPE_CELLS = ["ContactCell", "DateCell", "IdentityCell", "MoneyCell", "NumberCell", "StageCell", "TextCell"];
+var SKELETON_ROWS = 5;
+var SKELETON_BAR = "72%";
 var str = (value2) => JSON.stringify(value2);
 function pascal(alias) {
   return alias.split(/[^a-zA-Z0-9]+/).filter((part) => part !== "").map((part) => part[0].toUpperCase() + part.slice(1)).join("");
 }
+function camel(alias) {
+  const name2 = pascal(alias);
+  return name2 === "" ? "rows" : name2[0].toLowerCase() + name2.slice(1);
+}
+function currencyOf(field) {
+  return "currency" in field && typeof field.currency === "string" ? field.currency : void 0;
+}
+function isMoney(field) {
+  return currencyOf(field) !== void 0 || "format" in field && field.format === "currency";
+}
+function worthFormat(field) {
+  if (!isMoney(field)) return `, format: "number"`;
+  const stated = currencyOf(field);
+  return stated === void 0 ? "" : `, currency: ${str(stated)}`;
+}
 function slotProp(entry, roles, slot2) {
   if (slot2.field === null) return null;
   const field = entry.fields.get(slot2.field.alias);
@@ -68135,11 +68424,11 @@ function slotProp(entry, roles, slot2) {
         const against = typeof decl.against === "number" ? `() => ${decl.against}` : `(r) => amount(r[T.${limit?.alias}])`;
         return `${slot2.name}={{ label: ${label}, value: (r) => amount(${ref2}), against: ${against}, alert: ${str(decl.alert)} }}`;
       }
-      return `${slot2.name}={{ label: ${label}, value: (r) => amount(${ref2}) }}`;
+      return `${slot2.name}={{ label: ${label}, value: (r) => amount(${ref2})${slot2.name === "worth" ? worthFormat(slot2.field) : ""} }}`;
     }
     case "amount": {
-      const currency = "currency" in slot2.field && typeof slot2.field.currency === "string" ? `, currency: ${str(slot2.field.currency)}` : "";
-      return `${slot2.name}={{ label: ${label}, value: (r) => amount(${ref2})${currency} }}`;
+      const stated = currencyOf(slot2.field);
+      return `${slot2.name}={{ label: ${label}, value: (r) => amount(${ref2})${stated === void 0 ? "" : `, currency: ${str(stated)}`} }}`;
     }
     case "when":
       return `${slot2.name}={{ label: ${label}, value: (r) => row.text(${ref2}) || null }}`;
@@ -68157,6 +68446,13 @@ function slotProp(entry, roles, slot2) {
 }
 var CELLS = `import { readFiles, readLinks, readSelect, row } from "@lotics/app-sdk";
 import { asColorName } from "@lotics/ui/colors";
+import { toDisplayFile, type DisplayFile } from "@lotics/ui/file_thumbnail";
+import { formatDate } from "@lotics/ui/format_date";
+import { formatMoney } from "@lotics/ui/format_money";
+import type { FactValue } from "@lotics/ui/record_facts";
+
+/** A select field's options, as the query's field-option read hands them over. */
+type OptionSource = { options: readonly { key: string; label: string; color?: string }[] } | undefined;
 
 /** A number cell, or nothing \u2014 an empty cell is absent, never 0, and a decimal the query kept as text reads as its number. */
 export const amount = (v: unknown): number | null =>
@@ -68168,79 +68464,560 @@ export const picture = (v: unknown): string | null => {
   return file === undefined ? null : (file.thumbnail_url ?? file.url);
 };
 
+/** A files cell as the kit draws a file \u2014 the conversion is the kit's, never an app's. */
+export const files = (v: unknown): DisplayFile[] => readFiles(v).map(toDisplayFile);
+
 /** A linked record's display name. */
 export const party = (v: unknown): string | null => row.link(v)?.display ?? null;
 
+/** A linked record's id \u2014 where the link goes. */
+export const linked = (v: unknown): string => row.link(v)?.id ?? "";
+
 /** The option keys a select cell holds. */
 export const keys = (v: unknown): string[] => readSelect(v).map((option) => option.key);
 
 /** A select field's options as the stages a shape's strip or set is made of. */
-export const stagesOf = (field: { options: readonly { key: string; label: string; color?: string }[] } | undefined) =>
+export const stagesOf = (field: OptionSource) =>
   (field?.options ?? []).map((option) => ({ key: option.key, label: option.label, color: option.color === undefined ? undefined : asColorName(option.color) }));
 
+/** The one option a cell holds, in the field's own colour. */
+export const stageOf = (field: OptionSource, v: unknown) => stagesOf(field).find((option) => option.key === row.opt(v)) ?? null;
+
+/** The options a cell holds, in the field's own colours. */
+export const chosen = (field: OptionSource, v: unknown) => {
+  const held = keys(v);
+  return stagesOf(field).filter((option) => held.includes(option.key));
+};
+
+/** The required options the record does not hold, by name \u2014 what is holding it where it is. */
+export const missing = (field: OptionSource, present: readonly string[]): string[] =>
+  stagesOf(field)
+    .filter((option) => !present.includes(option.key))
+    .map((option) => option.label);
+
+/** The gap in a required set, as a section's issue \u2014 what is MISSING, by name. Nothing missing, no issue. */
+export const gap = (field: OptionSource, present: readonly string[], say: (names: readonly string[]) => string) => {
+  const absent = missing(field, present);
+  return absent.length === 0 ? undefined : { level: "warning" as const, text: say(absent) };
+};
+
+/** The option each child row was filed under \u2014 the present half of a required set. */
+export const filed = (rows: readonly Record<string, unknown>[], key: string): string[] =>
+  rows.map((child) => row.opt(child[key]) ?? "").filter((option) => option !== "");
+
+/** An amount as the headline figure, in the reader's locale. */
+export const money = (v: unknown, locale: string, none: string, currency?: string): string => {
+  const value = amount(v);
+  return value === null ? none : formatMoney(value, { locale, currency });
+};
+
+/** A measure as the headline figure. */
+export const count = (v: unknown, locale: string, none: string): string => {
+  const value = amount(v);
+  return value === null ? none : value.toLocaleString(locale);
+};
+
+/** A measure on the side of its limit that needs attention. */
+export const past = (value: unknown, limit: unknown, alert: "over" | "under"): boolean => {
+  const read = amount(value);
+  const against = amount(limit);
+  if (read === null || against === null) return false;
+  return alert === "over" ? read > against : read < against;
+};
+
+/** A measure AND the limit it is judged by, as ONE fact \u2014 the meter the register's own row draws, the gap named under it. A row with no limit to read it against has nothing to be over or under, so it is the plain number. */
+export const level = (value: unknown, limit: unknown, alert: "over" | "under"): FactValue => {
+  const against = amount(limit);
+  return against === null
+    ? { kind: "number", value: amount(value) }
+    : { kind: "level", value: amount(value), limit: against, alert };
+};
+
+/** A date cell as the words a record's provenance line carries. */
+export const when = (v: unknown, locale: string): string => formatDate(row.text(v), { locale });
+
 /** Any cell, as the words a record surface shows for it. */
 export const shown = (v: unknown): string => {
   const options = readSelect(v);
   if (options.length > 0) return options.map((option) => option.label).join(", ");
   const links = readLinks(v);
   if (links.length > 0) return links.map((link) => link.display).join(", ");
-  const files = readFiles(v);
-  if (files.length > 0) return files.map((file) => file.filename).join(", ");
+  const attached = readFiles(v);
+  if (attached.length > 0) return attached.map((file) => file.filename).join(", ");
   if (typeof v === "boolean") return v ? "\u2713" : "";
   return row.text(v);
 };
 `;
-function screenSource(entry, roles) {
+var CELL_HELPERS = [
+  "amount",
+  "chosen",
+  "count",
+  "filed",
+  "files",
+  "gap",
+  "keys",
+  "level",
+  "linked",
+  "missing",
+  "money",
+  "party",
+  "past",
+  "picture",
+  "shown",
+  "stageOf",
+  "stagesOf",
+  "when"
+];
+var SECTION_ICON = {
+  facts: "info",
+  progress: "workflow",
+  /** A required set of PAPERS — one row per document the record owes. */
+  documents: "file-stack",
+  /** A required set of THINGS — services, checks — ticked off, nothing attached. */
+  items: "list-checks",
+  children: "list",
+  files: "image"
+};
+function pagesByEntity(bound, app) {
+  const pages = /* @__PURE__ */ new Map();
+  for (const entry of bound) {
+    if (entry.screen.app.alias !== app.alias || entry.screen.record !== "page") continue;
+    if (!pages.has(entry.screen.entity.alias)) pages.set(entry.screen.entity.alias, entry.screen.screen.alias);
+  }
+  return pages;
+}
+function factSource(field, bound, role, ref2, options, pages, level) {
+  const flag = `{ kind: "flag", value: row.bool(${ref2}), yes: words.record.yes, no: words.record.no }`;
+  const value2 = (() => {
+    if (role === "contact") return `{ kind: "contact", text: row.text(${ref2}) }`;
+    if (role === "verdict") return flag;
+    if (level !== void 0) return `level(${ref2}, ${level.against}, ${str(level.alert)})`;
+    switch (field.type) {
+      case "boolean":
+        return flag;
+      case "number": {
+        const stated = currencyOf(field);
+        return isMoney(field) ? `{ kind: "money", amount: amount(${ref2})${stated === void 0 ? "" : `, currency: ${str(stated)}`} }` : `{ kind: "number", value: amount(${ref2}) }`;
+      }
+      case "formula":
+      case "rollup":
+        return `{ kind: "number", value: amount(${ref2}) }`;
+      case "date":
+        return `{ kind: "date", date: row.text(${ref2}) || null }`;
+      case "select":
+        return field.multi === true ? `{ kind: "set", options: chosen(${options}, ${ref2}) }` : `{ kind: "stage", stage: stageOf(${options}, ${ref2}) }`;
+      case "select_record_link": {
+        const target = pages.get(field.target_entity);
+        const open = target === void 0 ? "" : `, onOpen: () => navigate(${str(`/${target}/`)} + linked(${ref2}))`;
+        return `{ kind: "link", name: party(${ref2})${open} }`;
+      }
+      case "files":
+        return `{ kind: "files", files: files(${ref2}) }`;
+      case "text":
+      case "autonumber":
+        return `{ kind: "text", text: row.text(${ref2}) }`;
+      default:
+        return `{ kind: "text", text: shown(${ref2}) }`;
+    }
+  })();
+  return `{ label: ${str(bound.label)}, value: ${value2} }`;
+}
+function factsBlock(facts, pad) {
+  return `<RecordFacts
+${pad}  facts={[
+${facts.map((fact) => `${pad}    ${fact},`).join("\n")}
+${pad}  ]}
+${pad}/>`;
+}
+function levelRead(entry, level, read) {
+  if (level === void 0) return void 0;
+  if (typeof level.limit === "number") return { against: String(level.limit), alert: level.alert };
+  const bound = entry.fields.get(level.limit.alias);
+  return bound === void 0 ? void 0 : { against: read(bound.alias), alert: level.alert };
+}
+function factsSource(entry, roles, section, read, pages, pad) {
+  const facts = section.fields.flatMap((field) => {
+    const bound = entry.fields.get(field.alias);
+    if (bound === void 0) return [];
+    const role = roleOf(roles, entry.screen.entity.alias, field.alias)?.role;
+    const level = levelRead(entry, section.levels[field.alias], read);
+    return [factSource(field, bound, role, read(bound.alias), `fields[T.${bound.alias}]`, pages, level)];
+  });
+  return factsBlock(facts, pad);
+}
+function childFactsSource(child, pages, pad) {
+  const rows = camel(child.alias);
+  const facts = [...child.fields.keys()].flatMap((alias) => {
+    const bound = child.fields.get(alias);
+    const field = child.entity.fields.find((candidate) => candidate.alias === alias);
+    if (bound === void 0 || field === void 0) return [];
+    const ref2 = `child[F.${child.tableAlias}.${bound.alias}]`;
+    return [factSource(field, bound, child.roles.get(alias), ref2, `${rows}Fields[F.${child.tableAlias}.${bound.alias}]`, pages)];
+  });
+  return factsBlock(facts, pad);
+}
+function roleColumn(spec) {
+  const { role, bind, ref: ref2, options } = spec;
+  const head = `{ key: ${str(spec.key)}, label: ${str(spec.label)}, priority: ${columnPriority(role)}`;
+  switch (role) {
+    case "identity":
+      return `${head}, flex: 2, cell: (${bind}) => <IdentityCell title={${spec.type === "select_record_link" ? `party(${ref2}) ?? ""` : `row.text(${ref2})`}} /> }`;
+    case "party":
+      return `${head}, flex: 1, cell: (${bind}) => <TextCell value={party(${ref2}) ?? ""} /> }`;
+    case "contact":
+      return `${head}, width: 200, cell: (${bind}) => <ContactCell value={row.text(${ref2})} copyLabel={words.copyButton.copy} /> }`;
+    case "when":
+      return `${head}, width: 112, cell: (${bind}) => <DateCell value={row.text(${ref2})} /> }`;
+    // An absent figure is ABSENT — a `?? 0` prints a plausible wrong number, and
+    // the same value reads "—" in the facts beside it.
+    case "measure":
+      return `${head}, width: 96, align: "right", cell: (${bind}) => { const level = amount(${ref2}); return level === null ? null : <NumberCell value={level} />; } }`;
+    case "amount":
+      return `${head}, width: 128, align: "right", cell: (${bind}) => { const sum = amount(${ref2}); return sum === null ? null : <MoneyCell value={sum} />; } }`;
+    case "lifecycle":
+      return `${head}, width: 120, cell: (${bind}) => { const held = stageOf(${options}, ${ref2}); return held === null ? null : <StageCell stage={held} />; } }`;
+    case "verdict":
+      return `${head}, width: 120, cell: (${bind}) => { const answer = row.bool(${ref2}); return answer === null ? null : <TextCell value={answer ? words.record.yes : words.record.no} />; } }`;
+    default:
+      return `${head}, width: 120, cell: (${bind}) => <TextCell value={shown(${ref2})} /> }`;
+  }
+}
+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;
+  return roleColumn({
+    role,
+    key: field.alias,
+    label: field.label,
+    type: field.type,
+    bind: "child",
+    ref: `child[F.${child.tableAlias}.${field.alias}]`,
+    options: `${camel(child.alias)}Fields[F.${child.tableAlias}.${field.alias}]`
+  });
+}
+function childrenSource(child, pages, pad) {
+  const rows = camel(child.alias);
+  const drawn = [...child.fields.keys()].filter((alias) => child.roles.get(alias) !== void 0);
+  const shown = new Set(
+    [...drawn].sort((a, b) => columnPriority(child.roles.get(a) ?? "identity") - columnPriority(child.roles.get(b) ?? "identity")).slice(0, CHILD_COLUMNS_SHOWN)
+  );
+  const columns = drawn.flatMap((alias) => {
+    const column = shown.has(alias) ? childColumn(child, alias) : null;
+    return column === null ? [] : [column];
+  });
+  const name2 = child.identity === void 0 ? void 0 : child.fields.get(child.identity);
+  const identity = name2 === void 0 ? `() => ""` : `(child) => ${name2.type === "select_record_link" ? `party(child[F.${child.tableAlias}.${name2.alias}]) ?? ""` : `row.text(child[F.${child.tableAlias}.${name2.alias}])`}`;
+  return `<RecordChildren
+${pad}  rows={${rows}.rows}
+${pad}  rowKey={(child) => child.__source_record_id ?? ""}
+${pad}  identity={${identity}}
+${pad}  columns={[
+${columns.map((column) => `${pad}    ${column},`).join("\n")}
+${pad}  ]}
+${pad}  record={{ render: (child) => (
+${pad}    ${childFactsSource(child, pages, `${pad}    `)}
+${pad}  ) }}
+${pad}  loading={${rows}.loading}
+${pad}  error={${rows}.error === null ? undefined : { message: ${rows}.error, onRetry: ${rows}.refetch }}
+${pad}/>`;
+}
+function deskSource(child, pages, pad) {
+  const rows = camel(child.alias);
+  const set2 = child.set === void 0 ? void 0 : child.fields.get(child.set);
+  if (set2 === void 0) return "";
+  const key = `F.${child.tableAlias}.${set2.alias}`;
+  const name2 = child.identity === void 0 ? void 0 : child.fields.get(child.identity);
+  const attached = child.files === void 0 ? void 0 : child.fields.get(child.files);
+  const target = pages.get(child.entity.alias);
+  const named = name2 === void 0 ? `stageOf(${rows}Fields[${key}], child[${key}])?.label ?? ""` : name2.type === "select_record_link" ? `party(child[F.${child.tableAlias}.${name2.alias}]) ?? ""` : `row.text(child[F.${child.tableAlias}.${name2.alias}])`;
+  const item = [
+    `key: row.opt(child[${key}]) ?? ""`,
+    `label: ${named}`,
+    ...attached === void 0 ? [] : [`files: files(child[F.${child.tableAlias}.${attached.alias}])`],
+    ...target === void 0 ? [] : [`onOpen: () => navigate(${str(`/${target}/`)} + (child.__source_record_id ?? ""))`]
+  ].join(", ");
+  return `<RecordExpectedSet
+${pad}  required={stagesOf(${rows}Fields[${key}])}
+${pad}  present={${rows}.rows.map((child) => ({ ${item} }))}
+${pad}  kind=${str(attached === void 0 ? "items" : "files")}${attached === void 0 ? "" : `
+${pad}  onOpenFile={(file) => void openExternal(file.url)}`}
+${pad}/>`;
+}
+function recordSource(entry, roles, read, pages, pad, led) {
+  const blockers = entry.sections.flatMap((section) => section.kind === "expected_set" && section.source === "own" ? [entry.fields.get(section.field.alias)] : []).flatMap((field) => field === void 0 ? [] : [`...missing(fields[T.${field.alias}], keys(${read(field.alias)}))`]).join(", ");
+  let facts = null;
+  const sections = [];
+  for (const section of entry.sections) {
+    switch (section.kind) {
+      case "facts": {
+        const { fields, levels } = section;
+        facts = (at2) => factsSource(entry, roles, { fields, levels }, read, pages, at2);
+        break;
+      }
+      case "progress": {
+        const field = entry.fields.get(section.field.alias);
+        if (field === void 0) break;
+        sections.push({
+          key: field.alias,
+          label: field.label,
+          icon: SECTION_ICON.progress,
+          body: `<RecordProgress
+${pad}  options={stagesOf(fields[T.${field.alias}])}
+${pad}  value={row.opt(${read(field.alias)})}${blockers === "" ? "" : `
+${pad}  blockers={[${blockers}]}`}
+${pad}/>`
+        });
+        break;
+      }
+      case "expected_set": {
+        if (section.source === "own") {
+          const field = entry.fields.get(section.field.alias);
+          if (field === void 0) break;
+          sections.push({
+            key: field.alias,
+            label: field.label,
+            icon: SECTION_ICON.items,
+            issue: `gap(fields[T.${field.alias}], keys(${read(field.alias)}), words.record.gap)`,
+            // The entity's OWN multi-select: the chosen options are things the
+            // record was sold or owes, not documents — there is nothing to
+            // attach and nothing to show a face of.
+            body: `<RecordExpectedSet
+${pad}  required={stagesOf(fields[T.${field.alias}])}
+${pad}  present={chosen(fields[T.${field.alias}], ${read(field.alias)}).map((option) => ({ key: option.key, label: option.label }))}
+${pad}  kind="items"
+${pad}/>`
+          });
+          break;
+        }
+        const child = entry.children.get(section.child.alias);
+        if (child === void 0 || child.set === void 0) break;
+        const rows = camel(child.alias);
+        const key = `F.${child.tableAlias}.${child.fields.get(child.set)?.alias ?? child.set}`;
+        sections.push({
+          key: child.entity.alias,
+          label: child.entity.label,
+          // A desk that attaches files is the DOCUMENTS it holds; one that
+          // attaches nothing is a list of things ticked off.
+          icon: child.files === void 0 ? SECTION_ICON.items : SECTION_ICON.documents,
+          // The band says WHICH entry is missing, by name — a fraction is the
+          // meter's caption, and the meter is already inside the section.
+          issue: `gap(${rows}Fields[${key}], filed(${rows}.rows, ${key}), words.record.gap)`,
+          body: deskSource(child, pages, pad)
+        });
+        break;
+      }
+      case "children": {
+        const child = entry.children.get(section.child.alias);
+        if (child === void 0) break;
+        sections.push({
+          key: child.entity.alias,
+          label: child.entity.label,
+          icon: SECTION_ICON.children,
+          body: childrenSource(child, pages, pad)
+        });
+        break;
+      }
+      // ONE PILE, PICTURES FIRST: every files field the entity carries, the mark
+      // leading, read into one section. A record's files are what it HOLDS, and
+      // splitting them by the field they were filed in makes a reader open three
+      // headings to see three photographs.
+      //
+      // EXCEPT THE ONE THE HEADER ALREADY DREW. A page leads with the mark's
+      // picture, so a section over that same field restates it a hundred pixels
+      // lower — and a section over what is LEFT of it reads "nothing here" on
+      // the ordinary record whose likeness is one photograph, contradicting the
+      // photograph above it. The mark is the header's; the section is every
+      // OTHER files field, and a record with none has no files section.
+      case "files": {
+        const held = section.fields.flatMap((field) => {
+          if (field.alias === led) return [];
+          const bound = entry.fields.get(field.alias);
+          return bound === void 0 ? [] : [{ field, bound }];
+        });
+        if (held.length === 0) break;
+        const pile = held.length === 1 ? `files(${read(held[0].bound.alias)})` : `[${held.map(({ bound }) => `...files(${read(bound.alias)})`).join(", ")}]`;
+        const marked = held.length === 1 && roleOf(roles, entry.screen.entity.alias, held[0].field.alias)?.role === "mark";
+        sections.push({
+          key: held[0].bound.alias,
+          label: held.map(({ bound }) => bound.label).join(" \xB7 "),
+          icon: SECTION_ICON.files,
+          body: `<RecordFiles files={${pile}}${marked ? ` lead="photos"` : ""} />`
+        });
+        break;
+      }
+    }
+  }
+  return { facts, sections };
+}
+function recordPreamble(entry, text, source, scoped) {
+  const lines = [];
+  if (!scoped.navigate && text.includes("navigate(")) lines.push(`  const navigate = useNavigate();`);
+  if (text.includes("words.")) lines.push(`  const words = useLoticsLocale();`);
+  if (/\btag\b/.test(text)) lines.push(`  const tag = useLocaleTag();`);
+  if (!scoped.options && text.includes("fields[T.")) {
+    lines.push(`  const options = useFieldOptions(${str(entry.screen.screen.alias)});`, `  const { fields } = options;`);
+  }
+  if (entry.children.size > 0) lines.push(`  const recordId = ${source};`);
+  for (const child of entry.children.values()) {
+    const rows = camel(child.alias);
+    lines.push(`  const ${rows} = useQuery(${str(child.alias)}, { ${child.param}: recordId }, { enabled: recordId !== "" });`);
+    if (text.includes(`${rows}Fields[`)) lines.push(`  const ${rows}Fields = useFieldOptions(${str(child.alias)}).fields;`);
+  }
+  return lines;
+}
+function drawerSection(section) {
+  return `        <Section>
+          <SectionHeading>
+            <SectionHeadingTitle icon=${str(section.icon)}>${section.label}</SectionHeadingTitle>
+          </SectionHeading>
+          ${section.body}
+        </Section>`;
+}
+function pageSection(section) {
+  const issue2 = section.issue === void 0 ? "" : `
+          issue: ${section.issue},`;
+  return `        {
+          key: ${str(section.key)},
+          label: ${str(section.label)},
+          icon: ${str(section.icon)},${issue2}
+          children: (
+            ${section.body}
+          ),
+        }`;
+}
+function screenSource(entry, roles, pages) {
   const { screen } = entry;
   const name2 = pascal(screen.screen.alias);
   const alias = screen.screen.alias;
+  const shapeName = screen.screen.shape;
+  const custom2 = shapeName === CUSTOM_SHAPE;
+  const page = screen.record === "page";
   const fieldsInOrder = [...entry.fields.values()];
-  const recordRows = fieldsInOrder.map((field) => `        <DetailRow label=${str(field.label)}>
-          <Text size="sm">{shown(r[T.${field.alias}])}</Text>
-        </DetailRow>`).join("\n");
   const identity = screen.slots.find((slot2) => slot2.role === "identity" && slot2.field !== null);
   const identityField = identity?.field == null ? void 0 : entry.fields.get(identity.field.alias);
-  const identityRead = identityField === void 0 ? void 0 : identityField.type === "select_record_link" ? `party(r[T.${identityField.alias}]) ?? ""` : `row.text(r[T.${identityField.alias}])`;
-  const pageTitle = identityRead ?? (fieldsInOrder.length === 0 ? `""` : `shown(r[T.${fieldsInOrder[0].alias}])`);
-  const page = screen.record === "page";
-  const record2 = `
-/** The record behind a row \u2014 every column the screen reads, as words. Grow it from here. */
+  const read = (fieldAlias) => `${page ? "r?." : "r"}[T.${fieldAlias}]`;
+  const named = (ref2) => identityField === void 0 ? void 0 : identityField.type === "select_record_link" ? `party(${ref2(identityField.alias)}) ?? ""` : `row.text(${ref2(identityField.alias)})`;
+  const rowRead = (fieldAlias) => `r[T.${fieldAlias}]`;
+  const identityRead = named(rowRead);
+  const fallback = fieldsInOrder.length === 0 ? `""` : fieldsInOrder[0].alias;
+  const rowTitle = identityRead ?? (fallback === `""` ? `""` : `shown(r[T.${fallback}])`);
+  const pageTitle = named(read) ?? (fallback === `""` ? `""` : `shown(${read(fallback)})`);
+  const markField = screen.entity.fields.find((field) => roleOf(roles, screen.entity.alias, field.alias)?.role === "mark");
+  const markBound = markField === void 0 ? void 0 : entry.fields.get(markField.alias);
+  const mark = markBound === void 0 ? "" : `
+      mark={{ kind: ${str(shapeName === "party_register" ? "group" : "thing")}, name: ${pageTitle}, image: picture(${read(markBound.alias)}) }}`;
+  const ledOnPage = markBound === void 0 ? void 0 : markField?.alias;
+  const inDrawer = recordSource(entry, roles, read, pages, "          ", void 0);
+  const drawerBody = (() => {
+    const parts = [
+      ...inDrawer.facts === null ? [] : [`      ${inDrawer.facts("      ")}`],
+      ...inDrawer.sections.length === 0 ? [] : [`      <SectionStack>
+${inDrawer.sections.map(drawerSection).join("\n")}
+      </SectionStack>`]
+    ];
+    return `    <Stack gap={24}>
+${parts.join("\n")}
+    </Stack>`;
+  })();
+  const drawerPreamble = recordPreamble(entry, drawerBody, `r.__source_record_id ?? ""`, { navigate: false, options: false });
+  const drawer = page || custom2 ? "" : `
+/** The record behind a row \u2014 the facts the plan left over, and the work its roles name. */
 function ${name2}Record({ r }: { r: QueryRow }) {
-  return (
-    <DetailTable>
-${recordRows}
-    </DetailTable>
+${drawerPreamble.join("\n")}${drawerPreamble.length === 0 ? "" : "\n"}  return (
+${drawerBody}
   );
 }
 `;
+  const inPage = recordSource(entry, roles, read, pages, "            ", ledOnPage);
+  const pageSections = inPage.sections.length > 0 ? inPage.sections : [
+    {
+      key: "facts",
+      label: screen.entity.label,
+      icon: SECTION_ICON.facts,
+      body: (inPage.facts ?? ((at2) => factsBlock([], at2)))("            ")
+    }
+  ];
+  const pageFacts = inPage.facts === null || inPage.sections.length === 0 ? "" : `
+      facts={
+        ${inPage.facts("        ")}
+      }`;
+  const amountSlot = screen.slots.find((slot2) => slot2.role === "amount" && slot2.field !== null);
+  const measureSlot = screen.slots.find((slot2) => slot2.role === "measure" && slot2.field !== null);
+  const figure = (() => {
+    if (amountSlot?.field != null) {
+      const field2 = entry.fields.get(amountSlot.field.alias);
+      if (field2 !== void 0) {
+        const stated2 = currencyOf(amountSlot.field);
+        return `
+      figure={{ label: ${str(field2.label)}, value: money(${read(field2.alias)}, tag, words.record.none${stated2 === void 0 ? "" : `, ${str(stated2)}`}) }}`;
+      }
+    }
+    if (measureSlot?.field == null) return "";
+    const field = entry.fields.get(measureSlot.field.alias);
+    if (field === void 0) return "";
+    const decl = roleOf(roles, screen.entity.alias, measureSlot.field.alias);
+    const limitAlias = entry.limits.get(measureSlot.field.alias);
+    const limit = limitAlias === void 0 ? void 0 : entry.fields.get(limitAlias);
+    const against = typeof decl?.against === "number" ? String(decl.against) : limit === void 0 ? void 0 : read(limit.alias);
+    const tone = decl?.alert === void 0 || against === void 0 ? "" : `, tone: past(${read(field.alias)}, ${against}, ${str(decl.alert)}) ? "danger" : undefined`;
+    const stated = currencyOf(measureSlot.field);
+    const value2 = isMoney(measureSlot.field) ? `money(${read(field.alias)}, tag, words.record.none${stated === void 0 ? "" : `, ${str(stated)}`})` : `count(${read(field.alias)}, tag, words.record.none)`;
+    return `
+      figure={{ label: ${str(field.label)}, value: ${value2}${tone} }}`;
+  })();
+  const whenSlot = screen.slots.find((slot2) => slot2.role === "when" && slot2.field !== null);
+  const whenField = whenSlot?.field == null ? void 0 : entry.fields.get(whenSlot.field.alias);
+  const pageProps = `      title={${pageTitle}}${mark}${whenField === void 0 ? "" : `
+      subtitle={when(${read(whenField.alias)}, tag) || undefined}`}${figure}
+      back={{ label: ${str(screen.screen.label)}, onPress: () => navigate(-1) }}`;
+  const pageReads = pageProps + pageFacts + pageSections.map(pageSection).join("");
+  const pageState = pageReads.includes("fields[T.") ? `      loading={loading || options.loading}
+      error={error === null ? (options.error === null ? undefined : { message: options.error, onRetry: options.refetch }) : { message: error, onRetry: refetch }}` : `      loading={loading}
+      error={error === null ? undefined : { message: error, onRetry: refetch }}`;
+  const pageBody = `    <RecordPage
+${pageProps}
+${pageState}
+      missing={error === null && !loading && r === undefined}${pageFacts}
+      sections={[
+${pageSections.map(pageSection).join(",\n")},
+      ]}
+    />`;
+  const pagePreamble = recordPreamble(entry, pageBody, `r?.__source_record_id ?? ""`, { navigate: true, options: false });
   const recordScreen = page ? `
 /** The page a row opens: arrived at cold, so it stands without the list. */
 export function ${name2}RecordScreen() {
   const { id } = useParams();
   const navigate = useNavigate();
-  const words = useLoticsLocale().shape;
-  const { rows } = useQuery(${str(alias)});
+  const { rows, loading, error, refetch } = useQuery(${str(alias)});
   const r = rows.find((candidate) => candidate.__source_record_id === id);
-  return (
-    <Stack gap={16}>
-      <BackButton onPress={() => navigate(-1)} />
-      {r === undefined ? (
-        <RegionState state="empty" message={words.empty} />
-      ) : (
-        <>
-          <RecordSummary title={${pageTitle}} />
-          <${name2}Record r={r} />
-        </>
-      )}
-    </Stack>
+${pagePreamble.join("\n")}${pagePreamble.length === 0 ? "" : "\n"}  return (
+${pageBody}
   );
 }
 ` : "";
   let body;
   let shapeImport = "";
-  const shapeName = screen.screen.shape;
   if (shapeName === CUSTOM_SHAPE) {
     const slots = screen.slots.map((slot2) => `${slot2.name} (${slot2.role}${slot2.field === null ? "" : `: ${slot2.field.label}`})`).join(", ");
+    const drawn = screen.slots.flatMap((slot2) => {
+      if (slot2.field === null || !DRAWN_ROLES.includes(slot2.role)) return [];
+      const field = entry.fields.get(slot2.field.alias);
+      if (field === void 0) return [];
+      return [
+        roleColumn({
+          role: slot2.role,
+          key: field.alias,
+          label: field.label,
+          type: field.type,
+          bind: "r",
+          ref: `r[T.${field.alias}]`,
+          options: `fields[T.${field.alias}]`
+        })
+      ];
+    });
+    const columns = drawn.length > 0 ? drawn : [`{ key: "identity", label: ${str(fieldsInOrder[0]?.label ?? "")}, flex: 2, cell: (r) => <IdentityCell title={${rowTitle}} /> }`];
+    const usesFields = columns.some((column) => column.includes("fields["));
     body = `
 const T = F.${entry.tableAlias};
 
@@ -68248,27 +69025,54 @@ const T = F.${entry.tableAlias};
  * ${screen.screen.label} \u2014 a CUSTOM screen: no registry shape fits it, so the plan
  * declared its slots as roles and the kit is composed here by hand.
  * Slots: ${slots}.
- * The query already reads every slot's column; build the screen from
- * \`node_modules/@lotics/ui/llms.txt\`, then file \`lotics report\` naming the shape
- * you wished existed.
+ * Each column below is the cell that slot's ROLE names \u2014 the device a registry
+ * shape draws that value with. Grow the screen from here
+ * (\`node_modules/@lotics/ui/llms.txt\`), then file \`lotics report\` naming the
+ * shape you wished existed.
  */
 export function ${name2}Screen() {
-  const { rows, loading, error, refetch } = useQuery(${str(alias)});
-  const words = useLoticsLocale().shape;${page ? "\n  const navigate = useNavigate();" : ""}
-  if (error !== null) return <RegionState state="error" message={error} onRetry={refetch} />;
-  if (loading) return <RegionState state="loading" />;
-  if (rows.length === 0) return <RegionState state="empty" message={words.empty} />;
+  const { rows, loading, error, refetch } = useQuery(${str(alias)});${usesFields ? `
+  const options = useFieldOptions(${str(alias)});
+  const { fields } = options;` : ""}
+  const words = useLoticsLocale();${page ? "\n  const navigate = useNavigate();" : ""}
+  const columns: ShapeColumn<QueryRow>[] = [
+${columns.map((column) => `    ${column},`).join("\n")}
+  ];
+  if (error !== null) return <RegionState state="error" message={error} onRetry={refetch} />;${usesFields ? `
+  if (options.error !== null) return <RegionState state="error" message={options.error} onRetry={options.refetch} />;` : ""}
+  // A READ IN FLIGHT WAITS AS THE REGISTER IT IS BECOMING, never a spinner: the
+  // columns above are already known, so the rows land into this grid without
+  // moving an edge. Five rows \u2014 enough for the grid to read as a register, too
+  // few to claim how long the band will be \u2014 and each bar stops short of its
+  // column so the row reads as cells rather than one slab.
+  if (loading${usesFields ? " || options.loading" : ""})
+    return (
+      <Table columns={columns}>
+        {Array.from({ length: ${SKELETON_ROWS} }, (_unused, index) => (
+          <TableRow key={index}>
+            {columns.map((column) => (
+              <TableCell key={column.key}>
+                <Skeleton width=${str(SKELETON_BAR)} />
+              </TableCell>
+            ))}
+          </TableRow>
+        ))}
+      </Table>
+    );
+  if (rows.length === 0) return <RegionState state="empty" message={words.shape.empty} />;
   return (
-    <Stack gap={16}>
+    <Table columns={columns}>
       {rows.map((r) => (
-        ${page ? `<PressableRow key={r.__source_record_id} accessibilityLabel={${pageTitle}} onPress={() => navigate(${str(`/${alias}/`)} + (r.__source_record_id ?? ""))}>
-          <${name2}Record r={r} />
-        </PressableRow>` : `<${name2}Record key={r.__source_record_id} r={r} />`}
+        <TableRow key={r.__source_record_id}${page ? ` accessibilityLabel={${rowTitle}} onPress={() => navigate(${str(`/${alias}/`)} + (r.__source_record_id ?? ""))}` : ""}>
+          {columns.map((column) => (
+            <TableCell key={column.key}>{column.cell(r)}</TableCell>
+          ))}
+        </TableRow>
       ))}
-    </Stack>
+    </Table>
   );
 }
-${record2}${recordScreen}`;
+${recordScreen}`;
   } else {
     const shape = SHAPE_MODULE[shapeName];
     shapeImport = `import { ${shape.component} } from ${str(shape.module)};`;
@@ -68306,23 +69110,35 @@ ${state}
     />
   );
 }
-${record2}${recordScreen}`;
-  }
-  const sdk = [body.includes("useFieldOptions(") ? "useFieldOptions" : "", body.includes("row.") ? "row" : "", "useQuery", "type QueryRow"].filter((name3) => name3 !== "");
-  const cells = ["amount", "keys", "party", "picture", "shown", "stagesOf"].filter((helper) => body.includes(`${helper}(`));
-  const kit = (entry2, module2) => body.includes(`<${entry2}`) || body.includes(`${entry2}(`) ? `import { ${entry2} } from ${str(module2)};` : "";
+${drawer}${recordScreen}`;
+  }
+  const sdk = [
+    body.includes("useFieldOptions(") ? "useFieldOptions" : "",
+    body.includes("openExternal(") ? "openExternal" : "",
+    body.includes("row.") ? "row" : "",
+    "useQuery",
+    // A screen whose record opens as a PAGE reads its row out of the query and
+    // never types one of its own, so the row type is not always reached for.
+    /\bQueryRow\b/.test(body) ? "type QueryRow" : ""
+  ].filter((each) => each !== "");
+  const cells = CELL_HELPERS.filter((helper) => body.includes(`${helper}(`));
+  const kit = (component, module2) => body.includes(`<${component}`) ? `import { ${component} } from ${str(module2)};` : "";
+  const router = ["useNavigate", "useParams"].filter((hook) => body.includes(`${hook}()`));
+  const sheet = [...SHAPE_CELLS.filter((cell) => body.includes(`<${cell} `)), ...body.includes("ShapeColumn<") ? ["type ShapeColumn"] : []];
+  const locale = ["useLocaleTag", "useLoticsLocale"].filter((hook) => body.includes(`${hook}(`));
   const imports = [
     `import { ${sdk.join(", ")} } from "@lotics/app-sdk";`,
-    page ? `import { useNavigate, useParams } from "react-router";` : "",
-    kit("BackButton", "@lotics/ui/back_button"),
-    `import { DetailRow, DetailTable } from "@lotics/ui/detail_row";`,
+    router.length === 0 ? "" : `import { ${router.join(", ")} } from "react-router";`,
     shapeImport,
-    body.includes("useLoticsLocale(") ? `import { useLoticsLocale } from "@lotics/ui/locale";` : "",
-    kit("PressableRow", "@lotics/ui/pressable_row"),
-    kit("RecordSummary", "@lotics/ui/record_summary"),
+    locale.length === 0 ? "" : `import { ${locale.join(", ")} } from "@lotics/ui/locale";`,
+    ...Object.entries(RECORD_MODULES).map(([component, module2]) => kit(component, module2)),
     kit("RegionState", "@lotics/ui/region_state"),
+    body.includes("<Section>") ? `import { Section, SectionHeading, SectionHeadingTitle } from "@lotics/ui/section_heading";` : "",
+    kit("SectionStack", "@lotics/ui/section_stack"),
+    sheet.length === 0 ? "" : `import { ${sheet.join(", ")} } from "@lotics/ui/shape_frame";`,
+    kit("Skeleton", "@lotics/ui/skeleton"),
     kit("Stack", "@lotics/ui/stack"),
-    `import { Text } from "@lotics/ui/text";`,
+    body.includes("<Table ") ? `import { Table, TableCell, TableRow } from "@lotics/ui/table";` : "",
     `import { F } from "../../.lotics/app_fields";`,
     cells.length === 0 ? "" : `import { ${cells.join(", ")} } from "./cells";`
   ].filter((line) => line !== "");
@@ -68386,10 +69202,11 @@ export default function App() {
 `;
 }
 function buildPlanFiles(app, bound, roles) {
+  const pages = pagesByEntity(bound, app);
   return [
     { path: "src/App.tsx", content: appSource(app, bound) },
     { path: "src/screens/cells.ts", content: CELLS },
-    ...bound.map((entry) => ({ path: `src/screens/${entry.screen.screen.alias}.tsx`, content: screenSource(entry, roles) }))
+    ...bound.map((entry) => ({ path: `src/screens/${entry.screen.screen.alias}.tsx`, content: screenSource(entry, roles, pages) }))
   ];
 }
 
@@ -68942,8 +69759,8 @@ function noteCopiedContent(templates, knowledgeDocs) {
     );
   }
 }
-async function libraryListPublic() {
-  const [presets, packages] = await Promise.all([fetchPresetIndex(), fetchOfficialStarters()]);
+async function libraryListPublic(apiUrl) {
+  const [presets, packages] = await Promise.all([fetchPresetIndex(), fetchOfficialStarters(apiUrl)]);
   printPresetSection(presets);
   printPackageSection(packages, "published by Lotics");
   console.error(
@@ -69071,8 +69888,8 @@ function printPackageHead(pkg) {
   console.log(`
 version      ${pkg.latest_version}`);
 }
-async function libraryShowPublic(starter_id) {
-  const pkg = await getOfficialStarter(starter_id);
+async function libraryShowPublic(apiUrl, starter_id) {
+  const pkg = await getOfficialStarter(apiUrl, starter_id);
   printPackageHead(pkg);
   console.log(`trust        official \u2014 reviewed by Lotics`);
   printPackageEntities(pkg.contract.entities);
@@ -69280,7 +70097,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| `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  "san_pham": { "ten": "identity", "anh": "mark" },\n  "ton_kho":  { "ton": { "role": "measure", "against": "ton_toi_thieu", "alert": "under" },\n                "hieu_suat": { "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": "kinh_doanh", "name": "Kinh doanh",\n    "description": "\u2026", "icon": "briefcase", "theme": { "color": "blue" }, // optional\n    "screens": [\n      { "alias": "khach_hang", "label": "Kh\xE1ch h\xE0ng", "shape": "party_register", "entity": "customer" },\n      { "alias": "don_hang",   "label": "\u0110\u01A1n h\xE0ng",   "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` | `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) | `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\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": "bang_do", "label": "B\u1EA3ng \u0111o", "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  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```\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.\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` 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';
 
 // src/scaffold_commands.ts
 function printModelReference() {
@@ -69411,6 +70228,39 @@ function resolvePlan(model) {
     })
   );
 }
+function describeRecord(model, resolved) {
+  const labels = (fields) => fields.map((field) => field.label).join(" \xB7 ");
+  const header = recordHeader(resolved);
+  const stated = [header.title, header.subtitle, header.figure].filter(
+    (field) => field !== void 0
+  );
+  const sections = recordSections(resolved.entity, model.contract.entities, model.field_roles, header).map((section) => {
+    switch (section.kind) {
+      case "facts": {
+        const fact = (field) => {
+          const level = section.levels[field.alias];
+          if (level === void 0) return field.label;
+          return `${field.label} against ${typeof level.limit === "number" ? level.limit : level.limit.label}`;
+        };
+        return `facts (${section.fields.map(fact).join(" \xB7 ")})`;
+      }
+      case "progress":
+        return section.field.type === "select" ? `progress: ${section.field.label} (${count(section.field.options.length, "stage")})` : `progress: ${section.field.label}`;
+      case "expected_set": {
+        const required2 = section.source === "own" ? section.field : section.setField;
+        const name2 = section.source === "own" ? section.field.label : section.child.label;
+        if (required2.type !== "select") return `documents: ${name2}`;
+        const set2 = `${required2.options.length} required`;
+        return section.source === "own" ? `documents: ${name2} (${set2})` : `documents: ${name2} (${required2.label}: ${set2})`;
+      }
+      case "children":
+        return `lines: ${section.child.label} (${section.fields.length === 0 ? "none" : labels(section.fields)})`;
+      case "files":
+        return `files: ${labels(section.fields)}`;
+    }
+  });
+  return [...stated.length === 0 ? [] : [`header (${labels(stated)})`], ...sections].join(" \xB7 ");
+}
 function describePlan(model) {
   const lines = [];
   let lastApp;
@@ -69427,6 +70277,7 @@ function describePlan(model) {
     lines.push(
       `    ${resolved.slots.map((entry) => `${entry.name} ${entry.field === null ? "(none)" : entry.field.label}`).join(" \xB7 ")}`
     );
+    lines.push(`    record: ${describeRecord(model, resolved)}`);
   }
   return lines;
 }
@@ -77492,7 +78343,7 @@ async function resolvePlanForCreate(client, from) {
     if (typeof table_id !== "string" || typeof table_name !== "string") continue;
     idsByName.set(table_name, [...idsByName.get(table_name) ?? [], table_id]);
   }
-  const names = planTableNames(screens);
+  const names = planTableNames(screens, model.contract.entities, model.field_roles);
   const absent = names.filter((name2) => (idsByName.get(name2) ?? []).length === 0);
   const twice = names.filter((name2) => (idsByName.get(name2) ?? []).length > 1);
   if (absent.length > 0) {
@@ -77509,7 +78360,7 @@ async function resolvePlanForCreate(client, from) {
   const live = await client.getWorkspaceSchema(ids);
   const unreadable = ids.filter((id) => !live.some((table) => table.id === id));
   if (unreadable.length > 0) throw new Error(`could not read table(s) ${unreadable.join(", ")} \u2014 check this key's access.`);
-  const { bound, missing } = bindScreens(screens, live, model.field_roles);
+  const { bound, missing } = bindScreens(screens, live, model.field_roles, model.contract.entities);
   if (missing.length > 0) {
     throw new Error(
       `the plan does not fit this workspace:
@@ -77541,7 +78392,7 @@ function withPlanFiles(starter, plan) {
 async function appSetSubdomain(client, args) {
   const meta3 = readAppMeta(process.cwd());
   const result = await client.setAppSubdomain(meta3.app_id, args.subdomain);
-  console.error(`Public address set: https://${result.public_subdomain}.lotics.app`);
+  console.error(`Public address set: ${result.origin}`);
 }
 async function appRename(client, args) {
   const meta3 = readAppMeta(process.cwd());
@@ -79363,33 +80214,37 @@ function signInInstructions(pending, options) {
 ${then}`;
 }
 async function startPendingLogin(email3) {
-  const request = await startCliLogin(email3);
+  const apiUrl = envApiUrl();
+  const request = await startCliLogin(apiUrl, email3);
   const pending = {
     request_id: request.request_id,
     secret: request.secret,
     code: request.code,
     expires_at: request.expires_at,
     email: email3,
-    api_url: API_BASE_URL
+    api_url: apiUrl
   };
   savePendingLogin(pending);
   return pending;
 }
-function saveApproval(state, email3, options) {
+function saveApproval(state, pending, options) {
   requireNonEmpty(state.api_key, "api_key");
   requireNonEmpty(state.organization_id, "organization_id");
   requireNonEmpty(state.workspace_id, "workspace_id");
   upsertProfile(state.organization_id, {
     api_key: state.api_key,
     org_name: state.organization_name,
+    // The host that minted the key, taken from the request rather than re-read:
+    // this is the whole of "which Lotics does this registration belong to".
+    api_url: pending.api_url,
     workspace_id: state.workspace_id
   });
   const existing = loadGlobalConfig() ?? {};
-  saveGlobalConfig({ ...existing, email: email3 });
+  saveGlobalConfig({ ...existing, email: pending.email });
   setActiveOrg(state.organization_id, options?.local === true ? "local" : "global");
   clearPendingLogin();
   return {
-    email: email3,
+    email: pending.email,
     orgId: state.organization_id,
     orgName: state.organization_name,
     workspaceId: state.workspace_id
@@ -79399,14 +80254,15 @@ async function claimPendingLogin() {
   const pending = loadPendingLogin();
   if (!pending) return { status: "none" };
   const expired = `The sign-in request expired. Run again:  lotics auth login ${pending.email}`;
+  const target = envApiUrl();
   if (Date.parse(pending.expires_at) <= Date.now()) {
     clearPendingLogin();
-    return pending.api_url === API_BASE_URL ? { status: "gone", message: expired } : { status: "none" };
+    return pending.api_url === target ? { status: "gone", message: expired } : { status: "none" };
   }
-  if (pending.api_url !== API_BASE_URL) return { status: "none" };
-  const state = await pollCliLogin(pending.request_id, pending.secret);
+  if (pending.api_url !== target) return { status: "none" };
+  const state = await pollCliLogin(pending.api_url, pending.request_id, pending.secret);
   if (state.status === "approved") {
-    return { status: "signed_in", account: saveApproval(state, pending.email) };
+    return { status: "signed_in", account: saveApproval(state, pending) };
   }
   if (state.status === "pending") {
     return {
@@ -79427,14 +80283,14 @@ async function awaitCliLogin(email3, options) {
   for (; ; ) {
     let state;
     try {
-      state = await pollCliLogin(pending.request_id, pending.secret);
+      state = await pollCliLogin(pending.api_url, pending.request_id, pending.secret);
     } catch (error52) {
       if (!(Date.now() < expiresAt)) throw error52;
       await new Promise((resolve2) => setTimeout(resolve2, POLL_INTERVAL_MS));
       continue;
     }
     if (state.status === "approved") {
-      return saveApproval(state, email3, options);
+      return saveApproval(state, pending, options);
     }
     if (state.status === "expired") {
       throw new Error(`That sign-in link expired. Run "lotics auth login ${email3}" again.`);
@@ -108451,8 +109307,8 @@ function prompt(question) {
     });
   });
 }
-async function publicPost(path14, body) {
-  const response = await fetch(`${API_BASE_URL}${path14}`, {
+async function publicPost(apiUrl, path14, body) {
+  const response = await fetch(`${apiUrl}${path14}`, {
     method: "POST",
     headers: { "Content-Type": "application/json" },
     body: JSON.stringify(body)
@@ -108465,7 +109321,8 @@ async function signupAccount(args) {
   if (args.name) body.name = args.name;
   const timezone = args.timezone ?? machineTimezone();
   if (timezone) body.timezone = timezone;
-  const { ok, status, data: data2 } = await publicPost("/v1/cli/signup", body);
+  const apiUrl = envApiUrl();
+  const { ok, status, data: data2 } = await publicPost(apiUrl, "/v1/cli/signup", body);
   if (!ok) {
     if (status === 409) {
       return { kind: "email_taken" };
@@ -108479,7 +109336,7 @@ async function signupAccount(args) {
   const orgId = data2.organization_id;
   const workspaceId = data2.workspace_id;
   const orgName = args.name || args.email.split("@")[0];
-  upsertProfile(orgId, { api_key: apiKey, org_name: orgName, workspace_id: workspaceId });
+  upsertProfile(orgId, { api_key: apiKey, org_name: orgName, api_url: apiUrl, workspace_id: workspaceId });
   const existing = loadGlobalConfig() ?? {};
   saveGlobalConfig({ ...existing, email: args.email });
   setActiveOrg(orgId, args.local ? "local" : "global");
@@ -108621,7 +109478,8 @@ async function handleSetup(providedKey, local) {
     console.error("No API key provided.");
     process.exit(1);
   }
-  const client = new LoticsClient({ apiKey });
+  const apiUrl = envApiUrl();
+  const client = new LoticsClient({ apiKey, apiUrl });
   let info;
   try {
     info = await client.whoami();
@@ -108647,6 +109505,7 @@ Multiple workspaces in ${info.organization_name}. Run "lotics workspace select <
   upsertProfile(info.organization_id, {
     api_key: apiKey,
     org_name: info.organization_name,
+    api_url: apiUrl,
     workspace_id: workspaceId
   });
   const existing = loadGlobalConfig() ?? {};
@@ -108684,9 +109543,9 @@ async function requireClient(flags, appWorkspaceId) {
   }
   const viewAsMemberId = flags.viewAs ?? process.env.LOTICS_VIEW_AS;
   noteScope({ org_id: ctx.orgId ?? void 0, workspace_id: ctx.workspaceId });
-  flushSpool((events) => postEvents(API_BASE_URL, ctx.apiKey, events));
+  flushSpool(ctx.apiUrl, (events) => postEvents(ctx.apiUrl, ctx.apiKey, events));
   return {
-    client: new LoticsClient({ apiKey: ctx.apiKey, workspaceId: ctx.workspaceId, viewAsMemberId }),
+    client: new LoticsClient({ apiKey: ctx.apiKey, apiUrl: ctx.apiUrl, workspaceId: ctx.workspaceId, viewAsMemberId }),
     ctx
   };
 }
@@ -108775,7 +109634,7 @@ function looksLikeModelFile(arg) {
 }
 async function main() {
   setInvocation(commandPath(process.argv.slice(2)), sessionId(), VERSION);
-  installTelemetry(startedAt);
+  installTelemetry(envApiUrl(), startedAt);
   const parsed = parseArgs(process.argv.slice(2));
   const { restArgs, flags } = parsed;
   let { command, subcommand, toolArgs } = parsed;
@@ -108995,7 +109854,7 @@ async function main() {
   if (command === "library") {
     if (subcommand === "list") {
       if (resolveContext(flags) === null) {
-        await libraryListPublic();
+        await libraryListPublic(envApiUrl());
         return;
       }
       const { client: client2, ctx: ctx2 } = await requireClient(flags);
@@ -109026,11 +109885,12 @@ async function main() {
       }
       if (flags.json) {
         setMachineOutput(true);
-        if (resolveContext(flags) === null) {
-          emitJson(await getOfficialStarter(toolArgs));
+        const shelfCtx = resolveContext(flags);
+        if (shelfCtx === null) {
+          emitJson(await getOfficialStarter(envApiUrl(), toolArgs));
           return;
         }
-        const published = await readOfficialStarter(toolArgs);
+        const published = await readOfficialStarter(shelfCtx.apiUrl, toolArgs);
         if (published.ok) {
           emitJson(published.package);
           return;
@@ -109052,7 +109912,7 @@ async function main() {
         return;
       }
       if (resolveContext(flags) === null) {
-        await libraryShowPublic(toolArgs);
+        await libraryShowPublic(envApiUrl(), toolArgs);
         return;
       }
       const { client: client2, ctx: ctx2 } = await requireClient(flags);
@@ -109173,7 +110033,7 @@ async function main() {
     }
     noteScope({ org_id: reportCtx.orgId ?? void 0, workspace_id: reportCtx.workspaceId });
     await reportCommand(
-      new LoticsClient({ apiKey: reportCtx.apiKey, workspaceId: reportCtx.workspaceId }),
+      new LoticsClient({ apiKey: reportCtx.apiKey, apiUrl: reportCtx.apiUrl, workspaceId: reportCtx.workspaceId }),
       {
         report: parsed2.report,
         version: VERSION,
@@ -109205,23 +110065,28 @@ async function main() {
         console.error('Not authenticated. Run "lotics auth signup", "lotics auth api-key <key>", or set LOTICS_API_KEY.');
         process.exit(1);
       }
-      const client2 = new LoticsClient({ apiKey: ctx2.apiKey });
+      const client2 = new LoticsClient({ apiKey: ctx2.apiKey, apiUrl: ctx2.apiUrl });
       const info = await client2.whoami();
       const existing = loadGlobalConfig() ?? {};
       saveGlobalConfig({ ...existing, email: info.email });
       const cached2 = existing.profiles?.[info.organization_id];
       if (cached2 && cached2.org_name !== info.organization_name) {
-        upsertProfile(info.organization_id, { api_key: cached2.api_key, org_name: info.organization_name });
+        upsertProfile(info.organization_id, {
+          api_key: cached2.api_key,
+          org_name: info.organization_name,
+          api_url: cached2.api_url
+        });
         console.error(`Renamed since this key was saved: "${cached2.org_name}" \u2192 "${info.organization_name}" (updated locally)`);
       }
       const viewAs = flags.viewAs ?? process.env.LOTICS_VIEW_AS;
       if (flags.json) {
-        console.log(JSON.stringify({ ...info, workspace_id: ctx2.workspaceId ?? null, source: ctx2.source, view_as: viewAs ?? null }, null, 2));
+        console.log(JSON.stringify({ ...info, workspace_id: ctx2.workspaceId ?? null, api_url: ctx2.apiUrl, source: ctx2.source, view_as: viewAs ?? null }, null, 2));
       } else {
         console.log(`Name:       ${info.name}`);
         console.log(`Email:      ${info.email}`);
         console.log(`Org:        ${info.organization_name} (${info.organization_id})`);
         console.log(`Workspace:  ${ctx2.workspaceId ?? "(none selected)"}`);
+        console.log(`API:        ${ctx2.apiUrl}`);
         console.log(`Source:     ${SOURCE_LABELS[ctx2.source]}`);
         if (viewAs) console.log(`View as:    ${viewAs} (admin preview; requires an admin key)`);
       }
@@ -109302,7 +110167,7 @@ async function main() {
     try {
       const ctx2 = resolveContext(flags, appManifestWorkspaceId(command, subcommand, void 0, flags));
       if (ctx2) {
-        client2 = new LoticsClient({ apiKey: ctx2.apiKey, workspaceId: ctx2.workspaceId });
+        client2 = new LoticsClient({ apiKey: ctx2.apiKey, apiUrl: ctx2.apiUrl, workspaceId: ctx2.workspaceId });
         await resolveWorkspace(client2, ctx2);
       }
     } catch (err2) {
@@ -109323,7 +110188,7 @@ async function main() {
     }
     applyAppManifestWorkspace(ctx2, command, subcommand, projectDir, flags);
     const viewAsMemberId = flags.viewAs ?? process.env.LOTICS_VIEW_AS;
-    const client2 = new LoticsClient({ apiKey: ctx2.apiKey, workspaceId: ctx2.workspaceId, viewAsMemberId });
+    const client2 = new LoticsClient({ apiKey: ctx2.apiKey, apiUrl: ctx2.apiUrl, workspaceId: ctx2.workspaceId, viewAsMemberId });
     await resolveWorkspace(client2, ctx2);
     await appCodegen({ projectDir, client: client2 });
     return;
@@ -109353,7 +110218,11 @@ async function main() {
           console.error("Note: a local pin (.lotics/config.json) overrides the global default in this directory. Use --local to change the pin here.");
         }
       }
-      await validateOrgWorkspacePin(new LoticsClient({ apiKey: profile.api_key }), orgId, profile);
+      await validateOrgWorkspacePin(
+        new LoticsClient({ apiKey: profile.api_key, apiUrl: profile.api_url }),
+        orgId,
+        profile
+      );
       return;
     }
     if (subcommand && subcommand !== "list") {
@@ -109372,6 +110241,7 @@ async function main() {
         orgIds.map((id) => ({
           org_id: id,
           org_name: profiles[id].org_name,
+          api_url: profiles[id].api_url,
           workspace_id: profiles[id].workspace_id ?? null,
           active: id === effectiveActive
         })),
@@ -109381,7 +110251,7 @@ async function main() {
     } else {
       for (const id of orgIds) {
         const marker = id === effectiveActive ? " (active)" : "";
-        console.log(`${id}  ${profiles[id].org_name}${marker}`);
+        console.log(`${id}  ${profiles[id].org_name}  ${profiles[id].api_url}${marker}`);
       }
     }
     return;
@@ -109414,7 +110284,7 @@ async function main() {
     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 query set <alias>              Push lotics.queries.<alias> to apps.queries (no deploy)");
-    console.error("  lotics app subdomain <new-subdomain> Rename the app's public <slug>.lotics.app address");
+    console.error("  lotics app subdomain <new-subdomain> Rename the app's public address (its subdomain)");
     console.error(`  lotics app rename "<new name>"        Rename the app's display name (launcher title)`);
     console.error("  lotics app dev [path]                Run the app locally with HMR + RPC forwarding");
     process.exit(1);
@@ -109634,7 +110504,7 @@ Available workspaces:`);
       const newSubdomain = toolArgs;
       if (!newSubdomain) {
         console.error("Usage: lotics app subdomain <new-subdomain>");
-        console.error("Renames the app's public address \u2014 https://<slug>.lotics.app");
+        console.error("Renames the app's public address \u2014 its subdomain under the apps domain");
         process.exit(1);
       }
       await appSetSubdomain(client, { subdomain: newSubdomain });