@xanots/sdk 0.0.8 → 0.0.10

package/guides/cli.md

@@ -24,14 +24,13 @@ xanots export ./xano/index.ts --lock       # opt into xano.lock (created beside
 xanots export ./xano/index.ts --frozen-lock  # CI guard: fail if the export would change the lock
 xanots lock rename --entry=xano/index.ts table users members  # move a lock entry after renaming in code
 xanots lock prune ./xano/index.ts --yes    # drop lock entries nothing exports anymore
-xanots lock prune --no-verify --entry=xano/index.ts --yes dbo:notes  # …or drop named keys without running the workspace
-xanots lock adopt live-export.json --entry=xano/index.ts --yes  # seed the lock from a live engine export
+xanots lock prune --identity-only --entry=xano/index.ts --yes dbo:notes  # …or drop named keys without running the workspace
+xanots lock import live-export.json --entry=xano/index.ts --yes  # seed the lock from a live engine export
 
 xanots login                               # OAuth sign-in (once) — pick the instance + workspace at consent
 xanots login --paste                       # …when the browser can't reach this machine's 127.0.0.1 (remote shell, container, Codespace)
 xanots workspace details                   # which instance/workspace am I bound to, and via which credential?
 xanots deploy ./xano/index.ts              # compile + import into a live ephemeral (the dev loop) → URL
-xanots deploy ./xano/index.ts --dest sandbox             # …or your throwaway singleton sandbox
 xanots deploy ./xano/index.ts --static ./frontend/dist   # also deploy a static frontend (onto the ephemeral)
 xanots deploy ./xano/index.ts --static ./frontend/dist --static-env PK=pk_live_1   # + extra public config
 xanots deploy --bundle ws.json             # deploy an already-exported bundle
@@ -43,33 +42,32 @@ xanots ephemeral impersonate <tenant>      # open it in the builder (--guest = r
 xanots release ./xano/index.ts --dry-run   # preview what promoting to your main workspace would change
 xanots release ./xano/index.ts             # promote: add + update, never delete, never touch table data
 xanots release ./xano/index.ts --prune     # …also delete objects this project released and no longer defines (needs xano.lock)
-xanots sandbox export                      # export the DEPLOYED sandbox workspace as a JSON bundle → ./sandbox.json
-xanots sandbox export --format multidoc --name backend               # …or the deployed sandbox as XanoScript → backend.xs
-xanots sandbox export --format multidoc --path -                     # …stream the multidoc to stdout (deploy first)
-xanots sandbox details                     # print the sandbox base URL + tenant details (pretty on a TTY, JSON when piped)
+xanots ephemeral export <tenant>           # export a DEPLOYED ephemeral as a JSON bundle → ./<tenant>.json
+xanots ephemeral export <tenant> --format multidoc --name backend    # …or as XanoScript → backend.xs
+xanots ephemeral export <tenant> --format multidoc --path -          # …stream the multidoc to stdout (deploy first)
 
 xanots workspace details                   # which workspace your token is scoped to (instance, id, name, guid)
 xanots workspace export --path ws.json     # your REAL workspace as a JSON bundle (`--path -` streams to stdout)
-xanots workspace codegen my-app            # …or as a runnable project (the pull direction)
-xanots sandbox codegen my-app              # same, from your sandbox
-xanots ephemeral codegen <tenant> my-app   # same, from an ephemeral (tenant first, path second)
-xanots codegen ws.json my-app              # …or from a bundle already on disk (offline, no auth)
+xanots init my-app --from workspace        # …or as a runnable project (the pull direction)
+xanots init my-app --from ephemeral:<tenant>   # same, from an ephemeral (the env is named inside the flag)
+xanots init my-app --from ./ws.json        # …or from a bundle already on disk (offline, no auth)
 
