@xano/sdk 1.0.4 → 1.0.6

package/guides/deploying.md

@@ -89,15 +89,15 @@ processes at once.
 > **Upgrading:** a file written before profiles is read as the `default` profile with no
 > action needed. It is rewritten in the new shape the next time something writes to it.
 
-**Project-local credentials** — pass `--local` to `login` to cache tokens in a
+**Project-local credentials** — pass `--local-auth` 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`, `whoami`, token refresh) resolves them **project-local first, global
 as a fallback**: it uses `./.xano/auth.json` when present, otherwise `~/.xanosdk/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`. A `logout`
+so a `--local-auth` project keeps working without repeating the flag. `login` and `logout` do
+**not** fall back: they target the shared global cache unless you pass `--local-auth`. A `logout`
 naming a profile that only `./.xano/auth.json` holds exits 8 (not found in the shared file)
-and names `xanosdk logout --local -p <name>` — it does not report the session as gone. A
+and names `xanosdk logout --local-auth -p <name>` — it does not report the session as gone. A
 logout clears stored profiles only: with the `XANO_*` credential variables still set, it
 says so, and commands keep authenticating with them. An explicit
 `--config`/`$XANO_CONFIG` wins over both default file locations; only the three-variable
@@ -113,7 +113,7 @@ as JSON, while the human-readable progress (and the live URLs) echoes to stderr:
 
 ```jsonc
 {
-  "kind": "ephemeral",                  // or "local-engine"
+  "kind": "ephemeral",                  // or "local"
   "destination": {                     // the PARENT it was created under, then the environment itself
     "instance": "https://x.xano.io", "workspaceId": 1, "kind": "ephemeral",
     "label": "ezm0-xkdq-6564", "url": "https://x.xano.io/tenant/ezm0-xkdq-6564",
@@ -144,7 +144,7 @@ again, when the suite could not be run — exit 6 — and `unreachable`, the tes
 (as `test run` takes them), when it stopped answering part-way; the same `N passed, M failed,
 K not run` line `test run-all` prints closes the run), `landingRecord` (`{ destination, file,
 recorded, changed, cleared }`: what this deploy recorded as landed, the scope of a later
-`--prune`; `null` for a local engine), `staticRemoved` (`{ urls, verified }`: the frontends a replace took down, below),
+`--prune`; `null` for a Xano Engine), `staticRemoved` (`{ urls, verified }`: the frontends a replace took down, below),
 `notApplied` (flags accepted and not acted on — `--expires-hours` on an ephemeral that already
 exists), `unconfigured`, and `passwordHashesUnverifiable` (below). The raw
 workspace blob is deliberately never dumped: it carries per-tenant secrets that must not land
@@ -152,8 +152,8 @@ in shell history or CI logs.
 
 `xanosdk test run-all --json` (and `test run`, `test list`) writes the same per-test entries at
 the top level, beside the backend they ran on: `kind`, `env` (the ephemeral's or tenant's handle;
-`null` for a local engine or a workspace), `name` (the backend's own name whatever its kind — the
-same handle on an ephemeral or tenant, the engine's name on a local engine) and `display` (its display
+`null` for a Xano Engine or a workspace), `name` (the backend's own name whatever its kind — the
+same handle on an ephemeral or tenant, the engine's name on a Xano Engine) and `display` (its display
 name), each always present, `null` where the backend has none. When the suite stops answering
 part-way, the rest are not started and the run exits 6 with a failure document whose
 `details.results` is that document — `total` the whole suite, `notRun` and `unreachable` the tests
@@ -169,8 +169,8 @@ out and named (`--env-var GREETING`) — pass them again, or keep them in `xano/
 `xano/.secrets.json`, which a deploy reads. The same text is the `--json` error's `message`.
 
 **Where it goes** — the instance your **token is bound to** (the token's `aud`), never a
-flag. `xanosdk deploy` create-or-refreshes an **ephemeral**, which is the only environment it
-writes to. Reaching your real workspace is the separate release flow: cut a release from
+flag. `xanosdk deploy --ephemeral` create-or-refreshes an **ephemeral**; a bare `xanosdk deploy`
+runs the code on the Xano Engine on this machine instead ([below](#deploying-locally)). Reaching your real workspace is the separate release flow: cut a release from
 what ran, then `xanosdk promote <release>` lands it there as a new branch, leaving live
 untouched until you say otherwise.
 
@@ -250,10 +250,10 @@ step, without re-importing the backend.
 directory and nothing else: no compile, no backend import. `--to` picks the destination —
 `ephemeral[:<name>]`, `workspace`, or `tenant:<name>`; left off, the backend this project last
 deployed to — and a workspace or tenant asks before replacing what its users are served
-(`--yes` in CI). `publish` does not reach a local engine, so after a local-engine deploy it
-refuses the tracked engine and names `--to ephemeral`; the engine takes a frontend through
-`xanosdk deploy --local-engine --static <dir>` instead (below). Scaffolded projects carry it as `npm run xano:deploy:frontend`,
-which rebuilds first.
+(`--yes` in CI). After a local deploy it publishes to that engine (`--to local`
+names it), server half included — the upload `xanosdk deploy --local --static <dir>`
+makes, without re-importing the backend (below). Scaffolded projects carry it as
+`npm run xano:deploy:frontend`, which rebuilds first.
 
 ```bash
 xanosdk promote v2 --set-live                     # the backend, landed and live
