@xanots/sdk 0.0.9 → 0.0.10

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/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/tests.md

@@ -51,7 +51,7 @@ The run is isolated in ways that make a correct test fail for reasons the failur
 
 `xanots test run-all` runs the unit tests AND the `workflowTest()` objects an environment carries. It takes no entry file and compiles nothing: it runs what is DEPLOYED, so deploy before testing.
 
-- `--dest ephemeral` (DEFAULT, `--name <env>` to pick one), `--dest sandbox`, or `--dest workspace`. Unlike `deploy`, `workspace` is allowed here — running a test reads.
+- `--env ephemeral` (DEFAULT — the one this project last deployed to), `--env ephemeral:<name>`, or `--env workspace`. Same grammar as `init --from`. `deploy` takes no `--env` at all; `test` does, and `workspace` is allowed here because running a test only reads.
 - `xanots test list` shows what is there without running it; `xanots test run "<name>"` runs one. When a name is ambiguous the error prints the qualified `function:math/happy path` form, which `run` also accepts.
 - `--kind unit|workflow` narrows to one family. `--concurrency <n>` defaults to 1: tests share the environment database.
 - A failing suite exits 5, distinct from a crash. Tests that could not be REACHED exit 6 — retry that one, investigate the other. An environment with no tests is success, not failure.

package/llms-full.txt

@@ -1,4 +1,4 @@
-# xanots v0.0.9
+# xanots v0.0.10
 
 > TypeScript SDK that compiles a typed Xano workspace into the importable packageExport JSON bundle.
 
@@ -50,7 +50,7 @@ installed), so a plain file read resolves them at the version you have.
 - [Column and input types](llms/fields.md): Read when declaring a table column (`f.*`) or a function/query input (`input.*`) — a type's options and accessor methods, and the `s.precondition` error/status contract that rides the same catalog.
 - [Filter catalog](llms/filters.md): Read when piping a value through `fl.*` — the full catalog with each filter's argument types.
 - [Lambda bodies (JavaScript)](llms/lambda.md): Read when writing a JavaScript body, or weighing whether to reach for one at all — `lam.fn`, `fl.lambda`, `fl.reduce`, `s.lambda`. Lambda workers are a bounded shared resource, and each surface binds a different set of identifiers.
-- [Lock file](llms/lock.md): Read when a `xano.lock` exists or should — renaming/pruning/adopting identities, seeding the lock programmatically, or asking which commands write it.
+- [Lock file](llms/lock.md): Read when a `xano.lock` exists or should — renaming/pruning/importing identities, seeding the lock programmatically, or asking which commands write it.
 - [Legacy paradigms and retired statements](llms/legacy.md): Read when the code was PULLED from an existing Xano instance rather than authored here — how a codegen'd tree reads and the three shapes in it that must not be "fixed", plus a `raw({ name: "mvp:…" })` statement, a `realtimeTrigger()`, or any name the catalogs do not list.
 - [Statement catalog](llms/statements-catalog.md): Read for the field signature of a specific statement — every surface, grouped by `s.*` namespace. Look here after the control-flow core in the router does not cover what you need.
 
@@ -115,7 +115,7 @@ which fails with a "must be ES modules" error until you switch it to module.
 
 Set `canonical` on every `apiGroup`. The engine mints the URL token server-side, so
 without one a group's client paths are unresolvable until a lock exists: the bundle
-exports fine and `xanots paths` / `getPath()` then fail on the very queries it just
+exports fine and `xanots routes` / `getPath()` then fail on the very queries it just
 built. An explicit `canonical` resolves them from the source alone.
 
 Build warnings: `export()` prints the shapes that deploy clean and then do the wrong
@@ -134,7 +134,7 @@ api-group/toolset canonical in a lock file written BESIDE THE ENTRY FILE —
 To rename an object: rename in code, export (stderr prints the exact fix-up), run
 `xanots lock rename <kind> <old> <new>`, export again — the original guid is emitted
 under the new name, so the engine renames in place instead of delete+create. Taking
-over an existing workspace: `xanots lock adopt <its-packageExport.json>` first, then
+over an existing workspace: `xanots lock import <its-packageExport.json>` first, then
 export. Pruning, programmatic seeding, and which commands write the lock:
 `llms/lock.md`.
 
@@ -147,19 +147,19 @@ environment and prints its URL.
 AND records — before importing. The blast radius is a disposable environment, not a
 production workspace, but confirm with the user before the first run.
 
