@xanots/sdk 0.0.8 → 0.0.10

package/dist/{routes-manifest-SP3ZXLMR.js → routes-manifest-PWZHDOI5.js}

@@ -98,7 +98,7 @@ ${overloadsFor("routePath", rows)}
 ${IMPLEMENTATION}${realtimeSection}`;
 }
 var HEADER = `/**
- * GENERATED by \`xanots paths --emit\`. Do not edit.
+ * GENERATED by \`xanots routes --emit\`. Do not edit.
  *
  * Plain data plus one interpolator \u2014 this file imports nothing, so a frontend
  * gets the typed path/verb (and socket) contract without pulling the SDK runtime
@@ -241,4 +241,4 @@ export {
   RouteManifestError,
   renderRouteManifest
 };
-//# sourceMappingURL=routes-manifest-SP3ZXLMR.js.map
+//# sourceMappingURL=routes-manifest-PWZHDOI5.js.map

package/dist/scaffold.js

@@ -4,10 +4,10 @@ import {
   allFrontendPresets,
   findFrontendPreset,
   resolveFrameworkFlag
-} from "./chunk-MU3O43L2.js";
+} from "./chunk-YBC3IKMF.js";
 import {
   renderIndexCss
-} from "./chunk-P5C2YKAM.js";
+} from "./chunk-ANUDXFEX.js";
 import {
   ACCENTS,
   ACCENT_TOKENS,

package/dist/{static-host-D6KS7X45.js → static-host-3WMV7IZO.js}

@@ -135,4 +135,4 @@ export {
   findSeedLeaks,
   tarGz2 as tarGz
 };
-//# sourceMappingURL=static-host-D6KS7X45.js.map
+//# sourceMappingURL=static-host-3WMV7IZO.js.map

package/dist/status-command-AL47VG7H.js

@@ -0,0 +1,162 @@
+import {
+  getEphemeral,
+  isExpired
+} from "./chunk-VNQM3V2C.js";
+import {
+  isMachineOutput,
+  writeJson
+} from "./chunk-NUQCEOKA.js";
+import {
+  getEnvironment,
+  readEphemeralState
+} from "./chunk-K5IOND4K.js";
+import {
+  getAccessToken
+} from "./chunk-QKM4U5UK.js";
+import "./chunk-FE5I6S6N.js";
+import {
+  fetchOrExplain,
+  httpFailure
+} from "./chunk-3IGNIP6R.js";
+import "./chunk-GNPVYOPB.js";
+import {
+  formatExpiration,
+  formatFields,
+  stdoutStyle
+} from "./chunk-EZG76F7R.js";
+
+// src/emit/status-command.ts
+var TIMEOUT_MS = 3e4;
+function asString(v) {
+  return typeof v === "string" && v !== "" ? v : void 0;
+}
+async function getJson(url, auth, action) {
+  const res = await fetchOrExplain(
+    url,
+    {
+      headers: { accept: "application/json", Authorization: `Bearer ${auth.access_token}` },
+      signal: AbortSignal.timeout(TIMEOUT_MS)
+    },
+    action,
+    TIMEOUT_MS
+  );
+  const text = await res.text();
+  if (!res.ok) throw new Error(httpFailure(action, res, text));
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new Error(`${action}: could not parse the response as JSON:
+${text.slice(0, 200)}`);
+  }
+}
+async function readWorkspace(auth) {
+  const list = await getJson(`${auth.instance}/api:meta/workspace`, auth, "workspace list");
+  const all = Array.isArray(list) ? list : [];
+  const match = all.find((w) => w.id === auth.workspaceId);
+  if (match === void 0) {
+    return {
+      id: auth.workspaceId,
+      name: null,
+      credential: auth.credentialType,
+      note: `this credential cannot see workspace ${auth.workspaceId} \u2014 run \`xanots workspace details\` for the ids that would work`
+    };
+  }
+  return {
+    id: auth.workspaceId,
+    name: asString(match.name) ?? null,
+    credential: auth.credentialType
+  };
+}
+async function readEnvironment(auth, cwd) {
+  const tracked = getEnvironment(readEphemeralState(cwd), auth.workspaceId);
+  if (tracked === void 0) return null;
+  const summary = await getEphemeral(auth, { parentWorkspaceId: auth.workspaceId, name: tracked.name });
+  if (summary === null) {
+    return {
+      name: tracked.name,
+      display: tracked.display,
+      url: tracked.url,
+      state: null,
+      expiresAt: tracked.expires_at,
+      alive: false
+    };
+  }
+  return {
+    name: summary.name,
+    display: summary.display,
+    url: summary.url,
+    state: summary.state ?? null,
+    expiresAt: summary.expiresAt,
+    alive: !isExpired(summary.expiresAt)
+  };
+}
+async function readStatus(args, cwd = process.cwd()) {
+  let auth;
+  try {
+    auth = await getAccessToken(args);
+  } catch {
+    return { signedIn: false, instance: null, user: null, workspace: null, environment: null };
+  }
+  const me = await getJson(`${auth.instance}/api:meta/auth/me`, auth, "whoami");
+  return {
+    signedIn: true,
+    instance: auth.instance,
+    user: {
+      id: typeof me.id === "number" ? me.id : void 0,
+      name: asString(me.name),
+      email: asString(me.email)
+    },
+    workspace: await readWorkspace(auth),
+    environment: await readEnvironment(auth, cwd)
+  };
+}
+function prettyStatus(status) {
+  const s = stdoutStyle();
+  if (!status.signedIn) {
+    return `
+${formatFields([
+      ["Signed in", `${s.bold("no")} ${s.dim("\xB7 run `xanots login`")}`]
+    ])}`;
+  }
+  const who = [status.user?.name, status.user?.email && `<${status.user.email}>`].filter(Boolean).join(" ");
+  const rows = [
+    ["Signed in", who !== "" ? who : s.dim("(unknown user)")],
+    ["Instance", s.bold(s.cyan(status.instance ?? ""))]
+  ];
+  const ws = status.workspace;
+  if (ws !== null) {
+    rows.push([
+      "Workspace",
+      `${ws.id}${ws.name === null ? "" : ` \xB7 ${ws.name}`} ${s.dim(`\xB7 ${ws.credential}`)}`
+    ]);
+    if (ws.note !== void 0) rows.push(["", s.dim(ws.note)]);
+  }
+  const env = status.environment;
+  if (env === null) {
+    rows.push(["Environment", s.dim("none yet \xB7 run `xanots deploy`")]);
+  } else if (!env.alive) {
+    rows.push([
+      "Environment",
+      `${env.name} ${s.dim("\xB7 gone or expired \xB7 run `xanots deploy` for a fresh one")}`
+    ]);
+  } else {
+    const state = env.state === null ? "" : ` ${s.dim(`\xB7 ${env.state}`)}`;
+    rows.push(["Environment", `${env.name}${state} ${s.dim(`\xB7 expires ${formatExpiration(env.expiresAt)}`)}`]);
+    if (env.url !== void 0) rows.push(["URL", s.bold(s.cyan(env.url))]);
+  }
+  return `
+${formatFields(rows)}`;
+}
+async function runStatusCommand(args) {
+  const status = await readStatus(args);
+  if (isMachineOutput(args)) {
+    writeJson(status);
+  } else {
+    process.stdout.write(prettyStatus(status));
+  }
+}
+export {
+  readStatus,
+  runStatusCommand
+};
+//# sourceMappingURL=status-command-AL47VG7H.js.map

package/dist/{store-CUCBSYLj.d.ts → store-BG1UPZ3Z.d.ts}

@@ -5051,7 +5051,7 @@ type RealtimeServerHandle = RealtimeServerDef & {
      * IN A BROWSER BUNDLE, prefer the generated manifest: importing this def for
      * its `getUrl()` pulls the SDK runtime in with it (the same ~289 kB floor a
      * query def costs — the factory CALLS that build the def run at module load).
-     * `xanots paths <entry> --emit xano/routes.gen.ts` writes the identical
+     * `xanots routes <entry> --emit xano/routes.gen.ts` writes the identical
      * address, tenant lift included, as `socketUrl("<server>", baseUrl)` in a file
      * that imports nothing.
      *
@@ -5353,7 +5353,7 @@ type RealtimeChannelHandle<I extends Record<string, InputDescriptor> = Record<st
      * channel).
      *
      * IN A BROWSER BUNDLE, prefer the generated manifest's `channelPath()`
-     * (`xanots paths <entry> --emit`): identical output and the same
+     * (`xanots routes <entry> --emit`): identical output and the same
      * compile-time param checking, in a file that imports no SDK runtime.
      */
     getChannel: IsStaticPath<N> extends true ? (params?: Record<string, never>) => string : (params: PathParamValues<N>) => string;