@@ -402,6 +402,12 @@ Add your own public config (base URLs, *publishable* keys) with `--static-env KE
 verbatim to the browser, so everything injected is **public** — never put secrets here;
 those belong in backend env, read server-side via `env(name)`.
 
+**Your dev server follows the deploy.** In a scaffolded project, a deploy that publishes no static site writes the backend
+URL into the project's gitignored `.env.local` as `VITE_XANO_HOST`, in a marked block that leaves your own values alone and
+is replaced rather than repeated next time. **Restart the dev server to pick it up.** `--no-dev-env` turns it off, and so
+do `--static <dir>` and a site an earlier deploy published there that still serves — a frontend reads the URL at runtime. A `.env.local` your repo does not ignore is
+reported, never written.
+
 **Showing a stored file.** A file column comes back as `{ path, name, type, size, meta,
 access, url }`. Don't use its `url`: on a tenant-scoped environment that field addresses the
 instance host *without* the `/tenant/<name>` segment and 404s — as a broken `<img>`, while
@@ -425,20 +431,20 @@ retrying the bare URL.
 
 ## Deploy targets, and what a release changes
 
-**Two targets**, so the dev loop and the production step stay distinct:
+**Disposable targets and real ones**, so the dev loop and the production step stay distinct:
 
 | Command | Where it goes |
 |---|---|
-| `xanosdk deploy` | A disposable **ephemeral** environment — create-or-refreshed each run, auto-expiring, with its own URL. This is the default and needs no flag. |
+| `xanosdk deploy` | The **Xano Engine** on this machine — the default, with no flag and no Xano account needed ([below](#deploying-locally)). `--local` spells it out. |
+| `xanosdk deploy --ephemeral` | A disposable **ephemeral** environment on Xano's cloud — create-or-refreshed each run, auto-expiring, with its own URL. |
 | `xanosdk promote <release>` | Your **main Xano instance** workspace — the production target. Lands a release on a branch named for it (`--set-live` serves it). Its table changes reach live as it lands — see [what a landing does to tables](#what-a-landing-does-to-tables). |
 | `xanosdk tenant deploy <tenant> <release>` | A **customer tenant** — the same release, landed on someone else's deployment. It **replaces** what the tenant serves: anything the release does not carry is removed. Static hosting is kept. |
 | `xanosdk deploy --to <dest>` | The **escape hatch**: merges a local build straight into `workspace` or `tenant:<name>`, skipping the release record. |
-| `xanosdk deploy --local-engine` | A **local engine** on this machine — no Xano account needed ([below](#deploying-to-a-local-engine)). |
-| `xanosdk test` | Nothing — it only reads. Runs the tests an already-deployed backend carries; `--on` picks which one, `local-engine` and `workspace` included. |
+| `xanosdk test` | Nothing — it only reads. Runs the tests an already-deployed backend carries; `--on` picks which one, `local` and `workspace` included. |
 
-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. `xanosdk
-export` and `xanosdk preflight` still work meanwhile.
+Not every instance has ephemeral environments enabled. Where they are off, `deploy --ephemeral`
+says so and names who can turn them on. A bare `deploy` (the Xano Engine), `xanosdk export` and
+`xanosdk preflight` still work meanwhile.
 
 Every `deploy` is a **full replace** of the disposable environment — always fresh — unless
 you pass `--keep-data`. Landing somewhere real is the opposite by design: it changes what
@@ -454,7 +460,7 @@ object in `details.outOfScope`, and the rerun with `--yes` printed).
 
 ### Keeping your data between deploys
 
-`xanosdk deploy --keep-data` redeploys to your ephemeral or local engine by **merging** into
+`xanosdk deploy --keep-data` redeploys to your ephemeral or Xano Engine by **merging** into
 what an earlier deploy put there, instead of replacing it. Code and schema changes land,
 objects removed from the project are deleted, and the rows already in the tables stay. Seed
 rows are not written again.
@@ -469,7 +475,7 @@ and exits 0, as any declined confirmation does). Without one the
 merge is refused before it writes, as `--prune` refuses the same deletion:
 `SDK_PRUNE_OUT_OF_SCOPE`, exit 2, each object in `details.outOfScope` as `{ type, name, label }`
 (the shape `deploy --to --prune` uses), and the rerun with `--yes` printed. A merge that goes ahead names them in `--json`'s `notLanded`. The scaffolded
-`npm run xano:deploy:local-engine` passes it, so the rows you enter through your app survive
+`npm run xano:deploy` passes it, so the rows you enter through your app survive
 every code change.
 
 It merges only into an environment an earlier deploy **finished** filling. Otherwise it
@@ -535,7 +541,7 @@ the name back restores them. Columns are named
 The limits, in one place: rows survive only in tables and columns that keep their identity
 (a table renamed through `xanosdk lock rename` keeps its rows; an unrecorded rename is refused,
 below); changed env values and a new table's seeds need `--reset`;
-a local engine's rows last as long as its process (an engine update restarts it empty, and the
+a Xano Engine's rows last as long as its process (an engine update restarts it empty, and the
 next run seeds); and a test whose `datasource` is `"live"`
 sees the kept rows, not only the seed fixtures.
 
@@ -602,24 +608,24 @@ Another import already running on the instance is not a refusal of the project:
 `--to` already merges, so `--keep-data --to` is refused; the flags that only mean something
 with `--to` (`--seed`, `--prune`, `--dry-run`, …) stay refused alongside it.
 
-### Deploying to a local engine
+### Deploying locally
 
-`xanosdk deploy --local-engine` deploys to an engine running on this machine instead of an
+`xanosdk deploy --local` deploys to an engine running on this machine instead of an
 ephemeral — no network round-trip per deploy. It needs nothing configured:
 
 - **The first run** resolves the latest published engine for this machine's platform,
   downloads it, checks it against the sha256 its release recorded, and **pins** that version in
-  your `package.json` under `"xanosdk": { "@xano/sdk": { "localEngine": "vX.Y.Z" } }` —
+  your `package.json` under `"xanosdk": { "@xano/sdk": { "engine": "vX.Y.Z" } }` —
   creating a `package.json` holding only that pin when the project has none. Commit that change —
   every checkout of the project then runs the same engine.
 - **Every later run** uses the pinned version, whatever is newest. Each version downloads once
   per machine and is shared by every project on it (`~/.xanosdk/local-engine`, or
-  `XANOSDK_LOCAL_ENGINE_HOME`); a cached pin deploys with no network access.
+  `XANOSDK_ENGINE_HOME`); a cached pin deploys with no network access.
 - **A newer engine** is announced on each deploy (checked at most once an hour; opt out with
   `XANOSDK_NO_UPDATE_CHECK=1`). In an interactive terminal the deploy asks whether to update,
   defaulting to no — a version you declined is only noted afterwards, not asked again. In CI,
   piped output or `--json` it prints a one-line notice and keeps the pin. The pin never moves
-  without a yes or an explicit `xanosdk local-engine update`.
+  without a yes or an explicit `xanosdk local update`.
 - **A running engine on a different version** than the one the project now resolves to — after
   an update, or after a teammate moved the pin — is stopped and replaced, and the deploy says
   so.
@@ -629,33 +635,32 @@ ephemeral — no network round-trip per deploy. It needs nothing configured:
   keeps the one-hour default; its `--ttl <duration>` flag changes it.
 
 An engine update restarts the engine, and a restarted engine starts **empty**: the next
-`--keep-data` run (which the scaffolded `npm run xano:deploy:local-engine` passes) seeds it
+`--keep-data` run (which the scaffolded `npm run xano:deploy` passes) seeds it
 rather than merging, so rows entered through your app do not survive the upgrade.
 
-**Operating on it.** After a local-engine deploy, the engine is the backend this project
+**Operating on it.** After a local deploy, the engine is the backend this project
 tracks, so bare `xanosdk test run-all`, `env set`, `env pull`, `tables`, `impersonate` and
-`status` reach it — none of them needs a Xano account. Name it explicitly as `local-engine`,
-or `local-engine:<name>` for another one from `xanosdk local-engine list` (the full grammar is in
-[the CLI guide](cli.md#naming-a-backend)). Two commands cannot serve it and refuse it by name:
-`publish` (a local engine takes its frontend from `deploy --local-engine --static`; or pass
-`--to ephemeral`) and `release create`
+`status` reach it — none of them needs a Xano account. Name it explicitly as `local`,
+or `local:<name>` for another one from `xanosdk local list` (the full grammar is in
+[the CLI guide](cli.md#naming-a-backend)). `publish` puts a built frontend on it without
+re-importing the backend. One command cannot serve it and refuses it by name: `release create`
 (the cut runs on the instance — pass `--from ephemeral`).
 
 | Command | What it does |
 |---|---|
-| `xanosdk local-engine update` | Moves the pin to the latest engine (`--version <v>`: that one, downgrades included), downloads it, and restarts the project's running engine on it. Commit `package.json`. |
-| `xanosdk local-engine cache list` | Each cached engine version, its size on disk, and the engines running on it. |
-| `xanosdk local-engine cache clear` | Removes every cached engine (`--version <v>`: just that one). An engine running on a removed version is stopped first; the next deploy fetches it again. |
+| `xanosdk local update` | Moves the pin to the latest engine (`--version <v>`: that one, downgrades included), downloads it, and restarts the project's running engine on it. Commit `package.json`. |
+| `xanosdk local cache list` | Each cached engine version, its size on disk, and the engines running on it. |
+| `xanosdk local cache clear` | Removes every cached engine (`--version <v>`: just that one). An engine running on a removed version is stopped first; the next deploy fetches it again. |
 
-#### A frontend on the local engine, and server rendering
+#### A frontend on the Xano Engine, and server rendering
 
-`xanosdk deploy <entry> --local-engine --static <dir>` publishes a built frontend to the
+`xanosdk deploy <entry> --local --static <dir>` publishes a built frontend to the
 engine's own static host after the import, as on an ephemeral, and reports it as `static.url`:
 `http://<prefix>.localhost:<port>`. Chrome, Firefox and Safari 26 resolve `*.localhost` to this
 machine by themselves (Safari on macOS 15 and earlier does not); a tool that does not resolve it
 can call the engine's own URL with a `Host: <prefix>.localhost:<port>` header. The engine needs a release
 that hosts static sites: an older one answers the upload with a 501, which the deploy reports