-**Two destinations, and the choice changes more than the target.**
+**One destination, and no flag for it.**
 
-- `--dest ephemeral` (DEFAULT) — a NAMED, workspace-scoped, auto-expiring tenant
-  (~1h; `--expires-hours` 1–72 at create time). The active one is tracked in
+- `xanots deploy` writes to a NAMED, workspace-scoped, auto-expiring ephemeral tenant
+  (~1h; `--expires-hours` 1–72 at create time), and to nothing else — an `--env` here
+  is a usage error, not a choice. The active env is tracked in
   `./.xano/ephemeral.json`, so deploying again REFRESHES it and the URL is unchanged;
   if it expired or was swept, a fresh one is created and the new URL is called out.
   `--static` puts the frontend ON THE EPHEMERAL, so backend and frontend share one
   disposable environment.
   ⚠ Only the BACKEND URL survives a refresh: the replace clears static hosting too,
   so `--static` publishes a NEW host every run and the previous URL stops serving.
-- `--dest sandbox` — your single throwaway tenant, no expiry. `--static` puts the
-  frontend on your OWN (parent) workspace instead, because the sandbox tenant does
-  not serve static hosting.
+- `xanots status` names the env this project last deployed to, its URL and its expiry,
+  without your having to remember which one it was.
 - `xanots release` promotes to your INSTANCE workspace and MERGES, not replaces:
   adds/updates what you define, deletes nothing, writes no rows. Destruction is
   opt-in per flag, previewed + confirmed, and can drop a table WITH its rows.
@@ -182,7 +182,7 @@ host falls back to '', and every call 404s off the dev server.
 ⚠ It is INJECTED in bracket form — `window["XANO_HOST"]="…"` — so verifying a deploy
 by grepping `window.XANO_HOST` matches nothing and reads as a failed inject. Grep the
 bare `XANO_HOST` token.
-⚠ `xanots validate` ignores the deploy login and reads `XANO_VALIDATE_INSTANCE` /
+⚠ `xanots preflight` ignores the deploy login and reads `XANO_VALIDATE_INSTANCE` /
 `XANO_VALIDATE_TOKEN` (+ optional `XANO_VALIDATE_WORKSPACE_ID`) from the environment.
 **Displaying a stored file.** A file column comes back as `{ path, name, type, size,
 meta, access, url }`. ⚠ Do NOT use its `url`: on a tenant-scoped environment that field
@@ -332,7 +332,7 @@ Non-obvious authoring rules:
   never removes it. The floor is the RUNTIME, not the def: a second def, or a much richer
   one, adds ~1 kB. So the cost is paid by importing ANY def at all, and reducing what a
   def does will not reduce it.
-  Fix: `xanots paths <entry> --emit xano/routes.gen.ts` (`routes` is an accepted alias) — verbs, paths, and sockets as
+  Fix: `xanots routes <entry> --emit xano/routes.gen.ts` (`paths` is an accepted alias) — verbs, paths, and sockets as
   plain data importing NOTHING, still compile-checked: `routePath("blog/{slug}", { slug })`,
   `channelPath("rooms/{room_id}", { room_id })`, `socketUrl("chat", baseUrl)` (tenant base
   URLs lifted to `wss://h/ws/<tenant>:<canonical>`). A rename is a type error, not a 404.
@@ -419,19 +419,10 @@ Non-obvious authoring rules:
   credential the runner has. As a file that triple is `{ "type": "token",
   "instance_base_url": …, "workspace_id": <n>, "meta_api_token": … }`. The older
   `$XANO_REFRESH_TOKEN` + `$XANO_CLIENT_ID` pair still works but ROTATES: single-use.
