@lotics/cli 0.106.0 → 0.109.0

package/AGENTS.md

@@ -57,5 +57,20 @@ whether something exists, read `lotics --help` § COMMANDS — the whole section
   half — an agent's `tool_names`/`inputs`/`outputs`, a workflow's schemas — is authored by the
   `set_app_*` tools. A manifest alias with no server binding only fails at the app's first call, so
   deploy warns about the mismatch.
+
+  **The five `lotics.*` keys look alike and point in three different directions.** Before editing one,
+  know which you are touching — this is the single most expensive thing to get wrong in a manifest:
+
+  | `lotics.<key>` | Owned by | Your edit reaches the app via |
+  |---|---|---|
+  | `queries`, `capabilities` | the manifest | `app deploy` — re-synced on every one (an absent `capabilities` block turns them all OFF) |
+  | `knowledge`, `config` | the manifest | `opctl app publish` / `app release` — package authoring only |
+  | `workflows` | the workflow row's verified contract | `app workflow set`, which type-checks the BODY against your declaration and refuses a schema the body cannot satisfy |
+  | `agents` | the app row | **nothing.** It is a mirror: `app codegen` re-silvers it from the app, and an agent is changed with `set_app_agent` |
+
+  `agents` is the one that bites, because editing a mirror still retypes `useAgentRun` — green
+  locally, unchanged in production. `app codegen` reverts such an edit and `app deploy` refuses while
+  the two disagree. An agent's PROSE is not in the manifest at all: it lives in
+  `src/agents/<alias>.md` and is pushed by `app agent set`.
 - **OAuth connections.** Attaching a connected account is web-only; the CLI can list them.
 - **Anything needing a browser.** `app dev` and `file preview` shell out to a local Chrome.

package/README.md

@@ -209,6 +209,11 @@ lotics app versions app_...                # ...for any app, without pulling it
 # use this after a rename, or when a pull ran offline.
 lotics app codegen                         # import { F, OPT } from "../.lotics/app_fields"
 
+# Every deploy pre-flight, WITHOUT the build or the version row: agent schemas vs
+# the live app, aliases the code calls that nothing bound, undeclared capabilities,
+# query drift. Exits 1 on what a deploy refuses, so CI can gate on it.
+lotics app check
+
 # Execute a bound app workflow end-to-end (inputs: inline / @file / stdin)
 lotics app workflow run issueInvoice '{"record_id":"rec_..."}'
 cat inputs.json | lotics app workflow run importRates   # bulk inputs bypass ARG_MAX

package/dist/src/cli.js

@@ -70180,11 +70180,58 @@ async function fetchLatestNpmVersion(packageName) {
     return null;
   }
 }
+function orderedLike(value, template) {
+  if (Array.isArray(value)) {
+    const t = Array.isArray(template) ? template : [];
+    return value.map((v, i2) => orderedLike(v, t[i2]));
+  }
+  if (value === null || typeof value !== "object") return value;
+  const from = value;
+  const tmpl = template !== null && typeof template === "object" && !Array.isArray(template) ? template : {};
+  const has2 = (o, k) => Object.prototype.hasOwnProperty.call(o, k);
+  const first3 = Object.keys(tmpl).filter((k) => has2(from, k));
+  const taken = new Set(first3);
+  const rest = Object.keys(from).filter((k) => !taken.has(k));
+  return Object.fromEntries(
+    [...first3, ...rest].map((k) => [k, orderedLike(from[k], tmpl[k])])
+  );
+}
 function toManifestAgents(agents) {
   return Object.fromEntries(
     Object.entries(agents).map(([alias, { instructions: _prose, ...typed }]) => [alias, typed])
   );
 }
+var AGENT_TYPED_KEYS = ["inputs", "outputs"];
+function sameSchema(a, b) {
+  const canonical = (v) => {
+    if (Array.isArray(v)) return v.map(canonical);
+    if (v && typeof v === "object") {
+      return Object.fromEntries(
+        Object.entries(v).sort(([x2], [y]) => x2 < y ? -1 : x2 > y ? 1 : 0).map(([k, val]) => [k, canonical(val)])
+      );
+    }
+    return v;
+  };
+  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;
+}
 var WORKFLOWS_DIR = path5.join("src", "workflows");
 var WORKFLOW_GLOBALS_DIR = path5.join(".lotics", "workflows");
 var AGENTS_DIR = path5.join("src", "agents");
