@lotics/cli 0.190.0 → 0.191.1

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];
@@ -39864,15 +39864,15 @@ var require_deflate = __commonJS({
       if (!strm) {
         return Z_STREAM_ERROR;
       }
-      var wrap = 1;
+      var wrap2 = 1;
       if (level === Z_DEFAULT_COMPRESSION) {
         level = 6;
       }
       if (windowBits < 0) {
-        wrap = 0;
+        wrap2 = 0;
         windowBits = -windowBits;
       } else if (windowBits > 15) {
-        wrap = 2;
+        wrap2 = 2;
         windowBits -= 16;
       }
       if (memLevel < 1 || memLevel > MAX_MEM_LEVEL || method !== Z_DEFLATED || windowBits < 8 || windowBits > 15 || level < 0 || level > 9 || strategy < 0 || strategy > Z_FIXED) {
@@ -39884,7 +39884,7 @@ var require_deflate = __commonJS({
       var s = new DeflateState();
       strm.state = s;
       s.strm = strm;
-      s.wrap = wrap;
+      s.wrap = wrap2;
       s.gzhead = null;
       s.w_bits = windowBits;
       s.w_size = 1 << s.w_bits;
@@ -40177,7 +40177,7 @@ var require_deflate = __commonJS({
       var dictLength = dictionary.length;
       var s;
       var str, n;
-      var wrap;
+      var wrap2;
       var avail;
       var next;
       var input;
@@ -40186,16 +40186,16 @@ var require_deflate = __commonJS({
         return Z_STREAM_ERROR;
       }
       s = strm.state;
-      wrap = s.wrap;
-      if (wrap === 2 || wrap === 1 && s.status !== INIT_STATE || s.lookahead) {
+      wrap2 = s.wrap;
+      if (wrap2 === 2 || wrap2 === 1 && s.status !== INIT_STATE || s.lookahead) {
         return Z_STREAM_ERROR;
       }
-      if (wrap === 1) {
+      if (wrap2 === 1) {
         strm.adler = adler32(strm.adler, dictionary, dictLength, 0);
       }
       s.wrap = 0;
       if (dictLength >= s.w_size) {
-        if (wrap === 0) {
+        if (wrap2 === 0) {
           zero(s.head);
           s.strstart = 0;
           s.block_start = 0;
@@ -40235,7 +40235,7 @@ var require_deflate = __commonJS({
       strm.next_in = next;
       strm.input = input;
       strm.avail_in = avail;
-      s.wrap = wrap;
+      s.wrap = wrap2;
       return Z_OK;
     }
     exports2.deflateInit = deflateInit;
@@ -41255,17 +41255,17 @@ var require_inflate = __commonJS({
       return inflateResetKeep(strm);
     }
     function inflateReset2(strm, windowBits) {
-      var wrap;
+      var wrap2;
       var state;
       if (!strm || !strm.state) {
         return Z_STREAM_ERROR;
       }
       state = strm.state;
       if (windowBits < 0) {
-        wrap = 0;
+        wrap2 = 0;
         windowBits = -windowBits;
       } else {
-        wrap = (windowBits >> 4) + 1;
+        wrap2 = (windowBits >> 4) + 1;
         if (windowBits < 48) {
           windowBits &= 15;
         }
@@ -41276,7 +41276,7 @@ var require_inflate = __commonJS({
       if (state.window !== null && state.wbits !== windowBits) {
         state.window = null;
       }
-      state.wrap = wrap;
+      state.wrap = wrap2;
       state.wbits = windowBits;
       return inflateReset(strm);
     }
@@ -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.1";
 
 // src/timezone.ts
 function machineTimezone() {
@@ -46110,6 +46110,167 @@ function matchDocArea(areas, query) {
   if (exact.length > 0) return exact;
   return areas.filter((a) => a.area.toLowerCase().includes(q));
 }
+var PAGE_BYTES = 16e3;
+var NAV_BYTES = PAGE_BYTES / 2;
+var CUT_MARK = "\n[cut \u2014 the whole document is at the path above]";
+var slugOf = (title) => title.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+function docSections(text) {
+  const lines = text.split("\n");
+  const found = [];
+  let fenced = false;
+  lines.forEach((line, index) => {
+    if (line.startsWith("```")) {
+      fenced = !fenced;
+      return;
+    }
+    if (fenced) return;
+    const m = /^(#{1,6})\s+(.+?)\s*$/.exec(line);
+    if (m === null) return;
+    const level = m[1].length;
+    for (const open of found) {
+      if (open.end === lines.length && open.level >= level) open.end = index;
+    }
+    found.push({ level, title: m[2], slug: slugOf(m[2]), line: index, end: lines.length });
+  });
+  return found;
+}
+function docRows(text) {
+  const found = [];
+  let fenced = false;
+  let header = true;
+  text.split("\n").forEach((line, index) => {
+    if (line.startsWith("```")) {
+      fenced = !fenced;
+      return;
+    }
+    if (fenced) return;
+    if (!line.startsWith("|")) {
+      header = true;
+      return;
+    }
+    const cells = line.split("|");
+    if (cells.length < 3) return;
+    const first3 = cells[1].trim();
+    if (/^:?-{2,}:?$/.test(first3)) return;
+    if (header) {
+      header = false;
+      return;
+    }
+    const key = first3.replace(/[`*[\]]/g, "").trim();
+    if (key === "") return;
+    found.push({ key, slug: slugOf(key), line: index });
+  });
+  return found;
+}
+var byteLength = (s) => Buffer.byteLength(s, "utf-8");
+var oneNewline = (s) => `${s.replace(/\n+$/, "")}
+`;
+var wrap = (names, width = 92) => names.reduce((out, name2) => {
+  const last3 = out[out.length - 1];
+  if (last3 !== void 0 && last3.length + name2.length + 1 <= width) {
+    out[out.length - 1] = `${last3} ${name2}`;
+    return out;
+  }
+  return [...out, `    ${name2}`];
+}, []);
+var fit = (lines, budget) => {
+  const kept = [];
+  let used = 0;
+  for (const line of lines) {
+    const cost = byteLength(line) + 1;
+    if (used + cost > budget) break;
+    kept.push(line);
+    used += cost;
+  }
+  return { kept, dropped: lines.length - kept.length };
+};
+var childrenOf = (sections, parent) => {
+  const within = parent === void 0 ? sections : sections.filter((s) => s.line > parent.line && s.line < parent.end);
+  if (within.length === 0) return [];
+  const top = Math.min(...within.map((s) => s.level));
+  return within.filter((s) => s.level === top);
+};
+var linesOf = (lines, section) => section === void 0 ? lines : lines.slice(section.line, section.end);
+var tableTop = (lines, rowLine) => {
+  for (let i2 = rowLine; i2 > 0; i2--) {
+    if (!lines[i2].startsWith("|")) return i2 + 1;
+  }
+  return 0;
+};
+var tableHeader = (lines, rowLine) => {
+  for (let i2 = rowLine; i2 > 0; i2--) {
+    if (/^\|\s*:?-{2,}/.test(lines[i2])) return i2 > 0 ? [lines[i2 - 1], lines[i2]] : [];
+    if (!lines[i2].startsWith("|")) return [];
+  }
+  return [];
+};
+function renderDocPage(text, args) {
+  const lines = text.split("\n");
+  const sections = docSections(text);
+  const rows = docRows(text);
+  const address = (slug) => `  lotics docs ${args.address}/${slug}`;
+  const navFor = (parent2) => {
+    const children2 = childrenOf(sections, parent2);
+    if (children2.length > 0) {
+      return children2.map(
+        (s) => `${address(s.slug)}   (${byteLength(linesOf(lines, s).join("\n"))} bytes)`
+      );
+    }
+    const within = parent2 === void 0 ? rows : rows.filter((r) => r.line > parent2.line && r.line < parent2.end);
+    if (within.length === 0) return [];
+    return [`  lotics docs ${args.address}/<name>, where <name> is one of:`, "", ...wrap(within.map((r) => r.slug))];
+  };
+  const titled = sections.length > 0 && sections[0].level === 1 ? sections[0] : void 0;
+  const listed = (nav2) => {
+    const shown = fit(nav2, NAV_BYTES);
+    return [...shown.kept, ...shown.dropped > 0 ? [`  \u2026 and ${shown.dropped} more`] : []].join(
+      "\n"
+    );
+  };
+  let current;
+  if (args.section !== void 0 && args.section !== "") {
+    const q = slugOf(args.section);
+    const pick4 = (all) => {
+      const exact = all.filter((s) => s.slug === q);
+      return exact.length > 0 ? exact : all.filter((s) => s.slug.startsWith(q));
+    };
+    const hitSections = pick4(sections.filter((s) => s.level > 1));
+    const hitRows = hitSections.length > 0 ? [] : pick4(rows);
+    if (hitSections.length + hitRows.length !== 1) {
+      const ambiguous = [...hitSections.map((s) => s.slug), ...hitRows.map((r) => r.slug)];
+      const list2 = listed(ambiguous.length > 1 ? ambiguous.map(address) : navFor(titled));
+      return {
+        error: ambiguous.length > 1 ? `"${args.section}" names more than one part of ${args.address}:
+${list2}` : `No "${args.section}" in ${args.address}. It holds:
+${list2}`
+      };
+    }
+    const row = hitRows[0];
+    if (row !== void 0) {
+      return { text: oneNewline([...tableHeader(lines, row.line), lines[row.line]].join("\n")) };
+    }
+    current = hitSections[0];
+  }
+  const whole = linesOf(lines, current).join("\n");
+  if (byteLength(whole) <= PAGE_BYTES) return { text: oneNewline(whole) };
+  const parent = current ?? titled;
+  const nav = navFor(parent);
+  const navText = nav.length === 0 ? "" : `
+
+This is ${byteLength(whole)} bytes; one page is ${PAGE_BYTES}. It holds:
+
+${listed(nav)}`;
+  const children = childrenOf(sections, parent);
+  const rowsWithin = parent === void 0 ? rows : rows.filter((r) => r.line > parent.line && r.line < parent.end);
+  const openingTo = children.length > 0 ? children[0].line : rowsWithin.length > 0 ? tableTop(lines, rowsWithin[0].line) : current?.end ?? lines.length;
+  const head = fit(
+    lines.slice(current?.line ?? 0, openingTo),
+    PAGE_BYTES - byteLength(navText) - byteLength(CUT_MARK) - 1
+  );
+  return {
+    text: oneNewline(`${head.kept.join("\n")}${head.dropped > 0 ? CUT_MARK : ""}${navText}`)
+  };
+}
 function onlySelfReference(areas) {
   return areas.length > 0 && areas.every((a) => a.pkg === "@lotics/cli");
 }
@@ -46129,6 +46290,7 @@ ${a.pkg}  ${a.version}`);
     lines.push(`  ${name2.length >= 24 ? `${name2}  ` : name2.padEnd(24)}${a.title}`);
   }
   lines.push("\n  lotics docs <area>            print one, e.g. `lotics docs ai`");
+  lines.push("  lotics docs <area>/<section>  one section \u2014 a long doc prints its section list");
   lines.push("  lotics docs <pkg>/<area>      when two packages share a name");
   lines.push("\n  Versions are the INSTALLED ones; a doc describes the version beside it.");
   if (onlySelfReference(areas)) {
@@ -46145,7 +46307,17 @@ function docsCommand(args) {
     console.log(renderDocIndex(areas));
     return;
   }
-  const hits = matchDocArea(areas, args.area);
+  const asked = args.area.trim();
+  let hits = matchDocArea(areas, asked);
+  let section;
+  if (hits.length === 0 && asked.includes("/")) {
+    const cut = asked.lastIndexOf("/");
+    const head = matchDocArea(areas, asked.slice(0, cut));
+    if (head.length > 0) {
+      hits = head;
+      section = asked.slice(cut + 1);
+    }
+  }
   if (hits.length === 0) {
     console.error(
       `No reference area matching "${args.area}".
@@ -46156,14 +46328,22 @@ function docsCommand(args) {
   if (hits.length > 1) {
     console.error(
       `"${args.area}" matches more than one reference \u2014 name the package:
-` + hits.map((a) => `  \u2022 lotics docs ${qualified(a)}   (${a.pkg} ${a.version})`).join("\n")
+` + hits.map(
+        (a) => `  \u2022 lotics docs ${qualified(a)}${section === void 0 ? "" : `/${section}`}   (${a.pkg} ${a.version})`
+      ).join("\n")
     );
     process.exit(1);
   }
   const hit = hits[0];
+  const address = areas.filter((a) => a.area === hit.area).length > 1 ? qualified(hit) : hit.area;
+  const page = renderDocPage(fs5.readFileSync(hit.absPath, "utf-8"), { address, section });
+  if ("error" in page) {
+    console.error(page.error);
+    process.exit(1);
+  }
   console.error(`${hit.pkg} ${hit.version} \xB7 ${path5.relative(projectDir, hit.absPath)}
 `);
-  process.stdout.write(fs5.readFileSync(hit.absPath, "utf-8"));
+  process.stdout.write(page.text);
 }
 
 // src/commands.ts
@@ -46201,9 +46381,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:",
@@ -46294,7 +46475,8 @@ var COMMANDS = [
     verbs: ["docs"],
     help: [
       "  lotics docs                          List the reference docs the npm packages in node_modules ship",
-      "  lotics docs <area>                   Print one (e.g. 'lotics docs ai')"
+      "  lotics docs <area>                   Print one, capped at a page (e.g. 'lotics docs ai')",
+      "  lotics docs <area>/<section>         One section, or one row of a table doc"
     ]
   },
   {
@@ -46350,7 +46532,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 +46542,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 +46622,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,12 +46815,11 @@ 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";
 var VITEST_SETUP_FILENAME = "vitest.setup.ts";
 var VITEST_SETUP_CONTENT = `// Runs before every test file (wired by vite.config.ts \`test.setupFiles\`).
 // Empty by default \u2014 put global test setup here: custom matchers, a fetch stub,
@@ -46669,7 +46855,7 @@ function buildStarterTemplate(args) {
             // or a broken vitest config, indefinitely. A detector that cannot
             // fire when the thing is ABSENT rather than excessive is not one.
             //
-            // What the scaffold seeds instead is `src/harness.test.ts`, which
+            // What the scaffold seeds instead is `src/harness.test.tsx`, which
             // asserts the HARNESS and nothing else. The file it replaces
             // (`src/App.test.tsx`) asserted the scaffold's placeholder copy
             // ("First item"), so it failed the moment the author did the very
@@ -46687,15 +46873,14 @@ function buildStarterTemplate(args) {
             // that IMPORTS @lotics/docx or @lotics/xlsx directly (its own doc/excel
             // builders) declares its own dependency then.
             "@lotics/ui": uiVersion,
-            "@react-native-picker/picker": "^2.7.0",
-            "expo-image": "~3.0.9",
+            // @base-ui/react is deliberately absent: @lotics/ui declares it as an
+            // EXACT peer, npm installs a peer, and a second declaration here is a
+            // version that drifts from the kit's — which Base UI punishes
+            // silently, since it passes state through React context and a nested
+            // copy renders parts that never open.
             "lucide-react": "^0.562.0",
-            "lucide-react-native": "^0.562.0",
             react: "^19.0.0",
             "react-dom": "^19.0.0",
-            "react-native": STARTER_REACT_NATIVE_VERSION,
-            "react-native-svg": "^15.0.0",
-            "react-native-web": "^0.21.0",
             // In-app routing for the scaffolded list→detail example. The app owns
             // its routing; the SDK's `isEmbedded()` picks memory vs browser history. `react-router` is the
             // canonical package (react-router-dom is a shim over it).
@@ -46744,9 +46929,10 @@ function buildStarterTemplate(args) {
             strict: true,
             noFallthroughCasesInSwitch: true
           },
-          // Restrict tsc to the project's own sources. tsgo follows
-          // transitive imports into node_modules — strict rules
-          // (noUnusedLocals etc.) would fire on @lotics/ui's source.
+          // Restrict tsc to the project's own sources — a `noEmit` program has
+          // no reason to walk anything else, and under the `LOTICS_UI_SRC`
+          // dev-link `@lotics/ui` resolves to a working copy of the kit's own
+          // .tsx, which strict rules (noUnusedLocals etc.) would then fire on.
           // `.lotics/**/*` (not bare `.lotics`): TypeScript's include glob walk
           // SKIPS dot-directories, so a bare `.lotics` silently loads zero of the
           // generated `.d.ts` augmentations and typed useWorkflow/useQuery/useAgentRun
@@ -46774,87 +46960,25 @@ function buildStarterTemplate(args) {
       path: "vite.config.ts",
       content: `/// <reference types="vitest" />
 import { defineConfig } from "vite";
-import type { Plugin } from "vite";
 import react from "@vitejs/plugin-react";
-import { loticsOptimizeDeps, loticsOptimizeExclude, loticsResolve } from "@lotics/ui/vite";
-
-// @lotics/ui/icon.tsx deep-imports \`lucide-react-native/dist/esm/icons/<name>\`.
-// lucide-react-native's \`exports\` map lists only "." and "./icons", so a strict
-// resolver (the sandbox's vite dev optimizer) blocks the deep path with
-// \`Missing "./dist/esm/icons/<name>" specifier\`. lucide-react ships the same
-// per-icon files with NO exports map, so redirect there. A \`resolveId\` PLUGIN
-// (not \`resolve.alias\`) is required: the dep-optimizer SCAN runs plugin
-// resolveId hooks but does NOT apply regex \`resolve.alias\`, so the alias alone
-// fixes the production build but leaves the dev preview broken.
-function lucideIconsWebAlias(): Plugin {
-  return {
-    name: "lucide-icons-web-alias",
-    enforce: "pre",
-    async resolveId(source, importer, options) {
-      const m = /^lucide-react-native\\/dist\\/esm\\/icons\\/(.+)$/.exec(source);
-      if (!m) return null;
-      return this.resolve(\`lucide-react/dist/esm/icons/\${m[1]}\`, importer, {
-        ...options,
-        skipSelf: true,
-      });
-    },
-  };
-}
+import { loticsResolve } from "@lotics/ui/vite";
 
 // Vite default base (/) emits absolute asset URLs in index.html. Lotics's
 // render endpoint rewrites those to /v1/apps/{id}/asset/... so the bundle
 // loads via the platform's asset proxy. Don't change \`base\` unless you
 // also adjust the rewrite logic in backend/api/apps.ts:rewriteAssetPaths.
 export default defineConfig({
-  plugins: [lucideIconsWebAlias(), react()],
-  // RN libraries reference globals Metro injects but Vite does not \u2014 undefined
-  // \u21D2 the bundle throws. \`__DEV__\` (react-native-web, @react-native-picker's
-  // UnimplementedView): throws at load, blank iframe. \`global\` (rn-web
-  // Animated's \`global.cancelAnimationFrame\`): throws when a spring animation is
-  // interrupted/torn down \u2014 e.g. toggling @lotics/ui's Switch. rollup hits it;
-  // the dev esbuild path masks it, so it only surfaces in the deployed app.
-  // rn-web only reads \`global.x\` as a free var, so mapping it to \`globalThis\`
-  // is safe. Define both so dev and the deployed build behave identically.
-  define: { __DEV__: "false", global: "globalThis" },
-  // The kit owns its own resolution \u2014 the react-native \u2192 react-native-web alias,
-  // \`.web.tsx\`-first extensions, the React dedupe, and the \`LOTICS_UI_SRC\`
-  // dev-link \u2014 for the same reason it owns \`loticsOptimizeDeps\`: every entry is
-  // dictated by @lotics/ui's internals, so shipping it WITH the kit means it can
-  // never drift from the version installed here. It also stops being an app's job
-  // to hand-carry a load-bearing alias that a regex edit twice deleted (GAP-133/142).
+  plugins: [react()],
+  // The kit owns this block: the \`LOTICS_UI_SRC\` dev-link and the React dedupe
+  // are decided by @lotics/ui's own delivery, so shipping it WITH the kit means
+  // it can never drift from the version installed here \u2014 and it stops being an
+  // app's job to hand-carry a line a regex edit twice deleted (GAP-133/142).
   // \`lotics app codegen\` writes the matching \`paths\` into
-  // .lotics/tsconfig.link.json, so tsc/vitest/eslint/your editor resolve the same
-  // @lotics/ui this does. To add your own alias, spread it:
+  // .lotics/tsconfig.link.json, so tsc/vitest/eslint/your editor resolve the
+  // same @lotics/ui this does. To add your own alias, spread it:
   //   const base = loticsResolve();
   //   resolve: { ...base, alias: [...base.alias, { find: "x", replacement: "y" }] }
   resolve: loticsResolve(),
-  optimizeDeps: {
-    // The dev dep-optimizer must pre-bundle @lotics/ui's RN-ecosystem + markdown
-    // CJS-interop deps or \`lotics app dev\` blanks the iframe ("does not provide an
-    // export named 'default'/'parse'"). Dev-ONLY: the prod rollup build resolves the
-    // interop without it, so typecheck/lint/build stay green while the dev iframe
-    // goes blank. The canonical list ships WITH @lotics/ui as \`loticsOptimizeDeps\`
-    // (imported above) so it can never drift from what the kit's transitive deps
-    // require across a major bump \u2014 the per-family rationale lives in that module.
-    // To add app-specific entries, spread: include: [...loticsOptimizeDeps, "my-dep"].
-    include: loticsOptimizeDeps,
-    // The kit is ONE module graph, so it must never be pre-bundled: the optimizer
-    // auto-discovers each @lotics/ui subpath and inlines a private copy of every
-    // context-owning module it reaches (locale, tooltip, portal, popover), leaving
-    // the provider filling one context and the component reading another.
-    exclude: loticsOptimizeExclude,
-    // The dep optimizer pre-bundles deps with a SEPARATE esbuild pass that
-    // top-level \`define\` doesn't always reach, so a pre-bundled RN dep can
-    // still hit \`__DEV__ is not defined\` under \`lotics app dev\`. Define it
-    // here too \u2014 belt-and-suspenders with the top-level \`define\` above.
-    // The optimizer pre-bundles with a SEPARATE esbuild resolver that ignores
-    // \`resolve.extensions\`, so \`.web.js\` must be repeated here or a pre-bundled
-    // RN dep still resolves \`./Picker\` to the native build.
-    esbuildOptions: {
-      define: { __DEV__: "false", global: "globalThis" },
-      resolveExtensions: [".web.tsx", ".web.ts", ".web.js", ".tsx", ".ts", ".jsx", ".js", ".json", ".mjs", ".mts"],
-    },
-  },
   build: {
     outDir: "dist",
     // No source maps in the production build: they ship the original source
@@ -46880,11 +47004,6 @@ export default defineConfig({
     // cross-site WS hijack fix) \u2014 without this entry the proxied preview page
     // loads over HTTP but HMR never connects, so edits stop live-updating.
     allowedHosts: [".lotics-sandbox.app"],
-    // @lotics/ui/fonts.css references the API's /iframe/fonts/*.woff2 files
-    // by root-relative URL. A deployed app is served from the API origin so
-    // they resolve directly; under \`lotics app dev\` the app runs on
-    // localhost, so proxy /iframe to the API to load the real fonts.
-    proxy: { "/iframe": { target: "https://api.lotics.ai", changeOrigin: true } },
   },
   test: {
     environment: "jsdom",
@@ -46893,39 +47012,31 @@ export default defineConfig({
     // EXIST either way: setupFiles naming a missing file makes vitest fail to
     // load every test. See vitest.setup.ts.
     setupFiles: ["./${VITEST_SETUP_FILENAME}"],
-    // RN packages ship Flow (\`import typeof\`) in their native source, reached
-    // transitively by RN-Web components (pickers, calendars, anything touching
-    // Animated). Vitest's web optimizer is OFF by default and ignores the
-    // \`optimizeDeps.resolveExtensions\` above, so it pre-bundles the native
-    // \`.js\` / \`src\` Flow files and esbuild can't parse them. Enable it with the
-    // same \`.web.js\`-first resolution so it bundles the compiled web variants
-    // (Picker.web.js, RN-Web dist) \u2014 without this, any test that renders a tree
-    // pulling a Picker / DatePicker fails with "Unexpected token 'typeof'".
+    // @lotics/ui ships built ESM whose every component module carries the
+    // literal \`import "./button.css"\` that delivers its sheet. Vitest hands
+    // node_modules to Node's ESM loader, which has no loader for \`.css\` \u2014 so
+    // without this line EVERY suite that touches a kit component fails to load
+    // with \`Unknown file extension ".css"\`, before a single assertion runs.
+    // Inlining routes those modules through Vite's transform instead, where a
+    // CSS import is inert under jsdom. Any package whose modules import CSS
+    // needs the same entry.
+    server: { deps: { inline: [/@lotics\\/ui/] } },
     deps: {
       optimizer: {
         web: {
           enabled: true,
-          // react + react-dom + the @testing-library renderer must ride in the
-          // SAME optimized chunk as react-native-web, so a rendered tree and the
-          // renderer share ONE react instance. Without this, a test that renders a
-          // non-trivial App tree hits a null hooks dispatcher ("Cannot read
-          // properties of null (reading 'useState')") the moment it mounts.
+          // Everything here ships COMPILED JS, so vitest pre-bundles each into
+          // its own chunk \u2014 and a chunk carrying its own react import splits the
+          // instance and nulls the hooks dispatcher the moment a rendered tree
+          // calls one ("Cannot read properties of null (reading 'useState')").
+          // They ride in ONE optimized chunk with react and the renderer instead.
           include: [
             "react",
             "react-dom",
             "react-dom/client",
             "react-dom/test-utils",
-            "react-native",
-            "react-native-web",
-            "react-native-svg",
-            "@react-native-picker/picker",
             "@testing-library/react",
             "@testing-library/dom",
-            // @lotics/app-sdk ships compiled dist/ JS (unlike @lotics/ui, which
-            // ships source vitest transforms inline) \u2014 pre-bundled into its own
-            // chunk, its react import splits from the shared instance and nulls
-            // the hooks dispatcher the instant a hook (useAgentRun / useQuery)
-            // runs in a rendered App tree.
             "@lotics/app-sdk",
             // The /router subpath is a SEPARATE optimizer entry \u2014 without it,
             // AppRouter's BrowserRouter bundles apart from the app's
@@ -46937,9 +47048,6 @@ export default defineConfig({
             // ("Invalid hook call") when a test renders the routed App tree.
             "react-router",
           ],
-          esbuildOptions: {
-            resolveExtensions: [".web.tsx", ".web.ts", ".web.js", ".tsx", ".ts", ".jsx", ".js", ".json", ".mjs", ".mts"],
-          },
         },
       },
     },
@@ -46963,8 +47071,8 @@ export default defineConfig({
        * default of html/body being content-sized collapses every \`flex: 1\`
        * to 0 and the surface shrinks to fit only its rendered content.
        *
-       * Also: #root is made a flex column so the outermost RN \`<View flex:1>\`
-       * inside App.tsx claims the full iframe height.
+       * Also: #root is a flex column, so App.tsx's outermost \`flex: 1\` box
+       * claims the full iframe height.
        */
       html, body, #root { height: 100%; margin: 0; }
       #root { display: flex; flex-direction: column; }
@@ -46979,45 +47087,47 @@ export default defineConfig({
     },
     {
       path: "src/main.tsx",
-      content: `import "@lotics/ui/index.css";
+      content: `import "@lotics/ui/styles.css";
 import "@lotics/ui/fonts.css";
-import { PortalHost } from "@lotics/ui/portal";
 import { LoticsLocaleProvider, vi } from "@lotics/ui/locale";
 import { mount } from "@lotics/app-sdk";
 import App from "./App";
 
+// \`styles.css\` is not optional. It carries the cascade-layer order, every design
+// token and the reset, and the kit's chrome reads those variables with NO inline
+// fallback \u2014 without it every colour, size and radius is invalid and the screen
+// renders unstyled but working.
+//
 // THIS APP LOOKS LIKE LOTICS unless you say otherwise, which is the right
 // default: the kit's own palette and typeface are what every screen in the
 // product wears, and an app that sets nothing belongs with them.
 //
-// If this app carries someone else's brand \u2014 a customer's typeface, their one
-// colour \u2014 \`applyLoticsTheme\` is the escape hatch. Call it ONCE, here, before
-// \`mount\`, so the variables are in place for the first paint:
-//
-//   import { applyLoticsTheme } from "@lotics/ui/theme";
-//   applyLoticsTheme({ primary: "#0F766E" });
+// If this app carries someone else's brand, a theme is a STYLESHEET \u2014 there is
+// no theme function. Declare the shadcn/ui variables in your own CSS, imported
+// after \`styles.css\`; an unlayered rule of yours beats every layered kit rule at
+// any specificity, with no \`!important\`:
 //
-// It is ADDITIVE \u2014 set what you own and every other role keeps the kit's value,
-// rather than resetting to some second set of defaults:
+//   :root, .light { --primary: #0F766E; --primary-foreground: #fff; --ring: #0F766E; }
+//   .dark         { --primary: #5EEAD4; --primary-foreground: #042F2E; --ring: #5EEAD4; }
 //
-//   accent      which of these \u2014 a selected row, an active filter
-//   primary     this is on \u2014 the filled button, a checkbox, an active tab's rail
-//   background  the raised surface (Card, Drawer, Modal); leave white unless you
-//               deliberately want a toned surface
-//   border      hairlines \u2014 a register is mostly these, so a small change here is
-//               felt against the whole screen
-//   bodyFont    the typeface for everything (a CSS stack you know RESOLVES, and
-//               that carries Vietnamese diacritics \u2014 a face without them turns
-//               "Th\u1EA9m \u0111\u1ECBnh" into tofu). Declare its @font-face in your own CSS.
-//   displayFont display type only; defaults to bodyFont
+// Paste BOTH blocks of whatever palette you start from: a token set only on
+// \`:root\` keeps its light value in dark mode, because your unlayered rule also
+// beats the kit's \`.dark\`. The roles worth knowing:
 //
-// Prefer it over declaring \`--lotics-*\` in your own stylesheet: two of those
-// values are DERIVED and fail quietly by hand \u2014 the selection wash is the accent
-// at 7%, and one bodyFont has to reach all three weight rungs or medium and
-// semibold stay in the kit's face and the screen reads as a font that half-loaded.
+//   --primary            this is on \u2014 the filled button, a checkbox, an active tab's rail
+//   --lotics-accent      which of these \u2014 a selected row, an active filter (themed: set
+//                        it in both blocks, beside --primary)
+//   --card               the raised surface (Card, Drawer, Dialog)
+//   --border             hairlines \u2014 a register is mostly these, so a small change
+//                        here is felt against the whole screen
+//   --font-sans          the typeface for everything (a stack you know RESOLVES, and that
+//                        carries Vietnamese diacritics \u2014 a face without them turns
+//                        "Th\u1EA9m \u0111\u1ECBnh" into tofu). Declare its @font-face in your own CSS.
+//   --lotics-font-display  display type only; defaults to --font-sans
 //
-// PortalHost is the render target for @lotics/ui overlays (Popover, Tooltip,
-// Dialog). Without it, Portal renders nothing \u2014 keep it wrapping the app.
+// Everything derived \u2014 the selection wash, hover and press shades, the hairline
+// ladder \u2014 is computed in CSS from those, so there is nothing to keep in step by
+// hand. The full contract is \`node_modules/@lotics/ui/docs/theming.md\`.
 //
 // LoticsLocaleProvider supplies the kit's own strings (Pagination, sort
 // headers, select-all, the Drawer's record nav\u2026) in one language \u2014 Vietnamese
@@ -47025,9 +47135,7 @@ import App from "./App";
 // LoticsLocale pack) for another language; remove it to fall back to English.
 mount(
   <LoticsLocaleProvider locale={vi}>
-    <PortalHost>
-      <App />
-    </PortalHost>
+    <App />
   </LoticsLocaleProvider>,
 );
 `
@@ -47041,21 +47149,22 @@ mount(
       //     host never sees it, so navigation never reloads the app); standalone,
       //     real path URLs. Browser Back/Forward walk app screens in both.
       //   - The full-container layout pattern is preserved in `Screen`: an outer
-      //     <View flex:1> claims the iframe height (index.html sets
-      //     html/body/#root to 100% + #root is a flex column). Keep that chain
-      //     plain — @lotics/ui/stack wraps children in an unstyled <View> that
-      //     breaks `flex: 1` propagation to a fill-remaining-space child.
+      //     `flex: 1` box claims the iframe height (index.html sets
+      //     html/body/#root to 100% + #root is a flex column). It is a plain
+      //     `<div>` rather than a kit primitive because that chain has to stay
+      //     unbroken — `Stack` is the right thing INSIDE it, where the gutter is
+      //     what you want, not around a fill-remaining-space child.
       // A single-screen app can delete the router and render one Screen directly.
       content: `import type { ReactNode } from "react";
-import { View } from "react-native";
 import { useNavigate, useParams } from "react-router";
 import { AppRouter } from "@lotics/app-sdk/router";
 import { useAiContext } from "@lotics/app-sdk";
 import { Card } from "@lotics/ui/card";
+import { Stack } from "@lotics/ui/stack";
 import { Text } from "@lotics/ui/text";
 import { Button } from "@lotics/ui/button";
 import { BackButton } from "@lotics/ui/back_button";
-import { EmptyState } from "@lotics/ui/empty_state";
+import { RegionState } from "@lotics/ui/region_state";
 
 // AppRouter makes the app's screens real URLs \u2014 write plain react-router
 // (useNavigate / useParams / <Link>) and it handles both modes. The app owns its
@@ -47072,14 +47181,16 @@ const ITEMS = [
   { id: "3", name: "Third item" },
 ];
 
-// Outer <View flex:1> claims the full iframe height \u2014 works because index.html
-// sets html/body/#root to 100% and #root is a flex column. Keep this flex chain
-// plain (not @lotics/ui/stack) so a fill-remaining-space child can claim height.
+// The outer box claims the full iframe height \u2014 it works because index.html sets
+// html/body/#root to 100% and #root is a flex column. Keep this chain plain: a
+// box that says nothing about \`flex\` is what breaks it.
 function Screen({ children }: { children: ReactNode }) {
   return (
-    <View style={{ flex: 1, padding: 24, alignItems: "center" }}>
-      <View style={{ maxWidth: 640, width: "100%", gap: 16 }}>{children}</View>
-    </View>
+    <div style={{ flex: 1, padding: 24, display: "flex", justifyContent: "center" }}>
+      <Stack gap={16} style={{ maxWidth: 640, width: "100%" }}>
+        {children}
+      </Stack>
+    </div>
   );
 }
 
@@ -47095,18 +47206,16 @@ function ListScreen() {
       </Text>
       {ITEMS.map((item) => (
         <Card key={item.id}>
-          <View
-            style={{
-              padding: 16,
-              flexDirection: "row",
-              alignItems: "center",
-              justifyContent: "space-between",
-              gap: 12,
-            }}
+          <Stack
+            direction="row"
+            gap={8}
+            align="center"
+            justify="between"
+            style={{ padding: 16 }}
           >
             <Text weight="medium">{item.name}</Text>
             <Button title="Open" color="primary" onPress={() => navigate("/item/" + item.id)} />
-          </View>
+          </Stack>
         </Card>
       ))}
     </Screen>
@@ -47140,20 +47249,20 @@ function ItemDetailScreen() {
           \`<Button title="Back">\` with no \`color\` draws NOTHING at rest \u2014 no
           ground, no border, no underline \u2014 so its only affordance is a hover
           wash, which touch and keyboard never see. BackButton also carries its
-          own \`alignSelf\`, so it needs no wrapping View to sit left. */}
+          own \`alignSelf\`, so it needs no wrapping box to sit left. */}
       <BackButton onPress={() => navigate(-1)} />
       <Text size="xl" weight="semibold">{item ? item.name : "Not found"}</Text>
       {/* Every state gets its own content. Swapping only the TITLE left the card
           below still describing the record the title had just said was missing. */}
       {item ? (
         <Card>
-          <View style={{ padding: 16, gap: 8 }}>
+          <Stack gap={4} style={{ padding: 16 }}>
             <Text>Detail for item {id}.</Text>
             <Text color="muted">Reached via in-app navigation, not a host route.</Text>
-          </View>
+          </Stack>
         </Card>
       ) : (
-        <EmptyState message={"No item with id " + id + "."} />
+        <RegionState state="empty" message={"No item with id " + id + "."} />
       )}
     </Screen>
   );
@@ -47224,25 +47333,6 @@ alias the binding is keyed by).
 capabilities only. \`apps.workflows\` has exactly one author: \`set_app_workflow\`
 (which \`lotics app workflow set\` calls). The typed \`inputs\`/\`outputs\` schema for
 each alias lives in \`package.json#lotics.workflows.<alias>\`.
-`
-    },
-    {
-      path: "src/lucide-react-native.d.ts",
-      content: `// Type shim for lucide-react-native's deep-icon imports
-// (\`lucide-react-native/dist/esm/icons/<name>\`). The package ships JS-only
-// files without per-file .d.ts. The lucideIconsWebAlias() plugin in
-// vite.config.ts redirects these to lucide-react at resolve time; this
-// declaration covers the TypeScript compile-time gap.
-declare module "lucide-react-native/dist/esm/icons/*" {
-  import type { ComponentType } from "react";
-  const Icon: ComponentType<{
-    size: number;
-    color: string;
-    fill?: string;
-    strokeWidth?: number;
-  }>;
-  export default Icon;
-}
 `
     },
     {
@@ -47252,13 +47342,16 @@ declare module "lucide-react-native/dist/esm/icons/*" {
   export default classes;
 }
 
-// Plain side-effect CSS imports (@lotics/ui ships .tsx with import "./x.css").
+// Plain side-effect CSS imports \u2014 @lotics/ui/styles.css, and any sheet of
+// your own.
 declare module "*.css";
 `
     },
     {
-      path: "src/harness.test.ts",
+      path: "src/harness.test.tsx",
       content: `import { describe, test, expect } from "vitest";
+import { render } from "@testing-library/react";
+import { Text } from "@lotics/ui/text";
 
 /**
  * The one test the scaffold seeds, and it is about the TEST SETUP rather than
@@ -47266,11 +47359,19 @@ declare module "*.css";
  * never has to be green over zero tests. It imports nothing of yours and
  * nothing generated, so it passes on a fresh clone before any codegen has run.
  *
+ * It renders a KIT component deliberately. @lotics/ui ships built ESM whose
+ * modules import their own \`.css\`, and a vitest that externalizes them dies
+ * with \`Unknown file extension ".css"\` on every suite that touches one \u2014 a
+ * whole-suite failure that a harness test importing only vitest would never
+ * see. \`test.server.deps.inline\` in vite.config.ts is what prevents it; this
+ * is what notices when that line goes.
+ *
  * Delete it once you have tests of your own, or keep it; it costs nothing.
  */
 describe("test harness", () => {
-  test("runs in a DOM", () => {
-    expect(typeof document).toBe("object");
+  test("renders a kit component in a DOM", () => {
+    const { container } = render(<Text>ok</Text>);
+    expect(container.textContent).toBe("ok");
   });
 });
 `
@@ -47311,6 +47412,59 @@ dist
 .DS_Store
 .lotics
 coverage
+`
+    },
+    {
+      path: "AGENTS.md",
+      content: `# ${args.app_name} \u2014 for the agent editing this app
+
+A Lotics custom-code app: React + Vite, data through \`@lotics/app-sdk\`, every pixel from
+\`@lotics/ui\`. Both are installed here \u2014 read them from \`node_modules\`, never from memory.
+
+## Read in this order, and stop when you have the answer
+
+1. **\`node_modules/@lotics/ui/llms.txt\`** \u2014 every kit entry by the data role it answers, its
+   import, and the one question that says where it does NOT go. One read, ~12k tokens.
+   **Start here for any UI question**, before writing a component of your own.
+2. **\`node_modules/@lotics/ui/dist/<module>.d.ts\`** \u2014 the props of the entry you picked, with the
+   source's own doc comments. **Never guess a prop; open the declaration.**
+3. **\`lotics docs ui/catalog/<Entry>\`** \u2014 that entry's full wrong-place test, one row.
+   **Never read \`catalog.md\` whole**: it is 334 entries, and you need one.
+4. **\`node_modules/@lotics/ui/examples/tpl_*.tsx\`** \u2014 a whole screen as source, when the SHAPE is
+   the question. Copy and adapt; never import from \`examples/\`.
+5. **\`node_modules/@lotics/app-sdk/AGENTS.md\`** \u2014 queries, workflows, files, AI.
+
+\`lotics docs\` lists what is installed here at the versions installed, so a reference always
+describes the code beside it. Every answer is capped at a page; a long one hands back its section
+list, and \`lotics docs <area>/<section>\` prints one section.
+
+## The rules that do not change
+
+- **Reuse before you build.** A capability the kit lacks is added to the kit, never hand-rolled
+  here. Search \`llms.txt\` for the role before writing a component.
+- **Customize through TOKENS and PROPS.** Tokens are the shadcn variables, the space rungs, the
+  radius ladder and the type ramp; props are \`variant\`, \`size\`, \`tone\`, \`render\` and slots.
+  \`className\`/\`style\` place an entry in your layout \u2014 they do not restyle it. The kit's DOM and
+  class names are private, so CSS that reaches inside an entry breaks on its next release.
+- **\`import "@lotics/ui/styles.css"\` once**, in \`src/main.tsx\` \u2014 it carries every token the kit's
+  \`var()\`s read, and without it the screen renders unstyled but working.
+- **A workflow is the only way this app writes.** Queries read; \`useWorkflow\` writes.
+
+## Before you commit \u2014 six checks
+
+1. **One value, one rendering.** A chart draws the entity its table draws, and a value's filter
+   renders it the way its cell does.
+2. **Every figure is formatted, by the reader's locale** \u2014 money, dates, quantities. A number
+   joined to a string is a number in somebody else's convention.
+3. **One accent.** Everything else is neutral or a valence, whose colour IS the meaning.
+4. **Every gap is a rung and the ratio is 1 : 3 : 6**: 4 inside a pair, 8 inside a group, 24
+   between bands, 48 between sections.
+5. **No bare native control.** A \`<button>\`, \`<input>\`, \`<select>\` or \`<table>\` in your source is a
+   control outside the type ramp, the locale and the keyboard contract.
+6. **No raw id reaches the reader.** \`rec_\`, \`opt_\` and \`fld_\` are keys; a cell shows the name.
+
+Then \`npm run typecheck && npm run lint && npm test\`, and \`lotics app deploy\`.
+The full review \u2014 the gates, the probes, the measurement snippets \u2014 is \`lotics docs ui/reviewing\`.
 `
     },
     {
@@ -47351,12 +47505,13 @@ import { Stack } from "@lotics/ui/stack";
 import { Card } from "@lotics/ui/card";
 import { Button } from "@lotics/ui/button";
 import { Text } from "@lotics/ui/text";
-// ... and Grid, Dialog, DatePicker, FormPicker, BarChart, LineChart, PieChart, Metric, ProgressBar, etc.
+// ... and Grid, Dialog, DatePicker, Select, BarChart, LineChart, PieChart, Metric, Progress, etc.
 \`\`\`
 
-@lotics/ui ships React Native primitives that render via react-native-web
-in this Vite app (the alias is preconfigured in \`vite.config.ts\`). See
-the full catalog with \`lotics docs ui\`.
+@lotics/ui ships built React DOM components with their own CSS \u2014 import
+\`@lotics/ui/styles.css\` once (main.tsx does) and every one of them is themed
+and addressable. Which entry answers which role is
+\`node_modules/@lotics/ui/llms.txt\`, one read.
 
 ## Routing
 
@@ -47369,11 +47524,15 @@ shareable and survives a full refresh. Standalone (\`<slug>.lotics.app\`) it's a
 normal browser router with real path URLs. A single-screen app can drop the
 router and render one screen directly.
 
-Run \`lotics docs\` for the SDK reference \u2014 it lists what the packages installed
-here actually ship, at the versions installed, so it can never point at a page
-that moved. \`lotics docs building_an_app\` is the sequence, read once before
-building; the area docs (\`lotics docs ai\`, \`lotics docs queries\`,
-\`lotics docs ui\`) are its detail.
+## References
+
+\`AGENTS.md\` in this directory is the reading order and the six checks before a
+commit. The references themselves ship inside the packages, so they always
+describe the versions installed here: \`node_modules/@lotics/ui/llms.txt\` and
+\`node_modules/@lotics/app-sdk/AGENTS.md\` are readable with no tooling at all.
+With the CLI on PATH, \`lotics docs\` indexes the same set and prints one page at
+a time \u2014 \`lotics docs building_an_app\` is the sequence, read once before
+building.
 `
     }
   ];
@@ -47567,9 +47726,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 +47905,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 +48017,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 +48169,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 +48480,8 @@ async function startDevServer(args) {
     stop: async () => {
       await stopAll();
       await stoppingPromise;
-    }
+    },
+    pendingRpc: () => inFlight
   };
 }
 async function pickPort(preferred, ...avoid) {
@@ -48346,6 +48535,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 +49597,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 +50009,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 +50160,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 +50196,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 +50238,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 +62931,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 +65635,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 +65653,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 +65667,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 +68365,7 @@ __export(expression_string_exports, {
   contains: () => contains2,
   endsWith: () => endsWith,
   formatNumber: () => formatNumber,
-  join: () => join,
+  join: () => join3,
   length: () => length,
   lower: () => lower,
   numberToWords: () => numberToWords,
@@ -67924,7 +68379,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 +68832,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 +68873,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 +72903,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 +72937,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 +73443,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 +73457,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 +73469,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
@@ -73341,8 +73796,8 @@ function warnAboutDevLink(projectDir, command) {
   const linked = config2.includes("loticsResolve") || config2.includes("LOTICS_UI_SRC");
   if (!linked) {
     console.error(
-      `\u26A0 LOTICS_UI_SRC is set but vite.config.ts never reads it \u2014 @lotics/ui will still resolve from node_modules, so kit edits will NOT ${command === "deploy" ? "ship" : "appear"}. Hand the whole resolve block to the kit (it owns the dev-link, the react-native alias, the extensions and the dedupe):
-    import { loticsOptimizeDeps, loticsResolve } from "@lotics/ui/vite";
+      `\u26A0 LOTICS_UI_SRC is set but vite.config.ts never reads it \u2014 @lotics/ui will still resolve from node_modules, so kit edits will NOT ${command === "deploy" ? "ship" : "appear"}. Hand the whole resolve block to the kit (it owns the dev-link and the React dedupe):
+    import { loticsResolve } from "@lotics/ui/vite";
     // \u2026
     resolve: loticsResolve(),`
     );
@@ -73420,6 +73875,71 @@ A newer kit is published \u2014 \`npm update ${findings.map((f) => f.pkg).join("
 ` + lines.join("\n")
   );
 }
+var KIT_SPECIFIER = "@lotics/ui/button";
+var KIT_INSTALLED_PATH = "/node_modules/@lotics/ui/dist/button.js";
+function inlineEntries(source) {
+  const out = [];
+  const key = /\binline\s*:\s*/g;
+  for (let match2 = key.exec(source); match2 !== null; match2 = key.exec(source)) {
+    const i2 = match2.index + match2[0].length;
+    if (source.startsWith("true", i2)) {
+      out.push({ kind: "everything" });
+      continue;
+    }
+    if (source[i2] !== "[") continue;
+    for (let depth = 1, i22 = i2 + 1; i22 < source.length && depth > 0; ) {
+      const c = source[i22];
+      if (c === "[") {
+        depth++;
+        i22++;
+      } else if (c === "]") {
+        depth--;
+        i22++;
+      } else if (c === '"' || c === "'" || c === "`") {
+        let j = i22 + 1;
+        while (j < source.length && source[j] !== c) j += source[j] === "\\" ? 2 : 1;
+        out.push({ kind: "string", value: source.slice(i22 + 1, j) });
+        i22 = j + 1;
+      } else if (c === "/" && source[i22 + 1] === "/") {
+        const nl = source.indexOf("\n", i22);
+        i22 = nl === -1 ? source.length : nl + 1;
+      } else if (c === "/" && source[i22 + 1] === "*") {
+        const end = source.indexOf("*/", i22);
+        i22 = end === -1 ? source.length : end + 2;
+      } else if (c === "/") {
+        let j = i22 + 1;
+        for (let inClass = false; j < source.length; j++) {
+          const ch = source[j];
+          if (ch === "\\") j++;
+          else if (ch === "[") inClass = true;
+          else if (ch === "]") inClass = false;
+          else if (ch === "/" && !inClass) break;
+          else if (ch === "\n") break;
+        }
+        if (source[j] === "/") {
+          let k = j + 1;
+          while (k < source.length && /[a-z]/.test(source[k])) k++;
+          out.push({ kind: "regex", source: source.slice(i22 + 1, j), flags: source.slice(j + 1, k) });
+          i22 = k;
+        } else i22++;
+      } else i22++;
+    }
+  }
+  return out;
+}
+function inlinesKitUnderVitest(viteConfig) {
+  return inlineEntries(viteConfig).some((entry) => {
+    if (entry.kind === "everything") return true;
+    if (entry.kind === "string")
+      return KIT_SPECIFIER === entry.value || KIT_SPECIFIER.startsWith(`${entry.value}/`);
+    try {
+      const re2 = new RegExp(entry.source, entry.flags.replace("g", ""));
+      return re2.test(KIT_SPECIFIER) || re2.test(KIT_INSTALLED_PATH);
+    } catch {
+      return false;
+    }
+  });
+}
 function ensureAppVitestSetup(projectDir) {
   const setupPath = path9.join(projectDir, VITEST_SETUP_FILENAME);
   if (!fs8.existsSync(setupPath)) {
@@ -73429,11 +73949,18 @@ function ensureAppVitestSetup(projectDir) {
   const viteConfigPath = path9.join(projectDir, "vite.config.ts");
   if (!fs8.existsSync(viteConfigPath)) return;
   const viteConfig = fs8.readFileSync(viteConfigPath, "utf-8");
-  if (/setupFiles\s*:/.test(viteConfig) && viteConfig.includes(VITEST_SETUP_FILENAME)) return;
-  console.error(
-    `\u26A0 vite.config.ts does not wire ${VITEST_SETUP_FILENAME}. Nothing is broken by that \u2014 it is the slot for global test setup (matchers, stubs, timezone pinning). Add it to the \`test\` block when you need one:
+  if (!(/setupFiles\s*:/.test(viteConfig) && viteConfig.includes(VITEST_SETUP_FILENAME))) {
+    console.error(
+      `\u26A0 vite.config.ts does not wire ${VITEST_SETUP_FILENAME}. Nothing is broken by that \u2014 it is the slot for global test setup (matchers, stubs, timezone pinning). Add it to the \`test\` block when you need one:
     setupFiles: ["./${VITEST_SETUP_FILENAME}"],`
-  );
+    );
+  }
+  if (!inlinesKitUnderVitest(viteConfig)) {
+    console.error(
+      `\u26A0 vite.config.ts does not inline @lotics/ui under vitest, so \`npm test\` fails to load every suite that renders a kit component ("Unknown file extension \\".css\\"") \u2014 the kit's modules import their own stylesheets and vitest hands node_modules to Node. Add it to the \`test\` block:
+    server: { deps: { inline: [/@lotics\\/ui/] } },`
+    );
+  }
 }
 async function appCodegen(args) {
   const projectDir = path9.resolve(args.projectDir ?? process.cwd());
@@ -73819,12 +74346,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 +74490,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 +74681,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 +74983,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 });
@@ -74606,6 +75149,13 @@ function isVersionBelow(version2, floor2) {
   if (minor !== floorMinor) return minor < floorMinor;
   return patch < floorPatch;
 }
+function bundlesReactNative(projectDir) {
+  const manifest = path9.join(projectDir, "package.json");
+  if (!fs8.existsSync(manifest)) return false;
+  const pkg = JSON.parse(fs8.readFileSync(manifest, "utf-8"));
+  const declared = { ...pkg.dependencies, ...pkg.devDependencies };
+  return "react-native" in declared || "react-native-web" in declared;
+}
 function warnIfProjectFootguns(projectDir, sourceText) {
   const lines = [];
   const sdkVersion = installedKitVersion(projectDir, "@lotics/app-sdk");
@@ -74621,7 +75171,7 @@ function warnIfProjectFootguns(projectDir, sourceText) {
     );
   }
   const configName = VITE_CONFIG_NAMES.find((name2) => fs8.existsSync(path9.join(projectDir, name2)));
-  if (configName !== void 0) {
+  if (configName !== void 0 && bundlesReactNative(projectDir)) {
     const config2 = fs8.readFileSync(path9.join(projectDir, configName), "utf-8");
     const defined = defineBlockKeys(config2);
     const missing = ["global", "__DEV__"].filter((name2) => !defined.has(name2));
@@ -75187,6 +75737,7 @@ function parseArgs(argv) {
     printCreated: false,
     cleanup: false,
     prune: false,
+    screens: false,
     noSampleData: false,
     adopt: false,
     entity: [],
@@ -75357,6 +75908,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 +76503,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 +76516,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 +76531,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 +76550,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 +76558,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 +76579,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 +76592,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 +76613,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 +76628,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 +76638,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 +76647,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 +76656,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 +76678,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 +76687,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 +76696,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 +76716,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 +76726,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 +76742,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 +77307,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 +77670,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 +77681,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 +77741,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 +77769,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 +77822,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 +77855,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 +77863,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 +77872,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 +77896,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 +77904,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 +77944,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 +77991,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 +78015,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 +78483,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 +78495,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 +78509,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 +78600,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 +78690,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 +78742,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 +78816,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 +78840,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 +79023,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 +79046,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 +81850,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 +81867,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 +81877,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 +81905,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 +87574,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 +89478,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 +90117,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 +90130,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 +90211,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 +90236,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;
@@ -89480,11 +90559,11 @@ function buildXfXml(s, fontId, fillId, borderId, numFmtId) {
   if (s.horizontalAlign || s.verticalAlign || s.wrapText || s.indent || s.textRotation || s.shrinkToFit) {
     const hAlign = s.horizontalAlign ? ` horizontal="${s.horizontalAlign}"` : "";
     const vAlign = s.verticalAlign ? ` vertical="${s.verticalAlign}"` : "";
-    const wrap = s.wrapText ? ' wrapText="1"' : "";
+    const wrap2 = s.wrapText ? ' wrapText="1"' : "";
     const indent = s.indent ? ` indent="${s.indent}"` : "";
     const rotation = s.textRotation !== void 0 ? ` textRotation="${s.textRotation === "vertical" ? 255 : s.textRotation}"` : "";
     const shrink = s.shrinkToFit ? ' shrinkToFit="1"' : "";
-    return `<xf ${attrs} applyAlignment="1"><alignment${hAlign}${vAlign}${wrap}${indent}${rotation}${shrink}/></xf>`;
+    return `<xf ${attrs} applyAlignment="1"><alignment${hAlign}${vAlign}${wrap2}${indent}${rotation}${shrink}/></xf>`;
   }
   return `<xf ${attrs}/>`;
 }
@@ -91521,9 +92600,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 +99423,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 +105948,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 +106389,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 +106645,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 +106881,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 +106893,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 +107234,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 +107687,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 +107803,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 +107829,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 +107991,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 +108295,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 +108472,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 +108480,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 +108824,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 +109200,7 @@ Available workspaces:`);
       return;
     }
     if (subcommand === "check") {
-      await appCheck(client, {});
+      await appCheck(client, { screens: flags.screens });
       return;
     }
     if (subcommand === "workflow") {