@xanots/sdk 0.0.9 → 0.0.11

package/llms/tests.md

@@ -51,7 +51,7 @@ The run is isolated in ways that make a correct test fail for reasons the failur
 
 `xanots test run-all` runs the unit tests AND the `workflowTest()` objects an environment carries. It takes no entry file and compiles nothing: it runs what is DEPLOYED, so deploy before testing.
 
-- `--dest ephemeral` (DEFAULT, `--name <env>` to pick one), `--dest sandbox`, or `--dest workspace`. Unlike `deploy`, `workspace` is allowed here — running a test reads.
+- `--env ephemeral` (DEFAULT — the one this project last deployed to), `--env ephemeral:<name>`, or `--env workspace`. Same grammar as `init --from`. `deploy` takes no `--env` at all; `test` does, and `workspace` is allowed here because running a test only reads.
 - `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.

package/llms/values.md

@@ -12,7 +12,7 @@
 - `c.array(a: Json[]) => Value` — Array constant (JSON string) → tag "const:array". Plain JSON literals only — a nested tagged value is rejected, same as c.obj.
 - `c.expression(source: string) => Value` — Xano Expression Engine source, passed through VERBATIM → tag "const:expr2". The string IS the expression: c.expression('"Hi, " ~ $input.name'), c.expression("$var.price * $var.qty"). ⚠️ NOT VALIDATED — never parsed or type-checked, invisible to InferResponse, and untouched by a rename that updates every typed ref(); a typo surfaces at runtime or as a wrong answer. Use it ONLY for syntax the typed surfaces cannot express (~ concatenation, inline arithmetic, conditionals) — prefer ref/inp/col, withFilters+fl.*, and obj() (which BUILDS a checked expression). Not the expr() condition builder.
 - `c.now() => Value` — Current time as epoch-ms — the engine-native const:epochms constant (no filter). Valid inline as a where/cmp operand. For cutoff math (cutoff = now - max_age) either compare inline or, for reuse/readability, hoist it into an s.set_var and compare against the var.
-- `obj(fields: Record<string, Value | nested>) => ObjValue<typeof fields>` — Dynamic object value → tag "const:expr2" (an object-literal expression string). The dynamic sibling of c.obj: members may be inp/ref/auth/col values, env()/setting()/sys.*, c.now(), c.* constants, nested records, or arrays — and each member may carry a FILTER CHAIN (withFilters + fl.*), which renders as the expression pipe `$var.row|get:"a.b"`. That matters most for the null-safe drill: db.get binds null on a miss, so ref(path, { safe: true }) inside an obj() is the normal shape, not a workaround — you do NOT need a preceding s.set_var to hoist it. The member record rides the return type, so InferResponse resolves each member the way it resolves a top-level response key — `response: { user: obj({ id: ref("row.id") }) }` derives `{ user: { id: Col | null } }`, and a raw nested object literal (`response: { user: { id: ref("row.id") } }`, auto-wrapped through this) derives the same. NEST WITH A RAW RECORD, not an inner obj() call: an inner call yields a const:expr2 value, which the expression serializer has no spelling for and THROWS. Still rejected: a filter ARGUMENT carrying its own chain (a trailing | binds to the whole value, not one argument), a DISABLED filter (an expression string cannot record that), and the output/response/toolset/reg tags — build those in a prior step and ref() them. Use for e.g. s.ai.agent.run args.
+- `obj(fields: Record<string, Value | nested>) => ObjValue<typeof fields>` — Dynamic object value → tag "const:expr2" (an object-literal expression string). The dynamic sibling of c.obj: members may be inp/ref/auth/col values, env()/setting()/sys.*, c.now(), c.* constants, nested records, or arrays — and each member may carry a FILTER CHAIN (withFilters + fl.*), which renders as the expression pipe `$var.row|get:"a.b"`. That matters most for the null-safe drill: db.get binds null on a miss, so ref(path, { safe: true }) inside an obj() is the normal shape, not a workaround — you do NOT need a preceding s.set_var to hoist it. The member record rides the return type, so InferResponse resolves each member the way it resolves a top-level response key — `response: { user: obj({ id: ref("row.id") }) }` derives `{ user: { id: Col | null } }`, and a raw nested object literal (`response: { user: { id: ref("row.id") } }`, auto-wrapped through this) derives the same. A constant record or list has two spellings that both work and render identically: bare (`{ a: 1 }`, `[]`) or `c.obj(...)`/`c.array([...])` — reach for the bare form, it is shorter. NEST WITH A RAW RECORD, not an inner obj() call: an inner call yields a const:expr2 value, which the expression serializer has no spelling for and THROWS. The legacy blank `c.obj(null)` is refused here (it evaluates to null, not {}) — write c.null() or c.obj(). Still rejected: a filter ARGUMENT carrying its own chain (a trailing | binds to the whole value, not one argument), a DISABLED filter (an expression string cannot record that), and the output/response/toolset/reg tags — build those in a prior step and ref() them. Use for e.g. s.ai.agent.run args.
 - `ref(name: string, opts?: { safe?: boolean }) => Value` — Reference a stack variable → tag "var". Pass { safe: true } for null-safe nested access — a dotted ref("owner.user_id", { safe: true }) compiles through the get filter so it resolves to null instead of raising "Unable to locate var" when the base is null.
 - `inp(name: string) => Value` — Reference a function/endpoint input → tag "input". Resolves ONLY against the `input` block of the def it sits in — a value produced earlier in the stack is `ref("var.field")`, not `inp("field")`. A name that is not declared here deploys clean and fails at runtime with ERROR_FATAL "Unable to locate input: <name>" on every branch that reads it; `export()` warns, and `--strict` fails the build. Sending the name in the request does NOT rescue it — an undeclared input is never bound, so the call fails identically with the value present. A dotted path drills INTO a declared input (`inp("action.amount")` needs a declared `action`).
 - `col(name: string) => Value` — Reference a table column → tag "col".

package/llms-full.txt

@@ -1,4 +1,4 @@
-# xanots v0.0.9
+# xanots v0.0.11
 
 > TypeScript SDK that compiles a typed Xano workspace into the importable packageExport JSON bundle.
 
@@ -23,7 +23,9 @@ every gotcha, and control flow. Per-surface detail lives in the topic files list
 below — open the one whose condition matches the task, and skip the rest. For
 exhaustive per-entry detail in NEITHER — a statement's full field schema with engine
 defaults, a filter's complete argument list, the engine `storedName` mapping — do a
-TARGETED lookup in the shipped `manifest.json` (grep or `jq` the one entry you need;
+TARGETED lookup in the shipped `manifest.json` (a program imports it as
+`@xanots/sdk/manifest.json`, which Node ESM needs `with { type: "json" }` on;
+grep or `jq` the one entry you need;
 it is ~65k tokens, so never read it whole). Its top-level keys are `name`, `version`, `description`, `coverage`, `values`, `objectKinds`, `fieldTypes`, `statements`, `filters`, `cli`, `cliGlobalFlags`. `statements` and `filters` are ARRAYS, not maps — SELECT, do not index:
   jq '.statements[] | select(.sPath=="db.get")' manifest.json
   jq '.filters[]    | select(.name=="json_decode")' manifest.json
@@ -50,7 +52,7 @@ installed), so a plain file read resolves them at the version you have.
 - [Column and input types](llms/fields.md): Read when declaring a table column (`f.*`) or a function/query input (`input.*`) — a type's options and accessor methods, and the `s.precondition` error/status contract that rides the same catalog.
 - [Filter catalog](llms/filters.md): Read when piping a value through `fl.*` — the full catalog with each filter's argument types.
 - [Lambda bodies (JavaScript)](llms/lambda.md): Read when writing a JavaScript body, or weighing whether to reach for one at all — `lam.fn`, `fl.lambda`, `fl.reduce`, `s.lambda`. Lambda workers are a bounded shared resource, and each surface binds a different set of identifiers.
-- [Lock file](llms/lock.md): Read when a `xano.lock` exists or should — renaming/pruning/adopting identities, seeding the lock programmatically, or asking which commands write it.
+- [Lock file](llms/lock.md): Read when a `xano.lock` exists or should — renaming/pruning/importing identities, seeding the lock programmatically, or asking which commands write it.
 - [Legacy paradigms and retired statements](llms/legacy.md): Read when the code was PULLED from an existing Xano instance rather than authored here — how a codegen'd tree reads and the three shapes in it that must not be "fixed", plus a `raw({ name: "mvp:…" })` statement, a `realtimeTrigger()`, or any name the catalogs do not list.
 - [Statement catalog](llms/statements-catalog.md): Read for the field signature of a specific statement — every surface, grouped by `s.*` namespace. Look here after the control-flow core in the router does not cover what you need.
 
@@ -115,7 +117,7 @@ which fails with a "must be ES modules" error until you switch it to module.
 
 Set `canonical` on every `apiGroup`. The engine mints the URL token server-side, so
 without one a group's client paths are unresolvable until a lock exists: the bundle
-exports fine and `xanots paths` / `getPath()` then fail on the very queries it just
+exports fine and `xanots routes` / `getPath()` then fail on the very queries it just
 built. An explicit `canonical` resolves them from the source alone.
 
 Build warnings: `export()` prints the shapes that deploy clean and then do the wrong
@@ -134,7 +136,7 @@ api-group/toolset canonical in a lock file written BESIDE THE ENTRY FILE —
 To rename an object: rename in code, export (stderr prints the exact fix-up), run
 `xanots lock rename <kind> <old> <new>`, export again — the original guid is emitted
 under the new name, so the engine renames in place instead of delete+create. Taking
-over an existing workspace: `xanots lock adopt <its-packageExport.json>` first, then
+over an existing workspace: `xanots lock import <its-packageExport.json>` first, then
 export. Pruning, programmatic seeding, and which commands write the lock:
 `llms/lock.md`.
 
@@ -147,19 +149,19 @@ environment and prints its URL.
 AND records — before importing. The blast radius is a disposable environment, not a
 production workspace, but confirm with the user before the first run.
 
-**Two destinations, and the choice changes more than the target.**
+**One destination, and no flag for it.**
 
-- `--dest ephemeral` (DEFAULT) — a NAMED, workspace-scoped, auto-expiring tenant
-  (~1h; `--expires-hours` 1–72 at create time). The active one is tracked in
+- `xanots deploy` writes to a NAMED, workspace-scoped, auto-expiring ephemeral tenant
+  (~1h; `--expires-hours` 1–72 at create time), and to nothing else — an `--env` here
+  is a usage error, not a choice. The active env is tracked in
   `./.xano/ephemeral.json`, so deploying again REFRESHES it and the URL is unchanged;
   if it expired or was swept, a fresh one is created and the new URL is called out.
   `--static` puts the frontend ON THE EPHEMERAL, so backend and frontend share one
   disposable environment.
   ⚠ Only the BACKEND URL survives a refresh: the replace clears static hosting too,
   so `--static` publishes a NEW host every run and the previous URL stops serving.
-- `--dest sandbox` — your single throwaway tenant, no expiry. `--static` puts the
-  frontend on your OWN (parent) workspace instead, because the sandbox tenant does
-  not serve static hosting.
+- `xanots status` names the env this project last deployed to, its URL and its expiry,
+  without your having to remember which one it was.
 - `xanots release` promotes to your INSTANCE workspace and MERGES, not replaces:
   adds/updates what you define, deletes nothing, writes no rows. Destruction is
   opt-in per flag, previewed + confirmed, and can drop a table WITH its rows.
@@ -182,7 +184,7 @@ host falls back to '', and every call 404s off the dev server.
 ⚠ It is INJECTED in bracket form — `window["XANO_HOST"]="…"` — so verifying a deploy
 by grepping `window.XANO_HOST` matches nothing and reads as a failed inject. Grep the
 bare `XANO_HOST` token.
-⚠ `xanots validate` ignores the deploy login and reads `XANO_VALIDATE_INSTANCE` /
+⚠ `xanots preflight` ignores the deploy login and reads `XANO_VALIDATE_INSTANCE` /
 `XANO_VALIDATE_TOKEN` (+ optional `XANO_VALIDATE_WORKSPACE_ID`) from the environment.
 **Displaying a stored file.** A file column comes back as `{ path, name, type, size,
 meta, access, url }`. ⚠ Do NOT use its `url`: on a tenant-scoped environment that field
@@ -266,6 +268,10 @@ Non-obvious authoring rules:
   check-in — use `db.query({ where: [expr(col("habit"), "=", ...), expr(col("date"), "=", ...)], as })`
   (a `where` array is ANDed) and branch on the result, rather than pushing the
   check to the client.
+- **A column named `run` is reserved.** The table deploys and reads back fine, then
+  EVERY `s.db.add` into it 400s — at any column type, with or without a value — and
+  the error names the column while complaining about the VALUE. Use `run_id`. Exact,
+  case-sensitive, one name: `Run`/`runs`/`run_id` are fine. `--strict` fails on it.
 - **System columns are auto-injected.** `id` + `created_at` are prepended to
   every table (`system: true` by default); declaring them by hand is redundant.
   `id` is an `int` PK by default; pass `idType: "uuid"` on the table for a uuid key.
@@ -320,19 +326,20 @@ Non-obvious authoring rules:
   `xanots export`/`deploy` CLI path. Seed rows are never emitted into the bundle
   either way; only `deploy` ships them. The `node:fs` writers
   (`writeBundle`/`writeArtifact`) and lock-file I/O import from `@xanots/sdk/node`,
-  NOT the browser-safe `@xanots/sdk` entry (which a frontend can import query
-  defs from to use `getPath()`/`InferInput` with no Node built-ins in the bundle).
+  NOT the browser-safe `@xanots/sdk` entry (a frontend imports defs from it for
+  `getPath()`/`InferInput`).
   The compiler machinery (per-kind `encode*`, the registries, the bundle serializer,
   the lock model) is on `@xanots/sdk/internal` and is never needed to author.
+  READING a bundle back is `@xanots/sdk/bundle` — a statement walker (`2.if.0` paths),
+  a structural hash, `mvp:*` catalog, `tableRefOf`.
 - **Client bundle size / tree-shaking.** `@xanots/sdk` is `sideEffects: false` and pulls
   no Node built-ins, so a bundler drops unused SDK exports. But importing a **def** for its
   `getPath()`/`verb`/`getUrl()`/`getChannel()` also pulls whatever its `stack` references:
   the `s.*`/`c.*` factory CALLS run at module load to BUILD it. Types are free.
   ⚠ A FLOOR — **~289 kB minified (~57 kB gzipped)** for the FIRST def; splitting modules
   never removes it. The floor is the RUNTIME, not the def: a second def, or a much richer
-  one, adds ~1 kB. So the cost is paid by importing ANY def at all, and reducing what a
-  def does will not reduce it.
-  Fix: `xanots paths <entry> --emit xano/routes.gen.ts` (`routes` is an accepted alias) — verbs, paths, and sockets as
+  one, adds ~1 kB — so reducing what a def does will not reduce it.
+  Fix: `xanots routes <entry> --emit xano/routes.gen.ts` (`paths` is an accepted alias) — verbs, paths, and sockets as
   plain data importing NOTHING, still compile-checked: `routePath("blog/{slug}", { slug })`,
   `channelPath("rooms/{room_id}", { room_id })`, `socketUrl("chat", baseUrl)` (tenant base
   URLs lifted to `wss://h/ws/<tenant>:<canonical>`). A rename is a type error, not a 404.