-xanots profile me                          # print the scoped user + instance base URL (pretty on a TTY, JSON when piped)
-xanots whoami                              # alias for `profile me`
+xanots status                              # who am I, which workspace, and the env this project last deployed to
+xanots whoami                              # print the scoped user + instance base URL (pretty on a TTY, JSON when piped)
+xanots profile me                          # alias for `whoami`
 xanots logout                              # revoke the refresh token + clear the shared cache (--local for the project one)
 xanots version                             # print the installed @xanots/sdk version
 xanots upgrade --check                     # is a newer @xanots/sdk published? exits 7 if so, 0 if current
 xanots upgrade                             # install it (-g or -D, matching how this CLI is installed)
 xanots help                                # grouped command reference (also the no-arg default)
 xanots <command> --help                    # that command's usage, subcommands, and flags (`xanots deploy --help`)
-xanots <noun> <verb> --help                # scoped to one verb (`xanots workspace codegen --help`)
+xanots <noun> <verb> --help                # scoped to one verb (`xanots workspace export --help`)
 xanots <command> --json                    # force JSON on stdout (otherwise: whenever stdout isn't a terminal)
 xanots completion zsh                      # shell completion script (also bash, fish) — see below
 
-xanots validate ./xano/index.ts            # import into a live instance, diff each object back
-xanots validate ./xano/index.ts --runtime  # also run each deployed function on the engine
-xanots validate ./xano/index.ts --capture  # write the fetched JSON as fixture candidates
+xanots preflight ./xano/index.ts           # import into a live instance, diff each object back (needs auth + a throwaway tenant)
+xanots preflight ./xano/index.ts --runtime # also run each deployed function on the engine
+xanots preflight ./xano/index.ts --capture # write the fetched JSON as fixture candidates
 ```
 
 ## Bundle key names vs. the names everything else uses
@@ -97,7 +95,7 @@ correctly looks *missing* if you go looking for `payload.table`. And `agent` and
 both land in `payload.toolset`, while the kind actually named `toolset` lands in
 `payload.tool`; matching on the word alone will pick the wrong array.
 
-This is also the format `xanots lock adopt` reads, so both directions are user-facing.
+This is also the format `xanots lock import` reads, so both directions are user-facing.
 
 
 **Build warnings, and `--strict`.** `export`/`deploy` print a `xanots:` warning for the
@@ -113,7 +111,7 @@ The programmatic equivalents are `emitBundle(app, { strict: true })` and
 ## Shell completion
 
 `xanots completion <bash|zsh|fish>` prints a completion script covering every command, verb, flag,
-and closed value set (`--dest ephemeral|sandbox`, `--format json|multidoc`, `--ai claude|codex|cursor|none`).
+and closed value set (`--env ephemeral|workspace`, `--format json|multidoc`, `--ai claude|codex|cursor|none`).
 It is generated from the CLI's own command table, so it never drifts from what the CLI accepts — but it
 is baked at generation time, so re-run it after upgrading.
 

package/guides/codegen.md

@@ -1,6 +1,22 @@
 # Pulling an existing workspace
 
-What `xanots codegen` writes, how faithful the pull is, and how to read its report.
+What `xanots init --from` writes, how faithful the pull is, and how to read its report.
+
+## Running it
+
+A pull is `init` with `xano/` filled from an existing backend instead of the empty starter,
+so it is the scaffold command with one extra flag:
+
+```bash
+xanots init my-app --from workspace          # your real workspace (the one your login is scoped to)
+xanots init my-app --from ephemeral:my-env   # a named ephemeral environment
+xanots init my-app --from ./ws.json          # a bundle already on disk — offline, no login
+```
+
+Everything else about the project is unchanged: `--framework`, the theme flags, `--ai` and
+`--web` mean the same thing here as they do without `--from`. The two flags that describe
+the pull itself — `--report` and `--skip-roundtrip` — are refused without it rather than
+silently ignored.
 
 ## The generated tree
 
@@ -49,7 +65,7 @@ it round-trips exactly.
 
 Then it checks its own work: the project it just wrote is loaded, exported, and diffed
 against the workspace it came from. A mismatch names the object and fails the command
-(`--no-verify` opts out). So "it compiled" and "it means the same thing" are separate
+(`--skip-roundtrip` opts out). So "it compiled" and "it means the same thing" are separate
 claims, and you get both.
 
 The findings above are printed either way. Verification runs after decoding is finished,
@@ -68,7 +84,7 @@ count and a collapsed object list, and each names the generated file it landed i
 the same data is written into `xano/.xanots-codegen.json` on every pull, so parity is
 trackable release over release and gateable in CI without scraping output.
 
-Re-pulling is a real workflow: a second `codegen` into the same directory refreshes
+Re-pulling is a real workflow: a second `init --from` into the same directory refreshes
 `xano/` and leaves the rest of the project — your `package.json`, your `frontend/` —
 exactly as you left it. No `--force` needed, because the tree carries a marker saying it
 was machine-written.
@@ -76,8 +92,8 @@ was machine-written.
 > ⚠️ **`xano/` is a scratch surface, and there is no `xanots workspace deploy`.**
 > Regenerating rewrites it (a directory that isn't a previous pull still needs `--force`),
 > it carries schema only — no table rows — and deploying it is a *full replace* of the
-> target. Pull from your real workspace, edit, and `deploy` to a disposable ephemeral or
-> sandbox. Workspace env var **values** ride inline in `xano/workspace.ts` (that is what a
+> target. Pull from your real workspace, edit, and `deploy` to a disposable ephemeral
+> environment. Workspace env var **values** ride inline in `xano/workspace.ts` (that is what a
 > deploy sends), so treat a pulled tree as secret-bearing before you commit it.
 
 ---

package/guides/coverage.md

@@ -34,7 +34,7 @@ runtime (XanoTS only compiles), and generating engine-side numeric ids/timestamp
 
 **Deferred (by design)** — folder auto-discovery, and the `service` / `vault` / `branch`
 payload sections. (Round-trip decompile is no longer deferred: that is
-`xanots codegen`, in the [CLI guide](cli.md); nor is `workflow_test` — it is a
+`xanots init --from`, in the [CLI guide](cli.md); nor is `workflow_test` — it is a
 first-class kind, see `workflowTest` in [Object kinds](object-kinds.md).) `InferResponse`
 auto-derivation covers the object-literal and single-`db`-variable cases (matching the engine's
 static walk), and follows a CALL into the object it invokes (`s.function.call`/`.run`,

package/guides/deploying.md

@@ -75,7 +75,7 @@ valid until you revoke it wherever you minted it. Save it with owner-only permis
 **Project-local credentials** — pass `--local` to `login` to cache tokens in a
 **project-local** `./.xano/auth.json` instead (which `login` **auto-adds to `.gitignore`**),
 scoping the sign-in to that directory. Every command that **reads** credentials
-(`deploy`/`details`, `profile me`, token refresh) resolves them **project-local first, global
+(`deploy`/`details`, `whoami`, token refresh) resolves them **project-local first, global
 as a fallback**: it uses `./.xano/auth.json` when present, otherwise `~/.xanots/auth.json` —
 so a `--local` project keeps working without repeating the flag. `login` and `logout` do
 **not** fall back: they target the shared global cache unless you pass `--local`. An explicit
@@ -92,16 +92,13 @@ workspace blob is deliberately never dumped: it carries per-tenant secrets that
 in shell history or CI logs.
 
 **Where it goes** — the instance your **token is bound to** (the token's `aud`), never a
-flag. `xanots deploy` create-or-refreshes an **ephemeral** (default) or resolves your
-throwaway **sandbox** (`--dest sandbox`); production promotion is the separate
-`xanots release` path to your main instance workspace, which merges rather than replacing.
+flag. `xanots deploy` create-or-refreshes an **ephemeral**, which is the only environment it
+writes to; production promotion is the separate `xanots release` path to your main instance
+workspace, which merges rather than replacing.
 
 **Static host** — `deploy --static <dir>` archives a directory and deploys it to a
-static host after the backend import. Its target follows the destination: with `--dest
-ephemeral` the frontend lands **on the ephemeral itself** (backend + frontend in one
-environment); with `--dest sandbox` it lands on your **own (parent) workspace**, since the
-sandbox tenant does not serve static hosting. For the parent-workspace case the target is the
-workspace your credential is already pinned to, and the CLI uploads the archive to
+static host after the backend import. The frontend lands **on the ephemeral itself**, so the
+backend and the frontend live in one environment. The CLI uploads the archive to
 `/api:meta/workspace/{id}/static_host/default/build` with your ordinary bearer. That route
 auto-creates the `default` host and **auto-deploys to `dev`**, returning the live URL — so
 the static step is independent of the backend deploy (the backend still runs first because
@@ -115,7 +112,7 @@ matches the canonical returned for the build just pushed — then prints `Fronte
 polls every second for the first 30s, then every two seconds out to 120s. An unconfirmed poll
 is a **warning, not a failure** (the build uploaded fine and usually comes online moments
 later; the exit code stays `0` and the summary records `"verified": false`). Verification is
