@lotics/cli 0.100.0 → 0.101.0

package/dist/src/cli.js

@@ -44769,8 +44769,8 @@ var LoticsClient = class {
    * no caller has to remember that a partial payload silently drops
    * `instructions`, `outputs` and the model pin.
    */
-  async setAppAgent(app_id, alias, declaration) {
-    return this.execute("set_app_agent", { app_id, alias, ...declaration });
+  async setAppAgent(app_id, alias, patch) {
+    return this.execute("set_app_agent", { app_id, alias, ...patch });
   }
   /**
    * Fetch one app workflow's faithful source + bound input/output schemas via
@@ -47256,12 +47256,58 @@ function undeclaredCapabilities(sourceText, declared) {
   }
   return used;
 }
-function unboundAliases(declared, bound) {
-  const boundWorkflows = new Set(bound.workflows ?? []);
-  const boundAgents = new Set(bound.agents ?? []);
+function driftedQueryAliases(a, b) {
+  const left = a ?? {};
+  const right = b ?? {};
+  return [.../* @__PURE__ */ new Set([...Object.keys(left), ...Object.keys(right)])].filter((alias) => canonicalJson(left[alias]) !== canonicalJson(right[alias])).sort();
+}
+function canonicalJson(value) {
+  const normalize = (v) => {
+    if (Array.isArray(v)) return v.map(normalize);
+    if (v === null || typeof v !== "object") return v;
+    const entries2 = Object.entries(v).sort(
+      ([x2], [y]) => x2 < y ? -1 : x2 > y ? 1 : 0
+    );
+    return entries2.map(([key, val]) => [key, normalize(val)]);
+  };
+  return JSON.stringify(normalize(value));
+}
+var ALIAS_CALL_HOOKS = {
+  queries: "useQuery",
+  workflows: "useWorkflow",
+  agents: "useAgentRun"
+};
+var LITERAL_ALIAS_ARG = `["'\`]([A-Za-z_$][A-Za-z0-9_$]*)["'\`]`;
+function calledAppAliases(sourceText) {
+  const out = {
+    queries: [],
+    workflows: [],
+    agents: [],
+    dynamic: []
+  };
+  for (const [kind, hook] of Object.entries(ALIAS_CALL_HOOKS)) {
+    const seen = /* @__PURE__ */ new Set();
+    let isDynamic = false;
+    for (const call of sourceText.matchAll(new RegExp(`\\b${hook}\\s*\\(`, "g"))) {
+      const rest = sourceText.slice(call.index + call[0].length);
+      const literal2 = new RegExp(`^\\s*${LITERAL_ALIAS_ARG}`).exec(rest);
+      if (literal2) seen.add(literal2[1]);
+      else isDynamic = true;
+    }
+    out[kind] = [...seen];
+    if (isDynamic) out.dynamic.push(hook);
+  }
+  return out;
+}
+function unboundAliases(called, bound) {
+  const missing = (from, against) => {
+    const have = new Set(against ?? []);
+    return [...from ?? []].filter((alias) => !have.has(alias));
+  };
   return {
-    workflows: [...declared.workflows ?? []].filter((a) => !boundWorkflows.has(a)),
-    agents: [...declared.agents ?? []].filter((a) => !boundAgents.has(a))
+    queries: missing(called.queries, bound.queries),
+    workflows: missing(called.workflows, bound.workflows),
+    agents: missing(called.agents, bound.agents)
   };
 }
 
@@ -69927,9 +69973,9 @@ function findPlaceableWindow(chars, from, width) {
   return null;
 }
 
-// src/workflow_envelope.ts
-var FALLBACK_ENVELOPE_PREFIX = "async function __workflow(): Promise<__WorkflowReturn | void> {\n";
-var FALLBACK_ENVELOPE_SUFFIX = "\n}";
+// ../shared/src/workflow_envelope.ts
+var WORKFLOW_ENVELOPE_PREFIX = "async function __workflow(): Promise<__WorkflowReturn | void> {\n";
+var WORKFLOW_ENVELOPE_SUFFIX = "\n}";
 var WORKFLOW_WRAPPER_OPENER = /^\s*async\s+function\s+__workflow\s*\(/;
 function stripWorkflowHeader(content) {
   const lines = content.split("\n");
@@ -70074,6 +70120,25 @@ function checkWorkflowBodies(tsApi, aliases) {
   }));
 }
 
