@lotics/cli 0.176.0 → 0.178.0

package/README.md

@@ -43,7 +43,7 @@ workspace, deploys the app, and prints a one-time sign-in link:
 
 ```bash
 curl -fsSL https://lotics.ai/install.sh | bash
-lotics start <starter_id> --email you@company.com
+lotics setup <starter_id> --email you@company.com
 ```
 
 The installer downloads one compiled executable — no Node.js, no npm. Copying a starter is the
@@ -51,7 +51,7 @@ one step that needs more: it builds the app locally, and building needs Node 18+
 
 Add `--json` for one machine-readable object instead of progress — the organization, the
 workspace, the app id, what was created, the sign-in link, and any warnings. Already signed in?
-Drop `--email` and `lotics start <starter_id>` copies into the account you have.
+Drop `--email` and `lotics setup <starter_id>` copies into the account you have.
 
 ## Install
 

package/dist/src/cli.js

@@ -44183,6 +44183,7 @@ function transportErrorMessage(status, parsed) {
 }
 
 // src/client.ts
+import crypto from "node:crypto";
 import fs2 from "node:fs";
 import path2 from "node:path";
 
@@ -44321,6 +44322,9 @@ async function fetchOfficialStarters() {
   return await response.json();
 }
 var SHELF_FETCH_TIMEOUT_MS = 1e4;
