@lotics/cli 0.204.0 → 0.205.1

package/dist/src/cli.js

@@ -14940,10 +14940,12 @@ var LoticsClient = class {
       body = {};
     }
     const message2 = typeof body.message === "string" ? body.message : text;
+    const hint = typeof body.hint === "string" ? `
+  ${body.hint}` : "";
     const trace = requestId === void 0 ? "" : `
 
   Request id: ${requestId} \u2014 quote this to Lotics support.`;
-    throw new LoticsRequestError(`${response.status}: ${message2}${trace}`, response.status, body);
+    throw new LoticsRequestError(`${response.status}: ${message2}${hint}${trace}`, response.status, body);
   }
   /**
    * The backend's `log()` middleware registers `user-agent`,
@@ -14993,9 +14995,23 @@ var LoticsClient = class {
     if (!response.ok) await this.throwResponseError(response, headers["x-request-id"]);
     return response.json();
   }
+  /** `email` is null for a credential no person signs in as; `account_type` is absent from an older server. */
+  /** `credential_origin` describes the CREDENTIAL this call carried, not the
+   *  member above: `sign_in` for a terminal somebody signed in from, `api_key`
+   *  for one an admin issued. Null for a row minted before it was recorded, and
+   *  absent from an older server — both mean not told. */
   async whoami() {
     return this.request("GET", "/v1/cli/whoami");
   }
+  /**
+   * Hand this client's own credential back — what `lotics auth logout` calls
+   * before it forgets the key, so signing out ends the credential instead of
+   * leaving a live one on a server nobody can see it from. Takes no id: the
+   * only thing it can revoke is the key these requests carry.
+   */
+  async revokeSelfCredential() {
+    return this.request("DELETE", "/v1/api_keys/self");
+  }
   /**
    * File a hand-written report, or a list of them in one call. Unlike a
    * telemetry flush, the headers this stamps are CORRECT: the invocation making
@@ -15191,8 +15207,12 @@ var LoticsClient = class {
    * provenance is a 400, and one already on the latest release a 409 — both
    * refusals, both before any write. Admin-only.
    */
