@lotics/cli 0.182.0 → 0.184.0

package/AGENTS.md

@@ -5,7 +5,7 @@ conventions are, and where the traps are.
 
 | Read | For |
 |---|---|
-| `lotics --help` | The verb inventory (§ COMMANDS) and global flags. Authoritative; never stale. |
+| `lotics --help` | The verb inventory (§ COMMANDS) and global flags. The verb LIST is generated and never stale; the prose beside each verb is hand-written, so where it disagrees with `docs/cli_reference.md`, the reference wins. |
 | `lotics tools` · `lotics tools <name>` | The agent tool registry and one tool's full JSON Schema. |
 | `lotics docs` · `lotics docs <area>` | Every reference the packages installed beside the project actually ship — `@lotics/app-sdk`, `@lotics/ui` and the document engines each carry their own, and this index only covers THIS package. Discovered by looking, not by a list, so it reports the installed VERSION of each: a doc always describes the code that is really there. |
 | [docs/building_an_app.md](./docs/building_an_app.md) | The SEQUENCE — scaffold, model, types, queries, workflows, screens, ship — and the deploy-free inner loop. The other references describe contracts; this one is the order they go in and why. Read it once before starting an app. |
@@ -29,7 +29,8 @@ Several capabilities exist **only** as commands and appear nowhere in `lotics to
 file and running a bound app agent are the two that most often get mistaken for missing. Concluding
 "the platform can't do X" from the tool list alone is a mistake; check both.
 
-⚠️ **`lotics <subcommand> --help` prints the generic top-level help.** It does not describe the
+⚠️ **`lotics <subcommand> --help` prints the generic top-level help**, except `lotics report --help`
+and a bare `lotics auth` / `xlsx` / `docx`, which print their own. It does not describe the
 subcommand, so an unhelpful response there is *not* evidence the subcommand is absent. To find out
 whether something exists, read `lotics --help` § COMMANDS — the whole section, not a narrow grep.
 
@@ -37,8 +38,9 @@ whether something exists, read `lotics --help` § COMMANDS — the whole section
 
 - **Scope is resolved per invocation.** `LOTICS_ORG` / `LOTICS_WORKSPACE` (or `LOTICS_API_KEY`) scope a
   single call without changing the active org or a directory pin — the safe way to touch one tenant
-  from a shell serving many. Every command echoes its resolved target to **stderr** (`lotics → <org> /
-  <workspace>`); read it back before trusting a write. Resolution precedence is in README § Organizations.
+  from a shell serving many. Every command that resolves a workspace echoes its target to **stderr**
+  (`lotics → <org> / <workspace>`); read it back before trusting a write. `file preview <fil_…>` is
+  the one credentialed command with no echo. Resolution precedence is in README § Organizations.
 - **Large payloads bypass `ARG_MAX`** — `lotics run <tool> @args.json` or piped stdin. A leading `@` is
   unambiguously a file path (JSON args start with `{`).
 - **stdout is the payload, stderr is the narration.** Progress, status lines, and the target echo go to
@@ -48,7 +50,8 @@ whether something exists, read `lotics --help` § COMMANDS — the whole section
   (`run_app_workflow`, `run_app_agent`, `run_app_query`). An `app` command exists only for work no
   tool call can do: scaffold, build, typecheck, serve, or read and push a local file.
 - **Exit codes are assertable, and they report the WORK rather than the call.** `lotics run` exits
-  non-zero when the result's own envelope carries a failed `status` (`error`/`failed`/`cancelled`),
+  non-zero when a `run_app_workflow` or `run_app_agent` result's own envelope carries a failed
+  `status` (`error`/`failed`/`cancelled`) — any other tool's top-level status is data and exits 0 —
   so `lotics run … && next-step` cannot walk past a refused run; `workspace doctor` exits non-zero on
   findings. An unrecognized status exits 0 — the list is an allowlist of failure, so a status added
   later never turns a working script red — and a parked run (`awaiting_input`) is not a failure.
@@ -88,11 +91,11 @@ whether something exists, read `lotics --help` § COMMANDS — the whole section
   | `queries`, `capabilities` | the manifest | `app deploy` — re-synced on every one (an absent `capabilities` block turns them all OFF) |
   | `knowledge` | the manifest | nothing, until the app is published as a starter — it declares which docs ship with it |
   | `workflows` | the workflow row's verified contract | `app workflow set`, which type-checks the BODY against your declaration and refuses a schema the body cannot satisfy |
-  | `agents` | the app row | **nothing.** It is a mirror: `app codegen` re-silvers it from the app, and an agent is changed with `set_app_agent` |
+  | `agents` | `inputs`/`outputs`: the manifest. Everything else: the app row | `app agent set`, and `app deploy`, which pushes a diverged `inputs`/`outputs` before it ships. The rest is a mirror `app codegen` re-silvers, changed with `set_app_agent` |
 
-  `agents` is the one that bites, because editing a mirror still retypes `useAgentRun` — green
-  locally, unchanged in production. `app codegen` reverts such an edit and `app deploy` refuses while
-  the two disagree. An agent's PROSE is not in the manifest at all: it lives in
-  `src/agents/<alias>.md` and is pushed by `app agent set`.
+  `agents` is the one that bites, because the two halves of the same block behave differently:
+  editing `tool_names` or `knowledge_doc_ids` still retypes `useAgentRun` — green locally, unchanged
+  in production, and reverted by the next `app codegen`. An agent's PROSE is not in the manifest at
+  all: it lives in `src/agents/<alias>.md` and is pushed by `app agent set`.
 - **OAuth connections.** Attaching a connected account is web-only; the CLI can list them.
 - **Anything needing a browser.** `app dev` and `file preview` shell out to a local Chrome.

package/README.md

@@ -70,7 +70,7 @@ irm https://lotics.ai/install.ps1 | iex           # Windows PowerShell — no No
 Re-run whichever installer you used; `npm install -g @lotics/cli@latest` updates an npm install.
 The CLI names the right one for the copy you are running when it sees a newer version.
 
-The CLI checks for updates once per day and prompts when a new version is available.
+The CLI checks for updates once per day and prints a note on stderr, naming the right installer, when a new version is available.
 
 ## Authentication
 
@@ -94,7 +94,7 @@ lotics auth api-key                  # interactive prompt
 lotics auth api-key ltk_...          # registers the key's org as a profile (now active)
 ```
 
-Run `lotics auth logout [<name|id>]` to remove a profile (default: the active org), or `lotics auth logout --all` to wipe the store.
+Run `lotics auth logout [<name|id>]` to remove a profile (default: the active org), or `lotics auth logout --all` to wipe the store. Inside a pinned directory the bare form removes the **pin**, not a profile — name the org to remove its credential.
 
 ## Organizations
 
@@ -120,7 +120,7 @@ lotics workspace select wks_...     # records the workspace in the local pin
 
 Each worktree resolves independently; switching the global default in another shell leaves pinned worktrees untouched. `.lotics/` should be gitignored.
 
-Every command names its target before it acts — `lotics → <org> / <workspace>` on **stderr**, so stdout stays clean for piping. When nothing in the directory or environment chose the org and it came from the machine-wide default, the line says so and prints the `--local` command to pin — that default is the one another shell can move between two of your commands. `lotics auth whoami` reports the same resolution on demand, including which source won.
+Every command that resolves a workspace names its target before it acts — `lotics → <org> / <workspace>` on **stderr**, so stdout stays clean for piping. When nothing in the directory or environment chose the org and it came from the machine-wide default, the line says so and prints the `--local` command to pin — that default is the one another shell can move between two of your commands. `lotics auth whoami` reports the same resolution on demand, including which source won.
 
 ### Resolution precedence
 
@@ -334,7 +334,8 @@ lotics run run_app_agent '{...}' --json              # full run summary to stdou
 # A run that outlives the call's bounded wait keeps going server-side; read it with
 lotics run get_app_agent_run '{"app_id":"app_abc","run_id":"run_..."}'
 
-# Dev-link @lotics/ui to a monorepo checkout for ONE command — nothing is written to disk
+# Dev-link @lotics/ui to a monorepo checkout for ONE command — nothing hand-written is touched
+# (the matching tsc `paths` land in the CLI's own .lotics/tsconfig.link.json)
 LOTICS_UI_SRC=/abs/monorepo/packages/ui/src lotics app dev
 LOTICS_UI_SRC=/abs/monorepo/packages/ui/src lotics app deploy -m "..."   # warns: bundles YOUR kit copy
 lotics app dev                             # unset ⇒ @lotics/ui resolves from node_modules again

package/dist/src/cli.js

@@ -44516,14 +44516,13 @@ var LoticsClient = class {
     return this.request("POST", "/v1/apps", body);
   }
   /**
-   * Retire (or `undo` un-retire) a registry package (backs `lotics app
-   * unpublish` — the endpoint/audit action keep the `retire` name to avoid API
-   * churn). Retiring refuses NEW installs and hides the package from non-owning
-   * orgs; existing installations keep working and may still upgrade. Owner-org
-   * admin-only.
+   * Take a starter off the shelf, or `undo` to put it back (backs `opctl
+   * starter unpublish`). It hides from non-owning orgs and can no longer be
+   * copied; copies already made are unaffected — they never linked back.
+   * Owner-org admin-only.
    */
-  async retirePackage(package_id, body) {
-    return this.request("POST", `/v1/packages/${encodeURIComponent(package_id)}/retire`, body);
+  async unpublishStarter(starter_id, body) {
+    return this.request("POST", `/v1/starters/${encodeURIComponent(starter_id)}/unpublish`, body);
   }
   /**
    * Edit a starter's registry listing — the name and description a stranger
@@ -44532,13 +44531,12 @@ var LoticsClient = class {
    * A version is an immutable snapshot; the listing is not. Omit a field to
    * leave it, pass `description: null` to clear it. Owner-org admin-only.
    */
-  async editPackageListing(package_id, body) {
-    return this.request("POST", `/v1/packages/${encodeURIComponent(package_id)}/listing`, body);
+  async editStarterListing(starter_id, body) {
+    return this.request("POST", `/v1/starters/${encodeURIComponent(starter_id)}/listing`, body);
   }
   // --- Starters (registry reads + copies) ---
-  // Authoring is server-side: apps via the publish job (`requestStarterPublish`),
-  // content starters via the `publish_content`/`release_content` tools. There is
-  // no client-side create-package / upload-bundle path.
+  // Authoring is server-side, through the publish job (`requestStarterPublish`).
+  // There is no client-side create-starter / upload-bundle path.
   /**
    * The starters this organization can copy — Lotics-reviewed ones plus its own,
    * never a catalogue of everything published. The server returns exactly what
@@ -44597,12 +44595,25 @@ var LoticsClient = class {
    * Fetch a registry starter's metadata (`latest_version` and the Lotics-backed
    * `is_official` trust badge). Admin-only; cross-tenant by id.
    */
-  async getPackage(package_id) {
-    return this.request("GET", `/v1/packages/${encodeURIComponent(package_id)}`);
+  async getStarter(starter_id) {
+    return this.request("GET", `/v1/starters/${encodeURIComponent(starter_id)}`);
   }
-  /** Version history newest-first (no contract payloads) — backs `opctl package show`. Admin-only. */
-  async listPackageVersions(package_id) {
-    return this.request("GET", `/v1/packages/${encodeURIComponent(package_id)}/versions`);
+  /** Version history newest-first (no contract payloads) — backs `opctl starter show`. Admin-only. */
+  async listStarterVersions(starter_id) {
+    return this.request("GET", `/v1/starters/${encodeURIComponent(starter_id)}/versions`);
+  }
+  /**
+   * One version's contract — what a copy of it is supposed to produce. The
+   * history above omits it (heavy per row); this is the read that carries it,
+   * so a check compares a copy against the declaration itself rather than
+   * against a description of it. Admin-only; cross-tenant by id like
+   * `getStarter`.
+   */
+  async getStarterVersion(starter_id, version2) {
+    return this.request(
+      "GET",
+      `/v1/starters/${encodeURIComponent(starter_id)}/versions/${encodeURIComponent(String(version2))}`
+    );
   }
   /**
    * Workspace-wide dangling-reference sweep — active app/workflow artifacts
@@ -44671,13 +44682,13 @@ var LoticsClient = class {
         const fields = table.fields.flatMap((field) => {
           if (field === null || typeof field !== "object") return [];
           const f = field;
-          if (typeof f.key !== "string" || typeof f.name !== "string") return [];
+          if (typeof f.key !== "string" || typeof f.name !== "string" || typeof f.type !== "string") return [];
           const options = Array.isArray(f.options) ? f.options.flatMap((opt) => {
             if (opt === null || typeof opt !== "object") return [];
             const o = opt;
             return typeof o.key === "string" && typeof o.name === "string" ? [{ id: o.key, label: o.name }] : [];
           }) : void 0;
-          return [{ id: f.key, name: f.name, ...options && options.length > 0 ? { options } : {} }];
+          return [{ id: f.key, name: f.name, type: f.type, ...options && options.length > 0 ? { options } : {} }];
         });
         return { id: table.id, name: table.name, fields };
       })
@@ -45431,6 +45442,25 @@ function resolveContext(flags, appWorkspaceId) {
   const envOrg = process.env.LOTICS_ORG;
   const envWorkspace = process.env.LOTICS_WORKSPACE;
   const wsOverride = flags.workspace ?? envWorkspace;
+  if (flags.org) {
+    if (flags.apiKey) {
+      throw new Error("Pass --org or --api-key, not both \u2014 they name two different credentials.");
+    }
+    const resolved = resolveProfileByNameOrId(loadGlobalConfig()?.profiles ?? {}, flags.org);
+    if (!resolved) {
+      throw new Error(
+        `--org "${flags.org}" matches no saved credential. Run "lotics org" to list, or "lotics auth api-key <key>" to add one.`
+      );
+    }
+    const [orgId, profile] = resolved;
+    return {
+      apiKey: profile.api_key,
+      orgId,
+      orgName: profile.org_name,
+      workspaceId: wsOverride ?? profile.workspace_id,
+      source: "flag_org"
+    };
+  }
   if (flags.apiKey) {
     return { apiKey: flags.apiKey, workspaceId: wsOverride, source: "flag" };
   }
@@ -45681,7 +45711,7 @@ function resultSideEffects(result) {
 }
 
 // src/version.ts
-var VERSION = "0.182.0";
+var VERSION = "0.184.0";
 
 // src/timezone.ts
 function machineTimezone() {
@@ -45892,7 +45922,8 @@ var COMMANDS = [
       "  lotics starter list                  Starters you can copy into this workspace. Works with",
       "                                       NO account \u2014 it then lists the published shelf, so you",
       "                                       can decide whether to copy one or build before signing up",
-      "  lotics starter show <starter_id>     What one carries: tables, docs, templates, sample data",
+      "  lotics starter show <starter_id>     Its name, description, current version, tile and trust",
+      "                                       standing \u2014 read it before copying one you did not publish",
       "  lotics starter init <starter_id>     Copy it in \u2014 schema, templates, knowledge docs,",
       "                                       sample records and its apps, deployed on Lotics. A",
       "                                       COPY: everything it creates is yours outright, with",
@@ -45915,7 +45946,7 @@ var COMMANDS = [
   {
     verbs: ["docs"],
     help: [
-      "  lotics docs                          List the reference docs of the INSTALLED packages",
+      "  lotics docs                          List the reference docs the npm packages in node_modules ship",
       "  lotics docs <area>                   Print one (e.g. 'lotics docs ai')"
     ]
   },
@@ -45967,8 +45998,10 @@ var COMMANDS = [
       "                                       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",
+      "                                       capabilities, query drift. Plus the one rule no",
+      "                                       deploy runs: a concrete id or an id-shaped",
+      "                                       placeholder in source a starter would ship.",
+      "                                       Exits 1 on any of it, so CI can gate on it",
       "  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",
@@ -46464,10 +46497,10 @@ export default defineConfig({
     // openly at the asset layer \u2014 the map would expose the very source the gate
     // exists to protect. Source maps aren't needed to run the app.
     sourcemap: false,
-    // Top-level await (package projects' generated .lotics/app_fields.ts
-    // resolves the installation binding at module load) needs es2022 \u2014 Vite's
-    // default 'modules' baseline is es2020 and esbuild hard-fails TLA there.
-    // Dev already transforms at esnext, so this only aligns the prod build.
+    // Vite's default 'modules' baseline is es2020, which is older than the
+    // browsers a Lotics app is served to and older than what dev already
+    // transforms at (esnext). Pinned so the prod build does not silently
+    // down-level past a feature the dev server accepted.
     target: "es2022",
   },
   server: {
@@ -46490,10 +46523,10 @@ export default defineConfig({
   },
   test: {
     environment: "jsdom",
-    // Global test setup, run before every test file (empty until an author fills it)
-    // collects. A package-linked app's generated .lotics/app_fields.ts awaits it
-    // at module load; without the stub that network call throws under jsdom and
-    // every test that imports the app graph fails to collect. See vitest.setup.ts.
+    // Global test setup, run before every test file. Ships empty \u2014 the slot is
+    // the author's (custom matchers, a fetch stub, timezone pinning). It must
+    // EXIST either way: setupFiles naming a missing file makes vitest fail to
+    // load every test. See vitest.setup.ts.
     setupFiles: ["./${VITEST_SETUP_FILENAME}"],
     // RN packages ship Flow (\`import typeof\`) in their native source, reached
     // transitively by RN-Web components (pickers, calendars, anything touching
@@ -46861,18 +46894,12 @@ declare module "*.css";
     {
       path: "src/harness.test.ts",
       content: `import { describe, test, expect } from "vitest";
-import { getAppBinding } from "@lotics/app-sdk";
 
 /**
  * The one test the scaffold seeds, and it is about the TEST SETUP rather than
  * about your app \u2014 so editing src/App.tsx can never break it, and \`npm test\`
- * never has to be green over zero tests.
- *
- * What it pins: tests run under jsdom, and vitest.setup.ts's echo stub answers
- * for \`getAppBinding\`. That second one is the whole reason the setup file
- * exists: a package-linked app's generated .lotics/app_fields.ts awaits it while
- * a test file is still COLLECTING, so without the stub every test fails before
- * any of them runs \u2014 including pure logic tests that never touch a field id.
+ * never has to be green over zero tests. It imports nothing of yours and
+ * nothing generated, so it passes on a fresh clone before any codegen has run.
  *
  * Delete it once you have tests of your own, or keep it; it costs nothing.
  */
@@ -46880,13 +46907,6 @@ describe("test harness", () => {
   test("runs in a DOM", () => {
     expect(typeof document).toBe("object");
   });
-
-  test("resolves the app binding from the setup stub, so the app graph collects", async () => {
-    const binding = await getAppBinding();
-    // The echo stub answers any alias with a self-identifying ':test:' id \u2014 one
-    // that can never be mistaken for a real fld_\u2026 from the workspace.
-    expect(binding.fields["anything.at.all"]).toContain(":test:");
-  });
 });
 `
     },
@@ -71267,6 +71287,203 @@ function checkWorkflowBodies(tsApi, aliases) {
   }));
 }
 
+// ../../node_modules/nanoid/index.js
+import { webcrypto as crypto3 } from "node:crypto";
+var POOL_SIZE_MULTIPLIER = 128;
+var pool;
+var poolOffset;
+function fillPool(bytes) {
+  if (bytes < 0) throw new RangeError("Wrong ID size");
+  try {
+    if (!pool || pool.length < bytes) {
+      pool = Buffer.allocUnsafe(bytes * POOL_SIZE_MULTIPLIER);
+      crypto3.getRandomValues(pool);
+      poolOffset = 0;
+    } else if (poolOffset + bytes > pool.length) {
+      crypto3.getRandomValues(pool);
+      poolOffset = 0;
+    }
+  } catch (e) {
+    pool = void 0;
+    throw e;
+  }
+  poolOffset += bytes;
+}
+function random(bytes) {
+  fillPool(bytes |= 0);
+  return pool.subarray(poolOffset - bytes, poolOffset);
+}
+function customRandom(alphabet, defaultSize, getRandom) {
+  let safeByteCutoff = 256 - 256 % alphabet.length;
+  if (safeByteCutoff === 256) {
+    let mask = alphabet.length - 1;
+    return (size2 = defaultSize) => {
+      if (!size2) return "";
+      let id = "";
+      while (true) {
+        let bytes = getRandom(size2);
+        let i2 = size2;
+        while (i2--) {
+          id += alphabet[bytes[i2] & mask];
+          if (id.length >= size2) return id;
+        }
+      }
+    };
+  }
+  let step = Math.ceil(1.6 * 256 * defaultSize / safeByteCutoff);
+  return (size2 = defaultSize) => {
+    if (!size2) return "";
+    let id = "";
+    while (true) {
+      let bytes = getRandom(step);
+      let i2 = step;
+      while (i2--) {
+        if (bytes[i2] < safeByteCutoff) {
+          id += alphabet[bytes[i2] % alphabet.length];
+          if (id.length >= size2) return id;
+        }
+      }
+    }
+  };
+}
+function customAlphabet(alphabet, size2 = 21) {
+  return customRandom(alphabet, size2, random);
+}
+
+// ../shared/src/id.ts
+var ID_ALPHABET = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
+var ID_LENGTH = 12;
+var nanoid3 = customAlphabet(ID_ALPHABET, ID_LENGTH);
+function generatePrefixedId(prefix) {
+  return `${prefix}_${nanoid3()}`;
+}
+var RECORD_ID_PATTERN = new RegExp(`^rec_[${ID_ALPHABET}]{${ID_LENGTH}}$`);
+function generateWorkspaceId() {
+  return generatePrefixedId("wsp");
+}
+function generateTableId() {
+  return generatePrefixedId("tbl");
+}
+function generateGroupId() {
+  return generatePrefixedId("grp");
+}
+function generateAppId() {
+  return generatePrefixedId("app");
+}
+function generateDocumentTemplateId() {
+  return generatePrefixedId("dtl");
+}
+
+// ../shared/src/table_field_keys.ts
+var nanoid4 = customAlphabet(ID_ALPHABET, 6);
+function generateFieldKey() {
+  return `fld_${nanoid4()}`;
+}
+function generateOptionKey() {
+  return `opt_${nanoid4()}`;
+}
+
+// ../shared/src/concrete_ids.ts
+function bodyWidth(id) {
+  return id.length - id.indexOf("_") - 1;
+}
+var GENERATED_BODY_WIDTH = /* @__PURE__ */ new Map([
+  ["tbl", bodyWidth(generateTableId())],
+  ["fld", bodyWidth(generateFieldKey())],
+  ["opt", bodyWidth(generateOptionKey())],
+  ["dtl", bodyWidth(generateDocumentTemplateId())],
+  ["grp", bodyWidth(generateGroupId())],
+  ["wsp", bodyWidth(generateWorkspaceId())],
+  ["app", bodyWidth(generateAppId())]
+]);
+function widthOf(prefix) {
+  const width = GENERATED_BODY_WIDTH.get(prefix);
+  if (width === void 0) throw new Error(`concrete_ids: no generator registered for ${prefix}_`);
+  return width;
+}
+var SCHEMA_PREFIXES = ["tbl", "fld", "opt", "dtl", "grp"];
+var SHORTEST_SCHEMA_BODY = Math.min(...SCHEMA_PREFIXES.map(widthOf));
+var CONCRETE_ID_SCAN = new RegExp(
+  `(?<![0-9A-Za-z])(?:${SCHEMA_PREFIXES.join("|")})_[0-9A-Za-z]{${SHORTEST_SCHEMA_BODY},}`,
+  "g"
+);
+var WORKSPACE_ID_SCAN = new RegExp(
+  `(?<![0-9A-Za-z])(?:organization-(?:[0-9a-z]+-)?[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}|wsp_[0-9A-Za-z]{${widthOf("wsp")}}(?![0-9A-Za-z])|app_[0-9A-Za-z]{${widthOf("app")}}(?![0-9A-Za-z])|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})`,
+  "g"
+);
+var ID_PLACEHOLDER_SCAN = new RegExp(
+  `(["'\`])((?:${SCHEMA_PREFIXES.join("|")})_[0-9A-Za-z]+)\\1`,
+  "g"
+);
+function isGeneratedIdBody(id) {
+  const underscore = id.indexOf("_");
+  if (underscore === -1) return true;
+  return /[0-9A-Z]/.test(id.slice(underscore + 1));
+}
+function isBelowGeneratedWidth(token) {
+  const underscore = token.indexOf("_");
+  const width = GENERATED_BODY_WIDTH.get(token.slice(0, underscore));
+  if (width === void 0) return false;
+  return token.length - underscore - 1 < width;
+}
+var SCAN_EXTENSIONS = [".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".html", ".css", ".json"];
+var SCAN_FILE_MAX_BYTES = 1024 * 1024;
+function normalizeScanPath(path13) {
+  return path13.replace(/\\/g, "/").replace(/^\.\//, "").replace(/^\/+/, "");
+}
+function hasScannableExtension(path13) {
+  return SCAN_EXTENSIONS.some((ext) => path13.endsWith(ext));
+}
+function isConcreteIdScanPath(path13) {
+  const name2 = normalizeScanPath(path13);
+  if (name2.endsWith(".md")) return true;
+  if (!name2.startsWith("src/")) return false;
+  if (name2.startsWith("src/workflows/")) return false;
+  return hasScannableExtension(name2);
+}
+function isTestFile(path13) {
+  return /\.(?:test|spec)\.[cm]?[jt]sx?$/.test(path13);
+}
+function isIdPlaceholderScanPath(path13) {
+  const name2 = normalizeScanPath(path13);
+  if (isTestFile(name2)) return false;
+  if (name2.endsWith(".md")) return true;
+  if (name2 === "package.json") return true;
+  if (!name2.startsWith("src/")) return false;
+  return hasScannableExtension(name2);
+}
+function firstLines(text, pattern, keep, into) {
+  text.split("\n").forEach((line, index) => {
+    for (const match2 of line.matchAll(pattern)) {
+      const id = match2[2] ?? match2[0];
+      if (!keep(id) || into.has(id)) continue;
+      into.set(id, index + 1);
+    }
+  });
+  return into;
+}
+function toFindings(path13, rule, lines) {
+  return [...lines].map(([id, line]) => ({ path: path13, line, id, rule }));
+}
+function scanFileForConcreteIds(path13, text) {
+  if (!isConcreteIdScanPath(path13)) return [];
+  const lines = firstLines(text, CONCRETE_ID_SCAN, () => true, /* @__PURE__ */ new Map());
+  firstLines(text, WORKSPACE_ID_SCAN, isGeneratedIdBody, lines);
+  return toFindings(path13, "concrete", lines);
+}
+function scanFileForIdPlaceholders(path13, text) {
+  if (!isIdPlaceholderScanPath(path13)) return [];
+  const lines = firstLines(text, ID_PLACEHOLDER_SCAN, isBelowGeneratedWidth, /* @__PURE__ */ new Map());
+  return toFindings(path13, "placeholder", lines);
+}
+function scanFileForIds(path13, text) {
+  const concrete = scanFileForConcreteIds(path13, text);
+  const seen = new Set(concrete.map((finding) => finding.id));
+  return [...concrete, ...scanFileForIdPlaceholders(path13, text).filter((f) => !seen.has(f.id))].sort(
+    (a, b) => a.line - b.line || (a.id < b.id ? -1 : 1)
+  );
+}
+
 // ../shared/src/agent_instructions.ts
 function agentFilePath(alias) {
   return `src/agents/${alias}.md`;
@@ -72599,6 +72816,44 @@ function readAppSourceText(projectDir) {
   walk2(srcDir);
   return parts.join("\n");
 }
+var ARCHIVE_EXCLUDES = ["node_modules", "dist", ".lotics", "*.tsbuildinfo", ".git"];
+function isArchiveExcluded(name2) {
+  return ARCHIVE_EXCLUDES.some(
+    (pattern) => pattern.startsWith("*") ? name2.endsWith(pattern.slice(1)) : name2 === pattern
+  );
+}
+function scanProjectForIds(projectDir) {
+  const findings = [];
+  const walk2 = (dir) => {
+    for (const entry of fs8.readdirSync(dir, { withFileTypes: true })) {
+      if (isArchiveExcluded(entry.name)) continue;
+      const full = path9.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        walk2(full);
+        continue;
+      }
+      if (!entry.isFile()) continue;
+      const rel = path9.relative(projectDir, full).split(path9.sep).join("/");
+      if (!isConcreteIdScanPath(rel) && !isIdPlaceholderScanPath(rel)) continue;
+      if (fs8.statSync(full).size > SCAN_FILE_MAX_BYTES) continue;
+      findings.push(...scanFileForIds(rel, fs8.readFileSync(full, "utf8")));
+    }
+  };
+  walk2(projectDir);
+  return findings.sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : a.line - b.line);
+}
+function reportPortabilityIds(findings) {
+  if (findings.length === 0) return;
+  console.error(
+    `
+\u2717 ${findings.length} id${findings.length === 1 ? "" : "s"} here cannot survive a copy into another workspace:`
+  );
+  for (const finding of findings) {
+    console.error(
+      finding.rule === "concrete" ? `  ${finding.path}:${finding.line} \u2014 ${finding.id} is this workspace's own id; address it through the generated .lotics/app_fields aliases (F/OPT), or in prose name the thing by alias.` : `  ${finding.path}:${finding.line} \u2014 ${finding.id} is id-shaped but no generator could have minted it; publish resolves every id against the app's footprint and refuses this one, so write a stand-in that is not id-shaped.`
+    );
+  }
+}
 async function appDeploy(client, args) {
   const projectDir = path9.resolve(args.projectDir ?? process.cwd());
   const meta3 = readAppMeta(projectDir);
@@ -72647,16 +72902,7 @@ async function appDeploy(client, args) {
   try {
     note("Packaging source...");
     await runTar(
-      [
-        "-czf",
-        tmpSource,
-        "--exclude=node_modules",
-        "--exclude=dist",
-        "--exclude=.lotics",
-        "--exclude=*.tsbuildinfo",
-        "--exclude=.git",
-        "."
-      ],
+      ["-czf", tmpSource, ...ARCHIVE_EXCLUDES.map((pattern) => `--exclude=${pattern}`), "."],
       projectDir
     );
     note("Packaging dist...");
@@ -72831,10 +73077,14 @@ async function appCheck(client, args = {}) {
   warnIfProjectFootguns(projectDir, sourceText);
   warnIfUnbranded(app);
   warnIfUndescribed(app);
-  if (!nothingPending(pending)) {
+  const unportable = scanProjectForIds(projectDir);
+  reportPortabilityIds(unportable);
+  if (!nothingPending(pending) || unportable.length > 0) {
     process.exit(1);
   }
-  console.error("Checked the app's bindings, capabilities and agent schemas \u2014 nothing blocking.");
+  console.error(
+    "Checked the app's bindings, capabilities, agent schemas and id portability \u2014 nothing blocking."
+  );
 }
 async function pushPendingBindings(client, projectDir, pending) {
   const plan = [
@@ -74085,7 +74335,7 @@ async function starterList(client) {
       description: s.description,
       tags: [
         s.is_official ? "official" : null,
-        s.owned_by_caller === true ? "yours" : null
+        s.owned_by_caller ? "yours" : null
       ].filter((t) => t !== null)
     }))
   );
@@ -74093,19 +74343,17 @@ async function starterList(client) {
   lotics starter init <starter_id>   Copy one into this workspace`);
 }
 async function starterShow(client, starter_id) {
-  const starter = await client.getPackage(starter_id);
+  const starter = await client.getStarter(starter_id);
   console.log(`${starter.name}  (${starter.id})`);
   if (starter.description) console.log(starter.description);
   console.log(
     `
-version   ${starter.latest_version}
-trust     ${starter.is_official ? "official \u2014 reviewed by Lotics" : starter.owned_by_caller === true ? "your organization's own" : "not copyable from this organization"}`
+version      ${starter.latest_version}
+trust        ${starter.is_official ? "official \u2014 reviewed by Lotics" : starter.owned_by_caller ? "your organization's own" : "not copyable from this organization"}`
   );
-  if (starter.icon !== void 0) {
-    console.log(`icon      ${starter.icon ?? "none \u2014 copies show a generic tile"}`);
-  }
+  console.log(`icon         ${starter.icon ?? "none \u2014 the shelf shows a generic tile"}`);
   if (starter.retired_at !== null) {
-    console.log(`retired   ${starter.retired_at} \u2014 can no longer be copied`);
+    console.log(`unpublished  ${starter.retired_at} \u2014 can no longer be copied`);
   }
 }
 function reportKnowledgeWarnings(warnings) {
@@ -74119,26 +74367,15 @@ function reportKnowledgeWarnings(warnings) {
   answering from nowhere. Create them with those names, or edit the agent.`
   );
 }
-function instantiateBody(args) {
-  return {
-    ...args.noSampleData === true ? { no_sample_data: true } : {},
-    ...args.adopt === true ? { adopt: true } : {},
-    build_on_server: true
-  };
-}
 async function starterInit(client, args) {
-  const starter = await client.getPackage(args.starter_id);
+  const starter = await client.getStarter(args.starter_id);
   note(
     `Copying ${starter.name}${starter.is_official ? " (official)" : ""} into this workspace\u2026`
   );
-  const result = await client.instantiateStarter(args.starter_id, instantiateBody(args));
-  if (!Array.isArray(result.apps)) {
-    throw new Error(
-      `This Lotics server predates this CLI and reported nothing about the copy's apps.
-  The copy itself landed \u2014 open it with "lotics auth web" \u2014 and retry once the platform
-  deploy completes. Do NOT copy again.`
-    );
-  }
+  const result = await client.instantiateStarter(args.starter_id, {
+    ...args.noSampleData === true ? { no_sample_data: true } : {},
+    ...args.adopt === true ? { adopt: true } : {}
+  });
   const tables = Object.keys(result.binding.entities ?? {}).sort();
   const knowledgeDocs = Object.keys(result.binding.knowledge ?? {}).sort();
   const templates = Object.keys(result.binding.templates ?? {}).sort();
@@ -74152,24 +74389,10 @@ async function starterInit(client, args) {
     error: app.error
   }));
   note(
-    `  Created ${tables.length} table${tables.length === 1 ? "" : "s"}, ${templates.length} template${templates.length === 1 ? "" : "s"}, ${knowledgeDocs.length} knowledge doc${knowledgeDocs.length === 1 ? "" : "s"}, ${records} sample record${records === 1 ? "" : "s"}${apps.length > 0 ? `, ${apps.length} app${apps.length === 1 ? "" : "s"}` : ""}.`
+    `  Created ${tables.length} table${tables.length === 1 ? "" : "s"}, ${templates.length} template${templates.length === 1 ? "" : "s"}, ${knowledgeDocs.length} knowledge doc${knowledgeDocs.length === 1 ? "" : "s"}, ${records} sample record${records === 1 ? "" : "s"}, ${apps.length} app${apps.length === 1 ? "" : "s"}.`
   );
   reportKnowledgeWarnings(result.knowledge_warnings);
-  const base = {
-    starter_id: args.starter_id,
-    starter_name: starter.name,
-    version: result.version,
-    app_ids: Object.fromEntries(apps.map((app) => [app.alias, app.app_id])),
-    apps,
-    created
-  };
-  if (apps.length === 0) {
-    note(`
-Done \u2014 these are yours now, with no link back to the starter.`);
-    noteCopiedContent(templates, knowledgeDocs);
-    return { ...base, signin_url: null };
-  }
-  if (starter.owned_by_caller !== true) {
+  if (!starter.owned_by_caller) {
     warn(
       `
 ${starter.name} is the publisher's code \u2014 its apps, workflows and agents \u2014 and runs in
@@ -74207,9 +74430,11 @@ ${failed.length} app${failed.length === 1 ? "" : "s"} landed without a version:
     signInUrl = null;
   }
   note(
-    `
+    (apps.length > 0 && failed.length === apps.length ? `
+${starter.name} landed, but none of its ${apps.length} app${apps.length === 1 ? "" : "s"} is live.
+` : `
 Done \u2014 ${starter.name} is live and yours.
-
+`) + `
   Edit anything: the tables, the apps, the templates, the docs. There is no link
   back to the starter and nothing to upgrade \u2014 this is your workspace now.
   Change an app's code:  lotics app pull <app_id>   (then lotics app deploy -m "<what changed>")
@@ -74228,7 +74453,15 @@ Done \u2014 ${starter.name} is live and yours.
   Open it \u2014 one-time sign-in link, expires in 15 minutes:
     ${signInUrl}`);
   }
-  return { ...base, signin_url: signInUrl };
+  return {
+    starter_id: args.starter_id,
+    starter_name: starter.name,
+    version: result.version,
+    app_ids: Object.fromEntries(apps.map((app) => [app.alias, app.app_id])),
+    apps,
+    created,
+    signin_url: signInUrl
+  };
 }
 async function starterFixturesCapture(client, args) {
   const projectDir = path10.resolve(args.projectDir ?? process.cwd());
@@ -103472,6 +103705,7 @@ function requireClient(flags, appWorkspaceId) {
   };
 }
 var SOURCE_LABELS = {
+  flag_org: "--org flag",
   flag: "--api-key flag",
   env_key: "LOTICS_API_KEY env",
   env_org: "LOTICS_ORG env",
@@ -103582,7 +103816,7 @@ async function main() {
     console.error(
       `--version prints this CLI's version and takes no argument; it cannot be combined with a command.
   The CLI version:            lotics --version
-  A package version to take:  operator-only for now \u2014 \`lotics upgrade\` takes the next release.`
+  A starter's version:        a copy always takes the latest; there is no flag for an older one.`
     );
     process.exit(1);
   }
@@ -103606,7 +103840,7 @@ async function main() {
       const email3 = flags.email ?? (process.stdin.isTTY ? await prompt("Email: ") : "");
       if (!email3) {
         console.error(
-          "This machine has no Lotics credential yet, so `start` needs an email to create one:\n  lotics setup " + starterId + " --email you@company.com"
+          "This machine has no Lotics credential yet, so `setup` needs an email to create one:\n  lotics setup " + starterId + " --email you@company.com"
         );
         process.exit(1);
       }

package/dist/src/client.d.ts

@@ -114,7 +114,7 @@ export interface FileUploadResult {
         error: string;
     }>;
 }
-/** One finding from a package publish/release extract. */
+/** One finding from the extract behind a starter publish. */
 export interface ExtractFinding {
     severity: "error" | "warning" | "info";
     area: string;
@@ -140,7 +140,7 @@ export interface StarterPublishRequest {
     color?: string;
 }
 export interface StarterPublishPreview {
-    /** The starter this would release into, or null when it would mint one. */
+    /** The starter this would publish into, or null when it would mint one. */
     starter_id: string | null;
     starter_name: string;
     version: number;
@@ -149,7 +149,7 @@ export interface StarterPublishPreview {
         app_id: string;
         name: string;
     }>;
-    /** Empty on a release — its aliases froze at v1. */
+    /** Empty after v1 — the aliases froze there. */
     renamable_aliases: {
         entities: string[];
         fields: string[];
@@ -182,7 +182,55 @@ export interface StarterPublish {
     started_at: string | null;
     finished_at: string | null;
 }
-/** Advisory knowledge warnings surfaced by install/upgrade (never block). */
+/**
+ * A published version's contract — the artifact set a copy of it creates.
+ *
+ * Narrowed to what a caller CHECKING a copy reads back. The authoritative shape
+ * is `packageContractSchema`, which lives in `@lotics/shared` — a specifier a
+ * published `.d.ts` cannot resolve, so it is declared here rather than imported,
+ * the same trade the publish shapes above make.
+ */
+export interface StarterVersionContract {
+    /**
+     * One table per entity, scaffolded under `label`, with the columns it
+     * declares — a copy whose table landed with the right NAME and the wrong
+     * columns is the failure a table-name check cannot see.
+     */
+    entities: Array<{
+        alias: string;
+        label: string;
+        fields: Array<{
+            alias: string;
+            label: string;
+            type: string;
+        }>;
+    }>;
+    templates: Array<{
+        alias: string;
+        label: string;
+    }>;
+    apps: Array<{
+        alias: string;
+        name: string;
+        /** The named queries the app's shipped source invokes. */
+        queries: Array<{
+            alias: string;
+            /** Param name → declaration. `required` defaults to TRUE when absent. */
+            params?: Record<string, {
+                required?: boolean;
+            }>;
+        }>;
+    }>;
+    /** The knowledge docs the starter ships, keyed by alias. */
+    knowledge: Record<string, {
+        name: string;
+    }>;
+    /** Sample rows per entity alias — `row_count` is the contract's own count of them. */
+    fixtures: Record<string, {
+        row_count: number;
+    }>;
+}
+/** Advisory knowledge warnings surfaced by a copy (never block). */
 export interface KnowledgeWarnings {
     /** `knowledge_expects` doc names with no matching workspace doc. */
     missing_expected_docs: string[];
@@ -406,13 +454,12 @@ export declare class LoticsClient {
         current_version_id: string | null;
     }>;
     /**
-     * Retire (or `undo` un-retire) a registry package (backs `lotics app
-     * unpublish` — the endpoint/audit action keep the `retire` name to avoid API
-     * churn). Retiring refuses NEW installs and hides the package from non-owning
-     * orgs; existing installations keep working and may still upgrade. Owner-org
-     * admin-only.
+     * Take a starter off the shelf, or `undo` to put it back (backs `opctl
+     * starter unpublish`). It hides from non-owning orgs and can no longer be
+     * copied; copies already made are unaffected — they never linked back.
+     * Owner-org admin-only.
      */
-    retirePackage(package_id: string, body: {
+    unpublishStarter(starter_id: string, body: {
         undo: boolean;
     }): Promise<{
         id: string;
@@ -426,7 +473,7 @@ export declare class LoticsClient {
      * A version is an immutable snapshot; the listing is not. Omit a field to
      * leave it, pass `description: null` to clear it. Owner-org admin-only.
      */
-    editPackageListing(package_id: string, body: {
+    editStarterListing(starter_id: string, body: {
         name?: string;
         description?: string | null;
         icon?: string | null;
@@ -437,11 +484,8 @@ export declare class LoticsClient {
         id: string;
         name: string;
         description: string | null;
-        icon?: string | null;
-        /** Optional for the same reason as `getPackage`'s: an older server omits it. */
-        theme?: {
-            color?: string | null;
-        } | null;
+        icon: string | null;
+        theme: Record<string, unknown> | null;
     }>;
     /**
      * The starters this organization can copy — Lotics-reviewed ones plus its own,
@@ -454,7 +498,7 @@ export declare class LoticsClient {
         description: string | null;
         latest_version: number;
         is_official: boolean;
-        owned_by_caller?: boolean;
+        owned_by_caller: boolean;
     }>>;
     /**
      * Copy a starter into the current workspace.
@@ -469,12 +513,6 @@ export declare class LoticsClient {
         version?: number;
         no_sample_data?: boolean;
         adopt?: boolean;
-        /**
-         * An echo for the rollout window: a server one release behind deploys
-         * only when asked, and this CLI cannot build a copy itself. Drop it once
-         * no such server is a rollback target.
-         */
-        build_on_server?: boolean;
     }): Promise<{
         /** Each app's deploy, in contract order. `error` set and `deployed` null when one did not land. */
         apps: Array<{
@@ -491,9 +529,7 @@ export declare class LoticsClient {
         version: number;
         binding: Record<string, Record<string, string>>;
         sample_record_ids: Record<string, string[]>;
-        knowledge_warnings: {
-            missing_expected_docs: string[];
-        };
+        knowledge_warnings: KnowledgeWarnings;
     }>;
     /**
      * Which starter this app is the origin of. 404 when it has published none.
@@ -536,37 +572,40 @@ export declare class LoticsClient {
      * Fetch a registry starter's metadata (`latest_version` and the Lotics-backed
      * `is_official` trust badge). Admin-only; cross-tenant by id.
      */
-    getPackage(package_id: string): Promise<{
+    getStarter(starter_id: string): Promise<{
         id: string;
         name: string;
         description: string | null;
         latest_version: number;
         is_official: boolean;
         retired_at: string | null;
-        /** Absent from a pre-deploy server — treat undefined as not-owned (the badge under-claims, never over-claims). */
-        owned_by_caller?: boolean;
-        /**
-         * The shelf tile, which every copy's app inherits.
-         *
-         * Optional for the same reason `owned_by_caller` is: a server that predates
-         * the field answers without it, and a CLI newer than the deployment it is
-         * talking to must read that as "not stated" rather than "not set".
-         */
-        icon?: string | null;
-        theme?: Record<string, unknown> | null;
+        /** Whether the CALLING org owns it — the copy-time trust badge, without exposing the owner's org id. */
+        owned_by_caller: boolean;
+        /** The shelf tile. Null = unset; a copy's app tiles come from the contract. */
+        icon: string | null;
+        theme: Record<string, unknown> | null;
         created_at: string;
         updated_at: string;
     }>;
-    /** Version history newest-first (no contract payloads) — backs `opctl package show`. Admin-only. */
-    listPackageVersions(package_id: string): Promise<{
+    /** Version history newest-first (no contract payloads) — backs `opctl starter show`. Admin-only. */
+    listStarterVersions(starter_id: string): Promise<{
         versions: Array<{
             version: number;
             changelog: string | null;
-            channel: "release" | "dev";
-            yanked_at: string | null;
             created_at: string;
         }>;
     }>;
+    /**
+     * One version's contract — what a copy of it is supposed to produce. The
+     * history above omits it (heavy per row); this is the read that carries it,
+     * so a check compares a copy against the declaration itself rather than
+     * against a description of it. Admin-only; cross-tenant by id like
+     * `getStarter`.
+     */
+    getStarterVersion(starter_id: string, version: number): Promise<{
+        version: number;
+        contract: StarterVersionContract;
+    }>;
     /**
      * Workspace-wide dangling-reference sweep — active app/workflow artifacts
      * whose prefixed schema ids no longer resolve. Backs
@@ -617,6 +656,7 @@ export declare class LoticsClient {
         fields: Array<{
             id: string;
             name: string;
+            type: string;
             options?: Array<{
                 id: string;
                 label: string;

package/dist/src/client.js

@@ -324,14 +324,13 @@ export class LoticsClient {
         return this.request("POST", "/v1/apps", body);
     }
     /**
-     * Retire (or `undo` un-retire) a registry package (backs `lotics app
-     * unpublish` — the endpoint/audit action keep the `retire` name to avoid API
-     * churn). Retiring refuses NEW installs and hides the package from non-owning
-     * orgs; existing installations keep working and may still upgrade. Owner-org
-     * admin-only.
+     * Take a starter off the shelf, or `undo` to put it back (backs `opctl
+     * starter unpublish`). It hides from non-owning orgs and can no longer be
+     * copied; copies already made are unaffected — they never linked back.
+     * Owner-org admin-only.
      */
-    async retirePackage(package_id, body) {
-        return this.request("POST", `/v1/packages/${encodeURIComponent(package_id)}/retire`, body);
+    async unpublishStarter(starter_id, body) {
+        return this.request("POST", `/v1/starters/${encodeURIComponent(starter_id)}/unpublish`, body);
     }
     /**
      * Edit a starter's registry listing — the name and description a stranger
@@ -340,13 +339,12 @@ export class LoticsClient {
      * A version is an immutable snapshot; the listing is not. Omit a field to
      * leave it, pass `description: null` to clear it. Owner-org admin-only.
      */
-    async editPackageListing(package_id, body) {
-        return this.request("POST", `/v1/packages/${encodeURIComponent(package_id)}/listing`, body);
+    async editStarterListing(starter_id, body) {
+        return this.request("POST", `/v1/starters/${encodeURIComponent(starter_id)}/listing`, body);
     }
     // --- Starters (registry reads + copies) ---
-    // Authoring is server-side: apps via the publish job (`requestStarterPublish`),
-    // content starters via the `publish_content`/`release_content` tools. There is
-    // no client-side create-package / upload-bundle path.
+    // Authoring is server-side, through the publish job (`requestStarterPublish`).
+    // There is no client-side create-starter / upload-bundle path.
     /**
      * The starters this organization can copy — Lotics-reviewed ones plus its own,
      * never a catalogue of everything published. The server returns exactly what
@@ -399,12 +397,22 @@ export class LoticsClient {
      * Fetch a registry starter's metadata (`latest_version` and the Lotics-backed
      * `is_official` trust badge). Admin-only; cross-tenant by id.
      */
-    async getPackage(package_id) {
-        return this.request("GET", `/v1/packages/${encodeURIComponent(package_id)}`);
+    async getStarter(starter_id) {
+        return this.request("GET", `/v1/starters/${encodeURIComponent(starter_id)}`);
     }
-    /** Version history newest-first (no contract payloads) — backs `opctl package show`. Admin-only. */
-    async listPackageVersions(package_id) {
-        return this.request("GET", `/v1/packages/${encodeURIComponent(package_id)}/versions`);
+    /** Version history newest-first (no contract payloads) — backs `opctl starter show`. Admin-only. */
+    async listStarterVersions(starter_id) {
+        return this.request("GET", `/v1/starters/${encodeURIComponent(starter_id)}/versions`);
+    }
+    /**
+     * One version's contract — what a copy of it is supposed to produce. The
+     * history above omits it (heavy per row); this is the read that carries it,
+     * so a check compares a copy against the declaration itself rather than
+     * against a description of it. Admin-only; cross-tenant by id like
+     * `getStarter`.
+     */
+    async getStarterVersion(starter_id, version) {
+        return this.request("GET", `/v1/starters/${encodeURIComponent(starter_id)}/versions/${encodeURIComponent(String(version))}`);
     }
     /**
      * Workspace-wide dangling-reference sweep — active app/workflow artifacts
@@ -484,7 +492,7 @@ export class LoticsClient {
                 if (field === null || typeof field !== "object")
                     return [];
                 const f = field;
-                if (typeof f.key !== "string" || typeof f.name !== "string")
+                if (typeof f.key !== "string" || typeof f.name !== "string" || typeof f.type !== "string")
                     return [];
                 const options = Array.isArray(f.options)
                     ? f.options.flatMap((opt) => {
@@ -496,7 +504,7 @@ export class LoticsClient {
                             : [];
                     })
                     : undefined;
-                return [{ id: f.key, name: f.name, ...(options && options.length > 0 ? { options } : {}) }];
+                return [{ id: f.key, name: f.name, type: f.type, ...(options && options.length > 0 ? { options } : {}) }];
             });
             return { id: table.id, name: table.name, fields };
         }));

package/docs/building_an_app.md

@@ -236,7 +236,8 @@ actually carries, not what the source says it should.
 
 ```
 npm run typecheck && npm run lint && npm test
-lotics app check                     # every pre-flight a deploy runs, without building or shipping
+lotics app check                     # every pre-flight a deploy runs, without building or shipping,
+                                     # plus the portability gate a starter publish applies
 lotics app deploy -m "<what changed + why>"
 ```
 

package/docs/cli_reference.md

@@ -24,7 +24,7 @@ Per-command syntax, flags, contracts, and gotchas for the public `lotics` CLI. S
 | `lotics run <tool> --json '<json>'` | Execute a tool (full JSON output) |
 | `lotics run <tool>` — **file cells** | A file in a tool's result carries its `fil_…` id and metadata and **no `url`**, on every tool and in both output modes. That is not a broken file — this surface resolves no URL for a cell. Reach the bytes with `lotics file download <file_id>`, which takes the id straight from the cell; the text output says so whenever a result carries one. |
 | — | **Every tool is invoked here, including the ones that RUN something** (`run_app_workflow`, `run_app_agent`, `run_app_query`). What stays an `app` command is work no tool call can do — scaffold, build, typecheck, serve, or read and push a local file. |
-| — | **The exit code reports the WORK, not just the call.** A result whose envelope carries a failed `status` (`error`/`failed`/`cancelled`) exits non-zero and prints `<tool> → <status>: <message>` to stderr, so `lotics run … && next-step` cannot walk past a refused run. The rule is an allowlist of FAILURE — an unrecognized status exits 0, so a status added later never turns a working script red. A parked run (`awaiting_input`) is not a failure: it is waiting for an answer and the work is still live. Only a TOP-LEVEL `status` counts; one inside the data belongs to the data. |
+| — | **The exit code reports the WORK, not just the call — for the two tools that RUN one.** `run_app_workflow` and `run_app_agent` whose envelope carries a failed `status` (`error`/`failed`/`cancelled`) exit non-zero and print `<tool> → <status>: <message>` to stderr, so `lotics run … && next-step` cannot walk past a refused run. The rule is an allowlist of FAILURE — an unrecognized status exits 0, so a status added later never turns a working script red. A parked run (`awaiting_input`) is not a failure: it is waiting for an answer and the work is still live. Only a TOP-LEVEL `status` counts; one inside the data belongs to the data. Any OTHER tool's `status` — `press_button`'s included — is data, and exits 0. |
 | `lotics run <tool> --print-created` | Report the records the call created, grouped by table, with a paste-ready `delete_records` per table and the mandatory caveat naming what cannot be auto-undone (external integrations, notifications, possible sub-workflows). Works for any tool that returns a `side_effects` block, not workflows alone. |
 | `lotics run <tool> --cleanup` | Implies `--print-created`, then runs those deletes — harvested records **only**, never files / external calls / notifications. **Not a rollback**; a rollback is structurally impossible here. A partial cleanup exits non-zero so a script cannot read it as success. |
 | `lotics upload <file\|dir...>` · `--stdin` · `--base64` · `--url <url>` | Upload files/directories via multipart POST to /v1/files. A directory expands to its immediate files; `--as <name>` renames a single upload. **Three alternative byte sources, for a caller that never had the bytes on disk** — an attachment decoded in memory, a generated document, a signed download link — each mutually exclusive with the others and with a path argument: `--stdin` takes raw bytes on stdin, `--base64` takes base64 on stdin (the shape attachments arrive in), `--url <url>` fetches the URL first. `--stdin`/`--base64` REQUIRE `--as`, because stdin carries no filename and the mime type is derived from it; `--url` falls back to `Content-Disposition` then the URL's last path segment. `--base64` decodes STRICTLY — `Buffer.from(s, "base64")` silently skips invalid characters and truncates on bad padding, so a corrupted pipe would otherwise store a short file that only fails when a human opens it. The `--url` fetch happens in the CLI, not the server: the URL comes from the operator running the command, so routing it through the backend would add an SSRF surface to buy what `curl` already does. |
@@ -43,13 +43,13 @@ Per-command syntax, flags, contracts, and gotchas for the public `lotics` CLI. S
 | `lotics app codegen [path]` | Regenerate `.lotics/*` from the manifest + workspace schema **without a deploy**. The three `.d.ts` companions (`app_{workflows,queries,agents}.d.ts`) are always rewritten (synchronous, no network). When credentials resolve, also rewrites the **runtime** `.lotics/app_fields.ts` — a real `.ts` exporting `F` (table→field→`"fld_…"`) + `OPT` (table→select-field→option→`"opt_…"`) keyed by display-name aliases, for the tables the app's queries reference (+ optional `package.json#lotics.codegen.tables` allowlist). **There is one form, and that is what makes a starter's source portable**: the keys are slugified DISPLAY NAMES and a starter carries its labels verbatim, so running codegen in a copy's own workspace emits the same keys pointing at that workspace's ids — no binding fetched at load, no prebuilt bundle to keep in step. Also refreshes each bound workflow's `.lotics/workflows/<alias>.globals.d.ts` + re-wraps its EXISTING `src/workflows/<alias>.ts` body in the current envelope (strips + re-wraps; never re-fetches the body, so local edits survive). **`.lotics/` is reconciled to the manifest, not merely added to** — a `<alias>.globals.d.ts` whose alias the manifest no longer declares is DELETED. Only that exact filename shape is removed; anything else in the directory is left alone. The reconcile runs before the credential branch, so it happens offline too. The authored counterpart is never deleted — a `src/workflows/<alias>.ts` the manifest does not declare is NAMED instead (`check` and `set` both take their alias set from the manifest, so editing an undeclared body is a silent no-op). A getApp / binding / schema / dts-fetch failure is non-fatal (warns, keeps the last-generated files). **Re-silvers `package.json#lotics.agents`** from the live app row whenever its `inputs`/`outputs` disagree, then rewrites the agent `.d.ts` from the refreshed block: that block is a mirror AND the offline seed for `useAgentRun` typings, so a stale copy types the app against an agent that does not exist. The write is surgical and order-preserving, so it changes only the fields that actually differ. A hand edit to that block is therefore reverted — it never changed the agent anyway; to change one, `set_app_agent`. |
 | `lotics setup <starter_id> [--email <addr>] [--json]` | **The whole first run, in one command.** Creates an account when this machine has no credential (the same call `auth signup` makes — `--name` and `--timezone` apply), then does exactly what `starter init` does, then prints the one-time sign-in link. It exists because the two-command form has a seam where the FIRST command exists only to produce a credential for the second, and a caller pasting a prompt has to get both right. **`--email` is only for creating an account**: with a credential already resolvable it is REFUSED rather than obeyed, because the two can name different organizations and preferring either one silently copies a starter into an org the caller did not name — the message says how to do each thing on purpose. Without it, `setup` copies into the account you already have and is a pure alias for `starter init`. A path positional is accepted and IGNORED with a warning — nothing is written to disk any more — so a prompt written for an older CLI still runs. **`--json` prints one object on stdout and nothing else** — `organization_id`, `workspace_id`, `app_ids` (alias → id), `apps` (each app's `version_number`, or its `error`), `signin_url`, and `created` — which NAMES what landed (`tables`, `templates` and `knowledge_docs` are alias arrays; `sample_records` is a row count, since rows are not named things). Aliases rather than counts because the next question is about a particular artifact: a copied template carries the publisher's wording and a copied knowledge doc describes how they work, so "which of these should be mine?" is the conversation a copy starts, and a count cannot begin it. Plus a `warnings` array carrying everything the prose form would have said out of band — an unbindable knowledge doc, a sign-in link that could not be minted, the publisher's-code disclosure, an app that landed without a version. A warning is never merely silenced: when the command fails with an error before it can emit, the ones it had collected go to stderr alongside it. Reachable with no install: `npx -y @lotics/cli setup …`. |
 | `lotics starter list` | **Works with no account**, and that is the point: whether to copy a starter or build from scratch is decided before one exists, so requiring a key would mean signing up to learn the answer was no. Unauthenticated it lists what Lotics publishes (`GET /v1/starters/official`, public). Authenticated it is the org shelf — The starters this organization can copy — Lotics-reviewed ones plus its own, each with at least one released version. Deliberately NOT a catalogue of everything published: the server returns exactly what a copy would be allowed to take, so the list can never offer something that then refuses. Admin-only. |
-| `lotics starter show <starter_id>` | One starter's name, description, current version and trust standing (`official` — reviewed by Lotics; `your organization's own`). Read it before copying a starter you did not publish. |
-| `lotics starter init <starter_id>` | **Copy a starter into this workspace.** Server-side it scaffolds the tables and fields, creates the document templates and knowledge docs, inserts the sample records, creates every app the starter carries and materializes each one's queries, workflows and agents onto it — then deploys each app from the dist the starter was published with, rewriting the publisher's sentinel field keys to this workspace's. No build runs anywhere, nothing is written to this machine, and nothing here needs node: the apps are live when the command returns. **What you get is yours outright**: ordinary apps plus ordinary tables, with no link back to the starter, nothing pinned, and nothing to upgrade. Edit any of it — `lotics app pull <app_id>` is how an app's code is edited afterwards. **The publisher's code runs in your workspace as you** — its apps, workflows and agents — which is why provenance is the gate: **copyable only if the starter is Lotics-reviewed or your own organization published it**, enforced server-side; the disclosure is printed (and carried in `--json`'s `warnings`) whenever the starter is not your own. **Refuses a workspace that already has tables** unless `--adopt`: scaffold matches an entity by DISPLAY NAME, so a starter declaring `Contacts` would bind to yours. An app whose deploy failed is reported by name with its reason and the exit is non-zero, but the copy is complete around it — the tables, the records and the app row exist — so it must not be run again; the publisher fixes the starter and it is copied into a fresh workspace. The sign-in link lands on the app when there is one, else on the workspace's app list. `--json` prints one object on stdout instead of progress (the shape is under `lotics setup`). `--no-sample-data` skips the sample records; with them, the created record ids are reported — they are ordinary records, delete them whenever. Resolves and ANNOUNCES its workspace first (`lotics → <org> / <workspace>` on stderr). Admin-only. Authoring the registry (`opctl starter publish/unpublish`) stays operator-only. |
-| `lotics starter fixtures capture [--entity <alias> ...] [--limit <n>]` | **(authoring)** Write this app's live records into the project as `fixtures/<entity-alias>.json` — the sample data a starter carries, so a copy lands with something in it. Run from an app project; the app id comes from its manifest. The alias-keyed shape is produced server-side, because the aliases are minted when the starter is extracted and exist nowhere a project can read them. `--entity` is repeatable and comma-separated; omitted, every table the app declares is captured. **Capture a linked set in ONE call** — a link between two rows only resolves within a single capture, so taking companies and contacts separately drops the edge between them (it says so when it happens). `--limit` bounds rows per table (default 10, max 200). **READ WHAT IT WROTE before committing**: these rows are created verbatim in every workspace that copies the starter, so a real customer name, price or address captured here is published. Files, formulas, rollups, lookups and autonumbers are never captured — the platform writes those. Admin-only; writes nothing to the workspace. |
+| `lotics starter show <starter_id>` | One starter's name, description, current version, shelf tile and trust standing (`official` — reviewed by Lotics; `your organization's own`; otherwise `not copyable from this organization`), plus the date it was unpublished once it has been. Read it before copying a starter you did not publish. Admin-only, and readable by id from any org — but an unpublished starter 404s for every org except the one that published it. |
+| `lotics starter init <starter_id>` | **Copy a starter into this workspace.** Server-side it scaffolds the tables and fields, creates the document templates and knowledge docs, inserts the sample records, creates every app the starter carries and materializes each one's queries, workflows and agents onto it — then deploys each app from the dist the starter was published with, rewriting the publisher's sentinel field keys to this workspace's. No build runs anywhere, nothing is written to this machine, and nothing here needs node: the apps are live when the command returns. **What you get is yours outright**: ordinary apps plus ordinary tables, with no link back to the starter, nothing pinned, and nothing to upgrade. Edit any of it — `lotics app pull <app_id>` is how an app's code is edited afterwards. **The publisher's code runs in your workspace as you** — its apps, workflows and agents — which is why provenance is the gate: **copyable only if the starter is Lotics-reviewed or your own organization published it**, enforced server-side; the disclosure is printed (and carried in `--json`'s `warnings`) whenever the starter is not your own. **Refuses a workspace that already has tables** unless `--adopt`: scaffold matches an entity by DISPLAY NAME, so a starter declaring `Contacts` would bind to yours. An app whose deploy failed is reported by name with its reason and the exit is non-zero, but the copy is complete around it — the tables, the records and the app row exist — so it must not be run again; the publisher fixes the starter and it is copied into a fresh workspace. The sign-in link lands on the app when there is one, else on the workspace's app list. `--json` prints one object on stdout instead of progress (the shape is under `lotics setup`). `--no-sample-data` skips the sample records, and a copy that ADOPTS an existing table writes none either — that table already holds real rows, and the fixture set links to itself, so it is all-or-nothing; with them, how many landed is reported. They are ordinary records, delete them whenever. Resolves and ANNOUNCES its workspace first (`lotics → <org> / <workspace>` on stderr). Admin-only. Authoring the registry (`opctl starter publish/unpublish`) stays operator-only. |
+| `lotics starter fixtures capture [--entity <alias> ...] [--limit <n>]` | **(authoring)** Write this app's live records into the project as `fixtures/<entity-alias>.json` — the sample data a starter carries, so a copy lands with something in it. Run from an app project; the app id comes from its manifest. The alias-keyed shape is produced server-side, because the aliases are minted when the starter is extracted and exist nowhere a project can read them. `--entity` is repeatable and comma-separated; omitted, every table the app declares is captured. **Capture a linked set in ONE call** — a link between two rows only resolves within a single capture, so taking companies and contacts separately drops the edge between them (it says so when it happens). `--limit` bounds rows per table (default 10, max 200 — a higher one is clamped, not refused). **A captured row is written into a copy exactly as it reads here**: a cell the origin left empty stays empty, because the copy's inserts do not apply field defaults. **READ WHAT IT WROTE before committing**: these rows are created verbatim in every workspace that copies the starter, so a real customer name, price or address captured here is published. Files, formulas, rollups, lookups and autonumbers are never captured — the platform writes those. Admin-only; writes nothing to the workspace. |
 | `lotics upgrade` | Update this CLI in place. Runs the same installer a person would, chosen by how THIS copy arrived: an npm install upgrades through npm, a script install re-runs the script — the runtime knows which (the executable is compiled, the npm bin runs under node), so nobody has to. It downloads nothing itself; resolving a version, verifying the checksum and replacing a running executable already exist in the installers, and a second copy of that inside the binary would be a second thing to get right. Replacing the binary while it runs is safe — a rename leaves the running image mapped on unix, and on Windows the installer moves the old aside precisely because the file is in use. Already current is a no-op that says so. Needs no auth. |
 | `lotics docs` \| `lotics docs <area>` | The index of the reference docs, **resolved out of the packages installed beside this project** — never carried by this CLI. **Both levels are discovered by looking**: every `@lotics/*` package carrying an `AGENTS.md` or a `docs/` in any `node_modules/@lotics` from the current directory UPWARD (nearest wins, so a hoisted root copy never shadows the one a project's own imports resolve to), and within each, every area it actually ships. Titles come from each file's own `# heading` and the version from the installed `package.json`, so a doc OR a whole package added upstream appears with no change to this CLI, and a skewed install is visible rather than reassuring. A package's index is named after the package (`lotics docs ui`), never `index`. `@lotics/app-sdk`, `@lotics/ui` and `@lotics/cli` sort first as a reading ORDER, not a filter. Both the index and `<area>` print to **stdout** — the index is the payload of a bare `lotics docs`, so `lotics docs | grep -i excel` works — with only the provenance line on stderr, so `lotics docs ai > ai.md` is the doc alone; a name two packages share is refused with both qualified forms (`lotics docs ui/templates`) rather than resolved silently. Needs no auth. Outside a project only `@lotics/cli`'s own resolve, and it says so. |
 | `lotics report '<json>'` \| `lotics report @report.json` | File a report with the Lotics team about what got in your way. **Covers the classes telemetry structurally cannot see**: a capability that does not exist (no command ran, so nothing was recorded), a command that exited 0 having done the wrong thing, an error whose message did not name the remedy, and anything that made authoring slower than it should be. **A frame, not a paragraph** — `{goal, actual, expected?, tried?, wanted?}`, `goal` and `actual` required, unknown keys dropped rather than refused. **No severity or category.** Ingest is inline JSON, `@file`, or `-` for stdin. A bare sentence is refused with the frame printed beside it, so the fix is one step; a bare invocation prints the frame BEFORE asking for a credential, since someone whose key will not resolve is exactly who has something to report. **Not spooled**: unlike telemetry it posts inline, prints whether it landed, and exits non-zero if it did not, echoing the report back so a failed send never loses it. Runs regardless of `LOTICS_TELEMETRY` — invoking it IS the consent that passive collection needs an opt-in for — but with telemetry off there are no recorded commands to attach, and it says so rather than implying context it does not have. Requires auth. Never paste records, file contents, or credentials. |
-| `lotics app check` | Every pre-flight `deploy` runs, WITHOUT building or shipping. **First, whether this project is even based on the served version** — the one thing a deploy REFUSES outright rather than pushing (the server 409s a stale `prev_version_id`), and the one finding that invalidates every other: a stale tree and the live app are two different apps, so comparing them reports nothing trustworthy. Stale exits 1 naming both versions and stops before the rest; a project with no stamp at all — or an app with no version yet — is a first deploy, not a conflict. `deploy` runs the SAME assertion off the app row it already fetched, so a stale tree fails before it pushes a binding or builds, instead of after the upload arrives and the server 409s. Then: the manifest's agent schemas against the live app row, every binding a deploy would push, aliases the source calls that nothing bound (queries, workflows AND agents), bindings this bundle stopped calling (the same transition — and the same baseline — `deploy` reports, so the two cannot disagree), capability-gated SDK calls the manifest doesn't declare, a missing icon/theme, a missing app `description` (it heads the capability catalog the chat agent reads every turn, and its absence has no other symptom), a `vite.config.ts` that never defines `global`/`__DEV__`, a `window.open` in the app's own source, and an INSTALLED `@lotics/app-sdk` below the version that understands the host's realtime push — read from `node_modules`, not the dependency range, because a caret is minor-locked below 1.0 so `^0.79.x` can never resolve `0.80` and `npm update` does nothing (all three fail ONLY in the deployed app — dev bundles with esbuild and production with rollup, so typecheck, lint, build and `app dev` are all green while react-native-web reads `global.cancelAnimationFrame` as a free variable and the sandboxed iframe drops a popup silently), an agent holding `run_app_query`/`run_app_workflow` with an EMPTY `query_aliases`/`workflow_aliases` (the tool is the capability, the alias list is the reach — empty means every call it makes is refused while the run still COMPLETES, so it surfaces as a model ignoring its prompt; read off the live row, never the manifest, which mirrors those fields but is pushed by no verb), and a notice for any alias the source computes at runtime (invisible to every check here and to `--prune`'s unbind guard). **And whether the kit this app builds against has fallen behind what is published** — `@lotics/ui` and `@lotics/app-sdk`, read from `node_modules` for the same reason as the floor check above: a range keeps accepting, so an app pinned `^44.x` reads healthy for a year, and even an in-range one sits on the lockfile's older patch until `npm update` (never `npm install`, which honours the lock). A MAJOR behind is loud and names the packages actually behind — plus `@lotics/ui`'s `MIGRATION.md`, when ui is one of them, since it is the only half that keeps one; anything smaller is one quiet line, because a warning that fires on every deploy is one the reader stops seeing. The registry lookup is bounded and every failure — offline, slow, private — is silence: a version check must never become a new way for a deploy to fail. Adds no rule of its own — each finding is the same helper `deploy` calls, so a green check means a deploy will not complain. **Exits 1 on what a `deploy` would REFUSE or PUSH** — an agent schema that disagrees with the live app, and any binding the project has ahead of the app (an edited workflow body or declaration, edited agent prose, a changed query). Both are things a deploy would act on, so CI gating on a green check means a deploy has nothing left to do; genuine advisories (capabilities, branding, a runtime-computed alias, orphaned bindings) stay advisory and never fail it. |
+| `lotics app check` | Every pre-flight `deploy` runs, WITHOUT building or shipping. **First, whether this project is even based on the served version** — the one thing a deploy REFUSES outright rather than pushing (the server 409s a stale `prev_version_id`), and the one finding that invalidates every other: a stale tree and the live app are two different apps, so comparing them reports nothing trustworthy. Stale exits 1 naming both versions and stops before the rest; a project with no stamp at all — or an app with no version yet — is a first deploy, not a conflict. `deploy` runs the SAME assertion off the app row it already fetched, so a stale tree fails before it pushes a binding or builds, instead of after the upload arrives and the server 409s. Then: the manifest's agent schemas against the live app row, every binding a deploy would push, aliases the source calls that nothing bound (queries, workflows AND agents), bindings this bundle stopped calling (the same transition — and the same baseline — `deploy` reports, so the two cannot disagree), capability-gated SDK calls the manifest doesn't declare, a missing icon/theme, a missing app `description` (it heads the capability catalog the chat agent reads every turn, and its absence has no other symptom), a `vite.config.ts` that never defines `global`/`__DEV__`, a `window.open` in the app's own source, and an INSTALLED `@lotics/app-sdk` below the version that understands the host's realtime push — read from `node_modules`, not the dependency range, because a caret is minor-locked below 1.0 so `^0.79.x` can never resolve `0.80` and `npm update` does nothing (all three fail ONLY in the deployed app — dev bundles with esbuild and production with rollup, so typecheck, lint, build and `app dev` are all green while react-native-web reads `global.cancelAnimationFrame` as a free variable and the sandboxed iframe drops a popup silently), an agent whose capability and its reach disagree, in EITHER direction, over any of the five declaration-bound tools (`run_app_query`/`run_app_workflow` against `query_aliases`/`workflow_aliases`; `grep_knowledge`/`read_knowledge`/`list_knowledge` against `knowledge_doc_ids`) — the tool is the capability, the list is the reach, and a tool with no reach means every call it makes is refused while the run still COMPLETES, so it surfaces as a model ignoring its prompt; read off the live row, never the manifest, which mirrors those fields but is pushed by no verb, and a notice for any alias the source computes at runtime (invisible to every check here and to `--prune`'s unbind guard). **And whether the kit this app builds against has fallen behind what is published** — `@lotics/ui` and `@lotics/app-sdk`, read from `node_modules` for the same reason as the floor check above: a range keeps accepting, so an app pinned `^44.x` reads healthy for a year, and even an in-range one sits on the lockfile's older patch until `npm update` (never `npm install`, which honours the lock). A MAJOR behind is loud and names the packages actually behind — plus `@lotics/ui`'s `MIGRATION.md`, when ui is one of them, since it is the only half that keeps one; anything smaller is one quiet line, because a warning that fires on every deploy is one the reader stops seeing. The registry lookup is bounded and every failure — offline, slow, private — is silence: a version check must never become a new way for a deploy to fail. Every deploy finding is the same helper `deploy` calls, so a green check means a deploy will not complain. **And the PORTABILITY gate, which is the one rule `check` runs that a deploy does not** — the ids an app cannot carry into another workspace, over the working tree, with the same exclusions the deploy tar applies. Two rules. **An id this workspace MINTED**, written into `src/`, a `.md` or the app's own docs — it resolves to nothing in a copy, and in prose it is an instruction the copier's agent follows; this is the one a `starter publish` also refuses, on the uploaded archive. **And an id-shaped STAND-IN** too short for the generator that mints its prefix (`"opt_X"`, `"fld_a"` — quoted or in a code span, so a bare `opt_in` stays legal, and never in a test file), which only `check` runs, and which additionally reads a workflow body and the manifest: those two are exempt from the first rule because a publish INVERTS a real id there, and it cannot invert a fake — so without this a stand-in survives until the publish resolves it against the app's footprint, on somebody else's machine. Each is reported as `<file>:<line> — <id>` with the one edit that fixes it. This gate reads only the files, but the command around it still needs a resolvable credential and the live app row, so it is not an offline check. **Exits 1 on that and on what a `deploy` would REFUSE or PUSH** — an agent schema that disagrees with the live app, and any binding the project has ahead of the app (an edited workflow body or declaration, edited agent prose, a changed query). Both are things a deploy would act on, so CI gating on a green check means a deploy has nothing left to do; genuine advisories (capabilities, branding, a runtime-computed alias, orphaned bindings) stay advisory and never fail it. |
 | `lotics app workflow set <alias>` | Push the edited `src/workflows/<alias>.ts` body through `set_app_workflow` (the single author of `apps.workflows`). Reads the body from disk (header + `/// <reference>` + `export {};` marker + the `__workflow` wrapper all stripped) + the typed `inputs`/`outputs` **and the `description`** from `package.json#lotics.workflows.<alias>`; the **server** re-verifies the body and echoes the bound `outputs` (declared, else DERIVED from `return({ data })`). The `description` is the one line an agent reads when choosing between the app's aliases (the workflow counterpart to a query's) — authored in the manifest so it lives beside the body in version control and rides every push; omit it and the workflow keeps whatever description it already has, so a push can never blank one set elsewhere. When the manifest declared NO `outputs`, the DERIVED echo is written back into `package.json#lotics.workflows.<alias>.outputs` (a SURGICAL write — preserves `knowledge`/`config` and every other manifest field) and that alias's types are refreshed in place, so `useWorkflow("<alias>")`'s `result.data` is typed immediately with no hand-copy and no second `lotics app codegen`; an explicitly-declared `outputs` is authoritative and never overwritten. Deploy still never authors workflows — this is a CLI convenience over the existing tool. Clear error + non-zero exit on a missing file, an alias absent from the manifest, or a verify failure. |
 | `lotics app agent set <alias>` | Push `src/agents/<alias>.md` — plus `inputs`/`outputs` when `package.json#lotics.agents.<alias>` declares them — through `set_app_agent`. The agent mirror of `app workflow set`, and the deploy-free authoring path for an agent's prose and its typed edges. **It sends only those fields.** Everything else is absent, and absent means unchanged, so a declaration this CLI does not model cannot be reverted by a push from a checkout that predates it — the chat authoring agent's `knowledge_doc_ids`, another operator's `query_aliases` grant. To change one of those, call `set_app_agent` with just that field (`lotics run set_app_agent '{"app_id":…,"alias":…,"tool_names":[…]}'` — it merges), then `app pull` to bring the manifest back in step. **CREATES the alias when the app has not bound one yet**, so a new agent is authored the same way a new workflow is: write the prose, declare the typed half, push. A create needs the prose file (an agent without instructions is not an agent); it is gated on nothing else, because what keeps a binding alive is a `useAppAgentRun("<alias>")` call site in the shipped bundle — a deploy prunes an agent the bundle never names, manifest entry or not. The prose push is a conditional write against the fingerprint this project last saw, so it is refused rather than allowed to overwrite prose someone else changed. Clear error + non-zero exit when there is no prose file and nothing declared to push instead, when a create has no prose to create from, or when the file is empty once the header is stripped. |
 | `lotics app query set <alias>` \| `--all` | Push `package.json#lotics.queries` (`{ ast, params? }` per alias) to `apps.queries` through `set_app_query` — **the only author of a query binding**, the mirror of `app workflow set`. A deploy pushes a DRIFTED declaration through this same verb before it ships (see `app deploy`), so this is the explicit single-alias path, not the only way a query reaches the app. The **server** validates each one exactly as it always did (alias identifier, workspace-only tables, resolvable fields, declared params). `--all` pushes every declared alias, alias-sorted, stopping at the first failure and naming what already landed. Clear error + non-zero exit on an alias absent from the manifest or a validation failure. **The declaration's fields MERGE**, so the manifest is not a snapshot: deleting `params` from an alias and pushing leaves the live params exactly where they were, because an absent key means "unchanged". Clear one with `params: null`, or replace the map with the set you want. |
@@ -57,7 +57,7 @@ Per-command syntax, flags, contracts, and gotchas for the public `lotics` CLI. S
 | `lotics app workflow check [alias]` | Check the editable workflow bodies locally, no auth / no network, in the **server's own order** — parse, then type-check. **Parse** runs `parseWorkflowJs` from `@lotics/shared` (the SAME module `verifyWorkflow` calls, never a second implementation) over the stripped body `set` would upload, with `toolNames: undefined` (the CLI ships no tool registry, so tool-name resolution stays a server check while every shape/scope rule runs here). A body the subset rejects reports **that error alone** and skips the compiler — it never reaches the server's compiler either, so tsc's opinion of it is noise. **Type-check** then builds an **isolated** `ts.Program` per alias from exactly that alias's `{body, globals}` pair — mirroring the server, which verifies one body at a time — so the per-alias ambient `trigger` never collides and `trigger.app_workflow.inputs` is checked against the right alias. All aliases run in ONE node process (N programs, not N `tsc` spawns), with the SAME compile options the server uses at set-time verify (lib `es2022` with no DOM, target ES2022, strict, NodeNext, `types:[]`, skipLibCheck) and the app's OWN `typescript` (resolved from its `node_modules`, never bundled into the CLI). What the compiler sees is the **checked source**, not the file: `rewriteAccumulatorAppends` from `@lotics/shared` — the SAME transform the server applies before its set-time compile — is applied in memory, so a pulled body's canonical `out = concat(out, [item])` accumulator checks green here exactly as it saves there, and the body on disk is never rewritten. Reports `<file>:<line>:<col> - <TS####\|subset>` at the **physical** line in `src/workflows/<alias>.ts`, so an editor jump lands on the offending code (these are deliberately NOT `set`'s body-relative numbers — `set` prints no file path, so there is no format to agree with); exits non-zero if any alias fails. Green is honest but not total: `set` additionally resolves names, lints and structurally validates against the live workspace — passes that need its tables and tool schemas, so they cannot run offline, and the success line says so. A bound alias with no body file yet warns + skips; a body with no globals errors (naming `lotics app codegen`, which refreshes types WITHOUT touching the body — a pull would overwrite it). **It also keeps the types honest.** Each alias's `.lotics/workflows/<alias>.globals.d.ts` carries a `// lotics:declaration <hash>` stamp of the manifest declaration it was rendered from; `check` compares it to `package.json#lotics.workflows.<alias>` and, when they differ, re-renders that alias's dts from the LOCAL declaration before compiling. Without it the verdict was confidently wrong in the exact case an author needs it — declare an input, run `check`, and get `TS2339: Property 'x' does not exist` pointing at your body for a schema the types have never been told about. The server renders a dts from a SUPPLIED declaration, so this works before the manifest has ever been deployed, which is when it matters (the order is edit → check → set). This is the ONE thing `check` uses the API for: it is skipped entirely when the stamps match (the common case, so `check` stays instant and offline), and with no credentials or a failed fetch it WARNS and checks against the older types rather than blocking. A file written before the stamp existed reads as unknown, never as matching, so a pre-existing checkout heals on its first run. |
 | `lotics app subdomain <new-subdomain>` | Rename the app's public `<slug>.lotics.app` address via `PUT /v1/apps/{id}/subdomain`. app_id comes from the local `package.json` manifest; the chosen slug must be a valid DNS label and free; the old address stops resolving. |
 | `lotics app rename "<new name>"` | Change the app's display name (launcher/title) via the `update_app` tool. app_id comes from the local `package.json` manifest; the public address (`subdomain`) and code (`deploy`) are unchanged. |
-| `lotics app dev [path] [--port=N] [--vite-port=N] [--view-as=<member_id>]` | Spawn Vite dev server + an RPC-forwarding HTTP server. The wrapper page embeds the iframe with `sandbox="allow-scripts allow-same-origin"` matching production; postMessage ops (query / workflow / members / context / upload / openExternal / urlState / agentRun) are forwarded to api.lotics.ai using the CLI's API key — file bytes move in **both** directions through the dev server's own relays, never browser↔storage: dev runs against the PROD bucket, whose CORS admits `https://*.lotics.app` and not `http://localhost:<port>`, so a direct browser transfer is blocked — no upload could complete and no preview engine (PDF/Word/Excel all FETCH the bytes) could read a file. `upload` mints a presigned URL and PUTs it **to `PUT /_upload/<file_id>`** (`dev/upload_relay.ts`) from the wrapper page — same-origin, so no preflight and no CORS — and Node forwards it on; every presigned `url`/`thumbnail_url`/`preview_url` on a **file object** in an RPC result is rewritten to **`GET /_file/<token>`** (`dev/file_relay.ts`, absolute — the iframe would resolve a relative path against Vite), which streams the bytes back with `Range` passthrough (206s intact, so PDF seeking works) and an `Access-Control-Allow-Origin` for the Vite origin (the one cross-origin hop left is OUR response to allow). Neither relay ever takes a destination from the client — it gets a `file_id`/token and transfers only to/from a URL it minted or observed itself, so there is no client-controlled target and no SSRF surface. A URL in a record's own text cell is NOT rewritten. Production is unchanged (direct-to-storage, no bytes through the API server); `openExternal` and `urlState.get/set` are handled locally (the latter read/write the wrapper page's own address bar — `set` writes in place via `replaceState` and browser back/forward broadcast a `url-state` message back, so `useUrlState` survives refresh and is shareable in the dev loop; in-app *routing* is the app's own (the iframe owns its url via `@lotics/app-sdk/router`), and the wrapper bakes the saved screen (`_loc`) into the iframe src on load so a refresh restores it, mirroring production); `agentRun` (streaming) is proxied through `POST /_agent_run`, which opens the run's SSE with the CLI key and pipes chunks back to the iframe (`stream-chunk`* → `stream-end`), so `useAgentRun` works in the dev loop just like production; `context` resolves the viewer (`member_id` from `cli/whoami` + `comments_enabled` from the local manifest) and fetches the installation's stored `config` live from the app row, so `useConfig()` renders the same values as production. `--view-as` (global flag; also `LOTICS_VIEW_AS`) threads `x-view-as-member-id` so `is_current_member` + `context` resolve to that member — **admin key only** (the server 403s a non-admin), writes stay attributed to the key owner. Hot reload via Vite; full DevTools / Playwright access via plain localhost. **Every forwarded op logs one line naming its ALIAS** — `[rpc] query applicants 231ms` — and `query applicants (count)` for a count request, which is a SECOND full execution of the same query rather than a cheap lookup. When requests overlap the line carries `· N in flight`. That number is the one to watch: the server bounds how many app queries run at once, so requests past the bound wait and the wait lands inside each request's own duration — a burst reads as "every query got slower", which looks like a slow database and is not one. A screen firing its list plus three facet counts on one keystroke shows up here as eight lines over one or two aliases; see `@lotics/app-sdk` `docs/data_fetching.md` (`useCount`, and handing `usePaginatedQuery` a `total`) and `docs/queries.md` §10 for collapsing them. **Holds no realtime connection** — push belongs to the product frontend, so an app previewed here never updates on an external write (a CLI run, another tab, an agent): reload to see it. Deliberate rather than missing, since the alternative is a second implementation of the channel in the wrapper page, and a blanket poll here would hide an app whose queries do not declare their tables — the one mistake the real host punishes. The startup banner says `realtime: off` so this is visible without reading this table. The dev-optimizer pre-bundle list (`optimizeDeps.include`, load-bearing for dev) is imported from `@lotics/ui/vite` (`loticsOptimizeDeps`) rather than hardcoded in the scaffold, so it tracks the installed `@lotics/ui` and can never go stale. Binds **loopback only** (`127.0.0.1`) — `/_rpc` dispatches with the developer's API key, so a socket on every interface would hand anyone on the network full read/write on the workspace. |
+| `lotics app dev [path] [--port=N] [--vite-port=N] [--view-as=<member_id>]` | Spawn Vite dev server + an RPC-forwarding HTTP server. The wrapper page embeds the iframe with `sandbox="allow-scripts allow-same-origin"` matching production; postMessage ops (query / workflow / members / context / upload / openExternal / urlState / agentRun) are forwarded to api.lotics.ai using the CLI's API key — file bytes move in **both** directions through the dev server's own relays, never browser↔storage: dev runs against the PROD bucket, whose CORS admits `https://*.lotics.app` and not `http://localhost:<port>`, so a direct browser transfer is blocked — no upload could complete and no preview engine (PDF/Word/Excel all FETCH the bytes) could read a file. `upload` mints a presigned URL and PUTs it **to `PUT /_upload/<file_id>`** (`dev/upload_relay.ts`) from the wrapper page — same-origin, so no preflight and no CORS — and Node forwards it on; every presigned `url`/`thumbnail_url`/`preview_url` on a **file object** in an RPC result is rewritten to **`GET /_file/<token>`** (`dev/file_relay.ts`, absolute — the iframe would resolve a relative path against Vite), which streams the bytes back with `Range` passthrough (206s intact, so PDF seeking works) and an `Access-Control-Allow-Origin` for the Vite origin (the one cross-origin hop left is OUR response to allow). Neither relay ever takes a destination from the client — it gets a `file_id`/token and transfers only to/from a URL it minted or observed itself, so there is no client-controlled target and no SSRF surface. A URL in a record's own text cell is NOT rewritten. Production is unchanged (direct-to-storage, no bytes through the API server); `openExternal` and `urlState.get/set` are handled locally (the latter read/write the wrapper page's own address bar — `set` writes in place via `replaceState` and browser back/forward broadcast a `url-state` message back, so `useUrlState` survives refresh and is shareable in the dev loop; in-app *routing* is the app's own (the iframe owns its url via `@lotics/app-sdk/router`), and the wrapper bakes the saved screen (`_loc`) into the iframe src on load so a refresh restores it, mirroring production); `agentRun` (streaming) is proxied through `POST /_agent_run`, which opens the run's SSE with the CLI key and pipes chunks back to the iframe (`stream-chunk`* → `stream-end`), so `useAgentRun` works in the dev loop just like production; `context` resolves the viewer (`member_id` from `cli/whoami` + `comments_enabled` from the local manifest) and fetches the app's stored `config` live from the app row, so `useConfig()` renders the same values as production. `--view-as` (global flag; also `LOTICS_VIEW_AS`) threads `x-view-as-member-id` so `is_current_member` + `context` resolve to that member — **admin key only** (the server 403s a non-admin), writes stay attributed to the key owner. Hot reload via Vite; full DevTools / Playwright access via plain localhost. **Every forwarded op logs one line naming its ALIAS** — `[rpc] query applicants 231ms` — and `query applicants (count)` for a count request, which is a SECOND full execution of the same query rather than a cheap lookup. When requests overlap the line carries `· N in flight`. That number is the one to watch: the server bounds how many app queries run at once, so requests past the bound wait and the wait lands inside each request's own duration — a burst reads as "every query got slower", which looks like a slow database and is not one. A screen firing its list plus three facet counts on one keystroke shows up here as eight lines over one or two aliases; see `@lotics/app-sdk` `docs/data_fetching.md` (`useCount`, and handing `usePaginatedQuery` a `total`) and `docs/queries.md` §10 for collapsing them. **Holds no realtime connection** — push belongs to the product frontend, so an app previewed here never updates on an external write (a CLI run, another tab, an agent): reload to see it. Deliberate rather than missing, since the alternative is a second implementation of the channel in the wrapper page, and a blanket poll here would hide an app whose queries do not declare their tables — the one mistake the real host punishes. The startup banner says `realtime: off` so this is visible without reading this table. The dev-optimizer pre-bundle list (`optimizeDeps.include`, load-bearing for dev) is imported from `@lotics/ui/vite` (`loticsOptimizeDeps`) rather than hardcoded in the scaffold, so it tracks the installed `@lotics/ui` and can never go stale. Binds **loopback only** (`127.0.0.1`) — `/_rpc` dispatches with the developer's API key, so a socket on every interface would hand anyone on the network full read/write on the workspace. |
 | `LOTICS_UI_SRC=<abs path to packages/ui/src>` (env, not a command) | Dev-link `@lotics/ui` to a monorepo checkout for the length of ONE command, **for every tool at once**. The app's `vite.config.ts` gets its whole `resolve` block from the kit (`resolve: loticsResolve()` — `@lotics/ui/vite`), which reads the variable at call time and adds the `@lotics/ui/*` → working-copy alias, so kit edits go live under `lotics app dev` (HMR) and bundle under `lotics app deploy`. In the same breath, every command that regenerates types (`create`/`pull`/`dev`/`deploy`/`codegen`, all via `writeAppDts`) writes **`.lotics/tsconfig.link.json`** — the matching `paths`, which the app's `tsconfig.json` `extends` — so `tsc`, vitest, eslint and your EDITOR resolve the same copy Vite does. Unset ⇒ every one of them goes back to `node_modules`, and the generated file is rewritten inert. **Why `paths` and not `npm link`:** the kit ships un-built `.tsx`, so a kit file outside `node_modules` resolves its OWN `react`/`react-native` from the monorepo — two copies in one program and every shared type stops matching ("Two different types with this name exist, but they are unrelated"). The generated file therefore also pins every peer @lotics/ui declares to the APP's copy, types-package first (`react` → `@types/react`; pinning the runtime package instead strands tsc on a `.js` with no declarations). The pin set is derived from the installed kit's `peerDependencies`, so it tracks the kit rather than rotting. **Nothing hand-written is touched** — the generated file lives in `.lotics/` (the CLI's own dir) and no config is edited by regex. Identical for a monorepo app and an EXTERNAL one (e.g. `~/lotics_apps`). `app deploy` still warns whenever the variable is set — that the bundle carries kit code from your working copy, or that the app's config predates `loticsResolve()` and never reads it, so the PUBLISHED kit is going out. An app whose `tsconfig.json` already `extends` something else is told rather than rewritten: add `./.lotics/tsconfig.link.json` to the array yourself. |
 | `lotics xlsx <subcmd>` | Local .xlsx read/write/edit using the bundled `@lotics/xlsx` engine (no auth, no network). `write` takes its JSON inline, as `@file`, or piped on stdin, ingested exactly as `run` ingests tool args. 14 named subcommands (read, write, set-cell, clear-range, merge, unmerge, add-sheet, delete-sheet, rename-sheet, insert-rows, delete-rows, insert-cols, delete-cols, set-style) + `batch` for applying multiple of the same 14 ops in a single parse/export cycle. `read` also takes `--sheet <name>` (limit output to one sheet — unknown name fails with the available list) and `--range <sheet>!<A1:G60>` (limit to a cell window; the `<sheet>!` prefix is optional when `--sheet` supplies the sheet, a single cell like `S1!B2` is a 1×1 window) to trim a large workbook's JSON — the output shape is unchanged, only the `sheets` array and each sheet's `cells` map are filtered. **`read` reports formatting back, so a generated file is verifiable through this path** rather than by unzipping OOXML: each cell carries `numFmt` when the file gave it one, and `--with-format` adds the resolved `style`. The asymmetry is deliberate — a parsed cell's style is *never* absent (every cell resolves to at least a font — size, name, colour), so emitting it by default would put three noise keys on every plain cell and make “is this styled?” unanswerable by presence; `numFmt` is genuinely absent on an unformatted cell, so it needs no flag. **`write` takes sheet-level `colWidths` (`{"A":34}`) and `rowHeights` (`{"1":44}`)** — without them every column is the default width and a human-facing workbook is unreadable no matter what the cells say. Both are written *pinned* (`customWidth`/`customHeight`), so Excel does not auto-fit them away, and both apply to a row/column that holds no cells (a spacer row's height survives). Keys are a bare column letter and a bare row number, bounded by Excel's grid (`A`…`XFD`, `1`…`1048576`): a key outside it, or a cell ref like `A1` where a column letter belongs, is **rejected** rather than resolved to something adjacent — past the grid the reference is written into the file verbatim, addressing a cell that cannot exist. Unknown **sheet** properties are rejected on the same terms as unknown cell properties — a silently-ignored `columnWidths` typo is a file that looks written and is not. **A `--flag` a subcommand does not know is refused by name** (`--with-formats` would otherwise read as proof the file carries no styles). `xlsx` and `docx` own their whole tail: a global flag's NAME means nothing there, so `xlsx delete-rows f.xlsx S1 5 3 --force` is refused rather than run, and `xlsx set-cell f.xlsx S1!A1 -v` writes the value `-v`. Subcommands whose trailing arg is CONTENT (`xlsx set-cell`, `docx replace-text`, `docx append-paragraph`/`insert-paragraph`) are deliberately exempt: a value may legitimately begin with `-` or `--`, and there a typo is indistinguishable from data. `--help` is the one spelling still reserved everywhere. They are covered instead by arity — **every fixed-shape subcommand refuses an argument past the last one it reads**, whatever it looks like, because the likeliest source is a flag the caller believes exists and these commands write in place. Arity rather than a leading `--` is the discriminator, since a sheet name may legitimately begin with one. **A cell VALUE is read as the type the caller stated, on both JSON surfaces.** `write`'s `cells` and `batch`'s `set-cell` `value` take the same union — a bare `string | number | boolean | null`, or a `{value, formula, numFmt, style}` object — and honour it: a JSON string writes a text cell, digits and all, so `"0071000512345"` (MST, số tài khoản, số vận đơn) keeps its leading zeros and `"1234567890123456789"` keeps its last two digits, neither of which survives being re-read as characters. The one reading applied to a BARE string is a leading `=`, which is a formula — the only way to write one in the shorthand form; `{"value": "=SUM(A1)"}` is the stated literal, and how a cell that must hold the text `=x` is expressed, on either surface. `value` is a literal on the object form of BOTH surfaces — `formula` is the key that says otherwise — and a literal beginning with `=` is **written as asked and named in a stderr warning**, since it is the one literal indistinguishable from a mistake: it renders in a viewer exactly like the formula the caller probably meant, computes nothing, and is skipped by every SUM over the column. The object form also carries `numFmt` and `style` per cell in `batch`, the same as in `write`. The `set-cell` POSITIONAL is different because a shell argument carries no type: there the characters are read for what they denote (`TRUE` → boolean, digits → number), stopped by two things — the target cell's number format being Text (`@`), and a zero-padded digit string, which stays text whatever the target format says (a deliberate divergence from Excel: losing a leading zero is unrecoverable, while a text cell in a number column is visible). Every subcommand that can introduce a formula (`write`, `set-cell`, `batch`) **evaluates it and writes the cached value**, so a generated formula does not read back blank: Excel and Sheets recalculate on open, but parsers — including this CLI's `read` and the rest of the platform — take the cached `<v>`. A formula the engine cannot evaluate still gets written, with a stderr warning naming the cells, rather than silently leaving a hole where a number belongs. Atomic in-place write (temp file + rename). |
 | `lotics docx <subcmd>` | Local .docx read/write/edit using the bundled `@lotics/docx` engine (OOXML round-trip surface only — no ProseMirror baggage). `write` takes its JSON inline, as `@file`, or piped on stdin, ingested exactly as `run` ingests tool args. Subcommands: read, write, append-paragraph, insert-paragraph, delete-block, replace-text, batch. A legacy `.doc` (Word 97–2003 OLE2 binary) is detected in `loadFile` and routed through `@lotics/ooxml`'s `loadDocxFromBuffer` (which re-emits it as real OOXML) before reading — so `lotics docx read` works on a `.doc`, not just a `.docx`. Opaque blocks (tables, custom XML) preserved verbatim. Atomic in-place write. **`replace-text` matches across run boundaries** — Word splits a run at every formatting change, so a `{{marker}}` routinely lands split — and reads straight THROUGH marks that occupy no place in the sentence (`w:proofErr`, `w:footnoteReference`, endnote/comment refs + ranges, `w:bookmarkStart`/`End`, `w:lastRenderedPageBreak`). `w:proofErr` is the one that decides whether this works in practice — Word brackets every word its dictionary rejects, so on non-English text it lands between nearly every pair of runs. It still refuses to join across anything that occupies space in the text — `w:br`, `w:tab`, `w:sym`, a drawing, or any tag not on that allowlist — because the joined string does not represent the glyph and a match there would rewrite text the caller never saw. The SAME rule applies inside a table cell as outside it — both run one `replaceInParagraph` over paragraphs found at any depth, so a marker split by a line break is refused in both rather than rewritten in the cell and skipped in the body under a success message. Zero matches is always a hard error, never a silent no-op, and when the words ARE on the page the error names the block and the splitting mark (`The text IS present at block 1, split by w:br …`) rather than claiming the text is absent. |

package/docs/document_templates.md

@@ -86,8 +86,10 @@ format handles display.
 At generate time, `data` must provide a key for **every** marker — pass `""` for fields
 that should render blank; a missing key fails with the full list of missing markers.
 
-To add markers/loops/conditionals to the uploaded file from the CLI: `word_replace_text`,
-`word_insert_loop`, `word_insert_conditional` (and their `remove_*` counterparts).
+To read the uploaded file before marking it: `word_get_content`, `word_find_text`,
+`word_get_table_data`. To add markers/loops/conditionals: `word_replace_text`,
+`word_insert_loop`, `word_insert_conditional` — unmarking is `word_replace_text` putting the
+plain text back.
 
 ### Email (`create_email_template`)
 

package/docs/knowledge_docs.md

@@ -70,10 +70,10 @@ that member's agent.
 Docs are not injected wholesale. The agent works the corpus like a filesystem, and all three
 verbs respect access + activation, so only docs the caller may use ever surface.
 
-1. **`list_knowledge`** — `ls`. The corpus as a folder tree: name, id, folder, and a truncated
-   description. No bodies.
+1. **`list_knowledge`** — `ls`. The corpus as a flat list: id, name, tags, and a truncated
+   description; `tag` narrows it. No bodies.
 2. **`grep_knowledge`** — `grep -rn`. Match across every readable doc (or one doc, or one
-   folder), returning **doc, line number, and the matching line**. It runs inside Postgres,
+   tag), returning **doc, line number, and the matching line**. It runs inside Postgres,
    so only matching lines cross the wire.
 3. **`read_knowledge`** — `cat` / `sed -n 'X,Yp'`. Read a doc whole or by line range, to see
    the context around a hit.
@@ -221,7 +221,7 @@ statement about discovery, so it cannot silently break an app that depends on a
 Reach for it instead of `rm` whenever the material still matters: last year's tariff schedule, a
 handbook a newer one replaced, the raw source a curated doc was written from.
 
-## Package-managed knowledge
+## Knowledge from a starter
 
 A knowledge doc can also arrive with a **starter** — a published snapshot of a workspace setup
 that carries a corpus of docs (and document templates) along with it. Copying a starter creates

package/package.json

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