@@ -385,17 +392,18 @@ Non-obvious authoring rules:
   return.
 - **Build regex-filter patterns with `c.regex(body, flags?)`, never `c.text`.**
   The regex filters (`regex_test`/`regex_match`/`regex_replace`/…) are pattern-piped
-  PHP `preg_*`: the piped value is the PATTERN and must be delimiter-wrapped. A bare
-  `c.text("^[^@\s]+@...$")` is an invalid pattern that matches *nothing* for every
-  input, so a precondition on it silently rejects all values (valid ones included).
-  `c.regex("^[^@\s]+@[^@\s]+\.[^@\s]+$", "i")` wraps + escapes it for you (accepts a
-  JS `RegExp` too: `c.regex(/^…$/i)`), and `withFilters` throws on a bare `c.text`
-  pattern pointing here — from ANY position in the chain, so a normalizer in front
-  (`withFilters(c.text("^hi"), fl.trim(), fl.regex_test(...))`) is refused too; nothing
-  upstream adds the delimiters. `s.expect.to_match`'s `value` is the same PATTERN slot,
-  refused the same way; a `ref`/`inp` pattern is passed through untouched, either place.
-  Better still, prefer a native typed input
-  (`input.email({...})`) over hand-rolled validation.
+  PHP `preg_*`: the piped value is the PATTERN and must be delimiter-wrapped, and the
+  ARGUMENT is the subject. A bare `c.text("^…$")` is an invalid pattern that matches
+  *nothing* for every input, so a precondition on it silently rejects all values.
+  `c.regex(body, "i")` wraps + escapes it for you (a JS `RegExp` too: `c.regex(/^…$/i)`).
+  Reversed — subject piped, pattern in the argument — reads correctly, type-checks, and
+  answers false for EVERY input, so an `if (matches) reject` guard admits what it
+  refuses. `withFilters` throws on a bare `c.text` pattern from ANY position in
+  the chain (a normalizer in front of the regex filter is refused too; nothing upstream
+  adds the delimiters) and on a pattern found in the subject slot; `s.expect.to_match`
+  is the same PATTERN slot, refused both ways; a `ref`/`inp` pattern is passed through untouched.
+  `export()` warns on a reversed pair in stored bytes. Better still:
+  a native typed input (`input.email`) over hand-rolled validation.
 - **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