-  async upgradeApp(app_id) {
-    return this.request("POST", `/v1/apps/${encodeURIComponent(app_id)}/upgrade`, {});
+  async upgradeApp(app_id, opts = {}) {
+    return this.request(
+      "POST",
+      `/v1/apps/${encodeURIComponent(app_id)}/upgrade`,
+      opts.acknowledge_breaking_api_change ? { acknowledge_breaking_api_change: true } : {}
+    );
   }
   /**
    * Capture live records from this workspace as a starter's sample data.
@@ -15386,6 +15406,36 @@ var LoticsClient = class {
       { public_subdomain }
     );
   }
+  /**
+   * Publish the app's API — the owner's promise about what its declared queries
+   * and workflows return to a caller outside the app.
+   *
+   * Snapshots the contract and answers the version it took, plus what the
+   * published surface exposes that the owner may not have intended. A query
+   * that does not name its columns is refused (400) before anything is written:
+   * the app cannot promise field names it never stated.
+   */
+  async publishAppApi(app_id) {
+    return this.request("POST", `/v1/apps/${encodeURIComponent(app_id)}/api/publish`, {});
+  }
+  /** End the promise. `unpublished: false` means the app was publishing nothing,
+   *  which this leaves unchanged. The superseded snapshot stays, so a later
+   *  publish continues the numbering rather than reusing a version. */
+  async unpublishAppApi(app_id) {
+    return this.request("DELETE", `/v1/apps/${encodeURIComponent(app_id)}/api/publish`);
+  }
+  /** Whether the app is publishing an API, and which contract version. */
+  async getAppApiPublication(app_id) {
+    return this.request("GET", `/v1/apps/${encodeURIComponent(app_id)}/api/publication`);
+  }
+  /**
+   * The published API as an OpenAPI 3.1 document — what a consumer's own
+   * generator reads. Rendered from the live SNAPSHOT rather than the manifest,
+   * so it describes what the app has promised; 404 while nothing is published.
+   */
+  async getAppOpenApiDocument(app_id) {
+    return this.request("GET", `/v1/apps/${encodeURIComponent(app_id)}/openapi.json`);
+  }
   async getAppVersion(app_id, version_id) {
     return this.request(
       "GET",
@@ -15475,7 +15525,10 @@ var LoticsClient = class {
       ...body.outputs ? { outputs: body.outputs } : {},
       ...body.name ? { name: body.name } : {},
       ...body.description ? { description: body.description } : {},
-      ...body.expected_body_sha ? { expected_body_sha: body.expected_body_sha } : {}
+      ...body.expected_body_sha ? { expected_body_sha: body.expected_body_sha } : {},
+      // Sent only when the caller asked for it: absent means "refuse a break",
+      // which is the answer a caller who said nothing gave.
+      ...body.acknowledge_breaking_api_change ? { acknowledge_breaking_api_change: true } : {}
     });
   }
   /**
@@ -15486,12 +15539,13 @@ var LoticsClient = class {
    * deploy validates the manifest. Note: `apps.queries` is manifest-authoritative,
    * so the next `lotics app deploy` overwrites this from the manifest.
    */
-  async setAppQuery(app_id, alias, declaration, expected_sha) {
+  async setAppQuery(app_id, alias, declaration, expected_sha, acknowledge_breaking_api_change) {
     return this.execute("set_app_query", {
       app_id,
       alias,
       declaration,
-      ...expected_sha ? { expected_sha } : {}
+      ...expected_sha ? { expected_sha } : {},
+      ...acknowledge_breaking_api_change ? { acknowledge_breaking_api_change: true } : {}
     });
   }
   /**
@@ -15694,16 +15748,12 @@ var LoticsClient = class {
     formData.append("workflow_aliases", JSON.stringify(args.workflow_aliases ?? []));
     formData.append("agent_aliases", JSON.stringify(args.agent_aliases ?? []));
     formData.append("query_aliases", JSON.stringify(args.query_aliases ?? []));
+    if (args.acknowledge_breaking_api_change) {
+      formData.append("acknowledge_breaking_api_change", "true");
+    }
     const url2 = `${this.baseUrl}/v1/apps/${encodeURIComponent(args.app_id)}/versions`;
     const headers = this.buildHeaders();
     const response = await fetch(url2, { method: "POST", headers, body: formData });
-    if (response.status === 409) {
-      const conflict = await response.json();
-      const err = new Error(conflict.message ?? "Deploy conflict \u2014 pull required");
-      err.code = "VERSION_CONFLICT";
-      err.current_version_id = conflict.current_version_id ?? null;
-      throw err;
-    }
     if (!response.ok) {
       await this.throwResponseError(response, headers["x-request-id"]);
     }
@@ -16432,6 +16482,7 @@ function upsertProfile(orgId, fields) {
   const workspace_id = fields.workspace_id ?? existing?.workspace_id;
   const profile = {
     api_key: fields.api_key,
+    kind: fields.kind,
     org_name: existing?.org_name ?? fields.org_name,
     ...existing?.server_name === void 0 ? {} : { server_name: existing.server_name },
     api_url: fields.api_url,
@@ -34139,6 +34190,9 @@ function capabilityDescriptionRefusal(kind, alias, description) {
   const plural = kind === "query" ? "queries" : "workflows";
   return `${noun} alias "${alias}" description is ${description.length} characters \u2014 the cap is ${MAX_APP_CAPABILITY_DESCRIPTION}. It is a one-line summary an agent reads when choosing between this app's ${plural}; longer guidance belongs in the agent's own instructions.`;
 }
+var APP_ANONYMOUS_REQUEST_MAX_BYTES = 256 * 1024;
+var PUBLIC_APP_UPLOAD_BYTES_LIMIT = 500 * 1024 * 1024;
+var PUBLIC_APP_UPLOAD_BYTES_WINDOW_SECONDS = 60 * 60;
 var appWorkflowDeclarationSchema = zod_default.object({
   workflow_id: zod_default.string().describe("ID of the workflow this alias resolves to"),
   inputs: zod_default.record(zod_default.string(), appWorkflowInputSchema).optional().describe(
@@ -34249,6 +34303,9 @@ var appSchema = zod_default.object({
     "Alias \u2192 agent declaration map. Each alias binds a streaming tool-loop agent the app runs via `useAgentRun(alias)` (an SSE stream), with declared tools, model, and typed inputs/outputs. Synced from the app's `lotics.agents` manifest on every deploy. The agent runs under the app's IAM principal; runs persist a flat history per session."
   ),
   theme: appThemeSchema.nullable().optional().describe("Theme settings for the app"),
+  can_author: zod_default.boolean().optional().describe(
+    "Whether the caller may author this app \u2014 open a draft, edit its source, publish it. True for the app's owner and for an organization admin. A `manager` share is not authoring: it manages the app under its owner's authority, which is somebody else's. Optional because an older server omits it \u2014 absent means that server's rule, an organization admin."
+  ),
   /**
    * The starter this app is the ORIGIN of, when it is one — list enrichment,
    * read from the registry rather than stored on the app.
@@ -40054,7 +40111,7 @@ function resultSideEffects(result) {
 }
 
 // src/version.ts
-var VERSION = "0.204.0";
+var VERSION = "0.205.1";
 
 // src/timezone.ts
 function machineTimezone() {
@@ -40631,6 +40688,11 @@ var COMMANDS = [
       "                                       --prune-invoked <alias> unbinds a workflow the",
       "                                       workspace has already RUN \u2014 named per alias, only",
       "                                       when you know that caller is gone)",
+      "         [--acknowledge-breaking-api]  \u2026 even though it breaks what the app's published API",
+      "                                       promises. Without it such a release is refused and",
+      "                                       every breaking change is named. It counts only from",
+      "                                       an organization admin. Same flag on app query set,",
+      "                                       app workflow set and app upgrade",
       "  lotics app versions [app_id]         Show deploy history newest-first (version,",
       "                                       timestamp, deployer, build status, -m message;",
       "                                       * marks the currently served version)",
@@ -40643,6 +40705,23 @@ var COMMANDS = [
       "                                       Already on the latest version says so and does",
       "                                       nothing; an app nobody copied has no package to",
       "                                       offer one",
+      "  lotics app api publish [app_id]      Publish the app's API \u2014 the promise its declared",
+      "                                       queries and workflows make to a caller outside it",
+      "                                       (a customer's own site or server), snapshotted as a",
+      "                                       contract version. Prints that version, when it was",
+      "                                       taken, and what the published surface exposes. A",
+      "                                       query that does not name the columns it returns is",
+      "                                       refused: those field names are not the app's to keep",
+      "  lotics app api unpublish [app_id]    End the promise. A later publish continues the",
+      "                                       numbering rather than reusing a version",
+      "  lotics app api status [app_id]       Whether an API is published, and which contract",
+      "                                       version its callers hold",
+      "  lotics app api spec [app_id] [-o <file.json>]",
+      "                                       The OpenAPI document of the published API, rendered",
+      "                                       from the snapshot \u2014 what a consumer's own generator",
+      "                                       reads. To stdout, or to the file named",
+      "         [--json]                      publish / unpublish / status answer with one object",
+      "                                       on stdout and nothing else; every warning rides in it",
       "  lotics app codegen [path]            Regenerate .lotics/* (types + field/option ids)",
       "                                       from the manifest + workspace schema \u2014 no deploy",
       "  lotics app check [--screens]         Run every deploy pre-flight WITHOUT building or",
@@ -44763,7 +44842,9 @@ function warn(text) {
   console.error(text);
 }
 function emitJson(value) {
-  const payload = collectedWarnings.length > 0 ? { ...value, warnings: [...collectedWarnings] } : value;
+  const own = "warnings" in value && Array.isArray(value.warnings) ? value.warnings : [];
+  const warnings = [...collectedWarnings, ...own];
+  const payload = warnings.length > 0 ? { ...value, warnings } : value;
   collectedWarnings.length = 0;
   console.log(JSON.stringify(payload, null, 2));
 }
@@ -46228,6 +46309,12 @@ function deepLinkLoc(pathname, search) {
   if (pathname === "/" || pathname === "/index.html") return null;
   return pathname + search;
 }
+function devRpcFailure(op, id, message2, field_errors) {
+  if (op !== "workflow") return { id, type: "error", message: message2 };
+  var data = { status: "error", message: message2 };
+  if (field_errors) data.field_errors = field_errors;
+  return { id, type: "result", data };
+}
 function buildWrapperPage(args) {
   const { app_name, app_id, workspace_id, vite_url, api_url, web_app_url } = args;
   return `<!doctype html>
@@ -46302,6 +46389,10 @@ function buildWrapperPage(args) {
       appSrc.searchParams.set("lotics_host", window.location.origin);
       iframe.src = appSrc.toString();
 
+      // What a failed op is posted back as \u2014 resolve-vs-reject, per op, the way
+      // both deployed transports settle it.
+      var devRpcFailure = (${devRpcFailure.toString()});
+
       async function rpc(op, payload) {
         const res = await fetch("/_rpc", {
           method: "POST",
@@ -46310,9 +46401,13 @@ function buildWrapperPage(args) {
         });
         const text = await res.text();
         if (!res.ok) {
-          let detail = text;
-          try { detail = JSON.parse(text).message ?? text; } catch (_) {}
-          throw new Error(detail || ("HTTP " + res.status));
+          // The server relays the API's own error envelope, so the refusal's
+          // code and the inputs it named survive to the app (see rpcFailureBody).
+          let detail = text, body = null;
+          try { body = JSON.parse(text); detail = body.message ?? text; } catch (_) {}
+          const err = new Error(detail || ("HTTP " + res.status));
+          if (body) { err.code = body.code; err.field_errors = body.field_errors; }
+          throw err;
         }
         return JSON.parse(text);
       }
@@ -46521,9 +46616,9 @@ function buildWrapperPage(args) {
           );
         } catch (err) {
           const message = err && err.message ? err.message : String(err);
-          console.error("[lotics-dev] " + msg.op + " failed:", message);
+          console.error("[lotics-dev] " + msg.op + " failed:", (err && err.code ? err.code + " \u2014 " : "") + message);
           iframe.contentWindow.postMessage(
-            { id: msg.id, type: "error", message: message },
+            devRpcFailure(msg.op, msg.id, message, err && err.field_errors),
             VITE_ORIGIN
           );
         }
@@ -46646,6 +46741,18 @@ var STOP_DEADLINE_MS = 2e3;
 function serializeRpcResult(result) {
   return JSON.stringify(result ?? null);
 }
+function rpcFailureBody(err) {
+  const message2 = err instanceof Error ? err.message : String(err);
+  if (!(err instanceof LoticsRequestError)) return { message: message2 };
+  const code = err.body.code;
+  const raw = err.body.field_errors;
+  const named = raw !== null && typeof raw === "object" && !Array.isArray(raw) ? Object.entries(raw).filter((e) => typeof e[1] === "string") : [];
+  return {
+    message: message2,
+    ...typeof code === "string" ? { code } : {},
+    ...named.length > 0 ? { field_errors: Object.fromEntries(named) } : {}
+  };
+}
 function servesWrapperPage(method, pathname) {
   return method === "GET" && !pathname.startsWith("/_");
 }
@@ -46772,11 +46879,11 @@ async function startDevServer(args) {
         );
       } catch (err) {
         release();
-        const message2 = err instanceof Error ? err.message : String(err);
-        process.stderr.write(`[rpc] ERROR ${message2}
+        const failure = rpcFailureBody(err);
+        process.stderr.write(`[rpc] ERROR ${failure.message}
 `);
         res.writeHead(500, { "Content-Type": "application/json" });
-        res.end(JSON.stringify({ message: message2 }));
+        res.end(JSON.stringify(failure));
       }
       return;
     }
@@ -53732,6 +53839,8 @@ var issueSchema = external_exports.object({
 });
 
 // src/app_commands.ts
+var BREAKING_API_CHANGE_CODE = "breaking_api_change";
+var ACKNOWLEDGMENT_ARG = "acknowledge_breaking_api_change";
 function orderedLike(value, template) {
   if (Array.isArray(value)) {
     const t = Array.isArray(template) ? template : [];
@@ -55248,7 +55357,9 @@ async function appUpgrade(client, args) {
   const appId = args.app_id ?? readAppMeta(process.cwd()).app_id;
   let result;
   try {
-    result = await client.upgradeApp(appId);
+    result = await client.upgradeApp(appId, {
+      acknowledge_breaking_api_change: args.acknowledgeBreakingApi
+    });
   } catch (error51) {
     if (!(error51 instanceof LoticsRequestError) || error51.status !== 409 || error51.body.reason !== "already_latest") {
       throw error51;
@@ -55277,6 +55388,64 @@ async function appUpgrade(client, args) {
   }
   console.error(`  Edit the new code:  lotics app pull ${result.app_id}`);
 }
+function apiTargetApp(app_id) {
+  return app_id ?? readAppMeta(process.cwd()).app_id;
+}
+async function appApiPublish(client, args) {
+  const appId = apiTargetApp(args.app_id);
+  let result;
+  try {
+    result = await client.publishAppApi(appId);
+  } catch (error51) {
+    if (!(error51 instanceof LoticsRequestError) || error51.status !== 400 || typeof error51.body.message !== "string") {
+      throw error51;
+    }
+    fail(error51.body.message);
+  }
+  if (isMachineOutput()) {
+    emitJson(result);
+    return;
+  }
+  note(
+    `Published the API of ${appId} \u2014 contract version ${result.contract_version}, ${result.published_at}.`
+  );
+  for (const warning of result.warnings) note(`  \u26A0 ${warning}`);
+  note(`  The document its callers read:  lotics app api spec ${appId}`);
+}
+async function appApiUnpublish(client, args) {
+  const appId = apiTargetApp(args.app_id);
+  const result = await client.unpublishAppApi(appId);
+  if (isMachineOutput()) {
+    emitJson(result);
+    return;
+  }
+  note(
+    result.unpublished ? `Stopped publishing the API of ${appId}.` : `${appId} was publishing no API \u2014 nothing changed.`
+  );
+}
+async function appApiStatus(client, args) {
+  const appId = apiTargetApp(args.app_id);
+  const publication = await client.getAppApiPublication(appId);
+  if (isMachineOutput()) {
+    emitJson({ app_id: appId, ...publication });
+    return;
+  }
+  console.log(
+    publication.published ? `${appId}: publishing API contract version ${publication.contract_version}, since ${publication.published_at}.` : `${appId}: publishing no API.`
+  );
+}
+async function appApiSpec(client, args) {
+  const appId = apiTargetApp(args.app_id);
+  const document2 = await client.getAppOpenApiDocument(appId);
+  const text = `${JSON.stringify(document2, null, 2)}
+`;
+  if (args.outputPath === void 0) {
+    process.stdout.write(text);
+    return;
+  }
+  fs11.writeFileSync(args.outputPath, text);
+  note(`Wrote the OpenAPI document of ${appId} to ${args.outputPath}`);
+}
 function defaultPullTarget(appId, appName) {
   const cwdPkgPath = path12.join(process.cwd(), "package.json");
   if (fs11.existsSync(cwdPkgPath)) {
@@ -55519,7 +55688,7 @@ async function appDeploy(client, args) {
   });
   let live = liveApp;
   if (!nothingPending(pending)) {
-    await pushPendingBindings(client, projectDir, pending);
+    await pushPendingBindings(client, projectDir, pending, args.acknowledgeBreakingApi);
     live = await client.getApp(meta3.app_id);
   }
   const sourceText = readAppSourceText(projectDir);
@@ -55594,7 +55763,8 @@ async function appDeploy(client, args) {
         // binding.
         workflow_aliases: called.workflows,
         query_aliases: called.queries,
-        agent_aliases: called.agents
+        agent_aliases: called.agents,
+        acknowledge_breaking_api_change: args.acknowledgeBreakingApi
       });
       writeAppMeta(projectDir, {
         ...meta3,
@@ -55651,7 +55821,8 @@ async function appDeploy(client, args) {
             orphans,
             undeclared,
             called.dynamic,
-            args.pruneInvoked ?? []
+            args.pruneInvoked ?? [],
+            args.acknowledgeBreakingApi
           );
         } else {
           warnAboutOrphanedBindings(called, liveAfter, meta3.bundle_calls, undeclared);
@@ -55669,11 +55840,19 @@ async function appDeploy(client, args) {
         }
       }
     } catch (err) {
-      const e = err;
-      if (e.code === "VERSION_CONFLICT") {
+      if (err instanceof LoticsRequestError && err.status === 409) {
+        const said = typeof err.body.message === "string" ? err.body.message : err.message;
+        if (err.body.code === BREAKING_API_CHANGE_CODE) {
+          throw new Error(
+            args.acknowledgeBreakingApi ? said : `${said}
+  The flag that carries the acknowledgment here is:  lotics app deploy --acknowledge-breaking-api`
+          );
+        }
+        const served = "current_version_id" in err.body ? err.body.current_version_id : void 0;
+        const stale = served !== void 0 && served !== (meta3.current_version_id ?? null);
         throw new Error(
-          `Deploy conflict: server is at version ${e.current_version_id ?? "unknown"} but local copy is based on ${meta3.current_version_id ?? "no version"}. Pull the latest before redeploying:
-  lotics app pull ${meta3.app_id}`
+          stale ? `${said}
+  Pull the latest before redeploying:  lotics app pull ${meta3.app_id}` : said
         );
       }
       throw err;
@@ -56018,7 +56197,7 @@ function reportStoredBodiesOwedMigration(projectDir, failing) {
   Edit each body, then 'lotics app workflow set <alias>'. Until then the stored body keeps running as it always has.`
   );
 }
-async function pushPendingBindings(client, projectDir, pending) {
+async function pushPendingBindings(client, projectDir, pending, acknowledgeBreakingApi) {
   const plan = [
     ...pending.queries.map((alias) => `query ${alias}`),
     ...pending.workflows.map((alias) => `workflow ${alias}`),
@@ -56029,10 +56208,10 @@ async function pushPendingBindings(client, projectDir, pending) {
 Pushing ${plan.length} binding${plan.length === 1 ? "" : "s"} ahead of the app: ${plan.join(", ")}`
   );
   for (const alias of pending.queries) {
-    await appQuerySet(client, { alias, projectDir });
+    await appQuerySet(client, { alias, projectDir, acknowledgeBreakingApi });
   }
   for (const alias of pending.workflows) {
-    await appWorkflowSet(client, { alias, projectDir });
+    await appWorkflowSet(client, { alias, projectDir, acknowledgeBreakingApi });
   }
   for (const alias of pending.agents) {
     await appAgentSet(client, { alias, projectDir });
@@ -56202,7 +56381,7 @@ function warnAboutOrphanedBindings(called, live, previouslyCalled, undeclared) {
   );
   return lines.length;
 }
-async function pruneOrphanedBindings(client, projectDir, app, orphans, undeclared, dynamic, pruneInvoked) {
+async function pruneOrphanedBindings(client, projectDir, app, orphans, undeclared, dynamic, pruneInvoked, acknowledgeBreakingApi) {
   const stillBound = { queries: [], workflows: [], agents: [] };
   const targets = [
     ...orphans.queries.map((alias) => ({
@@ -56260,7 +56439,9 @@ async function pruneOrphanedBindings(client, projectDir, app, orphans, undeclare
       // Sent only for the aliases the operator named, so the default stays the
       // guard: a run recorded against an alias means something outside the
       // bundle reaches it.
-      ...overrideInvocationGuard ? { even_if_invoked: true } : {}
+      ...overrideInvocationGuard ? { even_if_invoked: true } : {},
+      // Agents carry no published entry, so the field is not theirs to take.
+      ...acknowledgeBreakingApi && target.kind !== "agents" ? { acknowledge_breaking_api_change: true } : {}
     });
     if (res.error) {
       console.error(`  \u2717 could not unbind ${target.label} \u2014 ${res.error}`);
@@ -56889,6 +57070,13 @@ function renderWorkflowIssue(issue2) {
   return issue2.suggestion ? `${head}
     ${issue2.suggestion}` : head;
 }
+function refusalAtThisSurface(res, command, acknowledged) {
+  const said = res.error ?? "";
+  const breaking = res.error_code === void 0 ? said.includes(ACKNOWLEDGMENT_ARG) : res.error_code === BREAKING_API_CHANGE_CODE;
+  if (acknowledged === true || !breaking) return said;
+  return `${said}
+  The flag that carries the acknowledgment here is:  ${command} --acknowledge-breaking-api`;
+}
 async function appWorkflowSet(client, args) {
   const projectDir = args.projectDir ?? process.cwd();
   const meta3 = readAppMeta(projectDir);
@@ -56930,10 +57118,19 @@ async function appWorkflowSet(client, args) {
     // The body this edit was built on. Turns the push into a conditional write:
     // if the live body moved since this project last saw it, the server refuses
     // rather than letting this copy overwrite a change nobody here has seen.
-    expected_body_sha: readSynced(projectDir).workflows[args.alias]?.live
+    expected_body_sha: readSynced(projectDir).workflows[args.alias]?.live,
+    // The author's answer to a published contract this body would break. Absent,
+    // the server refuses such a write and names each change.
+    acknowledge_breaking_api_change: args.acknowledgeBreakingApi
   });
   if (res.error) {
-    console.error(`Failed to set workflow "${args.alias}": ${res.error}`);
+    console.error(
+      `Failed to set workflow "${args.alias}": ` + refusalAtThisSurface(
+        res,
+        `lotics app workflow set ${args.alias}`,
+        args.acknowledgeBreakingApi
+      )
+    );
     process.exit(1);
   }
   const parsed = zod_default.object({
@@ -57007,11 +57204,16 @@ async function appQuerySet(client, args) {
       meta3.app_id,
       alias,
       declaration,
-      readSynced(projectDir).queries[alias]?.live
+      readSynced(projectDir).queries[alias]?.live,
+      // The author's answer to a published contract this declaration would
+      // break. Absent, the server refuses such a write and names each change.
+      args.acknowledgeBreakingApi
     );
     if (res.error) {
       if (pushed.length > 0) console.error(`Pushed before the failure: ${pushed.join(", ")}.`);
-      console.error(`Failed to set query "${alias}": ${res.error}`);
+      console.error(
+        `Failed to set query "${alias}": ` + refusalAtThisSurface(res, `lotics app query set ${alias}`, args.acknowledgeBreakingApi)
+      );
       process.exit(1);
     }
     const querySha = declarationSha(declaration);
@@ -57405,6 +57607,7 @@ function parseArgs(argv) {
     cleanup: false,
     prune: false,
     pruneInvoked: [],
+    acknowledgeBreakingApi: false,
     screens: false,
     screen: [],
     width: [],
@@ -57582,6 +57785,9 @@ function parseArgs(argv) {
       case "--prune":
         flags.prune = true;
         break;
+      case "--acknowledge-breaking-api":
+        flags.acknowledgeBreakingApi = true;
+        break;
       case "--screens":
         flags.screens = true;
         break;
@@ -57691,6 +57897,8 @@ function saveApproval(state, pending, options) {
   requireNonEmpty(state.workspace_id, "workspace_id");
   upsertProfile(state.organization_id, {
     api_key: state.api_key,
+    // A person pressed Confirm: this row IS their terminal's session.
+    kind: "sign_in",
     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".
@@ -58370,7 +58578,7 @@ async function signupAccount(args) {
   const orgId = data.organization_id;
   const workspaceId = data.workspace_id;
   const orgName = args.name || args.email.split("@")[0];
-  upsertProfile(orgId, { api_key: apiKey, org_name: orgName, api_url: apiUrl, workspace_id: workspaceId });
+  upsertProfile(orgId, { api_key: apiKey, kind: "sign_in", org_name: orgName, api_url: apiUrl, workspace_id: workspaceId });
   const existing = loadGlobalConfig() ?? {};
   saveGlobalConfig({ ...existing, email: args.email });
   setActiveOrg(orgId, args.local ? "local" : "global");
@@ -58540,24 +58748,54 @@ Multiple workspaces in ${info.organization_name}. Run "lotics workspace select <
   }
   upsertProfile(info.organization_id, {
     api_key: apiKey,
+    // Pasted in rather than signed in: nobody signs in as an API key, and
+    // `auth whoami` says which this machine is holding.
+    kind: "api_key",
     org_name: info.organization_name,
     api_url: apiUrl,
     workspace_id: workspaceId,
     workspace_name: workspaceName
   });
   noteServerOrgName(info.organization_id, info.organization_name);
-  const existing = loadGlobalConfig() ?? {};
-  saveGlobalConfig({ ...existing, email: info.email });
+  if (info.email !== null) {
+    saveGlobalConfig({ ...loadGlobalConfig(), email: info.email });
+  }
   setActiveOrg(info.organization_id, local ? "local" : "global");
   clearPendingLogin();
+  const who = info.email ?? info.name;
   if (local) {
-    console.error(`Authenticated as ${info.email} in ${info.organization_name}.`);
+    console.error(`Authenticated as ${who} in ${info.organization_name}.`);
     console.error(`  Pinned this directory: ${getConfigPath("local")}`);
   } else {
-    console.error(`Authenticated as ${info.email} in ${info.organization_name} (now active).`);
+    console.error(`Authenticated as ${who} in ${info.organization_name} (now active).`);
     console.error(`  Saved to the "${info.organization_name}" profile in ~/.lotics`);
   }
 }
+async function credentialIsSignIn(client, profile) {
+  if (profile.kind) return profile.kind === "sign_in";
+  try {
+    return (await client.whoami()).credential_origin === "sign_in";
+  } catch {
+    return false;
+  }
+}
+async function revokeCredential(orgId, profile) {
+  const client = new LoticsClient({ apiKey: profile.api_key, apiUrl: profile.api_url });
+  if (!await credentialIsSignIn(client, profile)) {
+    console.error(
+      `The "${profile.org_name}" key (${orgId}) was removed from this machine and is still active \u2014 revoke it yourself under Settings \u2192 Security \u2192 "Keys and terminals" if it acts as you, or ask an admin (Settings \u2192 API keys).`
+    );
+    return;
+  }
+  try {
+    await client.revokeSelfCredential();
+  } catch (error51) {
+    const reason = (error51 instanceof Error ? error51.message : String(error51)).replace(/\s+/g, " ");
+    console.error(
+      `Could not revoke the "${profile.org_name}" credential (${orgId}) server-side (${reason}) \u2014 it is forgotten here, so revoke it under Settings \u2192 Security \u2192 "Keys and terminals" if it is still live.`
+    );
+  }
+}
 async function resolveContextOrClaim(flags, options) {
   const appWorkspaceId = options?.appWorkspaceId;
   const resolved = resolveContext(flags, appWorkspaceId);
@@ -59205,7 +59443,7 @@ async function main() {
       const client2 = new LoticsClient({ apiKey: ctx2.apiKey, apiUrl: ctx2.apiUrl });
       const info = await client2.whoami();
       const existing = loadGlobalConfig() ?? {};
-      saveGlobalConfig({ ...existing, email: info.email });
+      if (info.email !== null) saveGlobalConfig({ ...existing, email: info.email });
       const cached2 = existing.profiles?.[info.organization_id];
       if (cached2 && (cached2.server_name ?? cached2.org_name) !== info.organization_name) {
         noteServerOrgName(info.organization_id, info.organization_name);
@@ -59216,14 +59454,17 @@ async function main() {
         }
       }
       const viewAs = flags.viewAs ?? process.env.LOTICS_VIEW_AS;
+      const kind = cached2?.kind ?? info.credential_origin ?? void 0;
+      const kindLabel = kind === "sign_in" ? "sign-in (lotics auth login)" : kind === "api_key" ? "API key" : "unknown";
       if (flags.json) {
-        console.log(JSON.stringify({ ...info, workspace_id: ctx2.workspaceId ?? null, api_url: ctx2.apiUrl, 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, credential_kind: kind ?? null, view_as: viewAs ?? null }, null, 2));
       } else {
         console.log(`Name:       ${info.name}`);
-        console.log(`Email:      ${info.email}`);
+        console.log(`Email:      ${info.email ?? "(none: nobody signs in as this key)"}`);
         console.log(`Org:        ${info.organization_name} (${info.organization_id})`);
         console.log(`Workspace:  ${ctx2.workspaceId ?? "(none selected)"}`);
         console.log(`API:        ${ctx2.apiUrl}`);
+        console.log(`Credential: ${kindLabel}`);
         console.log(`Source:     ${SOURCE_LABELS[ctx2.source]}`);
         if (viewAs) console.log(`View as:    ${viewAs} (admin preview; requires an admin key)`);
       }
@@ -59238,6 +59479,9 @@ async function main() {
       }
       if (flags.all) {
         const g2 = loadGlobalConfig();
+        for (const [orgId2, profile2] of Object.entries(g2?.profiles ?? {})) {
+          await revokeCredential(orgId2, profile2);
+        }
         saveGlobalConfig({ last_update_check: g2?.last_update_check, latest_version: g2?.latest_version });
         console.error("Removed all saved credentials.");
         return;
@@ -59257,6 +59501,7 @@ async function main() {
         process.exit(1);
       }
       const [orgId, profile] = resolved;
+      await revokeCredential(orgId, profile);
       removeProfile(orgId);
       clearPendingLogin();
       console.error(`Removed the "${profile.org_name}" credential (${orgId}).`);
@@ -59417,6 +59662,9 @@ 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 api publish|unpublish|status|spec [app_id]");
+    console.error("                                       The app's API: publish the promise its queries and");
+    console.error("                                       workflows make to callers outside it, or read it back");
     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");
@@ -59738,10 +59986,40 @@ Available workspaces:`);
       await appDeploy(client, {
         message: (flags.message ?? toolArgs)?.trim() || void 0,
         prune: flags.prune,
-        pruneInvoked: flags.pruneInvoked
+        pruneInvoked: flags.pruneInvoked,
+        acknowledgeBreakingApi: flags.acknowledgeBreakingApi
       });
       return;
     }
+    if (subcommand === "api") {
+      const action = toolArgs;
+      const appId = restArgs.find((a) => !a.startsWith("-"));
+      if (flags.json) setMachineOutput(true);
+      if (action === "publish") {
+        await appApiPublish(client, { app_id: appId });
+        return;
+      }
+      if (action === "unpublish") {
+        await appApiUnpublish(client, { app_id: appId });
+        return;
+      }
+      if (action === "status") {
+        await appApiStatus(client, { app_id: appId });
+        return;
+      }
+      if (action === "spec") {
+        await appApiSpec(client, { app_id: appId, outputPath: flags.output });
+        return;
+      }
+      console.error("Usage:");
+      console.error("  lotics app api publish [app_id]     Publish the app's API and snapshot its contract");
+      console.error("  lotics app api unpublish [app_id]   Stop publishing it");
+      console.error("  lotics app api status [app_id]      Whether it publishes one, and which version");
+      console.error("  lotics app api spec [app_id] [-o <file.json>]");
+      console.error("                                     The OpenAPI document its callers read");
+      console.error("  --json                             One object on stdout, and nothing else");
+      process.exit(1);
+    }
     if (subcommand === "subdomain") {
       const newSubdomain = toolArgs;
       if (!newSubdomain) {
@@ -59768,7 +60046,10 @@ Available workspaces:`);
       return;
     }
     if (subcommand === "upgrade") {
-      await appUpgrade(client, { app_id: toolArgs || void 0 });
+      await appUpgrade(client, {
+        app_id: toolArgs || void 0,
+        acknowledgeBreakingApi: flags.acknowledgeBreakingApi
+      });
       return;
     }
     if (subcommand === "check") {
@@ -59808,7 +60089,10 @@ Available workspaces:`);
           console.error("Pushes the edited src/workflows/<alias>.ts body via set_app_workflow.");
           process.exit(1);
         }
-        await appWorkflowSet(client, { alias });
+        await appWorkflowSet(client, {
+          alias,
+          acknowledgeBreakingApi: flags.acknowledgeBreakingApi
+        });
         return;
       }
       if (action === "pull") {
@@ -59844,7 +60128,10 @@ Available workspaces:`);
       const action = toolArgs;
       if (action === "set") {
         if (flags.all) {
-          await appQuerySet(client, { all: true });
+          await appQuerySet(client, {
+            all: true,
+            acknowledgeBreakingApi: flags.acknowledgeBreakingApi
+          });
           return;
         }
         const alias = restArgs.find((a) => !a.startsWith("--"));
@@ -59855,7 +60142,7 @@ Available workspaces:`);
           );
           process.exit(1);
         }
-        await appQuerySet(client, { alias });
+        await appQuerySet(client, { alias, acknowledgeBreakingApi: flags.acknowledgeBreakingApi });
         return;
       }
       console.error("Usage:");