@lotics/cli 0.123.0 → 0.128.0

package/dist/src/cli.js

@@ -45587,8 +45587,8 @@ import { randomUUID } from "node:crypto";
 import { tmpdir } from "node:os";
 
 // src/starter_template.ts
-var STARTER_FALLBACK_UI_VERSION = "27.11.0";
-var STARTER_FALLBACK_SDK_VERSION = "0.52.0";
+var STARTER_FALLBACK_UI_VERSION = "28.1.0";
+var STARTER_FALLBACK_SDK_VERSION = "0.73.0";
 var STARTER_REACT_NATIVE_VERSION = "0.85.3";
 var VITEST_SETUP_FILENAME = "vitest.setup.ts";
 var VITEST_SETUP_CONTENT = `import { vi } from "vitest";
@@ -45793,7 +45793,6 @@ export default defineConfig({
   //   const base = loticsResolve();
   //   resolve: { ...base, alias: [...base.alias, { find: "x", replacement: "y" }] }
   resolve: loticsResolve(),
-  },
   optimizeDeps: {
     // The dev dep-optimizer must pre-bundle @lotics/ui's RN-ecosystem + markdown
     // CJS-interop deps or \`lotics app dev\` blanks the iframe ("does not provide an
@@ -47501,6 +47500,9 @@ function calledAppAliases(sourceText) {
   }
   return out;
 }
+function orphanedAliases(bound, called) {
+  return unboundAliases(bound, called);
+}
 function unboundAliases(called, bound) {
   const missing = (from, against) => {
     const have = new Set(against ?? []);
@@ -64786,6 +64788,7 @@ var querySourceSchema = zod_default.lazy(
     zod_default.object({ expression: zod_default.string() })
   ])
 );
+var FILES_PROJECTION_MAX_LIMIT = 10;
 var queryProjectionColumnObjectSchema = zod_default.object({
   output: zod_default.string().optional().describe(
     "Output column name. Omit for a passthrough \u2014 it defaults to the source field key. Required only to rename, or for a computed source."
@@ -64801,6 +64804,9 @@ var queryProjectionColumnObjectSchema = zod_default.object({
     kind: zod_default.literal("source_field").describe("Currently the only writable target kind")
   }).optional().describe(
     "Marks this column as writable through to the originating source field. Valid only when `source` is a bare-string field reference and upstream addressing (source_table_id, source_field_key) is unambiguous. The compiler validates this and rejects otherwise."
+  ),
+  limit: zod_default.number().int().min(1).max(FILES_PROJECTION_MAX_LIMIT).optional().describe(
+    "FILES columns only: return at most this many entries per cell, in stored order. For a list that renders ONE thumbnail per row \u2014 without it the column yields the whole array and the response pays to resolve every entry it will never show."
   )
 });
 var queryProjectionColumnSchema = zod_default.union([
@@ -70433,56 +70439,53 @@ function sameSchema(a, b) {
   };
   return JSON.stringify(canonical(a)) === JSON.stringify(canonical(b));
 }
-function agentTypeDivergences(manifestAgents, liveAgents) {
-  const out = [];
-  for (const [alias, declared] of Object.entries(manifestAgents ?? {})) {
-    const live = (liveAgents ?? {})[alias];
-    if (!live) {
-      out.push(
-        `${alias} \u2014 typed locally but NOT bound on the app, so useAgentRun("${alias}") 400s at runtime`
-      );
-      continue;
-    }
-    for (const key of AGENT_TYPED_KEYS) {
-      if (!sameSchema(declared[key], live[key])) {
-        out.push(`${alias}.${key} \u2014 local types disagree with the live agent`);
-      }
-    }
-  }
-  return out;
-}
 function workflowTypeDivergences(manifestWorkflows, liveWorkflows) {
   const out = [];
   for (const [alias, declared] of Object.entries(manifestWorkflows ?? {})) {
     const live = (liveWorkflows ?? {})[alias];
     if (!live) {
-      out.push(`${alias} \u2014 declared locally but NOT bound on the app`);
+      out.push({ alias });
       continue;
     }
     for (const key of ["inputs", "outputs"]) {
-      if (!sameSchema(declared[key], live[key])) {
-        out.push(`${alias}.${key} \u2014 the manifest declares a schema the live binding does not have`);
-      }
+      if (!sameSchema(declared[key], live[key])) out.push({ alias, key });
     }
   }
   return out;
 }
+function syncedEntry(entry) {
+  if (entry === void 0) return void 0;
+  return typeof entry === "string" ? { content: entry } : entry;
+}
 function readSynced(projectDir) {
   try {
     const pkg2 = JSON.parse(
       fs6.readFileSync(path7.join(projectDir, "package.json"), "utf-8")
     );
-    return pkg2.lotics?.synced ?? {};
+    const raw = pkg2.lotics?.synced ?? {};
+    return {
+      workflows: normalizeSyncedMap(raw.workflows),
+      agents: normalizeSyncedMap(raw.agents),
+      queries: normalizeSyncedMap(raw.queries)
+    };
   } catch {
-    return {};
+    return { workflows: {}, agents: {}, queries: {} };
   }
 }
-function writeSynced(projectDir, kind, alias, sha) {
+function normalizeSyncedMap(map3) {
+  return Object.fromEntries(
+    Object.entries(map3 ?? {}).map(([alias, entry]) => [
+      alias,
+      syncedEntry(entry)
+    ])
+  );
+}
+function writeSynced(projectDir, kind, alias, entry) {
   const pkgPath2 = path7.join(projectDir, "package.json");
   const pkg2 = JSON.parse(fs6.readFileSync(pkgPath2, "utf-8"));
   if (!pkg2.lotics) return;
   pkg2.lotics.synced ??= {};
-  pkg2.lotics.synced[kind] = { ...pkg2.lotics.synced[kind], [alias]: sha };
+  pkg2.lotics.synced[kind] = { ...pkg2.lotics.synced[kind], [alias]: entry };
   fs6.writeFileSync(pkgPath2, JSON.stringify(pkg2, null, 2) + "\n");
 }
 var WORKFLOWS_DIR = path7.join("src", "workflows");
@@ -70544,11 +70547,14 @@ function writeWorkflowGlobals(projectDir, alias, dts) {
 `);
   return file2;
 }
+function normalizeWorkflowBody(source) {
+  return source.replace(/\s+$/, "");
+}
 function writeWorkflowFile(projectDir, alias, source, envelope = { prefix: WORKFLOW_ENVELOPE_PREFIX, suffix: WORKFLOW_ENVELOPE_SUFFIX }) {
   const dir = path7.join(projectDir, WORKFLOWS_DIR);
   fs6.mkdirSync(dir, { recursive: true });
   const file2 = workflowFilePath(projectDir, alias);
-  const body = source.replace(/\s+$/, "");
+  const body = normalizeWorkflowBody(source);
   fs6.writeFileSync(file2, `${workflowFileHeader(alias)}
 ${envelope.prefix}${body}${envelope.suffix}
 `);
@@ -70570,7 +70576,7 @@ function writeAgentFile(projectDir, alias, instructions) {
   );
   return file2;
 }