-- **Event-driven objects fire on an EPHEMERAL, not in the sandbox.** A `task`
-  (scheduled), an `mcpServer`, and every trigger — `tableTrigger` included — run normally
-  on an ephemeral env, which is `deploy`'s DEFAULT destination. So test an event-driven
-  design (screen-on-insert, cron cleanup, MCP tool call) by deploying it and letting it
-  run.
-  ⚠ Under `--dest sandbox` they import cleanly but their stacks NEVER execute, and there
-  is no way to fire one manually — an insert on a bound table does not run its
-  `tableTrigger`, and the design silently does nothing. Only synchronously-invoked objects
-  (queries, functions, and the agents an endpoint calls with `s.ai.agent.run`) run there.
-  If you must stay on the sandbox, verify the logic out of band: factor the body into a
-  `defineFunction` (or a callable `query`) and invoke it directly — a `tableTrigger` that
-  screens a row on insert should delegate to a function a `query` can also call via
-  `s.function.run`, and you assert against that.
+- **Event-driven objects fire on an EPHEMERAL.** A `task` (scheduled), an `mcpServer`,
+  and every trigger — `tableTrigger` included — run normally on an ephemeral env, which
+  is where `deploy` sends them. So test an event-driven design (screen-on-insert, cron
+  cleanup, MCP tool call) by deploying it and letting it run.
 - **Zero-based numeric keys make `c.obj` a LIST.** `c.obj({ "0": "a" })` evaluates to
   `["a"]`: a numeric key IS an index in the engine's data model, so keys that are exactly
   `0..n-1` come back as a list with HTTP 200 and no error. Write `c.array([...])` when you
@@ -539,7 +530,7 @@ to survive a rename).
     - ⚠ Under `"custom"`, `allowOrigins` is matched as EXACT strings (scheme+host+port, no wildcard or subdomain expansion) and `"*"` is compared as a literal origin — it matches NOTHING. An unmatched origin gets no `access-control-*` headers at all, so the call fails in the browser on a missing `access-control-allow-origin` while export, deploy and the preflight all look fine. Name each origin, or use `mode: "default"` for any-origin. `allowMethods` gates the REAL response too: a verb left off gets no CORS headers back even though its preflight passes. Export warns on an empty origin list, a `"*"` entry, and a policy with no method enabled.
 - `defineFunction`/`query`/`apiGroup` above cover the queries+tables core; the four below are the "reach past that" primitives (tasks, workflow tests, middleware, tools). Agents and MCP servers are the same family and live in `llms/kinds-agent-mcp.md`. Same envelope conventions (`guid?`, `description?`, `docs?`, `tags?`, `history?`) unless noted.
 - `task({ name, guid?, description?, docs?, datasource?, active?, tags?, history?, schedule?, stack?, middleware? })` — a scheduled background job (function-like `stack`, no `input`/`response`).
-  - `schedule?`: a `ScheduleDef[]` (NOT a single object) — `{ startsOn, freq?, repeatEnabled?, endsOn?, endsEnabled? }`. `startsOn`/`endsOn` are **timestamp strings** validated at encode time — `"2026-01-01T00:00:00Z"`, or the space-separated `"2026-01-01 00:00:00+0000"` a pulled workspace carries — never epoch numbers, and never zoneless; `freq` is the repeat interval **in seconds** (default `86400` = daily); `endsOn` present ⇒ the schedule has an end. `endsEnabled?` defaults to that and is recovery-only — state it to reproduce a stored schedule that remembers an end date with the gate OFF. Fires on an ephemeral; does NOT fire in the sandbox (see Gotchas).
+  - `schedule?`: a `ScheduleDef[]` (NOT a single object) — `{ startsOn, freq?, repeatEnabled?, endsOn?, endsEnabled? }`. `startsOn`/`endsOn` are **timestamp strings** validated at encode time — `"2026-01-01T00:00:00Z"`, or the space-separated `"2026-01-01 00:00:00+0000"` a pulled workspace carries — never epoch numbers, and never zoneless; `freq` is the repeat interval **in seconds** (default `86400` = daily); `endsOn` present ⇒ the schedule has an end. `endsEnabled?` defaults to that and is recovery-only — state it to reproduce a stored schedule that remembers an end date with the gate OFF. Fires on an ephemeral (see Gotchas).
 - `workflowTest({ name, guid?, description?, docs?, datasource?, active?, tags?, stack? })` — an end-to-end test. NO `input`/`response`: `.call` something with an `as`, then assert on that var — `s.function.call({ fn, input, as: "r" })`, `s.expect.to_equal({ expr: ref("r"), value: c.int(42) })`. `s.expect.*` belongs here — it is not inert elsewhere (a failure 500s the request), so treat one in a query/function/task as a mistake to remove. `active?` defaults `true`; chain tests with `s.workflow_test.call({ workflowTest: <def handle> })`.
   - `datasource?`: **the trap.** Default `""` is an EMPTY datasource (recommended), not "no datasource". Any non-empty name makes the engine CLONE it before EVERY run — against production-sized data, slow enough to fail the run. `"live"` warns at compile time; other names don't.
 - `middleware({ name, guid?, description?, docs?, resultStrategy?, exceptionPolicy?, tags?, history?, input?, stack?, response?, responseShape?, tests? })` — a pre/post interceptor (function-like `stack`); attach it via a host's `middleware: { pre, post }`. ⚠ `input` ENCODES but an ATTACHED middleware never has it bound — the host request binds its own inputs, so `inp()` inside pre/post fails at runtime with `Unable to locate input` and a declared default does not stand in (`export()` warns). Read the request body with `s.util.get_all_input` instead; it yields a `{ type, vars }` envelope. `s.middleware.call` is the one path that DOES bind the declared map.