@@ -419,19 +427,10 @@ Non-obvious authoring rules:
   credential the runner has. As a file that triple is `{ "type": "token",
   "instance_base_url": …, "workspace_id": <n>, "meta_api_token": … }`. The older
   `$XANO_REFRESH_TOKEN` + `$XANO_CLIENT_ID` pair still works but ROTATES: single-use.
-- **Event-driven objects fire on an EPHEMERAL, not in the sandbox.** A `task`
-  (scheduled), an `mcpServer`, and every trigger — `tableTrigger` included — run normally
-  on an ephemeral env, which is `deploy`'s DEFAULT destination. So test an event-driven
-  design (screen-on-insert, cron cleanup, MCP tool call) by deploying it and letting it
-  run.
-  ⚠ Under `--dest sandbox` they import cleanly but their stacks NEVER execute, and there
-  is no way to fire one manually — an insert on a bound table does not run its
-  `tableTrigger`, and the design silently does nothing. Only synchronously-invoked objects
-  (queries, functions, and the agents an endpoint calls with `s.ai.agent.run`) run there.
-  If you must stay on the sandbox, verify the logic out of band: factor the body into a
-  `defineFunction` (or a callable `query`) and invoke it directly — a `tableTrigger` that
-  screens a row on insert should delegate to a function a `query` can also call via
-  `s.function.run`, and you assert against that.
+- **Event-driven objects fire on an EPHEMERAL.** A `task` (scheduled), an `mcpServer`,
+  and every trigger — `tableTrigger` included — run normally on an ephemeral env, which
+  is where `deploy` sends them. So test an event-driven design (screen-on-insert, cron
+  cleanup, MCP tool call) by deploying it and letting it run.
 - **Zero-based numeric keys make `c.obj` a LIST.** `c.obj({ "0": "a" })` evaluates to
   `["a"]`: a numeric key IS an index in the engine's data model, so keys that are exactly
   `0..n-1` come back as a list with HTTP 200 and no error. Write `c.array([...])` when you
