@lotics/cli 0.181.1 → 0.182.0

package/README.md

@@ -39,18 +39,19 @@ package (reachable at `node_modules/@lotics/cli/docs/*.md` once installed):
 ## Start from a starter, in one command
 
 Install the CLI, then copy a starter — it creates the account, copies the starter into its
-workspace, deploys the app, and prints a one-time sign-in link:
+workspace, deploys its apps, and prints a one-time sign-in link:
 
 ```bash
 curl -fsSL https://lotics.ai/install.sh | bash
 lotics setup <starter_id> --email you@company.com
 ```
 
-The installer downloads one compiled executable — no Node.js, no npm. Copying a starter is the
-one step that needs more: it builds the app locally, and building needs Node 18+.
+The installer downloads one compiled executable — no Node.js, no npm, and copying a starter needs
+neither: every app is deployed on Lotics and nothing is written here. Node 18+ comes in only when
+you pull an app's source to change it (`lotics app pull <app_id>`) and build it to deploy again.
 
 Add `--json` for one machine-readable object instead of progress — the organization, the
-workspace, the app id, what was created, the sign-in link, and any warnings. Already signed in?
+workspace, the app ids, what was created, the sign-in link, and any warnings. Already signed in?
 Drop `--email` and `lotics setup <starter_id>` copies into the account you have.
 
 ## Install

package/dist/src/cli.js