-skipped when the response carries no canonical to compare against. Pass **`--no-verify`** to
+skipped when the response carries no canonical to compare against. Pass **`--skip-liveness`** to
 skip the wait entirely — useful for fast iterative deploys or when the deployed URL isn't
 reachable from the machine running the CLI.
 
@@ -132,7 +129,7 @@ leaves every deep link and refresh running with the global unset — and the pag
 Injection is skipped (reported as a warning, not a failure) when the archive has no document
 with a `<head>` to anchor to, and any individual document that lacks one is named; values are
 `<`-escaped so one containing `</script>` can't break out of the element. This is why a
-prebuilt `frontend/dist` can retarget any sandbox with no rebuild.
+prebuilt `frontend/dist` can retarget any environment with no rebuild.
 
 > **Caching — verify with a cache buster.** The static host serves `index.html` with
 > `Cache-Control: public, max-age=3600`, so a browser (or CDN) that loaded the page before
@@ -143,10 +140,10 @@ prebuilt `frontend/dist` can retarget any sandbox with no rebuild.
 > copy — `curl -s "$URL/?nocache=$(date +%s)"` — and check the fetched HTML for the injected
 > `window.XANO_HOST` line rather than retrying the same cached URL.
 
-`xanots sandbox details` prints the same **sandbox base URL** (`GET /api:meta/sandbox/me`,
-projected to JSON) out of band, for cases where you'd rather bake it in at build time.
-(`xanots profile me` prints the *instance* base URL, i.e. the account's origin rather than
-the sandbox tenant.) A static failure after a committed backend deploy **does not roll
+`xanots status` prints the same **environment base URL** out of band, for cases where you'd
+rather bake it in at build time — along with the environment's name and expiry, without your
+having to know either. (`xanots whoami` prints the *instance* base URL, i.e. the account's
+origin rather than the environment.) A static failure after a committed backend deploy **does not roll
 back**: it exits with code `3` and a resumable message telling you to re-run with `--static`
 to retry just that step.
 
