@lotics/cli 0.101.0 → 0.102.0

package/dist/render_page.js

@@ -28695,6 +28695,73 @@ ${e.toString()}`);
       offsetYEmu
     };
   }
+  var EMU_PER_PT = 12700;
+  var VML_UNIT_TO_EMU = {
+    pt: EMU_PER_PT,
+    in: EMU_PER_PT * 72,
+    cm: EMU_PER_PT * 72 / 2.54,
+    mm: EMU_PER_PT * 72 / 25.4,
+    pc: EMU_PER_PT * 12,
+    px: EMU_PER_PT * 72 / 96
+  };
+  function readVmlLength(style, property) {
+    const match = new RegExp(`(?:^|;)\\s*${property}\\s*:\\s*([0-9.]+)([a-z]*)`, "i").exec(style);
+    if (!match) return null;
+    const value = Number.parseFloat(match[1]);
+    if (!Number.isFinite(value)) return null;
+    const unit = match[2].toLowerCase();
+    const perUnit = unit === "" ? EMU_PER_PT : VML_UNIT_TO_EMU[unit];
+    if (perUnit === void 0) return null;
+    return Math.round(value * perUnit);
+  }
+  function parsePict(pictXml) {
+    if (getTagName(pictXml) !== "w:pict") return null;
+    const imagedata = findFirstByTag(pictXml, "v:imagedata");
+    if (!imagedata) return null;
+    const relationshipId = getAttr(imagedata, "r:id") ?? getAttr(imagedata, "r:embed") ?? null;
+    if (relationshipId === null) return null;
+    const shape = findFirstByTag(pictXml, "v:shape") ?? findFirstByTag(pictXml, "v:rect");
+    const style = shape ? getAttr(shape, "style") ?? "" : "";
+    return {
+      relationshipId,
+      widthEmu: readVmlLength(style, "width"),
+      heightEmu: readVmlLength(style, "height"),
+      alt: (shape ? getAttr(shape, "alt") : void 0) ?? "",
+      // VML positioning is a CSS-ish `style`, not the wp: anchor vocabulary the
+      // anchor fields describe. Reporting it as inline keeps the renderer from
+      // acting on offsets that were never read.
+      inline: true,
+      wrap: null,
+      floatSide: null,
+      behindDoc: false,
+      offsetXEmu: null,
+      offsetYEmu: null
+    };
+  }
+  function parseAlternateContent(el) {
+    if (getTagName(el) !== "mc:AlternateContent") return null;
+    const branches = getChildren(el).filter((child) => {
+      const tag = getTagName(child);
+      return tag === "mc:Choice" || tag === "mc:Fallback";
+    });
+    const ordered = [
+      ...branches.filter((b) => getTagName(b) === "mc:Choice"),
+      ...branches.filter((b) => getTagName(b) === "mc:Fallback")
+    ];
+    for (const branch of ordered) {
+      const drawing = findFirstByTag(branch, "w:drawing");
+      if (drawing) {
+        const info = parseDrawing(drawing);
+        if (info && info.relationshipId !== null) return info;
+      }
+      const pict = findFirstByTag(branch, "w:pict");
+      if (pict) {
+        const info = parsePict(pict);
+        if (info) return info;
+      }
+    }
+    return null;
+  }
   function readPosOffset(containerEl, positionTag) {
     const position = findFirstByTag(containerEl, positionTag);
     if (!position) return null;
@@ -42936,6 +43003,24 @@ ${e.toString()}`);
       }
     };
   }
