@xanots/sdk 0.0.9 → 0.0.11

package/guides/README.md

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

package/guides/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

@@ -94,7 +94,7 @@ on the query and every caller derives from that single source of truth:
 
 ```ts
 const getPost = query({
-  verb: "GET", apiGroup: blog, name: "get_post",
+  verb: "GET", apiGroup: blog, name: "get_post/{id}",   // one row → address it in the path
   input: { id: input.int({ required: true }) },
   stack: [s.db.query({ table: post, where: expr(col("id"), "=", inp("id")), as: "rows" })],
   // A filtered response is opaque to the static walk, so derivation is `unknown`.
@@ -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/filters.md

@@ -39,12 +39,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>[]`
@@ -136,11 +137,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`

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

@@ -13,7 +13,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? } }`.
@@ -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-data.md

@@ -12,7 +12,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.
@@ -54,6 +54,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`.