-function writeAgentFiles(projectDir, agents) {
+function writeAgentFiles(projectDir, agents, opts) {
   const written = [];
   for (const [alias, declaration] of Object.entries(agents)) {
     const instructions = declaration.instructions;
@@ -70578,15 +70584,33 @@ function writeAgentFiles(projectDir, agents) {
       console.error(`\u26A0 Skipped src/agents/${alias}.md \u2014 the live declaration carries no instructions.`);
       continue;
     }
+    if (!opts.overwrite && localPromptUnpushed(projectDir, alias)) {
+      opts.kept.push(`src/agents/${alias}.md`);
+      continue;
+    }
     writeAgentFile(projectDir, alias, instructions);
     written.push(alias);
   }
   return written;
 }
+function localPromptUnpushed(projectDir, alias) {
+  const file2 = agentFilePath2(projectDir, alias);
+  if (!fs6.existsSync(file2)) return false;
+  const baseline = readSynced(projectDir).agents[alias]?.content;
+  if (baseline === void 0) return true;
+  return contentSha(stripAgentHeader(fs6.readFileSync(file2, "utf-8"))) !== baseline;
+}
 function generatedWorkflowDescription(appName, alias) {
   return `Workflow invoked by app "${appName}" via useWorkflow("${alias}").`;
 }
-async function writeWorkflowFiles(client, projectDir, app_id, appName, workflows) {
+function localBodyUnpushed(projectDir, alias) {
+  const file2 = workflowFilePath(projectDir, alias);
+  if (!fs6.existsSync(file2)) return false;
+  const baseline = readSynced(projectDir).workflows[alias]?.content;
+  if (baseline === void 0) return true;
+  return contentSha(stripWorkflowHeader(fs6.readFileSync(file2, "utf-8"))) !== baseline;
+}
+async function writeWorkflowFiles(client, projectDir, app_id, appName, workflows, opts) {
   const written = [];
   for (const [alias, declaration] of Object.entries(workflows)) {
     const res = await client.getAppWorkflow(app_id, alias);
@@ -70595,7 +70619,9 @@ async function writeWorkflowFiles(client, projectDir, app_id, appName, workflows
         `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;
+    const result = res.result === null || typeof res.result !== "object" ? null : res.result;
+    const source = result?.source;
+    const body_sha = typeof result?.body_sha === "string" ? result.body_sha : void 0;
     if (typeof source !== "string" || source.trim() === "") {
       console.error(
         `\u26A0 Skipped src/workflows/${alias}.ts \u2014 legacy workflow with no rendered body.`
@@ -70609,8 +70635,15 @@ async function writeWorkflowFiles(client, projectDir, app_id, appName, workflows
       alias,
       toWorkflowDtsDeclaration(declaration)
     );
+    if (!opts.overwrite && localBodyUnpushed(projectDir, alias)) {
+      opts.kept.push(`src/workflows/${alias}.ts`);
+      continue;
+    }
     writeWorkflowFile(projectDir, alias, source, envelope);
-    writeSynced(projectDir, "workflows", alias, contentSha(source));
+    writeSynced(projectDir, "workflows", alias, {
+      content: contentSha(normalizeWorkflowBody(source)),
+      ...body_sha ? { live: body_sha } : {}
+    });
     const rowDescription = res.result.description;
     if (typeof rowDescription === "string" && rowDescription !== "" && // Skip the server's GENERATED default. It is what an undescribed alias
     // carries, so writing it back would commit a line of noise per workflow
@@ -70725,9 +70758,12 @@ function writeAppMeta(projectDir, meta3) {
   const pkgPath2 = path7.join(projectDir, "package.json");
   const pkg2 = JSON.parse(fs6.readFileSync(pkgPath2, "utf-8"));
   const existing = pkg2.lotics && typeof pkg2.lotics === "object" ? pkg2.lotics : {};
+  const supplied = new Set(
+    Object.entries(meta3).filter(([, value2]) => value2 !== void 0).map(([key]) => key)
+  );
   const preserved = {};
   for (const [key, value2] of Object.entries(existing)) {
-    if (!APP_META_KEYS.includes(key)) preserved[key] = value2;
+    if (!supplied.has(key)) preserved[key] = value2;
   }
   pkg2.lotics = { ...meta3, ...preserved };
   fs6.writeFileSync(pkgPath2, JSON.stringify(pkg2, null, 2) + "\n");
@@ -70747,7 +70783,7 @@ function writeWorkflowOutputs(projectDir, alias, outputs) {
 function workflowBodyDrift(projectDir, workflows, synced = {}) {
   const drifted = [];
   for (const alias of Object.keys(workflows ?? {})) {
-    const baseline = synced[alias];
+    const baseline = syncedEntry(synced[alias])?.content;
     if (baseline === void 0) continue;
     const file2 = workflowFilePath(projectDir, alias);
     if (!fs6.existsSync(file2)) continue;
@@ -70757,17 +70793,6 @@ function workflowBodyDrift(projectDir, workflows, synced = {}) {
   }
   return drifted;
 }
-function reportWorkflowBodyDrift(projectDir, workflows, synced = {}) {
-  const drifted = workflowBodyDrift(projectDir, workflows, synced);
-  if (drifted.length === 0) return false;
-  console.error(
-    `
-\u2717 ${drifted.length === 1 ? "This workflow body differs" : "These workflow bodies differ"} from what is live: ${drifted.join(", ")}
-  A deploy does not push bodies, so this version would not reproduce what runs.
-  Send each with 'lotics app workflow set <alias>' \u2014 or revert the file to drop the edit.`
-  );
-  return true;
-}
 function ensureAppTsconfig(projectDir) {
   const tsconfigPath = path7.join(projectDir, "tsconfig.json");
   if (!fs6.existsSync(tsconfigPath)) {
@@ -70882,6 +70907,7 @@ function writeAppDts(projectDir, manifest) {
   writeDevLinkTsconfig(projectDir);
   writeKitTypeAugmentation(projectDir);
   ensureAppTsconfig(projectDir);
+  ensureAppVitestSetup(projectDir);
   return written.map(([file2]) => file2);
 }
 function readCodegenTablesAllowlist(projectDir) {
@@ -70909,7 +70935,6 @@ function writeBindingAppFields(projectDir, binding) {
   fs6.mkdirSync(dotLotics, { recursive: true });
   const file2 = path7.join(dotLotics, "app_fields.ts");
   fs6.writeFileSync(file2, generatePackageAppFields(binding));
-  ensureAppVitestSetup(projectDir);
   return file2;
 }
 async function writeGeneratedAppFields(client, projectDir, app, queries) {
@@ -70930,6 +70955,15 @@ async function writeGeneratedAppFields(client, projectDir, app, queries) {
     } else {
       const tableIds = resolveCodegenTableIds(projectDir, queries);
       const tables = await client.getWorkspaceSchema(tableIds);
+      const missing = tableIds.filter((id) => !tables.some((t) => t.id === id));
+      if (missing.length > 0) {
+        console.error(
+          `\u26A0 Skipped .lotics/app_fields.ts \u2014 ${missing.length} table(s) the app queries could not be read: ${missing.join(", ")}.
+  Writing anyway would bake a narrowed F/OPT map that compiles and then throws at runtime. Check this key's access to those tables.
+  An existing app_fields.ts is kept and still works; a project that has none yet will fail to BUILD until this resolves \u2014 which is the loud failure, not a new problem.`
+        );
+        return;
+      }
       const fieldsPath = writeAppFields(projectDir, tables);
       console.error(
         `Wrote ${fieldsPath} (baked form \u2014 bespoke; ${tables.length} table${tables.length === 1 ? "" : "s"})`
@@ -71216,11 +71250,15 @@ async function appPull(client, args) {
   const tmpFile = path7.join(tmpdir(), `lotics-app-${app.id}-${Date.now()}.tar.gz`);
   console.error(`Downloading source archive...`);
   await downloadToFile(sourceUrl, tmpFile);
+  const keptLocal = [];
+  const stagingDir = fs6.mkdtempSync(path7.join(tmpdir(), `lotics-pull-${app.id}-`));
   try {
+    await runTar(["-xzf", tmpFile, "-C", stagingDir], stagingDir);
     console.error(`Extracting to ${targetPath}...`);
-    await runTar(["-xzf", tmpFile, "-C", targetPath], targetPath);
+    keptLocal.push(...copyTree(stagingDir, targetPath, { overwrite: args.force === true }));
   } finally {
     if (fs6.existsSync(tmpFile)) fs6.unlinkSync(tmpFile);
+    fs6.rmSync(stagingDir, { recursive: true, force: true });
   }
   stampPulledManifest(targetPath, {
     app_id: app.id,
@@ -71232,7 +71270,8 @@ async function appPull(client, args) {
     agents: app.agents ?? {}
   });
   for (const [alias, declaration] of Object.entries(app.queries ?? {})) {
-    writeSynced(targetPath, "queries", alias, declarationSha(declaration));
+    const sha = declarationSha(declaration);
+    writeSynced(targetPath, "queries", alias, { content: sha, live: sha });
   }
   await writeGeneratedAppFields(
     client,
@@ -71242,7 +71281,10 @@ async function appPull(client, args) {
   );
   const workflows = app.workflows ?? {};
   if (Object.keys(workflows).length > 0) {
-    const written = await writeWorkflowFiles(client, targetPath, app.id, app.name, workflows);
+    const written = await writeWorkflowFiles(client, targetPath, app.id, app.name, workflows, {
+      overwrite: args.force === true,
+      kept: keptLocal
+    });
     if (written.length > 0) {
       console.error(
         `Wrote ${written.length} workflow ${written.length === 1 ? "body" : "bodies"} to ${WORKFLOWS_DIR}/ (${written.join(", ")})`
@@ -71251,10 +71293,15 @@ async function appPull(client, args) {
   }
   const agents = app.agents ?? {};
   if (Object.keys(agents).length > 0) {
-    const written = writeAgentFiles(targetPath, agents);
+    const written = writeAgentFiles(targetPath, agents, {
+      overwrite: args.force === true,
+      kept: keptLocal
+    });
     for (const alias of written) {
       const instructions = agents[alias]?.instructions;
-      if (instructions !== void 0) writeSynced(targetPath, "agents", alias, contentSha(instructions));
+      if (instructions === void 0) continue;
+      const sha = contentSha(instructions);
+      writeSynced(targetPath, "agents", alias, { content: sha, live: sha });
     }
     if (written.length > 0) {
       console.error(
@@ -71264,6 +71311,7 @@ async function appPull(client, args) {
   }
   console.error(`Installing npm dependencies...`);
   await runNpm(["install"], targetPath);
+  reportKeptLocalFiles(keptLocal, app.id);
   console.error(`
 Ready. Next steps:`);
   console.error(`  cd ${path7.relative(process.cwd(), targetPath) || "."}`);
@@ -71289,35 +71337,33 @@ async function appDeploy(client, args) {
   const meta3 = readAppMeta(projectDir);
   warnAboutDevLink(projectDir, "deploy");
   const liveApp = await client.getApp(meta3.app_id);
-  const divergences = agentTypeDivergences(meta3.agents, liveApp.agents);
-  if (divergences.length > 0) {
-    console.error(
-      `
-Refusing to deploy \u2014 package.json#lotics.agents disagrees with the live app:
-` + divergences.map((d) => `  \u2022 ${d}`).join("\n") + `
-
-  lotics.agents is a REFLECTION of the app, not an authoring surface, but it is what
-  types useAgentRun \u2014 so this build was checked against an agent that does not exist.
-  To take the app's shape:      lotics app codegen   (refreshes the block + the types)
-  To CHANGE the agent instead:  lotics run set_app_agent '{"app_id":"${meta3.app_id}","alias":"\u2026","outputs":{\u2026}}'
-                                (send only what changes \u2014 the server merges), then codegen.`
-    );
-    process.exit(1);
+  const pending = pendingBindings({
+    projectDir,
+    meta: meta3,
+    synced: readSynced(projectDir).workflows,
+    live: liveApp
+  });
+  if (!nothingPending(pending)) {
+    await pushPendingBindings(client, projectDir, pending);
   }
-  const declarationDrift = reportWorkflowDeclarationDrift(meta3.workflows, liveApp.workflows);
   const sourceText = readAppSourceText(projectDir);
   const called = calledAppAliases(sourceText);
-  const proseDrift = reportAgentProseDrift(projectDir, liveApp.agents);
-  const bodyDrift = reportWorkflowBodyDrift(projectDir, meta3.workflows, readSynced(projectDir).workflows);
-  const queryDrift = reportQueryDrift(liveApp, meta3.queries ?? {});
-  if (bodyDrift || declarationDrift || proseDrift || queryDrift) {
-    console.error(`
-  Nothing was deployed.`);
-    process.exit(1);
-  }
   warnIfDynamicAliases(called);
   warnIfUndeclaredCapabilities(sourceText, meta3.capabilities);
   writeAppDts(projectDir, { workflows: meta3.workflows, queries: meta3.queries, agents: meta3.agents });
+  try {
+    await writeGeneratedAppFields(
+      client,
+      projectDir,
+      { app_id: meta3.app_id, package_id: liveApp.package_id },
+      meta3.queries ?? {}
+    );
+  } catch (err2) {
+    console.error(
+      `\u26A0 Could not regenerate .lotics/app_fields.ts (${err2.message}).
+  The build will use whatever is on disk \u2014 run 'lotics app codegen' if this app is published.`
+    );
+  }
   console.error("Building...");
   await runNpm(["run", "build"], projectDir);
   const distDir = path7.join(projectDir, "dist");
@@ -71354,7 +71400,7 @@ Refusing to deploy \u2014 package.json#lotics.agents disagrees with the live app
         source_archive: fs6.readFileSync(tmpSource),
         dist_archive: fs6.readFileSync(tmpDist),
         prev_version_id: meta3.current_version_id,
-        message: args.message,
+        message: args.message ?? derivedDeployMessage(pending),
         // 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
@@ -71379,13 +71425,24 @@ Refusing to deploy \u2014 package.json#lotics.agents disagrees with the live app
       });
       console.error(`Deployed v${result.version_number} (${result.version_id})`);
       console.error(`Bundle size: ${(result.bundle_size_bytes / 1024).toFixed(1)} KB`);
+      let liveAfter;
       try {
-        const app = await client.getApp(meta3.app_id);
-        warnIfUnbranded(app);
-        warnIfUnboundAliases(app, called);
+        liveAfter = await client.getApp(meta3.app_id);
       } catch (err2) {
         console.error(`(skipped post-deploy checks: ${err2.message})`);
       }
+      if (liveAfter) {
+        warnIfUnbranded(liveAfter);
+        warnIfUnboundAliases(liveAfter, called);
+      }
+      if (liveAfter) {
+        await pruneOrphanedBindings(
+          client,
+          meta3.app_id,
+          orphanedBindings(called, liveAfter),
+          called.dynamic
+        );
+      }
     } catch (err2) {
       const e = err2;
       if (e.code === "VERSION_CONFLICT") {
@@ -71425,78 +71482,233 @@ async function readLiveQueries(client, appId) {
     process.exit(1);
   }
 }
-function reportQueryDrift(app, manifest) {
-  const drifted = driftedQueryAliases(manifest, app.queries);
-  if (drifted.length === 0) return false;
-  console.error(
-    `
-\u2717 ${drifted.length} quer${drifted.length === 1 ? "y" : "ies"} in package.json differ from the app: ${drifted.join(", ")}
-  A deploy does not write them, so this version would not reproduce what runs.
-  Push yours with 'lotics app query set --all' (or one alias at a time),
-  or adopt the app's with 'lotics app pull'.`
-  );
-  return drifted.length > 0;
-}
 async function appCheck(client, args = {}) {
   const projectDir = path7.resolve(args.projectDir ?? process.cwd());
   const meta3 = readAppMeta(projectDir);
   const app = await client.getApp(meta3.app_id);
   const sourceText = readAppSourceText(projectDir);
   const called = calledAppAliases(sourceText);
-  const divergences = agentTypeDivergences(meta3.agents, app.agents);
-  for (const d of divergences) {
-    console.error(`\u2717 package.json#lotics.agents.${d}`);
-  }
-  if (divergences.length > 0) {
-    console.error(
-      `  A deploy REFUSES this: the bundle would be typed against an agent that does not exist.
-  Take the app's shape with 'lotics app pull ${meta3.app_id}', or change the agent with set_app_agent.`
-    );
-  }
   warnAboutDevLink(projectDir, "deploy");
-  const proseDrift = reportAgentProseDrift(projectDir, app.agents);
-  const bodyDrift = reportWorkflowBodyDrift(projectDir, meta3.workflows, readSynced(projectDir).workflows);
-  const declarationDrift = reportWorkflowDeclarationDrift(meta3.workflows, app.workflows);
-  const queryDrift = reportQueryDrift(app, meta3.queries ?? {});
+  warnAboutOrphanedBindings(called, app);
+  const pending = pendingBindings({
+    projectDir,
+    meta: meta3,
+    synced: readSynced(projectDir).workflows,
+    live: app
+  });
+  reportPending(pending);
   warnIfDynamicAliases(called);
   warnIfUndeclaredCapabilities(sourceText, meta3.capabilities);
   warnIfUnboundAliases(app, called);
   warnIfUnbranded(app);
-  if (divergences.length > 0 || bodyDrift || declarationDrift || proseDrift || queryDrift) {
+  if (!nothingPending(pending)) {
     process.exit(1);
   }
   console.error("Checked the app's bindings, capabilities and agent schemas \u2014 nothing blocking.");
 }
-function reportAgentProseDrift(projectDir, liveAgents) {
-  let drifted = false;
+async function pushPendingBindings(client, projectDir, pending) {
+  const plan = [
+    ...pending.queries.map((alias) => `query ${alias}`),
+    ...pending.workflows.map((alias) => `workflow ${alias}`),
+    ...pending.agents.map((alias) => `agent ${alias}`)
+  ];
+  console.error(
+    `
+Pushing ${plan.length} binding${plan.length === 1 ? "" : "s"} ahead of the app: ${plan.join(", ")}`
+  );
+  for (const alias of pending.queries) {
+    await appQuerySet(client, { alias, projectDir });
+  }
+  for (const alias of pending.workflows) {
+    await appWorkflowSet(client, { alias, projectDir });
+  }
+  for (const alias of pending.agents) {
+    await appAgentSet(client, { alias, projectDir });
+  }
+}
+function pendingBindings(args) {
+  const { projectDir, meta: meta3, synced, live } = args;
+  const workflows = /* @__PURE__ */ new Set([
+    ...workflowBodyDrift(projectDir, meta3.workflows, synced),
+    ...divergedWorkflowAliases(meta3.workflows, live.workflows)
+  ]);
+  return {
+    workflows: [...workflows].sort(),
+    agents: [
+      .../* @__PURE__ */ new Set([
+        ...driftedAgentAliases(projectDir, live.agents),
+        // A manifest declaration that disagrees with the live row is a push now,
+        // the same as a workflow's. `agentTypeDivergences` renders one line per
+        // (alias, key) for a human, and the alias is its first token — but an
+        // alias that diverged on both `inputs` and `outputs` still needs exactly
+        // one push.
+        ...divergedAgentAliases(meta3.agents, live.agents)
+      ])
+    ].sort(),
+    // Only aliases the manifest DECLARES. `driftedQueryAliases` is symmetric —
+    // it unions both key sets — so an alias deleted locally but still bound live
+    // reads as drift, and queueing it sends the author to a push that refuses
+    // ("declare it first") for a declaration they deliberately removed. A
+    // deletion is not a push, and this detector only decides what to push;
+    // unbinding is `remove_app_query`, which no deploy runs for any artifact.
+    queries: [...driftedQueryAliases(meta3.queries ?? {}, live.queries)].filter((alias) => (meta3.queries ?? {})[alias] !== void 0).sort()
+  };
+}
+function reportPending(pending) {
+  const lines = [
+    ...pending.workflows.map((a) => `  \u2022 workflow "${a}" \u2014 lotics app workflow set ${a}`),
+    ...pending.agents.map((a) => `  \u2022 agent "${a}" \u2014 lotics app agent set ${a}`),
+    ...pending.queries.map((a) => `  \u2022 query "${a}" \u2014 lotics app query set ${a}`)
+  ];
+  if (lines.length === 0) return;
+  console.error(
+    `
+\u2717 ${lines.length} binding${lines.length === 1 ? " is" : "s are"} ahead of the app:
+` + lines.join("\n") + `
+
+  A version shipped now would not reproduce what runs. 'lotics app deploy' pushes
+  these for you; revert the file instead to drop the edit.`
+  );
+}
+function nothingPending(pending) {
+  return pending.workflows.length === 0 && pending.agents.length === 0 && pending.queries.length === 0;
+}
+function divergedAgentAliases(manifestAgents, liveAgents) {
+  const out = [];
+  for (const [alias, declared] of Object.entries(manifestAgents ?? {})) {
+    const live = (liveAgents ?? {})[alias];
+    if (!live) continue;
+    if (AGENT_TYPED_KEYS.some((key) => !sameSchema(declared[key], live[key]))) out.push(alias);
+  }
+  return out;
+}
+function driftedAgentAliases(projectDir, liveAgents) {
+  const drifted = [];
   for (const [alias, live] of Object.entries(liveAgents ?? {})) {
     const file2 = agentFilePath2(projectDir, alias);
     if (!fs6.existsSync(file2)) continue;
     const local = stripAgentHeader(fs6.readFileSync(file2, "utf-8"));
     if (local === "" || local === (live.instructions ?? "")) continue;
-    drifted = true;
+    drifted.push(alias);
+  }
+  return drifted.sort();
+}
+function divergedWorkflowAliases(manifestWorkflows, liveWorkflows) {
+  return [
+    ...new Set(workflowTypeDivergences(manifestWorkflows, liveWorkflows).map((d) => d.alias))
+  ].sort();
+}
+function orphanedBindings(called, live) {
+  const agentDeclarations = Object.values(live.agents ?? {});
+  const referenced = {
+    queries: [...called.queries, ...agentDeclarations.flatMap((a) => a.query_aliases ?? [])],
+    workflows: [...called.workflows, ...agentDeclarations.flatMap((a) => a.workflow_aliases ?? [])],
+    // Nothing declares an agent but the client bundle — an agent cannot run another.
+    agents: called.agents
+  };
+  return orphanedAliases(
+    {
+      queries: Object.keys(live.queries ?? {}),
+      workflows: Object.keys(live.workflows ?? {}),
+      agents: Object.keys(live.agents ?? {})
+    },
+    referenced
+  );
+}
+function warnAboutOrphanedBindings(called, live) {
+  const orphans = orphanedBindings(called, live);
+  const lines = [
+    ...orphans.queries.map((a) => `  \u2022 query ${a}`),
+    ...orphans.workflows.map((a) => `  \u2022 workflow ${a}`),
+    ...orphans.agents.map((a) => `  \u2022 agent ${a}`)
+  ];
+  if (lines.length === 0) return 0;
+  console.error(
+    `
+\u26A0 ${lines.length} binding(s) are live but named nowhere in this bundle:
+` + lines.join("\n") + (called.dynamic.length > 0 ? `
+
+  This app computes an alias at runtime, so one of these may be called after
+  all \u2014 a deploy therefore leaves them ALL in place. Make those call sites
+  literal and a deploy will clean them up.` : `
+
+  A deploy unbinds these after it ships.`)
+  );
+  return lines.length;
+}
+async function pruneOrphanedBindings(client, appId, orphans, dynamic) {
+  const targets = [
+    ...orphans.queries.map((alias) => ({ tool: "remove_app_query", alias, label: `query ${alias}` })),
+    ...orphans.workflows.map((alias) => ({
+      tool: "remove_app_workflow",
+      alias,
+      label: `workflow ${alias}`
+    })),
+    ...orphans.agents.map((alias) => ({ tool: "remove_app_agent", alias, label: `agent ${alias}` }))
+  ];
+  if (targets.length === 0) return 0;
+  if (dynamic.length > 0) {
     console.error(
       `
-\u2717 ${path7.relative(projectDir, file2)} differs from the live agent's instructions.
-  A deploy does not push prose, so this version would not reproduce what runs.
-  Send it with 'lotics app agent set ${alias}' \u2014 or revert the file to drop the edit.`
+\u26A0 Left ${targets.length} unused binding(s) in place: this app calls ${dynamic.join(" / ")} with an alias it computes at runtime, and a static scan cannot tell which binding that reaches \u2014 so any of these may be live:
+` + 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 drifted;
+  let failed = 0;
+  for (const target of targets) {
+    const res = await client.execute(target.tool, { app_id: appId, 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}`);
+  }
+  return failed;
+}
+function derivedDeployMessage(pending) {
+  const parts = [
+    ...pending.queries.map((a) => `query ${a}`),
+    ...pending.workflows.map((a) => `workflow ${a}`),
+    ...pending.agents.map((a) => `agent ${a}`)
+  ];
+  return parts.length === 0 ? "Deployed app code" : `Deployed app code; pushed ${parts.join(", ")}`;
+}
+function copyTree(from, to, opts, relative = "") {
+  const kept = [];
+  for (const entry of fs6.readdirSync(from, { withFileTypes: true })) {
+    const src = path7.join(from, entry.name);
+    const dest = path7.join(to, entry.name);
+    const rel = path7.join(relative, entry.name);
+    if (entry.isDirectory()) {
+      fs6.mkdirSync(dest, { recursive: true });
+      kept.push(...copyTree(src, dest, opts, rel));
+      continue;
+    }
+    if (!opts.overwrite && fs6.existsSync(dest)) {
+      if (fs6.readFileSync(src).equals(fs6.readFileSync(dest))) continue;
+      kept.push(rel);
+      continue;
+    }
+    fs6.copyFileSync(src, dest);
+  }
+  return kept;
 }
-function reportWorkflowDeclarationDrift(manifestWorkflows, liveWorkflows) {
-  const divergences = workflowTypeDivergences(manifestWorkflows, liveWorkflows);
-  if (divergences.length === 0) return false;
+function reportKeptLocalFiles(kept, appId) {
+  if (kept.length === 0) return;
   console.error(
     `
-\u2717 package.json#lotics.workflows disagrees with the live app:
-` + divergences.map((d) => `  \u2022 ${d}`).join("\n") + `
-
-  This build's types came from the manifest, so the mismatch is invisible to tsc \u2014
-  the bundle would ship typed against a schema the live binding rejects.
-  Push the declarations:  lotics app workflow set <alias>   (a deploy never binds one)`
+${kept.length} local file(s) differ from the app and were KEPT, not overwritten:
+` + kept.slice(0, 20).map((f) => `  \u2022 ${f}`).join("\n") + (kept.length > 20 ? `
+  \u2026 and ${kept.length - 20} more` : ``) + `
+
+  Everything else was refreshed from the app. Your edits are intact.
+  Ship them:            lotics app deploy      (pushes bodies, prompts and declarations)
+  See the difference:   lotics app check
+  Take the app's copy:  lotics app pull ${appId} --force   (DISCARDS the files above)`
   );
-  return true;
 }
 function warnIfDynamicAliases(called) {
   if (called.dynamic.length === 0) return;
@@ -71760,7 +71972,7 @@ Agent "${args.alias}" run ${run.id} \u2192 ${run.status}${run.error_message ? `:
   if (run.status !== "completed") process.exit(1);
 }
 async function appAgentSet(client, args) {
-  const projectDir = process.cwd();
+  const projectDir = args.projectDir ?? process.cwd();
   const meta3 = readAppMeta(projectDir);
   noteScope({ alias: args.alias });
   const app = await client.getApp(meta3.app_id);
@@ -71771,37 +71983,51 @@ async function appAgentSet(client, args) {
     );
     process.exit(1);
   }
+  const declared = meta3.agents?.[args.alias];
+  const hasDeclaration = declared?.inputs !== void 0 || declared?.outputs !== void 0;
   const file2 = agentFilePath2(projectDir, args.alias);
-  if (!fs6.existsSync(file2)) {
+  if (!fs6.existsSync(file2) && !hasDeclaration) {
     console.error(
-      `No instructions at ${path7.relative(projectDir, file2)}. Run 'lotics app pull ${meta3.app_id}' to write ${AGENTS_DIR}/${args.alias}.md, then edit it.`
+      `No instructions at ${path7.relative(projectDir, file2)}, and nothing declared in package.json#lotics.agents.${args.alias} to push instead.
+  Run 'lotics app pull ${meta3.app_id}' to write ${AGENTS_DIR}/${args.alias}.md, then edit it.`
     );
     process.exit(1);
   }
-  const instructions = stripAgentHeader(fs6.readFileSync(file2, "utf-8"));
+  const instructions = fs6.existsSync(file2) ? stripAgentHeader(fs6.readFileSync(file2, "utf-8")) : void 0;
   if (instructions === "") {
     console.error(
       `${path7.relative(projectDir, file2)} is empty after stripping the header \u2014 refusing to push an empty prompt.`
     );
     process.exit(1);
   }
+  const proseBaseline = readSynced(projectDir).agents[args.alias]?.live;
   const res = await client.setAppAgent(meta3.app_id, args.alias, {
-    instructions,
-    // Conditional on the prose this edit was built from, so a push from a stale
-    // checkout is refused instead of overwriting an edit made elsewhere.
-    ...readSynced(projectDir).agents?.[args.alias] ? { expected_instructions_sha: readSynced(projectDir).agents?.[args.alias] } : {}
+    // Prose and its precondition ride together. Gating a declaration-only push on
+    // the prose baseline would refuse it because someone edited a PROMPT — a
+    // precondition must guard what this call actually writes.
+    ...instructions !== void 0 ? { instructions, ...proseBaseline ? { expected_instructions_sha: proseBaseline } : {} } : {},
+    ...declared?.inputs !== void 0 ? { inputs: declared.inputs } : {},
+    ...declared?.outputs !== void 0 ? { outputs: declared.outputs } : {}
   });
   if (res.error) {
     console.error(`Failed to set agent "${args.alias}": ${res.error}`);
     process.exit(1);
   }
-  writeSynced(projectDir, "agents", args.alias, contentSha(instructions));
+  if (instructions !== void 0) {
+    const proseSha = contentSha(instructions);
+    writeSynced(projectDir, "agents", args.alias, { content: proseSha, live: proseSha });
+  }
+  const pushed = [
+    ...instructions !== void 0 ? [`${instructions.length} chars of instructions`] : [],
+    ...declared?.inputs !== void 0 ? ["inputs"] : [],
+    ...declared?.outputs !== void 0 ? ["outputs"] : []
+  ];
   console.error(
-    `Set agent "${args.alias}" (${instructions.length} chars of instructions` + (live.model_tier ? `, ${live.model_tier}` : "") + `). Typed fields left as they are.`
+    `Set agent "${args.alias}" (${pushed.join(", ")}` + (live.model_tier ? `, ${live.model_tier}` : "") + `). Everything else left as it is.`
   );
 }
 async function appWorkflowSet(client, args) {
-  const projectDir = process.cwd();
+  const projectDir = args.projectDir ?? process.cwd();
   const meta3 = readAppMeta(projectDir);
   const declaration = meta3.workflows?.[args.alias];
   if (!declaration) {
@@ -71813,7 +72039,9 @@ async function appWorkflowSet(client, args) {
   const file2 = workflowFilePath(projectDir, args.alias);
   if (!fs6.existsSync(file2)) {
     console.error(
-      `No workflow body at ${path7.relative(projectDir, file2)}. Run 'lotics app pull ${meta3.app_id}' to write src/workflows/${args.alias}.ts, then edit it.`
+      `No workflow body at ${path7.relative(projectDir, file2)}.
+  If "${args.alias}" is already bound:  lotics app pull ${meta3.app_id}   (writes the body)
+  If it is a NEW alias you declared:    create that file yourself, then re-run this.`
     );
     process.exit(1);
   }
@@ -71838,13 +72066,17 @@ async function appWorkflowSet(client, args) {
     // The body this edit was built on. Turns the push into a conditional write:
     // if the live body moved since this project last saw it, the server refuses
     // rather than letting this copy overwrite a change nobody here has seen.
-    expected_body_sha: readSynced(projectDir).workflows?.[args.alias]
+    expected_body_sha: readSynced(projectDir).workflows[args.alias]?.live
   });
   if (res.error) {
     console.error(`Failed to set workflow "${args.alias}": ${res.error}`);
     process.exit(1);
   }
-  writeSynced(projectDir, "workflows", args.alias, contentSha(source));
+  const pushedBodySha = res.result !== null && typeof res.result === "object" ? res.result.body_sha : void 0;
+  writeSynced(projectDir, "workflows", args.alias, {
+    content: contentSha(source),
+    ...typeof pushedBodySha === "string" ? { live: pushedBodySha } : {}
+  });
   const result = res.result ?? {};
   const workflowId = typeof result.workflow_id === "string" ? result.workflow_id : "(unknown)";
   console.error(`Set workflow "${args.alias}" \u2192 ${workflowId}`);
@@ -71864,7 +72096,7 @@ async function appWorkflowSet(client, args) {
   }
 }
 async function appQuerySet(client, args) {
-  const projectDir = process.cwd();
+  const projectDir = args.projectDir ?? process.cwd();
   const meta3 = readAppMeta(projectDir);
   const declared = meta3.queries ?? {};
   const aliases = "all" in args ? Object.keys(declared).sort() : [args.alias];
@@ -71886,21 +72118,22 @@ async function appQuerySet(client, args) {
       meta3.app_id,
       alias,
       declaration,
-      readSynced(projectDir).queries?.[alias]
+      readSynced(projectDir).queries[alias]?.live
     );
     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);
     }
-    writeSynced(projectDir, "queries", alias, declarationSha(declaration));
+    const querySha = declarationSha(declaration);
+    writeSynced(projectDir, "queries", alias, { content: querySha, live: querySha });
     pushed.push(alias);
   }
   console.error(
     `Set ${pushed.length} quer${pushed.length === 1 ? "y" : "ies"} on ${meta3.app_id}: ${pushed.join(", ")}.`
   );
 }
-async function appWorkflowPull(client) {
+async function appWorkflowPull(client, args = {}) {
   const projectDir = process.cwd();
   const meta3 = readAppMeta(projectDir);
   const app = await client.getApp(meta3.app_id);
@@ -71909,10 +72142,15 @@ async function appWorkflowPull(client) {
     console.error(`App ${meta3.app_id} has no bound workflows.`);
     return;
   }
-  const written = await writeWorkflowFiles(client, projectDir, meta3.app_id, app.name, workflows);
+  const kept = [];
+  const written = await writeWorkflowFiles(client, projectDir, meta3.app_id, app.name, workflows, {
+    overwrite: args.force === true,
+    kept
+  });
   console.error(
     `Wrote ${written.length} workflow ${written.length === 1 ? "body" : "bodies"} to ${WORKFLOWS_DIR}/` + (written.length > 0 ? ` (${written.join(", ")})` : "")
   );
+  reportKeptLocalFiles(kept, meta3.app_id);
   ensureAppTsconfig(projectDir);
 }
 async function appWorkflowCheck(args) {
@@ -71995,6 +72233,7 @@ ${totalErrors} error${totalErrors === 1 ? "" : "s"} across ${results.length - pa
 function parseArgs(argv) {
   const flags = {
     json: false,
+    force: false,
     timeout: void 0,
     output: void 0,
     as: void 0,
@@ -72027,6 +72266,9 @@ function parseArgs(argv) {
       case "--json":
         flags.json = true;
         break;
+      case "--force":
+        flags.force = true;
+        break;
       case "--timeout":
         flags.timeout = parseInt(argv[++i2], 10);
         break;
@@ -100725,17 +100967,11 @@ Available workspaces:`);
         process.exit(1);
       }
       const targetPath = restArgs[0];
-      await appPull(client, { app_id: appId, targetPath });
+      await appPull(client, { app_id: appId, targetPath, force: flags.force === true });
       return;
     }
     if (subcommand === "deploy") {
-      const message2 = (flags.message ?? toolArgs)?.trim();
-      if (!message2) {
-        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: message2 });
+      await appDeploy(client, { message: (flags.message ?? toolArgs)?.trim() || void 0 });
       return;
     }
     if (subcommand === "subdomain") {
@@ -100816,7 +101052,7 @@ Available workspaces:`);
         return;
       }
       if (action === "pull") {
-        await appWorkflowPull(client);
+        await appWorkflowPull(client, { force: flags.force === true });
         return;
       }
       workflowUsage();

package/dist/src/client.d.ts

@@ -244,6 +244,14 @@ export declare class LoticsClient {
             model_tier?: string;
             inputs?: Record<string, unknown>;
             outputs?: Record<string, unknown>;
+            /**
+             * The app's own queries/workflows this agent may call through
+             * `run_app_query` / `run_app_workflow`. These are REFERENCES that never
+             * appear in the client bundle, so anything asking "is this alias still
+             * used" must read them or it will answer no for an agent-driven app.
+             */
+            query_aliases?: string[];
+            workflow_aliases?: string[];
         }> | null;
         /**
          * Installation-level customization config values (the `useConfig()`

package/docs/cli_reference.md

@@ -29,11 +29,11 @@ Per-command syntax, flags, contracts, and gotchas for the public `lotics` CLI. S
 | `lotics knowledge update <id> [--from <file.md> \| --content <str>] [--name <n>] [--description <d>]` | Call `update_knowledge` with **only** the provided fields (a body from --from/--content becomes `content`; the tool diffs + CASes the content change internally, so the CLI passes no `expected_content_file_id`). At least one field required; --from and --content are mutually exclusive. |
 | `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, AND the runtime `.lotics/app_fields.ts` (the same linked-vs-bespoke branch `app codegen` runs, off the app row already fetched — see that row for the two forms). That one is not optional: `app deploy` tars source with `--exclude=.lotics`, so no archive can carry it, and a pulled project whose `src/` imports `F`/`OPT` would fail to build with `Could not resolve "../../.lotics/app_fields"` until `app codegen` was run by hand. The write NAMES the form and the reason, because an in-place pull can FLIP a project between them (`opctl app publish` links an origin, `package eject` unlinks it) and that changes what the module does at load. Skipped under `--view-as` (the schema is read as that member and silently drops tables they cannot see — a narrowed `F` map compiles and then throws at runtime, worse than the missing module). A binding/schema fetch failure is non-fatal and names the right recovery for what is on disk: an existing file is kept, an ABSENT one warns about the build error and points at `app codegen`. Pull GENERATES but never RECONCILES `.lotics/` — deleting a companion whose alias the manifest no longer declares is `app codegen`'s alone, since pull's authority is the server's alias set and a declared-but-not-yet-`set` alias is supported. 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_tier`/…) — 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 + 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, read by `useWorkflow` codegen and by `app workflow set`, never written by a deploy). 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 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. **A pull never overwrites a file that differs from what it is about to write** — it writes only what is ABSENT or already identical, keeps the rest, and reports which files it kept plus the commands that close the gap. An in-place refresh used to replace uncommitted work silently, since `tar -xzf` overwrites unconditionally and the command still exits 0. The same rule covers the two kinds the archive does NOT carry — `src/workflows/<alias>.ts` and `src/agents/<alias>.md`, both rewritten from the live row on every pull — so an unpushed body or prompt survives too. The comparison is against the app's own content, not git, so it holds for a project that was never a repo. `--force` takes the app's copy and DISCARDS local edits; there is no other way to lose them. — `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, AND the runtime `.lotics/app_fields.ts` (the same linked-vs-bespoke branch `app codegen` runs, off the app row already fetched — see that row for the two forms). That one is not optional: `app deploy` tars source with `--exclude=.lotics`, so no archive can carry it, and a pulled project whose `src/` imports `F`/`OPT` would fail to build with `Could not resolve "../../.lotics/app_fields"` until `app codegen` was run by hand. The write NAMES the form and the reason, because an in-place pull can FLIP a project between them (`opctl app publish` links an origin, `package eject` unlinks it) and that changes what the module does at load. Skipped under `--view-as` (the schema is read as that member and silently drops tables they cannot see — a narrowed `F` map compiles and then throws at runtime, worse than the missing module). A binding/schema fetch failure is non-fatal and names the right recovery for what is on disk: an existing file is kept, an ABSENT one warns about the build error and points at `app codegen`. Pull GENERATES but never RECONCILES `.lotics/` — deleting a companion whose alias the manifest no longer declares is `app codegen`'s alone, since pull's authority is the server's alias set and a declared-but-not-yet-`set` alias is supported. 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_tier`/…) — 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 OPTIONAL — omitted, the deploy derives the version message from what it actually pushed. Requiring it was the most common real failure in CLI telemetry, and a hard stop yields a retry plus filler rather than an audit trail; pass `-m` when you have a reason worth recording. npm run build; tar source + dist; POST /v1/apps/{id}/versions multipart. **One command ships everything**: before the bundle moves, a deploy pushes every binding the project has ahead of the app — an edited workflow body or declaration, edited agent prose, a changed query — through `set_app_query`, then `set_app_workflow`, then `set_app_agent`, and fails the release if any push is refused. That order is required: an agent declares the query and workflow aliases it may call, so pushing it before its own new query is refused. It never AUTHORS a binding itself — those verbs stay the single writers — and each push carries the fingerprint the project last saw live (`lotics.synced`), so a stale checkout is refused rather than overwriting another author's edit. `package.json` means the same thing for both artifacts: editing `lotics.agents.<alias>.inputs`/`outputs` is pushed exactly like the workflow equivalent (only those two fields — `set_app_agent` merges, so everything the manifest does not model is left untouched). It also regenerates `.lotics/app_fields.ts` before building, since the build INLINES it and which form is correct follows from whether the app is a package installation — a deploy that skipped it could ship an origin's baked ids into every other install. `lotics app check` reports the same set without pushing; neither has a `--strict`. Deploy also sends the manifest's `lotics.workflows` alias KEYS 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 warns about any alias the source CALLS that is NOT bound, and **unbinds the inverse** — bindings the app still serves that this bundle names nowhere. No flag: an orphan is a live, callable read path under the deployer's authority, and a deploy that adds bindings automatically but requires a decision to remove one just accumulates them. Unbinding runs AFTER the version is live, because the removal tools refuse an alias the SERVED version still declares — so doing it first is refused by the guard that makes it safe. It is skipped ENTIRELY (with a warning, never a failure) when the source computes an alias at run time, since the scan cannot tell which binding that reaches; that is the only case where the reference set is incomplete, because a binding is reachable from the bundle and from an agent's `query_aliases`/`workflow_aliases` and from nothing else — an app workflow carries no `on({...})` trigger, so no table event or schedule reaches one. A binding that will not unbind is reported and does NOT fail the release: the version is live and correct, and the leftover is the state every deploy left behind before this existed. |
 | `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). **`.lotics/` is reconciled to the manifest, not merely added to** — a `<alias>.globals.d.ts` whose alias the manifest no longer declares is DELETED (that directory is read as the app's alias inventory, so a companion for a binding nobody can reach misreports what the app has). Only that exact filename shape is removed; anything else in the directory is left alone. The reconcile runs before the credential branch, so it happens offline too. The authored counterpart is never deleted — a `src/workflows/<alias>.ts` the manifest does not declare is NAMED instead (`check` and `set` both take their alias set from the manifest, so editing an undeclared body is a silent no-op). A getApp / binding / schema / dts-fetch failure is non-fatal (warns, keeps the last-generated files). **Re-silvers `package.json#lotics.agents`** from the live app row whenever its `inputs`/`outputs` disagree, then rewrites the agent `.d.ts` from the refreshed block: that block is a mirror AND the offline seed for `useAgentRun` typings, so a stale copy types the app against an agent that does not exist. Refreshing here makes the divergence self-healing on a command already in the loop and keeps the remedy off `app pull` (which rewrites `src/workflows/*.ts` and would eat uncommitted body edits). The write is surgical and order-preserving (`orderedLike`), so it changes only the fields that actually differ. A hand edit to that block is therefore reverted — it never changed the agent anyway; to change one, `set_app_agent`. |
-| `lotics app check` | Every pre-flight `deploy` runs, WITHOUT building or shipping: the manifest's agent schemas against the live app row, aliases the source calls that nothing bound (queries, workflows AND agents), capability-gated SDK calls the manifest doesn't declare, `lotics.queries` drift, a missing icon/theme, and a notice for any alias the source computes at runtime (invisible to every check here and to the deploy's unbind guard). Adds no rule of its own — each finding is the same helper `deploy` calls, so a green check means a deploy will not complain. **Exits 1 only on what `deploy` REFUSES** (an agent schema that disagrees with the live app), so CI can gate on it while advisories stay advisory. It also names any `src/agents/<alias>.md` that differs from the live agent's instructions — a WARNING, not a gate, because `deploy` never pushes prose and shipping unrelated UI while a prompt is mid-edit is normal; a stale prompt does not make the bundle lie about its own types the way a stale schema does. The point is the question being ASKABLE: these checks used to cost a build, a tar, an upload and a version row in the audit trail, which is expensive enough that the honest move was to skip them and find out in production. |
+| `lotics app check` | Every pre-flight `deploy` runs, WITHOUT building or shipping: the manifest's agent schemas against the live app row, every binding a deploy would push, aliases the source calls that nothing bound (queries, workflows AND agents), bindings the app serves that the source names nowhere, capability-gated SDK calls the manifest doesn't declare, a missing icon/theme, and a notice for any alias the source computes at runtime (invisible to every check here and to the deploy's unbind guard). Adds no rule of its own — each finding is the same helper `deploy` calls, so a green check means a deploy will not complain. **Exits 1 on what a `deploy` would REFUSE or PUSH** — an agent schema that disagrees with the live app, and any binding the project has ahead of the app (an edited workflow body or declaration, edited agent prose, a changed query). Both are things a deploy would act on, so CI gating on a green check means a deploy has nothing left to do; genuine advisories (capabilities, branding, a runtime-computed alias, orphaned bindings) stay advisory and never fail it. The point is the question being ASKABLE: these checks used to cost a build, a tar, an upload and a version row in the audit trail, which is expensive enough that the honest move was to skip them and find out in production. |
 | `lotics app workflow run <alias> '<json>'` | Execute a bound app workflow end-to-end via `appWorkflow`. `app_id` comes from the local manifest; the alias must be bound (`set_app_workflow`). Inputs ingest exactly like `lotics run` (inline JSON / `@file` / stdin — bulk inputs bypass `ARG_MAX`). Prints the full `{status,message,data,files,side_effects}` JSON to stdout + a one-line summary to stderr; exits non-zero on `status:"error"` (assertable). `--print-created` (alias `--report-effects`) renders the honest post-run harvest: created records grouped by table, a paste-ready `lotics run delete_records …` per table, then the **mandatory caveat** naming what cannot be auto-undone (external integrations + notifications) and that sub-workflows may have run. `--cleanup` (DEFAULT OFF, implies the report) additionally runs the deletes for harvested records ONLY — never files / external / notifications. Neither is a rollback — a rollback is structurally impossible here. |
 | `lotics app workflow set <alias>` | Push the edited `src/workflows/<alias>.ts` body through `set_app_workflow` (the single author of `apps.workflows`). Reads the body from disk (header + `/// <reference>` + `export {};` marker + the `__workflow` wrapper all stripped) + the typed `inputs`/`outputs` **and the `description`** from `package.json#lotics.workflows.<alias>`; the **server** re-verifies the body and echoes the bound `outputs` (declared, else DERIVED from `return({ data })`). The `description` is the one line an agent reads when choosing between the app's aliases (the workflow counterpart to a query's) — authored in the manifest so it lives beside the body in version control and rides every push; omit it and the workflow keeps whatever description it already has, so a push can never blank one set elsewhere. When the manifest declared NO `outputs`, the DERIVED echo is written back into `package.json#lotics.workflows.<alias>.outputs` (a SURGICAL write — preserves `knowledge`/`config` and every other manifest field) and that alias's types are refreshed in place, so `useWorkflow("<alias>")`'s `result.data` is typed immediately with no hand-copy and no second `lotics app codegen`; an explicitly-declared `outputs` is authoritative and never overwritten. Deploy still never authors workflows — this is a CLI convenience over the existing tool. Clear error + non-zero exit on a missing file, an alias absent from the manifest, or a verify failure. |
 | `lotics app agent set <alias>` | Push 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 an agent's PROSE. It sends the instructions and nothing else: the server merges against the stored declaration, so every typed field keeps exactly what is bound. This is deliberate and it is the opposite of what the symmetry with `app workflow set` suggests — **the manifest is a snapshot from the last `app pull`, so replaying its typed half would silently revert whatever was bound since** (the chat authoring agent adding `knowledge_doc_ids`, another operator granting `query_aliases`), and the CLI would print success while the agent quietly lost its knowledge and its read surface. To change a typed field, call `set_app_agent` with just that field (`lotics run set_app_agent '{"app_id":…,"alias":…,"outputs":{…}}'` — it merges), then `app pull` to bring the manifest back in step. Editing `package.json#lotics.agents` by hand pushes nothing, and since that block is what types `useAgentRun`, `codegen` warns and `deploy` REFUSES while it disagrees with the live app. 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`. |

package/package.json

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