+function newRequestId() {
+  return crypto.randomUUID().replace(/-/g, "").slice(0, 12);
+}
 var LoticsClient = class {
   apiKey;
   workspaceId;
@@ -44337,7 +44341,18 @@ var LoticsClient = class {
     this.viewAsMemberId = options.viewAsMemberId;
     this.baseUrl = API_BASE_URL;
   }
-  async throwResponseError(response) {
+  /**
+   * The id is appended to the MESSAGE rather than carried on a field, because
+   * the only thing that reliably reaches a person is what got printed: the CLI's
+   * top-level handler writes `error.message` to stderr, and the telemetry tail
+   * captures the same bytes. A field would have to be read by every one of ~60
+   * exit sites to be worth anything.
+   *
+   * `requestId` is optional because one caller legitimately has none — a
+   * presigned CDN download is not a request of ours and appears in none of our
+   * logs. Every call against the API passes the id its own headers carry.
+   */
+  async throwResponseError(response, requestId) {
     const text = await response.text();
     let message2;
     try {
@@ -44346,15 +44361,23 @@ var LoticsClient = class {
     } catch {
       message2 = text;
     }
-    throw new Error(`${response.status}: ${message2}`);
+    const trace = requestId === void 0 ? "" : `
+
+  Request id: ${requestId} \u2014 quote this to Lotics support.`;
+    throw new Error(`${response.status}: ${message2}${trace}`);
   }
   /**
-   * The backend's `log()` middleware registers `user-agent` and
-   * `x-posthog-session-id` onto the per-request Logger, so they ride EVERY log
-   * line that request emits — the validation 400, the tool error, the timing.
-   * Sending them is therefore the whole of the correlation work: it turns an
-   * anonymous API-key request into "`app workflow set`, from cli 0.117.0, the
-   * fourth command of this session".
+   * The backend's `log()` middleware registers `user-agent`,
+   * `x-posthog-session-id` and `x-request-id` onto the per-request Logger, so
+   * they ride EVERY log line that request emits — the validation 400, the tool
+   * error, the timing. Sending them is therefore the whole of the correlation
+   * work: it turns an anonymous API-key request into "`app workflow set`, from
+   * cli 0.117.0, the fourth command of this session".
+   *
+   * The request id is minted HERE, with the other headers, so it cannot reach
+   * some paths and not others: several commands build their own transport around
+   * these headers, and an id threaded only through `request` would leave
+   * `app deploy`, `uploadFiles` and every workflow call unfindable.
    */
   buildHeaders() {
     const invocation2 = getInvocation();
@@ -44376,6 +44399,7 @@ var LoticsClient = class {
         headers["x-posthog-session-id"] = invocation2.session;
       }
     }
+    headers["x-request-id"] = newRequestId();
     return headers;
   }
   async request(method, path13, body) {
@@ -44387,7 +44411,7 @@ var LoticsClient = class {
       init.body = JSON.stringify(body);
     }
     const response = await fetch(url2, init);
-    if (!response.ok) await this.throwResponseError(response);
+    if (!response.ok) await this.throwResponseError(response, headers["x-request-id"]);
     return response.json();
   }
   async whoami() {
@@ -44438,13 +44462,14 @@ var LoticsClient = class {
       const timeout = setTimeout(() => controller.abort(), options.timeoutMs);
       try {
         const url2 = `${this.baseUrl}/v1/tools/execute`;
+        const headers = { ...this.buildHeaders(), "Content-Type": "application/json" };
         const response = await fetch(url2, {
           method: "POST",
-          headers: { ...this.buildHeaders(), "Content-Type": "application/json" },
+          headers,
           body: JSON.stringify(body),
           signal: controller.signal
         });
-        if (!response.ok) await this.throwResponseError(response);
+        if (!response.ok) await this.throwResponseError(response, headers["x-request-id"]);
         return response.json();
       } catch (error52) {
         if (error52 instanceof Error && error52.name === "AbortError") {
@@ -44862,16 +44887,12 @@ var LoticsClient = class {
    * iframe. Mirrors POST /v1/apps/{app_id}/agents/{alias}/runs.
    */
   async appAgentRunStream(app_id, alias, body, signal) {
+    const headers = { ...this.buildHeaders(), "Content-Type": "application/json" };
     const res = await fetch(
       `${this.baseUrl}/v1/apps/${encodeURIComponent(app_id)}/agents/${encodeURIComponent(alias)}/runs`,
-      {
-        method: "POST",
-        headers: { ...this.buildHeaders(), "Content-Type": "application/json" },
-        body: JSON.stringify(body),
-        signal
-      }
+      { method: "POST", headers, body: JSON.stringify(body), signal }
     );
-    if (!res.ok) await this.throwResponseError(res);
+    if (!res.ok) await this.throwResponseError(res, headers["x-request-id"]);
     return res;
   }
   /**
@@ -44881,16 +44902,12 @@ var LoticsClient = class {
    * POST /v1/apps/{app_id}/agent-runs/{run_id}/continue.
    */
   async appAgentRunContinueStream(app_id, run_id, body, signal) {
+    const headers = { ...this.buildHeaders(), "Content-Type": "application/json" };
     const res = await fetch(
       `${this.baseUrl}/v1/apps/${encodeURIComponent(app_id)}/agent-runs/${encodeURIComponent(run_id)}/continue`,
-      {
-        method: "POST",
-        headers: { ...this.buildHeaders(), "Content-Type": "application/json" },
-        body: JSON.stringify(body),
-        signal
-      }
+      { method: "POST", headers, body: JSON.stringify(body), signal }
     );
-    if (!res.ok) await this.throwResponseError(res);
+    if (!res.ok) await this.throwResponseError(res, headers["x-request-id"]);
     return res;
   }
   /**
@@ -45009,12 +45026,8 @@ var LoticsClient = class {
     formData.append("agent_aliases", JSON.stringify(args.agent_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",
-      headers: this.buildHeaders(),
-      // no Content-Type — fetch sets multipart boundary
-      body: formData
-    });
+    const headers = this.buildHeaders();
+    const response = await fetch(url2, { method: "POST", headers, body: formData });
     if (response.status === 409) {
       const conflict = await response.json();
       const err2 = new Error(conflict.message ?? "Deploy conflict \u2014 pull required");
@@ -45023,7 +45036,7 @@ var LoticsClient = class {
       throw err2;
     }
     if (!response.ok) {
-      await this.throwResponseError(response);
+      await this.throwResponseError(response, headers["x-request-id"]);
     }
     return response.json();
   }
@@ -45039,11 +45052,14 @@ var LoticsClient = class {
     return absolutePath;
   }
   async downloadFileById(fileId, outputDir, options) {
+    const signedHeaders = this.buildHeaders();
     const signedUrlRes = await fetch(
       `${this.baseUrl}/v1/files/${encodeURIComponent(fileId)}/signed_url`,
-      { headers: this.buildHeaders() }
+      { headers: signedHeaders }
     );
-    if (!signedUrlRes.ok) await this.throwResponseError(signedUrlRes);
+    if (!signedUrlRes.ok) {
+      await this.throwResponseError(signedUrlRes, signedHeaders["x-request-id"]);
+    }
     const { url: url2 } = await signedUrlRes.json();
     const response = await fetch(url2);
     if (!response.ok) await this.throwResponseError(response);
@@ -45103,12 +45119,9 @@ var LoticsClient = class {
       formData.append("file", new Blob([item.bytes], { type: mimeType }), item.filename);
     }
     const url2 = `${this.baseUrl}/v1/files`;
-    const response = await fetch(url2, {
-      method: "POST",
-      headers: this.buildHeaders(),
-      body: formData
-    });
-    if (!response.ok) await this.throwResponseError(response);
+    const headers = this.buildHeaders();
+    const response = await fetch(url2, { method: "POST", headers, body: formData });
+    if (!response.ok) await this.throwResponseError(response, headers["x-request-id"]);
     return response.json();
   }
 };
@@ -45200,7 +45213,7 @@ async function resolveUploadSource(sourceFlag, flags) {
 }
 
 // src/telemetry.ts
-import crypto from "node:crypto";
+import crypto2 from "node:crypto";
 import fs3 from "node:fs";
 import os2 from "node:os";
 import path3 from "node:path";
@@ -45276,7 +45289,7 @@ function buildEvent(exitCode, durationMs, now) {
   if (invocation2 === null || invocation2.session === null) return null;
   const message2 = exitCode === 0 ? "" : stripNarration(stderrTail);
   return {
-    event_id: crypto.randomUUID(),
+    event_id: crypto2.randomUUID(),
     ts: now.toISOString(),
     cli_session_id: invocation2.session,
     cli_command: invocation2.command,
@@ -45343,8 +45356,8 @@ function flushSpool(post, minEvents = 5) {
   const batch = events.slice(0, MAX_FLUSH_EVENTS);
   const sent = `${lines.slice(0, batch.length).join("\n")}
 `;
-  void post(batch).then(() => {
-    clearSpool(sent);
+  void post(batch).then((outcome) => {
+    if (outcome !== "retry") clearSpool(sent);
   }).catch(() => {
   });
 }
@@ -45358,7 +45371,9 @@ async function postEvents(baseUrl, apiKey, events, timeoutMs = 5e3) {
       body: JSON.stringify({ events }),
       signal: controller.signal
     });
-    if (!res.ok) throw new Error(`telemetry flush: ${res.status}`);
+    if (res.ok) return "delivered";
+    const permanent = res.status >= 400 && res.status < 500 && res.status !== 408 && res.status !== 429;
+    return permanent ? "rejected" : "retry";
   } finally {
     clearTimeout(timer2);
   }
@@ -45696,7 +45711,7 @@ function resultSideEffects(result) {
 }
 
 // src/version.ts
-var VERSION = "0.176.0";
+var VERSION = "0.178.0";
 
 // src/timezone.ts
 function machineTimezone() {
@@ -45864,9 +45879,9 @@ function docsCommand(args) {
 // src/commands.ts
 var COMMANDS = [
   {
-    verbs: ["start"],
+    verbs: ["setup"],
     help: [
-      "  lotics start <starter_id> [path] --email <you@co.com>",
+      "  lotics setup <starter_id> [path] --email <you@co.com>",
       "                                       First run, one command: create an account if this",
       "                                       machine has none, then copy the starter into its",
       "                                       workspace \u2014 schema, templates, knowledge docs,",
@@ -48192,6 +48207,22 @@ ${inputLines.join("\n")}
 }
 `;
 }
+var LINK_TSCONFIG_PATH = ".lotics/tsconfig.link.json";
+function generateLinkTsconfig(paths) {
+  const header = Object.keys(paths).length > 0 ? `// 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 resolves from node_modules as normal, so this is inert. It still
+// has to exist: tsconfig.json extends it, and a missing extends target fails
+// the build outright.
+`;
+  return `${header}${JSON.stringify({ compilerOptions: { paths } }, null, 2)}
+`;
+}
 var CAPABILITY_GATED_CALLS = {
   comments: ["useComments", "createComment", "updateComment", "deleteComment"]
 };
@@ -71905,18 +71936,17 @@ function ensureAppTsconfig(projectDir) {
   }
   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}`) {
+    parsed.extends = `./${LINK_TSCONFIG_PATH}`;
+    changes.push(`added "extends": "./${LINK_TSCONFIG_PATH}" (so tsc resolves the same @lotics/ui as Vite)`);
+  } else if (existingExtends !== `./${LINK_TSCONFIG_PATH}`) {
     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.`
+      `\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_PATH}" to "extends" (it accepts an array) to fix it.`
     );
   }
   if (changes.length === 0) return;
   fs8.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 = {};
@@ -71931,19 +71961,8 @@ function writeDevLinkTsconfig(projectDir) {
       paths[`${peer}/*`] = [`${target}/*`];
     }
   }
-  const file2 = path9.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.
-`;
-  fs8.writeFileSync(file2, `${header}${JSON.stringify({ compilerOptions: { paths } }, null, 2)}
-`);
+  const file2 = path9.join(projectDir, LINK_TSCONFIG_PATH);
+  fs8.writeFileSync(file2, generateLinkTsconfig(paths));
   return file2;
 }
 function writeKitTypeAugmentation(projectDir) {
@@ -73984,7 +74003,7 @@ async function starterListPublic() {
   printStarterRows(starters);
   console.error(
     `
-  lotics start <starter_id> --email you@company.com   Copy one \u2014 creates your account too
+  lotics setup <starter_id> --email you@company.com   Copy one \u2014 creates your account too
 
   This machine has no Lotics account yet, so this is the published shelf.
   Signed in, the same command also lists what your own organization published.`
@@ -74128,6 +74147,15 @@ Building ${starter.name} \u2014 this runs its build on your machine (its package
   } else if (serverDeployed === null) {
     note(`Building and deploying\u2026`);
   }
+  if (serverDeployed === null && result.build_error) {
+    warn(
+      `
+Lotics could not build ${starter.name} \u2014 building here instead.
+  ${result.build_error.split("\n")[0]}
+  The copy is fine: the tables, the records and the app all landed. Do NOT
+  copy again, and do not write a replacement app \u2014 only the build is missing.`
+    );
+  }
   const resumeDir = path10.relative(process.cwd(), targetPath) || ".";
   try {
     if (serverDeployed !== null) {
@@ -103592,10 +103620,10 @@ async function main() {
     console.log(VERSION);
     return;
   }
-  if (command === "start") {
+  if (command === "setup") {
     const starterId = subcommand;
     if (!starterId) {
-      console.error("Usage: lotics start <starter_id> [path] [--email <you@co.com>] [--json]");
+      console.error("Usage: lotics setup <starter_id> [path] [--email <you@co.com>] [--json]");
       console.error("       Creates an account if this machine has none, then copies the starter");
       console.error("       into its workspace: schema, templates, knowledge docs, sample records");
       console.error("       and a deployed app. Ends with a one-time sign-in link.");
@@ -103608,7 +103636,7 @@ async function main() {
       const email3 = flags.email ?? (process.stdin.isTTY ? await prompt("Email: ") : "");
       if (!email3) {
         console.error(
-          "This machine has no Lotics credential yet, so `start` needs an email to create one:\n  lotics start " + starterId + " --email you@company.com"
+          "This machine has no Lotics credential yet, so `start` needs an email to create one:\n  lotics setup " + starterId + " --email you@company.com"
         );
         process.exit(1);
       }
@@ -103627,7 +103655,7 @@ async function main() {
     } else if (flags.email !== void 0) {
       console.error(
         `Already authenticated (${SOURCE_LABELS[existing.source]}), so --email would create a SECOND account and copy into it.
-  Copy into the account you have:  lotics start ${starterId}
+  Copy into the account you have:  lotics setup ${starterId}
   Or create another one first:     lotics auth signup ${flags.email}`
       );
       process.exit(1);

package/dist/src/client.d.ts

@@ -163,12 +163,17 @@ export declare class LoticsClient {
     constructor(options: LoticsClientOptions);
     private throwResponseError;
     /**
-     * The backend's `log()` middleware registers `user-agent` and
-     * `x-posthog-session-id` onto the per-request Logger, so they ride EVERY log
-     * line that request emits — the validation 400, the tool error, the timing.
-     * Sending them is therefore the whole of the correlation work: it turns an
-     * anonymous API-key request into "`app workflow set`, from cli 0.117.0, the
-     * fourth command of this session".
+     * The backend's `log()` middleware registers `user-agent`,
+     * `x-posthog-session-id` and `x-request-id` onto the per-request Logger, so
+     * they ride EVERY log line that request emits — the validation 400, the tool
+     * error, the timing. Sending them is therefore the whole of the correlation
+     * work: it turns an anonymous API-key request into "`app workflow set`, from
+     * cli 0.117.0, the fourth command of this session".
+     *
+     * The request id is minted HERE, with the other headers, so it cannot reach
+     * some paths and not others: several commands build their own transport around
+     * these headers, and an id threaded only through `request` would leave
+     * `app deploy`, `uploadFiles` and every workflow call unfindable.
      */
     private buildHeaders;
     private request;
@@ -422,6 +427,11 @@ export declare class LoticsClient {
             version_id: string;
             version_number: number;
         } | null;
+        /**
+         * Why the server built nothing, when it was asked to and `deployed` is null.
+         * Absent from an older server's response for the same reason as `deployed`.
+         */
+        build_error?: string | null;
         binding: Record<string, Record<string, string>>;
         sample_record_ids: Record<string, string[]>;
         knowledge_warnings: {

package/dist/src/client.js

@@ -1,4 +1,5 @@
 import { transportErrorMessage } from "@lotics/shared/transport_error";
+import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 import { getInvocation } from "./invocation.js";
@@ -115,6 +116,18 @@ export async function fetchOfficialStarters() {
 }
 /** Long enough for a slow link, short enough that a dead one still says so. */
 const SHELF_FETCH_TIMEOUT_MS = 10_000;
+/**
+ * A short id for one request, short because a person has to read it back to us.
+ *
+ * Not `generateLocalId` from `@lotics/shared`: this file is the UNBUNDLED
+ * library entry, so every bare specifier it imports has to resolve from a
+ * package whose `dependencies` are empty. `node:crypto` is a builtin and costs
+ * nothing, and the server treats the header as opaque — it logs whatever
+ * arrives, so matching its id ALPHABET buys nothing.
+ */
+function newRequestId() {
+    return crypto.randomUUID().replace(/-/g, "").slice(0, 12);
+}
 export class LoticsClient {
     apiKey;
     workspaceId;
@@ -131,7 +144,18 @@ export class LoticsClient {
         this.viewAsMemberId = options.viewAsMemberId;
         this.baseUrl = API_BASE_URL;
     }
-    async throwResponseError(response) {
+    /**
+     * The id is appended to the MESSAGE rather than carried on a field, because
+     * the only thing that reliably reaches a person is what got printed: the CLI's
+     * top-level handler writes `error.message` to stderr, and the telemetry tail
+     * captures the same bytes. A field would have to be read by every one of ~60
+     * exit sites to be worth anything.
+     *
+     * `requestId` is optional because one caller legitimately has none — a
+     * presigned CDN download is not a request of ours and appears in none of our
+     * logs. Every call against the API passes the id its own headers carry.
+     */
+    async throwResponseError(response, requestId) {
         const text = await response.text();
         let message;
         try {
@@ -141,15 +165,21 @@ export class LoticsClient {
         catch {
             message = text;
         }
-        throw new Error(`${response.status}: ${message}`);
+        const trace = requestId === undefined ? "" : `\n\n  Request id: ${requestId} — quote this to Lotics support.`;
+        throw new Error(`${response.status}: ${message}${trace}`);
     }
     /**
-     * The backend's `log()` middleware registers `user-agent` and
-     * `x-posthog-session-id` onto the per-request Logger, so they ride EVERY log
-     * line that request emits — the validation 400, the tool error, the timing.
-     * Sending them is therefore the whole of the correlation work: it turns an
-     * anonymous API-key request into "`app workflow set`, from cli 0.117.0, the
-     * fourth command of this session".
+     * The backend's `log()` middleware registers `user-agent`,
+     * `x-posthog-session-id` and `x-request-id` onto the per-request Logger, so
+     * they ride EVERY log line that request emits — the validation 400, the tool
+     * error, the timing. Sending them is therefore the whole of the correlation
+     * work: it turns an anonymous API-key request into "`app workflow set`, from
+     * cli 0.117.0, the fourth command of this session".
+     *
+     * The request id is minted HERE, with the other headers, so it cannot reach
+     * some paths and not others: several commands build their own transport around
+     * these headers, and an id threaded only through `request` would leave
+     * `app deploy`, `uploadFiles` and every workflow call unfindable.
      */
     buildHeaders() {
         const invocation = getInvocation();
@@ -171,6 +201,9 @@ export class LoticsClient {
                 headers["x-posthog-session-id"] = invocation.session;
             }
         }
+        // Unconditional, unlike the session header: this describes the request
+        // rather than tracking anyone, and it is what makes a failure findable.
+        headers["x-request-id"] = newRequestId();
         return headers;
     }
     async request(method, path, body) {
@@ -183,7 +216,7 @@ export class LoticsClient {
         }
         const response = await fetch(url, init);
         if (!response.ok)
-            await this.throwResponseError(response);
+            await this.throwResponseError(response, headers["x-request-id"]);
         return response.json();
     }
     async whoami() {
@@ -234,14 +267,15 @@ export class LoticsClient {
             const timeout = setTimeout(() => controller.abort(), options.timeoutMs);
             try {
                 const url = `${this.baseUrl}/v1/tools/execute`;
+                const headers = { ...this.buildHeaders(), "Content-Type": "application/json" };
                 const response = await fetch(url, {
                     method: "POST",
-                    headers: { ...this.buildHeaders(), "Content-Type": "application/json" },
+                    headers,
                     body: JSON.stringify(body),
                     signal: controller.signal,
                 });
                 if (!response.ok)
-                    await this.throwResponseError(response);
+                    await this.throwResponseError(response, headers["x-request-id"]);
                 return response.json();
             }
             catch (error) {
@@ -662,14 +696,10 @@ export class LoticsClient {
      * iframe. Mirrors POST /v1/apps/{app_id}/agents/{alias}/runs.
      */
     async appAgentRunStream(app_id, alias, body, signal) {
-        const res = await fetch(`${this.baseUrl}/v1/apps/${encodeURIComponent(app_id)}/agents/${encodeURIComponent(alias)}/runs`, {
-            method: "POST",
-            headers: { ...this.buildHeaders(), "Content-Type": "application/json" },
-            body: JSON.stringify(body),
-            signal,
-        });
+        const headers = { ...this.buildHeaders(), "Content-Type": "application/json" };
+        const res = await fetch(`${this.baseUrl}/v1/apps/${encodeURIComponent(app_id)}/agents/${encodeURIComponent(alias)}/runs`, { method: "POST", headers, body: JSON.stringify(body), signal });
         if (!res.ok)
-            await this.throwResponseError(res);
+            await this.throwResponseError(res, headers["x-request-id"]);
         return res;
     }
     /**
@@ -679,14 +709,10 @@ export class LoticsClient {
      * POST /v1/apps/{app_id}/agent-runs/{run_id}/continue.
      */
     async appAgentRunContinueStream(app_id, run_id, body, signal) {
-        const res = await fetch(`${this.baseUrl}/v1/apps/${encodeURIComponent(app_id)}/agent-runs/${encodeURIComponent(run_id)}/continue`, {
-            method: "POST",
-            headers: { ...this.buildHeaders(), "Content-Type": "application/json" },
-            body: JSON.stringify(body),
-            signal,
-        });
+        const headers = { ...this.buildHeaders(), "Content-Type": "application/json" };
+        const res = await fetch(`${this.baseUrl}/v1/apps/${encodeURIComponent(app_id)}/agent-runs/${encodeURIComponent(run_id)}/continue`, { method: "POST", headers, body: JSON.stringify(body), signal });
         if (!res.ok)
-            await this.throwResponseError(res);
+            await this.throwResponseError(res, headers["x-request-id"]);
         return res;
     }
     /**
@@ -775,11 +801,8 @@ export class LoticsClient {
         formData.append("agent_aliases", JSON.stringify(args.agent_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",
-            headers: this.buildHeaders(), // no Content-Type — fetch sets multipart boundary
-            body: formData,
-        });
+        const headers = this.buildHeaders(); // no Content-Type — fetch sets multipart boundary
+        const response = await fetch(url, { method: "POST", headers, body: formData });
         if (response.status === 409) {
             const conflict = (await response.json());
             const err = new Error(conflict.message ?? "Deploy conflict — pull required");
@@ -789,7 +812,7 @@ export class LoticsClient {
             throw err;
         }
         if (!response.ok) {
-            await this.throwResponseError(response);
+            await this.throwResponseError(response, headers["x-request-id"]);
         }
         return response.json();
     }
@@ -809,9 +832,11 @@ export class LoticsClient {
         // edge Worker that doesn't accept the API key). The signed_url endpoint
         // takes the API key and returns a short-lived, directly-fetchable URL
         // whose Content-Disposition carries the original filename.
-        const signedUrlRes = await fetch(`${this.baseUrl}/v1/files/${encodeURIComponent(fileId)}/signed_url`, { headers: this.buildHeaders() });
-        if (!signedUrlRes.ok)
-            await this.throwResponseError(signedUrlRes);
+        const signedHeaders = this.buildHeaders();
+        const signedUrlRes = await fetch(`${this.baseUrl}/v1/files/${encodeURIComponent(fileId)}/signed_url`, { headers: signedHeaders });
+        if (!signedUrlRes.ok) {
+            await this.throwResponseError(signedUrlRes, signedHeaders["x-request-id"]);
+        }
         const { url } = (await signedUrlRes.json());
         const response = await fetch(url);
         if (!response.ok)
@@ -890,13 +915,10 @@ export class LoticsClient {
             formData.append("file", new Blob([item.bytes], { type: mimeType }), item.filename);
         }
         const url = `${this.baseUrl}/v1/files`;
-        const response = await fetch(url, {
-            method: "POST",
-            headers: this.buildHeaders(),
-            body: formData,
-        });
+        const headers = this.buildHeaders();
+        const response = await fetch(url, { method: "POST", headers, body: formData });
         if (!response.ok)
-            await this.throwResponseError(response);
+            await this.throwResponseError(response, headers["x-request-id"]);
         return response.json();
     }
 }

package/docs/cli_reference.md

@@ -41,10 +41,10 @@ Per-command syntax, flags, contracts, and gotchas for the public `lotics` CLI. S
 | `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 a stale copy would ship ids that no longer name what the source thinks they do. `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 run run_app_workflow`, whose whole contract is that the alias is bound server-side, or chat's call 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. **A removal DELETES the local declaration too** — `package.json#lotics.<kind>.<alias>` and its `synced` baseline — because leaving it would undo the prune: the manifest is what the next plain deploy pushes FROM, so the binding came straight back. That makes the act destructive rather than merely reversible, so what it deleted is written to `.lotics/pruned/<kind>/<alias>.json` and the ✓ names that file plus the `set` verb that re-binds it, on the same line. (These trees are never committed, so git is not the fallback; `lotics app pull --from-version <apv_…>` is the only other route back.) After a successful prune the generated companions are regenerated from the narrowed manifest — the `.d.ts` set and, when a query was pruned, `.lotics/app_fields.ts`, whose table set is derived from the surviving query ASTs. A table named ONLY by the pruned query leaves `F`/`OPT`, which is reported: if your source still addresses it, add the table id to `package.json#lotics.codegen.tables`. A local write that fails at any of this reports what could not be written and which aliases were already unbound server-side; it never fails the release, which is already live. 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. After a successful deploy it also REFRESHES the `.lotics/workflows/<alias>.globals.d.ts` of any alias whose `// lotics:declaration` stamp says this deploy moved its declaration (only those — refreshing every bound alias would cost one round trip each on every deploy to fix something only ever wrong right after a manifest edit), from the manifest declaration, re-wrapping the SAME on-disk body (never re-fetching it, so local edits survive). A deploy is the moment the manifest becomes real, so it is also the moment the local types stop matching it — and the author's next act is usually `workflow set`, whose body would otherwise be typechecked against the declaration as it stood before this deploy. Non-fatal: the release already shipped, and stale types never fail it. |
 | `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` — 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). **There is one form, and that is what makes a starter's source portable**: the keys are slugified DISPLAY NAMES and a starter carries its labels verbatim, so running codegen in a copy's own workspace emits the same keys pointing at that workspace's ids — no binding fetched at load, no prebuilt bundle to keep in step. 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`. |
-| `lotics start <starter_id> [path] [--email <addr>] [--json]` | **The whole first run, in one command.** Creates an account when this machine has no credential (the same call `auth signup` makes — `--name` and `--timezone` apply), then does exactly what `starter init` does, then prints the one-time sign-in link. It exists because the two-command form has a seam where the FIRST command exists only to produce a credential for the second, and a caller pasting a prompt has to get both right. **`--email` is only for creating an account**: with a credential already resolvable it is REFUSED rather than obeyed, because the two can name different organizations and preferring either one silently copies a starter into an org the caller did not name — the message says how to do each thing on purpose. Without it, `start` copies into the account you already have and is a pure alias for `starter init`. **`--json` prints one object on stdout and nothing else** — `organization_id`, `workspace_id`, `app_id`, `project_dir`, `signin_url`, and `created` — which NAMES what landed (`tables`, `templates` and `knowledge_docs` are alias arrays; `sample_records` is a row count, since rows are not named things). Aliases rather than counts because the next question is about a particular artifact: a copied template carries the publisher's wording and a copied knowledge doc describes how they work, so "which of these should be mine?" is the conversation a copy starts, and a count cannot begin it. Plus a `warnings` array carrying everything the prose form would have said out of band — an unbindable knowledge doc, a sign-in link that could not be minted, and the notice naming whose build is about to run on this machine. A warning is never merely silenced: when the command fails with an error before it can emit, the ones it had collected go to stderr alongside it. npm's and vite's own output is captured under `--json` and surfaced only if the build FAILS, where it rides out in the error. Reachable with no install: `npx -y @lotics/cli start …`. |
+| `lotics setup <starter_id> [path] [--email <addr>] [--json]` | **The whole first run, in one command.** Creates an account when this machine has no credential (the same call `auth signup` makes — `--name` and `--timezone` apply), then does exactly what `starter init` does, then prints the one-time sign-in link. It exists because the two-command form has a seam where the FIRST command exists only to produce a credential for the second, and a caller pasting a prompt has to get both right. **`--email` is only for creating an account**: with a credential already resolvable it is REFUSED rather than obeyed, because the two can name different organizations and preferring either one silently copies a starter into an org the caller did not name — the message says how to do each thing on purpose. Without it, `setup` copies into the account you already have and is a pure alias for `starter init`. **`--json` prints one object on stdout and nothing else** — `organization_id`, `workspace_id`, `app_id`, `project_dir`, `signin_url`, and `created` — which NAMES what landed (`tables`, `templates` and `knowledge_docs` are alias arrays; `sample_records` is a row count, since rows are not named things). Aliases rather than counts because the next question is about a particular artifact: a copied template carries the publisher's wording and a copied knowledge doc describes how they work, so "which of these should be mine?" is the conversation a copy starts, and a count cannot begin it. Plus a `warnings` array carrying everything the prose form would have said out of band — an unbindable knowledge doc, a sign-in link that could not be minted, and the notice naming whose build is about to run on this machine. A warning is never merely silenced: when the command fails with an error before it can emit, the ones it had collected go to stderr alongside it. npm's and vite's own output is captured under `--json` and surfaced only if the build FAILS, where it rides out in the error. Reachable with no install: `npx -y @lotics/cli start …`. |
 | `lotics starter list` | **Works with no account**, and that is the point: whether to copy a starter or build from scratch is decided before one exists, so requiring a key would mean signing up to learn the answer was no. Unauthenticated it lists what Lotics publishes (`GET /v1/starters/official`, public). Authenticated it is the org shelf — The starters this organization can copy — Lotics-reviewed ones plus its own, each with at least one released version. Deliberately NOT a catalogue of everything published: the server returns exactly what a copy would be allowed to take, so the list can never offer something that then refuses. Admin-only. |
 | `lotics starter show <starter_id>` | One starter's name, description, current version and trust standing (`official` — reviewed by Lotics; `your organization's own`). Read it before copying a starter you did not publish. |
-| `lotics starter init <starter_id> [path]` | **Copy a starter into this workspace.** Server-side it scaffolds the tables and fields, creates the document templates and knowledge docs, inserts the sample records, creates a BESPOKE app and materializes its queries, workflows and agents onto it. Then it stops: a starter ships **source only**, with no prebuilt bundle, so the app source is downloaded here, hydrated against the live app (the same steps `app pull` runs), built, and deployed — which is why this needs node and a few minutes, and why the app is not servable until the deploy lands. **What you get is yours outright**: an ordinary app plus ordinary tables, with no link back to the starter, nothing pinned, and nothing to upgrade. Edit any of it. **It builds the publisher's code on your machine** — the copy has to build where your workspace's field ids are, so `npm run build` runs their build script and vite loads their `vite.config.ts` in Node, as you. Dependencies install with `npm ci --ignore-scripts` — the lockfile's exact tree (so a starter published months ago resolves the same packages today), and no lifecycle scripts (the path that fires before you run anything). Neither changes the build itself. That is why provenance is the gate: **copyable only if the starter is Lotics-reviewed or your own organization published it** — copying runs the author's code (its bundle, its workflows, its agents) under YOUR authority, so provenance is the gate, enforced server-side. **Refuses a workspace that already has tables** unless `--adopt`: scaffold matches an entity by DISPLAY NAME, so a starter declaring `Contacts` would bind to yours. `--json` prints one object on stdout instead of progress (the shape is under `lotics start`) and captures npm/vite output unless the build fails. `--no-sample-data` skips the sample records; with them, the created record ids are reported — they are ordinary records, delete them whenever. Resolves and ANNOUNCES its workspace first (`lotics → <org> / <workspace>` on stderr). Admin-only. Authoring the registry (`starter publish/release/unpublish`) stays operator-only. |
+| `lotics starter init <starter_id> [path]` | **Copy a starter into this workspace.** Server-side it scaffolds the tables and fields, creates the document templates and knowledge docs, inserts the sample records, creates a BESPOKE app and materializes its queries, workflows and agents onto it. Then it stops: a starter ships **source only**, with no prebuilt bundle, so the app source is downloaded here, hydrated against the live app (the same steps `app pull` runs), built, and deployed — which is why this needs node and a few minutes, and why the app is not servable until the deploy lands. **What you get is yours outright**: an ordinary app plus ordinary tables, with no link back to the starter, nothing pinned, and nothing to upgrade. Edit any of it. **It builds the publisher's code on your machine** — the copy has to build where your workspace's field ids are, so `npm run build` runs their build script and vite loads their `vite.config.ts` in Node, as you. Dependencies install with `npm ci --ignore-scripts` — the lockfile's exact tree (so a starter published months ago resolves the same packages today), and no lifecycle scripts (the path that fires before you run anything). Neither changes the build itself. That is why provenance is the gate: **copyable only if the starter is Lotics-reviewed or your own organization published it** — copying runs the author's code (its bundle, its workflows, its agents) under YOUR authority, so provenance is the gate, enforced server-side. **Refuses a workspace that already has tables** unless `--adopt`: scaffold matches an entity by DISPLAY NAME, so a starter declaring `Contacts` would bind to yours. `--json` prints one object on stdout instead of progress (the shape is under `lotics setup`) and captures npm/vite output unless the build fails. `--no-sample-data` skips the sample records; with them, the created record ids are reported — they are ordinary records, delete them whenever. Resolves and ANNOUNCES its workspace first (`lotics → <org> / <workspace>` on stderr). Admin-only. Authoring the registry (`starter publish/release/unpublish`) stays operator-only. |
 | `lotics starter fixtures capture [--entity <alias> ...] [--limit <n>]` | **(authoring)** Write this app's live records into the project as `fixtures/<entity-alias>.json` — the sample data a starter carries, so a copy lands with something in it. Run from an app project; the app id comes from its manifest. The alias-keyed shape is produced server-side, because the aliases are minted when the starter is extracted and exist nowhere a project can read them. `--entity` is repeatable and comma-separated; omitted, every table the app declares is captured. **Capture a linked set in ONE call** — a link between two rows only resolves within a single capture, so taking companies and contacts separately drops the edge between them (it says so when it happens). `--limit` bounds rows per table (default 10, max 200). **READ WHAT IT WROTE before committing**: these rows are created verbatim in every workspace that copies the starter, so a real customer name, price or address captured here is published. Files, formulas, rollups, lookups and autonumbers are never captured — the platform writes those. Admin-only; writes nothing to the workspace. |
 | `lotics upgrade` | Update this CLI in place. Runs the same installer a person would, chosen by how THIS copy arrived: an npm install upgrades through npm, a script install re-runs the script — the runtime knows which (the executable is compiled, the npm bin runs under node), so nobody has to. It downloads nothing itself; resolving a version, verifying the checksum and replacing a running executable already exist in the installers, and a second copy of that inside the binary would be a second thing to get right. Replacing the binary while it runs is safe — a rename leaves the running image mapped on unix, and on Windows the installer moves the old aside precisely because the file is in use. Already current is a no-op that says so. Needs no auth. |
 | `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. |

package/package.json

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