@lotics/cli 0.181.1 → 0.183.0

package/dist/src/cli.js

@@ -44516,14 +44516,13 @@ var LoticsClient = class {
     return this.request("POST", "/v1/apps", body);
   }
   /**
-   * Retire (or `undo` un-retire) a registry package (backs `lotics app
-   * unpublish` — the endpoint/audit action keep the `retire` name to avoid API
-   * churn). Retiring refuses NEW installs and hides the package from non-owning
-   * orgs; existing installations keep working and may still upgrade. Owner-org
-   * admin-only.
+   * 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
+   * copied; copies already made are unaffected — they never linked back.
+   * Owner-org admin-only.
    */
-  async retirePackage(package_id, body) {
-    return this.request("POST", `/v1/packages/${encodeURIComponent(package_id)}/retire`, body);
+  async unpublishStarter(starter_id, body) {
+    return this.request("POST", `/v1/starters/${encodeURIComponent(starter_id)}/unpublish`, body);
   }
   /**
    * Edit a starter's registry listing — the name and description a stranger
@@ -44532,13 +44531,12 @@ var LoticsClient = class {
    * A version is an immutable snapshot; the listing is not. Omit a field to
    * leave it, pass `description: null` to clear it. Owner-org admin-only.
    */
-  async editPackageListing(package_id, body) {
-    return this.request("POST", `/v1/packages/${encodeURIComponent(package_id)}/listing`, body);
+  async editStarterListing(starter_id, body) {
+    return this.request("POST", `/v1/starters/${encodeURIComponent(starter_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, through the publish job (`requestStarterPublish`).
+  // There is no client-side create-starter / 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 +44549,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) {
@@ -44598,12 +44595,12 @@ var LoticsClient = class {
    * Fetch a registry starter's metadata (`latest_version` and the Lotics-backed
    * `is_official` trust badge). Admin-only; cross-tenant by id.
    */
-  async getPackage(package_id) {
-    return this.request("GET", `/v1/packages/${encodeURIComponent(package_id)}`);
+  async getStarter(starter_id) {
+    return this.request("GET", `/v1/starters/${encodeURIComponent(starter_id)}`);
   }
-  /** Version history newest-first (no contract payloads) — backs `opctl package show`. Admin-only. */
-  async listPackageVersions(package_id) {
-    return this.request("GET", `/v1/packages/${encodeURIComponent(package_id)}/versions`);
+  /** Version history newest-first (no contract payloads) — backs `opctl starter show`. Admin-only. */
+  async listStarterVersions(starter_id) {
+    return this.request("GET", `/v1/starters/${encodeURIComponent(starter_id)}/versions`);
   }
   /**
    * Workspace-wide dangling-reference sweep — active app/workflow artifacts
@@ -44613,74 +44610,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 +45679,7 @@ function resultSideEffects(result) {
 }
 
 // src/version.ts
-var VERSION = "0.181.1";
+var VERSION = "0.183.0";
 
 // src/timezone.ts
 function machineTimezone() {
@@ -45881,11 +45849,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"
@@ -45922,13 +45890,13 @@ var COMMANDS = [
       "  lotics starter list                  Starters you can copy into this workspace. Works with",
       "                                       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 show <starter_id>     Its name, description, current version, tile and trust",
+      "                                       standing \u2014 read it before copying one you did not publish",
+      "  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>",
@@ -45946,7 +45914,7 @@ var COMMANDS = [
   {
     verbs: ["docs"],
     help: [
-      "  lotics docs                          List the reference docs of the INSTALLED packages",
+      "  lotics docs                          List the reference docs the npm packages in node_modules ship",
       "  lotics docs <area>                   Print one (e.g. 'lotics docs ai')"
     ]
   },
@@ -46495,10 +46463,10 @@ export default defineConfig({
     // openly at the asset layer \u2014 the map would expose the very source the gate
     // exists to protect. Source maps aren't needed to run the app.
     sourcemap: false,
-    // Top-level await (package projects' generated .lotics/app_fields.ts
-    // resolves the installation binding at module load) needs es2022 \u2014 Vite's
-    // default 'modules' baseline is es2020 and esbuild hard-fails TLA there.
-    // Dev already transforms at esnext, so this only aligns the prod build.
+    // Vite's default 'modules' baseline is es2020, which is older than the
+    // browsers a Lotics app is served to and older than what dev already
+    // transforms at (esnext). Pinned so the prod build does not silently
+    // down-level past a feature the dev server accepted.
     target: "es2022",
   },
   server: {
@@ -46521,10 +46489,10 @@ export default defineConfig({
   },
   test: {
     environment: "jsdom",
-    // Global test setup, run before every test file (empty until an author fills it)
-    // collects. A package-linked app's generated .lotics/app_fields.ts awaits it
-    // at module load; without the stub that network call throws under jsdom and
-    // every test that imports the app graph fails to collect. See vitest.setup.ts.
+    // Global test setup, run before every test file. Ships empty \u2014 the slot is
+    // the author's (custom matchers, a fetch stub, timezone pinning). It must
+    // EXIST either way: setupFiles naming a missing file makes vitest fail to
+    // load every test. See vitest.setup.ts.
     setupFiles: ["./${VITEST_SETUP_FILENAME}"],
     // RN packages ship Flow (\`import typeof\`) in their native source, reached
     // transitively by RN-Web components (pickers, calendars, anything touching
@@ -46892,18 +46860,12 @@ declare module "*.css";
     {
       path: "src/harness.test.ts",
       content: `import { describe, test, expect } from "vitest";
-import { getAppBinding } from "@lotics/app-sdk";
 
 /**
  * The one test the scaffold seeds, and it is about the TEST SETUP rather than
  * about your app \u2014 so editing src/App.tsx can never break it, and \`npm test\`
- * never has to be green over zero tests.
- *
- * What it pins: tests run under jsdom, and vitest.setup.ts's echo stub answers
- * for \`getAppBinding\`. That second one is the whole reason the setup file
- * exists: a package-linked app's generated .lotics/app_fields.ts awaits it while
- * a test file is still COLLECTING, so without the stub every test fails before
- * any of them runs \u2014 including pure logic tests that never touch a field id.
+ * never has to be green over zero tests. It imports nothing of yours and
+ * nothing generated, so it passes on a fresh clone before any codegen has run.
  *
  * Delete it once you have tests of your own, or keep it; it costs nothing.
  */
@@ -46911,13 +46873,6 @@ describe("test harness", () => {
   test("runs in a DOM", () => {
     expect(typeof document).toBe("object");
   });
-
-  test("resolves the app binding from the setup stub, so the app graph collects", async () => {
-    const binding = await getAppBinding();
-    // The echo stub answers any alias with a self-identifying ':test:' id \u2014 one
-    // that can never be mistaken for a real fld_\u2026 from the workspace.
-    expect(binding.fields["anything.at.all"]).toContain(":test:");
-  });
 });
 `
     },
@@ -74054,7 +74009,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) {
@@ -74117,7 +74071,7 @@ async function starterList(client) {
       description: s.description,
       tags: [
         s.is_official ? "official" : null,
-        s.owned_by_caller === true ? "yours" : null
+        s.owned_by_caller ? "yours" : null
       ].filter((t) => t !== null)
     }))
   );
@@ -74125,19 +74079,17 @@ async function starterList(client) {
   lotics starter init <starter_id>   Copy one into this workspace`);
 }
 async function starterShow(client, starter_id) {
-  const starter = await client.getPackage(starter_id);
+  const starter = await client.getStarter(starter_id);
   console.log(`${starter.name}  (${starter.id})`);
   if (starter.description) console.log(starter.description);
   console.log(
     `
-version   ${starter.latest_version}
-trust     ${starter.is_official ? "official \u2014 reviewed by Lotics" : starter.owned_by_caller === true ? "your organization's own" : "not copyable from this organization"}`
+version      ${starter.latest_version}
+trust        ${starter.is_official ? "official \u2014 reviewed by Lotics" : starter.owned_by_caller ? "your organization's own" : "not copyable from this organization"}`
   );
-  if (starter.icon !== void 0) {
-    console.log(`icon      ${starter.icon ?? "none \u2014 copies show a generic tile"}`);
-  }
+  console.log(`icon         ${starter.icon ?? "none \u2014 the shelf shows a generic tile"}`);
   if (starter.retired_at !== null) {
-    console.log(`retired   ${starter.retired_at} \u2014 can no longer be copied`);
+    console.log(`unpublished  ${starter.retired_at} \u2014 can no longer be copied`);
   }
 }
 function reportKnowledgeWarnings(warnings) {
@@ -74151,130 +74103,58 @@ function reportKnowledgeWarnings(warnings) {
   answering from nowhere. Create them with those names, or edit the agent.`
   );
 }
-function instantiateBody(args) {
-  return {
-    ...args.noSampleData === true ? { no_sample_data: true } : {},
-    ...args.adopt === true ? { adopt: true } : {},
-    build_on_server: true
-  };
-}
 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.`);
-  }
+  const starter = await client.getStarter(args.starter_id);
   note(
     `Copying ${starter.name}${starter.is_official ? " (official)" : ""} into this workspace\u2026`
   );
-  const result = await client.instantiateStarter(args.starter_id, instantiateBody(args));
+  const result = await client.instantiateStarter(args.starter_id, {
+    ...args.noSampleData === true ? { no_sample_data: true } : {},
+    ...args.adopt === true ? { adopt: true } : {}
+  });
   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} app${apps.length === 1 ? "" : "s"}.`
   );
   reportKnowledgeWarnings(result.knowledge_warnings);
-  if (result.app_id === null || result.bundle_url === null) {
-    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 });
-  }
-  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) {
+  if (!starter.owned_by_caller) {
     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) {
@@ -74286,17 +74166,15 @@ insert the sample records again.`
     signInUrl = null;
   }
   note(
-    `
+    (apps.length > 0 && failed.length === apps.length ? `
+${starter.name} landed, but none of its ${apps.length} app${apps.length === 1 ? "" : "s"} is live.
+` : `
 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,18 +74185,16 @@ 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,
+    app_ids: Object.fromEntries(apps.map((app) => [app.alias, app.app_id])),
+    apps,
     created,
     signin_url: signInUrl
   };
@@ -103064,7 +102940,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 +103039,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",
@@ -103675,7 +103551,7 @@ async function main() {
     console.error(
       `--version prints this CLI's version and takes no argument; it cannot be combined with a command.
   The CLI version:            lotics --version
-  A package version to take:  operator-only for now \u2014 \`lotics upgrade\` takes the next release.`
+  A starter's version:        a copy always takes the latest; there is no flag for an older one.`
     );
     process.exit(1);
   }
@@ -103686,10 +103562,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);
     }
@@ -103699,7 +103575,7 @@ async function main() {
       const email3 = flags.email ?? (process.stdin.isTTY ? await prompt("Email: ") : "");
       if (!email3) {
         console.error(
-          "This machine has no Lotics credential yet, so `start` needs an email to create one:\n  lotics setup " + starterId + " --email you@company.com"
+          "This machine has no Lotics credential yet, so `setup` needs an email to create one:\n  lotics setup " + starterId + " --email you@company.com"
         );
         process.exit(1);
       }
@@ -103725,9 +103601,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 +103635,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 +103680,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);
   }