@lotics/cli 0.136.0 → 0.142.0

package/dist/src/cli.js

@@ -26822,12 +26822,12 @@ var require_tokens = __commonJS({
       });
     }
     exports2.assignCategoriesMapProp = assignCategoriesMapProp;
-    function singleAssignCategoriesToksMap(path10, nextNode) {
-      utils_1.forEach(path10, function(pathNode) {
+    function singleAssignCategoriesToksMap(path12, nextNode) {
+      utils_1.forEach(path12, function(pathNode) {
         nextNode.categoryMatchesMap[pathNode.tokenTypeIdx] = true;
       });
       utils_1.forEach(nextNode.CATEGORIES, function(nextCategory) {
-        var newPath = path10.concat(nextNode);
+        var newPath = path12.concat(nextNode);
         if (!utils_1.contains(newPath, nextCategory)) {
           singleAssignCategoriesToksMap(newPath, nextCategory);
         }
@@ -28590,10 +28590,10 @@ var require_interpreter = __commonJS({
       /** @class */
       (function(_super) {
         __extends(AbstractNextPossibleTokensWalker2, _super);
-        function AbstractNextPossibleTokensWalker2(topProd, path10) {
+        function AbstractNextPossibleTokensWalker2(topProd, path12) {
           var _this = _super.call(this) || this;
           _this.topProd = topProd;
-          _this.path = path10;
+          _this.path = path12;
           _this.possibleTokTypes = [];
           _this.nextProductionName = "";
           _this.nextProductionOccurrence = 0;
@@ -28647,9 +28647,9 @@ var require_interpreter = __commonJS({
       /** @class */
       (function(_super) {
         __extends(NextAfterTokenWalker2, _super);
-        function NextAfterTokenWalker2(topProd, path10) {
-          var _this = _super.call(this, topProd, path10) || this;
-          _this.path = path10;
+        function NextAfterTokenWalker2(topProd, path12) {
+          var _this = _super.call(this, topProd, path12) || this;
+          _this.path = path12;
           _this.nextTerminalName = "";
           _this.nextTerminalOccurrence = 0;
           _this.nextTerminalName = _this.path.lastTok.name;
@@ -29346,10 +29346,10 @@ var require_lookahead = __commonJS({
       }
       return result;
     }
-    function pathToHashKeys(path10) {
+    function pathToHashKeys(path12) {
       var keys3 = [""];
-      for (var i2 = 0; i2 < path10.length; i2++) {
-        var tokType = path10[i2];
+      for (var i2 = 0; i2 < path12.length; i2++) {
+        var tokType = path12[i2];
         var longerKeys = [];
         for (var j = 0; j < keys3.length; j++) {
           var currShorterKey = keys3[j];
@@ -29661,9 +29661,9 @@ var require_checks = __commonJS({
       return errors2;
     }
     exports2.validateRuleIsOverridden = validateRuleIsOverridden;
-    function validateNoLeftRecursion(topRule, currRule, errMsgProvider, path10) {
-      if (path10 === void 0) {
-        path10 = [];
+    function validateNoLeftRecursion(topRule, currRule, errMsgProvider, path12) {
+      if (path12 === void 0) {
+        path12 = [];
       }
       var errors2 = [];
       var nextNonTerminals = getFirstNoneTerminal(currRule.definition);
@@ -29676,15 +29676,15 @@ var require_checks = __commonJS({
           errors2.push({
             message: errMsgProvider.buildLeftRecursionError({
               topLevelRule: topRule,
-              leftRecursionPath: path10
+              leftRecursionPath: path12
             }),
             type: parser_1.ParserDefinitionErrorType.LEFT_RECURSION,
             ruleName
           });
         }
-        var validNextSteps = utils2.difference(nextNonTerminals, path10.concat([topRule]));
+        var validNextSteps = utils2.difference(nextNonTerminals, path12.concat([topRule]));
         var errorsFromNextSteps = utils2.map(validNextSteps, function(currRefRule) {
-          var newPath = utils2.cloneArr(path10);
+          var newPath = utils2.cloneArr(path12);
           newPath.push(currRefRule);
           return validateNoLeftRecursion(topRule, currRefRule, errMsgProvider, newPath);
         });
@@ -37293,8 +37293,8 @@ var require_utils4 = __commonJS({
       var result = transform2[inputType][outputType](input);
       return result;
     };
-    exports2.resolve = function(path10) {
-      var parts = path10.split("/");
+    exports2.resolve = function(path12) {
+      var parts = path12.split("/");
       var result = [];
       for (var index = 0; index < parts.length; index++) {
         var part = parts[index];
@@ -43147,18 +43147,18 @@ var require_object = __commonJS({
       var object2 = new ZipObject(name2, zipObjectContent, o);
       this.files[name2] = object2;
     };
-    var parentFolder = function(path10) {
-      if (path10.slice(-1) === "/") {
-        path10 = path10.substring(0, path10.length - 1);
+    var parentFolder = function(path12) {
+      if (path12.slice(-1) === "/") {
+        path12 = path12.substring(0, path12.length - 1);
       }
-      var lastSlash = path10.lastIndexOf("/");
-      return lastSlash > 0 ? path10.substring(0, lastSlash) : "";
+      var lastSlash = path12.lastIndexOf("/");
+      return lastSlash > 0 ? path12.substring(0, lastSlash) : "";
     };
-    var forceTrailingSlash = function(path10) {
-      if (path10.slice(-1) !== "/") {
-        path10 += "/";
+    var forceTrailingSlash = function(path12) {
+      if (path12.slice(-1) !== "/") {
+        path12 += "/";
       }
-      return path10;
+      return path12;
     };
     var folderAdd = function(name2, createFolders) {
       createFolders = typeof createFolders !== "undefined" ? createFolders : defaults2.createFolders;
@@ -44160,9 +44160,9 @@ var require_lib4 = __commonJS({
 // src/cli.ts
 import dns from "node:dns";
 import net2 from "node:net";
-import fs11 from "node:fs";
+import fs13 from "node:fs";
 import os4 from "node:os";
-import path9 from "node:path";
+import path11 from "node:path";
 import readline from "node:readline";
 
 // ../shared/src/transport_error.ts
@@ -44345,8 +44345,8 @@ var LoticsClient = class {
     }
     return headers;
   }
-  async request(method, path10, body) {
-    const url2 = `${this.baseUrl}${path10}`;
+  async request(method, path12, body) {
+    const url2 = `${this.baseUrl}${path12}`;
     const headers = this.buildHeaders();
     const init = { method, headers };
     if (body !== void 0) {
@@ -44360,6 +44360,14 @@ var LoticsClient = class {
   async whoami() {
     return this.request("GET", "/v1/cli/whoami");
   }
+  /**
+   * File a hand-written report. Unlike a telemetry flush, the headers this
+   * stamps are CORRECT: the invocation making the request is the one the report
+   * is about, so the courier and the cargo are the same session.
+   */
+  async sendReport(body) {
+    return this.request("POST", "/v1/cli/report", body);
+  }
   setWorkspaceId(id) {
     this.workspaceId = id;
   }
@@ -45614,9 +45622,422 @@ var pkgPath = path5.resolve(path5.dirname(fileURLToPath(import.meta.url)), "../.
 var pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
 var VERSION = pkg.version;
 
-// src/app_commands.ts
+// src/docs_command.ts
+import fs5 from "node:fs";
+import path6 from "node:path";
+import { fileURLToPath as fileURLToPath2 } from "node:url";
+var READING_ORDER = ["@lotics/app-sdk", "@lotics/ui", "@lotics/cli"];
+function firstHeading(file2) {
+  let text;
+  try {
+    text = fs5.readFileSync(file2, "utf-8");
+  } catch {
+    return "";
+  }
+  for (const line of text.split("\n", 40)) {
+    const m = /^#\s+(.+?)\s*$/.exec(line);
+    if (m) return m[1];
+  }
+  return "";
+}
+function readVersion(pkgDir) {
+  try {
+    const raw = fs5.readFileSync(path6.join(pkgDir, "package.json"), "utf-8");
+    return JSON.parse(raw).version ?? "?";
+  } catch {
+    return "?";
+  }
+}
+function ownPackageDir() {
+  return path6.resolve(path6.dirname(fileURLToPath2(import.meta.url)), "../..");
+}
+function referencePackageDirs(projectDir) {
+  const found = /* @__PURE__ */ new Map();
+  for (let dir = projectDir; ; ) {
+    const scope = path6.join(dir, "node_modules", "@lotics");
+    if (fs5.existsSync(scope)) {
+      for (const name2 of fs5.readdirSync(scope)) {
+        const pkgDir = path6.join(scope, name2);
+        const carries = fs5.existsSync(path6.join(pkgDir, "AGENTS.md")) || fs5.existsSync(path6.join(pkgDir, "docs"));
+        if (carries && !found.has(`@lotics/${name2}`)) found.set(`@lotics/${name2}`, pkgDir);
+      }
+    }
+    const parent = path6.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  const own = ownPackageDir();
+  if (!found.has("@lotics/cli") && fs5.existsSync(path6.join(own, "AGENTS.md"))) {
+    found.set("@lotics/cli", own);
+  }
+  return [...found.entries()].map(([pkg2, dir]) => ({ pkg: pkg2, dir })).sort((a, b) => {
+    const ia = READING_ORDER.indexOf(a.pkg);
+    const ib = READING_ORDER.indexOf(b.pkg);
+    if (ia !== ib) return (ia < 0 ? READING_ORDER.length : ia) - (ib < 0 ? READING_ORDER.length : ib);
+    return a.pkg.localeCompare(b.pkg);
+  });
+}
+function collectDocAreas(projectDir) {
+  const found = [];
+  for (const { pkg: pkg2, dir } of referencePackageDirs(projectDir)) {
+    const version2 = readVersion(dir);
+    const index = path6.join(dir, "AGENTS.md");
+    if (fs5.existsSync(index)) {
+      found.push({
+        area: pkg2.replace("@lotics/", ""),
+        pkg: pkg2,
+        version: version2,
+        absPath: index,
+        title: firstHeading(index)
+      });
+    }
+    const docsDir = path6.join(dir, "docs");
+    if (!fs5.existsSync(docsDir)) continue;
+    for (const file2 of fs5.readdirSync(docsDir).sort()) {
+      if (!file2.endsWith(".md")) continue;
+      const abs2 = path6.join(docsDir, file2);
+      found.push({
+        area: file2.replace(/\.md$/, ""),
+        pkg: pkg2,
+        version: version2,
+        absPath: abs2,
+        title: firstHeading(abs2)
+      });
+    }
+  }
+  return found;
+}
+function qualified(a) {
+  return `${a.pkg.replace("@lotics/", "")}/${a.area}`;
+}
+function matchDocArea(areas, query) {
+  const q = query.trim().toLowerCase().replace(/\.md$/, "");
+  const exact = areas.filter((a) => a.area.toLowerCase() === q || qualified(a).toLowerCase() === q);
+  if (exact.length > 0) return exact;
+  return areas.filter((a) => a.area.toLowerCase().includes(q));
+}
+function onlySelfReference(areas) {
+  return areas.length > 0 && areas.every((a) => a.pkg === "@lotics/cli");
+}
+function renderDocIndex(areas) {
+  if (areas.length === 0) {
+    return "No reference packages resolved here.\n  The references ship INSIDE the packages, so they appear once a project installs them:\n  @lotics/app-sdk, @lotics/ui \u2014 run this from an app directory (see `lotics app create`).";
+  }
+  const lines = [];
+  let currentPkg = "";
+  for (const a of areas) {
+    if (a.pkg !== currentPkg) {
+      currentPkg = a.pkg;
+      lines.push(`
+${a.pkg}  ${a.version}`);
+    }
+    const name2 = a.absPath.endsWith("AGENTS.md") ? `${a.area}  \u2190 start here` : a.area;
+    lines.push(`  ${name2.padEnd(24)}${a.title}`);
+  }
+  lines.push("\n  lotics docs <area>            print one, e.g. `lotics docs ai`");
+  lines.push("  lotics docs <pkg>/<area>      when two packages share a name");
+  lines.push("\n  Versions are the INSTALLED ones; a doc describes the version beside it.");
+  if (onlySelfReference(areas)) {
+    lines.push(
+      "\n  Only this CLI's own reference resolved here \u2014 the @lotics/app-sdk and @lotics/ui\n  references are NOT among them. They ship inside those packages, so they appear\n  once a project installs them: `lotics app create <name>` scaffolds one with both."
+    );
+  }
+  return lines.join("\n");
+}
+function docsCommand(args) {
+  const projectDir = path6.resolve(args.projectDir ?? process.cwd());
+  const areas = collectDocAreas(projectDir);
+  if (args.area === void 0 || args.area === "") {
+    console.log(renderDocIndex(areas));
+    return;
+  }
+  const hits = matchDocArea(areas, args.area);
+  if (hits.length === 0) {
+    console.error(
+      `No reference area matching "${args.area}".
+  Run \`lotics docs\` for what is installed here.`
+    );
+    process.exit(1);
+  }
+  if (hits.length > 1) {
+    console.error(
+      `"${args.area}" matches more than one reference \u2014 name the package:
+` + hits.map((a) => `  \u2022 lotics docs ${qualified(a)}   (${a.pkg} ${a.version})`).join("\n")
+    );
+    process.exit(1);
+  }
+  const hit = hits[0];
+  console.error(`${hit.pkg} ${hit.version} \xB7 ${path6.relative(projectDir, hit.absPath)}
+`);
+  process.stdout.write(fs5.readFileSync(hit.absPath, "utf-8"));
+}
+
+// src/commands.ts
+var COMMANDS = [
+  {
+    verbs: ["org"],
+    help: [
+      "  lotics org                           List saved orgs (marks active)",
+      "  lotics org use <name|id> [--local]   Switch active org (--local pins this dir)"
+    ]
+  },
+  {
+    verbs: ["workspace"],
+    help: [
+      "  lotics workspace                     List workspaces in the active org (marks current)",
+      "  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)"
+    ]
+  },
+  {
+    verbs: ["tools"],
+    help: [
+      "  lotics tools                         List all available tools",
+      "  lotics tools <name>                  Show tool description and input schema"
+    ]
+  },
+  {
+    verbs: ["install"],
+    help: ["  lotics install <package_id>          Materialize a published package into this workspace"]
+  },
+  {
+    verbs: ["upgrade"],
+    help: ["  lotics upgrade                       Take the installed package's next version"]
+  },
+  {
+    verbs: ["docs"],
+    help: [
+      "  lotics docs                          List the reference docs of the INSTALLED packages",
+      "  lotics docs <area>                   Print one (e.g. 'lotics docs ai')"
+    ]
+  },
+  {
+    verbs: ["report"],
+    help: [
+      "  lotics report '<json>'               Tell the Lotics team what got in your way \u2014 a",
+      "                                       capability that is missing, a command that",
+      "                                       succeeded but did the wrong thing, an error that",
+      "                                       did not say how to fix it. Nothing else records",
+      "                                       these. A frame, not a paragraph: {goal, actual,",
+      "                                       expected?, tried?, wanted?} \u2014 run it bare for the",
+      "                                       full prompt. Also @file.json, or '-' for stdin"
+    ]
+  },
+  {
+    verbs: ["run"],
+    help: [
+      "  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)"
+    ]
+  },
+  {
+    verbs: ["app"],
+    help: [
+      "  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 \u2014 COMMIT",
+      "                                       (-m is required \u2014 it's the version's audit trail;",
+      "                                       carries code + queries only \u2014 workflow bindings are",
+      "                                       managed by set_app_workflow / remove_app_workflow)",
+      "  lotics app versions [app_id]         Show deploy history newest-first (version,",
+      "                                       timestamp, deployer, build status, -m message;",
+      "                                       * marks the currently served version)",
+      "  lotics app codegen [path]            Regenerate .lotics/* (types + field/option ids)",
+      "                                       from the manifest + workspace schema \u2014 no deploy",
+      "  lotics app check                     Run every deploy pre-flight WITHOUT building or",
+      "                                       shipping: agent schemas vs the live app, workflow",
+      "                                       declarations and BODIES vs what is live, aliases",
+      "                                       the code calls but nothing bound, undeclared",
+      "                                       capabilities, query drift. Exits 1 on what a",
+      "                                       deploy would refuse, so CI can gate on it",
+      "  lotics app workflow run <alias> '<json>'  Execute a bound app workflow end-to-end",
+      "                                       (inputs: inline JSON, @file, or stdin;",
+      "                                        --print-created reports created records +",
+      "                                        a paste-ready cleanup plan; --cleanup also",
+      "                                        deletes those records \u2014 NOT a rollback)",
+      "  lotics app workflow set <alias>      Push the edited src/workflows/<alias>.ts body",
+      "                                       through set_app_workflow (server verifies)",
+      "  lotics app workflow pull             Rewrite src/workflows/*.ts from the server",
+      "  lotics app workflow check [alias]    Typecheck src/workflows bodies locally (one",
+      "                                       isolated program per alias; the app's own tsc)",
+      "  lotics app query set <alias>         Push package.json#lotics.queries.<alias> to",
+      "                                       apps.queries via set_app_query (no deploy;",
+      "                                       re-synced by the next deploy from the manifest)",
+      "  lotics app agent run <app_id> <alias> '<json>'  Run a bound app agent end-to-end",
+      "                                       (inputs: inline JSON, @file, or stdin; streams",
+      "                                        progress to stderr, reports the settled run;",
+      "                                        --session <id> continues a thread; --json)",
+      "  lotics app agent set <alias>         Push the edited src/agents/<alias>.md instructions,",
+      "                                       and ONLY those \u2014 the server merges, so the typed",
+      "                                       fields keep whatever is bound (a manifest is a",
+      "                                       snapshot; replaying it would revert them). Change",
+      "                                       those with set_app_agent, then pull.",
+      "  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)"
+    ]
+  },
+  {
+    verbs: ["knowledge"],
+    help: [
+      "  lotics knowledge list                List knowledge docs (id, name, description)",
+      "  lotics knowledge create --name <n> [--description <d>] --from <file.md>",
+      "                                       Create a doc from a file (or --content <str>);",
+      "                                       prints the new id",
+      "  lotics knowledge get <id> [-o <file.md>]",
+      "                                       Fetch a doc's content (to a file, or stdout;",
+      "                                       --json for the full doc)",
+      "  lotics knowledge update <id> [--from <file.md> | --content <str>] [--name <n>] [--description <d>]",
+      "                                       Update a doc \u2014 sends only the fields you pass",
+      "  lotics knowledge rm <id>             Archive a doc"
+    ]
+  },
+  {
+    verbs: ["xlsx"],
+    help: [
+      "  lotics xlsx <subcommand> ...         Read/write/edit .xlsx files on your local filesystem",
+      "                                       (uses the bundled Lotics xlsx engine; prefer over",
+      "                                       npm xlsx/exceljs for round-trip fidelity)"
+    ]
+  },
+  {
+    verbs: ["docx"],
+    help: [
+      "  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)"
+    ]
+  },
+  {
+    // `file` is a noun-group whose three verbs also stand alone.
+    verbs: ["file"],
+    aliases: ["upload", "download", "preview"],
+    help: [
+      "  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|fil_id> [-o png]",
+      "                                       Render a .docx/.xlsx to a PNG \u2014 a local path OR a",
+      "                                       stored file id (downloaded first). Frontend engines;",
+      "                                       needs a Chrome/Chromium on the machine"
+    ]
+  }
+];
+function renderCommandsHelp() {
+  return COMMANDS.flatMap((group) => group.help).join("\n");
+}
+function knownVerbs() {
+  return new Set(COMMANDS.flatMap((group) => [...group.verbs, ...group.aliases ?? []]));
+}
+
+// src/report_command.ts
 import fs6 from "node:fs";
 import path7 from "node:path";
+var LIMITS = { goal: 2e3, expected: 2e3, actual: 4e3, tried: 4e3, wanted: 2e3 };
+var REPORT_USAGE = `Usage: lotics report '<json>'      lotics report @report.json      \u2026 | lotics report -
+
+Tell the Lotics team what got in your way. Most valuable, in order:
+
+  \u2022 A capability that seems missing \u2014 "there is no way to <X>".
+    Nothing else can see this: no command ran, so nothing was recorded.
+  \u2022 A command that succeeded but did the wrong thing. Exit 0 hides it completely.
+  \u2022 An error message that did not name the remedy.
+  \u2022 Anything that made authoring slower than it should have been.
+
+The report is a frame, not a paragraph \u2014 these are the facts that exist only
+where you are sitting. The commands you ran attach themselves; do not retype them.
+
+  {
+    "goal":     "what you were trying to accomplish",          (required)
+    "actual":   "what happened instead",                       (required)
+    "expected": "what you expected \u2014 the gap is the defect",
+    "tried":    "what you already tried, and what it said",
+    "wanted":   "what would have unblocked you"
+  }
+
+There is no severity or category to pick. How bad and how common are read off
+the corpus; what you were trying to do is not recoverable from anywhere else.
+
+Do not paste customer records, file contents, or credentials.`;
+function parseReport(raw) {
+  const text = raw.trim();
+  if (text === "") return { error: "Nothing to report." };
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    return {
+      error: text.startsWith("{") ? "That is not valid JSON." : "A report is a JSON object, not a sentence \u2014 the frame below is what makes it debuggable."
+    };
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    return { error: "A report is a JSON object." };
+  }
+  const fields = parsed;
+  const read = (key) => {
+    const value2 = fields[key];
+    if (value2 === void 0 || value2 === null) return void 0;
+    if (typeof value2 !== "string") return void 0;
+    const trimmed = value2.trim();
+    return trimmed === "" ? void 0 : trimmed.slice(0, LIMITS[key]);
+  };
+  const goal = read("goal");
+  const actual = read("actual");
+  const missing = [goal === void 0 ? "goal" : "", actual === void 0 ? "actual" : ""].filter(
+    (k) => k !== ""
+  );
+  if (goal === void 0 || actual === void 0) {
+    return { error: `A report needs ${missing.join(" and ")}.` };
+  }
+  return { report: { goal, actual, expected: read("expected"), tried: read("tried"), wanted: read("wanted") } };
+}
+function appIdOf(projectDir) {
+  try {
+    const raw = fs6.readFileSync(path7.join(projectDir, "package.json"), "utf-8");
+    const pkg2 = JSON.parse(raw);
+    const appId = pkg2.lotics?.app_id;
+    return typeof appId === "string" && appId !== "" ? appId : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function echoReport(report) {
+  console.error("\nNothing was sent. Your report, so it is not lost:\n");
+  console.error(JSON.stringify(report, null, 2));
+}
+async function reportCommand(client, options) {
+  const report = options.report;
+  const session = getInvocation()?.session ?? null;
+  try {
+    await client.sendReport({
+      report,
+      cli_session_id: session,
+      cli_version: options.version,
+      workspace_id: options.workspaceId,
+      app_id: appIdOf(options.projectDir ?? process.cwd())
+    });
+  } catch (error52) {
+    console.error(
+      `Could not file the report: ${error52 instanceof Error ? error52.message : String(error52)}`
+    );
+    echoReport(report);
+    process.exit(1);
+  }
+  console.error("Filed. Thank you \u2014 this is read.");
+  if (session === null) {
+    console.error(
+      "\n  Sent without the session's commands attached \u2014 telemetry is off, so they were\n  never recorded. `export LOTICS_TELEMETRY=1` attaches them to the next report,\n  which is the difference between a description and a reproduction."
+    );
+  }
+}
+
+// src/app_commands.ts
+import fs8 from "node:fs";
+import path9 from "node:path";
 import { spawn as spawn2 } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import { tmpdir } from "node:os";
@@ -46298,7 +46719,7 @@ import { Text } from "@lotics/ui/text";
 
 @lotics/ui ships React Native primitives that render via react-native-web
 in this Vite app (the alias is preconfigured in \`vite.config.ts\`). See
-the full export list at https://www.npmjs.com/package/@lotics/ui.
+the full catalog with \`lotics docs ui\`.
 
 ## Routing
 
@@ -46311,7 +46732,9 @@ shareable and survives a full refresh. Standalone (\`<slug>.lotics.app\`) it's a
 normal browser router with real path URLs. A single-screen app can drop the
 router and render one screen directly.
 
-See https://lotics.ai/docs/app-sdk for the SDK reference.
+Run \`lotics docs\` for the SDK reference \u2014 it lists what the packages installed
+here actually ship, at the versions installed, so it can never point at a page
+that moved. (\`lotics docs ai\`, \`lotics docs queries\`, \`lotics docs ui\`.)
 `
     }
   ];
@@ -47553,11 +47976,15 @@ function codeWithoutComments(sourceText) {
   return out.join("");
 }
 var ALIAS_CALL_HOOKS = {
-  queries: "useQuery",
-  workflows: "useWorkflow",
-  agents: "useAgentRun"
+  queries: ["useQuery", "usePaginatedQuery", "useInfiniteQuery", "useFieldOptions"],
+  workflows: ["useWorkflow"],
+  agents: ["useAgentRun"]
 };
 var LITERAL_ALIAS_ARG = `["'\`]([A-Za-z_$][A-Za-z0-9_$]*)["'\`]`;
+function isAppSourcePath(projectRelativePath) {
+  const normalized = projectRelativePath.replace(/\\/g, "/").replace(/^\.\//, "");
+  return normalized.startsWith("src/") && /\.(ts|tsx|js|jsx)$/.test(normalized);
+}
 function calledAppAliases(sourceText) {
   const code = codeWithoutComments(sourceText);
   const out = {
@@ -47566,17 +47993,19 @@ function calledAppAliases(sourceText) {
     agents: [],
     dynamic: []
   };
-  for (const [kind, hook] of Object.entries(ALIAS_CALL_HOOKS)) {
+  for (const [kind, hooks] of Object.entries(ALIAS_CALL_HOOKS)) {
     const seen = /* @__PURE__ */ new Set();
-    let isDynamic = false;
-    for (const call of code.matchAll(new RegExp(`\\b${hook}\\s*\\(`, "g"))) {
-      const rest2 = code.slice(call.index + call[0].length);
-      const literal2 = new RegExp(`^\\s*${LITERAL_ALIAS_ARG}`).exec(rest2);
-      if (literal2) seen.add(literal2[1]);
-      else isDynamic = true;
+    for (const hook of hooks) {
+      let isDynamic = false;
+      for (const call of code.matchAll(new RegExp(`\\b${hook}\\s*\\(`, "g"))) {
+        const rest2 = code.slice(call.index + call[0].length);
+        const literal2 = new RegExp(`^\\s*${LITERAL_ALIAS_ARG}`).exec(rest2);
+        if (literal2) seen.add(literal2[1]);
+        else isDynamic = true;
+      }
+      if (isDynamic) out.dynamic.push(hook);
     }
     out[kind] = [...seen];
-    if (isDynamic) out.dynamic.push(hook);
   }
   return out;
 }
@@ -47870,8 +48299,8 @@ export type AppRoles = typeof ROLE;
 }
 
 // src/app_workflow_check.ts
-import fs5 from "node:fs";
-import path6 from "node:path";
+import fs7 from "node:fs";
+import path8 from "node:path";
 import { createRequire } from "node:module";
 
 // ../shared/src/parse_workflow_js.ts
@@ -48643,10 +49072,10 @@ function mergeDefs(...defs) {
 function cloneDef(schema) {
   return mergeDefs(schema._zod.def);
 }
-function getElementAtPath(obj, path10) {
-  if (!path10)
+function getElementAtPath(obj, path12) {
+  if (!path12)
     return obj;
-  return path10.reduce((acc, key) => acc?.[key], obj);
+  return path12.reduce((acc, key) => acc?.[key], obj);
 }
 function promiseAllObject(promisesObj) {
   const keys3 = Object.keys(promisesObj);
@@ -49055,11 +49484,11 @@ function explicitlyAborted(x2, startIndex = 0) {
   }
   return false;
 }
-function prefixIssues(path10, issues) {
+function prefixIssues(path12, issues) {
   return issues.map((iss) => {
     var _a4;
     (_a4 = iss).path ?? (_a4.path = []);
-    iss.path.unshift(path10);
+    iss.path.unshift(path12);
     return iss;
   });
 }
@@ -49206,16 +49635,16 @@ function flattenError(error52, mapper = (issue2) => issue2.message) {
 }
 function formatError(error52, mapper = (issue2) => issue2.message) {
   const fieldErrors = { _errors: [] };
-  const processError = (error53, path10 = []) => {
+  const processError = (error53, path12 = []) => {
     for (const issue2 of error53.issues) {
       if (issue2.code === "invalid_union" && issue2.errors.length) {
-        issue2.errors.map((issues) => processError({ issues }, [...path10, ...issue2.path]));
+        issue2.errors.map((issues) => processError({ issues }, [...path12, ...issue2.path]));
       } else if (issue2.code === "invalid_key") {
-        processError({ issues: issue2.issues }, [...path10, ...issue2.path]);
+        processError({ issues: issue2.issues }, [...path12, ...issue2.path]);
       } else if (issue2.code === "invalid_element") {
-        processError({ issues: issue2.issues }, [...path10, ...issue2.path]);
+        processError({ issues: issue2.issues }, [...path12, ...issue2.path]);
       } else {
-        const fullpath = [...path10, ...issue2.path];
+        const fullpath = [...path12, ...issue2.path];
         if (fullpath.length === 0) {
           fieldErrors._errors.push(mapper(issue2));
         } else {
@@ -49242,17 +49671,17 @@ function formatError(error52, mapper = (issue2) => issue2.message) {
 }
 function treeifyError(error52, mapper = (issue2) => issue2.message) {
   const result = { errors: [] };
-  const processError = (error53, path10 = []) => {
+  const processError = (error53, path12 = []) => {
     var _a4, _b2;
     for (const issue2 of error53.issues) {
       if (issue2.code === "invalid_union" && issue2.errors.length) {
-        issue2.errors.map((issues) => processError({ issues }, [...path10, ...issue2.path]));
+        issue2.errors.map((issues) => processError({ issues }, [...path12, ...issue2.path]));
       } else if (issue2.code === "invalid_key") {
-        processError({ issues: issue2.issues }, [...path10, ...issue2.path]);
+        processError({ issues: issue2.issues }, [...path12, ...issue2.path]);
       } else if (issue2.code === "invalid_element") {
-        processError({ issues: issue2.issues }, [...path10, ...issue2.path]);
+        processError({ issues: issue2.issues }, [...path12, ...issue2.path]);
       } else {
-        const fullpath = [...path10, ...issue2.path];
+        const fullpath = [...path12, ...issue2.path];
         if (fullpath.length === 0) {
           result.errors.push(mapper(issue2));
           continue;
@@ -49284,8 +49713,8 @@ function treeifyError(error52, mapper = (issue2) => issue2.message) {
 }
 function toDotPath(_path) {
   const segs = [];
-  const path10 = _path.map((seg) => typeof seg === "object" ? seg.key : seg);
-  for (const seg of path10) {
+  const path12 = _path.map((seg) => typeof seg === "object" ? seg.key : seg);
+  for (const seg of path12) {
     if (typeof seg === "number")
       segs.push(`[${seg}]`);
     else if (typeof seg === "symbol")
@@ -61977,13 +62406,13 @@ function resolveRef(ref2, ctx) {
   if (!ref2.startsWith("#")) {
     throw new Error("External $ref is not supported, only local refs (#/...) are allowed");
   }
-  const path10 = ref2.slice(1).split("/").filter(Boolean);
-  if (path10.length === 0) {
+  const path12 = ref2.slice(1).split("/").filter(Boolean);
+  if (path12.length === 0) {
     return ctx.rootSchema;
   }
   const defsKey = ctx.version === "draft-2020-12" ? "$defs" : "definitions";
-  if (path10[0] === defsKey) {
-    const key = path10[1];
+  if (path12[0] === defsKey) {
+    const key = path12[1];
     if (!key || !ctx.defs[key]) {
       throw new Error(`Reference not found: ${ref2}`);
     }
@@ -66666,9 +67095,9 @@ __export(expression_object_exports, {
   pick: () => pick3,
   values: () => values2
 });
-function getNestedValue(obj, path10) {
+function getNestedValue(obj, path12) {
   if (obj == null) return void 0;
-  const parts = path10.split(".");
+  const parts = path12.split(".");
   let value2 = obj;
   for (const part of parts) {
     if (value2 == null) return void 0;
@@ -66707,11 +67136,11 @@ function entries(obj) {
   }
   return Object.entries(obj);
 }
-function get(obj, path10, defaultValue) {
-  if (typeof path10 !== "string") {
+function get(obj, path12, defaultValue) {
+  if (typeof path12 !== "string") {
     throw new Error("get: path must be a string");
   }
-  const value2 = getNestedValue(obj, path10);
+  const value2 = getNestedValue(obj, path12);
   return value2 !== void 0 ? value2 : defaultValue;
 }
 function pick3(obj, fields) {
@@ -68594,17 +69023,17 @@ function readFromChanges(chain2) {
     if (first3.kind === "bracket-number" || first3.kind === "bracket-expr") {
       fail(first3.node, "changes is keyed by field name, not numeric index.");
     }
-    const path10 = [{ at: "key", key: first3.key }];
+    const path12 = [{ at: "key", key: first3.key }];
     for (const seg of segments.slice(1)) {
       if (seg.kind === "bracket-number") {
-        path10.push({ at: "index", index: seg.index });
+        path12.push({ at: "index", index: seg.index });
       } else if (seg.kind === "bracket-expr") {
-        path10.push({ at: "index", index: seg.expr });
+        path12.push({ at: "index", index: seg.expr });
       } else {
-        path10.push({ at: "key", key: seg.key });
+        path12.push({ at: "key", key: seg.key });
       }
     }
-    return { kind: "read", source: { from: "trigger_changes" }, path: path10 };
+    return { kind: "read", source: { from: "trigger_changes" }, path: path12 };
   });
 }
 var TRIGGER_RECORD_VIEWS = /* @__PURE__ */ new Map([
@@ -68622,17 +69051,17 @@ function readFromTrigger(chain2) {
     return view === "trigger_changes" ? readFromChanges(lowered) : readFromRecord(view, lowered);
   }
   return wrapOptionalGuards(chain2, (segments) => {
-    const path10 = [];
+    const path12 = [];
     for (const seg of segments) {
       if (seg.kind === "bracket-number") {
-        path10.push({ at: "index", index: seg.index });
+        path12.push({ at: "index", index: seg.index });
       } else if (seg.kind === "bracket-expr") {
-        path10.push({ at: "index", index: seg.expr });
+        path12.push({ at: "index", index: seg.expr });
       } else {
-        path10.push({ at: "key", key: seg.key });
+        path12.push({ at: "key", key: seg.key });
       }
     }
-    return { kind: "read", source: { from: "trigger" }, path: path10 };
+    return { kind: "read", source: { from: "trigger" }, path: path12 };
   });
 }
 function readFromRuntime(chain2) {
@@ -68654,17 +69083,17 @@ function readFromRuntime(chain2) {
     const parked = PARKED_RUNTIME_KEYS.get(key);
     if (parked) fail(first3.node, parked, parkedRuntimeKeyConstruct(key));
     const source = { from: "runtime", key };
-    const path10 = [];
+    const path12 = [];
     for (const seg of segments.slice(1)) {
       if (seg.kind === "bracket-number") {
-        path10.push({ at: "index", index: seg.index });
+        path12.push({ at: "index", index: seg.index });
       } else if (seg.kind === "bracket-expr") {
-        path10.push({ at: "index", index: seg.expr });
+        path12.push({ at: "index", index: seg.expr });
       } else {
-        path10.push({ at: "key", key: seg.key });
+        path12.push({ at: "key", key: seg.key });
       }
     }
-    return { kind: "read", source, path: path10 };
+    return { kind: "read", source, path: path12 };
   });
 }
 function readFromForeachItem(chain2) {
@@ -68700,17 +69129,17 @@ function readFromLexical(name2, chain2) {
 }
 function readFromStepOutput(stepId, chain2) {
   return wrapOptionalGuards(chain2, (segments) => {
-    const path10 = [];
+    const path12 = [];
     for (const seg of segments) {
       if (seg.kind === "bracket-number") {
-        path10.push({ at: "index", index: seg.index });
+        path12.push({ at: "index", index: seg.index });
       } else if (seg.kind === "bracket-expr") {
-        path10.push({ at: "index", index: seg.expr });
+        path12.push({ at: "index", index: seg.expr });
       } else {
-        path10.push({ at: "key", key: seg.key });
+        path12.push({ at: "key", key: seg.key });
       }
     }
-    return { kind: "read", source: { from: "step_output", step_id: stepId }, path: path10 };
+    return { kind: "read", source: { from: "step_output", step_id: stepId }, path: path12 };
   });
 }
 function classifyRecordPath(segs) {
@@ -70375,7 +70804,7 @@ function subsetIssues(bodySource, offset) {
   ];
 }
 async function loadProjectTypescript(projectDir) {
-  const requireFromProject = createRequire(path6.join(projectDir, "package.json"));
+  const requireFromProject = createRequire(path8.join(projectDir, "package.json"));
   let resolved;
   try {
     resolved = requireFromProject.resolve("typescript");
@@ -70388,12 +70817,12 @@ async function loadProjectTypescript(projectDir) {
   return mod2.default ?? mod2;
 }
 function pathToImportUrl(p) {
-  const resolved = path6.resolve(p);
+  const resolved = path8.resolve(p);
   const prefixed = resolved.startsWith("/") ? resolved : `/${resolved}`;
-  return `file://${prefixed.split(path6.sep).join("/")}`;
+  return `file://${prefixed.split(path8.sep).join("/")}`;
 }
 function checkOneWorkflowBody(tsApi, input) {
-  const wrapped = fs5.readFileSync(input.bodyPath, "utf-8");
+  const wrapped = fs7.readFileSync(input.bodyPath, "utf-8");
   const offset = bodyLineOffset(wrapped);
   const subset = subsetIssues(stripWorkflowHeader(wrapped), offset);
   if (subset) return subset;
@@ -70440,7 +70869,7 @@ function checkOneWorkflowBody(tsApi, input) {
 }
 function createCheckedSourceHost(tsApi, options, bodyPath, bodyText) {
   const base = tsApi.createCompilerHost(options, false);
-  const key = (fileName) => base.getCanonicalFileName(path6.resolve(fileName).replace(/\\/g, "/"));
+  const key = (fileName) => base.getCanonicalFileName(path8.resolve(fileName).replace(/\\/g, "/"));
   const bodyKey = key(bodyPath);
   return {
     ...base,
@@ -70457,6 +70886,1035 @@ function checkWorkflowBodies(tsApi, aliases) {
   }));
 }
 
+// ../shared/src/schemas/table_fields.ts
+var tableFieldTypeNameSchema = zod_default.enum([
+  "text",
+  "number",
+  "date",
+  "boolean",
+  "select",
+  "select_member",
+  "select_record_link",
+  "files",
+  "formula",
+  "rollup",
+  "lookup",
+  "button",
+  "autonumber"
+]);
+var tableFieldBaseSchema = zod_default.object({
+  key: zod_default.string().describe("Unique field key"),
+  name: zod_default.string().describe("Display name"),
+  description: zod_default.string().describe("Field description"),
+  confirm_before_update: zod_default.boolean().optional().describe("Show confirmation before AI updates")
+});
+var numberFormatSchema = zod_default.enum(["number", "currency", "percentage"]);
+var textFormatSchema = zod_default.enum(["text", "link", "markdown"]);
+var dateFormatSchema = zod_default.enum(["date", "datetime", "date_range", "datetime_range"]);
+var DEFAULT_VALUE_DESC = "Value pre-filled into a new record when none is supplied for this field. Applied on create only \u2014 existing records are never backfilled. null clears it.";
+var textDefaultValueSchema = zod_default.string().nullish().describe(DEFAULT_VALUE_DESC);
+var numberDefaultValueSchema = zod_default.number().nullish().describe(DEFAULT_VALUE_DESC);
+var booleanDefaultValueSchema = zod_default.boolean().nullish().describe(DEFAULT_VALUE_DESC);
+var dateDefaultValueSchema = zod_default.string().nullish().describe(`${DEFAULT_VALUE_DESC} A date string in the field's format.`);
+var selectDefaultValueSchema = zod_default.array(zod_default.string()).nullish().describe(`${DEFAULT_VALUE_DESC} Option key(s) \u2014 one for single-select.`);
+var memberDefaultValueSchema = zod_default.array(zod_default.string()).nullish().describe(`${DEFAULT_VALUE_DESC} Member ID(s) \u2014 one for single-select.`);
+var tableNumberFieldSchema = tableFieldBaseSchema.extend({
+  type: zod_default.literal("number"),
+  format: numberFormatSchema,
+  currency: zod_default.string().optional().describe("ISO 4217 code"),
+  default_value: numberDefaultValueSchema
+});
+var tableTextFieldSchema = tableFieldBaseSchema.extend({
+  type: zod_default.literal("text"),
+  unique: zod_default.boolean().optional().describe("Unique values required"),
+  // it's `optional` only for backward compatibility
+  format: textFormatSchema.optional(),
+  default_value: textDefaultValueSchema
+});
+var tableDateFieldSchema = tableFieldBaseSchema.extend({
+  type: zod_default.literal("date"),
+  format: dateFormatSchema.optional(),
+  timezone: zod_default.string().optional().describe("IANA timezone"),
+  derive_from: zod_default.enum(["created_at", "updated_at"]).optional().describe(
+    "Auto-populate from the row's system timestamp. `created_at` stamps once at insert time; `updated_at` re-stamps on every record edit. Derived fields are read-only \u2014 user-supplied values are silently ignored at write time, matching the formula/rollup/lookup pattern. Replaces the per-table after_create workflow pattern."
+  ),
+  // A derived date is read-only, so derive_from and default_value are mutually
+  // exclusive — enforced in validateFieldDefaultValue.
+  default_value: dateDefaultValueSchema
+});
+var tableBooleanFieldSchema = tableFieldBaseSchema.extend({
+  type: zod_default.literal("boolean"),
+  default_value: booleanDefaultValueSchema
+});
+var tableSelectFieldOptionSchema = zod_default.object({
+  key: zod_default.string(),
+  name: zod_default.string(),
+  color: optionColorSchema
+});
+var tableSelectFieldSchema = tableFieldBaseSchema.extend({
+  type: zod_default.literal("select"),
+  options: zod_default.array(tableSelectFieldOptionSchema),
+  multi: zod_default.boolean().optional().describe("Allow multiple selections"),
+  default_value: selectDefaultValueSchema
+});
+var tableSelectMemberFieldSchema = tableFieldBaseSchema.extend({
+  type: zod_default.literal("select_member"),
+  multi: zod_default.boolean().optional().describe("Allow multiple selections"),
+  default_value: memberDefaultValueSchema
+});
+var recordLinkItemSchema = zod_default.object({
+  id: zod_default.string(),
+  display: zod_default.string()
+});
+var selectRecordLinkValueSchema = zod_default.array(recordLinkItemSchema);
+var tableSelectRecordLinkFieldInputSchema = tableFieldBaseSchema.extend({
+  type: zod_default.literal("select_record_link"),
+  table_id: zod_default.string().describe("Linked table ID"),
+  display_field_keys: zod_default.array(zod_default.string()).optional().describe(
+    "Field keys of the linked table shown as the link's display text and as the columns in the record picker. If omitted, auto-selects the first text field."
+  ),
+  display_field_widths: zod_default.record(zod_default.string(), zod_default.number().int().positive()).optional().describe(
+    "Per-column widths in pixels for the record picker, keyed by linked-table field key. Missing keys fall back to the default column width."
+  ),
+  sync_both_ways: zod_default.boolean().optional().describe("Enable bidirectional link sync. If the target table has exactly one existing unpaired link field pointing back, pairs with it instead of creating a new field."),
+  paired_field_display_field_keys: zod_default.array(zod_default.string()).optional().describe("Display fields for paired link"),
+  paired_field_name: zod_default.string().optional().describe(
+    "Name for the auto-created paired field on the target table when sync_both_ways=true. If omitted, falls back to the source table's name (auto-uniquified with a numeric suffix on collision). Rejected as a conflict if a field with this name already exists on the target."
+  ),
+  cardinality: zod_default.enum(["one", "many"]).optional().describe(
+    "How many linked records this field can hold. Default 'many' (multi-select). 'one' = single-select; this side holds exactly one link to the partner. Requires sync_both_ways/paired_field_key. Setting 'one' on both paired sides is rejected."
+  )
+});
+var tableSelectRecordLinkFieldSchema = tableFieldBaseSchema.extend({
+  type: zod_default.literal("select_record_link").describe("Field type for linking to records in another table"),
+  table_id: zod_default.string().describe("ID of the target table that records can be linked to"),
+  display_field_keys: zod_default.array(zod_default.string()).optional().default([]).describe(
+    "Field keys of the linked table shown as the link's display text and as the columns in the record picker. If empty, the picker shows all fields."
+  ),
+  display_field_widths: zod_default.record(zod_default.string(), zod_default.number().int().positive()).optional().describe(
+    "Per-column widths in pixels for the record picker, keyed by linked-table field key. Missing keys fall back to the default column width."
+  ),
+  paired_field_key: zod_default.string().optional().describe(
+    "Key of the paired link field in the linked table. If set to a string, this indicates a bidirectional link where both tables can reference each other and data synchronizes in both directions. Both fields have paired_field_key pointing to each other. If set to null, explicitly disconnects the bidirectional link (clears paired_field_key on both sides). If undefined, no change is made to the existing paired_field_key."
+  ),
+  cardinality: zod_default.enum(["one", "many"]).optional().describe(
+    "How many linked records this field can hold. Default 'many' (multi-select). 'one' = single-select; this side holds exactly one link to the partner. Requires paired_field_key. Two paired sides cannot both be 'one'."
+  )
+});
+var tableRollupFieldSchema = tableFieldBaseSchema.extend({
+  type: zod_default.literal("rollup").describe(
+    "Field type for aggregating values from linked records (sum, avg, filled, earliest, etc.)"
+  ),
+  source_field_key: zod_default.string().describe("The field key of the select_record_link field to rollup from"),
+  aggregate_option: aggregateOptionSchema.describe(
+    "The field aggregation function to apply (e.g., sum, avg, filled, earliest)"
+  ),
+  filter: tableRecordFiltersGroupNodeSchema.optional().describe(
+    "Optional filter to apply to linked records before aggregation. Only records matching the filter conditions will be included in the rollup calculation."
+  ),
+  aggregate_field_type: tableFieldTypeNameSchema.optional().describe(
+    "What this rollup's CELL holds \u2014 'date' for earliest/latest, 'number' for every other operation (counts, sums, percentages). Derived from the operation, not from the aggregated field: a 'filled' count over a files column is a number. Server-derived at write time; ignored on input."
+  ),
+  aggregate_field_format: zod_default.string().optional().describe(
+    "The format of this rollup's own value. Operations that preserve the aggregated value's unit (sum/avg/median/min/max/range/earliest/latest) inherit the target field's format; counting operations are 'number', percentages 'percentage'. Server-derived at write time; ignored on input."
+  ),
+  aggregate_field_currency: zod_default.string().optional().describe(
+    "The currency code of this rollup's own value (e.g. 'USD', 'VND'), inherited from the aggregated field only when the operation preserves its unit \u2014 a COUNT of a currency column carries no currency. Server-derived at write time; ignored on input."
+  )
+});
+var lookupOrderBySchema = zod_default.object({
+  field_key: zod_default.string(),
+  direction: zod_default.enum(["asc", "desc"])
+});
+var tableLookupFieldSchema = tableFieldBaseSchema.extend({
+  type: zod_default.literal("lookup").describe("Field type for displaying values from fields in linked records"),
+  source_field_key: zod_default.string().describe("The field key of the select_record_link field to lookup from"),
+  lookup_field_key: zod_default.string().describe("The field key from the linked records to display"),
+  lookup_field_type: tableFieldTypeNameSchema.optional().describe(
+    "The type of the target lookup field (e.g. 'text', 'number', 'date'). Resolved from the linked table's field definition at read time."
+  ),
+  lookup_field_format: zod_default.string().optional().describe(
+    "The format of the target lookup field (e.g. 'currency', 'percentage', 'datetime'). Resolved from the linked table's field definition at read time."
+  ),
+  lookup_field_currency: zod_default.string().optional().describe(
+    "The currency code of the target lookup field (e.g. 'USD', 'VND'). Resolved from the linked table's field definition at read time."
+  ),
+  lookup_field_options: zod_default.array(zod_default.object({ key: zod_default.string(), name: zod_default.string(), color: zod_default.string().optional() })).optional().describe(
+    "Options for select-type lookup fields. Synced from the source select field's options."
+  ),
+  order_by: lookupOrderBySchema.optional().describe(
+    "When set, sort the linked records by this field on the linked table and return ONLY the picked field from the single extreme record (desc=latest, asc=earliest), as a one-element array. Omit to return every linked record's value as an array. field_key must be a field on the linked table."
+  )
+});
+var tableFilesFieldSchema = tableFieldBaseSchema.extend({
+  type: zod_default.literal("files").describe("Field type for file attachments (images, PDFs, documents)")
+});
+var formulaInputSchema = zod_default.object({
+  expression: zod_default.string().describe(
+    "JavaScript expression. Uses {Field Name} for field references."
+  ),
+  format: zod_default.enum(["number", "currency", "percentage", "link"]).optional().describe(
+    "Display format. 'number' / 'currency' / 'percentage' for numeric results; 'link' for text-output formulas that return a URL \u2014 renders the result as a clickable link."
+  ),
+  currency: zod_default.string().optional().describe("ISO 4217 currency code, e.g. USD, VND, EUR")
+});
+var formulaSchema = formulaInputSchema.extend({
+  output_type: zod_default.enum(["number", "text", "date", "datetime", "boolean"]).optional().describe("Output type of the formula. Inferred by the backend from the expression \u2014 read-only on input. `datetime` when the result carries a time of day (references a datetime field or a time-bearing helper)."),
+  volatile: zod_default.boolean().optional().describe("Whether the formula's result depends on `now()` or other non-deterministic helpers. Inferred by the backend \u2014 read-only on input.")
+});
+var tableFormulaFieldSchema = tableFieldBaseSchema.extend({
+  type: zod_default.literal("formula").describe("Field type for calculated values based on expressions"),
+  formula: formulaSchema.describe("Formula configuration and expression")
+});
+var workflowMetadataSchema = zod_default.object({
+  table_ids: zod_default.array(zod_default.string()).describe("IDs of the tables this workflow affects"),
+  staged_for_app_id: zod_default.string().optional().describe(
+    "Present while the row is a draft-staged fork for this app; cleared when the app publishes the binding. Marked rows left unbound are archived at publish/discard."
+  )
+});
+var workflowSchema = zod_default.object({
+  id: zod_default.string().describe("Unique identifier for the workflow"),
+  name: zod_default.string().describe("Display name of the workflow"),
+  description: zod_default.string().describe("Human-readable description of what this workflow does"),
+  steps: zod_default.unknown().describe(
+    "AST-valued step tree (tool calls, conditionals, loops)."
+  ),
+  metadata: workflowMetadataSchema.nullable().optional().describe("Metadata for the workflow"),
+  current_version: zod_default.number().int().describe("Current version number"),
+  enabled: zod_default.boolean().describe("Whether this workflow is active"),
+  workspace_id: zod_default.string().describe("ID of the workspace this workflow belongs to"),
+  created_at: zod_default.string().describe("Timestamp when workflow was created"),
+  updated_at: zod_default.string().describe("Timestamp of last update")
+});
+var tableButtonFieldSchema = tableFieldBaseSchema.extend({
+  type: zod_default.literal("button").describe("Field type for action buttons"),
+  text: zod_default.string().describe("Button label text displayed to users"),
+  workflow_id: zod_default.string().nullable().optional().describe(
+    "ID of the workflow the button presses trigger. Null means no action configured \u2014 pressing the button is a no-op. Button authoring is retired: existing bindings keep running, but nothing sets a new one."
+  )
+});
+var tableAutonumberFieldSchema = tableFieldBaseSchema.extend({
+  type: zod_default.literal("autonumber"),
+  prefix: zod_default.string().optional().describe(
+    "Literal prefix prepended to every display value (e.g. 'KH-' \u2192 'KH-001'). Ignored when `template` is set."
+  ),
+  padding: zod_default.number().int().min(1).max(20).optional().describe(
+    "Zero-pad the integer to this width. Default 1 (no padding). 3 \u2192 '001', '012', '123', '1234' (overflow uses the actual width). Ignored when `template` is set."
+  ),
+  template: zod_default.string().optional().describe(
+    "Format template with placeholder tokens evaluated at insert time. Tokens: {N} (raw integer), {N:W} (zero-padded to width W, e.g. {N:3} \u2192 001), {YEAR} (4-digit year), {YEAR:2} (2-digit year), {MONTH} (2-digit month), {DAY} (2-digit day). Date tokens use the workspace timezone. Example: 'HM-{YEAR}-{N:3}' yields 'HM-2026-001'. Stored as the composed string; subsequent template edits do NOT re-format existing rows (date tokens would lose the original creation date)."
+  )
+});
+var tableFieldSchema = zod_default.discriminatedUnion("type", [
+  tableNumberFieldSchema,
+  tableTextFieldSchema,
+  tableDateFieldSchema,
+  tableBooleanFieldSchema,
+  tableSelectFieldSchema,
+  tableSelectMemberFieldSchema,
+  tableSelectRecordLinkFieldSchema,
+  tableRollupFieldSchema,
+  tableLookupFieldSchema,
+  tableFilesFieldSchema,
+  tableFormulaFieldSchema,
+  tableButtonFieldSchema,
+  tableAutonumberFieldSchema
+]);
+var tableFieldInputSchema = zod_default.discriminatedUnion("type", [
+  tableNumberFieldSchema,
+  tableTextFieldSchema,
+  tableDateFieldSchema,
+  tableBooleanFieldSchema,
+  tableSelectFieldSchema,
+  tableSelectMemberFieldSchema,
+  tableSelectRecordLinkFieldInputSchema,
+  tableRollupFieldSchema,
+  tableLookupFieldSchema,
+  tableFilesFieldSchema,
+  tableFormulaFieldSchema,
+  tableButtonFieldSchema,
+  tableAutonumberFieldSchema
+]);
+var tableFieldsSchema = zod_default.array(tableFieldSchema);
+var tableFieldCreateBaseSchema = zod_default.object({
+  name: zod_default.string().describe("Display name"),
+  description: zod_default.string().describe("Field description"),
+  confirm_before_update: zod_default.boolean().optional().describe("Show confirmation before AI updates")
+});
+var tableSelectFieldOptionCreateSchema = zod_default.object({
+  name: zod_default.string(),
+  color: optionColorSchema
+});
+var tableFieldTypeConfigSchema = zod_default.discriminatedUnion("type", [
+  zod_default.object({
+    type: zod_default.literal("number"),
+    format: numberFormatSchema.default("number"),
+    currency: zod_default.string().optional().describe("ISO 4217 code"),
+    default_value: numberDefaultValueSchema
+  }),
+  zod_default.object({
+    type: zod_default.literal("text"),
+    unique: zod_default.boolean().optional().describe("Unique values required"),
+    format: textFormatSchema.default("text"),
+    default_value: textDefaultValueSchema
+  }),
+  zod_default.object({
+    type: zod_default.literal("date"),
+    format: dateFormatSchema.optional(),
+    timezone: zod_default.string().optional().describe("IANA timezone"),
+    derive_from: zod_default.enum(["created_at", "updated_at"]).nullable().optional().describe("Auto-populate from row system timestamp; field becomes read-only. Only valid for date/datetime formats. Pass null to clear and revert to a manual date field."),
+    default_value: dateDefaultValueSchema
+  }),
+  zod_default.object({
+    type: zod_default.literal("boolean"),
+    default_value: booleanDefaultValueSchema
+  }),
+  zod_default.object({
+    type: zod_default.literal("select"),
+    options: zod_default.array(tableSelectFieldOptionCreateSchema),
+    multi: zod_default.boolean().optional().describe("Allow multiple selections"),
+    default_value: selectDefaultValueSchema
+  }),
+  zod_default.object({
+    type: zod_default.literal("select_member"),
+    multi: zod_default.boolean().optional().describe("Allow multiple selections"),
+    default_value: memberDefaultValueSchema
+  }),
+  zod_default.object({
+    type: zod_default.literal("select_record_link"),
+    table_id: zod_default.string().describe("Linked table ID"),
+    display_field_keys: zod_default.array(zod_default.string()).optional().describe(
+      "Field keys of the linked table shown as the link's display text and as the columns in the record picker. If omitted, auto-selects the first text field."
+    ),
+    display_field_widths: zod_default.record(zod_default.string(), zod_default.number().int().positive()).optional().describe(
+      "Per-column widths in pixels for the record picker, keyed by linked-table field key. Missing keys fall back to the default column width."
+    ),
+    sync_both_ways: zod_default.boolean().optional().describe("Enable bidirectional link sync. If the target table has exactly one existing unpaired link field pointing back, pairs with it instead of creating a new field."),
+    paired_field_display_field_keys: zod_default.array(zod_default.string()).optional().describe("Paired field display"),
+    paired_field_name: zod_default.string().optional().describe(
+      "Name for the auto-created paired field on the target table when sync_both_ways=true. Omit to default to the source table's name (auto-uniquified on collision). If supplied and a field with the same name already exists on the target, the create is rejected."
+    ),
+    cardinality: zod_default.enum(["one", "many"]).optional().describe(
+      "How many linked records this field can hold. Default 'many' (multi-select). 'one' = single-select; this side holds exactly one link to the partner. Requires sync_both_ways. Two paired sides cannot both be 'one'."
+    )
+  }),
+  zod_default.object({
+    type: zod_default.literal("rollup"),
+    source_field_key: zod_default.string().describe("Source link field key"),
+    aggregate_option: aggregateOptionSchema,
+    filter: tableRecordFiltersGroupNodeSchema.optional().describe("Filter linked records")
+  }),
+  zod_default.object({
+    type: zod_default.literal("lookup"),
+    source_field_key: zod_default.string().describe("Source link field key"),
+    lookup_field_key: zod_default.string().describe("Field to display"),
+    order_by: lookupOrderBySchema.optional().describe("Ordered lookup: pick only the extreme linked record's field (desc=latest, asc=earliest)")
+  }),
+  zod_default.object({
+    type: zod_default.literal("files")
+  }),
+  zod_default.object({
+    type: zod_default.literal("formula"),
+    formula: formulaInputSchema
+  }),
+  // `button` is deliberately absent: button fields are legacy — this union
+  // shapes CREATE input only, and new buttons can no longer be created
+  // (see LEGACY_FIELD_TYPES). Stored button fields still parse via the
+  // stored-field union above, and update paths keep accepting text edits.
+  zod_default.object({
+    type: zod_default.literal("autonumber"),
+    prefix: zod_default.string().optional().describe("Literal prefix prepended to display (ignored when template is set)"),
+    padding: zod_default.number().int().min(1).max(20).optional().describe("Zero-pad the integer to this width (default 1) (ignored when template is set)"),
+    template: zod_default.string().optional().describe(
+      "Format template \u2014 tokens evaluate at insert time: {N}, {N:W} (padded), {YEAR}, {YEAR:2}, {MONTH}, {DAY}. Date tokens use workspace timezone. Example: 'HM-{YEAR}-{N:3}' \u2192 'HM-2026-001'."
+    )
+  })
+]);
+var tableFieldCreateInputSchema = zod_default.intersection(
+  tableFieldCreateBaseSchema,
+  tableFieldTypeConfigSchema
+);
+var fieldVisibilitySchema = zod_default.enum(["visible", "hidden"]).describe(
+  "Field visibility state: 'visible' = shown to everyone, 'hidden' = not shown by default but members can toggle"
+);
+
+// ../shared/src/schemas/field_config.ts
+var fieldConfigEntrySchema = zod_default.object({
+  key: zod_default.string().min(1).describe("Field key"),
+  visibility: fieldVisibilitySchema,
+  width: zod_default.number().optional()
+});
+
+// ../shared/src/schemas/iam.ts
+var jsonSchemaSchema = zod_default.string();
+var organizationSchema = zod_default.object({
+  id: zod_default.string().describe("Unique identifier for the organization"),
+  name: zod_default.string().describe("Display name of the organization"),
+  slug: zod_default.string().nullable().describe("Slug for the organization")
+});
+var memberSchema = zod_default.object({
+  member_id: zod_default.string().describe("Unique identifier for the member"),
+  organization_id: zod_default.string().describe("Organization ID the member belongs to"),
+  name: zod_default.string().describe("Display name of the member"),
+  email_address: zod_default.string().describe("Email address of the member"),
+  role: zod_default.enum(["owner", "admin", "member"]).describe("Organization role"),
+  image: zod_default.string().nullable().optional().describe("URL to the member's profile picture"),
+  account_type: zod_default.enum(["self_managed", "admin_managed"]).describe(
+    "How the account is credentialed. admin_managed means an admin chose the sign-in identifier and set the password, so the address has no inbox \u2014 nothing may be emailed to it until the member claims a real one."
+  )
+});
+var pendingInvitationSchema = zod_default.object({
+  invitation_id: zod_default.string().describe("Unique identifier for the pending invitation"),
+  organization_id: zod_default.string().describe("Organization the invitee will join on accept"),
+  email: zod_default.string().describe("Email the invitation was sent to"),
+  name: zod_default.string().nullable().describe("Admin-supplied display name (carried onto member.name on accept; invitee can override at accept time)"),
+  role: zod_default.enum(["owner", "admin", "member"]).describe("Role the invitee will receive on accept"),
+  expires_at: zod_default.string().describe("ISO timestamp when the invitation expires")
+});
+var workspaceSchema = zod_default.object({
+  id: zod_default.string().describe("Unique identifier for the workspace"),
+  name: zod_default.string().describe("Display name of the workspace"),
+  default_currency: zod_default.string().describe("Default currency code for the workspace"),
+  timezone: zod_default.string().describe("IANA timezone name (e.g., 'America/New_York', 'Asia/Tokyo')"),
+  organization_id: zod_default.string().describe("Organization ID this workspace belongs to"),
+  created_at: zod_default.string().describe("Timestamp when workspace was created")
+});
+var memberGroupSchema = zod_default.object({
+  id: zod_default.string().describe("Unique identifier for the member group"),
+  name: zod_default.string().describe("Display name of the group"),
+  description: zod_default.string().optional().describe("Optional description of the group's purpose"),
+  member_ids: zod_default.array(zod_default.string()).describe("Array of member IDs in this group"),
+  invitation_ids: zod_default.array(zod_default.string()).describe("Array of pending invitation IDs pre-granted membership; migrated to member_ids on accept"),
+  organization_id: zod_default.string().describe("ID of the organization this group belongs to"),
+  created_at: zod_default.string().describe("Timestamp when group was created"),
+  created_by: zod_default.string().describe("Member ID of the user who created this group")
+});
+var principalGroupSchema = zod_default.object({
+  id: zod_default.string().describe("Unique identifier for the member group"),
+  name: zod_default.string().describe("Display name of the group"),
+  description: zod_default.string().optional().describe("Optional description of the group's purpose"),
+  member_count: zod_default.number().int().describe("Number of accepted members in the group"),
+  invitation_count: zod_default.number().int().describe("Number of pending invitations pre-granted membership")
+});
+var PUBLIC_PRINCIPAL_ID = "public";
+var principalSchema = zod_default.discriminatedUnion("type", [
+  zod_default.object({
+    type: zod_default.literal("member").describe("Principal type: individual member"),
+    id: zod_default.string().describe("Member ID")
+  }),
+  zod_default.object({
+    type: zod_default.literal("member_group").describe("Principal type: group of members"),
+    id: zod_default.string().describe("Member group ID")
+  }),
+  zod_default.object({
+    type: zod_default.literal("organization").describe("Principal type: all members in organization"),
+    id: zod_default.string().describe("Organization ID")
+  }),
+  zod_default.object({
+    type: zod_default.literal("public").describe("Principal type: anyone, including unauthenticated visitors"),
+    id: zod_default.literal(PUBLIC_PRINCIPAL_ID).describe("Always the `public` sentinel \u2014 no entity")
+  }),
+  // Pending invitation as principal: lets admins pre-grant group membership and
+  // resource access before the invitee accepts. Never resolved as a Subject —
+  // a pending invitee cannot authenticate, so these bindings stay dormant until
+  // accept-time migration rewrites them to type:"member".
+  zod_default.object({
+    type: zod_default.literal("invitation").describe("Principal type: pending invitation (not yet accepted)"),
+    id: zod_default.string().describe("Invitation ID")
+  })
+]);
+var subjectSchema = zod_default.discriminatedUnion("type", [
+  zod_default.object({
+    type: zod_default.literal("member").describe("Subject type: authenticated member"),
+    id: zod_default.string().describe("Member ID")
+  }),
+  zod_default.object({
+    type: zod_default.literal("public").describe("Subject type: unauthenticated visitor")
+  })
+]);
+var resourceTypeSchema = zod_default.enum(["table", "table_view", "app", "automation", "skill", "document_template", "instruction", "knowledge_doc"]);
+var resourceRoleBindingSchema = zod_default.object({
+  id: zod_default.string().describe("Unique identifier for the role binding"),
+  principal: principalSchema.describe(
+    "Who this role binding applies to (member, group, or organization)"
+  ),
+  resource_type: resourceTypeSchema.describe("Type of resource being accessed"),
+  resource_id: zod_default.string().describe("ID of the specific resource"),
+  role: zod_default.string().describe("Role name (e.g., 'viewer', 'editor', 'manager', 'user')")
+});
+
+// ../shared/src/schemas/table_records.ts
+var tableWorkflowEventSchema = zod_default.enum([
+  "before_create",
+  "after_create",
+  "before_update",
+  "after_update",
+  "before_delete",
+  "after_delete"
+]);
+var tableWorkflowSchema = zod_default.object({
+  id: zod_default.string().describe("Unique table-workflow binding ID (tbw_ prefix)"),
+  name: zod_default.string().describe("Human-readable name"),
+  description: zod_default.string().describe("Description of what this workflow does"),
+  enabled: zod_default.boolean().describe("Whether this workflow is active"),
+  event: tableWorkflowEventSchema.describe(
+    "Lifecycle event that fires this workflow. before_* runs synchronously and may reject the mutation; after_* runs after commit and does not block."
+  ),
+  workflow_id: zod_default.string().describe(
+    "ID of the workflow row that owns this binding's steps. The workflow's steps_v2 is the source of truth for the AST."
+  ),
+  // Recursive v2 expression AST. Lazy schema would crash the OpenAPI walker;
+  // runtime is `unknown` and the casted Zod type preserves the compile-time
+  // signature for callers. Write paths re-parse with the strict schema before
+  // storage.
+  if: zod_default.unknown().nullable().optional().describe(
+    "Optional pre-execution gate. Evaluated against the trigger context (record / prev_record / changes / runtime); the workflow fires only when truthy. Skip gating means the workflow always fires."
+  ),
+  created_at: zod_default.string().describe("When the binding was created"),
+  updated_at: zod_default.string().describe("When the binding was last modified"),
+  archived_at: zod_default.string().nullable().optional().describe(
+    "Set when the binding was removed (soft-delete). An archived binding never fires and is hidden from active listings, but is restorable; null/absent = active."
+  )
+});
+var tableWorkflowMessageSchema = zod_default.object({
+  table_workflow_id: zod_default.string().describe("tbw_* binding that emitted the message."),
+  workflow_name: zod_default.string().describe("Human name of the workflow at execution time."),
+  event: tableWorkflowEventSchema.describe(
+    "Lifecycle event that produced the message. Only before_* events can surface here."
+  ),
+  record_id: zod_default.string().describe(
+    "Record that triggered the workflow. Lets the UI scope the message to a specific row in bulk responses."
+  ),
+  message: zod_default.string().describe("Author-provided text from the workflow's return.message.")
+});
+var tableSchema = zod_default.object({
+  id: zod_default.string().describe("Unique identifier for the table"),
+  workspace_id: zod_default.string().describe("ID of the workspace this table belongs to"),
+  name: zod_default.string().describe("Display name of the table"),
+  description: zod_default.string().describe("Description of the table's purpose"),
+  position: zod_default.number().int().optional().nullable().describe("Display ordering index for the table. Lower numbers are shown first. "),
+  fields: tableFieldsSchema.describe("Array of field definitions for this table"),
+  workflows: zod_default.array(tableWorkflowSchema).optional().describe(
+    "Workflows attached to this table that fire around record mutations. before_* run synchronously and may reject; after_* run after commit and do not block."
+  ),
+  private_filters: tableRecordFiltersGroupNodeSchema.nullable().optional().describe("Row-level private filters AND'd to every query as a security boundary (admin bypass)"),
+  colors: tableRecordColorsSchema.nullable().optional().describe("Color rules for styling records based on filter conditions"),
+  approvers: zod_default.array(principalSchema).nullable().optional().describe(
+    "Principals (members, groups, or the organization) who review locked-record change requests on this table. Null/empty = organization admins review. The requester never reviews their own request."
+  ),
+  created_at: zod_default.string().describe("Timestamp when table was created")
+});
+var recordDataTemplateSchema = zod_default.object({
+  id: zod_default.string().describe("Unique identifier for the record data template"),
+  name: zod_default.string().describe("Display name of the record data template"),
+  description: zod_default.string().describe("Description of the record data template"),
+  table_id: zod_default.string().describe("ID of the table this record template belongs to"),
+  data: zod_default.record(zod_default.string(), zod_default.unknown()).describe("The data of the record template. The key is the Field key.")
+});
+var tableRecordSchema = zod_default.object({
+  id: zod_default.string().describe("Unique identifier for the record"),
+  table_id: zod_default.string().describe("ID of the table this record belongs to"),
+  workspace_id: zod_default.string().describe("ID of the workspace this record belongs to"),
+  data: zod_default.record(zod_default.string(), zod_default.unknown()).describe("The data of the record. The key is the Field key."),
+  locked: zod_default.boolean().optional().describe("Whether the entire record is locked from editing"),
+  draft: zod_default.boolean().optional().describe("Whether the record is an unsubmitted draft \u2014 UI-only in-progress state, not yet a real row. Row-visibility scoping is enforced at submit, not while a draft is being filled in."),
+  updated_at: zod_default.string().describe("Timestamp of last update"),
+  created_at: zod_default.string().describe("Timestamp when record was created")
+});
+var viewSummaryEntrySchema = zod_default.object({
+  operation: zod_default.string().describe("Operation to perform on the field"),
+  field_key: zod_default.string().describe("Field key to display in the summary row")
+});
+var viewSummarySchema = zod_default.record(zod_default.string(), viewSummaryEntrySchema.nullable().optional()).nullable().optional().describe("Map of field keys to summary operations.");
+var visibleToEntrySchema = zod_default.object({
+  type: zod_default.enum(["member", "group"]).describe("Principal kind that may see the view: an individual member or a member group"),
+  id: zod_default.string().describe("Member ID (type=member) or member-group ID (type=group)")
+});
+var visibleToSchema = zod_default.array(visibleToEntrySchema).nullable();
+var tableViewSchema = zod_default.object({
+  id: zod_default.string().describe("Unique identifier for the view"),
+  table_id: zod_default.string().describe("ID of the table this view displays"),
+  workspace_id: zod_default.string().describe("ID of the workspace this view belongs to"),
+  name: zod_default.string().describe("Display name of the view"),
+  description: zod_default.string().describe("Description of the view's purpose"),
+  visible_to: visibleToSchema.optional().describe(
+    "Sidebar declutter list (NOT access control). null/absent = every member with access to the parent table sees this view; a non-empty list of members/groups restricts who sees it in the explorer. [] is normalized to null on write."
+  ),
+  position: zod_default.number().int().nullable().describe(
+    "Display ordering index for the view. Lower numbers are shown first. Use incremental values with gaps (100, 200, 300) instead of consecutive numbers (1, 2, 3) to enable efficient reordering without updating multiple records. Example: To insert between 100 and 200, use 150."
+  ),
+  frozen_columns: zod_default.number().int().nullable().optional().describe("Number of columns to freeze. Frozen columns are not scrollable."),
+  summary: viewSummarySchema,
+  default_record_data_template_id: zod_default.string().nullable().optional().describe("ID of the record template to use as the default record initial data"),
+  field_config: zod_default.array(fieldConfigEntrySchema).describe(
+    "Ordered array of field config entries. Order = display order, visibility = per-entry. Fields not listed are hidden."
+  ),
+  sort: tableRecordSortSchema.nullable().describe("Sorting configuration for records in this view"),
+  filters: tableRecordFiltersGroupNodeSchema.nullable().describe("Filter conditions applied to records in this view"),
+  created_at: zod_default.string().describe("Timestamp when view was created")
+});
+var tableWithViewsSchema = tableSchema.extend({
+  views: zod_default.array(tableViewSchema).describe("Array of views for this table")
+});
+var explorerViewSchema = zod_default.object({
+  id: zod_default.string(),
+  name: zod_default.string(),
+  owner_member_id: zod_default.string(),
+  // Per-view sidebar declutter list (NOT access control). null = every member
+  // with table access sees this view; a non-empty member/group list restricts
+  // it. Surfaced here so the table share dialog can render and edit each view's
+  // audience without a second round-trip.
+  visible_to: visibleToSchema.optional(),
+  // Per-requesting-member sidebar preference: true if this member has hidden
+  // the view. Hiding is UX-only — it never affects access or other members.
+  hidden: zod_default.boolean()
+});
+var explorerTableSchema = zod_default.object({
+  id: zod_default.string(),
+  name: zod_default.string(),
+  position: zod_default.number().int().nullable().optional(),
+  views: zod_default.array(explorerViewSchema),
+  owner_member_id: zod_default.string(),
+  // Active package installations whose binding includes this table — the
+  // sidebar marks these so members see the structure is app-managed before
+  // they try to change it. Absent for unbound tables.
+  package_apps: zod_default.array(zod_default.object({ id: zod_default.string(), name: zod_default.string() })).optional()
+});
+var documentTemplateTypeSchema = zod_default.enum(["html", "pdf-form", "excel", "word", "email"]).describe("Template type: 'html' for HTML templates, 'pdf-form' for fillable PDF forms, 'excel' for Excel templates, 'word' for Word templates, 'email' for email HTML templates");
+var documentTemplateSchema = zod_default.object({
+  id: zod_default.string().describe("Unique identifier for the document template"),
+  workspace_id: zod_default.string().describe("ID of the workspace this template belongs to"),
+  name: zod_default.string().describe("Display name of the template"),
+  type: documentTemplateTypeSchema,
+  template: zod_default.string().describe("Template content with variable placeholders (e.g., {{customer_name}})"),
+  format: zod_default.string().describe("Supported document formats.").optional(),
+  orientation: zod_default.enum(["portrait", "landscape"]).describe("Page orientation for PDF generation").optional(),
+  variables: zod_default.record(zod_default.string(), zod_default.unknown()).describe("Data to pass to the template."),
+  current_version: zod_default.number().describe("Current version number of the template"),
+  created_at: zod_default.string().describe("Timestamp when template was created"),
+  template_url: zod_default.string().nullable().describe("Signed URL to download the template file (pdf-form/excel only)")
+});
+
+// ../shared/src/schemas/packages.ts
+var contractAliasSchema = zod_default.string().regex(
+  /^[a-z][a-z0-9_]*$/,
+  "alias must be a lowercase slug: start with a letter, then letters/digits/underscores"
+);
+var runtimeAliasSchema = zod_default.string().min(1).max(200);
+var contractFieldBaseSchema = zod_default.object({
+  alias: contractAliasSchema.describe("Stable local alias, unique within the entity"),
+  // No braces: scaffold translates formula expressions from `{alias}` to the
+  // platform's `{Field Label}` reference form, so a brace inside a label would
+  // corrupt every formula that references the field.
+  label: zod_default.string().min(1).regex(/^[^{}]*$/, "field labels cannot contain { or }").describe("Display label used as the field name at scaffold time"),
+  description: zod_default.string().optional(),
+  required: zod_default.boolean().optional().describe(
+    "Advisory only: marks the field required for app-form/workflow UX. The table data model has no required constraint, so scaffold does NOT enforce it at the schema level \u2014 validation lives in the app/workflow layer."
+  )
+});
+var contractSelectOptionSchema = zod_default.object({
+  alias: contractAliasSchema.describe("Stable local alias, unique within the field"),
+  label: zod_default.string().min(1).describe("Display label for the option"),
+  color: optionColorSchema
+});
+var contractAutonumberConfigSchema = tableAutonumberFieldSchema.pick({
+  prefix: true,
+  padding: true,
+  template: true
+});
+var contractTextFieldSchema = contractFieldBaseSchema.extend({
+  type: zod_default.literal("text"),
+  unique: zod_default.boolean().optional().describe("Unique values required"),
+  format: textFormatSchema.optional()
+});
+var contractNumberFieldSchema = contractFieldBaseSchema.extend({
+  type: zod_default.literal("number"),
+  format: numberFormatSchema.optional(),
+  currency: zod_default.string().optional().describe("ISO 4217 code")
+});
+var contractDateFieldSchema = contractFieldBaseSchema.extend({
+  type: zod_default.literal("date"),
+  format: dateFormatSchema.optional(),
+  timezone: zod_default.string().optional().describe("IANA timezone"),
+  derive_from: zod_default.enum(["created_at", "updated_at"]).optional().describe("Auto-populate from the row's system timestamp; the field becomes read-only.")
+});
+var contractBooleanFieldSchema = contractFieldBaseSchema.extend({
+  type: zod_default.literal("boolean")
+});
+var contractSelectFieldSchema = contractFieldBaseSchema.extend({
+  type: zod_default.literal("select"),
+  options: zod_default.array(contractSelectOptionSchema).min(1),
+  multi: zod_default.boolean().optional().describe("Allow multiple selections")
+});
+var contractSelectMemberFieldSchema = contractFieldBaseSchema.extend({
+  type: zod_default.literal("select_member"),
+  multi: zod_default.boolean().optional().describe("Allow multiple selections")
+});
+var contractSelectRecordLinkFieldSchema = contractFieldBaseSchema.extend({
+  type: zod_default.literal("select_record_link"),
+  target_entity: contractAliasSchema.describe("Alias of the entity this field links to"),
+  sync_both_ways: zod_default.boolean().optional().describe("Create a paired link field on the target entity for bidirectional sync"),
+  paired_field_alias: contractAliasSchema.optional().describe(
+    "The pair edge of a bidirectional link: the field alias ON THE TARGET ENTITY that is this link's sync partner. Both sides of a pair carry it, each naming the other. Scaffold creates whichever side it reaches first WITH the pairing (the platform auto-creates the partner) and binds the partner alias to the auto-created field \u2014 without this edge the two contract fields would be created independently and collide with the auto-created partner."
+  ),
+  cardinality: zod_default.enum(["one", "many"]).optional().describe("How many linked records this field holds. Default 'many'."),
+  display_field_aliases: zod_default.array(contractAliasSchema).optional().describe("Field aliases on the target entity shown as the link's display text / picker columns")
+});
+var contractFilesFieldSchema = contractFieldBaseSchema.extend({
+  type: zod_default.literal("files")
+});
+var contractFormulaFieldSchema = contractFieldBaseSchema.extend({
+  type: zod_default.literal("formula"),
+  formula: formulaInputSchema.describe(
+    "Formula config. The expression references other fields on the SAME entity by alias in braces, e.g. `{quantity} * {unit_price}`."
+  )
+});
+var contractRollupFieldSchema = contractFieldBaseSchema.extend({
+  type: zod_default.literal("rollup"),
+  source_field_alias: contractAliasSchema.describe(
+    "Alias of a select_record_link field on this entity to roll up from"
+  ),
+  aggregate_option: aggregateOptionSchema.describe(
+    "Aggregation operation. Its `field_key` names a field alias on the linked entity."
+  )
+});
+var contractLookupFieldSchema = contractFieldBaseSchema.extend({
+  type: zod_default.literal("lookup"),
+  source_field_alias: contractAliasSchema.describe(
+    "Alias of a select_record_link field on this entity to look up through"
+  ),
+  lookup_field_alias: contractAliasSchema.describe(
+    "Alias of the field on the linked entity to display"
+  ),
+  order_by: lookupOrderBySchema.optional().describe("Ordered lookup. Its `field_key` names a field alias on the linked entity.")
+});
+var contractAutonumberFieldSchema = contractFieldBaseSchema.extend({
+  type: zod_default.literal("autonumber"),
+  ...contractAutonumberConfigSchema.shape
+});
+var contractFieldSchema = zod_default.discriminatedUnion("type", [
+  contractTextFieldSchema,
+  contractNumberFieldSchema,
+  contractDateFieldSchema,
+  contractBooleanFieldSchema,
+  contractSelectFieldSchema,
+  contractSelectMemberFieldSchema,
+  contractSelectRecordLinkFieldSchema,
+  contractFilesFieldSchema,
+  contractFormulaFieldSchema,
+  contractRollupFieldSchema,
+  contractLookupFieldSchema,
+  contractAutonumberFieldSchema
+]);
+var contractEntitySchema = zod_default.object({
+  alias: contractAliasSchema.describe("Stable entity alias, unique within the contract"),
+  label: zod_default.string().min(1).describe("Display label used as the table name at scaffold time"),
+  description: zod_default.string().optional(),
+  fields: zod_default.array(contractFieldSchema).min(1)
+});
+var contractRoleSchema = zod_default.object({
+  alias: contractAliasSchema.describe("Stable role alias, bound to a workspace group at install"),
+  label: zod_default.string().min(1)
+});
+var contractTemplateBaseSchema = zod_default.object({
+  alias: contractAliasSchema.describe("Stable template alias, unique within the contract"),
+  label: zod_default.string().min(1),
+  content_sha256: zod_default.string().optional().describe(
+    "sha256 (64-char lowercase hex) of the template content \u2014 inline: the utf-8 content string; file-backed: the bytes_ref bytes. The modified-detection reference. Optional in the schema so contracts published before template sha still parse; REQUIRED at publish (validatePackageContract)."
+  )
+});
+var contractInlineTemplateSchema = (templateType) => contractTemplateBaseSchema.extend({
+  type: zod_default.literal(templateType),
+  content: zod_default.string().min(1).describe("Inline template content; placeholders reference field aliases")
+});
+var contractFileTemplateSchema = (templateType) => contractTemplateBaseSchema.extend({
+  type: zod_default.literal(templateType),
+  bytes_ref: zod_default.string().min(1).describe("Path of the backing file within the package bundle; markers reference field aliases")
+});
+var contractTemplateSchema = zod_default.discriminatedUnion("type", [
+  contractInlineTemplateSchema("html"),
+  contractInlineTemplateSchema("email"),
+  contractFileTemplateSchema("excel"),
+  contractFileTemplateSchema("word"),
+  contractFileTemplateSchema("pdf-form")
+]);
+var contractFromTableNodeSchema = zod_default.object({
+  kind: zod_default.literal("from_table"),
+  from_entity: contractAliasSchema.describe("Entity alias this query reads from"),
+  filter: tableRecordFiltersSchema.optional(),
+  search: zod_default.string().optional(),
+  sort: tableRecordSortSchema.optional(),
+  limit: zod_default.number().optional()
+});
+var contractProjectNodeSchema = zod_default.object({
+  kind: zod_default.literal("project"),
+  from: zod_default.lazy(() => contractQueryNodeSchema),
+  columns: zod_default.array(queryProjectionColumnSchema).min(1)
+});
+var contractFilterNodeSchema = zod_default.object({
+  kind: zod_default.literal("filter"),
+  from: zod_default.lazy(() => contractQueryNodeSchema),
+  predicate: tableRecordFiltersSchema
+});
+var contractJoinNodeSchema = zod_default.object({
+  kind: zod_default.literal("join"),
+  left: zod_default.lazy(() => contractQueryNodeSchema),
+  right: zod_default.lazy(() => contractQueryNodeSchema),
+  on: queryJoinPredicateSchema,
+  type: zod_default.enum(["inner", "left"])
+});
+var contractUnionNodeSchema = zod_default.object({
+  kind: zod_default.literal("union"),
+  sources: zod_default.array(zod_default.lazy(() => contractQueryNodeSchema)).min(2)
+});
+var contractGroupNodeSchema = zod_default.object({
+  kind: zod_default.literal("group"),
+  from: zod_default.lazy(() => contractQueryNodeSchema),
+  by: zod_default.array(zod_default.string()),
+  aggregates: zod_default.array(queryAggregateColumnSchema).min(1)
+});
+var contractWindowNodeSchema = zod_default.object({
+  kind: zod_default.literal("window"),
+  from: zod_default.lazy(() => contractQueryNodeSchema),
+  partition_by: zod_default.array(zod_default.string()),
+  order_by: tableRecordSortSchema,
+  frame: queryWindowFrameSchema.optional(),
+  aggregates: zod_default.array(queryAggregateColumnSchema).optional(),
+  functions: zod_default.array(queryWindowFunctionColumnSchema).optional()
+});
+var contractSortNodeSchema = zod_default.object({
+  kind: zod_default.literal("sort"),
+  from: zod_default.lazy(() => contractQueryNodeSchema),
+  by: tableRecordSortSchema
+});
+var contractLimitNodeSchema = zod_default.object({
+  kind: zod_default.literal("limit"),
+  from: zod_default.lazy(() => contractQueryNodeSchema),
+  n: zod_default.number().int().positive(),
+  offset: zod_default.number().int().nonnegative().optional()
+});
+var contractUnpivotNodeSchema = zod_default.object({
+  kind: zod_default.literal("unpivot"),
+  from: zod_default.lazy(() => contractQueryNodeSchema),
+  passthrough: zod_default.array(queryUnpivotPassthroughColumnSchema),
+  row_columns: zod_default.array(queryUnpivotRowColumnSchema).min(1),
+  rows: zod_default.array(zod_default.record(zod_default.string(), querySourceSchema)).min(1)
+});
+var contractUnnestNodeSchema = zod_default.object({
+  kind: zod_default.literal("unnest"),
+  from: zod_default.lazy(() => contractQueryNodeSchema),
+  source: zod_default.string(),
+  output: zod_default.string(),
+  display_output: zod_default.string().optional(),
+  keep_empty: zod_default.boolean().optional()
+});
+var contractQueryNodeSchema = zod_default.lazy(
+  () => zod_default.discriminatedUnion("kind", [
+    contractFromTableNodeSchema,
+    contractProjectNodeSchema,
+    contractFilterNodeSchema,
+    contractJoinNodeSchema,
+    contractUnionNodeSchema,
+    contractGroupNodeSchema,
+    contractWindowNodeSchema,
+    contractSortNodeSchema,
+    contractLimitNodeSchema,
+    contractUnpivotNodeSchema,
+    contractUnnestNodeSchema
+  ])
+);
+var contractQuerySchema = zod_default.object({
+  alias: runtimeAliasSchema.describe(
+    "Stable query alias, unique within the contract \u2014 carried verbatim from the app (source invokes it at runtime)"
+  ),
+  params: zod_default.record(zod_default.string(), appWorkflowInputSchema).optional().describe("Typed param schema. Keys are param names referenced as {{params.<name>}} in the ast."),
+  ast: contractQueryNodeSchema
+});
+var contractLifecycleEventSchema = tableWorkflowEventSchema;
+var contractWorkflowTriggerSchema = zod_default.discriminatedUnion("type", [
+  zod_default.object({ type: zod_default.literal("app") }),
+  zod_default.object({
+    type: zod_default.literal("entity_lifecycle"),
+    entity: contractAliasSchema.describe("Alias of the entity whose lifecycle fires this workflow"),
+    event: contractLifecycleEventSchema
+  })
+]);
+var contractWorkflowSchema = zod_default.object({
+  alias: runtimeAliasSchema.describe(
+    "Stable workflow alias, unique within the contract \u2014 app-trigger aliases are carried verbatim from the app (source invokes them at runtime)"
+  ),
+  trigger: contractWorkflowTriggerSchema,
+  inputs: zod_default.record(zod_default.string(), appWorkflowInputSchema).optional().describe("Typed inputs. record_link `table_id` names an entity alias; member `group` a role alias."),
+  outputs: zod_default.record(zod_default.string(), appWorkflowOutputSchema).optional().describe("Typed outputs. record_link `table_id` names an entity alias."),
+  body: zod_default.string().min(1).describe("Alias-form JS-subset workflow source. Identifiers are resolved against the binding at materialize time.")
+});
+var contractAgentSchema = appAgentDeclarationSchema.extend({
+  alias: runtimeAliasSchema.describe(
+    "Stable agent alias, unique within the contract \u2014 carried verbatim from the app (source invokes it at runtime)"
+  ),
+  knowledge_expects: zod_default.array(zod_default.string().min(1)).optional().describe(
+    "Doc NAMES this agent must read that the package does NOT own \u2014 the installer's own docs. Resolved by name against the installing workspace: exactly one non-archived match binds, zero or several bind nothing and surface as an install warning, because doc names are not unique and picking one would be a guess. The agent installs either way."
+  ),
+  knowledge_aliases: zod_default.array(contractAliasSchema).optional().describe(
+    "Package knowledge docs this agent may read, by contract alias. Materialize resolves each against `binding.knowledge` to the installing workspace's own doc id and writes the agent's `knowledge_doc_ids`. Omit for an agent that reads no package knowledge \u2014 an agent whose declared set does not travel can read NOTHING, since a declared set bounds every read."
+  )
+});
+var contractConfigBaseSchema = zod_default.object({
+  alias: contractAliasSchema.describe("Stable config alias, unique within the contract"),
+  label: zod_default.string().min(1),
+  description: zod_default.string().optional()
+});
+var contractTextConfigSchema = contractConfigBaseSchema.extend({
+  type: zod_default.literal("text"),
+  default: zod_default.string()
+});
+var contractBooleanConfigSchema = contractConfigBaseSchema.extend({
+  type: zod_default.literal("boolean"),
+  default: zod_default.boolean()
+});
+var contractColorConfigSchema = contractConfigBaseSchema.extend({
+  type: zod_default.literal("color"),
+  default: optionColorSchema
+});
+var contractNumberConfigSchema = contractConfigBaseSchema.extend({
+  type: zod_default.literal("number"),
+  default: zod_default.number()
+});
+var contractSelectConfigSchema = contractConfigBaseSchema.extend({
+  type: zod_default.literal("select"),
+  options: zod_default.array(zod_default.object({ value: zod_default.string(), label: zod_default.string().min(1) })).min(1),
+  default: zod_default.string()
+});
+var contractConfigEntrySchema = zod_default.discriminatedUnion("type", [
+  contractTextConfigSchema,
+  contractBooleanConfigSchema,
+  contractColorConfigSchema,
+  contractNumberConfigSchema,
+  contractSelectConfigSchema
+]);
+var packageKindSchema = zod_default.enum(["app", "content"]);
+var contractKnowledgeEntrySchema = zod_default.object({
+  name: zod_default.string().min(1).describe(
+    "Display name \u2014 the runtime routing key an agent resolves the doc by; unique across the contract's knowledge"
+  ),
+  description: zod_default.string().describe("Doc description (may be empty)"),
+  // Optional so contracts published before folders still parse; absent means
+  // root. A curated corpus is exactly the case where organization is authored
+  // deliberately, so install and upgrade have to carry it — otherwise every
+  // installed corpus lands flat and the customer re-files it by hand.
+  path: zod_default.string().optional().describe("Folder the doc is filed under; omitted means root"),
+  content_ref: zod_default.string().min(1).describe("Path of the content file within the bundle \u2014 must be `knowledge/<alias>.md`"),
+  content_sha256: zod_default.string().describe("sha256 (64-char lowercase hex) of the content bytes \u2014 the modified-detection reference")
+});
+var contractKnowledgeSchema = zod_default.record(contractAliasSchema, contractKnowledgeEntrySchema);
+var packageContractSchema = zod_default.object({
+  entities: zod_default.array(contractEntitySchema).default([]),
+  roles: zod_default.array(contractRoleSchema).default([]),
+  templates: zod_default.array(contractTemplateSchema).default([]),
+  queries: zod_default.array(contractQuerySchema).default([]),
+  workflows: zod_default.array(contractWorkflowSchema).default([]),
+  agents: zod_default.array(contractAgentSchema).default([]),
+  config: zod_default.array(contractConfigEntrySchema).default([]),
+  // Package-managed knowledge docs (alias → metadata + content sha). Defaults to
+  // {} so contracts published before knowledge packaging still parse.
+  knowledge: contractKnowledgeSchema.default({}),
+  // Doc NAMES the package's agents route to but the package does not own —
+  // install/health WARN (advisory) when a name has no doc in the workspace.
+  // The first instance of the general cross-package "expects" contract.
+  knowledge_expects: zod_default.array(zod_default.string()).default([])
+});
+var bindingMapSchema = zod_default.record(zod_default.string().min(1), zod_default.string().min(1));
+var bindingSchema = zod_default.object({
+  entities: bindingMapSchema.default({}),
+  fields: bindingMapSchema.default({}),
+  options: bindingMapSchema.default({}),
+  templates: bindingMapSchema.default({}),
+  roles: bindingMapSchema.default({}),
+  // Artifact registry, not a schema binding: the package-owned table-workflow
+  // ROW id per entity_lifecycle workflow alias. Materialize matches/updates by
+  // this id (a display name is forgeable and renameable), upgrade prunes by
+  // it, and hashes look rows up through it. Excluded from BINDING_NAMESPACES:
+  // a deleted row is a modified-core finding (fingerprints), never binding
+  // drift, so validateBinding/applyDriftResolutions ignore it.
+  workflows: bindingMapSchema.default({}),
+  // The app's BUNDLED knowledge corpus: contract knowledge alias → the
+  // workspace's concrete `kdc_` id. One row, one pin — the app installation IS
+  // the anchor for its bundled docs (`package_content_installations` rows are
+  // standalone content packages only). Excluded from BINDING_NAMESPACES: a
+  // gone/edited doc is detected by the knowledge upgrade preview (live doc +
+  // content-sha reads), never by validateBinding's live-id sweep.
+  knowledge: bindingMapSchema.default({})
+});
+var BINDING_NAMESPACES = ["entities", "fields", "options", "templates", "roles"];
+var contentBindingMapSchema = zod_default.record(zod_default.string().min(1), zod_default.string().min(1));
+var packageContentBindingSchema = zod_default.object({
+  knowledge: contentBindingMapSchema.default({}),
+  templates: contentBindingMapSchema.default({})
+});
+var bindingDriftSchema = zod_default.object({
+  namespace: zod_default.enum(BINDING_NAMESPACES),
+  alias: zod_default.string(),
+  id: zod_default.string().describe("The stale concrete id the alias was bound to")
+});
+var driftResolutionSchema = zod_default.union([
+  zod_default.literal("recreate"),
+  zod_default.object({ bind_to: zod_default.string().min(1) })
+]);
+var MODIFIED_ARTIFACT_KINDS = ["queries", "workflows", "agents", "template"];
+var modifiedArtifactSchema = zod_default.object({
+  kind: zod_default.enum(MODIFIED_ARTIFACT_KINDS),
+  alias: zod_default.string(),
+  // Templates only: the OLD pinned contract carried no content_sha256, so the
+  // preview cannot attribute the divergence from the target to a local edit vs.
+  // the older upstream content — a one-time consent, converging once a
+  // sha-carrying version is pinned. Surfaces can say "can't verify local edits
+  // (older package version)".
+  baseline_unknown: zod_default.boolean().optional()
+});
+var packageArtifactHashesSchema = zod_default.object({
+  queries: zod_default.record(zod_default.string(), zod_default.string()),
+  workflows: zod_default.record(zod_default.string(), zod_default.string()),
+  agents: zod_default.record(zod_default.string(), zod_default.string())
+});
+var modificationResolutionSchema = zod_default.union([zod_default.literal("revert"), zod_default.literal("keep")]);
+var KNOWLEDGE_UPGRADE_CHANGES = ["added", "changed", "removed", "drifted"];
+var knowledgeUpgradeEntrySchema = zod_default.object({
+  alias: zod_default.string(),
+  name: zod_default.string().describe("The doc's display name \u2014 the target contract's name, or the live name for a drifted doc"),
+  change: zod_default.enum(KNOWLEDGE_UPGRADE_CHANGES),
+  /** `changed`/`removed` only: the live doc's content diverged from the OLD pinned sha. */
+  modified: zod_default.boolean(),
+  /** The bound live doc id; null for `added`, or for a `drifted` doc that is gone. */
+  doc_id: zod_default.string().nullable()
+});
+function knowledgeEntryNeedsConsent(entry) {
+  if (entry.change === "drifted") return true;
+  if (entry.change === "changed" || entry.change === "removed") return entry.modified;
+  return false;
+}
+var knowledgeResolutionSchema = zod_default.enum(["apply", "keep", "archive", "recreate", "unbind"]);
+var upgradeResolutionsSchema = zod_default.record(
+  zod_default.string(),
+  zod_default.union([driftResolutionSchema, modificationResolutionSchema, knowledgeResolutionSchema])
+);
+var knowledgeBindConsentSchema = zod_default.record(zod_default.string(), zod_default.string());
+var knowledgeUpgradeResolutionsSchema = zod_default.object({
+  resolutions: zod_default.record(zod_default.string(), knowledgeResolutionSchema).default({}),
+  bind_to: knowledgeBindConsentSchema.default({})
+});
+var knowledgeBoundRefSchema = zod_default.object({
+  alias: zod_default.string(),
+  name: zod_default.string(),
+  /** The bound doc id; null when the bound doc is gone/archived (drift). */
+  doc_id: zod_default.string().nullable()
+});
+var appInstallationConfigValueSchema = zod_default.union([zod_default.string(), zod_default.number(), zod_default.boolean()]);
+var appInstallationConfigSchema = zod_default.record(
+  contractAliasSchema,
+  appInstallationConfigValueSchema
+);
+var appInstallationProvenanceSchema = zod_default.enum(["install", "adopt"]);
+
 // ../shared/src/agent_instructions.ts
 function agentFilePath(alias) {
   return `src/agents/${alias}.md`;
@@ -70564,7 +72022,7 @@ function syncedEntry(entry) {
 function readSynced(projectDir) {
   try {
     const pkg2 = JSON.parse(
-      fs6.readFileSync(path7.join(projectDir, "package.json"), "utf-8")
+      fs8.readFileSync(path9.join(projectDir, "package.json"), "utf-8")
     );
     const raw = pkg2.lotics?.synced ?? {};
     return {
@@ -70585,16 +72043,16 @@ function normalizeSyncedMap(map3) {
   );
 }
 function writeSynced(projectDir, kind, alias, entry) {
-  const pkgPath2 = path7.join(projectDir, "package.json");
-  const pkg2 = JSON.parse(fs6.readFileSync(pkgPath2, "utf-8"));
+  const pkgPath2 = path9.join(projectDir, "package.json");
+  const pkg2 = JSON.parse(fs8.readFileSync(pkgPath2, "utf-8"));
   if (!pkg2.lotics) return;
   pkg2.lotics.synced ??= {};
   pkg2.lotics.synced[kind] = { ...pkg2.lotics.synced[kind], [alias]: entry };
-  fs6.writeFileSync(pkgPath2, JSON.stringify(pkg2, null, 2) + "\n");
+  fs8.writeFileSync(pkgPath2, JSON.stringify(pkg2, null, 2) + "\n");
 }
-var WORKFLOWS_DIR = path7.join("src", "workflows");
-var WORKFLOW_GLOBALS_DIR = path7.join(".lotics", "workflows");
-var AGENTS_DIR = path7.join("src", "agents");
+var WORKFLOWS_DIR = path9.join("src", "workflows");
+var WORKFLOW_GLOBALS_DIR = path9.join(".lotics", "workflows");
+var AGENTS_DIR = path9.join("src", "agents");
 var WORKFLOW_TSCONFIG_EXCLUDES = ["src/workflows", ".lotics/workflows"];
 var LOTICS_INCLUDE_GLOB = ".lotics/**/*";
 var STALE_LOTICS_INCLUDES = /* @__PURE__ */ new Set([".lotics", "./.lotics", ".lotics/"]);
@@ -70605,7 +72063,7 @@ function isMissingWorkflowBodyError(error52) {
   return /has no step source|cannot be rendered|unsupported step/i.test(error52);
 }
 function workflowFileHeader(alias) {
-  const refPath = path7.join("..", "..", WORKFLOW_GLOBALS_DIR, `${alias}.globals.d.ts`).split(path7.sep).join("/");
+  const refPath = path9.join("..", "..", WORKFLOW_GLOBALS_DIR, `${alias}.globals.d.ts`).split(path9.sep).join("/");
   return `/// <reference path="${refPath}" />
 // Auto-pulled workflow body for "${alias}". Edit the BODY between the wrapper
 // lines below, then check + push with:
@@ -70619,35 +72077,35 @@ export {};
 `;
 }
 function workflowFilePath(projectDir, alias) {
-  return path7.join(projectDir, WORKFLOWS_DIR, `${alias}.ts`);
+  return path9.join(projectDir, WORKFLOWS_DIR, `${alias}.ts`);
 }
 var GLOBALS_SUFFIX = ".globals.d.ts";
 function workflowGlobalsPath(projectDir, alias) {
-  return path7.join(projectDir, WORKFLOW_GLOBALS_DIR, `${alias}${GLOBALS_SUFFIX}`);
+  return path9.join(projectDir, WORKFLOW_GLOBALS_DIR, `${alias}${GLOBALS_SUFFIX}`);
 }
 function pruneOrphanWorkflowGlobals(projectDir, declared) {
-  const dir = path7.join(projectDir, WORKFLOW_GLOBALS_DIR);
-  if (!fs6.existsSync(dir)) return [];
+  const dir = path9.join(projectDir, WORKFLOW_GLOBALS_DIR);
+  if (!fs8.existsSync(dir)) return [];
   const removed = [];
-  for (const entry of fs6.readdirSync(dir)) {
+  for (const entry of fs8.readdirSync(dir)) {
     if (!entry.endsWith(GLOBALS_SUFFIX)) continue;
     const alias = entry.slice(0, -GLOBALS_SUFFIX.length);
     if (declared.has(alias)) continue;
-    fs6.unlinkSync(path7.join(dir, entry));
+    fs8.unlinkSync(path9.join(dir, entry));
     removed.push(alias);
   }
   return removed.sort();
 }
 function orphanWorkflowBodies(projectDir, declared) {
-  const dir = path7.join(projectDir, WORKFLOWS_DIR);
-  if (!fs6.existsSync(dir)) return [];
-  return fs6.readdirSync(dir).filter((e) => e.endsWith(".ts") && !e.endsWith(".d.ts") && !e.endsWith(".test.ts")).map((e) => e.slice(0, -".ts".length)).filter((alias) => !declared.has(alias)).sort();
+  const dir = path9.join(projectDir, WORKFLOWS_DIR);
+  if (!fs8.existsSync(dir)) return [];
+  return fs8.readdirSync(dir).filter((e) => e.endsWith(".ts") && !e.endsWith(".d.ts") && !e.endsWith(".test.ts")).map((e) => e.slice(0, -".ts".length)).filter((alias) => !declared.has(alias)).sort();
 }
 function writeWorkflowGlobals(projectDir, alias, dts) {
-  const dir = path7.join(projectDir, WORKFLOW_GLOBALS_DIR);
-  fs6.mkdirSync(dir, { recursive: true });
+  const dir = path9.join(projectDir, WORKFLOW_GLOBALS_DIR);
+  fs8.mkdirSync(dir, { recursive: true });
   const file2 = workflowGlobalsPath(projectDir, alias);
-  fs6.writeFileSync(file2, `${dts.replace(/\s+$/, "")}
+  fs8.writeFileSync(file2, `${dts.replace(/\s+$/, "")}
 `);
   return file2;
 }
@@ -70655,26 +72113,26 @@ function normalizeWorkflowBody(source) {
   return source.replace(/\s+$/, "");
 }
 function writeWorkflowFile(projectDir, alias, source, envelope = { prefix: WORKFLOW_ENVELOPE_PREFIX, suffix: WORKFLOW_ENVELOPE_SUFFIX }) {
-  const dir = path7.join(projectDir, WORKFLOWS_DIR);
-  fs6.mkdirSync(dir, { recursive: true });
+  const dir = path9.join(projectDir, WORKFLOWS_DIR);
+  fs8.mkdirSync(dir, { recursive: true });
   const file2 = workflowFilePath(projectDir, alias);
   const body = normalizeWorkflowBody(source);
-  fs6.writeFileSync(file2, `${workflowFileHeader(alias)}
+  fs8.writeFileSync(file2, `${workflowFileHeader(alias)}
 ${envelope.prefix}${body}${envelope.suffix}
 `);
   return file2;
 }
 function agentFilePath2(projectDir, alias) {
-  return path7.join(projectDir, ...agentFilePath(alias).split("/"));
+  return path9.join(projectDir, ...agentFilePath(alias).split("/"));
 }
 var CLI_AGENT_NOTES = [
   "Pulled from the LIVE app row; edit here, then: lotics app agent set <alias>",
   "The typed fields (inputs/outputs/tool_names/model_tier) live in package.json#lotics.agents"
 ];
 function writeAgentFile(projectDir, alias, instructions) {
-  fs6.mkdirSync(path7.join(projectDir, AGENTS_DIR), { recursive: true });
+  fs8.mkdirSync(path9.join(projectDir, AGENTS_DIR), { recursive: true });
   const file2 = agentFilePath2(projectDir, alias);
-  fs6.writeFileSync(
+  fs8.writeFileSync(
     file2,
     wrapAgentFile({ alias, instructions, notes: CLI_AGENT_NOTES.map((n) => n.replace("<alias>", alias)) })
   );
@@ -70699,20 +72157,20 @@ function writeAgentFiles(projectDir, agents, opts) {
 }
 function localPromptUnpushed(projectDir, alias) {
   const file2 = agentFilePath2(projectDir, alias);
-  if (!fs6.existsSync(file2)) return false;
+  if (!fs8.existsSync(file2)) return false;
   const baseline = readSynced(projectDir).agents[alias]?.content;
   if (baseline === void 0) return true;
-  return contentSha(stripAgentHeader(fs6.readFileSync(file2, "utf-8"))) !== baseline;
+  return contentSha(stripAgentHeader(fs8.readFileSync(file2, "utf-8"))) !== baseline;
 }
 function generatedWorkflowDescription(appName, alias) {
   return `Workflow invoked by app "${appName}" via useWorkflow("${alias}").`;
 }
 function localBodyUnpushed(projectDir, alias) {
   const file2 = workflowFilePath(projectDir, alias);
-  if (!fs6.existsSync(file2)) return false;
+  if (!fs8.existsSync(file2)) return false;
   const baseline = readSynced(projectDir).workflows[alias]?.content;
   if (baseline === void 0) return true;
-  return contentSha(stripWorkflowHeader(fs6.readFileSync(file2, "utf-8"))) !== baseline;
+  return contentSha(stripWorkflowHeader(fs8.readFileSync(file2, "utf-8"))) !== baseline;
 }
 async function writeWorkflowFiles(client, projectDir, app_id, appName, workflows, opts) {
   const written = [];
@@ -70767,12 +72225,12 @@ async function writeWorkflowFiles(client, projectDir, app_id, appName, workflows
   return written;
 }
 function writeWorkflowDescription(projectDir, alias, description) {
-  const pkgPath2 = path7.join(projectDir, "package.json");
-  const pkg2 = JSON.parse(fs6.readFileSync(pkgPath2, "utf-8"));
+  const pkgPath2 = path9.join(projectDir, "package.json");
+  const pkg2 = JSON.parse(fs8.readFileSync(pkgPath2, "utf-8"));
   const declaration = pkg2.lotics?.workflows?.[alias];
   if (!declaration) return;
   declaration.description = description;
-  fs6.writeFileSync(pkgPath2, JSON.stringify(pkg2, null, 2) + "\n");
+  fs8.writeFileSync(pkgPath2, JSON.stringify(pkg2, null, 2) + "\n");
 }
 async function fetchWorkflowGlobals(client, projectDir, app_id, alias, declaration) {
   try {
@@ -70822,20 +72280,20 @@ function runNpm(args, cwd) {
 }
 function readAppWorkspaceId(projectDir) {
   try {
-    const pkgPath2 = path7.join(projectDir, "package.json");
-    if (!fs6.existsSync(pkgPath2)) return null;
-    const pkg2 = JSON.parse(fs6.readFileSync(pkgPath2, "utf-8"));
+    const pkgPath2 = path9.join(projectDir, "package.json");
+    if (!fs8.existsSync(pkgPath2)) return null;
+    const pkg2 = JSON.parse(fs8.readFileSync(pkgPath2, "utf-8"));
     return pkg2.lotics?.workspace_id ?? null;
   } catch {
     return null;
   }
 }
 function readAppMeta(projectDir) {
-  const pkgPath2 = path7.join(projectDir, "package.json");
-  if (!fs6.existsSync(pkgPath2)) {
+  const pkgPath2 = path9.join(projectDir, "package.json");
+  if (!fs8.existsSync(pkgPath2)) {
     throw new Error(`No package.json found at ${projectDir}. Run 'lotics app create' first.`);
   }
-  const pkg2 = JSON.parse(fs6.readFileSync(pkgPath2, "utf-8"));
+  const pkg2 = JSON.parse(fs8.readFileSync(pkgPath2, "utf-8"));
   if (!pkg2.lotics?.app_id || !pkg2.lotics.workspace_id) {
     throw new Error(
       `package.json is missing the 'lotics' field with app_id and workspace_id. Was this folder created with 'lotics app create'?`
@@ -70854,8 +72312,8 @@ function readAppMeta(projectDir) {
   };
 }
 function writeAppMeta(projectDir, meta3) {
-  const pkgPath2 = path7.join(projectDir, "package.json");
-  const pkg2 = JSON.parse(fs6.readFileSync(pkgPath2, "utf-8"));
+  const pkgPath2 = path9.join(projectDir, "package.json");
+  const pkg2 = JSON.parse(fs8.readFileSync(pkgPath2, "utf-8"));
   const existing = pkg2.lotics && typeof pkg2.lotics === "object" ? pkg2.lotics : {};
   const supplied = new Set(
     Object.entries(meta3).filter(([, value2]) => value2 !== void 0).map(([key]) => key)
@@ -70865,11 +72323,11 @@ function writeAppMeta(projectDir, meta3) {
     if (!supplied.has(key)) preserved[key] = value2;
   }
   pkg2.lotics = { ...meta3, ...preserved };
-  fs6.writeFileSync(pkgPath2, JSON.stringify(pkg2, null, 2) + "\n");
+  fs8.writeFileSync(pkgPath2, JSON.stringify(pkg2, null, 2) + "\n");
 }
 function writeWorkflowOutputs(projectDir, alias, outputs) {
-  const pkgPath2 = path7.join(projectDir, "package.json");
-  const pkg2 = JSON.parse(fs6.readFileSync(pkgPath2, "utf-8"));
+  const pkgPath2 = path9.join(projectDir, "package.json");
+  const pkg2 = JSON.parse(fs8.readFileSync(pkgPath2, "utf-8"));
   const declaration = pkg2.lotics?.workflows?.[alias];
   if (!declaration) {
     throw new Error(
@@ -70877,7 +72335,7 @@ function writeWorkflowOutputs(projectDir, alias, outputs) {
     );
   }
   declaration.outputs = outputs;
-  fs6.writeFileSync(pkgPath2, JSON.stringify(pkg2, null, 2) + "\n");
+  fs8.writeFileSync(pkgPath2, JSON.stringify(pkg2, null, 2) + "\n");
 }
 function workflowBodyDrift(projectDir, workflows, synced = {}) {
   const drifted = [];
@@ -70885,16 +72343,16 @@ function workflowBodyDrift(projectDir, workflows, synced = {}) {
     const baseline = syncedEntry(synced[alias])?.content;
     if (baseline === void 0) continue;
     const file2 = workflowFilePath(projectDir, alias);
-    if (!fs6.existsSync(file2)) continue;
-    const source = stripWorkflowHeader(fs6.readFileSync(file2, "utf-8"));
+    if (!fs8.existsSync(file2)) continue;
+    const source = stripWorkflowHeader(fs8.readFileSync(file2, "utf-8"));
     if (source.trim() === "" || contentSha(source) === baseline) continue;
     drifted.push(alias);
   }
   return drifted;
 }
 function ensureAppTsconfig(projectDir) {
-  const tsconfigPath = path7.join(projectDir, "tsconfig.json");
-  if (!fs6.existsSync(tsconfigPath)) {
+  const tsconfigPath = path9.join(projectDir, "tsconfig.json");
+  if (!fs8.existsSync(tsconfigPath)) {
     console.error(
       `\u26A0 No tsconfig.json at ${projectDir} \u2014 could not ensure "include" has "${LOTICS_INCLUDE_GLOB}" (a bare .lotics loads none of the generated types) or "exclude" has ${WORKFLOW_TSCONFIG_EXCLUDES.join(", ")}.`
     );
@@ -70902,7 +72360,7 @@ function ensureAppTsconfig(projectDir) {
   }
   let parsed;
   try {
-    parsed = JSON.parse(fs6.readFileSync(tsconfigPath, "utf-8"));
+    parsed = JSON.parse(fs8.readFileSync(tsconfigPath, "utf-8"));
   } catch (err2) {
     console.error(
       `\u26A0 Could not parse tsconfig.json (${err2 instanceof Error ? err2.message : String(err2)}) \u2014 ensure "include" has "${LOTICS_INCLUDE_GLOB}" and "exclude" has ${WORKFLOW_TSCONFIG_EXCLUDES.join(", ")} manually.`
@@ -70935,7 +72393,7 @@ function ensureAppTsconfig(projectDir) {
     );
   }
   if (changes.length === 0) return;
-  fs6.writeFileSync(tsconfigPath, JSON.stringify(parsed, null, 2) + "\n");
+  fs8.writeFileSync(tsconfigPath, JSON.stringify(parsed, null, 2) + "\n");
   console.error(`Patched tsconfig.json: ${changes.join("; ")}.`);
 }
 var LINK_TSCONFIG = ".lotics/tsconfig.link.json";
@@ -70945,15 +72403,15 @@ function writeDevLinkTsconfig(projectDir) {
   if (uiSrc) {
     paths["@lotics/ui/*"] = [`${uiSrc}/*`];
     for (const peer of readKitPeerNames(projectDir)) {
-      const typesDir = path7.join(projectDir, "node_modules", typesPackageFor(peer));
-      const runtimeDir = path7.join(projectDir, "node_modules", peer);
-      const target = fs6.existsSync(typesDir) ? `../node_modules/${typesPackageFor(peer)}` : fs6.existsSync(runtimeDir) ? `../node_modules/${peer}` : null;
+      const typesDir = path9.join(projectDir, "node_modules", typesPackageFor(peer));
+      const runtimeDir = path9.join(projectDir, "node_modules", peer);
+      const target = fs8.existsSync(typesDir) ? `../node_modules/${typesPackageFor(peer)}` : fs8.existsSync(runtimeDir) ? `../node_modules/${peer}` : null;
       if (!target) continue;
       paths[peer] = [target];
       paths[`${peer}/*`] = [`${target}/*`];
     }
   }
-  const file2 = path7.join(projectDir, ".lotics", "tsconfig.link.json");
+  const file2 = path9.join(projectDir, ".lotics", "tsconfig.link.json");
   const header = uiSrc ? `// GENERATED by \`lotics app codegen\` \u2014 do not edit.
 // LOTICS_UI_SRC is set, so @lotics/ui resolves to your working copy for tsc,
 // vitest, eslint and your editor \u2014 the same copy Vite is bundling. The peer
@@ -70964,45 +72422,45 @@ function writeDevLinkTsconfig(projectDir) {
 // LOTICS_UI_SRC is not set, so this is inert and @lotics/ui resolves from
 // node_modules as normal.
 `;
-  fs6.writeFileSync(file2, `${header}${JSON.stringify({ compilerOptions: { paths } }, null, 2)}
+  fs8.writeFileSync(file2, `${header}${JSON.stringify({ compilerOptions: { paths } }, null, 2)}
 `);
   return file2;
 }
 function writeKitTypeAugmentation(projectDir) {
   const uiSrc = process.env.LOTICS_UI_SRC;
-  const source = uiSrc ? path7.join(uiSrc, "react_native.d.ts") : path7.join(projectDir, "node_modules", "@lotics", "ui", "src", "react_native.d.ts");
-  const target = path7.join(projectDir, ".lotics", "react_native.d.ts");
-  if (!fs6.existsSync(source)) {
-    if (fs6.existsSync(target)) fs6.rmSync(target);
+  const source = uiSrc ? path9.join(uiSrc, "react_native.d.ts") : path9.join(projectDir, "node_modules", "@lotics", "ui", "src", "react_native.d.ts");
+  const target = path9.join(projectDir, ".lotics", "react_native.d.ts");
+  if (!fs8.existsSync(source)) {
+    if (fs8.existsSync(target)) fs8.rmSync(target);
     return;
   }
-  fs6.writeFileSync(
+  fs8.writeFileSync(
     target,
     `// GENERATED by \`lotics app codegen\` from @lotics/ui \u2014 do not edit.
 // The kit's web-only ViewStyle/TextStyle properties, which react-native does
 // not model. Delete any hand-copied src/react_native.d.ts; this replaces it.
-` + fs6.readFileSync(source, "utf-8")
+` + fs8.readFileSync(source, "utf-8")
   );
 }
 function typesPackageFor(peer) {
   return peer.startsWith("@") ? `@types/${peer.slice(1).replace("/", "__")}` : `@types/${peer}`;
 }
 function readKitPeerNames(projectDir) {
-  const kitPkg = path7.join(projectDir, "node_modules", "@lotics", "ui", "package.json");
-  if (!fs6.existsSync(kitPkg)) return [];
-  const parsed = JSON.parse(fs6.readFileSync(kitPkg, "utf-8"));
+  const kitPkg = path9.join(projectDir, "node_modules", "@lotics", "ui", "package.json");
+  if (!fs8.existsSync(kitPkg)) return [];
+  const parsed = JSON.parse(fs8.readFileSync(kitPkg, "utf-8"));
   const peers = parsed.peerDependencies;
   return peers && typeof peers === "object" ? Object.keys(peers) : [];
 }
 function writeAppDts(projectDir, manifest) {
-  const dotLotics = path7.join(projectDir, ".lotics");
-  fs6.mkdirSync(dotLotics, { recursive: true });
+  const dotLotics = path9.join(projectDir, ".lotics");
+  fs8.mkdirSync(dotLotics, { recursive: true });
   const written = [
-    [path7.join(dotLotics, "app_workflows.d.ts"), generateAppWorkflowsDts(manifest.workflows)],
-    [path7.join(dotLotics, "app_queries.d.ts"), generateAppQueriesDts(manifest.queries)],
-    [path7.join(dotLotics, "app_agents.d.ts"), generateAppAgentsDts(manifest.agents)]
+    [path9.join(dotLotics, "app_workflows.d.ts"), generateAppWorkflowsDts(manifest.workflows)],
+    [path9.join(dotLotics, "app_queries.d.ts"), generateAppQueriesDts(manifest.queries)],
+    [path9.join(dotLotics, "app_agents.d.ts"), generateAppAgentsDts(manifest.agents)]
   ];
-  for (const [file2, content] of written) fs6.writeFileSync(file2, content);
+  for (const [file2, content] of written) fs8.writeFileSync(file2, content);
   writeDevLinkTsconfig(projectDir);
   writeKitTypeAugmentation(projectDir);
   ensureAppTsconfig(projectDir);
@@ -71010,7 +72468,7 @@ function writeAppDts(projectDir, manifest) {
   return written.map(([file2]) => file2);
 }
 function readCodegenTablesAllowlist(projectDir) {
-  const pkg2 = JSON.parse(fs6.readFileSync(path7.join(projectDir, "package.json"), "utf-8"));
+  const pkg2 = JSON.parse(fs8.readFileSync(path9.join(projectDir, "package.json"), "utf-8"));
   const tables = pkg2.lotics?.codegen?.tables;
   return Array.isArray(tables) ? tables.filter((t) => typeof t === "string") : [];
 }
@@ -71023,17 +72481,17 @@ function resolveCodegenTableIds(projectDir, queries) {
   return [...ids];
 }
 function writeAppFields(projectDir, tables) {
-  const dotLotics = path7.join(projectDir, ".lotics");
-  fs6.mkdirSync(dotLotics, { recursive: true });
-  const file2 = path7.join(dotLotics, "app_fields.ts");
-  fs6.writeFileSync(file2, generateAppFields(tables));
+  const dotLotics = path9.join(projectDir, ".lotics");
+  fs8.mkdirSync(dotLotics, { recursive: true });
+  const file2 = path9.join(dotLotics, "app_fields.ts");
+  fs8.writeFileSync(file2, generateAppFields(tables));
   return file2;
 }
 function writeBindingAppFields(projectDir, binding) {
-  const dotLotics = path7.join(projectDir, ".lotics");
-  fs6.mkdirSync(dotLotics, { recursive: true });
-  const file2 = path7.join(dotLotics, "app_fields.ts");
-  fs6.writeFileSync(file2, generatePackageAppFields(binding));
+  const dotLotics = path9.join(projectDir, ".lotics");
+  fs8.mkdirSync(dotLotics, { recursive: true });
+  const file2 = path9.join(dotLotics, "app_fields.ts");
+  fs8.writeFileSync(file2, generatePackageAppFields(binding));
   return file2;
 }
 async function writeGeneratedAppFields(client, projectDir, app, queries) {
@@ -71074,7 +72532,7 @@ async function writeGeneratedAppFields(client, projectDir, app, queries) {
 }
 function warnAppFieldsUnwritten(projectDir, err2) {
   const reason = err2 instanceof Error ? err2.message : String(err2);
-  if (fs6.existsSync(path7.join(projectDir, ".lotics", "app_fields.ts"))) {
+  if (fs8.existsSync(path9.join(projectDir, ".lotics", "app_fields.ts"))) {
     console.error(`\u26A0 Could not regenerate .lotics/app_fields.ts (${reason}). Kept the existing file.`);
     return;
   }
@@ -71085,8 +72543,8 @@ function warnAppFieldsUnwritten(projectDir, err2) {
 function warnAboutDevLink(projectDir, command) {
   const uiSrc = process.env.LOTICS_UI_SRC;
   if (!uiSrc) return;
-  const viteConfigPath = path7.join(projectDir, "vite.config.ts");
-  const config2 = fs6.existsSync(viteConfigPath) ? fs6.readFileSync(viteConfigPath, "utf-8") : "";
+  const viteConfigPath = path9.join(projectDir, "vite.config.ts");
+  const config2 = fs8.existsSync(viteConfigPath) ? fs8.readFileSync(viteConfigPath, "utf-8") : "";
   const linked = config2.includes("loticsResolve") || config2.includes("LOTICS_UI_SRC");
   if (!linked) {
     console.error(
@@ -71104,19 +72562,19 @@ function warnAboutDevLink(projectDir, command) {
   }
 }
 function ensureAppVitestSetup(projectDir) {
-  const setupPath = path7.join(projectDir, VITEST_SETUP_FILENAME);
-  if (!fs6.existsSync(setupPath)) {
-    fs6.writeFileSync(setupPath, VITEST_SETUP_CONTENT);
+  const setupPath = path9.join(projectDir, VITEST_SETUP_FILENAME);
+  if (!fs8.existsSync(setupPath)) {
+    fs8.writeFileSync(setupPath, VITEST_SETUP_CONTENT);
     console.error(`Wrote ${VITEST_SETUP_FILENAME} (stubs getAppBinding so \`npm test\` collects).`);
-  } else if (!fs6.readFileSync(setupPath, "utf-8").includes("getAppBinding")) {
+  } else if (!fs8.readFileSync(setupPath, "utf-8").includes("getAppBinding")) {
     console.error(
       `\u26A0 ${VITEST_SETUP_FILENAME} exists but does not stub getAppBinding \u2014 \`npm test\` will fail to collect any test that imports the app graph (the binding-form .lotics/app_fields.ts awaits a network call). Add the stub to it:
 ${VITEST_SETUP_CONTENT}`
     );
   }
-  const viteConfigPath = path7.join(projectDir, "vite.config.ts");
-  if (!fs6.existsSync(viteConfigPath)) return;
-  const viteConfig = fs6.readFileSync(viteConfigPath, "utf-8");
+  const viteConfigPath = path9.join(projectDir, "vite.config.ts");
+  if (!fs8.existsSync(viteConfigPath)) return;
+  const viteConfig = fs8.readFileSync(viteConfigPath, "utf-8");
   if (/setupFiles\s*:/.test(viteConfig) && viteConfig.includes(VITEST_SETUP_FILENAME)) return;
   console.error(
     `\u26A0 vite.config.ts does not wire ${VITEST_SETUP_FILENAME} \u2014 \`npm test\` will fail to collect any test that imports the app graph (the binding-form .lotics/app_fields.ts awaits a network call). Add it to the \`test\` block:
@@ -71124,7 +72582,7 @@ ${VITEST_SETUP_CONTENT}`
   );
 }
 async function appCodegen(args) {
-  const projectDir = path7.resolve(args.projectDir ?? process.cwd());
+  const projectDir = path9.resolve(args.projectDir ?? process.cwd());
   const meta3 = readAppMeta(projectDir);
   const dtsPaths = writeAppDts(projectDir, {
     workflows: meta3.workflows,
@@ -71138,7 +72596,7 @@ async function appCodegen(args) {
   }
   for (const alias of orphanWorkflowBodies(projectDir, declared)) {
     console.error(
-      `\u26A0 ${path7.join(WORKFLOWS_DIR, `${alias}.ts`)} is not declared in package.json#lotics.workflows \u2014 'workflow check' and 'workflow set' both skip it. Declare the alias or delete the file.`
+      `\u26A0 ${path9.join(WORKFLOWS_DIR, `${alias}.ts`)} is not declared in package.json#lotics.workflows \u2014 'workflow check' and 'workflow set' both skip it. Declare the alias or delete the file.`
     );
   }
   if (!args.client) {
@@ -71189,8 +72647,8 @@ async function refreshWorkflowGlobals(client, projectDir, app_id, workflows) {
 }
 async function refreshWorkflowTypes(client, projectDir, app_id, alias, declaration) {
   const file2 = workflowFilePath(projectDir, alias);
-  if (!fs6.existsSync(file2)) return false;
-  const body = stripWorkflowHeader(fs6.readFileSync(file2, "utf-8"));
+  if (!fs8.existsSync(file2)) return false;
+  const body = stripWorkflowHeader(fs8.readFileSync(file2, "utf-8"));
   if (body.trim() === "") return false;
   const envelope = await fetchWorkflowGlobals(client, projectDir, app_id, alias, declaration);
   writeWorkflowFile(projectDir, alias, body, envelope);
@@ -71220,21 +72678,21 @@ async function downloadToFile(url2, destPath) {
     throw new Error(`Failed to download ${url2}: ${response.status}`);
   }
   const buffer = Buffer.from(await response.arrayBuffer());
-  fs6.writeFileSync(destPath, buffer);
+  fs8.writeFileSync(destPath, buffer);
 }
 function appDirName(name2) {
   const cleaned = name2.replace(/[/\\]+/g, "-").replace(/[<>:"|?*]/g, "").replace(/\s+/g, " ").trim().replace(/^[.\s-]+|[.\s-]+$/g, "");
   return cleaned || "app";
 }
 async function appCreate(client, args) {
-  const targetPath = path7.resolve(args.targetPath ?? appDirName(args.name));
-  if (fs6.existsSync(targetPath)) {
-    const entries2 = fs6.readdirSync(targetPath);
+  const targetPath = path9.resolve(args.targetPath ?? appDirName(args.name));
+  if (fs8.existsSync(targetPath)) {
+    const entries2 = fs8.readdirSync(targetPath);
     if (entries2.length > 0) {
       throw new Error(`Target directory ${targetPath} is not empty.`);
     }
   }
-  fs6.mkdirSync(targetPath, { recursive: true });
+  fs8.mkdirSync(targetPath, { recursive: true });
   const [uiLatest, sdkLatest] = await Promise.all([
     requireLatestNpmVersion("@lotics/ui"),
     requireLatestNpmVersion("@lotics/app-sdk")
@@ -71249,9 +72707,9 @@ async function appCreate(client, args) {
     sdk_version: `^${sdkLatest}`
   });
   for (const file2 of files) {
-    const fullPath = path7.join(targetPath, file2.path);
-    fs6.mkdirSync(path7.dirname(fullPath), { recursive: true });
-    fs6.writeFileSync(fullPath, file2.content);
+    const fullPath = path9.join(targetPath, file2.path);
+    fs8.mkdirSync(path9.dirname(fullPath), { recursive: true });
+    fs8.writeFileSync(fullPath, file2.content);
   }
   console.error(`Scaffolded ${files.length} files into ${targetPath}`);
   writeAppDts(targetPath, {});
@@ -71264,8 +72722,10 @@ async function appCreate(client, args) {
   });
   console.error(`
 Ready. Next steps:`);
-  console.error(`  cd ${path7.relative(process.cwd(), targetPath) || "."}`);
+  console.error(`  cd ${path9.relative(process.cwd(), targetPath) || "."}`);
+  console.error(`  lotics docs                # the contracts, at the versions installed here`);
   console.error(`  # edit src/App.tsx, then:`);
+  console.error(`  lotics app check           # every pre-flight a deploy runs`);
   console.error(`  lotics app deploy`);
 }
 async function appSetSubdomain(client, args) {
@@ -71321,11 +72781,11 @@ async function appVersions(client, args) {
   }
 }
 function defaultPullTarget(appId, appName) {
-  const cwdPkgPath = path7.join(process.cwd(), "package.json");
-  if (fs6.existsSync(cwdPkgPath)) {
+  const cwdPkgPath = path9.join(process.cwd(), "package.json");
+  if (fs8.existsSync(cwdPkgPath)) {
     let pkg2 = null;
     try {
-      pkg2 = JSON.parse(fs6.readFileSync(cwdPkgPath, "utf-8"));
+      pkg2 = JSON.parse(fs8.readFileSync(cwdPkgPath, "utf-8"));
     } catch (err2) {
       console.error(
         `\u26A0 Could not parse ${cwdPkgPath} (${err2 instanceof Error ? err2.message : String(err2)}) \u2014 pulling into a fresh ${appDirName(appName)}/ subdir.`
@@ -71346,20 +72806,20 @@ async function appPull(client, args) {
   if (!versionId) throw new Error(`App ${app.id} has no version to pull.`);
   const version2 = await client.getAppVersion(app.id, versionId);
   const sourceUrl = await client.getAppVersionSourceUrl(app.id, version2.id);
-  const targetPath = path7.resolve(args.targetPath ?? defaultPullTarget(app.id, app.name));
-  fs6.mkdirSync(targetPath, { recursive: true });
-  const tmpFile = path7.join(tmpdir(), `lotics-app-${app.id}-${Date.now()}.tar.gz`);
+  const targetPath = path9.resolve(args.targetPath ?? defaultPullTarget(app.id, app.name));
+  fs8.mkdirSync(targetPath, { recursive: true });
+  const tmpFile = path9.join(tmpdir(), `lotics-app-${app.id}-${Date.now()}.tar.gz`);
   console.error(`Downloading source archive...`);
   await downloadToFile(sourceUrl, tmpFile);
   const keptLocal = [];
-  const stagingDir = fs6.mkdtempSync(path7.join(tmpdir(), `lotics-pull-${app.id}-`));
+  const stagingDir = fs8.mkdtempSync(path9.join(tmpdir(), `lotics-pull-${app.id}-`));
   try {
     await runTar(["-xzf", tmpFile, "-C", stagingDir], stagingDir);
     console.error(`Extracting to ${targetPath}...`);
     keptLocal.push(...copyTree(stagingDir, targetPath, { overwrite: args.force === true }));
   } finally {
-    if (fs6.existsSync(tmpFile)) fs6.unlinkSync(tmpFile);
-    fs6.rmSync(stagingDir, { recursive: true, force: true });
+    if (fs8.existsSync(tmpFile)) fs8.unlinkSync(tmpFile);
+    fs8.rmSync(stagingDir, { recursive: true, force: true });
   }
   stampPulledManifest(targetPath, {
     app_id: app.id,
@@ -71419,26 +72879,28 @@ async function appPull(client, args) {
   reportKeptLocalFiles(keptLocal, app.id);
   console.error(`
 Ready. Next steps:`);
-  console.error(`  cd ${path7.relative(process.cwd(), targetPath) || "."}`);
+  console.error(`  cd ${path9.relative(process.cwd(), targetPath) || "."}`);
   console.error(`  # edit src/App.tsx`);
   console.error(`  lotics app deploy`);
 }
 function readAppSourceText(projectDir) {
-  const srcDir = path7.join(projectDir, "src");
-  if (!fs6.existsSync(srcDir)) return "";
+  const srcDir = path9.join(projectDir, "src");
+  if (!fs8.existsSync(srcDir)) return "";
   const parts = [];
   const walk2 = (dir) => {
-    for (const entry of fs6.readdirSync(dir, { withFileTypes: true })) {
-      const full = path7.join(dir, entry.name);
+    for (const entry of fs8.readdirSync(dir, { withFileTypes: true })) {
+      const full = path9.join(dir, entry.name);
       if (entry.isDirectory()) walk2(full);
-      else if (/\.(ts|tsx|js|jsx)$/.test(entry.name)) parts.push(fs6.readFileSync(full, "utf8"));
+      else if (isAppSourcePath(path9.relative(projectDir, full))) {
+        parts.push(fs8.readFileSync(full, "utf8"));
+      }
     }
   };
   walk2(srcDir);
   return parts.join("\n");
 }
 async function appDeploy(client, args) {
-  const projectDir = path7.resolve(args.projectDir ?? process.cwd());
+  const projectDir = path9.resolve(args.projectDir ?? process.cwd());
   const meta3 = readAppMeta(projectDir);
   warnAboutDevLink(projectDir, "deploy");
   const liveApp = await client.getApp(meta3.app_id);
@@ -71455,6 +72917,7 @@ async function appDeploy(client, args) {
   const called = calledAppAliases(sourceText);
   warnIfDynamicAliases(called);
   warnIfUndeclaredCapabilities(sourceText, meta3.capabilities);
+  warnIfProjectFootguns(projectDir, sourceText);
   writeAppDts(projectDir, { workflows: meta3.workflows, queries: meta3.queries, agents: meta3.agents });
   try {
     await writeGeneratedAppFields(
@@ -71471,14 +72934,14 @@ async function appDeploy(client, args) {
   }
   console.error("Building...");
   await runNpm(["run", "build"], projectDir);
-  const distDir = path7.join(projectDir, "dist");
-  if (!fs6.existsSync(distDir)) {
+  const distDir = path9.join(projectDir, "dist");
+  if (!fs8.existsSync(distDir)) {
     throw new Error(
       `Build did not produce a dist/ directory in ${projectDir}. Check that 'npm run build' is configured correctly (Vite/etc. defaults to dist/).`
     );
   }
-  const tmpSource = path7.join(tmpdir(), `lotics-source-${Date.now()}.tar.gz`);
-  const tmpDist = path7.join(tmpdir(), `lotics-dist-${Date.now()}.tar.gz`);
+  const tmpSource = path9.join(tmpdir(), `lotics-source-${Date.now()}.tar.gz`);
+  const tmpDist = path9.join(tmpdir(), `lotics-dist-${Date.now()}.tar.gz`);
   try {
     console.error("Packaging source...");
     await runTar(
@@ -71502,8 +72965,8 @@ async function appDeploy(client, args) {
       const result = await client.deployAppVersion({
         queries: liveQueries,
         app_id: meta3.app_id,
-        source_archive: fs6.readFileSync(tmpSource),
-        dist_archive: fs6.readFileSync(tmpDist),
+        source_archive: fs8.readFileSync(tmpSource),
+        dist_archive: fs8.readFileSync(tmpDist),
         prev_version_id: meta3.current_version_id,
         message: args.message ?? derivedDeployMessage(pending),
         // Capabilities ARE manifest-authoritative: always send,
@@ -71511,6 +72974,14 @@ async function appDeploy(client, args) {
         // `capabilities` block turns every capability OFF on the next deploy
         // (fail-safe; the declaration is the grant).
         capabilities: meta3.capabilities ?? {},
+        // The three alias sets below are IGNORED by a current server, which derives
+        // them from the source archive this same request uploads — the client that
+        // acts on the set cannot also be the one that reports it. They are still
+        // sent because a server that predates that change DOES read them, and reads
+        // an absent field as `[]`, which switches the unbind guard off for every
+        // version deployed during a rollback window. Drop them once no such server
+        // is a rollback target — the same reasoning as the `queries` echo above.
+        //
         // Workflow BINDINGS are NOT a deploy concern — set_app_workflow /
         // remove_app_workflow own apps.workflows. What IS sent is the set of
         // aliases this bundle CALLS (never the bindings), so remove_app_workflow
@@ -71539,6 +73010,7 @@ async function appDeploy(client, args) {
       if (liveAfter) {
         warnIfUnbranded(liveAfter);
         warnIfUnboundAliases(liveAfter, called);
+        warnIfInertAgentTools(liveAfter);
       }
       if (liveAfter) {
         await pruneOrphanedBindings(
@@ -71559,8 +73031,8 @@ async function appDeploy(client, args) {
       throw err2;
     }
   } finally {
-    if (fs6.existsSync(tmpSource)) fs6.unlinkSync(tmpSource);
-    if (fs6.existsSync(tmpDist)) fs6.unlinkSync(tmpDist);
+    if (fs8.existsSync(tmpSource)) fs8.unlinkSync(tmpSource);
+    if (fs8.existsSync(tmpDist)) fs8.unlinkSync(tmpDist);
   }
 }
 function warnIfUnbranded(app) {
@@ -71587,8 +73059,82 @@ async function readLiveQueries(client, appId) {
     process.exit(1);
   }
 }
+async function installCommand(client, args) {
+  const res = await client.installPackage(args.packageId, {});
+  if (res.kind === "app") {
+    const { app } = res;
+    console.error(
+      `Installed "${app.name}" (${app.id})` + (app.package_version !== null ? ` at v${app.package_version}` : "") + `.
+  Open it from the workspace's app launcher.
+  To work on it locally:  lotics app pull ${app.id}
+  To give it an address:  lotics app subdomain <slug>   (from inside that project)`
+    );
+    reportKnowledgeWarnings(res.knowledge_warnings);
+    return;
+  }
+  console.error(
+    `Installed content package (${res.installation.id}).
+  Its documents and templates are now in this workspace.`
+  );
+  reportKnowledgeWarnings(res.warnings);
+}
+function reportKnowledgeWarnings(warnings) {
+  const missing = warnings.missing_expected_docs;
+  if (missing.length === 0) return;
+  console.error(
+    `
+\u26A0 ${missing.length} expected knowledge doc(s) are missing from this workspace:
+` + missing.map((name2) => `  \u2022 ${name2}`).join("\n") + `
+  An agent declaring one of these reads nothing from it \u2014 the run still completes,
+  answering from nowhere. Create them, then re-run the install.`
+  );
+}
+async function upgradeCommand(client, args) {
+  const projectDir = path9.resolve(args.projectDir ?? process.cwd());
+  const meta3 = readAppMeta(projectDir);
+  const plan = await client.previewPackageUpgrade(meta3.app_id, {});
+  if (plan.from_version === plan.to_version) {
+    console.error(`Already on v${plan.from_version} \u2014 nothing to take.`);
+    return;
+  }
+  const blockers = [
+    ...plan.diff.breaking.map(
+      (b) => `  \u2022 breaking: ${b.entity}.${b.alias} ${b.kind} ${b.from} \u2192 ${b.to}`
+    ),
+    ...plan.modified.map(
+      (m) => `  \u2022 locally modified: ${m.kind} "${m.alias}"` + (m.baseline_unknown === true ? " (no baseline recorded \u2014 cannot tell what changed)" : "")
+    ),
+    ...plan.drift.map((d) => `  \u2022 drifted: ${d.namespace} "${d.alias}"`),
+    // The FOURTH refusal source, and the one this originally missed. The server
+    // throws a BadRequestError for every entry `knowledgeEntryNeedsConsent`
+    // accepts, so leaving it out did not make those upgrades work — it swapped
+    // the carefully-framed refusal for a raw wire 400. Read the canonical
+    // predicate rather than re-deriving the rule: a hand-listed subset of a
+    // server-side decision is how three of four got covered in the first place.
+    ...plan.knowledge.filter(knowledgeEntryNeedsConsent).map(
+      (k) => `  \u2022 knowledge: "${k.alias}" (${k.change}${k.modified ? ", locally edited" : ""})`
+    )
+  ];
+  if (blockers.length > 0) {
+    console.error(
+      `v${plan.from_version} \u2192 v${plan.to_version} needs decisions this command will not make for you:
+` + blockers.join("\n") + `
+
+  Each one resolves by choosing what to KEEP, and guessing would discard
+  work nobody asked to lose. Resolve them, or ask an operator to run the
+  upgrade with explicit resolutions.`
+    );
+    process.exit(1);
+  }
+  const applied = await client.upgradePackage(meta3.app_id, { version: plan.to_version });
+  console.error(
+    `Upgraded to v${applied.package_version ?? plan.to_version}.` + (plan.changelog ? `
+  ${plan.changelog}` : "") + `
+  Run \`lotics app pull\` to bring this checkout in step.`
+  );
+}
 async function appCheck(client, args = {}) {
-  const projectDir = path7.resolve(args.projectDir ?? process.cwd());
+  const projectDir = path9.resolve(args.projectDir ?? process.cwd());
   const meta3 = readAppMeta(projectDir);
   const app = await client.getApp(meta3.app_id);
   const sourceText = readAppSourceText(projectDir);
@@ -71605,6 +73151,8 @@ async function appCheck(client, args = {}) {
   warnIfDynamicAliases(called);
   warnIfUndeclaredCapabilities(sourceText, meta3.capabilities);
   warnIfUnboundAliases(app, called);
+  warnIfInertAgentTools(app);
+  warnIfProjectFootguns(projectDir, sourceText);
   warnIfUnbranded(app);
   if (!nothingPending(pending)) {
     process.exit(1);
@@ -71692,8 +73240,8 @@ function driftedAgentAliases(projectDir, liveAgents) {
   const drifted = [];
   for (const [alias, live] of Object.entries(liveAgents ?? {})) {
     const file2 = agentFilePath2(projectDir, alias);
-    if (!fs6.existsSync(file2)) continue;
-    const local = stripAgentHeader(fs6.readFileSync(file2, "utf-8"));
+    if (!fs8.existsSync(file2)) continue;
+    const local = stripAgentHeader(fs8.readFileSync(file2, "utf-8"));
     if (local === "" || local === (live.instructions ?? "")) continue;
     drifted.push(alias);
   }
@@ -71796,21 +73344,21 @@ function derivedDeployMessage(pending) {
 }
 function copyTree(from, to, opts, relative = "") {
   const kept = [];
-  for (const entry of fs6.readdirSync(from, { withFileTypes: true })) {
-    const src = path7.join(from, entry.name);
-    const dest = path7.join(to, entry.name);
-    const rel = path7.join(relative, entry.name);
+  for (const entry of fs8.readdirSync(from, { withFileTypes: true })) {
+    const src = path9.join(from, entry.name);
+    const dest = path9.join(to, entry.name);
+    const rel = path9.join(relative, entry.name);
     if (entry.isDirectory()) {
-      fs6.mkdirSync(dest, { recursive: true });
+      fs8.mkdirSync(dest, { recursive: true });
       kept.push(...copyTree(src, dest, opts, rel));
       continue;
     }
-    if (!opts.overwrite && fs6.existsSync(dest)) {
-      if (fs6.readFileSync(src).equals(fs6.readFileSync(dest))) continue;
+    if (!opts.overwrite && fs8.existsSync(dest)) {
+      if (fs8.readFileSync(src).equals(fs8.readFileSync(dest))) continue;
       kept.push(rel);
       continue;
     }
-    fs6.copyFileSync(src, dest);
+    fs8.copyFileSync(src, dest);
   }
   return kept;
 }
@@ -71846,6 +73394,151 @@ function warnIfUndeclaredCapabilities(sourceText, capabilities) {
   Add to package.json#lotics.capabilities:  ${block}`
   );
 }
+var VITE_CONFIG_NAMES = [
+  "vite.config.ts",
+  "vite.config.mts",
+  "vite.config.cts",
+  "vite.config.js",
+  "vite.config.mjs",
+  "vite.config.cjs"
+];
+function codeOnly(source) {
+  let out = "";
+  let i2 = 0;
+  while (i2 < source.length) {
+    const two = source.slice(i2, i2 + 2);
+    if (two === "//") {
+      while (i2 < source.length && source[i2] !== "\n") {
+        out += " ";
+        i2++;
+      }
+      continue;
+    }
+    if (two === "/*") {
+      while (i2 < source.length && source.slice(i2, i2 + 2) !== "*/") {
+        out += source[i2] === "\n" ? "\n" : " ";
+        i2++;
+      }
+      out += "  ";
+      i2 += 2;
+      continue;
+    }
+    const quote = source[i2];
+    if (quote === '"' || quote === "'" || quote === "`") {
+      out += " ";
+      i2++;
+      while (i2 < source.length && source[i2] !== quote) {
+        if (source[i2] === "\\") {
+          out += "  ";
+          i2 += 2;
+          continue;
+        }
+        out += source[i2] === "\n" ? "\n" : " ";
+        i2++;
+      }
+      out += " ";
+      i2++;
+      continue;
+    }
+    out += source[i2];
+    i2++;
+  }
+  return out;
+}
+function defineBlockKeys(config2) {
+  const code = codeOnly(config2);
+  const keys3 = /* @__PURE__ */ new Set();
+  for (const opener of code.matchAll(/\bdefine\s*:\s*\{/g)) {
+    let depth = 1;
+    let i2 = opener.index + opener[0].length;
+    const start = i2;
+    while (i2 < code.length && depth > 0) {
+      if (code[i2] === "{") depth++;
+      else if (code[i2] === "}") depth--;
+      i2++;
+    }
+    for (const key of code.slice(start, i2).matchAll(/(?:^|[{,])\s*([A-Za-z_$][\w$]*)\s*:/g)) {
+      keys3.add(key[1]);
+    }
+  }
+  return keys3;
+}
+function warnIfProjectFootguns(projectDir, sourceText) {
+  const lines = [];
+  const configName = VITE_CONFIG_NAMES.find((name2) => fs8.existsSync(path9.join(projectDir, name2)));
+  if (configName !== void 0) {
+    const config2 = fs8.readFileSync(path9.join(projectDir, configName), "utf-8");
+    const defined = defineBlockKeys(config2);
+    const missing = ["global", "__DEV__"].filter((name2) => !defined.has(name2));
+    if (missing.length > 0) {
+      lines.push(
+        [
+          `  \u2022 ${configName} does not define ${missing.join(" or ")} \u2014 react-native-web reads`,
+          "    `global.cancelAnimationFrame` and `__DEV__` as free variables, so the DEPLOYED",
+          "    app throws while dev, build and typecheck all pass.",
+          '      define: { __DEV__: "false", global: "globalThis" }   (top level AND optimizeDeps.esbuildOptions)'
+        ].join("\n")
+      );
+    }
+  }
+  if (/\bwindow\.open\s*\(/.test(sourceText)) {
+    lines.push(
+      [
+        "  \u2022 src calls window.open \u2014 the app runs in a sandboxed iframe, which drops it",
+        "    silently: no error, no navigation.",
+        '      import { openExternal } from "@lotics/app-sdk"'
+      ].join("\n")
+    );
+  }
+  if (lines.length === 0) return;
+  console.error(
+    ["\n\u26A0 This project has a footgun that only shows up once deployed:", ...lines].join("\n")
+  );
+}
+var DECLARATION_BOUND_TOOLS = [
+  { tool: "run_app_query", field: "query_aliases", noun: "read nothing", placeholder: "<alias>" },
+  { tool: "run_app_workflow", field: "workflow_aliases", noun: "write nothing", placeholder: "<alias>" },
+  { tool: "grep_knowledge", field: "knowledge_doc_ids", noun: "search nothing", placeholder: "kdc_\u2026" },
+  { tool: "read_knowledge", field: "knowledge_doc_ids", noun: "read nothing", placeholder: "kdc_\u2026" },
+  { tool: "list_knowledge", field: "knowledge_doc_ids", noun: "list nothing", placeholder: "kdc_\u2026" }
+];
+function warnIfInertAgentTools(app) {
+  const lines = [];
+  for (const [alias, agent] of Object.entries(app.agents ?? {})) {
+    const decl = agent;
+    const tools = decl.tool_names ?? [];
+    for (const { tool, field, noun, placeholder } of DECLARATION_BOUND_TOOLS) {
+      const granted = decl[field];
+      const hasReach = Array.isArray(granted) && granted.length > 0;
+      const hasTool = tools.includes(tool);
+      if (hasTool && !hasReach) {
+        lines.push(
+          `  \u2022 agent "${alias}" holds ${tool} with no ${field} \u2014 it can ${noun}.
+      lotics run set_app_agent '{"app_id":"${app.id}","alias":"${alias}","${field}":["${placeholder}"]}'`
+        );
+      }
+      if (!hasTool && hasReach && !anyToolReaches(tools, field)) {
+        lines.push(
+          `  \u2022 agent "${alias}" declares ${field} but holds no tool that reads it \u2014 nothing can reach them.
+      lotics run set_app_agent '{"app_id":"${app.id}","alias":"${alias}","tool_names":${JSON.stringify([...tools, tool])}}'`
+        );
+      }
+    }
+  }
+  if (lines.length === 0) return;
+  console.error(
+    [
+      "\n\u26A0 An agent's capability and its reach disagree. The tool is the capability;",
+      "  the declared list is the reach \u2014 either half alone means the call is refused",
+      "  or never made, and the run still completes, so this shows up as a prompt problem.",
+      ...lines,
+      "  Then `lotics app pull` to bring the manifest back in step."
+    ].join("\n")
+  );
+}
+function anyToolReaches(tools, field) {
+  return DECLARATION_BOUND_TOOLS.some((g) => g.field === field && tools.includes(g.tool));
+}
 function warnIfUnboundAliases(app, called) {
   const {
     queries: unboundQueries,
@@ -71870,7 +73563,7 @@ function warnIfUnboundAliases(app, called) {
   console.error(lines.join("\n"));
 }
 async function appDev(client, args) {
-  const projectDir = path7.resolve(args.projectDir ?? process.cwd());
+  const projectDir = path9.resolve(args.projectDir ?? process.cwd());
   const meta3 = readAppMeta(projectDir);
   warnAboutDevLink(projectDir, "dev");
   writeAppDts(projectDir, { workflows: meta3.workflows, queries: meta3.queries, agents: meta3.agents });
@@ -72099,7 +73792,7 @@ async function appAgentSet(client, args) {
   const declared = meta3.agents?.[args.alias];
   const hasDeclaration = declared?.inputs !== void 0 || declared?.outputs !== void 0;
   const file2 = agentFilePath2(projectDir, args.alias);
-  const hasProse = fs6.existsSync(file2);
+  const hasProse = fs8.existsSync(file2);
   if (!hasProse) {
     if (isNew) {
       console.error(
@@ -72110,16 +73803,16 @@ async function appAgentSet(client, args) {
     }
     if (!hasDeclaration) {
       console.error(
-        `No instructions at ${path7.relative(projectDir, file2)}, and nothing declared in package.json#lotics.agents.${args.alias} to push instead.
+        `No instructions at ${path9.relative(projectDir, file2)}, and nothing declared in package.json#lotics.agents.${args.alias} to push instead.
   Run 'lotics app pull ${meta3.app_id}' to write ${AGENTS_DIR}/${args.alias}.md, then edit it.`
       );
       process.exit(1);
     }
   }
-  const instructions = hasProse ? stripAgentHeader(fs6.readFileSync(file2, "utf-8")) : void 0;
+  const instructions = hasProse ? stripAgentHeader(fs8.readFileSync(file2, "utf-8")) : void 0;
   if (instructions === "") {
     console.error(
-      `${path7.relative(projectDir, file2)} is empty after stripping the header \u2014 refusing to push an empty prompt.`
+      `${path9.relative(projectDir, file2)} is empty after stripping the header \u2014 refusing to push an empty prompt.`
     );
     process.exit(1);
   }
@@ -72151,6 +73844,27 @@ async function appAgentSet(client, args) {
     // The verb is the one line that says which of the two just happened.
     `${isNew ? "Created" : "Set"} agent "${args.alias}" (${pushed.join(", ")}` + (live?.model_tier ? `, ${live.model_tier}` : "") + (isNew ? `). Nothing else is declared yet \u2014 set tool_names / knowledge_doc_ids / query_aliases with set_app_agent.` : `). Everything else left as it is.`)
   );
+  const UNSENT = [
+    "tool_names",
+    "query_aliases",
+    "workflow_aliases",
+    "knowledge_doc_ids",
+    "model_tier",
+    "effort_level"
+  ];
+  const same = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+  const liveFields = { ...live };
+  const carried = UNSENT.filter(
+    (f) => declared?.[f] !== void 0 && !same(declared[f], liveFields[f])
+  );
+  if (!isNew && carried.length > 0) {
+    console.error(
+      `  Not sent: ${carried.join(", ")} \u2014 this command pushes prose, inputs and outputs only.
+  Edit one of those in package.json and nothing moves. To change it:
+    lotics run set_app_agent '{"app_id":"${meta3.app_id}","alias":"${args.alias}","<field>":\u2026}'
+  then \`lotics app pull\`.`
+    );
+  }
 }
 async function appWorkflowSet(client, args) {
   const projectDir = args.projectDir ?? process.cwd();
@@ -72163,18 +73877,18 @@ async function appWorkflowSet(client, args) {
     process.exit(1);
   }
   const file2 = workflowFilePath(projectDir, args.alias);
-  if (!fs6.existsSync(file2)) {
+  if (!fs8.existsSync(file2)) {
     console.error(
-      `No workflow body at ${path7.relative(projectDir, file2)}.
+      `No workflow body at ${path9.relative(projectDir, file2)}.
   If "${args.alias}" is already bound:  lotics app pull ${meta3.app_id}   (writes the body)
   If it is a NEW alias you declared:    create that file yourself, then re-run this.`
     );
     process.exit(1);
   }
   noteScope({ alias: args.alias });
-  const source = stripWorkflowHeader(fs6.readFileSync(file2, "utf-8"));
+  const source = stripWorkflowHeader(fs8.readFileSync(file2, "utf-8"));
   if (source.trim() === "") {
-    console.error(`Workflow body ${path7.relative(projectDir, file2)} is empty after stripping the header.`);
+    console.error(`Workflow body ${path9.relative(projectDir, file2)} is empty after stripping the header.`);
     process.exit(1);
   }
   const res = await client.setAppWorkflow(meta3.app_id, args.alias, {
@@ -72307,15 +74021,15 @@ async function appWorkflowCheck(args) {
   for (const alias of aliases) {
     const bodyPath = workflowFilePath(projectDir, alias);
     const globalsPath = workflowGlobalsPath(projectDir, alias);
-    if (!fs6.existsSync(bodyPath)) {
+    if (!fs8.existsSync(bodyPath)) {
       console.error(
-        `\u26A0 Skipped "${alias}" \u2014 no body at ${path7.relative(projectDir, bodyPath)}. Run 'lotics app workflow pull' to write it.`
+        `\u26A0 Skipped "${alias}" \u2014 no body at ${path9.relative(projectDir, bodyPath)}. Run 'lotics app workflow pull' to write it.`
       );
       continue;
     }
-    if (!fs6.existsSync(globalsPath)) {
+    if (!fs8.existsSync(globalsPath)) {
       console.error(
-        `Cannot check "${alias}" \u2014 missing types at ${path7.relative(projectDir, globalsPath)}. Run 'lotics app workflow pull' (or 'lotics app codegen') to fetch them.`
+        `Cannot check "${alias}" \u2014 missing types at ${path9.relative(projectDir, globalsPath)}. Run 'lotics app workflow pull' (or 'lotics app codegen') to fetch them.`
       );
       process.exit(1);
     }
@@ -72334,7 +74048,7 @@ async function appWorkflowCheck(args) {
 function printWorkflowCheckResults(projectDir, results) {
   let totalErrors = 0;
   for (const r of results) {
-    const rel = path7.relative(projectDir, r.bodyPath);
+    const rel = path9.relative(projectDir, r.bodyPath);
     if (r.issues.length === 0) {
       console.error(`\u2713 ${r.alias} (${rel}) \u2014 clean`);
       continue;
@@ -72546,11 +74260,11 @@ async function validateOrgWorkspacePin(client, orgId, profile) {
 }
 
 // src/xlsx.ts
-import fs8 from "node:fs";
+import fs10 from "node:fs";
 
 // src/file_command_io.ts
-import fs7 from "node:fs";
-import path8 from "node:path";
+import fs9 from "node:fs";
+import path10 from "node:path";
 var CliError = class extends Error {
   constructor(message2) {
     super(message2);
@@ -72571,14 +74285,14 @@ function rejectExtraArgs(rest2, arity, usage) {
   fail2(`${usage} takes ${arity} argument${arity === 1 ? "" : "s"} after <file>, got ${rest2.length}. Unused: ${rest2.slice(arity).join(" ")}`);
 }
 function writeFileAtomic(filePath, bytes) {
-  const dir = path8.dirname(path8.resolve(filePath));
-  const tmp = path8.join(dir, `.${path8.basename(filePath)}.${process.pid}.${Date.now()}.tmp`);
-  fs7.writeFileSync(tmp, bytes);
+  const dir = path10.dirname(path10.resolve(filePath));
+  const tmp = path10.join(dir, `.${path10.basename(filePath)}.${process.pid}.${Date.now()}.tmp`);
+  fs9.writeFileSync(tmp, bytes);
   try {
-    fs7.renameSync(tmp, filePath);
+    fs9.renameSync(tmp, filePath);
   } catch (error52) {
     try {
-      fs7.unlinkSync(tmp);
+      fs9.unlinkSync(tmp);
     } catch {
     }
     throw error52;
@@ -75375,16 +77089,16 @@ var MatcherView = class {
    * @returns {string|undefined}
    */
   getCurrentTag() {
-    const path10 = this._matcher.path;
-    return path10.length > 0 ? path10[path10.length - 1].tag : void 0;
+    const path12 = this._matcher.path;
+    return path12.length > 0 ? path12[path12.length - 1].tag : void 0;
   }
   /**
    * Get current namespace.
    * @returns {string|undefined}
    */
   getCurrentNamespace() {
-    const path10 = this._matcher.path;
-    return path10.length > 0 ? path10[path10.length - 1].namespace : void 0;
+    const path12 = this._matcher.path;
+    return path12.length > 0 ? path12[path12.length - 1].namespace : void 0;
   }
   /**
    * Get current node's attribute value.
@@ -75392,9 +77106,9 @@ var MatcherView = class {
    * @returns {*}
    */
   getAttrValue(attrName) {
-    const path10 = this._matcher.path;
-    if (path10.length === 0) return void 0;
-    return path10[path10.length - 1].values?.[attrName];
+    const path12 = this._matcher.path;
+    if (path12.length === 0) return void 0;
+    return path12[path12.length - 1].values?.[attrName];
   }
   /**
    * Check if current node has an attribute.
@@ -75402,9 +77116,9 @@ var MatcherView = class {
    * @returns {boolean}
    */
   hasAttr(attrName) {
-    const path10 = this._matcher.path;
-    if (path10.length === 0) return false;
-    const current = path10[path10.length - 1];
+    const path12 = this._matcher.path;
+    if (path12.length === 0) return false;
+    const current = path12[path12.length - 1];
     return current.values !== void 0 && attrName in current.values;
   }
   /**
@@ -75430,18 +77144,18 @@ var MatcherView = class {
    * @returns {number}
    */
   getPosition() {
-    const path10 = this._matcher.path;
-    if (path10.length === 0) return -1;
-    return path10[path10.length - 1].position ?? 0;
+    const path12 = this._matcher.path;
+    if (path12.length === 0) return -1;
+    return path12[path12.length - 1].position ?? 0;
   }
   /**
    * Get current node's repeat counter (occurrence count of this tag name).
    * @returns {number}
    */
   getCounter() {
-    const path10 = this._matcher.path;
-    if (path10.length === 0) return -1;
-    return path10[path10.length - 1].counter ?? 0;
+    const path12 = this._matcher.path;
+    if (path12.length === 0) return -1;
+    return path12[path12.length - 1].counter ?? 0;
   }
   /**
    * Get current node's sibling index (alias for getPosition).
@@ -81099,10 +82813,10 @@ function resolveRelativePath(basePath, relativePath) {
   }
   return resolved.join("/");
 }
-function findZipEntry(zipEntries, path10) {
-  if (zipEntries[path10]) return zipEntries[path10];
-  if (zipEntries[`xl/${path10}`]) return zipEntries[`xl/${path10}`];
-  const noSlash = path10.replace(/^\//, "");
+function findZipEntry(zipEntries, path12) {
+  if (zipEntries[path12]) return zipEntries[path12];
+  if (zipEntries[`xl/${path12}`]) return zipEntries[`xl/${path12}`];
+  const noSlash = path12.replace(/^\//, "");
   if (zipEntries[noSlash]) return zipEntries[noSlash];
   return void 0;
 }
@@ -82734,9 +84448,9 @@ function parseExcelFromZip(zip, options) {
   }
   return result;
 }
-function findEntry(zip, path10) {
-  if (zip[path10]) return zip[path10];
-  const lower2 = path10.toLowerCase();
+function findEntry(zip, path12) {
+  if (zip[path12]) return zip[path12];
+  const lower2 = path12.toLowerCase();
   for (const key of Object.keys(zip)) {
     if (key.toLowerCase() === lower2) return zip[key];
   }
@@ -83373,12 +85087,12 @@ function extractPivotRoundTripInfo(originalZip) {
     if (paths.length > 0) pivotTablesBySheetIndex.set(i2, paths);
   }
   const pivotXmlPaths = [];
-  for (const path10 of Object.keys(originalZip)) {
-    if (path10.startsWith("xl/pivotTables/") && path10.endsWith(".xml")) {
-      pivotXmlPaths.push(path10);
+  for (const path12 of Object.keys(originalZip)) {
+    if (path12.startsWith("xl/pivotTables/") && path12.endsWith(".xml")) {
+      pivotXmlPaths.push(path12);
     }
-    if (path10.startsWith("xl/pivotCache/") && path10.endsWith(".xml")) {
-      pivotXmlPaths.push(path10);
+    if (path12.startsWith("xl/pivotCache/") && path12.endsWith(".xml")) {
+      pivotXmlPaths.push(path12);
     }
   }
   return { cachesByWorkbook, pivotTablesBySheetIndex, pivotXmlPaths };
@@ -83386,15 +85100,15 @@ function extractPivotRoundTripInfo(originalZip) {
 function decode3(bytes) {
   return new TextDecoder().decode(bytes);
 }
-function pivotContentTypeFor(path10) {
-  if (path10.startsWith("xl/pivotTables/") && path10.endsWith(".xml")) {
-    return `<Override PartName="/${path10}" ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.pivotTable+xml"/>`;
+function pivotContentTypeFor(path12) {
+  if (path12.startsWith("xl/pivotTables/") && path12.endsWith(".xml")) {
+    return `<Override PartName="/${path12}" ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.pivotTable+xml"/>`;
   }
-  if (path10.includes("/pivotCacheDefinition") && path10.endsWith(".xml")) {
-    return `<Override PartName="/${path10}" ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.pivotCacheDefinition+xml"/>`;
+  if (path12.includes("/pivotCacheDefinition") && path12.endsWith(".xml")) {
+    return `<Override PartName="/${path12}" ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.pivotCacheDefinition+xml"/>`;
   }
-  if (path10.includes("/pivotCacheRecords") && path10.endsWith(".xml")) {
-    return `<Override PartName="/${path10}" ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.pivotCacheRecords+xml"/>`;
+  if (path12.includes("/pivotCacheRecords") && path12.endsWith(".xml")) {
+    return `<Override PartName="/${path12}" ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.pivotCacheRecords+xml"/>`;
   }
   return void 0;
 }
@@ -83467,16 +85181,16 @@ function exportWorkbook(workbook, originalZip) {
       regeneratedPaths.add(`xl/worksheets/sheet${i2 + 1}.xml`);
       regeneratedPaths.add(`xl/worksheets/_rels/sheet${i2 + 1}.xml.rels`);
     }
-    for (const path10 of Object.keys(originalZip)) {
-      if (path10.startsWith("xl/drawings/") || path10.startsWith("xl/charts/") || path10.startsWith("xl/tables/") || path10.startsWith("xl/media/")) {
-        regeneratedPaths.add(path10);
+    for (const path12 of Object.keys(originalZip)) {
+      if (path12.startsWith("xl/drawings/") || path12.startsWith("xl/charts/") || path12.startsWith("xl/tables/") || path12.startsWith("xl/media/")) {
+        regeneratedPaths.add(path12);
       }
     }
-    for (const [path10, data2] of Object.entries(originalZip)) {
-      if (regeneratedPaths.has(path10)) continue;
-      const ext = path10.slice(path10.lastIndexOf(".") + 1).toLowerCase();
+    for (const [path12, data2] of Object.entries(originalZip)) {
+      if (regeneratedPaths.has(path12)) continue;
+      const ext = path12.slice(path12.lastIndexOf(".") + 1).toLowerCase();
       if (!DECLARED_EXTENSIONS.includes(ext)) continue;
-      entries2[path10] = data2;
+      entries2[path12] = data2;
     }
   }
   const sharedStrings = buildSharedStrings(workbook);
@@ -83492,8 +85206,8 @@ function exportWorkbook(workbook, originalZip) {
     buildWorkbookRels(workbook, pivotInfo)
   );
   const extraContentTypes = [];
-  for (const path10 of pivotInfo.pivotXmlPaths) {
-    const ct = pivotContentTypeFor(path10);
+  for (const path12 of pivotInfo.pivotXmlPaths) {
+    const ct = pivotContentTypeFor(path12);
     if (ct) extraContentTypes.push(ct);
   }
   let globalChartIndex = 1;
@@ -92518,14 +94232,14 @@ var DependencyGraph = class {
       stack.push({ cell: p, path: [cell, p] });
     }
     while (stack.length > 0) {
-      const { cell: current, path: path10 } = stack.pop();
-      if (current === cell) return path10;
+      const { cell: current, path: path12 } = stack.pop();
+      if (current === cell) return path12;
       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: [...path10, p] });
+        stack.push({ cell: p, path: [...path12, p] });
       }
     }
     return null;
@@ -93737,8 +95451,8 @@ var SIMPLE_SHEET_KEYS = /* @__PURE__ */ new Set(["name", "cells", "merges", "fre
 var MAX_COLUMN = 16384;
 var MAX_ROW = 1048576;
 function loadFile(filePath) {
-  if (!fs8.existsSync(filePath)) fail2(`File not found: ${filePath}`);
-  const buffer = fs8.readFileSync(filePath);
+  if (!fs10.existsSync(filePath)) fail2(`File not found: ${filePath}`);
+  const buffer = fs10.readFileSync(filePath);
   const arrayBuffer = buffer.buffer.slice(buffer.byteOffset, buffer.byteOffset + buffer.byteLength);
   const originalZip = unzipXlsx(arrayBuffer);
   const parsed = parseExcelBuffer(arrayBuffer);
@@ -93788,7 +95502,7 @@ function lazyEngine(workbook) {
   };
 }
 function readToJson(filePath, filter3, opts) {
-  const buffer = fs8.readFileSync(filePath);
+  const buffer = fs10.readFileSync(filePath);
   const arrayBuffer = buffer.buffer.slice(buffer.byteOffset, buffer.byteOffset + buffer.byteLength);
   const parsed = parseExcelBuffer(arrayBuffer);
   let sheets = parsed.sheets;
@@ -94301,7 +96015,7 @@ async function runXlsxCommand(subcommand, toolArgs, restArgs) {
 }
 
 // src/docx.ts
-import fs9 from "node:fs";
+import fs11 from "node:fs";
 
 // ../ooxml/src/doc/errors.ts
 var DocParseError = class extends Error {
@@ -98917,8 +100631,8 @@ async function docModelToDocx(model) {
 // ../ooxml/src/opc.ts
 var import_jszip = __toESM(require_lib4(), 1);
 function dropFolderEntries(zip) {
-  for (const [path10, entry] of Object.entries(zip.files)) {
-    if (entry.dir) delete zip.files[path10];
+  for (const [path12, entry] of Object.entries(zip.files)) {
+    if (entry.dir) delete zip.files[path12];
   }
 }
 
@@ -99150,11 +100864,11 @@ async function parseDocx(buffer) {
   const zip = await import_jszip3.default.loadAsync(buffer);
   const parts = /* @__PURE__ */ new Map();
   const filePromises = [];
-  zip.forEach((path10, file2) => {
+  zip.forEach((path12, file2) => {
     if (file2.dir) return;
     filePromises.push(
       file2.async("uint8array").then((bytes) => {
-        parts.set(path10, bytes);
+        parts.set(path12, bytes);
       })
     );
   });
@@ -99386,9 +101100,9 @@ var DEFAULT_PARTS = [
   ["word/theme/theme1.xml", () => encoder.encode(THEME_XML)]
 ];
 function fillDefaultParts(parts) {
-  for (const [path10, makeBytes] of DEFAULT_PARTS) {
-    if (!parts.has(path10)) {
-      parts.set(path10, makeBytes());
+  for (const [path12, makeBytes] of DEFAULT_PARTS) {
+    if (!parts.has(path12)) {
+      parts.set(path12, makeBytes());
     }
   }
   return parts;
@@ -99398,9 +101112,9 @@ function fillDefaultParts(parts) {
 async function serializeDocx(doc) {
   const zip = new import_jszip4.default();
   const parts = fillDefaultParts(new Map(doc.parts));
-  for (const [path10, bytes] of parts) {
-    if (path10 === "word/document.xml") continue;
-    zip.file(path10, bytes);
+  for (const [path12, bytes] of parts) {
+    if (path12 === "word/document.xml") continue;
+    zip.file(path12, bytes);
   }
   const documentXml = serializeDocumentXml(doc);
   zip.file("word/document.xml", documentXml);
@@ -99487,8 +101201,8 @@ var DEFAULT_DOC_ATTRS = {
   "@_xmlns:w": "http://schemas.openxmlformats.org/wordprocessingml/2006/main"
 };
 async function loadFile2(filePath) {
-  if (!fs9.existsSync(filePath)) fail2(`File not found: ${filePath}`);
-  const bytes = fs9.readFileSync(filePath);
+  if (!fs11.existsSync(filePath)) fail2(`File not found: ${filePath}`);
+  const bytes = fs11.readFileSync(filePath);
   if (isLegacyDoc(bytes)) {
     const upgraded = await saveDocxToBuffer(await loadDocxFromBuffer(bytes));
     return parseDocx(new Uint8Array(upgraded));
@@ -99973,10 +101687,10 @@ async function runDocxCommand(subcommand, toolArgs, restArgs) {
 }
 
 // src/knowledge.ts
-import fs10 from "node:fs";
+import fs12 from "node:fs";
 function readBodyFile(filePath) {
-  if (!fs10.existsSync(filePath)) fail2(`File not found: ${filePath}`);
-  return fs10.readFileSync(filePath, "utf-8");
+  if (!fs12.existsSync(filePath)) fail2(`File not found: ${filePath}`);
+  return fs12.readFileSync(filePath, "utf-8");
 }
 function resolveBody(flags, required2) {
   if (flags.from !== void 0 && flags.content !== void 0) {
@@ -100120,9 +101834,9 @@ 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 { join as join2, dirname, resolve, extname, basename } from "node:path";
-import { fileURLToPath as fileURLToPath2 } from "node:url";
+import { fileURLToPath as fileURLToPath3 } from "node:url";
 import { setTimeout as sleep2 } from "node:timers/promises";
-var HERE = dirname(fileURLToPath2(import.meta.url));
+var HERE = dirname(fileURLToPath3(import.meta.url));
 function fail3(msg) {
   console.error(msg);
   process.exit(1);
@@ -100353,84 +102067,7 @@ USAGE
   Query tools return IDs used as arguments to other tools.
 
 COMMANDS
-  lotics org                           List saved orgs (marks active)
-  lotics org use <name|id> [--local]   Switch active org (--local pins this dir)
-  lotics workspace                     List workspaces in the active org (marks current)
-  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 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 \u2014 COMMIT
-                                       (-m is required \u2014 it's the version's audit trail;
-                                       carries code + queries only \u2014 workflow bindings are
-                                       managed by set_app_workflow / remove_app_workflow)
-  lotics app versions [app_id]         Show deploy history newest-first (version,
-                                       timestamp, deployer, build status, -m message;
-                                       * marks the currently served version)
-  lotics app codegen [path]            Regenerate .lotics/* (types + field/option ids)
-                                       from the manifest + workspace schema \u2014 no deploy
-  lotics app check                     Run every deploy pre-flight WITHOUT building or
-                                       shipping: agent schemas vs the live app, workflow
-                                       declarations and BODIES vs what is live, aliases
-                                       the code calls but nothing bound, undeclared
-                                       capabilities, query drift. Exits 1 on what a
-                                       deploy would refuse, so CI can gate on it
-  lotics app workflow run <alias> '<json>'  Execute a bound app workflow end-to-end
-                                       (inputs: inline JSON, @file, or stdin;
-                                        --print-created reports created records +
-                                        a paste-ready cleanup plan; --cleanup also
-                                        deletes those records \u2014 NOT a rollback)
-  lotics app workflow set <alias>      Push the edited src/workflows/<alias>.ts body
-                                       through set_app_workflow (server verifies)
-  lotics app workflow pull             Rewrite src/workflows/*.ts from the server
-  lotics app workflow check [alias]    Typecheck src/workflows bodies locally (one
-                                       isolated program per alias; the app's own tsc)
-  lotics app query set <alias>         Push package.json#lotics.queries.<alias> to
-                                       apps.queries via set_app_query (no deploy;
-                                       re-synced by the next deploy from the manifest)
-  lotics app agent run <app_id> <alias> '<json>'  Run a bound app agent end-to-end
-                                       (inputs: inline JSON, @file, or stdin; streams
-                                        progress to stderr, reports the settled run;
-                                        --session <id> continues a thread; --json)
-  lotics app agent set <alias>         Push the edited src/agents/<alias>.md instructions,
-                                       and ONLY those \u2014 the server merges, so the typed
-                                       fields keep whatever is bound (a manifest is a
-                                       snapshot; replaying it would revert them). Change
-                                       those with set_app_agent, then pull.
-  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 knowledge list                List knowledge docs (id, name, description)
-  lotics knowledge create --name <n> [--description <d>] --from <file.md>
-                                       Create a doc from a file (or --content <str>);
-                                       prints the new id
-  lotics knowledge get <id> [-o <file.md>]
-                                       Fetch a doc's content (to a file, or stdout;
-                                       --json for the full doc)
-  lotics knowledge update <id> [--from <file.md> | --content <str>] [--name <n>] [--description <d>]
-                                       Update a doc \u2014 sends only the fields you pass
-  lotics knowledge rm <id>             Archive a doc
-  lotics xlsx <subcommand> ...         Read/write/edit .xlsx files on your local filesystem
-                                       (uses the bundled Lotics xlsx engine; prefer over
-                                       npm xlsx/exceljs for round-trip fidelity)
-  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|fil_id> [-o png]
-                                       Render a .docx/.xlsx to a PNG \u2014 a local path OR a
-                                       stored file id (downloaded first). Frontend engines;
-                                       needs a Chrome/Chromium on the machine
+${renderCommandsHelp()}
 
 FLAGS
   --json             Full JSON output (default is human-readable text)
@@ -100527,8 +102164,8 @@ function prompt(question) {
     });
   });
 }
-async function publicPost(path10, body) {
-  const response = await fetch(`${API_BASE_URL}${path10}`, {
+async function publicPost(path12, body) {
+  const response = await fetch(`${API_BASE_URL}${path12}`, {
     method: "POST",
     headers: { "Content-Type": "application/json" },
     body: JSON.stringify(body)
@@ -100653,7 +102290,7 @@ function announceTarget(ctx, workspaceId) {
   console.error(`lotics \u2192 ${org} / ${workspaceId}`);
 }
 function appManifestWorkspaceId(command, subcommand, pathArg, flags) {
-  if (command !== "app") return void 0;
+  if (command !== "app" && command !== "upgrade") return void 0;
   if (flags.workspace || process.env.LOTICS_WORKSPACE) return void 0;
   if (subcommand === "create" || subcommand === "pull") return void 0;
   const dir = pathArg && !pathArg.startsWith("-") ? pathArg : process.cwd();
@@ -100696,13 +102333,13 @@ async function resolveWorkspace(client, ctx) {
 function resolveUploadPaths(rawPaths) {
   const result = [];
   for (const p of rawPaths) {
-    const resolved = path9.resolve(p);
-    const stat = fs11.statSync(resolved);
+    const resolved = path11.resolve(p);
+    const stat = fs13.statSync(resolved);
     if (stat.isDirectory()) {
-      const entries2 = fs11.readdirSync(resolved, { withFileTypes: true });
+      const entries2 = fs13.readdirSync(resolved, { withFileTypes: true });
       for (const entry of entries2) {
         if (entry.isFile()) {
-          result.push(path9.join(resolved, entry.name));
+          result.push(path11.join(resolved, entry.name));
         }
       }
     } else {
@@ -100726,14 +102363,90 @@ async function main() {
     subcommand = toolArgs;
     toolArgs = restArgs.shift();
   }
+  if (flags.help && command === "report") {
+    console.error(REPORT_USAGE);
+    return;
+  }
   if (flags.help || !command && !flags.version) {
     printHelp();
     return;
   }
+  if (flags.version && command !== void 0) {
+    console.error(
+      `--version prints this CLI's version and takes no argument; it cannot be combined with a command.
+  The CLI version:            lotics --version
+  A package version to take:  operator-only for now \u2014 \`lotics upgrade\` takes the next release.`
+    );
+    process.exit(1);
+  }
   if (flags.version) {
     console.log(VERSION);
     return;
   }
+  if (command === "install") {
+    if (!subcommand) {
+      console.error("Usage: lotics install <package_id>");
+      console.error("       Materializes a published package into the current workspace.");
+      process.exit(1);
+    }
+    const { client: client2, ctx: ctx2 } = requireClient(flags);
+    await resolveWorkspace(client2, ctx2);
+    await installCommand(client2, { packageId: subcommand });
+    return;
+  }
+  if (command === "upgrade") {
+    const { client: client2, ctx: ctx2 } = requireClient(flags);
+    applyAppManifestWorkspace(ctx2, command, subcommand, void 0, flags);
+    await resolveWorkspace(client2, ctx2);
+    await upgradeCommand(client2, {});
+    return;
+  }
+  if (command === "docs") {
+    docsCommand({ area: subcommand });
+    return;
+  }
+  if (command === "report") {
+    let input = subcommand ?? "";
+    if (input.startsWith("@")) {
+      const file2 = input.slice(1);
+      if (!fs13.existsSync(file2)) {
+        console.error(`No such file: ${file2}`);
+        process.exit(1);
+      }
+      input = fs13.readFileSync(file2, "utf-8");
+    } else if (input === "-") {
+      input = await readStdin();
+    }
+    if (input.trim() === "") {
+      console.error(REPORT_USAGE);
+      process.exit(1);
+    }
+    const parsed2 = parseReport(input);
+    if ("error" in parsed2) {
+      console.error(`${parsed2.error}
+`);
+      console.error(REPORT_USAGE);
+      process.exit(1);
+    }
+    const reportCtx = resolveContext(flags);
+    if (!reportCtx) {
+      console.error(
+        'Not authenticated, so this could not be sent. Run "lotics auth signup", "lotics auth api-key <key>", or set LOTICS_API_KEY.'
+      );
+      echoReport(parsed2.report);
+      process.exit(1);
+    }
+    noteScope({ org_id: reportCtx.orgId ?? void 0, workspace_id: reportCtx.workspaceId });
+    await reportCommand(
+      new LoticsClient({ apiKey: reportCtx.apiKey, workspaceId: reportCtx.workspaceId }),
+      {
+        report: parsed2.report,
+        version: VERSION,
+        workspaceId: reportCtx.workspaceId
+      }
+    );
+    return;
+  }
   if (command === "auth") {
     if (subcommand === "signup") {
       await handleSignup(toolArgs, flags);
@@ -100827,13 +102540,13 @@ async function main() {
   if (command === "preview") {
     if (subcommand && isStoredFileId(subcommand)) {
       const { client: client2 } = requireClient(flags);
-      const tmpDir = fs11.mkdtempSync(path9.join(os4.tmpdir(), "lotics-preview-"));
+      const tmpDir = fs13.mkdtempSync(path11.join(os4.tmpdir(), "lotics-preview-"));
       try {
         const { path: localPath, filename } = await client2.downloadFileById(subcommand, tmpDir);
         const output = flags.output ?? defaultPreviewOutputPath(filename, process.cwd());
         await runPreviewCommand(localPath, { output });
       } finally {
-        fs11.rmSync(tmpDir, { recursive: true, force: true });
+        fs13.rmSync(tmpDir, { recursive: true, force: true });
       }
       return;
     }
@@ -100916,9 +102629,12 @@ async function main() {
     }
     return;
   }
-  if (command !== "tools" && command !== "upload" && command !== "run" && command !== "download" && command !== "workspace" && command !== "app" && command !== "knowledge") {
+  if (!knownVerbs().has(command ?? "")) {
     console.error(`Unknown command: ${command}`);
-    console.error('Run "lotics --help" for usage.');
+    console.error('Run "lotics --help" for usage \u2014 read \xA7 COMMANDS whole, not a grep.');
+    console.error(
+      `If Lotics genuinely cannot do this yet, say so \u2014 run \`lotics report\` for the frame.`
+    );
     process.exit(1);
   }
   if (command === "app" && !subcommand) {
@@ -101172,7 +102888,7 @@ Available workspaces:`);
         const ingested = await ingestJsonArgs({
           rawArg: restArgs[1],
           stdinIsTTY: process.stdin.isTTY ?? false,
-          readFile: (p) => fs11.readFileSync(p, "utf-8"),
+          readFile: (p) => fs13.readFileSync(p, "utf-8"),
           readStdin
         });
         if (ingested.kind === "error") {
@@ -101223,7 +102939,7 @@ Available workspaces:`);
         const ingested = await ingestJsonArgs({
           rawArg: restArgs[2],
           stdinIsTTY: process.stdin.isTTY ?? false,
-          readFile: (p) => fs11.readFileSync(p, "utf-8"),
+          readFile: (p) => fs13.readFileSync(p, "utf-8"),
           readStdin
         });
         if (ingested.kind === "error") {
@@ -101379,7 +103095,7 @@ ${JSON.stringify(info.input_schema, null, 2)}`);
     const ingested = await ingestJsonArgs({
       rawArg: toolArgs,
       stdinIsTTY: process.stdin.isTTY ?? false,
-      readFile: (p) => fs11.readFileSync(p, "utf-8"),
+      readFile: (p) => fs13.readFileSync(p, "utf-8"),
       readStdin
     });
     if (ingested.kind === "error") {