@lotics/cli 0.70.0 → 0.73.0

package/dist/src/cli.js

@@ -12243,12 +12243,12 @@ var require_tokens = __commonJS({
       });
     }
     exports2.assignCategoriesMapProp = assignCategoriesMapProp;
-    function singleAssignCategoriesToksMap(path8, nextNode) {
-      utils_1.forEach(path8, function(pathNode) {
+    function singleAssignCategoriesToksMap(path9, nextNode) {
+      utils_1.forEach(path9, function(pathNode) {
         nextNode.categoryMatchesMap[pathNode.tokenTypeIdx] = true;
       });
       utils_1.forEach(nextNode.CATEGORIES, function(nextCategory) {
-        var newPath = path8.concat(nextNode);
+        var newPath = path9.concat(nextNode);
         if (!utils_1.contains(newPath, nextCategory)) {
           singleAssignCategoriesToksMap(newPath, nextCategory);
         }
@@ -14011,10 +14011,10 @@ var require_interpreter = __commonJS({
       /** @class */
       (function(_super) {
         __extends(AbstractNextPossibleTokensWalker2, _super);
-        function AbstractNextPossibleTokensWalker2(topProd, path8) {
+        function AbstractNextPossibleTokensWalker2(topProd, path9) {
           var _this = _super.call(this) || this;
           _this.topProd = topProd;
-          _this.path = path8;
+          _this.path = path9;
           _this.possibleTokTypes = [];
           _this.nextProductionName = "";
           _this.nextProductionOccurrence = 0;
@@ -14068,9 +14068,9 @@ var require_interpreter = __commonJS({
       /** @class */
       (function(_super) {
         __extends(NextAfterTokenWalker2, _super);
-        function NextAfterTokenWalker2(topProd, path8) {
-          var _this = _super.call(this, topProd, path8) || this;
-          _this.path = path8;
+        function NextAfterTokenWalker2(topProd, path9) {
+          var _this = _super.call(this, topProd, path9) || this;
+          _this.path = path9;
           _this.nextTerminalName = "";
           _this.nextTerminalOccurrence = 0;
           _this.nextTerminalName = _this.path.lastTok.name;
@@ -14767,10 +14767,10 @@ var require_lookahead = __commonJS({
       }
       return result;
     }
-    function pathToHashKeys(path8) {
+    function pathToHashKeys(path9) {
       var keys2 = [""];
-      for (var i2 = 0; i2 < path8.length; i2++) {
-        var tokType = path8[i2];
+      for (var i2 = 0; i2 < path9.length; i2++) {
+        var tokType = path9[i2];
         var longerKeys = [];
         for (var j = 0; j < keys2.length; j++) {
           var currShorterKey = keys2[j];
@@ -15082,9 +15082,9 @@ var require_checks = __commonJS({
       return errors;
     }
     exports2.validateRuleIsOverridden = validateRuleIsOverridden;
-    function validateNoLeftRecursion(topRule, currRule, errMsgProvider, path8) {
-      if (path8 === void 0) {
-        path8 = [];
+    function validateNoLeftRecursion(topRule, currRule, errMsgProvider, path9) {
+      if (path9 === void 0) {
+        path9 = [];
       }
       var errors = [];
       var nextNonTerminals = getFirstNoneTerminal(currRule.definition);
@@ -15097,15 +15097,15 @@ var require_checks = __commonJS({
           errors.push({
             message: errMsgProvider.buildLeftRecursionError({
               topLevelRule: topRule,
-              leftRecursionPath: path8
+              leftRecursionPath: path9
             }),
             type: parser_1.ParserDefinitionErrorType.LEFT_RECURSION,
             ruleName
           });
         }
-        var validNextSteps = utils.difference(nextNonTerminals, path8.concat([topRule]));
+        var validNextSteps = utils.difference(nextNonTerminals, path9.concat([topRule]));
         var errorsFromNextSteps = utils.map(validNextSteps, function(currRefRule) {
-          var newPath = utils.cloneArr(path8);
+          var newPath = utils.cloneArr(path9);
           newPath.push(currRefRule);
           return validateNoLeftRecursion(topRule, currRefRule, errMsgProvider, newPath);
         });
@@ -20127,7 +20127,7 @@ var require_BufferList = __commonJS({
         this.head = this.tail = null;
         this.length = 0;
       };
-      BufferList.prototype.join = function join(s) {
+      BufferList.prototype.join = function join2(s) {
         if (this.length === 0) return "";
         var p = this.head;
         var ret = "" + p.data;
@@ -22102,8 +22102,8 @@ var require_lib2 = __commonJS({
         return this;
       }
       var p = this.constructor;
-      return this.then(resolve2, reject3);
-      function resolve2(value) {
+      return this.then(resolve3, reject3);
+      function resolve3(value) {
         function yes() {
           return value;
         }
@@ -22256,8 +22256,8 @@ var require_lib2 = __commonJS({
       }
       return out;
     }
-    Promise2.resolve = resolve;
-    function resolve(value) {
+    Promise2.resolve = resolve2;
+    function resolve2(value) {
       if (value instanceof this) {
         return value;
       }
@@ -22714,8 +22714,8 @@ var require_utils4 = __commonJS({
       var result = transform[inputType][outputType](input);
       return result;
     };
-    exports2.resolve = function(path8) {
-      var parts = path8.split("/");
+    exports2.resolve = function(path9) {
+      var parts = path9.split("/");
       var result = [];
       for (var index = 0; index < parts.length; index++) {
         var part = parts[index];
@@ -22788,10 +22788,10 @@ var require_utils4 = __commonJS({
       var promise = external.Promise.resolve(inputData).then(function(data) {
         var isBlob = support.blob && (data instanceof Blob || ["[object File]", "[object Blob]"].indexOf(Object.prototype.toString.call(data)) !== -1);
         if (isBlob && typeof FileReader !== "undefined") {
-          return new external.Promise(function(resolve, reject2) {
+          return new external.Promise(function(resolve2, reject2) {
             var reader = new FileReader();
             reader.onload = function(e) {
-              resolve(e.target.result);
+              resolve2(e.target.result);
             };
             reader.onerror = function(e) {
               reject2(e.target.error);
@@ -23346,7 +23346,7 @@ var require_StreamHelper = __commonJS({
       }
     }
     function accumulate(helper, updateCallback) {
-      return new external.Promise(function(resolve, reject2) {
+      return new external.Promise(function(resolve2, reject2) {
         var dataArray = [];
         var chunkType = helper._internalType, resultType = helper._outputType, mimeType = helper._mimeType;
         helper.on("data", function(data, meta) {
@@ -23360,7 +23360,7 @@ var require_StreamHelper = __commonJS({
         }).on("end", function() {
           try {
             var result = transformZipOutput(resultType, concat2(chunkType, dataArray), mimeType);
-            resolve(result);
+            resolve2(result);
           } catch (e) {
             reject2(e);
           }
@@ -28568,18 +28568,18 @@ var require_object = __commonJS({
       var object = new ZipObject(name, zipObjectContent, o);
       this.files[name] = object;
     };
-    var parentFolder = function(path8) {
-      if (path8.slice(-1) === "/") {
-        path8 = path8.substring(0, path8.length - 1);
+    var parentFolder = function(path9) {
+      if (path9.slice(-1) === "/") {
+        path9 = path9.substring(0, path9.length - 1);
       }
-      var lastSlash = path8.lastIndexOf("/");
-      return lastSlash > 0 ? path8.substring(0, lastSlash) : "";
+      var lastSlash = path9.lastIndexOf("/");
+      return lastSlash > 0 ? path9.substring(0, lastSlash) : "";
     };
-    var forceTrailingSlash = function(path8) {
-      if (path8.slice(-1) !== "/") {
-        path8 += "/";
+    var forceTrailingSlash = function(path9) {
+      if (path9.slice(-1) !== "/") {
+        path9 += "/";
       }
-      return path8;
+      return path9;
     };
     var folderAdd = function(name, createFolders) {
       createFolders = typeof createFolders !== "undefined" ? createFolders : defaults2.createFolders;
@@ -29473,7 +29473,7 @@ var require_load = __commonJS({
     var Crc32Probe = require_Crc32Probe();
     var nodejsUtils = require_nodejsUtils();
     function checkEntryCRC32(zipEntry) {
-      return new external.Promise(function(resolve, reject2) {
+      return new external.Promise(function(resolve2, reject2) {
         var worker = zipEntry.decompressed.getContentWorker().pipe(new Crc32Probe());
         worker.on("error", function(e) {
           reject2(e);
@@ -29481,7 +29481,7 @@ var require_load = __commonJS({
           if (worker.streamInfo.crc32 !== zipEntry.decompressed.crc32) {
             reject2(new Error("Corrupted zip : CRC32 mismatch"));
           } else {
-            resolve();
+            resolve2();
           }
         }).resume();
       });
@@ -29581,8 +29581,8 @@ var require_lib3 = __commonJS({
 // src/cli.ts
 import dns from "node:dns";
 import net2 from "node:net";
-import fs8 from "node:fs";
-import path7 from "node:path";
+import fs9 from "node:fs";
+import path8 from "node:path";
 import readline from "node:readline";
 
 // src/client.ts
@@ -29680,8 +29680,8 @@ var LoticsClient = class {
     }
     return headers;
   }
-  async request(method, path8, body) {
-    const url = `${this.baseUrl}${path8}`;
+  async request(method, path9, body) {
+    const url = `${this.baseUrl}${path9}`;
     const headers = this.buildHeaders();
     const init = { method, headers };
     if (body !== void 0) {
@@ -29698,9 +29698,22 @@ var LoticsClient = class {
   setWorkspaceId(id) {
     this.workspaceId = id;
   }
+  /** The workspace id the client targets (the `x-workspace-id` header), if resolved. */
+  getWorkspaceId() {
+    return this.workspaceId;
+  }
   async listWorkspaces() {
     return this.request("GET", "/v1/workspaces");
   }
+  /**
+   * Resolve one workspace's info by id from the org's workspace list (the only
+   * API-key-accessible source carrying `is_dev`). Returns null when the
+   * workspace isn't visible to these credentials.
+   */
+  async getWorkspaceInfo(id) {
+    const workspaces = await this.listWorkspaces();
+    return workspaces.find((w) => w.id === id) ?? null;
+  }
   async createWorkspace(body) {
     return this.request("POST", "/v1/workspaces", body);
   }
@@ -29749,6 +29762,175 @@ var LoticsClient = class {
   async createApp(body) {
     return this.request("POST", "/v1/apps", body);
   }
+  /**
+   * Install an app package version into the current workspace — scaffolds the
+   * data model, deploys the package bundle, materializes its
+   * queries/workflows/agents, and pins the installation. Returns the resulting
+   * installation app. `version` omitted installs the latest published version.
+   */
+  async installAppPackage(package_id, body) {
+    return this.request(
+      "POST",
+      `/v1/app-packages/${encodeURIComponent(package_id)}/installations`,
+      body
+    );
+  }
+  /**
+   * Eject an installation from its package — re-deploy the pinned version's
+   * source as a workspace-owned app version, then sever the package link
+   * (clears `package_id`/`package_version`, stamps `ejected_at`). One-way: the
+   * app becomes a normal bespoke app and can no longer be upgraded. Returns the
+   * resulting app.
+   */
+  async ejectAppPackage(app_id) {
+    return this.request("POST", `/v1/apps/${encodeURIComponent(app_id)}/eject`);
+  }
+  /**
+   * Extract a DRAFT app package from an existing bespoke app — the promotion
+   * read (docs/app_packages.md § Promotion). Pure: nothing is written. Returns
+   * the alias-keyed draft `contract` (opaque to the CLI — the server is the
+   * validating authority), the origin workspace's `binding` (which doubles as
+   * the adopt binding), a findings `report` (any `error` ⇒ not publishable
+   * as-is), and the file-backed `template_files` the CLI must stage into the
+   * project at their `bytes_ref` paths. Backs `lotics package extract`.
+   * Admin-only.
+   */
+  async extractAppPackage(app_id) {
+    return this.request("GET", `/v1/apps/${encodeURIComponent(app_id)}/package-extract`);
+  }
+  /**
+   * Adopt a published package onto an EXISTING (bespoke or ejected) app — the
+   * final promotion step. The workspace already holds the concrete objects, so
+   * nothing is scaffolded or rewritten: the server verifies the `binding` is
+   * complete, live, and FAITHFUL to the version's contract, then writes only the
+   * installation pin (the app becomes installation #1, upgradeable again). A
+   * ConflictError names the aliases that diverge. `version` omitted adopts the
+   * latest. Backs `lotics package adopt`. Admin-only.
+   */
+  async adoptAppPackage(app_id, body) {
+    return this.request("POST", `/v1/apps/${encodeURIComponent(app_id)}/package-adopt`, body);
+  }
+  /**
+   * Fleet upgrade — bring every installation of a package across the CALLER'S
+   * org to the target version (latest when omitted) in one call. Hands-off
+   * applies only where the preview is clean; installations with breaking/
+   * drift/modified-core findings are skipped and reported for the normal
+   * per-installation consent flow. Backs `lotics package fleet-upgrade`.
+   * Admin-only; org-scoped (no workspace header needed).
+   */
+  async fleetUpgradeAppPackage(package_id, body) {
+    return this.request(
+      "POST",
+      `/v1/app-packages/${encodeURIComponent(package_id)}/fleet-upgrade`,
+      body
+    );
+  }
+  // --- App packages (registry authoring + dev harness) ---
+  /**
+   * Create a registry app package — the Lotics-owned, workspace-agnostic
+   * blueprint. `lotics package publish` calls this on first publish (when the
+   * local manifest has no `package_id`), then publishes version 1 against the
+   * returned id. Admin-only.
+   */
+  async createAppPackage(body) {
+    return this.request("POST", "/v1/app-packages", body);
+  }
+  /**
+   * Fetch a registry app package's metadata (incl. `latest_version` and the
+   * Lotics-backed `is_official` trust badge). Admin-only; cross-tenant by id.
+   */
+  async getAppPackage(package_id) {
+    return this.request("GET", `/v1/app-packages/${encodeURIComponent(package_id)}`);
+  }
+  /**
+   * Publish a new immutable package version — multipart upload of the alias-keyed
+   * contract (JSON) + the prebuilt code bundle (a gzipped tarball carrying
+   * `source.tar.gz` + `dist.tar.gz` members). The server validates the contract +
+   * bundle, then allocates the next monotonic version. The `contract` is opaque
+   * JSON to the transport (the server is the validating authority). Admin-only.
+   */
+  async publishAppPackageVersion(package_id, args) {
+    const formData = new FormData();
+    formData.append("contract", JSON.stringify(args.contract));
+    formData.append(
+      "bundle",
+      new Blob([new Uint8Array(args.bundle)], { type: "application/gzip" }),
+      "bundle.tar.gz"
+    );
+    if (args.changelog) formData.append("changelog", args.changelog);
+    const url = `${this.baseUrl}/v1/app-packages/${encodeURIComponent(package_id)}/versions`;
+    const response = await fetch(url, {
+      method: "POST",
+      headers: this.buildHeaders(),
+      // no Content-Type — fetch sets the multipart boundary
+      body: formData
+    });
+    if (!response.ok) await this.throwResponseError(response);
+    return response.json();
+  }
+  /**
+   * Upgrade a package installation to a newer published version — extends the
+   * binding additively, re-materializes the target version's
+   * queries/workflows/agents (preserving workspace overlay), prunes dropped
+   * package artifacts, and bumps the pin. `version` omitted upgrades to the
+   * latest. Returns the resulting app. Admin-only.
+   */
+  async upgradeAppPackage(app_id, body) {
+    return this.request(
+      "POST",
+      `/v1/apps/${encodeURIComponent(app_id)}/package-upgrade`,
+      body
+    );
+  }
+  /**
+   * Preview a package upgrade — the additive plan, informational removals,
+   * breaking contract changes, the binding drift report, and the modified-core
+   * report — with no writes. Admin-only.
+   */
+  async previewAppPackageUpgrade(app_id, opts = {}) {
+    const query = opts.version !== void 0 ? `?version=${opts.version}` : "";
+    return this.request(
+      "GET",
+      `/v1/apps/${encodeURIComponent(app_id)}/package-upgrade${query}`
+    );
+  }
+  /**
+   * Re-bind a package role to a different workspace group (the current group
+   * still exists). Re-materializes at the pinned version; refuses over
+   * modified-core findings. Admin-only.
+   */
+  async rebindAppPackageRole(app_id, body) {
+    return this.request(
+      "POST",
+      `/v1/apps/${encodeURIComponent(app_id)}/package-rebind-role`,
+      body
+    );
+  }
+  /**
+   * Workspace-wide dangling-reference sweep — active app/workflow artifacts
+   * whose prefixed schema ids no longer resolve. Backs
+   * `lotics workspace doctor`. Admin-only.
+   */
+  async getWorkspaceDanglingReferences() {
+    return this.request("GET", "/v1/workspaces/dangling-references");
+  }
+  /**
+   * Health check for a package installation — version pin vs. registry latest,
+   * binding drift, and locally modified core artifacts. Read-only; backs
+   * `lotics package doctor`. Admin-only.
+   */
+  async getAppPackageHealth(app_id) {
+    return this.request("GET", `/v1/apps/${encodeURIComponent(app_id)}/package-health`);
+  }
+  /**
+   * Reset a package installation in a DEV workspace — drop the package-owned
+   * scaffolded tables and re-scaffold clean. Hard-gated server-side to dev
+   * workspaces (a non-dev workspace is refused). Returns the resulting app.
+   * Admin-only.
+   */
+  async resetAppPackage(app_id) {
+    return this.request("POST", `/v1/apps/${encodeURIComponent(app_id)}/package-reset`);
+  }
   /**
    * 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`
@@ -31112,10 +31294,11 @@ async function dispatchRpc(client, body, opts) {
   }
   switch (body.op) {
     case "context": {
-      const who = await client.whoami();
+      const [who, app] = await Promise.all([client.whoami(), client.getApp(body.app_id)]);
       return {
         member_id: who.member_id,
-        comments_enabled: opts?.commentsEnabled ?? false
+        comments_enabled: opts?.commentsEnabled ?? false,
+        config: app.config ?? {}
       };
     }
     case "query": {
@@ -31553,8 +31736,8 @@ async function startDevServer(args) {
   );
   let stopped = false;
   let stoppingResolve = null;
-  const stoppingPromise = new Promise((resolve) => {
-    stoppingResolve = resolve;
+  const stoppingPromise = new Promise((resolve2) => {
+    stoppingResolve = resolve2;
   });
   viteChild.on("exit", (code, signal) => {
     if (!stopped) {
@@ -31655,11 +31838,11 @@ async function startDevServer(args) {
     res.writeHead(404, { "Content-Type": "text/plain" });
     res.end("Not Found");
   });
-  await new Promise((resolve, reject2) => {
+  await new Promise((resolve2, reject2) => {
     server.once("error", reject2);
     server.listen(wrapperPort, () => {
       server.off("error", reject2);
-      resolve();
+      resolve2();
     });
   });
   async function stopAll() {
@@ -31668,11 +31851,11 @@ async function startDevServer(args) {
     if (!viteChild.killed) {
       viteChild.kill("SIGINT");
     }
-    await new Promise((resolve) => server.close(() => resolve()));
+    await new Promise((resolve2) => server.close(() => resolve2()));
     stoppingResolve?.();
   }
-  const ready = new Promise((resolve) => {
-    setTimeout(resolve, 800);
+  const ready = new Promise((resolve2) => {
+    setTimeout(resolve2, 800);
   });
   return {
     port: wrapperPort,
@@ -31688,22 +31871,22 @@ async function pickPort(preferred, ...avoid) {
   if (!avoid.includes(preferred) && await isPortFree(preferred)) {
     return preferred;
   }
-  return new Promise((resolve, reject2) => {
+  return new Promise((resolve2, reject2) => {
     const srv = net.createServer();
     srv.once("error", reject2);
     srv.listen(0, () => {
       const addr = srv.address();
       const port = typeof addr === "object" && addr ? addr.port : 0;
-      srv.close(() => port ? resolve(port) : reject2(new Error("Failed to pick port")));
+      srv.close(() => port ? resolve2(port) : reject2(new Error("Failed to pick port")));
     });
   });
 }
 function isPortFree(port) {
-  return new Promise((resolve) => {
+  return new Promise((resolve2) => {
     const srv = net.createServer();
-    srv.once("error", () => resolve(false));
+    srv.once("error", () => resolve2(false));
     srv.listen(port, () => {
-      srv.close(() => resolve(true));
+      srv.close(() => resolve2(true));
     });
   });
 }
@@ -31995,6 +32178,7 @@ function walk(node, visit) {
     case "sort":
     case "limit":
     case "unpivot":
+    case "unnest":
       walk(node.from, visit);
       return;
     case "join":
@@ -32337,7 +32521,7 @@ async function fetchWorkflowGlobals(client, projectDir, app_id, alias) {
   }
 }
 function runTar(args, cwd) {
-  return new Promise((resolve, reject2) => {
+  return new Promise((resolve2, reject2) => {
     const proc = spawn2("tar", args, { cwd, stdio: ["ignore", "ignore", "pipe"] });
     let stderr = "";
     proc.stderr.on("data", (chunk) => {
@@ -32345,17 +32529,17 @@ function runTar(args, cwd) {
     });
     proc.on("error", reject2);
     proc.on("exit", (code) => {
-      if (code === 0) resolve();
+      if (code === 0) resolve2();
       else reject2(new Error(`tar ${args.join(" ")} failed with exit ${code}: ${stderr}`));
     });
   });
 }
 function runNpm(args, cwd) {
-  return new Promise((resolve, reject2) => {
+  return new Promise((resolve2, reject2) => {
     const proc = spawn2("npm", args, { cwd, stdio: "inherit", env: ipv4ChildEnv(process.env) });
     proc.on("error", reject2);
     proc.on("exit", (code) => {
-      if (code === 0) resolve();
+      if (code === 0) resolve2();
       else reject2(new Error(`npm ${args.join(" ")} exited with code ${code}`));
     });
   });
@@ -32851,11 +33035,11 @@ async function appDev(client, args) {
   console.error(`  Ctrl-C to stop.
 `);
   openBrowser(url);
-  await new Promise((resolve) => {
+  await new Promise((resolve2) => {
     const onSig = () => {
       process.off("SIGINT", onSig);
       process.off("SIGTERM", onSig);
-      resolve();
+      resolve2();
     };
     process.on("SIGINT", onSig);
     process.on("SIGTERM", onSig);
@@ -33162,6 +33346,724 @@ function escapeRegExp(s) {
   return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
 
+// src/package_commands.ts
+import fs6 from "node:fs";
+import path7 from "node:path";
+import { tmpdir as tmpdir2 } from "node:os";
+
+// src/file_command_io.ts
+import fs5 from "node:fs";
+import path6 from "node:path";
+var CliError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "CliError";
+  }
+};
+function fail(message) {
+  throw new CliError(message);
+}
+function writeFileAtomic(filePath, bytes) {
+  const dir = path6.dirname(path6.resolve(filePath));
+  const tmp = path6.join(dir, `.${path6.basename(filePath)}.${process.pid}.${Date.now()}.tmp`);
+  fs5.writeFileSync(tmp, bytes);
+  try {
+    fs5.renameSync(tmp, filePath);
+  } catch (error) {
+    try {
+      fs5.unlinkSync(tmp);
+    } catch {
+    }
+    throw error;
+  }
+  console.error(`Wrote ${filePath}`);
+}
+
+// src/package_commands.ts
+var CONTRACT_FILE = "contract.json";
+var ADOPT_BINDING_FILE = "adopt_binding.json";
+function packageJsonPath(projectDir) {
+  return path7.join(projectDir, "package.json");
+}
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function readPackageProject(projectDir) {
+  const pkgPath2 = packageJsonPath(projectDir);
+  if (!fs6.existsSync(pkgPath2)) {
+    throw new Error(
+      `No package.json in ${projectDir}. Run this inside a package project (lotics package new <name>).`
+    );
+  }
+  const parsed = JSON.parse(fs6.readFileSync(pkgPath2, "utf-8"));
+  if (!isPlainObject(parsed)) throw new Error(`Malformed package.json in ${projectDir}.`);
+  const lotics = parsed.lotics;
+  const pkg2 = isPlainObject(lotics) ? lotics.package : void 0;
+  if (!isPlainObject(pkg2) || typeof pkg2.name !== "string") {
+    throw new Error(
+      `${pkgPath2} has no lotics.package manifest \u2014 not a package project. Use "lotics package new <name>".`
+    );
+  }
+  const dev = {};
+  if (isPlainObject(pkg2.dev)) {
+    for (const [ws, entry] of Object.entries(pkg2.dev)) {
+      if (isPlainObject(entry) && typeof entry.app_id === "string" && typeof entry.version === "number") {
+        dev[ws] = { app_id: entry.app_id, version: entry.version };
+      }
+    }
+  }
+  const manifest = {
+    id: typeof pkg2.id === "string" ? pkg2.id : null,
+    name: pkg2.name,
+    description: typeof pkg2.description === "string" ? pkg2.description : null,
+    version: typeof pkg2.version === "number" ? pkg2.version : null,
+    dev
+  };
+  return { pkgJson: parsed, manifest };
+}
+function writePackageManifest(projectDir, project) {
+  const next = {
+    ...project.pkgJson,
+    lotics: {
+      ...isPlainObject(project.pkgJson.lotics) ? project.pkgJson.lotics : {},
+      package: project.manifest
+    }
+  };
+  writeFileAtomic(
+    packageJsonPath(projectDir),
+    new TextEncoder().encode(JSON.stringify(next, null, 2) + "\n")
+  );
+}
+function sanitizePackageJsonForSource(pkgJson) {
+  const lotics = isPlainObject(pkgJson.lotics) ? pkgJson.lotics : {};
+  const pkg2 = isPlainObject(lotics.package) ? lotics.package : {};
+  const { dev: _dev, ...pkgWithoutDev } = pkg2;
+  return {
+    ...pkgJson,
+    lotics: { ...lotics, package: pkgWithoutDev }
+  };
+}
+function draftPackageProjectFromApp(appPkgJson, args) {
+  const { lotics: _appManifest, ...rest } = appPkgJson;
+  return {
+    pkgJson: rest,
+    manifest: { id: null, name: args.name, description: args.description, version: null, dev: {} }
+  };
+}
+function parseAdoptBindingFile(raw, expectedAppId) {
+  if (!isPlainObject(raw) || typeof raw.app_id !== "string" || typeof raw.workspace_id !== "string" || !isPlainObject(raw.binding)) {
+    throw new Error(
+      "Malformed .lotics/adopt_binding.json \u2014 expected { app_id, workspace_id, binding }."
+    );
+  }
+  if (raw.app_id !== expectedAppId) {
+    throw new Error(
+      `.lotics/adopt_binding.json records app ${raw.app_id}, but you are adopting ${expectedAppId}. A binding maps one app's concrete ids and must never be applied to another \u2014 run "lotics package extract ${expectedAppId}" to produce the right pin.`
+    );
+  }
+  return {
+    app_id: raw.app_id,
+    workspace_id: raw.workspace_id,
+    binding: raw.binding
+  };
+}
+function formatExtractReport(report) {
+  const order = ["error", "warning", "info"];
+  const lines = order.flatMap(
+    (severity) => report.filter((f) => f.severity === severity).map((f) => `  [${f.severity}] ${f.area}: ${f.message}`)
+  );
+  return { lines, hasError: report.some((f) => f.severity === "error") };
+}
+function readContract(projectDir) {
+  const contractPath = path7.join(projectDir, CONTRACT_FILE);
+  if (!fs6.existsSync(contractPath)) {
+    throw new Error(
+      `No ${CONTRACT_FILE} in ${projectDir}. A package project declares its data model there.`
+    );
+  }
+  return JSON.parse(fs6.readFileSync(contractPath, "utf-8"));
+}
+var SOURCE_STAGE_EXCLUDES = /* @__PURE__ */ new Set([
+  "node_modules",
+  "dist",
+  ".lotics",
+  ".git",
+  "bundle.tar.gz",
+  "package.json"
+]);
+function stagePackageSource(projectDir, sourceStage) {
+  const project = readPackageProject(projectDir);
+  fs6.mkdirSync(sourceStage, { recursive: true });
+  for (const entry of fs6.readdirSync(projectDir)) {
+    if (SOURCE_STAGE_EXCLUDES.has(entry) || entry.endsWith(".tsbuildinfo")) continue;
+    fs6.cpSync(path7.join(projectDir, entry), path7.join(sourceStage, entry), { recursive: true });
+  }
+  fs6.writeFileSync(
+    path7.join(sourceStage, "package.json"),
+    JSON.stringify(sanitizePackageJsonForSource(project.pkgJson), null, 2) + "\n"
+  );
+}
+async function buildPackageBundle(projectDir) {
+  console.error("Building...");
+  await runNpm(["run", "build"], projectDir);
+  const distDir = path7.join(projectDir, "dist");
+  if (!fs6.existsSync(distDir)) {
+    throw new Error(
+      `Build did not produce a dist/ directory in ${projectDir}. Check that 'npm run build' is configured correctly.`
+    );
+  }
+  const stage = fs6.mkdtempSync(path7.join(tmpdir2(), "lotics-pkg-"));
+  const bundlePath = path7.join(tmpdir2(), `lotics-bundle-${Date.now()}.tar.gz`);
+  try {
+    console.error("Packaging source...");
+    const sourceStage = path7.join(stage, "source");
+    stagePackageSource(projectDir, sourceStage);
+    await runTar(["-czf", path7.join(stage, "source.tar.gz"), "-C", sourceStage, "."], projectDir);
+    console.error("Packaging dist...");
+    await runTar(["-czf", path7.join(stage, "dist.tar.gz"), "-C", distDir, "."], projectDir);
+    console.error("Bundling...");
+    await runTar(["-czf", bundlePath, "source.tar.gz", "dist.tar.gz"], stage);
+    return fs6.readFileSync(bundlePath);
+  } finally {
+    fs6.rmSync(stage, { recursive: true, force: true });
+    if (fs6.existsSync(bundlePath)) fs6.unlinkSync(bundlePath);
+  }
+}
+function starterContract(name) {
+  return {
+    entities: [
+      {
+        alias: "item",
+        label: name,
+        description: `Records managed by the ${name} package.`,
+        fields: [
+          { alias: "name", label: "Name", type: "text", required: true },
+          { alias: "notes", label: "Notes", type: "text" },
+          {
+            alias: "status",
+            label: "Status",
+            type: "select",
+            options: [
+              { alias: "open", label: "Open", color: "blue" },
+              { alias: "done", label: "Done", color: "green" }
+            ]
+          }
+        ]
+      }
+    ],
+    roles: [],
+    templates: [],
+    queries: [
+      {
+        alias: "items",
+        ast: {
+          kind: "from_table",
+          from_entity: "item",
+          sort: [{ field_key: "name", order: "asc" }]
+        }
+      }
+    ],
+    workflows: [],
+    agents: [],
+    config: [
+      { alias: "heading", label: "List heading", type: "text", default: name }
+    ]
+  };
+}
+async function packageNew(args) {
+  const targetPath = path7.resolve(args.targetPath ?? appDirName(args.name));
+  if (fs6.existsSync(targetPath) && fs6.readdirSync(targetPath).length > 0) {
+    throw new Error(`Target directory ${targetPath} is not empty.`);
+  }
+  fs6.mkdirSync(targetPath, { recursive: true });
+  const files = buildStarterTemplate({
+    app_name: args.name,
+    app_id: "",
+    workspace_id: ""
+  });
+  for (const file of files) {
+    const fullPath = path7.join(targetPath, file.path);
+    if (file.path === "package.json") {
+      const pkg2 = JSON.parse(file.content);
+      const manifest = {
+        id: null,
+        name: args.name,
+        description: null,
+        version: null,
+        dev: {}
+      };
+      pkg2.lotics = { package: manifest };
+      fs6.mkdirSync(path7.dirname(fullPath), { recursive: true });
+      fs6.writeFileSync(fullPath, JSON.stringify(pkg2, null, 2) + "\n");
+      continue;
+    }
+    fs6.mkdirSync(path7.dirname(fullPath), { recursive: true });
+    fs6.writeFileSync(fullPath, file.content);
+  }
+  fs6.writeFileSync(
+    path7.join(targetPath, CONTRACT_FILE),
+    JSON.stringify(starterContract(args.name), null, 2) + "\n"
+  );
+  console.error(`Scaffolded ${files.length + 1} files into ${targetPath}`);
+  console.error("Installing npm dependencies...");
+  await runNpm(["install"], targetPath);
+  console.error(`
+Ready. Next steps:`);
+  console.error(`  cd ${path7.relative(process.cwd(), targetPath) || "."}`);
+  console.error(`  # edit contract.json + src/App.tsx, then run it against a dev workspace:`);
+  console.error(`  lotics workspace create "<name> dev" --dev`);
+  console.error(`  lotics package dev --workspace <dev_ws>`);
+}
+async function packageBuild(args) {
+  const projectDir = path7.resolve(args.projectDir ?? process.cwd());
+  readPackageProject(projectDir);
+  const bundle = await buildPackageBundle(projectDir);
+  const out = path7.join(projectDir, "bundle.tar.gz");
+  fs6.writeFileSync(out, bundle);
+  console.error(`Built ${out} (${(bundle.byteLength / 1024).toFixed(1)} KB)`);
+}
+async function publishVersion(client, projectDir, opts) {
+  const project = readPackageProject(projectDir);
+  const contract = readContract(projectDir);
+  let packageId = project.manifest.id;
+  if (packageId === null) {
+    const pkg2 = await client.createAppPackage({
+      name: project.manifest.name,
+      description: project.manifest.description
+    });
+    packageId = pkg2.id;
+    project.manifest.id = packageId;
+    writePackageManifest(projectDir, project);
+    console.error(`Created package ${pkg2.name} (${pkg2.id}).`);
+  }
+  const bundle = await buildPackageBundle(projectDir);
+  console.error("Publishing version...");
+  const version = await client.publishAppPackageVersion(packageId, {
+    contract,
+    bundle,
+    changelog: opts.changelog ?? null
+  });
+  project.manifest.version = version.version;
+  writePackageManifest(projectDir, project);
+  return { package_id: packageId, version: version.version };
+}
+async function packagePublish(client, args) {
+  const projectDir = path7.resolve(args.projectDir ?? process.cwd());
+  const { package_id, version } = await publishVersion(client, projectDir, {
+    changelog: args.changelog
+  });
+  console.error(`Published ${package_id} v${version}.`);
+  console.error(`  Install it:  lotics package install ${package_id} --version ${version}`);
+}
+function assertDevWorkspace(workspace) {
+  if (workspace.is_dev === true) return;
+  throw new Error(
+    `Workspace "${workspace.name}" (${workspace.id}) is not a dev workspace. "lotics package dev"/"sync" scaffold package tables into the target workspace, so it must be a throwaway dev workspace. Create one with "lotics workspace create <name> --dev" and pass --workspace <dev_ws>.`
+  );
+}
+async function syncToDevWorkspace(client, projectDir) {
+  const devWorkspaceId = client.getWorkspaceId();
+  if (!devWorkspaceId) {
+    throw new Error(
+      "No dev workspace selected. Pass --workspace <dev_ws> (a workspace created with --dev)."
+    );
+  }
+  const workspace = await client.getWorkspaceInfo(devWorkspaceId);
+  if (!workspace) {
+    throw new Error(
+      `Workspace ${devWorkspaceId} is not accessible with these credentials. Pass --workspace <dev_ws> (a workspace created with --dev).`
+    );
+  }
+  assertDevWorkspace(workspace);
+  const { package_id, version } = await publishVersion(client, projectDir, {
+    changelog: "dev sync"
+  });
+  const project = readPackageProject(projectDir);
+  const existing = project.manifest.dev[devWorkspaceId];
+  let appId;
+  if (existing) {
+    console.error(`Upgrading dev installation ${existing.app_id} \u2192 v${version}...`);
+    const app = await client.upgradeAppPackage(existing.app_id, { version });
+    appId = app.id;
+  } else {
+    console.error(`Installing ${package_id} v${version} into dev workspace ${devWorkspaceId}...`);
+    const app = await client.installAppPackage(package_id, { version });
+    appId = app.id;
+  }
+  project.manifest.dev[devWorkspaceId] = { app_id: appId, version };
+  writePackageManifest(projectDir, project);
+  const installed = await client.getApp(appId);
+  return { app_id: appId, app_name: installed.name, workspace_id: devWorkspaceId, version };
+}
+async function packageSync(client, args) {
+  const projectDir = path7.resolve(args.projectDir ?? process.cwd());
+  const result = await syncToDevWorkspace(client, projectDir);
+  console.error(
+    `Synced ${result.app_name} v${result.version} \u2192 ${result.app_id} (workspace ${result.workspace_id}).`
+  );
+}
+async function packageDev(client, args) {
+  const projectDir = path7.resolve(args.projectDir ?? process.cwd());
+  const synced = await syncToDevWorkspace(client, projectDir);
+  const handle = await startDevServer({
+    projectDir,
+    app_id: synced.app_id,
+    app_name: synced.app_name,
+    workspace_id: synced.workspace_id,
+    api_url: client.baseUrl,
+    port: args.port,
+    vitePort: args.vitePort,
+    client
+  });
+  await handle.ready;
+  const url = `http://localhost:${handle.port}`;
+  console.error(`
+  lotics package dev`);
+  console.error(`  package:   ${synced.app_name} (dev installation ${synced.app_id} v${synced.version})`);
+  console.error(`  workspace: ${synced.workspace_id} (dev)`);
+  if (client.viewAsMemberId) {
+    console.error(`  view as:   ${client.viewAsMemberId}`);
+  }
+  console.error(`  vite:      http://localhost:${handle.vitePort}/`);
+  console.error(`  open:      ${url}`);
+  console.error(`  rpc:       ${client.baseUrl} (via Bearer API key)
+`);
+  console.error(`  Edit contract.json then re-run "lotics package dev" / "lotics package sync" to migrate.`);
+  console.error(`  Ctrl-C to stop.
+`);
+  openBrowser(url);
+  await new Promise((resolve2) => {
+    const onSig = () => {
+      process.off("SIGINT", onSig);
+      process.off("SIGTERM", onSig);
+      resolve2();
+    };
+    process.on("SIGINT", onSig);
+    process.on("SIGTERM", onSig);
+  });
+  console.error("\nStopping\u2026");
+  await handle.stop();
+}
+async function packageReset(client, args) {
+  const projectDir = path7.resolve(args.projectDir ?? process.cwd());
+  const devWorkspaceId = client.getWorkspaceId();
+  if (!devWorkspaceId) {
+    throw new Error(
+      "No dev workspace selected. Pass --workspace <dev_ws> (a workspace created with --dev)."
+    );
+  }
+  const { manifest } = readPackageProject(projectDir);
+  const pin = manifest.dev[devWorkspaceId];
+  if (!pin) {
+    throw new Error(
+      `No dev installation recorded for workspace ${devWorkspaceId}. Run "lotics package dev --workspace ${devWorkspaceId}" first.`
+    );
+  }
+  console.error(`Resetting dev installation ${pin.app_id} in workspace ${devWorkspaceId}...`);
+  const app = await client.resetAppPackage(pin.app_id);
+  console.error(`Reset ${app.name} \u2192 ${app.id}. The scaffolded tables were dropped and re-created clean.`);
+}
+function resolveInstallationAppId(client, explicit) {
+  if (explicit) return explicit;
+  const workspaceId = client.getWorkspaceId();
+  if (!workspaceId) {
+    throw new Error("Pass an app id (lotics package doctor <app_id>) or select a workspace.");
+  }
+  let manifest;
+  try {
+    ({ manifest } = readPackageProject(path7.resolve(process.cwd())));
+  } catch {
+    throw new Error(
+      "No app id given and the current directory is not a package project. Pass one explicitly: lotics package doctor <app_id>."
+    );
+  }
+  const pin = manifest.dev[workspaceId];
+  if (!pin) {
+    throw new Error(
+      `No app id given and no dev installation recorded for workspace ${workspaceId}. Pass one explicitly: lotics package doctor <app_id>.`
+    );
+  }
+  return pin.app_id;
+}
+function parseResolveFlags(resolve2) {
+  const resolutions = {};
+  for (const entry of resolve2) {
+    const eq = entry.indexOf("=");
+    if (eq <= 0 || eq === entry.length - 1) {
+      throw new Error(
+        `Invalid --resolve "${entry}" \u2014 expected <key>=recreate|revert|keep or <key>=<existing_id>.`
+      );
+    }
+    const key = entry.slice(0, eq);
+    const value = entry.slice(eq + 1);
+    resolutions[key] = value === "recreate" || value === "revert" || value === "keep" ? value : { bind_to: value };
+  }
+  return resolutions;
+}
+async function packageDoctor(client, args) {
+  const app_id = resolveInstallationAppId(client, args.app_id);
+  const health = await client.getAppPackageHealth(app_id);
+  console.error(`${health.package_name} \u2014 installation ${health.app_id}`);
+  console.error(
+    `  Installed: v${health.installed_version}   Latest: v${health.latest_version}` + (health.update_available ? "   \u2192 update available" : "")
+  );
+  if (health.drift.length === 0) {
+    console.error("  Binding: healthy \u2014 every bound alias resolves.");
+  } else {
+    console.error(`  Binding drift (${health.drift.length}):`);
+    for (const d of health.drift) {
+      console.error(`    - ${d.namespace}.${d.alias} \u2192 ${d.id} (missing from the workspace)`);
+    }
+    console.error(
+      `  Resolve while upgrading:
+    lotics package upgrade ${app_id} --resolve <namespace.alias>=recreate   (or =<existing_id> to re-point)`
+    );
+    process.exitCode = 1;
+  }
+  if (health.modified.length === 0) {
+    console.error("  Package artifacts: pristine \u2014 no local edits an upgrade would revert.");
+  } else {
+    console.error(`  Locally modified package artifacts (${health.modified.length}):`);
+    for (const m of health.modified) {
+      console.error(`    - ${m.kind}.${m.alias} (an upgrade overwrites this unless kept)`);
+    }
+    console.error(
+      `  Consent while upgrading:
+    lotics package upgrade ${app_id} --resolve <kind.alias>=revert   (or =keep to retain the edit)`
+    );
+    process.exitCode = 1;
+  }
+  if (health.update_available) {
+    console.error(`  Upgrade: lotics package upgrade ${app_id}`);
+  }
+}
+async function packageUpgrade(client, args) {
+  const preview = await client.previewAppPackageUpgrade(args.app_id, {
+    ...args.version !== void 0 ? { version: args.version } : {}
+  });
+  console.error(
+    `Upgrade v${preview.from_version} \u2192 v${preview.to_version}` + (preview.changelog ? ` \u2014 ${preview.changelog}` : "")
+  );
+  const summarize = (sets) => Object.entries(sets).filter(([, entries]) => entries.length > 0).map(([kind, entries]) => `${entries.length} ${kind}`).join(", ");
+  const added = summarize(preview.diff.added);
+  const removed = summarize(preview.diff.removed);
+  if (added) console.error(`  Adds: ${added}`);
+  if (removed) console.error(`  Unbinds (workspace data kept): ${removed}`);
+  if (preview.diff.breaking.length > 0) {
+    console.error(
+      "  Breaking contract changes \u2014 NOT resolvable via --resolve (a bound alias's shape changed):"
+    );
+    for (const b of preview.diff.breaking) {
+      console.error(`    - ${b.entity}.${b.alias} (${b.kind}): ${b.from} \u2192 ${b.to}`);
+    }
+    console.error(
+      `  There is no in-flow resolution for this class. The package author must publish a version
+  that keeps these aliases' shape stable, or eject this app (severing the package link)
+  before making the change:  lotics package eject ${args.app_id}`
+    );
+    process.exit(1);
+  }
+  const unresolvedDrift = preview.drift.filter(
+    (d) => args.resolutions[`${d.namespace}.${d.alias}`] === void 0
+  );
+  const unresolvedModified = preview.modified.filter(
+    (m) => args.resolutions[`${m.kind}.${m.alias}`] === void 0
+  );
+  if (unresolvedDrift.length > 0 || unresolvedModified.length > 0) {
+    if (unresolvedDrift.length > 0) {
+      console.error("  Binding drift must be resolved before upgrading:");
+      for (const d of unresolvedDrift) {
+        console.error(
+          `    --resolve ${d.namespace}.${d.alias}=recreate   (or =<existing_id> to re-point; was ${d.id})`
+        );
+      }
+    }
+    if (unresolvedModified.length > 0) {
+      console.error("  Locally modified package artifacts need consent before upgrading:");
+      for (const m of unresolvedModified) {
+        console.error(
+          `    --resolve ${m.kind}.${m.alias}=revert   (overwrite the local edit; or =keep to retain it)`
+        );
+      }
+    }
+    process.exit(1);
+  }
+  const app = await client.upgradeAppPackage(args.app_id, {
+    ...args.version !== void 0 ? { version: args.version } : {},
+    ...Object.keys(args.resolutions).length > 0 ? { resolutions: args.resolutions } : {}
+  });
+  console.error(`Upgraded ${app.name} \u2192 v${app.package_version} (${app.id}).`);
+}
+async function packageInstall(client, args) {
+  const pkg2 = await client.getAppPackage(args.package_id);
+  console.error(
+    pkg2.is_official ? `Installing ${pkg2.name} \u2014 official Lotics package...` : `Installing ${pkg2.name} \u2014 third-party package (runs under your authority once installed)...`
+  );
+  const app = await client.installAppPackage(args.package_id, {
+    ...args.version !== void 0 ? { version: args.version } : {}
+  });
+  const versionLabel = app.package_version !== null ? `v${app.package_version}` : "(unknown version)";
+  console.error(
+    `Installed ${app.name} ${versionLabel} \u2192 ${app.id} (workspace ${app.workspace_id}).`
+  );
+  console.error("  The data model, queries, workflows, and agents are live.");
+  console.error("  Pull it for local editing:  lotics app pull " + app.id);
+}
+async function packageEject(client, args) {
+  const app = await client.ejectAppPackage(args.app_id);
+  console.error(`Ejected ${app.name} \u2192 ${app.id} (workspace ${app.workspace_id}).`);
+  console.error("  The package link is severed \u2014 it's now a normal bespoke app and can no longer be upgraded.");
+  console.error("  Its data model, queries, workflows, and templates are unchanged.");
+  console.error("  Pull the pinned source for local editing:  lotics app pull " + app.id);
+}
+async function packageExtract(client, args) {
+  const app = await client.getApp(args.app_id);
+  if (!app.current_version_id) {
+    throw new Error(
+      `App ${app.id} has no deployed version \u2014 extract stages its source archive, so deploy it first.`
+    );
+  }
+  const extracted = await client.extractAppPackage(args.app_id);
+  const { lines, hasError } = formatExtractReport(extracted.report);
+  if (lines.length > 0) {
+    console.error(`Extraction report (${extracted.report.length}):`);
+    for (const line of lines) console.error(line);
+  } else {
+    console.error("Extraction report: no findings.");
+  }
+  const targetPath = path7.resolve(args.targetPath ?? appDirName(app.name));
+  if (fs6.existsSync(targetPath) && fs6.readdirSync(targetPath).length > 0) {
+    throw new Error(`Target directory ${targetPath} is not empty.`);
+  }
+  fs6.mkdirSync(targetPath, { recursive: true });
+  const version = await client.getAppVersion(app.id, app.current_version_id);
+  const sourceUrl = await client.getAppVersionSourceUrl(app.id, version.id);
+  const tmpFile = path7.join(tmpdir2(), `lotics-extract-${app.id}-${Date.now()}.tar.gz`);
+  console.error("Downloading source archive...");
+  await client.downloadFile(sourceUrl, tmpFile);
+  try {
+    console.error(`Extracting to ${targetPath}...`);
+    await runTar(["-xzf", tmpFile, "-C", targetPath], targetPath);
+  } finally {
+    if (fs6.existsSync(tmpFile)) fs6.unlinkSync(tmpFile);
+  }
+  const appPkgJson = JSON.parse(
+    fs6.readFileSync(packageJsonPath(targetPath), "utf-8")
+  );
+  writePackageManifest(
+    targetPath,
+    draftPackageProjectFromApp(appPkgJson, { name: app.name, description: null })
+  );
+  fs6.writeFileSync(
+    path7.join(targetPath, CONTRACT_FILE),
+    JSON.stringify(extracted.contract, null, 2) + "\n"
+  );
+  console.error(`Wrote ${CONTRACT_FILE}`);
+  for (const tf of extracted.template_files) {
+    const dest = path7.join(targetPath, tf.bytes_ref);
+    fs6.mkdirSync(path7.dirname(dest), { recursive: true });
+    const { path: downloaded } = await client.downloadFileById(tf.file_id, path7.dirname(dest));
+    if (path7.resolve(downloaded) !== path7.resolve(dest)) fs6.renameSync(downloaded, dest);
+    console.error(`Wrote ${tf.bytes_ref}`);
+  }
+  const dotLotics = path7.join(targetPath, ".lotics");
+  fs6.mkdirSync(dotLotics, { recursive: true });
+  fs6.writeFileSync(
+    path7.join(dotLotics, ADOPT_BINDING_FILE),
+    JSON.stringify(
+      { app_id: app.id, workspace_id: app.workspace_id, binding: extracted.binding },
+      null,
+      2
+    ) + "\n"
+  );
+  console.error(`Wrote .lotics/${ADOPT_BINDING_FILE}`);
+  console.error("Installing npm dependencies...");
+  await runNpm(["install"], targetPath);
+  if (hasError) {
+    console.error(
+      "\nExtraction produced error findings \u2014 the draft is written but NOT publishable as-is."
+    );
+    console.error(
+      "Fix the reported items above, then publish (which re-validates the contract)."
+    );
+    process.exitCode = 1;
+    return;
+  }
+  console.error("\nDraft package project written. Next steps:");
+  console.error(`  cd ${path7.relative(process.cwd(), targetPath) || "."}`);
+  console.error("  # review the aliases in contract.json, then:");
+  console.error(`  lotics package publish -m "v1"`);
+  console.error(`  lotics package adopt ${app.id}   (from this project, same workspace)`);
+}
+async function packageAdopt(client, args) {
+  const projectDir = path7.resolve(args.projectDir ?? process.cwd());
+  const { manifest } = readPackageProject(projectDir);
+  if (manifest.id === null) {
+    throw new Error(
+      "This package project has never been published (no package id). Publish first:\n  lotics package publish"
+    );
+  }
+  const version = args.version ?? manifest.version;
+  if (version === null) {
+    throw new Error(
+      "No version to adopt \u2014 publish this project first (lotics package publish) or pass --version N."
+    );
+  }
+  const bindingPath = path7.join(projectDir, ".lotics", ADOPT_BINDING_FILE);
+  if (!fs6.existsSync(bindingPath)) {
+    throw new Error(
+      `No .lotics/${ADOPT_BINDING_FILE} in ${projectDir}. Adopt binds the origin app that "lotics package extract" recorded \u2014 run extract to produce this project.`
+    );
+  }
+  const pin = parseAdoptBindingFile(
+    JSON.parse(fs6.readFileSync(bindingPath, "utf-8")),
+    args.app_id
+  );
+  const app = await client.adoptAppPackage(args.app_id, {
+    package_id: manifest.id,
+    version,
+    binding: pin.binding
+  });
+  console.error(
+    `Adopted ${app.name} \u2192 installation of ${app.package_id} v${app.package_version}.`
+  );
+  console.error(`  Verify the installation:  lotics package doctor ${app.id}`);
+}
+async function packageFleetUpgrade(client, args) {
+  const result = await client.fleetUpgradeAppPackage(args.package_id, {
+    ...args.version !== void 0 ? { version: args.version } : {}
+  });
+  console.error(`Fleet upgrade of ${result.package_id} \u2192 v${result.target_version}:`);
+  if (result.installations.length === 0) {
+    console.error("  No installations of this package in your organization.");
+    return;
+  }
+  const counts = { upgraded: 0, up_to_date: 0, skipped: 0, failed: 0 };
+  for (const inst of result.installations) {
+    counts[inst.outcome]++;
+    const from = inst.from_version === null ? "?" : `v${inst.from_version}`;
+    const line = `  [${inst.outcome}] ${inst.workspace_name} \u2014 ${inst.app_name} (${from} \u2192 v${result.target_version})`;
+    if (inst.outcome === "skipped" && inst.blockers) {
+      console.error(
+        `${line}: breaking=${inst.blockers.breaking} drift=${inst.blockers.drift} modified=${inst.blockers.modified}`
+      );
+      console.error(
+        `      resolve via:  lotics package upgrade ${inst.app_id} --version ${result.target_version} ...`
+      );
+    } else if (inst.message) {
+      console.error(`${line}: ${inst.message}`);
+    } else {
+      console.error(line);
+    }
+  }
+  console.error(
+    `Done: ${counts.upgraded} upgraded, ${counts.up_to_date} already current, ${counts.skipped} skipped, ${counts.failed} failed.`
+  );
+  if (counts.skipped > 0 || counts.failed > 0) {
+    process.exitCode = 1;
+  }
+}
+
 // src/args.ts
 function parseArgs(argv) {
   const flags = {
@@ -33178,9 +34080,12 @@ function parseArgs(argv) {
     message: void 0,
     local: false,
     all: false,
+    dev: false,
     yes: false,
     printCreated: false,
     cleanup: false,
+    packageVersion: void 0,
+    resolve: [],
     version: false,
     help: false
   };
@@ -33231,6 +34136,9 @@ function parseArgs(argv) {
       case "--local":
         flags.local = true;
         break;
+      case "--dev":
+        flags.dev = true;
+        break;
       case "--all":
         flags.all = true;
         break;
@@ -33245,10 +34153,32 @@ function parseArgs(argv) {
       case "--cleanup":
         flags.cleanup = true;
         break;
+      case "--resolve": {
+        const value = argv[++i2];
+        if (value === void 0 || value.startsWith("-")) {
+          throw new Error(
+            "--resolve requires a value: <key>=recreate|revert|keep or <key>=<existing_id> (drift: <namespace.alias>; modified core: <kind>.<alias>)."
+          );
+        }
+        flags.resolve.push(value);
+        break;
+      }
       case "--version":
-      case "-v":
-        flags.version = true;
+      case "-v": {
+        const next = argv[i2 + 1];
+        if (command === "package") {
+          if (next === void 0 || next.startsWith("-")) {
+            throw new Error(
+              "--version requires a version number for package commands (e.g. --version 2)."
+            );
+          }
+          flags.packageVersion = next;
+          i2++;
+        } else {
+          flags.version = true;
+        }
         break;
+      }
       case "--help":
       case "-h":
         flags.help = true;
@@ -33299,35 +34229,7 @@ async function ingestJsonArgs(opts) {
 }
 
 // src/xlsx.ts
-import fs6 from "node:fs";
-
-// src/file_command_io.ts
-import fs5 from "node:fs";
-import path6 from "node:path";
-var CliError = class extends Error {
-  constructor(message) {
-    super(message);
-    this.name = "CliError";
-  }
-};
-function fail(message) {
-  throw new CliError(message);
-}
-function writeFileAtomic(filePath, bytes) {
-  const dir = path6.dirname(path6.resolve(filePath));
-  const tmp = path6.join(dir, `.${path6.basename(filePath)}.${process.pid}.${Date.now()}.tmp`);
-  fs5.writeFileSync(tmp, bytes);
-  try {
-    fs5.renameSync(tmp, filePath);
-  } catch (error) {
-    try {
-      fs5.unlinkSync(tmp);
-    } catch {
-    }
-    throw error;
-  }
-  console.error(`Wrote ${filePath}`);
-}
+import fs7 from "node:fs";
 
 // ../xlsx/node_modules/fast-xml-parser/src/util.js
 var nameStartChar = ":A-Za-z_\\u00C0-\\u00D6\\u00D8-\\u00F6\\u00F8-\\u02FF\\u0370-\\u037D\\u037F-\\u1FFF\\u200C-\\u200D\\u2070-\\u218F\\u2C00-\\u2FEF\\u3001-\\uD7FF\\uF900-\\uFDCF\\uFDF0-\\uFFFD";
@@ -36104,16 +37006,16 @@ var MatcherView = class {
    * @returns {string|undefined}
    */
   getCurrentTag() {
-    const path8 = this._matcher.path;
-    return path8.length > 0 ? path8[path8.length - 1].tag : void 0;
+    const path9 = this._matcher.path;
+    return path9.length > 0 ? path9[path9.length - 1].tag : void 0;
   }
   /**
    * Get current namespace.
    * @returns {string|undefined}
    */
   getCurrentNamespace() {
-    const path8 = this._matcher.path;
-    return path8.length > 0 ? path8[path8.length - 1].namespace : void 0;
+    const path9 = this._matcher.path;
+    return path9.length > 0 ? path9[path9.length - 1].namespace : void 0;
   }
   /**
    * Get current node's attribute value.
@@ -36121,9 +37023,9 @@ var MatcherView = class {
    * @returns {*}
    */
   getAttrValue(attrName) {
-    const path8 = this._matcher.path;
-    if (path8.length === 0) return void 0;
-    return path8[path8.length - 1].values?.[attrName];
+    const path9 = this._matcher.path;
+    if (path9.length === 0) return void 0;
+    return path9[path9.length - 1].values?.[attrName];
   }
   /**
    * Check if current node has an attribute.
@@ -36131,9 +37033,9 @@ var MatcherView = class {
    * @returns {boolean}
    */
   hasAttr(attrName) {
-    const path8 = this._matcher.path;
-    if (path8.length === 0) return false;
-    const current = path8[path8.length - 1];
+    const path9 = this._matcher.path;
+    if (path9.length === 0) return false;
+    const current = path9[path9.length - 1];
     return current.values !== void 0 && attrName in current.values;
   }
   /**
@@ -36141,18 +37043,18 @@ var MatcherView = class {
    * @returns {number}
    */
   getPosition() {
-    const path8 = this._matcher.path;
-    if (path8.length === 0) return -1;
-    return path8[path8.length - 1].position ?? 0;
+    const path9 = this._matcher.path;
+    if (path9.length === 0) return -1;
+    return path9[path9.length - 1].position ?? 0;
   }
   /**
    * Get current node's repeat counter (occurrence count of this tag name).
    * @returns {number}
    */
   getCounter() {
-    const path8 = this._matcher.path;
-    if (path8.length === 0) return -1;
-    return path8[path8.length - 1].counter ?? 0;
+    const path9 = this._matcher.path;
+    if (path9.length === 0) return -1;
+    return path9[path9.length - 1].counter ?? 0;
   }
   /**
    * Get current node's sibling index (alias for getPosition).
@@ -41608,10 +42510,10 @@ function resolveRelativePath(basePath, relativePath) {
   }
   return resolved.join("/");
 }
-function findZipEntry(zipEntries, path8) {
-  if (zipEntries[path8]) return zipEntries[path8];
-  if (zipEntries[`xl/${path8}`]) return zipEntries[`xl/${path8}`];
-  const noSlash = path8.replace(/^\//, "");
+function findZipEntry(zipEntries, path9) {
+  if (zipEntries[path9]) return zipEntries[path9];
+  if (zipEntries[`xl/${path9}`]) return zipEntries[`xl/${path9}`];
+  const noSlash = path9.replace(/^\//, "");
   if (zipEntries[noSlash]) return zipEntries[noSlash];
   return void 0;
 }
@@ -43334,9 +44236,9 @@ function parseExcelFromZip(zip, options) {
   }
   return result;
 }
-function findEntry(zip, path8) {
-  if (zip[path8]) return zip[path8];
-  const lower = path8.toLowerCase();
+function findEntry(zip, path9) {
+  if (zip[path9]) return zip[path9];
+  const lower = path9.toLowerCase();
   for (const key of Object.keys(zip)) {
     if (key.toLowerCase() === lower) return zip[key];
   }
@@ -43947,12 +44849,12 @@ function extractPivotRoundTripInfo(originalZip) {
     if (paths.length > 0) pivotTablesBySheetIndex.set(i2, paths);
   }
   const pivotXmlPaths = [];
-  for (const path8 of Object.keys(originalZip)) {
-    if (path8.startsWith("xl/pivotTables/") && path8.endsWith(".xml")) {
-      pivotXmlPaths.push(path8);
+  for (const path9 of Object.keys(originalZip)) {
+    if (path9.startsWith("xl/pivotTables/") && path9.endsWith(".xml")) {
+      pivotXmlPaths.push(path9);
     }
-    if (path8.startsWith("xl/pivotCache/") && path8.endsWith(".xml")) {
-      pivotXmlPaths.push(path8);
+    if (path9.startsWith("xl/pivotCache/") && path9.endsWith(".xml")) {
+      pivotXmlPaths.push(path9);
     }
   }
   return { cachesByWorkbook, pivotTablesBySheetIndex, pivotXmlPaths };
@@ -43960,15 +44862,15 @@ function extractPivotRoundTripInfo(originalZip) {
 function decode(bytes) {
   return new TextDecoder().decode(bytes);
 }
-function pivotContentTypeFor(path8) {
-  if (path8.startsWith("xl/pivotTables/") && path8.endsWith(".xml")) {
-    return `<Override PartName="/${path8}" ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.pivotTable+xml"/>`;
+function pivotContentTypeFor(path9) {
+  if (path9.startsWith("xl/pivotTables/") && path9.endsWith(".xml")) {
+    return `<Override PartName="/${path9}" ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.pivotTable+xml"/>`;
   }
-  if (path8.includes("/pivotCacheDefinition") && path8.endsWith(".xml")) {
-    return `<Override PartName="/${path8}" ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.pivotCacheDefinition+xml"/>`;
+  if (path9.includes("/pivotCacheDefinition") && path9.endsWith(".xml")) {
+    return `<Override PartName="/${path9}" ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.pivotCacheDefinition+xml"/>`;
   }
-  if (path8.includes("/pivotCacheRecords") && path8.endsWith(".xml")) {
-    return `<Override PartName="/${path8}" ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.pivotCacheRecords+xml"/>`;
+  if (path9.includes("/pivotCacheRecords") && path9.endsWith(".xml")) {
+    return `<Override PartName="/${path9}" ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.pivotCacheRecords+xml"/>`;
   }
   return void 0;
 }
@@ -44040,13 +44942,13 @@ function exportWorkbook(workbook, originalZip) {
       regeneratedPaths.add(`xl/worksheets/sheet${i2 + 1}.xml`);
       regeneratedPaths.add(`xl/worksheets/_rels/sheet${i2 + 1}.xml.rels`);
     }
-    for (const path8 of Object.keys(originalZip)) {
-      if (path8.startsWith("xl/drawings/") || path8.startsWith("xl/charts/") || path8.startsWith("xl/tables/") || path8.startsWith("xl/media/")) {
-        regeneratedPaths.add(path8);
+    for (const path9 of Object.keys(originalZip)) {
+      if (path9.startsWith("xl/drawings/") || path9.startsWith("xl/charts/") || path9.startsWith("xl/tables/") || path9.startsWith("xl/media/")) {
+        regeneratedPaths.add(path9);
       }
     }
-    for (const [path8, data] of Object.entries(originalZip)) {
-      if (!regeneratedPaths.has(path8)) entries[path8] = data;
+    for (const [path9, data] of Object.entries(originalZip)) {
+      if (!regeneratedPaths.has(path9)) entries[path9] = data;
     }
   }
   const sharedStrings = buildSharedStrings(workbook);
@@ -44061,8 +44963,8 @@ function exportWorkbook(workbook, originalZip) {
     buildWorkbookRels(workbook, pivotInfo)
   );
   const extraContentTypes = [];
-  for (const path8 of pivotInfo.pivotXmlPaths) {
-    const ct = pivotContentTypeFor(path8);
+  for (const path9 of pivotInfo.pivotXmlPaths) {
+    const ct = pivotContentTypeFor(path9);
     if (ct) extraContentTypes.push(ct);
   }
   let globalChartIndex = 1;
@@ -45823,14 +46725,14 @@ var DependencyGraph = class {
       stack.push({ cell: p, path: [cell, p] });
     }
     while (stack.length > 0) {
-      const { cell: current, path: path8 } = stack.pop();
-      if (current === cell) return path8;
+      const { cell: current, path: path9 } = stack.pop();
+      if (current === cell) return path9;
       if (visited.has(current)) continue;
       visited.add(current);
       const nextPrec = this.precedents.get(current);
       if (!nextPrec) continue;
       for (const p of nextPrec) {
-        stack.push({ cell: p, path: [...path8, p] });
+        stack.push({ cell: p, path: [...path9, p] });
       }
     }
     return null;
@@ -46821,8 +47723,8 @@ function adjustMergedCellsForColDelete(sheet, atCol, count) {
 
 // src/xlsx.ts
 function loadFile(filePath) {
-  if (!fs6.existsSync(filePath)) fail(`File not found: ${filePath}`);
-  const buffer = fs6.readFileSync(filePath);
+  if (!fs7.existsSync(filePath)) fail(`File not found: ${filePath}`);
+  const buffer = fs7.readFileSync(filePath);
   const arrayBuffer = buffer.buffer.slice(buffer.byteOffset, buffer.byteOffset + buffer.byteLength);
   const originalZip = unzipXlsx(arrayBuffer);
   const parsed = parseExcelBuffer(arrayBuffer);
@@ -46872,7 +47774,7 @@ function lazyEngine(workbook) {
   };
 }
 function readToJson(filePath) {
-  const buffer = fs6.readFileSync(filePath);
+  const buffer = fs7.readFileSync(filePath);
   const arrayBuffer = buffer.buffer.slice(buffer.byteOffset, buffer.byteOffset + buffer.byteLength);
   const parsed = parseExcelBuffer(arrayBuffer);
   return {
@@ -47262,7 +48164,7 @@ async function runXlsxCommand(subcommand, toolArgs, restArgs) {
 }
 
 // src/docx.ts
-import fs7 from "node:fs";
+import fs8 from "node:fs";
 
 // ../docx/src/parse/parser.ts
 var import_jszip = __toESM(require_lib3(), 1);
@@ -49033,11 +49935,11 @@ async function parseDocx(buffer) {
   const zip = await import_jszip.default.loadAsync(buffer);
   const parts = /* @__PURE__ */ new Map();
   const filePromises = [];
-  zip.forEach((path8, file) => {
+  zip.forEach((path9, file) => {
     if (file.dir) return;
     filePromises.push(
       file.async("uint8array").then((bytes) => {
-        parts.set(path8, bytes);
+        parts.set(path9, bytes);
       })
     );
   });
@@ -49266,9 +50168,9 @@ var DEFAULT_PARTS = [
   ["word/theme/theme1.xml", () => encoder.encode(THEME_XML)]
 ];
 function fillDefaultParts(parts) {
-  for (const [path8, makeBytes] of DEFAULT_PARTS) {
-    if (!parts.has(path8)) {
-      parts.set(path8, makeBytes());
+  for (const [path9, makeBytes] of DEFAULT_PARTS) {
+    if (!parts.has(path9)) {
+      parts.set(path9, makeBytes());
     }
   }
   return parts;
@@ -49278,9 +50180,9 @@ function fillDefaultParts(parts) {
 async function serializeDocx(doc) {
   const zip = new import_jszip2.default();
   const parts = fillDefaultParts(new Map(doc.parts));
-  for (const [path8, bytes] of parts) {
-    if (path8 === "word/document.xml") continue;
-    zip.file(path8, bytes);
+  for (const [path9, bytes] of parts) {
+    if (path9 === "word/document.xml") continue;
+    zip.file(path9, bytes);
   }
   const documentXml = serializeDocumentXml(doc);
   zip.file("word/document.xml", documentXml);
@@ -49366,8 +50268,8 @@ var DEFAULT_DOC_ATTRS = {
   "@_xmlns:w": "http://schemas.openxmlformats.org/wordprocessingml/2006/main"
 };
 async function loadFile2(filePath) {
-  if (!fs7.existsSync(filePath)) fail(`File not found: ${filePath}`);
-  const bytes = fs7.readFileSync(filePath);
+  if (!fs8.existsSync(filePath)) fail(`File not found: ${filePath}`);
+  const bytes = fs8.readFileSync(filePath);
   return parseDocx(new Uint8Array(bytes));
 }
 async function writeDoc(filePath, doc) {
@@ -49655,6 +50557,198 @@ async function runDocxCommand(subcommand, toolArgs, restArgs) {
   }
 }
 
+// src/preview.ts
+import { spawn as spawn3 } from "node:child_process";
+import { createServer } from "node:http";
+import { readFileSync as readFileSync2, writeFileSync, existsSync, mkdtempSync, rmSync, readdirSync } from "node:fs";
+import { tmpdir as tmpdir3 } from "node:os";
+import { join, dirname, resolve, extname, basename } from "node:path";
+import { fileURLToPath as fileURLToPath2 } from "node:url";
+import { setTimeout as sleep } from "node:timers/promises";
+var HERE = dirname(fileURLToPath2(import.meta.url));
+function fail2(msg) {
+  console.error(msg);
+  process.exit(1);
+}
+function findChrome() {
+  const env = process.env.LOTICS_CHROME || process.env.CHROME_PATH;
+  if (env && existsSync(env)) return env;
+  const home = process.env.HOME || "";
+  const pwDir = process.platform === "darwin" ? `${home}/Library/Caches/ms-playwright` : `${home}/.cache/ms-playwright`;
+  if (existsSync(pwDir)) {
+    const rel = process.platform === "darwin" ? ["chrome-mac/Chromium.app/Contents/MacOS/Chromium"] : ["chrome-linux/chrome", "chrome-linux/headless_shell"];
+    const revs = readdirSync(pwDir).filter((n) => n.startsWith("chromium-") || n.startsWith("chromium_headless_shell-")).sort().reverse();
+    for (const rev2 of revs) {
+      for (const r of rel) {
+        const bin = join(pwDir, rev2, r);
+        if (existsSync(bin)) return bin;
+      }
+    }
+  }
+  const systemPaths = [
+    "/usr/bin/google-chrome",
+    "/usr/bin/google-chrome-stable",
+    "/usr/bin/chromium",
+    "/usr/bin/chromium-browser",
+    "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+    "/Applications/Chromium.app/Contents/MacOS/Chromium"
+  ];
+  return systemPaths.find((p) => existsSync(p)) ?? null;
+}
+async function cdpConnect(wsUrl) {
+  const ws = new WebSocket(wsUrl);
+  await new Promise((res, rej) => {
+    ws.onopen = () => res();
+    ws.onerror = () => rej(new Error("CDP websocket failed to open"));
+  });
+  let id = 0;
+  const pending = /* @__PURE__ */ new Map();
+  ws.onclose = () => {
+    for (const done of pending.values()) done(Promise.reject(new Error("CDP connection closed (Chrome exited?)")));
+    pending.clear();
+  };
+  ws.onmessage = (e) => {
+    const m = JSON.parse(String(e.data));
+    if (m.id != null && pending.has(m.id)) {
+      const done = pending.get(m.id);
+      pending.delete(m.id);
+      done(m.error ? Promise.reject(new Error(m.error.message)) : m.result);
+    }
+  };
+  const send = (method, params = {}) => new Promise((res) => {
+    const i2 = ++id;
+    pending.set(i2, (r) => res(r));
+    ws.send(JSON.stringify({ id: i2, method, params }));
+  });
+  return { send, close: () => ws.close() };
+}
+async function runPreviewCommand(filePath, flags) {
+  if (!filePath) fail2("Usage: lotics preview <file.docx|.xlsx> [--out <file.png>]");
+  const abs = resolve(filePath);
+  if (!existsSync(abs)) fail2(`File not found: ${abs}`);
+  const ext = extname(abs).toLowerCase();
+  const type = ext === ".docx" ? "docx" : ext === ".xlsx" || ext === ".xls" || ext === ".csv" ? "xlsx" : null;
+  if (!type) fail2(`Unsupported file type "${ext}" \u2014 preview supports .docx and .xlsx/.csv. (PDFs open directly \u2014 no preview needed.)`);
+  if (typeof WebSocket === "undefined") {
+    fail2("lotics preview needs Node 22+ (it drives Chrome over CDP via the built-in WebSocket). Upgrade Node and retry.");
+  }
+  const bundlePath = join(HERE, "..", "render_page.js");
+  if (!existsSync(bundlePath)) fail2(`Render bundle missing at ${bundlePath} \u2014 reinstall @lotics/cli (build step failed).`);
+  const chrome = findChrome();
+  if (!chrome) {
+    fail2(
+      "No Chrome/Chromium found. Set CHROME_PATH to a Chrome binary, or install one:\n  npx playwright install chromium   (then it's auto-detected)\n  or install Google Chrome / Chromium via your package manager."
+    );
+  }
+  const b64 = readFileSync2(abs).toString("base64");
+  const bundle = readFileSync2(bundlePath, "utf8");
+  const html = `<!doctype html><html><head><meta charset="utf-8"><style>body{margin:0;background:#fff;font-family:sans-serif}#root{padding:20px;max-width:1240px;margin:0 auto}</style></head><body><div id="root"></div><script>window.__LOTICS_RENDER=${JSON.stringify({ type, b64 })}</script><script src="/render_page.js"></script></body></html>`;
+  const server = createServer((req, res) => {
+    if (req.url === "/render_page.js") {
+      res.writeHead(200, { "content-type": "application/javascript" });
+      res.end(bundle);
+    } else {
+      res.writeHead(200, { "content-type": "text/html" });
+      res.end(html);
+    }
+  });
+  await new Promise((r) => server.listen(0, "127.0.0.1", () => r()));
+  const httpPort = server.address().port;
+  const udd = mkdtempSync(join(tmpdir3(), "lotics-render-"));
+  const child = spawn3(chrome, [
+    "--headless=new",
+    "--disable-gpu",
+    "--no-sandbox",
+    "--hide-scrollbars",
+    // Large multi-sheet renders exhaust the (often tiny) /dev/shm in containers/WSL2 and
+    // crash the tab; back shared memory with /tmp instead.
+    "--disable-dev-shm-usage",
+    "--force-device-scale-factor=2",
+    "--remote-debugging-port=0",
+    `--user-data-dir=${udd}`,
+    "about:blank"
+  ], { stdio: "ignore" });
+  const cleanup = () => {
+    try {
+      child.kill();
+    } catch {
+    }
+    try {
+      server.close();
+    } catch {
+    }
+    try {
+      rmSync(udd, { recursive: true, force: true });
+    } catch {
+    }
+  };
+  try {
+    let cdpPort = 0;
+    const portFile = join(udd, "DevToolsActivePort");
+    for (let i2 = 0; i2 < 100 && !cdpPort; i2++) {
+      if (existsSync(portFile)) {
+        const p = parseInt(readFileSync2(portFile, "utf8").split("\n")[0], 10);
+        if (p) cdpPort = p;
+      }
+      if (!cdpPort) await sleep(100);
+    }
+    if (!cdpPort) throw new Error("Chrome did not expose a debugging port (launch failed?).");
+    let target;
+    for (let i2 = 0; i2 < 60 && !target?.webSocketDebuggerUrl; i2++) {
+      try {
+        const list = await (await fetch(`http://127.0.0.1:${cdpPort}/json/list`)).json();
+        target = list.find((t) => t.type === "page");
+      } catch {
+      }
+      if (!target?.webSocketDebuggerUrl) await sleep(100);
+    }
+    if (!target?.webSocketDebuggerUrl) throw new Error("No Chrome page target available.");
+    const cdp = await cdpConnect(target.webSocketDebuggerUrl);
+    await cdp.send("Page.enable");
+    await cdp.send("Runtime.enable");
+    await cdp.send("Page.navigate", { url: `http://127.0.0.1:${httpPort}/` });
+    let err2;
+    let done = false;
+    const warnings = [];
+    for (let i2 = 0; i2 < 200; i2++) {
+      const r = await cdp.send("Runtime.evaluate", {
+        expression: "({done: !!window.__loticsDone, err: window.__loticsError || '', warnings: window.__loticsWarnings || []})",
+        returnByValue: true
+      });
+      const v = r.result?.value;
+      if (v?.done) {
+        done = true;
+        err2 = v.err || void 0;
+        if (v.warnings?.length) warnings.push(...v.warnings);
+        break;
+      }
+      await sleep(75);
+    }
+    if (!done) throw new Error("Render timed out (page never signaled completion).");
+    if (err2) throw new Error(`Render engine error: ${err2}`);
+    const metrics = await cdp.send("Page.getLayoutMetrics");
+    const size = metrics.cssContentSize ?? metrics.contentSize ?? { width: 1240, height: 1600 };
+    const MAX_CAPTURE = 15e3;
+    const w = Math.ceil(size.width);
+    const h = Math.ceil(size.height);
+    if (w > MAX_CAPTURE || h > MAX_CAPTURE) {
+      warnings.push(`content ${w}\xD7${h}px clipped to ${Math.min(w, MAX_CAPTURE)}\xD7${Math.min(h, MAX_CAPTURE)}px (exceeds the ${MAX_CAPTURE}px capture limit)`);
+    }
+    const shot = await cdp.send("Page.captureScreenshot", {
+      format: "png",
+      captureBeyondViewport: true,
+      clip: { x: 0, y: 0, width: Math.min(w, MAX_CAPTURE), height: Math.min(h, MAX_CAPTURE), scale: 1 }
+    });
+    cdp.close();
+    const outPath = flags.output ? resolve(flags.output) : join(dirname(abs), basename(abs, ext) + ".png");
+    writeFileSync(outPath, Buffer.from(shot.data, "base64"));
+    console.log(`Rendered ${basename(abs)} \u2192 ${outPath}  (${Math.min(w, MAX_CAPTURE)}\xD7${Math.min(h, MAX_CAPTURE)}, via ${basename(chrome)})`);
+    for (const warn of warnings) console.error(`  \u26A0 ${warn}`);
+  } finally {
+    cleanup();
+  }
+}
+
 // src/cli.ts
 dns.setDefaultResultOrder("ipv4first");
 net2.setDefaultAutoSelectFamilyAttemptTimeout(2e3);
@@ -49701,15 +50795,12 @@ COMMANDS
   lotics workspace select <id>         Switch to a different workspace
   lotics workspace create <name>       Create a new workspace (admin only)
   lotics workspace delete <id> --yes   Delete a workspace (admin only; soft delete, recoverable)
+  lotics workspace doctor              Report dangling schema references (admin only)
   lotics tools                         List all available tools
   lotics tools <name>                  Show tool description and input schema
   lotics run <tool> '<json>'           Execute a tool
   lotics run <tool> @args.json         Read JSON args from a file (large payloads)
   cat args.json | lotics run <tool>    Read JSON args from stdin (large payloads)
-  lotics upload <file|dir...>          Upload files (directories expand to their immediate files)
-  lotics download <file_id>            Download a file by ID
-  lotics download record <record_id> <field_key>
-                                       Download all files on a record file field
   lotics app create <name> [path]      Create a new custom-code app + scaffold locally
   lotics app pull <app_id> [path]      Bootstrap full local env (source + npm install + types)
   lotics app deploy -m <message>       Build + upload current dir as a new version
@@ -49737,6 +50828,37 @@ COMMANDS
   lotics app subdomain <new-subdomain> Rename the app's public <slug>.lotics.app address
   lotics app rename "<new name>"       Rename the app's display name (launcher title)
   lotics app dev [path]                Run the app locally with HMR (RPC forwarded to prod)
+  lotics package new <name> [path]     Scaffold a package project (contract + app source)
+  lotics package build [path]          Build the publishable bundle (source + dist)
+  lotics package publish [path]        Publish a new immutable package version
+  lotics package dev [path]            Sync the package into a dev workspace + run the app
+                                       dev server (--workspace <dev_ws> selects it)
+  lotics package sync [path]           Re-sync (additive migrate + materialize) into a dev ws
+  lotics package reset [path]          DEV-ONLY: drop scaffolded tables + re-scaffold clean
+  lotics package install <package> [--version N]
+                                       Install an app package into this workspace
+                                       (scaffolds the data model + deploys + materializes)
+  lotics package upgrade <app_id> [--version N] [--resolve <key>=recreate|revert|keep|<id> ...]
+                                       Preview-then-apply a package upgrade; refuses while
+                                       any drift/modified finding lacks a --resolve, and
+                                       hard-stops on breaking contract changes
+  lotics package doctor [app_id]       Installation health: version pin vs latest, binding
+                                       drift, locally modified core (exit 1 on findings)
+  lotics package rebind-role <app_id> <alias> <grp_id>
+                                       Re-point a package role at a different group
+                                       (re-materializes at the pinned version)
+  lotics package eject <app_id>        Sever an installation's package link
+                                       (re-deploys the pinned source as a bespoke app)
+  lotics package extract <app_id> [path]   Promote a bespoke app to a draft package
+                                       project (contract + binding + templates); always
+                                       writes the draft, exits 1 on error findings
+  lotics package adopt <app_id> [path]     Bind the published package project onto the
+                                       origin app (reads .lotics/adopt_binding.json;
+                                       --version N pins a specific version)
+  lotics package fleet-upgrade <package_id> [--version N]
+                                       Upgrade EVERY installation of the package across
+                                       your org: applies where the preview is clean,
+                                       skips + reports findings (exit 1 unless all current)
   lotics ui link <component> [--ui-src <path>] [--remove]
                                        Dev-link @lotics/ui to packages/ui/src (Vite alias
                                        + tsc paths) for live HMR + typecheck. Monorepo apps
@@ -49747,6 +50869,12 @@ COMMANDS
   lotics docx <subcommand> ...         Read/write/edit .docx files on your local filesystem
                                        (uses the bundled Lotics OOXML engine; preserves
                                        tables, images, and unknown markup verbatim)
+  lotics file upload <file|dir...>     Upload files (alias: lotics upload)
+  lotics file download <file_id>       Download a file by ID (alias: lotics download)
+  lotics file download record <record_id> <field_key>
+                                       Download all files on a record file field
+  lotics file preview <file> [-o png]  Render a .docx/.xlsx to a PNG (frontend engines;
+                                       needs a Chrome/Chromium on the machine)
 
 FLAGS
   --json             Full JSON output (default is human-readable text)
@@ -49759,6 +50887,8 @@ FLAGS
                      is_current_member / row-scoping resolve to them (also
                      LOTICS_VIEW_AS env; admin key only; writes stay yours)
   --local            Pin the current directory (lotics org use / auth api-key)
+  --dev              (lotics workspace create) Mark a throwaway app-package dev
+                     workspace \u2014 required for "lotics package reset"
   --all              (lotics auth logout) Remove every saved credential
   --version          Show version
 
@@ -49824,10 +50954,10 @@ Resolution precedence (highest first):
   > global active profile. LOTICS_WORKSPACE / --workspace override the workspace.`);
 }
 function readStdin() {
-  return new Promise((resolve, reject2) => {
+  return new Promise((resolve2, reject2) => {
     const chunks = [];
     process.stdin.on("data", (chunk) => chunks.push(chunk));
-    process.stdin.on("end", () => resolve(Buffer.concat(chunks).toString("utf-8").trim()));
+    process.stdin.on("end", () => resolve2(Buffer.concat(chunks).toString("utf-8").trim()));
     process.stdin.on("error", reject2);
   });
 }
@@ -49836,15 +50966,15 @@ function prompt(question) {
     input: process.stdin,
     output: process.stderr
   });
-  return new Promise((resolve) => {
+  return new Promise((resolve2) => {
     rl.question(question, (answer) => {
       rl.close();
-      resolve(answer.trim());
+      resolve2(answer.trim());
     });
   });
 }
-async function publicPost(path8, body) {
-  const response = await fetch(`${API_BASE_URL}${path8}`, {
+async function publicPost(path9, body) {
+  const response = await fetch(`${API_BASE_URL}${path9}`, {
     method: "POST",
     headers: { "Content-Type": "application/json" },
     body: JSON.stringify(body)
@@ -49990,13 +51120,13 @@ async function resolveWorkspace(client, ctx) {
 function resolveUploadPaths(rawPaths) {
   const result = [];
   for (const p of rawPaths) {
-    const resolved = path7.resolve(p);
-    const stat = fs8.statSync(resolved);
+    const resolved = path8.resolve(p);
+    const stat = fs9.statSync(resolved);
     if (stat.isDirectory()) {
-      const entries = fs8.readdirSync(resolved, { withFileTypes: true });
+      const entries = fs9.readdirSync(resolved, { withFileTypes: true });
       for (const entry of entries) {
         if (entry.isFile()) {
-          result.push(path7.join(resolved, entry.name));
+          result.push(path8.join(resolved, entry.name));
         }
       }
     } else {
@@ -50006,7 +51136,18 @@ function resolveUploadPaths(rawPaths) {
   return result;
 }
 async function main() {
-  const { command, subcommand, toolArgs, restArgs, flags } = parseArgs(process.argv.slice(2));
+  const parsed = parseArgs(process.argv.slice(2));
+  const { restArgs, flags } = parsed;
+  let { command, subcommand, toolArgs } = parsed;
+  if (command === "file") {
+    if (!subcommand) {
+      printHelp();
+      return;
+    }
+    command = subcommand;
+    subcommand = toolArgs;
+    toolArgs = restArgs.shift();
+  }
   if (flags.help || !command && !flags.version) {
     printHelp();
     return;
@@ -50100,6 +51241,10 @@ async function main() {
     await runDocxCommand(subcommand, toolArgs, restArgs);
     return;
   }
+  if (command === "preview") {
+    await runPreviewCommand(subcommand, flags);
+    return;
+  }
   if (command === "ui") {
     if (subcommand === "link") {
       const component = toolArgs;
@@ -50116,6 +51261,19 @@ async function main() {
     console.error("Usage: lotics ui link <component> [--ui-src <abs path>] [--remove]");
     process.exit(1);
   }
+  if (command === "package" && subcommand === "new") {
+    const name = toolArgs;
+    if (!name) {
+      console.error("Usage: lotics package new <name> [path]");
+      process.exit(1);
+    }
+    await packageNew({ name, targetPath: restArgs[0] });
+    return;
+  }
+  if (command === "package" && subcommand === "build") {
+    await packageBuild({ projectDir: toolArgs });
+    return;
+  }
   if (command === "app" && subcommand === "workflow" && toolArgs === "check") {
     await appWorkflowCheck({ alias: restArgs[0] });
     return;
@@ -50190,7 +51348,7 @@ async function main() {
     }
     return;
   }
-  if (command !== "tools" && command !== "upload" && command !== "run" && command !== "download" && command !== "workspace" && command !== "app") {
+  if (command !== "tools" && command !== "upload" && command !== "run" && command !== "download" && command !== "workspace" && command !== "app" && command !== "package") {
     console.error(`Unknown command: ${command}`);
     console.error('Run "lotics --help" for usage.');
     process.exit(1);
@@ -50212,6 +51370,24 @@ async function main() {
     console.error("  lotics app dev [path]                Run the app locally with HMR + RPC forwarding");
     process.exit(1);
   }
+  if (command === "package" && !subcommand) {
+    console.error("Usage:");
+    console.error("  lotics package new <name> [path]                 Scaffold a package project (contract + app source)");
+    console.error("  lotics package build [path]                      Build the publishable bundle (source + dist)");
+    console.error("  lotics package publish [path] [-m <changelog>]   Publish a new immutable package version");
+    console.error("  lotics package dev [path] [--workspace <ws>]     Sync into a dev workspace + run the app dev server");
+    console.error("  lotics package sync [path] [--workspace <ws>]    Re-sync (additive migrate + materialize) into a dev workspace");
+    console.error("  lotics package reset [path] [--workspace <ws>]   DEV-ONLY: drop scaffolded tables + re-scaffold clean");
+    console.error("  lotics package install <package> [--version N]   Install a package into this workspace");
+    console.error("  lotics package upgrade <app_id> [--version N] [--resolve ns.alias=recreate|<id>]   Preview + apply an upgrade");
+    console.error("  lotics package doctor [app_id]                   Health: version pin vs latest + binding drift");
+    console.error("  lotics package rebind-role <app_id> <alias> <grp_id>   Re-point a package role at another group");
+    console.error("  lotics package eject <app_id>                    Sever an installation's package link");
+    console.error("  lotics package extract <app_id> [path]           Promote a bespoke app to a draft package project");
+    console.error("  lotics package adopt <app_id> [path]             Bind the published project onto the origin app");
+    console.error("  lotics package fleet-upgrade <package_id> [--version N]   Upgrade every org installation (clean ones apply; findings skip)");
+    process.exit(1);
+  }
   if (command === "run" && !subcommand) {
     console.error(
       "Usage: lotics run <tool> '<json_args>'\n       lotics run <tool> @args.json   (read args from a file \u2014 for large payloads)\n       cat args.json | lotics run <tool>   (read args from stdin)"
@@ -50238,6 +51414,25 @@ async function main() {
   }
   const { client, ctx } = requireClient(flags);
   if (command === "workspace") {
+    if (subcommand === "doctor") {
+      await resolveWorkspace(client, ctx);
+      const dangling = await client.getWorkspaceDanglingReferences();
+      if (dangling.length === 0) {
+        console.error("Workspace references: healthy \u2014 every referenced schema id resolves.");
+        return;
+      }
+      console.error(`Dangling schema references (${dangling.length}):`);
+      for (const d of dangling) {
+        console.error(
+          `  - ${d.referent.kind} "${d.referent.name}" (${d.referent.id}) \u2192 ${d.namespace} ${d.id} (missing)`
+        );
+      }
+      console.error(
+        "Each referent points at schema that no longer exists \u2014 edit or archive it, or recreate the missing schema."
+      );
+      process.exitCode = 1;
+      return;
+    }
     const workspaces = await client.listWorkspaces();
     const currentWorkspaceId = ctx.workspaceId;
     if (subcommand === "select") {
@@ -50266,11 +51461,11 @@ Available workspaces:`);
     if (subcommand === "create") {
       const name = toolArgs;
       if (!name) {
-        console.error("Usage: lotics workspace create <name> [--timezone <tz>]");
+        console.error("Usage: lotics workspace create <name> [--timezone <tz>] [--dev]");
         process.exit(1);
       }
       const timezone = flags.timezone;
-      const created = await client.createWorkspace({ name, timezone });
+      const created = await client.createWorkspace({ name, timezone, is_dev: flags.dev || void 0 });
       setSelectedWorkspace(created.id);
       client.setWorkspaceId(created.id);
       if (flags.json) {
@@ -50332,6 +51527,150 @@ Available workspaces:`);
     return;
   }
   await resolveWorkspace(client, ctx);
+  if (command === "package") {
+    if (subcommand === "install") {
+      const packageId = toolArgs;
+      if (!packageId) {
+        console.error("Usage: lotics package install <package> [--version N]");
+        process.exit(1);
+      }
+      let version;
+      if (flags.packageVersion !== void 0) {
+        version = Number(flags.packageVersion);
+        if (!Number.isInteger(version) || version <= 0) {
+          console.error(`Invalid --version "${flags.packageVersion}" \u2014 expected a positive integer.`);
+          process.exit(1);
+        }
+      }
+      await packageInstall(client, { package_id: packageId, version });
+      return;
+    }
+    if (subcommand === "eject") {
+      const appId = toolArgs;
+      if (!appId) {
+        console.error("Usage: lotics package eject <app_id>");
+        process.exit(1);
+      }
+      await packageEject(client, { app_id: appId });
+      return;
+    }
+    if (subcommand === "extract") {
+      const appId = toolArgs;
+      if (!appId) {
+        console.error("Usage: lotics package extract <app_id> [path]");
+        console.error("Promotes a bespoke app to a draft package project (contract + binding + templates).");
+        process.exit(1);
+      }
+      await packageExtract(client, { app_id: appId, targetPath: restArgs[0] });
+      return;
+    }
+    if (subcommand === "adopt") {
+      const appId = toolArgs;
+      if (!appId) {
+        console.error("Usage: lotics package adopt <app_id> [path]");
+        console.error("Binds the published package project (this dir, or [path]) onto the origin app.");
+        process.exit(1);
+      }
+      let version;
+      if (flags.packageVersion !== void 0) {
+        version = Number(flags.packageVersion);
+        if (!Number.isInteger(version) || version <= 0) {
+          console.error(`Invalid --version "${flags.packageVersion}" \u2014 expected a positive integer.`);
+          process.exit(1);
+        }
+      }
+      await packageAdopt(client, { app_id: appId, version, projectDir: restArgs[0] });
+      return;
+    }
+    if (subcommand === "fleet-upgrade") {
+      const packageId = toolArgs;
+      if (!packageId) {
+        console.error("Usage: lotics package fleet-upgrade <package_id> [--version N]");
+        process.exit(1);
+      }
+      let version;
+      if (flags.packageVersion !== void 0) {
+        version = Number(flags.packageVersion);
+        if (!Number.isInteger(version) || version <= 0) {
+          console.error(`Invalid --version "${flags.packageVersion}" \u2014 expected a positive integer.`);
+          process.exit(1);
+        }
+      }
+      await packageFleetUpgrade(client, { package_id: packageId, version });
+      return;
+    }
+    if (subcommand === "doctor") {
+      await packageDoctor(client, { app_id: toolArgs });
+      return;
+    }
+    if (subcommand === "rebind-role") {
+      const appId = toolArgs;
+      const [roleAlias, groupId] = restArgs;
+      if (!appId || !roleAlias || !groupId) {
+        console.error("Usage: lotics package rebind-role <app_id> <role_alias> <grp_id>");
+        process.exit(1);
+      }
+      const result = await client.rebindAppPackageRole(appId, {
+        role_alias: roleAlias,
+        group_id: groupId
+      });
+      console.error(
+        `Rebound role "${result.role_alias}" \u2192 ${result.group_id}` + (result.previous_group_id ? ` (was ${result.previous_group_id})` : "") + ". Package workflows/agents were re-materialized against the new group."
+      );
+      return;
+    }
+    if (subcommand === "upgrade") {
+      const appId = toolArgs;
+      if (!appId) {
+        console.error(
+          "Usage: lotics package upgrade <app_id> [--version N] [--resolve <namespace.alias>=recreate|<id> ...]"
+        );
+        process.exit(1);
+      }
+      let version;
+      if (flags.packageVersion !== void 0) {
+        version = Number(flags.packageVersion);
+        if (!Number.isInteger(version) || version <= 0) {
+          console.error(`Invalid --version "${flags.packageVersion}" \u2014 expected a positive integer.`);
+          process.exit(1);
+        }
+      }
+      await packageUpgrade(client, {
+        app_id: appId,
+        version,
+        resolutions: parseResolveFlags(flags.resolve)
+      });
+      return;
+    }
+    if (subcommand === "publish") {
+      await packagePublish(client, { projectDir: toolArgs, changelog: flags.message });
+      return;
+    }
+    if (subcommand === "sync") {
+      await packageSync(client, { projectDir: toolArgs });
+      return;
+    }
+    if (subcommand === "reset") {
+      await packageReset(client, { projectDir: toolArgs });
+      return;
+    }
+    if (subcommand === "dev") {
+      const projectDir = toolArgs;
+      let port;
+      let vitePort;
+      for (const a of restArgs) {
+        const portMatch = /^--port=(\d+)$/.exec(a);
+        const vitePortMatch = /^--vite-port=(\d+)$/.exec(a);
+        if (portMatch) port = Number(portMatch[1]);
+        else if (vitePortMatch) vitePort = Number(vitePortMatch[1]);
+      }
+      await packageDev(client, { projectDir, port, vitePort });
+      return;
+    }
+    console.error(`Unknown package subcommand: ${subcommand}`);
+    console.error("Run 'lotics package' for usage.");
+    process.exit(1);
+  }
   if (command === "app") {
     if (subcommand === "create") {
       const name = toolArgs;
@@ -50411,7 +51750,7 @@ Available workspaces:`);
         const ingested = await ingestJsonArgs({
           rawArg: restArgs[1],
           stdinIsTTY: process.stdin.isTTY ?? false,
-          readFile: (p) => fs8.readFileSync(p, "utf-8"),
+          readFile: (p) => fs9.readFileSync(p, "utf-8"),
           readStdin
         });
         if (ingested.kind === "error") {
@@ -50563,7 +51902,7 @@ ${JSON.stringify(info.input_schema, null, 2)}`);
     const ingested = await ingestJsonArgs({
       rawArg: toolArgs,
       stdinIsTTY: process.stdin.isTTY ?? false,
-      readFile: (p) => fs8.readFileSync(p, "utf-8"),
+      readFile: (p) => fs9.readFileSync(p, "utf-8"),
       readStdin
     });
     if (ingested.kind === "error") {