@lotics/cli 0.63.0 → 0.65.0

package/dist/app_commands.d.ts

@@ -87,16 +87,23 @@ export declare function writeWorkflowFile(projectDir: string, alias: string, sou
  */
 export declare function stripWorkflowHeader(content: string): string;
 /**
- * Add the workflow-body globs to the main `tsconfig.json`'s `exclude` if missing,
- * preserving every other exclude. The starter ships these excludes already, but
- * an app SCAFFOLDED before this CLI release (or one with a hand-written tsconfig)
- * doesn't — and pulling bodies into it would otherwise break its
- * `npm run typecheck`: the bodies pull the app's DOM lib (the server doesn't) and
- * the per-alias ambient globals collide on `trigger`. Idempotent — a second pull
- * is a no-op. Warns exactly what it added. A missing/unparseable tsconfig is a
- * non-fatal warn (the pull itself still succeeds); the author fixes the config.
+ * Heal a pre-existing app's `tsconfig.json` so its generated types load and its
+ * `npm run typecheck` stays honest. Idempotent, run on every pull / codegen /
+ * deploy. Two things the current starter ships but an app SCAFFOLDED before those
+ * releases (or with a hand-written tsconfig) can lack:
+ *
+ *  1. `include`: a bare `.lotics` is rewritten to the recursive `LOTICS_INCLUDE_GLOB`.
+ *     A bare dot-dir is skipped by TypeScript's include-glob walk, so the codegen'd
+ *     `.d.ts` never enter the program — every `useQuery`/`useWorkflow`/`useAgentRun`
+ *     param and result silently falls back to `unknown`.
+ *  2. `exclude`: the workflow-body globs — the bodies use the app's DOM lib (the
+ *     server doesn't) and the per-alias ambient globals collide on `trigger`,
+ *     poisoning typecheck. Checked separately by `lotics app workflow check`.
+ *
+ * A missing / unparseable tsconfig is a non-fatal warn (the caller still succeeds);
+ * the author fixes the config.
  */
-export declare function ensureWorkflowTsconfigExcludes(projectDir: string): void;
+export declare function ensureAppTsconfig(projectDir: string): void;
 /**
  * `lotics app codegen [path]` — regenerate every `.lotics/` artifact from the
  * manifest + workspace schema, WITHOUT a deploy. The `.d.ts` companions are
@@ -235,7 +242,7 @@ export declare function undeclaredCapabilities(sourceText: string, declared: Rec
  */
 export declare function appDeploy(client: LoticsClient, args: {
     projectDir?: string;
-    message?: string;
+    message: string;
 }): Promise<void>;
 /**
  * `lotics app dev [path] [--port=5174] [--vite-port=5173]`

package/dist/app_commands.js

@@ -64,6 +64,17 @@ const WORKFLOW_GLOBALS_DIR = path.join(".lotics", "workflows");
  * with `/` separators — tsconfig globs are POSIX even on Windows.
  */
 const WORKFLOW_TSCONFIG_EXCLUDES = ["src/workflows", ".lotics/workflows"];
+/**
+ * The include glob that actually loads the generated `.lotics/*.d.ts` companions.
+ * A BARE `.lotics` entry loads NONE of them: TypeScript's include-glob walk skips
+ * dot-directories, so `useQuery` / `useWorkflow` / `useAgentRun` fall back to their
+ * untyped string overloads and every param / input / result silently becomes
+ * `unknown`. The current starter emits the glob (`starter_template.ts`); apps
+ * scaffolded before that fix shipped the bare form and need healing.
+ */
+const LOTICS_INCLUDE_GLOB = ".lotics/**/*";
+/** The bare `.lotics` forms an older starter emitted — all skipped by the glob walk. */
+const STALE_LOTICS_INCLUDES = new Set([".lotics", "./.lotics", ".lotics/"]);
 /**
  * The `async function __workflow(...)` wrapper a workflow body sits inside —
  * the SAME envelope the server compiles the body within at `set_app_workflow`
@@ -304,20 +315,27 @@ function writeAppMeta(projectDir, meta) {
     fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + "\n");
 }
 /**
- * Add the workflow-body globs to the main `tsconfig.json`'s `exclude` if missing,
- * preserving every other exclude. The starter ships these excludes already, but
- * an app SCAFFOLDED before this CLI release (or one with a hand-written tsconfig)
- * doesn't — and pulling bodies into it would otherwise break its
- * `npm run typecheck`: the bodies pull the app's DOM lib (the server doesn't) and
- * the per-alias ambient globals collide on `trigger`. Idempotent — a second pull
- * is a no-op. Warns exactly what it added. A missing/unparseable tsconfig is a
- * non-fatal warn (the pull itself still succeeds); the author fixes the config.
+ * Heal a pre-existing app's `tsconfig.json` so its generated types load and its
+ * `npm run typecheck` stays honest. Idempotent, run on every pull / codegen /
+ * deploy. Two things the current starter ships but an app SCAFFOLDED before those
+ * releases (or with a hand-written tsconfig) can lack:
+ *
+ *  1. `include`: a bare `.lotics` is rewritten to the recursive `LOTICS_INCLUDE_GLOB`.
+ *     A bare dot-dir is skipped by TypeScript's include-glob walk, so the codegen'd
+ *     `.d.ts` never enter the program — every `useQuery`/`useWorkflow`/`useAgentRun`
+ *     param and result silently falls back to `unknown`.
+ *  2. `exclude`: the workflow-body globs — the bodies use the app's DOM lib (the
+ *     server doesn't) and the per-alias ambient globals collide on `trigger`,
+ *     poisoning typecheck. Checked separately by `lotics app workflow check`.
+ *
+ * A missing / unparseable tsconfig is a non-fatal warn (the caller still succeeds);
+ * the author fixes the config.
  */
-export function ensureWorkflowTsconfigExcludes(projectDir) {
+export function ensureAppTsconfig(projectDir) {
     const tsconfigPath = path.join(projectDir, "tsconfig.json");
     if (!fs.existsSync(tsconfigPath)) {
-        console.error(`⚠ No tsconfig.json at ${projectDir} — could not ensure ${WORKFLOW_TSCONFIG_EXCLUDES.join(", ")} are excluded. ` +
-            `Add them to your tsconfig's "exclude" so npm run typecheck skips the workflow bodies.`);
+        console.error(`⚠ No tsconfig.json at ${projectDir} — could not ensure "include" has "${LOTICS_INCLUDE_GLOB}" ` +
+            `(a bare .lotics loads none of the generated types) or "exclude" has ${WORKFLOW_TSCONFIG_EXCLUDES.join(", ")}.`);
         return;
     }
     let parsed;
@@ -326,30 +344,47 @@ export function ensureWorkflowTsconfigExcludes(projectDir) {
     }
     catch (err) {
         console.error(`⚠ Could not parse tsconfig.json (${err instanceof Error ? err.message : String(err)}) — ` +
-            `add ${WORKFLOW_TSCONFIG_EXCLUDES.join(", ")} to its "exclude" manually so npm run typecheck skips the workflow bodies.`);
+            `ensure "include" has "${LOTICS_INCLUDE_GLOB}" and "exclude" has ${WORKFLOW_TSCONFIG_EXCLUDES.join(", ")} manually.`);
         return;
     }
     if (!parsed || typeof parsed !== "object")
         return;
-    // `exclude` is a TOP-LEVEL tsconfig field — tsc ignores `compilerOptions.exclude`,
-    // so the workflow globs must land at the top level or `npm run typecheck` still
-    // loads the bodies + their colliding per-alias globals.
-    const current = Array.isArray(parsed.exclude) ? parsed.exclude : [];
-    const currentStrings = current.filter((e) => typeof e === "string");
-    const toAdd = WORKFLOW_TSCONFIG_EXCLUDES.filter((g) => !currentStrings.includes(g));
-    if (toAdd.length === 0)
+    const changes = [];
+    // 1. Heal a stale bare `.lotics` include so the generated `.d.ts` actually load
+    //    (a bare dot-dir is invisible to TypeScript's include-glob walk).
+    if (Array.isArray(parsed.include)) {
+        const inc = parsed.include.filter((e) => typeof e === "string");
+        if (inc.some((e) => STALE_LOTICS_INCLUDES.has(e))) {
+            const healed = inc.map((e) => (STALE_LOTICS_INCLUDES.has(e) ? LOTICS_INCLUDE_GLOB : e));
+            parsed.include = healed.filter((e, i) => healed.indexOf(e) === i); // dedupe if the glob was already present
+            changes.push(`rewrote a bare ".lotics" to "${LOTICS_INCLUDE_GLOB}" in "include" (a dot-dir loads zero generated types)`);
+        }
+    }
+    // 2. Ensure the workflow-body excludes. `exclude` is a TOP-LEVEL tsconfig field —
+    //    tsc ignores `compilerOptions.exclude`, so they must land at the top level.
+    const currentEx = Array.isArray(parsed.exclude)
+        ? parsed.exclude.filter((e) => typeof e === "string")
+        : [];
+    const toAdd = WORKFLOW_TSCONFIG_EXCLUDES.filter((g) => !currentEx.includes(g));
+    if (toAdd.length > 0) {
+        parsed.exclude = [...currentEx, ...toAdd];
+        changes.push(`added ${toAdd.join(", ")} to "exclude"`);
+    }
+    if (changes.length === 0)
         return;
-    parsed.exclude = [...currentStrings, ...toAdd];
     fs.writeFileSync(tsconfigPath, JSON.stringify(parsed, null, 2) + "\n");
-    console.error(`Patched tsconfig.json: added ${toAdd.join(", ")} to "exclude" so npm run typecheck skips the workflow bodies ` +
-        `(check them with: lotics app workflow check).`);
+    console.error(`Patched tsconfig.json: ${changes.join("; ")}.`);
 }
 /**
- * Write `.lotics/app_workflows.d.ts` + `.lotics/app_queries.d.ts` from the
- * manifest's `workflows` / `queries` maps. Called from `app create / pull /
- * dev / deploy` so the augmented `AppWorkflows` / `AppQueries` types stay in
- * sync with the manifest. The starter tsconfig.json includes `.lotics/` so
- * tsc + Vite pick the files up automatically.
+ * Write the three `.lotics/app_{workflows,queries,agents}.d.ts` companions from
+ * the manifest's maps, then heal the app's tsconfig so they actually load. Called
+ * from `app create / pull / dev / deploy / codegen`, so the augmented `AppWorkflows`
+ * / `AppQueries` / `AppAgents` types stay in sync with the manifest.
+ *
+ * The heal is at the write boundary on purpose: a `.d.ts` written but not loaded is
+ * useless (a bare `.lotics` include is skipped by TypeScript's include-glob walk and
+ * loads zero of them), so `ensureAppTsconfig` couples "wrote the types" with "the
+ * program can see them" — no caller can do one without the other.
  */
 function writeAppDts(projectDir, manifest) {
     const dotLotics = path.join(projectDir, ".lotics");
@@ -361,6 +396,7 @@ function writeAppDts(projectDir, manifest) {
     ];
     for (const [file, content] of written)
         fs.writeFileSync(file, content);
+    ensureAppTsconfig(projectDir);
     return written.map(([file]) => file);
 }
 /**
@@ -450,10 +486,6 @@ export async function appCodegen(args) {
     // it, so the local typecheck tracks the current workspace schema. Aliases
     // never pulled (no body file yet) are skipped — codegen isn't a pull.
     await refreshWorkflowGlobals(args.client, projectDir, meta.app_id, Object.keys(meta.workflows ?? {}));
-    // Keep the main tsconfig excluding the workflow-body globs (idempotent) so
-    // npm run typecheck never loads the bodies or their colliding per-alias globals.
-    if (Object.keys(meta.workflows ?? {}).length > 0)
-        ensureWorkflowTsconfigExcludes(projectDir);
 }
 /**
  * For each bound alias that already has a local body file, fetch its current
@@ -745,9 +777,6 @@ export async function appPull(client, args) {
         if (written.length > 0) {
             console.error(`Wrote ${written.length} workflow ${written.length === 1 ? "body" : "bodies"} to ${WORKFLOWS_DIR}/ (${written.join(", ")})`);
         }
-        // A pre-existing app's tsconfig may predate the workflow-body excludes; pulling
-        // bodies into it would break its npm run typecheck. Patch it idempotently.
-        ensureWorkflowTsconfigExcludes(targetPath);
     }
     console.error(`Installing npm dependencies...`);
     await runNpm(["install"], targetPath);
@@ -806,7 +835,11 @@ function readAppSourceText(projectDir) {
  * both archives in R2, creates an app_versions row, and atomically advances
  * the app's current_version pointer.
  */
-export async function appDeploy(client, args) {
+export async function appDeploy(client, 
+// `message` is required — each deploy is a version row read back by
+// `lotics app versions`; a blank message loses the audit trail. The CLI
+// enforces non-empty at the dispatch; the type enforces it for every caller.
+args) {
     const projectDir = path.resolve(args.projectDir ?? process.cwd());
     const meta = readAppMeta(projectDir);
     // Pre-flight (GAP-29): a capability the code calls but the manifest doesn't
@@ -1183,9 +1216,10 @@ export async function appWorkflowPull(client) {
     const written = await writeWorkflowFiles(client, projectDir, meta.app_id, aliases);
     console.error(`Wrote ${written.length} workflow ${written.length === 1 ? "body" : "bodies"} to ${WORKFLOWS_DIR}/` +
         (written.length > 0 ? ` (${written.join(", ")})` : ""));
-    // A pre-existing app's tsconfig may predate the workflow-body excludes; pulling
-    // bodies into it would break its npm run typecheck. Patch it idempotently.
-    ensureWorkflowTsconfigExcludes(projectDir);
+    // This command writes workflow BODIES, not the `.d.ts` — so it doesn't reach
+    // `writeAppDts`'s heal. Heal here so the bodies land excluded and a stale
+    // `.lotics` include doesn't leave the app's other generated types dead.
+    ensureAppTsconfig(projectDir);
 }
 /**
  * `lotics app workflow check [alias]` — local TypeScript type check of the

package/dist/app_commands.test.js

@@ -2,7 +2,7 @@ import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
 import fs from "node:fs";
 import path from "node:path";
 import { tmpdir } from "node:os";
-import { stampPulledManifest, undeclaredCapabilities, appDirName, defaultPullTarget, ensureWorkflowTsconfigExcludes, appCodegen, appUiLink, appVersions, appWorkflowSet, appWorkflowPull, appExecuteWorkflow, writeWorkflowFile, writeWorkflowGlobals, stripWorkflowHeader, FALLBACK_ENVELOPE_PREFIX, FALLBACK_ENVELOPE_SUFFIX, } from "./app_commands.js";
+import { stampPulledManifest, undeclaredCapabilities, appDirName, defaultPullTarget, ensureAppTsconfig, appCodegen, appUiLink, appVersions, appWorkflowSet, appWorkflowPull, appExecuteWorkflow, writeWorkflowFile, writeWorkflowGlobals, stripWorkflowHeader, FALLBACK_ENVELOPE_PREFIX, FALLBACK_ENVELOPE_SUFFIX, } from "./app_commands.js";
 /**
  * `appPull` reads workflows from the live App row (server response), NOT from
  * the manifest embedded in the extracted source archive. The frozen archive
@@ -680,7 +680,7 @@ describe("defaultPullTarget", () => {
         expect(defaultPullTarget("app_X", "Sales Tracker")).toBe("Sales Tracker");
     });
 });
-describe("ensureWorkflowTsconfigExcludes", () => {
+describe("ensureAppTsconfig", () => {
     let dir;
     beforeEach(() => {
         dir = fs.mkdtempSync(path.join(tmpdir(), "lotics-tsconfig-"));
@@ -692,37 +692,60 @@ describe("ensureWorkflowTsconfigExcludes", () => {
     const read = () => JSON.parse(fs.readFileSync(tsconfigPath(), "utf-8"));
     it("adds both workflow globs to the TOP-LEVEL exclude", () => {
         fs.writeFileSync(tsconfigPath(), JSON.stringify({ compilerOptions: {}, exclude: ["node_modules"] }));
-        ensureWorkflowTsconfigExcludes(dir);
+        ensureAppTsconfig(dir);
         expect(read().exclude).toEqual(["node_modules", "src/workflows", ".lotics/workflows"]);
     });
     it("writes TOP-LEVEL even when a compilerOptions.exclude exists (tsc ignores the nested key)", () => {
         fs.writeFileSync(tsconfigPath(), JSON.stringify({ compilerOptions: { exclude: ["x"] } }));
-        ensureWorkflowTsconfigExcludes(dir);
+        ensureAppTsconfig(dir);
         const cfg = read();
         expect(cfg.exclude).toEqual(["src/workflows", ".lotics/workflows"]);
         expect(cfg.compilerOptions.exclude).toEqual(["x"]); // left untouched (and tsc-ignored)
     });
     it("preserves pre-existing top-level excludes", () => {
         fs.writeFileSync(tsconfigPath(), JSON.stringify({ exclude: ["node_modules", "dist"] }));
-        ensureWorkflowTsconfigExcludes(dir);
+        ensureAppTsconfig(dir);
         expect(read().exclude).toEqual(["node_modules", "dist", "src/workflows", ".lotics/workflows"]);
     });
     it("is idempotent — a second call writes nothing new", () => {
         fs.writeFileSync(tsconfigPath(), JSON.stringify({ exclude: ["node_modules"] }));
-        ensureWorkflowTsconfigExcludes(dir);
+        ensureAppTsconfig(dir);
         const afterFirst = fs.readFileSync(tsconfigPath(), "utf-8");
-        ensureWorkflowTsconfigExcludes(dir);
+        ensureAppTsconfig(dir);
         expect(fs.readFileSync(tsconfigPath(), "utf-8")).toBe(afterFirst);
     });
     it("warns + does not throw or create a file when there is no tsconfig", () => {
-        expect(() => ensureWorkflowTsconfigExcludes(dir)).not.toThrow();
+        expect(() => ensureAppTsconfig(dir)).not.toThrow();
         expect(fs.existsSync(tsconfigPath())).toBe(false);
     });
     it("warns + does not throw on an unparseable tsconfig (left as-is)", () => {
         fs.writeFileSync(tsconfigPath(), "{ not json,, }");
-        expect(() => ensureWorkflowTsconfigExcludes(dir)).not.toThrow();
+        expect(() => ensureAppTsconfig(dir)).not.toThrow();
         expect(fs.readFileSync(tsconfigPath(), "utf-8")).toBe("{ not json,, }");
     });
+    it("rewrites a bare .lotics include to the glob (a dot-dir loads zero generated types)", () => {
+        fs.writeFileSync(tsconfigPath(), JSON.stringify({ include: ["src", ".lotics"], exclude: ["node_modules"] }));
+        ensureAppTsconfig(dir);
+        expect(read().include).toEqual(["src", ".lotics/**/*"]);
+    });
+    it("leaves an already-correct .lotics/**/* include untouched (idempotent)", () => {
+        fs.writeFileSync(tsconfigPath(), JSON.stringify({ include: ["src", ".lotics/**/*"], exclude: ["node_modules", "src/workflows", ".lotics/workflows"] }));
+        const before = fs.readFileSync(tsconfigPath(), "utf-8");
+        ensureAppTsconfig(dir);
+        expect(fs.readFileSync(tsconfigPath(), "utf-8")).toBe(before);
+    });
+    it("dedupes when both a bare .lotics and the glob are present", () => {
+        fs.writeFileSync(tsconfigPath(), JSON.stringify({ include: [".lotics", ".lotics/**/*", "src"] }));
+        ensureAppTsconfig(dir);
+        expect(read().include).toEqual([".lotics/**/*", "src"]);
+    });
+    it("heals the include AND adds the excludes in a single write", () => {
+        fs.writeFileSync(tsconfigPath(), JSON.stringify({ include: ["src", ".lotics"], exclude: ["node_modules"] }));
+        ensureAppTsconfig(dir);
+        const cfg = read();
+        expect(cfg.include).toEqual(["src", ".lotics/**/*"]);
+        expect(cfg.exclude).toEqual(["node_modules", "src/workflows", ".lotics/workflows"]);
+    });
 });
 describe("appVersions", () => {
     let logLines;

package/dist/cli.js

@@ -71,7 +71,8 @@ COMMANDS
                                        Download all files on a record file field
   lotics app create <name> [path]      Create a new custom-code app + scaffold locally
   lotics app pull <app_id> [path]      Bootstrap full local env (source + npm install + types)
-  lotics app deploy [-m <message>]     Build + upload current dir as a new version
+  lotics app deploy -m <message>       Build + upload current dir as a new version
+                                       (-m is required — it's the version's audit trail)
                                        (code + queries only — workflow bindings are
                                        managed by set_app_workflow / remove_app_workflow)
   lotics app versions [app_id]         Show deploy history newest-first (version,
@@ -598,7 +599,7 @@ async function main() {
         console.error("Usage:");
         console.error("  lotics app create <name> [path]      Scaffold a new app locally");
         console.error("  lotics app pull <app_id> [path]      Pull an existing app for local editing");
-        console.error("  lotics app deploy [-m <message>]     Build + upload the current directory");
+        console.error("  lotics app deploy -m <message>       Build + upload the current directory (-m required)");
         console.error("  lotics app versions [app_id]         Show deploy history (version, when, who, message)");
         console.error("  lotics app codegen [path]            Regenerate .lotics/* (types + field ids) — no deploy");
         console.error("  lotics app workflow run <alias> '<json>'  Execute a bound app workflow end-to-end");
@@ -729,7 +730,14 @@ async function main() {
         }
         if (subcommand === "deploy") {
             // The message is either `-m <message>` or a bare positional arg after `deploy`.
-            const message = flags.message ?? toolArgs;
+            // Required: every deploy is a version row, and `lotics app versions` reads
+            // the message back — a blank one makes the deploy history useless.
+            const message = (flags.message ?? toolArgs)?.trim();
+            if (!message) {
+                console.error('Usage: lotics app deploy -m "<what changed + why>"');
+                console.error("A deploy message is required — it's the version's audit trail (see `lotics app versions`).");
+                process.exit(1);
+            }
             await appDeploy(client, { message });
             return;
         }

package/dist/generate_app_workflows_dts.js

@@ -122,7 +122,7 @@ function inputDeclToTsType(decl) {
         case "date_range":
             return "{ start: string; end: string }";
         case "file":
-            return "string";
+            return decl.multi === true ? "ReadonlyArray<string>" : "string";
         case "object": {
             const fields = decl.fields !== null && typeof decl.fields === "object"
                 ? decl.fields

package/dist/generate_app_workflows_dts.test.js

@@ -70,4 +70,14 @@ describe("generateAppWorkflowsDts", () => {
         });
         expect(dts).toContain('owner: string; tags: ReadonlyArray<"a" | "b">');
     });
+    it("types a multi file input as ReadonlyArray<string>, single file as string", () => {
+        const dts = generateAppWorkflowsDts({
+            attach: {
+                workflow_id: "wfl_f",
+                inputs: { one: { type: "file" }, many: { type: "file", multi: true } },
+            },
+        });
+        expect(dts).toContain("one: string");
+        expect(dts).toContain("many: ReadonlyArray<string>");
+    });
 });

package/dist/src/cli.js

@@ -3387,7 +3387,7 @@ var require_jstat = __commonJS({
       }
     })(exports2, function() {
       var jStat = (function(Math2, undefined2) {
-        var concat = Array.prototype.concat;
+        var concat2 = Array.prototype.concat;
         var slice = Array.prototype.slice;
         var toString = Object.prototype.toString;
         function calcRdx(n, m) {
@@ -3407,7 +3407,7 @@ var require_jstat = __commonJS({
           return typeof num === "number" ? num - num === 0 : false;
         }
         function toVector(arr) {
-          return concat.apply([], arr);
+          return concat2.apply([], arr);
         }
         function jStat2() {
           return new jStat2._init(arguments);
@@ -20136,7 +20136,7 @@ var require_BufferList = __commonJS({
         }
         return ret;
       };
-      BufferList.prototype.concat = function concat(n) {
+      BufferList.prototype.concat = function concat2(n) {
         if (this.length === 0) return Buffer2.alloc(0);
         var ret = Buffer2.allocUnsafe(n >>> 0);
         var p = this.head;
@@ -23322,7 +23322,7 @@ var require_StreamHelper = __commonJS({
           return utils.transformTo(type, content);
       }
     }
-    function concat(type, dataArray) {
+    function concat2(type, dataArray) {
       var i2, index = 0, res = null, totalLength = 0;
       for (i2 = 0; i2 < dataArray.length; i2++) {
         totalLength += dataArray[i2].length;
@@ -23359,7 +23359,7 @@ var require_StreamHelper = __commonJS({
           reject2(err2);
         }).on("end", function() {
           try {
-            var result = transformZipOutput(resultType, concat(chunkType, dataArray), mimeType);
+            var result = transformZipOutput(resultType, concat2(chunkType, dataArray), mimeType);
             resolve(result);
           } catch (e) {
             reject2(e);
@@ -31803,7 +31803,7 @@ function inputDeclToTsType(decl) {
     case "date_range":
       return "{ start: string; end: string }";
     case "file":
-      return "string";
+      return decl.multi === true ? "ReadonlyArray<string>" : "string";
     case "object": {
       const fields = decl.fields !== null && typeof decl.fields === "object" ? decl.fields : {};
       return inputsToType(fields);
@@ -32219,6 +32219,8 @@ async function fetchLatestNpmVersion(packageName) {
 var WORKFLOWS_DIR = path5.join("src", "workflows");
 var WORKFLOW_GLOBALS_DIR = path5.join(".lotics", "workflows");
 var WORKFLOW_TSCONFIG_EXCLUDES = ["src/workflows", ".lotics/workflows"];
+var LOTICS_INCLUDE_GLOB = ".lotics/**/*";
+var STALE_LOTICS_INCLUDES = /* @__PURE__ */ new Set([".lotics", "./.lotics", ".lotics/"]);
 var FALLBACK_ENVELOPE_PREFIX = "async function __workflow(): Promise<__WorkflowReturn | void> {\n";
 var FALLBACK_ENVELOPE_SUFFIX = "\n}";
 function workflowFileHeader(alias) {
@@ -32362,11 +32364,11 @@ function writeAppMeta(projectDir, meta) {
   pkg2.lotics = meta;
   fs4.writeFileSync(pkgPath2, JSON.stringify(pkg2, null, 2) + "\n");
 }
-function ensureWorkflowTsconfigExcludes(projectDir) {
+function ensureAppTsconfig(projectDir) {
   const tsconfigPath = path5.join(projectDir, "tsconfig.json");
   if (!fs4.existsSync(tsconfigPath)) {
     console.error(
-      `\u26A0 No tsconfig.json at ${projectDir} \u2014 could not ensure ${WORKFLOW_TSCONFIG_EXCLUDES.join(", ")} are excluded. Add them to your tsconfig's "exclude" so npm run typecheck skips the workflow bodies.`
+      `\u26A0 No tsconfig.json at ${projectDir} \u2014 could not ensure "include" has "${LOTICS_INCLUDE_GLOB}" (a bare .lotics loads none of the generated types) or "exclude" has ${WORKFLOW_TSCONFIG_EXCLUDES.join(", ")}.`
     );
     return;
   }
@@ -32375,20 +32377,29 @@ function ensureWorkflowTsconfigExcludes(projectDir) {
     parsed = JSON.parse(fs4.readFileSync(tsconfigPath, "utf-8"));
   } catch (err2) {
     console.error(
-      `\u26A0 Could not parse tsconfig.json (${err2 instanceof Error ? err2.message : String(err2)}) \u2014 add ${WORKFLOW_TSCONFIG_EXCLUDES.join(", ")} to its "exclude" manually so npm run typecheck skips the workflow bodies.`
+      `\u26A0 Could not parse tsconfig.json (${err2 instanceof Error ? err2.message : String(err2)}) \u2014 ensure "include" has "${LOTICS_INCLUDE_GLOB}" and "exclude" has ${WORKFLOW_TSCONFIG_EXCLUDES.join(", ")} manually.`
     );
     return;
   }
   if (!parsed || typeof parsed !== "object") return;
-  const current = Array.isArray(parsed.exclude) ? parsed.exclude : [];
-  const currentStrings = current.filter((e) => typeof e === "string");
-  const toAdd = WORKFLOW_TSCONFIG_EXCLUDES.filter((g) => !currentStrings.includes(g));
-  if (toAdd.length === 0) return;
-  parsed.exclude = [...currentStrings, ...toAdd];
+  const changes = [];
+  if (Array.isArray(parsed.include)) {
+    const inc = parsed.include.filter((e) => typeof e === "string");
+    if (inc.some((e) => STALE_LOTICS_INCLUDES.has(e))) {
+      const healed = inc.map((e) => STALE_LOTICS_INCLUDES.has(e) ? LOTICS_INCLUDE_GLOB : e);
+      parsed.include = healed.filter((e, i2) => healed.indexOf(e) === i2);
+      changes.push(`rewrote a bare ".lotics" to "${LOTICS_INCLUDE_GLOB}" in "include" (a dot-dir loads zero generated types)`);
+    }
+  }
+  const currentEx = Array.isArray(parsed.exclude) ? parsed.exclude.filter((e) => typeof e === "string") : [];
+  const toAdd = WORKFLOW_TSCONFIG_EXCLUDES.filter((g) => !currentEx.includes(g));
+  if (toAdd.length > 0) {
+    parsed.exclude = [...currentEx, ...toAdd];
+    changes.push(`added ${toAdd.join(", ")} to "exclude"`);
+  }
+  if (changes.length === 0) return;
   fs4.writeFileSync(tsconfigPath, JSON.stringify(parsed, null, 2) + "\n");
-  console.error(
-    `Patched tsconfig.json: added ${toAdd.join(", ")} to "exclude" so npm run typecheck skips the workflow bodies (check them with: lotics app workflow check).`
-  );
+  console.error(`Patched tsconfig.json: ${changes.join("; ")}.`);
 }
 function writeAppDts(projectDir, manifest) {
   const dotLotics = path5.join(projectDir, ".lotics");
@@ -32399,6 +32410,7 @@ function writeAppDts(projectDir, manifest) {
     [path5.join(dotLotics, "app_agents.d.ts"), generateAppAgentsDts(manifest.agents)]
   ];
   for (const [file, content] of written) fs4.writeFileSync(file, content);
+  ensureAppTsconfig(projectDir);
   return written.map(([file]) => file);
 }
 function readCodegenTablesAllowlist(projectDir) {
@@ -32447,7 +32459,6 @@ async function appCodegen(args) {
     );
   }
   await refreshWorkflowGlobals(args.client, projectDir, meta.app_id, Object.keys(meta.workflows ?? {}));
-  if (Object.keys(meta.workflows ?? {}).length > 0) ensureWorkflowTsconfigExcludes(projectDir);
 }
 async function refreshWorkflowGlobals(client, projectDir, app_id, aliases) {
   for (const alias of aliases) {
@@ -32630,7 +32641,6 @@ async function appPull(client, args) {
         `Wrote ${written.length} workflow ${written.length === 1 ? "body" : "bodies"} to ${WORKFLOWS_DIR}/ (${written.join(", ")})`
       );
     }
-    ensureWorkflowTsconfigExcludes(targetPath);
   }
   console.error(`Installing npm dependencies...`);
   await runNpm(["install"], targetPath);
@@ -32945,7 +32955,7 @@ async function appWorkflowPull(client) {
   console.error(
     `Wrote ${written.length} workflow ${written.length === 1 ? "body" : "bodies"} to ${WORKFLOWS_DIR}/` + (written.length > 0 ? ` (${written.join(", ")})` : "")
   );
-  ensureWorkflowTsconfigExcludes(projectDir);
+  ensureAppTsconfig(projectDir);
 }
 async function appWorkflowCheck(args) {
   const projectDir = process.cwd();
@@ -42644,8 +42654,426 @@ function ensureVmlArray(val) {
   return Array.isArray(val) ? val : [val];
 }
 
+// ../xlsx/src/biff8_reader.ts
+var OLE2_MAGIC2 = [208, 207, 17, 224, 161, 177, 26, 225];
+var ENDOFCHAIN = 4294967294;
+var FREESECT = 4294967295;
+var DEFAULT_MAX_ROWS = 1e4;
+function isOle2(bytes) {
+  return bytes.length >= 8 && OLE2_MAGIC2.every((b, i2) => bytes[i2] === b);
+}
+function readCfbStreams(bytes) {
+  const dv = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  const u162 = (o) => dv.getUint16(o, true);
+  const u32 = (o) => dv.getUint32(o, true);
+  const sectorSize = 1 << u162(30);
+  const miniSectorSize = 1 << u162(32);
+  const firstDirSector = u32(48);
+  const miniCutoff = u32(56);
+  const firstMiniFatSector = u32(60);
+  const firstDifatSector = u32(68);
+  if (sectorSize < 512 || sectorSize > 1 << 20) {
+    throw new Error("Unsupported .xls: invalid OLE2 sector size");
+  }
+  const sectorOffset = (n) => sectorSize * (n + 1);
+  const difat = [];
+  for (let i2 = 0; i2 < 109; i2++) {
+    const v = u32(76 + i2 * 4);
+    if (v !== FREESECT) difat.push(v);
+  }
+  let ds = firstDifatSector;
+  const entriesPerSector = sectorSize / 4;
+  for (let guard = 0; ds !== ENDOFCHAIN && ds !== FREESECT && guard < 1 << 20; guard++) {
+    const base = sectorOffset(ds);
+    for (let i2 = 0; i2 < entriesPerSector - 1; i2++) {
+      const v = u32(base + i2 * 4);
+      if (v !== FREESECT) difat.push(v);
+    }
+    ds = u32(base + (entriesPerSector - 1) * 4);
+  }
+  const fat = [];
+  for (const fatSector of difat) {
+    const base = sectorOffset(fatSector);
+    for (let i2 = 0; i2 < entriesPerSector; i2++) fat.push(u32(base + i2 * 4));
+  }
+  const readChain = (src, start, size, ss, offOf, chain) => {
+    const maxSectors = Math.floor(src.length / ss) + 2;
+    const parts = [];
+    let s = start;
+    for (let guard = 0; s !== ENDOFCHAIN && s !== FREESECT && s < chain.length && guard < maxSectors; guard++) {
+      const o = offOf(s);
+      parts.push(src.subarray(o, o + ss));
+      s = chain[s];
+    }
+    const merged = concat(parts);
+    return size != null ? merged.subarray(0, size) : merged;
+  };
+  const readBig = (start, size) => readChain(bytes, start, size, sectorSize, sectorOffset, fat);
+  const dirBytes = readBig(firstDirSector, null);
+  const ddv = new DataView(dirBytes.buffer, dirBytes.byteOffset, dirBytes.byteLength);
+  const dir = [];
+  for (let off = 0; off + 128 <= dirBytes.length; off += 128) {
+    const nameLen = ddv.getUint16(off + 64, true);
+    const type = ddv.getUint8(off + 66);
+    if (nameLen < 2 || type === 0) continue;
+    const name = utf16le(dirBytes.subarray(off, off + nameLen - 2));
+    dir.push({ name, type, start: ddv.getUint32(off + 116, true), size: Number(ddv.getBigUint64(off + 120, true)) });
+  }
+  const root = dir.find((e) => e.type === 5);
+  const miniStream = root ? readBig(root.start, root.size) : new Uint8Array(0);
+  const miniFatBytes = readBig(firstMiniFatSector, null);
+  const miniFat = [];
+  for (let i2 = 0; i2 + 4 <= miniFatBytes.length; i2 += 4) miniFat.push(miniFatBytes[i2] | miniFatBytes[i2 + 1] << 8 | miniFatBytes[i2 + 2] << 16 | miniFatBytes[i2 + 3] << 24);
+  const readMini = (start, size) => readChain(miniStream, start, size, miniSectorSize, (n) => n * miniSectorSize, miniFat);
+  const readStream = (e) => e.size >= miniCutoff ? readBig(e.start, e.size) : readMini(e.start, e.size);
+  return dir.filter((e) => e.type === 2).map((e) => ({ name: e.name, bytes: readStream(e) }));
+}
+var REC = {
+  FORMULA: 6,
+  EOF: 10,
+  CONTINUE: 60,
+  DATEMODE: 34,
+  FILEPASS: 47,
+  BLANK: 513,
+  NUMBER: 515,
+  LABEL: 516,
+  STRING: 519,
+  BOOLERR: 517,
+  BOUNDSHEET: 133,
+  FORMAT: 1054,
+  XF: 224,
+  RK: 638,
+  MULRK: 189,
+  MULBLANK: 190,
+  LABELSST: 253,
+  SST: 252,
+  BOF: 2057
+};
+function* iterRecords(stream, from, to) {
+  const dv = new DataView(stream.buffer, stream.byteOffset, stream.byteLength);
+  let p = from;
+  while (p + 4 <= to) {
+    const type = dv.getUint16(p, true);
+    const len = dv.getUint16(p + 2, true);
+    const bodyStart = p + 4;
+    if (bodyStart + len > stream.length) break;
+    yield { type, body: stream.subarray(bodyStart, bodyStart + len), offset: p };
+    p = bodyStart + len;
+  }
+}
+function parseGlobals(stream) {
+  const sstChunks = [];
+  const formats = /* @__PURE__ */ new Map();
+  const xfFormatIds = [];
+  const boundsheets = [];
+  let date1904 = false;
+  let sawSst = false;
+  let sstUnique = 0;
+  let end = stream.length;
+  let started = false;
+  const dv = new DataView(stream.buffer, stream.byteOffset, stream.byteLength);
+  for (const r of iterRecords(stream, 0, stream.length)) {
+    if (r.type === REC.BOF) {
+      if (started) {
+        end = r.offset;
+        break;
+      }
+      started = true;
+      continue;
+    }
+    if (r.type === REC.EOF) {
+      end = r.offset;
+      break;
+    }
+  }
+  for (const r of iterRecords(stream, 0, end)) {
+    switch (r.type) {
+      case REC.FILEPASS:
+        throw new PasswordProtectedError();
+      case REC.DATEMODE:
+        date1904 = readU16(r.body, 0) === 1;
+        break;
+      case REC.SST:
+        sawSst = true;
+        sstUnique = readU32(r.body, 4);
+        sstChunks.push(r.body.subarray(8));
+        break;
+      case REC.CONTINUE:
+        if (sawSst) sstChunks.push(r.body);
+        break;
+      case REC.FORMAT: {
+        const id = readU16(r.body, 0);
+        formats.set(id, readUnicodeShort(r.body, 2, 2));
+        break;
+      }
+      case REC.XF: {
+        xfFormatIds.push(readU16(r.body, 2));
+        break;
+      }
+      case REC.BOUNDSHEET: {
+        const pos = dv.getUint32(r.offset + 4, true);
+        boundsheets.push({ name: readUnicodeShort(r.body, 6, 1), pos });
+        break;
+      }
+      default:
+        break;
+    }
+  }
+  const sst = parseSst(sstChunks, sstUnique);
+  const xfFormats = xfFormatIds.map((id) => formats.get(id) ?? builtinFormat(id));
+  return { sst, date1904, xfFormats, boundsheets };
+}
+function parseSst(chunks, count) {
+  const out = [];
+  if (chunks.length === 0) return out;
+  let ci = 0;
+  let off = 0;
+  const atEnd = () => ci >= chunks.length;
+  const cur = () => chunks[ci];
+  const advanceChunk = () => {
+    ci++;
+    off = 0;
+  };
+  const rawU8 = () => {
+    while (!atEnd() && off >= cur().length) advanceChunk();
+    if (atEnd()) return 0;
+    return cur()[off++];
+  };
+  const rawU16 = () => rawU8() | rawU8() << 8;
+  const rawU32 = () => rawU8() | rawU8() << 8 | rawU8() << 16 | rawU8() << 24;
+  const skip = (n) => {
+    for (let i2 = 0; i2 < n; i2++) rawU8();
+  };
+  for (let s = 0; s < count && !atEnd(); s++) {
+    const cch = rawU16();
+    const grbit = rawU8();
+    let high = (grbit & 1) !== 0;
+    const rich = (grbit & 8) !== 0 ? rawU16() : 0;
+    const ext = (grbit & 4) !== 0 ? rawU32() : 0;
+    let str = "";
+    let read = 0;
+    while (read < cch) {
+      if (off >= cur().length) {
+        advanceChunk();
+        if (atEnd()) break;
+        high = (cur()[off++] & 1) !== 0;
+      }
+      if (high) {
+        const code = cur()[off] | cur()[off + 1] << 8;
+        off += 2;
+        str += String.fromCharCode(code);
+      } else {
+        str += String.fromCharCode(cur()[off++]);
+      }
+      read++;
+    }
+    skip(rich * 4 + ext);
+    out.push(str);
+  }
+  return out;
+}
+function parseSheet2(stream, start, name, g, maxRows) {
+  const sheet = emptySheet(name);
+  const grid = /* @__PURE__ */ new Map();
+  let maxRow = -1;
+  let truncated = false;
+  const put = (row, col, cell) => {
+    if (row >= maxRows) {
+      truncated = true;
+      return;
+    }
+    let r = grid.get(row);
+    if (!r) {
+      r = /* @__PURE__ */ new Map();
+      grid.set(row, r);
+    }
+    r.set(col, cell);
+    if (row > maxRow) maxRow = row;
+  };
+  let end = stream.length;
+  let seenBof = false;
+  for (const r of iterRecords(stream, start, stream.length)) {
+    if (r.type === REC.BOF) {
+      if (seenBof) {
+        end = r.offset;
+        break;
+      }
+      seenBof = true;
+      continue;
+    }
+    if (r.type === REC.EOF) {
+      end = r.offset;
+      break;
+    }
+  }
+  for (const r of iterRecords(stream, start, end)) {
+    switch (r.type) {
+      case REC.LABELSST: {
+        const row = readU16(r.body, 0), col = readU16(r.body, 2), isst = readU32(r.body, 6);
+        put(row, col, textCell(col, g.sst[isst] ?? ""));
+        break;
+      }
+      case REC.LABEL: {
+        const row = readU16(r.body, 0), col = readU16(r.body, 2);
+        put(row, col, textCell(col, readUnicodeShort(r.body, 6, 2)));
+        break;
+      }
+      case REC.NUMBER: {
+        const row = readU16(r.body, 0), col = readU16(r.body, 2), xf = readU16(r.body, 4);
+        put(row, col, numberCell(col, readF64(r.body, 6), g.xfFormats[xf]));
+        break;
+      }
+      case REC.RK: {
+        const row = readU16(r.body, 0), col = readU16(r.body, 2), xf = readU16(r.body, 4);
+        put(row, col, numberCell(col, decodeRk(readU32(r.body, 6)), g.xfFormats[xf]));
+        break;
+      }
+      case REC.MULRK: {
+        const row = readU16(r.body, 0), first2 = readU16(r.body, 2);
+        const n = (r.body.length - 6) / 6;
+        for (let i2 = 0; i2 < n; i2++) {
+          const xf = readU16(r.body, 4 + i2 * 6);
+          const rk = readU32(r.body, 6 + i2 * 6);
+          put(row, first2 + i2, numberCell(first2 + i2, decodeRk(rk), g.xfFormats[xf]));
+        }
+        break;
+      }
+      case REC.FORMULA: {
+        const row = readU16(r.body, 0), col = readU16(r.body, 2), xf = readU16(r.body, 4);
+        const cell = formulaCell(col, r.body, g.xfFormats[xf]);
+        if (cell) put(row, col, cell);
+        break;
+      }
+      // BLANK / MULBLANK / BOOLERR carry no data value we surface — skipped.
+      default:
+        break;
+    }
+  }
+  const rows = [];
+  for (let ri = 0; ri <= maxRow; ri++) {
+    const r = grid.get(ri);
+    if (!r) continue;
+    const cells = [...r.values()].sort((a, b) => a.column - b.column);
+    rows.push({ index: ri, height: sheet.defaultRowHeight, cells, hidden: false });
+  }
+  sheet.rows = rows;
+  sheet.totalRowCount = maxRow + 1;
+  sheet.truncated = truncated;
+  return sheet;
+}
+function textCell(column, text) {
+  return { column, value: text, typedValue: text, content: { type: "plain", text }, style: {} };
+}
+function numberCell(column, num, numFmt) {
+  const value = Number.isFinite(num) ? String(num) : "";
+  return {
+    column,
+    value,
+    rawValue: num,
+    typedValue: num,
+    numFmtCode: numFmt && numFmt !== "General" ? numFmt : void 0,
+    content: { type: "plain", text: value },
+    style: {}
+  };
+}
+function formulaCell(column, body, numFmt) {
+  if (readU16(body, 12) === 65535) {
+    const kind = body[6];
+    if (kind === 1) {
+      const b = body[8] !== 0;
+      return { column, value: b ? "TRUE" : "FALSE", typedValue: b, content: { type: "plain", text: b ? "TRUE" : "FALSE" }, style: {} };
+    }
+    return null;
+  }
+  return numberCell(column, readF64(body, 6), numFmt);
+}
+function decodeRk(rk) {
+  const div100 = (rk & 1) !== 0;
+  const isInt = (rk & 2) !== 0;
+  let n;
+  if (isInt) {
+    n = rk >> 2;
+  } else {
+    const buf = new ArrayBuffer(8);
+    new DataView(buf).setUint32(4, rk & 4294967292, true);
+    n = new DataView(buf).getFloat64(0, true);
+  }
+  return div100 ? n / 100 : n;
+}
+function readU16(b, o) {
+  return b[o] | b[o + 1] << 8;
+}
+function readU32(b, o) {
+  return (b[o] | b[o + 1] << 8 | b[o + 2] << 16 | b[o + 3] << 24) >>> 0;
+}
+function readF64(b, o) {
+  return new DataView(b.buffer, b.byteOffset + o, 8).getFloat64(0, true);
+}
+function readUnicodeShort(b, offset, lenBytes) {
+  const cch = lenBytes === 1 ? b[offset] : readU16(b, offset);
+  const grbit = b[offset + lenBytes];
+  const high = (grbit & 1) !== 0;
+  let p = offset + lenBytes + 1;
+  let s = "";
+  for (let i2 = 0; i2 < cch; i2++) {
+    if (high) {
+      s += String.fromCharCode(b[p] | b[p + 1] << 8);
+      p += 2;
+    } else {
+      s += String.fromCharCode(b[p]);
+      p += 1;
+    }
+  }
+  return s;
+}
+function utf16le(b) {
+  let s = "";
+  for (let i2 = 0; i2 + 1 < b.length; i2 += 2) s += String.fromCharCode(b[i2] | b[i2 + 1] << 8);
+  return s;
+}
+function concat(parts) {
+  let total = 0;
+  for (const p of parts) total += p.length;
+  const out = new Uint8Array(total);
+  let o = 0;
+  for (const p of parts) {
+    out.set(p, o);
+    o += p.length;
+  }
+  return out;
+}
+function builtinFormat(id) {
+  const DATES = {
+    14: "m/d/yyyy",
+    15: "d-mmm-yy",
+    16: "d-mmm",
+    17: "mmm-yy",
+    18: "h:mm AM/PM",
+    19: "h:mm:ss AM/PM",
+    20: "h:mm",
+    21: "h:mm:ss",
+    22: "m/d/yyyy h:mm",
+    45: "mm:ss",
+    46: "[h]:mm:ss",
+    47: "mm:ss.0"
+  };
+  return DATES[id] ?? "General";
+}
+function parseBiff8(bytes, options) {
+  const streams = readCfbStreams(bytes);
+  if (streams.some((s) => /^EncryptedPackage$/i.test(s.name))) throw new PasswordProtectedError();
+  const wb = streams.find((s) => /^workbook$/i.test(s.name)) ?? streams.find((s) => /^book$/i.test(s.name));
+  if (!wb) throw new Error("Not a valid .xls: no Workbook stream in the OLE2 container");
+  const g = parseGlobals(wb.bytes);
+  const maxRows = options?.maxRowsPerSheet ?? DEFAULT_MAX_ROWS;
+  const sheets = g.boundsheets.length > 0 ? g.boundsheets.map((bs) => parseSheet2(wb.bytes, bs.pos, bs.name, g, maxRows)) : [emptySheet("Sheet1")];
+  return { sheets, activeSheetIndex: 0 };
+}
+
 // ../xlsx/src/excel_parser.ts
 function parseExcelBuffer(arrayBuffer, options) {
+  const bytes = new Uint8Array(arrayBuffer);
+  if (isOle2(bytes)) return parseBiff8(bytes, options);
   const zip = unzipXlsx(arrayBuffer);
   return parseExcelFromZip(zip, options);
 }
@@ -49203,7 +49631,8 @@ COMMANDS
                                        Download all files on a record file field
   lotics app create <name> [path]      Create a new custom-code app + scaffold locally
   lotics app pull <app_id> [path]      Bootstrap full local env (source + npm install + types)
-  lotics app deploy [-m <message>]     Build + upload current dir as a new version
+  lotics app deploy -m <message>       Build + upload current dir as a new version
+                                       (-m is required \u2014 it's the version's audit trail)
                                        (code + queries only \u2014 workflow bindings are
                                        managed by set_app_workflow / remove_app_workflow)
   lotics app versions [app_id]         Show deploy history newest-first (version,
@@ -49683,7 +50112,7 @@ async function main() {
     console.error("Usage:");
     console.error("  lotics app create <name> [path]      Scaffold a new app locally");
     console.error("  lotics app pull <app_id> [path]      Pull an existing app for local editing");
-    console.error("  lotics app deploy [-m <message>]     Build + upload the current directory");
+    console.error("  lotics app deploy -m <message>       Build + upload the current directory (-m required)");
     console.error("  lotics app versions [app_id]         Show deploy history (version, when, who, message)");
     console.error("  lotics app codegen [path]            Regenerate .lotics/* (types + field ids) \u2014 no deploy");
     console.error("  lotics app workflow run <alias> '<json>'  Execute a bound app workflow end-to-end");
@@ -49807,7 +50236,12 @@ Available workspaces:`);
       return;
     }
     if (subcommand === "deploy") {
-      const message = flags.message ?? toolArgs;
+      const message = (flags.message ?? toolArgs)?.trim();
+      if (!message) {
+        console.error('Usage: lotics app deploy -m "<what changed + why>"');
+        console.error("A deploy message is required \u2014 it's the version's audit trail (see `lotics app versions`).");
+        process.exit(1);
+      }
       await appDeploy(client, { message });
       return;
     }

package/package.json

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