+  function imageNode(info, originalXml, marks) {
+    return docxSchema.nodes.image_inline.create(
+      {
+        relationshipId: info.relationshipId,
+        widthEmu: info.widthEmu,
+        heightEmu: info.heightEmu,
+        alt: info.alt,
+        originalXml,
+        wrap: info.wrap,
+        floatSide: info.floatSide,
+        behindDoc: info.behindDoc,
+        offsetXEmu: info.offsetXEmu,
+        offsetYEmu: info.offsetYEmu
+      },
+      void 0,
+      marks
+    );
+  }
   function convertRunChild(child, marks, state) {
     if (child.kind === "text") {
       if (child.value.length === 0) return [];
@@ -42963,26 +43048,15 @@ ${e.toString()}`);
     }
     if (tag === "w:drawing") {
       const info = parseDrawing(child.xml);
-      if (info) {
-        return [
-          docxSchema.nodes.image_inline.create(
-            {
-              relationshipId: info.relationshipId,
-              widthEmu: info.widthEmu,
-              heightEmu: info.heightEmu,
-              alt: info.alt,
-              originalXml: child.xml,
-              wrap: info.wrap,
-              floatSide: info.floatSide,
-              behindDoc: info.behindDoc,
-              offsetXEmu: info.offsetXEmu,
-              offsetYEmu: info.offsetYEmu
-            },
-            void 0,
-            marks
-          )
-        ];
-      }
+      if (info) return [imageNode(info, child.xml, marks)];
+    }
+    if (tag === "mc:AlternateContent") {
+      const info = parseAlternateContent(child.xml);
+      if (info) return [imageNode(info, child.xml, marks)];
+    }
+    if (tag === "w:pict") {
+      const info = parsePict(child.xml);
+      if (info) return [imageNode(info, child.xml, marks)];
     }
     return [
       docxSchema.nodes.opaque_inline.create({ xml: child.xml }, void 0, marks)

package/dist/src/cli.js

@@ -44955,6 +44955,7 @@ var LoticsClient = class {
       formData.append("capabilities", JSON.stringify(args.capabilities));
     }
     formData.append("workflow_aliases", JSON.stringify(args.workflow_aliases ?? []));
+    formData.append("query_aliases", JSON.stringify(args.query_aliases ?? []));
     const url2 = `${this.baseUrl}/v1/apps/${encodeURIComponent(args.app_id)}/versions`;
     const response = await fetch(url2, {
       method: "POST",
@@ -64945,18 +64946,25 @@ var appWorkflowDeclarationSchema = zod_default.object({
   ).refine(
     (outputs) => outputs === void 0 || Object.values(outputs).every((o) => appWorkflowOutputDepth(o) <= MAX_APP_WORKFLOW_OUTPUT_DEPTH),
     { message: `output schema nesting exceeds the max depth of ${MAX_APP_WORKFLOW_OUTPUT_DEPTH}` }
+  ),
+  description: zod_default.string().optional().describe(
+    "What this workflow does, in one line \u2014 read by an agent choosing between the app's aliases, the same job a query's `description` does. `lotics app workflow set` sends it, so it lives beside the body in version control; omitted, the workflow keeps the description already on it."
   )
 });
 var appWorkflowContractSchema = zod_default.object({
   inputs: zod_default.record(zod_default.string(), appWorkflowInputSchema).optional(),
   outputs: zod_default.record(zod_default.string(), appWorkflowOutputSchema).optional()
 });
+var MAX_APP_CAPABILITY_DESCRIPTION = 300;
 var appQueryDeclarationSchema = zod_default.object({
   ast: zod_default.unknown().describe(
     "Query AST template (a QueryNode). Validated server-side via parseQueryNode at deploy. May embed {{params.<name>}} tokens in filter value positions."
   ),
   params: zod_default.record(zod_default.string(), appWorkflowInputSchema).optional().describe(
     "Typed param schema. Keys are param names referenced as {{params.<name>}} in the ast; values declare type + constraints. The server validates the caller's params payload against this before interpolating. Omit for queries that take no params."
+  ),
+  description: zod_default.string().optional().describe(
+    `What this query returns, in one line \u2014 read by an agent choosing between the app's aliases. An alias is a JS identifier, which names a query without saying what it covers. Capped at ${MAX_APP_CAPABILITY_DESCRIPTION} characters.`
   )
 });
 var appAgentDeclarationSchema = zod_default.object({
@@ -70243,7 +70251,10 @@ function writeAgentFiles(projectDir, agents) {
   }
   return written;
 }
-async function writeWorkflowFiles(client, projectDir, app_id, workflows) {
+function generatedWorkflowDescription(appName, alias) {
+  return `Workflow invoked by app "${appName}" via useWorkflow("${alias}").`;
+}
+async function writeWorkflowFiles(client, projectDir, app_id, appName, workflows) {
   const written = [];
   for (const [alias, declaration] of Object.entries(workflows)) {
     const res = await client.getAppWorkflow(app_id, alias);
@@ -70267,10 +70278,27 @@ async function writeWorkflowFiles(client, projectDir, app_id, workflows) {
       toWorkflowDtsDeclaration(declaration)
     );
     writeWorkflowFile(projectDir, alias, source, envelope);
+    const rowDescription = res.result.description;
+    if (typeof rowDescription === "string" && rowDescription !== "" && // Skip the server's GENERATED default. It is what an undescribed alias
+    // carries, so writing it back would commit a line of noise per workflow
+    // into every app that never authored one — and the manifest would then
+    // push it back, entrenching it. Matched by reconstruction, not by
+    // sniffing the wording, so it can only ever skip the exact default.
+    rowDescription !== generatedWorkflowDescription(appName, alias)) {
+      writeWorkflowDescription(projectDir, alias, rowDescription);
+    }
     written.push(alias);
   }
   return written;
 }
+function writeWorkflowDescription(projectDir, alias, description) {
+  const pkgPath2 = path5.join(projectDir, "package.json");
+  const pkg2 = JSON.parse(fs4.readFileSync(pkgPath2, "utf-8"));
+  const declaration = pkg2.lotics?.workflows?.[alias];
+  if (!declaration) return;
+  declaration.description = description;
+  fs4.writeFileSync(pkgPath2, JSON.stringify(pkg2, null, 2) + "\n");
+}
 async function fetchWorkflowGlobals(client, projectDir, app_id, alias, declaration) {
   try {
     const { dts, envelope_prefix, envelope_suffix } = await fetchWorkflowDts(
@@ -70712,7 +70740,7 @@ async function appPull(client, args) {
   });
   const workflows = app.workflows ?? {};
   if (Object.keys(workflows).length > 0) {
-    const written = await writeWorkflowFiles(client, targetPath, app.id, workflows);
+    const written = await writeWorkflowFiles(client, targetPath, app.id, app.name, workflows);
     if (written.length > 0) {
       console.error(
         `Wrote ${written.length} workflow ${written.length === 1 ? "body" : "bodies"} to ${WORKFLOWS_DIR}/ (${written.join(", ")})`
@@ -70822,7 +70850,8 @@ async function appDeploy(client, args) {
         // typing artifact maintained by habit, so its keys answered this question
         // with whatever the author last remembered to write. Stop calling an
         // alias + redeploy to lift the guard before removing its binding.
-        workflow_aliases: called.workflows
+        workflow_aliases: called.workflows,
+        query_aliases: called.queries
       });
       writeAppMeta(projectDir, {
         ...meta3,
@@ -71189,7 +71218,15 @@ async function appWorkflowSet(client, args) {
   const res = await client.setAppWorkflow(meta3.app_id, args.alias, {
     source,
     inputs: declaration.inputs,
-    outputs: declaration.outputs
+    outputs: declaration.outputs,
+    // What an agent reads when choosing between this app's workflows. Carried
+    // from the manifest, alongside `inputs`, so it lives in version control
+    // beside the body and rides every push — the CLI sent no description at
+    // all, which is why a CLI-authored app's aliases all rendered the generated
+    // `Workflow invoked by app "X" via useWorkflow("y")`. Absent leaves
+    // whatever is on the row, so this can never blank a description set
+    // elsewhere.
+    description: declaration.description
   });
   if (res.error) {
     console.error(`Failed to set workflow "${args.alias}": ${res.error}`);
@@ -71252,7 +71289,7 @@ async function appWorkflowPull(client) {
     console.error(`App ${meta3.app_id} has no bound workflows.`);
     return;
   }
-  const written = await writeWorkflowFiles(client, projectDir, meta3.app_id, workflows);
+  const written = await writeWorkflowFiles(client, projectDir, meta3.app_id, app.name, workflows);
   console.error(
     `Wrote ${written.length} workflow ${written.length === 1 ? "body" : "bodies"} to ${WORKFLOWS_DIR}/` + (written.length > 0 ? ` (${written.join(", ")})` : "")
   );
@@ -71373,7 +71410,14 @@ function appUiLink(args) {
       console.error("No @lotics/ui dev-link alias present \u2014 nothing to remove.");
       return;
     }
-    const stripped = source.replace(new RegExp(`^\\s*\\{ find: ${escapeRegExp(UI_ALIAS_FIND_SOURCE)}.*$\\n?`, "m"), "");
+    const stripped = source.replace(
+      new RegExp(
+        `\\n?[ \\t]*\\{ find: ${escapeRegExp(UI_ALIAS_FIND_SOURCE)}, ` + // The replacement is a JSON-encoded path, so it cannot contain an
+        // unescaped quote — bounded, rather than greedy to end of line.
+        String.raw`replacement: "(?:[^"\\]|\\.)*" \},`
+      ),
+      ""
+    );
     fs4.writeFileSync(viteConfigPath, stripped);
     console.error(`Removed the @lotics/ui dev-link alias from ${viteConfigPath}.`);
     console.error("Restart `lotics app dev` and rm -rf node_modules/.vite to clear cached modules.");
@@ -89648,37 +89692,47 @@ function extractParagraphText(el) {
   }
   return parts.join("");
 }
-function getRunsFromParagraph(el) {
-  const runs = [];
+function getParagraphTextSegments(el) {
+  const segments = [];
   for (const child of getChildren(el)) {
     if (getTagName(child) !== "w:r") continue;
-    let text = "";
-    let hasText = false;
+    let pending = [];
+    const flush = () => {
+      if (pending.length === 0) return;
+      const text = pending.map(
+        (node) => getChildren(node).reduce(
+          (acc, tn) => typeof tn["#text"] === "string" ? acc + tn["#text"] : acc,
+          ""
+        )
+      ).join("");
+      segments.push({ element: child, textNodes: pending, text });
+      pending = [];
+    };
     for (const grandchild of getChildren(child)) {
-      if (getTagName(grandchild) !== "w:t") continue;
-      hasText = true;
-      for (const tn of getChildren(grandchild)) {
-        if (typeof tn["#text"] === "string") text += tn["#text"];
+      if (getTagName(grandchild) === "w:t") {
+        pending.push(grandchild);
+        continue;
       }
+      flush();
     }
-    if (hasText) runs.push({ element: child, text });
+    flush();
   }
-  return runs;
+  return segments;
 }
-function writeRunText(runElement, newText) {
-  const children = getChildren(runElement);
-  const textNode = { "w:t": [{ "#text": newText }], ":@": { "@_xml:space": "preserve" } };
-  const indices = children.flatMap((c, i2) => getTagName(c) === "w:t" ? [i2] : []);
-  if (indices.length === 0) {
-    children.push(textNode);
-    return;
+function setSegmentText(segment, newText) {
+  const children = getChildren(segment.element);
+  const textNode = {
+    "w:t": [{ "#text": newText }],
+    ":@": { "@_xml:space": "preserve" }
+  };
+  const head = children.indexOf(segment.textNodes[0]);
+  children[head] = textNode;
+  for (let i2 = segment.textNodes.length - 1; i2 >= 1; i2--) {
+    const at2 = children.indexOf(segment.textNodes[i2]);
+    if (at2 >= 0) children.splice(at2, 1);
   }
-  children[indices[0]] = textNode;
-  for (let i2 = indices.length - 1; i2 >= 1; i2--) children.splice(indices[i2], 1);
-}
-function setRunText(run, newText) {
-  writeRunText(run.element, newText);
-  run.text = newText;
+  segment.textNodes = [textNode];
+  segment.text = newText;
 }
 function computeReplacementRanges(text, query, replacement, matchType, maxReplacements, startCount) {
   const ranges = [];
@@ -89713,39 +89767,39 @@ function computeReplacementRanges(text, query, replacement, matchType, maxReplac
   }
   return { ranges, count };
 }
-function applyRangeReplacements(runs, ranges) {
+function applyRangeReplacements(segments, ranges) {
   if (ranges.length === 0) return;
   const bounds = [];
   let offset = 0;
-  for (const run of runs) {
-    bounds.push({ run, start: offset, end: offset + run.text.length });
-    offset += run.text.length;
+  for (const segment of segments) {
+    bounds.push({ segment, start: offset, end: offset + segment.text.length });
+    offset += segment.text.length;
   }
-  const joined = runs.map((r) => r.text).join("");
+  const joined = segments.map((s) => s.text).join("");
   const sorted = [...ranges].sort((a, b) => a.start - b.start);
-  for (const { run, start: runStart, end: runEnd } of bounds) {
+  for (const { segment, start: segStart, end: segEnd } of bounds) {
     let next = "";
-    let cursor = runStart;
+    let cursor = segStart;
     for (const range2 of sorted) {
-      if (range2.end <= runStart || range2.start >= runEnd) continue;
-      const keepUntil = Math.min(range2.start, runEnd);
-      const from = Math.max(cursor, runStart);
+      if (range2.end <= segStart || range2.start >= segEnd) continue;
+      const keepUntil = Math.min(range2.start, segEnd);
+      const from = Math.max(cursor, segStart);
       if (keepUntil > from) next += joined.slice(from, keepUntil);
-      if (runStart <= range2.start && range2.start < runEnd) next += range2.replacement;
+      if (segStart <= range2.start && range2.start < segEnd) next += range2.replacement;
       cursor = Math.max(cursor, range2.end);
     }
-    const tail = Math.max(cursor, runStart);
-    if (runEnd > tail) next += joined.slice(tail, runEnd);
-    if (next !== run.text) setRunText(run, next);
+    const tail = Math.max(cursor, segStart);
+    if (segEnd > tail) next += joined.slice(tail, segEnd);
+    if (next !== segment.text) setSegmentText(segment, next);
   }
 }
 function replaceInParagraph(el, query, replacement, matchType, maxReplacements, replacementsMade) {
   if (!extractParagraphText(el)) return replacementsMade;
-  const runs = getRunsFromParagraph(el);
-  if (runs.length === 0) return replacementsMade;
-  const text = runs.length === 1 ? runs[0].text : runs.map((r) => r.text).join("");
+  const segments = getParagraphTextSegments(el);
+  if (segments.length === 0) return replacementsMade;
+  const text = segments.length === 1 ? segments[0].text : segments.map((s) => s.text).join("");
   const { ranges, count } = computeReplacementRanges(text, query, replacement, matchType, maxReplacements, replacementsMade);
-  applyRangeReplacements(runs, ranges);
+  applyRangeReplacements(segments, ranges);
   return count;
 }
 function replaceText(bodyElements, query, replacement, matchType = "contains", maxReplacements = Infinity) {

package/dist/src/client.d.ts

@@ -222,6 +222,7 @@ export declare class LoticsClient {
         queries?: Record<string, {
             ast: unknown;
             params?: Record<string, unknown>;
+            description?: string;
         }> | null;
         /**
          * Live alias → agent declaration map from `apps.agents`. Source of truth for
@@ -866,6 +867,7 @@ export declare class LoticsClient {
     setAppQuery(app_id: string, alias: string, declaration: {
         ast: unknown;
         params?: Record<string, unknown>;
+        description?: string;
     }): Promise<ToolExecuteResult>;
     /**
      * Bind (create or replace) an app agent by alias via the `set_app_agent` tool
@@ -1006,14 +1008,16 @@ export declare class LoticsClient {
         prev_version_id?: string | null;
         message?: string | null;
         /**
-         * Alias → query declaration map from `package.json#lotics.queries`. Each
-         * value is `{ ast, params? }` — a fixed query AST template and an optional
-         * typed param schema. Always sent (empty object when none declared) so the
-         * server overwrites apps.queries authoritatively.
+         * Alias → query declaration map ECHOED BACK from the live row (see
+         * `readLiveQueries`), not read from the manifest. Every key the row holds
+         * must survive the round trip — `description` included — because a server
+         * that treats a present map as authoritative writes exactly what it is
+         * sent, so a lossy echo silently strips whatever it forgot.
          */
         queries?: Record<string, {
             ast: unknown;
             params?: Record<string, unknown>;
+            description?: string;
         }>;
         /**
          * Opt-in app capabilities from `package.json#lotics.capabilities`. The CLI
@@ -1032,6 +1036,7 @@ export declare class LoticsClient {
          * (empty array when none declared).
          */
         workflow_aliases?: string[];
+        query_aliases?: string[];
     }): Promise<{
         version_id: string;
         version_number: number;

package/dist/src/client.js

@@ -723,6 +723,7 @@ export class LoticsClient {
         // server records what the served version calls — the remove_app_workflow
         // guard reads this back. These are the manifest KEYS only, never bindings.
         formData.append("workflow_aliases", JSON.stringify(args.workflow_aliases ?? []));
+        formData.append("query_aliases", JSON.stringify(args.query_aliases ?? []));
         const url = `${this.baseUrl}/v1/apps/${encodeURIComponent(args.app_id)}/versions`;
         const response = await fetch(url, {
             method: "POST",

package/docs/cli_reference.md

@@ -30,15 +30,15 @@ Per-command syntax, flags, contracts, and gotchas for the public `lotics` CLI. S
 | `lotics knowledge rm <id>` | Archive the doc via `delete_knowledge` (`{ knowledge_doc_id }`). The REST execute path does not gate `needsApproval`, so this runs unattended. |
 | `lotics app create <name> [path]` | Scaffold a Vite+React+TS custom-code app project; POST /v1/apps; npm install; vite build; upload as v1 |
 | `lotics app pull <app_id> [path]` | Download source archive from R2 (presigned), extract, npm install, stamp package.json's `lotics` field. With no `[path]`: refresh the cwd IN PLACE when it's already this app's own project (its manifest `app_id` matches — the documented `cd <app> && lotics app pull` flow), else clone into an `<name>/` subdir; this avoids the stray nested `./<name>/` subdir a pull-from-inside-the-app used to drop. — `workflows` and `agents` are sourced from the live App row (NOT the archived manifest), so `set_app_workflow` / `set_app_agent` authoring survives the pull. Regenerates `.lotics/app_{workflows,queries,agents}.d.ts` so `useWorkflow` / `useQuery` / `useAgentRun` stay typed. Also writes one `src/workflows/<alias>.ts` per bound workflow (faithful body from `get_app_workflow`) and one `src/agents/<alias>.md` per bound agent (its instructions, straight off the live row) — so the prose an author actually edits lives in a file, and pull always overwrites it from live, leaving no second copy to drift. A legacy workflow alias with no rendered source, or an agent with no instructions, warns and is skipped. The stamped `lotics.agents` map carries the TYPED half only (`inputs`/`outputs`/`tool_names`/`model_id`/…) — an agent's prose lives solely in its `.md`, so there is never a second local copy to desync; a stale `instructions` left by an older CLI is inert and disappears on the next pull |
-| `lotics app deploy -m <message>` | **`-m` is REQUIRED** (CLI errors without a non-empty message) — each deploy is a version row read back by `lotics app versions`, so a blank message loses the audit trail. npm run build; tar source + dist; POST /v1/apps/{id}/versions multipart. Carries code + capabilities only — **neither queries nor workflow/agent bindings are a deploy concern** (`set_app_workflow` / `remove_app_workflow` own `apps.workflows`; the manifest's `workflows` map is a pulled reflection used only for `useWorkflow` codegen). Deploy DOES send the manifest's `lotics.workflows` alias KEYS (not the bindings) as `workflow_aliases`, recorded on the version row so `remove_app_workflow` can refuse to unbind an alias the served version still declares. It also reports any `lotics.queries` alias whose declaration DIFFERS from the app's, naming both recoveries (`app query set --all` to push yours, `app pull` to adopt the app's) — a deploy no longer writes them, so the two are allowed to drift. After a successful deploy it **warns loudly about any alias the source CALLS that is NOT bound on the server** (a `getApp` diff via `warnIfUnboundAliases`) — since deploy never binds them, that would otherwise throw only at the app's first `useWorkflow` / `useAgentRun` call; the warning points to `lotics app workflow set` / `set_app_agent`. Advisory only (never fails the deploy). |
+| `lotics app 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). A getApp / binding / schema / dts-fetch failure is non-fatal (warns, keeps the last-generated files). |
 | `lotics app workflow run <alias> '<json>'` | Execute a bound app workflow end-to-end via `appWorkflow`. `app_id` comes from the local manifest; the alias must be bound (`set_app_workflow`). Inputs ingest exactly like `lotics run` (inline JSON / `@file` / stdin — bulk inputs bypass `ARG_MAX`). Prints the full `{status,message,data,files,side_effects}` JSON to stdout + a one-line summary to stderr; exits non-zero on `status:"error"` (assertable). `--print-created` (alias `--report-effects`) renders the honest post-run harvest (GAP-58): created records grouped by table, a paste-ready `lotics run delete_records …` per table, then the **mandatory caveat** naming what cannot be auto-undone (external integrations + notifications) and that sub-workflows may have run. `--cleanup` (DEFAULT OFF, implies the report) additionally runs the deletes for harvested records ONLY — never files / external / notifications. Neither is a rollback — a rollback is structurally impossible here. |
-| `lotics app workflow set <alias>` | Push the edited `src/workflows/<alias>.ts` body through `set_app_workflow` (the single author of `apps.workflows`). Reads the body from disk (header + `/// <reference>` + `export {};` marker + the `__workflow` wrapper all stripped) + the typed `inputs`/`outputs` from `package.json#lotics.workflows.<alias>`; the **server** re-verifies the body and echoes the bound `outputs` (declared, else DERIVED from `return({ data })`). When the manifest declared NO `outputs`, the DERIVED echo is written back into `package.json#lotics.workflows.<alias>.outputs` (a SURGICAL write — preserves `knowledge`/`config` and every other manifest field) and that alias's types are refreshed in place, so `useWorkflow("<alias>")`'s `result.data` is typed immediately with no hand-copy and no second `lotics app codegen`; an explicitly-declared `outputs` is authoritative and never overwritten. Deploy still never authors workflows — this is a CLI convenience over the existing tool. Clear error + non-zero exit on a missing file, an alias absent from the manifest, or a verify failure. |
+| `lotics app 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 query set <alias>` \| `--all` | Push `package.json#lotics.queries` (`{ ast, params? }` per alias) to `apps.queries` through `set_app_query` — **the only author of a query binding**, the mirror of `app workflow set`. A deploy ships code and binds nothing. The **server** validates each one exactly as it always did (alias identifier, workspace-only tables, resolvable fields, declared params). `--all` pushes every declared alias, alias-sorted, stopping at the first failure and naming what already landed. Clear error + non-zero exit on an alias absent from the manifest or a validation failure. |
 | `lotics app agent run <app_id> <alias> ['<json>'\|@file\|stdin]` | Run a bound app agent end-to-end (GAP-87). A run needs no deployed UI bundle — just the app row + the bound agent declaration + member auth — so the **`app_id` is explicit** (not read from a local manifest). Inputs ingest exactly like `lotics run` (inline JSON / `@file` / stdin; empty = `{}`). Opens the run's SSE (`appAgentRunStream`), streams `text-delta` prose to **stderr** as live progress, then reports from the **settled run RECORD** (`listAgentRuns`, polled to a terminal status — the client stream can close a beat before the run settles, or drop while it runs on server-side): default prints the run's structured `output` (JSON) or final text to **stdout** + a status line to stderr; `--json` prints the full run summary to stdout. Selects THIS run by the `x-app-agent-run-id` header (ordering-independent). Exits 0 **only** when the settled status is `completed`; otherwise non-zero with the run's error surfaced. A settled run that never appears fails loudly (never a silent success). A fresh `session_id` is minted per run (self-contained); `--session <id>` continues an existing thread (prior runs become the agent's context). |
-| `lotics app workflow pull` | Rewrite every `src/workflows/<alias>.ts` from the server (faithful body per bound alias via `get_app_workflow`) **+ its `.lotics/workflows/<alias>.globals.d.ts`** (via `getAppWorkflowDts`, so the body is locally typecheckable via `lotics app workflow check`) without a full `app pull` (no source archive, no npm install). A legacy alias with no rendered source warns and is skipped; a dts-fetch failure is non-fatal (body still written with the fallback wrapper, typecheck degraded). Also idempotently patches the main `tsconfig.json` `exclude` to cover `src/workflows` + `.lotics/workflows` so a pre-existing app's `npm run typecheck` never loads the bodies or the colliding per-alias globals. |
+| `lotics app workflow 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. |
 | `lotics app workflow check [alias]` | Check the editable workflow bodies locally, no auth / no network, in the **server's own order** — parse, then type-check. **Parse** runs `parseWorkflowJs` from `@lotics/shared` (the SAME module `verifyWorkflow` calls, never a second implementation — that is what let the two diverge once) over the stripped body `set` would upload, with `toolNames: undefined` (the CLI ships no tool registry, so tool-name resolution stays a server check while every shape/scope rule runs here). A body the subset rejects reports **that error alone** and skips the compiler — it never reaches the server's compiler either, so tsc's opinion of it is noise. **Type-check** then builds an **isolated** `ts.Program` per alias from exactly that alias's `{body, globals}` pair — mirroring the server, which verifies one body at a time — so the per-alias ambient `trigger` never collides and `trigger.app_workflow.inputs` is checked against the right alias (GAP-59). All aliases run in ONE node process (N programs, not N `tsc` spawns), with the SAME compile options the server uses at set-time verify (lib `es2022` with no DOM, target ES2022, strict, NodeNext, `types:[]`, skipLibCheck) and the app's OWN `typescript` (resolved from its `node_modules`, never bundled into the CLI). What the compiler sees is the **checked source**, not the file: `rewriteAccumulatorAppends` from `@lotics/shared` — the SAME transform the server applies before its set-time compile — is applied in memory, so a pulled body's canonical `out = concat(out, [item])` accumulator checks green here exactly as it saves there (compiling the raw text went red on it), and the body on disk is never rewritten. Reports `<file>:<line>:<col> - <TS####\|subset>` at the **physical** line in `src/workflows/<alias>.ts`, so an editor jump lands on the offending code (these are deliberately NOT `set`'s body-relative numbers — `set` prints no file path, so there is no format to agree with); exits non-zero if any alias fails. Green is honest but not total: `set` additionally resolves names, lints and structurally validates against the live workspace — passes that need its tables and tool schemas, so they cannot run offline, and the success line says so. A bound alias with no body file yet warns + skips; a body with no globals errors (run a pull). |
 | `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. |

package/package.json

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