@@ -7332,10 +7332,10 @@ interface ManifestCliFlag {
  * `src/emit/commands.ts` — the same table that renders `--help` and generates the
  * shell completions.
  *
- * It used to be hand-maintained here, and it drifted: `init` and `validate` were
+ * It used to be hand-maintained here, and it drifted: `init` and `preflight` were
  * missing outright, `deploy` was short six flags, and the `--static` description
- * claimed the frontend always lands on the parent workspace (true only under
- * `--dest sandbox`). Deriving it makes that class of drift unrepresentable, which
+ * claimed the frontend lands on the parent workspace, which it does not.
+ * Deriving it makes that class of drift unrepresentable, which
  * matters more now that `llms.txt` no longer documents the CLI — this array and
  * `--help` are the only two surfaces, and they are now one source.
  */

package/dist/{test-command-RRNNJ45I.js → test-command-YAZLKLGQ.js}

@@ -1,25 +1,28 @@
-import {
-  resolveMetaTarget
-} from "./chunk-XP7S3VWY.js";
-import "./chunk-MDXR5E5Q.js";
-import "./chunk-3EYUR3TX.js";
-import "./chunk-NDZFBZHC.js";
-import {
-  getAccessToken
-} from "./chunk-3QW5NFZJ.js";
-import "./chunk-BKDJN76G.js";
 import {
   isMachineOutput,
   writeJson
 } from "./chunk-NUQCEOKA.js";
+import {
+  resolveMetaTarget
+} from "./chunk-ZQ2PKR6R.js";
+import "./chunk-K5IOND4K.js";
+import {
+  getAccessToken
+} from "./chunk-QKM4U5UK.js";
+import "./chunk-FE5I6S6N.js";
 import {
   fetchOrExplain,
   httpFailure,
   serverMessage
 } from "./chunk-3IGNIP6R.js";
 import {
+  parseEnvSelector,
+  unknownEnv
+} from "./chunk-CTD5ZCV6.js";
+import {
+  UsageError,
   unknownSubcommand
-} from "./chunk-JQLR64UC.js";
+} from "./chunk-F6CYJ7TN.js";
 import "./chunk-GNPVYOPB.js";
 import {
   blank,
@@ -29,7 +32,7 @@ import {
   success,
   warn
 } from "./chunk-EZG76F7R.js";
-import "./chunk-OKNSR7MT.js";
+import "./chunk-DIA7CT7J.js";
 
 // src/deploy/tests.ts
 var TIMEOUT_MS = 12e4;
@@ -189,7 +192,7 @@ async function runTest(auth, target, handle) {
 
 // src/emit/test-command.ts
 var EXIT_TESTS_FAILED = 5;
-var DEFAULT_DEST = "ephemeral";
+var DEFAULT_ENV = { kind: "ephemeral" };
 async function mapWithConcurrency(items, limit, work) {
   const results = new Array(items.length);
   let next = 0;
@@ -224,7 +227,7 @@ function summarize(dest, env, outcomes) {
     total: outcomes.length,
     passed: outcomes.filter((o) => o.status === "pass").length,
     failed: outcomes.filter((o) => o.status === "fail").length,
-    results: outcomes.map((o) => ({
+    tests: outcomes.map((o) => ({
       kind: o.kind,
       name: o.name,
       object: o.object,
@@ -250,10 +253,22 @@ function report(args, dest, env, outcomes) {
   }
   if (summary.failed > 0) process.exitCode = EXIT_TESTS_FAILED;
 }
-async function resolveTarget(args, auth) {
-  const dest = args.dest ?? DEFAULT_DEST;
-  const target = await resolveMetaTarget(auth, { dest, name: args.name });
-  return { dest, env: target.env ?? null, target };
+function assertNoName(args) {
+  if (args.name === void 0) return;
+  throw new UsageError(
+    `\`xanots test\` takes no \`--name\` \u2014 name the environment inside \`--env\` instead: \`--env ephemeral:${args.name}\`.`,
+    { helpFor: { command: "test", subcommand: args.subcommand } }
+  );
+}
+function selectEnv(args) {
+  if (args.env === void 0) return DEFAULT_ENV;
+  return parseEnvSelector(args.env) ?? (() => {
+    throw unknownEnv("--env", args.env, { command: "test", subcommand: args.subcommand });
+  })();
+}
+async function resolveTarget(selector, auth) {
+  const target = await resolveMetaTarget(auth, selector);
+  return { dest: selector.kind, env: target.env ?? null, target };
 }
 async function collect(auth, target, kind) {
   return listTests(auth, target, {
@@ -264,8 +279,8 @@ async function collect(auth, target, kind) {
 function nameWidth(handles) {
   return Math.max(0, ...handles.map((h) => h.name.length));
 }
-async function runList(args, auth) {
-  const { dest, env, target } = await resolveTarget(args, auth);
+async function runList(args, auth, selector) {
+  const { dest, env, target } = await resolveTarget(selector, auth);
   const handles = await collect(auth, target, args.kind);
   if (isMachineOutput(args)) {
     writeJson({
@@ -300,13 +315,13 @@ function match(handles, needle) {
   if (qualified.length > 0) return qualified;
   return handles.filter((h) => h.name === needle);
 }
-async function runOne(args, auth, name) {
-  const { dest, env, target } = await resolveTarget(args, auth);
+async function runOne(args, auth, selector, name) {
+  const { dest, env, target } = await resolveTarget(selector, auth);
   const handles = await collect(auth, target, args.kind);
   const found = match(handles, name);
   if (found.length === 0) {
     throw new Error(
-      `No test named "${name}" in ${target.label}. Run \`xanots test list${args.dest ? ` --dest ${args.dest}` : ""}\` to see what is there.`
+      `No test named "${name}" in ${target.label}. Run \`xanots test list${args.env ? ` --env ${args.env}` : ""}\` to see what is there.`
     );
   }
   if (found.length > 1) {
@@ -348,8 +363,8 @@ async function runSuite(auth, target, opts) {
     return outcome;
   });
 }
-async function runAll(args, auth) {
-  const { dest, env, target } = await resolveTarget(args, auth);
+async function runAll(args, auth, selector) {
+  const { dest, env, target } = await resolveTarget(selector, auth);
   const outcomes = await runSuite(auth, target, {
     kind: args.kind,
     concurrency: args.concurrency,
@@ -358,19 +373,21 @@ async function runAll(args, auth) {
   report(args, dest, env, outcomes);
 }
 async function runTestCommand(args) {
+  assertNoName(args);
+  const selector = selectEnv(args);
   const auth = await getAccessToken(args);
   switch (args.subcommand) {
     case "list":
-      return runList(args, auth);
+      return runList(args, auth, selector);
     case "run": {
       const name = args.positionals[0];
       if (name === void 0 || name === "") {
         throw new Error('`xanots test run` needs a test name: `xanots test run "<name>"`.');
       }
-      return runOne(args, auth, name);
+      return runOne(args, auth, selector, name);
     }
     case "run-all":
-      return runAll(args, auth);
+      return runAll(args, auth, selector);
     default:
       throw unknownSubcommand("test", args.subcommand);
   }
@@ -380,4 +397,4 @@ export {
   runSuite,
   runTestCommand
 };
-//# sourceMappingURL=test-command-RRNNJ45I.js.map
+//# sourceMappingURL=test-command-YAZLKLGQ.js.map

package/dist/{upgrade-command-XFOAWDI3.js → upgrade-command-FB5QJ363.js}

@@ -1,20 +1,20 @@
 import {
   assertProjectDir
 } from "./chunk-ERQZFWIW.js";
+import {
+  refreshAgentFiles
+} from "./chunk-JGCWTCA7.js";
 import {
   isMachineOutput,
   writeJson
 } from "./chunk-NUQCEOKA.js";
-import {
-  refreshAgentFiles
-} from "./chunk-QIWBCS7N.js";
-import "./chunk-4PE4ZAB7.js";
+import "./chunk-KA6G2L7U.js";
 import {
   runNpm
 } from "./chunk-ZSYZTGJH.js";
 import {
   sdkDep
-} from "./chunk-P5C2YKAM.js";
+} from "./chunk-ANUDXFEX.js";
 import "./chunk-Q77KNEUL.js";
 import {
   checkForUpgrade,
@@ -22,10 +22,11 @@ import {
   registryUrl,
   suppressUpdateNotice,
   upgradeCommand
-} from "./chunk-CDAQUY5W.js";
-import "./chunk-SNO3KHCY.js";
-import "./chunk-JQLR64UC.js";
+} from "./chunk-5YCQ2QHH.js";
+import "./chunk-ACCBOMCB.js";
+import "./chunk-CTD5ZCV6.js";
 import "./chunk-OYMR5AMJ.js";
+import "./chunk-F6CYJ7TN.js";
 import "./chunk-GNPVYOPB.js";
 import {
   blank,
@@ -35,9 +36,9 @@ import {
   success,
   warn
 } from "./chunk-EZG76F7R.js";
-import "./chunk-FEQTQ6PM.js";
-import "./chunk-OKNSR7MT.js";
-import "./chunk-64QK6JEK.js";
+import "./chunk-VKSOTZK3.js";
+import "./chunk-DIA7CT7J.js";
+import "./chunk-LBYWGMOA.js";
 import "./chunk-WHOJWOSV.js";
 import "./chunk-5XZ744TS.js";
 import "./chunk-7JDT4PBU.js";
@@ -174,4 +175,4 @@ function messageOf(err) {
 export {
   runUpgradeCommand
 };
-//# sourceMappingURL=upgrade-command-XFOAWDI3.js.map
+//# sourceMappingURL=upgrade-command-FB5QJ363.js.map

package/dist/{workspace-K72NP7SX.js → workspace-2COHDBM3.js}

@@ -46,4 +46,4 @@ ${text}`);
 export {
   resolveScopedWorkspaceId
 };
-//# sourceMappingURL=workspace-K72NP7SX.js.map
+//# sourceMappingURL=workspace-2COHDBM3.js.map

package/dist/{workspace-command-QCFELEGR.js → workspace-command-43P42FBP.js}

@@ -1,48 +1,49 @@
-import {
-  fetchWorkspaceBundle,
-  runCodegenCommand
-} from "./chunk-EM5QPTXP.js";
-import "./chunk-ZOYMZZ3S.js";
 import {
   resolveOutputTarget
-} from "./chunk-JQJPFUZI.js";
-import "./chunk-3EYUR3TX.js";
+} from "./chunk-WGPXT2G2.js";
 import {
   printMicroserviceSection,
   readMicroservices
-} from "./chunk-NDZFBZHC.js";
+} from "./chunk-3UABJA4X.js";
+import {
+  isMachineOutput,
+  writeJson
+} from "./chunk-NUQCEOKA.js";
+import {
+  fetchWorkspaceBundle
+} from "./chunk-I7DQDJAM.js";
+import "./chunk-3INK4Y4E.js";
+import "./chunk-ZQ2PKR6R.js";
+import "./chunk-K5IOND4K.js";
 import {
   ENV_WORKSPACE,
   getAccessToken
-} from "./chunk-3QW5NFZJ.js";
-import "./chunk-BKDJN76G.js";
-import "./chunk-QTNO2WD6.js";
+} from "./chunk-QKM4U5UK.js";
+import "./chunk-FE5I6S6N.js";
+import "./chunk-7ZYW652H.js";
 import "./chunk-ZUTSMMAG.js";
 import "./chunk-X4DVXBFY.js";
-import "./chunk-C3M5K4ZH.js";
-import {
-  isMachineOutput,
-  writeJson
-} from "./chunk-NUQCEOKA.js";
-import "./chunk-4PE4ZAB7.js";
-import "./chunk-ZSYZTGJH.js";
 import {
   fetchOrExplain,
   httpFailure
 } from "./chunk-3IGNIP6R.js";
-import "./chunk-2ROR3AZC.js";
+import "./chunk-YYFXVYPX.js";
+import "./chunk-KA6G2L7U.js";
+import "./chunk-ZSYZTGJH.js";
+import "./chunk-75Z74TA7.js";
 import "./chunk-LU7TRWMC.js";
-import "./chunk-MU3O43L2.js";
-import "./chunk-P5C2YKAM.js";
+import "./chunk-YBC3IKMF.js";
+import "./chunk-ANUDXFEX.js";
 import "./chunk-Q77KNEUL.js";
 import "./chunk-4BXJGVZ3.js";
-import "./chunk-3MDKV2VA.js";
-import "./chunk-SNO3KHCY.js";
+import "./chunk-P6TAVLOX.js";
+import "./chunk-ACCBOMCB.js";
+import "./chunk-CTD5ZCV6.js";
+import "./chunk-OYMR5AMJ.js";
 import {
   removedSubcommand,
   unknownSubcommand
-} from "./chunk-JQLR64UC.js";
-import "./chunk-OYMR5AMJ.js";
+} from "./chunk-F6CYJ7TN.js";
 import "./chunk-GNPVYOPB.js";
 import {
   formatFields,
@@ -50,9 +51,9 @@ import {
   step,
   success
 } from "./chunk-EZG76F7R.js";
-import "./chunk-FEQTQ6PM.js";
-import "./chunk-OKNSR7MT.js";
-import "./chunk-64QK6JEK.js";
+import "./chunk-VKSOTZK3.js";
+import "./chunk-DIA7CT7J.js";
+import "./chunk-LBYWGMOA.js";
 import "./chunk-WHOJWOSV.js";
 import "./chunk-5XZ744TS.js";
 import "./chunk-7JDT4PBU.js";
@@ -67,10 +68,8 @@ async function runWorkspaceCommand(args) {
       return runDetails(args);
     case "export":
       return runExport(args);
-    case "codegen":
-      return runCodegenCommand(args, { kind: "workspace" });
     case "branch": {
-      const { runBranchCommand } = await import("./branch-commands-PBQ36L4A.js");
+      const { runBranchCommand } = await import("./branch-commands-2BLOC2GR.js");
       return runBranchCommand(args);
     }
     case "deploy":
@@ -160,4 +159,4 @@ async function runExport(args) {
 export {
   runWorkspaceCommand
 };
-//# sourceMappingURL=workspace-command-QCFELEGR.js.map
+//# sourceMappingURL=workspace-command-43P42FBP.js.map

package/dist/{workspace-export-AJMGN3CQ.js → workspace-export-DURY5WYL.js}

@@ -1,10 +1,10 @@
 import {
   exportWorkspaceBundle
-} from "./chunk-QTNO2WD6.js";
+} from "./chunk-7ZYW652H.js";
 import "./chunk-ZUTSMMAG.js";
 import "./chunk-X4DVXBFY.js";
 import "./chunk-3IGNIP6R.js";
 export {
   exportWorkspaceBundle
 };
-//# sourceMappingURL=workspace-export-AJMGN3CQ.js.map
+//# sourceMappingURL=workspace-export-DURY5WYL.js.map

package/guides/README.md

@@ -11,10 +11,10 @@ typed, so your editor's autocomplete is usually the faster lookup — tab-comple
 | [Object kinds](object-kinds.md) | Every authorable kind, and splitting a workspace across microservices |
 | [Authoring reference](authoring.md) | Tables and fields, statements, values, inputs, middleware, request history |
 | [CLI](cli.md) | Every command, shell completion, and what failures look like |
-| [Signing in & deploying](deploying.md) | Auth, ephemerals, `--static`, releasing to production, `xanots validate` |
+| [Signing in & deploying](deploying.md) | Auth, ephemerals, `--static`, releasing to production, `xanots preflight` |
 | [Environment & identity](environment.md) | Every environment variable, and how `xano.lock` pins identity |
 | [The typed frontend surface](typed-frontend.md) | Path resolution, input/response inference, bundle cost, the route manifest |
-| [Pulling an existing workspace](codegen.md) | What `xanots codegen` writes, how faithful it is, and how to read its report |
+| [Pulling an existing workspace](codegen.md) | What `xanots init --from` writes, how faithful it is, and how to read its report |
 | [Coverage & agent grounding](coverage.md) | What's covered, what's out of scope, and the files agents read |
 
 ## The agent-facing surface

package/guides/authoring.md

@@ -127,7 +127,7 @@ auto-assigned `id`/`created_at`, `s.db.del` binds `null`, and `edit`/`del` **thr
 `s.db.query` mirrors the whole Xano query builder — `returnType`, `bind` joins, computed
 `eval` columns, `aggregate` groups, `distinct`, and the full operator set via
 `cmp(left, op, right)` with `and(...)`/`or(...)` for boolean groups. Signatures are in
-`llms/statements-data.md`; four behaviors are worth knowing here:
+`llms/statements-data.md`; five behaviors are worth knowing here:
 
 - **A join condition spells its two sides differently.** The joined table's column takes its
   `as` alias; this query's own columns stay bare:
@@ -148,6 +148,14 @@ auto-assigned `id`/`created_at`, `s.db.del` binds `null`, and `edit`/`del` **thr
   disagree: a branch folds terms strictly left to right (`a OR b AND c` = `(a OR b) AND c`)
   while a `db.query` filter inherits SQL's AND-before-OR precedence (`a OR (b AND c)`). Write
   `and(or(a, b), c)` or `or(a, and(b, c))` — each says exactly one thing in every context.
+- **`like`/`ilike` take the operand as the pattern, verbatim.** The operand *is* the pattern,
+  so `cmp(col("body"), "ilike", inp("q"))` with a bare term matches only a whole-string equal —
+  and the endpoint answers 200 with an empty list, which reads as "no results for that query".
+  For substring search use `includes` / `not includes`, which wrap the operand in `%…%`
+  themselves and match case-insensitively. Prefer that over building `"%" + term + "%"`: a
+  hand-built pattern is non-empty even for a blank term, which defeats the `ignoreEmpty` below.
+  `contains` / `@>` / `overlaps` are JSON and array containment, not text — on a text column
+  they fail with a parse error.
 - **`ignoreEmpty` DROPS the clause — it does not match zero rows.** `cmp(col("owner"), "in",
   ids, { ignoreEmpty: true })` with an empty `ids` returns the **unfiltered** table, where the
   same clause without the flag matches nothing. Never put it on a filter that scopes rows to a