-without failing the backend (exit `3`), and `xanosdk local-engine update` moves the pin on.
+without failing the backend (exit `3`), and `xanosdk local update` moves the pin on.
 
 The engine hosts built output only, and refuses a build of more than 20,000 files or 256 MB unpacked.
 The deploy checks both before the import, so an oversize directory stops the run with nothing
@@ -681,7 +686,7 @@ that keeps a `svelte.config.js`.
 
 `vite build` then writes the client assets and prerendered pages at the output's root, a
 `404.html` fallback shell, and the server half in `.xano-ssr/`. Deployed with
-`--local-engine --static <that directory>`, the engine serves the files as files and renders every other
+`--local --static <that directory>`, the engine serves the files as files and renders every other
 path (a dynamic route, `__data.json`, a form action) through the server half, so a crawler that
 fetches `/products/lamp` gets that product's own `<title>` and meta tags. A server `load` reads
 the engine's own URL as `XANO_HOST` from `$env/dynamic/private`:
@@ -718,20 +723,20 @@ there instead (and says so in the build log), so that route boots — an unknown
 
 The cache above holds the engine **binaries**. A running engine keeps its own **runtime data** —
 its unpacked runtime files, its logs, and the records of running engines — beside them, under
-`engine/` in the same directory (`~/.xanosdk/local-engine`, or `XANOSDK_LOCAL_ENGINE_HOME`): in
+`engine/` in the same directory (`~/.xanosdk/local-engine`, or `XANOSDK_ENGINE_HOME`): in
 `engine/Library/Caches` on macOS and `engine/.cache` on Linux, the directory holding `dist`,
 `instances` and `logs` folders. Its `logs` folder holds one file per engine start; a start that
 fails names it.
 
 Expect it to reach roughly 600 MB after the first deploy, and to grow by a similar amount for
