@lotics/cli 0.192.0 → 0.192.2

package/README.md

@@ -195,7 +195,7 @@ Every request identifies the CLI (`user-agent: lotics-cli/<version> node/<v> <pl
 **`LOTICS_TELEMETRY=1` additionally records the session.** Off by default. Set it in your shell profile rather than per command — each invocation is its own process. When set:
 
 - Requests carry a session id shared by every command in the sitting — under an agent harness it adopts the harness's own session id, otherwise it rolls over after 30 minutes idle (`~/.lotics/session.json`).
-- Each invocation appends one record to `~/.lotics/telemetry.ndjson` — the command, its exit code, how long it took, and, on a failure, the message that was printed. Batches are sent on a later run; a failed send is retried, never dropped silently.
+- Each invocation appends one record to `~/.lotics/telemetry-<host>.ndjson` — the command, its exit code, how long it took, and, on a failure, the message that was printed. One spool per Lotics the CLI talks to, so a record made against one instance is only ever sent to that instance. Batches are sent on a later run against the same host; a failed send is retried, never dropped silently.
 
 Arguments contribute a **hash** and a **shape** (`records[].data.name:string`) and nothing else — no values, no file contents, no record data. The hash is the point: two failures in a row with the same hash mean the error message did not tell you enough to fix the call.
 

package/dist/src/cli.js

@@ -44372,10 +44372,9 @@ var LoticsRequestError = class extends Error {
   status;
   body;
 };
-var API_BASE_URL = process.env.LOTICS_API_URL ?? "https://api.lotics.ai";
 var WEB_APP_URL = process.env.LOTICS_WEB_URL ?? "https://lotics.ai";
-async function fetchOfficialStarters() {
-  const read = await getPublicJson(`${API_BASE_URL}/v1/starters/official`, "list the packages");
+async function fetchOfficialStarters(apiUrl) {
+  const read = await getPublicJson(`${apiUrl}/v1/starters/official`, "list the packages");
   if (!read.ok) {
     throw new Error(
       `Lotics answered ${read.status} listing the packages. If this keeps happening, browse ${WEB_APP_URL}/docs/cli.`
@@ -44395,16 +44394,16 @@ async function getPublicJson(url2, what) {
   if (!response.ok) return { ok: false, status: response.status };
   return { ok: true, body: await response.json() };
 }
-async function readOfficialStarter(starter_id) {
+async function readOfficialStarter(apiUrl, starter_id) {
   const read = await getPublicJson(
-    `${API_BASE_URL}/v1/starters/official/${encodeURIComponent(starter_id)}`,
+    `${apiUrl}/v1/starters/official/${encodeURIComponent(starter_id)}`,
     `read ${starter_id}`
   );
   if (!read.ok) return read;
   return { ok: true, package: read.body };
 }
-async function getOfficialStarter(starter_id) {
-  const read = await readOfficialStarter(starter_id);
+async function getOfficialStarter(apiUrl, starter_id) {
+  const read = await readOfficialStarter(apiUrl, starter_id);
   if (!read.ok) {
     throw new Error(
       `Lotics answered ${read.status} reading ${starter_id}. Only packages Lotics publishes can be read without an account.`
@@ -44413,10 +44412,10 @@ async function getOfficialStarter(starter_id) {
   return read.package;
 }
 var PUBLIC_FETCH_TIMEOUT_MS = 1e4;
-async function startCliLogin(email3) {
+async function startCliLogin(apiUrl, email3) {
   let response;
   try {
-    response = await fetch(`${API_BASE_URL}/v1/cli/login_requests`, {
+    response = await fetch(`${apiUrl}/v1/cli/login_requests`, {
       method: "POST",
       headers: { "Content-Type": "application/json" },
       body: JSON.stringify({ email: email3 }),
@@ -44432,8 +44431,8 @@ async function startCliLogin(email3) {
   }
   return await response.json();
 }
-async function pollCliLogin(request_id, secret) {
-  const url2 = `${API_BASE_URL}/v1/cli/login_requests/${encodeURIComponent(request_id)}`;
+async function pollCliLogin(apiUrl, request_id, secret) {
+  const url2 = `${apiUrl}/v1/cli/login_requests/${encodeURIComponent(request_id)}`;
   let response;
   try {
     response = await fetch(url2, {
@@ -44460,14 +44459,14 @@ var LoticsClient = class {
    *  construction — surfaced so `lotics app dev` can show it in the banner. */
   viewAsMemberId;
   /** API URL the client is configured against. Read-only after construction.
-   *  Surfaced for callers that need to display or log it (e.g., `lotics app dev`
-   *  shows it in the banner). */
+   *  Surfaced for callers that need to display it (`lotics app dev`'s banner) or
+   *  to hand it on (the wrapper page's RPC target, the scaffold's font proxy). */
   baseUrl;
   constructor(options) {
     this.apiKey = options.apiKey;
     this.workspaceId = options.workspaceId;
     this.viewAsMemberId = options.viewAsMemberId;
-    this.baseUrl = API_BASE_URL;
+    this.baseUrl = options.apiUrl;
   }
   /**
    * The id is appended to the MESSAGE rather than carried on a field, because
@@ -44870,9 +44869,10 @@ var LoticsClient = class {
     return tables.filter((t) => t !== null);
   }
   /**
-   * Rename an app's public subdomain — its `<slug>.lotics.app` address.
-   * Mirrors PUT /v1/apps/{app_id}/subdomain. The old subdomain stops
-   * resolving once the change lands.
+   * Rename an app's public subdomain — the label its origin is built on.
+   * Mirrors PUT /v1/apps/{app_id}/subdomain, and returns the finished `origin`
+   * because only the instance knows the domain and scheme it serves apps on.
+   * The old subdomain stops resolving once the change lands.
    */
   async setAppSubdomain(app_id, public_subdomain) {
     return this.request(
@@ -45500,8 +45500,16 @@ function canonicalize(value2) {
 var MAX_ERROR_CHARS = 2e3;
 var MAX_SPOOL_BYTES = 1024 * 1024;
 var MAX_FLUSH_EVENTS = 500;
-function spoolPath() {
-  return path3.join(os2.homedir(), ".lotics", "telemetry.ndjson");
+function spoolPath(apiUrl) {
+  const shard = crypto2.createHash("sha256").update(apiUrl).digest("hex").slice(0, 12);
+  return path3.join(os2.homedir(), ".lotics", `telemetry-${shard}.ndjson`);
+}
+var targetApiUrl = "";
+function noteTarget(apiUrl) {
+  targetApiUrl = apiUrl;
+}
+function invocationTarget() {
+  return targetApiUrl;
 }
 var stderrTail = "";
 function recordStderr(text) {
@@ -45561,8 +45569,8 @@ function buildEvent(exitCode, durationMs, now) {
     ...pendingScope
   };
 }
-function appendEvent(event) {
-  const file2 = spoolPath();
+function appendEvent(event, apiUrl) {
+  const file2 = spoolPath(apiUrl);
   try {
     fs3.mkdirSync(path3.dirname(file2), { recursive: true });
     if ((fs3.statSync(file2, { throwIfNoEntry: false })?.size ?? 0) > MAX_SPOOL_BYTES) {
@@ -45573,11 +45581,11 @@ function appendEvent(event) {
   } catch {
   }
 }
-function readSpool() {
+function readSpool(apiUrl) {
   try {
     const events = [];
     const lines = [];
-    for (const line of fs3.readFileSync(spoolPath(), "utf-8").split("\n")) {
+    for (const line of fs3.readFileSync(spoolPath(apiUrl), "utf-8").split("\n")) {
       if (line.trim() === "") continue;
       try {
         events.push(JSON.parse(line));
@@ -45590,32 +45598,34 @@ function readSpool() {
     return { events: [], lines: [] };
   }
 }
-function clearSpool(sent) {
+function clearSpool(apiUrl, sent) {
   try {
-    const current = fs3.readFileSync(spoolPath(), "utf-8");
-    fs3.writeFileSync(spoolPath(), current.startsWith(sent) ? current.slice(sent.length) : "", {
+    const file2 = spoolPath(apiUrl);
+    const current = fs3.readFileSync(file2, "utf-8");
+    fs3.writeFileSync(file2, current.startsWith(sent) ? current.slice(sent.length) : "", {
       mode: 384
     });
   } catch {
   }
 }
-function installTelemetry(startedAt2 = Date.now()) {
+function installTelemetry(target, startedAt2 = Date.now()) {
   if (!telemetryEnabled()) return;
+  noteTarget(target);
   installStderrCapture();
   process.on("exit", (code) => {
     const event = buildEvent(code, Date.now() - startedAt2, /* @__PURE__ */ new Date());
-    if (event !== null) appendEvent(event);
+    if (event !== null) appendEvent(event, invocationTarget());
   });
 }
-function flushSpool(post, minEvents = 5) {
+function flushSpool(apiUrl, post, minEvents = 5) {
   if (!telemetryEnabled()) return;
-  const { events, lines } = readSpool();
+  const { events, lines } = readSpool(apiUrl);
   if (events.length < minEvents) return;
   const batch = events.slice(0, MAX_FLUSH_EVENTS);
   const sent = `${lines.slice(0, batch.length).join("\n")}
 `;
   void post(batch).then((outcome) => {
-    if (outcome !== "retry") clearSpool(sent);
+    if (outcome !== "retry") clearSpool(apiUrl, sent);
   }).catch(() => {
   });
 }
@@ -45641,6 +45651,10 @@ async function postEvents(baseUrl, apiKey, events, timeoutMs = 5e3) {
 import fs4 from "node:fs";
 import path4 from "node:path";
 import os3 from "node:os";
+var HOSTED_API_URL = "https://api.lotics.ai";
+function envApiUrl() {
+  return process.env.LOTICS_API_URL ?? HOSTED_API_URL;
+}
 function globalConfigFile() {
   return path4.join(os3.homedir(), ".lotics", "config.json");
 }
@@ -45663,12 +45677,34 @@ function configFileForScope(scope) {
   return globalConfigFile();
 }
 function readConfigFile(file2) {
+  let parsed;
   try {
     const raw = fs4.readFileSync(file2, "utf-8");
-    return JSON.parse(raw);
+    parsed = JSON.parse(raw);
   } catch {
     return null;
   }
+  return upgradeProfileApiUrls(file2, parsed);
+}
+function upgradeProfileApiUrls(file2, config2) {
+  const profiles = config2.profiles;
+  if (!profiles) return config2;
+  const entries2 = Object.entries(profiles);
+  if (!entries2.some(([, profile]) => !profile.api_url)) return config2;
+  const upgraded = {
+    ...config2,
+    profiles: Object.fromEntries(
+      entries2.map(([orgId, profile]) => [
+        orgId,
+        { ...profile, api_url: profile.api_url || HOSTED_API_URL }
+      ])
+    )
+  };
+  try {
+    writeConfigFile(file2, upgraded);
+  } catch {
+  }
+  return upgraded;
 }
 function writeConfigFile(file2, config2) {
   fs4.mkdirSync(path4.dirname(file2), { recursive: true, mode: 448 });
@@ -45715,6 +45751,11 @@ function resolveProfileByNameOrId(profiles, nameOrId) {
   return null;
 }
 function resolveContext(flags, appWorkspaceId) {
+  const resolved = resolveCredential(flags, appWorkspaceId);
+  if (resolved) noteTarget(resolved.apiUrl);
+  return resolved;
+}
+function resolveCredential(flags, appWorkspaceId) {
   const envKey = process.env.LOTICS_API_KEY;
   const envOrg = process.env.LOTICS_ORG;
   const envWorkspace = process.env.LOTICS_WORKSPACE;
@@ -45732,6 +45773,7 @@ function resolveContext(flags, appWorkspaceId) {
     const [orgId, profile] = resolved;
     return {
       apiKey: profile.api_key,
+      apiUrl: profile.api_url,
       orgId,
       orgName: profile.org_name,
       workspaceId: wsOverride ?? profile.workspace_id,
@@ -45739,10 +45781,10 @@ function resolveContext(flags, appWorkspaceId) {
     };
   }
   if (flags.apiKey) {
-    return { apiKey: flags.apiKey, workspaceId: wsOverride, source: "flag" };
+    return { apiKey: flags.apiKey, apiUrl: envApiUrl(), workspaceId: wsOverride, source: "flag" };
   }
   if (envKey) {
-    return { apiKey: envKey, workspaceId: wsOverride, source: "env_key" };
+    return { apiKey: envKey, apiUrl: envApiUrl(), workspaceId: wsOverride, source: "env_key" };
   }
   const global2 = loadGlobalConfig();
   const profiles = global2?.profiles ?? {};
@@ -45756,6 +45798,7 @@ function resolveContext(flags, appWorkspaceId) {
     const [orgId, profile] = resolved;
     return {
       apiKey: profile.api_key,
+      apiUrl: profile.api_url,
       orgId,
       orgName: profile.org_name,
       workspaceId: wsOverride ?? profile.workspace_id,
@@ -45772,6 +45815,7 @@ function resolveContext(flags, appWorkspaceId) {
     }
     return {
       apiKey: profile.api_key,
+      apiUrl: profile.api_url,
       orgId: local.active_org,
       orgName: profile.org_name,
       workspaceId: wsOverride ?? local.workspace_id ?? profile.workspace_id,
@@ -45789,6 +45833,7 @@ function resolveContext(flags, appWorkspaceId) {
       const [orgId, profile] = matches[0];
       return {
         apiKey: profile.api_key,
+        apiUrl: profile.api_url,
         orgId,
         orgName: profile.org_name,
         workspaceId: appWorkspaceId,
@@ -45805,6 +45850,7 @@ function resolveContext(flags, appWorkspaceId) {
     }
     return {
       apiKey: profile.api_key,
+      apiUrl: profile.api_url,
       orgId: global2.active_org,
       orgName: profile.org_name,
       workspaceId: wsOverride ?? profile.workspace_id,
@@ -45819,6 +45865,7 @@ function upsertProfile(orgId, fields) {
   const profile = {
     api_key: fields.api_key,
     org_name: fields.org_name,
+    api_url: fields.api_url,
     workspace_id: fields.workspace_id ?? existing?.workspace_id
   };
   saveGlobalConfig({
@@ -46001,7 +46048,7 @@ function resultSideEffects(result) {
 }
 
 // src/version.ts
-var VERSION = "0.192.0";
+var VERSION = "0.192.2";
 
 // src/timezone.ts
 function machineTimezone() {
@@ -46562,7 +46609,7 @@ var COMMANDS = [
       "                                       fields keep whatever is bound (a manifest is a",
       "                                       snapshot; replaying it would revert them). Change",
       "                                       those with set_app_agent, then pull.",
-      "  lotics app subdomain <new-subdomain> Rename the app's public <slug>.lotics.app address",
+      "  lotics app subdomain <new-subdomain> Rename the app's public address (its subdomain)",
       `  lotics app rename "<new name>"       Rename the app's display name (launcher title)`,
       "  lotics app dev [path]                Run the app locally with HMR (RPC forwarded to prod)"
     ]