@@ -639,7 +630,7 @@ The run is isolated in ways that make a correct test fail for reasons the failur
 
 `xanots test run-all` runs the unit tests AND the `workflowTest()` objects an environment carries. It takes no entry file and compiles nothing: it runs what is DEPLOYED, so deploy before testing.
 
-- `--dest ephemeral` (DEFAULT, `--name <env>` to pick one), `--dest sandbox`, or `--dest workspace`. Unlike `deploy`, `workspace` is allowed here — running a test reads.
+- `--env ephemeral` (DEFAULT — the one this project last deployed to), `--env ephemeral:<name>`, or `--env workspace`. Same grammar as `init --from`. `deploy` takes no `--env` at all; `test` does, and `workspace` is allowed here because running a test only reads.
 - `xanots test list` shows what is there without running it; `xanots test run "<name>"` runs one. When a name is ambiguous the error prints the qualified `function:math/happy path` form, which `run` also accepts.
 - `--kind unit|workflow` narrows to one family. `--concurrency <n>` defaults to 1: tests share the environment database.
 - A failing suite exits 5, distinct from a crash. Tests that could not be REACHED exit 6 — retry that one, investigate the other. An environment with no tests is success, not failure.
@@ -650,7 +641,7 @@ The run is isolated in ways that make a correct test fail for reasons the failur
 
 > Read when the workspace defines an `agent()` or an `mcpServer()`.
 
-- `mcpServer({ name, guid?, description?, instructions?, docs?, enabled?, canonical?, spec?, tags?, history?, tools?, llm?, output? })` — an MCP toolset. `llm?`/`output?` are the same blocks `agent()` takes and are usually absent: an MCP server and an agent are ONE stored object distinguished by `type`. Returns a handle with `getPath()`/`getUrl(baseUrl)` for the Streamable-HTTP endpoint — `getUrl` is NOT idempotent, a `baseUrl` already carrying an `/x2/mcp/<…>/stream` path THROWS, so resolve ONCE from the instance base URL. Fires on an ephemeral; not in sandbox.
+- `mcpServer({ name, guid?, description?, instructions?, docs?, enabled?, canonical?, spec?, tags?, history?, tools?, llm?, output? })` — an MCP toolset. `llm?`/`output?` are the same blocks `agent()` takes and are usually absent: an MCP server and an agent are ONE stored object distinguished by `type`. Returns a handle with `getPath()`/`getUrl(baseUrl)` for the Streamable-HTTP endpoint — `getUrl` is NOT idempotent, a `baseUrl` already carrying an `/x2/mcp/<…>/stream` path THROWS, so resolve ONCE from the instance base URL. Fires on an ephemeral.
   - `tools?`: a `ToolsetToolEntry[]`. Pass the `tool()` HANDLES directly (`tools: [saveNote]`), like every other collection in the SDK; use the `{ tool, enabled?, auth? }` wrapper only when a tool needs `enabled: false` or per-tool `auth`. `auth` names an auth **table** (a `table({ auth: true })` handle or its name) — Xano's ONLY MCP auth surface (per-tool; there is no server-level gate). An entry that names no tool (no handle, no `id`) THROWS at export rather than emitting the `id: 0` null reference it used to; a deliberate raw `id: 0` warns and is carried through, so a pulled workspace still round-trips.
 - `agent({ name, guid?, description?, docs?, enabled?, canonical?, tags?, history?, llm, tools?, output? })` — an LLM orchestrator. No top-level `instructions`/`prompt`/`spec` — the prompt lives under `llm`. Invoke from a stack with `s.ai.agent.run({ agent, args })`.
   - `llm` (REQUIRED): typed provider settings, a discriminated union on `type` (`"xano-free" | "anthropic" | "openai" | "google-genai"`). Shared fields: `systemPrompt?`, `maxSteps?` (default `5`), and `prompt?` XOR `messages?` (genuinely exclusive: both is a type error and throws — the engine stores ONE `prompt_type`, so one would be dropped); plus provider fields (`apiKey?`, `model?`, `temperature?`, `reasoningEffort?`, …). String fields accept Twig placeholders — `{{ $args.x }}` for run inputs (the `args` of `s.ai.agent.run`), `{{ $env.NAME }}` for env vars.