@@ -44535,10 +44535,10 @@ var LoticsClient = class {
   async editPackageListing(package_id, body) {
     return this.request("POST", `/v1/packages/${encodeURIComponent(package_id)}/listing`, body);
   }
-  // --- Packages (registry reads + installations) ---
-  // Authoring is server-side: apps via `POST /v1/apps/{id}/package-publish|release`,
-  // content packages via the `publish_content`/`release_content` tools. There is no
-  // client-side create-package / upload-bundle path.
+  // --- Starters (registry reads + copies) ---
+  // Authoring is server-side: apps via the publish job (`requestStarterPublish`),
+  // content starters via the `publish_content`/`release_content` tools. There is
+  // no client-side create-package / upload-bundle path.
   /**
    * The starters this organization can copy — Lotics-reviewed ones plus its own,
    * never a catalogue of everything published. The server returns exactly what
@@ -44551,10 +44551,9 @@ var LoticsClient = class {
    * Copy a starter into the current workspace.
    *
    * Server-side this scaffolds the schema, creates the templates, docs and
-   * sample records, creates a BESPOKE app and materializes onto it — then stops.
-   * It deploys nothing: a starter ships source only, and the source has to be
-   * built where codegen can bake THIS workspace's field ids. `bundle_url` is a
-   * presigned GET of that source, and finishing the job is the caller's half.
+   * sample records, creates every app the starter carries and deploys each
+   * from its prebuilt dist — no build anywhere. `apps` reports each deploy;
+   * one that failed carries its `error` and the copy is complete around it.
    * Admin-only.
    */
   async instantiateStarter(starter_id, body) {
@@ -44613,74 +44612,45 @@ var LoticsClient = class {
   async getWorkspaceDanglingReferences() {
     return this.request("GET", "/v1/workspaces/dangling-references");
   }
+  // --- Starter publishing (the authoring verbs; copying is `instantiateStarter`) ---
   /**
-   * Preview a release — the dry run behind `opctl app release`. Runs the
-   * binding-aware extract of the origin (aliases stable through the app's current
-   * binding) and reports the next version number, the new + changed aliases, the
-   * bundled-knowledge delta, and any extract findings (an `error` blocks the
-   * apply). An optional `knowledge` declaration (from the pulled app manifest)
-   * re-declares the bundle set — added/dropped/changed docs surface in the delta;
-   * omitted, the current corpus is reconstructed from the pin. No writes. Admin,
-   * owning-org only.
+   * 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
+   * 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
+   * knowledge delta, and the findings (an `error` blocks the publish). No
+   * writes. Admin-only.
    */
-  async previewPackageRelease(app_id, opts = {}) {
+  async previewStarterPublish(opts) {
     const params = new URLSearchParams();
-    if (opts.knowledge !== void 0 && opts.knowledge.length > 0) {
-      params.set("knowledge", JSON.stringify(opts.knowledge));
-    }
-    const query = params.toString();
-    return this.request(
-      "GET",
-      `/v1/apps/${encodeURIComponent(app_id)}/package-release${query ? `?${query}` : ""}`
-    );
+    params.set("app_ids", opts.app_ids.join(","));
+    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);
+    if (opts.description !== void 0) params.set("description", opts.description);
+    if (opts.icon !== void 0) params.set("icon", opts.icon);
+    if (opts.color !== void 0) params.set("color", opts.color);
+    return this.request("GET", `/v1/starters/publish-preview?${params.toString()}`);
   }
   /**
-   * Release — snapshot the origin app into the next registry version. The server
-   * binding-aware-extracts it, repackages its deployed source + dist as the
-   * bundle, publishes the next `release`-channel version with the changelog, and
-   * re-pins the origin. An optional `knowledge` declaration re-declares the
-   * bundled-knowledge set (added/dropped/re-snapshotted docs; omitted preserves
-   * the current corpus). Error findings from extract surface as a 409; a
-   * missing/archived declared doc is a 400, a foreign-package doc a 409. Admin,
-   * owning-org only. Backs `opctl app release --yes`.
+   * Publish this workspace's apps as a starter version — a JOB, because every
+   * app is built once against sentinel field keys and eleven builds outlast a
+   * request. Everything a request can refuse is refused here with nothing
+   * written: a blocking finding or another publish still running for this
+   * org (409), a missing deploy or a bad declaration (400). The response is
+   * the job to poll with `getStarterPublish`. Admin-only.
    */
-  async releasePackage(app_id, body) {
-    return this.request("POST", `/v1/apps/${encodeURIComponent(app_id)}/package-release`, body);
-  }
-  /**
-   * Dry-run preview of a first-release — the `GET` behind `opctl app publish`
-   * (no `--yes`), the publish-side analogue of `previewPackageRelease`. The
-   * server runs the same fresh-alias extract + `src/` scan the apply runs
-   * (through any `renames`) and returns the package name it would mint, the
-   * auto-minted RENAMABLE aliases (the exact `--rename` keys), and the extract
-   * findings (an `error` blocks the apply). No writes. Admin-only.
-   */
-  async previewPublishAppPackage(app_id, opts = {}) {
-    const params = new URLSearchParams();
-    if (opts.knowledge !== void 0 && opts.knowledge.length > 0) {
-      params.set("knowledge", JSON.stringify(opts.knowledge));
-    }
-    if (opts.renames !== void 0 && opts.renames.length > 0) {
-      params.set("renames", JSON.stringify(opts.renames));
-    }
-    const query = params.toString();
-    return this.request(
-      "GET",
-      `/v1/apps/${encodeURIComponent(app_id)}/package-publish${query ? `?${query}` : ""}`
-    );
+  async requestStarterPublish(body) {
+    const { color, ...rest2 } = body;
+    return this.request("POST", "/v1/starters/publishes", {
+      ...rest2,
+      ...color !== void 0 ? { theme: { color } } : {}
+    });
   }
-  /**
-   * First-release apply — mint a package from a BESPOKE app and publish v1 in one
-   * call (the `POST` behind `opctl app publish --yes`). The server extracts an
-   * alias-keyed contract from the app (fresh aliases; `renames` fixes them before
-   * v1 freezes), creates the registry package (name/description from the app),
-   * publishes v1 from the app's deployed source + dist, and pins the origin as
-   * installation #1. Error findings from extract surface as a 409. An
-   * already-linked app must use `releasePackage` instead. Admin-only. Backs
-   * `opctl app publish <app_id>`.
-   */
-  async publishAppAsPackage(app_id, body) {
-    return this.request("POST", `/v1/apps/${encodeURIComponent(app_id)}/package-publish`, body);
+  /** The state of a publish: which app is building, and the version once every dist is in. */
+  async getStarterPublish(publish_id) {
+    return this.request("GET", `/v1/starters/publishes/${encodeURIComponent(publish_id)}`);
   }
   /**
    * Resolve the display name + fields (incl. select options) of the given tables
@@ -45711,7 +45681,7 @@ function resultSideEffects(result) {
 }
 
 // src/version.ts
-var VERSION = "0.181.1";
+var VERSION = "0.182.0";
 
 // src/timezone.ts
 function machineTimezone() {
@@ -45881,11 +45851,11 @@ var COMMANDS = [
   {
     verbs: ["setup"],
     help: [
-      "  lotics setup <starter_id> [path] --email <you@co.com>",
+      "  lotics setup <starter_id> --email <you@co.com>",
       "                                       First run, one command: create an account if this",
       "                                       machine has none, then copy the starter into its",
       "                                       workspace \u2014 schema, templates, knowledge docs,",
-      "                                       sample records, a deployed app \u2014 and print a",
+      "                                       sample records, its apps deployed \u2014 and print a",
       "                                       one-time sign-in link. Drop --email to copy into",
       "                                       the account you already have. --json prints one",
       "                                       object and nothing else"
@@ -45923,12 +45893,11 @@ var COMMANDS = [
       "                                       NO account \u2014 it then lists the published shelf, so you",
       "                                       can decide whether to copy one or build before signing up",
       "  lotics starter show <starter_id>     What one carries: tables, docs, templates, sample data",
-      "  lotics starter init <starter_id> [path]",
-      "                                       Copy it in \u2014 schema, templates, knowledge docs,",
-      "                                       sample records and an editable app project. A COPY:",
-      "                                       everything it creates is yours outright, with no",
-      "                                       link back and nothing to upgrade. Builds and deploys",
-      "                                       locally, so it needs node + a few minutes.",
+      "  lotics starter init <starter_id>     Copy it in \u2014 schema, templates, knowledge docs,",
+      "                                       sample records and its apps, deployed on Lotics. A",
+      "                                       COPY: everything it creates is yours outright, with",
+      "                                       no link back and nothing to upgrade. Nothing lands",
+      "                                       on this machine; lotics app pull <app_id> edits one.",
       "                                       --no-sample-data skips the sample records;",
       "                                       --adopt allows a workspace that is not empty",
       "  lotics starter fixtures capture --entity <alias> --limit <n>",
@@ -74054,7 +74023,6 @@ function parseArgs(argv) {
 // src/starter_commands.ts
 import fs9 from "node:fs";
 import path10 from "node:path";
-import { tmpdir as tmpdir2 } from "node:os";
 function printStarterRows(rows) {
   const width = Math.max(...rows.map((row) => row.id.length));
   for (const row of rows) {
@@ -74160,121 +74128,74 @@ function instantiateBody(args) {
 }
 async function starterInit(client, args) {
   const starter = await client.getPackage(args.starter_id);
-  const targetPath = path10.resolve(args.targetPath ?? appDirName(starter.name));
-  if (fs9.existsSync(targetPath) && fs9.readdirSync(targetPath).length > 0) {
-    throw new Error(`Target directory ${targetPath} is not empty. Pass an empty path and re-run.`);
-  }
   note(
     `Copying ${starter.name}${starter.is_official ? " (official)" : ""} into this workspace\u2026`
   );
   const result = await client.instantiateStarter(args.starter_id, instantiateBody(args));
+  if (!Array.isArray(result.apps)) {
+    throw new Error(
+      `This Lotics server predates this CLI and reported nothing about the copy's apps.
+  The copy itself landed \u2014 open it with "lotics auth web" \u2014 and retry once the platform
+  deploy completes. Do NOT copy again.`
+    );
+  }
   const tables = Object.keys(result.binding.entities ?? {}).sort();
   const knowledgeDocs = Object.keys(result.binding.knowledge ?? {}).sort();
   const templates = Object.keys(result.binding.templates ?? {}).sort();
   const records = Object.values(result.sample_record_ids).reduce((n, ids) => n + ids.length, 0);
-  const created = {
-    tables,
-    templates,
-    knowledge_docs: knowledgeDocs,
-    sample_records: records
-  };
+  const created = { tables, templates, knowledge_docs: knowledgeDocs, sample_records: records };
+  const apps = result.apps.map((app) => ({
+    alias: app.alias,
+    app_id: app.app_id,
+    name: app.name,
+    version_number: app.deployed?.version_number ?? null,
+    error: app.error
+  }));
   note(
-    `  Created ${tables.length} table${tables.length === 1 ? "" : "s"}, ${templates.length} template${templates.length === 1 ? "" : "s"}, ${knowledgeDocs.length} knowledge doc${knowledgeDocs.length === 1 ? "" : "s"}, ${records} sample record${records === 1 ? "" : "s"}.`
+    `  Created ${tables.length} table${tables.length === 1 ? "" : "s"}, ${templates.length} template${templates.length === 1 ? "" : "s"}, ${knowledgeDocs.length} knowledge doc${knowledgeDocs.length === 1 ? "" : "s"}, ${records} sample record${records === 1 ? "" : "s"}${apps.length > 0 ? `, ${apps.length} app${apps.length === 1 ? "" : "s"}` : ""}.`
   );
   reportKnowledgeWarnings(result.knowledge_warnings);
-  if (result.app_id === null || result.bundle_url === null) {
+  const base = {
+    starter_id: args.starter_id,
+    starter_name: starter.name,
+    version: result.version,
+    app_ids: Object.fromEntries(apps.map((app) => [app.alias, app.app_id])),
+    apps,
+    created
+  };
+  if (apps.length === 0) {
     note(`
 Done \u2014 these are yours now, with no link back to the starter.`);
     noteCopiedContent(templates, knowledgeDocs);
-    return {
-      starter_id: args.starter_id,
-      starter_name: starter.name,
-      version: result.version,
-      app_id: null,
-      project_dir: null,
-      created,
-      signin_url: null
-    };
-  }
-  fs9.mkdirSync(targetPath, { recursive: true });
-  note(`Downloading source\u2026`);
-  const bundleFile = path10.join(tmpdir2(), `lotics-starter-${args.starter_id}-${process.pid}.tar.gz`);
-  const wrapperDir = fs9.mkdtempSync(path10.join(tmpdir2(), `lotics-starter-`));
-  try {
-    await downloadToFile(result.bundle_url, bundleFile);
-    await runTar(["-xzf", bundleFile, "-C", wrapperDir], wrapperDir);
-    const sourceArchive = path10.join(wrapperDir, "source.tar.gz");
-    if (!fs9.existsSync(sourceArchive)) {
-      throw new Error(
-        `Starter bundle carried no source.tar.gz \u2014 the app (${result.app_id}) exists but has no code. Report this to the starter's publisher.`
-      );
-    }
-    await runTar(["-xzf", sourceArchive, "-C", targetPath], targetPath);
-  } finally {
-    if (fs9.existsSync(bundleFile)) fs9.unlinkSync(bundleFile);
-    fs9.rmSync(wrapperDir, { recursive: true, force: true });
-  }
-  for (const dir of ["knowledge", "fixtures"]) {
-    fs9.rmSync(path10.join(targetPath, dir), { recursive: true, force: true });
+    return { ...base, signin_url: null };
   }
-  const app = await client.getApp(result.app_id);
-  const kept = [];
-  await hydrateAppProject(client, targetPath, app, {
-    // Nothing is deployed yet; the build below is what mints v1.
-    stamp: { id: null, number: null },
-    kept
-  });
-  const serverDeployed = result.deployed ?? null;
   if (starter.owned_by_caller !== true) {
     warn(
-      serverDeployed !== null ? `
-Built ${starter.name} on Lotics \u2014 its package scripts and vite config are the
-  publisher's code, run in an isolated container rather than on your machine.${starter.is_official ? " Lotics reviewed this starter." : ""}` : `
-Building ${starter.name} \u2014 this runs its build on your machine (its package scripts
-  and vite config are the publisher's code, executed as you).${starter.is_official ? " Lotics reviewed this starter." : ""}`
+      `
+${starter.name} is the publisher's code \u2014 its apps, workflows and agents \u2014 and runs in
+  this workspace as you.${starter.is_official ? " Lotics reviewed this starter." : ""}`
     );
-  } else if (serverDeployed === null) {
-    note(`Building and deploying\u2026`);
   }
-  if (serverDeployed === null && result.build_error) {
-    warn(
-      `
-Lotics could not build ${starter.name} \u2014 building here instead.
-  ${result.build_error.split("\n")[0]}
-  The copy is fine: the tables, the records and the app all landed. Do NOT
-  copy again, and do not write a replacement app \u2014 only the build is missing.`
+  for (const app of apps) {
+    note(
+      app.error === null ? `  \u2713 ${app.name}  (${app.app_id}, v${app.version_number})` : `  \u2717 ${app.name}  (${app.app_id}): ${app.error.split("\n")[0]}`
     );
   }
-  const resumeDir = path10.relative(process.cwd(), targetPath) || ".";
-  try {
-    if (serverDeployed !== null) {
-      note(`Deployed v${serverDeployed.version_number} \u2014 built on Lotics, no Node needed here.`);
-    } else {
-      await prepareProjectToolchain(targetPath);
-      await appDeploy(client, {
-        projectDir: targetPath,
-        message: `Copied from starter ${starter.name}`
-      });
-    }
-  } catch (error52) {
-    const reason = error52 instanceof Error ? error52.message : String(error52);
-    throw new Error(
-      `${reason}
-
-The copy itself is DONE and nothing needs repeating: the tables, the sample
-records and the project all landed. Only the deploy is left.
-
-  Finish it:  cd ${resumeDir} && lotics app deploy -m "Copied from starter ${starter.name}"
-
-Do NOT re-run the copy \u2014 it would adopt the tables this one just created and
-insert the sample records again.`
+  const failed = apps.filter((app) => app.error !== null);
+  if (failed.length > 0) {
+    warn(
+      `
+${failed.length} app${failed.length === 1 ? "" : "s"} landed without a version: ${failed.map((app) => app.name).join(", ")}.
+  The copy is otherwise complete \u2014 do NOT copy again, and do not write a replacement
+  app. Report this to the starter's publisher; a fixed starter is copied into a fresh workspace.`
     );
+    process.exitCode = 1;
   }
   let signInUrl = null;
   try {
     const link = await client.login({
       return_link: true,
-      redirect_path: `/apps/${result.app_id}`
+      redirect_path: apps.length === 1 ? `/apps/${apps[0].app_id}` : "/apps"
     });
     signInUrl = link.url ?? null;
   } catch (error52) {
@@ -74288,15 +74209,11 @@ insert the sample records again.`
   note(
     `
 Done \u2014 ${starter.name} is live and yours.
-  App:     ${result.app_id}
-  Project: ${targetPath}
-
-  Edit anything: the tables, the app source, the templates, the docs. There is no
-  link back to the starter and nothing to upgrade \u2014 this is your app now.
-  Ship a change:  cd ${path10.relative(process.cwd(), targetPath) || "."} && lotics app deploy -m "<what changed>"
 
-  How to change it:  lotics docs building_an_app   (then \`lotics docs\` for the rest \u2014
-  the SDK and UI references are installed in this project, so they match its versions)`
+  Edit anything: the tables, the apps, the templates, the docs. There is no link
+  back to the starter and nothing to upgrade \u2014 this is your workspace now.
+  Change an app's code:  lotics app pull <app_id>   (then lotics app deploy -m "<what changed>")
+  How to change it:      lotics docs building_an_app   (then \`lotics docs\` for the rest)`
   );
   if (records > 0) {
     note(
@@ -74307,21 +74224,11 @@ Done \u2014 ${starter.name} is live and yours.
   }
   noteCopiedContent(templates, knowledgeDocs);
   if (signInUrl !== null) {
-    note(
-      `
+    note(`
   Open it \u2014 one-time sign-in link, expires in 15 minutes:
-    ${signInUrl}`
-    );
+    ${signInUrl}`);
   }
-  return {
-    starter_id: args.starter_id,
-    starter_name: starter.name,
-    version: result.version,
-    app_id: result.app_id,
-    project_dir: targetPath,
-    created,
-    signin_url: signInUrl
-  };
+  return { ...base, signin_url: signInUrl };
 }
 async function starterFixturesCapture(client, args) {
   const projectDir = path10.resolve(args.projectDir ?? process.cwd());
@@ -103064,7 +102971,7 @@ async function runKnowledgeCommand(client, subcommand, toolArgs, flags, restArgs
 import { spawn as spawn3 } from "node:child_process";
 import { createServer } from "node:http";
 import { readFileSync, writeFileSync, existsSync as existsSync2, mkdtempSync, rmSync, readdirSync } from "node:fs";
-import { tmpdir as tmpdir3 } from "node:os";
+import { tmpdir as tmpdir2 } from "node:os";
 import { join as join2, dirname, resolve, extname, basename } from "node:path";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
 import { setTimeout as sleep } from "node:timers/promises";
@@ -103163,7 +103070,7 @@ async function runPreviewCommand(filePath, flags) {
   });
   await new Promise((r) => server.listen(0, "127.0.0.1", () => r()));
   const httpPort = server.address().port;
-  const udd = mkdtempSync(join2(tmpdir3(), "lotics-render-"));
+  const udd = mkdtempSync(join2(tmpdir2(), "lotics-render-"));
   const child = spawn3(chrome, [
     "--headless=new",
     "--disable-gpu",
@@ -103686,10 +103593,10 @@ async function main() {
   if (command === "setup") {
     const starterId = subcommand;
     if (!starterId) {
-      console.error("Usage: lotics setup <starter_id> [path] [--email <you@co.com>] [--json]");
+      console.error("Usage: lotics setup <starter_id> [--email <you@co.com>] [--json]");
       console.error("       Creates an account if this machine has none, then copies the starter");
       console.error("       into its workspace: schema, templates, knowledge docs, sample records");
-      console.error("       and a deployed app. Ends with a one-time sign-in link.");
+      console.error("       and its apps, deployed. Ends with a one-time sign-in link.");
       console.error("       --json prints one object and nothing else.");
       process.exit(1);
     }
@@ -103725,9 +103632,9 @@ async function main() {
     }
     const { client: client2, ctx: ctx2 } = requireClient(flags);
     await resolveWorkspace(client2, ctx2);
+    if (toolArgs !== void 0) warn(`A path is no longer needed \u2014 a copy writes nothing to disk. Ignoring "${toolArgs}".`);
     const result = await starterInit(client2, {
       starter_id: starterId,
-      ...toolArgs !== void 0 ? { targetPath: toolArgs } : {},
       ...flags.noSampleData === true ? { noSampleData: true } : {},
       ...flags.adopt === true ? { adopt: true } : {}
     });
@@ -103759,18 +103666,18 @@ async function main() {
     }
     if (subcommand === "init") {
       if (!toolArgs) {
-        console.error("Usage: lotics starter init <starter_id> [path] [--no-sample-data] [--adopt]");
+        console.error("Usage: lotics starter init <starter_id> [--no-sample-data] [--adopt]");
         console.error("       Copies a starter into this workspace: schema, templates, knowledge");
-        console.error("       docs, sample records and an editable app project. Builds and deploys");
-        console.error("       locally, so it needs node and a few minutes.");
+        console.error("       docs, sample records and its apps, deployed on Lotics. Nothing is");
+        console.error("       written here; edit an app afterwards with lotics app pull <app_id>.");
         process.exit(1);
       }
       if (flags.json) setMachineOutput(true);
       const { client: client2, ctx: ctx2 } = requireClient(flags);
       await resolveWorkspace(client2, ctx2);
+      if (restArgs[0] !== void 0) warn(`A path is no longer needed \u2014 a copy writes nothing to disk. Ignoring "${restArgs[0]}".`);
       const result = await starterInit(client2, {
         starter_id: toolArgs,
-        ...restArgs[0] !== void 0 ? { targetPath: restArgs[0] } : {},
         ...flags.noSampleData === true ? { noSampleData: true } : {},
         ...flags.adopt === true ? { adopt: true } : {}
       });
@@ -103804,7 +103711,7 @@ async function main() {
       return;
     }
     console.error(
-      "Usage: lotics starter list | show <starter_id> | init <starter_id> [path] | fixtures capture"
+      "Usage: lotics starter list | show <starter_id> | init <starter_id> | fixtures capture"
     );
     process.exit(1);
   }

package/dist/src/client.d.ts

@@ -120,6 +120,68 @@ export interface ExtractFinding {
     area: string;
     message: string;
 }
+export interface StarterPublishRequest {
+    /** 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. */
+    knowledge_doc_ids?: string[];
+    /** First publish only: alias fixes before v1 freezes them. */
+    renames?: Array<{
+        from: string;
+        to: string;
+    }>;
+    /** First publish only: the listing name; defaults to the workspace's. */
+    name?: string;
+    /** First publish only: the listing description; defaults to the first app's. */
+    description?: string;
+    /** First publish only: the listing icon; defaults to the first app's. */
+    icon?: string;
+    /** First publish only: the listing accent colour; defaults to the first app's. */
+    color?: string;
+}
+export interface StarterPublishPreview {
+    /** The starter this would release into, or null when it would mint one. */
+    starter_id: string | null;
+    starter_name: string;
+    version: number;
+    apps: Array<{
+        alias: string;
+        app_id: string;
+        name: string;
+    }>;
+    /** Empty on a release — its aliases froze at v1. */
+    renamable_aliases: {
+        entities: string[];
+        fields: string[];
+        options: string[];
+        roles: string[];
+        templates: string[];
+    };
+    added_aliases: string[];
+    changed_artifacts: string[];
+    knowledge: {
+        added: string[];
+        removed: string[];
+        changed: string[];
+    };
+    findings: ExtractFinding[];
+}
+/** A publish is a job; this is the row the requester polls. */
+export interface StarterPublish {
+    id: string;
+    status: "pending" | "building" | "completed" | "failed";
+    /** Null until a first publish completes. */
+    starter_id: string | null;
+    version_id: string | null;
+    version: number | null;
+    app_ids: string[];
+    building_app_alias: string | null;
+    apps_built: number;
+    error: string | null;
+    created_at: string;
+    started_at: string | null;
+    finished_at: string | null;
+}
 /** Advisory knowledge warnings surfaced by install/upgrade (never block). */
 export interface KnowledgeWarnings {
     /** `knowledge_expects` doc names with no matching workspace doc. */
@@ -398,40 +460,35 @@ export declare class LoticsClient {
      * Copy a starter into the current workspace.
      *
      * Server-side this scaffolds the schema, creates the templates, docs and
-     * sample records, creates a BESPOKE app and materializes onto it — then stops.
-     * It deploys nothing: a starter ships source only, and the source has to be
-     * built where codegen can bake THIS workspace's field ids. `bundle_url` is a
-     * presigned GET of that source, and finishing the job is the caller's half.
+     * sample records, creates every app the starter carries and deploys each
+     * from its prebuilt dist — no build anywhere. `apps` reports each deploy;
+     * one that failed carries its `error` and the copy is complete around it.
      * Admin-only.
      */
     instantiateStarter(starter_id: string, body: {
         version?: number;
         no_sample_data?: boolean;
         adopt?: boolean;
-        /** Ask the server to build and deploy the copy, so this machine needs no Node. */
+        /**
+         * An echo for the rollout window: a server one release behind deploys
+         * only when asked, and this CLI cannot build a copy itself. Drop it once
+         * no such server is a rollback target.
+         */
         build_on_server?: boolean;
     }): Promise<{
-        app_id: string | null;
+        /** Each app's deploy, in contract order. `error` set and `deployed` null when one did not land. */
+        apps: Array<{
+            alias: string;
+            app_id: string;
+            name: string;
+            deployed: {
+                version_id: string;
+                version_number: number;
+            } | null;
+            error: string | null;
+        }>;
         starter_id: string;
         version: number;
-        bundle_url: string | null;
-        /**
-         * The version the SERVER deployed, when it did.
-         *
-         * Optional in this type on purpose: a server that predates the field omits
-         * it entirely, and it is absent rather than null. Callers must treat "not
-         * there" and "null" alike and build locally — assuming the request was
-         * honoured would report success over an app nobody built.
-         */
-        deployed?: {
-            version_id: string;
-            version_number: number;
-        } | null;
-        /**
-         * Why the server built nothing, when it was asked to and `deployed` is null.
-         * Absent from an older server's response for the same reason as `deployed`.
-         */
-        build_error?: string | null;
         binding: Record<string, Record<string, string>>;
         sample_record_ids: Record<string, string[]>;
         knowledge_warnings: {
@@ -525,120 +582,28 @@ export declare class LoticsClient {
         };
     }>>;
     /**
-     * Preview a release — the dry run behind `opctl app release`. Runs the
-     * binding-aware extract of the origin (aliases stable through the app's current
-     * binding) and reports the next version number, the new + changed aliases, the
-     * bundled-knowledge delta, and any extract findings (an `error` blocks the
-     * apply). An optional `knowledge` declaration (from the pulled app manifest)
-     * re-declares the bundle set — added/dropped/changed docs surface in the delta;
-     * omitted, the current corpus is reconstructed from the pin. No writes. Admin,
-     * owning-org only.
-     */
-    previewPackageRelease(app_id: string, opts?: {
-        /** alias → doc_id re-declaring the bundled-knowledge set (from the manifest). */
-        knowledge?: Array<{
-            alias: string;
-            doc_id: string;
-        }>;
-    }): Promise<{
-        package_id: string;
-        version: number;
-        added_aliases: string[];
-        changed_artifacts: string[];
-        /** Absent from a pre-declaration server (deploy skew) — treat as empty delta. */
-        knowledge?: {
-            added: string[];
-            removed: string[];
-            changed: string[];
-        };
-        findings: ExtractFinding[];
-    }>;
-    /**
-     * Release — snapshot the origin app into the next registry version. The server
-     * binding-aware-extracts it, repackages its deployed source + dist as the
-     * bundle, publishes the next `release`-channel version with the changelog, and
-     * re-pins the origin. An optional `knowledge` declaration re-declares the
-     * bundled-knowledge set (added/dropped/re-snapshotted docs; omitted preserves
-     * the current corpus). Error findings from extract surface as a 409; a
-     * missing/archived declared doc is a 400, a foreign-package doc a 409. Admin,
-     * owning-org only. Backs `opctl app release --yes`.
-     */
-    releasePackage(app_id: string, body: {
-        changelog: string;
-        /** alias → doc_id re-declaring the bundled-knowledge set (from the manifest). */
-        knowledge?: Array<{
-            alias: string;
-            doc_id: string;
-        }>;
-    }): Promise<{
-        package_id: string;
-        version: number;
-        added_aliases: string[];
-        changed_artifacts: string[];
-        /** Absent from a pre-declaration server (deploy skew) — treat as empty delta. */
-        knowledge?: {
-            added: string[];
-            removed: string[];
-            changed: string[];
-        };
-    }>;
+     * 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
+     * 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
+     * knowledge delta, and the findings (an `error` blocks the publish). No
+     * writes. Admin-only.
+     */
+    previewStarterPublish(opts: StarterPublishRequest): Promise<StarterPublishPreview>;
     /**
-     * Dry-run preview of a first-release — the `GET` behind `opctl app publish`
-     * (no `--yes`), the publish-side analogue of `previewPackageRelease`. The
-     * server runs the same fresh-alias extract + `src/` scan the apply runs
-     * (through any `renames`) and returns the package name it would mint, the
-     * auto-minted RENAMABLE aliases (the exact `--rename` keys), and the extract
-     * findings (an `error` blocks the apply). No writes. Admin-only.
+     * Publish this workspace's apps as a starter version — a JOB, because every
+     * app is built once against sentinel field keys and eleven builds outlast a
+     * request. Everything a request can refuse is refused here with nothing
+     * written: a blocking finding or another publish still running for this
+     * org (409), a missing deploy or a bad declaration (400). The response is
+     * the job to poll with `getStarterPublish`. Admin-only.
      */
-    previewPublishAppPackage(app_id: string, opts?: {
-        renames?: Array<{
-            from: string;
-            to: string;
-        }>;
-        /** alias → doc_id for the app's package-managed knowledge (from its manifest). */
-        knowledge?: Array<{
-            alias: string;
-            doc_id: string;
-        }>;
-    }): Promise<{
-        app_id: string;
-        package_name: string;
-        renamable_aliases: {
-            entities: string[];
-            fields: string[];
-            options: string[];
-            roles: string[];
-            templates: string[];
-            workflows: string[];
-        };
-        findings: ExtractFinding[];
-    }>;
-    /**
-     * First-release apply — mint a package from a BESPOKE app and publish v1 in one
-     * call (the `POST` behind `opctl app publish --yes`). The server extracts an
-     * alias-keyed contract from the app (fresh aliases; `renames` fixes them before
-     * v1 freezes), creates the registry package (name/description from the app),
-     * publishes v1 from the app's deployed source + dist, and pins the origin as
-     * installation #1. Error findings from extract surface as a 409. An
-     * already-linked app must use `releasePackage` instead. Admin-only. Backs
-     * `opctl app publish <app_id>`.
-     */
-    publishAppAsPackage(app_id: string, body: {
-        renames?: Array<{
-            from: string;
-            to: string;
-        }>;
+    requestStarterPublish(body: StarterPublishRequest & {
         changelog?: string | null;
-        /** alias → doc_id for the app's package-managed knowledge (from its manifest). */
-        knowledge?: Array<{
-            alias: string;
-            doc_id: string;
-        }>;
-    }): Promise<{
-        package_id: string;
-        version: number;
-        app_id: string;
-    }>;
+    }): Promise<StarterPublish>;
+    /** The state of a publish: which app is building, and the version once every dist is in. */
+    getStarterPublish(publish_id: string): Promise<StarterPublish>;
     /**
      * Resolve the display name + fields (incl. select options) of the given tables
      * — the schema `lotics app codegen` turns into the runtime `.lotics/app_fields.ts`

package/dist/src/client.js

@@ -343,10 +343,10 @@ export class LoticsClient {
     async editPackageListing(package_id, body) {
         return this.request("POST", `/v1/packages/${encodeURIComponent(package_id)}/listing`, body);
     }
-    // --- Packages (registry reads + installations) ---
-    // Authoring is server-side: apps via `POST /v1/apps/{id}/package-publish|release`,
-    // content packages via the `publish_content`/`release_content` tools. There is no
-    // client-side create-package / upload-bundle path.
+    // --- Starters (registry reads + copies) ---
+    // Authoring is server-side: apps via the publish job (`requestStarterPublish`),
+    // content starters via the `publish_content`/`release_content` tools. There is
+    // no client-side create-package / upload-bundle path.
     /**
      * The starters this organization can copy — Lotics-reviewed ones plus its own,
      * never a catalogue of everything published. The server returns exactly what
@@ -359,10 +359,9 @@ export class LoticsClient {
      * Copy a starter into the current workspace.
      *
      * Server-side this scaffolds the schema, creates the templates, docs and
-     * sample records, creates a BESPOKE app and materializes onto it — then stops.
-     * It deploys nothing: a starter ships source only, and the source has to be
-     * built where codegen can bake THIS workspace's field ids. `bundle_url` is a
-     * presigned GET of that source, and finishing the job is the caller's half.
+     * sample records, creates every app the starter carries and deploys each
+     * from its prebuilt dist — no build anywhere. `apps` reports each deploy;
+     * one that failed carries its `error` and the copy is complete around it.
      * Admin-only.
      */
     async instantiateStarter(starter_id, body) {
@@ -415,68 +414,51 @@ export class LoticsClient {
     async getWorkspaceDanglingReferences() {
         return this.request("GET", "/v1/workspaces/dangling-references");
     }
+    // --- Starter publishing (the authoring verbs; copying is `instantiateStarter`) ---
     /**
-     * Preview a release — the dry run behind `opctl app release`. Runs the
-     * binding-aware extract of the origin (aliases stable through the app's current
-     * binding) and reports the next version number, the new + changed aliases, the
-     * bundled-knowledge delta, and any extract findings (an `error` blocks the
-     * apply). An optional `knowledge` declaration (from the pulled app manifest)
-     * re-declares the bundle set — added/dropped/changed docs surface in the delta;
-     * omitted, the current corpus is reconstructed from the pin. No writes. Admin,
-     * owning-org only.
+     * 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
+     * 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
+     * knowledge delta, and the findings (an `error` blocks the publish). No
+     * writes. Admin-only.
      */
-    async previewPackageRelease(app_id, opts = {}) {
+    async previewStarterPublish(opts) {
         const params = new URLSearchParams();
-        if (opts.knowledge !== undefined && opts.knowledge.length > 0) {
-            params.set("knowledge", JSON.stringify(opts.knowledge));
-        }
-        const query = params.toString();
-        return this.request("GET", `/v1/apps/${encodeURIComponent(app_id)}/package-release${query ? `?${query}` : ""}`);
-    }
-    /**
-     * Release — snapshot the origin app into the next registry version. The server
-     * binding-aware-extracts it, repackages its deployed source + dist as the
-     * bundle, publishes the next `release`-channel version with the changelog, and
-     * re-pins the origin. An optional `knowledge` declaration re-declares the
-     * bundled-knowledge set (added/dropped/re-snapshotted docs; omitted preserves
-     * the current corpus). Error findings from extract surface as a 409; a
-     * missing/archived declared doc is a 400, a foreign-package doc a 409. Admin,
-     * owning-org only. Backs `opctl app release --yes`.
-     */
-    async releasePackage(app_id, body) {
-        return this.request("POST", `/v1/apps/${encodeURIComponent(app_id)}/package-release`, body);
-    }
-    /**
-     * Dry-run preview of a first-release — the `GET` behind `opctl app publish`
-     * (no `--yes`), the publish-side analogue of `previewPackageRelease`. The
-     * server runs the same fresh-alias extract + `src/` scan the apply runs
-     * (through any `renames`) and returns the package name it would mint, the
-     * auto-minted RENAMABLE aliases (the exact `--rename` keys), and the extract
-     * findings (an `error` blocks the apply). No writes. Admin-only.
-     */
-    async previewPublishAppPackage(app_id, opts = {}) {
-        const params = new URLSearchParams();
-        if (opts.knowledge !== undefined && opts.knowledge.length > 0) {
-            params.set("knowledge", JSON.stringify(opts.knowledge));
-        }
-        if (opts.renames !== undefined && opts.renames.length > 0) {
+        params.set("app_ids", opts.app_ids.join(","));
+        if (opts.knowledge_doc_ids !== undefined)
+            params.set("knowledge_doc_ids", opts.knowledge_doc_ids.join(","));
+        if (opts.renames !== undefined && opts.renames.length > 0)
             params.set("renames", JSON.stringify(opts.renames));
-        }
-        const query = params.toString();
-        return this.request("GET", `/v1/apps/${encodeURIComponent(app_id)}/package-publish${query ? `?${query}` : ""}`);
+        if (opts.name !== undefined)
+            params.set("name", opts.name);
+        if (opts.description !== undefined)
+            params.set("description", opts.description);
+        if (opts.icon !== undefined)
+            params.set("icon", opts.icon);
+        if (opts.color !== undefined)
+            params.set("color", opts.color);
+        return this.request("GET", `/v1/starters/publish-preview?${params.toString()}`);
+    }
+    /**
+     * Publish this workspace's apps as a starter version — a JOB, because every
+     * app is built once against sentinel field keys and eleven builds outlast a
+     * request. Everything a request can refuse is refused here with nothing
+     * written: a blocking finding or another publish still running for this
+     * org (409), a missing deploy or a bad declaration (400). The response is
+     * the job to poll with `getStarterPublish`. Admin-only.
+     */
+    async requestStarterPublish(body) {
+        const { color, ...rest } = body;
+        return this.request("POST", "/v1/starters/publishes", {
+            ...rest,
+            ...(color !== undefined ? { theme: { color } } : {}),
+        });
     }
-    /**
-     * First-release apply — mint a package from a BESPOKE app and publish v1 in one
-     * call (the `POST` behind `opctl app publish --yes`). The server extracts an
-     * alias-keyed contract from the app (fresh aliases; `renames` fixes them before
-     * v1 freezes), creates the registry package (name/description from the app),
-     * publishes v1 from the app's deployed source + dist, and pins the origin as
-     * installation #1. Error findings from extract surface as a 409. An
-     * already-linked app must use `releasePackage` instead. Admin-only. Backs
-     * `opctl app publish <app_id>`.
-     */
-    async publishAppAsPackage(app_id, body) {
-        return this.request("POST", `/v1/apps/${encodeURIComponent(app_id)}/package-publish`, body);
+    /** The state of a publish: which app is building, and the version once every dist is in. */
+    async getStarterPublish(publish_id) {
+        return this.request("GET", `/v1/starters/publishes/${encodeURIComponent(publish_id)}`);
     }
     /**
      * Resolve the display name + fields (incl. select options) of the given tables

package/docs/cli_reference.md

@@ -41,10 +41,10 @@ Per-command syntax, flags, contracts, and gotchas for the public `lotics` CLI. S
 | `lotics app deploy [--prune] -m <message>` | `-m` is OPTIONAL — omitted, the deploy derives the version message from what it actually pushed; pass `-m` when you have a reason worth recording. npm run build; tar source + dist; POST /v1/apps/{id}/versions multipart. **One command ships everything**: before the bundle moves, a deploy pushes every binding the project has ahead of the app — an edited workflow body or declaration, edited agent prose, a changed query — through `set_app_query`, then `set_app_workflow`, then `set_app_agent`, and fails the release if any push is refused. That order is required: an agent declares the query and workflow aliases it may call, so pushing it before its own new query is refused. A workflow's `description` is part of that push and is compared against the recorded baseline, not the live app — it lives on the workflow ROW, which `getApp` does not carry. It never AUTHORS a binding itself — those verbs stay the single writers — and each push carries the fingerprint the project last saw live (`lotics.synced`), so a stale checkout is refused rather than overwriting another author's edit. `package.json` means the same thing for both artifacts: editing `lotics.agents.<alias>.inputs`/`outputs` is pushed exactly like the workflow equivalent (only those two fields — `set_app_agent` merges, so everything the manifest does not model is left untouched). It also regenerates `.lotics/app_fields.ts` before building, since the build INLINES it and a stale copy would ship ids that no longer name what the source thinks they do. `lotics app check` reports the same set without pushing; neither has a `--strict`. What the version RECORDS as the aliases it calls — the set `remove_app_workflow` / `remove_app_query` / `remove_app_agent` consult to refuse unbinding one the served version still reaches — is read by the SERVER out of the source archive this deploy uploads, not reported by the deploy. That matters because the deploy is also what unbinds: a client supplying the evidence used to refuse its own removal cannot be checked by it. After a successful deploy it warns about any alias the source CALLS that is NOT bound, and **names the inverse** — but as a TRANSITION, not a state: bindings this bundle *stopped* calling, compared against what the previous deploy's bundle called (`package.json#lotics.bundle_calls`, which a deploy records). It does NOT remove them: **`--prune` does, and only when passed.** The distinction is what makes the report readable. A static scan sees the bundle's call sites and an agent's `query_aliases`/`workflow_aliases`; it cannot see `lotics run run_app_query`/`run_app_workflow`, whose whole contract is that the alias is bound server-side, or chat's call under `app:use` — and the capability catalog publishes EVERY declared alias to both. So an alias the bundle never called is the normal shape of an agent-facing binding, not a dead one, and reporting it fired on every app built to be driven by an agent while pointing at the flag that deletes it. An alias that WAS called and is not any more is different: that is a call site the author removed, which is compile-, check- and deploy-clean while the binding keeps serving. **No baseline ⇒ nothing reported** — a manifest from before this field, or one a `pull` rebuilt from the server row, costs one quiet deploy and then self-heals, because silence is the only honest answer with nothing to compare. The baseline is STICKY: it advances only once nothing is outstanding, so the `--prune` this warning names still finds the transition on a later run instead of reporting ✓ over a binding that still serves. Pruning runs AFTER the version is live, because the removal tools refuse an alias the SERVED version still declares — so doing it first is refused by the guard that makes it safe. `--prune` is skipped ENTIRELY (with a warning, never a failure) when the source computes an alias at run time, since the scan cannot tell which binding that reaches and pruning "the rest" would be guessing with a deletion. **A removal DELETES the local declaration too** — `package.json#lotics.<kind>.<alias>` and its `synced` baseline — because leaving it would undo the prune: the manifest is what the next plain deploy pushes FROM, so the binding came straight back. That makes the act destructive rather than merely reversible, so what it deleted is written to `.lotics/pruned/<kind>/<alias>.json` and the ✓ names that file plus the `set` verb that re-binds it, on the same line. (These trees are never committed, so git is not the fallback; `lotics app pull --from-version <apv_…>` is the only other route back.) After a successful prune the generated companions are regenerated from the narrowed manifest — the `.d.ts` set and, when a query was pruned, `.lotics/app_fields.ts`, whose table set is derived from the surviving query ASTs. A table named ONLY by the pruned query leaves `F`/`OPT`, which is reported: if your source still addresses it, add the table id to `package.json#lotics.codegen.tables`. A local write that fails at any of this reports what could not be written and which aliases were already unbound server-side; it never fails the release, which is already live. A binding that will not unbind is reported and does NOT fail the release: the version is live and correct — and the server refuses to unbind a WORKFLOW this workspace has actually run (a recorded execution means a caller the source cannot name), which surfaces here as `✗ could not unbind …` with the date it last ran. After a successful deploy it also REFRESHES the `.lotics/workflows/<alias>.globals.d.ts` of any alias whose `// lotics:declaration` stamp says this deploy moved its declaration (only those — refreshing every bound alias would cost one round trip each on every deploy to fix something only ever wrong right after a manifest edit), from the manifest declaration, re-wrapping the SAME on-disk body (never re-fetching it, so local edits survive). A deploy is the moment the manifest becomes real, so it is also the moment the local types stop matching it — and the author's next act is usually `workflow set`, whose body would otherwise be typechecked against the declaration as it stood before this deploy. Non-fatal: the release already shipped, and stale types never fail it. |
 | `lotics app versions [app_id]` | `GET /v1/apps/{id}/versions` — print deploy history newest-first (version number, timestamp, deployer name, build status, the `-m` message; `*` marks the currently-served version). app_id from the local manifest, or pass one to inspect any app without pulling it. Admin-only server-side (mirrors deploy + source download). Answers "what shipped, when, by whom" — e.g. whether a fix was live at an incident's time. Title → stderr, table → stdout (pipeable). |
 | `lotics app codegen [path]` | Regenerate `.lotics/*` from the manifest + workspace schema **without a deploy**. The three `.d.ts` companions (`app_{workflows,queries,agents}.d.ts`) are always rewritten (synchronous, no network). When credentials resolve, also rewrites the **runtime** `.lotics/app_fields.ts` — a real `.ts` exporting `F` (table→field→`"fld_…"`) + `OPT` (table→select-field→option→`"opt_…"`) keyed by display-name aliases, for the tables the app's queries reference (+ optional `package.json#lotics.codegen.tables` allowlist). **There is one form, and that is what makes a starter's source portable**: the keys are slugified DISPLAY NAMES and a starter carries its labels verbatim, so running codegen in a copy's own workspace emits the same keys pointing at that workspace's ids — no binding fetched at load, no prebuilt bundle to keep in step. Also refreshes each bound workflow's `.lotics/workflows/<alias>.globals.d.ts` + re-wraps its EXISTING `src/workflows/<alias>.ts` body in the current envelope (strips + re-wraps; never re-fetches the body, so local edits survive). **`.lotics/` is reconciled to the manifest, not merely added to** — a `<alias>.globals.d.ts` whose alias the manifest no longer declares is DELETED. Only that exact filename shape is removed; anything else in the directory is left alone. The reconcile runs before the credential branch, so it happens offline too. The authored counterpart is never deleted — a `src/workflows/<alias>.ts` the manifest does not declare is NAMED instead (`check` and `set` both take their alias set from the manifest, so editing an undeclared body is a silent no-op). A getApp / binding / schema / dts-fetch failure is non-fatal (warns, keeps the last-generated files). **Re-silvers `package.json#lotics.agents`** from the live app row whenever its `inputs`/`outputs` disagree, then rewrites the agent `.d.ts` from the refreshed block: that block is a mirror AND the offline seed for `useAgentRun` typings, so a stale copy types the app against an agent that does not exist. The write is surgical and order-preserving, so it changes only the fields that actually differ. A hand edit to that block is therefore reverted — it never changed the agent anyway; to change one, `set_app_agent`. |
-| `lotics setup <starter_id> [path] [--email <addr>] [--json]` | **The whole first run, in one command.** Creates an account when this machine has no credential (the same call `auth signup` makes — `--name` and `--timezone` apply), then does exactly what `starter init` does, then prints the one-time sign-in link. It exists because the two-command form has a seam where the FIRST command exists only to produce a credential for the second, and a caller pasting a prompt has to get both right. **`--email` is only for creating an account**: with a credential already resolvable it is REFUSED rather than obeyed, because the two can name different organizations and preferring either one silently copies a starter into an org the caller did not name — the message says how to do each thing on purpose. Without it, `setup` copies into the account you already have and is a pure alias for `starter init`. **`--json` prints one object on stdout and nothing else** — `organization_id`, `workspace_id`, `app_id`, `project_dir`, `signin_url`, and `created` — which NAMES what landed (`tables`, `templates` and `knowledge_docs` are alias arrays; `sample_records` is a row count, since rows are not named things). Aliases rather than counts because the next question is about a particular artifact: a copied template carries the publisher's wording and a copied knowledge doc describes how they work, so "which of these should be mine?" is the conversation a copy starts, and a count cannot begin it. Plus a `warnings` array carrying everything the prose form would have said out of band — an unbindable knowledge doc, a sign-in link that could not be minted, and the notice naming whose build is about to run on this machine. A warning is never merely silenced: when the command fails with an error before it can emit, the ones it had collected go to stderr alongside it. npm's and vite's own output is captured under `--json` and surfaced only if the build FAILS, where it rides out in the error. Reachable with no install: `npx -y @lotics/cli start …`. |
+| `lotics setup <starter_id> [--email <addr>] [--json]` | **The whole first run, in one command.** Creates an account when this machine has no credential (the same call `auth signup` makes — `--name` and `--timezone` apply), then does exactly what `starter init` does, then prints the one-time sign-in link. It exists because the two-command form has a seam where the FIRST command exists only to produce a credential for the second, and a caller pasting a prompt has to get both right. **`--email` is only for creating an account**: with a credential already resolvable it is REFUSED rather than obeyed, because the two can name different organizations and preferring either one silently copies a starter into an org the caller did not name — the message says how to do each thing on purpose. Without it, `setup` copies into the account you already have and is a pure alias for `starter init`. A path positional is accepted and IGNORED with a warning — nothing is written to disk any more — so a prompt written for an older CLI still runs. **`--json` prints one object on stdout and nothing else** — `organization_id`, `workspace_id`, `app_ids` (alias → id), `apps` (each app's `version_number`, or its `error`), `signin_url`, and `created` — which NAMES what landed (`tables`, `templates` and `knowledge_docs` are alias arrays; `sample_records` is a row count, since rows are not named things). Aliases rather than counts because the next question is about a particular artifact: a copied template carries the publisher's wording and a copied knowledge doc describes how they work, so "which of these should be mine?" is the conversation a copy starts, and a count cannot begin it. Plus a `warnings` array carrying everything the prose form would have said out of band — an unbindable knowledge doc, a sign-in link that could not be minted, the publisher's-code disclosure, an app that landed without a version. A warning is never merely silenced: when the command fails with an error before it can emit, the ones it had collected go to stderr alongside it. Reachable with no install: `npx -y @lotics/cli setup …`. |
 | `lotics starter list` | **Works with no account**, and that is the point: whether to copy a starter or build from scratch is decided before one exists, so requiring a key would mean signing up to learn the answer was no. Unauthenticated it lists what Lotics publishes (`GET /v1/starters/official`, public). Authenticated it is the org shelf — The starters this organization can copy — Lotics-reviewed ones plus its own, each with at least one released version. Deliberately NOT a catalogue of everything published: the server returns exactly what a copy would be allowed to take, so the list can never offer something that then refuses. Admin-only. |
 | `lotics starter show <starter_id>` | One starter's name, description, current version and trust standing (`official` — reviewed by Lotics; `your organization's own`). Read it before copying a starter you did not publish. |
-| `lotics starter init <starter_id> [path]` | **Copy a starter into this workspace.** Server-side it scaffolds the tables and fields, creates the document templates and knowledge docs, inserts the sample records, creates a BESPOKE app and materializes its queries, workflows and agents onto it. Then it stops: a starter ships **source only**, with no prebuilt bundle, so the app source is downloaded here, hydrated against the live app (the same steps `app pull` runs), built, and deployed — which is why this needs node and a few minutes, and why the app is not servable until the deploy lands. **What you get is yours outright**: an ordinary app plus ordinary tables, with no link back to the starter, nothing pinned, and nothing to upgrade. Edit any of it. **It builds the publisher's code on your machine** — the copy has to build where your workspace's field ids are, so `npm run build` runs their build script and vite loads their `vite.config.ts` in Node, as you. Dependencies install with `npm ci --ignore-scripts` — the lockfile's exact tree (so a starter published months ago resolves the same packages today), and no lifecycle scripts (the path that fires before you run anything). Neither changes the build itself. That is why provenance is the gate: **copyable only if the starter is Lotics-reviewed or your own organization published it** — copying runs the author's code (its bundle, its workflows, its agents) under YOUR authority, so provenance is the gate, enforced server-side. **Refuses a workspace that already has tables** unless `--adopt`: scaffold matches an entity by DISPLAY NAME, so a starter declaring `Contacts` would bind to yours. `--json` prints one object on stdout instead of progress (the shape is under `lotics setup`) and captures npm/vite output unless the build fails. `--no-sample-data` skips the sample records; with them, the created record ids are reported — they are ordinary records, delete them whenever. Resolves and ANNOUNCES its workspace first (`lotics → <org> / <workspace>` on stderr). Admin-only. Authoring the registry (`starter publish/release/unpublish`) stays operator-only. |
+| `lotics starter init <starter_id>` | **Copy a starter into this workspace.** Server-side it scaffolds the tables and fields, creates the document templates and knowledge docs, inserts the sample records, creates every app the starter carries and materializes each one's queries, workflows and agents onto it — then deploys each app from the dist the starter was published with, rewriting the publisher's sentinel field keys to this workspace's. No build runs anywhere, nothing is written to this machine, and nothing here needs node: the apps are live when the command returns. **What you get is yours outright**: ordinary apps plus ordinary tables, with no link back to the starter, nothing pinned, and nothing to upgrade. Edit any of it — `lotics app pull <app_id>` is how an app's code is edited afterwards. **The publisher's code runs in your workspace as you** — its apps, workflows and agents — which is why provenance is the gate: **copyable only if the starter is Lotics-reviewed or your own organization published it**, enforced server-side; the disclosure is printed (and carried in `--json`'s `warnings`) whenever the starter is not your own. **Refuses a workspace that already has tables** unless `--adopt`: scaffold matches an entity by DISPLAY NAME, so a starter declaring `Contacts` would bind to yours. An app whose deploy failed is reported by name with its reason and the exit is non-zero, but the copy is complete around it — the tables, the records and the app row exist — so it must not be run again; the publisher fixes the starter and it is copied into a fresh workspace. The sign-in link lands on the app when there is one, else on the workspace's app list. `--json` prints one object on stdout instead of progress (the shape is under `lotics setup`). `--no-sample-data` skips the sample records; with them, the created record ids are reported — they are ordinary records, delete them whenever. Resolves and ANNOUNCES its workspace first (`lotics → <org> / <workspace>` on stderr). Admin-only. Authoring the registry (`opctl starter publish/unpublish`) stays operator-only. |
 | `lotics starter fixtures capture [--entity <alias> ...] [--limit <n>]` | **(authoring)** Write this app's live records into the project as `fixtures/<entity-alias>.json` — the sample data a starter carries, so a copy lands with something in it. Run from an app project; the app id comes from its manifest. The alias-keyed shape is produced server-side, because the aliases are minted when the starter is extracted and exist nowhere a project can read them. `--entity` is repeatable and comma-separated; omitted, every table the app declares is captured. **Capture a linked set in ONE call** — a link between two rows only resolves within a single capture, so taking companies and contacts separately drops the edge between them (it says so when it happens). `--limit` bounds rows per table (default 10, max 200). **READ WHAT IT WROTE before committing**: these rows are created verbatim in every workspace that copies the starter, so a real customer name, price or address captured here is published. Files, formulas, rollups, lookups and autonumbers are never captured — the platform writes those. Admin-only; writes nothing to the workspace. |
 | `lotics upgrade` | Update this CLI in place. Runs the same installer a person would, chosen by how THIS copy arrived: an npm install upgrades through npm, a script install re-runs the script — the runtime knows which (the executable is compiled, the npm bin runs under node), so nobody has to. It downloads nothing itself; resolving a version, verifying the checksum and replacing a running executable already exist in the installers, and a second copy of that inside the binary would be a second thing to get right. Replacing the binary while it runs is safe — a rename leaves the running image mapped on unix, and on Windows the installer moves the old aside precisely because the file is in use. Already current is a no-op that says so. Needs no auth. |
 | `lotics docs` \| `lotics docs <area>` | The index of the reference docs, **resolved out of the packages installed beside this project** — never carried by this CLI. **Both levels are discovered by looking**: every `@lotics/*` package carrying an `AGENTS.md` or a `docs/` in any `node_modules/@lotics` from the current directory UPWARD (nearest wins, so a hoisted root copy never shadows the one a project's own imports resolve to), and within each, every area it actually ships. Titles come from each file's own `# heading` and the version from the installed `package.json`, so a doc OR a whole package added upstream appears with no change to this CLI, and a skewed install is visible rather than reassuring. A package's index is named after the package (`lotics docs ui`), never `index`. `@lotics/app-sdk`, `@lotics/ui` and `@lotics/cli` sort first as a reading ORDER, not a filter. Both the index and `<area>` print to **stdout** — the index is the payload of a bare `lotics docs`, so `lotics docs | grep -i excel` works — with only the provenance line on stderr, so `lotics docs ai > ai.md` is the doc alone; a name two packages share is refused with both qualified forms (`lotics docs ui/templates`) rather than resolved silently. Needs no auth. Outside a project only `@lotics/cli`'s own resolve, and it says so. |

package/package.json

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