@lotics/cli 0.143.0 → 0.143.3

package/dist/src/cli.js

@@ -16769,7 +16769,7 @@ var require_operators = __commonJS({
       }
     };
     var type2Number = { "boolean": 3, "string": 2, "number": 1 };
-    var Infix = {
+    var Infix2 = {
       compareOp: (value1, infix, value2, isArray1, isArray22) => {
         if (value1 == null) value1 = 0;
         if (value2 == null) value2 = 0;
@@ -16860,7 +16860,7 @@ var require_operators = __commonJS({
     module2.exports = {
       Prefix,
       Postfix,
-      Infix,
+      Infix: Infix2,
       Operators: {
         compareOp: ["<", ">", "=", "<>", "<=", ">="],
         concatOp: ["&"],
@@ -16875,7 +16875,7 @@ var require_math = __commonJS({
   "../../node_modules/fast-formula-parser/formulas/functions/math.js"(exports2, module2) {
     var FormulaError = require_error();
     var { FormulaHelpers, Types, Factorials, Criteria } = require_helpers();
-    var { Infix } = require_operators();
+    var { Infix: Infix2 } = require_operators();
     var H = FormulaHelpers;
     var f = [];
     var fd2 = [];
@@ -17398,7 +17398,7 @@ var require_math = __commonJS({
               if (criteria.match === criteria.value.test(value2)) {
                 sum2 += valueToAdd;
               }
-            } else if (Infix.compareOp(value2, criteria.op, criteria.value, Array.isArray(value2), isCriteriaArray)) {
+            } else if (Infix2.compareOp(value2, criteria.op, criteria.value, Array.isArray(value2), isCriteriaArray)) {
               sum2 += valueToAdd;
             }
           });
@@ -23678,7 +23678,7 @@ var require_statistical = __commonJS({
   "../../node_modules/fast-formula-parser/formulas/functions/statistical.js"(exports2, module2) {
     var FormulaError = require_error();
     var { FormulaHelpers, Types, Criteria, Address } = require_helpers();
-    var { Infix } = require_operators();
+    var { Infix: Infix2 } = require_operators();
     var H = FormulaHelpers;
     var { DistributionFunctions } = require_distribution();
     var StatisticalFunctions = {
@@ -23740,7 +23740,7 @@ var require_statistical = __commonJS({
                 sum2 += valueToAdd;
                 cnt++;
               }
-            } else if (Infix.compareOp(value2, criteria.op, criteria.value, Array.isArray(value2), isCriteriaArray)) {
+            } else if (Infix2.compareOp(value2, criteria.op, criteria.value, Array.isArray(value2), isCriteriaArray)) {
               sum2 += valueToAdd;
               cnt++;
             }
@@ -23779,7 +23779,7 @@ var require_statistical = __commonJS({
             if (criteria.op === "wc") {
               if (criteria.match === criteria.value.test(value2))
                 cnt++;
-            } else if (Infix.compareOp(value2, criteria.op, criteria.value, Array.isArray(value2), isCriteriaArray)) {
+            } else if (Infix2.compareOp(value2, criteria.op, criteria.value, Array.isArray(value2), isCriteriaArray)) {
               cnt++;
             }
           });
@@ -33332,7 +33332,7 @@ var require_utils2 = __commonJS({
   "../../node_modules/fast-formula-parser/grammar/utils.js"(exports2, module2) {
     var FormulaError = require_error();
     var { Address } = require_helpers();
-    var { Prefix, Postfix, Infix, Operators } = require_operators();
+    var { Prefix, Postfix, Infix: Infix2, Operators } = require_operators();
     var Collection = require_collection();
     var MAX_ROW2 = 1048576;
     var MAX_COLUMN2 = 16384;
@@ -33456,11 +33456,11 @@ var require_utils2 = __commonJS({
         if (this.isFormulaError(val2))
           return val2;
         if (Operators.compareOp.includes(infix))
-          return Infix.compareOp(val1, infix, val2, isArray1, isArray22);
+          return Infix2.compareOp(val1, infix, val2, isArray1, isArray22);
         else if (Operators.concatOp.includes(infix))
-          return Infix.concatOp(val1, infix, val2, isArray1, isArray22);
+          return Infix2.concatOp(val1, infix, val2, isArray1, isArray22);
         else if (Operators.mathOp.includes(infix))
-          return Infix.mathOp(val1, infix, val2, isArray1, isArray22);
+          return Infix2.mathOp(val1, infix, val2, isArray1, isArray22);
         else
           throw new Error(`Unrecognized infix: ${infix}`);
       }
@@ -34012,7 +34012,7 @@ var require_utils3 = __commonJS({
   "../../node_modules/fast-formula-parser/grammar/dependency/utils.js"(exports2, module2) {
     var FormulaError = require_error();
     var { FormulaHelpers, Types, Address } = require_helpers();
-    var { Prefix, Postfix, Infix, Operators } = require_operators();
+    var { Prefix, Postfix, Infix: Infix2, Operators } = require_operators();
     var Collection = require_collection();
     var MAX_ROW2 = 1048576;
     var MAX_COLUMN2 = 16384;
@@ -45731,8 +45731,8 @@ function renderDocIndex(areas) {
       lines.push(`
 ${a.pkg}  ${a.version}`);
     }
-    const name2 = a.absPath.endsWith("AGENTS.md") ? `${a.area}  \u2190 start here` : a.area;
-    lines.push(`  ${name2.padEnd(24)}${a.title}`);
+    const name2 = a.absPath.endsWith("AGENTS.md") ? `${a.area}  \u2190 start here` : a.pkg === "@lotics/cli" && a.area === "building_an_app" ? `${a.area}  \u2190 read once, first` : a.area;
+    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 <pkg>/<area>      when two packages share a name");
@@ -46734,7 +46734,9 @@ 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 ai\`, \`lotics docs queries\`, \`lotics docs ui\`.)
+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.
 `
     }
   ];
@@ -72889,7 +72891,8 @@ async function appPull(client, args) {
   console.error(`
 Ready. Next steps:`);
   console.error(`  cd ${path9.relative(process.cwd(), targetPath) || "."}`);
-  console.error(`  # edit src/App.tsx`);
+  console.error(`  lotics docs                # the contracts, at the versions installed here`);
+  console.error(`  # edit src/App.tsx, then:`);
   console.error(`  lotics app deploy`);
 }
 function readAppSourceText(projectDir) {
@@ -73018,6 +73021,7 @@ async function appDeploy(client, args) {
       }
       if (liveAfter) {
         warnIfUnbranded(liveAfter);
+        warnIfUndescribed(liveAfter);
         warnIfUnboundAliases(liveAfter, called);
         warnIfInertAgentTools(liveAfter);
       }
@@ -73056,6 +73060,15 @@ function warnIfUnbranded(app) {
   Find an icon:  lotics run search_app_icons '{"query":"<word>"}'`
   );
 }
+function warnIfUndescribed(app) {
+  if (app.description && app.description.trim() !== "") return;
+  console.error(
+    `
+\u26A0 This app has no description \u2014 the capability catalog its chat agent reads every turn
+  lists the aliases and says nothing about what to do with them.
+  Set it:  lotics run update_app '{"app_id":"${app.id}","description":"<what the app is for, and the standing job it does>"}'`
+  );
+}
 async function readLiveQueries(client, appId) {
   try {
     const app = await client.getApp(appId);
@@ -73163,6 +73176,7 @@ async function appCheck(client, args = {}) {
   warnIfInertAgentTools(app);
   warnIfProjectFootguns(projectDir, sourceText);
   warnIfUnbranded(app);
+  warnIfUndescribed(app);
   if (!nothingPending(pending)) {
     process.exit(1);
   }
@@ -84774,14 +84788,14 @@ function readSourceData(workbook, cache) {
   if (!range2) return void 0;
   const header = [];
   for (let col = range2.startCol; col <= range2.endCol; col++) {
-    const cell = sheet.getCell(rowColToRef(range2.startRow, col));
+    const cell = sheet.getCellAt(range2.startRow, col);
     header.push(formatHeader(cell?.value));
   }
   const records = [];
   for (let row = range2.startRow + 1; row <= range2.endRow; row++) {
     const rec = [];
     for (let col = range2.startCol; col <= range2.endCol; col++) {
-      const cell = sheet.getCell(rowColToRef(row, col));
+      const cell = sheet.getCellAt(row, col);
       rec.push(coerceValue(cell?.value));
     }
     records.push(rec);
@@ -86325,23 +86339,70 @@ var CellMap = class {
   get size() {
     return this.store.size;
   }
+  /**
+   * The populated extent of this map, memoized until a mutation invalidates it.
+   *
+   * It lives HERE rather than on `SheetModel` because it is a pure function of
+   * the cell set: a cache held next to the data cannot outlive it, so replacing
+   * a sheet's map can never serve the previous map's extent. Every mutator
+   * below drops it, including the packed pair — those bypass `set`/`delete`
+   * entirely and are what the row/column commands use.
+   *
+   * Walking PACKED keys is the other half. `keys()` unpacks each key into an A1
+   * string, which the caller then reparsed with a regex, so the old form packed,
+   * unpacked and reparsed the whole sheet on every call — and it is called once
+   * per oversized range during a recompute.
+   */
+  usedRange() {
+    if (!this.usedRangeCache) {
+      let minRow2 = Infinity;
+      let maxRow2 = 0;
+      let minCol2 = Infinity;
+      let maxCol2 = 0;
+      for (const packed of this.store.keys()) {
+        const { row, col } = unpackRowCol(packed);
+        if (row < minRow2) minRow2 = row;
+        if (row > maxRow2) maxRow2 = row;
+        if (col < minCol2) minCol2 = col;
+        if (col > maxCol2) maxCol2 = col;
+      }
+      this.usedRangeCache = maxRow2 === 0 ? { minRow: 1, maxRow: 1, minCol: 1, maxCol: 1 } : { minRow: minRow2, maxRow: maxRow2, minCol: minCol2, maxCol: maxCol2 };
+    }
+    const { minRow, maxRow, minCol, maxCol } = this.usedRangeCache;
+    return { minRow, maxRow, minCol, maxCol };
+  }
   get(ref2) {
     return this.store.get(packRef(ref2));
   }
+  /**
+   * Read by coordinate, skipping the A1 round trip.
+   *
+   * `get(ref)` costs a number→string→regex→number conversion per call, which
+   * is invisible until a caller reads a range cell by cell: on one real
+   * workbook `refToRowCol` alone was 39% of a full recompute. A caller already
+   * holding (row, col) — the range resolver, any grid walk — should use this.
+   */
+  getAt(row, col) {
+    return this.store.get(packRowCol(row, col));
+  }
   set(ref2, cell) {
     const key = packRef(ref2);
     if (key < 0) return this;
     this.store.set(key, cell);
+    this.usedRangeCache = void 0;
     return this;
   }
   has(ref2) {
     return this.store.has(packRef(ref2));
   }
   delete(ref2) {
-    return this.store.delete(packRef(ref2));
+    const deleted = this.store.delete(packRef(ref2));
+    if (deleted) this.usedRangeCache = void 0;
+    return deleted;
   }
   clear() {
     this.store.clear();
+    this.usedRangeCache = void 0;
   }
   *keys() {
     for (const k of this.store.keys()) yield unpackRef(k);
@@ -86369,10 +86430,13 @@ var CellMap = class {
   /** Direct packed-key set, for the same hot loops. */
   setPacked(packed, cell) {
     this.store.set(packed, cell);
+    this.usedRangeCache = void 0;
   }
   /** Direct packed-key delete. */
   deletePacked(packed) {
-    return this.store.delete(packed);
+    const deleted = this.store.delete(packed);
+    if (deleted) this.usedRangeCache = void 0;
+    return deleted;
   }
 };
 var StyleRegistry = class {
@@ -86555,6 +86619,10 @@ var SheetModel = class {
   getCell(ref2) {
     return this.cells.get(ref2);
   }
+  /** Read by coordinate, skipping the A1 round trip — see `CellMap.getAt`. */
+  getCellAt(row, col) {
+    return this.cells.getAt(row, col);
+  }
   /**
    * Set cell value with optional inline style. Interns style via the
    * StyleRegistry when available. When `style` is supplied and matches the
@@ -86649,22 +86717,12 @@ var SheetModel = class {
       this.set(ref2, label, style);
     });
   }
-  /** Compute the bounding box of all non-empty cells. */
+  /**
+   * The populated extent of the sheet. Derived from — and cached by — the cell
+   * map, so it cannot outlive the data it describes.
+   */
   getUsedRange() {
-    let minRow = Infinity;
-    let maxRow = 0;
-    let minCol = Infinity;
-    let maxCol = 0;
-    for (const ref2 of this.cells.keys()) {
-      const rc = refToRowCol(ref2);
-      if (!rc) continue;
-      if (rc.row < minRow) minRow = rc.row;
-      if (rc.row > maxRow) maxRow = rc.row;
-      if (rc.col < minCol) minCol = rc.col;
-      if (rc.col > maxCol) maxCol = rc.col;
-    }
-    if (maxRow === 0) return { minRow: 1, maxRow: 1, minCol: 1, maxCol: 1 };
-    return { minRow, maxRow, minCol, maxCol };
+    return this.cells.usedRange();
   }
 };
 var WorkbookModel = class {
@@ -86911,7 +86969,7 @@ function applyAutoFilterHiddenRows(sheet) {
     let visible = true;
     for (const filterCol of activeFilters) {
       const col = startCol + filterCol.colIndex;
-      const cell = sheet.getCell(rowColToRef(r, col));
+      const cell = sheet.getCellAt(r, col);
       const cellText = cell?.displayValue ?? "";
       if (filterCol.filterValues && filterCol.filterValues.length > 0) {
         if (!filterCol.filterValues.includes(cellText)) {
@@ -94141,6 +94199,28 @@ function parseCellKey(key) {
   const bang = key.indexOf("!");
   return { sheet: key.slice(0, bang), ref: key.slice(bang + 1) };
 }
+var COARSE_COL_SUFFIX = ":*";
+var COARSE_ROW_PREFIX = "*:";
+function columnKey(sheet, column) {
+  return `${sheet}!${column}${COARSE_COL_SUFFIX}`;
+}
+function rowKey(sheet, row) {
+  return `${sheet}!${COARSE_ROW_PREFIX}${row}`;
+}
+function isCoarseKey(key) {
+  return key.endsWith(COARSE_COL_SUFFIX) || key.includes(`!${COARSE_ROW_PREFIX}`);
+}
+var A1 = /^([A-Z]+)(\d+)$/;
+function coarseKeysFor(cellKeyStr) {
+  const bang = cellKeyStr.indexOf("!");
+  if (bang < 0) return [];
+  const sheet = cellKeyStr.slice(0, bang);
+  const ref2 = cellKeyStr.slice(bang + 1);
+  const m = A1.exec(ref2);
+  if (!m) return [];
+  return [columnKey(sheet, m[1]), rowKey(sheet, Number(m[2]))];
+}
+var EMPTY = /* @__PURE__ */ new Set();
 var DependencyGraph = class {
   constructor() {
     // Forward edges: cell → cells it references (precedents)
@@ -94175,19 +94255,35 @@ var DependencyGraph = class {
   }
   /** Get all cells that directly depend on the given cell. */
   getDirectDependents(cell) {
-    return Array.from(this.dependents.get(cell) ?? []);
+    return Array.from(this.dependentsOf(cell));
+  }
+  /**
+   * Everything that references this cell — directly, or through the column or
+   * row node that contains it. The single place `dependents` is read, so a
+   * whole-column reference cannot be forgotten by one traversal and honoured by
+   * another.
+   */
+  dependentsOf(cell) {
+    const direct = this.dependents.get(cell);
+    if (isCoarseKey(cell)) return direct ?? EMPTY;
+    const coarse = coarseKeysFor(cell);
+    let widened;
+    for (const key of coarse) {
+      const via = this.dependents.get(key);
+      if (!via || via.size === 0) continue;
+      widened ??= new Set(direct);
+      for (const d of via) widened.add(d);
+    }
+    return widened ?? direct ?? EMPTY;
   }
   /** Get all cells that need recalculation when the given cells change, in topological order. */
   getRecalcOrder(changed) {
-    const changedSet = new Set(changed);
     const affected = /* @__PURE__ */ new Set();
     const queue = [...changed];
     let head = 0;
     while (head < queue.length) {
       const cell = queue[head++];
-      const deps = this.dependents.get(cell);
-      if (!deps) continue;
-      for (const dep of deps) {
+      for (const dep of this.dependentsOf(cell)) {
         if (!affected.has(dep)) {
           affected.add(dep);
           queue.push(dep);
@@ -94196,15 +94292,11 @@ var DependencyGraph = class {
     }
     if (affected.size === 0) return [];
     const inDegree = /* @__PURE__ */ new Map();
+    for (const cell of affected) inDegree.set(cell, 0);
     for (const cell of affected) {
-      let count = 0;
-      const prec = this.precedents.get(cell);
-      if (prec) {
-        for (const p of prec) {
-          if (affected.has(p)) count++;
-        }
+      for (const dep of this.dependentsOf(cell)) {
+        if (affected.has(dep)) inDegree.set(dep, (inDegree.get(dep) ?? 0) + 1);
       }
-      inDegree.set(cell, count);
     }
     const result = [];
     const ready = [];
@@ -94215,9 +94307,7 @@ var DependencyGraph = class {
     while (readyHead < ready.length) {
       const cell = ready[readyHead++];
       result.push(cell);
-      const deps = this.dependents.get(cell);
-      if (!deps) continue;
-      for (const dep of deps) {
+      for (const dep of this.dependentsOf(cell)) {
         if (!affected.has(dep)) continue;
         const newDeg = (inDegree.get(dep) ?? 1) - 1;
         inDegree.set(dep, newDeg);
@@ -94238,12 +94328,13 @@ var DependencyGraph = class {
     const stack = new Array();
     const prec = this.precedents.get(cell);
     if (!prec) return null;
+    const originCoarse = new Set(coarseKeysFor(cell));
     for (const p of prec) {
       stack.push({ cell: p, path: [cell, p] });
     }
     while (stack.length > 0) {
       const { cell: current, path: path12 } = stack.pop();
-      if (current === cell) return path12;
+      if (current === cell || originCoarse.has(current)) return path12;
       if (visited.has(current)) continue;
       visited.add(current);
       const nextPrec = this.precedents.get(current);
@@ -94356,6 +94447,20 @@ function parseTableRange(ref2) {
   };
 }
 
+// ../xlsx/src/blank_comparison.ts
+var import_operators = __toESM(require_operators(), 1);
+var patched = false;
+function applyExcelBlankSemantics() {
+  if (patched) return;
+  patched = true;
+  const original = import_operators.Infix.compareOp;
+  import_operators.Infix.compareOp = (value1, infix, value2, isArray1, isArray22) => {
+    if (value1 == null && typeof value2 === "string") value1 = "";
+    if (value2 == null && typeof value1 === "string") value2 = "";
+    return original(value1, infix, value2, isArray1, isArray22);
+  };
+}
+
 // ../xlsx/src/formula_engine.ts
 var unwrapArg = (a) => a !== null && typeof a === "object" && "value" in a ? a.value : a;
 function adaptFormulajs(fn) {
@@ -94398,9 +94503,24 @@ function formulajsBridgeWithContext() {
   bridgeCtxCache = withCtx;
   return withCtx;
 }
+var MAX_EXPANDED_CELLS = 1e4;
 var FormulaEngine = class _FormulaEngine {
   constructor(workbook) {
     this.graph = new DependencyGraph();
+    /**
+     * Formula cells (by key) whose text the parser could not read AT ALL, found
+     * while building the graph from a loaded file.
+     *
+     * They are held apart from every other failure because the honest response
+     * differs: a formula that evaluates TO an error has been understood, so
+     * writing `#DIV/0!` reports a real answer, while one we cannot parse has not
+     * been — and overwriting the value its author computed would replace a
+     * correct number with a guess. These keep their cached value and are named in
+     * the report instead. The engine's own rule, one level down: degrade what you
+     * cannot draw, refuse what you cannot read.
+     */
+    this.unreadableFormulas = /* @__PURE__ */ new Set();
+    applyExcelBlankSemantics();
     this.workbook = workbook;
     this.parser = new import_fast_formula_parser.default({
       onCell: (ref2) => this.resolveCell(ref2),
@@ -94421,11 +94541,13 @@ var FormulaEngine = class _FormulaEngine {
   /** Build dependency graph from all formula cells in the workbook. */
   buildGraph() {
     this.graph.clear();
+    this.unreadableFormulas.clear();
     for (const sheet of this.workbook.sheets) {
       for (const [ref2, cell] of sheet.cells) {
         if (!cell.formula) continue;
         const key = cellKey({ sheet: sheet.name, ref: ref2 });
-        const deps = this.extractDependencies(cell.formula, sheet.name);
+        const { deps, readable } = this.analyzeFormula(cell.formula, sheet.name);
+        if (!readable) this.unreadableFormulas.add(key);
         this.graph.setDependencies(key, deps);
       }
     }
@@ -94481,8 +94603,13 @@ var FormulaEngine = class _FormulaEngine {
   onCellChanged(sheetName, ref2, formula) {
     const key = cellKey({ sheet: sheetName, ref: ref2 });
     if (formula) {
-      const deps = this.extractDependencies(formula, sheetName);
+      const { deps, readable } = this.analyzeFormula(formula, sheetName);
       this.graph.setDependencies(key, deps);
+      this.unreadableFormulas.delete(key);
+      if (!readable) {
+        this.setCellError(key, "#ERROR!");
+        return;
+      }
       const cycle = this.graph.detectCycle(key);
       if (cycle) {
         this.setCellError(key, "#CIRC!");
@@ -94491,6 +94618,7 @@ var FormulaEngine = class _FormulaEngine {
       this.evaluateCell(key);
     } else {
       this.graph.removeCell(key);
+      this.unreadableFormulas.delete(key);
     }
     const order = this.graph.getRecalcOrder([key]);
     for (const depKey of order) {
@@ -94507,6 +94635,7 @@ var FormulaEngine = class _FormulaEngine {
   // ===========================================================================
   /** Evaluate a single formula cell and update its value. */
   evaluateCell(key) {
+    if (this.unreadableFormulas.has(key)) return;
     const { sheet: sheetName, ref: ref2 } = parseCellKey(key);
     const sheetIndex = this.workbook.sheets.findIndex((s) => s.name === sheetName);
     if (sheetIndex < 0) return;
@@ -94555,26 +94684,60 @@ var FormulaEngine = class _FormulaEngine {
   // ===========================================================================
   /** Extract cell/range references from a formula string. Returns empty array for unparseable formulas. */
   extractDependencies(formula, currentSheet) {
-    const sheet = this.workbook.sheets.find((s) => s.name === currentSheet);
-    const expanded = sheet ? expandStructuredRefs(formula, sheet.tables, 1) : formula;
-    const deps = this.depParser.parse(expanded, { sheet: currentSheet, row: 1, col: 1 });
+    return this.analyzeFormula(formula, currentSheet).deps;
+  }
+  /**
+   * Dependencies plus whether the parser could read the formula at all.
+   *
+   * `fast-formula-parser` reports a formula it cannot LEX by throwing, the same
+   * channel it uses for `#VALUE!`, so the lexer failure of a single cell used to
+   * escape `buildGraph` and abort the recompute for the entire workbook —
+   * observed on a real workbook whose `VLOOKUP` pointed at another file
+   * (`'[1]DATA'!B:C`, an external-workbook reference the lexer has no rule for).
+   * Anything the grammar does not cover lands here the same way, so this catches
+   * the class rather than that one syntax.
+   */
+  analyzeFormula(formula, currentSheet) {
+    let deps;
+    try {
+      const sheet = this.workbook.sheets.find((s) => s.name === currentSheet);
+      const expanded = sheet ? expandStructuredRefs(formula, sheet.tables, 1) : formula;
+      deps = this.depParser.parse(expanded, { sheet: currentSheet, row: 1, col: 1 });
+    } catch {
+      return { deps: [], readable: false };
+    }
     const refs = [];
     for (const dep of deps) {
       const depSheet = dep.sheet ?? currentSheet;
       if (dep.from && dep.to) {
-        const maxCells = 1e4;
-        let count = 0;
-        for (let r = dep.from.row; r <= dep.to.row && count < maxCells; r++) {
-          for (let c = dep.from.col; c <= dep.to.col && count < maxCells; c++) {
+        const rows = dep.to.row - dep.from.row + 1;
+        const cols = dep.to.col - dep.from.col + 1;
+        if (rows * cols > MAX_EXPANDED_CELLS) {
+          if (cols <= rows) {
+            for (let c = dep.from.col; c <= dep.to.col; c++) {
+              refs.push(columnKey(depSheet, colNumToLetters(c)));
+            }
+          } else {
+            for (let r = dep.from.row; r <= dep.to.row; r++) {
+              refs.push(rowKey(depSheet, r));
+            }
+          }
+          continue;
+        }
+        for (let r = dep.from.row; r <= dep.to.row; r++) {
+          for (let c = dep.from.col; c <= dep.to.col; c++) {
             refs.push(cellKey({ sheet: depSheet, ref: rowColToRef(r, c) }));
-            count++;
           }
         }
       } else if (dep.row != null && dep.col != null) {
         refs.push(cellKey({ sheet: depSheet, ref: rowColToRef(dep.row, dep.col) }));
       }
     }
-    return refs;
+    return { deps: refs, readable: true };
+  }
+  /** Formula cells the parser could not read, by key. Read by the recompute report. */
+  unreadable() {
+    return this.unreadableFormulas;
   }
   // ===========================================================================
   // Cell value resolution callbacks
@@ -94611,8 +94774,7 @@ var FormulaEngine = class _FormulaEngine {
     for (let r = ref2.from.row; r <= lastRow; r++) {
       const row = [];
       for (let c = ref2.from.col; c <= lastCol; c++) {
-        const cell = sheet.getCell(rowColToRef(r, c));
-        row.push(cell?.value ?? null);
+        row.push(sheet.getCellAt(r, c)?.value ?? null);
       }
       result.push(row);
     }
@@ -94696,15 +94858,19 @@ function recomputeAll(workbook) {
   const engine = new FormulaEngine(workbook);
   engine.buildGraph();
   engine.evaluateAll();
-  return collectRecomputeReport(workbook);
+  return collectRecomputeReport(workbook, engine.unreadable());
 }
-function collectRecomputeReport(workbook) {
+function collectRecomputeReport(workbook, unreadable) {
   let total = 0;
   const unevaluated = [];
   for (const sheet of workbook.sheets) {
     for (const [ref2, cell] of sheet.cells) {
       if (!cell.formula) continue;
       total++;
+      if (unreadable.has(cellKey({ sheet: sheet.name, ref: ref2 }))) {
+        unevaluated.push({ sheet: sheet.name, ref: ref2, formula: cell.formula, error: "#UNREADABLE!" });
+        continue;
+      }
       if (cell.value === null) {
         unevaluated.push({ sheet: sheet.name, ref: ref2, formula: cell.formula, error: cell.error ?? "#ERROR!" });
       }
@@ -95642,9 +95808,9 @@ function applySheetCells(workbook, sheetIndex, def) {
     }
   }
   if (def.rowHeights) {
-    for (const [rowKey, height] of Object.entries(def.rowHeights)) {
-      const row = Number(rowKey);
-      if (!Number.isInteger(row) || row < 1) fail2(`Invalid row in sheet "${def.name}".rowHeights: ${rowKey}`);
+    for (const [rowKey2, height] of Object.entries(def.rowHeights)) {
+      const row = Number(rowKey2);
+      if (!Number.isInteger(row) || row < 1) fail2(`Invalid row in sheet "${def.name}".rowHeights: ${rowKey2}`);
       sheet.rowHeights.set(row, height);
     }
   }
@@ -102076,6 +102242,10 @@ USAGE
   Tools are grouped by category (tables, records, views, etc.).
   Query tools return IDs used as arguments to other tools.
 
+  Building an APP? Read \`lotics docs building_an_app\` first \u2014 the sequence the
+  \`lotics app *\` commands below go in \u2014 then \`lotics docs\` for the area
+  references installed beside the project.
+
 COMMANDS
 ${renderCommandsHelp()}
 

package/dist/src/client.d.ts

@@ -224,6 +224,10 @@ export declare class LoticsClient {
     getApp(app_id: string): Promise<{
         id: string;
         name: string;
+        /** What the app is for. Heads the capability catalog the member's chat agent
+         *  reads every turn the app is open, so it is where a standing process is
+         *  stated. Null when unset. */
+        description?: string | null;
         workspace_id: string;
         current_version_id: string | null;
         /** Launcher icon — a Lucide name, or an image ref. Null when unset. */