@@ -182,9 +179,9 @@ secret must not deploy against whatever happens to be on the runner.
 > use** — a stored one is spent by its first exchange, so a job that runs twice fails the
 > second time. Prefer the meta credential.
 
-## Validating against a live instance (xanots validate)
+## Checking against a live instance (xanots preflight)
 
-`xanots validate` proves your compiled output against a **real, running Xano
+`xanots preflight` proves your compiled output against a **real, running Xano
 instance** — not a static snapshot. It compiles your workspace, imports it into a
 **fresh ephemeral environment created for that run**, exports it back, and diffs it
 against what you compiled, so you catch three classes of problem a local build can't:
@@ -195,7 +192,7 @@ against what you compiled, so you catch three classes of problem a local build c
 
 It talks only to public meta API routes — the **same** archive import `xanots
 deploy` uses, plus the workspace export — and never touches XanoScript. There is one
-way into an instance, so a transport bug is one `validate` reproduces rather than
+way into an instance, so a transport bug is one `preflight` reproduces rather than
 routes around.
 
 It is non-destructive: nothing you own is written to. Each run creates its own
@@ -217,11 +214,11 @@ XANO_VALIDATE_TOKEN=your-meta-bearer-token
 ```
 
 ```bash
-xanots validate ./xano/index.ts                      # import + round-trip diff, reports per object (every authored kind)
-xanots validate ./xano/index.ts --runtime            # + run each deployed function
-xanots validate ./xano/index.ts --capture            # + write fetched JSON to ./validate-out (fixture candidates)
-xanots validate ./xano/index.ts --instance http://localhost:8080   # override the target for one run
-xanots validate --bundle ws.json                     # validate an already-exported bundle
+xanots preflight ./xano/index.ts                      # import + round-trip diff, reports per object (every authored kind)
+xanots preflight ./xano/index.ts --runtime            # + run each deployed function
+xanots preflight ./xano/index.ts --capture            # + write fetched JSON to ./validate-out (fixture candidates)
+xanots preflight ./xano/index.ts --instance http://localhost:8080   # override the target for one run
+xanots preflight --bundle ws.json                     # check an already-exported bundle
 ```
 
 Config comes from the environment (a `.env` is autoloaded; a real env var wins),
@@ -243,10 +240,10 @@ know the URL ahead of time:
 const HOST = (typeof window !== "undefined" && window.XANO_HOST) || import.meta.env.VITE_XANO_HOST;
 ```
 