@@ -728,7 +719,7 @@ The run is isolated in ways that make a correct test fail for reasons the failur
   - **Tenant instances (isolated DB):** a tenant's realtime objects live in the TENANT's database, so BOTH halves of a client must name the tenant.
     - Socket: `server.getUrl(base, { tenant })` → `/ws/<tenant>:<canonical>`. ⚠ A bare canonical on a tenant host resolves against the INSTANCE workspace instead.
     - That colon form is PECULIAR TO THE SOCKET. Every other tenant URL gives the tenant its OWN segment — the HTTP half of the same client is `https://<host>/tenant/<tenant>/api:<canonical>/…`. NO request header is required for either.
-    - Because the shapes differ, `getUrl` TRANSLATES a tenant base URL instead of concatenating: pass the `https://<host>/tenant/<name>` that `sandbox details` prints (and that deploy injects as `window.XANO_HOST`) and the tenant is LIFTED into the socket form. So `getUrl(window.XANO_HOST)` needs no `{ tenant }`, and a CONFLICTING `{ tenant }` alongside it throws.
+    - Because the shapes differ, `getUrl` TRANSLATES a tenant base URL instead of concatenating: pass the `https://<host>/tenant/<name>` that `xanots status` prints (and that deploy injects as `window.XANO_HOST`) and the tenant is LIFTED into the socket form. So `getUrl(window.XANO_HOST)` needs no `{ tenant }`, and a CONFLICTING `{ tenant }` alongside it throws.
     - ⚠ `getUrl`/`socketUrl` are NOT idempotent — a `baseUrl` that already carries a `/ws/<…>` path (an earlier result of either) THROWS. Resolve ONCE from the http(s) base; pass that result to `new WebSocket`, never back in as a base.
     - Still pass `{ tenant }` explicitly for a tenant on its OWN DOMAIN — the hostname carries it for HTTP, but there is nothing in the URL for the socket to lift.
     - ⚠ Tokens are tenant-scoped (audience `<tenant>:<license>`, not the bare license), so one minted through the instance workspace is REJECTED by a tenant's realtime server — authenticate and dial through the same tenant.
@@ -1367,7 +1358,7 @@ TypeScript annotations survive in the body, and top-level `await` works.
 
 # Lock file
 
-> Read when a `xano.lock` exists or should — renaming/pruning/adopting identities, seeding the lock programmatically, or asking which commands write it.
+> Read when a `xano.lock` exists or should — renaming/pruning/importing identities, seeding the lock programmatically, or asking which commands write it.
 
 `xano.lock` pins each object's guid and each api-group/toolset canonical, so renames
 stay renames (guids otherwise derive from `(type, name)`; a query's from `(api group,
@@ -1380,11 +1371,11 @@ old key drops automatically once its guid re-lands under the composed one).
 - `xanots lock rename <kind> <old> <new>` — `kind` is the payload key (or `table`/`api_group`).
   Run it after renaming in code; the next export emits the original guid under the new name.
 - `xanots lock prune <entry-file> [keys…] --yes` — drops orphaned entries. Finding orphans
-  RUNS the entry's module scope (env assertions included); `--no-verify --yes <kind:name>…`
+  RUNS the entry's module scope (env assertions included); `--identity-only --yes <kind:name>…`
   prunes named keys with no evaluation and no orphan check.
-- `xanots lock adopt <live-bundle.json> [--yes]` — seed the lock from an engine
+- `xanots lock import <live-bundle.json> [--yes]` — seed the lock from an engine
   packageExport when taking over an existing workspace.
-- Every lock subcommand accepts `--lock=<path>`. `rename`/`adopt` take no entry file, so
+- Every lock subcommand accepts `--lock=<path>`. `rename`/`import` take no entry file, so
   from outside the lock's directory pass `--lock` (or `--entry=<entry-file>` to derive it).
 - Programmatic use: call `seedLockOverrides(readLockFile(path))` BEFORE importing any def
   module — references bake guids at import time, so late seeding is a silent no-op
@@ -1392,7 +1383,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