@lotics/cli 0.106.0 → 0.110.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

@@ -45332,7 +45332,7 @@ import { randomUUID } from "node:crypto";
 import { tmpdir } from "node:os";
 
 // src/starter_template.ts
-var STARTER_FALLBACK_UI_VERSION = "12.1.0";
+var STARTER_FALLBACK_UI_VERSION = "27.11.0";
 var STARTER_FALLBACK_SDK_VERSION = "0.52.0";
 var STARTER_REACT_NATIVE_VERSION = "0.85.3";
 var VITEST_SETUP_FILENAME = "vitest.setup.ts";
@@ -45486,7 +45486,7 @@ function buildStarterTemplate(args) {
 import { defineConfig } from "vite";
 import type { Plugin } from "vite";
 import react from "@vitejs/plugin-react";
-import { loticsOptimizeDeps } from "@lotics/ui/vite";
+import { loticsOptimizeDeps, loticsResolve } from "@lotics/ui/vite";
 
 // @lotics/ui/icon.tsx deep-imports \`lucide-react-native/dist/esm/icons/<name>\`.
 // lucide-react-native's \`exports\` map lists only "." and "./icons", so a strict
@@ -45515,11 +45515,6 @@ function lucideIconsWebAlias(): Plugin {
 // render endpoint rewrites those to /v1/apps/{id}/asset/... so the bundle
 // loads via the platform's asset proxy. Don't change \`base\` unless you
 // also adjust the rewrite logic in backend/api/apps.ts:rewriteAssetPaths.
-//
-// react-native \u2192 react-native-web alias lets @lotics/ui's RN primitives
-// (View, Text, Pressable, StyleSheet, etc.) render in a pure-web environment.
-// .web.tsx is prioritized in resolve.extensions so per-target variants
-// (avatar.web.tsx, wave_avatar.web.tsx) win over the native .tsx file.
 export default defineConfig({
   plugins: [lucideIconsWebAlias(), react()],
   // RN libraries reference globals Metro injects but Vite does not \u2014 undefined
@@ -45531,41 +45526,18 @@ export default defineConfig({
   // rn-web only reads \`global.x\` as a free var, so mapping it to \`globalThis\`
   // is safe. Define both so dev and the deployed build behave identically.
   define: { __DEV__: "false", global: "globalThis" },
-  resolve: {
-    // \`LOTICS_UI_SRC\` dev-links @lotics/ui to a monorepo checkout, so kit edits
-    // go live (HMR) and bundle on deploy without a publish round-trip:
-    //   LOTICS_UI_SRC=/abs/path/to/packages/ui/src lotics app dev
-    // Unset \u21D2 the kit resolves from node_modules as normal. It lives in the ENV,
-    // never in this file: the link used to be written here by \`lotics ui link\`
-    // and removed by \`--remove\`, which is a regex editing TypeScript \u2014 it twice
-    // took the react-native alias below with it and left the app unable to build.
-    // State that only exists for the length of one command belongs in the command.
-    // VITE ONLY: \`tsc\` still resolves @lotics/ui from node_modules (the kit's
-    // src is RN-Web and cannot typecheck inside an app), so typecheck the kit in
-    // packages/ui and let the publish restore this app's own typecheck.
-    alias: [
-      ...(process.env.LOTICS_UI_SRC
-        ? [{ find: /^@lotics\\/ui\\/(.+)$/, replacement: \`\${process.env.LOTICS_UI_SRC}/$1\` }]
-        : []),
-      { find: "react-native", replacement: "react-native-web" },
-    ],
-    // \`.web.js\` resolves the web build of RN packages that ship \`X.js\` (native)
-    // beside \`X.web.js\` (web) \u2014 e.g. @react-native-picker/picker, whose compiled
-    // \`Picker.web.js\` renders a real <select>. Without it the extensionless
-    // \`require("./Picker")\` picks native \`Picker.js\` and the standard Picker
-    // renders nothing on web.
-    // \`.mjs\`/\`.mts\` keep parity with Vite's DEFAULT resolver, which this override
-    // otherwise drops \u2014 a bare package subpath that ships ONLY as \`.mjs\` (e.g.
-    // \`lucide-react/dynamic\`, imported by @lotics/ui's DynamicIcon/AppIcon) would
-    // fail to resolve under \`lotics app dev\` while the prod rollup build resolves
-    // it, so the gap is dev-only and silent (build/typecheck/lint stay green).
-    extensions: [".web.tsx", ".web.ts", ".web.js", ".tsx", ".ts", ".jsx", ".js", ".mjs", ".mts"],
-    // @lotics/ui ships source and is consumed across many subpath entries
-    // (./card, ./metric, ./use_screen_size, \u2026). Without dedupe, Vite can
-    // pre-bundle a subpath into its own chunk with a second React copy \u2014 a
-    // hook called from there hits a null dispatcher ("Invalid hook call").
-    // Pin React (and RN-Web) to a single instance shared by every chunk.
-    dedupe: ["react", "react-dom", "react-native-web"],
+  // The kit owns its own resolution \u2014 the react-native \u2192 react-native-web alias,
+  // \`.web.tsx\`-first extensions, the React dedupe, and the \`LOTICS_UI_SRC\`
+  // dev-link \u2014 for the same reason it owns \`loticsOptimizeDeps\`: every entry is
+  // dictated by @lotics/ui's internals, so shipping it WITH the kit means it can
+  // never drift from the version installed here. It also stops being an app's job
+  // to hand-carry a load-bearing alias that a regex edit twice deleted (GAP-133/142).
+  // \`lotics app codegen\` writes the matching \`paths\` into
+  // .lotics/tsconfig.link.json, so tsc/vitest/eslint/your editor resolve the same
+  // @lotics/ui this does. To add your own alias, spread it:
+  //   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
@@ -45942,48 +45914,6 @@ declare module "lucide-react-native/dist/esm/icons/*" {
 
 // Plain side-effect CSS imports (@lotics/ui ships .tsx with import "./x.css").
 declare module "*.css";
-`
-    },
-    {
-      path: "src/react_native.d.ts",
-      content: `import "react-native";
-
-// Augments react-native's types with the web-only fields @lotics/ui consumes:
-// Pressable's \`hovered\` callback state, plus web-only ViewStyle / TextStyle
-// properties (cursor, outline, boxShadow, etc.) used by its primitives.
-// Each iframe app needs its own copy \u2014 TypeScript doesn't auto-pick-up
-// \`.d.ts\` files inside dependencies.
-declare module "react-native" {
-  interface PressableStateCallbackType {
-    hovered: boolean;
-  }
-
-  interface ViewStyle {
-    backdropFilter?: string;
-    backgroundImage?: string;
-    boxShadow?: string;
-    boxSizing?: string;
-    cursor?: string;
-    touchAction?: string;
-    transitionDuration?: string;
-    transitionProperty?: string;
-    appearance?: string;
-    outline?: string;
-    outlineColor?: string;
-    outlineStyle?: string;
-    outlineWidth?: number;
-    outlineOffset?: number;
-  }
-
-  interface TextStyle {
-    outline?: string;
-    outlineColor?: string;
-    outlineStyle?: string;
-    outlineWidth?: number;
-    outlineOffset?: number;
-    appearance?: string;
-  }
-}
 `
     },
     {
@@ -70180,11 +70110,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");
@@ -70483,10 +70460,75 @@ function ensureAppTsconfig(projectDir) {
     parsed.exclude = [...currentEx, ...toAdd];
     changes.push(`added ${toAdd.join(", ")} to "exclude"`);
   }
+  const existingExtends = parsed.extends;
+  if (existingExtends === void 0) {
+    parsed.extends = `./${LINK_TSCONFIG}`;
+    changes.push(`added "extends": "./${LINK_TSCONFIG}" (so tsc resolves the same @lotics/ui as Vite)`);
+  } else if (existingExtends !== `./${LINK_TSCONFIG}`) {
+    console.error(
+      `\u26A0 tsconfig.json already extends ${JSON.stringify(existingExtends)}, so the dev-link config was not added \u2014 \`tsc\` will keep resolving @lotics/ui from node_modules even under LOTICS_UI_SRC. Add "./${LINK_TSCONFIG}" to "extends" (it accepts an array) to fix it.`
+    );
+  }
   if (changes.length === 0) return;
   fs4.writeFileSync(tsconfigPath, JSON.stringify(parsed, null, 2) + "\n");
   console.error(`Patched tsconfig.json: ${changes.join("; ")}.`);
 }
+var LINK_TSCONFIG = ".lotics/tsconfig.link.json";
+function writeDevLinkTsconfig(projectDir) {
+  const uiSrc = process.env.LOTICS_UI_SRC;
+  const paths = {};
+  if (uiSrc) {
+    paths["@lotics/ui/*"] = [`${uiSrc}/*`];
+    for (const peer of readKitPeerNames(projectDir)) {
+      const typesDir = path5.join(projectDir, "node_modules", typesPackageFor(peer));
+      const runtimeDir = path5.join(projectDir, "node_modules", peer);
+      const target = fs4.existsSync(typesDir) ? `../node_modules/${typesPackageFor(peer)}` : fs4.existsSync(runtimeDir) ? `../node_modules/${peer}` : null;
+      if (!target) continue;
+      paths[peer] = [target];
+      paths[`${peer}/*`] = [`${target}/*`];
+    }
+  }
+  const file2 = path5.join(projectDir, ".lotics", "tsconfig.link.json");
+  const header = uiSrc ? `// GENERATED by \`lotics app codegen\` \u2014 do not edit.
+// LOTICS_UI_SRC is set, so @lotics/ui resolves to your working copy for tsc,
+// vitest, eslint and your editor \u2014 the same copy Vite is bundling. The peer
+// pins keep ONE react / react-native in the program; without them the kit's
+// source resolves its own copies and every shared type stops matching.
+// Unset LOTICS_UI_SRC and re-run to go back to the published kit.
+` : `// GENERATED by \`lotics app codegen\` \u2014 do not edit.
+// LOTICS_UI_SRC is not set, so this is inert and @lotics/ui resolves from
+// node_modules as normal.
+`;
+  fs4.writeFileSync(file2, `${header}${JSON.stringify({ compilerOptions: { paths } }, null, 2)}
+`);
+  return file2;
+}
+function writeKitTypeAugmentation(projectDir) {
+  const uiSrc = process.env.LOTICS_UI_SRC;
+  const source = uiSrc ? path5.join(uiSrc, "react_native.d.ts") : path5.join(projectDir, "node_modules", "@lotics", "ui", "src", "react_native.d.ts");
+  const target = path5.join(projectDir, ".lotics", "react_native.d.ts");
+  if (!fs4.existsSync(source)) {
+    if (fs4.existsSync(target)) fs4.rmSync(target);
+    return;
+  }
+  fs4.writeFileSync(
+    target,
+    `// GENERATED by \`lotics app codegen\` from @lotics/ui \u2014 do not edit.
+// The kit's web-only ViewStyle/TextStyle properties, which react-native does
+// not model. Delete any hand-copied src/react_native.d.ts; this replaces it.
+` + fs4.readFileSync(source, "utf-8")
+  );
+}
+function typesPackageFor(peer) {
+  return peer.startsWith("@") ? `@types/${peer.slice(1).replace("/", "__")}` : `@types/${peer}`;
+}
+function readKitPeerNames(projectDir) {
+  const kitPkg = path5.join(projectDir, "node_modules", "@lotics", "ui", "package.json");
+  if (!fs4.existsSync(kitPkg)) return [];
+  const parsed = JSON.parse(fs4.readFileSync(kitPkg, "utf-8"));
+  const peers = parsed.peerDependencies;
+  return peers && typeof peers === "object" ? Object.keys(peers) : [];
+}
 function writeAppDts(projectDir, manifest) {
   const dotLotics = path5.join(projectDir, ".lotics");
   fs4.mkdirSync(dotLotics, { recursive: true });
@@ -70496,6 +70538,8 @@ function writeAppDts(projectDir, manifest) {
     [path5.join(dotLotics, "app_agents.d.ts"), generateAppAgentsDts(manifest.agents)]
   ];
   for (const [file2, content] of written) fs4.writeFileSync(file2, content);
+  writeDevLinkTsconfig(projectDir);
+  writeKitTypeAugmentation(projectDir);
   ensureAppTsconfig(projectDir);
   return written.map(([file2]) => file2);
 }
@@ -70564,28 +70608,26 @@ function warnAppFieldsUnwritten(projectDir, err2) {
     `\u26A0 Could not generate .lotics/app_fields.ts (${reason}), and this project has none. Any source importing F/OPT will fail to build with 'Could not resolve "../../.lotics/app_fields"'. Run 'lotics app codegen' once you can reach the workspace.`
   );
 }
-function warnIfDeployingLinkedKit(projectDir) {
-  const uiSrc = process.env.LOTICS_UI_SRC;
-  if (!uiSrc) return;
-  const viteConfigPath = path5.join(projectDir, "vite.config.ts");
-  if (!fs4.existsSync(viteConfigPath)) return;
-  if (!fs4.readFileSync(viteConfigPath, "utf-8").includes("LOTICS_UI_SRC")) return;
-  console.error(
-    `\u26A0 LOTICS_UI_SRC is set \u2014 this deploy bundles @lotics/ui from ${uiSrc}, NOT the published package. The deployed app will run kit code that exists only on this machine. Unset it and re-deploy once the kit change is published if that is not what you want.`
-  );
-}
-function warnIfDevLinkIgnored(projectDir) {
+function warnAboutDevLink(projectDir, command) {
   const uiSrc = process.env.LOTICS_UI_SRC;
   if (!uiSrc) return;
   const viteConfigPath = path5.join(projectDir, "vite.config.ts");
-  if (!fs4.existsSync(viteConfigPath)) return;
-  if (fs4.readFileSync(viteConfigPath, "utf-8").includes("LOTICS_UI_SRC")) return;
-  console.error(
-    `\u26A0 LOTICS_UI_SRC is set but vite.config.ts never reads it \u2014 @lotics/ui will still resolve from node_modules, so kit edits will NOT appear. Add the dev-link entry to \`resolve.alias\` (refresh vite.config.ts from the starter, or paste):
-    ...(process.env.LOTICS_UI_SRC
-      ? [{ find: /^@lotics\\/ui\\/(.+)$/, replacement: \`\${process.env.LOTICS_UI_SRC}/$1\` }]
-      : []),`
-  );
+  const config2 = fs4.existsSync(viteConfigPath) ? fs4.readFileSync(viteConfigPath, "utf-8") : "";
+  const linked = config2.includes("loticsResolve") || config2.includes("LOTICS_UI_SRC");
+  if (!linked) {
+    console.error(
+      `\u26A0 LOTICS_UI_SRC is set but vite.config.ts never reads it \u2014 @lotics/ui will still resolve from node_modules, so kit edits will NOT ${command === "deploy" ? "ship" : "appear"}. Hand the whole resolve block to the kit (it owns the dev-link, the react-native alias, the extensions and the dedupe):
+    import { loticsOptimizeDeps, loticsResolve } from "@lotics/ui/vite";
+    // \u2026
+    resolve: loticsResolve(),`
+    );
+    return;
+  }
+  if (command === "deploy") {
+    console.error(
+      `\u26A0 LOTICS_UI_SRC is set \u2014 this deploy bundles @lotics/ui from ${uiSrc}, NOT the published package. The deployed app will run kit code that exists only on this machine. Unset it and re-deploy once the kit change is published if that is not what you want.`
+    );
+  }
 }
 function ensureAppVitestSetup(projectDir) {
   const setupPath = path5.join(projectDir, VITEST_SETUP_FILENAME);
@@ -70631,8 +70673,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 +70685,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) {
@@ -70882,25 +70939,28 @@ function readAppSourceText(projectDir) {
 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) {
-    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])));
+  warnAboutDevLink(projectDir, "deploy");
+  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 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 +71079,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.`
+    );
+  }
+  warnAboutDevLink(projectDir, "deploy");
+  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,
@@ -71045,7 +71162,7 @@ function warnIfUnboundAliases(app, called) {
 async function appDev(client, args) {
   const projectDir = path5.resolve(args.projectDir ?? process.cwd());
   const meta3 = readAppMeta(projectDir);
-  warnIfDevLinkIgnored(projectDir);
+  warnAboutDevLink(projectDir, "dev");
   writeAppDts(projectDir, { workflows: meta3.workflows, queries: meta3.queries, agents: meta3.agents });
   const app = await client.getApp(meta3.app_id);
   const handle = await startDevServer({
@@ -92068,6 +92185,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 +92207,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 +92731,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 +92947,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. |
@@ -43,7 +44,7 @@ Per-command syntax, flags, contracts, and gotchas for the public `lotics` CLI. S
 | `lotics app subdomain <new-subdomain>` | Rename the app's public `<slug>.lotics.app` address via `PUT /v1/apps/{id}/subdomain`. app_id comes from the local `package.json` manifest; the chosen slug must be a valid DNS label and free; the old address stops resolving. |
 | `lotics app rename "<new name>"` | Change the app's display name (launcher/title) via the `update_app` tool. app_id comes from the local `package.json` manifest; the public address (`subdomain`) and code (`deploy`) are unchanged. |
 | `lotics app dev [path] [--port=N] [--vite-port=N] [--view-as=<member_id>]` | Spawn Vite dev server + an RPC-forwarding HTTP server. The wrapper page embeds the iframe with `sandbox="allow-scripts allow-same-origin"` matching production; postMessage ops (query / workflow / members / context / upload / openExternal / urlState / agentRun) are forwarded to api.lotics.ai using the CLI's API key — file bytes move in **both** directions through the dev server's own relays, never browser↔storage: dev runs against the PROD bucket, whose CORS admits `https://*.lotics.app` and not `http://localhost:<port>`, so a direct browser transfer is blocked — no upload could complete and no preview engine (PDF/Word/Excel all FETCH the bytes) could read a file. `upload` mints a presigned URL and PUTs it **to `PUT /_upload/<file_id>`** (`dev/upload_relay.ts`) from the wrapper page — same-origin, so no preflight and no CORS — and Node forwards it on; every presigned `url`/`thumbnail_url`/`preview_url` on a **file object** in an RPC result is rewritten to **`GET /_file/<token>`** (`dev/file_relay.ts`, absolute — the iframe would resolve a relative path against Vite), which streams the bytes back with `Range` passthrough (206s intact, so PDF seeking works) and an `Access-Control-Allow-Origin` for the Vite origin (the one cross-origin hop left is OUR response to allow). Neither relay ever takes a destination from the client — it gets a `file_id`/token and transfers only to/from a URL it minted or observed itself, so there is no client-controlled target and no SSRF surface. A URL in a record's own text cell is NOT rewritten. Production is unchanged (direct-to-storage, no bytes through the API server); `openExternal` and `urlState.get/set` are handled locally (the latter read/write the wrapper page's own address bar — `set` writes in place via `replaceState` and browser back/forward broadcast a `url-state` message back, so `useUrlState` survives refresh and is shareable in the dev loop; in-app *routing* is the app's own (the iframe owns its url via `@lotics/app-sdk/router`), and the wrapper bakes the saved screen (`_loc`) into the iframe src on load so a refresh restores it, mirroring production); `agentRun` (streaming) is proxied through `POST /_agent_run`, which opens the run's SSE with the CLI key and pipes chunks back to the iframe (`stream-chunk`* → `stream-end`), so `useAgentRun` works in the dev loop just like production; `context` resolves the viewer (`member_id` from `cli/whoami` + `comments_enabled` from the local manifest) and fetches the installation's stored `config` live from the app row, so `useConfig()` renders the same values as production. `--view-as` (global flag; also `LOTICS_VIEW_AS`) threads `x-view-as-member-id` so `is_current_member` + `context` resolve to that member — **admin key only** (the server 403s a non-admin), writes stay attributed to the key owner. Hot reload via Vite; full DevTools / Playwright access via plain localhost. The dev-optimizer pre-bundle list (`optimizeDeps.include`, load-bearing for dev) is imported from `@lotics/ui/vite` (`loticsOptimizeDeps`) rather than hardcoded in the scaffold, so it tracks the installed `@lotics/ui` and can never go stale. Binds **loopback only** (`127.0.0.1`) — `/_rpc` dispatches with the developer's API key, so a socket on every interface would hand anyone on the network full read/write on the workspace. |
-| `LOTICS_UI_SRC=<abs path to packages/ui/src>` (env, not a command) | Dev-link `@lotics/ui` to a monorepo checkout for the length of ONE command: the app's own `vite.config.ts` reads the variable and adds a `{ find: /^@lotics\/ui\/(.+)$/, replacement: "<LOTICS_UI_SRC>/$1" }` entry to `resolve.alias`, so kit edits go live under `lotics app dev` (HMR) and bundle under `lotics app deploy`. Unset ⇒ the kit resolves from `node_modules` as normal. **Nothing is written to disk** — there is no link/unlink step, nothing to leave switched on, and no config for the CLI to corrupt (the `lotics ui link` command this replaces edited `vite.config.ts` by regex and twice deleted the load-bearing `react-native` → `react-native-web` alias with the array's closing bracket, breaking the app's build entirely). Identical for a monorepo app and an EXTERNAL one (e.g. `~/lotics_apps`). `app dev` **warns** when the variable is set but the app's `vite.config.ts` predates it (scaffolded earlier) and prints the lines to add; `app deploy` **warns** that the bundle carries kit code from your working copy rather than the published package. **Vite-only, by design:** the app's `tsc` still resolves `@lotics/ui` from `node_modules` (the published `.d.ts`) — the kit `src` can't be typechecked inside an app because it's RN-Web, so typecheck the kit in `packages/ui` and let the finalize publish restore the app's own typecheck. |
+| `LOTICS_UI_SRC=<abs path to packages/ui/src>` (env, not a command) | Dev-link `@lotics/ui` to a monorepo checkout for the length of ONE command, **for every tool at once**. The app's `vite.config.ts` gets its whole `resolve` block from the kit (`resolve: loticsResolve()` — `@lotics/ui/vite`), which reads the variable at call time and adds the `@lotics/ui/*` → working-copy alias, so kit edits go live under `lotics app dev` (HMR) and bundle under `lotics app deploy`. In the same breath, every command that regenerates types (`create`/`pull`/`dev`/`deploy`/`codegen`, all via `writeAppDts`) writes **`.lotics/tsconfig.link.json`** — the matching `paths`, which the app's `tsconfig.json` `extends` — so `tsc`, vitest, eslint and your EDITOR resolve the same copy Vite does. Unset ⇒ every one of them goes back to `node_modules`, and the generated file is rewritten inert. **Why `paths` and not `npm link`:** the kit ships un-built `.tsx`, so a kit file outside `node_modules` resolves its OWN `react`/`react-native` from the monorepo — two copies in one program and every shared type stops matching ("Two different types with this name exist, but they are unrelated"). The generated file therefore also pins every peer @lotics/ui declares to the APP's copy, types-package first (`react` → `@types/react`; pinning the runtime package instead strands tsc on a `.js` with no declarations). The pin set is derived from the installed kit's `peerDependencies`, so it tracks the kit rather than rotting. **Nothing hand-written is touched** — the generated file lives in `.lotics/` (the CLI's own dir) and no config is edited by regex, which is what the deleted `lotics ui link` did when it twice destroyed the load-bearing `react-native` alias along with the array's closing bracket. Identical for a monorepo app and an EXTERNAL one (e.g. `~/lotics_apps`). `app deploy` still warns whenever the variable is set — that the bundle carries kit code from your working copy, or that the app's config predates `loticsResolve()` and never reads it, so the PUBLISHED kit is going out. An app whose `tsconfig.json` already `extends` something else is told rather than rewritten: add `./.lotics/tsconfig.link.json` to the array yourself. |
 | `lotics xlsx <subcmd>` | Local .xlsx read/write/edit using the bundled `@lotics/xlsx` engine (no auth, no network). 14 named subcommands (read, write, set-cell, clear-range, merge, unmerge, add-sheet, delete-sheet, rename-sheet, insert-rows, delete-rows, insert-cols, delete-cols, set-style) + `batch` for applying multiple of the same 14 ops in a single parse/export cycle. `read` also takes `--sheet <name>` (limit output to one sheet — unknown name fails with the available list) and `--range <sheet>!<A1:G60>` (limit to a cell window; the `<sheet>!` prefix is optional when `--sheet` supplies the sheet, a single cell like `S1!B2` is a 1×1 window) to trim a large workbook's JSON — the output shape is unchanged, only the `sheets` array and each sheet's `cells` map are filtered. Atomic in-place write (temp file + rename). |
 | `lotics docx <subcmd>` | Local .docx read/write/edit using the bundled `@lotics/docx` engine (OOXML round-trip surface only — no ProseMirror baggage). Subcommands: read, write, append-paragraph, insert-paragraph, delete-block, replace-text, batch. A legacy `.doc` (Word 97–2003 OLE2 binary) is detected in `loadFile` and routed through `@lotics/ooxml`'s `loadDocxFromBuffer` (which re-emits it as real OOXML) before reading — so `lotics docx read` works on a `.doc`, not just a `.docx`. Opaque blocks (tables, custom XML) preserved verbatim. Atomic in-place write. **`replace-text` matches across run boundaries** — Word splits a run at every formatting change, so a `{{marker}}` routinely lands split — and reads straight THROUGH marks that occupy no place in the sentence (`w:proofErr`, `w:footnoteReference`, endnote/comment refs + ranges, `w:bookmarkStart`/`End`, `w:lastRenderedPageBreak`). `w:proofErr` is the one that decides whether this works in practice — Word brackets every word its dictionary rejects, so on non-English text it lands between nearly every pair of runs. It still refuses to join across anything that occupies space in the text — `w:br`, `w:tab`, `w:sym`, a drawing, or any tag not on that allowlist — because the joined string does not represent the glyph and a match there would rewrite text the caller never saw. The SAME rule applies inside a table cell as outside it — both run one `replaceInParagraph` over paragraphs found at any depth, so a marker split by a line break is refused in both rather than rewritten in the cell and skipped in the body under a success message. Zero matches is always a hard error, never a silent no-op, and when the words ARE on the page the error names the block and the splitting mark (`The text IS present at block 1, split by w:br …`) rather than claiming the text is absent. |
 | `lotics file preview <file\|fil_id> [-o out.png]` | (also `lotics preview`) Render a .docx/.xlsx to a PNG using the SAME engines the frontend FilePreview uses (`@lotics/docx` `loadDocxIntoElement` / `@lotics/xlsx` `drawSpreadsheet`) — so what you see matches an operator. Accepts a **local path** OR a stored **`fil_…` id** (`isStoredFileId` — a bare id, no extension): an id is first downloaded to a temp dir via `downloadFileById` (the `signed_url` presign path — same authority as `lotics file download`), rendered, then the transient source is removed; with no `-o` the PNG lands in cwd under the stored file's base name (`defaultPreviewOutputPath`). Drives a headless Chrome over **CDP with only Node built-ins** (`WebSocket`/`fetch`/`http`/`child_process`) — zero npm deps, the CLI stays a single bundled binary. The browser render logic is a separate esbuild **browser** bundle shipped at `dist/render_page.js` (built by `build_cli.mjs`, excluded from the node `tsgo`), served over a throwaway localhost http server and screenshotted full-page. **Requires a Chrome/Chromium on the machine** — detected from `CHROME_PATH`/`LOTICS_CHROME`, then Playwright's installed chromium, then system paths — inherent to rendering these browser formats; a clear "install a browser" error otherwise. PDFs need no render (open them directly). |

package/package.json

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