-`window.XANO_HOST` is the **sandbox tenant** URL your deployed APIs answer at (the same
-value `xanots sandbox details` prints as `baseUrl`); it is *not* `xanots profile me`,
-which prints your account's instance origin. Because injection happens at deploy time, a
-prebuilt `frontend/dist` retargets any sandbox with **no rebuild** — ideal for headless agents.
+`window.XANO_HOST` is the **environment** URL your deployed APIs answer at (the same value
+`xanots status` prints as the environment's URL); it is *not* `xanots whoami`, which prints
+your account's instance origin. Because injection happens at deploy time, a prebuilt
+`frontend/dist` retargets any environment with **no rebuild** — ideal for headless agents.
 Add your own public config (base URLs, *publishable* keys) with `--static-env KEY=VALUE`
 (repeatable), exposed the same way as `window.<KEY>`. A static host serves these files
 verbatim to the browser, so everything injected is **public** — never put secrets here;
@@ -275,13 +272,13 @@ exact string `window.XANO_HOST` (the dot form is valid to *read* the global in y
 
 | Command | Where it goes |
 |---|---|
-| `xanots deploy` | A disposable **ephemeral** environment (default) — create-or-refreshed each run, auto-expiring, with its own URL. `--dest sandbox` targets your throwaway singleton instead. |
+| `xanots deploy` | A disposable **ephemeral** environment — create-or-refreshed each run, auto-expiring, with its own URL. There is no other destination and no flag to choose one. |
 | `xanots release` | Your **main Xano instance** workspace — the production target. **Merges** by default: objects are updated in place or added, and your table data is never touched unless you ask. |
-| `xanots test` | Nothing — it only reads. Runs the tests an already-deployed environment carries; `--dest` picks which one, `workspace` included. |
+| `xanots test` | Nothing — it only reads. Runs the tests an already-deployed environment carries; `--env` picks which one, `workspace` included. |
 
-Not every instance has ephemeral environments enabled. Where they are off, the default
-`deploy` says so and points at `--dest sandbox` — note that `--static` then publishes the
-frontend to your own (parent) workspace, replacing whatever it is hosting.
+Not every instance has ephemeral environments enabled. Where they are off, `deploy` says so
+and names who can turn them on — there is no second destination to fall back to. `xanots
+export` and `xanots preflight` still work meanwhile.
 
 Every `deploy` is a **full replace** of the disposable environment — always fresh, no
 merge mode, no flags to get wrong. A `release` is the opposite by design: it changes what
@@ -325,7 +322,7 @@ with no lock entry is an object the project never created — a table built in t
 team's API group — and the release is refused rather than deleting it. A prune with no lock
 at all is refused too: without one there is no record of what belongs to the project, so
 every deletion would be a guess. To delete something that is genuinely yours to remove,
-adopt it first (`xanots lock adopt`). Releasing a pre-exported `--bundle` carries no entry
+import its identities first (`xanots lock import`). Releasing a pre-exported `--bundle` carries no entry
 file to find a lock beside, so name it with `--lock=<path>`.
 
 **A dropped column is destructive, and does not need a flag to happen.** Removing a column
@@ -355,4 +352,4 @@ XANO_REFRESH_TOKEN=… XANO_CLIENT_ID=… npx @xanots/sdk deploy --bundle ws.jso
 ```
 
 > ⚠️ A deploy is a full replace of the target environment, including its table records,
-> before importing. The blast radius is your own disposable ephemeral/sandbox — but anything
+> before importing. The blast radius is your own disposable ephemeral — but anything

package/guides/environment.md

@@ -22,7 +22,7 @@ are what you get when the variable is unset.
 | `XANO_ORIGIN` | OAuth host to sign in against, instead of the default — the same thing `--origin` does. |
 | `XANO_NO_BROWSER` | Set to anything non-empty and `xanots login` will **not** launch a browser; it prints the authorize URL to stderr for you to open yourself. The loopback server still runs and still waits for the redirect, so the flow completes only if the browser you open it in can reach this machine's `127.0.0.1`. For a machine that has no browser to launch. When the browser is on a **different** machine, that redirect cannot arrive — use `xanots login --paste` instead. |
 
-**`xanots validate`** — its own target, deliberately separate from the deploy login
+**`xanots preflight`** — its own target, deliberately separate from the deploy login
 
 | Variable | What it does |
 |---|---|
@@ -78,7 +78,7 @@ updated on every export (written atomically before the bundle). **Commit it next
 code.** A project from `xanots init` is locked from its first export — both its `xano:export`
 and `xano:deploy` scripts pass `--lock`, and `npm run xano:check` is the `--frozen-lock` CI
 guard. Adopt it early either way: once identities have drifted, the only way back is
-`lock adopt` against the deployed workspace.
+`lock import` against the deployed workspace.
 
 Precedence at emit is always **explicit in-code value → lock entry → name derivation**.
 
@@ -92,7 +92,7 @@ losing it costs nothing.
 The lock is load-bearing exactly where a live guid **diverges** from that derivation, which
 happens two ways:
 
-- **Adopted** objects — anything built in the Xano UI first and taken over with `lock adopt`.
+- **Adopted** objects — anything built in the Xano UI first and taken over with `lock import`.
   The engine assigned those guids randomly; nothing in your code can re-derive them.
 - **Renamed** objects — `lock rename` pins the original guid under the new name, so the
   derivation no longer reproduces it.
@@ -125,7 +125,7 @@ try to create everything. `xanots release ./xano/index.ts --replace` now re-pins
 workspace itself and tells you to commit it. If there is no lock to re-pin, it says so —
 without one, the next release duplicates every object.
 
-**Adopting a live workspace** — `xanots lock adopt <bundle.json>` seeds the lock from a
+**Importing a live workspace's identities** — `xanots lock import <bundle.json>` seeds the lock from a
 real engine `packageExport`, capturing the live workspace's random guids by `(type, name)`
 so code takes over an existing workspace and the first sync updates in place instead of
 duplicating.

package/guides/object-kinds.md

@@ -122,7 +122,7 @@ query({
 
 A pull brings tests back, along with a query's saved request/response `example`. The one
 thing it withholds is a test's auth `token` — that is an expiring credential rather than
-authored configuration, so `xanots codegen` reports it as a deliberate omission instead of
+authored configuration, so `xanots init --from` reports it as a deliberate omission instead of
 writing it into a committed tree.
 
 **Four of the `Run …` statements only run inside a workflow test.** `s.api.call`,
@@ -311,8 +311,8 @@ nothing checks that spelling, so prefer the def wherever there is one.
 
 A container takes time to come up, so `xanots deploy` waits for it: after the import it
 reads each microservice and reports whether it is ready, still starting, or failed, then
-lists them. Skip the wait with `--no-verify`. The same report is available any time from
-`xanots ephemeral get <env>`, `xanots sandbox details`, and `xanots workspace details`.
+lists them. Skip the wait with `--skip-liveness`. The same report is available any time from
+`xanots status`, `xanots ephemeral get <env>`, and `xanots workspace details`.
 
 Two outcomes, and only one of them is a warning:
 

package/guides/project-structure.md

@@ -31,7 +31,7 @@ Paths are lower case throughout — an HTTP verb is the one exception, because i
 the method rather than a word. Bindings keep the object's own casing, so a file name
 and the symbol it exports can differ.
 
-That is the shape `xanots codegen` writes, and its `index.ts` re-exports every object
+That is the shape `xanots init --from` writes, and its `index.ts` re-exports every object
 by name — import from the tree's root rather than from a file, since a file path moves
 when an object's parent or its `_shared.ts` placement changes. Hand-authored projects are
 free to use any other layout; only `index.ts` registering the objects matters.

package/guides/scaffold.md

@@ -11,10 +11,13 @@ What `xanots init` writes, the two frontend presets, theming, add-ons, and the S
 (repeatable; writes `CLAUDE.md`/`AGENTS.md`/Cursor rules — none by default),
 `--marketplace <pkg>` (repeatable, comma-separated; installs add-ons and
 registers them — below), `--force` (scaffold into a non-empty folder),
-`--no-install` (skip `npm install`).
+`--no-install` (skip `npm install`), `--web` (choose all of the above in a
+browser instead — see [Choosing in a browser](#choosing-in-a-browser)),
+`--from <source>` (fill `xano/` from an existing backend rather than the
+starter — see [Pulling an existing workspace](codegen.md)).
 In a terminal, `init` prompts for the framework and the AI files; every prompt
 has a default, so pressing enter twice is a valid answer. The look is never
-prompted for — it comes from the flags above, or from `xanots onboard`.
+prompted for — it comes from the flags above, or from `--web`.
 The starter backend is empty but already compiles and deploys — grow it from the
 walkthrough in `xano/EXAMPLE.md`.
 
@@ -63,6 +66,26 @@ project — the mistake npm answers by silently writing to the wrong `package.js
 The package name is passed through exactly as typed, so version specifiers, tags,
 and third-party packages all work.
 
+## Choosing in a browser
+
+`--web` collects the same choices against a live preview instead of on the
+command line:
+
+```bash
+xanots init my-app --web
+```
+
+It is a launcher, not a second scaffolder: a configurator is downloaded on
+demand, serves a local page, and finishes by running `init` with the flags your
+choices imply — printing the equivalent command so the project stays
+reproducible from a script. Everything after `--web` is passed to it untouched,
+including `--help`, which is why that one form reaches the network. `xanots help
+init` stays offline, like `init` itself.
+
+Because the configurator is fetched at run time, `--web` needs the npm registry
+before it can start. `init` on its own reaches out only to install the new
+project's dependencies, which `--no-install` skips.
+
 ## The frontend preset
 
 To point `npm run dev` at a real backend, copy `.env.example` to `.env.local` — both

package/guides/typed-frontend.md

@@ -168,7 +168,7 @@ is paid by importing any def at all.
 almost no bundle cost:
 
 ```bash
-xanots paths ./xano/index.ts --emit xano/routes.gen.ts
+xanots routes ./xano/index.ts --emit xano/routes.gen.ts
 ```
 
 The emitted file is plain data plus one interpolator and imports nothing at all — the same

package/llms/fields.md

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

package/llms/kinds-agent-mcp.md

@@ -2,7 +2,7 @@
 
 > 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.

package/llms/kinds-core.md

@@ -21,7 +21,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.

package/llms/kinds-realtime.md

@@ -46,7 +46,7 @@
   - **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.

package/llms/lock.md

@@ -1,6 +1,6 @@
 # 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,
@@ -13,11 +13,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
@@ -25,7 +25,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/statements-calls.md

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

package/llms/statements-data.md

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

package/llms/tests.md

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