+// ../shared/src/agent_instructions.ts
+function agentFilePath(alias) {
+  return `src/agents/${alias}.md`;
+}
+function agentFileHeader(alias, notes = []) {
+  return `<!-- lotics: instructions for agent "${alias}".
+` + notes.map((n) => `     ${n}
+`).join("") + `     This comment is stripped before the prose reaches the live prompt. -->`;
+}
+function wrapAgentFile(args) {
+  return `${agentFileHeader(args.alias, args.notes)}
+
+${args.instructions.replace(/\s+$/, "")}
+`;
+}
+function stripAgentHeader(text) {
+  return text.replace(/<!--\s*lotics:[\s\S]*?-->\n?/g, "").replace(/\n{3,}/g, "\n\n").trim();
+}
+
 // src/app_commands.ts
 async function fetchLatestNpmVersion(packageName) {
   try {
@@ -70105,8 +70170,11 @@ var STALE_LOTICS_INCLUDES = /* @__PURE__ */ new Set([".lotics", "./.lotics", ".l
 function toWorkflowDtsDeclaration(d) {
   return { inputs: d.inputs, outputs: d.outputs };
 }
+function isMissingWorkflowBodyError(error51) {
+  return /has no step source|cannot be rendered|unsupported step/i.test(error51);
+}
 function isUnknownWorkflowAliasError(err2) {
-  return err2 instanceof Error && /^400:/.test(err2.message) && /has no workflow alias/i.test(err2.message);
+  return err2 instanceof Error && err2.message.startsWith("400:") && /has no workflow alias/i.test(err2.message);
 }
 function workflowFileHeader(alias) {
   const refPath = path5.join("..", "..", WORKFLOW_GLOBALS_DIR, `${alias}.globals.d.ts`).split(path5.sep).join("/");
@@ -70136,7 +70204,7 @@ function writeWorkflowGlobals(projectDir, alias, dts) {
 `);
   return file2;
 }
-function writeWorkflowFile(projectDir, alias, source, envelope = { prefix: FALLBACK_ENVELOPE_PREFIX, suffix: FALLBACK_ENVELOPE_SUFFIX }) {
+function writeWorkflowFile(projectDir, alias, source, envelope = { prefix: WORKFLOW_ENVELOPE_PREFIX, suffix: WORKFLOW_ENVELOPE_SUFFIX }) {
   const dir = path5.join(projectDir, WORKFLOWS_DIR);
   fs4.mkdirSync(dir, { recursive: true });
   const file2 = workflowFilePath(projectDir, alias);
@@ -70146,24 +70214,20 @@ ${envelope.prefix}${body}${envelope.suffix}
 `);
   return file2;
 }
-function agentFilePath(projectDir, alias) {
-  return path5.join(projectDir, AGENTS_DIR, `${alias}.md`);
-}
-function agentFileHeader(alias) {
-  return `<!-- lotics: instructions for agent "${alias}".
-     Pulled from the LIVE app row; edit here, then: lotics app agent set ${alias}
-     The typed fields (inputs/outputs/tool_names/model_id) live in package.json#lotics.agents.${alias} -->`;
-}
-function stripAgentHeader(text) {
-  return text.replace(/<!--\s*lotics:[\s\S]*?-->\n?/g, "").replace(/\n{3,}/g, "\n\n").trim();
+function agentFilePath2(projectDir, alias) {
+  return path5.join(projectDir, ...agentFilePath(alias).split("/"));
 }
+var CLI_AGENT_NOTES = [
+  "Pulled from the LIVE app row; edit here, then: lotics app agent set <alias>",
+  "The typed fields (inputs/outputs/tool_names/model_id) live in package.json#lotics.agents"
+];
 function writeAgentFile(projectDir, alias, instructions) {
   fs4.mkdirSync(path5.join(projectDir, AGENTS_DIR), { recursive: true });
-  const file2 = agentFilePath(projectDir, alias);
-  fs4.writeFileSync(file2, `${agentFileHeader(alias)}
-
-${instructions.replace(/\s+$/, "")}
-`);
+  const file2 = agentFilePath2(projectDir, alias);
+  fs4.writeFileSync(
+    file2,
+    wrapAgentFile({ alias, instructions, notes: CLI_AGENT_NOTES.map((n) => n.replace("<alias>", alias)) })
+  );
   return file2;
 }
 function writeAgentFiles(projectDir, agents) {
@@ -70183,10 +70247,15 @@ async function writeWorkflowFiles(client, projectDir, app_id, workflows) {
   const written = [];
   for (const [alias, declaration] of Object.entries(workflows)) {
     const res = await client.getAppWorkflow(app_id, alias);
-    const source = res.error || res.result === null || typeof res.result !== "object" ? null : res.result.source;
+    if (res.error && !isMissingWorkflowBodyError(res.error)) {
+      throw new Error(
+        `Could not read workflow "${alias}" of ${app_id}: ${res.error}. Reading app workflow source requires an admin member \u2014 check the role behind this API key.`
+      );
+    }
+    const source = res.result === null || typeof res.result !== "object" ? null : res.result.source;
     if (typeof source !== "string" || source.trim() === "") {
       console.error(
-        `\u26A0 Skipped src/workflows/${alias}.ts \u2014 the server returned no readable source (${res.error ?? "legacy workflow with no rendered body"}).`
+        `\u26A0 Skipped src/workflows/${alias}.ts \u2014 legacy workflow with no rendered body.`
       );
       continue;
     }
@@ -70216,7 +70285,7 @@ async function fetchWorkflowGlobals(client, projectDir, app_id, alias, declarati
     console.error(
       `\u26A0 Could not fetch workflow types for "${alias}" (${err2 instanceof Error ? err2.message : String(err2)}). Wrote the body with the fallback wrapper; its local typecheck may be degraded.`
     );
-    return { prefix: FALLBACK_ENVELOPE_PREFIX, suffix: FALLBACK_ENVELOPE_SUFFIX };
+    return { prefix: WORKFLOW_ENVELOPE_PREFIX, suffix: WORKFLOW_ENVELOPE_SUFFIX };
   }
 }
 async function fetchWorkflowDts(client, app_id, alias, declaration) {
@@ -70684,7 +70753,16 @@ function readAppSourceText(projectDir) {
 async function appDeploy(client, args) {
   const projectDir = path5.resolve(args.projectDir ?? process.cwd());
   const meta3 = readAppMeta(projectDir);
-  const undeclared = undeclaredCapabilities(readAppSourceText(projectDir), meta3.capabilities);
+  const sourceText = readAppSourceText(projectDir);
+  const called = calledAppAliases(sourceText);
+  if (called.dynamic.length > 0) {
+    console.error(
+      `
+\u26A0 This app calls ${called.dynamic.join(" / ")} with an alias it computes at runtime, which this deploy cannot read.
+  The version records only the aliases named as literals, so removing a binding this app reaches dynamically will NOT be refused.`
+    );
+  }
+  const undeclared = undeclaredCapabilities(sourceText, meta3.capabilities);
   if (undeclared.length > 0) {
     const block = JSON.stringify(Object.fromEntries(undeclared.map((c) => [c, true])));
     console.error(
@@ -70721,29 +70799,30 @@ async function appDeploy(client, args) {
     );
     console.error("Packaging dist...");
     await runTar(["-czf", tmpDist, "-C", distDir, "."], projectDir);
+    const liveQueries = await readLiveQueries(client, meta3.app_id);
     console.error("Uploading...");
     try {
       const result = await client.deployAppVersion({
+        queries: liveQueries,
         app_id: meta3.app_id,
         source_archive: fs4.readFileSync(tmpSource),
         dist_archive: fs4.readFileSync(tmpDist),
         prev_version_id: meta3.current_version_id,
         message: args.message,
-        // Sync apps.queries from the manifest. Server validates each query
-        // template (parseQueryNode, table access, param coverage).
-        queries: meta3.queries ?? {},
-        // Capabilities are manifest-authoritative (like queries): always send,
+        // Capabilities ARE manifest-authoritative: always send,
         // defaulting to `{}` when the manifest declares none — so deleting the
         // `capabilities` block turns every capability OFF on the next deploy
         // (fail-safe; the declaration is the grant).
         capabilities: meta3.capabilities ?? {},
         // Workflow BINDINGS are NOT a deploy concern — set_app_workflow /
-        // remove_app_workflow own apps.workflows. But the alias KEYS of the
-        // manifest's `workflows` map ARE sent (never the bindings): they record
-        // which aliases this bundle declares, so remove_app_workflow can refuse
-        // to unbind an alias the served version still calls. Drop an alias from
-        // the manifest + redeploy to lift that guard before removing its binding.
-        workflow_aliases: Object.keys(meta3.workflows ?? {})
+        // remove_app_workflow own apps.workflows. What IS sent is the set of
+        // aliases this bundle CALLS (never the bindings), so remove_app_workflow
+        // can refuse to unbind one the served version still uses. Read off the
+        // source, the same rule the chat publish uses: the manifest's map is a
+        // typing artifact maintained by habit, so its keys answered this question
+        // with whatever the author last remembered to write. Stop calling an
+        // alias + redeploy to lift the guard before removing its binding.
+        workflow_aliases: called.workflows
       });
       writeAppMeta(projectDir, {
         ...meta3,
@@ -70755,7 +70834,8 @@ async function appDeploy(client, args) {
       try {
         const app = await client.getApp(meta3.app_id);
         warnIfUnbranded(app);
-        warnIfUnboundAliases(app, meta3.workflows ?? {}, meta3.agents ?? {});
+        warnIfUnboundAliases(app, called);
+        warnIfQueriesDiffer(app, meta3.queries ?? {});
       } catch (err2) {
         console.error(`(skipped post-deploy checks: ${err2.message})`);
       }
@@ -70786,17 +70866,47 @@ function warnIfUnbranded(app) {
   Find an icon:  lotics run search_app_icons '{"query":"<word>"}'`
   );
 }
-function warnIfUnboundAliases(app, declaredWorkflows, declaredAgents) {
-  const { workflows: unboundWorkflows, agents: unboundAgents } = unboundAliases(
-    { workflows: Object.keys(declaredWorkflows), agents: Object.keys(declaredAgents) },
-    { workflows: Object.keys(app.workflows ?? {}), agents: Object.keys(app.agents ?? {}) }
+async function readLiveQueries(client, appId) {
+  try {
+    const app = await client.getApp(appId);
+    return app.queries ?? {};
+  } catch (err2) {
+    console.error(
+      `Could not read ${appId}'s current queries, which this deploy has to send back unchanged: ${err2 instanceof Error ? err2.message : String(err2)}
+  Nothing was deployed. Retry.`
+    );
+    process.exit(1);
+  }
+}
+function warnIfQueriesDiffer(app, manifest) {
+  const drifted = driftedQueryAliases(manifest, app.queries);
+  if (drifted.length === 0) return;
+  console.error(
+    `
+\u26A0 ${drifted.length} quer${drifted.length === 1 ? "y" : "ies"} in package.json differ from the app: ${drifted.join(", ")}
+  A deploy does not write them. Push yours with 'lotics app query set --all'
+  (or one alias at a time), or adopt the app's with 'lotics app pull'.`
   );
-  if (unboundWorkflows.length === 0 && unboundAgents.length === 0) return;
+}
+function warnIfUnboundAliases(app, called) {
+  const {
+    queries: unboundQueries,
+    workflows: unboundWorkflows,
+    agents: unboundAgents
+  } = unboundAliases(called, {
+    queries: Object.keys(app.queries ?? {}),
+    workflows: Object.keys(app.workflows ?? {}),
+    agents: Object.keys(app.agents ?? {})
+  });
+  if (unboundQueries.length === 0 && unboundWorkflows.length === 0 && unboundAgents.length === 0) {
+    return;
+  }
   const lines = [
-    "\n\u26A0 The manifest declares aliases that are NOT bound on the server. Deploy ships code +",
-    '  queries only \u2014 it does NOT bind workflows/agents, so the app will throw "has no \u2026 alias"',
-    "  the first time it calls them. Bind each one:"
+    "\n\u26A0 This app CALLS aliases that are NOT bound on the server. A deploy ships code and",
+    '  binds nothing, so the app will throw "has no \u2026 alias" the first time it calls them.',
+    "  Bind each one:"
   ];
+  for (const alias of unboundQueries) lines.push(`  \u2022 query "${alias}"  \u2192  lotics app query set ${alias}`);
   for (const alias of unboundWorkflows) lines.push(`  \u2022 workflow "${alias}"  \u2192  lotics app workflow set ${alias}`);
   for (const alias of unboundAgents) lines.push(`  \u2022 agent "${alias}"  \u2192  bind with set_app_agent (lotics run set_app_agent \u2026)`);
   console.error(lines.join("\n"));
@@ -71031,7 +71141,7 @@ async function appAgentSet(client, args) {
     );
     process.exit(1);
   }
-  const file2 = agentFilePath(projectDir, args.alias);
+  const file2 = agentFilePath2(projectDir, args.alias);
   if (!fs4.existsSync(file2)) {
     console.error(
       `No instructions at ${path5.relative(projectDir, file2)}. Run 'lotics app pull ${meta3.app_id}' to write ${AGENTS_DIR}/${args.alias}.md, then edit it.`
@@ -71045,13 +71155,13 @@ async function appAgentSet(client, args) {
     );
     process.exit(1);
   }
-  const res = await client.setAppAgent(meta3.app_id, args.alias, { ...live, instructions });
+  const res = await client.setAppAgent(meta3.app_id, args.alias, { instructions });
   if (res.error) {
     console.error(`Failed to set agent "${args.alias}": ${res.error}`);
     process.exit(1);
   }
   console.error(
-    `Set agent "${args.alias}" (${instructions.length} chars of instructions` + (live.model_id ? `, ${live.model_id}` : "") + `). Typed fields taken from the live row.`
+    `Set agent "${args.alias}" (${instructions.length} chars of instructions` + (live.model_id ? `, ${live.model_id}` : "") + `). Typed fields left as they are.`
   );
 }
 async function appWorkflowSet(client, args) {
@@ -71106,20 +71216,31 @@ async function appWorkflowSet(client, args) {
 async function appQuerySet(client, args) {
   const projectDir = process.cwd();
   const meta3 = readAppMeta(projectDir);
-  const declaration = meta3.queries?.[args.alias];
-  if (!declaration) {
-    console.error(
-      `No query "${args.alias}" in package.json#lotics.queries. Declare it there (alias \u2192 { ast, params? }) first.`
-    );
-    process.exit(1);
+  const declared = meta3.queries ?? {};
+  const aliases = "all" in args ? Object.keys(declared).sort() : [args.alias];
+  if (aliases.length === 0) {
+    console.error("No queries in package.json#lotics.queries \u2014 nothing to push.");
+    return;
   }
-  const res = await client.setAppQuery(meta3.app_id, args.alias, declaration);
-  if (res.error) {
-    console.error(`Failed to set query "${args.alias}": ${res.error}`);
-    process.exit(1);
+  const pushed = [];
+  for (const alias of aliases) {
+    const declaration = declared[alias];
+    if (!declaration) {
+      console.error(
+        `No query "${alias}" in package.json#lotics.queries. Declare it there (alias \u2192 { ast, params? }) first.`
+      );
+      process.exit(1);
+    }
+    const res = await client.setAppQuery(meta3.app_id, alias, declaration);
+    if (res.error) {
+      if (pushed.length > 0) console.error(`Pushed before the failure: ${pushed.join(", ")}.`);
+      console.error(`Failed to set query "${alias}": ${res.error}`);
+      process.exit(1);
+    }
+    pushed.push(alias);
   }
   console.error(
-    `Set query "${args.alias}" on ${meta3.app_id}. (apps.queries is manifest-authoritative \u2014 the next 'lotics app deploy' re-syncs it.)`
+    `Set ${pushed.length} quer${pushed.length === 1 ? "y" : "ies"} on ${meta3.app_id}: ${pushed.join(", ")}.`
   );
 }
 async function appWorkflowPull(client) {
@@ -92655,11 +92776,15 @@ Available workspaces:`);
     if (subcommand === "query") {
       const action = toolArgs;
       if (action === "set") {
-        const alias = restArgs[0];
+        if (restArgs.includes("--all")) {
+          await appQuerySet(client, { all: true });
+          return;
+        }
+        const alias = restArgs.find((a) => !a.startsWith("--"));
         if (!alias) {
-          console.error("Usage: lotics app query set <alias>");
+          console.error("Usage: lotics app query set <alias> | --all");
           console.error(
-            "Pushes package.json#lotics.queries.<alias> to apps.queries via set_app_query (no deploy)."
+            "Pushes package.json#lotics.queries to apps.queries via set_app_query. A deploy does not."
           );
           process.exit(1);
         }
@@ -92668,7 +92793,10 @@ Available workspaces:`);
       }
       console.error("Usage:");
       console.error(
-        "  lotics app query set <alias>   Push package.json#lotics.queries.<alias> to apps.queries (no deploy)"
+        "  lotics app query set <alias>   Push package.json#lotics.queries.<alias> to apps.queries"
+      );
+      console.error(
+        "  lotics app query set --all     Push every declared query (a deploy does not write them)"
       );
       process.exit(1);
     }

package/dist/src/client.d.ts

@@ -879,12 +879,10 @@ export declare class LoticsClient {
      * `instructions`, `outputs` and the model pin.
      */
     setAppAgent(app_id: string, alias: string, 
-    /** The WHOLE declaration. Typed loosely on purpose: the caller builds it by
-     *  spreading the live one, so a field the server adds later is forwarded
-     *  without this signature (or the caller) having to learn about it. */
-    declaration: Record<string, unknown> & {
-        instructions: string;
-    }): Promise<ToolExecuteResult>;
+    /** ONLY the fields being changed. The server merges against the stored
+     *  declaration, so nothing a caller omits is lost and a field the server adds
+     *  later needs no change here. Pass `null` to clear an optional field. */
+    patch: Record<string, unknown>): Promise<ToolExecuteResult>;
     /**
      * Fetch one app workflow's faithful source + bound input/output schemas via
      * `get_app_workflow`. `source` is the JS-subset body re-rendered from the

package/dist/src/client.js

@@ -572,11 +572,11 @@ export class LoticsClient {
      * `instructions`, `outputs` and the model pin.
      */
     async setAppAgent(app_id, alias, 
-    /** The WHOLE declaration. Typed loosely on purpose: the caller builds it by
-     *  spreading the live one, so a field the server adds later is forwarded
-     *  without this signature (or the caller) having to learn about it. */
-    declaration) {
-        return this.execute("set_app_agent", { app_id, alias, ...declaration });
+    /** ONLY the fields being changed. The server merges against the stored
+     *  declaration, so nothing a caller omits is lost and a field the server adds
+     *  later needs no change here. Pass `null` to clear an optional field. */
+    patch) {
+        return this.execute("set_app_agent", { app_id, alias, ...patch });
     }
     /**
      * Fetch one app workflow's faithful source + bound input/output schemas via

package/docs/cli_reference.md

@@ -30,13 +30,13 @@ Per-command syntax, flags, contracts, and gotchas for the public `lotics` CLI. S
 | `lotics knowledge rm <id>` | Archive the doc via `delete_knowledge` (`{ knowledge_doc_id }`). The REST execute path does not gate `needsApproval`, so this runs unattended. |
 | `lotics app create <name> [path]` | Scaffold a Vite+React+TS custom-code app project; POST /v1/apps; npm install; vite build; upload as v1 |
 | `lotics app pull <app_id> [path]` | Download source archive from R2 (presigned), extract, npm install, stamp package.json's `lotics` field. With no `[path]`: refresh the cwd IN PLACE when it's already this app's own project (its manifest `app_id` matches — the documented `cd <app> && lotics app pull` flow), else clone into an `<name>/` subdir; this avoids the stray nested `./<name>/` subdir a pull-from-inside-the-app used to drop. — `workflows` and `agents` are sourced from the live App row (NOT the archived manifest), so `set_app_workflow` / `set_app_agent` authoring survives the pull. Regenerates `.lotics/app_{workflows,queries,agents}.d.ts` so `useWorkflow` / `useQuery` / `useAgentRun` stay typed. Also writes one `src/workflows/<alias>.ts` per bound workflow (faithful body from `get_app_workflow`) and one `src/agents/<alias>.md` per bound agent (its instructions, straight off the live row) — so the prose an author actually edits lives in a file, and pull always overwrites it from live, leaving no second copy to drift. A legacy workflow alias with no rendered source, or an agent with no instructions, warns and is skipped. The stamped `lotics.agents` map carries the TYPED half only (`inputs`/`outputs`/`tool_names`/`model_id`/…) — an agent's prose lives solely in its `.md`, so there is never a second local copy to desync; a stale `instructions` left by an older CLI is inert and disappears on the next pull |
-| `lotics app deploy -m <message>` | **`-m` is REQUIRED** (CLI errors without a non-empty message) — each deploy is a version row read back by `lotics app versions`, so a blank message loses the audit trail. npm run build; tar source + dist; POST /v1/apps/{id}/versions multipart. Carries code + queries + capabilities only — workflow bindings are NOT a deploy concern (`set_app_workflow` / `remove_app_workflow` own `apps.workflows`; the manifest's `workflows` map is a pulled reflection used only for `useWorkflow` codegen). Deploy DOES send the manifest's `lotics.workflows` alias KEYS (not the bindings) as `workflow_aliases`, recorded on the version row so `remove_app_workflow` can refuse to unbind an alias the served version still declares. After a successful deploy it also **warns loudly about any `lotics.workflows` / `lotics.agents` alias declared in the manifest but NOT bound on the server** (a `getApp` diff via `warnIfUnboundAliases`) — since deploy never binds them, that would otherwise throw only at the app's first `useWorkflow` / `useAgentRun` call; the warning points to `lotics app workflow set` / `set_app_agent`. Advisory only (never fails the deploy). |
+| `lotics app deploy -m <message>` | **`-m` is REQUIRED** (CLI errors without a non-empty message) — each deploy is a version row read back by `lotics app versions`, so a blank message loses the audit trail. npm run build; tar source + dist; POST /v1/apps/{id}/versions multipart. Carries code + capabilities only — **neither queries nor workflow/agent bindings are a deploy concern** (`set_app_workflow` / `remove_app_workflow` own `apps.workflows`; the manifest's `workflows` map is a pulled reflection used only for `useWorkflow` codegen). Deploy DOES send the manifest's `lotics.workflows` alias KEYS (not the bindings) as `workflow_aliases`, recorded on the version row so `remove_app_workflow` can refuse to unbind an alias the served version still declares. It also reports any `lotics.queries` alias whose declaration DIFFERS from the app's, naming both recoveries (`app query set --all` to push yours, `app pull` to adopt the app's) — a deploy no longer writes them, so the two are allowed to drift. After a successful deploy it **warns loudly about any alias the source CALLS that is NOT bound on the server** (a `getApp` diff via `warnIfUnboundAliases`) — since deploy never binds them, that would otherwise throw only at the app's first `useWorkflow` / `useAgentRun` call; the warning points to `lotics app workflow set` / `set_app_agent`. Advisory only (never fails the deploy). |
 | `lotics app versions [app_id]` | `GET /v1/apps/{id}/versions` — print deploy history newest-first (version number, timestamp, deployer name, build status, the `-m` message; `*` marks the currently-served version). app_id from the local manifest, or pass one to inspect any app without pulling it. Admin-only server-side (mirrors deploy + source download). Answers "what shipped, when, by whom" — e.g. whether a fix was live at an incident's time. The deploy pipeline already persisted all of this in `app_versions`; this is the read surface. Title → stderr, table → stdout (pipeable). |
 | `lotics app codegen [path]` | Regenerate `.lotics/*` from the manifest + workspace schema **without a deploy**. The three `.d.ts` companions (`app_{workflows,queries,agents}.d.ts`) are always rewritten (synchronous, no network). When credentials resolve, also rewrites the **runtime** `.lotics/app_fields.ts` — **branched on whether the app is a package installation** (`getApp().package_id` set, from `generate_package_fields.ts`): a **linked/published** app emits the BINDING form (`F`/`OPT`/`ROLE` resolved from the installation's LIVE binding — via `appBinding` / the `binding` RPC — at module load through `getAppBinding()` + top-level await, so the source stays portable across every install); a **bespoke** app emits the BAKED form (`generate_app_fields.ts`) — a real `.ts` exporting `F` (table→field→`"fld_…"`) + `OPT` (table→select-field→option→`"opt_…"`) keyed by display-name aliases, for the tables the app's queries reference (+ optional `package.json#lotics.codegen.tables` allowlist). Both forms share the `F`/`OPT` shape (contract aliases derive from the same slugified display names), so a published origin's deployed source compiles unchanged. Writing the BINDING form also heals the project's vitest setup (`ensureAppVitestSetup`, folded into the same write boundary): the binding form awaits `getAppBinding()` (a network call) at module load, so without a stub `npm test` fails to collect any test that imports the app graph — the heal writes `vitest.setup.ts` (mocks only `getAppBinding`, returning an echo binding: any alias → a self-identifying `fld:test:…`/`opt:test:…`/`grp:test:…` id) if absent, and warns the one-liner to add to `vite.config.ts`'s `test.setupFiles` if the wiring is missing (TS source isn't safely munged, mirroring `ensureAppTsconfig`'s JSONC-tsconfig warn). New scaffolds ship both. Also refreshes each bound workflow's `.lotics/workflows/<alias>.globals.d.ts` + re-wraps its EXISTING `src/workflows/<alias>.ts` body in the current envelope (strips + re-wraps; never re-fetches the body, so local edits survive). A getApp / binding / schema / dts-fetch failure is non-fatal (warns, keeps the last-generated files). |
 | `lotics app workflow run <alias> '<json>'` | Execute a bound app workflow end-to-end via `appWorkflow`. `app_id` comes from the local manifest; the alias must be bound (`set_app_workflow`). Inputs ingest exactly like `lotics run` (inline JSON / `@file` / stdin — bulk inputs bypass `ARG_MAX`). Prints the full `{status,message,data,files,side_effects}` JSON to stdout + a one-line summary to stderr; exits non-zero on `status:"error"` (assertable). `--print-created` (alias `--report-effects`) renders the honest post-run harvest (GAP-58): created records grouped by table, a paste-ready `lotics run delete_records …` per table, then the **mandatory caveat** naming what cannot be auto-undone (external integrations + notifications) and that sub-workflows may have run. `--cleanup` (DEFAULT OFF, implies the report) additionally runs the deletes for harvested records ONLY — never files / external / notifications. Neither is a rollback — a rollback is structurally impossible here. |
 | `lotics app workflow set <alias>` | Push the edited `src/workflows/<alias>.ts` body through `set_app_workflow` (the single author of `apps.workflows`). Reads the body from disk (header + `/// <reference>` + `export {};` marker + the `__workflow` wrapper all stripped) + the typed `inputs`/`outputs` from `package.json#lotics.workflows.<alias>`; the **server** re-verifies the body and echoes the bound `outputs` (declared, else DERIVED from `return({ data })`). When the manifest declared NO `outputs`, the DERIVED echo is written back into `package.json#lotics.workflows.<alias>.outputs` (a SURGICAL write — preserves `knowledge`/`config` and every other manifest field) and that alias's types are refreshed in place, so `useWorkflow("<alias>")`'s `result.data` is typed immediately with no hand-copy and no second `lotics app codegen`; an explicitly-declared `outputs` is authoritative and never overwritten. Deploy still never authors workflows — this is a CLI convenience over the existing tool. Clear error + non-zero exit on a missing file, an alias absent from the manifest, or a verify failure. |
 | `lotics app agent set <alias>` | Push the edited `src/agents/<alias>.md` instructions back through `set_app_agent` — the agent mirror of `app workflow set`, and the deploy-free authoring path for `apps.agents`. Reads the prose from disk (the `<!-- lotics: … -->` header stripped) and the typed fields (`inputs`/`outputs`/`tool_names`/`model_id`/`effort_level`/`knowledge_doc_ids`/`query_aliases`/`workflow_aliases`) from `package.json#lotics.agents.<alias>`, then sends them as ONE declaration. That assembly is the point: **`set_app_agent` REPLACES the declaration rather than patching it**, so a hand-built payload that sets one field silently drops the instructions, the output schema and the model pin — a silent, unrecoverable edit against a live prompt. Clear error + non-zero exit on a missing file, an alias absent from the manifest, or a file that is empty once the header is stripped (refusing to push an empty prompt). `app pull` writes the file; edit, then `set`. |
-| `lotics app query set <alias>` | Push `package.json#lotics.queries.<alias>` (`{ ast, params? }`) to `apps.queries` through `set_app_query` — the deploy-free inner loop for named queries, the mirror of `app workflow set`. The **server** validates it exactly as a deploy does (alias identifier, workspace-only tables, resolvable fields, declared params). Note: `apps.queries` is manifest-authoritative, so the next `lotics app deploy` re-syncs the whole map from the manifest — keep the declaration in the manifest to survive. Clear error + non-zero exit on an alias absent from the manifest or a validation failure. |
+| `lotics app query set <alias>` \| `--all` | Push `package.json#lotics.queries` (`{ ast, params? }` per alias) to `apps.queries` through `set_app_query` — **the only author of a query binding**, the mirror of `app workflow set`. A deploy ships code and binds nothing. The **server** validates each one exactly as it always did (alias identifier, workspace-only tables, resolvable fields, declared params). `--all` pushes every declared alias, alias-sorted, stopping at the first failure and naming what already landed. Clear error + non-zero exit on an alias absent from the manifest or a validation failure. |
 | `lotics app agent run <app_id> <alias> ['<json>'\|@file\|stdin]` | Run a bound app agent end-to-end (GAP-87). A run needs no deployed UI bundle — just the app row + the bound agent declaration + member auth — so the **`app_id` is explicit** (not read from a local manifest). Inputs ingest exactly like `lotics run` (inline JSON / `@file` / stdin; empty = `{}`). Opens the run's SSE (`appAgentRunStream`), streams `text-delta` prose to **stderr** as live progress, then reports from the **settled run RECORD** (`listAgentRuns`, polled to a terminal status — the client stream can close a beat before the run settles, or drop while it runs on server-side): default prints the run's structured `output` (JSON) or final text to **stdout** + a status line to stderr; `--json` prints the full run summary to stdout. Selects THIS run by the `x-app-agent-run-id` header (ordering-independent). Exits 0 **only** when the settled status is `completed`; otherwise non-zero with the run's error surfaced. A settled run that never appears fails loudly (never a silent success). A fresh `session_id` is minted per run (self-contained); `--session <id>` continues an existing thread (prior runs become the agent's context). |
 | `lotics app workflow pull` | Rewrite every `src/workflows/<alias>.ts` from the server (faithful body per bound alias via `get_app_workflow`) **+ its `.lotics/workflows/<alias>.globals.d.ts`** (via `getAppWorkflowDts`, so the body is locally typecheckable via `lotics app workflow check`) without a full `app pull` (no source archive, no npm install). A legacy alias with no rendered source warns and is skipped; a dts-fetch failure is non-fatal (body still written with the fallback wrapper, typecheck degraded). Also idempotently patches the main `tsconfig.json` `exclude` to cover `src/workflows` + `.lotics/workflows` so a pre-existing app's `npm run typecheck` never loads the bodies or the colliding per-alias globals. |
 | `lotics app workflow check [alias]` | Check the editable workflow bodies locally, no auth / no network, in the **server's own order** — parse, then type-check. **Parse** runs `parseWorkflowJs` from `@lotics/shared` (the SAME module `verifyWorkflow` calls, never a second implementation — that is what let the two diverge once) over the stripped body `set` would upload, with `toolNames: undefined` (the CLI ships no tool registry, so tool-name resolution stays a server check while every shape/scope rule runs here). A body the subset rejects reports **that error alone** and skips the compiler — it never reaches the server's compiler either, so tsc's opinion of it is noise. **Type-check** then builds an **isolated** `ts.Program` per alias from exactly that alias's `{body, globals}` pair — mirroring the server, which verifies one body at a time — so the per-alias ambient `trigger` never collides and `trigger.app_workflow.inputs` is checked against the right alias (GAP-59). All aliases run in ONE node process (N programs, not N `tsc` spawns), with the SAME compile options the server uses at set-time verify (lib `es2022` with no DOM, target ES2022, strict, NodeNext, `types:[]`, skipLibCheck) and the app's OWN `typescript` (resolved from its `node_modules`, never bundled into the CLI). What the compiler sees is the **checked source**, not the file: `rewriteAccumulatorAppends` from `@lotics/shared` — the SAME transform the server applies before its set-time compile — is applied in memory, so a pulled body's canonical `out = concat(out, [item])` accumulator checks green here exactly as it saves there (compiling the raw text went red on it), and the body on disk is never rewritten. Reports `<file>:<line>:<col> - <TS####\|subset>` at the **physical** line in `src/workflows/<alias>.ts`, so an editor jump lands on the offending code (these are deliberately NOT `set`'s body-relative numbers — `set` prints no file path, so there is no format to agree with); exits non-zero if any alias fails. Green is honest but not total: `set` additionally resolves names, lints and structurally validates against the live workspace — passes that need its tables and tool schemas, so they cannot run offline, and the success line says so. A bound alias with no body file yet warns + skips; a body with no globals errors (run a pull). |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/cli",
-  "version": "0.100.0",
+  "version": "0.101.0",
   "description": "Lotics SDK and CLI for AI agents",
   "type": "module",
   "bin": {
@@ -18,6 +18,7 @@
   "scripts": {
     "build": "tsgo -p tsconfig.build.json && node scripts/build_cli.mjs",
     "typecheck": "tsgo --noEmit",
+    "lint": "oxlint",
     "test": "vitest run",
     "prepublishOnly": "npm run build"
   },