@lotics/cli 0.144.0 → 0.146.0

package/dist/src/cli.js

@@ -46405,6 +46405,36 @@ import { LoticsLocaleProvider, vi } from "@lotics/ui/locale";
 import { mount } from "@lotics/app-sdk";
 import App from "./App";
 
+// THIS APP LOOKS LIKE LOTICS unless you say otherwise, which is the right
+// default: the kit's own palette and typeface are what every screen in the
+// product wears, and an app that sets nothing belongs with them.
+//
+// If this app carries someone else's brand \u2014 a customer's typeface, their one
+// colour \u2014 \`applyLoticsTheme\` is the escape hatch. Call it ONCE, here, before
+// \`mount\`, so the variables are in place for the first paint:
+//
+//   import { applyLoticsTheme } from "@lotics/ui/theme";
+//   applyLoticsTheme({ primary: "#0F766E" });
+//
+// It is ADDITIVE \u2014 set what you own and every other role keeps the kit's value,
+// rather than resetting to some second set of defaults:
+//
+//   accent      which of these \u2014 a selected row, an active filter
+//   primary     this is on \u2014 the filled button, a checkbox, an active tab's rail
+//   background  the raised surface (Card, Drawer, Modal); leave white unless you
+//               deliberately want a toned surface
+//   border      hairlines \u2014 a register is mostly these, so a small change here is
+//               felt against the whole screen
+//   bodyFont    the typeface for everything (a CSS stack you know RESOLVES, and
+//               that carries Vietnamese diacritics \u2014 a face without them turns
+//               "Th\u1EA9m \u0111\u1ECBnh" into tofu). Declare its @font-face in your own CSS.
+//   displayFont display type only; defaults to bodyFont
+//
+// Prefer it over declaring \`--lotics-*\` in your own stylesheet: two of those
+// values are DERIVED and fail quietly by hand \u2014 the selection wash is the accent
+// at 7%, and one bodyFont has to reach all three weight rungs or medium and
+// semibold stay in the kit's face and the screen reads as a font that half-loaded.
+//
 // PortalHost is the render target for @lotics/ui overlays (Popover, Tooltip,
 // Dialog). Without it, Portal renders nothing \u2014 keep it wrapping the app.
 //
