@xanots/sdk 0.0.8 → 0.0.9

package/dist/{init-command-4MG3UKUO.js → init-command-OVFFW4QS.js}

@@ -2,7 +2,7 @@ import {
   projectShellFiles,
   runInitCommand,
   sanitizeAppName
-} from "./chunk-C3M5K4ZH.js";
+} from "./chunk-6Z5CNWFC.js";
 import {
   resolveAiFlags
 } from "./chunk-4PE4ZAB7.js";
@@ -10,14 +10,14 @@ import "./chunk-ZSYZTGJH.js";
 import "./chunk-MU3O43L2.js";
 import "./chunk-P5C2YKAM.js";
 import "./chunk-Q77KNEUL.js";
-import "./chunk-SNO3KHCY.js";
+import "./chunk-K3YSQDXJ.js";
 import "./chunk-JQLR64UC.js";
 import "./chunk-OYMR5AMJ.js";
 import "./chunk-GNPVYOPB.js";
 import "./chunk-EZG76F7R.js";
-import "./chunk-FEQTQ6PM.js";
+import "./chunk-UDL46O35.js";
 import "./chunk-OKNSR7MT.js";
-import "./chunk-64QK6JEK.js";
+import "./chunk-QONOJO45.js";
 import "./chunk-WHOJWOSV.js";
 import "./chunk-5XZ744TS.js";
 import "./chunk-7JDT4PBU.js";
@@ -27,4 +27,4 @@ export {
   runInitCommand,
   sanitizeAppName
 };
-//# sourceMappingURL=init-command-4MG3UKUO.js.map
+//# sourceMappingURL=init-command-OVFFW4QS.js.map

package/dist/internal.js