-each engine version you run, since every version unpacks its own copy. `xanosdk local-engine cache
-list` shows its size, and `xanosdk local-engine cache clear` (with no `--version`) removes it with the
+each engine version you run, since every version unpacks its own copy. `xanosdk local cache
+list` shows its size, and `xanosdk local cache clear` (with no `--version`) removes it with the
 engines once none is running — it names any engine still up; stop it and clear again. The next
 deploy recreates what it needs.
 
 Versions before this layout unpacked the same runtime into your own per-user cache directory.
 Nothing runs from that copy now; `cache list` shows it when it is there, and
-`xanosdk local-engine cache clear --legacy-runtime` removes it after asking (`--yes` without a
+`xanosdk local cache clear --legacy-runtime` removes it after asking (`--yes` without a
 terminal).
 
 #### Running a different engine without moving the pin
@@ -739,9 +744,9 @@ terminal).
 To try an experimental build, or a published version the project hasn't moved to, override the
 pin for your own runs instead of editing `package.json`:
 
-- `--local-engine=<value>` for one deploy;
-- `XANOSDK_LOCAL_ENGINE_OVERRIDE=<value>` for every deploy in this shell, including
-  `npm run xano:deploy:local-engine`, which passes a bare flag.
+- `--local=<value>` for one deploy;
+- `XANOSDK_ENGINE_OVERRIDE=<value>` for every deploy in this shell, including
+  `npm run xano:deploy`, which passes a bare flag.
 
 Both take a **version** (`v0.1.8`, or `0.1.8`: that release from the release manager), an
 **`https` URL** to an engine archive, or the **path** to an engine archive on this machine. A
@@ -758,24 +763,24 @@ next `--keep-data` run seeds it); unset the variable and the next deploy goes ba
 engine the same way.
 
 ```bash
-export XANOSDK_LOCAL_ENGINE_OVERRIDE=~/Downloads/engine-experimental.tar.gz
-npm run xano:deploy:local-engine          # runs the experimental build; package.json untouched
-unset XANOSDK_LOCAL_ENGINE_OVERRIDE        # next deploy is back on the pinned version
+export XANOSDK_ENGINE_OVERRIDE=~/Downloads/engine-experimental.tar.gz
+npm run xano:deploy          # runs the experimental build; package.json untouched
+unset XANOSDK_ENGINE_OVERRIDE        # next deploy is back on the pinned version
 ```
 
-`XANOSDK_LOCAL_ENGINE_TOKEN`, when set, is sent only to an override URL's host.
+`XANOSDK_ENGINE_TOKEN`, when set, is sent only to an override URL's host.
 `XANOSDK_ENGINE_RELEASES_URL` points version lookups at a different engine release service. Its
 engines are downloaded fresh on every deploy and kept apart from the version cache, and the
 deploy runs its latest without reading or writing the pin or checking for updates;
-`xanosdk local-engine update` refuses while it is set.
+`xanosdk local update` refuses while it is set.
 
 ### The release flow
 
 This is the path to a real destination. Each step leaves something the next one can name:
 
 ```bash
-xanosdk deploy ./xano/index.ts --test   # 1. stand it up on an ephemeral, run its tests
-xanosdk release create v1               # 2. cut a release from what just ran (after a local-engine deploy: --from ephemeral)
+xanosdk deploy ./xano/index.ts --ephemeral --test   # 1. stand it up on an ephemeral, run its tests
+xanosdk release create v1               # 2. cut a release from what just ran (after a local deploy: --from ephemeral)
 xanosdk promote v1                      # 3. land it in your workspace, on a branch named for it
 xanosdk tenant deploy acme v1           #    …or on a customer tenant
 ```
