@lotics/cli 0.143.0 → 0.143.2

package/dist/render_page.js

@@ -4563,7 +4563,7 @@ ${e.toString()}`);
         }
       };
       var type2Number = { "boolean": 3, "string": 2, "number": 1 };
-      var Infix = {
+      var Infix2 = {
         compareOp: (value1, infix, value2, isArray1, isArray2) => {
           if (value1 == null) value1 = 0;
           if (value2 == null) value2 = 0;
@@ -4654,7 +4654,7 @@ ${e.toString()}`);
       module2.exports = {
         Prefix,
         Postfix,
-        Infix,
+        Infix: Infix2,
         Operators: {
           compareOp: ["<", ">", "=", "<>", "<=", ">="],
           concatOp: ["&"],
@@ -4669,7 +4669,7 @@ ${e.toString()}`);
     "../../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 = [];
@@ -5192,7 +5192,7 @@ ${e.toString()}`);
                 if (criteria.match === criteria.value.test(value2)) {
                   sum += 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)) {
                 sum += valueToAdd;
               }
             });
@@ -11472,7 +11472,7 @@ ${e.toString()}`);
     "../../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 = {
@@ -11534,7 +11534,7 @@ ${e.toString()}`);
                   sum += 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)) {
                 sum += valueToAdd;
                 cnt++;
               }
@@ -11573,7 +11573,7 @@ ${e.toString()}`);
               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++;
               }
             });
@@ -21126,7 +21126,7 @@ ${e.toString()}`);
     "../../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_ROW = 1048576;
       var MAX_COLUMN = 16384;
@@ -21250,11 +21250,11 @@ ${e.toString()}`);
           if (this.isFormulaError(val2))
             return val2;
           if (Operators.compareOp.includes(infix))
-            return Infix.compareOp(val1, infix, val2, isArray1, isArray2);
+            return Infix2.compareOp(val1, infix, val2, isArray1, isArray2);
           else if (Operators.concatOp.includes(infix))
-            return Infix.concatOp(val1, infix, val2, isArray1, isArray2);
+            return Infix2.concatOp(val1, infix, val2, isArray1, isArray2);
           else if (Operators.mathOp.includes(infix))
-            return Infix.mathOp(val1, infix, val2, isArray1, isArray2);
+            return Infix2.mathOp(val1, infix, val2, isArray1, isArray2);
           else
             throw new Error(`Unrecognized infix: ${infix}`);
         }
@@ -21806,7 +21806,7 @@ ${e.toString()}`);
     "../../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_ROW = 1048576;
       var MAX_COLUMN = 16384;
@@ -53990,14 +53990,14 @@ ${e.toString()}`);
     if (!range) return void 0;
     const header = [];
     for (let col = range.startCol; col <= range.endCol; col++) {
-      const cell = sheet.getCell(rowColToRef(range.startRow, col));
+      const cell = sheet.getCellAt(range.startRow, col);
       header.push(formatHeader(cell?.value));
     }
     const records = [];
     for (let row = range.startRow + 1; row <= range.endRow; row++) {
       const rec = [];
       for (let col = range.startCol; col <= range.endCol; col++) {
-        const cell = sheet.getCell(rowColToRef(row, col));
+        const cell = sheet.getCellAt(row, col);
         rec.push(coerceValue(cell?.value));
       }
       records.push(rec);
@@ -54041,23 +54041,70 @@ ${e.toString()}`);
     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);
@@ -54085,10 +54132,13 @@ ${e.toString()}`);
     /** 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 {
@@ -54271,6 +54321,10 @@ ${e.toString()}`);
     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