@@ -33,7 +33,7 @@ import {
   taskKind,
   toolKind,
   workflowTestKind
-} from "./chunk-7AXQKABT.js";
+} from "./chunk-7OXFMCTX.js";
 import {
   GENERATED_SPECS,
   GENERATED_STATEMENT_NAMES,
@@ -55,7 +55,7 @@ import {
   registerSpec,
   triggerKind,
   workspaceKind
-} from "./chunk-3MDKV2VA.js";
+} from "./chunk-ZZLPTHT5.js";
 import {
   COMMANDS,
   FLAGS,
@@ -109,7 +109,7 @@ import {
   serializeBundle,
   tableKind,
   toNestedFields
-} from "./chunk-64QK6JEK.js";
+} from "./chunk-QONOJO45.js";
 import "./chunk-WHOJWOSV.js";
 import {
   encodeStatement,
@@ -765,7 +765,7 @@ function renderTestsSection() {
     "",
     "- The run uses an EMPTY datasource, so **no `table({ seed })` rows exist while it runs** and every `db` read misses. A test that buys seeded row 1 fails with its own precondition message, which reads as a wrong id rather than an empty database. Create what the test needs INSIDE the test \u2014 typically a `defineFunction` fixture the stack calls first.",
     '- `s.api.call` does NOT raise when the endpoint answers with an error. It BINDS the error envelope (`{code, message}`) to its `as` and carries on, so a later `s.expect.to_be_defined({ expr: ref("r.field") })` reports the ASSERTION while the real failure was the call, four statements up. Assert on the envelope \u2014 `s.expect.to_contain({ expr: ref("r.code"), value: c.text("ERROR_CODE_INPUT_ERROR") })` \u2014 when a call may fail. `s.function.run` raises instead; the two disagree.',
-    "- `s.expect.to_throw({ body, exception? })` runs `body` in an ISOLATED var stack, so a variable bound EARLIER in the test is not visible inside it \u2014 bind what the body needs inside the body. `exception` is text the raised message must CONTAIN; omit it to accept any error.",
+    '- `s.expect.to_throw({ body, exception? })` runs `body` in an ISOLATED var stack, so a variable bound EARLIER in the test is not visible inside it \u2014 bind what the body needs inside the body. `exception` is a `Value` whose text the raised message must CONTAIN (`c.text("already exists")`, not a bare string); omit it to accept any error.',
     "- `s.expect.to_throw` catches such a call only when the error carries a MESSAGE. `ERROR_CODE_ACCESS_DENIED` arrives with an empty one, so `to_throw` around an auth-refused call reports `to_throw failed - response is ok` \u2014 which reads as a broken auth gate on a gate that works.",
     "- An endpoint's `auth` gate is NOT enforced on `s.api.call`. A `query({ auth: users })` runs anyway and fails only where its stack dereferences `auth(...)`. A stack that never touches `auth(...)` runs unauthenticated and passes.",
     "- Neither `auth.token` nor an `Authorization` entry in `headers` authenticates the call \u2014 a token that answers 200 over real HTTP is refused here. To cover auth-gated logic, move the body into a `defineFunction` taking the user id and `s.function.call` that; the gate itself is not reachable from a workflow test.",
@@ -778,6 +778,7 @@ function renderTestsSection() {
     '- `xanots test list` shows what is there without running it; `xanots test run "<name>"` runs one. When a name is ambiguous the error prints the qualified `function:math/happy path` form, which `run` also accepts.',
     "- `--kind unit|workflow` narrows to one family. `--concurrency <n>` defaults to 1: tests share the environment database.",
     "- A failing suite exits 5, distinct from a crash. Tests that could not be REACHED exit 6 \u2014 retry that one, investigate the other. An environment with no tests is success, not failure.",
+    '- For CI, the exit code says THAT something failed and the JSON says WHICH. Every progress line goes to stderr and stdout carries one JSON document \u2014 emitted whenever stdout is not a terminal, or on demand with `--json`. `run-all` and `run`: `{ dest, env, total, passed, failed, tests: [{ kind, name, object?, status: "pass"|"fail", message?, timing? }] }`, with the same keys on an empty suite. `list` is `{ dest, env, total, tests: [...] }` and `deploy --test` nests the run under `testRun`. The per-test array is always `tests`.',
     "- `xanots deploy ./index.ts --test` deploys and then runs the suite against what it just shipped. A failure exits 5 WITHOUT retracting the deploy \u2014 the environment is live either way.",
     ""
   ];
@@ -1125,7 +1126,7 @@ function renderSections(m) {
     "  `s.while`/`s.switch`/`s.try_catch`/`s.db.transaction`/`s.expect.to_throw`",
     "  take their sub-stack as `body` (`try`/`catch`/`finally` for `try_catch`);",
     "  `s.group(body)` and `s.util.post_process(body)` take it **positionally**.",
-    "  `s.for` is **count-bounded** (`{ as, count, body }`), not from/to. See the",
+    "  `s.for` is **count-bounded** (`{ as, count: <Value>, body }`), not from/to. See the",
     "  authored signatures in `llms/statements-data.md`.",
     "- **MCP servers & agents are distinct root kinds** that both persist under the",
     "  `toolset` payload key (so a same-name pair collides). `mcpServer({...})` exposes",
@@ -1477,8 +1478,9 @@ function renderSections(m) {
     "`s.db.get`/`edit`/`del` on that column answer HTTP 400 `Missing param: field_value` rather",
     "than matching nothing. Declare `f.tableRef(users, { required: true, default: 0 })` for",
     '"not set yet" \u2014 `s.db.get({ fieldName: "driver", fieldValue: c.int(0) })` matches no row and',
-    "binds `null`, which is the answer the null was reaching for. `export()` warns on a literal",
-    "`c.null()` in that slot.",
+    "binds `null`, which is the answer the null was reaching for \u2014 and never `s.db.get_by_id`,",
+    "which validates `id >= 1` and fails the whole request on the sentinel. `export()` warns on a",
+    "literal `c.null()` in that slot.",
     "An `f.vector(size)` column is SEARCHED through `s.db.query`'s `eval` pipeline, not through",
     'any `SearchOp`: give the table `index: [{ type: "vector", fields: [{ name: "embedding", op:',
     '"vector_cosine_ops" }] }]`, then rank with a distance filter + a sort on its alias (see',
@@ -1630,14 +1632,14 @@ function renderSections(m) {
     '- **Every** statement takes `disabled?`/`description?` \u2014 annotations on the stack item, not args: `disabled: true` is Xano\'s "disable step" (kept in the stack, skipped at runtime), `description` the note beside it. Inline on object-arg factories; a trailing object on the positional ones (`s.set_var("x", v, { disabled: true })`).',
     '- **Statements with an `as`** also take `asFilters?` \u2014 `fl.*` filters on the RESULT as it binds, in order, same slot as `disabled`: `s.set_var("x", v, { asFilters: [fl.trim(), fl.lower()] })`. Saves a follow-up `set_var`. Throws without an `as`. The bound variable is RETYPED by the chain (`db.query` + `[fl.count()]` \u2192 `number`); filters whose result the engine declares as `any` (`get`, `set`, `json_decode`, \u2026) fold to `unknown`.',
     "- `s.conditional({ when, then, elif?, else? })` \u2014 if/elif/else. `when` is a condition (`expr`/`cmp`/`and`/`or`); `elif` is an ordered `[{ when, then }]` (each an else-if branch); `then`/`else` are `Statement[]`.",
-    "- `s.for({ as, count, body })` \u2014 **count-bounded** loop (`as` is the index), NOT from/to.",
+    "- `s.for({ as, count, body })` \u2014 **count-bounded** loop (`as` is the index), NOT from/to; `count` is a `Value`, not a bare number.",
     "- `s.foreach({ as, list, body })` \u2014 iterate `list`; `as` is the current item.",
     "- `s.while({ when, body })` \u2014 `when` is a condition (`expr`/`cmp`/`and`/`or`).",
     "- `s.switch({ on, cases: [{ when, body, break? }], default? })` \u2014 multi-way branch on a subject `Value` `on`; each `case`'s `when` is a literal `Value` matched against `on` (NOT a comparison \u2014 use `s.conditional` for `<`/`>`/ranges). \u26A0 **Omitting `break: true` FALLS THROUGH** \u2014 the matched case also runs every LATER case body. Type-checks clean; only `export --strict` catches it.",
     "- `s.try_catch({ try, catch?, finally? })` \u2014 three `Statement[]` blocks.",
     "- `s.group(body)` / `s.util.post_process(body)` \u2014 take a `Statement[]` **positionally**.",
     "- `s.foreach_break()` / `s.foreach_continue()` / `s.foreach_remove()` \u2014 nullary loop control.",
-    "- `s.expect.to_throw({ body, exception? })` \u2014 `body` is the statements expected to raise.",
+    "- `s.expect.to_throw({ body, exception? })` \u2014 `body` is the statements expected to raise; `exception` is a `Value`, not a bare string.",
     ""
   );
   const stmtData = [
@@ -1650,7 +1652,8 @@ function renderSections(m) {
     "primary key `id`):",
     "",
     "- `s.db.get({ table, fieldName?, fieldValue, lock?, output?, as? })` \u2014 one row by field match; `output` restricts returned columns (and overrides column visibility \u2014 it can pull `internal` columns like a password hash).",
-    "- `s.db.get_by_id({ table, id, output?, addon?, tableAlias?, as? })` \u2014 get by primary key. Takes `id`, NOT `fieldName`/`fieldValue`; binds the row or `null` like `db.get`. Both spellings are live in pulled workspaces.",
+    "- `s.db.get_by_id({ table, id, output?, addon?, tableAlias?, as? })` \u2014 get by primary key. Takes `id`, NOT `fieldName`/`fieldValue`; binds the row or `null` for an id that names no row. Both spellings are live in pulled workspaces.",
+    '  - \u26A0 `id` is validated `>= 1`, so the `0` sentinel an optional `f.tableRef` stores fails the request with HTTP 400 `Value is less than the minimum value of 1` \u2014 it does NOT bind `null`. The throw is not scoped to the lookup: inside a `foreach` it kills the whole request, so one unset FK loses every other row\'s work. Read a nullable FK with the field-match form, which binds `null` on `0` and lets the loop finish: `s.db.get({ table, fieldName: "id", fieldValue: ref("row.fk"), as })`.',
     "- `s.db.has({ table, fieldName?, fieldValue, as? })` \u2014 existence test.",
     "- `s.db.del({ table, fieldName?, fieldValue, as? })` \u2014 delete by field match.",
     "- `s.db.add({ table, row?, data?, output?, as? })` \u2014 insert; `row` is a partial keyed by column.",
@@ -1658,8 +1661,9 @@ function renderSections(m) {
     "  - `null` is accepted on EVERY column, including ones that refuse every other literal, and encodes `const:null` \u2014 a write OF null, not the same as omitting the key. A column's `nullable` is not consulted at encode; the engine refuses a null it forbids.",
     "  - Omitting a key on `add` writes the column's type default \u2014 declared `default` if set, `[]` for a list, `{}` for obj/json, else `null`. That `null` is EMITTED, not what the row holds: the engine applies the column's nullability, so a `nullable` column keeps `null` and a non-nullable one lands on its type's zero value (`\"\"`, `0`, `false`). Set the cell when the stored value matters. On `edit` an omitted key keeps its stored value.",
     "  - An `f.password()` cell takes the PLAINTEXT \u2014 the column hashes on write, so a pre-hashed value, or a hashing filter on the cell, stores a hash of a hash that `security.check_password` can never match.",
+    "  - A `table({ seed })` cell hashes the same way: the import writes the plaintext through the column's own rules, so a seeded credential matches under `security.check_password` exactly as an added one does. Demo accounts work as fixtures \u2014 the usual caution about seed data applies, since the plaintext sits in the repo.",
     "- `s.db.edit({ table, fieldName?, fieldValue, row?, data?, output?, as? })` \u2014 update by field match.",
-    "- `s.db.patch({ table, fieldName?, fieldValue, data, output?, as? })` \u2014 merge a partial (`data` is an object value).",
+    "- `s.db.patch({ table, fieldName?, fieldValue, data, output?, as? })` \u2014 merge a partial. \u26A0 Unlike `db.edit`'s `row`, `data` is a single object `Value` \u2014 write `obj({ unread: c.int(0) })`, not the column-keyed record `row` takes.",
     "  On these three, `output` restricts the columns of the RETURNED row only \u2014 it does not change",
     "  what is written. Not offered on `db.del`/`db.has` (their result is a scalar) or on",
     "  `db.add_or_edit` (no output envelope).",
@@ -1668,6 +1672,7 @@ function renderSections(m) {
     "  - `where` / `additionalWhere` \u2014 `expr(...)`, an `expr[]` (ANDed), or a raw `Value`. Rides `context.search`.",
     "    - \u26A0 `ignoreEmpty` DROPS the predicate when the operand is empty \u2014 it does not match zero rows. On an `in` comparison an empty list therefore returns the UNFILTERED set, so never use it to scope rows to a permitted-id list: an empty list of permissions returns everything.",
     "    - For the full operator set use `cmp(left, op, right, { ignoreEmpty? })` \u2014 `op`: `in`/`not in`/`like`/`ilike`/`between`/`contains`/`includes`/`overlaps`/`@>`/`~`/`search`/\u2026 plus the `expr` comparisons. Database-only \u2014 a runtime condition takes the `expr` set only.",
+    '    - \u26A0 `like`/`ilike` take the operand as the PATTERN, verbatim: a bare term matches only an exact whole-string equal, and the endpoint answers HTTP 200 with zero rows \u2014 nothing reports a problem, so a search box that matches nothing ships. For substring matching use `includes`/`not includes`, which wrap the operand in `%\u2026%` themselves and match case-INSENSITIVELY. Prefer them over a hand-built `"%" + term + "%"`, which is non-empty even for an empty term and so defeats `ignoreEmpty`; `includes` composes with it. `contains`/`@>`/`overlaps` are JSON/array containment, not text \u2014 on a text column they 400 `ParseError: Invalid value for param`.',
     "    - Compose nested boolean logic with `and(...)` / `or(...)` groups (also available on `addon()` `where`).",
     "    - An operand may be a bare value (`col`/`inp`/`ref`/`auth`/`c.*`) OR a **filtered** value (`withFilters(...)`) inline \u2014 the engine compiles the string and arithmetic filters (`trim`, `concat`, `upper`, `lower`, \u2026) into the SQL.",
     "    - \u26A0 The REQUEST-TIME timestamp filters have no SQL form and kill the request with a bare fatal naming nothing: `epochms_transform`, `epochms_add_ms`, `epochms_add_secs`, `epochms_date`, `epochms_from_format`. For a relative cutoff use the SQL-side family instead (`epochms_add_day`, `epochms_sub_month`, `epochms_year`, \u2026) or compute it in an earlier `s.set_var` and `ref()` that. `export --strict` reports it; a bare `c.now()` operand is always fine.",
@@ -1793,6 +1798,7 @@ function renderSections(m) {
     '- `s.api.call({ api, input?, headers?, auth?, as? })` \u2014 invoke an endpoint. `api` takes the `query()` def HANDLE (or a `{ name, guid }` pair) \u2014 a bare name is refused, because a query\'s identity is composed from its api group, verb, and name. `headers` REPLACES the request headers the callee sees and takes the same shapes as `s.api.request`\'s \u2014 a `{ "Name": value }` record (values may be tagged), a `string[]` of `"Name: value"` lines, or one `Value`. `auth` is `{ token, ignoreExpiration? }`: `token` must be a BARE STRING \u2014 a tagged `Value` deploys clean and then fails the run with `Param: token - Text filter requires an integer, float, string or boolean value`, since the engine stores that slot as plain text and never evaluates it. Neither slot authenticates the call today; see `llms/tests.md` for what a workflow-test run actually sees. WORKFLOW-TEST ONLY (see Gotchas in `llms.txt`) \u2014 elsewhere it deploys clean and 500s the first real request.',
     '- `s.api.request({ url, method?, params?, headers?, timeout?, follow_location?, verify_host?, verify_peer?, ca_certificate?, certificate?, certificate_pass?, private_key?, private_key_pass?, description?, output?, as? })` \u2014 external HTTP request (`mvp:api_request`). Ergonomic types, each also accepting a dynamic `Value`: `method` suggests the 7 verbs (GET/POST/PUT/DELETE/HEAD/OPTIONS/PATCH), `params` a plain JSON object **or** a FLAT record whose values are tagged `Value`s (`{ count: ref("count") }`, each lifted via a `set` filter \u2014 the same record-of-values shape `response: { key: value }` takes); a tagged value NESTED inside an object or array THROWS at encode, so wrap a structured body in `obj({...})`, which encodes any depth as one `const:expr2` (\u2192 query string for GET/HEAD/OPTIONS, body otherwise), `headers` a `{ "Name": value }` record whose values may be tagged (`{ "x-api-key": env("KEY") }`, each pair joined to a `"Name: value"` line) **or** a `string[]` of full header lines \u2014 prefer a header over a `?key=` query param for a credential \u2014 a URL travels into access logs, proxies and `Referer`. \u26A0 Neither spelling is envelope-safe: the `as` envelope\'s `request` half mirrors `url`, `params` AND `headers`, so never return it raw from a credentialed request \u2014 read `response.result`. A NAME outside the header-token charset is refused, and a LITERAL value carrying a newline is refused; a value may hold `:` and spaces (`Bearer a: b` is a valid value). A TAGGED value cannot be checked at build time, so strip CRLF from caller-controlled input before this slot. Literal pairs lead the emitted array and computed ones follow, so the wire order is not the record\'s key order, `timeout` a `number` in seconds (1\u201386400), and `follow_location`/`verify_host`/`verify_peer` booleans. `description` (Settings tab) and `output` filters (Output tab) ride the envelope. SSL cert interdependencies (certificate\u2194private_key, ca_certificate\u2192verify_peer) are checked at build time when statically provable, else by the engine at runtime. The `as` result is typed as the `{request, response}` envelope (`response.status: number`, `response.result: unknown`), so `InferResponse` resolves a `ref` to it. Same typed result on `webflow.request` and `microservice.request`.',
     "- `s.stream.from_request({ url, method?, \u2026tls, as? })` \u2014 streaming external HTTP request (`mvp:streaming_api_request`); same typed field surface as `s.api.request` (no description/output envelope). `url` is REQUIRED \u2014 it shares `api.request`'s engine declaration, which has no default.",
+    '- `s.util.send_email({ to, subject, message, from?, cc?, bcc?, reply_to?, service_provider?, api_key?, scheduled_at?, as? })` \u2014 send email from the stack. `service_provider` is `"xano"` (the built-in mailer \u2014 needs NO `api_key` and no configuration, and does not require a verified sender) or `"resend"` (pass the key as `api_key: env("RESEND_API_KEY")`). Prefer this over hand-rolling `s.api.request` against a mail provider.',
     "- `s.webflow.request({ path, method?, \u2026tls, as? })` \u2014 Webflow API request (`mvp:connect_webflow_api_request`); like `s.api.request` but addressed by `path` (host is engine-supplied), and `path` is REQUIRED \u2014 the engine rejects an empty one. No `headers`: the engine builds its own from the workspace's Webflow connection and ignores an authored value.",
     "- `s.task.call` / `s.tool.call` / `s.trigger.call` / `s.middleware.call` / `s.addon.call` \u2014 same `{ <target>, input?, as? }` shape against the named kind. `s.task.call` and `s.trigger.call` are WORKFLOW-TEST ONLY (see Gotchas in `llms.txt`); `s.tool.call`, `s.middleware.call` and `s.addon.call` run from any stack.",
     "- `s.action.call({ actionId, input?, registry?, as? })` / `s.action.package.call({ traceId, versionId, slug, input?, registry?, as? })` \u2014 invoke an installed action. Ids are SUPPLIED, never derived from a name: an action is installed onto the instance, so its identity is assigned at install and differs per instance \u2014 read them off a call in a pulled workspace. The package form needs all three parts; they are one composite and two of them address nothing. `registry` is the action's own settings, `input` the per-call arguments.",
@@ -1991,7 +1997,7 @@ function renderDocs(m) {
     {
       path: "llms/statements-calls.md",
       title: "Auth, cross-object calls, and microservices",
-      readWhen: "Read when the stack authenticates (the signup/login/token recipe is here), calls another object (`s.function.run`, `s.api.request`, `s.tool.call`), or reaches a microservice.",
+      readWhen: "Read when the stack authenticates (the signup/login/token recipe is here), calls another object (`s.function.run`, `s.api.request`, `s.tool.call`), sends email (`s.util.send_email`), or reaches a microservice.",
       body: s.stmtCalls
     },
     {

package/dist/{lock-commands-Y4S4NUCE.js → lock-commands-ET7NIOLH.js}

@@ -1,6 +1,6 @@
 import {
   loadDefault
-} from "./chunk-SNO3KHCY.js";
+} from "./chunk-K3YSQDXJ.js";
 import {
   UsageError,
   missingArgument,
@@ -14,9 +14,9 @@ import "./chunk-GNPVYOPB.js";
 import "./chunk-EZG76F7R.js";
 import {
   Xano
-} from "./chunk-FEQTQ6PM.js";
+} from "./chunk-UDL46O35.js";
 import "./chunk-OKNSR7MT.js";
-import "./chunk-64QK6JEK.js";
+import "./chunk-QONOJO45.js";
 import "./chunk-WHOJWOSV.js";
 import "./chunk-5XZ744TS.js";
 import {
@@ -229,4 +229,4 @@ ${lines}
 export {
   runLockCommand
 };
-//# sourceMappingURL=lock-commands-Y4S4NUCE.js.map
+//# sourceMappingURL=lock-commands-ET7NIOLH.js.map

package/dist/node.js

@@ -5,7 +5,7 @@ import {
 import {
   TEST_EXPECT_TYPES,
   expect
-} from "./chunk-2ROR3AZC.js";
+} from "./chunk-5YQOIFT4.js";
 import {
   addon,
   agent,
@@ -17,7 +17,7 @@ import {
   task,
   tool,
   workflowTest
-} from "./chunk-7AXQKABT.js";
+} from "./chunk-7OXFMCTX.js";
 import {
   actionCall,
   actionPackageCall,
@@ -100,7 +100,7 @@ import {
   workflowTestCall,
   workspaceConfig,
   workspaceTrigger
-} from "./chunk-3MDKV2VA.js";
+} from "./chunk-ZZLPTHT5.js";
 import {
   exportBundleJson,
   loadDefault,
@@ -108,7 +108,7 @@ import {
   run,
   writeArtifact,
   writeBundle
-} from "./chunk-SNO3KHCY.js";
+} from "./chunk-K3YSQDXJ.js";
 import "./chunk-JQLR64UC.js";
 import {
   readLockFile,
@@ -119,7 +119,7 @@ import "./chunk-EZG76F7R.js";
 import {
   Xano,
   workspace
-} from "./chunk-FEQTQ6PM.js";
+} from "./chunk-UDL46O35.js";
 import "./chunk-OKNSR7MT.js";
 import {
   LAMBDA_BINDINGS,
@@ -167,7 +167,7 @@ import {
   toSearchParams,
   toolset,
   withFilters
-} from "./chunk-64QK6JEK.js";
+} from "./chunk-QONOJO45.js";
 import "./chunk-WHOJWOSV.js";
 import {
   annotate,

package/dist/{release-command-DN75G5GJ.js → release-command-4EXVLYV2.js}

@@ -6,7 +6,7 @@ import {
 import {
   assertBundleInput,
   loadBundleText
-} from "./chunk-PYS7UNNW.js";
+} from "./chunk-KSV7VOEX.js";
 import {
   sharedSchemaChanges
 } from "./chunk-5HCDZ2XN.js";
@@ -37,7 +37,7 @@ import {
 import "./chunk-3IGNIP6R.js";
 import {
   resolveLockPath
-} from "./chunk-SNO3KHCY.js";
+} from "./chunk-K3YSQDXJ.js";
 import {
   UsageError,
   assertWritableDest
@@ -55,9 +55,9 @@ import {
   success,
   warn
 } from "./chunk-EZG76F7R.js";
-import "./chunk-FEQTQ6PM.js";
+import "./chunk-UDL46O35.js";
 import "./chunk-OKNSR7MT.js";
-import "./chunk-64QK6JEK.js";
+import "./chunk-QONOJO45.js";
 import "./chunk-WHOJWOSV.js";
 import "./chunk-5XZ744TS.js";
 import {
@@ -443,7 +443,7 @@ async function runReleaseCommand(args) {
     { withSeed: req.records === true }
   );
   if (args.static !== void 0) {
-    const { assertNoSeedLeaks } = await import("./deploy-command-QZ3GNLAD.js");
+    const { assertNoSeedLeaks } = await import("./deploy-command-5TTI4TUP.js");
     await assertNoSeedLeaks(args.static, nonPublicSeedValues, args.allowSeedInStatic);
   }
   const workspaceId = auth.workspaceId;
@@ -585,7 +585,7 @@ Retry, or drop \`--backup-branch\` to release without one.`,
     ...backupLabel !== void 0 ? { backupBranch: backupLabel } : {}
   };
   if (args.static !== void 0) {
-    const { buildStaticEnv, deployStaticTo } = await import("./deploy-command-QZ3GNLAD.js");
+    const { buildStaticEnv, deployStaticTo } = await import("./deploy-command-5TTI4TUP.js");
     const env = buildStaticEnv(auth.instance, args.staticEnv);
     const explicit = Object.keys(args.staticEnv).length > 0;
     summary.static = await deployStaticTo(
@@ -604,4 +604,4 @@ Retry, or drop \`--backup-branch\` to release without one.`,
 export {
   runReleaseCommand
 };
-//# sourceMappingURL=release-command-DN75G5GJ.js.map
+//# sourceMappingURL=release-command-4EXVLYV2.js.map

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

@@ -1,6 +1,6 @@
 import {
   resolveMetaTarget
-} from "./chunk-XP7S3VWY.js";
+} from "./chunk-YNZFIY4J.js";
 import "./chunk-MDXR5E5Q.js";
 import "./chunk-3EYUR3TX.js";
 import "./chunk-NDZFBZHC.js";
@@ -224,7 +224,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,
@@ -380,4 +380,4 @@ export {
   runSuite,
   runTestCommand
 };
-//# sourceMappingURL=test-command-RRNNJ45I.js.map
+//# sourceMappingURL=test-command-2F5LKMI6.js.map

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

@@ -22,8 +22,8 @@ import {
   registryUrl,
   suppressUpdateNotice,
   upgradeCommand
-} from "./chunk-CDAQUY5W.js";
-import "./chunk-SNO3KHCY.js";
+} from "./chunk-OW2QZEWL.js";
+import "./chunk-K3YSQDXJ.js";
 import "./chunk-JQLR64UC.js";
 import "./chunk-OYMR5AMJ.js";
 import "./chunk-GNPVYOPB.js";
@@ -35,9 +35,9 @@ import {
   success,
   warn
 } from "./chunk-EZG76F7R.js";
-import "./chunk-FEQTQ6PM.js";
+import "./chunk-UDL46O35.js";
 import "./chunk-OKNSR7MT.js";
-import "./chunk-64QK6JEK.js";
+import "./chunk-QONOJO45.js";
 import "./chunk-WHOJWOSV.js";
 import "./chunk-5XZ744TS.js";
 import "./chunk-7JDT4PBU.js";
@@ -174,4 +174,4 @@ function messageOf(err) {
 export {
   runUpgradeCommand
 };
-//# sourceMappingURL=upgrade-command-XFOAWDI3.js.map
+//# sourceMappingURL=upgrade-command-QL523I62.js.map

package/dist/{validate-command-GLF5ZOOW.js → validate-command-SK5FPCV7.js}

@@ -1,8 +1,8 @@
 import {
   assertBundleInput,
   loadBundleText
-} from "./chunk-PYS7UNNW.js";
-import "./chunk-SNO3KHCY.js";
+} from "./chunk-KSV7VOEX.js";
+import "./chunk-K3YSQDXJ.js";
 import "./chunk-JQLR64UC.js";
 import "./chunk-OYMR5AMJ.js";
 import "./chunk-GNPVYOPB.js";
@@ -14,9 +14,9 @@ import {
   success,
   warn
 } from "./chunk-EZG76F7R.js";
-import "./chunk-FEQTQ6PM.js";
+import "./chunk-UDL46O35.js";
 import "./chunk-OKNSR7MT.js";
-import "./chunk-64QK6JEK.js";
+import "./chunk-QONOJO45.js";
 import "./chunk-WHOJWOSV.js";
 import "./chunk-5XZ744TS.js";
 import "./chunk-7JDT4PBU.js";
@@ -119,4 +119,4 @@ function fmt(v) {
 export {
   runValidateCommand
 };
-//# sourceMappingURL=validate-command-GLF5ZOOW.js.map
+//# sourceMappingURL=validate-command-SK5FPCV7.js.map

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

@@ -1,7 +1,7 @@
 import {
   fetchWorkspaceBundle,
   runCodegenCommand
-} from "./chunk-EM5QPTXP.js";
+} from "./chunk-L6TPHWAU.js";
 import "./chunk-ZOYMZZ3S.js";
 import {
   resolveOutputTarget
@@ -19,7 +19,7 @@ import "./chunk-BKDJN76G.js";
 import "./chunk-QTNO2WD6.js";
 import "./chunk-ZUTSMMAG.js";
 import "./chunk-X4DVXBFY.js";
-import "./chunk-C3M5K4ZH.js";
+import "./chunk-6Z5CNWFC.js";
 import {
   isMachineOutput,
   writeJson
@@ -30,14 +30,14 @@ import {
   fetchOrExplain,
   httpFailure
 } from "./chunk-3IGNIP6R.js";
-import "./chunk-2ROR3AZC.js";
+import "./chunk-5YQOIFT4.js";
 import "./chunk-LU7TRWMC.js";
 import "./chunk-MU3O43L2.js";
 import "./chunk-P5C2YKAM.js";
 import "./chunk-Q77KNEUL.js";
 import "./chunk-4BXJGVZ3.js";
-import "./chunk-3MDKV2VA.js";
-import "./chunk-SNO3KHCY.js";
+import "./chunk-ZZLPTHT5.js";
+import "./chunk-K3YSQDXJ.js";
 import {
   removedSubcommand,
   unknownSubcommand
@@ -50,9 +50,9 @@ import {
   step,
   success
 } from "./chunk-EZG76F7R.js";
-import "./chunk-FEQTQ6PM.js";
+import "./chunk-UDL46O35.js";
 import "./chunk-OKNSR7MT.js";
-import "./chunk-64QK6JEK.js";
+import "./chunk-QONOJO45.js";
 import "./chunk-WHOJWOSV.js";
 import "./chunk-5XZ744TS.js";
 import "./chunk-7JDT4PBU.js";
@@ -160,4 +160,4 @@ async function runExport(args) {
 export {
   runWorkspaceCommand
 };
-//# sourceMappingURL=workspace-command-QCFELEGR.js.map
+//# sourceMappingURL=workspace-command-HYA6JEKK.js.map

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

package/llms/fields.md

@@ -35,8 +35,9 @@ an `int`, and a null in it is unqueryable: `null` is never a legal `fieldValue`/
 `s.db.get`/`edit`/`del` on that column answer HTTP 400 `Missing param: field_value` rather
 than matching nothing. Declare `f.tableRef(users, { required: true, default: 0 })` for
 "not set yet" — `s.db.get({ fieldName: "driver", fieldValue: c.int(0) })` matches no row and
-binds `null`, which is the answer the null was reaching for. `export()` warns on a literal
-`c.null()` in that slot.
+binds `null`, which is the answer the null was reaching for — and never `s.db.get_by_id`,
+which validates `id >= 1` and fails the whole request on the sentinel. `export()` warns on a
+literal `c.null()` in that slot.
 An `f.vector(size)` column is SEARCHED through `s.db.query`'s `eval` pipeline, not through
 any `SearchOp`: give the table `index: [{ type: "vector", fields: [{ name: "embedding", op:
 "vector_cosine_ops" }] }]`, then rank with a distance filter + a sort on its alias (see

package/llms/statements-calls.md

@@ -1,6 +1,6 @@
 # Auth, cross-object calls, and microservices
 
-> Read when the stack authenticates (the signup/login/token recipe is here), calls another object (`s.function.run`, `s.api.request`, `s.tool.call`), or reaches a microservice.
+> Read when the stack authenticates (the signup/login/token recipe is here), calls another object (`s.function.run`, `s.api.request`, `s.tool.call`), sends email (`s.util.send_email`), or reaches a microservice.
 
 Auth & calls:
 
@@ -16,6 +16,7 @@ Auth & calls:
 - `s.api.call({ api, input?, headers?, auth?, as? })` — invoke an endpoint. `api` takes the `query()` def HANDLE (or a `{ name, guid }` pair) — a bare name is refused, because a query's identity is composed from its api group, verb, and name. `headers` REPLACES the request headers the callee sees and takes the same shapes as `s.api.request`'s — a `{ "Name": value }` record (values may be tagged), a `string[]` of `"Name: value"` lines, or one `Value`. `auth` is `{ token, ignoreExpiration? }`: `token` must be a BARE STRING — a tagged `Value` deploys clean and then fails the run with `Param: token - Text filter requires an integer, float, string or boolean value`, since the engine stores that slot as plain text and never evaluates it. Neither slot authenticates the call today; see `llms/tests.md` for what a workflow-test run actually sees. WORKFLOW-TEST ONLY (see Gotchas in `llms.txt`) — elsewhere it deploys clean and 500s the first real request.
 - `s.api.request({ url, method?, params?, headers?, timeout?, follow_location?, verify_host?, verify_peer?, ca_certificate?, certificate?, certificate_pass?, private_key?, private_key_pass?, description?, output?, as? })` — external HTTP request (`mvp:api_request`). Ergonomic types, each also accepting a dynamic `Value`: `method` suggests the 7 verbs (GET/POST/PUT/DELETE/HEAD/OPTIONS/PATCH), `params` a plain JSON object **or** a FLAT record whose values are tagged `Value`s (`{ count: ref("count") }`, each lifted via a `set` filter — the same record-of-values shape `response: { key: value }` takes); a tagged value NESTED inside an object or array THROWS at encode, so wrap a structured body in `obj({...})`, which encodes any depth as one `const:expr2` (→ query string for GET/HEAD/OPTIONS, body otherwise), `headers` a `{ "Name": value }` record whose values may be tagged (`{ "x-api-key": env("KEY") }`, each pair joined to a `"Name: value"` line) **or** a `string[]` of full header lines — prefer a header over a `?key=` query param for a credential — a URL travels into access logs, proxies and `Referer`. ⚠ Neither spelling is envelope-safe: the `as` envelope's `request` half mirrors `url`, `params` AND `headers`, so never return it raw from a credentialed request — read `response.result`. A NAME outside the header-token charset is refused, and a LITERAL value carrying a newline is refused; a value may hold `:` and spaces (`Bearer a: b` is a valid value). A TAGGED value cannot be checked at build time, so strip CRLF from caller-controlled input before this slot. Literal pairs lead the emitted array and computed ones follow, so the wire order is not the record's key order, `timeout` a `number` in seconds (1–86400), and `follow_location`/`verify_host`/`verify_peer` booleans. `description` (Settings tab) and `output` filters (Output tab) ride the envelope. SSL cert interdependencies (certificate↔private_key, ca_certificate→verify_peer) are checked at build time when statically provable, else by the engine at runtime. The `as` result is typed as the `{request, response}` envelope (`response.status: number`, `response.result: unknown`), so `InferResponse` resolves a `ref` to it. Same typed result on `webflow.request` and `microservice.request`.
 - `s.stream.from_request({ url, method?, …tls, as? })` — streaming external HTTP request (`mvp:streaming_api_request`); same typed field surface as `s.api.request` (no description/output envelope). `url` is REQUIRED — it shares `api.request`'s engine declaration, which has no default.
+- `s.util.send_email({ to, subject, message, from?, cc?, bcc?, reply_to?, service_provider?, api_key?, scheduled_at?, as? })` — send email from the stack. `service_provider` is `"xano"` (the built-in mailer — needs NO `api_key` and no configuration, and does not require a verified sender) or `"resend"` (pass the key as `api_key: env("RESEND_API_KEY")`). Prefer this over hand-rolling `s.api.request` against a mail provider.
 - `s.webflow.request({ path, method?, …tls, as? })` — Webflow API request (`mvp:connect_webflow_api_request`); like `s.api.request` but addressed by `path` (host is engine-supplied), and `path` is REQUIRED — the engine rejects an empty one. No `headers`: the engine builds its own from the workspace's Webflow connection and ignores an authored value.
 - `s.task.call` / `s.tool.call` / `s.trigger.call` / `s.middleware.call` / `s.addon.call` — same `{ <target>, input?, as? }` shape against the named kind. `s.task.call` and `s.trigger.call` are WORKFLOW-TEST ONLY (see Gotchas in `llms.txt`); `s.tool.call`, `s.middleware.call` and `s.addon.call` run from any stack.
 - `s.action.call({ actionId, input?, registry?, as? })` / `s.action.package.call({ traceId, versionId, slug, input?, registry?, as? })` — invoke an installed action. Ids are SUPPLIED, never derived from a name: an action is installed onto the instance, so its identity is assigned at install and differs per instance — read them off a call in a pulled workspace. The package form needs all three parts; they are one composite and two of them address nothing. `registry` is the action's own settings, `input` the per-call arguments.

package/llms/statements-data.md

@@ -11,7 +11,8 @@ DB reads/writes (`table` is a def handle or name; `fieldName` defaults to the
 primary key `id`):
 
 - `s.db.get({ table, fieldName?, fieldValue, lock?, output?, as? })` — one row by field match; `output` restricts returned columns (and overrides column visibility — it can pull `internal` columns like a password hash).
-- `s.db.get_by_id({ table, id, output?, addon?, tableAlias?, as? })` — get by primary key. Takes `id`, NOT `fieldName`/`fieldValue`; binds the row or `null` like `db.get`. Both spellings are live in pulled workspaces.
+- `s.db.get_by_id({ table, id, output?, addon?, tableAlias?, as? })` — get by primary key. Takes `id`, NOT `fieldName`/`fieldValue`; binds the row or `null` for an id that names no row. Both spellings are live in pulled workspaces.
+  - ⚠ `id` is validated `>= 1`, so the `0` sentinel an optional `f.tableRef` stores fails the request with HTTP 400 `Value is less than the minimum value of 1` — it does NOT bind `null`. The throw is not scoped to the lookup: inside a `foreach` it kills the whole request, so one unset FK loses every other row's work. Read a nullable FK with the field-match form, which binds `null` on `0` and lets the loop finish: `s.db.get({ table, fieldName: "id", fieldValue: ref("row.fk"), as })`.
 - `s.db.has({ table, fieldName?, fieldValue, as? })` — existence test.
 - `s.db.del({ table, fieldName?, fieldValue, as? })` — delete by field match.
 - `s.db.add({ table, row?, data?, output?, as? })` — insert; `row` is a partial keyed by column.
@@ -19,8 +20,9 @@ primary key `id`):
   - `null` is accepted on EVERY column, including ones that refuse every other literal, and encodes `const:null` — a write OF null, not the same as omitting the key. A column's `nullable` is not consulted at encode; the engine refuses a null it forbids.
   - Omitting a key on `add` writes the column's type default — declared `default` if set, `[]` for a list, `{}` for obj/json, else `null`. That `null` is EMITTED, not what the row holds: the engine applies the column's nullability, so a `nullable` column keeps `null` and a non-nullable one lands on its type's zero value (`""`, `0`, `false`). Set the cell when the stored value matters. On `edit` an omitted key keeps its stored value.
   - An `f.password()` cell takes the PLAINTEXT — the column hashes on write, so a pre-hashed value, or a hashing filter on the cell, stores a hash of a hash that `security.check_password` can never match.
+  - A `table({ seed })` cell hashes the same way: the import writes the plaintext through the column's own rules, so a seeded credential matches under `security.check_password` exactly as an added one does. Demo accounts work as fixtures — the usual caution about seed data applies, since the plaintext sits in the repo.
 - `s.db.edit({ table, fieldName?, fieldValue, row?, data?, output?, as? })` — update by field match.
-- `s.db.patch({ table, fieldName?, fieldValue, data, output?, as? })` — merge a partial (`data` is an object value).
+- `s.db.patch({ table, fieldName?, fieldValue, data, output?, as? })` — merge a partial. ⚠ Unlike `db.edit`'s `row`, `data` is a single object `Value` — write `obj({ unread: c.int(0) })`, not the column-keyed record `row` takes.
   On these three, `output` restricts the columns of the RETURNED row only — it does not change
   what is written. Not offered on `db.del`/`db.has` (their result is a scalar) or on
   `db.add_or_edit` (no output envelope).
@@ -29,6 +31,7 @@ primary key `id`):
   - `where` / `additionalWhere` — `expr(...)`, an `expr[]` (ANDed), or a raw `Value`. Rides `context.search`.
     - ⚠ `ignoreEmpty` DROPS the predicate when the operand is empty — it does not match zero rows. On an `in` comparison an empty list therefore returns the UNFILTERED set, so never use it to scope rows to a permitted-id list: an empty list of permissions returns everything.
     - For the full operator set use `cmp(left, op, right, { ignoreEmpty? })` — `op`: `in`/`not in`/`like`/`ilike`/`between`/`contains`/`includes`/`overlaps`/`@>`/`~`/`search`/… plus the `expr` comparisons. Database-only — a runtime condition takes the `expr` set only.
+    - ⚠ `like`/`ilike` take the operand as the PATTERN, verbatim: a bare term matches only an exact whole-string equal, and the endpoint answers HTTP 200 with zero rows — nothing reports a problem, so a search box that matches nothing ships. For substring matching use `includes`/`not includes`, which wrap the operand in `%…%` themselves and match case-INSENSITIVELY. Prefer them over a hand-built `"%" + term + "%"`, which is non-empty even for an empty term and so defeats `ignoreEmpty`; `includes` composes with it. `contains`/`@>`/`overlaps` are JSON/array containment, not text — on a text column they 400 `ParseError: Invalid value for param`.
     - Compose nested boolean logic with `and(...)` / `or(...)` groups (also available on `addon()` `where`).
     - An operand may be a bare value (`col`/`inp`/`ref`/`auth`/`c.*`) OR a **filtered** value (`withFilters(...)`) inline — the engine compiles the string and arithmetic filters (`trim`, `concat`, `upper`, `lower`, …) into the SQL.
     - ⚠ The REQUEST-TIME timestamp filters have no SQL form and kill the request with a bare fatal naming nothing: `epochms_transform`, `epochms_add_ms`, `epochms_add_secs`, `epochms_date`, `epochms_from_format`. For a relative cutoff use the SQL-side family instead (`epochms_add_day`, `epochms_sub_month`, `epochms_year`, …) or compute it in an earlier `s.set_var` and `ref()` that. `export --strict` reports it; a bare `c.now()` operand is always fine.

package/llms/tests.md

@@ -42,7 +42,7 @@ The run is isolated in ways that make a correct test fail for reasons the failur
 
 - The run uses an EMPTY datasource, so **no `table({ seed })` rows exist while it runs** and every `db` read misses. A test that buys seeded row 1 fails with its own precondition message, which reads as a wrong id rather than an empty database. Create what the test needs INSIDE the test — typically a `defineFunction` fixture the stack calls first.
 - `s.api.call` does NOT raise when the endpoint answers with an error. It BINDS the error envelope (`{code, message}`) to its `as` and carries on, so a later `s.expect.to_be_defined({ expr: ref("r.field") })` reports the ASSERTION while the real failure was the call, four statements up. Assert on the envelope — `s.expect.to_contain({ expr: ref("r.code"), value: c.text("ERROR_CODE_INPUT_ERROR") })` — when a call may fail. `s.function.run` raises instead; the two disagree.
-- `s.expect.to_throw({ body, exception? })` runs `body` in an ISOLATED var stack, so a variable bound EARLIER in the test is not visible inside it — bind what the body needs inside the body. `exception` is text the raised message must CONTAIN; omit it to accept any error.
+- `s.expect.to_throw({ body, exception? })` runs `body` in an ISOLATED var stack, so a variable bound EARLIER in the test is not visible inside it — bind what the body needs inside the body. `exception` is a `Value` whose text the raised message must CONTAIN (`c.text("already exists")`, not a bare string); omit it to accept any error.
 - `s.expect.to_throw` catches such a call only when the error carries a MESSAGE. `ERROR_CODE_ACCESS_DENIED` arrives with an empty one, so `to_throw` around an auth-refused call reports `to_throw failed - response is ok` — which reads as a broken auth gate on a gate that works.
 - An endpoint's `auth` gate is NOT enforced on `s.api.call`. A `query({ auth: users })` runs anyway and fails only where its stack dereferences `auth(...)`. A stack that never touches `auth(...)` runs unauthenticated and passes.
 - Neither `auth.token` nor an `Authorization` entry in `headers` authenticates the call — a token that answers 200 over real HTTP is refused here. To cover auth-gated logic, move the body into a `defineFunction` taking the user id and `s.function.call` that; the gate itself is not reachable from a workflow test.
@@ -55,4 +55,5 @@ The run is isolated in ways that make a correct test fail for reasons the failur
 - `xanots test list` shows what is there without running it; `xanots test run "<name>"` runs one. When a name is ambiguous the error prints the qualified `function:math/happy path` form, which `run` also accepts.
 - `--kind unit|workflow` narrows to one family. `--concurrency <n>` defaults to 1: tests share the environment database.
 - A failing suite exits 5, distinct from a crash. Tests that could not be REACHED exit 6 — retry that one, investigate the other. An environment with no tests is success, not failure.
+- For CI, the exit code says THAT something failed and the JSON says WHICH. Every progress line goes to stderr and stdout carries one JSON document — emitted whenever stdout is not a terminal, or on demand with `--json`. `run-all` and `run`: `{ dest, env, total, passed, failed, tests: [{ kind, name, object?, status: "pass"|"fail", message?, timing? }] }`, with the same keys on an empty suite. `list` is `{ dest, env, total, tests: [...] }` and `deploy --test` nests the run under `testRun`. The per-test array is always `tests`.
 - `xanots deploy ./index.ts --test` deploys and then runs the suite against what it just shipped. A failure exits 5 WITHOUT retracting the deploy — the environment is live either way.