@@ -531,7 +530,7 @@ to survive a rename).
   - `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). 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.
+  - `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). The CONVERSE is warned, not enforced: an input a `GET`/`DELETE`/`HEAD` looks ONE ROW up by (`s.db.get`/`get_by_id`/`has`/by-field edit/patch/delete) belongs in the path — `export()` warns `query.path-segment-candidate`. It still serves `?blog_id=1`, but the route is not addressable and `getPath()` types STATIC, so a caller cannot pass the value positionally. A segment is any value naming WHICH resource is wanted, not just an id (`"shop/{country}"`). An input that NARROWS A LIST (`s.db.query`) stays a query-string param. 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 value that IS `.`/`..` (a URL parser drops those before routing — `%2e` counts — addressing a different endpoint). The keys are typed from the literal `name`, so a typo is a compile error. The HANDLE's `q.toSearchParams(input)` drops path params for a GET; the free `query.toSearchParams(input)` has no view of the route and keeps every key.
 - `apiGroup({ name, guid?, canonical?, description?, docs?, swagger?, apiGroupEnabled?, documentation?, cors? })` — a query container; register it and bind queries to it via their `apiGroup`.
   - `cors?`: `{ mode?, allowOrigins?: string[], allowHeaders?: string[], allowCredentials?, maxAge?, allowMethods?: { get?, post?, put?, patch?, delete?, head? } }`.
@@ -539,7 +538,7 @@ to survive a rename).
     - ⚠ 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 call fails in the browser on a missing `access-control-allow-origin` while export, deploy and the preflight all 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.
 - `defineFunction`/`query`/`apiGroup` above cover the queries+tables core; the four below are the "reach past that" primitives (tasks, workflow tests, middleware, tools). Agents and MCP servers are the same family and live in `llms/kinds-agent-mcp.md`. Same 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`).
-  - `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** (default `86400` = daily); `endsOn` present ⇒ the schedule has an end. `endsEnabled?` defaults to that and is recovery-only — state it to reproduce a stored schedule that remembers an end date with the gate OFF. Fires on an ephemeral; does NOT fire in the sandbox (see Gotchas).
+  - `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** (default `86400` = daily); `endsOn` present ⇒ the schedule has an end. `endsEnabled?` defaults to that and is recovery-only — state it to reproduce a stored schedule that remembers an end date with the gate 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?`: **the trap.** 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. `"live"` warns at compile time; other names don't.
 - `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. `s.middleware.call` is the one path that DOES bind the declared map.
@@ -639,7 +638,7 @@ The run is isolated in ways that make a correct test fail for reasons the failur
 
 `xanots test run-all` runs the unit tests AND the `workflowTest()` objects an environment carries. It takes no entry file and compiles nothing: it runs what is DEPLOYED, so deploy before testing.
 
-- `--dest ephemeral` (DEFAULT, `--name <env>` to pick one), `--dest sandbox`, or `--dest workspace`. Unlike `deploy`, `workspace` is allowed here — running a test reads.
+- `--env ephemeral` (DEFAULT — the one this project last deployed to), `--env ephemeral:<name>`, or `--env workspace`. Same grammar as `init --from`. `deploy` takes no `--env` at all; `test` does, and `workspace` is allowed here because running a test only reads.
 - `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.
@@ -650,7 +649,7 @@ The run is isolated in ways that make a correct test fail for reasons the failur
 
 > Read when the workspace defines an `agent()` or an `mcpServer()`.
 
