@lotics/cli 0.188.0 → 0.190.0

package/dist/src/client.d.ts

@@ -78,6 +78,34 @@ export interface ToolInfo {
     description: string;
     input_schema: unknown;
 }
+/**
+ * What `POST /v1/apps/{app_id}/upgrade` reports it did — an offer applied in
+ * part, and every part it declined to touch named back.
+ *
+ * Both `skipped_*` lists are aliases the owner has EDITED since the copy, so
+ * the new version's body was left alone; `dropped_fields` are columns the new
+ * version stopped declaring and that still hold the owner's data. Neither is an
+ * error, and both are the reason this result is printed rather than counted.
+ */
+export interface AppUpgradeResult {
+    app_id: string;
+    from_version: number;
+    to_version: number;
+    deployed: {
+        version_id: string;
+        version_number: number;
+    };
+    created_fields: Array<{
+        entity: string;
+        field: string;
+    }>;
+    skipped_workflows: string[];
+    skipped_agents: string[];
+    dropped_fields: Array<{
+        entity: string;
+        field: string;
+    }>;
+}
 /**
  * A single knowledge doc with its HYDRATED body — the shape of
  * `GET /v1/knowledge_docs/{id}`, and the one content-read path a non-sandbox
@@ -114,13 +142,15 @@ export interface FileUploadResult {
         error: string;
     }>;
 }
-/** One finding from the extract behind a starter publish. */
+/** One finding from the extract behind a package publish. */
 export interface ExtractFinding {
     severity: "error" | "warning" | "info";
     area: string;
     message: string;
 }
 export interface StarterPublishRequest {
+    /** The package to release into. Omitted, the origin apps resolve it. */
+    starter_id?: string;
     /** The origin apps that ship, in alias-minting order. */
     app_ids: string[];
     /** Live knowledge doc ids to bundle. Omitted keeps the previous version's set; [] drops them all. */
@@ -144,6 +174,11 @@ export interface StarterPublishPreview {
     starter_id: string | null;
     starter_name: string;
     version: number;
+    /** The entities it would carry. */
+    entities: Array<{
+        alias: string;
+        label: string;
+    }>;
     apps: Array<{
         alias: string;
         app_id: string;
@@ -199,6 +234,7 @@ export interface StarterVersionContract {
     entities: Array<{
         alias: string;
         label: string;
+        description?: string;
         fields: Array<{
             alias: string;
             label: string;
@@ -235,21 +271,105 @@ export interface KnowledgeWarnings {
     /** `knowledge_expects` doc names with no matching workspace doc. */
     missing_expected_docs: string[];
 }
+/**
+ * A workspace MODEL on the wire — a package contract with no apps, plus the
+ * first rows that travel beside it keyed by entity alias.
+ *
+ * The contract's authoritative shape is `packageContractSchema` in
+ * `@lotics/shared`, a specifier a published `.d.ts` cannot resolve — so the wire
+ * body is typed structurally here, the same trade `StarterVersionContract`
+ * makes. The CLI passes a value it has already parsed through that schema.
+ */
+export interface ScaffoldWorkspaceRequest {
+    contract: Record<string, unknown>;
+    rows?: Record<string, Array<{
+        ref: string;
+        fields: Record<string, unknown>;
+    }>>;
+    /** Bind an entity whose label already names a table here. Absent, a colliding label is refused. */
+    adopt?: boolean;
+}
+export interface ScaffoldWorkspaceResult {
+    /** Every entity the model declares, in contract order. */
+    entities: Array<{
+        alias: string;
+        table_id: string;
+        /** False when a table of that label already existed and was adopted. */
+        created: boolean;
+    }>;
+    roles: Array<{
+        alias: string;
+        group_id: string;
+    }>;
+    /** Ids of the rows written, per entity alias — the handle for deleting them again. */
+    record_ids: Record<string, string[]>;
+    /** Rows were sent and none were written, because the run adopted a table. */
+    rows_skipped: boolean;
+}
+/**
+ * A workspace read BACK as a model — the inverse of the scaffold above.
+ *
+ * `entities` and `roles` are the model file's own two keys, whose authoritative
+ * shapes are `contractEntitySchema` / `contractRoleSchema` in `@lotics/shared` —
+ * specifiers a published `.d.ts` cannot resolve, so they are typed here as what
+ * this client does with them, which is hand them on whole. The same trade
+ * `ScaffoldWorkspaceRequest` makes in the other direction.
+ *
+ * `findings` are about the export rather than part of it: a workspace holds
+ * things a model file cannot express, and a file that dropped them silently
+ * would be read as the whole workspace.
+ */
+export interface WorkspaceModelExport {
+    contract: {
+        entities: Array<Record<string, unknown>>;
+        roles: Array<Record<string, unknown>>;
+        templates: Array<Record<string, unknown>>;
+    };
+    findings: Array<{
+        severity: "error" | "warning" | "info";
+        area: string;
+        message: string;
+    }>;
+}
+/**
+ * A request the API refused. The message carries the status and the server's
+ * sentence, which is what reaches a person; `status` and `body` are for the
+ * few callers that branch on a refusal — a 409 whose `body.reason` says the
+ * run had nothing to do, rather than that it failed.
+ */
+export declare class LoticsRequestError extends Error {
+    readonly status: number;
+    readonly body: Record<string, unknown>;
+    constructor(message: string, status: number, body: Record<string, unknown>);
+}
 export declare const API_BASE_URL: string;
 /**
- * Where a person goes when the CLI cannot finish the job — the one case being a
- * returning user on a machine that holds no key, since every route back in
- * needs one. Held beside the API base so the pair is read together, and named
- * once rather than inlined at each message that has to point somewhere.
+ * 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
+ * together, named once rather than inlined at each message that points
+ * somewhere, and overridable for the same reason the API base is — a run against
+ * a local site must read that site's presets, not production's.
  */
-export declare const WEB_APP_URL = "https://lotics.ai";
-/** One starter on the public shelf — what a chooser decides with, nothing else. */
+export declare const WEB_APP_URL: string;
+/** One package on the public shelf — what a chooser decides with, nothing else. */
 export interface OfficialStarter {
     id: string;
     name: string;
     description: string | null;
     icon: string | null;
     latest_version: number;
+    /**
+     * The apps the copy creates. A name and a sentence leave the chooser
+     * guessing; these are what someone's own words get matched against when
+     * deciding between a package and a model.
+     */
+    apps: Array<{
+        alias: string;
+        name: string;
+        description?: string;
+    }>;
+    /** How many tables the copy creates — the other half of "what is in this?". */
+    table_count: number;
 }
 /**
  * The starters Lotics publishes, fetched with no credential.
@@ -260,6 +380,152 @@ export interface OfficialStarter {
  * exists, so needing one to ask means signing up to find out the answer was no.
  */
 export declare function fetchOfficialStarters(): Promise<OfficialStarter[]>;
+/**
+ * One keyless GET of JSON, bounded — the shape every read that predates an
+ * account takes.
+ *
+ * Bounded because these are the FIRST commands a new user runs and a hang with
+ * nothing on screen is the worst version of the failure; `config.ts` bounds its
+ * own unattended fetch for the same reason, and `docs/network_reliability.md` is
+ * a log of connections from our users' networks degrading rather than refusing,
+ * which is the shape that hangs.
+ *
+ * A transport failure THROWS and a status is RETURNED, because only the first is
+ * "check your connection": a status means the server replied and the network is
+ * demonstrably fine, and a caller that answered both the same way would tell an
+ * owner their package is missing every time the link drops.
+ */
+export declare function getPublicJson(url: string, what: string): Promise<{
+    ok: true;
+    body: unknown;
+} | {
+    ok: false;
+    status: number;
+}>;
+/**
+ * One official package READ WHOLE, with no credential — or the status that says
+ * the shelf does not serve it.
+ *
+ * The shelf row says what a package is; this says what is in it — entities with
+ * their fields, the roles, each template's metadata and each app's name. Never a
+ * workflow body: this is a read for deciding and for writing a model from, not a
+ * copy.
+ *
+ * Unauthenticated for the same reason the shelf is: a preset is READ rather than
+ * instantiated, and the whole point of reading one is that it happens before an
+ * account exists. Only official packages are served — the `is_official` filter,
+ * exactly as on the shelf — so a caller's OWN package answers a status here and
+ * is read through the authenticated pair instead. A transport failure still
+ * 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<{
+    ok: true;
+    package: OfficialStarterRead;
+} | {
+    ok: false;
+    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>;
+/** A column as the public read shows it: enough to write a model field from. */
+export interface OfficialStarterField {
+    alias: string;
+    label: string;
+    type: string;
+}
+/** A table as the public read shows it: its columns. */
+export interface OfficialStarterEntity {
+    alias: string;
+    label: string;
+    description?: string;
+    fields: OfficialStarterField[];
+}
+/**
+ * What the public read of one package carries.
+ *
+ * Every namespace is declared structurally, NARROWED to what a reader turning
+ * this into a model needs — fields carry their type, apps only their name — the
+ * same trade `StarterVersionContract` makes: a published `.d.ts` cannot resolve
+ * `@lotics/shared`. `packageContractSchema` is the definition, and the CLI
+ * parses a preset's block through `modelPresetSchema` before resolving a `from`
+ * file against it.
+ */
+export interface OfficialStarterRead {
+    id: string;
+    name: string;
+    description: string | null;
+    latest_version: number;
+    contract: {
+        entities: OfficialStarterEntity[];
+        roles: Array<{
+            alias: string;
+            label: string;
+        }>;
+        templates: Array<{
+            alias: string;
+            label: string;
+            type: string;
+        }>;
+        /** The apps a copy creates. */
+        apps: Array<{
+            alias: string;
+            name: string;
+            description?: string;
+        }>;
+        /** Sample rows per entity alias — how many, never the rows. */
+        fixtures: Record<string, {
+            row_count: number;
+        }>;
+        knowledge: Record<string, {
+            name: string;
+            description: string;
+        }>;
+        knowledge_expects: string[];
+    };
+}
+/**
+ * What a terminal holds while it waits to be let in: the handle the server knows
+ * the request by, the `secret` that proves this is the same terminal that asked,
+ * and the `code` the person matches against the confirm page before pressing it.
+ *
+ * `secret` is a credential and is never printed — the `code` is what a person
+ * reads, and it proves nothing on its own.
+ */
+export interface CliLoginRequest {
+    request_id: string;
+    secret: string;
+    code: string;
+    expires_at: string;
+}
+/** Where a login request stands. `approved` carries the key, and only once. */
+export type CliLoginState = {
+    status: "pending";
+} | {
+    status: "expired";
+} | {
+    status: "claimed";
+} | {
+    status: "approved";
+    api_key: string;
+    organization_id: string;
+    organization_name: string;
+    workspace_id: string;
+};
+/**
+ * Ask Lotics to mail a sign-in link, and read back whether it was confirmed.
+ *
+ * Plain functions rather than `LoticsClient` methods for the same reason
+ * `fetchOfficialStarters` is one: there is no key to build a client around, and
+ * that is the whole point — this is the pair a terminal holding NO credential
+ * uses to obtain one. Sending an `Authorization` header would make the endpoint
+ * answerable only to callers who no longer need it.
+ *
+ * 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 class LoticsClient {
     private apiKey;
     private workspaceId;
@@ -322,6 +588,26 @@ export declare class LoticsClient {
         name: string;
         timezone?: string;
     }): Promise<WorkspaceInfo>;
+    /**
+     * Apply a workspace MODEL to the current workspace — the from-scratch half of
+     * the starter pipeline, on a contract nobody published.
+     *
+     * Additive: with `adopt`, an entity whose label already names a table here
+     * binds to it and gains the fields, options and views it is missing; without
+     * `adopt`, that label is refused. Nothing is ever modified or deleted, and
+     * rows land only where every bound table is empty. Admin-only.
+     */
+    scaffoldWorkspace(body: ScaffoldWorkspaceRequest): Promise<ScaffoldWorkspaceResult>;
+    /**
+     * Read this workspace's schema back as a model — the tables it has (or only
+     * the ones named), their fields, options and views, plus its roles.
+     *
+     * A pure read, and admin-only for the same reason the scaffold is: the whole
+     * schema is what comes back.
+     */
+    exportWorkspaceModel(opts?: {
+        tables?: string[];
+    }): Promise<WorkspaceModelExport>;
     /** Renames (and re-settings) the CURRENT workspace — the endpoint reads the
      *  target from the request's workspace, never a path id. */
     updateWorkspace(body: {
@@ -455,7 +741,7 @@ export declare class LoticsClient {
     }>;
     /**
      * Take a starter off the shelf, or `undo` to put it back (backs `opctl
-     * starter unpublish`). It hides from non-owning orgs and can no longer be
+     * library unpublish`). It hides from non-owning orgs and can no longer be
      * copied; copies already made are unaffected — they never linked back.
      * Owner-org admin-only.
      */
@@ -499,6 +785,14 @@ export declare class LoticsClient {
         latest_version: number;
         is_official: boolean;
         owned_by_caller: boolean;
+        /** The apps a copy creates — the same contents the public shelf names. */
+        apps: Array<{
+            alias: string;
+            name: string;
+            description?: string;
+        }>;
+        /** How many tables the copy creates. */
+        table_count: number;
     }>>;
     /**
      * Copy a starter into the current workspace.
@@ -513,6 +807,20 @@ export declare class LoticsClient {
         version?: number;
         no_sample_data?: boolean;
         adopt?: boolean;
+        /**
+         * The labels THIS workspace calls the package's entities and fields.
+         *
+         * Scaffold adopts by label, so binding renames the contract's labels
+         * before it runs and the copy lands on the tables the caller already has.
+         * A bound field whose type differs from the one the contract declares is
+         * refused — the type is the contract, only the naming moves. Structural
+         * for the same reason the rest of this file's wire shapes are;
+         * `packageBindSchema` in `@lotics/shared` is the definition.
+         */
+        bind?: Record<string, {
+            label?: string;
+            fields?: Record<string, string>;
+        }>;
     }): Promise<{
         /** Each app's deploy, in contract order. `error` set and `deployed` null when one did not land. */
         apps: Array<{
@@ -541,6 +849,21 @@ export declare class LoticsClient {
         starter_id: string;
         latest_version: number;
     }>;
+    /**
+     * Apply the latest version of the package this app was copied from.
+     *
+     * The other provenance direction from `getAppOriginStarter`, and the only one
+     * that writes: that one answers which package this app PUBLISHED, this one
+     * reads what a copy recorded and re-derives the app against a later release.
+     *
+     * The offer is partial by design and the result says how partial: schema is
+     * additive (`created_fields`, and a `dropped_fields` the new version stopped
+     * declaring is left standing), and an artifact the owner has edited is kept
+     * and named (`skipped_workflows` / `skipped_agents`). An app with no
+     * provenance is a 400, and one already on the latest release a 409 — both
+     * refusals, both before any write. Admin-only.
+     */
+    upgradeApp(app_id: string): Promise<AppUpgradeResult>;
     /**
      * Capture live records from this workspace as a starter's sample data.
      *
@@ -587,7 +910,7 @@ export declare class LoticsClient {
         created_at: string;
         updated_at: string;
     }>;
-    /** Version history newest-first (no contract payloads) — backs `opctl starter show`. Admin-only. */
+    /** Version history newest-first (no contract payloads) — backs `opctl library show`. Admin-only. */
     listStarterVersions(starter_id: string): Promise<{
         versions: Array<{
             version: number;
@@ -622,7 +945,7 @@ export declare class LoticsClient {
     }>>;
     /**
      * Preview publishing a set of this workspace's apps as one starter version —
-     * the GET behind `opctl starter publish` (no `--yes`). The server runs the
+     * the GET behind `opctl library publish` (no `--yes`). The server runs the
      * same extraction the publish runs and reports which starter it would
      * release into (null: it would mint one), the next version, the aliases a
      * first publish can still rename, the diff against the current version, the

package/dist/src/client.js

@@ -139,27 +139,94 @@ function getMimeType(filename) {
   return MIME_MAP[ext] ?? "application/octet-stream";
 }
 var MULTIPART_THRESHOLD_BYTES = 8 * 1024 * 1024;
+var LoticsRequestError = class extends Error {
+  constructor(message, status, body) {
+    super(message);
+    this.status = status;
+    this.body = body;
+    this.name = "LoticsRequestError";
+  }
+  status;
+  body;
+};
 var API_BASE_URL = process.env.LOTICS_API_URL ?? "https://api.lotics.ai";
-var WEB_APP_URL = "https://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");
+  if (!read.ok) {
+    throw new Error(
+      `Lotics answered ${read.status} listing the packages. If this keeps happening, browse ${WEB_APP_URL}/docs/cli.`
+    );
+  }
+  return read.body;
+}
+async function getPublicJson(url, what) {
   let response;
   try {
-    response = await fetch(`${API_BASE_URL}/v1/starters/official`, {
-      signal: AbortSignal.timeout(SHELF_FETCH_TIMEOUT_MS)
+    response = await fetch(url, { signal: AbortSignal.timeout(PUBLIC_FETCH_TIMEOUT_MS) });
+  } catch (error) {
+    throw new Error(
+      `Could not reach Lotics to ${what} (${error instanceof Error ? error.message : String(error)}). Check your connection, or browse ${WEB_APP_URL}/docs/cli.`
+    );
+  }
+  if (!response.ok) return { ok: false, status: response.status };
+  return { ok: true, body: await response.json() };
+}
+async function readOfficialStarter(starter_id) {
+  const read = await getPublicJson(
+    `${API_BASE_URL}/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);
+  if (!read.ok) {
+    throw new Error(
+      `Lotics answered ${read.status} reading ${starter_id}. Only packages Lotics publishes can be read without an account.`
+    );
+  }
+  return read.package;
+}
+var PUBLIC_FETCH_TIMEOUT_MS = 1e4;
+async function startCliLogin(email) {
+  let response;
+  try {
+    response = await fetch(`${API_BASE_URL}/v1/cli/login_requests`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ email }),
+      signal: AbortSignal.timeout(PUBLIC_FETCH_TIMEOUT_MS)
     });
   } catch (error) {
     throw new Error(
-      `Could not reach Lotics to list the starters (${error instanceof Error ? error.message : String(error)}). Check your connection, or browse ${WEB_APP_URL}/docs/cli.`
+      `Could not reach Lotics to send a sign-in link (${error instanceof Error ? error.message : String(error)}). Check your connection, or sign in at ${WEB_APP_URL}.`
     );
   }
   if (!response.ok) {
+    throw new Error(`Lotics answered ${response.status} asking for a sign-in link.`);
+  }
+  return await response.json();
+}
+async function pollCliLogin(request_id, secret) {
+  const url = `${API_BASE_URL}/v1/cli/login_requests/${encodeURIComponent(request_id)}`;
+  let response;
+  try {
+    response = await fetch(url, {
+      headers: { "x-lotics-login-secret": secret },
+      signal: AbortSignal.timeout(PUBLIC_FETCH_TIMEOUT_MS)
+    });
+  } catch (error) {
     throw new Error(
-      `Lotics answered ${response.status} listing the starters. If this keeps happening, browse ${WEB_APP_URL}/docs/cli.`
+      `Could not reach Lotics while waiting for the sign-in (${error instanceof Error ? error.message : String(error)}). Run "lotics auth login" again once the connection is back.`
     );
   }
+  if (!response.ok) {
+    throw new Error(`Lotics answered ${response.status} waiting for the sign-in.`);
+  }
   return await response.json();
 }
-var SHELF_FETCH_TIMEOUT_MS = 1e4;
 function newRequestId() {
   return crypto.randomUUID().replace(/-/g, "").slice(0, 12);
 }
@@ -192,17 +259,18 @@ var LoticsClient = class {
    */
   async throwResponseError(response, requestId) {
     const text = await response.text();
-    let message;
+    let body = {};
     try {
       const json = JSON.parse(text);
-      message = json.message ?? text;
+      if (typeof json === "object" && json !== null && !Array.isArray(json)) body = { ...json };
     } catch {
-      message = text;
+      body = {};
     }
+    const message = typeof body.message === "string" ? body.message : text;
     const trace = requestId === void 0 ? "" : `
 
   Request id: ${requestId} \u2014 quote this to Lotics support.`;
-    throw new Error(`${response.status}: ${message}${trace}`);
+    throw new LoticsRequestError(`${response.status}: ${message}${trace}`, response.status, body);
   }
   /**
    * The backend's `log()` middleware registers `user-agent`,
@@ -276,6 +344,33 @@ var LoticsClient = class {
   async createWorkspace(body) {
     return this.request("POST", "/v1/workspaces", body);
   }
+  /**
+   * Apply a workspace MODEL to the current workspace — the from-scratch half of
+   * the starter pipeline, on a contract nobody published.
+   *
+   * Additive: with `adopt`, an entity whose label already names a table here
+   * binds to it and gains the fields, options and views it is missing; without
+   * `adopt`, that label is refused. Nothing is ever modified or deleted, and
+   * rows land only where every bound table is empty. Admin-only.
+   */
+  async scaffoldWorkspace(body) {
+    return this.request("POST", "/v1/workspaces/scaffold", body);
+  }
+  /**
+   * Read this workspace's schema back as a model — the tables it has (or only
+   * the ones named), their fields, options and views, plus its roles.
+   *
+   * A pure read, and admin-only for the same reason the scaffold is: the whole
+   * schema is what comes back.
+   */
+  async exportWorkspaceModel(opts = {}) {
+    const params = new URLSearchParams();
+    if (opts.tables !== void 0 && opts.tables.length > 0) {
+      params.set("tables", opts.tables.join(","));
+    }
+    const qs = params.toString();
+    return this.request("GET", `/v1/workspaces/model${qs ? `?${qs}` : ""}`);
+  }
   /** Renames (and re-settings) the CURRENT workspace — the endpoint reads the
    *  target from the request's workspace, never a path id. */
   async updateWorkspace(body) {
@@ -355,7 +450,7 @@ var LoticsClient = class {
   }
   /**
    * Take a starter off the shelf, or `undo` to put it back (backs `opctl
-   * starter unpublish`). It hides from non-owning orgs and can no longer be
+   * library unpublish`). It hides from non-owning orgs and can no longer be
    * copied; copies already made are unaffected — they never linked back.
    * Owner-org admin-only.
    */
@@ -408,6 +503,23 @@ var LoticsClient = class {
   async getAppOriginStarter(app_id) {
     return this.request("GET", `/v1/apps/${encodeURIComponent(app_id)}/origin-starter`);
   }
+  /**
+   * Apply the latest version of the package this app was copied from.
+   *
+   * The other provenance direction from `getAppOriginStarter`, and the only one
+   * that writes: that one answers which package this app PUBLISHED, this one
+   * reads what a copy recorded and re-derives the app against a later release.
+   *
+   * The offer is partial by design and the result says how partial: schema is
+   * additive (`created_fields`, and a `dropped_fields` the new version stopped
+   * declaring is left standing), and an artifact the owner has edited is kept
+   * and named (`skipped_workflows` / `skipped_agents`). An app with no
+   * 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`, {});
+  }
   /**
    * Capture live records from this workspace as a starter's sample data.
    *
@@ -436,7 +548,7 @@ var LoticsClient = class {
   async getStarter(starter_id) {
     return this.request("GET", `/v1/starters/${encodeURIComponent(starter_id)}`);
   }
-  /** Version history newest-first (no contract payloads) — backs `opctl starter show`. Admin-only. */
+  /** Version history newest-first (no contract payloads) — backs `opctl library show`. Admin-only. */
   async listStarterVersions(starter_id) {
     return this.request("GET", `/v1/starters/${encodeURIComponent(starter_id)}/versions`);
   }
@@ -464,7 +576,7 @@ var LoticsClient = class {
   // --- Starter publishing (the authoring verbs; copying is `instantiateStarter`) ---
   /**
    * Preview publishing a set of this workspace's apps as one starter version —
-   * the GET behind `opctl starter publish` (no `--yes`). The server runs the
+   * the GET behind `opctl library publish` (no `--yes`). The server runs the
    * same extraction the publish runs and reports which starter it would
    * release into (null: it would mint one), the next version, the aliases a
    * first publish can still rename, the diff against the current version, the
@@ -474,6 +586,7 @@ var LoticsClient = class {
   async previewStarterPublish(opts) {
     const params = new URLSearchParams();
     params.set("app_ids", opts.app_ids.join(","));
+    if (opts.starter_id !== void 0) params.set("starter_id", opts.starter_id);
     if (opts.knowledge_doc_ids !== void 0) params.set("knowledge_doc_ids", opts.knowledge_doc_ids.join(","));
     if (opts.renames !== void 0 && opts.renames.length > 0) params.set("renames", JSON.stringify(opts.renames));
     if (opts.name !== void 0) params.set("name", opts.name);
@@ -1050,6 +1163,12 @@ var LoticsClient = class {
 export {
   API_BASE_URL,
   LoticsClient,
+  LoticsRequestError,
   WEB_APP_URL,
-  fetchOfficialStarters
+  fetchOfficialStarters,
+  getOfficialStarter,
+  getPublicJson,
+  pollCliLogin,
+  readOfficialStarter,
+  startCliLogin
 };

package/docs/building_an_app.md

@@ -237,7 +237,7 @@ actually carries, not what the source says it should.
 ```
 npm run typecheck && npm run lint && npm test
 lotics app check                     # every pre-flight a deploy runs, without building or shipping,
-                                     # plus the portability gate a starter publish applies
+                                     # plus the portability gate a library publish applies
 lotics app deploy -m "<what changed + why>"
 ```