@@ -71273,6 +71303,9 @@ var memberSchema = zod_default.object({
   ),
   archived: zod_default.boolean().optional().describe(
     "True when this person has been removed from the organization. The membership survives removal so records naming them keep resolving; it grants nothing. Optional because an older server omits it \u2014 absent means active."
+  ),
+  joined_at: zod_default.string().optional().describe(
+    "ISO timestamp of when this membership began. Optional because an older server omits it \u2014 absent means not told, never 'joined at the epoch'."
   )
 });
 var pendingInvitationSchema = zod_default.object({
@@ -72670,6 +72703,44 @@ async function refreshWorkflowTypes(client, projectDir, app_id, alias, declarati
   writeWorkflowFile(projectDir, alias, body, envelope);
   return true;
 }
+function readPriorStamp(projectDir) {
+  const pkgPath2 = path9.join(projectDir, "package.json");
+  if (!fs8.existsSync(pkgPath2)) return null;
+  let pkg2;
+  try {
+    pkg2 = JSON.parse(fs8.readFileSync(pkgPath2, "utf-8"));
+  } catch {
+    return null;
+  }
+  const lotics = pkg2.lotics && typeof pkg2.lotics === "object" ? pkg2.lotics : null;
+  if (!lotics) return null;
+  const id = lotics.current_version_id;
+  const number4 = lotics.version_number;
+  if (typeof id !== "string" || typeof number4 !== "number") return null;
+  return { id, number: number4 };
+}
+function assertProjectIsCurrent(meta3, app) {
+  if (!meta3.current_version_id || !app.current_version_id) return;
+  if (meta3.current_version_id === app.current_version_id) return;
+  throw new Error(
+    `This project is based on an older version of the app.
+    project: ${meta3.current_version_id}
+    served:  ${app.current_version_id}
+  Someone deployed since this copy was pulled, so the server refuses a deploy
+  from here \u2014 and a stale tree compared against the live app reports nothing
+  trustworthy either.
+  Get the served version:  lotics app pull ${meta3.app_id}
+  Local edits you have not deployed are KEPT and listed, never overwritten.`
+  );
+}
+function stampAfterPull(args) {
+  const { prior, pulled, keptCount } = args;
+  if (keptCount === 0 || prior === null || prior.id === pulled.id) {
+    return { ...pulled, held: false };
+  }
+  const older = prior.number < pulled.number ? prior : pulled;
+  return { ...older, held: true };
+}
 function stampPulledManifest(projectDir, args) {
   writeAppMeta(projectDir, {
     app_id: args.app_id,
@@ -72824,6 +72895,7 @@ async function appPull(client, args) {
   const sourceUrl = await client.getAppVersionSourceUrl(app.id, version2.id);
   const targetPath = path9.resolve(args.targetPath ?? defaultPullTarget(app.id, app.name));
   fs8.mkdirSync(targetPath, { recursive: true });
+  const prior = readPriorStamp(targetPath);
   const tmpFile = path9.join(tmpdir(), `lotics-app-${app.id}-${Date.now()}.tar.gz`);
   console.error(`Downloading source archive...`);
   await downloadToFile(sourceUrl, tmpFile);
@@ -72842,6 +72914,11 @@ async function appPull(client, args) {
     if (fs8.existsSync(tmpFile)) fs8.unlinkSync(tmpFile);
     fs8.rmSync(stagingDir, { recursive: true, force: true });
   }
+  const stamp = stampAfterPull({
+    prior,
+    pulled: { id: versionId, number: version2.version },
+    keptCount: keptLocal.length
+  });
   stampPulledManifest(targetPath, {
     app_id: app.id,
     workspace_id: app.workspace_id,
@@ -72849,8 +72926,8 @@ async function appPull(client, args) {
     // after pulling an OLD one would let the next deploy ship that old source as
     // if it were built on the newest — the version guard exists to refuse
     // exactly that, and it can only do so if this tells the truth.
-    current_version_id: versionId,
-    version_number: version2.version,
+    current_version_id: stamp.id,
+    version_number: stamp.number,
     workflows: app.workflows ?? {},
     queries: app.queries ?? {},
     agents: app.agents ?? {}
@@ -72897,7 +72974,14 @@ async function appPull(client, args) {
   }
   console.error(`Installing npm dependencies...`);
   await runNpm(["install"], targetPath);
-  reportKeptLocalFiles(keptLocal, app.id);
+  reportKeptLocalFiles(keptLocal, app.id, {
+    // `prior` is non-null whenever the stamp was held — `stampAfterPull` cannot
+    // hold against nothing — so the fallback only covers the un-held branch,
+    // which never prints it.
+    prior: prior?.number ?? version2.version,
+    pulled: version2.version,
+    heldAt: stamp.held ? stamp.number : null
+  });
   console.error(`
 Ready. Next steps:`);
   console.error(`  cd ${path9.relative(process.cwd(), targetPath) || "."}`);
@@ -72926,6 +73010,7 @@ async function appDeploy(client, args) {
   const meta3 = readAppMeta(projectDir);
   warnAboutDevLink(projectDir, "deploy");
   const liveApp = await client.getApp(meta3.app_id);
+  assertProjectIsCurrent(meta3, liveApp);
   const pending = pendingBindings({
     projectDir,
     meta: meta3,
@@ -73173,6 +73258,7 @@ async function appCheck(client, args = {}) {
   const projectDir = path9.resolve(args.projectDir ?? process.cwd());
   const meta3 = readAppMeta(projectDir);
   const app = await client.getApp(meta3.app_id);
+  assertProjectIsCurrent(meta3, app);
   const sourceText = readAppSourceText(projectDir);
   const called = calledAppAliases(sourceText);
   warnAboutDevLink(projectDir, "deploy");
@@ -73413,18 +73499,37 @@ function copyTree(from, to, opts, relative = "") {
   }
   return kept;
 }
-function reportKeptLocalFiles(kept, appId) {
+function reportKeptLocalFiles(kept, appId, motion) {
   if (kept.length === 0) return;
-  console.error(
-    `
+  const list2 = kept.slice(0, 20).map((f) => `  \u2022 ${f}`).join("\n") + (kept.length > 20 ? `
+  \u2026 and ${kept.length - 20} more` : ``);
+  const header = `
 ${kept.length} local file(s) differ from the app and were KEPT, not overwritten:
-` + kept.slice(0, 20).map((f) => `  \u2022 ${f}`).join("\n") + (kept.length > 20 ? `
-  \u2026 and ${kept.length - 20} more` : ``) + `
+${list2}`;
+  if (motion === null || motion.heldAt === null) {
+    console.error(
+      header + `
 
-  Everything else was refreshed from the app. Your edits are intact.
-  Ship them:            lotics app deploy      (pushes bodies, prompts and declarations)
-  See the difference:   lotics app check
+  Everything else was refreshed from the app. Your edits are intact` + (motion === null ? `.
+` : `, and
+  this project was already on v${motion.pulled} \u2014 so these are your work, ahead of the app.
+`) + `  Ship them:            lotics app deploy      (pushes bodies, prompts and declarations)
   Take the app's copy:  lotics app pull ${appId} --force   (DISCARDS the files above)`
+    );
+    return;
+  }
+  console.error(
+    header + `
+
+  \u26A0 This tree now mixes v${motion.prior}, which it was on, and v${motion.pulled}, which was pulled.
+  The files above were NOT replaced, so the kept ones may be your unshipped
+  work OR simply the other version. Nothing here can tell those apart \u2014
+  both merely "differ from the archive".
+
+  The version stamp was left at v${motion.heldAt} so a deploy from this tree is
+  REFUSED rather than shipping a half-and-half bundle. To move on, pick one:
+  Take the app's copy:  lotics app pull ${appId} --force   (DISCARDS the files above)
+  Keep yours:           reconcile the files above by hand, then re-run this pull`
   );
 }
 function warnIfDynamicAliases(called) {
@@ -74045,7 +74150,7 @@ async function appWorkflowPull(client, args = {}) {
   console.error(
     `Wrote ${written.length} workflow ${written.length === 1 ? "body" : "bodies"} to ${WORKFLOWS_DIR}/` + (written.length > 0 ? ` (${written.join(", ")})` : "")
   );
-  reportKeptLocalFiles(kept, meta3.app_id);
+  reportKeptLocalFiles(kept, meta3.app_id, null);
   ensureAppTsconfig(projectDir);
 }
 async function appWorkflowCheck(args) {

package/docs/cli_reference.md

@@ -29,7 +29,7 @@ Per-command syntax, flags, contracts, and gotchas for the public `lotics` CLI. S
 | `lotics knowledge update <id> [--from <file.md> \| --content <str>] [--name <n>] [--description <d>]` | Call `update_knowledge` with **only** the provided fields (a body from --from/--content becomes `content`; the tool diffs + CASes the content change internally, so the CLI passes no `expected_content_file_id`). At least one field required; --from and --content are mutually exclusive. |
 | `lotics knowledge rm <id>` | Archive the doc via `delete_knowledge` (`{ knowledge_doc_id }`). The REST execute path does not gate `needsApproval`, so this runs unattended. |
 | `lotics app create <name> [path]` | Scaffold a Vite+React+TS custom-code app project; POST /v1/apps; npm install; vite build; upload as v1 |
-| `lotics app pull <app_id> [path]` | Download source archive from R2 (presigned), extract, npm install, stamp package.json's `lotics` field. With no `[path]`: refresh the cwd IN PLACE when it's already this app's own project (its manifest `app_id` matches — the documented `cd <app> && lotics app pull` flow), else clone into an `<name>/` subdir. **A pull never overwrites a file that differs from what it is about to write** — it writes only what is ABSENT or already identical, keeps the rest, and reports which files it kept plus the commands that close the gap. The same rule covers `src/workflows/<alias>.ts` and `src/agents/<alias>.md`, so an unpushed body or prompt survives too. Those two are written from the LIVE App row (`apps.workflows` / `apps.agents`), which owns them, and the archive's own copy of them is deliberately SKIPPED on extract: a deploy tars the whole source directory, so the tarball holds a deploy-time snapshot that is stale for anything authored since. The comparison is against the app's own content, not git, so it holds for a project that was never a repo. `--force` takes the app's copy and DISCARDS local edits; there is no other way to lose them. **`--from-version <apv_…>`** pulls an OLDER revision instead of the current one (`lotics app versions` lists the ids) — point it at a NEW path to read a previous revision without disturbing the project you are in. The manifest records the version actually written, never the live pointer, so a deploy from that checkout is refused by the version guard rather than shipping old source over newer. — `workflows` and `agents` are sourced from the live App row (NOT the archived manifest), so `set_app_workflow` / `set_app_agent` authoring survives the pull. Regenerates `.lotics/app_{workflows,queries,agents}.d.ts` so `useWorkflow` / `useQuery` / `useAgentRun` stay typed, AND the runtime `.lotics/app_fields.ts` (the same linked-vs-bespoke branch `app codegen` runs, off the app row already fetched — see that row for the two forms). That one is not optional: `app deploy` tars source with `--exclude=.lotics`, so no archive can carry it, and a pulled project whose `src/` imports `F`/`OPT` would fail to build with `Could not resolve "../../.lotics/app_fields"` until `app codegen` was run by hand. The write NAMES the form and the reason, because an in-place pull can FLIP a project between them (`opctl app publish` links an origin, `package eject` unlinks it) and that changes what the module does at load. Skipped under `--view-as` (the schema is read as that member and silently drops tables they cannot see — a narrowed `F` map compiles and then throws at runtime, worse than the missing module). A binding/schema fetch failure is non-fatal and names the right recovery for what is on disk: an existing file is kept, an ABSENT one warns about the build error and points at `app codegen`. Pull GENERATES but never RECONCILES `.lotics/` — deleting a companion whose alias the manifest no longer declares is `app codegen`'s alone, since pull's authority is the server's alias set and a declared-but-not-yet-`set` alias is supported. Also writes one `src/workflows/<alias>.ts` per bound workflow (faithful body from `get_app_workflow`) and one `src/agents/<alias>.md` per bound agent (its instructions, straight off the live row) — so the prose an author actually edits lives in a file, and pull always overwrites it from live, leaving no second copy to drift. A legacy workflow alias with no rendered source, or an agent with no instructions, warns and is skipped. The stamped `lotics.agents` map carries the TYPED half only (`inputs`/`outputs`/`tool_names`/`model_tier`/…) — an agent's prose lives solely in its `.md`, so there is never a second local copy to desync; a stale `instructions` left by an older CLI is inert and disappears on the next pull |
+| `lotics app 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. **A pull never overwrites a file that differs from what it is about to write** — it writes only what is ABSENT or already identical, keeps the rest, and reports which files it kept plus the commands that close the gap. The same rule covers `src/workflows/<alias>.ts` and `src/agents/<alias>.md`, so an unpushed body or prompt survives too. Those two are written from the LIVE App row (`apps.workflows` / `apps.agents`), which owns them, and the archive's own copy of them is deliberately SKIPPED on extract: a deploy tars the whole source directory, so the tarball holds a deploy-time snapshot that is stale for anything authored since. The comparison is against the app's own content, not git, so it holds for a project that was never a repo. `--force` takes the app's copy and DISCARDS local edits; there is no other way to lose them. **When a pull ACROSS versions keeps files, the manifest is left on the OLDER of the two versions** — the tree is then part one and part the other, and claiming the newer would make `deploy`'s `prev_version_id` check pass and ship a half-and-half bundle. Older, not "the one it had": `--from-version` pulls a deliberately old revision, so the version it had is the NEWER side, and holding that would match what the server serves and let the old source ship. Either way a deploy from that tree is refused until you reconcile the listed files by hand and pull again, or take the app's copy with `--force`. The report says which version each side is on, because a kept file is your unshipped work when the project was already current and merely the OLD version when it was behind — and nothing in a byte comparison can tell those apart. **`--from-version <apv_…>`** pulls an OLDER revision instead of the current one (`lotics app versions` lists the ids) — point it at a NEW path to read a previous revision without disturbing the project you are in. The manifest records the version actually written, never the live pointer, so a deploy from that checkout is refused by the version guard rather than shipping old source over newer. — `workflows` and `agents` are sourced from the live App row (NOT the archived manifest), so `set_app_workflow` / `set_app_agent` authoring survives the pull. Regenerates `.lotics/app_{workflows,queries,agents}.d.ts` so `useWorkflow` / `useQuery` / `useAgentRun` stay typed, AND the runtime `.lotics/app_fields.ts` (the same linked-vs-bespoke branch `app codegen` runs, off the app row already fetched — see that row for the two forms). That one is not optional: `app deploy` tars source with `--exclude=.lotics`, so no archive can carry it, and a pulled project whose `src/` imports `F`/`OPT` would fail to build with `Could not resolve "../../.lotics/app_fields"` until `app codegen` was run by hand. The write NAMES the form and the reason, because an in-place pull can FLIP a project between them (`opctl app publish` links an origin, `package eject` unlinks it) and that changes what the module does at load. Skipped under `--view-as` (the schema is read as that member and silently drops tables they cannot see — a narrowed `F` map compiles and then throws at runtime, worse than the missing module). A binding/schema fetch failure is non-fatal and names the right recovery for what is on disk: an existing file is kept, an ABSENT one warns about the build error and points at `app codegen`. Pull GENERATES but never RECONCILES `.lotics/` — deleting a companion whose alias the manifest no longer declares is `app codegen`'s alone, since pull's authority is the server's alias set and a declared-but-not-yet-`set` alias is supported. Also writes one `src/workflows/<alias>.ts` per bound workflow (faithful body from `get_app_workflow`) and one `src/agents/<alias>.md` per bound agent (its instructions, straight off the live row) — so the prose an author actually edits lives in a file, and pull always overwrites it from live, leaving no second copy to drift. A legacy workflow alias with no rendered source, or an agent with no instructions, warns and is skipped. The stamped `lotics.agents` map carries the TYPED half only (`inputs`/`outputs`/`tool_names`/`model_tier`/…) — an agent's prose lives solely in its `.md`, so there is never a second local copy to desync; a stale `instructions` left by an older CLI is inert and disappears on the next pull |
 | `lotics app deploy [--prune] -m <message>` | `-m` is OPTIONAL — omitted, the deploy derives the version message from what it actually pushed; pass `-m` when you have a reason worth recording. npm run build; tar source + dist; POST /v1/apps/{id}/versions multipart. **One command ships everything**: before the bundle moves, a deploy pushes every binding the project has ahead of the app — an edited workflow body or declaration, edited agent prose, a changed query — through `set_app_query`, then `set_app_workflow`, then `set_app_agent`, and fails the release if any push is refused. That order is required: an agent declares the query and workflow aliases it may call, so pushing it before its own new query is refused. A workflow's `description` is part of that push and is compared against the recorded baseline, not the live app — it lives on the workflow ROW, which `getApp` does not carry. It never AUTHORS a binding itself — those verbs stay the single writers — and each push carries the fingerprint the project last saw live (`lotics.synced`), so a stale checkout is refused rather than overwriting another author's edit. `package.json` means the same thing for both artifacts: editing `lotics.agents.<alias>.inputs`/`outputs` is pushed exactly like the workflow equivalent (only those two fields — `set_app_agent` merges, so everything the manifest does not model is left untouched). It also regenerates `.lotics/app_fields.ts` before building, since the build INLINES it and which form is correct follows from whether the app is a package installation — a deploy that skipped it could ship an origin's baked ids into every other install. `lotics app check` reports the same set without pushing; neither has a `--strict`. What the version RECORDS as the aliases it calls — the set `remove_app_workflow` / `remove_app_query` / `remove_app_agent` consult to refuse unbinding one the served version still reaches — is read by the SERVER out of the source archive this deploy uploads, not reported by the deploy. That matters because the deploy is also what unbinds: a client supplying the evidence used to refuse its own removal cannot be checked by it. After a successful deploy it warns about any alias the source CALLS that is NOT bound, and **names the inverse** — bindings the app still serves that this bundle mentions nowhere. It does NOT remove them: **`--prune` does, and only when passed.** A static scan sees the bundle's call sites and an agent's `query_aliases`/`workflow_aliases`; it cannot see `lotics app workflow run <alias>`, whose whole contract is that the alias is bound server-side, or chat's `run_app_workflow` under `app:use`. An operator-driven workflow therefore leaves no call site anywhere in the source and is indistinguishable from a dead one here — so a deploy that pruned by default deleted working tooling and printed it as a ✓. Pruning runs AFTER the version is live, because the removal tools refuse an alias the SERVED version still declares — so doing it first is refused by the guard that makes it safe. `--prune` is skipped ENTIRELY (with a warning, never a failure) when the source computes an alias at run time, since the scan cannot tell which binding that reaches and pruning "the rest" would be guessing with a deletion. Each removal prints the command that RESTORES it (`lotics app query set <alias>` / `app workflow set` / `app agent set`) on the same line as the ✓, because the act was always reversible and only ever failed to say so. A binding that will not unbind is reported and does NOT fail the release: the version is live and correct — and the server refuses to unbind a WORKFLOW this workspace has actually run (a recorded execution means a caller the source cannot name), which surfaces here as `✗ could not unbind …` with the date it last ran. |
 | `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. 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: 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). 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. 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. The write is surgical and order-preserving, 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`. |
@@ -37,7 +37,7 @@ Per-command syntax, flags, contracts, and gotchas for the public `lotics` CLI. S
 | `lotics upgrade` | Take the installed package's next version for the app in this directory (`app_id` from the local manifest — and the WORKSPACE from the same manifest, exactly as `lotics app *` does, so the command that knows which workspace it belongs to never rides the ambient profile). Announces its target on stderr before acting. **Applies the version it PREVIEWED**, not "latest" re-resolved server-side, so a release landing mid-command cannot install a contract whose diff was never checked. **Previews first and applies only a CLEAN upgrade**: a breaking contract change, a locally modified artifact, binding drift, or bundled knowledge needing consent (all FOUR sources the preview returns) is reported per item and REFUSED with exit 1, because each resolves by choosing what to keep and a guess discards work nobody asked to lose. Already-current is a no-op that says so. On success it names the new version and the changelog, and points at `lotics app pull` to bring the checkout in step. The resolutions flow for a conflicted upgrade stays in `opctl` — that case needs a person, and the person is an operator. |
 | `lotics docs` \| `lotics docs <area>` | The index of the reference docs, **resolved out of the packages installed beside this project** — never carried by this CLI. **Both levels are discovered by looking**: every `@lotics/*` package carrying an `AGENTS.md` or a `docs/` in any `node_modules/@lotics` from the current directory UPWARD (nearest wins, so a hoisted root copy never shadows the one a project's own imports resolve to), and within each, every area it actually ships. Titles come from each file's own `# heading` and the version from the installed `package.json`, so a doc OR a whole package added upstream appears with no change to this CLI, and a skewed install is visible rather than reassuring. A package's index is named after the package (`lotics docs ui`), never `index`. `@lotics/app-sdk`, `@lotics/ui` and `@lotics/cli` sort first as a reading ORDER, not a filter. Both the index and `<area>` print to **stdout** — the index is the payload of a bare `lotics docs`, so `lotics docs | grep -i excel` works — with only the provenance line on stderr, so `lotics docs ai > ai.md` is the doc alone; a name two packages share is refused with both qualified forms (`lotics docs ui/templates`) rather than resolved silently. Needs no auth. Outside a project only `@lotics/cli`'s own resolve, and it says so. |
 | `lotics report '<json>'` \| `lotics report @report.json` | File a report with the Lotics team about what got in your way. **Covers the classes telemetry structurally cannot see**: a capability that does not exist (no command ran, so nothing was recorded), a command that exited 0 having done the wrong thing, an error whose message did not name the remedy, and anything that made authoring slower than it should be. **A frame, not a paragraph** — `{goal, actual, expected?, tried?, wanted?}`, `goal` and `actual` required, unknown keys dropped rather than refused. **No severity or category.** Ingest is inline JSON, `@file`, or `-` for stdin. A bare sentence is refused with the frame printed beside it, so the fix is one step; a bare invocation prints the frame BEFORE asking for a credential, since someone whose key will not resolve is exactly who has something to report. **Not spooled**: unlike telemetry it posts inline, prints whether it landed, and exits non-zero if it did not, echoing the report back so a failed send never loses it. Runs regardless of `LOTICS_TELEMETRY` — invoking it IS the consent that passive collection needs an opt-in for — but with telemetry off there are no recorded commands to attach, and it says so rather than implying context it does not have. Requires auth. Never paste records, file contents, or credentials. |
-| `lotics app check` | Every pre-flight `deploy` runs, WITHOUT building or shipping: the manifest's agent schemas against the live app row, every binding a deploy would push, aliases the source calls that nothing bound (queries, workflows AND agents), bindings the app serves that the source names nowhere, capability-gated SDK calls the manifest doesn't declare, a missing icon/theme, a missing app `description` (it heads the capability catalog the chat agent reads every turn, and its absence has no other symptom), a `vite.config.ts` that never defines `global`/`__DEV__` and a `window.open` in the app's own source (both fail ONLY in the deployed app — dev bundles with esbuild and production with rollup, so typecheck, lint, build and `app dev` are all green while react-native-web reads `global.cancelAnimationFrame` as a free variable and the sandboxed iframe drops a popup silently), an agent holding `run_app_query`/`run_app_workflow` with an EMPTY `query_aliases`/`workflow_aliases` (the tool is the capability, the alias list is the reach — empty means every call it makes is refused while the run still COMPLETES, so it surfaces as a model ignoring its prompt; read off the live row, never the manifest, which mirrors those fields but is pushed by no verb), and a notice for any alias the source computes at runtime (invisible to every check here and to `--prune`'s unbind guard). Adds no rule of its own — each finding is the same helper `deploy` calls, so a green check means a deploy will not complain. **Exits 1 on what a `deploy` would REFUSE or PUSH** — an agent schema that disagrees with the live app, and any binding the project has ahead of the app (an edited workflow body or declaration, edited agent prose, a changed query). Both are things a deploy would act on, so CI gating on a green check means a deploy has nothing left to do; genuine advisories (capabilities, branding, a runtime-computed alias, orphaned bindings) stay advisory and never fail it. |
+| `lotics app check` | Every pre-flight `deploy` runs, WITHOUT building or shipping. **First, whether this project is even based on the served version** — the one thing a deploy REFUSES outright rather than pushing (the server 409s a stale `prev_version_id`), and the one finding that invalidates every other: a stale tree and the live app are two different apps, so comparing them reports nothing trustworthy. Stale exits 1 naming both versions and stops before the rest; a project with no stamp at all — or an app with no version yet — is a first deploy, not a conflict. `deploy` runs the SAME assertion off the app row it already fetched, so a stale tree fails before it pushes a binding or builds, instead of after the upload arrives and the server 409s. Then: the manifest's agent schemas against the live app row, every binding a deploy would push, aliases the source calls that nothing bound (queries, workflows AND agents), bindings the app serves that the source names nowhere, capability-gated SDK calls the manifest doesn't declare, a missing icon/theme, a missing app `description` (it heads the capability catalog the chat agent reads every turn, and its absence has no other symptom), a `vite.config.ts` that never defines `global`/`__DEV__` and a `window.open` in the app's own source (both fail ONLY in the deployed app — dev bundles with esbuild and production with rollup, so typecheck, lint, build and `app dev` are all green while react-native-web reads `global.cancelAnimationFrame` as a free variable and the sandboxed iframe drops a popup silently), an agent holding `run_app_query`/`run_app_workflow` with an EMPTY `query_aliases`/`workflow_aliases` (the tool is the capability, the alias list is the reach — empty means every call it makes is refused while the run still COMPLETES, so it surfaces as a model ignoring its prompt; read off the live row, never the manifest, which mirrors those fields but is pushed by no verb), and a notice for any alias the source computes at runtime (invisible to every check here and to `--prune`'s unbind guard). Adds no rule of its own — each finding is the same helper `deploy` calls, so a green check means a deploy will not complain. **Exits 1 on what a `deploy` would REFUSE or PUSH** — an agent schema that disagrees with the live app, and any binding the project has ahead of the app (an edited workflow body or declaration, edited agent prose, a changed query). Both are things a deploy would act on, so CI gating on a green check means a deploy has nothing left to do; genuine advisories (capabilities, branding, a runtime-computed alias, orphaned bindings) stay advisory and never fail it. |
 | `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 `src/agents/<alias>.md` — plus `inputs`/`outputs` when `package.json#lotics.agents.<alias>` declares them — through `set_app_agent`. The agent mirror of `app workflow set`, and the deploy-free authoring path for an agent's prose and its typed edges. **It sends only those fields.** Everything else is absent, and absent means unchanged, so a declaration this CLI does not model cannot be reverted by a push from a checkout that predates it — the chat authoring agent's `knowledge_doc_ids`, another operator's `query_aliases` grant. To change one of those, call `set_app_agent` with just that field (`lotics run set_app_agent '{"app_id":…,"alias":…,"tool_names":[…]}'` — it merges), then `app pull` to bring the manifest back in step. **CREATES the alias when the app has not bound one yet**, so a new agent is authored the same way a new workflow is: write the prose, declare the typed half, push. A create needs the prose file (an agent without instructions is not an agent); it is gated on nothing else, because what keeps a binding alive is a `useAppAgentRun("<alias>")` call site in the shipped bundle — a deploy prunes an agent the bundle never names, manifest entry or not. The prose push is a conditional write against the fingerprint this project last saw, so it is refused rather than allowed to overwrite prose someone else changed. Clear error + non-zero exit when there is no prose file and nothing declared to push instead, when a create has no prose to create from, or when the file is empty once the header is stripped. |

package/package.json

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