@@ -70631,8 +70678,9 @@ async function appCodegen(args) {
     );
     return;
   }
+  let app = null;
   try {
-    const app = await args.client.getApp(meta3.app_id);
+    app = await args.client.getApp(meta3.app_id);
     await writeGeneratedAppFields(
       args.client,
       projectDir,
@@ -70642,6 +70690,20 @@ async function appCodegen(args) {
   } catch (err2) {
     warnAppFieldsUnwritten(projectDir, err2);
   }
+  if (app) {
+    const refreshedAgents = orderedLike(toManifestAgents(app.agents ?? {}), meta3.agents);
+    if (!sameSchema(meta3.agents ?? {}, refreshedAgents)) {
+      writeAppMeta(projectDir, { ...meta3, agents: refreshedAgents });
+      writeAppDts(projectDir, {
+        workflows: meta3.workflows,
+        queries: meta3.queries,
+        agents: refreshedAgents
+      });
+      console.error(
+        `Refreshed package.json#lotics.agents from the app \u2014 that block reflects it, so a hand edit retypes useAgentRun without changing the agent. To change one: set_app_agent.`
+      );
+    }
+  }
   await refreshWorkflowGlobals(args.client, projectDir, meta3.app_id, meta3.workflows ?? {});
 }
 async function refreshWorkflowGlobals(client, projectDir, app_id, workflows) {
@@ -70883,24 +70945,27 @@ async function appDeploy(client, args) {
   const projectDir = path5.resolve(args.projectDir ?? process.cwd());
   const meta3 = readAppMeta(projectDir);
   warnIfDeployingLinkedKit(projectDir);
-  const sourceText = readAppSourceText(projectDir);
-  const called = calledAppAliases(sourceText);
-  if (called.dynamic.length > 0) {
+  const liveApp = await client.getApp(meta3.app_id);
+  const divergences = agentTypeDivergences(meta3.agents, liveApp.agents);
+  if (divergences.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(
-      `
-\u26A0 This app calls capability-gated SDK functions for ${undeclared.join(", ")} but the manifest doesn't declare ${undeclared.length > 1 ? "them" : "it"} \u2014 those calls will 403 at runtime.
-  Add to package.json#lotics.capabilities:  ${block}`
+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 sourceText = readAppSourceText(projectDir);
+  const called = calledAppAliases(sourceText);
+  warnIfAgentProseDiffers(projectDir, liveApp.agents);
+  warnIfDynamicAliases(called);
+  warnIfUndeclaredCapabilities(sourceText, meta3.capabilities);
   writeAppDts(projectDir, { workflows: meta3.workflows, queries: meta3.queries, agents: meta3.agents });
   console.error("Building...");
   await runNpm(["run", "build"], projectDir);
@@ -71019,6 +71084,63 @@ function warnIfQueriesDiffer(app, manifest) {
   (or one alias at a time), or adopt the app's with 'lotics app pull'.`
   );
 }
+async function appCheck(client, args = {}) {
+  const projectDir = path5.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.`
+    );
+  }
+  warnIfDeployingLinkedKit(projectDir);
+  warnIfAgentProseDiffers(projectDir, app.agents);
+  warnIfDynamicAliases(called);
+  warnIfUndeclaredCapabilities(sourceText, meta3.capabilities);
+  warnIfUnboundAliases(app, called);
+  warnIfQueriesDiffer(app, meta3.queries ?? {});
+  warnIfUnbranded(app);
+  if (divergences.length > 0) process.exit(1);
+  console.error("Checked the app's bindings, capabilities and agent schemas \u2014 nothing blocking.");
+}
+function warnIfAgentProseDiffers(projectDir, liveAgents) {
+  for (const [alias, live] of Object.entries(liveAgents ?? {})) {
+    const file2 = agentFilePath2(projectDir, alias);
+    if (!fs4.existsSync(file2)) continue;
+    const local = stripAgentHeader(fs4.readFileSync(file2, "utf-8"));
+    if (local === "" || local === (live.instructions ?? "")) continue;
+    console.error(
+      `
+\u26A0 ${path5.relative(projectDir, file2)} differs from the live agent's instructions.
+  A deploy does not push prose. Send it with 'lotics app agent set ${alias}'.`
+    );
+  }
+}
+function warnIfDynamicAliases(called) {
+  if (called.dynamic.length === 0) return;
+  console.error(
+    `
+\u26A0 This app calls ${called.dynamic.join(" / ")} with an alias it computes at runtime, which no static check can read.
+  A version records only the aliases named as literals, so removing a binding this app reaches dynamically will NOT be refused.`
+  );
+}
+function warnIfUndeclaredCapabilities(sourceText, capabilities) {
+  const undeclared = undeclaredCapabilities(sourceText, capabilities);
+  if (undeclared.length === 0) return;
+  const block = JSON.stringify(Object.fromEntries(undeclared.map((c) => [c, true])));
+  console.error(
+    `
+\u26A0 This app calls capability-gated SDK functions for ${undeclared.join(", ")} but the manifest doesn't declare ${undeclared.length > 1 ? "them" : "it"} \u2014 those calls will 403 at runtime.
+  Add to package.json#lotics.capabilities:  ${block}`
+  );
+}
 function warnIfUnboundAliases(app, called) {
   const {
     queries: unboundQueries,
@@ -92068,6 +92190,11 @@ COMMANDS
                                        * marks the currently served version)
   lotics app codegen [path]            Regenerate .lotics/* (types + field/option ids)
                                        from the manifest + workspace schema \u2014 no deploy
+  lotics app check                     Run every deploy pre-flight WITHOUT building or
+                                       shipping: agent schemas vs the live app, aliases
+                                       the code calls but nothing bound, undeclared
+                                       capabilities, query drift. Exits 1 on what a
+                                       deploy would refuse, so CI can gate on it
   lotics app workflow run <alias> '<json>'  Execute a bound app workflow end-to-end
                                        (inputs: inline JSON, @file, or stdin;
                                         --print-created reports created records +
@@ -92085,10 +92212,11 @@ COMMANDS
                                        (inputs: inline JSON, @file, or stdin; streams
                                         progress to stderr, reports the settled run;
                                         --session <id> continues a thread; --json)
-  lotics app agent set <alias>         Push the edited src/agents/<alias>.md instructions
-                                       + the manifest's typed fields through set_app_agent
-                                       (set_app_agent REPLACES the declaration \u2014 this
-                                        sends it whole so nothing is silently dropped)
+  lotics app agent set <alias>         Push the edited src/agents/<alias>.md instructions,
+                                       and ONLY those \u2014 the server merges, so the typed
+                                       fields keep whatever is bound (a manifest is a
+                                       snapshot; replaying it would revert them). Change
+                                       those with set_app_agent, then pull.
   lotics app subdomain <new-subdomain> Rename the app's public <slug>.lotics.app address
   lotics app rename "<new name>"       Rename the app's display name (launcher title)
   lotics app dev [path]                Run the app locally with HMR (RPC forwarded to prod)
@@ -92608,6 +92736,7 @@ async function main() {
     console.error("  lotics app deploy -m <message>       Build + upload the current directory (-m required)");
     console.error("  lotics app versions [app_id]         Show deploy history (version, when, who, message)");
     console.error("  lotics app codegen [path]            Regenerate .lotics/* (types + field ids) \u2014 no deploy");
+    console.error("  lotics app check                     Deploy's pre-flight without the build (exits 1 on a blocker)");
     console.error("  lotics app workflow run <alias> '<json>'  Execute a bound app workflow end-to-end");
     console.error("  lotics app workflow set <alias>           Push the edited src/workflows/<alias>.ts body");
     console.error("  lotics app workflow pull                  Rewrite src/workflows/*.ts from the server");
@@ -92823,6 +92952,10 @@ Available workspaces:`);
       await appVersions(client, { app_id: appId });
       return;
     }
+    if (subcommand === "check") {
+      await appCheck(client, {});
+      return;
+    }
     if (subcommand === "workflow") {
       const action = toolArgs;
       const workflowUsage = () => {

package/docs/cli_reference.md

@@ -32,10 +32,11 @@ Per-command syntax, flags, contracts, and gotchas for the public `lotics` CLI. S
 | `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_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 + 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 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). |
+| `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 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 `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 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`. |
 | `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. 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). Each alias's `description` is folded back into `package.json#lotics.workflows.<alias>` from the same read — the alias binding the manifest is otherwise stamped from carries `inputs`/`outputs` but not the description, which lives on the workflow ROW, so without this a pull would erase an authored one. The server's GENERATED default is skipped, so an app that never described its workflows gains no manifest noise. 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. |

package/package.json

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