@@ -54365,22 +54419,12 @@ ${e.toString()}`);
         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 {
@@ -54627,7 +54671,7 @@ ${e.toString()}`);
       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)) {
@@ -61857,6 +61901,28 @@ ${e.toString()}`);
     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)
@@ -61891,19 +61957,35 @@ ${e.toString()}`);
     }
     /** 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 ?? (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);
@@ -61912,15 +61994,11 @@ ${e.toString()}`);
       }
       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 = [];
@@ -61931,9 +62009,7 @@ ${e.toString()}`);
       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);
@@ -61954,12 +62030,13 @@ ${e.toString()}`);
       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 } = stack.pop();
-        if (current === cell) return path;
+        if (current === cell || originCoarse.has(current)) return path;
         if (visited.has(current)) continue;
         visited.add(current);
         const nextPrec = this.precedents.get(current);
@@ -62072,6 +62149,20 @@ ${e.toString()}`);
     };
   }
 
+  // ../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, isArray2) => {
+      if (value1 == null && typeof value2 === "string") value1 = "";
+      if (value2 == null && typeof value1 === "string") value2 = "";
+      return original(value1, infix, value2, isArray1, isArray2);
+    };
+  }
+
   // ../xlsx/src/formula_engine.ts
   var unwrapArg = (a) => a !== null && typeof a === "object" && "value" in a ? a.value : a;
   function adaptFormulajs(fn) {
@@ -62114,9 +62205,24 @@ ${e.toString()}`);
     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),
@@ -62137,11 +62243,13 @@ ${e.toString()}`);
     /** 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);
         }
       }
@@ -62197,8 +62305,13 @@ ${e.toString()}`);
     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!");
@@ -62207,6 +62320,7 @@ ${e.toString()}`);
         this.evaluateCell(key);
       } else {
         this.graph.removeCell(key);
+        this.unreadableFormulas.delete(key);
       }
       const order = this.graph.getRecalcOrder([key]);
       for (const depKey of order) {
@@ -62223,6 +62337,7 @@ ${e.toString()}`);
     // ===========================================================================
     /** 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;
@@ -62271,26 +62386,60 @@ ${e.toString()}`);
     // ===========================================================================
     /** 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
@@ -62320,8 +62469,7 @@ ${e.toString()}`);
       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);
       }
@@ -62411,15 +62559,19 @@ ${e.toString()}`);
     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!" });
         }

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;
@@ -73018,6 +73018,7 @@ async function appDeploy(client, args) {
       }
       if (liveAfter) {
         warnIfUnbranded(liveAfter);
+        warnIfUndescribed(liveAfter);
         warnIfUnboundAliases(liveAfter, called);
         warnIfInertAgentTools(liveAfter);
       }
@@ -73056,6 +73057,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 +73173,7 @@ async function appCheck(client, args = {}) {
   warnIfInertAgentTools(app);
   warnIfProjectFootguns(projectDir, sourceText);
   warnIfUnbranded(app);
+  warnIfUndescribed(app);
   if (!nothingPending(pending)) {
     process.exit(1);
   }
@@ -84774,14 +84785,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 +86336,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 +86427,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 +86616,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 +86714,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 +86966,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 +94196,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 +94252,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 +94289,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 +94304,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 +94325,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 +94444,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 +94500,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 +94538,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 +94600,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 +94615,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 +94632,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 +94681,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 +94771,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 +94855,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 +95805,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);
     }
   }

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. */

package/docs/building_an_app.md

@@ -109,6 +109,13 @@ writes the schema back into the manifest and refreshes that alias's types in pla
 The alias's `description` rides along from the manifest. It is the one line an agent reads when
 choosing between your workflows, so write it rather than leaving the generated placeholder.
 
+**Every workflow you declare is also the chat agent's write surface.** So the alias's *shape* is an
+agent-facing decision, not only a screen-facing one — take a list where one job covers many
+records; say in an optional input's own `description` what omitting it means, since the agent
+cannot see the default your body applies; make the write survive running twice on the same input;
+and gate anything irreversible with `wait_for_approval` inside the body. `lotics docs ai` and
+`lotics docs workflows` carry each of those.
+
 **Static green is not a run.** `check` and `set` prove parse, types, name resolution and lint —
 they evaluate nothing. Rehearse before the first live run:
 
@@ -196,12 +203,19 @@ lotics app deploy -m "<what changed + why>"
 `-m` is optional; the deploy derives a message from what it pushed. Write one when the *why* is
 worth keeping.
 
-Then set the icon and colour — the most-forgotten step, and the deploy warns when they are unset:
+Then set the icon, the colour and the app's own `description` — the most-forgotten step, which is
+why `deploy` and `check` both warn while any of them is unset:
 
 ```
-lotics run update_app '{"app_id":"…","icon":"<lucide-name>","theme":{"color":"blue"}}'
+lotics run update_app '{"app_id":"…","icon":"<lucide-name>","theme":{"color":"blue"},
+  "description":"<what the app is for, and the standing job it does>"}'
 ```
 
