@lotics/cli 0.71.0 → 0.74.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);
         });
@@ -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];
@@ -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;
@@ -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`
@@ -29830,6 +30012,10 @@ var LoticsClient = class {
     const qs = group_id ? `?group_id=${encodeURIComponent(group_id)}` : "";
     return this.request("GET", `/v1/apps/${encodeURIComponent(app_id)}/members${qs}`);
   }
+  /** A package installation's alias→id maps (fields/options/roles) — the app's runtime F/OPT resolution. */
+  async appBinding(app_id) {
+    return this.request("GET", `/v1/apps/${encodeURIComponent(app_id)}/binding`);
+  }
   /**
    * Resolve the full option set (key, label, color) of a named query's select
    * columns — the picker companion to `appQuery`. Mirrors
@@ -30372,7 +30558,7 @@ import { tmpdir } from "node:os";
 
 // src/starter_template.ts
 var STARTER_FALLBACK_UI_VERSION = "6.1.0";
-var STARTER_FALLBACK_SDK_VERSION = "0.40.0";
+var STARTER_FALLBACK_SDK_VERSION = "0.51.0";
 var STARTER_REACT_NATIVE_VERSION = "0.85.3";
 function buildStarterTemplate(args) {
   const uiVersion = args.ui_version ?? `^${STARTER_FALLBACK_UI_VERSION}`;
@@ -30592,6 +30778,11 @@ export default defineConfig({
   build: {
     outDir: "dist",
     sourcemap: true,
+    // Top-level await (package projects' generated .lotics/app_fields.ts
+    // resolves the installation binding at module load) needs es2022 \u2014 Vite's
+    // default 'modules' baseline is es2020 and esbuild hard-fails TLA there.
+    // Dev already transforms at esnext, so this only aligns the prod build.
+    target: "es2022",
   },
   server: {
     // Allow the sandboxed null-origin iframe used by \`lotics app dev\` to
@@ -31095,6 +31286,7 @@ var SUPPORTED_OPS = /* @__PURE__ */ new Set([
   "workflow",
   "members",
   "context",
+  "binding",
   "upload_url",
   "upload_complete",
   "comments.list",
@@ -31112,10 +31304,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": {
@@ -31151,6 +31344,8 @@ async function dispatchRpc(client, body, opts) {
       const p = body.payload;
       return client.appMembers(body.app_id, p?.group);
     }
+    case "binding":
+      return client.appBinding(body.app_id);
     case "upload_url": {
       const p = body.payload;
       if (!p || typeof p.filename !== "string" || typeof p.mime_type !== "string" || typeof p.file_size !== "number") {
@@ -31995,6 +32190,7 @@ function walk(node, visit) {
     case "sort":
     case "limit":
     case "unpivot":
+    case "unnest":
       walk(node.from, visit);
       return;
     case "join":
@@ -33162,6 +33358,864 @@ 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/generate_package_fields.ts
+var HEADER5 = `// Auto-generated by 'lotics package new/extract/dev/sync' from contract.json.
+// DO NOT EDIT \u2014 regenerated whenever the contract changes.
+//
+// Package apps resolve F/OPT/ROLE at MODULE LOAD from the installation's
+// binding (contract alias \u2192 THIS workspace's concrete id) via the SDK's
+// \`binding\` RPC. Top-level await: the module graph waits for the binding
+// before any importer evaluates, so every entry is a plain string.
+import { getAppBinding } from "@lotics/app-sdk";
+
+const binding = await getAppBinding();
+
+function bound(map: Record<string, string>, key: string, kind: string): string {
+  const id = map[key];
+  if (id === undefined) {
+    throw new Error(
+      \`app_fields: \${kind} "\${key}" is not in this installation's binding \u2014 \` +
+        \`the generated app_fields.ts is stale relative to the installed contract version.\`,
+    );
+  }
+  return id;
+}
+`;
+function generatePackageAppFields(contract) {
+  const entities = contract.entities ?? [];
+  const roles = contract.roles ?? [];
+  const fieldBlocks = [];
+  for (const entity of entities) {
+    const lines = (entity.fields ?? []).map(
+      (field) => `    ${propKey(field.alias)}: bound(binding.fields, ${JSON.stringify(`${entity.alias}.${field.alias}`)}, "field"),`
+    );
+    if (lines.length === 0) continue;
+    fieldBlocks.push(`  ${propKey(entity.alias.toUpperCase())}: {
+${lines.join("\n")}
+  },`);
+  }
+  const optionBlocks = [];
+  for (const entity of entities) {
+    const perField = [];
+    for (const field of entity.fields ?? []) {
+      const options = field.options ?? [];
+      if (options.length === 0) continue;
+      const lines = options.map(
+        (option) => `      ${propKey(option.alias)}: bound(binding.options, ${JSON.stringify(`${entity.alias}.${field.alias}:${option.alias}`)}, "option"),`
+      );
+      perField.push(`    ${propKey(field.alias)}: {
+${lines.join("\n")}
+    },`);
+    }
+    if (perField.length > 0) {
+      optionBlocks.push(`  ${propKey(entity.alias.toUpperCase())}: {
+${perField.join("\n")}
+  },`);
+    }
+  }
+  const fMap = fieldBlocks.length > 0 ? `export const F = {
+${fieldBlocks.join("\n")}
+} as const;` : `export const F = {} as const;`;
+  const optMap = optionBlocks.length > 0 ? `export const OPT = {
+${optionBlocks.join("\n")}
+} as const;` : `export const OPT = {} as const;`;
+  const roleMap = roles.length > 0 ? `export const ROLE = {
+${roles.map((role) => `  ${propKey(role.alias)}: bound(binding.roles, ${JSON.stringify(role.alias)}, "role"),`).join("\n")}
+} as const;` : `export const ROLE = {} as const;`;
+  return `${HEADER5}
+${fMap}
+
+${optMap}
+
+${roleMap}
+
+/** Field-id alias map: \`F[<ENTITY>][<field>]\` is this installation's \`fld_\u2026\` id. */
+export type AppFields = typeof F;
+/** Select-option alias map: \`OPT[<ENTITY>][<field>][<option>]\` is this installation's \`opt_\u2026\` id. */
+export type AppOptions = typeof OPT;
+/** Role alias map: \`ROLE[<role>]\` is this installation's \`grp_\u2026\` id. */
+export type AppRoles = typeof ROLE;
+`;
+}
+
+// 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 dotLoticsDirEnsured(projectDir) {
+  const dir = path7.join(projectDir, ".lotics");
+  fs6.mkdirSync(dir, { recursive: true });
+  return dir;
+}
+function cmpVersions(a, b) {
+  const pa = a.split(".").map(Number);
+  const pb = b.split(".").map(Number);
+  for (let i2 = 0; i2 < 3; i2++) {
+    const d = (pa[i2] || 0) - (pb[i2] || 0);
+    if (d !== 0) return d;
+  }
+  return 0;
+}
+function packageSdkRange(sdkLatest) {
+  const version = sdkLatest !== null && cmpVersions(sdkLatest, STARTER_FALLBACK_SDK_VERSION) > 0 ? sdkLatest : STARTER_FALLBACK_SDK_VERSION;
+  return `^${version}`;
+}
+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"));
+}
+function writePackageAppFields(projectDir) {
+  const contract = readContract(projectDir);
+  const dotLotics = path7.join(projectDir, ".lotics");
+  fs6.mkdirSync(dotLotics, { recursive: true });
+  fs6.writeFileSync(path7.join(dotLotics, "app_fields.ts"), generatePackageAppFields(contract));
+  console.error("Wrote .lotics/app_fields.ts (contract-derived, runtime-resolved)");
+}
+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 [uiLatest, sdkLatest] = await Promise.all([
+    fetchLatestNpmVersion("@lotics/ui"),
+    fetchLatestNpmVersion("@lotics/app-sdk")
+  ]);
+  const files = buildStarterTemplate({
+    app_name: args.name,
+    app_id: "",
+    workspace_id: "",
+    ui_version: uiLatest ? `^${uiLatest}` : void 0,
+    sdk_version: packageSdkRange(sdkLatest)
+  });
+  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"
+  );
+  writePackageAppFields(targetPath);
+  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);
+  writePackageAppFields(projectDir);
+  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")
+  );
+  const draft = draftPackageProjectFromApp(appPkgJson, { name: app.name, description: null });
+  const deps = isPlainObject(draft.pkgJson.dependencies) ? draft.pkgJson.dependencies : {};
+  const originRange = typeof deps["@lotics/app-sdk"] === "string" ? deps["@lotics/app-sdk"] : null;
+  const originFloor = originRange?.replace(/^[\^~]/, "") ?? null;
+  if (originFloor === null || cmpVersions(originFloor, STARTER_FALLBACK_SDK_VERSION) < 0) {
+    const raised = packageSdkRange(await fetchLatestNpmVersion("@lotics/app-sdk"));
+    draft.pkgJson.dependencies = { ...deps, "@lotics/app-sdk": raised };
+    console.error(`Raised @lotics/app-sdk to ${raised} (generated app_fields needs getAppBinding)`);
+  }
+  writePackageManifest(targetPath, draft);
+  fs6.writeFileSync(
+    path7.join(targetPath, CONTRACT_FILE),
+    JSON.stringify(extracted.contract, null, 2) + "\n"
+  );
+  console.error(`Wrote ${CONTRACT_FILE}`);
+  writePackageAppFields(targetPath);
+  const starterViteConfig = buildStarterTemplate({
+    app_name: app.name,
+    app_id: "",
+    workspace_id: ""
+  }).find((f) => f.path === "vite.config.ts");
+  if (starterViteConfig === void 0) {
+    throw new Error("starter template is missing vite.config.ts \u2014 cannot refresh the package project");
+  }
+  const viteConfigPath = path7.join(targetPath, "vite.config.ts");
+  const originViteConfig = fs6.existsSync(viteConfigPath) ? fs6.readFileSync(viteConfigPath, "utf-8") : null;
+  fs6.writeFileSync(viteConfigPath, starterViteConfig.content);
+  if (originViteConfig !== null && originViteConfig !== starterViteConfig.content) {
+    const stash = path7.join(dotLoticsDirEnsured(targetPath), "vite.config.origin.ts");
+    fs6.writeFileSync(stash, originViteConfig);
+    console.error(
+      "Refreshed vite.config.ts from the starter (build.target es2022). The origin app's config differed \u2014 its original was saved to .lotics/vite.config.origin.ts; re-apply any custom optimizeDeps/plugins entries you still need (never dev-link aliases)."
+    );
+  } else {
+    console.error("Refreshed vite.config.ts from the starter (build.target es2022)");
+  }
+  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 +34232,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 +34288,9 @@ function parseArgs(argv) {
       case "--local":
         flags.local = true;
         break;
+      case "--dev":
+        flags.dev = true;
+        break;
       case "--all":
         flags.all = true;
         break;
@@ -33245,10 +34305,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 +34381,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 +37158,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 +37175,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 +37185,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 +37195,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 +42662,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 +44388,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 +45001,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 +45014,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 +45094,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 +45115,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 +46877,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 +47875,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 +47926,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 +48316,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 +50087,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 +50320,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 +50332,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 +50420,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) {
@@ -49659,7 +50713,7 @@ async function runDocxCommand(subcommand, toolArgs, restArgs) {
 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 tmpdir2 } from "node:os";
+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";
@@ -49752,7 +50806,7 @@ async function runPreviewCommand(filePath, flags) {
   });
   await new Promise((r) => server.listen(0, "127.0.0.1", () => r()));
   const httpPort = server.address().port;
-  const udd = mkdtempSync(join(tmpdir2(), "lotics-render-"));
+  const udd = mkdtempSync(join(tmpdir3(), "lotics-render-"));
   const child = spawn3(chrome, [
     "--headless=new",
     "--disable-gpu",
@@ -49893,6 +50947,7 @@ 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
@@ -49925,6 +50980,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
@@ -49953,6 +51039,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
 
@@ -50037,8 +51125,8 @@ function prompt(question) {
     });
   });
 }
-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)
@@ -50184,13 +51272,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 {
@@ -50325,6 +51413,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;
@@ -50399,7 +51500,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);
@@ -50421,6 +51522,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)"
@@ -50447,6 +51566,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") {
@@ -50475,11 +51613,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) {
@@ -50541,6 +51679,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;
@@ -50620,7 +51902,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") {
@@ -50772,7 +52054,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") {