@@ -982,7 +987,7 @@ instead, so stdout is never empty. Branch on `code`, not on the message:
 | `SDK_EXPORT_INVALID` | The workspace failed an export check, or `--strict` promoted a warning. | `details.diagnostics`: `{ severity, code, message }` per failed check; under `--strict`, every warning that fails it; `code` names the check, e.g. `seed.public-seed`; `details.warnings` beside it, empty when the run printed none |
 | `SDK_CREDENTIAL_REJECTED` | The instance, or its sign-in server, refused the credential this run used: exit 1. The message names the sign-in that fixes it. | `details`: `{ profile, credentialType, instance, workspaceId, signIn }` (`profile` is `null` for an environment credential; `instance` and `workspaceId` are `null` for a refused `XANO_REFRESH_TOKEN`; `signIn` is `null` when the fix is a variable or an upgrade rather than a command) |
 | `SDK_USAGE` | The command line was mistyped or incomplete — an unknown flag, a value on a flag that takes none, a flag without the one it needs (`--dry-run` without `--to`), a missing argument, a confirmation with no terminal to ask on, a local file or directory it names that does not exist: exit 1. | `suggestion`: the closest match, when one is close enough |
-| `SDK_ERROR` | Any failure without a code of its own yet — including a NAMED thing that cannot be found (a backend, release, branch, static host, test, profile or local-engine version: exit 8). A network failure or a server error (5xx) is exit 8 before anything is written — the backend's lookup, a read-only command's read (`tables`, `test list`, `env pull`, `status`, `whoami`, `workspace details`, `workspace branch`'s list), a local engine's release lookup or download, and `--keep-data`'s reads ahead of its merge (whether the environment can merge, its live read, the merge preview) got no answer or a 5xx; rerun as printed — and exit 1 at a later step that never reached it (an import that was not sent: nothing was written — retry). A `501` on `--keep-data`'s check is an answer, not an outage: that backend cannot merge, so it is exit 1 with the deploy that replaces instead. | `suggestion`: the near name a not-found one is one slip from, when there is one (`suggestions`: every one, when a command missed several) |
+| `SDK_ERROR` | Any failure without a code of its own yet — including a NAMED thing that cannot be found (a backend, release, branch, static host, test, profile or Xano Engine version: exit 8). A network failure or a server error (5xx) is exit 8 before anything is written — the backend's lookup, a read-only command's read (`tables`, `test list`, `env pull`, `status`, `whoami`, `workspace details`, `workspace branch`'s list), a Xano Engine's release lookup or download, and `--keep-data`'s reads ahead of its merge (whether the environment can merge, its live read, the merge preview) got no answer or a 5xx; rerun as printed — and exit 1 at a later step that never reached it (an import that was not sent: nothing was written — retry). A `501` on `--keep-data`'s check is an answer, not an outage: that backend cannot merge, so it is exit 1 with the deploy that replaces instead. | `suggestion`: the near name a not-found one is one slip from, when there is one (`suggestions`: every one, when a command missed several) |
 
 A piped stdout gets the document too, without `--json`, so a script reading the pipe never gets
 an empty stdout. The exception is a command whose stdout is the data itself (`export` to stdout,
@@ -1238,6 +1243,58 @@ object with the same key *and* the same identity, so a lock cannot pin a guid th
 never had. If none of the lock's identities appear in the source, that is what pointing a
 project at an unrelated backend looks like, and the pull is refused unless you pass `--yes`.
 
+### Which side changed: the sync baseline
+
+When a workspace and this project differ, `workspace diff` also says **which side moved** since
+they last matched. Every command that makes them match records a baseline in `xano.lock`, under
+`synced`. A baseline is one content digest per object, kept per workspace and per branch. The
+commands that record one are `deploy --to workspace`, a verified `promote`, `pull workspace`
+and `init --from workspace`. Commit it with the rest of the lock.
+
+```bash
+xanosdk workspace diff ./xano/index.ts --json
+```
+
+```jsonc
+{
+  "matched": false,
+  "differing": ["query:GET list (apiGroup orders)", "table:order"],
+  "baseline": { "at": "2026-10-05T13:36:31.000Z", "by": "pull" },
+  "changedThere": ["query:GET list (apiGroup orders)"], // edited in Xano since the baseline
+  "changedHere": ["table:order"],                        // edited in this project since
+  "changedBoth": [],                                     // edited on both sides: a conflict
+  "unclassified": []                                     // differs, direction unknown
+}
+```
+
+- `changedThere`: pull before you deploy, or the deploy overwrites that edit.
+- `changedHere`: deploy it.
+- `changedBoth`: reconcile by hand.
+- `unclassified`: the baseline cannot tell. The object has no baseline entry, both sides
+  already differed when it was taken, or it is the workspace's own settings row, which is
+  never digested. A changed slug also shows only here, because digests leave slugs out.
+
+Additions and deletions are classified as well. The baseline keeps this project's objects apart
+from the rest of the branch, so an object the project never held (another source's, or a section
+a pull does not write into `xano/`) is never reported as deleted here; it shows up only when it
+changes in Xano. An object that is new in Xano counts as `changedThere` only when the baseline is
+**complete**: a pull, an `init --from`, a verified
+`promote` and a `--replace` record every object on the branch, and so does a merge deploy
+that read the branch first. With no baseline for the branch, `baseline` is `null` and the
+four lists are empty. A run that finds the branch exactly as recorded leaves the lock alone.
+
+A few things to know about the baseline:
+
+- It records what the branch holds after the sync, read back from the branch where the command
+  can do so, so an object stored differently from how it compiles is not reported as changed in
+  Xano. It is recorded whoever's objects landed (a `--bundle` from elsewhere, a release another
+  project cut), because it describes the branch, not ownership.
+- A baseline taken by a different SDK version under an older digest scheme is set aside
+  (`baseline: null`) and replaced by the next sync, rather than read as every object changed.
+- An SDK older than this feature drops `synced` when it rewrites `xano.lock`. Nothing breaks: the
+  next sync records a new baseline.
+- On a merge conflict in `xano.lock`, keep either side's baseline for a branch, or delete it.
+
 ### Deploying to a branch
 
 `--branch <label>` stages on a Xano branch instead of the live one, which is the safer shape

package/guides/environment.md

@@ -16,7 +16,7 @@ are what you get when the variable is unset.
 | `XANO_META_TOKEN` | Meta API bearer token. With the two above it forms a complete credential that outranks every other source, reads no file, and never rotates. |
 | `XANO_REFRESH_TOKEN` | OAuth refresh token for non-interactive runs (CI, agents). Paired with `XANO_CLIENT_ID`; the target instance comes from the token's own `aud` claim. Rotates on use — prefer the meta credential above. |
 | `XANO_CLIENT_ID` | OAuth client id that goes with `XANO_REFRESH_TOKEN`. Both are copied once out of the profile in `auth.json` after a local `xanosdk login`. |
-| `XANO_CONFIG` | Explicit path to the credential file. Wins over both default locations — the same thing `--config <path>` does. Refused beside `--local`, which names a different file. |
+| `XANO_CONFIG` | Explicit path to the credential file. Wins over both default locations — the same thing `--config <path>` does. Refused beside `--local-auth`, which names a different file. |
 | `XANO_PROFILE` | Which stored credential profile to act as, when no `--profile` names one. Outranked by the flag, by the project's `xano.profile.json` pin, and by an environment credential (which displaces it with a note on stderr). |
 | `XANO_GLOBAL_CONFIG` | Moves the **shared** credential cache off `~/.xanosdk/auth.json`. Only changes where the global cache lives; the project-local `./.xano/auth.json` and the `XANO_CONFIG`/`--config` override are unaffected. |
 | `XANO_CLIENT_FILE` | Moves the OAuth **client-registration** cache off `~/.xano/xanosdk-clients.json`. That file holds the `client_id` minted per auth host + redirect URI, not a credential. |
@@ -49,14 +49,14 @@ are what you get when the variable is unset.
 | `XANOSDK_UPDATE_REGISTRY` | Registry URL the check reads, instead of the npm endpoint for `@xano/sdk`. |
 | `XANOSDK_UPDATE_CACHE` | Moves the check's cache file off `~/.xanosdk/update-check.json`. |
 
-**Local engine** (see [Deploying to a local engine](deploying.md#deploying-to-a-local-engine))
+**Xano Engine** (see [Deploying locally](deploying.md#deploying-locally))
 
 | Variable | What it does |
 |---|---|
-| `XANOSDK_LOCAL_ENGINE_OVERRIDE` | An engine to run instead of the project's pinned one, for every `deploy --local-engine` in this shell: a version (`v0.1.8`), an `https://` URL to an engine archive (plain `http://` only from this machine), or an archive path. A value on `--local-engine=` beats it; it never reads or moves the pin. |
-| `XANOSDK_LOCAL_ENGINE_TOKEN` | Bearer credential sent with an override URL's download — only to that URL's own origin, never to another host a redirect leads to. |
-| `XANOSDK_LOCAL_ENGINE_HOME` | Moves everything the local engine writes off `~/.xanosdk/local-engine`: the engine cache, the running-engine records, and the engine's own logs and runtime data — see [where the engine keeps its data](deploying.md#where-the-engine-keeps-its-data). |
-| `XANOSDK_ENGINE_RELEASES_URL` | A different engine release service for version lookups. Its engines are fetched fresh each deploy, the pin is not read or written, and `xanosdk local-engine update` refuses while it is set. |
+| `XANOSDK_ENGINE_OVERRIDE` | An engine to run instead of the project's pinned one, for every `deploy --local` in this shell: a version (`v0.1.8`), an `https://` URL to an engine archive (plain `http://` only from this machine), or an archive path. A value on `--local=` beats it; it never reads or moves the pin. |
+| `XANOSDK_ENGINE_TOKEN` | Bearer credential sent with an override URL's download — only to that URL's own origin, never to another host a redirect leads to. |
+| `XANOSDK_ENGINE_HOME` | Moves everything the Xano Engine writes off `~/.xanosdk/local-engine`: the engine cache, the running-engine records, and the engine's own logs and runtime data — see [where the engine keeps its data](deploying.md#where-the-engine-keeps-its-data). |
+| `XANOSDK_ENGINE_RELEASES_URL` | A different engine release service for version lookups. Its engines are fetched fresh each deploy, the pin is not read or written, and `xanosdk local update` refuses while it is set. |
 
 **Escape hatches**
 
@@ -113,8 +113,8 @@ xanosdk env pull --from workspace --yes # and skip the confirmation
 ```
 
 The source is a backend that is running: `workspace`, `ephemeral[:<name>]`,
-`local-engine[:<name>]`, or `tenant:<name>` — the [backend grammar](cli.md#naming-a-backend)
-every command shares. Left off, it is the ephemeral or local engine this project last
+`local[:<name>]`, or `tenant:<name>` — the [backend grammar](cli.md#naming-a-backend)
+every command shares. Left off, it is the ephemeral or Xano Engine this project last
 deployed to. A bundle path is refused, because its env is whatever it was built with,
 which is the stale set this command exists to replace.
 
@@ -132,7 +132,7 @@ resolved env values in cleartext (see the `--bundle` note below).
 
 ```bash
 printf %s "$STRIPE_KEY" | xanosdk env set STRIPE_KEY --to workspace --yes  # value on stdin
-xanosdk env set FEATURE_FLAG on --to local-engine                          # or as the second argument
+xanosdk env set FEATURE_FLAG on --to local                          # or as the second argument
 xanosdk env unset STRIPE_KEY --to tenant:prod-eu                            # remove it
 ```
 
@@ -142,12 +142,12 @@ a deploy can't do that job. A merge deploy only adds names that aren't there yet
 `--replace` rewrites the whole workspace.
 
 The destination is `--to workspace`, `--to ephemeral[:<name>]`, `--to tenant:<name>`, or
-`--to local-engine[:<name>]` for a local engine. With none of these, the command writes to
-the ephemeral or local engine this project last deployed to. It never falls back to your
-workspace or a tenant, and a local engine needs no Xano account. A write to
+`--to local[:<name>]` for a Xano Engine. With none of these, the command writes to
+the ephemeral or Xano Engine this project last deployed to. It never falls back to your
+workspace or a tenant, and a Xano Engine needs no Xano account. A write to
 the workspace or a tenant asks for confirmation first, and `--yes` skips it; that flag is
 required when there is no terminal, including when the value is piped in. Ephemerals and the
-local engine are throwaway, so the command doesn't ask.
+Xano Engine are throwaway, so the command doesn't ask.
 
 The value is never printed. Pipe it on stdin to keep it out of shell history. One trailing
 newline is dropped, so `echo` works too. An empty value is refused unless

package/guides/marketplace.md

@@ -169,6 +169,23 @@ that arrived some other way is configured by this run too: a plain `npm install`
 pull request, a `git pull` that changed `package.json`. It also means nothing has to recover
 a package name out of a `file:` or tarball specifier in order to configure it.
 
+A **toolchain module** gets two more steps, and `reinstall` runs both as well. Its peers other
+than `@xano/sdk` (`zod`, say) are added as direct dependencies through the project's package
+manager: yarn never installs peers, and pnpm does not link them where `routes.gen.ts` can import
+them. Then, when the project keeps a `routes.gen.ts` beside its entry, the file is regenerated,
+so the module's section lands with the module rather than at the next `xano:routes`. Under
+`--json`, `peers` lists the specs that were added (`["zod@^4.0.0"]`, or `[]`), and `routes` says
+what happened to the file:
+
+| `routes` | Meaning |
+|---|---|
+| `written` | Regenerated. |
+| `unchanged` | Already up to date. |
+| `absent` | The project has no `routes.gen.ts` to refresh. |
+| `skipped` | It could not be regenerated here. The warning says why; run `npm run xano:routes`. |
+
+`remove` reports `routes` the same way, for the file it regenerates without the removed module.
+
 `init` takes the same names and resolves them the same way — `--marketplace auth` is
 `@xano-sdk/auth`, and an unlisted name exits 8 before anything is written — so a project can be
 scaffolded with its add-ons already installed and registered:
@@ -207,6 +224,10 @@ What happens then depends on whether the module predates the command:
 | `install` re-run over a module already in `dependencies`, or `reinstall` | Refused and **left alone**, settings included, because deleting a module you already had over a version mismatch is not a repair. Upgrade the SDK, or `marketplace remove` it. |
 | `init --marketplace` | Reported as a module that was not added and taken back off disk. The scaffold itself completes and works. |
 
+A *different* installed module that is out of range does not stop the verb. `install`, `reinstall`
+and `remove` skip it with a warning naming its range and the fix, and leave its settings and its
+`routes.gen.ts` block exactly as they were. `export`, `deploy` and `preflight` still refuse it.
+
 The point of undoing the install is that the alternative is worse: a module whose hooks were
 built against a contract this SDK does not have registers and applies **nothing**, so
 `Installed` would be followed by a project where every command that loads modules refuses it.

package/guides/module-contract.md

@@ -163,6 +163,7 @@ const plugin: ToolchainPlugin = {
   answersFromConfig: (config) => ({ ... }),
   onBundle: async (ctx) => ({ ... }),
   onPreflight: async (ctx) => ({ ... }),
+  routesManifest: (ctx) => ({ imports: [...], source: "..." }),
 };
 
 export default plugin;
@@ -175,10 +176,11 @@ guessing which would run code the manifest did not describe.
 Every hook is optional. A module that only adds a `.gitattributes` line declares
 `contributes` alone.
 
-Five hooks, and deliberately no more. This contract was designed from one example, and a
-contract designed from one example generalizes badly, so it covers exactly what that first
-module needed and stops. The second toolchain module is the one that should widen it, with a
-real second set of requirements in hand.
+Six hooks, and deliberately no more. The first five were designed from one example (a module
+that renders the workspace to a committed tree) and cover exactly what it needed. The sixth,
+`routesManifest`, was added when a second module, `@xano-sdk/zod`, brought a second real set
+of requirements: writing into a file the SDK generates rather than a tree of its own. A hook
+is added when a module needs it, not in anticipation.
 
 ## Questions
 
@@ -452,6 +454,78 @@ reason to blank.
 A project whose plugins declare no `onPreflight` never pays for the engine's rendering at all,
 so declaring the hook is what turns that fetch on.
 
+## `routesManifest`
+
+```ts
+import type { ToolchainPlugin } from "@xano/sdk/plugin";
+
+const plugin: ToolchainPlugin = {
+  kind: "toolchain",
+  routesManifest: (ctx) => ({
+    imports: [{ from: "zod", names: ["z"] }],
+    source: `export const ROUTE_SCHEMAS = ...;`,
+  }),
+};
+```
+
+Your module's section of the route manifest, `xano/routes.gen.ts`. It runs wherever that file
+is written: `xanosdk routes ./xano/index.ts --emit xano/routes.gen.ts` (the scaffold's
+`xano:routes`), `pull`, `generate`, and the refresh `marketplace install`, `reinstall` and
+`remove` make, so your block lands with your module.
+
+| `RoutesManifestContext` | What it carries |
+|---|---|
+| `inputs` | Every endpoint's, channel's and message's request inputs, under the manifest's final keys (`routes`, `channels`, `messages`), in a fixed order. |
+| `config` | Your block from the project's `package.json` `"xanosdk"` object. |
+| `sdkVersion` | The running `@xano/sdk` version. |
+
+`inputs` is a validator-neutral description (type `RouteInputs` in `@xano/sdk/plugin`, not
+the generated map of the same name): each input's name, type, `required`, `nullable`, list
+bounds, enum values, methods, and children. A database link is one `dbLink` entry carrying the
+linked table's expanded `columns`, to spread into the surrounding object; `columns` is
+`undefined` when the payload does not carry that table, which is not "no columns". Walk this
+rather than the payload: it is the same description the SDK renders its own `RouteInputs`,
+`ChannelInputs` and `MessageInputs` types from, so a validator built from it cannot disagree
+with them.
+
+**Where the section lands.** The SDK composes the file: the merged imports of every module at
+the top, then the core sections, then each module's `source` in a marked block, blocks ordered
+by package name:
+
+```ts
+// xanosdk:begin @xano-sdk/zod
+// xanosdk:version 1.0.3 - generated; edits inside this block are overwritten
+...
+// xanosdk:end @xano-sdk/zod
+```
+
+Your source is in the same file as the core sections, so it names `RouteInputs`,
+`ChannelInputs`, `MessageInputs` and `MessageName` directly, without importing them; all four
+are always emitted, as `{}` when empty. Anything you export is exported from `routes.gen.ts`.
+Your names share one scope with the core sections and every other module's, so a collision
+fails the user's typecheck rather than being renamed. A blank `source` writes no block, and its
+imports are dropped with it: that is how a config that turns the section off removes it.
+
+**Imports are declared, never written.** The core sections import nothing, which is what keeps
+the file free of the SDK runtime in a frontend bundle. Declare yours in `imports`; never put an
+`import` line in `source`. Each `from` must be a bare package name: `@xano/sdk` and its
+subpaths, a relative or absolute path, and a protocol (`node:`) are all refused, naming your
+module. Each name must be a plain identifier, with no `as` rename. A package you import must
+resolve from the user's project, so declare it in your `peerDependencies`:
+`xanosdk marketplace install` adds each peer other than `@xano/sdk` that the project does not
+already declare as a direct dependency, with your range, through the project's package manager.
+
+**Synchronous and pure.** No filesystem, network, clock or randomness: the same context must
+return the same section every time. Every writer of the file must produce the same bytes for
+the same workspace and installed modules, or `routes --emit --strict` passes or fails depending
+on which command last wrote it. A Promise, or any value that is not `{ imports?, source }`, is
+refused, and `source` must not spell a block marker (`// xanosdk:begin`, `// xanosdk:end`).
+
+**A throw is your module failing, not the manifest.** The core sections are still refreshed,
+your previous block is kept exactly as it was, and a warning names your module. On
+`routes --emit --strict` it is fatal instead, because a check that did not run must not read
+as one that passed.
+
 ## `HookResult`: `failed` is not a throw
 
 ```ts
@@ -544,6 +618,8 @@ Things worth proving about your own module:
 - Your `onBundle` writes nothing when `ctx.frozen` is true.
 - Your `onBundle` handles `ctx.entry === undefined`.
 - Your hooks never read `payload.env` values, because they are blanked.
+- `routesManifest` returns the same section for the same context, called twice, and what it
+  writes typechecks beside the core sections of a real `routes.gen.ts`.
 
 ## Publishing
 

package/guides/project-structure.md

@@ -41,3 +41,17 @@ free to use any other layout; only `index.ts` registering the objects matters.
 Authoring is **declarative def-objects** passed to factories; there is no callback/chaining
 builder. `xano.export()` returns the importable `packageExport` bundle, and
 `xanosdk export`/`deploy` read the module's default export.
+
+## Wiring a project by hand
+
+`xanosdk init` writes all of this for you. Without it, two lines set a project up:
+
+```bash
+npm init -y && npm pkg set type=module && npm install -D @xano/sdk
+npx xanosdk upgrade     # rewrites npm's caret to the range init writes
+```
+
+Write your workspace in `xano/index.ts`; `login` and `deploy` are unchanged. `type=module`
+matters: Xano SDK defs are ESM-only, and `npm init` writes `"type": "commonjs"`. A TypeScript
+entry wants [`tsx`](https://tsx.is) (`npm i -D tsx`), which the CLI picks up — Node's type
+stripping does not remap a workspace's `./x.js` imports.