+The `description` is not a label. It heads the capability listing the member's chat agent reads on
+**every** turn, so a standing process the app expects that agent to carry out belongs there and
+nowhere else — not in workspace instructions and not in a knowledge doc, both of which apply to
+every app at once (`lotics docs ai`).
+
 Finally, update the app's own `README.md` on any model or behaviour change and redeploy, so the
 brief travels with the app rather than living in whoever built it.
 
@@ -223,7 +237,7 @@ lotics app deploy -m "…"             # pushes pending bindings, then ships
 ```
 
 A deploy pushes any workflow body, agent prose or query that is ahead of the app **before** it
-ships the bundle, so forgetting a `set` no longer ships a bundle typed against a binding that does
-not exist. `lotics app check` reports the same set without pushing.
+ships the bundle, so a forgotten `set` cannot ship a bundle typed against a binding that does not
+exist. `lotics app check` reports the same set without pushing.
 
 Keep the CLI current: an old one silently drops manifest fields it does not model.

package/docs/cli_reference.md

@@ -37,7 +37,7 @@ Per-command syntax, flags, contracts, and gotchas for the public `lotics` CLI. S
 | `lotics upgrade` | Take the installed package's next version for the app in this directory (`app_id` from the local manifest — and the WORKSPACE from the same manifest, exactly as `lotics app *` does, so the command that knows which workspace it belongs to never rides the ambient profile). Announces its target on stderr before acting. **Applies the version it PREVIEWED**, not "latest" re-resolved server-side, so a release landing mid-command cannot install a contract whose diff was never checked. **Previews first and applies only a CLEAN upgrade**: a breaking contract change, a locally modified artifact, binding drift, or bundled knowledge needing consent (all FOUR sources the preview returns — the server throws for each, so omitting one only swapped the framed refusal for a raw wire 400) is reported per item and REFUSED with exit 1, because each resolves by choosing what to keep and a guess discards work nobody asked to lose. Already-current is a no-op that says so. On success it names the new version and the changelog, and points at `lotics app pull` to bring the checkout in step. The resolutions flow for a conflicted upgrade stays in `opctl` — that case needs a person, and the person is an operator. |
 | `lotics docs` \| `lotics docs <area>` | The index of the reference docs, **resolved out of the packages installed beside this project** — never carried by this CLI. **Both levels are discovered by looking**: every `@lotics/*` package carrying an `AGENTS.md` or a `docs/` in any `node_modules/@lotics` from the current directory UPWARD (nearest wins, so a hoisted root copy never shadows the one a project's own imports resolve to — checking only cwd made an agent editing `src/App.tsx`, or anyone on a workspaces/pnpm layout, see app-sdk and ui vanish while the `@lotics/cli` fallback kept the index looking complete) (six do today — app-sdk, ui, cli, docx, ooxml, xlsx), and within each, every area it actually ships. Titles come from each file's own `# heading` and the version from the installed `package.json`, so a doc OR a whole package added upstream appears with no change to this CLI, and a skewed install is visible rather than reassuring. A package's index is named after the package (`lotics docs ui`), never `index` — every package has one, so a shared name would make the most obvious query the one guaranteed to be ambiguous. `@lotics/app-sdk`, `@lotics/ui` and `@lotics/cli` sort first as a reading ORDER, not a filter. Bundling them here instead would print the contract of whichever kit version this CLI was built against — the kit publishes several times a day — and serving them from an endpoint would answer `latest` to a project on a pin: both are current-and-wrong, which is the one failure npm already prevents. Both the index and `<area>` print to **stdout** — the index is the payload of a bare `lotics docs`, so `lotics docs | grep -i excel` works — with only the provenance line on stderr, so `lotics docs ai > ai.md` is the doc alone; a name two packages share is refused with both qualified forms (`lotics docs ui/templates`) rather than resolved silently. Needs no auth — the references describe the product, not a workspace, so a key that will not resolve is exactly when someone reaches for them. Outside a project only `@lotics/cli`'s own resolve, and it says so. |
 | `lotics report '<json>'` \| `lotics report @report.json` | File a report with the Lotics team about what got in your way. **Covers the classes telemetry structurally cannot see**: a capability that does not exist (no command ran, so nothing was recorded), a command that exited 0 having done the wrong thing, an error whose message did not name the remedy, and anything that made authoring slower than it should be. **A frame, not a paragraph** — `{goal, actual, expected?, tried?, wanted?}`, `goal` and `actual` required, unknown keys dropped rather than refused. The frame exists because a session join reconstructs what was RUN and can never reconstruct what was WANTED: "the deploy warned twice" is unactionable, the same line under a goal names the defect. Each field becomes its own log attribute, so `goal` clusters across sessions instead of being grepped out of prose. **No severity or category** — those are judgements rather than facts, derivable at analysis time (a report followed by more commands on the same task shows a workaround; one followed by nothing shows a dead end), and a taxonomy shipped in a released binary cannot be corrected without a release. Ingest is inline JSON, `@file`, or `-` for stdin. The explicit `-` is the one place this departs from `run`, and it has to: `run` reaches stdin only after a tool name, while a report's single positional IS the payload, so bare and piped are the same argv. `isTTY` cannot separate them — it is falsy for a pipe a supervisor holds open and never writes to — so guessing hangs the bare form forever, and a grace period instead drops the report of any writer slower than the timer. A bare sentence is refused with the frame printed beside it, so the fix is one step; a bare invocation prints the frame BEFORE asking for a credential, since someone whose key will not resolve is exactly who has something to report. **Not spooled**: unlike telemetry it posts inline, prints whether it landed, and exits non-zero if it did not, echoing the report back so a failed send never loses it. Runs regardless of `LOTICS_TELEMETRY` — invoking it IS the consent that passive collection needs an opt-in for — but with telemetry off there are no recorded commands to attach, and it says so rather than implying context it does not have. Requires auth. Never paste records, file contents, or credentials. |
-| `lotics app check` | Every pre-flight `deploy` runs, WITHOUT building or shipping: the manifest's agent schemas against the live app row, every binding a deploy would push, aliases the source calls that nothing bound (queries, workflows AND agents), bindings the app serves that the source names nowhere, capability-gated SDK calls the manifest doesn't declare, a missing icon/theme, a `vite.config.ts` that never defines `global`/`__DEV__` and a `window.open` in the app's own source (both fail ONLY in the deployed app — dev bundles with esbuild and production with rollup, so typecheck, lint, build and `app dev` are all green while react-native-web reads `global.cancelAnimationFrame` as a free variable and the sandboxed iframe drops a popup silently), an agent holding `run_app_query`/`run_app_workflow` with an EMPTY `query_aliases`/`workflow_aliases` (the tool is the capability, the alias list is the reach — empty means every call it makes is refused while the run still COMPLETES, so it surfaces as a model ignoring its prompt; read off the live row, never the manifest, which mirrors those fields but is pushed by no verb), and a notice for any alias the source computes at runtime (invisible to every check here and to the deploy's unbind guard). Adds no rule of its own — each finding is the same helper `deploy` calls, so a green check means a deploy will not complain. **Exits 1 on what a `deploy` would REFUSE or PUSH** — an agent schema that disagrees with the live app, and any binding the project has ahead of the app (an edited workflow body or declaration, edited agent prose, a changed query). Both are things a deploy would act on, so CI gating on a green check means a deploy has nothing left to do; genuine advisories (capabilities, branding, a runtime-computed alias, orphaned bindings) stay advisory and never fail it. The point is the question being ASKABLE: these checks used to cost a build, a tar, an upload and a version row in the audit trail, which is expensive enough that the honest move was to skip them and find out in production. |
+| `lotics app check` | Every pre-flight `deploy` runs, WITHOUT building or shipping: the manifest's agent schemas against the live app row, every binding a deploy would push, aliases the source calls that nothing bound (queries, workflows AND agents), bindings the app serves that the source names nowhere, capability-gated SDK calls the manifest doesn't declare, a missing icon/theme, a missing app `description` (it heads the capability catalog the chat agent reads every turn, and its absence has no other symptom), a `vite.config.ts` that never defines `global`/`__DEV__` and a `window.open` in the app's own source (both fail ONLY in the deployed app — dev bundles with esbuild and production with rollup, so typecheck, lint, build and `app dev` are all green while react-native-web reads `global.cancelAnimationFrame` as a free variable and the sandboxed iframe drops a popup silently), an agent holding `run_app_query`/`run_app_workflow` with an EMPTY `query_aliases`/`workflow_aliases` (the tool is the capability, the alias list is the reach — empty means every call it makes is refused while the run still COMPLETES, so it surfaces as a model ignoring its prompt; read off the live row, never the manifest, which mirrors those fields but is pushed by no verb), and a notice for any alias the source computes at runtime (invisible to every check here and to the deploy's unbind guard). Adds no rule of its own — each finding is the same helper `deploy` calls, so a green check means a deploy will not complain. **Exits 1 on what a `deploy` would REFUSE or PUSH** — an agent schema that disagrees with the live app, and any binding the project has ahead of the app (an edited workflow body or declaration, edited agent prose, a changed query). Both are things a deploy would act on, so CI gating on a green check means a deploy has nothing left to do; genuine advisories (capabilities, branding, a runtime-computed alias, orphaned bindings) stay advisory and never fail it. The point is the question being ASKABLE: these checks used to cost a build, a tar, an upload and a version row in the audit trail, which is expensive enough that the honest move was to skip them and find out in production. |
 | `lotics app workflow run <alias> '<json>'` | Execute a bound app workflow end-to-end via `appWorkflow`. `app_id` comes from the local manifest; the alias must be bound (`set_app_workflow`). Inputs ingest exactly like `lotics run` (inline JSON / `@file` / stdin — bulk inputs bypass `ARG_MAX`). Prints the full `{status,message,data,files,side_effects}` JSON to stdout + a one-line summary to stderr; exits non-zero on `status:"error"` (assertable). `--print-created` (alias `--report-effects`) renders the honest post-run harvest: created records grouped by table, a paste-ready `lotics run delete_records …` per table, then the **mandatory caveat** naming what cannot be auto-undone (external integrations + notifications) and that sub-workflows may have run. `--cleanup` (DEFAULT OFF, implies the report) additionally runs the deletes for harvested records ONLY — never files / external / notifications. Neither is a rollback — a rollback is structurally impossible here. |
 | `lotics app workflow set <alias>` | Push the edited `src/workflows/<alias>.ts` body through `set_app_workflow` (the single author of `apps.workflows`). Reads the body from disk (header + `/// <reference>` + `export {};` marker + the `__workflow` wrapper all stripped) + the typed `inputs`/`outputs` **and the `description`** from `package.json#lotics.workflows.<alias>`; the **server** re-verifies the body and echoes the bound `outputs` (declared, else DERIVED from `return({ data })`). The `description` is the one line an agent reads when choosing between the app's aliases (the workflow counterpart to a query's) — authored in the manifest so it lives beside the body in version control and rides every push; omit it and the workflow keeps whatever description it already has, so a push can never blank one set elsewhere. When the manifest declared NO `outputs`, the DERIVED echo is written back into `package.json#lotics.workflows.<alias>.outputs` (a SURGICAL write — preserves `knowledge`/`config` and every other manifest field) and that alias's types are refreshed in place, so `useWorkflow("<alias>")`'s `result.data` is typed immediately with no hand-copy and no second `lotics app codegen`; an explicitly-declared `outputs` is authoritative and never overwritten. Deploy still never authors workflows — this is a CLI convenience over the existing tool. Clear error + non-zero exit on a missing file, an alias absent from the manifest, or a verify failure. |
 | `lotics app agent set <alias>` | Push `src/agents/<alias>.md` — plus `inputs`/`outputs` when `package.json#lotics.agents.<alias>` declares them — through `set_app_agent`. The agent mirror of `app workflow set`, and the deploy-free authoring path for an agent's prose and its typed edges. **It sends only those fields.** Everything else is absent, and absent means unchanged, so a declaration this CLI does not model cannot be reverted by a push from a checkout that predates it — the chat authoring agent's `knowledge_doc_ids`, another operator's `query_aliases` grant. To change one of those, call `set_app_agent` with just that field (`lotics run set_app_agent '{"app_id":…,"alias":…,"tool_names":[…]}'` — it merges), then `app pull` to bring the manifest back in step. **CREATES the alias when the app has not bound one yet**, so a new agent is authored the same way a new workflow is: write the prose, declare the typed half, push. A create needs the prose file (an agent without instructions is not an agent); it is gated on nothing else, because what keeps a binding alive is a `useAppAgentRun("<alias>")` call site in the shipped bundle — a deploy prunes an agent the bundle never names, manifest entry or not. The prose push is a conditional write against the fingerprint this project last saw, so it is refused rather than allowed to overwrite prose someone else changed. Clear error + non-zero exit when there is no prose file and nothing declared to push instead, when a create has no prose to create from, or when the file is empty once the header is stripped. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/cli",
-  "version": "0.143.0",
+  "version": "0.143.2",
   "description": "Lotics SDK and CLI for AI agents",
   "type": "module",
   "bin": {