@@ -46997,8 +47044,8 @@ export default defineConfig({
   server: {
     // Allow the sandboxed null-origin iframe used by \`lotics app dev\` to
     // fetch HMR client + source modules from the dev server. Production
-    // iframe loads modules from api.lotics.ai which already permits null
-    // origin via CORS.
+    // iframe loads modules from the API, which already permits null origin
+    // via CORS.
     cors: { origin: "*" },
     // Chat-authoring previews reach this dev server through the sandbox proxy
     // at \`5173-<id>-<token>.lotics-sandbox.app\`. Vite \u22655.4.12 rejects HMR
@@ -65067,7 +65114,7 @@ var appSchema = zod_default.object({
     "Pointer to the currently-published app_versions row in R2. Set once the app has been deployed at least once via `lotics app deploy`; null before the first deploy."
   ),
   public_subdomain: zod_default.string().describe(
-    "DNS label for the app's public origin: `<public_subdomain>.lotics.app`. Server-generated, high-entropy, and distinct from `id` (app_ids are not valid DNS labels). Assigned at creation for every app."
+    "DNS label for the app's public origin, under the instance's apps domain. Server-generated, high-entropy, and distinct from `id` (app_ids are not valid DNS labels). Assigned at creation for every app."
   ),
   public_password_set: zod_default.boolean().optional().describe(
     "Whether a shared password gates the public binding. True \u2192 anonymous visitors must authenticate at `/v1/apps/{app_id}/public/authenticate` before any publicAppAccess endpoint resolves. The hash itself is never sent over the wire; only this flag is exposed (and only on authenticated owner-side reads \u2014 the public by-subdomain response surfaces the same fact as `requires_password`)."
@@ -68942,8 +68989,8 @@ function noteCopiedContent(templates, knowledgeDocs) {
     );
   }
 }
-async function libraryListPublic() {
-  const [presets, packages] = await Promise.all([fetchPresetIndex(), fetchOfficialStarters()]);
+async function libraryListPublic(apiUrl) {
+  const [presets, packages] = await Promise.all([fetchPresetIndex(), fetchOfficialStarters(apiUrl)]);
   printPresetSection(presets);
   printPackageSection(packages, "published by Lotics");
   console.error(
@@ -69071,8 +69118,8 @@ function printPackageHead(pkg) {
   console.log(`
 version      ${pkg.latest_version}`);
 }
-async function libraryShowPublic(starter_id) {
-  const pkg = await getOfficialStarter(starter_id);
+async function libraryShowPublic(apiUrl, starter_id) {
+  const pkg = await getOfficialStarter(apiUrl, starter_id);
   printPackageHead(pkg);
   console.log(`trust        official \u2014 reviewed by Lotics`);
   printPackageEntities(pkg.contract.entities);
@@ -77541,7 +77588,7 @@ function withPlanFiles(starter, plan) {
 async function appSetSubdomain(client, args) {
   const meta3 = readAppMeta(process.cwd());
   const result = await client.setAppSubdomain(meta3.app_id, args.subdomain);
-  console.error(`Public address set: https://${result.public_subdomain}.lotics.app`);
+  console.error(`Public address set: ${result.origin}`);
 }
 async function appRename(client, args) {
   const meta3 = readAppMeta(process.cwd());
@@ -79363,33 +79410,37 @@ function signInInstructions(pending, options) {
 ${then}`;
 }
 async function startPendingLogin(email3) {
-  const request = await startCliLogin(email3);
+  const apiUrl = envApiUrl();
+  const request = await startCliLogin(apiUrl, email3);
   const pending = {
     request_id: request.request_id,
     secret: request.secret,
     code: request.code,
     expires_at: request.expires_at,
     email: email3,
-    api_url: API_BASE_URL
+    api_url: apiUrl
   };
   savePendingLogin(pending);
   return pending;
 }
-function saveApproval(state, email3, options) {
+function saveApproval(state, pending, options) {
   requireNonEmpty(state.api_key, "api_key");
   requireNonEmpty(state.organization_id, "organization_id");
   requireNonEmpty(state.workspace_id, "workspace_id");
   upsertProfile(state.organization_id, {
     api_key: state.api_key,
     org_name: state.organization_name,
+    // The host that minted the key, taken from the request rather than re-read:
+    // this is the whole of "which Lotics does this registration belong to".
+    api_url: pending.api_url,
     workspace_id: state.workspace_id
   });
   const existing = loadGlobalConfig() ?? {};
-  saveGlobalConfig({ ...existing, email: email3 });
+  saveGlobalConfig({ ...existing, email: pending.email });
   setActiveOrg(state.organization_id, options?.local === true ? "local" : "global");
   clearPendingLogin();
   return {
-    email: email3,
+    email: pending.email,
     orgId: state.organization_id,
     orgName: state.organization_name,
     workspaceId: state.workspace_id
@@ -79399,14 +79450,15 @@ async function claimPendingLogin() {
   const pending = loadPendingLogin();
   if (!pending) return { status: "none" };
   const expired = `The sign-in request expired. Run again:  lotics auth login ${pending.email}`;
+  const target = envApiUrl();
   if (Date.parse(pending.expires_at) <= Date.now()) {
     clearPendingLogin();
-    return pending.api_url === API_BASE_URL ? { status: "gone", message: expired } : { status: "none" };
+    return pending.api_url === target ? { status: "gone", message: expired } : { status: "none" };
   }
-  if (pending.api_url !== API_BASE_URL) return { status: "none" };
-  const state = await pollCliLogin(pending.request_id, pending.secret);
+  if (pending.api_url !== target) return { status: "none" };
+  const state = await pollCliLogin(pending.api_url, pending.request_id, pending.secret);
   if (state.status === "approved") {
-    return { status: "signed_in", account: saveApproval(state, pending.email) };
+    return { status: "signed_in", account: saveApproval(state, pending) };
   }
   if (state.status === "pending") {
     return {
@@ -79427,14 +79479,14 @@ async function awaitCliLogin(email3, options) {
   for (; ; ) {
     let state;
     try {
-      state = await pollCliLogin(pending.request_id, pending.secret);
+      state = await pollCliLogin(pending.api_url, pending.request_id, pending.secret);
     } catch (error52) {
       if (!(Date.now() < expiresAt)) throw error52;
       await new Promise((resolve2) => setTimeout(resolve2, POLL_INTERVAL_MS));
       continue;
     }
     if (state.status === "approved") {
-      return saveApproval(state, email3, options);
+      return saveApproval(state, pending, options);
     }
     if (state.status === "expired") {
       throw new Error(`That sign-in link expired. Run "lotics auth login ${email3}" again.`);
@@ -108451,8 +108503,8 @@ function prompt(question) {
     });
   });
 }
-async function publicPost(path14, body) {
-  const response = await fetch(`${API_BASE_URL}${path14}`, {
+async function publicPost(apiUrl, path14, body) {
+  const response = await fetch(`${apiUrl}${path14}`, {
     method: "POST",
     headers: { "Content-Type": "application/json" },
     body: JSON.stringify(body)
@@ -108465,7 +108517,8 @@ async function signupAccount(args) {
   if (args.name) body.name = args.name;
   const timezone = args.timezone ?? machineTimezone();
   if (timezone) body.timezone = timezone;
-  const { ok, status, data: data2 } = await publicPost("/v1/cli/signup", body);
+  const apiUrl = envApiUrl();
+  const { ok, status, data: data2 } = await publicPost(apiUrl, "/v1/cli/signup", body);
   if (!ok) {
     if (status === 409) {
       return { kind: "email_taken" };
@@ -108479,7 +108532,7 @@ async function signupAccount(args) {
   const orgId = data2.organization_id;
   const workspaceId = data2.workspace_id;
   const orgName = args.name || args.email.split("@")[0];
-  upsertProfile(orgId, { api_key: apiKey, org_name: orgName, workspace_id: workspaceId });
+  upsertProfile(orgId, { api_key: apiKey, org_name: orgName, api_url: apiUrl, workspace_id: workspaceId });
   const existing = loadGlobalConfig() ?? {};
   saveGlobalConfig({ ...existing, email: args.email });
   setActiveOrg(orgId, args.local ? "local" : "global");
@@ -108621,7 +108674,8 @@ async function handleSetup(providedKey, local) {
     console.error("No API key provided.");
     process.exit(1);
   }
-  const client = new LoticsClient({ apiKey });
+  const apiUrl = envApiUrl();
+  const client = new LoticsClient({ apiKey, apiUrl });
   let info;
   try {
     info = await client.whoami();
@@ -108647,6 +108701,7 @@ Multiple workspaces in ${info.organization_name}. Run "lotics workspace select <
   upsertProfile(info.organization_id, {
     api_key: apiKey,
     org_name: info.organization_name,
+    api_url: apiUrl,
     workspace_id: workspaceId
   });
   const existing = loadGlobalConfig() ?? {};
@@ -108684,9 +108739,9 @@ async function requireClient(flags, appWorkspaceId) {
   }
   const viewAsMemberId = flags.viewAs ?? process.env.LOTICS_VIEW_AS;
   noteScope({ org_id: ctx.orgId ?? void 0, workspace_id: ctx.workspaceId });
-  flushSpool((events) => postEvents(API_BASE_URL, ctx.apiKey, events));
+  flushSpool(ctx.apiUrl, (events) => postEvents(ctx.apiUrl, ctx.apiKey, events));
   return {
-    client: new LoticsClient({ apiKey: ctx.apiKey, workspaceId: ctx.workspaceId, viewAsMemberId }),
+    client: new LoticsClient({ apiKey: ctx.apiKey, apiUrl: ctx.apiUrl, workspaceId: ctx.workspaceId, viewAsMemberId }),
     ctx
   };
 }
@@ -108775,7 +108830,7 @@ function looksLikeModelFile(arg) {
 }
 async function main() {
   setInvocation(commandPath(process.argv.slice(2)), sessionId(), VERSION);
-  installTelemetry(startedAt);
+  installTelemetry(envApiUrl(), startedAt);
   const parsed = parseArgs(process.argv.slice(2));
   const { restArgs, flags } = parsed;
   let { command, subcommand, toolArgs } = parsed;
@@ -108995,7 +109050,7 @@ async function main() {
   if (command === "library") {
     if (subcommand === "list") {
       if (resolveContext(flags) === null) {
-        await libraryListPublic();
+        await libraryListPublic(envApiUrl());
         return;
       }
       const { client: client2, ctx: ctx2 } = await requireClient(flags);
@@ -109026,11 +109081,12 @@ async function main() {
       }
       if (flags.json) {
         setMachineOutput(true);
-        if (resolveContext(flags) === null) {
-          emitJson(await getOfficialStarter(toolArgs));
+        const shelfCtx = resolveContext(flags);
+        if (shelfCtx === null) {
+          emitJson(await getOfficialStarter(envApiUrl(), toolArgs));
           return;
         }
-        const published = await readOfficialStarter(toolArgs);
+        const published = await readOfficialStarter(shelfCtx.apiUrl, toolArgs);
         if (published.ok) {
           emitJson(published.package);
           return;
@@ -109052,7 +109108,7 @@ async function main() {
         return;
       }
       if (resolveContext(flags) === null) {
-        await libraryShowPublic(toolArgs);
+        await libraryShowPublic(envApiUrl(), toolArgs);
         return;
       }
       const { client: client2, ctx: ctx2 } = await requireClient(flags);
@@ -109173,7 +109229,7 @@ async function main() {
     }
     noteScope({ org_id: reportCtx.orgId ?? void 0, workspace_id: reportCtx.workspaceId });
     await reportCommand(
-      new LoticsClient({ apiKey: reportCtx.apiKey, workspaceId: reportCtx.workspaceId }),
+      new LoticsClient({ apiKey: reportCtx.apiKey, apiUrl: reportCtx.apiUrl, workspaceId: reportCtx.workspaceId }),
       {
         report: parsed2.report,
         version: VERSION,
@@ -109205,23 +109261,28 @@ async function main() {
         console.error('Not authenticated. Run "lotics auth signup", "lotics auth api-key <key>", or set LOTICS_API_KEY.');
         process.exit(1);
       }
-      const client2 = new LoticsClient({ apiKey: ctx2.apiKey });
+      const client2 = new LoticsClient({ apiKey: ctx2.apiKey, apiUrl: ctx2.apiUrl });
       const info = await client2.whoami();
       const existing = loadGlobalConfig() ?? {};
       saveGlobalConfig({ ...existing, email: info.email });
       const cached2 = existing.profiles?.[info.organization_id];
       if (cached2 && cached2.org_name !== info.organization_name) {
-        upsertProfile(info.organization_id, { api_key: cached2.api_key, org_name: info.organization_name });
+        upsertProfile(info.organization_id, {
+          api_key: cached2.api_key,
+          org_name: info.organization_name,
+          api_url: cached2.api_url
+        });
         console.error(`Renamed since this key was saved: "${cached2.org_name}" \u2192 "${info.organization_name}" (updated locally)`);
       }
       const viewAs = flags.viewAs ?? process.env.LOTICS_VIEW_AS;
       if (flags.json) {
-        console.log(JSON.stringify({ ...info, workspace_id: ctx2.workspaceId ?? null, source: ctx2.source, view_as: viewAs ?? null }, null, 2));
+        console.log(JSON.stringify({ ...info, workspace_id: ctx2.workspaceId ?? null, api_url: ctx2.apiUrl, source: ctx2.source, view_as: viewAs ?? null }, null, 2));
       } else {
         console.log(`Name:       ${info.name}`);
         console.log(`Email:      ${info.email}`);
         console.log(`Org:        ${info.organization_name} (${info.organization_id})`);
         console.log(`Workspace:  ${ctx2.workspaceId ?? "(none selected)"}`);
+        console.log(`API:        ${ctx2.apiUrl}`);
         console.log(`Source:     ${SOURCE_LABELS[ctx2.source]}`);
         if (viewAs) console.log(`View as:    ${viewAs} (admin preview; requires an admin key)`);
       }
@@ -109302,7 +109363,7 @@ async function main() {
     try {
       const ctx2 = resolveContext(flags, appManifestWorkspaceId(command, subcommand, void 0, flags));
       if (ctx2) {
-        client2 = new LoticsClient({ apiKey: ctx2.apiKey, workspaceId: ctx2.workspaceId });
+        client2 = new LoticsClient({ apiKey: ctx2.apiKey, apiUrl: ctx2.apiUrl, workspaceId: ctx2.workspaceId });
         await resolveWorkspace(client2, ctx2);
       }
     } catch (err2) {
@@ -109323,7 +109384,7 @@ async function main() {
     }
     applyAppManifestWorkspace(ctx2, command, subcommand, projectDir, flags);
     const viewAsMemberId = flags.viewAs ?? process.env.LOTICS_VIEW_AS;
-    const client2 = new LoticsClient({ apiKey: ctx2.apiKey, workspaceId: ctx2.workspaceId, viewAsMemberId });
+    const client2 = new LoticsClient({ apiKey: ctx2.apiKey, apiUrl: ctx2.apiUrl, workspaceId: ctx2.workspaceId, viewAsMemberId });
     await resolveWorkspace(client2, ctx2);
     await appCodegen({ projectDir, client: client2 });
     return;
@@ -109353,7 +109414,11 @@ async function main() {
           console.error("Note: a local pin (.lotics/config.json) overrides the global default in this directory. Use --local to change the pin here.");
         }
       }
-      await validateOrgWorkspacePin(new LoticsClient({ apiKey: profile.api_key }), orgId, profile);
+      await validateOrgWorkspacePin(
+        new LoticsClient({ apiKey: profile.api_key, apiUrl: profile.api_url }),
+        orgId,
+        profile
+      );
       return;
     }
     if (subcommand && subcommand !== "list") {
@@ -109372,6 +109437,7 @@ async function main() {
         orgIds.map((id) => ({
           org_id: id,
           org_name: profiles[id].org_name,
+          api_url: profiles[id].api_url,
           workspace_id: profiles[id].workspace_id ?? null,
           active: id === effectiveActive
         })),
@@ -109381,7 +109447,7 @@ async function main() {
     } else {
       for (const id of orgIds) {
         const marker = id === effectiveActive ? " (active)" : "";
-        console.log(`${id}  ${profiles[id].org_name}${marker}`);
+        console.log(`${id}  ${profiles[id].org_name}  ${profiles[id].api_url}${marker}`);
       }
     }
     return;
@@ -109414,7 +109480,7 @@ async function main() {
     console.error("  lotics app workflow pull                  Rewrite src/workflows/*.ts from the server");
     console.error("  lotics app workflow check [alias]         Typecheck src/workflows bodies locally");
     console.error("  lotics app query set <alias>              Push lotics.queries.<alias> to apps.queries (no deploy)");
-    console.error("  lotics app subdomain <new-subdomain> Rename the app's public <slug>.lotics.app address");
+    console.error("  lotics app subdomain <new-subdomain> Rename the app's public address (its subdomain)");
     console.error(`  lotics app rename "<new name>"        Rename the app's display name (launcher title)`);
     console.error("  lotics app dev [path]                Run the app locally with HMR + RPC forwarding");
     process.exit(1);
@@ -109634,7 +109700,7 @@ Available workspaces:`);
       const newSubdomain = toolArgs;
       if (!newSubdomain) {
         console.error("Usage: lotics app subdomain <new-subdomain>");
-        console.error("Renames the app's public address \u2014 https://<slug>.lotics.app");
+        console.error("Renames the app's public address \u2014 its subdomain under the apps domain");
         process.exit(1);
       }
       await appSetSubdomain(client, { subdomain: newSubdomain });

package/dist/src/client.d.ts

@@ -21,6 +21,11 @@ export interface AppQueryFilterGroup {
 export type AppQueryFilter = AppQueryFilterCondition | AppQueryFilterGroup;
 export interface LoticsClientOptions {
     apiKey: string;
+    /** The Lotics this key belongs to — `ResolvedContext.apiUrl`, which is the
+     *  registration's own `api_url`. Required and never defaulted: a client that
+     *  can fall back to an ambient host is a client that can send a private
+     *  instance's key to production (`docs/on_premise.md` section 8). */
+    apiUrl: string;
     workspaceId?: string;
     /** Admin "View as": when set, every request carries `x-view-as-member-id`, so
      *  the backend evaluates IAM scoping (and `is_current_member`) as this member.
@@ -342,7 +347,6 @@ export declare class LoticsRequestError extends Error {
     readonly body: Record<string, unknown>;
     constructor(message: string, status: number, body: Record<string, unknown>);
 }
-export declare const API_BASE_URL: string;
 /**
  * The website: where a person goes when the CLI cannot finish the job, and where
  * the presets are SERVED FROM. Held beside the API base so the pair is read
@@ -379,7 +383,7 @@ export interface OfficialStarter {
  * starter for what I do, or should I build?" is decided before an account
  * exists, so needing one to ask means signing up to find out the answer was no.
  */
-export declare function fetchOfficialStarters(): Promise<OfficialStarter[]>;
+export declare function fetchOfficialStarters(apiUrl: string): Promise<OfficialStarter[]>;
 /**
  * One keyless GET of JSON, bounded — the shape every read that predates an
  * account takes.
@@ -419,7 +423,7 @@ export declare function getPublicJson(url: string, what: string): Promise<{
  * throws: "unreachable" is not "not on the shelf", and answering both the same
  * way would tell an owner their package is missing every time the link drops.
  */
-export declare function readOfficialStarter(starter_id: string): Promise<{
+export declare function readOfficialStarter(apiUrl: string, starter_id: string): Promise<{
     ok: true;
     package: OfficialStarterRead;
 } | {
@@ -427,7 +431,7 @@ export declare function readOfficialStarter(starter_id: string): Promise<{
     status: number;
 }>;
 /** The same read for a caller with nothing to fall back to — a refusal is the end. */
-export declare function getOfficialStarter(starter_id: string): Promise<OfficialStarterRead>;
+export declare function getOfficialStarter(apiUrl: string, starter_id: string): Promise<OfficialStarterRead>;
 /** A column as the public read shows it: enough to write a model field from. */
 export interface OfficialStarterField {
     alias: string;
@@ -524,8 +528,8 @@ export type CliLoginState = {
  * The same answer whether or not the address has an account: it would
  * otherwise tell any stranger which emails are registered here.
  */
-export declare function startCliLogin(email: string): Promise<CliLoginRequest>;
-export declare function pollCliLogin(request_id: string, secret: string): Promise<CliLoginState>;
+export declare function startCliLogin(apiUrl: string, email: string): Promise<CliLoginRequest>;
+export declare function pollCliLogin(apiUrl: string, request_id: string, secret: string): Promise<CliLoginState>;
 export declare class LoticsClient {
     private apiKey;
     private workspaceId;
@@ -533,8 +537,8 @@ export declare class LoticsClient {
      *  construction — surfaced so `lotics app dev` can show it in the banner. */
     readonly viewAsMemberId: string | undefined;
     /** API URL the client is configured against. Read-only after construction.
-     *  Surfaced for callers that need to display or log it (e.g., `lotics app dev`
-     *  shows it in the banner). */
+     *  Surfaced for callers that need to display it (`lotics app dev`'s banner) or
+     *  to hand it on (the wrapper page's RPC target, the scaffold's font proxy). */
     readonly baseUrl: string;
     constructor(options: LoticsClientOptions);
     private throwResponseError;
@@ -987,13 +991,15 @@ export declare class LoticsClient {
         }>;
     }>>;
     /**
-     * Rename an app's public subdomain — its `<slug>.lotics.app` address.
-     * Mirrors PUT /v1/apps/{app_id}/subdomain. The old subdomain stops
-     * resolving once the change lands.
+     * Rename an app's public subdomain — the label its origin is built on.
+     * Mirrors PUT /v1/apps/{app_id}/subdomain, and returns the finished `origin`
+     * because only the instance knows the domain and scheme it serves apps on.
+     * The old subdomain stops resolving once the change lands.
      */
     setAppSubdomain(app_id: string, public_subdomain: string): Promise<{
         app_id: string;
         public_subdomain: string;
+        origin: string;
     }>;
     getAppVersion(app_id: string, version_id: string): Promise<{
         id: string;

package/dist/src/client.js

@@ -149,10 +149,9 @@ var LoticsRequestError = class extends Error {
   status;
   body;
 };
-var API_BASE_URL = process.env.LOTICS_API_URL ?? "https://api.lotics.ai";
 var WEB_APP_URL = process.env.LOTICS_WEB_URL ?? "https://lotics.ai";
-async function fetchOfficialStarters() {
-  const read = await getPublicJson(`${API_BASE_URL}/v1/starters/official`, "list the packages");
+async function fetchOfficialStarters(apiUrl) {
+  const read = await getPublicJson(`${apiUrl}/v1/starters/official`, "list the packages");
   if (!read.ok) {
     throw new Error(
       `Lotics answered ${read.status} listing the packages. If this keeps happening, browse ${WEB_APP_URL}/docs/cli.`
@@ -172,16 +171,16 @@ async function getPublicJson(url, what) {
   if (!response.ok) return { ok: false, status: response.status };
   return { ok: true, body: await response.json() };
 }
-async function readOfficialStarter(starter_id) {
+async function readOfficialStarter(apiUrl, starter_id) {
   const read = await getPublicJson(
-    `${API_BASE_URL}/v1/starters/official/${encodeURIComponent(starter_id)}`,
+    `${apiUrl}/v1/starters/official/${encodeURIComponent(starter_id)}`,
     `read ${starter_id}`
   );
   if (!read.ok) return read;
   return { ok: true, package: read.body };
 }
-async function getOfficialStarter(starter_id) {
-  const read = await readOfficialStarter(starter_id);
+async function getOfficialStarter(apiUrl, starter_id) {
+  const read = await readOfficialStarter(apiUrl, starter_id);
   if (!read.ok) {
     throw new Error(
       `Lotics answered ${read.status} reading ${starter_id}. Only packages Lotics publishes can be read without an account.`
@@ -190,10 +189,10 @@ async function getOfficialStarter(starter_id) {
   return read.package;
 }
 var PUBLIC_FETCH_TIMEOUT_MS = 1e4;
-async function startCliLogin(email) {
+async function startCliLogin(apiUrl, email) {
   let response;
   try {
-    response = await fetch(`${API_BASE_URL}/v1/cli/login_requests`, {
+    response = await fetch(`${apiUrl}/v1/cli/login_requests`, {
       method: "POST",
       headers: { "Content-Type": "application/json" },
       body: JSON.stringify({ email }),
@@ -209,8 +208,8 @@ async function startCliLogin(email) {
   }
   return await response.json();
 }
-async function pollCliLogin(request_id, secret) {
-  const url = `${API_BASE_URL}/v1/cli/login_requests/${encodeURIComponent(request_id)}`;
+async function pollCliLogin(apiUrl, request_id, secret) {
+  const url = `${apiUrl}/v1/cli/login_requests/${encodeURIComponent(request_id)}`;
   let response;
   try {
     response = await fetch(url, {
@@ -237,14 +236,14 @@ var LoticsClient = class {
    *  construction — surfaced so `lotics app dev` can show it in the banner. */
   viewAsMemberId;
   /** API URL the client is configured against. Read-only after construction.
-   *  Surfaced for callers that need to display or log it (e.g., `lotics app dev`
-   *  shows it in the banner). */
+   *  Surfaced for callers that need to display it (`lotics app dev`'s banner) or
+   *  to hand it on (the wrapper page's RPC target, the scaffold's font proxy). */
   baseUrl;
   constructor(options) {
     this.apiKey = options.apiKey;
     this.workspaceId = options.workspaceId;
     this.viewAsMemberId = options.viewAsMemberId;
-    this.baseUrl = API_BASE_URL;
+    this.baseUrl = options.apiUrl;
   }
   /**
    * The id is appended to the MESSAGE rather than carried on a field, because
@@ -647,9 +646,10 @@ var LoticsClient = class {
     return tables.filter((t) => t !== null);
   }
   /**
-   * Rename an app's public subdomain — its `<slug>.lotics.app` address.
-   * Mirrors PUT /v1/apps/{app_id}/subdomain. The old subdomain stops
-   * resolving once the change lands.
+   * Rename an app's public subdomain — the label its origin is built on.
+   * Mirrors PUT /v1/apps/{app_id}/subdomain, and returns the finished `origin`
+   * because only the instance knows the domain and scheme it serves apps on.
+   * The old subdomain stops resolving once the change lands.
    */
   async setAppSubdomain(app_id, public_subdomain) {
     return this.request(
@@ -1161,7 +1161,6 @@ var LoticsClient = class {
   }
 };
 export {
-  API_BASE_URL,
   LoticsClient,
   LoticsRequestError,
   WEB_APP_URL,

package/docs/cli_reference.md

@@ -7,11 +7,11 @@ Per-command syntax, flags, contracts, and gotchas for the public `lotics` CLI. S
 | `lotics` / `lotics --help` | Show full help with capabilities, tool categories, workflow |
 | `lotics auth signup <email>` | Create account + org + API key, sends magic link email. Registers the new org as a profile; `--local` pins this directory to it (pointer) instead of setting the global default. |
 | `lotics auth login <email>` | Sign in an account that already exists, on a machine holding no key. **Two steps, and it does not wait for the person.** The first prints the page to open — `https://lotics.ai/cli_login/<request_id>`, also mailed — and the code that page must show, records the request, and exits 0. They sign in there if asked, check the code and press Confirm. **Then the next command that needs a credential collects the key** before it does its own work, so the second step is just re-running whatever was wanted; a command run before Confirm exits 1 naming the page and the code again, and once the 15 minutes are up it says to ask again. The handful that run WITHOUT a credential — `library list`/`show`, `scaffold docs`/`check`, `app codegen`, `app workflow check` — claim nothing, so one of those run after Confirm still answers as though signed out. `--wait` keeps one command instead, holding the terminal until Confirm; `--local` pins this directory to that org rather than setting the global default, and implies `--wait` (a pin names THIS directory, so only the terminal that stays in it can write one). `--json` prints `organization_id`, `workspace_id` and `organization_name` when it finishes signed in, and `request_id`, `confirm_url`, `code`, `email`, `expires_at` when it is the first step. The request's secret is never printed and the org's key never leaves the store. |
-| `lotics auth api-key [key]` | `whoami` → **upsert** the key's org as a profile in the global store (never overwrites). `--local` additionally pins this directory to it (pointer) instead of setting the global default. |
+| `lotics auth api-key [key]` | `whoami` → **upsert** the key's org as a profile in the global store (never overwrites). The profile records the instance the key was verified against (`LOTICS_API_URL`, default `https://api.lotics.ai`), and every later command for that org goes there. `--local` additionally pins this directory to it (pointer) instead of setting the global default. |
 | `lotics auth web` | Send a magic link email to access the web app (requires auth) |
-| `lotics auth whoami` | Print active account name, email, org, resolved workspace, and the resolution **source** (flag/env/local/app-manifest/global). `--json` adds `workspace_id` + `source`. |
+| `lotics auth whoami` | Print active account name, email, org, resolved workspace, the instance the credential belongs to, and the resolution **source** (flag/env/local/app-manifest/global). `--json` adds `workspace_id`, `api_url` + `source`. |
 | `lotics auth logout [<name\|id>]` | In a pinned dir: delete the local pin. Else: remove one profile (default the active org). `--all`: wipe the global store. |
-| `lotics org` | List saved orgs (profiles) from the global store, marks active for this directory (a local pin wins over the global default). |
+| `lotics org` | List saved orgs (profiles) from the global store with the instance each belongs to, marks active for this directory (a local pin wins over the global default). |
 | `lotics org use <name\|id> [--local]` | Switch the active org by org name (case-insensitive, ambiguous → error) or id. No flag → global `active_org`; `--local` → a `.lotics/config.json` pointer in the current dir. |
 | `lotics workspace` | List workspaces in the active org, marks current with `(current)` |
 | `lotics workspace select <id>` | Set the workspace in the **active scope** — a local pin if the dir has one, else the active org's global profile |
@@ -61,7 +61,7 @@ Per-command syntax, flags, contracts, and gotchas for the public `lotics` CLI. S
 | `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 pushes a DRIFTED declaration through this same verb before it ships (see `app deploy`), so this is the explicit single-alias path, not the only way a query reaches the app. 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. **The declaration's fields MERGE**, so the manifest is not a snapshot: deleting `params` from an alias and pushing leaves the live params exactly where they were, because an absent key means "unchanged". Clear one with `params: null`, or replace the map with the set you want. After the push it regenerates `.lotics/app_queries.d.ts` from the manifest, so the types the next `npm run typecheck` reads match what was just pushed. |
 | `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) 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. 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, 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 (naming `lotics app codegen`, which refreshes types WITHOUT touching the body — a pull would overwrite it). **It also keeps the types honest.** Each alias's `.lotics/workflows/<alias>.globals.d.ts` carries a `// lotics:declaration <hash>` stamp of the manifest declaration it was rendered from; `check` compares it to `package.json#lotics.workflows.<alias>` and, when they differ, re-renders that alias's dts from the LOCAL declaration before compiling. Without it the verdict was confidently wrong in the exact case an author needs it — declare an input, run `check`, and get `TS2339: Property 'x' does not exist` pointing at your body for a schema the types have never been told about. The server renders a dts from a SUPPLIED declaration, so this works before the manifest has ever been deployed, which is when it matters (the order is edit → check → set). This is the ONE thing `check` uses the API for: it is skipped entirely when the stamps match (the common case, so `check` stays instant and offline), and with no credentials or a failed fetch it WARNS and checks against the older types rather than blocking. A file written before the stamp existed reads as unknown, never as matching, so a pre-existing checkout heals on its first run. |
-| `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 subdomain <new-subdomain>` | Rename the app's public address under the instance's apps domain via `PUT /v1/apps/{id}/subdomain`. app_id comes from the local `package.json` manifest; the chosen slug must be a valid DNS label and free; the old address stops resolving. |
 | `lotics app rename "<new name>"` | Change the app's display name (launcher/title) via the `update_app` tool. app_id comes from the local `package.json` manifest; the public address (`subdomain`) and code (`deploy`) are unchanged. |
 | `lotics app dev [path] [--port=N] [--vite-port=N] [--view-as=<member_id>]` | Spawn Vite dev server + an RPC-forwarding HTTP server. The wrapper page embeds the iframe with `sandbox="allow-scripts allow-same-origin"` matching production; postMessage ops (query / workflow / members / context / upload / openExternal / urlState / agentRun) are forwarded to api.lotics.ai using the CLI's API key — file bytes move in **both** directions through the dev server's own relays, never browser↔storage: dev runs against the PROD bucket, whose CORS admits `https://*.lotics.app` and not `http://localhost:<port>`, so a direct browser transfer is blocked — no upload could complete and no preview engine (PDF/Word/Excel all FETCH the bytes) could read a file. `upload` mints a presigned URL and PUTs it **to `PUT /_upload/<file_id>`** (`dev/upload_relay.ts`) from the wrapper page — same-origin, so no preflight and no CORS — and Node forwards it on; every presigned `url`/`thumbnail_url`/`preview_url` on a **file object** in an RPC result is rewritten to **`GET /_file/<token>`** (`dev/file_relay.ts`, absolute — the iframe would resolve a relative path against Vite), which streams the bytes back with `Range` passthrough (206s intact, so PDF seeking works) and an `Access-Control-Allow-Origin` for the Vite origin (the one cross-origin hop left is OUR response to allow). Neither relay ever takes a destination from the client — it gets a `file_id`/token and transfers only to/from a URL it minted or observed itself, so there is no client-controlled target and no SSRF surface. A URL in a record's own text cell is NOT rewritten. Production is unchanged (direct-to-storage, no bytes through the API server); `openExternal` and `urlState.get/set` are handled locally (the latter read/write the wrapper page's own address bar — `set` writes in place via `replaceState` and browser back/forward broadcast a `url-state` message back, so `useUrlState` survives refresh and is shareable in the dev loop; in-app *routing* is the app's own (the iframe owns its url via `@lotics/app-sdk/router`), and the wrapper bakes the saved screen (`_loc`) into the iframe src on load so a refresh restores it, mirroring production); `agentRun` (streaming) is proxied through `POST /_agent_run`, which opens the run's SSE with the CLI key and pipes chunks back to the iframe (`stream-chunk`* → `stream-end`), so `useAgentRun` works in the dev loop just like production; `context` resolves the viewer (`member_id` from `cli/whoami` + `comments_enabled` from the local manifest) and fetches the app's stored `config` live from the app row, so `useConfig()` renders the same values as production. `--view-as` (global flag; also `LOTICS_VIEW_AS`) threads `x-view-as-member-id` so `is_current_member` + `context` resolve to that member — **admin key only** (the server 403s a non-admin), writes stay attributed to the key owner. Hot reload via Vite; full DevTools / Playwright access via plain localhost. **Every forwarded op logs one line naming its ALIAS** — `[rpc] query applicants 231ms` — and `query applicants (count)` for a count request, which is a SECOND full execution of the same query rather than a cheap lookup. When requests overlap the line carries `· N in flight`. That number is the one to watch: the server bounds how many app queries run at once, so requests past the bound wait and the wait lands inside each request's own duration — a burst reads as "every query got slower", which looks like a slow database and is not one. A screen firing its list plus three facet counts on one keystroke shows up here as eight lines over one or two aliases; see `@lotics/app-sdk` `docs/data_fetching.md` (`useCount`, and handing `usePaginatedQuery` a `total`) and `docs/queries.md` §10 for collapsing them. **Holds no realtime connection** — push belongs to the product frontend, so an app previewed here never updates on an external write (a CLI run, another tab, an agent): reload to see it. Deliberate rather than missing, since the alternative is a second implementation of the channel in the wrapper page, and a blanket poll here would hide an app whose queries do not declare their tables — the one mistake the real host punishes. The startup banner says `realtime: off` so this is visible without reading this table. The scaffold's `vite.config.ts` carries no dev-optimizer list: @lotics/ui ships built ESM, so Vite's own dep scanner reaches its CJS-interop imports and pre-bundles them without being told to. Binds **loopback only** (`127.0.0.1`) — `/_rpc` dispatches with the developer's API key, so a socket on every interface would hand anyone on the network full read/write on the workspace. |
 | `LOTICS_UI_SRC=<abs path to packages/ui/src>` (env, not a command) | Dev-link `@lotics/ui` to a monorepo checkout for the length of ONE command, **for every tool at once**. The app's `vite.config.ts` gets its whole `resolve` block from the kit (`resolve: loticsResolve()` — `@lotics/ui/vite`), which reads the variable at call time and adds the `@lotics/ui/*` → working-copy alias, so kit edits go live under `lotics app dev` (HMR) and bundle under `lotics app deploy`. In the same breath, every command that regenerates types (`create`/`pull`/`dev`/`deploy`/`codegen`, all via `writeAppDts`) writes **`.lotics/tsconfig.link.json`** — the matching `paths`, which the app's `tsconfig.json` `extends` — so `tsc`, vitest, eslint and your EDITOR resolve the same copy Vite does. Unset ⇒ every one of them goes back to `node_modules`, and the generated file is rewritten inert. **Why `paths` and not `npm link`:** under the dev-link a kit file sits OUTSIDE the app's `node_modules` and resolves its OWN `react` from the monorepo — two copies in one program and every shared type stops matching ("Two different types with this name exist, but they are unrelated"). The generated file therefore also pins every peer @lotics/ui declares to the APP's copy, types-package first (`react` → `@types/react`; pinning the runtime package instead strands tsc on a `.js` with no declarations). The pin set is derived from the installed kit's `peerDependencies`, so it tracks the kit rather than rotting. **Nothing hand-written is touched** — the generated file lives in `.lotics/` (the CLI's own dir) and no config is edited by regex. Identical for a monorepo app and an EXTERNAL one (e.g. `~/lotics_apps`). `app deploy` still warns whenever the variable is set — that the bundle carries kit code from your working copy, or that the app's config predates `loticsResolve()` and never reads it, so the PUBLISHED kit is going out. An app whose `tsconfig.json` already `extends` something else is told rather than rewritten: add `./.lotics/tsconfig.link.json` to the array yourself. |

package/package.json

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