@lotics/cli 0.162.0 → 0.164.0

package/dist/src/cli.js

@@ -44177,7 +44177,9 @@ function gatewayErrorMessage(status) {
 }
 function transportErrorMessage(status, parsed) {
   const jsonMessage = parsed && typeof parsed.message === "string" ? parsed.message : null;
-  return parsed === null || status >= 500 || jsonMessage === null ? gatewayErrorMessage(status) : jsonMessage;
+  if (jsonMessage === null) return gatewayErrorMessage(status);
+  const authored = typeof parsed.code === "string" && parsed.code.length > 0;
+  return status < 500 || authored ? jsonMessage : gatewayErrorMessage(status);
 }
 
 // src/client.ts
@@ -44478,6 +44480,16 @@ var LoticsClient = class {
   async retirePackage(package_id, body) {
     return this.request("POST", `/v1/packages/${encodeURIComponent(package_id)}/retire`, body);
   }
+  /**
+   * Edit a starter's registry listing — the name and description a stranger
+   * reads before copying, and what every copy's app row is created from.
+   *
+   * A version is an immutable snapshot; the listing is not. Omit a field to
+   * leave it, pass `description: null` to clear it. Owner-org admin-only.
+   */
+  async editPackageListing(package_id, body) {
+    return this.request("POST", `/v1/packages/${encodeURIComponent(package_id)}/listing`, body);
+  }
   // --- Packages (registry reads + installations) ---
   // Authoring is server-side: apps via `POST /v1/apps/{id}/package-publish|release`,
   // content packages via the `publish_content`/`release_content` tools. There is no
@@ -45964,6 +45976,7 @@ var COMMANDS = [
   },
   {
     verbs: ["xlsx"],
+    ownsTail: true,
     help: [
       "  lotics xlsx <subcommand> ...         Read/write/edit .xlsx files on your local filesystem",
       "                                       (uses the bundled Lotics xlsx engine; prefer over",
@@ -45972,6 +45985,7 @@ var COMMANDS = [
   },
   {
     verbs: ["docx"],
+    ownsTail: true,
     help: [
       "  lotics docx <subcommand> ...         Read/write/edit .docx files on your local filesystem",
       "                                       (uses the bundled Lotics OOXML engine; preserves",
@@ -46003,6 +46017,32 @@ function renderCommandsHelp() {
 function knownVerbs() {
   return new Set(COMMANDS.flatMap((group) => [...group.verbs, ...group.aliases ?? []]));
 }
+var SUBCOMMAND_ARGS = /* @__PURE__ */ new Map([
+  ["xlsx read", { valueFlags: ["--sheet", "--range"], flags: ["--with-format"] }],
+  ["xlsx set-cell", { content: true }],
+  ["docx read", { flags: ["--include-opaque"] }],
+  ["docx append-paragraph", { flags: ["--style="], content: true }],
+  ["docx insert-paragraph", { flags: ["--style=", "--at="], content: true }],
+  ["docx delete-block", { flags: ["--at="] }],
+  ["docx replace-text", { content: true }]
+]);
+function commandOwnsTail(command) {
+  if (command === void 0) return false;
+  return COMMANDS.some(
+    (group) => group.ownsTail === true && [...group.verbs, ...group.aliases ?? []].includes(command)
+  );
+}
+function subcommandArgs(command, subcommand) {
+  if (command === void 0 || subcommand === void 0) return void 0;
+  return SUBCOMMAND_ARGS.get(`${command} ${subcommand}`);
+}
+function knownSubcommandFlags(command, subcommand) {
+  const spec = subcommandArgs(command, subcommand);
+  return [...spec?.valueFlags ?? [], ...spec?.flags ?? []];
+}
+function matchesKnownFlag(known, arg) {
+  return known.some((k) => k.endsWith("=") ? arg.startsWith(k) : arg === k);
+}
 
 // src/report_command.ts
 import fs6 from "node:fs";
@@ -46141,6 +46181,22 @@ function buildStarterTemplate(args) {
             typecheck: "tsc --noEmit",
             // Scope to src/ — oxlint's default scan walks node_modules too.
             lint: "oxlint src",
+            // No `--passWithNoTests`, deliberately. It would be justified by a
+            // TEMPORARY condition ("the scaffold seeds nothing") and then ship
+            // forever in every app's package.json and CI, where its only
+            // remaining effect is to turn "vitest discovered no test files" into
+            // success — a green suite over a renamed `src/`, a changed `include`
+            // or a broken vitest config, indefinitely. A detector that cannot
+            // fire when the thing is ABSENT rather than excessive is not one.
+            //
+            // What the scaffold seeds instead is `src/harness.test.ts`, which
+            // asserts the HARNESS and nothing else. The file it replaces
+            // (`src/App.test.tsx`) asserted the scaffold's placeholder copy
+            // ("First item"), so it failed the moment the author did the very
+            // thing the closing instructions tell them to do — edit
+            // `src/App.tsx` — and a smoke test that renders `<App/>` would fail
+            // the same way for any real app whose first screen reaches the host
+            // bridge on mount. The harness test touches neither.
             test: "vitest run"
           },
           dependencies: {
@@ -46716,15 +46772,33 @@ declare module "*.css";
 `
     },
     {
-      path: "src/App.test.tsx",
+      path: "src/harness.test.ts",
       content: `import { describe, test, expect } from "vitest";
-import { render } from "@testing-library/react";
-import App from "./App";
+import { getAppBinding } from "@lotics/app-sdk";
+
+/**
+ * The one test the scaffold seeds, and it is about the TEST SETUP rather than
+ * about your app \u2014 so editing src/App.tsx can never break it, and \`npm test\`
+ * never has to be green over zero tests.
+ *
+ * What it pins: tests run under jsdom, and vitest.setup.ts's echo stub answers
+ * for \`getAppBinding\`. That second one is the whole reason the setup file
+ * exists: a package-linked app's generated .lotics/app_fields.ts awaits it while
+ * a test file is still COLLECTING, so without the stub every test fails before
+ * any of them runs \u2014 including pure logic tests that never touch a field id.
+ *
+ * Delete it once you have tests of your own, or keep it; it costs nothing.
+ */
+describe("test harness", () => {
+  test("runs in a DOM", () => {
+    expect(typeof document).toBe("object");
+  });
 
-describe("App", () => {
-  test("renders the default route", () => {
-    const { container } = render(<App />);
-    expect(container.textContent).toContain("First item");
+  test("resolves the app binding from the setup stub, so the app graph collects", async () => {
+    const binding = await getAppBinding();
+    // The echo stub answers any alias with a self-identifying ':test:' id \u2014 one
+    // that can never be mistaken for a real fld_\u2026 from the workspace.
+    expect(binding.fields["anything.at.all"]).toContain(":test:");
   });
 });
 `
@@ -62911,7 +62985,20 @@ var readSourceSchema = zod_default.discriminatedUnion("from", [
   zod_default.object({ from: zod_default.literal("trigger_record") }),
   zod_default.object({ from: zod_default.literal("trigger_record_prev") }),
   zod_default.object({ from: zod_default.literal("trigger_changes") }),
-  zod_default.object({ from: zod_default.literal("foreach_item") }),
+  // `name` is the loop's bind name, and it is OPTIONAL for one reason: every
+  // body stored before names existed emits the bare form, and those resolve to
+  // the innermost frame — today's behaviour, and correct for any loop that is
+  // not nested. Without a name a read inside a NESTED loop cannot say which
+  // loop it means, so both binds resolve to the inner item and a join between
+  // two collections silently matches nothing. The parser emits the name now, so
+  // a body gets correct nesting the first time it is saved through it.
+  zod_default.object({ from: zod_default.literal("foreach_item"), name: zod_default.string().min(1).optional() }),
+  // No `name` here, deliberately: the JS surface spells the index as one
+  // reserved `index` keyword with no per-loop form, so the innermost loop is
+  // the only thing a read can mean. A name would be representable, honoured at
+  // run time, and silently rewritten to the innermost by the renderer — which
+  // prints every index as `index` — reintroducing the corruption above for a
+  // case nothing can author.
   zod_default.object({ from: zod_default.literal("foreach_index") }),
   zod_default.object({
     from: zod_default.literal("step_output"),
@@ -64810,7 +64897,14 @@ var formulaAggregateOperationSchema = external_exports.enum([
   "median",
   "min",
   "max",
-  "range"
+  "range",
+  "earliest",
+  "latest",
+  "date_range",
+  "checked",
+  "unchecked",
+  "percent_checked",
+  "percent_unchecked"
 ]);
 var rollupAggregateOperationSchema = external_exports.enum([
   "empty",
@@ -64910,25 +65004,25 @@ var aggregateOperationSchema = external_exports.enum([
   "string_agg"
 ]);
 var OPERATION_FIELD_TYPES = {
-  empty: ["text", "number", "date", "select", "select_member", "select_record_link", "files", "formula", "rollup"],
-  filled: ["text", "number", "date", "select", "select_member", "select_record_link", "files", "formula", "rollup"],
-  percent_empty: ["text", "number", "date", "select", "select_member", "select_record_link", "files", "formula", "rollup"],
-  percent_filled: ["text", "number", "date", "select", "select_member", "select_record_link", "files", "formula", "rollup"],
-  unique: ["text", "number", "date", "select", "select_member", "files", "formula", "rollup"],
-  percent_unique: ["text", "number", "date", "select", "select_member", "files", "formula", "rollup"],
+  empty: ["text", "number", "date", "select", "select_member", "select_record_link", "files", "formula", "rollup", "autonumber"],
+  filled: ["text", "number", "date", "select", "select_member", "select_record_link", "files", "formula", "rollup", "autonumber"],
+  percent_empty: ["text", "number", "date", "select", "select_member", "select_record_link", "files", "formula", "rollup", "autonumber"],
+  percent_filled: ["text", "number", "date", "select", "select_member", "select_record_link", "files", "formula", "rollup", "autonumber"],
+  unique: ["text", "number", "date", "select", "select_member", "files", "formula", "rollup", "autonumber"],
+  percent_unique: ["text", "number", "date", "select", "select_member", "files", "formula", "rollup", "autonumber"],
   sum: ["number", "formula", "rollup"],
   avg: ["number", "formula", "rollup"],
   median: ["number", "formula", "rollup"],
   min: ["number", "formula", "rollup"],
   max: ["number", "formula", "rollup"],
   range: ["number", "formula", "rollup"],
-  earliest: ["date", "rollup"],
-  latest: ["date", "rollup"],
-  date_range: ["date", "rollup"],
-  checked: ["boolean"],
-  unchecked: ["boolean"],
-  percent_checked: ["boolean"],
-  percent_unchecked: ["boolean"]
+  earliest: ["date", "formula", "rollup"],
+  latest: ["date", "formula", "rollup"],
+  date_range: ["date", "formula", "rollup"],
+  checked: ["boolean", "formula"],
+  unchecked: ["boolean", "formula"],
+  percent_checked: ["boolean", "formula"],
+  percent_unchecked: ["boolean", "formula"]
 };
 var FIELD_TYPE_OPERATIONS = /* @__PURE__ */ new Map();
 for (const [operation, fieldTypes] of Object.entries(OPERATION_FIELD_TYPES)) {
@@ -65608,8 +65702,7 @@ var appWorkflowInputRecordLinkSchema = appWorkflowInputBaseSchema.extend({
   table_id: zod_default.string().describe("Records must belong to this table. Validated at execute time + workflow save."),
   multi: zod_default.boolean().optional().describe("When true, accept an array of record_ids. Defaults to single.")
 });
-var appWorkflowInputSelectSchema = appWorkflowInputBaseSchema.extend({
-  type: zod_default.literal("select"),
+var selectOptionSourceShape = {
   options: zod_default.array(
     zod_default.object({
       label: zod_default.string(),
@@ -65617,20 +65710,27 @@ var appWorkflowInputSelectSchema = appWorkflowInputBaseSchema.extend({
     })
   ).min(1).optional().describe("Inline option set. Provide EITHER `options` OR `field`, never both."),
   field: zod_default.string().optional().describe(
-    "A select field's key (fld_\u2026) whose CURRENT options back this input \u2014 resolved at type-gen, validated at run time, drift-proof. Provide EITHER `field` OR `options`, never both."
+    "A select field's key (fld_\u2026) whose CURRENT options back this declaration \u2014 resolved at type-gen, validated at run time, drift-proof. Provide EITHER `field` OR `options`, never both."
   ),
   multi: zod_default.boolean().optional()
-}).check((ctx) => {
-  const hasOptions = ctx.value.options !== void 0;
-  const hasField = ctx.value.field !== void 0;
-  if (hasOptions === hasField) {
-    ctx.issues.push({
-      code: "custom",
-      input: ctx.value,
-      message: "select input must declare exactly one of `options` (inline) or `field` (a fld_\u2026 key resolved to the field's current options) \u2014 not both, not neither"
-    });
-  }
-});
+};
+function checkExactlyOneOptionSource(kind) {
+  return (ctx) => {
+    const hasOptions = ctx.value.options !== void 0;
+    const hasField = ctx.value.field !== void 0;
+    if (hasOptions === hasField) {
+      ctx.issues.push({
+        code: "custom",
+        input: ctx.value,
+        message: `select ${kind} must declare exactly one of \`options\` (inline) or \`field\` (a fld_\u2026 key resolved to the field's current options) \u2014 not both, not neither`
+      });
+    }
+  };
+}
+var appWorkflowInputSelectSchema = appWorkflowInputBaseSchema.extend({
+  type: zod_default.literal("select"),
+  ...selectOptionSourceShape
+}).check(checkExactlyOneOptionSource("input"));
 var appWorkflowInputDateRangeSchema = appWorkflowInputBaseSchema.extend({
   type: zod_default.literal("date_range"),
   include_time: zod_default.boolean().optional().describe("When true, the range includes time components (datetime). Defaults to false.")
@@ -65701,11 +65801,14 @@ var appWorkflowOutputSchema = zod_default.lazy(
       table_id: zod_default.string(),
       multi: zod_default.boolean().optional()
     }),
+    // The SAME shape and the SAME check as the select INPUT, not a copy of
+    // them: the two surfaces declare one vocabulary (GAP-294), so accepting
+    // `field` on one and not the other — or validating it differently — just
+    // moves the drift somewhere nobody looks.
     appWorkflowOutputBaseSchema.extend({
       type: zod_default.literal("select"),
-      options: zod_default.array(zod_default.object({ label: zod_default.string(), value: zod_default.string() })).min(1),
-      multi: zod_default.boolean().optional()
-    }),
+      ...selectOptionSourceShape
+    }).check(checkExactlyOneOptionSource("output")),
     appWorkflowOutputBaseSchema.extend({
       type: zod_default.literal("object"),
       fields: zod_default.record(zod_default.string(), appWorkflowOutputSchema)
@@ -66075,7 +66178,6 @@ __export(expression_array_exports, {
   includes: () => includes,
   intersection: () => intersection2,
   intersectionBy: () => intersectionBy,
-  isEmpty: () => isEmpty2,
   last: () => last2,
   list: () => list,
   maxBy: () => maxBy,
@@ -66530,13 +66632,6 @@ function size(arr) {
   }
   return arr.length;
 }
-function isEmpty2(arr) {
-  if (arr == null) return true;
-  if (!Array.isArray(arr)) {
-    throw new Error("isEmpty: expected array, got " + typeof arr);
-  }
-  return arr.length === 0;
-}
 function includes(collection, value2) {
   if (collection == null) return false;
   if (Array.isArray(collection)) return collection.includes(value2);
@@ -66807,6 +66902,7 @@ function capitalize(str) {
   return str.charAt(0).toUpperCase() + str.slice(1).toLowerCase();
 }
 function replace(str, search, replacement) {
+  if (str == null) return "";
   if (typeof str !== "string") {
     throw new Error("replace: expected string, got " + typeof str);
   }
@@ -66819,6 +66915,7 @@ function replace(str, search, replacement) {
   return str.replace(search, replacement);
 }
 function replaceAll(str, search, replacement) {
+  if (str == null) return "";
   if (typeof str !== "string") {
     throw new Error("replaceAll: expected string, got " + typeof str);
   }
@@ -66851,6 +66948,7 @@ function endsWith(str, suffix) {
   return str.endsWith(suffix);
 }
 function substring(str, start, end) {
+  if (str == null) return "";
   if (typeof str !== "string") {
     throw new Error("substring: expected string, got " + typeof str);
   }
@@ -66863,6 +66961,7 @@ function substring(str, start, end) {
   return str.substring(start, end);
 }
 function padStart(str, length2, char) {
+  if (str == null) return "";
   if (typeof str !== "string") {
     throw new Error("padStart: expected string, got " + typeof str);
   }
@@ -66875,6 +66974,7 @@ function padStart(str, length2, char) {
   return str.padStart(length2, char);
 }
 function padEnd(str, length2, char) {
+  if (str == null) return "";
   if (typeof str !== "string") {
     throw new Error("padEnd: expected string, got " + typeof str);
   }
@@ -66980,6 +67080,7 @@ function numberToWords(value2) {
   return negative ? "\xE2m " + result : result;
 }
 function formatNumber(value2, decimals) {
+  if (value2 == null) return "";
   if (typeof value2 !== "number" || Number.isNaN(value2)) {
     throw new Error("formatNumber: expected number, got " + typeof value2);
   }
@@ -67007,15 +67108,17 @@ __export(expression_math_exports, {
   sum: () => sum
 });
 function mean(arr) {
-  if (arr == null || !Array.isArray(arr)) {
+  if (arr == null) return null;
+  if (!Array.isArray(arr)) {
     throw new Error("mean: expected array, got " + typeof arr);
   }
-  if (arr.length === 0) {
-    throw new Error("mean: array cannot be empty");
+  const present = arr.filter((item) => item != null);
+  if (present.length === 0) {
+    return null;
   }
-  const numArr = arr;
-  const sum2 = numArr.reduce((a, b) => a + b, 0);
-  const result = sum2 / numArr.length;
+  const numArr = present;
+  const total = numArr.reduce((a, b) => a + b, 0);
+  const result = total / numArr.length;
   if (isNaN(result)) {
     throw new Error("mean: array contains non-numeric values");
   }
@@ -67028,7 +67131,7 @@ function min(...values3) {
   if (values3.length === 1 && Array.isArray(values3[0])) {
     const arr = values3[0];
     if (arr.length === 0) {
-      throw new Error("min: array cannot be empty");
+      return null;
     }
     return arr.reduce((minVal, item) => {
       if (minVal == null) return item;
@@ -67037,9 +67140,9 @@ function min(...values3) {
         return item < minVal ? item : minVal;
       }
       return String(item) < String(minVal) ? item : minVal;
-    });
+    }) ?? null;
   }
-  return values3.reduce((minVal, item) => {
+  const smallest = values3.reduce((minVal, item) => {
     if (minVal == null) return item;
     if (item == null) return minVal;
     if (typeof minVal === "number" && typeof item === "number") {
@@ -67047,6 +67150,7 @@ function min(...values3) {
     }
     return String(item) < String(minVal) ? item : minVal;
   });
+  return smallest ?? null;
 }
 function max(...values3) {
   if (values3.length === 0) {
@@ -67055,7 +67159,7 @@ function max(...values3) {
   if (values3.length === 1 && Array.isArray(values3[0])) {
     const arr = values3[0];
     if (arr.length === 0) {
-      throw new Error("max: array cannot be empty");
+      return null;
     }
     return arr.reduce((maxVal, item) => {
       if (maxVal == null) return item;
@@ -67064,9 +67168,9 @@ function max(...values3) {
         return item > maxVal ? item : maxVal;
       }
       return String(item) > String(maxVal) ? item : maxVal;
-    });
+    }) ?? null;
   }
-  return values3.reduce((maxVal, item) => {
+  const largest = values3.reduce((maxVal, item) => {
     if (maxVal == null) return item;
     if (item == null) return maxVal;
     if (typeof maxVal === "number" && typeof item === "number") {
@@ -67074,8 +67178,10 @@ function max(...values3) {
     }
     return String(item) > String(maxVal) ? item : maxVal;
   });
+  return largest ?? null;
 }
 function round(value2, precision) {
+  if (value2 == null) return null;
   if (typeof value2 !== "number") {
     throw new Error("round: expected number, got " + typeof value2);
   }
@@ -67094,24 +67200,28 @@ function sum(arr) {
   return arr.reduce((a, b) => a + b, 0);
 }
 function abs(n) {
+  if (n == null) return null;
   if (typeof n !== "number") {
     throw new Error("abs: expected number, got " + typeof n);
   }
   return Math.abs(n);
 }
 function ceil(n) {
+  if (n == null) return null;
   if (typeof n !== "number") {
     throw new Error("ceil: expected number, got " + typeof n);
   }
   return Math.ceil(n);
 }
 function floor(n) {
+  if (n == null) return null;
   if (typeof n !== "number") {
     throw new Error("floor: expected number, got " + typeof n);
   }
   return Math.floor(n);
 }
 function clamp(n, min2, max3) {
+  if (n == null) return null;
   if (typeof n !== "number") {
     throw new Error("clamp: expected number, got " + typeof n);
   }
@@ -67129,6 +67239,7 @@ function clamp(n, min2, max3) {
   return n;
 }
 function percentage(part, total, decimals) {
+  if (part == null || total == null) return null;
   if (typeof part !== "number") {
     throw new Error("percentage: part must be a number");
   }
@@ -67149,6 +67260,7 @@ function percentage(part, total, decimals) {
   return percent;
 }
 function pow(base, exponent) {
+  if (base == null || exponent == null) return null;
   if (typeof base !== "number") {
     throw new Error("pow: base must be a number");
   }
@@ -67158,6 +67270,7 @@ function pow(base, exponent) {
   return Math.pow(base, exponent);
 }
 function sqrt(n) {
+  if (n == null) return null;
   if (typeof n !== "number") {
     throw new Error("sqrt: expected number, got " + typeof n);
   }
@@ -67167,6 +67280,7 @@ function sqrt(n) {
   return Math.sqrt(n);
 }
 function mod(n, divisor) {
+  if (n == null || divisor == null) return null;
   if (typeof n !== "number") {
     throw new Error("mod: expected number, got " + typeof n);
   }
@@ -67339,7 +67453,7 @@ __export(expression_type_exports, {
   coalesce: () => coalesce,
   isArray: () => isArray2,
   isBoolean: () => isBoolean,
-  isEmpty: () => isEmpty3,
+  isEmpty: () => isEmpty2,
   isNotNull: () => isNotNull,
   isNull: () => isNull,
   isNumber: () => isNumber,
@@ -67351,6 +67465,22 @@ __export(expression_type_exports, {
   toString: () => toString,
   typeOf: () => typeOf
 });
+
+// ../shared/src/schemas/database_types.ts
+function isEmptyFieldValue(value2) {
+  if (value2 === null || value2 === void 0) {
+    return true;
+  }
+  if (typeof value2 === "string") {
+    return value2 === "";
+  }
+  if (Array.isArray(value2)) {
+    return value2.length === 0;
+  }
+  return false;
+}
+
+// ../shared/src/expression_type.ts
 function isArray2(val) {
   return Array.isArray(val);
 }
@@ -67373,6 +67503,7 @@ function coalesce(...values3) {
   return void 0;
 }
 function toNumber(val) {
+  if (val == null) return null;
   if (typeof val === "number") return val;
   if (typeof val === "string") {
     const parsed = parseFloat(val);
@@ -67384,9 +67515,7 @@ function toNumber(val) {
   throw new Error("toNumber: expected number or string, got " + typeof val);
 }
 function toString(val) {
-  if (val == null) {
-    throw new Error("toString: cannot convert null or undefined to string");
-  }
+  if (val == null) return "";
   return String(val);
 }
 function isNull(val) {
@@ -67395,13 +67524,11 @@ function isNull(val) {
 function isNotNull(val) {
   return !isNull(val);
 }
-function isEmpty3(val) {
-  if (val === null || val === void 0) return true;
-  if (typeof val === "string") return val.length === 0;
-  if (Array.isArray(val)) return val.length === 0;
-  return false;
+function isEmpty2(val) {
+  return isEmptyFieldValue(val);
 }
 function parseJson(value2) {
+  if (value2 == null) return null;
   if (typeof value2 !== "string") {
     throw new Error("parseJson: expected a JSON string, got " + typeof value2);
   }
@@ -69066,7 +69193,7 @@ function walkRead(node, scope) {
     return readFromLambdaParam(root, chain2);
   }
   if (scope.foreachBinds.includes(root)) {
-    return readFromForeachItem(chain2);
+    return readFromForeachItem(root, chain2);
   }
   if (scope.stepIds.has(root)) {
     return readFromStepOutput(root, chain2);
@@ -69192,10 +69319,13 @@ function readFromRuntime(chain2) {
     return { kind: "read", source, path: path14 };
   });
 }
-function readFromForeachItem(chain2) {
+function readFromForeachItem(name2, chain2) {
   return wrapOptionalGuards(chain2, (segments) => ({
     kind: "read",
-    source: { from: "foreach_item" },
+    // NAMED, so a read inside a nested loop says which loop it means. Without
+    // it both binds resolved to the innermost item, and a join between two
+    // collections matched nothing while the workflow reported success.
+    source: { from: "foreach_item", name: name2 },
     path: classifyRecordPath(segments)
   }));
 }
@@ -70151,7 +70281,11 @@ function walkForOf(stmt, scope, stepIds, opts, stepId, description, nextSyntheti
         type: "bind",
         expression: patternEntryExpression(entry, {
           kind: "read",
-          source: { from: "foreach_item" },
+          // The loop's synthetic bind name, stated rather than left to the
+          // innermost-frame fallback — these bind steps happen to run where
+          // this loop IS innermost, and naming it keeps that true if the
+          // lowering ever moves.
+          source: { from: "foreach_item", name: bindName },
           path: [entry.segment]
         })
       });
@@ -71002,7 +71136,10 @@ ${args.instructions.replace(/\s+$/, "")}
 `;
 }
 function stripAgentHeader(text) {
-  return text.replace(/<!--\s*lotics:[\s\S]*?-->\n?/g, "").replace(/\n{3,}/g, "\n\n").trim();
+  return normalizeAgentInstructions(text.replace(/<!--\s*lotics:[\s\S]*?-->\n?/g, ""));
+}
+function normalizeAgentInstructions(text) {
+  return text.replace(/\n{3,}/g, "\n\n").trim();
 }
 
 // src/npm_registry.ts
@@ -71121,6 +71258,49 @@ function writeSynced(projectDir, kind, alias, entry) {
   pkg2.lotics.synced[kind] = { ...pkg2.lotics.synced[kind], [alias]: entry };
   fs8.writeFileSync(pkgPath2, JSON.stringify(pkg2, null, 2) + "\n");
 }
+function readManifestEntry(projectDir, kind, alias) {
+  const pkg2 = readManifest(projectDir);
+  if (!pkg2.lotics) return { found: false };
+  const entry = { found: true };
+  let found = false;
+  const declarations = pkg2.lotics[kind];
+  if (declarations && typeof declarations === "object" && !Array.isArray(declarations)) {
+    const map3 = declarations;
+    if (alias in map3) {
+      entry.declaration = map3[alias];
+      found = true;
+    }
+  }
+  const baselines = pkg2.lotics.synced?.[kind];
+  if (baselines && alias in baselines) {
+    entry.synced = baselines[alias];
+    found = true;
+  }
+  return found ? entry : { found: false };
+}
+function readManifest(projectDir) {
+  const pkgPath2 = path10.join(projectDir, "package.json");
+  return JSON.parse(fs8.readFileSync(pkgPath2, "utf-8"));
+}
+function removeFromManifest(projectDir, kind, alias) {
+  const pkgPath2 = path10.join(projectDir, "package.json");
+  const pkg2 = readManifest(projectDir);
+  if (!pkg2.lotics) return;
+  const declarations = pkg2.lotics[kind];
+  if (declarations && typeof declarations === "object" && !Array.isArray(declarations)) {
+    delete declarations[alias];
+  }
+  const baselines = pkg2.lotics.synced?.[kind];
+  if (baselines) delete baselines[alias];
+  fs8.writeFileSync(pkgPath2, JSON.stringify(pkg2, null, 2) + "\n");
+}
+function parkPrunedDeclaration(projectDir, kind, alias, removed) {
+  const dir = path10.join(projectDir, ".lotics", "pruned", kind);
+  fs8.mkdirSync(dir, { recursive: true });
+  const file2 = path10.join(dir, `${alias}.json`);
+  fs8.writeFileSync(file2, JSON.stringify(removed, null, 2) + "\n");
+  return path10.relative(projectDir, file2);
+}
 var WORKFLOWS_DIR = path10.join("src", "workflows");
 var WORKFLOW_GLOBALS_DIR = path10.join(".lotics", "workflows");
 var AGENTS_DIR = path10.join("src", "agents");
@@ -71270,13 +71450,52 @@ function writeAgentFiles(projectDir, agents, opts) {
   }
   return written;
 }
+function parkLiveAgentProse(projectDir, alias, instructions) {
+  const dir = path10.join(projectDir, ".lotics", "agents");
+  const file2 = path10.join(dir, `${alias}.live.md`);
+  try {
+    fs8.mkdirSync(dir, { recursive: true });
+    fs8.writeFileSync(file2, normalizeAgentInstructions(instructions) + "\n");
+    return path10.relative(projectDir, file2);
+  } catch (err2) {
+    console.error(
+      `\u26A0 Could not write the live prose for ${alias} to ${path10.relative(projectDir, file2)}: ${err2 instanceof Error ? err2.message : String(err2)}`
+    );
+    return null;
+  }
+}
+function reportUnseenLive(kind, unseen, appId) {
+  if (unseen.length === 0) return;
+  const plural = unseen.length === 1;
+  console.error(
+    `
+\u26A0 Kept your ${plural ? kind : `${kind}s`} for ` + unseen.map((u) => u.parked ? `${u.alias} (live copy written to ${u.parked})` : u.alias).join(", ") + ` \u2014 and the live ${kind} has CHANGED since this checkout last saw it, so somebody else edited ${plural ? "it" : "them"}.
+  Your next deploy will be REFUSED for ${plural ? "this alias" : "these aliases"}, which is the point: pushing would overwrite their edit.
+  Merge what you want from the live copy into your file and deploy, or run 'lotics app pull ${appId} --force' to take the live version and discard yours.`
+  );
+}
+function parkLiveWorkflowBody(projectDir, alias, source) {
+  const dir = path10.join(projectDir, WORKFLOW_GLOBALS_DIR);
+  const file2 = path10.join(dir, `${alias}.live.ts`);
+  try {
+    fs8.mkdirSync(dir, { recursive: true });
+    fs8.writeFileSync(file2, normalizeWorkflowBody(source) + "\n");
+    return path10.relative(projectDir, file2);
+  } catch (err2) {
+    console.error(
+      `\u26A0 Could not write the live body for ${alias} to ${path10.relative(projectDir, file2)}: ${err2 instanceof Error ? err2.message : String(err2)}`
+    );
+    return null;
+  }
+}
 function localPromptUnpushed(projectDir, alias, live) {
   const file2 = agentFilePath2(projectDir, alias);
   if (!fs8.existsSync(file2)) return false;
-  const onDisk = fs8.readFileSync(file2, "utf-8");
+  const onDisk = stripAgentHeader(fs8.readFileSync(file2, "utf-8"));
+  if (onDisk === normalizeAgentInstructions(live)) return false;
   const baseline = readSynced(projectDir).agents[alias]?.content;
-  if (baseline === void 0) return stripAgentHeader(onDisk).trim() !== live.trim();
-  return contentSha(stripAgentHeader(onDisk)) !== baseline;
+  if (baseline === void 0) return true;
+  return contentSha(onDisk) !== baseline;
 }
 function generatedWorkflowDescription(appName, alias) {
   return `Workflow invoked by app "${appName}" via useWorkflow("${alias}").`;
@@ -71285,14 +71504,15 @@ function localBodyUnpushed(projectDir, alias, live) {
   const file2 = workflowFilePath(projectDir, alias);
   if (!fs8.existsSync(file2)) return false;
   const onDisk = fs8.readFileSync(file2, "utf-8");
+  if (stripWorkflowHeader(onDisk).trim() === normalizeWorkflowBody(live).trim()) return false;
   const baseline = readSynced(projectDir).workflows[alias]?.content;
-  if (baseline === void 0) {
-    return stripWorkflowHeader(onDisk).trim() !== normalizeWorkflowBody(live).trim();
-  }
+  if (baseline === void 0) return true;
   return contentSha(stripWorkflowHeader(onDisk)) !== baseline;
 }
 async function writeWorkflowFiles(client, projectDir, app_id, appName, workflows, opts) {
   const written = [];
+  const kept = [];
+  const unseenLive = [];
   for (const [alias, declaration] of Object.entries(workflows)) {
     const res = await client.getAppWorkflow(app_id, alias);
     if (res.error && !isMissingWorkflowBodyError(res.error)) {
@@ -71317,7 +71537,16 @@ async function writeWorkflowFiles(client, projectDir, app_id, appName, workflows
       toWorkflowDtsDeclaration(declaration)
     );
     if (!opts.overwrite && localBodyUnpushed(projectDir, alias, source)) {
-      opts.kept.push(`src/workflows/${alias}.ts`);
+      kept.push(`src/workflows/${alias}.ts`);
+      const previous = readSynced(projectDir).workflows[alias];
+      if (body_sha && (previous?.live === void 0 || previous.live === body_sha)) {
+        writeSynced(projectDir, "workflows", alias, { ...previous, live: body_sha });
+      } else if (body_sha) {
+        unseenLive.push({
+          alias,
+          parked: parkLiveWorkflowBody(projectDir, alias, source)
+        });
+      }
       continue;
     }
     writeWorkflowFile(projectDir, alias, source, envelope2);
@@ -71341,7 +71570,7 @@ async function writeWorkflowFiles(client, projectDir, app_id, appName, workflows
     }
     written.push(alias);
   }
-  return written;
+  return { written, kept, unseenLive };
 }
 function writeWorkflowDescription(projectDir, alias, description) {
   const pkgPath2 = path10.join(projectDir, "package.json");
@@ -72041,15 +72270,21 @@ async function hydrateAppProject(client, targetPath, app, opts) {
   );
   const workflows = app.workflows ?? {};
   if (Object.keys(workflows).length > 0) {
-    const written = await writeWorkflowFiles(client, targetPath, app.id, app.name, workflows, {
-      overwrite: opts.force === true,
-      kept: opts.kept
-    });
+    const { written, kept, unseenLive } = await writeWorkflowFiles(
+      client,
+      targetPath,
+      app.id,
+      app.name,
+      workflows,
+      { overwrite: opts.force === true }
+    );
+    opts.kept.push(...kept);
     if (written.length > 0) {
       console.error(
         `Wrote ${written.length} workflow ${written.length === 1 ? "body" : "bodies"} to ${WORKFLOWS_DIR}/ (${written.join(", ")})`
       );
     }
+    reportUnseenLive("workflow body", unseenLive, app.id);
   }
   const agents = app.agents ?? {};
   if (Object.keys(agents).length > 0) {
@@ -72057,17 +72292,31 @@ async function hydrateAppProject(client, targetPath, app, opts) {
       overwrite: opts.force === true,
       kept: opts.kept
     });
-    for (const alias of written) {
-      const instructions = agents[alias]?.instructions;
-      if (instructions === void 0) continue;
-      const sha = contentSha(instructions);
-      writeSynced(targetPath, "agents", alias, { content: sha, live: sha });
+    const unseenLiveProse = [];
+    for (const [alias, declaration] of Object.entries(agents)) {
+      const instructions = declaration?.instructions;
+      if (typeof instructions !== "string") continue;
+      const live = contentSha(instructions);
+      if (written.includes(alias)) {
+        writeSynced(targetPath, "agents", alias, {
+          content: contentSha(normalizeAgentInstructions(instructions)),
+          live
+        });
+        continue;
+      }
+      const previous = readSynced(targetPath).agents[alias];
+      if (previous?.live === void 0 || previous.live === live) {
+        writeSynced(targetPath, "agents", alias, { ...previous, live });
+        continue;
+      }
+      unseenLiveProse.push({ alias, parked: parkLiveAgentProse(targetPath, alias, instructions) });
     }
     if (written.length > 0) {
       console.error(
         `Wrote ${written.length} agent instruction ${written.length === 1 ? "file" : "files"} to ${AGENTS_DIR}/ (${written.join(", ")})`
       );
     }
+    reportUnseenLive("prompt", unseenLiveProse, app.id);
   }
   await runNpmInstall(targetPath);
   writeAppDtsKitLinks(targetPath);
@@ -72090,16 +72339,17 @@ async function appPull(client, args) {
   console.error(`Downloading source archive...`);
   await downloadToFile(sourceUrl, tmpFile);
   const keptLocal = [];
+  const restoredFromArchive = [];
   const stagingDir = fs8.mkdtempSync(path10.join(tmpdir(), `lotics-pull-${app.id}-`));
   try {
     await runTar(["-xzf", tmpFile, "-C", stagingDir], stagingDir);
     console.error(`Extracting to ${targetPath}...`);
-    keptLocal.push(
-      ...copyTree(stagingDir, targetPath, {
-        overwrite: args.force === true,
-        skip: [WORKFLOWS_DIR, AGENTS_DIR].map((d) => d.split(path10.sep).join("/"))
-      })
-    );
+    const copied = copyTree(stagingDir, targetPath, {
+      overwrite: args.force === true,
+      skip: [WORKFLOWS_DIR, AGENTS_DIR].map((d) => d.split(path10.sep).join("/"))
+    });
+    keptLocal.push(...copied.kept);
+    restoredFromArchive.push(...copied.created);
   } finally {
     if (fs8.existsSync(tmpFile)) fs8.unlinkSync(tmpFile);
     fs8.rmSync(stagingDir, { recursive: true, force: true });
@@ -72114,6 +72364,7 @@ async function appPull(client, args) {
     ...args.force !== void 0 ? { force: args.force } : {},
     kept: keptLocal
   });
+  reportRestoredFiles(restoredFromArchive, prior !== null);
   reportKeptLocalFiles(keptLocal, app.id, {
     // `prior` is non-null whenever the stamp was held — `stampAfterPull` cannot
     // hold against nothing — so the fallback only covers the un-held branch,
@@ -72275,7 +72526,8 @@ async function appDeploy(client, args) {
         if (args.prune) {
           await pruneOrphanedBindings(
             client,
-            meta3.app_id,
+            projectDir,
+            { app_id: meta3.app_id },
             orphanedBindings(called, liveAfter),
             called.dynamic
           );
@@ -72443,7 +72695,7 @@ function driftedAgentAliases(projectDir, liveAgents) {
     const file2 = agentFilePath2(projectDir, alias);
     if (!fs8.existsSync(file2)) continue;
     const local = stripAgentHeader(fs8.readFileSync(file2, "utf-8"));
-    if (local === "" || local === (live.instructions ?? "")) continue;
+    if (local === "" || local === normalizeAgentInstructions(live.instructions ?? "")) continue;
     drifted.push(alias);
   }
   return drifted.sort();
@@ -72505,28 +72757,31 @@ function warnAboutOrphanedBindings(called, live) {
   );
   return lines.length;
 }
-async function pruneOrphanedBindings(client, appId, orphans, dynamic) {
+async function pruneOrphanedBindings(client, projectDir, app, orphans, dynamic) {
   const targets = [
     ...orphans.queries.map((alias) => ({
       tool: "remove_app_query",
+      kind: "queries",
       alias,
       label: `query ${alias}`,
-      restore: `lotics app query set ${alias}`
+      setCommand: `lotics app query set ${alias}`
     })),
     ...orphans.workflows.map((alias) => ({
       tool: "remove_app_workflow",
+      kind: "workflows",
       alias,
       label: `workflow ${alias}`,
-      restore: `lotics app workflow set ${alias}`
+      setCommand: `lotics app workflow set ${alias}`
     })),
     ...orphans.agents.map((alias) => ({
       tool: "remove_app_agent",
+      kind: "agents",
       alias,
       label: `agent ${alias}`,
-      restore: `lotics app agent set ${alias}`
+      setCommand: `lotics app agent set ${alias}`
     }))
   ];
-  if (targets.length === 0) return 0;
+  if (targets.length === 0) return;
   if (dynamic.length > 0) {
     console.error(
       `
@@ -72534,19 +72789,63 @@ async function pruneOrphanedBindings(client, appId, orphans, dynamic) {
 ` + targets.map((t) => `    \u2022 ${t.label}`).join("\n") + `
   Make those call sites literal and the next deploy will clean them up, or remove the ones you know are dead by hand.`
     );
-    return targets.length;
+    return;
   }
-  let failed = 0;
+  const tablesBefore = new Set(resolveCodegenTableIds(projectDir, readAppMeta(projectDir).queries ?? {}));
+  let removedLocally = false;
   for (const target of targets) {
-    const res = await client.execute(target.tool, { app_id: appId, alias: target.alias });
+    const res = await client.execute(target.tool, { app_id: app.app_id, alias: target.alias });
     if (res.error) {
-      failed += 1;
       console.error(`  \u2717 could not unbind ${target.label} \u2014 ${res.error}`);
       continue;
     }
-    console.error(`  \u2713 unbound ${target.label} \u2014 restore: ${target.restore}`);
+    let line;
+    try {
+      const entry = readManifestEntry(projectDir, target.kind, target.alias);
+      if (entry.found) {
+        const parked = parkPrunedDeclaration(projectDir, target.kind, target.alias, {
+          declaration: entry.declaration,
+          synced: entry.synced
+        });
+        removeFromManifest(projectDir, target.kind, target.alias);
+        removedLocally = true;
+        line = `  \u2713 unbound ${target.label} + removed package.json#lotics.${target.kind}.${target.alias} \u2014 restore: put ${parked} back under lotics.${target.kind}.${target.alias}, then ${target.setCommand}`;
+      } else {
+        line = `  \u2713 unbound ${target.label} \u2014 nothing was declared for it in package.json, so there is nothing to restore from this project (recover it with lotics app pull --from-version <apv_\u2026>)`;
+      }
+    } catch (err2) {
+      console.error(
+        `  \u2713 unbound ${target.label} server-side, but could not update the local project \u2014 ${err2 instanceof Error ? err2.message : String(err2)}. lotics.${target.kind}.${target.alias} is still declared: remove it by hand, or the next deploy re-creates the binding.`
+      );
+      continue;
+    }
+    console.error(line);
+  }
+  if (removedLocally) {
+    try {
+      const meta3 = readAppMeta(projectDir);
+      writeAppDts(projectDir, {
+        workflows: meta3.workflows,
+        queries: meta3.queries,
+        agents: meta3.agents
+      });
+      if (orphans.queries.length > 0) {
+        const dropped = [...tablesBefore].filter(
+          (id) => !resolveCodegenTableIds(projectDir, meta3.queries ?? {}).includes(id)
+        );
+        if (dropped.length > 0) {
+          console.error(
+            `  \u26A0 .lotics/app_fields.ts no longer covers ${dropped.join(", ")} \u2014 ${dropped.length === 1 ? "that table was" : "those tables were"} named only by the pruned quer${orphans.queries.length === 1 ? "y" : "ies"}. If your source still uses F/OPT for ${dropped.length === 1 ? "it" : "them"}, add ${dropped.map((id) => `"${id}"`).join(", ")} to package.json#lotics.codegen.tables and re-run lotics app codegen.`
+          );
+        }
+        await writeGeneratedAppFields(client, projectDir, app, meta3.queries ?? {});
+      }
+    } catch (err2) {
+      console.error(
+        `  \u2717 could not refresh the generated companions after pruning \u2014 ${err2 instanceof Error ? err2.message : String(err2)}. Run lotics app codegen.`
+      );
+    }
   }
-  return failed;
 }
 function derivedDeployMessage(pending) {
   const parts = [
@@ -72558,6 +72857,7 @@ function derivedDeployMessage(pending) {
 }
 function copyTree(from, to, opts, relative = "") {
   const kept = [];
+  const created = [];
   for (const entry of fs8.readdirSync(from, { withFileTypes: true })) {
     const src = path10.join(from, entry.name);
     const dest = path10.join(to, entry.name);
@@ -72565,17 +72865,32 @@ function copyTree(from, to, opts, relative = "") {
     if (opts.skip?.includes(rel.split(path10.sep).join("/"))) continue;
     if (entry.isDirectory()) {
       fs8.mkdirSync(dest, { recursive: true });
-      kept.push(...copyTree(src, dest, opts, rel));
+      const child = copyTree(src, dest, opts, rel);
+      kept.push(...child.kept);
+      created.push(...child.created);
       continue;
     }
-    if (!opts.overwrite && fs8.existsSync(dest)) {
+    const existed = fs8.existsSync(dest);
+    if (!opts.overwrite && existed) {
       if (fs8.readFileSync(src).equals(fs8.readFileSync(dest))) continue;
       kept.push(rel);
       continue;
     }
     fs8.copyFileSync(src, dest);
+    if (!existed) created.push(rel);
   }
-  return kept;
+  return { kept, created };
+}
+function reportRestoredFiles(restored, isRefresh) {
+  if (!isRefresh || restored.length === 0) return;
+  const shown = restored.slice(0, 10);
+  console.error(
+    `
+Restored ${restored.length} file${restored.length === 1 ? "" : "s"} the app's last deployed source carries and your tree did not:
+` + shown.map((f) => `  \u2022 ${f}`).join("\n") + (restored.length > shown.length ? `
+  \u2022 \u2026and ${restored.length - shown.length} more` : "") + `
+  A pull mirrors the last DEPLOYED source, so a file you deleted here comes back until the deletion ships. Delete it again and run 'lotics app deploy' to make it stick.`
+  );
 }
 function reportKeptLocalFiles(kept, appId, motion) {
   if (kept.length === 0) return;
@@ -73135,15 +73450,19 @@ async function appWorkflowPull(client, args = {}) {
     console.error(`App ${meta3.app_id} has no bound workflows.`);
     return;
   }
-  const kept = [];
-  const written = await writeWorkflowFiles(client, projectDir, meta3.app_id, app.name, workflows, {
-    overwrite: args.force === true,
-    kept
-  });
+  const { written, kept, unseenLive } = await writeWorkflowFiles(
+    client,
+    projectDir,
+    meta3.app_id,
+    app.name,
+    workflows,
+    { overwrite: args.force === true }
+  );
   console.error(
     `Wrote ${written.length} workflow ${written.length === 1 ? "body" : "bodies"} to ${WORKFLOWS_DIR}/` + (written.length > 0 ? ` (${written.join(", ")})` : "")
   );
   reportKeptLocalFiles(kept, meta3.app_id, null);
+  reportUnseenLive("workflow body", unseenLive, meta3.app_id);
   ensureAppTsconfig(projectDir);
 }
 async function appWorkflowCheck(args) {
@@ -73291,6 +73610,23 @@ function parseArgs(argv) {
   let i2 = 0;
   while (i2 < argv.length) {
     const arg = argv[i2];
+    if (subcommand !== void 0 && commandOwnsTail(command) && arg !== "--help" && arg !== "-h") {
+      const local = subcommandArgs(command, subcommand);
+      const looksLikeFlag = arg.length > 1 && arg.startsWith("-");
+      const declared = looksLikeFlag && local !== void 0 && matchesKnownFlag([...local.valueFlags ?? [], ...local.flags ?? []], arg);
+      if (declared) {
+        restArgs.push(arg);
+        if ((local?.valueFlags ?? []).includes(arg) && i2 + 1 < argv.length) restArgs.push(argv[++i2]);
+      } else if (looksLikeFlag && local?.content !== true) {
+        unknownFlag = arg;
+      } else if (!toolArgs) {
+        toolArgs = arg;
+      } else {
+        restArgs.push(arg);
+      }
+      i2++;
+      continue;
+    }
     switch (arg) {
       case "--json":
         flags.json = true;
@@ -73715,11 +74051,13 @@ var CliError = class extends Error {
 function fail2(message2) {
   throw new CliError(message2);
 }
-function rejectUnknownFlags(rest2, known, usage) {
-  const matches = (a) => known.some((k) => k.endsWith("=") ? a.startsWith(k) : a === k);
-  const unknown2 = rest2.filter((a) => a.startsWith("--") && !matches(a));
+function rejectUnknownFlags(rest2, command, subcommand) {
+  const known = knownSubcommandFlags(command, subcommand);
+  const unknown2 = rest2.filter((a) => a.startsWith("--") && !matchesKnownFlag(known, a));
   if (unknown2.length === 0) return;
-  fail2(`Unknown ${unknown2.length > 1 ? "flags" : "flag"} for ${usage}: ${unknown2.join(", ")}. Supported: ${known.join(", ")}.`);
+  fail2(
+    `Unknown ${unknown2.length > 1 ? "flags" : "flag"} for ${command} ${subcommand}: ${unknown2.join(", ")}. Supported: ${known.join(", ")}.`
+  );
 }
 function rejectExtraArgs(rest2, arity, usage) {
   if (rest2.length <= arity) return;
@@ -94808,6 +95146,37 @@ function collectRecomputeReport(workbook, unreadable) {
   return { total, unevaluated };
 }
 
+// ../xlsx/src/numfmt_type.ts
+function classifyNumFmt(code) {
+  if (!code || code === "General") return "general";
+  const first3 = code.split(";")[0] ?? code;
+  const currency = hasCurrencyTokens(first3);
+  const stripped = stripQuotedLiterals(first3);
+  if (stripped.trim() === "@") return "text";
+  if (hasDateTokens(stripped)) return "date";
+  if (stripped.includes("%")) return "percent";
+  if (currency) return "currency";
+  if (/[#0?]/.test(stripped)) return "numeric";
+  return "general";
+}
+function stripQuotedLiterals(code) {
+  return code.replace(/"[^"]*"/g, "").replace(/\\./g, " ");
+}
+function hasDateTokens(code) {
+  if (/\b(y{1,4}|d{1,4}|h{1,2}|s{1,2}|am\/pm|a\/p)\b/i.test(code)) return true;
+  if (/[ymdhs]\s*[-\/.:\s]\s*m/i.test(code)) return true;
+  if (/m\s*[-\/.:\s]\s*[ymdhs]/i.test(code)) return true;
+  return false;
+}
+function hasCurrencyTokens(code) {
+  if (/[$¥€£₫¢]/.test(code)) return true;
+  if (/\[\$/.test(code)) return true;
+  return false;
+}
+function isPaddedIdentifier(input) {
+  return /^[+-]?0\d/.test(input);
+}
+
 // ../xlsx/src/clipboard.ts
 function adjustFormulaRefsForRowShift(formula, atRow, delta) {
   return formula.replace(
@@ -94835,17 +95204,18 @@ function adjustFormulaRefsForColShift(formula, atCol, delta) {
 }
 
 // ../xlsx/src/spreadsheet_commands.ts
-function setCellValueCommand(workbook, engine, sheetIndex, row, col, newValue) {
+function setCellValueCommand(workbook, engine, sheetIndex, row, col, newValue, options) {
   const sheet = workbook.sheets[sheetIndex];
   const ref2 = rowColToRef(row, col);
   const oldCell = sheet.getCell(ref2);
   const oldValue = oldCell?.value ?? null;
   const oldFormula = oldCell?.formula;
-  const isFormula = newValue.startsWith("=");
-  const formula = isFormula ? newValue.slice(1) : void 0;
-  const value2 = isFormula ? null : parseInputValue(newValue);
   const styleIndex = oldCell?.styleIndex ?? 0;
   const numFmtCode = oldCell?.numFmtCode ?? "General";
+  const isText = typeof newValue === "string" && options?.typed !== true;
+  const isFormula = isText && newValue.startsWith("=");
+  const formula = isFormula ? newValue.slice(1) : void 0;
+  const value2 = isFormula ? null : isText ? parseInputValue(newValue, numFmtCode) : newValue;
   return {
     description: `Set ${ref2} = ${newValue}`,
     execute() {
@@ -95384,6 +95754,43 @@ function deleteColsCommand(workbook, sheetIndex, at2, count) {
     }
   };
 }
+function setRangeNumFmtCommand(workbook, sheetIndex, startRow, startCol, endRow, endCol, numFmtCode) {
+  const sheet = workbook.sheets[sheetIndex];
+  const snapshot = /* @__PURE__ */ new Map();
+  for (let r = startRow; r <= endRow; r++) {
+    for (let c = startCol; c <= endCol; c++) {
+      const ref2 = rowColToRef(r, c);
+      const cell = sheet.getCell(ref2);
+      snapshot.set(ref2, cell ? { value: cell.value, styleIndex: cell.styleIndex, numFmtCode: cell.numFmtCode, formula: cell.formula } : null);
+    }
+  }
+  const rangeRef = `${rowColToRef(startRow, startCol)}:${rowColToRef(endRow, endCol)}`;
+  return {
+    description: `Format ${rangeRef} as ${numFmtCode}`,
+    execute() {
+      for (let r = startRow; r <= endRow; r++) {
+        for (let c = startCol; c <= endCol; c++) {
+          const ref2 = rowColToRef(r, c);
+          const cell = sheet.getCell(ref2);
+          if (cell) {
+            sheet.set(ref2, cell.value, sheet.styles?.get(cell.styleIndex), numFmtCode, cell.formula);
+          } else {
+            sheet.set(ref2, null, void 0, numFmtCode);
+          }
+        }
+      }
+    },
+    undo() {
+      for (const [ref2, snap] of snapshot) {
+        if (snap) {
+          sheet.set(ref2, snap.value, sheet.styles?.get(snap.styleIndex), snap.numFmtCode, snap.formula);
+        } else {
+          sheet.deleteCell(ref2);
+        }
+      }
+    }
+  };
+}
 function addSheetCommand(workbook, name2) {
   return {
     description: `Add sheet ${name2}`,
@@ -95426,10 +95833,23 @@ function renameSheetCommand(workbook, index, newName) {
     }
   };
 }
-function parseInputValue(input) {
+function batchCommand(description, commands) {
+  return {
+    description,
+    execute() {
+      for (const cmd of commands) cmd.execute();
+    },
+    undo() {
+      for (let i2 = commands.length - 1; i2 >= 0; i2--) commands[i2].undo();
+    }
+  };
+}
+function parseInputValue(input, numFmtCode) {
   if (input === "") return null;
+  if (classifyNumFmt(numFmtCode) === "text") return input;
   if (input.toUpperCase() === "TRUE") return true;
   if (input.toUpperCase() === "FALSE") return false;
+  if (isPaddedIdentifier(input.trim())) return input;
   const num3 = Number(input);
   if (!isNaN(num3) && input.trim() !== "") return num3;
   return input;
@@ -95702,21 +96122,20 @@ function applySheetCells(workbook, sheetIndex, def) {
   const sheet = workbook.sheets[sheetIndex];
   if (def.cells) {
     for (const [ref2, raw] of Object.entries(def.cells)) {
-      const cell = normalizeSimpleCell(raw, def.name, ref2);
-      const coord = refToRowCol(ref2.toUpperCase());
+      const cell = normalizeSimpleCell(raw, `sheet "${def.name}" cell ${ref2}`);
+      const upper2 = ref2.toUpperCase();
+      const coord = refToRowCol(upper2);
       if (!coord) fail2(`Invalid cell ref in sheet "${def.name}": ${ref2}`);
-      const stringValue = cell.formula ? `=${cell.formula}` : valueToInput(cell.value);
-      const cmd = setCellValueCommand(workbook, void 0, sheetIndex, coord.row, coord.col, stringValue);
-      cmd.execute();
+      sheet.set(
+        upper2,
+        cell.formula ? null : cell.value ?? null,
+        void 0,
+        cell.numFmt,
+        cell.formula ?? void 0
+      );
       if (cell.style) {
         setRangeStyleCommand(workbook, sheetIndex, coord.row, coord.col, coord.row, coord.col, cell.style).execute();
       }
-      if (cell.numFmt !== void 0) {
-        const upper2 = ref2.toUpperCase();
-        const target = sheet.getCell(upper2);
-        if (target) target.numFmtCode = cell.numFmt;
-        else sheet.set(upper2, null, cell.style, cell.numFmt);
-      }
     }
   }
   if (def.merges) {
@@ -95744,22 +96163,33 @@ function applySheetCells(workbook, sheetIndex, def) {
     }
   }
 }
-function normalizeSimpleCell(raw, sheetName, ref2) {
+function normalizeSimpleCell(raw, label) {
   if (raw && typeof raw === "object" && !Array.isArray(raw)) {
     const unknown2 = Object.keys(raw).filter((k) => !SIMPLE_CELL_KEYS.has(k));
     if (unknown2.length > 0) {
       fail2(
-        `Unknown propert${unknown2.length > 1 ? "ies" : "y"} on sheet "${sheetName}" cell ${ref2}: ${unknown2.join(", ")}. Supported: ${[...SIMPLE_CELL_KEYS].join(", ")}.`
+        `Unknown propert${unknown2.length > 1 ? "ies" : "y"} on ${label}: ${unknown2.join(", ")}. Supported: ${[...SIMPLE_CELL_KEYS].join(", ")}.`
       );
     }
+    if (raw.formula === void 0 || raw.formula === null) {
+      if (typeof raw.value === "string" && raw.value.startsWith("=")) {
+        console.error(
+          `Warning: ${label} was written as the text ${JSON.stringify(raw.value)}. An object cell's "value" is a literal; write {"formula": ${JSON.stringify(raw.value.slice(1))}} or the bare string ${JSON.stringify(raw.value)} for a formula.`
+        );
+      }
+    }
     return raw;
   }
+  if (raw !== null && !["string", "number", "boolean"].includes(typeof raw)) {
+    fail2(
+      `Value of ${label} must be a string, number, boolean, null, or a { ${[...SIMPLE_CELL_KEYS].join(", ")} } object, got ${JSON.stringify(raw) ?? typeof raw}.`
+    );
+  }
+  if (typeof raw === "string" && raw.startsWith("=")) {
+    return { formula: raw.slice(1) };
+  }
   return { value: raw };
 }
-function valueToInput(value2) {
-  if (value2 === null || value2 === void 0) return "";
-  return String(value2);
-}
 function readOptionFlag(rest2, name2) {
   const i2 = rest2.indexOf(name2);
   if (i2 < 0) return void 0;
@@ -95774,7 +96204,6 @@ function splitOptionalSheetRef(spec) {
 }
 function xlsxRead(filePath, rest2) {
   if (!filePath) fail2("Usage: lotics xlsx read <file> [--sheet <name>] [--range <sheet>!<A1:G60>] [--with-format]");
-  rejectUnknownFlags(rest2, ["--sheet", "--range", "--with-format"], "xlsx read");
   const rangeArg = readOptionFlag(rest2, "--range");
   const sheetArg = readOptionFlag(rest2, "--sheet");
   const withFormat = rest2.includes("--with-format");
@@ -95984,7 +96413,29 @@ function buildBatchCommand(workbook, engine, op, index) {
       const sheetIndex = resolveSheetIndex(workbook, op.sheet);
       const coord = refToRowCol(op.ref.toUpperCase());
       if (!coord) fail2(`[op ${index}] Invalid cell ref: ${op.ref}`);
-      return setCellValueCommand(workbook, engine.get(), sheetIndex, coord.row, coord.col, op.value);
+      const cell = normalizeSimpleCell(op.value, `[op ${index}] set-cell ${op.sheet}!${op.ref}`);
+      const commands = [
+        cell.formula ? (
+          // The entry path is the only one that writes a formula, and it takes
+          // it spelled the way a person types it. Re-adding the `=` this
+          // surface's reader just stripped is lossless and keeps the formula
+          // write in one place.
+          setCellValueCommand(workbook, engine.get(), sheetIndex, coord.row, coord.col, `=${cell.formula}`)
+        ) : setCellValueCommand(workbook, engine.get(), sheetIndex, coord.row, coord.col, cell.value ?? null, {
+          typed: true
+        })
+      ];
+      if (cell.numFmt !== void 0) {
+        commands.push(
+          setRangeNumFmtCommand(workbook, sheetIndex, coord.row, coord.col, coord.row, coord.col, cell.numFmt)
+        );
+      }
+      if (cell.style) {
+        commands.push(
+          setRangeStyleCommand(workbook, sheetIndex, coord.row, coord.col, coord.row, coord.col, cell.style)
+        );
+      }
+      return commands.length === 1 ? commands[0] : batchCommand(`Set ${op.sheet}!${op.ref}`, commands);
     }
     case "clear-range": {
       const sheetIndex = resolveSheetIndex(workbook, op.sheet);
@@ -96041,6 +96492,8 @@ Uses Lotics' own xlsx engine; round-trips faithfully with the Lotics editor and
   lotics xlsx write <file> '<json>'                Create .xlsx from {"sheets":[{"name","cells":{"A1":...}}]}
                                                    A cell is a bare value, or {value|formula, numFmt, style}:
                                                    {"A1":{"value":1234,"numFmt":"#,##0 \\"\u20AB\\"","style":{"fontBold":true}}}
+                                                   A bare "=A1+B1" is a formula; an object's "value" is
+                                                   always a literal, so use {"formula":"A1+B1"} there.
                                                    A sheet also takes merges, freeze, colWidths ({"A":34}),
                                                    rowHeights ({"1":44}). Unknown properties are rejected.
   lotics xlsx set-cell <file> <sheet>!<ref> '<v>'  Set cell value (prefix '=' for formula)
@@ -101655,7 +102108,6 @@ function buildDoc(input) {
 }
 async function docxRead(filePath, rest2) {
   if (!filePath) fail2("Usage: lotics docx read <file> [--include-opaque]");
-  rejectUnknownFlags(rest2, ["--include-opaque"], "docx read");
   const includeOpaque = rest2.includes("--include-opaque");
   const doc = await loadFile2(filePath);
   console.log(JSON.stringify(readToJson2(doc, includeOpaque), null, 2));
@@ -101690,7 +102142,7 @@ function firstPositional(rest2) {
   return rest2.find((a) => !a.startsWith("--"));
 }
 async function docxAppendParagraph(filePath, rest2) {
-  rejectUnknownFlags(rest2, ["--style="], "docx append-paragraph");
+  rejectUnknownFlags(rest2, "docx", "append-paragraph");
   const text = firstPositional(rest2);
   if (!filePath || text === void 0) fail2("Usage: lotics docx append-paragraph <file> '<text>' [--style=NAME]");
   const style = getStyleFlag(rest2);
@@ -101700,7 +102152,7 @@ async function docxAppendParagraph(filePath, rest2) {
   await writeDoc(filePath, replaceChildren(doc, newChildren));
 }
 async function docxInsertParagraph(filePath, rest2) {
-  rejectUnknownFlags(rest2, ["--style=", "--at="], "docx insert-paragraph");
+  rejectUnknownFlags(rest2, "docx", "insert-paragraph");
   const text = firstPositional(rest2);
   const at2 = getAtFlag(rest2);
   if (!filePath || text === void 0 || at2 === void 0) {
@@ -101717,7 +102169,6 @@ async function docxInsertParagraph(filePath, rest2) {
   await writeDoc(filePath, replaceChildren(doc, newChildren));
 }
 async function docxDeleteBlock(filePath, rest2) {
-  rejectUnknownFlags(rest2, ["--at="], "docx delete-block");
   const at2 = getAtFlag(rest2);
   if (!filePath || at2 === void 0) fail2("Usage: lotics docx delete-block <file> --at=<index>");
   const doc = await loadFile2(filePath);