@lotics/cli 0.190.0 → 0.191.0

package/dist/src/cli.js

@@ -26822,12 +26822,12 @@ var require_tokens = __commonJS({
       });
     }
     exports2.assignCategoriesMapProp = assignCategoriesMapProp;
-    function singleAssignCategoriesToksMap(path13, nextNode) {
-      utils_1.forEach(path13, function(pathNode) {
+    function singleAssignCategoriesToksMap(path14, nextNode) {
+      utils_1.forEach(path14, function(pathNode) {
         nextNode.categoryMatchesMap[pathNode.tokenTypeIdx] = true;
       });
       utils_1.forEach(nextNode.CATEGORIES, function(nextCategory) {
-        var newPath = path13.concat(nextNode);
+        var newPath = path14.concat(nextNode);
         if (!utils_1.contains(newPath, nextCategory)) {
           singleAssignCategoriesToksMap(newPath, nextCategory);
         }
@@ -28590,10 +28590,10 @@ var require_interpreter = __commonJS({
       /** @class */
       (function(_super) {
         __extends(AbstractNextPossibleTokensWalker2, _super);
-        function AbstractNextPossibleTokensWalker2(topProd, path13) {
+        function AbstractNextPossibleTokensWalker2(topProd, path14) {
           var _this = _super.call(this) || this;
           _this.topProd = topProd;
-          _this.path = path13;
+          _this.path = path14;
           _this.possibleTokTypes = [];
           _this.nextProductionName = "";
           _this.nextProductionOccurrence = 0;
@@ -28647,9 +28647,9 @@ var require_interpreter = __commonJS({
       /** @class */
       (function(_super) {
         __extends(NextAfterTokenWalker2, _super);
-        function NextAfterTokenWalker2(topProd, path13) {
-          var _this = _super.call(this, topProd, path13) || this;
-          _this.path = path13;
+        function NextAfterTokenWalker2(topProd, path14) {
+          var _this = _super.call(this, topProd, path14) || this;
+          _this.path = path14;
           _this.nextTerminalName = "";
           _this.nextTerminalOccurrence = 0;
           _this.nextTerminalName = _this.path.lastTok.name;
@@ -29346,10 +29346,10 @@ var require_lookahead = __commonJS({
       }
       return result;
     }
-    function pathToHashKeys(path13) {
+    function pathToHashKeys(path14) {
       var keys3 = [""];
-      for (var i2 = 0; i2 < path13.length; i2++) {
-        var tokType = path13[i2];
+      for (var i2 = 0; i2 < path14.length; i2++) {
+        var tokType = path14[i2];
         var longerKeys = [];
         for (var j = 0; j < keys3.length; j++) {
           var currShorterKey = keys3[j];
@@ -29661,9 +29661,9 @@ var require_checks = __commonJS({
       return errors2;
     }
     exports2.validateRuleIsOverridden = validateRuleIsOverridden;
-    function validateNoLeftRecursion(topRule, currRule, errMsgProvider, path13) {
-      if (path13 === void 0) {
-        path13 = [];
+    function validateNoLeftRecursion(topRule, currRule, errMsgProvider, path14) {
+      if (path14 === void 0) {
+        path14 = [];
       }
       var errors2 = [];
       var nextNonTerminals = getFirstNoneTerminal(currRule.definition);
@@ -29676,15 +29676,15 @@ var require_checks = __commonJS({
           errors2.push({
             message: errMsgProvider.buildLeftRecursionError({
               topLevelRule: topRule,
-              leftRecursionPath: path13
+              leftRecursionPath: path14
             }),
             type: parser_1.ParserDefinitionErrorType.LEFT_RECURSION,
             ruleName
           });
         }
-        var validNextSteps = utils2.difference(nextNonTerminals, path13.concat([topRule]));
+        var validNextSteps = utils2.difference(nextNonTerminals, path14.concat([topRule]));
         var errorsFromNextSteps = utils2.map(validNextSteps, function(currRefRule) {
-          var newPath = utils2.cloneArr(path13);
+          var newPath = utils2.cloneArr(path14);
           newPath.push(currRefRule);
           return validateNoLeftRecursion(topRule, currRefRule, errMsgProvider, newPath);
         });
@@ -34706,7 +34706,7 @@ var require_BufferList = __commonJS({
         this.head = this.tail = null;
         this.length = 0;
       };
-      BufferList.prototype.join = function join3(s) {
+      BufferList.prototype.join = function join5(s) {
         if (this.length === 0) return "";
         var p = this.head;
         var ret = "" + p.data;
@@ -37293,8 +37293,8 @@ var require_utils4 = __commonJS({
       var result = transform2[inputType][outputType](input);
       return result;
     };
-    exports2.resolve = function(path13) {
-      var parts = path13.split("/");
+    exports2.resolve = function(path14) {
+      var parts = path14.split("/");
       var result = [];
       for (var index = 0; index < parts.length; index++) {
         var part = parts[index];
@@ -43147,18 +43147,18 @@ var require_object = __commonJS({
       var object2 = new ZipObject(name2, zipObjectContent, o);
       this.files[name2] = object2;
     };
-    var parentFolder = function(path13) {
-      if (path13.slice(-1) === "/") {
-        path13 = path13.substring(0, path13.length - 1);
+    var parentFolder = function(path14) {
+      if (path14.slice(-1) === "/") {
+        path14 = path14.substring(0, path14.length - 1);
       }
-      var lastSlash = path13.lastIndexOf("/");
-      return lastSlash > 0 ? path13.substring(0, lastSlash) : "";
+      var lastSlash = path14.lastIndexOf("/");
+      return lastSlash > 0 ? path14.substring(0, lastSlash) : "";
     };
-    var forceTrailingSlash = function(path13) {
-      if (path13.slice(-1) !== "/") {
-        path13 += "/";
+    var forceTrailingSlash = function(path14) {
+      if (path14.slice(-1) !== "/") {
+        path14 += "/";
       }
-      return path13;
+      return path14;
     };
     var folderAdd = function(name2, createFolders) {
       createFolders = typeof createFolders !== "undefined" ? createFolders : defaults2.createFolders;
@@ -44162,7 +44162,7 @@ import dns from "node:dns";
 import net2 from "node:net";
 import fs15 from "node:fs";
 import os4 from "node:os";
-import path12 from "node:path";
+import path13 from "node:path";
 import readline from "node:readline";
 
 // ../shared/src/transport_error.ts
@@ -44531,8 +44531,8 @@ var LoticsClient = class {
     headers["x-request-id"] = newRequestId();
     return headers;
   }
-  async request(method, path13, body) {
-    const url2 = `${this.baseUrl}${path13}`;
+  async request(method, path14, body) {
+    const url2 = `${this.baseUrl}${path14}`;
     const headers = this.buildHeaders();
     const init = { method, headers };
     if (body !== void 0) {
@@ -46001,7 +46001,7 @@ function resultSideEffects(result) {
 }
 
 // src/version.ts
-var VERSION = "0.190.0";
+var VERSION = "0.191.0";
 
 // src/timezone.ts
 function machineTimezone() {
@@ -46201,9 +46201,10 @@ var COMMANDS = [
       "                                       and a worked example. Offline, no account",
       "  lotics scaffold check <file>         Prove a model before anyone sees it \u2014 offline, no",
       "                                       account, no network. Reports EVERY problem in one",
-      "                                       run; exits 1 if there is one, else a one-line",
-      "                                       summary of what it would create. --json prints",
-      "                                       the counts, or the findings that stopped it",
+      "                                       run; exits 1 if there is one, else what it would",
+      "                                       create, every planned screen with the field in each",
+      "                                       slot, and what the first rows would show. --json",
+      "                                       prints the counts and the plan, or the findings",
       "  lotics scaffold apply <file>         Create the model's tables, fields, options, views,",
       "                                       roles and first rows in this workspace, then copy in",
       "                                       every package its apply list names. Additive:",
@@ -46350,7 +46351,7 @@ var COMMANDS = [
       "                                       offer one",
       "  lotics app codegen [path]            Regenerate .lotics/* (types + field/option ids)",
       "                                       from the manifest + workspace schema \u2014 no deploy",
-      "  lotics app check                     Run every deploy pre-flight WITHOUT building or",
+      "  lotics app check [--screens]         Run every deploy pre-flight WITHOUT building or",
       "                                       shipping: the app's own typecheck over regenerated",
       "                                       .lotics types, agent schemas vs the live app, workflow",
       "                                       declarations and BODIES vs what is live, aliases",
@@ -46360,6 +46361,9 @@ var COMMANDS = [
       "                                       the pulled types, and a concrete id or an",
       "                                       id-shaped placeholder in source a starter",
       "                                       would ship.",
+      "                                       --screens also renders the app headless (needs",
+      "                                       Chrome) at 1280 and 375 and measures every screen",
+      "                                       against the review probes (lotics docs cli_reference).",
       "                                       Exits 1 on any of it, so CI can gate on it",
       "  lotics app workflow set <alias>      Push the edited src/workflows/<alias>.ts body",
       "                                       through set_app_workflow (server verifies)",
@@ -46437,7 +46441,9 @@ var COMMANDS = [
       "  lotics file preview <file|fil_id> [-o png]",
       "                                       Render a .docx/.xlsx to a PNG \u2014 a local path OR a",
       "                                       stored file id (downloaded first). Frontend engines;",
-      "                                       needs a Chrome/Chromium on the machine"
+      "                                       needs a Chrome/Chromium on the machine. A .html",
+      "                                       renders as the page it is, sized to its content \u2014",
+      "                                       the way a demo's paper props are made"
     ]
   }
 ];
@@ -46628,9 +46634,9 @@ async function reportCommand(client, options) {
 // src/app_commands.ts
 import fs8 from "node:fs";
 import path9 from "node:path";
-import { spawn as spawn2 } from "node:child_process";
+import { spawn as spawn3 } from "node:child_process";
 import { createHash as createHash3 } from "node:crypto";
-import { tmpdir } from "node:os";
+import { tmpdir as tmpdir2 } from "node:os";
 
 // src/starter_template.ts
 var STARTER_REACT_NATIVE_VERSION = "0.85.3";
@@ -47567,9 +47573,22 @@ async function dispatchRpc(client, body, opts) {
   }
 }
 
+// ../shared/src/open_app_target.ts
+function openAppTarget(payload) {
+  const appId = payload?.app_id;
+  const route = payload?.route;
+  if (typeof appId !== "string" || !/^app_[A-Za-z0-9]+$/.test(appId)) {
+    throw new Error("openApp requires an app id (app_\u2026)");
+  }
+  if (typeof route !== "string" || !/^\/(?:[^/\\][^\\]*)?$/.test(route)) {
+    throw new Error("openApp requires an in-app route starting with /");
+  }
+  return { app_id: appId, href: `/apps/${appId}?_loc=${encodeURIComponent(route)}` };
+}
+
 // src/dev/wrapper_page.ts
 function buildWrapperPage(args) {
-  const { app_name, app_id, workspace_id, vite_url, api_url } = args;
+  const { app_name, app_id, workspace_id, vite_url, api_url, web_app_url } = args;
   return `<!doctype html>
 <html lang="en">
 <head>
@@ -47733,6 +47752,19 @@ function buildWrapperPage(args) {
         return undefined;
       }
 
+      // openApp \u2014 the cross-app hop. The product host routes to the sibling in
+      // place; this wrapper serves ONE app and has no shell to route inside, so
+      // the hop opens the sibling on the web app in a new tab. The check is the
+      // host's own function, inlined by source.
+      var openAppTarget = (${openAppTarget.toString()});
+      function handleOpenApp(payload) {
+        var target = openAppTarget(payload);
+        // Same refusal as the host: a hop to itself is in-app navigation.
+        if (target.app_id === ${JSON.stringify(app_id)}) throw new Error("openApp is for a sibling app; navigate inside this app with its own router");
+        window.open(${JSON.stringify(web_app_url)} + target.href, "_blank", "noopener,noreferrer");
+        return undefined;
+      }
+
       // urlState.get/set \u2014 useUrlState keeps app view-state (filters, search) in
       // THIS wrapper page's address bar so it survives refresh and is shareable,
       // mirroring the production host. Handled locally (the URL is the store; no
@@ -47832,6 +47864,8 @@ function buildWrapperPage(args) {
             ? await handleUpload(msg.payload)
             : msg.op === "openExternal"
             ? handleOpenExternal(msg.payload)
+            : msg.op === "openApp"
+            ? handleOpenApp(msg.payload)
             : msg.op === "urlState.get"
             ? readUrlParams()
             : msg.op === "urlState.set"
@@ -47982,7 +48016,8 @@ async function startDevServer(args) {
     app_id: args.app_id,
     workspace_id: args.workspace_id,
     vite_url: viteUrl,
-    api_url: args.api_url
+    api_url: args.api_url,
+    web_app_url: WEB_APP_URL
   });
   const viteEntry = path7.join(args.projectDir, "node_modules", "vite", "bin", "vite.js");
   if (!existsSync(viteEntry)) {
@@ -48292,7 +48327,8 @@ async function startDevServer(args) {
     stop: async () => {
       await stopAll();
       await stoppingPromise;
-    }
+    },
+    pendingRpc: () => inFlight
   };
 }
 async function pickPort(preferred, ...avoid) {
@@ -48346,6 +48382,272 @@ function openBrowser(url2) {
   child.unref();
 }
 
+// src/app_screens_check.ts
+import { existsSync as existsSync3, readFileSync as readFileSync2 } from "node:fs";
+import { dirname, join as join2 } from "node:path";
+import { fileURLToPath as fileURLToPath2 } from "node:url";
+import { setTimeout as sleep3 } from "node:timers/promises";
+
+// src/chrome.ts
+import { spawn as spawn2 } from "node:child_process";
+import { existsSync as existsSync2, mkdtempSync, readFileSync, readdirSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { setTimeout as sleep2 } from "node:timers/promises";
+function findChrome() {
+  const env = process.env.LOTICS_CHROME || process.env.CHROME_PATH;
+  if (env && existsSync2(env)) return env;
+  const home = process.env.HOME || "";
+  const pwDir = process.platform === "darwin" ? `${home}/Library/Caches/ms-playwright` : `${home}/.cache/ms-playwright`;
+  if (existsSync2(pwDir)) {
+    const rel = process.platform === "darwin" ? ["chrome-mac/Chromium.app/Contents/MacOS/Chromium"] : [
+      "chrome-linux64/chrome",
+      "chrome-linux/chrome",
+      "chrome-headless-shell-linux64/chrome-headless-shell",
+      "chrome-linux/headless_shell"
+    ];
+    const revs = readdirSync(pwDir).filter((n) => n.startsWith("chromium-") || n.startsWith("chromium_headless_shell-")).sort().reverse();
+    for (const rev2 of revs) {
+      for (const r of rel) {
+        const bin = join(pwDir, rev2, r);
+        if (existsSync2(bin)) return bin;
+      }
+    }
+  }
+  const systemPaths = [
+    "/usr/bin/google-chrome",
+    "/usr/bin/google-chrome-stable",
+    "/usr/bin/chromium",
+    "/usr/bin/chromium-browser",
+    "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+    "/Applications/Chromium.app/Contents/MacOS/Chromium"
+  ];
+  return systemPaths.find((p) => existsSync2(p)) ?? null;
+}
+var NO_CHROME_MESSAGE = "No Chrome/Chromium found. Set CHROME_PATH to a Chrome binary, or install one:\n  npx playwright install chromium   (then it's auto-detected)\n  or install Google Chrome / Chromium via your package manager.";
+async function cdpConnect(wsUrl) {
+  const ws = new WebSocket(wsUrl);
+  await new Promise((res, rej) => {
+    ws.onopen = () => res();
+    ws.onerror = () => rej(new Error("CDP websocket failed to open"));
+  });
+  let id = 0;
+  const pending = /* @__PURE__ */ new Map();
+  ws.onclose = () => {
+    for (const done of pending.values()) done(Promise.reject(new Error("CDP connection closed (Chrome exited?)")));
+    pending.clear();
+  };
+  ws.onmessage = (e) => {
+    const m = JSON.parse(String(e.data));
+    if (m.id == null) return;
+    const done = pending.get(m.id);
+    if (done === void 0) return;
+    pending.delete(m.id);
+    done(m.error ? Promise.reject(new Error(m.error.message)) : m.result);
+  };
+  const send = (method, params = {}) => new Promise((res) => {
+    const i2 = ++id;
+    pending.set(i2, (r) => res(r));
+    ws.send(JSON.stringify({ id: i2, method, params }));
+  });
+  return { send, close: () => ws.close() };
+}
+async function launchChrome(options = {}) {
+  const chrome = findChrome();
+  if (chrome === null) throw new Error(NO_CHROME_MESSAGE);
+  if (typeof WebSocket === "undefined") {
+    throw new Error("This command needs Node 22+ (it drives Chrome over CDP via the built-in WebSocket). Upgrade Node and retry.");
+  }
+  const udd = mkdtempSync(join(tmpdir(), "lotics-chrome-"));
+  const child = spawn2(chrome, [
+    "--headless=new",
+    "--disable-gpu",
+    "--no-sandbox",
+    "--hide-scrollbars",
+    // Large renders exhaust the (often tiny) /dev/shm in containers/WSL2 and
+    // crash the tab; back shared memory with /tmp instead.
+    "--disable-dev-shm-usage",
+    `--force-device-scale-factor=${options.deviceScaleFactor ?? 2}`,
+    ...options.sameProcessFrames ? ["--disable-features=IsolateOrigins,site-per-process"] : [],
+    "--remote-debugging-port=0",
+    `--user-data-dir=${udd}`,
+    "about:blank"
+  ], { stdio: "ignore" });
+  const close = () => {
+    child.kill();
+    rmSync(udd, { recursive: true, force: true });
+  };
+  try {
+    let cdpPort = 0;
+    const portFile = join(udd, "DevToolsActivePort");
+    for (let i2 = 0; i2 < 100 && !cdpPort; i2++) {
+      if (existsSync2(portFile)) {
+        const p = parseInt(readFileSync(portFile, "utf8").split("\n")[0], 10);
+        if (p) cdpPort = p;
+      }
+      if (!cdpPort) await sleep2(100);
+    }
+    if (!cdpPort) throw new Error("Chrome did not expose a debugging port (launch failed?).");
+    let target;
+    for (let i2 = 0; i2 < 60 && !target?.webSocketDebuggerUrl; i2++) {
+      try {
+        const list2 = await (await fetch(`http://127.0.0.1:${cdpPort}/json/list`)).json();
+        target = list2.find((t) => t.type === "page");
+      } catch {
+      }
+      if (!target?.webSocketDebuggerUrl) await sleep2(100);
+    }
+    if (!target?.webSocketDebuggerUrl) throw new Error("No Chrome page target available.");
+    const cdp = await cdpConnect(target.webSocketDebuggerUrl);
+    await cdp.send("Page.enable");
+    await cdp.send("Runtime.enable");
+    return { cdp, chrome, close: () => {
+      cdp.close();
+      close();
+    } };
+  } catch (error52) {
+    close();
+    throw error52;
+  }
+}
+
+// src/app_screens_check.ts
+var HERE = dirname(fileURLToPath2(import.meta.url));
+var SCREEN_WIDTHS = [1280, 375];
+async function findAppFrame(cdp, viteUrl) {
+  for (let attempt = 0; attempt < 100; attempt++) {
+    const tree = await cdp.send("Page.getFrameTree");
+    const child = (tree.frameTree.childFrames ?? []).find((frame) => frame.frame.url.startsWith(viteUrl));
+    if (child !== void 0) return child.frame.id;
+    await sleep3(100);
+  }
+  throw new Error(`The app's frame never appeared under the dev wrapper (${viteUrl}).`);
+}
+async function evaluate(cdp, contextId, expression) {
+  const result = await cdp.send(
+    "Runtime.evaluate",
+    { expression, contextId, returnByValue: true, awaitPromise: true }
+  );
+  if (result.exceptionDetails !== void 0) {
+    throw new Error(
+      `probe failed in the page: ${result.exceptionDetails.exception?.description ?? result.exceptionDetails.text}`
+    );
+  }
+  return result.result.value;
+}
+var SETTLE_BUDGET_MS = 15e3;
+var SETTLE_TICK_MS = 250;
+async function settle(cdp, contextId, pendingRpc) {
+  let previous = -1;
+  let count2 = 0;
+  for (let elapsed = 0; elapsed < SETTLE_BUDGET_MS; elapsed += SETTLE_TICK_MS) {
+    count2 = await evaluate(cdp, contextId, "__loticsProbe.textLeafCount()");
+    if (pendingRpc() === 0 && count2 > 0 && count2 === previous) return { count: count2, settled: true };
+    previous = pendingRpc() === 0 ? count2 : -1;
+    await sleep3(SETTLE_TICK_MS);
+  }
+  return { count: count2, settled: false };
+}
+function emptyCensus(screen, width) {
+  return { screen, width, leaves: 0, money: 0, bare: 0, encoded: 0, strips: 0 };
+}
+async function checkAppScreens(client, args) {
+  const bundlePath = join2(HERE, "..", "probe_page.js");
+  if (!existsSync3(bundlePath)) {
+    throw new Error(`Probe bundle missing at ${bundlePath} \u2014 reinstall @lotics/cli (build step failed).`);
+  }
+  const bundle = readFileSync2(bundlePath, "utf8");
+  const dev = await startDevServer({
+    projectDir: args.projectDir,
+    app_id: args.app_id,
+    app_name: args.app_name,
+    workspace_id: args.workspace_id,
+    api_url: client.baseUrl,
+    client,
+    commentsEnabled: args.commentsEnabled
+  });
+  await dev.ready;
+  const wrapperUrl = `http://localhost:${dev.port}/`;
+  const viteUrl = `http://localhost:${dev.vitePort}/`;
+  const findings = [];
+  const census = [];
+  let session;
+  try {
+    session = await launchChrome({ deviceScaleFactor: 1, sameProcessFrames: true });
+    for (const width of SCREEN_WIDTHS) {
+      await session.cdp.send("Emulation.setDeviceMetricsOverride", {
+        width,
+        height: 900,
+        deviceScaleFactor: 1,
+        mobile: width < 600
+      });
+      await session.cdp.send("Page.navigate", { url: wrapperUrl });
+      const frameId = await findAppFrame(session.cdp, viteUrl);
+      const world = await session.cdp.send("Page.createIsolatedWorld", {
+        frameId,
+        worldName: "lotics-probe"
+      });
+      const contextId = world.executionContextId;
+      await evaluate(session.cdp, contextId, bundle);
+      await settle(session.cdp, contextId, dev.pendingRpc);
+      const tabs = await evaluate(session.cdp, contextId, "__loticsProbe.tabs()");
+      const screens = tabs.length > 0 ? tabs : ["root"];
+      for (let index = 0; index < screens.length; index++) {
+        const screen = screens[index];
+        if (tabs.length > 0) {
+          await evaluate(session.cdp, contextId, `__loticsProbe.pressTab(${index})`);
+        }
+        const rendered = await settle(session.cdp, contextId, dev.pendingRpc);
+        if (rendered.count === 0) {
+          findings.push({ screen, width, probe: "render", total: 0, count: 1, detail: ["no text rendered \u2014 the screen did not load, so nothing below it was measured"] });
+          census.push(emptyCensus(screen, width));
+          continue;
+        }
+        if (!rendered.settled) {
+          findings.push({
+            screen,
+            width,
+            probe: "settle",
+            total: rendered.count,
+            count: 1,
+            detail: [`still changing after ${SETTLE_BUDGET_MS / 1e3}s \u2014 measured as it was; a request still in flight, or a render that never stops`]
+          });
+        }
+        const results = await evaluate(
+          session.cdp,
+          contextId,
+          `__loticsProbe.run({ truncation: ${width < 600} })`
+        );
+        for (const result of results.findings) findings.push({ screen, width, ...result });
+        census.push({ screen, width, ...results.census });
+      }
+    }
+  } finally {
+    session?.close();
+    await dev.stop();
+  }
+  return { findings, census };
+}
+function formatScreenFindings(report) {
+  const lines = ["Screens measured:"];
+  for (const row of report.census) {
+    lines.push(
+      `  ${row.screen} @${row.width} \xB7 ${row.leaves} text runs \xB7 ${row.money} money strings \xB7 ${row.bare} bare values / ${row.encoded} encoded \xB7 ${row.strips} tab strip${row.strips === 1 ? "" : "s"}`
+    );
+  }
+  if (report.findings.length === 0) {
+    lines.push(`Every screen measured clean at ${SCREEN_WIDTHS.join(" and ")}.`);
+    return lines.join("\n");
+  }
+  lines.push(`Screens \u2014 ${report.findings.length} finding${report.findings.length === 1 ? "" : "s"}:`);
+  for (const finding of report.findings) {
+    lines.push(`  ${finding.screen} @${finding.width} \xB7 ${finding.probe} (${finding.count} of ${finding.total})`);
+    for (const detail of finding.detail) lines.push(`      ${detail}`);
+  }
+  lines.push("  The probes are @lotics/ui docs/reviewing.md, by name \u2014 each names its measurement and its fix.");
+  return lines.join("\n");
+}
+
 // src/output.ts
 var machineMode = false;
 var collectedWarnings = [];
@@ -49142,10 +49444,10 @@ function mergeDefs(...defs) {
 function cloneDef(schema) {
   return mergeDefs(schema._zod.def);
 }
-function getElementAtPath(obj, path13) {
-  if (!path13)
+function getElementAtPath(obj, path14) {
+  if (!path14)
     return obj;
-  return path13.reduce((acc, key) => acc?.[key], obj);
+  return path14.reduce((acc, key) => acc?.[key], obj);
 }
 function promiseAllObject(promisesObj) {
   const keys3 = Object.keys(promisesObj);
@@ -49554,11 +49856,11 @@ function explicitlyAborted(x2, startIndex = 0) {
   }
   return false;
 }
-function prefixIssues(path13, issues) {
+function prefixIssues(path14, issues) {
   return issues.map((iss) => {
     var _a4;
     (_a4 = iss).path ?? (_a4.path = []);
-    iss.path.unshift(path13);
+    iss.path.unshift(path14);
     return iss;
   });
 }
@@ -49705,16 +50007,16 @@ function flattenError(error52, mapper = (issue2) => issue2.message) {
 }
 function formatError(error52, mapper = (issue2) => issue2.message) {
   const fieldErrors = { _errors: [] };
-  const processError = (error53, path13 = []) => {
+  const processError = (error53, path14 = []) => {
     for (const issue2 of error53.issues) {
       if (issue2.code === "invalid_union" && issue2.errors.length) {
-        issue2.errors.map((issues) => processError({ issues }, [...path13, ...issue2.path]));
+        issue2.errors.map((issues) => processError({ issues }, [...path14, ...issue2.path]));
       } else if (issue2.code === "invalid_key") {
-        processError({ issues: issue2.issues }, [...path13, ...issue2.path]);
+        processError({ issues: issue2.issues }, [...path14, ...issue2.path]);
       } else if (issue2.code === "invalid_element") {
-        processError({ issues: issue2.issues }, [...path13, ...issue2.path]);
+        processError({ issues: issue2.issues }, [...path14, ...issue2.path]);
       } else {
-        const fullpath = [...path13, ...issue2.path];
+        const fullpath = [...path14, ...issue2.path];
         if (fullpath.length === 0) {
           fieldErrors._errors.push(mapper(issue2));
         } else {
@@ -49741,17 +50043,17 @@ function formatError(error52, mapper = (issue2) => issue2.message) {
 }
 function treeifyError(error52, mapper = (issue2) => issue2.message) {
   const result = { errors: [] };
-  const processError = (error53, path13 = []) => {
+  const processError = (error53, path14 = []) => {
     var _a4, _b2;
     for (const issue2 of error53.issues) {
       if (issue2.code === "invalid_union" && issue2.errors.length) {
-        issue2.errors.map((issues) => processError({ issues }, [...path13, ...issue2.path]));
+        issue2.errors.map((issues) => processError({ issues }, [...path14, ...issue2.path]));
       } else if (issue2.code === "invalid_key") {
-        processError({ issues: issue2.issues }, [...path13, ...issue2.path]);
+        processError({ issues: issue2.issues }, [...path14, ...issue2.path]);
       } else if (issue2.code === "invalid_element") {
-        processError({ issues: issue2.issues }, [...path13, ...issue2.path]);
+        processError({ issues: issue2.issues }, [...path14, ...issue2.path]);
       } else {
-        const fullpath = [...path13, ...issue2.path];
+        const fullpath = [...path14, ...issue2.path];
         if (fullpath.length === 0) {
           result.errors.push(mapper(issue2));
           continue;
@@ -49783,8 +50085,8 @@ function treeifyError(error52, mapper = (issue2) => issue2.message) {
 }
 function toDotPath(_path) {
   const segs = [];
-  const path13 = _path.map((seg) => typeof seg === "object" ? seg.key : seg);
-  for (const seg of path13) {
+  const path14 = _path.map((seg) => typeof seg === "object" ? seg.key : seg);
+  for (const seg of path14) {
     if (typeof seg === "number")
       segs.push(`[${seg}]`);
     else if (typeof seg === "symbol")
@@ -62476,13 +62778,13 @@ function resolveRef(ref2, ctx) {
   if (!ref2.startsWith("#")) {
     throw new Error("External $ref is not supported, only local refs (#/...) are allowed");
   }
-  const path13 = ref2.slice(1).split("/").filter(Boolean);
-  if (path13.length === 0) {
+  const path14 = ref2.slice(1).split("/").filter(Boolean);
+  if (path14.length === 0) {
     return ctx.rootSchema;
   }
   const defsKey = ctx.version === "draft-2020-12" ? "$defs" : "definitions";
-  if (path13[0] === defsKey) {
-    const key = path13[1];
+  if (path14[0] === defsKey) {
+    const key = path14[1];
     if (!key || !ctx.defs[key]) {
       throw new Error(`Reference not found: ${ref2}`);
     }
@@ -65180,16 +65482,16 @@ function conditionValueIssue(type, operator, value2, fieldKey) {
       return null;
   }
 }
-function conditionIssues(node, path13, fieldMap) {
+function conditionIssues(node, path14, fieldMap) {
   if (!node || typeof node !== "object") {
-    return [`${path13}: expected condition object, got ${typeof node}`];
+    return [`${path14}: expected condition object, got ${typeof node}`];
   }
   const obj = node;
   if (obj.type === "locked") {
     const validOps2 = VALID_OPERATORS.locked;
     if (typeof obj.operator !== "string" || !validOps2.includes(obj.operator)) {
       return [
-        `${path13}: invalid operator '${String(obj.operator)}' for locked filter. Valid: ${validOps2.join(", ")}`
+        `${path14}: invalid operator '${String(obj.operator)}' for locked filter. Valid: ${validOps2.join(", ")}`
       ];
     }
     return [];
@@ -65198,12 +65500,12 @@ function conditionIssues(node, path13, fieldMap) {
     const validOps2 = VALID_OPERATORS.current_member;
     if (typeof obj.operator !== "string" || !validOps2.includes(obj.operator)) {
       return [
-        `${path13}: invalid operator '${String(obj.operator)}' for current_member filter. Valid: ${validOps2.join(", ")}`
+        `${path14}: invalid operator '${String(obj.operator)}' for current_member filter. Valid: ${validOps2.join(", ")}`
       ];
     }
     if (!Array.isArray(obj.value) || obj.value.length === 0 || !obj.value.every((v) => typeof v === "string" && v.length > 0)) {
       return [
-        `${path13}: current_member '${obj.operator}' expects a non-empty string[] of group IDs.`
+        `${path14}: current_member '${obj.operator}' expects a non-empty string[] of group IDs.`
       ];
     }
     return [];
@@ -65212,45 +65514,45 @@ function conditionIssues(node, path13, fieldMap) {
     const validOps2 = VALID_OPERATORS.record_id;
     if (typeof obj.operator !== "string" || !validOps2.includes(obj.operator)) {
       return [
-        `${path13}: invalid operator '${String(obj.operator)}' for record_id filter. Valid: ${validOps2.join(", ")}`
+        `${path14}: invalid operator '${String(obj.operator)}' for record_id filter. Valid: ${validOps2.join(", ")}`
       ];
     }
     if (!Array.isArray(obj.value) || obj.value.length === 0 || !obj.value.every((v) => typeof v === "string" && v.length > 0)) {
-      return [`${path13}: record_id '${obj.operator}' expects a non-empty string[] of record ids.`];
+      return [`${path14}: record_id '${obj.operator}' expects a non-empty string[] of record ids.`];
     }
     return [];
   }
   if (typeof obj.field_key !== "string" || !obj.field_key) {
-    return [`${path13}: field_key must be a non-empty string`];
+    return [`${path14}: field_key must be a non-empty string`];
   }
   let filterType;
   if (fieldMap) {
     filterType = fieldMap.get(obj.field_key);
     if (filterType === void 0) {
       const available = Array.from(fieldMap.keys()).join(", ");
-      return [`${path13}: unknown field_key '${obj.field_key}'. Available: ${available}`];
+      return [`${path14}: unknown field_key '${obj.field_key}'. Available: ${available}`];
     }
   } else if (typeof obj.type === "string") {
     filterType = obj.type;
   }
   if (filterType === "button") {
-    return [`${path13}: a button field holds no data and cannot be filtered.`];
+    return [`${path14}: a button field holds no data and cannot be filtered.`];
   }
   if (typeof filterType !== "string" || !VALID_FILTER_TYPES.includes(filterType)) {
     const named = fieldMap && filterType !== obj.type ? `'${String(filterType)}' (resolved from field '${obj.field_key}')` : `'${String(obj.type)}'`;
-    return [`${path13}: invalid filter type ${named}. Valid: ${VALID_FILTER_TYPES.join(", ")}`];
+    return [`${path14}: invalid filter type ${named}. Valid: ${VALID_FILTER_TYPES.join(", ")}`];
   }
   const validOps = VALID_OPERATORS[filterType];
   if (typeof obj.operator !== "string" || !validOps.includes(obj.operator)) {
     return [
-      `${path13}: invalid operator '${String(obj.operator)}' for ${filterType} filter. Valid: ${validOps.join(", ")}`
+      `${path14}: invalid operator '${String(obj.operator)}' for ${filterType} filter. Valid: ${validOps.join(", ")}`
     ];
   }
   const valueIssue = conditionValueIssue(filterType, obj.operator, obj.value, obj.field_key);
   return valueIssue ? [valueIssue] : [];
 }
-function validateFilterCondition(condition, path13 = "filter") {
-  return conditionIssues(condition, path13, void 0);
+function validateFilterCondition(condition, path14 = "filter") {
+  return conditionIssues(condition, path14, void 0);
 }
 function inheritedFilterType(type, format2, fallback) {
   switch (type) {
@@ -67910,7 +68212,7 @@ __export(expression_string_exports, {
   contains: () => contains2,
   endsWith: () => endsWith,
   formatNumber: () => formatNumber,
-  join: () => join,
+  join: () => join3,
   length: () => length,
   lower: () => lower,
   numberToWords: () => numberToWords,
@@ -67924,7 +68226,7 @@ __export(expression_string_exports, {
   trim: () => trim,
   upper: () => upper
 });
-function join(arr, separator) {
+function join3(arr, separator) {
   if (arr == null) return "";
   if (!Array.isArray(arr)) {
     throw new Error("join: expected array, got " + typeof arr);
@@ -68377,9 +68679,9 @@ __export(expression_object_exports, {
   pick: () => pick3,
   values: () => values2
 });
-function getNestedValue(obj, path13) {
+function getNestedValue(obj, path14) {
   if (obj == null) return void 0;
-  const parts = path13.split(".");
+  const parts = path14.split(".");
   let value2 = obj;
   for (const part of parts) {
     if (value2 == null) return void 0;
@@ -68418,11 +68720,11 @@ function entries(obj) {
   }
   return Object.entries(obj);
 }
-function get(obj, path13, defaultValue) {
-  if (typeof path13 !== "string") {
+function get(obj, path14, defaultValue) {
+  if (typeof path14 !== "string") {
     throw new Error("get: path must be a string");
   }
-  const value2 = getNestedValue(obj, path13);
+  const value2 = getNestedValue(obj, path14);
   return value2 !== void 0 ? value2 : defaultValue;
 }
 function pick3(obj, fields) {
@@ -72448,24 +72750,24 @@ function isBelowGeneratedWidth(token) {
 }
 var SCAN_EXTENSIONS = [".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".html", ".css", ".json"];
 var SCAN_FILE_MAX_BYTES = 1024 * 1024;
-function normalizeScanPath(path13) {
-  return path13.replace(/\\/g, "/").replace(/^\.\//, "").replace(/^\/+/, "");
+function normalizeScanPath(path14) {
+  return path14.replace(/\\/g, "/").replace(/^\.\//, "").replace(/^\/+/, "");
 }
-function hasScannableExtension(path13) {
-  return SCAN_EXTENSIONS.some((ext) => path13.endsWith(ext));
+function hasScannableExtension(path14) {
+  return SCAN_EXTENSIONS.some((ext) => path14.endsWith(ext));
 }
-function isConcreteIdScanPath(path13) {
-  const name2 = normalizeScanPath(path13);
+function isConcreteIdScanPath(path14) {
+  const name2 = normalizeScanPath(path14);
   if (name2.endsWith(".md")) return true;
   if (!name2.startsWith("src/")) return false;
   if (name2.startsWith("src/workflows/")) return false;
   return hasScannableExtension(name2);
 }
-function isTestFile(path13) {
-  return /\.(?:test|spec)\.[cm]?[jt]sx?$/.test(path13);
+function isTestFile(path14) {
+  return /\.(?:test|spec)\.[cm]?[jt]sx?$/.test(path14);
 }
-function isIdPlaceholderScanPath(path13) {
-  const name2 = normalizeScanPath(path13);
+function isIdPlaceholderScanPath(path14) {
+  const name2 = normalizeScanPath(path14);
   if (isTestFile(name2)) return false;
   if (name2.endsWith(".md")) return true;
   if (name2 === "package.json") return true;
@@ -72482,24 +72784,24 @@ function firstLines(text, pattern, keep, into) {
   });
   return into;
 }
-function toFindings(path13, rule, lines) {
-  return [...lines].map(([id, line]) => ({ path: path13, line, id, rule }));
+function toFindings(path14, rule, lines) {
+  return [...lines].map(([id, line]) => ({ path: path14, line, id, rule }));
 }
-function scanFileForConcreteIds(path13, text) {
-  if (!isConcreteIdScanPath(path13)) return [];
+function scanFileForConcreteIds(path14, text) {
+  if (!isConcreteIdScanPath(path14)) return [];
   const lines = firstLines(text, CONCRETE_ID_SCAN, () => true, /* @__PURE__ */ new Map());
   firstLines(text, WORKSPACE_ID_SCAN, isGeneratedIdBody, lines);
-  return toFindings(path13, "concrete", lines);
+  return toFindings(path14, "concrete", lines);
 }
-function scanFileForIdPlaceholders(path13, text) {
-  if (!isIdPlaceholderScanPath(path13)) return [];
+function scanFileForIdPlaceholders(path14, text) {
+  if (!isIdPlaceholderScanPath(path14)) return [];
   const lines = firstLines(text, ID_PLACEHOLDER_SCAN, isBelowGeneratedWidth, /* @__PURE__ */ new Map());
-  return toFindings(path13, "placeholder", lines);
+  return toFindings(path14, "placeholder", lines);
 }
-function scanFileForIds(path13, text) {
-  const concrete = scanFileForConcreteIds(path13, text);
+function scanFileForIds(path14, text) {
+  const concrete = scanFileForConcreteIds(path14, text);
   const seen = new Set(concrete.map((finding) => finding.id));
-  return [...concrete, ...scanFileForIdPlaceholders(path13, text).filter((f) => !seen.has(f.id))].sort(
+  return [...concrete, ...scanFileForIdPlaceholders(path14, text).filter((f) => !seen.has(f.id))].sort(
     (a, b) => a.line - b.line || (a.id < b.id ? -1 : 1)
   );
 }
@@ -72988,7 +73290,7 @@ async function fetchWorkflowDts(client, app_id, alias, declaration) {
 }
 function runTar(args, cwd) {
   return new Promise((resolve2, reject2) => {
-    const proc = spawn2("tar", args, { cwd, stdio: ["ignore", "ignore", "pipe"] });
+    const proc = spawn3("tar", args, { cwd, stdio: ["ignore", "ignore", "pipe"] });
     let stderr = "";
     proc.stderr.on("data", (chunk) => {
       stderr += chunk.toString();
@@ -73002,7 +73304,7 @@ function runTar(args, cwd) {
 }
 function npmIsInstalled() {
   return new Promise((resolve2) => {
-    const probe = spawn2("npm", ["--version"], {
+    const probe = spawn3("npm", ["--version"], {
       shell: process.platform === "win32",
       stdio: "ignore",
       env: ipv4ChildEnv(process.env)
@@ -73014,7 +73316,7 @@ function npmIsInstalled() {
 function runNpm(args, cwd) {
   const quiet = isMachineOutput();
   return new Promise((resolve2, reject2) => {
-    const proc = spawn2("npm", args, {
+    const proc = spawn3("npm", args, {
       cwd,
       // On Windows `npm` is `npm.cmd`, a batch file Node will not execute
       // without a shell — bare `spawn("npm")` dies at ENOENT, which took every
@@ -73819,12 +74121,12 @@ async function appPull(client, args) {
   const targetPath = path9.resolve(args.targetPath ?? defaultPullTarget(app.id, app.name));
   fs8.mkdirSync(targetPath, { recursive: true });
   const prior = readPriorStamp(targetPath);
-  const tmpFile = path9.join(tmpdir(), `lotics-app-${app.id}-${Date.now()}.tar.gz`);
+  const tmpFile = path9.join(tmpdir2(), `lotics-app-${app.id}-${Date.now()}.tar.gz`);
   console.error(`Downloading source archive...`);
   await downloadToFile(sourceUrl, tmpFile);
   const keptLocal = [];
   const restoredFromArchive = [];
-  const stagingDir = fs8.mkdtempSync(path9.join(tmpdir(), `lotics-pull-${app.id}-`));
+  const stagingDir = fs8.mkdtempSync(path9.join(tmpdir2(), `lotics-pull-${app.id}-`));
   try {
     await runTar(["-xzf", tmpFile, "-C", stagingDir], stagingDir);
     console.error(`Extracting to ${targetPath}...`);
@@ -73963,8 +74265,8 @@ async function appDeploy(client, args) {
       `Build did not produce a dist/ directory in ${projectDir}. Check that 'npm run build' is configured correctly (Vite/etc. defaults to dist/).`
     );
   }
-  const tmpSource = path9.join(tmpdir(), `lotics-source-${Date.now()}.tar.gz`);
-  const tmpDist = path9.join(tmpdir(), `lotics-dist-${Date.now()}.tar.gz`);
+  const tmpSource = path9.join(tmpdir2(), `lotics-source-${Date.now()}.tar.gz`);
+  const tmpDist = path9.join(tmpdir2(), `lotics-dist-${Date.now()}.tar.gz`);
   try {
     note("Packaging source...");
     await runTar(
@@ -74154,11 +74456,27 @@ async function appCheck(client, args = {}) {
     console.error(err2 instanceof Error ? err2.message : String(err2));
     typesFailing = true;
   }
-  if (!nothingPending(pending) || unportable.length > 0 || bodiesFailing > 0 || typesFailing) {
+  let screenFindings = 0;
+  if (args.screens === true && !typesFailing) {
+    const report = await checkAppScreens(client, {
+      projectDir,
+      app_id: meta3.app_id,
+      app_name: app.name,
+      workspace_id: meta3.workspace_id,
+      commentsEnabled: meta3.capabilities?.comments
+    });
+    screenFindings = report.findings.length;
+    noteScope({
+      probe_findings: screenFindings,
+      probes: [...new Set(report.findings.map((finding) => finding.probe))]
+    });
+    console.error(formatScreenFindings(report));
+  }
+  if (!nothingPending(pending) || unportable.length > 0 || bodiesFailing > 0 || typesFailing || screenFindings > 0) {
     process.exit(1);
   }
   console.error(
-    "Checked the app's types, bindings, capabilities, agent schemas, workflow bodies and id portability \u2014 nothing blocking."
+    "Checked the app's types, bindings, capabilities, agent schemas, workflow bodies and id portability" + (args.screens === true ? ", and every screen at 1280 and 375" : "") + " \u2014 nothing blocking."
   );
 }
 async function countFailingWorkflowBodies(client, projectDir, meta3) {
@@ -74440,13 +74758,13 @@ function derivedDeployMessage(pending) {
   ];
   return parts.length === 0 ? "Deployed app code" : `Deployed app code; pushed ${parts.join(", ")}`;
 }
-function copyTree(from, to, opts, relative = "") {
+function copyTree(from, to, opts, relative2 = "") {
   const kept = [];
   const created = [];
   for (const entry of fs8.readdirSync(from, { withFileTypes: true })) {
     const src = path9.join(from, entry.name);
     const dest = path9.join(to, entry.name);
-    const rel = path9.join(relative, entry.name);
+    const rel = path9.join(relative2, entry.name);
     if (opts.skip?.includes(rel.split(path9.sep).join("/"))) continue;
     if (entry.isDirectory()) {
       fs8.mkdirSync(dest, { recursive: true });
@@ -75187,6 +75505,7 @@ function parseArgs(argv) {
     printCreated: false,
     cleanup: false,
     prune: false,
+    screens: false,
     noSampleData: false,
     adopt: false,
     entity: [],
@@ -75357,6 +75676,9 @@ function parseArgs(argv) {
       case "--prune":
         flags.prune = true;
         break;
+      case "--screens":
+        flags.screens = true;
+        break;
       case "--version":
       case "-v":
         flags.version = true;
@@ -75949,10 +76271,10 @@ var packageContractSchema = zod_default.object({
   // copy WARNS (advisory) when a name has no doc in the workspace.
   knowledge_expects: zod_default.array(zod_default.string()).default([])
 });
-function checkTraversalFilter(node, path13, contextEntity, fieldByEntity, errors2) {
+function checkTraversalFilter(node, path14, contextEntity, fieldByEntity, errors2) {
   if (contextEntity === null) {
     errors2.push({
-      path: path13,
+      path: path14,
       message: `traversal filter "${node.path[0]}" resolves only directly over a from_table`
     });
     return;
@@ -75962,14 +76284,14 @@ function checkTraversalFilter(node, path13, contextEntity, fieldByEntity, errors
     const parsed2 = parseFieldKeyName(hop);
     if (parsed2 === null) {
       errors2.push({
-        path: path13,
+        path: path14,
         message: `traversal path[${index}] "${hop}" is not an entity.field alias`
       });
       return;
     }
     if (parsed2.entity !== current) {
       errors2.push({
-        path: path13,
+        path: path14,
         message: index === 0 ? `traversal path[0] "${hop}" is addressed on entity "${parsed2.entity}", but the filter holding it reads "${current}"` : `traversal path[${index}] "${hop}" is addressed on entity "${parsed2.entity}", but the hop before it lands on "${current}"`
       });
       return;
@@ -75977,14 +76299,14 @@ function checkTraversalFilter(node, path13, contextEntity, fieldByEntity, errors
     const field = fieldByEntity.get(parsed2.entity)?.get(parsed2.field);
     if (field === void 0) {
       errors2.push({
-        path: path13,
+        path: path14,
         message: `traversal path[${index}] "${hop}" is not a field on entity "${parsed2.entity}"`
       });
       return;
     }
     if (field.type !== "select_record_link") {
       errors2.push({
-        path: path13,
+        path: path14,
         message: `traversal path[${index}] "${hop}" is a ${field.type} field, not select_record_link`
       });
       return;
@@ -75996,7 +76318,7 @@ function checkTraversalFilter(node, path13, contextEntity, fieldByEntity, errors
   const parsed = parseFieldKeyName(innerField);
   if (parsed === null || parsed.entity !== current) {
     errors2.push({
-      path: path13,
+      path: path14,
       message: `traversal condition "${innerField}" must be an entity.field alias on "${current}", the entity its path lands on`
     });
     return;
@@ -76004,12 +76326,12 @@ function checkTraversalFilter(node, path13, contextEntity, fieldByEntity, errors
   const target = fieldByEntity.get(parsed.entity)?.get(parsed.field);
   if (target === void 0) {
     errors2.push({
-      path: path13,
+      path: path14,
       message: `traversal condition "${innerField}" is not a field on entity "${parsed.entity}"`
     });
     return;
   }
-  checkConditionShape(node.condition, parsed.entity, target, path13, fieldByEntity, errors2);
+  checkConditionShape(node.condition, parsed.entity, target, path14, fieldByEntity, errors2);
 }
 function contractFilterType(entityAlias, field, fieldByEntity, hops = 0) {
   if (field.type === "formula") {
@@ -76025,12 +76347,12 @@ function contractFilterType(entityAlias, field, fieldByEntity, hops = 0) {
   }
   return resolveFilterType(field);
 }
-function checkConditionShape(condition, entityAlias, field, path13, fieldByEntity, errors2) {
+function checkConditionShape(condition, entityAlias, field, path14, fieldByEntity, errors2) {
   const type = contractFilterType(entityAlias, field, fieldByEntity);
   if (type === void 0 && condition.type === void 0) return;
   const typed = type === void 0 ? condition : { ...condition, type };
-  for (const message2 of validateFilterCondition(typed, path13)) {
-    errors2.push({ path: path13, message: message2.startsWith(`${path13}: `) ? message2.slice(path13.length + 2) : message2 });
+  for (const message2 of validateFilterCondition(typed, path14)) {
+    errors2.push({ path: path14, message: message2.startsWith(`${path14}: `) ? message2.slice(path14.length + 2) : message2 });
   }
   if (field.type !== "select") return;
   const declared = new Set(field.options.map((option) => option.alias));
@@ -76038,20 +76360,20 @@ function checkConditionShape(condition, entityAlias, field, path13, fieldByEntit
   for (const raw of values3) {
     if (typeof raw !== "string" || isTemplateExpression(raw) || declared.has(raw)) continue;
     errors2.push({
-      path: path13,
+      path: path14,
       message: `filters field "${field.alias}" on option "${raw}", which that field does not declare (${declared.size > 0 ? [...declared].join(", ") : "it declares none"})`
     });
   }
 }
-function checkFilterFields(filters, path13, contextEntity, fieldByEntity, errors2, checkField) {
+function checkFilterFields(filters, path14, contextEntity, fieldByEntity, errors2, checkField) {
   if (filters.node_type === "group") {
     for (const child of filters.children) {
-      checkFilterFields(child, path13, contextEntity, fieldByEntity, errors2, checkField);
+      checkFilterFields(child, path14, contextEntity, fieldByEntity, errors2, checkField);
     }
     return;
   }
   if (filters.node_type === "traversal") {
-    checkTraversalFilter(filters, path13, contextEntity, fieldByEntity, errors2);
+    checkTraversalFilter(filters, path14, contextEntity, fieldByEntity, errors2);
     return;
   }
   if (filters.type === "current_member") return;
@@ -76059,13 +76381,13 @@ function checkFilterFields(filters, path13, contextEntity, fieldByEntity, errors
   checkField(filters.field_key);
   if (contextEntity === null) return;
   const field = fieldByEntity.get(contextEntity)?.get(filters.field_key);
-  if (field !== void 0) checkConditionShape(filters, contextEntity, field, path13, fieldByEntity, errors2);
+  if (field !== void 0) checkConditionShape(filters, contextEntity, field, path14, fieldByEntity, errors2);
 }
-function checkInputRefs(input, path13, entityAliases, roleAliases, optionAliases, fieldAliases, errors2) {
+function checkInputRefs(input, path14, entityAliases, roleAliases, optionAliases, fieldAliases, errors2) {
   if (input.type === "record_link") {
     if (!entityAliases.has(input.table_id)) {
       errors2.push({
-        path: path13,
+        path: path14,
         message: `record_link input references entity "${input.table_id}" which is not a declared entity`
       });
     }
@@ -76074,7 +76396,7 @@ function checkInputRefs(input, path13, entityAliases, roleAliases, optionAliases
   if (input.type === "member") {
     if (input.group !== void 0 && !roleAliases.has(input.group)) {
       errors2.push({
-        path: path13,
+        path: path14,
         message: `member input references role "${input.group}" which is not a declared role`
       });
     }
@@ -76084,7 +76406,7 @@ function checkInputRefs(input, path13, entityAliases, roleAliases, optionAliases
     if (input.field !== void 0) {
       if (!fieldAliases.has(input.field)) {
         errors2.push({
-          path: path13,
+          path: path14,
           message: `select input references field "${input.field}" which is not a declared field alias (entity.field)`
         });
       }
@@ -76093,7 +76415,7 @@ function checkInputRefs(input, path13, entityAliases, roleAliases, optionAliases
     for (const option of input.options ?? []) {
       if (option.value.includes(":") && !optionAliases.has(option.value)) {
         errors2.push({
-          path: path13,
+          path: path14,
           message: `select input option value "${option.value}" is not a declared option alias (entity.field:opt)`
         });
       }
@@ -76102,19 +76424,19 @@ function checkInputRefs(input, path13, entityAliases, roleAliases, optionAliases
   }
   if (input.type === "object") {
     for (const [key, child] of Object.entries(input.fields)) {
-      checkInputRefs(child, `${path13}.${key}`, entityAliases, roleAliases, optionAliases, fieldAliases, errors2);
+      checkInputRefs(child, `${path14}.${key}`, entityAliases, roleAliases, optionAliases, fieldAliases, errors2);
     }
     return;
   }
   if (input.type === "array") {
-    checkInputRefs(input.items, `${path13}[]`, entityAliases, roleAliases, optionAliases, fieldAliases, errors2);
+    checkInputRefs(input.items, `${path14}[]`, entityAliases, roleAliases, optionAliases, fieldAliases, errors2);
   }
 }
-function checkOutputRefs(output, path13, entityAliases, optionAliases, fieldAliases, errors2) {
+function checkOutputRefs(output, path14, entityAliases, optionAliases, fieldAliases, errors2) {
   if (output.type === "record_link") {
     if (!entityAliases.has(output.table_id)) {
       errors2.push({
-        path: path13,
+        path: path14,
         message: `record_link output references entity "${output.table_id}" which is not a declared entity`
       });
     }
@@ -76124,7 +76446,7 @@ function checkOutputRefs(output, path13, entityAliases, optionAliases, fieldAlia
     if (output.field !== void 0) {
       if (!fieldAliases.has(output.field)) {
         errors2.push({
-          path: path13,
+          path: path14,
           message: `select output references field "${output.field}" which is not a declared field alias (entity.field)`
         });
       }
@@ -76133,7 +76455,7 @@ function checkOutputRefs(output, path13, entityAliases, optionAliases, fieldAlia
     for (const option of output.options ?? []) {
       if (option.value.includes(":") && !optionAliases.has(option.value)) {
         errors2.push({
-          path: path13,
+          path: path14,
           message: `select output option value "${option.value}" is not a declared option alias (entity.field:opt)`
         });
       }
@@ -76142,16 +76464,16 @@ function checkOutputRefs(output, path13, entityAliases, optionAliases, fieldAlia
   }
   if (output.type === "object") {
     for (const [key, child] of Object.entries(output.fields)) {
-      checkOutputRefs(child, `${path13}.${key}`, entityAliases, optionAliases, fieldAliases, errors2);
+      checkOutputRefs(child, `${path14}.${key}`, entityAliases, optionAliases, fieldAliases, errors2);
     }
     return;
   }
   if (output.type === "array") {
-    checkOutputRefs(output.items, `${path13}[]`, entityAliases, optionAliases, fieldAliases, errors2);
+    checkOutputRefs(output.items, `${path14}[]`, entityAliases, optionAliases, fieldAliases, errors2);
   }
 }
-function checkSourceLinks(source, path13, parentEntity, fieldByEntity, errors2) {
-  const recur = (child) => checkSourceLinks(child, path13, parentEntity, fieldByEntity, errors2);
+function checkSourceLinks(source, path14, parentEntity, fieldByEntity, errors2) {
+  const recur = (child) => checkSourceLinks(child, path14, parentEntity, fieldByEntity, errors2);
   if (typeof source === "string") return;
   if ("eq" in source) return source.eq.forEach(recur);
   if ("neq" in source) return source.neq.forEach(recur);
@@ -76162,7 +76484,7 @@ function checkSourceLinks(source, path13, parentEntity, fieldByEntity, errors2)
   if (!("link" in source)) return;
   if (parentEntity === null) {
     errors2.push({
-      path: path13,
+      path: path14,
       message: `link source "${source.link.source}" resolves only directly over a from_table`
     });
     return;
@@ -76172,14 +76494,14 @@ function checkSourceLinks(source, path13, parentEntity, fieldByEntity, errors2)
   const sourceField = parentFields.get(source.link.source);
   if (sourceField === void 0) {
     errors2.push({
-      path: path13,
+      path: path14,
       message: `link source "${source.link.source}" is not a field on entity "${parentEntity}"`
     });
     return;
   }
   if (sourceField.type !== "select_record_link") {
     errors2.push({
-      path: path13,
+      path: path14,
       message: `link source "${source.link.source}" on entity "${parentEntity}" is a ${sourceField.type} field, not select_record_link`
     });
     return;
@@ -76188,68 +76510,68 @@ function checkSourceLinks(source, path13, parentEntity, fieldByEntity, errors2)
   if (targetFields === void 0) return;
   if (!targetFields.has(source.link.field)) {
     errors2.push({
-      path: path13,
+      path: path14,
       message: `link field "${source.link.field}" is not a field on target entity "${sourceField.target_entity}"`
     });
   }
 }
-function checkQueryFilterTraversals(filters, path13, contextEntity, fieldByEntity, errors2) {
-  checkFilterFields(filters, path13, contextEntity, fieldByEntity, errors2, () => {
+function checkQueryFilterTraversals(filters, path14, contextEntity, fieldByEntity, errors2) {
+  checkFilterFields(filters, path14, contextEntity, fieldByEntity, errors2, () => {
   });
 }
-function checkQueryEntityRefs(node, path13, entityAliases, fieldByEntity, errors2) {
+function checkQueryEntityRefs(node, path14, entityAliases, fieldByEntity, errors2) {
   const recur = (child, childPath) => checkQueryEntityRefs(child, childPath, entityAliases, fieldByEntity, errors2);
   const linkParent = (from) => from.kind === "from_table" ? from.from_entity : null;
   switch (node.kind) {
     case "from_table":
       if (!entityAliases.has(node.from_entity)) {
         errors2.push({
-          path: path13,
+          path: path14,
           message: `from_table references entity "${node.from_entity}" which is not a declared entity`
         });
         return;
       }
       if (node.filter !== void 0) {
-        checkQueryFilterTraversals(node.filter, `${path13}.filter`, node.from_entity, fieldByEntity, errors2);
+        checkQueryFilterTraversals(node.filter, `${path14}.filter`, node.from_entity, fieldByEntity, errors2);
       }
       return;
     case "filter":
       checkQueryFilterTraversals(
         node.predicate,
-        `${path13}.predicate`,
+        `${path14}.predicate`,
         node.from.kind === "from_table" ? node.from.from_entity : null,
         fieldByEntity,
         errors2
       );
-      recur(node.from, `${path13}.from`);
+      recur(node.from, `${path14}.from`);
       return;
     case "join":
-      recur(node.left, `${path13}.left`);
-      recur(node.right, `${path13}.right`);
+      recur(node.left, `${path14}.left`);
+      recur(node.right, `${path14}.right`);
       return;
     case "union":
-      node.sources.forEach((source, i2) => recur(source, `${path13}.sources[${i2}]`));
+      node.sources.forEach((source, i2) => recur(source, `${path14}.sources[${i2}]`));
       return;
     case "project":
       node.columns.forEach((column, i2) => {
         if (typeof column === "string") return;
-        checkSourceLinks(column.source, `${path13}.columns[${i2}]`, linkParent(node.from), fieldByEntity, errors2);
+        checkSourceLinks(column.source, `${path14}.columns[${i2}]`, linkParent(node.from), fieldByEntity, errors2);
       });
-      recur(node.from, `${path13}.from`);
+      recur(node.from, `${path14}.from`);
       return;
     case "unpivot":
       node.passthrough.forEach((column, i2) => {
-        checkSourceLinks(column.source, `${path13}.passthrough[${i2}]`, linkParent(node.from), fieldByEntity, errors2);
+        checkSourceLinks(column.source, `${path14}.passthrough[${i2}]`, linkParent(node.from), fieldByEntity, errors2);
       });
       node.rows.forEach((row, i2) => {
         for (const [key, source] of Object.entries(row)) {
-          checkSourceLinks(source, `${path13}.rows[${i2}].${key}`, linkParent(node.from), fieldByEntity, errors2);
+          checkSourceLinks(source, `${path14}.rows[${i2}].${key}`, linkParent(node.from), fieldByEntity, errors2);
         }
       });
-      recur(node.from, `${path13}.from`);
+      recur(node.from, `${path14}.from`);
       return;
     default:
-      recur(node.from, `${path13}.from`);
+      recur(node.from, `${path14}.from`);
   }
 }
 var WORKFLOW_BODY_TOKEN_PATTERN = /@@(entity|field|option|role|template):([^@]+)@@/g;
@@ -76753,6 +77075,357 @@ var bindingDriftSchema = zod_default.object({
   id: zod_default.string().describe("The stale concrete id the alias was bound to")
 });
 
+// ../shared/src/schemas/field_roles.ts
+var fieldRoleSchema = zod_default.enum([
+  "identity",
+  "mark",
+  "lifecycle",
+  "measure",
+  "expected_set",
+  "amount",
+  "when",
+  "party",
+  "contact",
+  "verdict"
+]);
+var FIELD_ROLE_TYPES = {
+  identity: ["text", "autonumber", "select_record_link"],
+  mark: ["files"],
+  lifecycle: ["select"],
+  measure: ["number", "formula", "rollup"],
+  expected_set: ["select"],
+  amount: ["number", "formula", "rollup"],
+  when: ["date"],
+  party: ["select_record_link"],
+  contact: ["text"],
+  verdict: ["boolean", "formula"]
+};
+var SINGLE_FIELD_ROLES = [
+  "identity",
+  "mark",
+  "lifecycle",
+  "amount",
+  "when",
+  "party",
+  "contact",
+  "verdict"
+];
+var fieldRoleDeclSchema = zod_default.object({
+  role: fieldRoleSchema,
+  against: zod_default.union([contractAliasSchema, zod_default.number()]).optional().describe("For a measure: the limit it is read against \u2014 a number field on the same entity, by alias, or a constant"),
+  alert: zod_default.enum(["over", "under"]).optional().describe("With against: which side of the limit needs attention \u2014 over a capacity, under a minimum")
+}).strict();
+var fieldRolesSchema = zod_default.record(
+  contractAliasSchema,
+  zod_default.record(
+    contractAliasSchema,
+    zod_default.preprocess((value2) => typeof value2 === "string" ? { role: value2 } : value2, fieldRoleDeclSchema).nullable()
+  )
+);
+function roleOf(roles, entity, field) {
+  if (!Object.hasOwn(roles, entity)) return void 0;
+  const fields = roles[entity];
+  return Object.hasOwn(fields, field) ? fields[field] ?? void 0 : void 0;
+}
+function checkFieldRoles(entities, roles) {
+  const errors2 = [];
+  const entityByAlias = new Map(entities.map((entity) => [entity.alias, entity]));
+  for (const [entityAlias, fields] of Object.entries(roles)) {
+    const entityPath = `field_roles.${entityAlias}`;
+    const entity = entityByAlias.get(entityAlias);
+    if (entity === void 0) {
+      errors2.push({ path: entityPath, message: `names entity "${entityAlias}", which this model does not declare` });
+      continue;
+    }
+    const fieldByAlias = new Map(entity.fields.map((field) => [field.alias, field]));
+    const seen = /* @__PURE__ */ new Map();
+    for (const [fieldAlias, decl] of Object.entries(fields)) {
+      const path14 = `${entityPath}.${fieldAlias}`;
+      const field = fieldByAlias.get(fieldAlias);
+      if (field === void 0) {
+        errors2.push({ path: path14, message: `names "${fieldAlias}", which is not a field of "${entityAlias}"` });
+        continue;
+      }
+      if (decl === null) {
+        errors2.push({ path: path14, message: `null clears a role a preset declared \u2014 this file starts from none` });
+        continue;
+      }
+      const allowed = FIELD_ROLE_TYPES[decl.role];
+      if (!allowed.includes(field.type)) {
+        errors2.push({ path: path14, message: `role "${decl.role}" sits on a ${allowed.join(" or ")} field, not a ${field.type}` });
+      }
+      if (SINGLE_FIELD_ROLES.includes(decl.role)) {
+        const first3 = seen.get(decl.role);
+        if (first3 !== void 0) {
+          errors2.push({ path: path14, message: `role "${decl.role}" is already "${first3}"'s \u2014 an entity carries it once` });
+        } else {
+          seen.set(decl.role, fieldAlias);
+        }
+      }
+      if (decl.role === "lifecycle" && field.type === "select" && field.multi === true) {
+        errors2.push({ path: path14, message: `a lifecycle is one stage at a time \u2014 a multi-select cannot be one` });
+      }
+      if (decl.against === void 0 && decl.alert === void 0) continue;
+      if (decl.role !== "measure") {
+        errors2.push({ path: path14, message: `against and alert belong to a measure \u2014 this role is "${decl.role}"` });
+        continue;
+      }
+      if (decl.against === void 0 || decl.alert === void 0) {
+        errors2.push({ path: path14, message: `against and alert are declared together \u2014 the limit, and which side of it needs attention` });
+        continue;
+      }
+      if (typeof decl.against === "number") continue;
+      if (decl.against === fieldAlias) {
+        errors2.push({ path: path14, message: `against names this field itself \u2014 a measure is read against another` });
+        continue;
+      }
+      const limit = fieldByAlias.get(decl.against);
+      if (limit === void 0) {
+        errors2.push({ path: path14, message: `against names "${decl.against}", which is not a field of "${entityAlias}"` });
+      } else if (limit.type !== "number") {
+        errors2.push({
+          path: path14,
+          message: `against names "${decl.against}", a ${limit.type} \u2014 a limit a row can state is a number field`
+        });
+      }
+    }
+  }
+  return errors2;
+}
+
+// ../shared/src/schemas/workspace_plan.ts
+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") },
+    record: "drawer",
+    tabs: "lifecycle"
+  },
+  party_register: {
+    label: "party register",
+    slots: { identity: slot("identity", true), mark: slot("mark"), contact: slot("contact"), worth: slot("measure"), risk: slot("verdict") },
+    record: "page",
+    tabs: "none"
+  },
+  offering_register: {
+    label: "offering register",
+    slots: { identity: slot("identity", true), mark: slot("mark"), price: slot("amount"), availability: slot("measure") },
+    record: "page",
+    tabs: "none"
+  },
+  transaction_ledger: {
+    label: "transaction ledger",
+    slots: { when: slot("when", true), amount: slot("amount", true), party: slot("party"), document: slot("expected_set") },
+    record: "drawer",
+    tabs: "none"
+  },
+  monitored_asset_set: {
+    label: "monitored-asset set",
+    slots: { identity: slot("identity", true), level: slot("measure", true), stage: slot("lifecycle") },
+    record: "drawer",
+    tabs: "none"
+  },
+  trend_deep_dive: {
+    label: "trend deep-dive",
+    slots: { when: slot("when", true), measure: slot("measure"), amount: slot("amount") },
+    record: "drawer",
+    tabs: "none"
+  }
+};
+var SHAPE_NAMES = Object.keys(SHAPE_REGISTRY);
+var CUSTOM_SHAPE = "custom";
+var contractScreenSchema = zod_default.object({
+  alias: contractAliasSchema.describe("Stable screen alias, unique within the app"),
+  label: zod_default.string().min(1).describe("What the screen is called in the app"),
+  shape: zod_default.enum([...SHAPE_NAMES, CUSTOM_SHAPE]).describe(`A shape, or "${CUSTOM_SHAPE}" with its own \`roles\``),
+  entity: contractAliasSchema.describe("The entity whose rows this screen is over"),
+  record: zod_default.enum(["drawer", "page"]).optional().describe("How one record opens from the list; absent, the shape decides"),
+  tabs: contractAliasSchema.nullable().optional().describe("A select field on the entity whose options are the tab strip; null for none; absent, the shape decides"),
+  slots: zod_default.record(zod_default.string(), contractAliasSchema).optional().describe("Slot \u2192 the field that fills it, where roles alone cannot decide"),
+  roles: zod_default.record(zod_default.string(), fieldRoleSchema).optional().describe(`For "${CUSTOM_SHAPE}" only: slot \u2192 the role that fills it`)
+});
+var modelAppSchema = contractAppSchema.pick({ alias: true, name: true, description: true, icon: true, theme: true }).extend({ screens: zod_default.array(contractScreenSchema).min(1) });
+function resolveScreen(app, screen, entityByAlias, roles) {
+  const path14 = `apps.${app.alias}.screens.${screen.alias}`;
+  const findings = [];
+  const entity = entityByAlias.get(screen.entity);
+  if (entity === void 0) {
+    findings.push({ path: `${path14}.entity`, message: `names entity "${screen.entity}", which this model does not declare` });
+  }
+  let slotSpec;
+  let shapeLabel;
+  let record2;
+  let tabsRule;
+  if (screen.shape === CUSTOM_SHAPE) {
+    if (screen.roles === void 0 || Object.keys(screen.roles).length === 0) {
+      findings.push({ path: `${path14}.roles`, message: `a "${CUSTOM_SHAPE}" screen declares its slots \u2014 \`roles\` maps each slot to the field role that fills it` });
+    }
+    slotSpec = Object.fromEntries(Object.entries(screen.roles ?? {}).map(([name2, role]) => [name2, slot(role, true)]));
+    shapeLabel = CUSTOM_SHAPE;
+    record2 = screen.record ?? "drawer";
+    tabsRule = "none";
+  } else {
+    const registry2 = SHAPE_REGISTRY[screen.shape];
+    if (screen.roles !== void 0) {
+      findings.push({ path: `${path14}.roles`, message: `"${screen.shape}" declares its own slots \u2014 \`roles\` is for a "${CUSTOM_SHAPE}" screen` });
+    }
+    slotSpec = registry2.slots;
+    shapeLabel = registry2.label;
+    record2 = screen.record ?? registry2.record;
+    tabsRule = registry2.tabs;
+  }
+  for (const name2 of Object.keys(screen.slots ?? {})) {
+    if (Object.hasOwn(slotSpec, name2)) continue;
+    findings.push({ path: `${path14}.slots.${name2}`, message: `"${shapeLabel}" has no slot "${name2}" \u2014 its slots are ${Object.keys(slotSpec).join(", ")}` });
+  }
+  if (entity === void 0) return { type: "invalid", findings };
+  const fieldByAlias = new Map(entity.fields.map((field) => [field.alias, field]));
+  const roleOfField = (field) => roleOf(roles, entity.alias, field.alias)?.role;
+  const slots = [];
+  const boundBy = /* @__PURE__ */ new Map();
+  for (const [name2, spec] of Object.entries(slotSpec)) {
+    const named = screen.slots?.[name2];
+    let field = null;
+    if (named !== void 0) {
+      const candidate = fieldByAlias.get(named);
+      if (candidate === void 0) {
+        findings.push({ path: `${path14}.slots.${name2}`, message: `names "${named}", which is not a field of entity "${entity.alias}"` });
+        continue;
+      }
+      const role = roleOfField(candidate);
+      if (role !== spec.role) {
+        findings.push({
+          path: `${path14}.slots.${name2}`,
+          message: `names "${named}", whose role is ${role === void 0 ? "not declared" : `"${role}"`} \u2014 this slot takes a "${spec.role}" field; declare the role in field_roles`
+        });
+        continue;
+      }
+      field = candidate;
+    } else {
+      const candidates = entity.fields.filter((f) => roleOfField(f) === spec.role);
+      if (candidates.length > 1) {
+        findings.push({
+          path: `${path14}.slots.${name2}`,
+          message: `"${entity.alias}" has ${candidates.length} "${spec.role}" fields (${candidates.map((f) => f.alias).join(", ")}) \u2014 name the one this slot takes`
+        });
+        continue;
+      }
+      if (candidates.length === 0 && spec.required) {
+        findings.push({ path: path14, message: `a ${shapeLabel} needs a "${spec.role}" field on "${entity.alias}" for its ${name2} \u2014 none declares that role` });
+        continue;
+      }
+      field = candidates[0] ?? null;
+    }
+    if (field !== null) {
+      const other = boundBy.get(field.alias);
+      if (other !== void 0) {
+        findings.push({ path: `${path14}.slots.${name2}`, message: `"${field.alias}" already fills ${other} \u2014 a field fills one slot` });
+        continue;
+      }
+      boundBy.set(field.alias, name2);
+    }
+    slots.push({ name: name2, role: spec.role, field });
+  }
+  let tabs = null;
+  if (screen.tabs === void 0) {
+    tabs = tabsRule === "lifecycle" ? entity.fields.find((field) => roleOfField(field) === "lifecycle") ?? null : null;
+  } else if (screen.tabs !== null) {
+    const field = fieldByAlias.get(screen.tabs);
+    if (field === void 0) {
+      findings.push({ path: `${path14}.tabs`, message: `names "${screen.tabs}", which is not a field of entity "${entity.alias}"` });
+    } else if (field.type !== "select") {
+      findings.push({ path: `${path14}.tabs`, message: `names "${screen.tabs}", a ${field.type} \u2014 a tab strip is a select field's options` });
+    } else {
+      tabs = field;
+    }
+  }
+  if (findings.length > 0) return { type: "invalid", findings };
+  return { type: "resolved", screen: { app, screen, entity, shapeLabel, record: record2, tabs, slots } };
+}
+function validateWorkspacePlan(model, roles, apps) {
+  const findings = [];
+  for (const dup of findDuplicates(apps.map((app) => app.alias))) {
+    findings.push({ path: "apps", message: `duplicate app alias "${dup}"` });
+  }
+  for (const dup of findDuplicates(apps.map((app) => app.name))) {
+    findings.push({ path: "apps", message: `duplicate app name "${dup}"` });
+  }
+  const entityByAlias = new Map(model.entities.map((entity) => [entity.alias, entity]));
+  for (const app of apps) {
+    for (const dup of findDuplicates(app.screens.map((screen) => screen.alias))) {
+      findings.push({ path: `apps.${app.alias}.screens`, message: `duplicate screen alias "${dup}"` });
+    }
+    for (const dup of findDuplicates(app.screens.map((screen) => screen.label))) {
+      findings.push({ path: `apps.${app.alias}.screens`, message: `duplicate screen label "${dup}"` });
+    }
+    for (const screen of app.screens) {
+      const resolved = resolveScreen(app, screen, entityByAlias, roles);
+      if (resolved.type === "invalid") findings.push(...resolved.findings);
+    }
+  }
+  return findings;
+}
+function roleCoverage(model, roles, rows) {
+  const notes = [];
+  for (const entity of model.entities) {
+    const entityRows = rows[entity.alias];
+    if (entityRows === void 0 || entityRows.length === 0) continue;
+    const fieldByAlias = new Map(entity.fields.map((field) => [field.alias, field]));
+    for (const field of entity.fields) {
+      const decl = roleOf(roles, entity.alias, field.alias);
+      if (decl === void 0) continue;
+      const path14 = `rows.${entity.alias}.${field.alias}`;
+      const values3 = entityRows.map((row) => row.fields[field.alias]);
+      switch (decl.role) {
+        case "lifecycle":
+        case "expected_set": {
+          if (field.type !== "select") break;
+          const used = new Set(values3.flatMap((value2) => Array.isArray(value2) ? value2 : [value2]));
+          const unused = field.options.filter((option) => !used.has(option.alias)).map((o) => o.label);
+          if (unused.length === 0) break;
+          notes.push({
+            path: path14,
+            message: decl.role === "lifecycle" ? `no row is in ${unused.length === 1 ? "stage" : "stages"} ${unused.join(", ")} \u2014 the desk shows ${unused.length === 1 ? "an empty band" : "empty bands"} there` : `no row has ${unused.join(", ")} \u2014 ${unused.length === 1 ? "that entry" : "those entries"} of the required set would show as ghosts on every subject`
+          });
+          break;
+        }
+        case "mark": {
+          const carried = values3.some((value2) => Array.isArray(value2) ? value2.length > 0 : typeof value2 === "string");
+          if (!carried) notes.push({ path: path14, message: `no row carries a picture \u2014 every register over it shows no mark` });
+          break;
+        }
+        case "measure": {
+          const { against, alert } = decl;
+          if (field.type !== "number" || against === void 0 || alert === void 0) break;
+          const read = entityRows.filter((row) => typeof row.fields[field.alias] === "number");
+          if (read.length === 0) {
+            notes.push({ path: path14, message: `no row carries a value \u2014 the meter has nothing to draw` });
+            break;
+          }
+          const limitOf = (row) => {
+            const raw = typeof against === "number" ? against : row.fields[against];
+            return typeof raw === "number" ? raw : void 0;
+          };
+          const attention = read.filter((row) => {
+            const limit = limitOf(row);
+            const level = row.fields[field.alias];
+            return limit !== void 0 && (alert === "over" ? level > limit : level < limit);
+          });
+          if (attention.length === 0) {
+            const limitName = typeof against === "number" ? String(against) : fieldByAlias.get(against)?.label ?? against;
+            notes.push({ path: path14, message: `no row is ${alert} ${limitName} \u2014 nothing on the screen needs attention` });
+          }
+          break;
+        }
+        default:
+          break;
+      }
+    }
+  }
+  return notes;
+}
+
 // ../shared/src/schemas/workspace_model.ts
 var workspaceModelContractSchema = packageContractSchema.omit({ apps: true, fixtures: true, knowledge: true, knowledge_expects: true }).extend({
   entities: zod_default.array(contractEntitySchema).describe("The tables this model creates, with their fields, options and views"),
@@ -76765,6 +77438,8 @@ var modelApplyEntrySchema = zod_default.object({
 }).strict();
 var workspaceModelFileSchema = workspaceModelContractSchema.extend({
   rows: contractRowsSchema.optional(),
+  field_roles: fieldRolesSchema.optional(),
+  apps: zod_default.array(modelAppSchema).optional(),
   preset: modelPresetSchema.optional(),
   apply: zod_default.array(modelApplyEntrySchema).optional()
 }).strict();
@@ -76774,6 +77449,8 @@ var workspaceModelOverlaySchema = zod_default.object({
   rename: packageBindSchema.optional().describe("Entity alias \u2192 what this business calls that table and its fields"),
   entities: zod_default.array(contractEntitySchema).optional().describe("Tables this business has that the preset does not declare"),
   rows: contractRowsSchema.optional(),
+  field_roles: fieldRolesSchema.optional().describe("Roles on the preset's fields and this business's own, over whatever the preset declares"),
+  apps: zod_default.array(modelAppSchema).optional(),
   apply: zod_default.array(modelApplyEntrySchema).optional()
 }).strict();
 function parseModelFile(raw) {
@@ -76832,13 +77509,25 @@ function resolveModelFrom(preset, overlay) {
       }))
     };
   }
+  const field_roles = { ...preset.field_roles };
+  for (const [entity, fields] of Object.entries(overlay.field_roles ?? {})) {
+    const merged2 = { ...field_roles[entity] };
+    for (const [field, decl] of Object.entries(fields)) {
+      if (decl === null) delete merged2[field];
+      else merged2[field] = decl;
+    }
+    if (Object.keys(merged2).length > 0) field_roles[entity] = merged2;
+    else delete field_roles[entity];
+  }
   return {
     type: "resolved",
     file: {
       entities: [...bound.contract.entities, ...overlay.entities ?? []],
       roles: contract.roles,
       templates: contract.templates,
+      ...Object.keys(field_roles).length > 0 ? { field_roles } : {},
       ...overlay.rows !== void 0 ? { rows: overlay.rows } : {},
+      ...overlay.apps !== void 0 ? { apps: overlay.apps } : {},
       ...overlay.apply !== void 0 ? { apply: overlay.apply } : {}
     }
   };
@@ -76848,9 +77537,29 @@ function toPackageContract(model) {
 }
 var ENTITIES_MAX = 50;
 var MODEL_ROWS_MAX = 2e3;
+var MODEL_DOCUMENTS_MAX = 2e3;
 function asList(value2) {
   return Array.isArray(value2) ? value2 : [value2];
 }
+function isStoredFileId(value2) {
+  return /^fil_[A-Za-z0-9]+$/.test(value2);
+}
+function modelRowDocuments(model, rows) {
+  const out = [];
+  for (const entity of model.entities) {
+    const filesFields = new Set(entity.fields.filter((field) => field.type === "files").map((field) => field.alias));
+    for (const row of rows[entity.alias] ?? []) {
+      for (const [field, value2] of Object.entries(row.fields)) {
+        if (!filesFields.has(field)) continue;
+        for (const raw of asList(value2)) {
+          if (typeof raw !== "string") continue;
+          out.push({ entity: entity.alias, ref: row.ref, field, value: raw, kind: isStoredFileId(raw) ? "file_id" : "path" });
+        }
+      }
+    }
+  }
+  return out;
+}
 function quote(value2) {
   return typeof value2 === "string" ? `"${value2}"` : `a ${typeof value2}`;
 }
@@ -76881,29 +77590,29 @@ function validateModelRows(model, rows) {
       }
       seenRefs.add(row.ref);
       for (const [fieldAlias, value2] of Object.entries(row.fields)) {
-        const path13 = `rows.${alias}.${row.ref}.${fieldAlias}`;
+        const path14 = `rows.${alias}.${row.ref}.${fieldAlias}`;
         const field = fieldByAlias.get(fieldAlias);
         if (field === void 0) {
           errors2.push({
-            path: path13,
+            path: path14,
             message: `is not a field of entity "${alias}" \u2014 a row's keys are field aliases (${fieldByAlias.size > 0 ? [...fieldByAlias.keys()].join(", ") : "this entity declares none"})`
           });
           continue;
         }
-        checkValue(field, value2, path13, refs, errors2);
+        checkValue(field, value2, path14, refs, errors2);
       }
     }
   }
   return errors2;
 }
-function checkValue(field, value2, path13, refs, errors2) {
+function checkValue(field, value2, path14, refs, errors2) {
   switch (field.type) {
     case "select": {
       const declared = new Set(field.options.map((option) => option.alias));
       for (const raw of asList(value2)) {
         if (typeof raw !== "string" || !declared.has(raw)) {
           errors2.push({
-            path: path13,
+            path: path14,
             message: `${quote(raw)} is not an option of this field \u2014 use an option alias (${declared.size > 0 ? [...declared].join(", ") : "this field declares none"})`
           });
         }
@@ -76914,7 +77623,7 @@ function checkValue(field, value2, path13, refs, errors2) {
       for (const raw of asList(value2)) {
         if (typeof raw !== "string" || !refs.has(raw)) {
           errors2.push({
-            path: path13,
+            path: path14,
             message: `${quote(raw)} names no row in this request \u2014 use "<entity-alias>:<ref>"`
           });
           continue;
@@ -76922,7 +77631,7 @@ function checkValue(field, value2, path13, refs, errors2) {
         const named = raw.slice(0, raw.indexOf(":"));
         if (named === field.target_entity) continue;
         errors2.push({
-          path: path13,
+          path: path14,
           message: `names a row of entity "${named}", but this field links to "${field.target_entity}"`
         });
       }
@@ -76931,17 +77640,23 @@ function checkValue(field, value2, path13, refs, errors2) {
     case "select_member": {
       if (value2 !== "self") {
         errors2.push({
-          path: path13,
+          path: path14,
           message: `${quote(value2)} is not a member this model can name \u2014 use "self"`
         });
       }
       return;
     }
     case "files": {
-      errors2.push({
-        path: path13,
-        message: `attaches a document, which only a starter bundle carries \u2014 upload it to the record after scaffolding`
-      });
+      for (const raw of asList(value2)) {
+        if (typeof raw !== "string" || raw === "") {
+          errors2.push({ path: path14, message: `${quote(raw)} is not a document \u2014 a path beside this file, or a fil_ id already uploaded here` });
+          continue;
+        }
+        if (isStoredFileId(raw)) continue;
+        if (raw.startsWith("/") || raw.split(/[\\/]/).includes("..")) {
+          errors2.push({ path: path14, message: `"${raw}" must be a relative path beside this file, with no ".."` });
+        }
+      }
       return;
     }
     case "formula":
@@ -76949,7 +77664,7 @@ function checkValue(field, value2, path13, refs, errors2) {
     case "lookup":
     case "autonumber": {
       errors2.push({
-        path: path13,
+        path: path14,
         message: `is a ${field.type} field, which the platform computes \u2014 drop the value`
       });
       return;
@@ -76957,13 +77672,13 @@ function checkValue(field, value2, path13, refs, errors2) {
     default: {
       if (!isFixtureScalarValue(value2)) {
         errors2.push({
-          path: path13,
+          path: path14,
           message: `must be a string, number, boolean or null on a ${field.type} field`
         });
         return;
       }
       if (field.type === "date" && parseFixtureDateExpression(value2).kind === "invalid") {
-        errors2.push({ path: path13, message: `${quote(value2)} is not a date \u2014 use ${FIXTURE_DATE_GRAMMAR}` });
+        errors2.push({ path: path14, message: `${quote(value2)} is not a date \u2014 use ${FIXTURE_DATE_GRAMMAR}` });
       }
     }
   }
@@ -76997,6 +77712,13 @@ function validateWorkspaceModel(model, rows) {
       message: `carries ${total} rows, above the ${MODEL_ROWS_MAX}-row cap for one model \u2014 a real data set belongs in an import`
     });
   }
+  const documents = new Set(modelRowDocuments(model, rows).map((document) => document.value)).size;
+  if (documents > MODEL_DOCUMENTS_MAX) {
+    errors2.push({
+      path: "rows",
+      message: `attaches ${documents} documents, above the ${MODEL_DOCUMENTS_MAX}-document cap for one model`
+    });
+  }
   errors2.push(...validateModelRows(model, rows));
   return errors2;
 }
@@ -77037,14 +77759,14 @@ function validateModelPreset(model, preset, rows) {
   }
   return errors2;
 }
-function unknownModelKeys(raw, kept, path13 = "") {
+function unknownModelKeys(raw, kept, path14 = "") {
   if (Array.isArray(raw)) {
     if (!Array.isArray(kept)) return [];
-    return raw.flatMap((item, i2) => unknownModelKeys(item, kept[i2], path13 === "" ? String(i2) : `${path13}.${i2}`));
+    return raw.flatMap((item, i2) => unknownModelKeys(item, kept[i2], path14 === "" ? String(i2) : `${path14}.${i2}`));
   }
   if (!isPlainObject2(raw) || !isPlainObject2(kept)) return [];
   return Object.keys(raw).flatMap((key) => {
-    const here = path13 === "" ? key : `${path13}.${key}`;
+    const here = path14 === "" ? key : `${path14}.${key}`;
     if (!(key in kept)) return [{ path: here, message: "unknown key \u2014 not part of the model" }];
     return unknownModelKeys(raw[key], kept[key], here);
   });
@@ -77061,16 +77783,18 @@ function readPresetModel(raw) {
       findings: [{ path: "from", message: "a preset IS the model it publishes, and this file names `from`" }]
     };
   }
-  const { preset, rows, apply, ...model } = parsed.parsed.file;
+  const { preset, rows, apps, apply, field_roles = {}, ...model } = parsed.parsed.file;
   const shape = [
     ...preset === void 0 ? [{ path: "preset", message: "a preset file carries a `preset` block \u2014 name, description, questions, variants" }] : [],
     ...rows === void 0 ? [] : [{ path: "rows", message: "a preset carries no first rows \u2014 they belong to the model a reader writes" }],
+    ...apps === void 0 ? [] : [{ path: "apps", message: "a preset carries no screens \u2014 the apps are the model a reader writes" }],
     ...apply === void 0 ? [] : [{ path: "apply", message: "a preset carries no `apply` \u2014 the packages to copy in are that reader's to name" }]
   ];
   if (preset === void 0 || shape.length > 0) return { type: "invalid", findings: shape };
   const findings = [
     ...unknownModelKeys(raw, parsed.parsed.file),
     ...validateWorkspaceModel(model, {}),
+    ...checkFieldRoles(model.entities, field_roles),
     ...validateModelPreset(model, preset, {})
   ];
   if (findings.length > 0) return { type: "invalid", findings };
@@ -77527,9 +78251,10 @@ Captured ${totalRows} row${totalRows === 1 ? "" : "s"} across ${result.captured.
 
 // src/scaffold_commands.ts
 import fs10 from "node:fs";
+import path11 from "node:path";
 
 // 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 not a model\'s to declare \u2014 build one in the workspace the model\ncreated, then publish that workspace as a starter.\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, and a value on a\n  files or platform-computed field.\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  "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  "apply":    [ /* published packages to copy in afterwards */ ] // optional\n}\n```\n\n**A model may not carry** `apps`, `fixtures`, `knowledge` or `knowledge_expects`,\nand no `excel` / `word` / `pdf-form` template: each of those is content that\nlives in a published bundle, which a model has none of. An unknown top-level key is\nan 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.\n\n```jsonc\n{ "alias": "order_ack", "label": "Order acknowledgement", "type": "email",\n  "content": "<p>Hello {{customer}}\u2026</p>" }\n```\n\n## Rows\n\nFirst records, keyed by entity alias. Up to 200 rows per entity and 2000 across\nthe model \u2014 a real data set belongs 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\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` | not allowed |\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## 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}\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`** and **`apply`** mean exactly what they mean in the full form \u2014\n  `"rows"` are this business\'s real first records, `"apply"` the packages copied\n  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  "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`.\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| `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\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.\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';
 
 // src/scaffold_commands.ts
 function printModelReference() {
@@ -77538,10 +78263,10 @@ function printModelReference() {
 function count(n, noun) {
   return `${n} ${noun}${n === 1 ? "" : "s"}`;
 }
-function issuePath(path13) {
-  return path13.length === 0 ? "the file" : path13.map((segment) => String(segment)).join(".");
+function issuePath(path14) {
+  return path14.length === 0 ? "the file" : path14.map((segment) => String(segment)).join(".");
 }
-function checkWorkspaceModel(raw) {
+function checkWorkspaceModel(raw, options = {}) {
   const parsed = workspaceModelFileSchema.safeParse(raw);
   if (!parsed.success) {
     return {
@@ -77552,28 +78277,87 @@ function checkWorkspaceModel(raw) {
       model: null
     };
   }
-  const { rows = {}, apply = [], preset, ...contract } = parsed.data;
+  const { rows = {}, field_roles = {}, apps = [], apply = [], preset, ...contract } = parsed.data;
   const findings = [
     // What the parse dropped is a mistake the author cannot otherwise see.
     ...unknownModelKeys(raw, parsed.data),
     ...validateWorkspaceModel(contract, rows),
+    // The roles, and every screen against them — the CLI's own checks, because
+    // neither a role nor the plan reaches the server.
+    ...checkFieldRoles(contract.entities, field_roles),
+    ...validateWorkspacePlan(contract, field_roles, apps),
     // Every BRANCH of a preset, applied onto the base and checked as a model of
     // its own — the branch nobody took is the one that fails in the workspace of
     // whoever takes it, who is the one reader who cannot fix it.
-    ...preset === void 0 ? [] : validateModelPreset(contract, preset, rows)
+    ...preset === void 0 ? [] : validateModelPreset(contract, preset, rows),
+    // A document a row names by path has to be beside the file, and the check
+    // is what proves it: `apply` uploading a path that is not there would fail
+    // after the tables exist, which is the outcome a model's author is least
+    // able to recover from.
+    ...options.baseDir === void 0 ? [] : missingDocuments(contract, rows, options.baseDir)
   ];
   if (findings.length > 0) return { findings, model: null };
-  return { findings, model: { contract, rows, apply } };
+  return { findings, model: { contract, rows, field_roles, apps, apply } };
+}
+function missingDocuments(contract, rows, baseDir) {
+  return modelRowDocuments(contract, rows).filter((document) => document.kind === "path" && !fs10.existsSync(path11.resolve(baseDir, document.value))).map((document) => ({
+    path: `rows.${document.entity}.${document.ref}.${document.field}`,
+    message: `"${document.value}" is not a file beside this model (looked in ${baseDir})`
+  }));
+}
+async function uploadModelDocuments(client, model, baseDir) {
+  const documents = modelRowDocuments(model.contract, model.rows).filter((document) => document.kind === "path");
+  if (documents.length === 0) return model.rows;
+  const paths = [...new Set(documents.map((document) => document.value))];
+  note(`Uploading ${count(paths.length, "document")} the rows attach\u2026`);
+  const idByPath = /* @__PURE__ */ new Map();
+  for (const relative2 of paths) {
+    const uploaded = await client.uploadFiles([path11.resolve(baseDir, relative2)]);
+    const error52 = uploaded.errors[0];
+    if (error52 !== void 0) {
+      throw new Error(`"${relative2}" could not be uploaded (${error52.error}), so no row was written.`);
+    }
+    const id = uploaded.files[0]?.id;
+    if (id === void 0) throw new Error(`The upload returned no file for "${relative2}".`);
+    idByPath.set(relative2, id);
+    note(`  uploaded  ${relative2}  ${id}`);
+  }
+  const filesFields = new Map(
+    model.contract.entities.map((entity) => [
+      entity.alias,
+      new Set(entity.fields.filter((field) => field.type === "files").map((field) => field.alias))
+    ])
+  );
+  return Object.fromEntries(
+    Object.entries(model.rows).map(([entityAlias, entityRows]) => [
+      entityAlias,
+      entityRows.map((row) => ({
+        ...row,
+        fields: Object.fromEntries(
+          Object.entries(row.fields).map(([fieldAlias, value2]) => [
+            fieldAlias,
+            filesFields.get(entityAlias)?.has(fieldAlias) ? (Array.isArray(value2) ? value2 : [value2]).map(
+              (raw) => typeof raw === "string" ? idByPath.get(raw) ?? raw : raw
+            ) : value2
+          ])
+        )
+      }))
+    ])
+  );
 }
 function countModel(model) {
   const fields = model.contract.entities.flatMap((entity) => entity.fields);
+  const screens = model.apps.flatMap((app) => app.screens);
   return {
     tables: model.contract.entities.length,
     fields: fields.length,
     links: fields.filter((field) => field.type === "select_record_link").length,
     views: model.contract.entities.reduce((n, entity) => n + entity.views.length, 0),
     roles: model.contract.roles.length,
-    rows: Object.values(model.rows).reduce((n, entityRows) => n + entityRows.length, 0)
+    rows: Object.values(model.rows).reduce((n, entityRows) => n + entityRows.length, 0),
+    apps: model.apps.length,
+    screens: screens.length,
+    custom: screens.filter((screen) => screen.shape === CUSTOM_SHAPE).length
   };
 }
 function summarizeModel(model) {
@@ -77584,13 +78368,65 @@ function summarizeModel(model) {
     count(counts.links, "link"),
     count(counts.views, "view"),
     count(counts.roles, "role"),
-    count(counts.rows, "row")
+    count(counts.rows, "row"),
+    ...counts.apps > 0 ? [count(counts.apps, "app"), count(counts.screens, "screen")] : [],
+    ...counts.custom > 0 ? [`${counts.custom} custom`] : []
   ].join(", ");
 }
+function resolvePlan(model) {
+  const entityByAlias = new Map(model.contract.entities.map((entity) => [entity.alias, entity]));
+  return model.apps.flatMap(
+    (app) => app.screens.flatMap((screen) => {
+      const resolved = resolveScreen(app, screen, entityByAlias, model.field_roles);
+      if (resolved.type === "invalid") {
+        throw new Error(`plan did not resolve: ${JSON.stringify(resolved.findings)}`);
+      }
+      return [resolved.screen];
+    })
+  );
+}
+function describePlan(model) {
+  const lines = [];
+  let lastApp;
+  for (const resolved of resolvePlan(model)) {
+    if (resolved.app.alias !== lastApp) {
+      lines.push(resolved.app.name);
+      lastApp = resolved.app.alias;
+    }
+    const rows = model.rows[resolved.entity.alias]?.length ?? 0;
+    const tabs = resolved.tabs === null ? "none" : resolved.tabs.type === "select" ? `${resolved.tabs.label} (${resolved.tabs.options.map((option) => option.label).join(" \u2192 ")})` : resolved.tabs.label;
+    lines.push(
+      `  ${resolved.screen.label} \u2014 ${resolved.shapeLabel} over ${resolved.entity.label} (${count(rows, "row")}) \xB7 ${resolved.record} \xB7 tabs: ${tabs}`
+    );
+    lines.push(
+      `    ${resolved.slots.map((entry) => `${entry.name} ${entry.field === null ? "(none)" : entry.field.label}`).join(" \xB7 ")}`
+    );
+  }
+  return lines;
+}
+function describeCoverage(model) {
+  return roleCoverage(model.contract, model.field_roles, model.rows).map((note2) => `  ${note2.path}: ${note2.message}`);
+}
+function planJson(model) {
+  return model.apps.map((app) => ({
+    alias: app.alias,
+    name: app.name,
+    screens: resolvePlan(model).filter((resolved) => resolved.app.alias === app.alias).map((resolved) => ({
+      alias: resolved.screen.alias,
+      label: resolved.screen.label,
+      shape: resolved.screen.shape,
+      entity: resolved.entity.alias,
+      record: resolved.record,
+      tabs: resolved.tabs === null ? null : resolved.tabs.alias,
+      slots: Object.fromEntries(resolved.slots.map((entry) => [entry.name, entry.field?.alias ?? null]))
+    }))
+  }));
+}
 var presetSourceSchema = zod_default.object({
   entities: zod_default.array(contractEntitySchema),
   roles: zod_default.array(contractRoleSchema),
   templates: zod_default.array(contractInlineTemplateSchema),
+  field_roles: fieldRolesSchema.default({}),
   preset: modelPresetSchema
 });
 async function resolveOverlay(file2, raw, overlay) {
@@ -77622,7 +78458,7 @@ async function resolveOverlay(file2, raw, overlay) {
   const { preset, ...contract } = source.data;
   const resolved = resolveModelFrom({ ...contract, variants: preset.variants }, overlay);
   if (resolved.type === "invalid") return { kind: "error", findings: resolved.findings };
-  const { findings, model } = checkWorkspaceModel(resolved.file);
+  const { findings, model } = checkWorkspaceModel(resolved.file, { baseDir: path11.dirname(path11.resolve(file2)) });
   const dropped = unknownModelKeys(raw, overlay);
   if (model === null || dropped.length > 0) {
     return { kind: "error", findings: [...dropped, ...findings] };
@@ -77674,7 +78510,7 @@ async function checkModelFile(file2) {
   if (parsed.parsed.form === "from") {
     return await resolveOverlay(file2, raw, parsed.parsed.overlay);
   }
-  const { findings, model } = checkWorkspaceModel(raw);
+  const { findings, model } = checkWorkspaceModel(raw, { baseDir: path11.dirname(path11.resolve(file2)) });
   if (model === null) return { kind: "error", findings };
   return { kind: "ok", model };
 }
@@ -77748,7 +78584,8 @@ Applying ${entry.package}\u2026`);
 async function scaffoldApply(client, model, options) {
   const labels = new Map(model.contract.entities.map((entity) => [entity.alias, entity.label]));
   note(`Applying the model \u2014 ${summarizeModel(model)}\u2026`);
-  const result = await postModel(client, model, options);
+  const rows = await uploadModelDocuments(client, model, path11.dirname(path11.resolve(options.file)));
+  const result = await postModel(client, { ...model, rows }, options);
   const width = Math.max(...result.entities.map((entity) => entity.alias.length), 0);
   for (const entity of result.entities) {
     note(
@@ -77771,6 +78608,16 @@ No rows were written \u2014 a table this model bound already holds records${adop
   the sample data, or add the rows yourself.`
     );
   }
+  const written = Object.values(result.record_ids).reduce((n, ids) => n + ids.length, 0);
+  if (written > 0) {
+    const runFile = `${path11.resolve(options.file)}.last_run.json`;
+    fs10.writeFileSync(
+      runFile,
+      `${JSON.stringify({ applied_at: (/* @__PURE__ */ new Date()).toISOString(), record_ids: result.record_ids }, null, 2)}
+`
+    );
+    note(`  rows written to ${path11.basename(runFile)} \u2014 delete_records over them resets the set`);
+  }
   const applied = await applyModelPackages(client, model.apply);
   const created = result.entities.filter((entity) => entity.created).length;
   const apps = applied.flatMap((entry) => entry.apps);
@@ -77944,7 +78791,7 @@ import fs12 from "node:fs";
 
 // src/file_command_io.ts
 import fs11 from "node:fs";
-import path11 from "node:path";
+import path12 from "node:path";
 var CliError = class extends Error {
   constructor(message2) {
     super(message2);
@@ -77967,8 +78814,8 @@ function rejectExtraArgs(rest2, arity, usage) {
   fail2(`${usage} takes ${arity} argument${arity === 1 ? "" : "s"} after <file>, got ${rest2.length}. Unused: ${rest2.slice(arity).join(" ")}`);
 }
 function writeFileAtomic(filePath, bytes) {
-  const dir = path11.dirname(path11.resolve(filePath));
-  const tmp = path11.join(dir, `.${path11.basename(filePath)}.${process.pid}.${Date.now()}.tmp`);
+  const dir = path12.dirname(path12.resolve(filePath));
+  const tmp = path12.join(dir, `.${path12.basename(filePath)}.${process.pid}.${Date.now()}.tmp`);
   fs11.writeFileSync(tmp, bytes);
   try {
     fs11.renameSync(tmp, filePath);
@@ -80771,16 +81618,16 @@ var MatcherView = class {
    * @returns {string|undefined}
    */
   getCurrentTag() {
-    const path13 = this._matcher.path;
-    return path13.length > 0 ? path13[path13.length - 1].tag : void 0;
+    const path14 = this._matcher.path;
+    return path14.length > 0 ? path14[path14.length - 1].tag : void 0;
   }
   /**
    * Get current namespace.
    * @returns {string|undefined}
    */
   getCurrentNamespace() {
-    const path13 = this._matcher.path;
-    return path13.length > 0 ? path13[path13.length - 1].namespace : void 0;
+    const path14 = this._matcher.path;
+    return path14.length > 0 ? path14[path14.length - 1].namespace : void 0;
   }
   /**
    * Get current node's attribute value.
@@ -80788,9 +81635,9 @@ var MatcherView = class {
    * @returns {*}
    */
   getAttrValue(attrName) {
-    const path13 = this._matcher.path;
-    if (path13.length === 0) return void 0;
-    return path13[path13.length - 1].values?.[attrName];
+    const path14 = this._matcher.path;
+    if (path14.length === 0) return void 0;
+    return path14[path14.length - 1].values?.[attrName];
   }
   /**
    * Check if current node has an attribute.
@@ -80798,9 +81645,9 @@ var MatcherView = class {
    * @returns {boolean}
    */
   hasAttr(attrName) {
-    const path13 = this._matcher.path;
-    if (path13.length === 0) return false;
-    const current = path13[path13.length - 1];
+    const path14 = this._matcher.path;
+    if (path14.length === 0) return false;
+    const current = path14[path14.length - 1];
     return current.values !== void 0 && attrName in current.values;
   }
   /**
@@ -80826,18 +81673,18 @@ var MatcherView = class {
    * @returns {number}
    */
   getPosition() {
-    const path13 = this._matcher.path;
-    if (path13.length === 0) return -1;
-    return path13[path13.length - 1].position ?? 0;
+    const path14 = this._matcher.path;
+    if (path14.length === 0) return -1;
+    return path14[path14.length - 1].position ?? 0;
   }
   /**
    * Get current node's repeat counter (occurrence count of this tag name).
    * @returns {number}
    */
   getCounter() {
-    const path13 = this._matcher.path;
-    if (path13.length === 0) return -1;
-    return path13[path13.length - 1].counter ?? 0;
+    const path14 = this._matcher.path;
+    if (path14.length === 0) return -1;
+    return path14[path14.length - 1].counter ?? 0;
   }
   /**
    * Get current node's sibling index (alias for getPosition).
@@ -86495,10 +87342,10 @@ function resolveRelativePath(basePath, relativePath) {
   }
   return resolved.join("/");
 }
-function findZipEntry(zipEntries, path13) {
-  if (zipEntries[path13]) return zipEntries[path13];
-  if (zipEntries[`xl/${path13}`]) return zipEntries[`xl/${path13}`];
-  const noSlash = path13.replace(/^\//, "");
+function findZipEntry(zipEntries, path14) {
+  if (zipEntries[path14]) return zipEntries[path14];
+  if (zipEntries[`xl/${path14}`]) return zipEntries[`xl/${path14}`];
+  const noSlash = path14.replace(/^\//, "");
   if (zipEntries[noSlash]) return zipEntries[noSlash];
   return void 0;
 }
@@ -88399,9 +89246,9 @@ function parseExcelFromZip(zip, options) {
   }
   return result;
 }
-function findEntry(zip, path13) {
-  if (zip[path13]) return zip[path13];
-  const lower2 = path13.toLowerCase();
+function findEntry(zip, path14) {
+  if (zip[path14]) return zip[path14];
+  const lower2 = path14.toLowerCase();
   for (const key of Object.keys(zip)) {
     if (key.toLowerCase() === lower2) return zip[key];
   }
@@ -89038,12 +89885,12 @@ function extractPivotRoundTripInfo(originalZip) {
     if (paths.length > 0) pivotTablesBySheetIndex.set(i2, paths);
   }
   const pivotXmlPaths = [];
-  for (const path13 of Object.keys(originalZip)) {
-    if (path13.startsWith("xl/pivotTables/") && path13.endsWith(".xml")) {
-      pivotXmlPaths.push(path13);
+  for (const path14 of Object.keys(originalZip)) {
+    if (path14.startsWith("xl/pivotTables/") && path14.endsWith(".xml")) {
+      pivotXmlPaths.push(path14);
     }
-    if (path13.startsWith("xl/pivotCache/") && path13.endsWith(".xml")) {
-      pivotXmlPaths.push(path13);
+    if (path14.startsWith("xl/pivotCache/") && path14.endsWith(".xml")) {
+      pivotXmlPaths.push(path14);
     }
   }
   return { cachesByWorkbook, pivotTablesBySheetIndex, pivotXmlPaths };
@@ -89051,15 +89898,15 @@ function extractPivotRoundTripInfo(originalZip) {
 function decode3(bytes) {
   return new TextDecoder().decode(bytes);
 }
-function pivotContentTypeFor(path13) {
-  if (path13.startsWith("xl/pivotTables/") && path13.endsWith(".xml")) {
-    return `<Override PartName="/${path13}" ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.pivotTable+xml"/>`;
+function pivotContentTypeFor(path14) {
+  if (path14.startsWith("xl/pivotTables/") && path14.endsWith(".xml")) {
+    return `<Override PartName="/${path14}" ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.pivotTable+xml"/>`;
   }
-  if (path13.includes("/pivotCacheDefinition") && path13.endsWith(".xml")) {
-    return `<Override PartName="/${path13}" ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.pivotCacheDefinition+xml"/>`;
+  if (path14.includes("/pivotCacheDefinition") && path14.endsWith(".xml")) {
+    return `<Override PartName="/${path14}" ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.pivotCacheDefinition+xml"/>`;
   }
-  if (path13.includes("/pivotCacheRecords") && path13.endsWith(".xml")) {
-    return `<Override PartName="/${path13}" ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.pivotCacheRecords+xml"/>`;
+  if (path14.includes("/pivotCacheRecords") && path14.endsWith(".xml")) {
+    return `<Override PartName="/${path14}" ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.pivotCacheRecords+xml"/>`;
   }
   return void 0;
 }
@@ -89132,16 +89979,16 @@ function exportWorkbook(workbook, originalZip) {
       regeneratedPaths.add(`xl/worksheets/sheet${i2 + 1}.xml`);
       regeneratedPaths.add(`xl/worksheets/_rels/sheet${i2 + 1}.xml.rels`);
     }
-    for (const path13 of Object.keys(originalZip)) {
-      if (path13.startsWith("xl/drawings/") || path13.startsWith("xl/charts/") || path13.startsWith("xl/tables/") || path13.startsWith("xl/media/")) {
-        regeneratedPaths.add(path13);
+    for (const path14 of Object.keys(originalZip)) {
+      if (path14.startsWith("xl/drawings/") || path14.startsWith("xl/charts/") || path14.startsWith("xl/tables/") || path14.startsWith("xl/media/")) {
+        regeneratedPaths.add(path14);
       }
     }
-    for (const [path13, data2] of Object.entries(originalZip)) {
-      if (regeneratedPaths.has(path13)) continue;
-      const ext = path13.slice(path13.lastIndexOf(".") + 1).toLowerCase();
+    for (const [path14, data2] of Object.entries(originalZip)) {
+      if (regeneratedPaths.has(path14)) continue;
+      const ext = path14.slice(path14.lastIndexOf(".") + 1).toLowerCase();
       if (!DECLARED_EXTENSIONS.includes(ext)) continue;
-      entries2[path13] = data2;
+      entries2[path14] = data2;
     }
   }
   const sharedStrings = buildSharedStrings(workbook);
@@ -89157,8 +90004,8 @@ function exportWorkbook(workbook, originalZip) {
     buildWorkbookRels(workbook, pivotInfo)
   );
   const extraContentTypes = [];
-  for (const path13 of pivotInfo.pivotXmlPaths) {
-    const ct = pivotContentTypeFor(path13);
+  for (const path14 of pivotInfo.pivotXmlPaths) {
+    const ct = pivotContentTypeFor(path14);
     if (ct) extraContentTypes.push(ct);
   }
   let globalChartIndex = 1;
@@ -91521,9 +92368,9 @@ function computeExpression(tokens) {
         break;
     }
   }
-  return evaluate(values3, operator);
+  return evaluate2(values3, operator);
 }
-function evaluate(values3, operator) {
+function evaluate2(values3, operator) {
   let result = false;
   switch (operator) {
     case ">":
@@ -98344,14 +99191,14 @@ var DependencyGraph = class {
       stack.push({ cell: p, path: [cell, p] });
     }
     while (stack.length > 0) {
-      const { cell: current, path: path13 } = stack.pop();
-      if (current === cell || originCoarse.has(current)) return path13;
+      const { cell: current, path: path14 } = stack.pop();
+      if (current === cell || originCoarse.has(current)) return path14;
       if (visited.has(current)) continue;
       visited.add(current);
       const nextPrec = this.precedents.get(current);
       if (!nextPrec) continue;
       for (const p of nextPrec) {
-        stack.push({ cell: p, path: [...path13, p] });
+        stack.push({ cell: p, path: [...path14, p] });
       }
     }
     return null;
@@ -104869,8 +105716,8 @@ function buildParagraphElement(para, ctx, bookmarks) {
   for (let i2 = 0; i2 <= runElements.length; i2++) slots.push([]);
   if (bookmarks) {
     for (const bm of bookmarks) {
-      const slot = Math.max(0, Math.min(runElements.length, bm.beforeRun));
-      slots[slot].push(bm.element);
+      const slot2 = Math.max(0, Math.min(runElements.length, bm.beforeRun));
+      slots[slot2].push(bm.element);
     }
   }
   const children = [];
@@ -105310,8 +106157,8 @@ async function docModelToDocx(model) {
 // ../ooxml/src/opc.ts
 var import_jszip = __toESM(require_lib4(), 1);
 function dropFolderEntries(zip) {
-  for (const [path13, entry] of Object.entries(zip.files)) {
-    if (entry.dir) delete zip.files[path13];
+  for (const [path14, entry] of Object.entries(zip.files)) {
+    if (entry.dir) delete zip.files[path14];
   }
 }
 
@@ -105566,11 +106413,11 @@ async function parseDocx(buffer) {
   const zip = await import_jszip3.default.loadAsync(buffer);
   const parts = /* @__PURE__ */ new Map();
   const filePromises = [];
-  zip.forEach((path13, file2) => {
+  zip.forEach((path14, file2) => {
     if (file2.dir) return;
     filePromises.push(
       file2.async("uint8array").then((bytes) => {
-        parts.set(path13, bytes);
+        parts.set(path14, bytes);
       })
     );
   });
@@ -105802,9 +106649,9 @@ var DEFAULT_PARTS = [
   ["word/theme/theme1.xml", () => encoder.encode(THEME_XML)]
 ];
 function fillDefaultParts(parts) {
-  for (const [path13, makeBytes] of DEFAULT_PARTS) {
-    if (!parts.has(path13)) {
-      parts.set(path13, makeBytes());
+  for (const [path14, makeBytes] of DEFAULT_PARTS) {
+    if (!parts.has(path14)) {
+      parts.set(path14, makeBytes());
     }
   }
   return parts;
@@ -105814,9 +106661,9 @@ function fillDefaultParts(parts) {
 async function serializeDocx(doc) {
   const zip = new import_jszip4.default();
   const parts = fillDefaultParts(new Map(doc.parts));
-  for (const [path13, bytes] of parts) {
-    if (path13 === "word/document.xml") continue;
-    zip.file(path13, bytes);
+  for (const [path14, bytes] of parts) {
+    if (path14 === "word/document.xml") continue;
+    zip.file(path14, bytes);
   }
   const documentXml = serializeDocumentXml(doc);
   zip.file("word/document.xml", documentXml);
@@ -106155,18 +107002,18 @@ function replaceInParagraph(p, search, replace2) {
     }
     if (matches.length === 0) continue;
     count2 += matches.length;
-    for (const slot of segment) {
+    for (const slot2 of segment) {
       let out = "";
-      let cursor = slot.start;
+      let cursor = slot2.start;
       for (const m of matches) {
-        if (m.end <= slot.start || m.start >= slot.end) continue;
-        const keepUntil = Math.max(cursor, Math.min(m.start, slot.end));
+        if (m.end <= slot2.start || m.start >= slot2.end) continue;
+        const keepUntil = Math.max(cursor, Math.min(m.start, slot2.end));
         if (keepUntil > cursor) out += joined.slice(cursor, keepUntil);
-        if (m.start >= slot.start && m.start < slot.end) out += replace2;
-        cursor = Math.max(cursor, Math.min(m.end, slot.end));
+        if (m.start >= slot2.start && m.start < slot2.end) out += replace2;
+        cursor = Math.max(cursor, Math.min(m.end, slot2.end));
       }
-      if (cursor < slot.end) out += joined.slice(cursor, slot.end);
-      rewritten.set(`${slot.inlineIndex}:${slot.childIndex}`, out);
+      if (cursor < slot2.end) out += joined.slice(cursor, slot2.end);
+      rewritten.set(`${slot2.inlineIndex}:${slot2.childIndex}`, out);
     }
   }
   if (count2 === 0) return [p, 0];
@@ -106608,167 +107455,113 @@ async function runKnowledgeCommand(client, subcommand, toolArgs, flags, restArgs
 }
 
 // src/preview.ts
-import { spawn as spawn3 } from "node:child_process";
 import { createServer } from "node:http";
-import { readFileSync, writeFileSync, existsSync as existsSync2, mkdtempSync, rmSync, readdirSync } from "node:fs";
-import { tmpdir as tmpdir2 } from "node:os";
-import { join as join2, dirname, resolve, extname, basename } from "node:path";
-import { fileURLToPath as fileURLToPath2 } from "node:url";
-import { setTimeout as sleep2 } from "node:timers/promises";
-var HERE = dirname(fileURLToPath2(import.meta.url));
+import { readFileSync as readFileSync3, writeFileSync, existsSync as existsSync4, realpathSync, statSync } from "node:fs";
+import { join as join4, dirname as dirname2, resolve, extname, basename, isAbsolute, relative } from "node:path";
+import { fileURLToPath as fileURLToPath3 } from "node:url";
+import { setTimeout as sleep4 } from "node:timers/promises";
+var HERE2 = dirname2(fileURLToPath3(import.meta.url));
 function fail3(msg) {
   console.error(msg);
   process.exit(1);
 }
-function findChrome() {
-  const env = process.env.LOTICS_CHROME || process.env.CHROME_PATH;
-  if (env && existsSync2(env)) return env;
-  const home = process.env.HOME || "";
-  const pwDir = process.platform === "darwin" ? `${home}/Library/Caches/ms-playwright` : `${home}/.cache/ms-playwright`;
-  if (existsSync2(pwDir)) {
-    const rel = process.platform === "darwin" ? ["chrome-mac/Chromium.app/Contents/MacOS/Chromium"] : ["chrome-linux/chrome", "chrome-linux/headless_shell"];
-    const revs = readdirSync(pwDir).filter((n) => n.startsWith("chromium-") || n.startsWith("chromium_headless_shell-")).sort().reverse();
-    for (const rev2 of revs) {
-      for (const r of rel) {
-        const bin = join2(pwDir, rev2, r);
-        if (existsSync2(bin)) return bin;
-      }
-    }
-  }
-  const systemPaths = [
-    "/usr/bin/google-chrome",
-    "/usr/bin/google-chrome-stable",
-    "/usr/bin/chromium",
-    "/usr/bin/chromium-browser",
-    "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
-    "/Applications/Chromium.app/Contents/MacOS/Chromium"
-  ];
-  return systemPaths.find((p) => existsSync2(p)) ?? null;
-}
-async function cdpConnect(wsUrl) {
-  const ws = new WebSocket(wsUrl);
-  await new Promise((res, rej) => {
-    ws.onopen = () => res();
-    ws.onerror = () => rej(new Error("CDP websocket failed to open"));
-  });
-  let id = 0;
-  const pending = /* @__PURE__ */ new Map();
-  ws.onclose = () => {
-    for (const done of pending.values()) done(Promise.reject(new Error("CDP connection closed (Chrome exited?)")));
-    pending.clear();
-  };
-  ws.onmessage = (e) => {
-    const m = JSON.parse(String(e.data));
-    if (m.id != null && pending.has(m.id)) {
-      const done = pending.get(m.id);
-      pending.delete(m.id);
-      done(m.error ? Promise.reject(new Error(m.error.message)) : m.result);
-    }
-  };
-  const send = (method, params = {}) => new Promise((res) => {
-    const i2 = ++id;
-    pending.set(i2, (r) => res(r));
-    ws.send(JSON.stringify({ id: i2, method, params }));
-  });
-  return { send, close: () => ws.close() };
-}
-function isStoredFileId(target) {
-  return /^fil_[A-Za-z0-9]+$/.test(target);
-}
 function defaultPreviewOutputPath(filename, cwd) {
-  return join2(cwd, basename(filename, extname(filename)) + ".png");
+  return join4(cwd, basename(filename, extname(filename)) + ".png");
 }
+var STATIC_TYPES = {
+  ".html": "text/html; charset=utf-8",
+  ".htm": "text/html; charset=utf-8",
+  ".css": "text/css",
+  ".js": "application/javascript",
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif",
+  ".svg": "image/svg+xml",
+  ".webp": "image/webp",
+  ".woff": "font/woff",
+  ".woff2": "font/woff2",
+  ".ttf": "font/ttf"
+};
 async function runPreviewCommand(filePath, flags) {
-  if (!filePath) fail3("Usage: lotics preview <file.docx|.xlsx | fil_id> [-o <file.png>]");
+  if (!filePath) fail3("Usage: lotics preview <file.docx|.xlsx|.html | fil_id> [-o <file.png>]");
   const abs2 = resolve(filePath);
-  if (!existsSync2(abs2)) fail3(`File not found: ${abs2}`);
+  if (!existsSync4(abs2)) fail3(`File not found: ${abs2}`);
   const ext = extname(abs2).toLowerCase();
-  const type = ext === ".docx" ? "docx" : ext === ".xlsx" || ext === ".xls" || ext === ".csv" ? "xlsx" : null;
-  if (!type) fail3(`Unsupported file type "${ext}" \u2014 preview supports .docx and .xlsx/.csv. (PDFs open directly \u2014 no preview needed.)`);
-  if (typeof WebSocket === "undefined") {
-    fail3("lotics preview needs Node 22+ (it drives Chrome over CDP via the built-in WebSocket). Upgrade Node and retry.");
-  }
-  const bundlePath = join2(HERE, "..", "render_page.js");
-  if (!existsSync2(bundlePath)) fail3(`Render bundle missing at ${bundlePath} \u2014 reinstall @lotics/cli (build step failed).`);
-  const chrome = findChrome();
-  if (!chrome) {
-    fail3(
-      "No Chrome/Chromium found. Set CHROME_PATH to a Chrome binary, or install one:\n  npx playwright install chromium   (then it's auto-detected)\n  or install Google Chrome / Chromium via your package manager."
-    );
+  const type = ext === ".docx" ? "docx" : ext === ".xlsx" || ext === ".xls" || ext === ".csv" ? "xlsx" : ext === ".html" || ext === ".htm" ? "html" : null;
+  if (!type) fail3(`Unsupported file type "${ext}" \u2014 preview supports .docx, .xlsx/.csv and .html. (PDFs open directly \u2014 no preview needed.)`);
+  let server;
+  let pageUrl;
+  if (type === "html") {
+    const dir = realpathSync(dirname2(abs2));
+    server = createServer((req, res) => {
+      let urlPath;
+      try {
+        urlPath = decodeURIComponent((req.url ?? "/").split("?")[0]);
+      } catch {
+        res.writeHead(400);
+        res.end();
+        return;
+      }
+      const target = resolve(dir, `.${urlPath}`);
+      if (!existsSync4(target) || !statSync(target).isFile()) {
+        res.writeHead(404);
+        res.end();
+        return;
+      }
+      const inside = relative(dir, realpathSync(target));
+      if (inside.startsWith("..") || isAbsolute(inside)) {
+        res.writeHead(404);
+        res.end();
+        return;
+      }
+      res.writeHead(200, { "content-type": STATIC_TYPES[extname(target).toLowerCase()] ?? "application/octet-stream" });
+      res.end(readFileSync3(target));
+    });
+    pageUrl = (port) => `http://127.0.0.1:${port}/${encodeURIComponent(basename(abs2))}`;
+  } else {
+    const bundlePath = join4(HERE2, "..", "render_page.js");
+    if (!existsSync4(bundlePath)) fail3(`Render bundle missing at ${bundlePath} \u2014 reinstall @lotics/cli (build step failed).`);
+    const b64 = readFileSync3(abs2).toString("base64");
+    const bundle = readFileSync3(bundlePath, "utf8");
+    const html = `<!doctype html><html><head><meta charset="utf-8"><style>body{margin:0;background:#fff;font-family:sans-serif}#root{padding:20px;max-width:1240px;margin:0 auto}</style></head><body><div id="root"></div><script>window.__LOTICS_RENDER=${JSON.stringify({ type, b64 })}</script><script src="/render_page.js"></script></body></html>`;
+    server = createServer((req, res) => {
+      if (req.url === "/render_page.js") {
+        res.writeHead(200, { "content-type": "application/javascript" });
+        res.end(bundle);
+      } else {
+        res.writeHead(200, { "content-type": "text/html" });
+        res.end(html);
+      }
+    });
+    pageUrl = (port) => `http://127.0.0.1:${port}/`;
   }
-  const b64 = readFileSync(abs2).toString("base64");
-  const bundle = readFileSync(bundlePath, "utf8");
-  const html = `<!doctype html><html><head><meta charset="utf-8"><style>body{margin:0;background:#fff;font-family:sans-serif}#root{padding:20px;max-width:1240px;margin:0 auto}</style></head><body><div id="root"></div><script>window.__LOTICS_RENDER=${JSON.stringify({ type, b64 })}</script><script src="/render_page.js"></script></body></html>`;
-  const server = createServer((req, res) => {
-    if (req.url === "/render_page.js") {
-      res.writeHead(200, { "content-type": "application/javascript" });
-      res.end(bundle);
-    } else {
-      res.writeHead(200, { "content-type": "text/html" });
-      res.end(html);
-    }
-  });
   await new Promise((r) => server.listen(0, "127.0.0.1", () => r()));
   const httpPort = server.address().port;
-  const udd = mkdtempSync(join2(tmpdir2(), "lotics-render-"));
-  const child = spawn3(chrome, [
-    "--headless=new",
-    "--disable-gpu",
-    "--no-sandbox",
-    "--hide-scrollbars",
-    // Large multi-sheet renders exhaust the (often tiny) /dev/shm in containers/WSL2 and
-    // crash the tab; back shared memory with /tmp instead.
-    "--disable-dev-shm-usage",
-    "--force-device-scale-factor=2",
-    "--remote-debugging-port=0",
-    `--user-data-dir=${udd}`,
-    "about:blank"
-  ], { stdio: "ignore" });
+  let session;
+  try {
+    session = await launchChrome();
+  } catch (error52) {
+    server.close();
+    fail3(error52 instanceof Error ? error52.message : String(error52));
+  }
+  const { cdp, chrome } = session;
   const cleanup = () => {
-    try {
-      child.kill();
-    } catch {
-    }
+    session.close();
     try {
       server.close();
     } catch {
     }
-    try {
-      rmSync(udd, { recursive: true, force: true });
-    } catch {
-    }
   };
   try {
-    let cdpPort = 0;
-    const portFile = join2(udd, "DevToolsActivePort");
-    for (let i2 = 0; i2 < 100 && !cdpPort; i2++) {
-      if (existsSync2(portFile)) {
-        const p = parseInt(readFileSync(portFile, "utf8").split("\n")[0], 10);
-        if (p) cdpPort = p;
-      }
-      if (!cdpPort) await sleep2(100);
-    }
-    if (!cdpPort) throw new Error("Chrome did not expose a debugging port (launch failed?).");
-    let target;
-    for (let i2 = 0; i2 < 60 && !target?.webSocketDebuggerUrl; i2++) {
-      try {
-        const list2 = await (await fetch(`http://127.0.0.1:${cdpPort}/json/list`)).json();
-        target = list2.find((t) => t.type === "page");
-      } catch {
-      }
-      if (!target?.webSocketDebuggerUrl) await sleep2(100);
-    }
-    if (!target?.webSocketDebuggerUrl) throw new Error("No Chrome page target available.");
-    const cdp = await cdpConnect(target.webSocketDebuggerUrl);
-    await cdp.send("Page.enable");
-    await cdp.send("Runtime.enable");
-    await cdp.send("Page.navigate", { url: `http://127.0.0.1:${httpPort}/` });
+    await cdp.send("Page.navigate", { url: pageUrl(httpPort) });
+    const doneExpression = type === "html" ? "({done: document.readyState === 'complete' && Array.from(document.images).every((i) => i.complete), err: '', warnings: []})" : "({done: !!window.__loticsDone, err: window.__loticsError || '', warnings: window.__loticsWarnings || []})";
     let err2;
     let done = false;
     const warnings = [];
     for (let i2 = 0; i2 < 200; i2++) {
       const r = await cdp.send("Runtime.evaluate", {
-        expression: "({done: !!window.__loticsDone, err: window.__loticsError || '', warnings: window.__loticsWarnings || []})",
+        expression: doneExpression,
         returnByValue: true
       });
       const v = r.result?.value;
@@ -106778,15 +107571,24 @@ async function runPreviewCommand(filePath, flags) {
         if (v.warnings?.length) warnings.push(...v.warnings);
         break;
       }
-      await sleep2(75);
+      await sleep4(75);
     }
     if (!done) throw new Error("Render timed out (page never signaled completion).");
     if (err2) throw new Error(`Render engine error: ${err2}`);
-    const metrics = await cdp.send("Page.getLayoutMetrics");
-    const size2 = metrics.cssContentSize ?? metrics.contentSize ?? { width: 1240, height: 1600 };
+    const measure = async () => {
+      const metrics = await cdp.send("Page.getLayoutMetrics");
+      const size2 = metrics.cssContentSize ?? metrics.contentSize ?? { width: 1240, height: 1600 };
+      return { w: Math.ceil(size2.width), h: Math.ceil(size2.height) };
+    };
+    const first3 = await measure();
+    await cdp.send("Emulation.setDeviceMetricsOverride", {
+      width: Math.min(first3.w, 15e3),
+      height: Math.min(first3.h, 15e3),
+      deviceScaleFactor: 2,
+      mobile: false
+    });
+    const { w, h } = await measure();
     const MAX_CAPTURE = 15e3;
-    const w = Math.ceil(size2.width);
-    const h = Math.ceil(size2.height);
     if (w > MAX_CAPTURE || h > MAX_CAPTURE) {
       warnings.push(`content ${w}\xD7${h}px clipped to ${Math.min(w, MAX_CAPTURE)}\xD7${Math.min(h, MAX_CAPTURE)}px (exceeds the ${MAX_CAPTURE}px capture limit)`);
     }
@@ -106795,8 +107597,7 @@ async function runPreviewCommand(filePath, flags) {
       captureBeyondViewport: true,
       clip: { x: 0, y: 0, width: Math.min(w, MAX_CAPTURE), height: Math.min(h, MAX_CAPTURE), scale: 1 }
     });
-    cdp.close();
-    const outPath = flags.output ? resolve(flags.output) : join2(dirname(abs2), basename(abs2, ext) + ".png");
+    const outPath = flags.output ? resolve(flags.output) : join4(dirname2(abs2), basename(abs2, ext) + ".png");
     writeFileSync(outPath, Buffer.from(shot.data, "base64"));
     console.log(`Rendered ${basename(abs2)} \u2192 ${outPath}  (${Math.min(w, MAX_CAPTURE)}\xD7${Math.min(h, MAX_CAPTURE)}, via ${basename(chrome)})`);
     for (const warn2 of warnings) console.error(`  \u26A0 ${warn2}`);
@@ -106958,8 +107759,8 @@ function prompt(question) {
     });
   });
 }
-async function publicPost(path13, body) {
-  const response = await fetch(`${API_BASE_URL}${path13}`, {
+async function publicPost(path14, body) {
+  const response = await fetch(`${API_BASE_URL}${path14}`, {
     method: "POST",
     headers: { "Content-Type": "application/json" },
     body: JSON.stringify(body)
@@ -107262,13 +108063,13 @@ async function resolveWorkspace(client, ctx) {
 function resolveUploadPaths(rawPaths) {
   const result = [];
   for (const p of rawPaths) {
-    const resolved = path12.resolve(p);
+    const resolved = path13.resolve(p);
     const stat = fs15.statSync(resolved);
     if (stat.isDirectory()) {
       const entries2 = fs15.readdirSync(resolved, { withFileTypes: true });
       for (const entry of entries2) {
         if (entry.isFile()) {
-          result.push(path12.join(resolved, entry.name));
+          result.push(path13.join(resolved, entry.name));
         }
       }
     } else {
@@ -107439,7 +108240,7 @@ async function main() {
       if (!toolArgs) {
         console.error(`Usage: lotics scaffold ${subcommand} <model.json>`);
         console.error(
-          subcommand === "check" ? '       Validates the model offline \u2014 no account, no network. Reports every\n       problem in one run; exits 1 if there is one.\n       A file written as {"from": "<preset_id>", \u2026} is the exception: it names a\n       published preset, so checking it READS that preset and needs the network\n       for that one step. Everything after it is the same offline check.\n       --json prints {ok, tables, fields, links, views, roles, rows} or the findings.' : "       Creates the model's tables, fields, options, views, roles and first rows\n       in this workspace. Additive: an existing table of the same name is\n       ADOPTED and given the fields, options and views it is missing, never\n       modified \u2014 while `setup` refuses that name instead. Rows land only\n       where every bound table is empty.\n       --json prints one object and nothing else."
+          subcommand === "check" ? '       Validates the model offline \u2014 no account, no network. Reports every\n       problem in one run; exits 1 if there is one.\n       A file written as {"from": "<preset_id>", \u2026} is the exception: it names a\n       published preset, so checking it READS that preset and needs the network\n       for that one step. Everything after it is the same offline check.\n       Prints the counts, then every planned screen with the field in each of\n       its slots, then what the first rows would show.\n       --json prints {ok, tables, fields, links, views, roles, rows, apps, screens,\n       plan, coverage} or the findings.' : "       Creates the model's tables, fields, options, views, roles and first rows\n       in this workspace. Additive: an existing table of the same name is\n       ADOPTED and given the fields, options and views it is missing, never\n       modified \u2014 while `setup` refuses that name instead. Rows land only\n       where every bound table is empty.\n       --json prints one object and nothing else."
         );
         console.error("       How to write one: lotics scaffold docs");
         process.exit(1);
@@ -107447,13 +108248,30 @@ async function main() {
       if (flags.json) setMachineOutput(true);
       const checked = await checkModelFile(toolArgs);
       if (checked.kind === "error") {
+        noteScope({ plan_findings: checked.findings.length });
         if (subcommand === "check" && flags.json) emitJson({ ok: false, findings: checked.findings });
         else reportModelFindings(toolArgs, checked.findings);
         process.exit(1);
       }
+      const counts = countModel(checked.model);
+      noteScope({ plan_screens: counts.screens, plan_custom: counts.custom, plan_findings: 0 });
       if (subcommand === "check") {
-        if (flags.json) emitJson({ ok: true, ...countModel(checked.model) });
-        else console.log(summarizeModel(checked.model));
+        const coverage = describeCoverage(checked.model);
+        if (flags.json) {
+          emitJson({
+            ok: true,
+            ...countModel(checked.model),
+            plan: planJson(checked.model),
+            coverage: roleCoverage(checked.model.contract, checked.model.field_roles, checked.model.rows)
+          });
+        } else {
+          console.log(summarizeModel(checked.model));
+          for (const line of describePlan(checked.model)) console.log(line);
+          if (coverage.length > 0) {
+            console.log("What the rows would show:");
+            for (const line of coverage) console.log(line);
+          }
+        }
         return;
       }
       const { client: client2, ctx: ctx2 } = await requireClient(flags);
@@ -107774,7 +108592,7 @@ async function main() {
   if (command === "preview") {
     if (subcommand && isStoredFileId(subcommand)) {
       const { client: client2 } = await requireClient(flags);
-      const tmpDir = fs15.mkdtempSync(path12.join(os4.tmpdir(), "lotics-preview-"));
+      const tmpDir = fs15.mkdtempSync(path13.join(os4.tmpdir(), "lotics-preview-"));
       try {
         const { path: localPath, filename } = await client2.downloadFileById(subcommand, tmpDir);
         const output = flags.output ?? defaultPreviewOutputPath(filename, process.cwd());
@@ -108150,7 +108968,7 @@ Available workspaces:`);
       return;
     }
     if (subcommand === "check") {
-      await appCheck(client, {});
+      await appCheck(client, { screens: flags.screens });
       return;
     }
     if (subcommand === "workflow") {