-- `mcpServer({ name, guid?, description?, instructions?, docs?, enabled?, canonical?, spec?, tags?, history?, tools?, 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; not in sandbox.
+- `mcpServer({ name, guid?, description?, instructions?, docs?, enabled?, canonical?, spec?, tags?, history?, tools?, 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.
   - `tools?`: a `ToolsetToolEntry[]`. Pass the `tool()` HANDLES directly (`tools: [saveNote]`), like every other collection in the SDK; use the `{ tool, enabled?, auth? }` wrapper only when a tool needs `enabled: false` or per-tool `auth`. `auth` names an auth **table** (a `table({ auth: true })` handle or its name) — Xano's ONLY MCP auth surface (per-tool; there is no server-level gate). An entry that names no tool (no handle, no `id`) THROWS at export rather than emitting the `id: 0` null reference it used to; a deliberate raw `id: 0` warns and is carried through, so a pulled workspace still round-trips.
 - `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.
@@ -728,7 +727,7 @@ The run is isolated in ways that make a correct test fail for reasons the failur
   - **Tenant instances (isolated DB):** a tenant's realtime objects live in the TENANT's database, so BOTH halves of a client must name the tenant.
     - Socket: `server.getUrl(base, { tenant })` → `/ws/<tenant>:<canonical>`. ⚠ A bare canonical on a tenant host resolves against the INSTANCE workspace instead.
     - That colon form is PECULIAR TO THE SOCKET. Every other tenant URL gives the tenant its OWN segment — the HTTP half of the same client is `https://<host>/tenant/<tenant>/api:<canonical>/…`. NO request header is required for either.
-    - Because the shapes differ, `getUrl` TRANSLATES a tenant base URL instead of concatenating: pass the `https://<host>/tenant/<name>` that `sandbox details` prints (and that deploy injects as `window.XANO_HOST`) and the tenant is LIFTED into the socket form. So `getUrl(window.XANO_HOST)` needs no `{ tenant }`, and a CONFLICTING `{ tenant }` alongside it throws.
+    - Because the shapes differ, `getUrl` TRANSLATES a tenant base URL instead of concatenating: pass the `https://<host>/tenant/<name>` that `xanots status` prints (and that deploy injects as `window.XANO_HOST`) and the tenant is LIFTED into the socket form. So `getUrl(window.XANO_HOST)` needs no `{ tenant }`, and a CONFLICTING `{ tenant }` alongside it throws.
     - ⚠ `getUrl`/`socketUrl` are NOT idempotent — a `baseUrl` that already carries a `/ws/<…>` path (an earlier result of either) THROWS. Resolve ONCE from the http(s) base; pass that result to `new WebSocket`, never back in as a base.
     - Still pass `{ tenant }` explicitly for a tenant on its OWN DOMAIN — the hostname carries it for HTTP, but there is nothing in the URL for the socket to lift.
     - ⚠ Tokens are tenant-scoped (audience `<tenant>:<license>`, not the bare license), so one minted through the instance workspace is REJECTED by a tenant's realtime server — authenticate and dial through the same tenant.
@@ -794,7 +793,7 @@ 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` 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 })`.
+  - ⚠ `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 })`. `export()` warns when the `id` is statically a `0` — the literal `c.int(0)`, an `inp()` whose declared input default is `0`, or a `ref()` to a column declared `default: 0` — and `--strict` fails the build.
 - `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.
@@ -836,6 +835,8 @@ primary key `id`):
   - `distinct` — `"auto"` (default) | `"yes"` | `"no"`, riding `context.return.<list|stream>.distinct`.
 - `s.db.truncate({ table, reset?, as? })` · `s.db.schema({ table, path, as? })`.
 - `s.db.direct_query({ sql, responseType?, args?, parser?, as? })` — `sql` is a **raw string** (not a `Value`); binds go in `args: Value[]`. `parser: "template_engine"` renders the body as a template first — how a query interpolates a column or table name a bound arg cannot carry; omit it for the default.
+  - Template placeholders are Twig over the request scope: `{{ $input.name }}` for an input, `{{ $var.name }}` for a stack variable. ⚠ A BARE `{{ name }}` renders as the empty string — HTTP 200, no error, a query that silently ran with a blank where the value belonged. A bound `?` arg carries a VALUE without the template at all.
+  - ⚠ A table's PHYSICAL name is **not stable across deploys**. A deploy is a full replace, so every table is created afresh and the id in its name moves every time — the same unchanged project redeployed three times gave one table three different names. Never store, cache, hardcode or fixture one: resolve it from `information_schema` inside the same request that uses it.
 - `s.db.external.<engine>.direct_query({ sql, connectionString, responseType?, args?, parser?, as? })` — same shape against an EXTERNAL database; `<engine>` is `postgres`/`mysql`/`mssql`/`oracle`/`snowflake`. `connectionString` is a `Value` — reach for `env(...)`, not a literal — stored as `context.connection_string_flex`. A bare string stores the older `context.connection_string` instead (an env-var name unless it looks like a URL); each form round-trips as itself.
 - `s.db.transaction({ body, as? })` — run a `Statement[]` atomically. `as` binds whatever the block returned.
 - `s.db.bulk.add({ table, items, allowIdField?, as? })` / `s.db.bulk.update` / `s.db.bulk.patch` — `items` is an array `Value`.
@@ -938,7 +939,7 @@ Microservices (the `microservice()` def and the statement that calls it):
 - `c.array(a: Json[]) => Value` — Array constant (JSON string) → tag "const:array". Plain JSON literals only — a nested tagged value is rejected, same as c.obj.
 - `c.expression(source: string) => Value` — Xano Expression Engine source, passed through VERBATIM → tag "const:expr2". The string IS the expression: c.expression('"Hi, " ~ $input.name'), c.expression("$var.price * $var.qty"). ⚠️ NOT VALIDATED — never parsed or type-checked, invisible to InferResponse, and untouched by a rename that updates every typed ref(); a typo surfaces at runtime or as a wrong answer. Use it ONLY for syntax the typed surfaces cannot express (~ concatenation, inline arithmetic, conditionals) — prefer ref/inp/col, withFilters+fl.*, and obj() (which BUILDS a checked expression). Not the expr() condition builder.
 - `c.now() => Value` — Current time as epoch-ms — the engine-native const:epochms constant (no filter). Valid inline as a where/cmp operand. For cutoff math (cutoff = now - max_age) either compare inline or, for reuse/readability, hoist it into an s.set_var and compare against the var.
-- `obj(fields: Record<string, Value | nested>) => ObjValue<typeof fields>` — Dynamic object value → tag "const:expr2" (an object-literal expression string). The dynamic sibling of c.obj: members may be inp/ref/auth/col values, env()/setting()/sys.*, c.now(), c.* constants, nested records, or arrays — and each member may carry a FILTER CHAIN (withFilters + fl.*), which renders as the expression pipe `$var.row|get:"a.b"`. That matters most for the null-safe drill: db.get binds null on a miss, so ref(path, { safe: true }) inside an obj() is the normal shape, not a workaround — you do NOT need a preceding s.set_var to hoist it. The member record rides the return type, so InferResponse resolves each member the way it resolves a top-level response key — `response: { user: obj({ id: ref("row.id") }) }` derives `{ user: { id: Col | null } }`, and a raw nested object literal (`response: { user: { id: ref("row.id") } }`, auto-wrapped through this) derives the same. NEST WITH A RAW RECORD, not an inner obj() call: an inner call yields a const:expr2 value, which the expression serializer has no spelling for and THROWS. Still rejected: a filter ARGUMENT carrying its own chain (a trailing | binds to the whole value, not one argument), a DISABLED filter (an expression string cannot record that), and the output/response/toolset/reg tags — build those in a prior step and ref() them. Use for e.g. s.ai.agent.run args.
+- `obj(fields: Record<string, Value | nested>) => ObjValue<typeof fields>` — Dynamic object value → tag "const:expr2" (an object-literal expression string). The dynamic sibling of c.obj: members may be inp/ref/auth/col values, env()/setting()/sys.*, c.now(), c.* constants, nested records, or arrays — and each member may carry a FILTER CHAIN (withFilters + fl.*), which renders as the expression pipe `$var.row|get:"a.b"`. That matters most for the null-safe drill: db.get binds null on a miss, so ref(path, { safe: true }) inside an obj() is the normal shape, not a workaround — you do NOT need a preceding s.set_var to hoist it. The member record rides the return type, so InferResponse resolves each member the way it resolves a top-level response key — `response: { user: obj({ id: ref("row.id") }) }` derives `{ user: { id: Col | null } }`, and a raw nested object literal (`response: { user: { id: ref("row.id") } }`, auto-wrapped through this) derives the same. A constant record or list has two spellings that both work and render identically: bare (`{ a: 1 }`, `[]`) or `c.obj(...)`/`c.array([...])` — reach for the bare form, it is shorter. NEST WITH A RAW RECORD, not an inner obj() call: an inner call yields a const:expr2 value, which the expression serializer has no spelling for and THROWS. The legacy blank `c.obj(null)` is refused here (it evaluates to null, not {}) — write c.null() or c.obj(). Still rejected: a filter ARGUMENT carrying its own chain (a trailing | binds to the whole value, not one argument), a DISABLED filter (an expression string cannot record that), and the output/response/toolset/reg tags — build those in a prior step and ref() them. Use for e.g. s.ai.agent.run args.
 - `ref(name: string, opts?: { safe?: boolean }) => Value` — Reference a stack variable → tag "var". Pass { safe: true } for null-safe nested access — a dotted ref("owner.user_id", { safe: true }) compiles through the get filter so it resolves to null instead of raising "Unable to locate var" when the base is null.
 - `inp(name: string) => Value` — Reference a function/endpoint input → tag "input". Resolves ONLY against the `input` block of the def it sits in — a value produced earlier in the stack is `ref("var.field")`, not `inp("field")`. A name that is not declared here deploys clean and fails at runtime with ERROR_FATAL "Unable to locate input: <name>" on every branch that reads it; `export()` warns, and `--strict` fails the build. Sending the name in the request does NOT rescue it — an undeclared input is never bound, so the call fails identically with the value present. A dotted path drills INTO a declared input (`inp("action.amount")` needs a declared `action`).
 - `col(name: string) => Value` — Reference a table column → tag "col".
@@ -1110,12 +1111,13 @@ database with a single `s.db.direct_query` UPDATE (`SET clicks = clicks + 1 WHER
 which the DB applies atomically. Reserve the pipeline form for low-contention counters
 where a rare lost update is acceptable.
 ⚠ `direct_query` needs the table's PHYSICAL Postgres name, which the typed surface
-does NOT expose: the engine derives a physical name from workspace + table ids (of the
-form `x<workspace_id>_<table_id>`, e.g. `x6_203970`), ids assigned at import — not knowable
-from a `table()` def (identity is a name + guid, not the numeric id), and `sql_name`
-persists empty. So the safe counter drops out of the typed surface: hardcode
-the physical name after inspecting the deployed table. A typed atomic path needs an
-engine change.
+does NOT expose: the engine derives it from ids assigned at import — not knowable from a
+`table()` def (identity is a name + guid, not the numeric id) — and `sql_name` persists
+empty. The derived name is also NOT STABLE: a deploy is a full replace, so every table is
+created afresh and the id in its name moves each time, on the same unchanged project. So
+the safe counter drops out of the typed surface: resolve the physical name from
+`information_schema` inside the request that uses it, and never store, cache or hardcode
+one. A typed atomic path needs an engine change.
 
 - `fl.add(value: decimal): decimal`
 - `fl.append(value: <T>, path: text): <T>[]`
@@ -1207,11 +1209,11 @@ engine change.
 - `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[]`
-- `fl.regex_match_all(subject: text): text[]`
+- `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`
-- `fl.regex_test(subject: text): bool`
+- `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`
@@ -1367,7 +1369,7 @@ TypeScript annotations survive in the body, and top-level `await` works.
 
 # Lock file
 
-> Read when a `xano.lock` exists or should — renaming/pruning/adopting identities, seeding the lock programmatically, or asking which commands write it.
+> Read when a `xano.lock` exists or should — renaming/pruning/importing identities, seeding the lock programmatically, or asking which commands write it.
 
 `xano.lock` pins each object's guid and each api-group/toolset canonical, so renames
 stay renames (guids otherwise derive from `(type, name)`; a query's from `(api group,
@@ -1380,11 +1382,11 @@ old key drops automatically once its guid re-lands under the composed one).
 - `xanots lock rename <kind> <old> <new>` — `kind` is the payload key (or `table`/`api_group`).
   Run it after renaming in code; the next export emits the original guid under the new name.
 - `xanots lock prune <entry-file> [keys…] --yes` — drops orphaned entries. Finding orphans
-  RUNS the entry's module scope (env assertions included); `--no-verify --yes <kind:name>…`
+  RUNS the entry's module scope (env assertions included); `--identity-only --yes <kind:name>…`
   prunes named keys with no evaluation and no orphan check.
-- `xanots lock adopt <live-bundle.json> [--yes]` — seed the lock from an engine
+- `xanots lock import <live-bundle.json> [--yes]` — seed the lock from an engine
   packageExport when taking over an existing workspace.
-- Every lock subcommand accepts `--lock=<path>`. `rename`/`adopt` take no entry file, so
+- Every lock subcommand accepts `--lock=<path>`. `rename`/`import` take no entry file, so
   from outside the lock's directory pass `--lock` (or `--entry=<entry-file>` to derive it).
 - Programmatic use: call `seedLockOverrides(readLockFile(path))` BEFORE importing any def
   module — references bake guids at import time, so late seeding is a silent no-op
@@ -1392,7 +1394,7 @@ old key drops automatically once its guid re-lands under the composed one).
 
 What writes the lock: `export`/`deploy` of an ENTRY FILE update it via the shared compile
 step — only when a lock exists or `--lock` is passed. Nothing from a DEPLOY is written
-back beyond that (an ephemeral/sandbox is a separate workspace, so its identities must
+back beyond that (an ephemeral is a separate workspace, so its identities must
 not pollute yours). The one write-back is `release --replace`, which mints fresh
 identities in the workspace the lock describes: it re-pins the lock from the rebuilt
 workspace, because otherwise the next release matches nothing and duplicates every

package/llms.txt

@@ -1,4 +1,4 @@
-# xanots v0.0.9
+# xanots v0.0.11
 
 > TypeScript SDK that compiles a typed Xano workspace into the importable packageExport JSON bundle.
 
@@ -23,7 +23,9 @@ every gotcha, and control flow. Per-surface detail lives in the topic files list
 below — open the one whose condition matches the task, and skip the rest. For
 exhaustive per-entry detail in NEITHER — a statement's full field schema with engine
 defaults, a filter's complete argument list, the engine `storedName` mapping — do a
-TARGETED lookup in the shipped `manifest.json` (grep or `jq` the one entry you need;
+TARGETED lookup in the shipped `manifest.json` (a program imports it as
+`@xanots/sdk/manifest.json`, which Node ESM needs `with { type: "json" }` on;
+grep or `jq` the one entry you need;
 it is ~65k tokens, so never read it whole). Its top-level keys are `name`, `version`, `description`, `coverage`, `values`, `objectKinds`, `fieldTypes`, `statements`, `filters`, `cli`, `cliGlobalFlags`. `statements` and `filters` are ARRAYS, not maps — SELECT, do not index:
   jq '.statements[] | select(.sPath=="db.get")' manifest.json
   jq '.filters[]    | select(.name=="json_decode")' manifest.json
@@ -50,7 +52,7 @@ installed), so a plain file read resolves them at the version you have.
 - [Column and input types](llms/fields.md): Read when declaring a table column (`f.*`) or a function/query input (`input.*`) — a type's options and accessor methods, and the `s.precondition` error/status contract that rides the same catalog.
 - [Filter catalog](llms/filters.md): Read when piping a value through `fl.*` — the full catalog with each filter's argument types.
 - [Lambda bodies (JavaScript)](llms/lambda.md): Read when writing a JavaScript body, or weighing whether to reach for one at all — `lam.fn`, `fl.lambda`, `fl.reduce`, `s.lambda`. Lambda workers are a bounded shared resource, and each surface binds a different set of identifiers.
-- [Lock file](llms/lock.md): Read when a `xano.lock` exists or should — renaming/pruning/adopting identities, seeding the lock programmatically, or asking which commands write it.
+- [Lock file](llms/lock.md): Read when a `xano.lock` exists or should — renaming/pruning/importing identities, seeding the lock programmatically, or asking which commands write it.
 - [Legacy paradigms and retired statements](llms/legacy.md): Read when the code was PULLED from an existing Xano instance rather than authored here — how a codegen'd tree reads and the three shapes in it that must not be "fixed", plus a `raw({ name: "mvp:…" })` statement, a `realtimeTrigger()`, or any name the catalogs do not list.
 - [Statement catalog](llms/statements-catalog.md): Read for the field signature of a specific statement — every surface, grouped by `s.*` namespace. Look here after the control-flow core in the router does not cover what you need.
 
@@ -115,7 +117,7 @@ which fails with a "must be ES modules" error until you switch it to module.
 
 Set `canonical` on every `apiGroup`. The engine mints the URL token server-side, so
 without one a group's client paths are unresolvable until a lock exists: the bundle
-exports fine and `xanots paths` / `getPath()` then fail on the very queries it just
+exports fine and `xanots routes` / `getPath()` then fail on the very queries it just
 built. An explicit `canonical` resolves them from the source alone.
 
 Build warnings: `export()` prints the shapes that deploy clean and then do the wrong
@@ -134,7 +136,7 @@ api-group/toolset canonical in a lock file written BESIDE THE ENTRY FILE —
 To rename an object: rename in code, export (stderr prints the exact fix-up), run
 `xanots lock rename <kind> <old> <new>`, export again — the original guid is emitted
 under the new name, so the engine renames in place instead of delete+create. Taking
-over an existing workspace: `xanots lock adopt <its-packageExport.json>` first, then
+over an existing workspace: `xanots lock import <its-packageExport.json>` first, then
 export. Pruning, programmatic seeding, and which commands write the lock:
 `llms/lock.md`.
 
@@ -147,19 +149,19 @@ environment and prints its URL.
 AND records — before importing. The blast radius is a disposable environment, not a
 production workspace, but confirm with the user before the first run.
 
-**Two destinations, and the choice changes more than the target.**
+**One destination, and no flag for it.**
 
-- `--dest ephemeral` (DEFAULT) — a NAMED, workspace-scoped, auto-expiring tenant
-  (~1h; `--expires-hours` 1–72 at create time). The active one is tracked in
+- `xanots deploy` writes to a NAMED, workspace-scoped, auto-expiring ephemeral tenant
+  (~1h; `--expires-hours` 1–72 at create time), and to nothing else — an `--env` here
+  is a usage error, not a choice. The active env is tracked in
   `./.xano/ephemeral.json`, so deploying again REFRESHES it and the URL is unchanged;
   if it expired or was swept, a fresh one is created and the new URL is called out.
   `--static` puts the frontend ON THE EPHEMERAL, so backend and frontend share one
   disposable environment.
   ⚠ Only the BACKEND URL survives a refresh: the replace clears static hosting too,
   so `--static` publishes a NEW host every run and the previous URL stops serving.
-- `--dest sandbox` — your single throwaway tenant, no expiry. `--static` puts the
-  frontend on your OWN (parent) workspace instead, because the sandbox tenant does
-  not serve static hosting.
+- `xanots status` names the env this project last deployed to, its URL and its expiry,
+  without your having to remember which one it was.
 - `xanots release` promotes to your INSTANCE workspace and MERGES, not replaces:
   adds/updates what you define, deletes nothing, writes no rows. Destruction is
   opt-in per flag, previewed + confirmed, and can drop a table WITH its rows.
@@ -182,7 +184,7 @@ host falls back to '', and every call 404s off the dev server.
 ⚠ It is INJECTED in bracket form — `window["XANO_HOST"]="…"` — so verifying a deploy
 by grepping `window.XANO_HOST` matches nothing and reads as a failed inject. Grep the
 bare `XANO_HOST` token.
-⚠ `xanots validate` ignores the deploy login and reads `XANO_VALIDATE_INSTANCE` /
+⚠ `xanots preflight` ignores the deploy login and reads `XANO_VALIDATE_INSTANCE` /
 `XANO_VALIDATE_TOKEN` (+ optional `XANO_VALIDATE_WORKSPACE_ID`) from the environment.
 **Displaying a stored file.** A file column comes back as `{ path, name, type, size,
 meta, access, url }`. ⚠ Do NOT use its `url`: on a tenant-scoped environment that field
@@ -266,6 +268,10 @@ Non-obvious authoring rules:
   check-in — use `db.query({ where: [expr(col("habit"), "=", ...), expr(col("date"), "=", ...)], as })`
   (a `where` array is ANDed) and branch on the result, rather than pushing the
   check to the client.
+- **A column named `run` is reserved.** The table deploys and reads back fine, then
+  EVERY `s.db.add` into it 400s — at any column type, with or without a value — and
+  the error names the column while complaining about the VALUE. Use `run_id`. Exact,
+  case-sensitive, one name: `Run`/`runs`/`run_id` are fine. `--strict` fails on it.
 - **System columns are auto-injected.** `id` + `created_at` are prepended to
   every table (`system: true` by default); declaring them by hand is redundant.
   `id` is an `int` PK by default; pass `idType: "uuid"` on the table for a uuid key.
@@ -320,19 +326,20 @@ Non-obvious authoring rules:
   `xanots export`/`deploy` CLI path. Seed rows are never emitted into the bundle
   either way; only `deploy` ships them. The `node:fs` writers
   (`writeBundle`/`writeArtifact`) and lock-file I/O import from `@xanots/sdk/node`,
-  NOT the browser-safe `@xanots/sdk` entry (which a frontend can import query
-  defs from to use `getPath()`/`InferInput` with no Node built-ins in the bundle).
+  NOT the browser-safe `@xanots/sdk` entry (a frontend imports defs from it for
+  `getPath()`/`InferInput`).
   The compiler machinery (per-kind `encode*`, the registries, the bundle serializer,
   the lock model) is on `@xanots/sdk/internal` and is never needed to author.
+  READING a bundle back is `@xanots/sdk/bundle` — a statement walker (`2.if.0` paths),
+  a structural hash, `mvp:*` catalog, `tableRefOf`.
 - **Client bundle size / tree-shaking.** `@xanots/sdk` is `sideEffects: false` and pulls
   no Node built-ins, so a bundler drops unused SDK exports. But importing a **def** for its
   `getPath()`/`verb`/`getUrl()`/`getChannel()` also pulls whatever its `stack` references:
   the `s.*`/`c.*` factory CALLS run at module load to BUILD it. Types are free.
   ⚠ A FLOOR — **~289 kB minified (~57 kB gzipped)** for the FIRST def; splitting modules
   never removes it. The floor is the RUNTIME, not the def: a second def, or a much richer
-  one, adds ~1 kB. So the cost is paid by importing ANY def at all, and reducing what a
-  def does will not reduce it.
-  Fix: `xanots paths <entry> --emit xano/routes.gen.ts` (`routes` is an accepted alias) — verbs, paths, and sockets as
+  one, adds ~1 kB — so reducing what a def does will not reduce it.
+  Fix: `xanots routes <entry> --emit xano/routes.gen.ts` (`paths` is an accepted alias) — verbs, paths, and sockets as
   plain data importing NOTHING, still compile-checked: `routePath("blog/{slug}", { slug })`,
   `channelPath("rooms/{room_id}", { room_id })`, `socketUrl("chat", baseUrl)` (tenant base
   URLs lifted to `wss://h/ws/<tenant>:<canonical>`). A rename is a type error, not a 404.
@@ -385,17 +392,18 @@ Non-obvious authoring rules:
   return.
 - **Build regex-filter patterns with `c.regex(body, flags?)`, never `c.text`.**
   The regex filters (`regex_test`/`regex_match`/`regex_replace`/…) are pattern-piped
-  PHP `preg_*`: the piped value is the PATTERN and must be delimiter-wrapped. A bare
-  `c.text("^[^@\s]+@...$")` is an invalid pattern that matches *nothing* for every
-  input, so a precondition on it silently rejects all values (valid ones included).
-  `c.regex("^[^@\s]+@[^@\s]+\.[^@\s]+$", "i")` wraps + escapes it for you (accepts a
-  JS `RegExp` too: `c.regex(/^…$/i)`), and `withFilters` throws on a bare `c.text`
-  pattern pointing here — from ANY position in the chain, so a normalizer in front
-  (`withFilters(c.text("^hi"), fl.trim(), fl.regex_test(...))`) is refused too; nothing
-  upstream adds the delimiters. `s.expect.to_match`'s `value` is the same PATTERN slot,
-  refused the same way; a `ref`/`inp` pattern is passed through untouched, either place.
-  Better still, prefer a native typed input
-  (`input.email({...})`) over hand-rolled validation.
+  PHP `preg_*`: the piped value is the PATTERN and must be delimiter-wrapped, and the
+  ARGUMENT is the subject. A bare `c.text("^…$")` is an invalid pattern that matches
+  *nothing* for every input, so a precondition on it silently rejects all values.
+  `c.regex(body, "i")` wraps + escapes it for you (a JS `RegExp` too: `c.regex(/^…$/i)`).
+  Reversed — subject piped, pattern in the argument — reads correctly, type-checks, and
+  answers false for EVERY input, so an `if (matches) reject` guard admits what it
+  refuses. `withFilters` throws on a bare `c.text` pattern from ANY position in
+  the chain (a normalizer in front of the regex filter is refused too; nothing upstream
+  adds the delimiters) and on a pattern found in the subject slot; `s.expect.to_match`
+  is the same PATTERN slot, refused both ways; a `ref`/`inp` pattern is passed through untouched.
+  `export()` warns on a reversed pair in stored bytes. Better still:
+  a native typed input (`input.email`) over hand-rolled validation.
 - **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
@@ -419,19 +427,10 @@ Non-obvious authoring rules:
   credential the runner has. As a file that triple is `{ "type": "token",
   "instance_base_url": …, "workspace_id": <n>, "meta_api_token": … }`. The older
   `$XANO_REFRESH_TOKEN` + `$XANO_CLIENT_ID` pair still works but ROTATES: single-use.
-- **Event-driven objects fire on an EPHEMERAL, not in the sandbox.** A `task`
-  (scheduled), an `mcpServer`, and every trigger — `tableTrigger` included — run normally
-  on an ephemeral env, which is `deploy`'s DEFAULT destination. So test an event-driven
-  design (screen-on-insert, cron cleanup, MCP tool call) by deploying it and letting it
-  run.
-  ⚠ Under `--dest sandbox` they import cleanly but their stacks NEVER execute, and there
-  is no way to fire one manually — an insert on a bound table does not run its
-  `tableTrigger`, and the design silently does nothing. Only synchronously-invoked objects
-  (queries, functions, and the agents an endpoint calls with `s.ai.agent.run`) run there.
-  If you must stay on the sandbox, verify the logic out of band: factor the body into a
-  `defineFunction` (or a callable `query`) and invoke it directly — a `tableTrigger` that
-  screens a row on insert should delegate to a function a `query` can also call via
-  `s.function.run`, and you assert against that.
+- **Event-driven objects fire on an EPHEMERAL.** A `task` (scheduled), an `mcpServer`,
+  and every trigger — `tableTrigger` included — run normally on an ephemeral env, which
+  is where `deploy` sends them. So test an event-driven design (screen-on-insert, cron
+  cleanup, MCP tool call) by deploying it and letting it run.
 - **Zero-based numeric keys make `c.obj` a LIST.** `c.obj({ "0": "a" })` evaluates to
   `["a"]`: a numeric key IS an index in the engine's data model, so keys that are exactly
   `0..n-1` come back as a list with HTTP 200 and no error. Write `c.array([...])` when you