@xano/sdk 1.0.0

package/llms/errors.md

@@ -0,0 +1,56 @@
+# Error index
+
+> Read when a request, test, build, or pull fails with a message you did not write — the string, its cause, and where the fix is.
+
+### Request-time (deployed) failures
+
+- `Unable to locate input: <name>` — `inp()` names an undeclared input, or an attached middleware reads its own `input` (never bound). Declare it; a stack value is `ref("var.field")`; middleware reads the body with `s.util.get_all_input`. `llms.txt`; `llms/kinds-core.md`.
+- `Unable to locate var: <a.b>` (HTTP 500) — a dotted `ref` into a null base (a `db.get` miss), or a column absent from the row (`f.password` is `internal`). Guard existence first, or use the null-safe `safe` option; name the column in `output`. In a `post` middleware, `<var>.vars` from `s.util.get_all_input` holds `{ status, result }` (plus `payload` on an error), not the request. `llms.txt`; `llms/kinds-core.md`.
+- `Missing var entry: <name>` inside `s.expect.to_throw` — the body runs in an isolated var stack; bind what it needs inside the body. `llms/tests.md`.
+- `Missing param: field_value` (HTTP 400) — a `db.*` match argument resolved to `null` (a safe ref, a nullable foreign key). Guard existence before the lookup; an optional FK stores `0` and is read with field-match `db.get`. `llms.txt`; `llms/fields.md`.
+- `Value is less than the minimum value of 1` (HTTP 400) — a `db.get` given `0` in an editor-authored workspace (SDK field-match `db.get` answers 200 + null). `llms/statements-data.md`.
+- `Invalid op: <op>` — a `cmp` operator (`in`, `like`, …) in a RUNTIME condition, which takes the `expr` set only; write `or(expr(...), expr(...))`. `llms/kinds-core.md`.
+- `Unsupported param format` / `Unsupported parameter reference` — an aggregate or `eval` `name` that is not a bare column, or a bare `eval` name for a joined column. `llms/statements-data.md`.
+- `ParseError: Invalid value for param` (HTTP 400) — `contains`/`@>`/`overlaps` on a text column (use `includes`), or a joined column qualified without `tableAlias`. `llms/statements-data.md`.
+- `ERROR_FATAL: <Type> does not exist: <type>:<n>` — `s.api.call`/`s.task.call`/`s.trigger.call`/`s.workflow_test.call` outside a workflow test; share logic via `defineFunction` + `s.function.run`. `llms.txt`.
+- `ERROR_FATAL "Unable to decode."` — a populated JSON string where the engine expects `c.obj`'s form; write `c.obj({...})` or `obj({...})`. `llms/values.md`.
+- `Precondition failed.` in place of your message — `error` was a bare string; pass `c.text("…")`. `llms/fields.md`.
+- `Param: token - Text filter requires an integer, float, string or boolean value` — `s.api.call` `auth.token` given a tagged `Value`; it must be a bare string. `llms/statements-calls.md`.
+- Every `s.db.add` into one table 400s naming a column while complaining about its VALUE — the column is named `run`. `llms.txt`.
+- HTTP 200 with an EMPTY body where `0` was expected — a bare `returnType: "count"` of zero; wrap it as `{ count: ref("n") }`. `llms/statements-data.md`.
+- HTTP 200 with `[]` from a `db.query` that matches rows — a paged query (`metadata: true`, the default) whose `output` names bare columns; the selection applies to the ENVELOPE, so prefix them (`items.<column>`) or set `metadata: false` inside `paging`. `llms.txt`; `llms/statements-data.md`.
+- Every field mapped off an `s.api.request` result reads `null` — the upstream answered an error (a 403 for a missing `User-Agent` is the common one) and its body arrived as ordinary `response.result`; send a `User-Agent` and gate on `response.status`. `llms/statements-calls.md`.
+- A lambda returns error TEXT with HTTP 200 (`Could not resolve "node:crypto"`, an undefined-binding message) — the body threw; use the preloaded globals, the surface's bindings, and `capture`. `llms/lambda.md`.
+- `Unable to locate request.` (404) on an endpoint that deployed — a lowercase verb, a `.` in the name, or a CORS `mode` typo that dropped the whole API group. `llms/kinds-core.md`.
+- A browser call fails on a missing `access-control-allow-origin` while deploy looks fine — CORS `mode: "custom"` with `"*"` or an unmatched origin. `llms/kinds-core.md`.
+- A websocket is closed right after the handshake — a refused `connect` gate: an empty/falsy return, a crash, or a gating trigger with no `response`. `llms/triggers.md`.
+- `to_throw failed - response is ok` around an auth-refused call — `ERROR_CODE_ACCESS_DENIED` carries no message; the auth gate is not reachable from a workflow test. `llms/tests.md`.
+- Output reads `Hi [object Object]` — a tagged value inside a JS template literal; compose at runtime with `withFilters` + `fl.concat`. `llms.txt`.
+
+### Build-time and tooling failures
+
+- `export --strict` fails on a warning whose shape is meant (a fixture pinning a hazard) — accept it on ITS def only with `diagnostics: { allow: ["<code>"] }`, which takes any warning code that def raised (never an error) on every def kind. Accepted warnings are still listed: `export({ accepted: [] })`, `--json` `accepted[]`. An allowed code the def no longer raises warns `diagnostics.allow-unused`.
+- `must be ES modules` — package.json says `"type": "commonjs"`; set `"type": "module"`. `llms.txt` Quickstart.
+- A response types as `StackTupleWidened` — a `Statement[]` helper was spread into the stack; return `statements(...)`. `llms.txt`; `llms/statements-runtime.md`.
+- `ERR_PACKAGE_PATH_NOT_EXPORTED` — `tsx -e "import …"`, or running from outside the project root; run a real file with `tsx <file.ts>` from the root. `llms/client.md`.
+- `Missing statement: mvp:placeholder` on import — an unconfigured slot in a pulled tree; replace it with the statement it stands in for. `llms/legacy.md`.
+- A CLI command fails under `--json` or piped (unless stdout carries data): stdout is `{ ok: false, error: { code, message, exitCode, details?, suggestion? } }`, as does a failed release write. Codes: `SDK_SEED_IN_STATIC` (`details.leaks[]` → `publicSeed`), `SDK_EXPORT_INVALID` (`details.diagnostics[]`, `--strict` too), `SDK_DRIFT`, `SDK_BRANCH_TAKEN`, `SDK_BRANCH_LIVE`, `SDK_RELEASE_NAME_TAKEN`, `SDK_RELEASE_FILES_NOT_CARRIED`, `SDK_LIVE_BRANCH_MISMATCH` (`details.conflictsWith`), `SDK_IDENTITY_CONFLICT`, `SDK_KIND_CONFLICT`, `SDK_PRUNE_OUT_OF_SCOPE`, `SDK_IMPORT_REFUSED`, `SDK_SHARED_SCHEMA_CHANGE`, `SDK_CONSTRAINT_VIOLATION`, `SDK_CREDENTIAL_REJECTED` (`details`: `{ profile, credentialType, instance, workspaceId, signIn }`; ids null on a refused env refresh), `SDK_USAGE` (`details.reason: "needs-confirmation"`: run its `Re-run as`), `SDK_ERROR`. Landing refusal `details.refused`: identityConflict, renamePending, kindConflict, uniqueViolation, tableTrigger, importInProgress, importRefused, pruneOutOfScope. `warnings[]` / `details.warnings` / `accepted[]` entries: `{ code, message, subject? }` (`subject`: the def's `{ kind, name }`). Backend documents add `selector` and `workspaceId`.
+- A CLI command reports `could not reach <url>: fetch failed (<code>)` — blocked egress, not a bad credential; fix it before `xanosdk login`, which rotates a single-use refresh token.
+
+### CLI exit codes
+
+A failure document's `exitCode` matches.
+
+| Code | Meaning | Next step |
+|---|---|---|
+| 0 | Success, and a `delete` of a missing name (`alreadyGone`). | — |
+| 1 | A usage error (a missing local file included), a refused request, or anything not listed. | Read the message. |
+| 2 | Ran and disagreed: `preflight` failed, `workspace diff` differed, `promote`, a release or an import did not land as sent or hit a conflict, the `init --from`/`pull` round-trip check failed, a lock or branch-label conflict, or `init` could not install its dependencies or an add-on (scaffolded anyway). | Fix what it reports. |
+| 3 | `deploy --static`: the backend landed, the static site did not. | Deploy the site again. |
+| 4 | `deploy --require-microservices`: a microservice was not ready in time. The backend landed. | Check the microservice. |
+| 5 | `test` / `deploy --test`: the suite ran and a test failed. A deploy is not retracted. | Fix the test or the code. |
+| 6 | `test`, `deploy --test`: the suite could not be reached. | Check the backend; rerun. |
+| 7 | `upgrade --check`: an upgrade is available. | `xanosdk upgrade`. |
+| 8 | A named backend could not be addressed (or a named release, profile, branch, test, module, lock entry, `--seed` guid or local-engine version is missing): gone, expired, unreachable, a stopped local engine, or a busy import. | Retry, or redeploy. |
+| 9 | A write whose outcome is unknown, Ctrl-C during a write included. | Read the target's state before retrying. |
+| 130 | Ctrl-C outside a write or install. | — |

package/llms/fields.md

@@ -0,0 +1,176 @@
+# Column and input types
+
+> Read when declaring a table column (`f.*`) or a function/query input (`input.*`) — a type's options and methods, and the `s.precondition` error/status contract. Also `table({ seed })` rows and `use_xdo`.
+
+Author table columns + function/API inputs with the typed catalog: `f.<type>(opts?)`
+for columns, `input.<type>(opts?)` for inputs. Common opts: `required`, `nullable`,
+`default`, `description`, `access` (a read omits `"internal"` columns, returns `"private"` ones; `InferRow`
+is the full row, both kept), `sensitive` (masks the input's value in request logs; a read still RETURNS a sensitive column — `access: "internal"` keeps it out).
+**`nullable` defaults PER TYPE, matching the engine's own column-creation API**: `true`
+for `f.vector`, `f.uuid`, every `f.geo.*` and every file type (`f.image`/`f.video`/
+`f.audio`/`f.attachment`), `false` for everything else (text, int, decimal, bool, email,
+enum, json, object, password, date, tableRef); inputs add date, timestamp and file, so an
+omitted one binds `null` (a `required` one still accepts an explicit `null`). Pass `nullable` to override —
+e.g. `f.geo.polygon({ nullable: false })`. An empty default becomes NULL only when
+nullable, so a non-null `f.vector(8)` column fails to create (`''` is not a vector).
+**`f.geo.*` values are `{ type, data }`, not GeoJSON.** The same shape goes in and comes
+back. `type` per column: `point` → `"point"`, `data` `{ lng, lat }`; `multipoint` → `"points"`,
+`linestring` → `"path"`, `polygon` → `"poly"` (ring closed for you), `data` `[{ lng, lat }, …]`;
+`multilinestring` → `"paths"`, `multipolygon` → `"polys"`, `data` `[[{ lng, lat }, …], …]`.
+Any other spelling (`"multipoint"`, `"linestring"`, `"Point"`) 400s `Only strings are supported for:`.
+Raw WKT text (`c.text("POINT(1 2)")`) is accepted on write too, but a read never returns one.
+`methods` (validators/transforms, names per type below): `"trim"`, `"min:8"`
+(a text arg keeps its `:`: `"startsWith:https://"`), or `{ name, arg }` — for unlisted names and `pattern`'s error text.
+`f.json({children})` declares the nested shape stored INSIDE a json column — an ARRAY of
+`{name, type, methods?, children?}`, order-significant, distinct from the `FieldMap` that
+`f.object` takes positionally. Omit it for an unstructured json column.
+`f.enum(values)`/`f.vector(size)`/`f.object(children)`/`f.tableRef(table)` take a
+positional payload before opts — and still accept the standard `FieldOptions` after it
+(`f.enum([])`/`input.enum([])` are accepted: a pulled enum with no options, not one to
+author — it brands the column `never`, which `InferRow` surfaces as `undefined`.)
+(e.g. `f.tableRef(users, { required: true })` — only `min`/`max` are listed as tableRef
+methods below, but `required`/`nullable`/`description`/… apply like any field.)
+An **OPTIONAL foreign key wants a `0` sentinel, not `nullable: true`**. `f.tableRef` to an int-keyed table stores
+an `int`, and a null in it is unqueryable: `null` is never a legal `fieldValue`/`id`, so
+`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. A uuid-keyed ref stays nullable even when `required` (a non-null one defaults to `""`, which no insert accepts).
+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
+`s.db.query` → `eval`). Without that pairing the column stores and indexes but nothing
+queries it.
+`{ array: true }` makes any `f.*` scalar a **list column** — `f.text({ array: true })`
+surfaces as `string[]` in `InferRow<typeof table>` (the column analogue of `input.list`).
+**Seed a table's starting rows with `table({ seed })`.** `seed` takes rows
+typed against the table's schema as a WRITE shape (a column without
+`required: true`, and the system columns, may be omitted; `null` needs
+`nullable: true`) — inline (`seed: [{ name: "…" }]`), a FILE
+(`seed: seedFile("./seed.json", import.meta.url)`; path resolves against the DECLARING
+file), or a thunk (`seed: () => import("./seed.json")`, async ok, `.default` unwrapped).
+Inline rows are TYPED against the schema at compile time; a `seedFile`/thunk seed is
+not — `xanosdk export`/`deploy` validates it, naming the row index and column.
+Timestamp seeds: epoch ms, `Date`, ISO 8601 date, or date-time with `Z`/offset; else THROWS.
+Int seeds: whole, in int64 (past 2^53: a string).
+⚠ Prefer `seedFile` for a file: a thunk's `import()` sits in
+YOUR module, so a bundler emits the JSON as a served chunk. Never put secrets
+in `seed`. `deploy --static` REFUSES a build carrying internal/sensitive seed values;
+declare public ones (demo logins) on the table: `publicSeed: ["password"]`.
+A replacing deploy re-seeds cleanly; `--keep-data` writes no seed rows.
+`seed` is evaluated on EVERY build, so a computed value (`Date.now()`) is fine:
+the lock records no seed data.
+A FILE column seeds from a repo file: `logo: hostedFile("./logo.png", import.meta.url)`;
+the row stores each backend's own copy. A wrong-kind file or a non-file column THROWS.
+A release carries no file bytes: `release create` refuses such rows and icons.
+Omit `id` and rows auto-number `1..N` (int PK) or take
+a stable derived uuid (uuid PK); supplying `id` pins it (and
+resets an int sequence past the max). All-or-nothing — mixing explicit and
+omitted `id` throws. A `system:false` PK is the author's to supply. Pinning is
+`seed`-only — `s.db.bulk.add` DROPS `id` unless `allowIdField: true`.
+**`use_xdo` storage mode.** Workspace setting (`registerWorkspace({ use_xdo })`,
+default `false`): `true` stores fields as JSON in the `xdo` column (+ `gin(xdo)` index),
+`false` real columns.
+Tables inherit it; override with `table({ useXdo })`; a merge refuses to switch a populated table.
+A **column `default` must stay within the BMP** — a 4-byte character (codepoint > U+FFFF,
+e.g. an emoji) is rejected at export; put such a value on an `input.<type>({ default })`.
+`input.*` mirrors `f.*` — every column type below is
+a legal input (scalars, files `input.image/video/audio/attachment`, `input.geo.*`,
+`input.vector(size)`, `input.tableRef(table)`, `input.object(children)`), plus
+`input.dbLink(table)` is the odd one: ONE entry that EXPANDS into one input per
+COLUMN of the linked table, so read them by column name (`inp("email")`), never by
+the entry's own name. `hidden: ["created_at"]` drops columns from that expansion.
+`input.list(element)` for arrays — wrap any element constructor, e.g.
+`input.list(input.text())` or `input.list(input.object({ id: f.int() }))`.
+**A file reaches a column in two steps.** `input.file` is the RAW upload (the request's
+multipart/base64 bytes) and cannot be written to a file column directly: store it first —
+`s.storage.create_image({ as: "img", value: inp("avatar"), access: "public" })`
+(read the upload with `inp`; `ref("input.avatar")` spells a stack VARIABLE named
+`input` and fails the request with `Missing var entry: input`) — then write
+`ref("img")` into the `f.image()` cell with `s.db.add`/`edit`. `access` defaults to
+`"public"` (a guessable URL): pass `"private"` and hand out `s.storage.sign_private_url`
+results for anything user-scoped. `create_video`/`create_audio`/`create_attachment` are
+the same shape for the other file columns, each fed `input.file` (`input.image`/… 400s an upload).
+**An empty file column is a stored null that `where` does not see as null.** `expr(col("file"), "!=", c.null())`
+matches EVERY row, and `= c.null()` matches none. Compare a key inside the file instead:
+`expr(col("file.path"), "!=", c.null())` keeps only the rows holding a file.
+**Typed inputs validate/coerce on bind, before your stack runs** — so reach for the
+specific type instead of hand-rolling checks. `input.email({ required: true })` rejects a
+malformed address with a 400 (and trims; add `methods: ["lower"]` to downcase) — no
+`regex_matches` needed; `input.int`/`input.decimal`/`input.uuid`/`input.enum([...])`/`input.date`
+likewise reject or coerce bad input at the boundary. Drop to `input.text` + `s.precondition`
+only for rules no type expresses.
+⚠ `input.url` is NOT one of them — there is no engine `url` type, so it stores as `text`
+and validates NOTHING: a `javascript:`/`data:` URL type-checks, imports, and binds. When the value gets navigated
+to, check the scheme in the stack. It is INPUT ONLY — there is no `f.url` column.
+⚠ `input.timestamp` binds epoch MILLISECONDS. A number is taken as ms as-is, so epoch
+SECONDS (`date +%s`) bind in January 1970 with no error. An ISO-8601 string keeps its
+offset but DROPS fractional seconds (`"…T19:30:00.123Z"` binds `…:00.000`). Send epoch ms
+(`Date.now()`, `getTime()`) whenever sub-second precision matters.
+⚠ `input.list` does NOT reject a non-array: one value binds as a ONE-item list (`"a"` →
+`["a"]`), and a non-JSON string given to an `input.object` binds an object of its
+children's DEFAULTS — so `input.list(input.object({...}))` given `"notalist"` binds
+`[{ name: "", … }]` with a 200. A list `min` does not catch it (that is one item). A string
+starting with `[` is parsed as JSON with NO element check at all. When the shape must hold,
+mark an object child `required: true` (the default-filled object then 400s with its param
+path) and check anything else with `s.precondition`.
+⚠ `s.precondition`'s `error` must be a TAGGED value — `c.text("…")`, not a bare string.
+The engine falls back to the generic "Precondition failed." whenever it reads an empty or
+non-scalar message, and a bare string lands there, so the client never sees your text. The
+`error_type` → HTTP status mapping is correct either way; only the message is lost.
+`error_type` is how a stack sets a FAILURE status: `badrequest`/`inputerror` → 400, `unauthorized` → 401, `accessdenied` → 403, `notfound` → 404, `toomanyrequests` → 429, `standard` → 500.
+For any other status — and for a redirect — use `respond.*`, which is sugar over
+`s.util.set_header` (that statement reaches the status line): `respond.status(201)`,
+`respond.redirect(url, { status?: 301|302|303|307 })` (a TUPLE — spread it; a `Location`
+alone does NOT redirect), and `respond.header(name, value)`. Position in the stack does not
+matter, a later status wins, and a FAILING `precondition` still wins over anything set
+before it. ⚠ `204` answers with an empty body whatever `response` says. ⚠ `respond.status`
+REFUSES `308`/`425`/`451`/`102`/`103`: the platform writes those and does not act on them,
+so the response is 200 with nothing reported — use 301, 429 and 403 instead.
+Normalizing transforms run on bind too — put `trim`/`lower`/`upper` on the input's `methods`
+so `inp("name")` reads already-normalized; don't reroll `var $x = inp("name")|trim` in the stack.
+⚠ `f.decimal`'s size depends on the table's layout; it takes no precision or scale option.
+On a normalized table (`useXdo: false`, the default) it is FIXED: 5 decimal places out
+of 14 total digits. `0.12345678` written and re-read is `0.12346` (`-0.000004` → `0`),
+and the rounding is silent at HTTP 200 — for a scalar `s.db.add`'s `as` output carries the
+STORED value, not the cell you sent, so comparing the two detects the loss; for a list
+(`array: true`) it is the unrounded list you sent, so only a re-read shows it. Rounding happens BEFORE
+the size is checked, so a magnitude needing 10 digits left of the point AFTER rounding 500s
+`ERROR_FATAL` `SQL Error: 0`, naming neither column nor value: `999999999.5` stores,
+`999999999.999999` does not. On a `useXdo: true` table it is a JSON number with no 5dp
+rounding (`0.123456789` reads back `0.123456789`). On either layout, for anything finer than 5dp
+store an integer count of the smallest unit (cents, satoshis) in an `f.int`.
+⚠ `f.int` is a SIGNED 64-bit column — `-9223372036854775808` to `9223372036854775807` —
+and past the ceiling it CLAMPS instead of failing: `9223372036854775808` and
+`18446744073709551615` both store as `9223372036854775807`, at HTTP 200 with no error, so
+an overflowed count reads back as a plausible number. The response carries every digit, but
+`JSON.parse` (so `res.json()`) rounds past `9007199254740991` — read a count that large as
+text or BigInt. `c.int()` refuses an unsafe number literal, so pass the string.
+
+- `f.text` — methods: alphaOk, digitOk, lower, max, min, ok, pattern, startsWith, trim, upper
+- `f.int` — methods: max, min
+- `f.decimal` — methods: max, min
+- `f.bool`
+- `f.uuid`
+- `f.date`
+- `f.email` — methods: lower, trim
+- `f.password` — methods: max, min, minAlpha, minDigit, minLowerAlpha, minSymbol, minUpperAlpha, salt
+- `f.json`
+- `f.timestamp` (stored `epochms`)
+- `f.image` (stored `blob_img`)
+- `f.video` (stored `blob_video`)
+- `f.audio` (stored `blob_audio`)
+- `f.attachment` (stored `blob`)
+- `input.file` — INPUT ONLY (no `f.` form)
+- `input.dbLink` (stored `<tableGuid>_mvpschema`) — INPUT ONLY (no `f.` form)
+- `f.geo.point` (stored `geo_point`)
+- `f.geo.multipoint` (stored `geo_multipoint`)
+- `f.geo.linestring` (stored `geo_linestring`)
+- `f.geo.multilinestring` (stored `geo_multilinestring`)
+- `f.geo.polygon` (stored `geo_polygon`)
+- `f.geo.multipolygon` (stored `geo_multipolygon`)
+- `f.enum`
+- `f.vector` — methods: max, min
+- `f.object` (stored `obj`)
+- `f.tableRef` (stored `int`) — methods: max, min

package/llms/filters.md

@@ -0,0 +1,183 @@
+# Filter catalog
+
+> Read when piping a value through `fl.*` — the full catalog with each filter's argument types.
+
+Attach to a value with `withFilters(v, fl.name(...))` — the value `filters[]`
+pipeline. Filters are passed spread (canonical); the array form
+`withFilters(v, [fl.a(), fl.b()])` is also accepted. Every filter is typed:
+the ones below carry named args, and the rest take NO arguments — call them
+`fl.<name>()`, and passing an argument is a compile error.
+A typed filter's declared argument list is an EXACT count, not a floor: passing more
+than it lists THROWS, in the type and at runtime. The extra argument used to ride into
+the filter's arg list, where the engine either ignores it or fails opaquely on a live
+endpoint. `filter("name", …)` is the untyped escape for a filter the catalog
+under-declares. Seven declared filters are exceptions the engine really does take more from, so they
+stay variadic: `concat` (trailing separator), `index_by` (trailing list flag), `get` (trailing variable
+map), `array_merge` and `array_merge_recursive` (any number of arrays), `jwe_encode` and
+`jwe_decode`. To send more than a zero-argument filter's `()` accepts, use the same
+`filter("name", …)` escape. A filter with NO declared list takes nothing and is emitted
+`()` — except the variadic few listed under the catalog, which take arguments the
+catalog never declared and so are not arity-checked at all.
+A typed filter also accepts one object of NAMED arguments (`fl.add({ value: 1 })`); a key
+the filter does not declare throws rather than being dropped.
+A bare JS **scalar** — string, number or boolean — is accepted in ANY `fl.*` argument and
+wrapped as the constant you would have written by hand (`fl.get("a.b", 0)` encodes
+identically to `fl.get(c.text("a.b"), c.int(0))`). An object or array must still be built
+with `c.obj`/`c.array`. Any argument also takes a runtime value (`inp`, `ref`, a
+`withFilters` chain) — inside `obj()`/`expr()` an argument cannot carry its own filter
+chain, so compute it in a prior `set_var`. The arg types below name each argument's
+ENGINE type, not the JS type you may pass.
+To add to a numeric column (counter, stock, balance), use `s.db.increment`
+(`llms/statements-data.md`) — one atomic UPDATE. A pipeline read-modify-write is NOT
+atomic (concurrent writers lose updates), and `col("clicks")` does NOT resolve to the
+stored value inside a `db.edit` `row` (it is `null`; `null + 1` aborts): `db.get` the row
+`as: "current"`, then `withFilters(ref("current.clicks"), fl.add(c.int(1)))`.
+
+- `fl.add(value: decimal): decimal`
+- `fl.append(value: <T>, path: text): <T>[]`
+- `fl.array_diff(value: <T>[]): <T>[]`
+- `fl.array_diff_assoc(value: <T>[]): <T>[]`
+- `fl.array_fill(start: int, count: int): any[]`
+- `fl.array_fill_keys(keys: any[]): any[]`
+- `fl.array_filter(match: obj, path?: text): <T>[]` — matches by EXAMPLE (an object of key/value pairs), not by code, and compares LOOSELY
+- `fl.array_find(match: obj): <T>` — a MISS THROWS (`Unable to find element.`) rather than yielding null — use `array_has` to test first
+- `fl.array_has(match: obj): bool`
+- `fl.array_intersect(value: <T>[]): <T>[]`
+- `fl.array_intersect_assoc(value: <T>[]): <T>[]`
+- `fl.array_merge(value: <T>[]): <T>[]`
+- `fl.array_merge_recursive(value: <T>[]): <T>[]`
+- `fl.array_push(value: <T>): <T>[]`
+- `fl.array_push_conditional(value: any, conditional: bool): <T>[]`
+- `fl.array_remove(value: <T>, path: text, strict?: bool): <T>[]`
+- `fl.array_replace(match: any, result: any): <T>[]`
+- `fl.array_set(path: text, value: any): obj` — sets a DOTTED path and returns the value; a non-object piped value is replaced by an empty one
+- `fl.array_slice(offset: int, length?: int): <T>[]`
+- `fl.array_unshift(value: <T>): <T>[]`
+- `fl.array_upmerge(match: obj, node: obj): <T>[]` — merges the node INTO each matched element; `array_replace` swaps the element whole
+- `fl.base_convert(from_base: any, to_base: any): text`
+- `fl.bitwise_and(value: int): int`
+- `fl.bitwise_or(value: int): int`
+- `fl.bitwise_xor(value: int): int`
+- `fl.clamp_max(max: decimal): decimal`
+- `fl.clamp_min(min: decimal): decimal`
+- `fl.concat(value: any): text`
+- `fl.contains(search: text): bool` — piped value is the subject text; the arg is the substring searched for
+- `fl.convert_encoding(to: text, from: text): text`
+- `fl.create_object(values: <T>[]): any`
+- `fl.crypto_jwe_decode(check_claims: json, key: json, key_algorithm: enum, content_algorithm: enum, timeDrift?: int): json`
+- `fl.crypto_jwe_encode(headers: json, key: json, key_algorithm: enum, content_algorithm: enum, ttl?: int): text`
+- `fl.crypto_jws_decode(check_claims: json, key: json, algorithm: enum, timeDrift?: int): json`
+- `fl.crypto_jws_encode(headers: json, key: json, algorithm: enum, ttl?: int): text`
+- `fl.csv_create(rows: text[], separator: text, enclosure: text, escape: text): text` — the header-writing counterpart to `csv_encode`: the PIPED value is the list of column names (written as the header line) and `rows` carries the data rows
+- `fl.csv_decode(separator: text, enclosure: text, escape: text): any`
+- `fl.csv_encode(separator: text, enclosure: text, escape: text): text` — writes NO header — values only, each row in THAT row's key order with no normalization across rows, so rows whose keys differ in order or count silently misalign columns. Nested cells are JSON-encoded and `false` writes empty. A piped array of SCALARS is treated as one row. Use `csv_create` for a header
+- `fl.csv_parse(separator: text, enclosure: text, escape: text): any`
+- `fl.decrypt(algorithm: enum, key: text, iv: text): text`
+- `fl.detect_encoding(encodings?: text): text`
+- `fl.div(value: decimal): decimal`
+- `fl.encrypt(algorithm: enum, key: text, iv: text): text`
+- `fl.ends_with(search: text): bool` — piped value is the subject text; the arg is the substring searched for
+- `fl.epochms_add_ms(milliseconds: int): epochms`
+- `fl.epochms_add_secs(seconds: int): epochms`
+- `fl.epochms_date(format: text, timezone?: text): text`
+- `fl.epochms_from_format(format: text, timezone?: text): text`
+- `fl.epochms_transform(format: text, timezone?: text): text` — applies a relative shift (e.g. "+1 day") to the timestamp
+- `fl.eq(value: <T>): bool`
+- `fl.every(code: text, timeout?: int): any[]` — `code` is a JS body run per element (true for all?), over `$this`/`$index`/`$parent`
+- `fl.filter(code: text, timeout?: int): any[]` — `code` is a JS body run per element (keep it? true/false), over `$this`/`$index`/`$parent`
+- `fl.filter_empty(path?: text): <T>[]` — keeps entries that are not empty ("", null, 0, "0", false, [], {})
+- `fl.filter_empty_array(path?: text): <T>[]`
+- `fl.filter_empty_object(path?: text): <T>[]`
+- `fl.filter_empty_text(path?: text): <T>[]`
+- `fl.filter_false(path?: text): <T>[]`
+- `fl.filter_null(path?: text): <T>[]`
+- `fl.filter_zero(path?: text): <T>[]`
+- `fl.find(code: text, timeout?: int): any[]` — `code` is a JS body run per element; returns the first element it accepts
+- `fl.findIndex(code: text, timeout?: int): any[]` — `code` is a JS body run per element; returns the first matching index
+- `fl.first_notempty(value: any): any` — first value that is not empty ("", null, 0, "0", false, [], {})
+- `fl.first_notnull(value: any): any`
+- `fl.fsort(path?: text, type?: "text"|"itext"|"natural"|"inatural"|"number", asc?: bool): <T>[]` — `type` is the comparator, and ONLY "number" compares numerically — "text"/"itext" are strcmp/strcasecmp, "natural"/"inatural" are the human-readable "a2 < a10" orderings. Default "itext". Anything else silently sorts as text, so a numeric sort MUST spell "number"; the path arg drills into each element
+- `fl.get(path: text, default?: json): any` — `path` may be a runtime value: after `fl.index_by("suite_id")`, `fl.get(ref("suite.id"))` returns that key's rows (null for a missing key)
+- `fl.gt(value: <T>): bool`
+- `fl.gte(value: <T>): bool`
+- `fl.has(path: text): bool`
+- `fl.hmac_md5(key: text, raw?: bool): text`
+- `fl.hmac_sha1(key: text, raw?: bool): text`
+- `fl.hmac_sha256(key: text, raw?: bool): text`
+- `fl.hmac_sha384(key: text, raw?: bool): text`
+- `fl.hmac_sha512(key: text, raw?: bool): text`
+- `fl.icontains(search: text): bool` — case-insensitive; piped value is the subject, the arg is the substring
+- `fl.iends_with(search: text): bool` — case-insensitive; piped value is the subject, the arg is the substring
+- `fl.in(search: <T>): bool`
+- `fl.index_by(path: text): { [key: string]: <T>[] }` — a GROUP-BY: every value is an ARRAY of the items sharing that key, even when only one does, so a lookup reads `idx[key][0]`. Items whose path is missing or non-scalar are dropped
+- `fl.istarts_with(search: text): bool` — case-insensitive; piped value is the subject, the arg is the substring
+- `fl.join(separator: text): text`
+- `fl.jwe_decode(arg1: any)`
+- `fl.jwe_encode(arg1: any)`
+- `fl.lambda(code: text, timeout?: int): any` — runs a JS body once over the piped value, which it binds as `$this` (NOT `$parent`)
+- `fl.log(base: <T>): decimal`
+- `fl.lt(value: <T>): bool`
+- `fl.lte(value: <T>): bool`
+- `fl.ltrim(mask?: text): text`
+- `fl.map(code: text, timeout?: int): any[]` — `code` is a JS body run per element, over `$this`/`$index`/`$parent` — build it with `lam.fn`
+- `fl.max(bound?: decimal): decimal`
+- `fl.md5(raw?: bool): text`
+- `fl.min(bound?: decimal): decimal`
+- `fl.mod(value: int): int`
+- `fl.mul(value: decimal): decimal`
+- `fl.ne(value: <T>): bool`
+- `fl.num_max(value: any): decimal`
+- `fl.num_min(value: any): decimal`
+- `fl.number_format(decimals: int, decimal_separator: text, thousands_separator: text): string`
+- `fl.pick(keys: text): <T>`
+- `fl.pow(exp: <T>): decimal`
+- `fl.prepend(value: <T>, path: text): <T>[]`
+- `fl.range(start: int, stop: int): int[]`
+- `fl.reduce(initial_value: int, code: text, timeout?: int): any[]` — `code` is a JS body run per element; the ACCUMULATOR is `$result` (there is no `$acc`) and `initial_value` is REQUIRED — omitting it would slot the code as the initial value
+- `fl.regex_match(subject: text): text[]` — piped value is the PATTERN, the arg is the subject — see `regex_test`
+- `fl.regex_match_all(subject: text): text[]` — piped value is the PATTERN, the arg is the subject — see `regex_test`
+- `fl.regex_quote(delimiter?: text): text`
+- `fl.regex_replace(replacement: text, subject: text): text` — piped value is the PATTERN, `subject` is the text searched — see `regex_test`. The replacement comes FIRST
+- `fl.regex_test(subject: text): bool` — piped value is the PATTERN (build it with `c.regex(...)`); the arg is the subject — the REVERSE of `contains`/`starts_with`. Swapped, it answers false for every input with no error, so write `withFilters(c.regex("^a+$"), fl.regex_test(inp("s")))` (or name the arg: `fl.regex_test({ subject: inp("s") })`). A pattern found in the subject slot is refused at build time
+- `fl.round(precision?: int): decimal`
+- `fl.rtrim(mask?: text): text`
+- `fl.secureid_decode(salt: text): int`
+- `fl.secureid_encode(salt: text): text`
+- `fl.set(path: text, value: any): any`
+- `fl.set_conditional(path: text, value: any, conditional: any): any`
+- `fl.set_ifnotempty(path: text, value: any): any`
+- `fl.set_ifnotnull(path: text, value: any): any`
+- `fl.sha1(raw?: bool): text`
+- `fl.sha256(raw?: bool): text`
+- `fl.sha384(raw?: bool): text`
+- `fl.sha512(raw?: bool): text`
+- `fl.some(code: text, timeout?: int): any[]` — `code` is a JS body run per element (true for any?), over `$this`/`$index`/`$parent`
+- `fl.splice(offset: int, length?: int, path?: text): <T>[]` — returns the REMOVED slice, not the remainder — [1,2,3,4] spliced at offset 1 length 2 yields [2,3]; with a `path` it removes in place and returns the whole value instead
+- `fl.split(separator: text): text[]`
+- `fl.starts_with(search: text): bool` — piped value is the subject text; the arg is the substring searched for
+- `fl.string_replace(search: text, replacement: text): text`
+- `fl.strip_tags(exclude?: text): text`
+- `fl.stripos(search: text): int`
+- `fl.strpos(search: text): int`
+- `fl.sub(value: decimal): decimal`
+- `fl.substr(start: int, length: int): text`
+- `fl.to_epoch_day(timezone?: text): int`
+- `fl.to_epoch_hour(timezone?: text): int`
+- `fl.to_epoch_minute(timezone?: text): int`
+- `fl.to_epoch_ms(timezone?: text): int`
+- `fl.to_epoch_sec(timezone?: text): int`
+- `fl.to_epochms(timezone?: text): epochms`
+- `fl.transform(expression: text): any` — `expression` is Xano Expression Engine source, NOT a JS body — no `return`, and the piped value is `$0` (or `$$`), NOT `$this` (which is null here). `$var`/`$input`/`$env`/`$auth` resolve and filters pipe inside it: `$0 * 2`, `$0|sort|join:","`. Parenthesize a pipe inside an object literal — `{ s: ($0|sort|join:",") }` — or its comma is read as the key separator and later keys vanish silently. For JavaScript use `lambda`
+- `fl.trim(mask?: text): text`
+- `fl.unique(path?: text): <T>[]`
+- `fl.unpick(keys: text): <T>` — returns the object without the named keys (inverse of a pick)
+- `fl.unset(path: text): any`
+- `fl.url_addarg(key: text, value: text, encoding_rfc3986?: bool): text`
+- `fl.url_delarg(key: text): text`
+- `fl.url_getarg(key: text, default?: text): text`
+- `fl.url_hasarg(key: text): text`
+- `fl.yaml_encode(options?: bool, inline?: int, indent?: int): text`
+
+Zero-argument filters — call as `fl.<name>()`; an argument is a compile error: abs, acos, acosh, addslashes, array_entries, array_keys, array_lower, array_pop, array_shift, array_shuffle, array_values, asin, asinh, atan, atanh, avg, base64_decode, base64_decode_urlsafe, base64_encode, base64_encode_urlsafe, bin2hex, bindec, bitwise_not, capitalize, ceil, cos, count, create_object_from_entries, decbin, dechex, decoct, deg2rad, empty, escape, even, exp, first, flatten, floor, from_utf8, hex2bin, hexdec, is_array, is_bool, is_decimal, is_int, is_object, is_text, is_uuid, json_decode, json_encode, last, list_encodings, ln, log10, lower, ms_to_secs, not, null, octdec, odd, product, querystring_parse, rad2deg, reverse, rsort, safe_array, secs_to_ms, sin, sort, sql_alias, sql_esc, sqrt, strip_accents, strlen, sum, tan, text_escape, text_unescape, to_bool, to_decimal, to_expr, to_geo_linestring, to_geo_multilinestring, to_geo_multipoint, to_geo_multipolygon, to_geo_point, to_geo_polygon, to_int, to_text, to_utf8, uid, upper, url_decode, url_decode_rfc3986, url_encode, url_encode_rfc3986, url_parse, uuid4, xml_decode, yaml_decode.
+
+Variadic filters — they take arguments, but no declared list, so the count is not checked: sprintf.

package/llms/kinds-agent-mcp.md

@@ -0,0 +1,30 @@
+# Agent and MCP def shapes
+
+> Read when defining an `agent()`, `mcpServer()`, `prompt()` or `resource()`.
+
+- `mcpServer({ name, guid?, description?, instructions?, docs?, enabled?, canonical?, spec?, tags?, history?, tools?, prompts?, resources?, oauth?, llm?, output? })` — an MCP toolset. `llm?`/`output?` are the same blocks `agent()` takes and are usually absent: an MCP server and an agent are ONE stored object distinguished by `type`. Returns a handle with `getPath()`/`getUrl(baseUrl)` for the Streamable-HTTP endpoint — `getUrl` is NOT idempotent, a `baseUrl` already carrying an `/x2/mcp/<…>/stream` path THROWS, so resolve ONCE from the instance base URL. Fires on an ephemeral. A TENANT rides AFTER the prefix (`/x2/mcp/tenant/<tenant>/<canonical>/<token>/stream`), not as a base-URL segment: `getUrl` LIFTS a `/tenant/<name>` out of the base and re-places it there, so `getUrl(window.XANO_HOST)` is correct as-is; concatenating them by hand builds an unregistered route that 404s. Pass `{ tenant }` when the base URL cannot name it (a tenant on its own domain).
+  - `tools?`: a `ToolsetToolEntry[]`. Pass the `tool()` HANDLES directly (`tools: [saveNote]`); use the `{ tool, enabled?, auth?, type?, resourceUri?, toolMeta? }` wrapper when an entry needs more. `type: "resource"` (+ a required `resourceUri`) is the LEGACY way to publish a tool as an MCP resource — author a `resource()` and list it in `resources` instead; `toolMeta` is extra metadata on a tool entry. The two payload fields are per-type and supplying the other one is refused, because the engine stores it against neither. `auth` names an auth **table** (a `table({ auth: true })` handle or its name) — per-tool, and the only gate there is. ⚠ It is also what gives the tool a CALLER, on an `agent()` exactly as on an MCP server. `auth()` inside a tool whose entry names no table does NOT return null: the call answers a normal result carrying `{"code":"ERROR_FATAL","message":""}`, so the model reads a successful tool result and reports success while nothing is written. A caller token does not rescue it — the ENTRY supplies identity. Spell it `{ tool: saveNote, auth: users }`; `export()` warns. An entry naming no tool THROWS at export; a deliberate raw `id: 0` warns and carries through.
+  - `prompts?` / `resources?`: `prompt()` / `resource()` HANDLES (or names), or a `{ prompt, enabled?, auth? }` / `{ resource, enabled?, auth? }` wrapper. `auth` names the auth table and is what gives the stack a caller: a prompt/resource reading `auth()` behind an entry with none answers every `prompts/get` / `resources/read` with `-32603 "Access Denied"` (`export()` warns `toolset.primitive-reads-auth-ungated`). Listing one target twice THROWS; two resources with one `uri` on one server fail `export()` (`mcp.resource-uri-duplicate`). MCP-server only — `agent()` takes tools only.
+  - `history?` is the server tier for its tools, prompts AND resources alike; an object's own `history` wins. The workspace tier (`workspaceConfig({ history })`) has `prompt` and `resource` keys, both default on.
+  - `oauth?`: per-server sign-in; omit and nothing changes. Union on `mode`; `authTable` (REQUIRED, auth `table()` handle or name) is whose row the signed-in user is — `auth()` on the whole server, `t.auth` in its trigger. Hosted (the platform is the authorization server): `{ mode: "hosted", authTable, loginUrl }` — clients are sent to `loginUrl` (YOUR page, which is also the consent screen) with `mcp_request`; show `s.mcp.oauth.request`, sign the user in, then your endpoint calls `s.mcp.oauth.complete` with their `decision` and the page redirects to the URL it binds. External (your IdP issues tokens): `{ mode: "external", authTable, issuer, column, audience?, audienceAck?, claim?, claimAck?, preset?, allowedClientIds? }` — token `claim` (default `sub`) matched against `column`; `preset` is `auth0|clerk|workos|entra|okta|cognito|generic`. `loginUrl`/`issuer`/`audience` take `env("NAME")` (resolved per environment).
+    - `export()` FAILS: hosted without `loginUrl` (`mcp.oauth-hosted-incomplete`); external without `issuer`/`column` (`mcp.oauth-external-incomplete`); `preset: "clerk"` without `allowedClientIds` (`mcp.oauth-preset-client-ids`); `claim` other than `sub`/`oid`/`email` without `claimAck` (`mcp.oauth-claim-unacked` — users can edit it at most providers). Unknown `mode`/`preset` THROWS; so do the dropped `consent`/`branding`/`trustedClients`.
+- `prompt({ name, guid?, description?, docs?, title?, icons?, tags?, history?, input?, stack?, response?, responseShape?, middleware? })` — an MCP prompt; takes `registerPrompts`. `input` is the prompt's arguments (each field's `description`/`required`/enum `values` reach the client; enum values also answer completion requests). `response`: a text value is ONE user message; a list of `{ role: "user" | "assistant", content }` is sent in order: `s.set_var("m", obj({ list: [obj({ role: c.text("user"), content: ref("body") })] }))`, `response: ref("m.list")`. Without `response` or a top-level `s.return`, `prompts/get` fails.
+- `resource({ name, uri, guid?, description?, docs?, mimeType?, title?, icons?, annotations?, tags?, history?, input?, stack?, response?, responseShape?, middleware? })` — an MCP resource; takes `registerResources`. Clients address it by `uri`, never `name`.
+  - `uri`: a literal (`"docs://readme"`, no `input`) or an RFC 6570 LEVEL-1 template (`"orders://{region}/{order_id}"`). It must start with a scheme; each `{variable}` is letters/digits/`_`, one per brace pair, never two adjacent. `input` must be EXACTLY the template's variables, each a single `text`/`int`/`decimal`/`bool`/`enum`/`email`/`uuid` — anything else THROWS. A value that does not convert is refused before the stack runs.
+  - `response`: a string is returned as text; non-UTF-8 content (a file, binary) as a base64 blob. `mimeType?` omitted → derived from what the stack returns.
+  - `annotations?`: `{ audience?: ("user" | "assistant")[], priority?: 0..1, lastModified?: ISO 8601 string }`.
+- MCP metadata, on `tool`/`prompt`/`resource`: `title?` (display name clients show instead of `name`); `icons?: { src, mimeType?, sizes?, theme? }[]` — `src` is `https:` (≤ 2048 chars), a base64 `data:` URI of PNG/JPEG/WebP (≤ 64 KiB), or `hostedFile("./icon.png", import.meta.url)`, a repo file served at each backend's own absolute URL (a pull keeps the `/vault/…` path); SVG, `http:` and every other scheme THROW; `mimeType` is `image/png|jpeg|webp`, `sizes` a list (`["48x48"]`, `["any"]`), `theme` `light|dark`. Tool only: `annotations?: { readOnlyHint?, destructiveHint?, idempotentHint?, openWorldHint? }` — hints; an unset one is derived by the platform — and `output?`, a structured-output schema in the `input` grammar: a returned plain object then reaches the client as `structuredContent` plus a text copy, and a result that does not match is a tool error naming the field.
+- `s.mcp.elicit({ key, message, input?, as? })` — ask the MCP client's user mid-call; binds `{ action: "accept" | "decline" | "cancel", content? }` (`content` only on accept, keyed by the `input` field names). `key`: a stable name unique in the stack; `message`: string or value. `input` is the form: a FLAT set of `text`/`email`/`date`/`int`/`decimal`/`bool`/`enum` fields (an enum may be a list); nested objects, files, JSON, timestamps, `password` and `sensitive` fields THROW. Works in tool, prompt and resource stacks.
+  - ⚠ The WHOLE stack re-runs from the top when the user answers — everything BEFORE an elicit runs once per round trip, so ASK FIRST, then act. A write before an elicit (`s.db.*` writes, raw SQL, a non-GET `s.api.request`, `s.util.send_email`, `s.function.run`/`.call`, `s.tool.call`) makes `export()` warn `mcp.write-before-elicit`; accept a deliberate one per def with `diagnostics: { allow: ["mcp.write-before-elicit"] }`. An elicit inside `s.db.transaction` commits the transaction's earlier writes on every round trip.
+  - Input is collected only from clients on MCP `2026-07-28` or later that declare form elicitation. Every other caller — an older client, a debug run, an agent, a workflow test — gets `{ action: "cancel" }` and the stack carries on, so ALWAYS handle `cancel`. A runtime error inside an async function run.
+- `s.mcp.progress({ progress, total?, message? })` — report progress to a client that asked for it (a no-op otherwise); values never go backwards (a lower `progress` is sent as the last one).
+- `s.mcp.oauth.complete({ request, decision, unsafe_user_id?, as? })` — run by the endpoint your `loginUrl` page calls after sign-in; `request` is the page's `mcp_request`. Signs in the CALLER (`auth()`, an `authTable` row whose session token is under 10 minutes old) and binds the single-use URL (text) to redirect to. `decision` (`"approve" | "deny"`, REQUIRED) is what the user chose on your page. ⚠ `unsafe_user_id` names the row directly, skipping the caller checks — anyone reaching that endpoint signs in as that user.
+- `s.mcp.oauth.request({ request, as? })` — a pending sign-in's verified details for your `loginUrl` page to show before the user approves: `{ client_name, client_logo, callback_host, client_verified, server_name }`. Does not consume it.
+- `s.mcp.oauth.revoke({ mcp_server, user_id? | grant_id? | all?, as? })` — end hosted sign-ins on a server: EXACTLY ONE of `user_id`, `grant_id`, `all: c.bool(true)`, else `export()` fails (`mcp.oauth-revoke-target`). Binds `{ revoked }`.
+- `agent({ name, guid?, description?, docs?, enabled?, canonical?, tags?, history?, llm, tools?, output? })` — an LLM orchestrator. No top-level `instructions`/`prompt`/`spec` — the prompt lives under `llm`. Invoke from a stack with `s.ai.agent.run({ agent, args })`.
+  - `llm` (REQUIRED): typed provider settings, a discriminated union on `type` (`"xano-free" | "anthropic" | "openai" | "google-genai"`). Shared fields: `systemPrompt?`, `maxSteps?` (default `5`), and `prompt?` XOR `messages?` (genuinely exclusive: both is a type error and throws — the engine stores ONE `prompt_type`, so one would be dropped); plus provider fields (`apiKey?`, `model?`, `temperature?`, `reasoningEffort?`, …). String fields accept Twig placeholders — `{{ $args.x }}` for run inputs (the `args` of `s.ai.agent.run`), `{{ $env.NAME }}` for env vars.
+  - `tools?`: same `ToolsetToolEntry[]` as `mcpServer` — bare `tool()` handles, or a `{ tool, enabled?, auth? }` wrapper when one needs `enabled`/`auth`. A tool reading `auth()` MUST use the wrapper naming the auth table — a bare handle runs it with no caller (see `mcpServer`'s `tools?`).
+  - `output?`: `{ schema: Record<string, input.*>, enabled? }` — structured-output schema. `schema` is a named-field record authored with the `input.*` catalog, exactly like a `defineFunction`/`query` `input:` map (the stored `structuredOutputsSchema` is the same wire shape as function inputs). e.g. `output: { schema: { priority: input.enum(["low","high"]), summary: input.text() } }`. When you pass the agent *handle* to `s.ai.agent.run({ agent })`, `.result` is typed straight from this schema — no `resultShape` witness needed (the shape is declared once). `resultShape` remains only to override that, or to type an agent referenced by bare name.
+  - **Run + read recipe (`s.ai.agent.run`):** bind the run to a var (`s.ai.agent.run({ agent, args, as: "run" })`) — it produces a rich envelope, and the completion is at **`.result`**. Read one structured field with a dotted ref (`response: ref("run.result.priority")`) or the whole completion (`ref("run.result")`, typed from `output.schema`); persist it in a later step the same way (`s.set_var("summary", ref("run.result.summary"))`). `args` is a plain object of run inputs (`{ topic: inp("topic") }` — raw literals are fine, e.g. `{ max_steps: 3 }`) surfaced to the agent as `{{ $args.topic }}`. `.toolCalls` is the FINAL step's calls only (often `[]`); every call is a `.steps[].content[]` entry of `type: "tool-call"`.
+  - **Marketplace:** for chat history, use `@xano-sdk/chatbot`; for vector RAG, use `@xano-sdk/vector` (`tools: [vector.searchTool]`). Find add-ons with `xanosdk marketplace search <q>`.
+- Both kinds persist under the `toolset` payload key, so a same-name `agent` + `mcpServer` pair derives ONE guid and `export()` throws — give them distinct names.

package/llms/kinds-core.md

@@ -0,0 +1,100 @@
+# Core def shapes
+
+> Read when authoring a function, query, api group, task, workflow test, middleware, tool, or addon — and for the `response` and `expr` shapes every one of them uses.
+
+The def-object passed to each factory. `?` = optional. `input` is keyed by
+input name (`input.<type>(opts?)`); `stack` is `Statement[]` (`s.*`); `response`
+is a `ResponseDef` (see **Responses** below). Object identity is `guid?` —
+omit it and it derives from `name` (for a query, from group + verb + name; set it
+to survive a rename).
+
+- `defineFunction({ name, guid?, description?, docs?, workspace?, input?, stack?, response?, tests? })`
+- `query({ name, verb, apiGroup?, guid?, auth?, input?, stack?, response?, responseType?, apiEnabled?, disabled?, cache?, description?, docs?, tests?, example? })` — a `cache` setting turns caching on unless `active: false`
+  - `verb`: `"GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD"` (required), UPPERCASE. Anything else — most often a lowercase `"post"` — makes `query()` THROW, because Xano does NOT reject it: it stores the verb as NULL, a null verb serves as GET, and the endpoint then answers on the wrong method while the one you meant 404s `Unable to locate request.`
+  - `apiGroup`: an `apiGroup()` def handle (or its name) — binds by guid, stable across syncs. Raw numeric `apiGroupId?` is the escape hatch and wins if both given.
+  - `auth`: `false` (no auth) or an auth-table id; `responseType`: `"standard" | "stream"` (default `standard`) — any other spelling THROWS, since Xano stores an unrecognized one as NULL and a null buffers as `standard`, so a misspelled stream quietly does not stream.
+  - `name` is the endpoint PATH within the group.
+    - A `{param}` segment is a URL PATH PARAM bound to the input of the same name, and segments chain: `name: "blog/{slug}/review/{review_id}"` + `input: { slug: input.text(), review_id: input.int() }`. Read it with `inp("slug")` like any other input.
+    - Every `{param}` MUST have a matching input or `query()` THROWS — Xano treats an unbound marker as inert route text, so the endpoint would answer on the path and see nothing.
+    - A `{param}` need NOT be a whole segment (`"blog/post-{slug}"` routes fine), but its type must fit one segment (no object/list/json/file/geo/vector); there are no wildcards or patterns. `required: true` is NOT demanded (the engine's editor leaves path inputs unmarked).
+    - An input a `GET`/`DELETE`/`HEAD` looks ONE ROW up by (`s.db.get`/by-field edit/patch/delete; not `has` or an email/token/code) belongs in the path — `export()` warns `query.path-segment-candidate`: `getPath()` types STATIC. A segment is any value naming WHICH resource is wanted (`"shop/{country}"`); one that NARROWS A LIST (`s.db.query`) stays a query param. Intended? `diagnostics: { allow: [code] }` on the query (any def, for its own advisories) accepts it under `--strict`.
+    - Routes are matched FIRST-FIT in creation order, and a literal gets NO precedence over a `{param}`: `"runs/{id}"` (a text `id`) created before `"runs/trend"` answers `GET /runs/trend` itself. Two routes in one group and verb that one request path can match are REFUSED at `export()` (`query.route-shadowed`) — reordering `registerQueries` cannot fix it, since a release keeps an existing route first. Make the paths disjoint (`"runs/by-id/{id}"`), or declare a numeric param `input.int({ required: true })` (or `decimal`): only a REQUIRED int/decimal segment matches digits only — an OPTIONAL one matches any text, so `input.int()` still takes `trend`.
+    - Inputs absent from the path are ordinary query-string/body params.
+    - Name charset is ONLY `A-Za-z0-9_-/{}`, max 200: a `.` (`"export.zip"`) is NOT rejected by Xano — it stores an EMPTY name that deploys clean then 404s forever, so `query()` THROWS. Use `"export_zip"` and set the extension in the response headers.
+  - **Client recipe:** `q.getPath({ params: { slug: "hello" } })` → `/api:<canonical>/blog/hello` — never interpolate by hand.
+    - `getPath` percent-encodes each value (so `?`/`#`/spaces stay in their segment) and throws on what encoding cannot contain: a `/`, and a segment that becomes `.`/`..` as sent (a URL parser drops those before routing, addressing a different endpoint).
+    - The keys are typed from the literal `name`, so a typo is a compile error.
+    - `q.toSearchParams(input)` drops GET path params (free `query.toSearchParams` keeps them); lists send `k[]=a&k[]=b` (`k=a&k=b` binds only `b`).
+  - Browser bundle cost, the `routes.gen.ts` alternative, and spot-checking a def from Node: `llms/client.md`.
+- `apiGroup({ name, guid?, canonical?, description?, docs?, swagger?, apiGroupEnabled?, documentation?, cors?, middleware? })` — a query container; queries bind to it via their `apiGroup`. `canonical` holds only letters, digits, `_` and `-` (it is the `<canonical>` of `/api:<canonical>`); anything else THROWS at build.
+  - `documentation?`: `{ require_token? }` — the gate on this group's hosted docs. `require_token: true` IS the declaration; the token lives in `xano/.secrets.json` under this group's guid, and a literal `token` FAILS the export. ⚠ ALWAYS emitted, present or not: an absent key is written as the engine default on import, so omitting the block CLEARS an existing gate (the opposite of the `workspaceConfig` rule). `swagger: true` publishes the docs; `require_token` gates them only alongside a non-empty token, so `swagger: true` with no gate makes the whole group readable by anyone with the URL — export warns once per build and `--strict` fails; `diagnostics: { allow: ["api-group.docs-public"] }` accepts it. A declared gate with NO token drops the block, so those bytes clear it: export FAILS under `swagger: true`, and with `swagger` off warns and completes.
+  - `cors?`: `{ mode?, allowOrigins?: string[], allowHeaders?: string[], allowCredentials?, maxAge?, allowMethods?: { get?, post?, put?, patch?, delete?, head? } }`.
+    - `mode?`: `"default"` (the default) | `"custom"` | `"disabled"`, lowercase — a fourth value THROWS at export (`apiGroup()` itself does not check), because Xano neither rejects nor blanks it: it DROPS THE WHOLE API GROUP on import, so the deploy succeeds and every query in the group 404s. ⚠ Every OTHER field applies only under `"custom"`: `"default"` serves a FIXED permissive policy (any origin, `allow-headers: *`, `allow-credentials: true`, `max-age: 86400`) and ignores the block, so setting `maxAge`/`allowCredentials`/`allowHeaders` alone changes nothing. `"disabled"` sends no CORS headers at all, so every browser call fails.
+    - ⚠ Under `"custom"`, `allowOrigins` is matched as EXACT strings (scheme+host+port, no wildcard or subdomain expansion) and `"*"` is compared as a literal origin — it matches NOTHING. An unmatched origin gets no `access-control-*` headers at all, so the browser call fails while export, deploy and the preflight look fine. Name each origin, or use `mode: "default"` for any-origin. `allowMethods` gates the REAL response too: a verb left off gets no CORS headers back even though its preflight passes. Export warns on an empty origin list, a `"*"` entry, and a policy with no method enabled; a non-origin entry (trailing `/`, path) is refused.
+- Tasks, workflow tests, middleware and tools below (agents and MCP servers: `llms/kinds-agent-mcp.md`) share the envelope conventions (`guid?`, `description?`, `docs?`, `tags?`, `history?`) unless noted.
+- `task({ name, guid?, description?, docs?, datasource?, active?, tags?, history?, schedule?, stack?, middleware? })` — a scheduled background job (function-like `stack`, no `input`/`response`). `active?` defaults `true`; `active: false` deploys it parked.
+  - `schedule?`: a `ScheduleDef[]` (NOT a single object) — `{ startsOn, freq?, repeatEnabled?, endsOn?, endsEnabled? }`. `startsOn`/`endsOn` are **timestamp strings** validated at encode time — `"2026-01-01T00:00:00Z"`, or the space-separated `"2026-01-01 00:00:00+0000"` a pulled workspace carries — never epoch numbers, and never zoneless; `freq` is the repeat interval **in SECONDS** (omitted ⇒ runs ONCE) — spell it `every("15m")`, a compile-time duration-to-seconds helper (`s`/`m`/`h`/`d`/`w`, terms concatenate). No cron, no timezone — a fixed-offset `startsOn` drifts an hour at each DST change; for a local time run hourly, gated on the local hour `withFilters(c.now(), fl.epochms_date("G", "America/New_York"))`. `repeatEnabled?`/`endsEnabled?` follow whether `freq`/`endsOn` is set and are recovery-only — state one to reproduce a stored gate left OFF. Fires on an ephemeral (see Gotchas).
+- `workflowTest({ name, guid?, description?, docs?, datasource?, active?, tags?, stack? })` — an end-to-end test. NO `input`/`response`: `.call` something with an `as`, then assert on that var — `s.function.call({ fn, input, as: "r" })`, `s.expect.to_equal({ expr: ref("r"), value: c.int(42) })`. `s.expect.*` belongs here — it is not inert elsewhere (a failure 500s the request), so treat one in a query/function/task as a mistake to remove. `active?` defaults `true`; chain tests with `s.workflow_test.call({ workflowTest: <def handle> })`.
+  - `datasource?`: Default `""` is an EMPTY datasource (recommended), not "no datasource". Any non-empty name makes the engine CLONE it before EVERY run — against production-sized data, slow enough to fail the run, which is why `"live"` warns at compile time. On an EPHEMERAL, `"live"` holds only the seed fixtures (plus rows a `--keep-data` deploy kept), so it is the way to read `table({ seed })` rows — a small clone, dropped after the run. ⚠ The value is STORED, so clear it before you promote or the same test clones the real database.
+- `middleware({ name, guid?, description?, docs?, resultStrategy?, exceptionPolicy?, tags?, history?, input?, stack?, response?, responseShape?, tests? })` — a pre/post interceptor (function-like `stack`); attach it via a host's `middleware: { pre, post }`. ⚠ `input` ENCODES but an ATTACHED middleware never has it bound — the host request binds its own inputs, so `inp()` inside pre/post fails at runtime with `Unable to locate input` and a declared default does not stand in (`export()` warns). Read the request body with `s.util.get_all_input` instead; it yields a `{ type, vars }` envelope whose `vars` DIFFERS BY PHASE: `pre` → the request inputs (`payload.vars.<field>`); `post` → `{ status, result }`, the host's outcome (`payload.vars.result.<field>`; plus `payload` on an error). A request field read in `post` 500s after the host already ran (`export()` warns); read the request there with `s.util.get_raw_input`. `s.middleware.call` is the one path that DOES bind the declared map.
+  - `resultStrategy?`: `"merge" | "replace"` (default `merge`) — how the middleware `response` folds into the accumulator of the phase it is ATTACHED to, and the two phases accumulate DIFFERENT things. In `post` the accumulator is the host's RESULT, so a returned object changes what the CALLER receives. In `pre` it is the host's REQUEST INPUTS, so a returned object changes what the HOST receives. `merge` folds key-by-key, `replace` substitutes wholesale; either way the next entry in the chain sees the updated value. So `pre` + `replace` DISCARDS every caller input the middleware does not re-emit, and a discarded input is then unreadable — a 500, even where it is declared `required: false`, because input defaulting has already happened by the time the override lands.
+  - `exceptionPolicy?`: `"silent" | "rethrow" | "critical"` (default `"rethrow"` — a throw ABORTS the request and surfaces the authored error/status, which is what a guard wants). `"silent"` swallows the throw and lets the request through, so a guard set to it is NOT enforced — use it only for advisory middleware. `"critical"` is `"rethrow"` plus skipping the `post` chain.
+- `tool({ name, guid?, description?, instructions?, docs?, enabled?, title?, annotations?, icons?, output?, tags?, history?, input?, stack?, response?, responseShape?, middleware? })` — a function-like operation (`input`/`stack`/`response`) that a toolset (MCP server or agent) exposes. Register it, then reference it from a toolset's `tools`. `title`/`annotations`/`icons`/`output` are MCP metadata (`llms/kinds-agent-mcp.md`).
+- An addon is a single table-bound db query, NOT a statement stack: `addon({ name, table, tableAlias?, where?, sort?, output: [cols], cardinality?: "single"|"list"|"count"|"exists"|"aggregate", group?, eval?, input?, context? })`, registered via `registerAddons([...])`.
+  - `table` auto-fills the `context.dbo` binding. ⚠ Never author `table: null` — that is a BROKEN table-less addon returning nothing; `codegen` emits it only for an already-broken pulled object.
+  - `tableAlias` is its SQL alias (`context.dbo.as`), qualifying `where`/`sort` columns (`col("merchant.id")`).
+  - `where`/`sort` take the same surface as `s.db.query`; `where` encodes `context.search`, `sort` encodes `context.return.list.sort` (`return.single.sort` with `cardinality: "single"`) and is refused with `count`/`exists`. `where` is the predicate binding the addon to the parent row — `expr(col("id"), "=", inp("user_id"))`.
+  - `cardinality` shapes the result (`context.return.type`, omitted for the `"list"` default). Rarer context (`eval`/`bind`/`lock`) stays raw `context` passthrough.
+  - End to end — define, register, attach:
+    ```ts
+    const author = addon({ name: "author", table: users, input: { user_id: input.int() }, where: expr(col("id"), "=", inp("user_id")), output: ["id", "display_name"], cardinality: "single" });
+    workspace("forum").registerAddons([author]); // plus the tables/queries
+    s.db.query({ table: threads, addon: [{ addon: author, as: "_author", input: { user_id: out("author_id") } }], as: "rows" }) // rows[]._author: { id, display_name }
+    ```
+### Responses
+
+The `response?` field (on functions, queries, tools, middleware, and
+response-bearing triggers) maps to the stored `result[]`:
+
+- `ResponseDef = Value | Record<string, Value>`.
+- A single `Value` → one unnamed result item: `response: ref("rows")`.
+- A record → one named item per key: `response: { user: ref("u"), token: ref("t") }`.
+- Omitted → empty `result[]` (no response body).
+
+### Expressions (`expr`)
+
+`expr(left, op, right)` builds the comparison used by every condition/`where`
+surface — `s.conditional`/`s.while` `when` (incl. each `elif` branch), and
+`db.query` `where`/`additionalWhere` (and the search triggers) — one shared tree.
+
+- `op`: `=`, `!=`, `>`, `<`, `>=`, `<=` (JS aliases `==` `===` `!==` are accepted and normalized).
+- `left`/`right` are `Value`s — `col("x")` (a table column, `db.*` statements only), `ref`, `inp`, `auth(...)`, or `c.*`.
+- For the full operator set (`in`/`like`/`ilike`/`between`/`contains`/`overlaps`/`@>`/`~`/`search`/…)
+  use `cmp(left, op, right, { ignoreEmpty? })`; compose nested boolean logic with `and(...)`/`or(...)`.
+- ⚠ The wider `cmp` operators are DATABASE-only (`where`, table view filter, db trigger
+  `search`). A RUNTIME condition — `s.conditional`/`elif`, `s.while`, `s.precondition`,
+  `array.*` `if` — takes the `expr` set only; the rest are refused at build time because
+  deployed they fail the request with `Invalid op: <op>` on that branch, usually a guard.
+  `cond.*` builds the filter-then-compare form that DOES run there, and handles the operand
+  direction (the engine's `in` filter pipes the ARRAY, the reverse of `contains`): `cond.in`,
+  `notIn`, `contains`/`icontains`/`notContains`, `startsWith`/`endsWith` (+ `i` forms),
+  `empty`/`notEmpty`, `isNull`/`notNull`, `between(v, lo, hi)`, `has(obj, path)`, `count(v, n)`.
+  Each returns a `Comparison`, usable anywhere `expr(...)` is.
+- A condition/`where` accepts a single `expr(...)`/`cmp(...)`, an `and()`/`or()` group, an array of
+  those (ANDed), or (for `where`) a raw `Value`. `s.conditional`/`s.while`/`s.switch`, `db.query`,
+  `precondition`, and the `array.*` predicates all take the same TREE shape (operators per above).
+- ⚠ `mixed(a, { or: b }, { and: c })` reproduces a container whose terms do NOT all join the
+  same way — pulled workspaces contain it. **Do not author it** (export warns `condition.mixed`). The
+  stored form does not record the grouping, and the two places it can appear disagree: a
+  branch (`s.conditional`/`s.while`/`precondition`) folds terms strictly left to right, so
+  `a OR b AND c` is `(a OR b) AND c`, while a `db.query` filter applies the engine's
+  AND-before-OR precedence and selects `a OR (b AND c)`. Write `and(or(a, b), c)` or
+  `or(a, and(b, c))` — each says one reading in every context. Pulls report these as
+  `ambiguous-condition`.
+- A **filtered** operand (`withFilters(...)`) works inline in any condition/`where` (conditional,
+  while, `db.query`/addon, …) — e.g. `cmp(withFilters(col("title"), fl.trim()), "=", inp("q"))`.
+- **Compose a rule set as SIBLINGS, not a folded chain.** `and(...rules)` takes any
+  number of terms and encodes flat; `rules.reduce((acc, r) => and(acc, r))` nests one
+  container per rule, which costs quadratic bytes (512 terms: 394 KiB flat, 21 MiB
+  folded) and is refused past 128 levels. Mixed joins: `and(or(...anyOf), ...allOf)`.
+- e.g. `db.query({ table: posts, where: expr(col("author"), "=", auth("id")), as: "rows" })`.