@xano/sdk 1.0.11 → 1.0.13

package/dist/{workspace-export-UHY22VBI.js → workspace-export-GHMUSX2P.js}

@@ -1,13 +1,13 @@
 import {
   assertBranchReadSupported,
   exportWorkspaceBundle
-} from "./chunk-QC3MKMDK.js";
+} from "./chunk-R7XZW4SB.js";
 import "./chunk-3DRXWLJ5.js";
 import "./chunk-X4DVXBFY.js";
-import "./chunk-TR7EOUQE.js";
+import "./chunk-DILYWJVP.js";
 import "./chunk-MF4W6FHU.js";
 import "./chunk-X2NL4KUO.js";
-import "./chunk-C6KBZH7M.js";
+import "./chunk-D4VKPOD4.js";
 import "./chunk-YEH5OIPF.js";
 import "./chunk-UTI5G6OJ.js";
 import "./chunk-5ZSO4T2G.js";
@@ -18,4 +18,4 @@ export {
   assertBranchReadSupported,
   exportWorkspaceBundle
 };
-//# sourceMappingURL=workspace-export-UHY22VBI.js.map
+//# sourceMappingURL=workspace-export-GHMUSX2P.js.map

package/dist/{writable-2A6MBSFD.js → writable-Y6CE2CGK.js}

@@ -5,9 +5,9 @@ import {
   unreadableError,
   unwritableBlocker,
   unwritableError
-} from "./chunk-ULUUOUQX.js";
+} from "./chunk-AUYXBKGR.js";
 import "./chunk-FWD7AL6N.js";
-import "./chunk-C6KBZH7M.js";
+import "./chunk-D4VKPOD4.js";
 import "./chunk-YEH5OIPF.js";
 import "./chunk-UTI5G6OJ.js";
 import "./chunk-5ZSO4T2G.js";
@@ -22,4 +22,4 @@ export {
   unwritableBlocker,
   unwritableError
 };
-//# sourceMappingURL=writable-2A6MBSFD.js.map
+//# sourceMappingURL=writable-Y6CE2CGK.js.map

package/dist/{xanosdk-import-767BQ2HP.js → xanosdk-import-HBQH3ZBS.js}

@@ -13,15 +13,15 @@ import {
   resetXanoSdkImportDetection,
   withDefaultBranchPointer,
   xanosdkImport
-} from "./chunk-B7JRCM2S.js";
+} from "./chunk-5XDKKE5Y.js";
 import "./chunk-3DRXWLJ5.js";
 import "./chunk-X4DVXBFY.js";
-import "./chunk-VJTTTIIB.js";
-import "./chunk-TR7EOUQE.js";
+import "./chunk-6QJORUHC.js";
+import "./chunk-DILYWJVP.js";
 import "./chunk-4KHEMC32.js";
 import "./chunk-MF4W6FHU.js";
 import "./chunk-X2NL4KUO.js";
-import "./chunk-C6KBZH7M.js";
+import "./chunk-D4VKPOD4.js";
 import "./chunk-7FIMUFBP.js";
 import "./chunk-H2V3N23D.js";
 import "./chunk-3JDU4VRL.js";
@@ -53,4 +53,4 @@ export {
   withDefaultBranchPointer,
   xanosdkImport
 };
-//# sourceMappingURL=xanosdk-import-767BQ2HP.js.map
+//# sourceMappingURL=xanosdk-import-HBQH3ZBS.js.map

package/dist/{xanosdk-project-PETOFVUQ.js → xanosdk-project-W45IR3Q7.js}

@@ -3,29 +3,29 @@ import {
   enterProjectRoot,
   isProjectDir,
   projectDirFrom
-} from "./chunk-RNKP5TA2.js";
+} from "./chunk-UKC65HBQ.js";
 import "./chunk-EUUUMY7J.js";
-import "./chunk-D5NAWB4P.js";
-import "./chunk-7YSZSEZL.js";
-import "./chunk-FGNDJBT4.js";
-import "./chunk-B3NH5UBI.js";
+import "./chunk-GRWYO2MS.js";
+import "./chunk-ZISPEBNM.js";
+import "./chunk-HDANNK4A.js";
+import "./chunk-JKGRQW6D.js";
 import "./chunk-ZFDZKNGG.js";
 import "./chunk-FWD7AL6N.js";
-import "./chunk-6PTITS3M.js";
+import "./chunk-C4TZP5PQ.js";
 import "./chunk-DXUICABI.js";
-import "./chunk-TR7EOUQE.js";
+import "./chunk-DILYWJVP.js";
 import "./chunk-4KHEMC32.js";
 import "./chunk-DNBP4GJN.js";
-import "./chunk-QL3ZJWGG.js";
+import "./chunk-H5FAYLCR.js";
 import "./chunk-WAVNUTMT.js";
-import "./chunk-5QOV52V4.js";
+import "./chunk-I2AVVARA.js";
 import "./chunk-LLNZGEFK.js";
 import "./chunk-HU7F56VF.js";
 import "./chunk-MF4W6FHU.js";
 import "./chunk-X2NL4KUO.js";
 import "./chunk-IZI3SYXH.js";
 import "./chunk-LJM5CIY4.js";
-import "./chunk-C6KBZH7M.js";
+import "./chunk-D4VKPOD4.js";
 import "./chunk-YEH5OIPF.js";
 import "./chunk-UTI5G6OJ.js";
 import "./chunk-5ZSO4T2G.js";
@@ -39,4 +39,4 @@ export {
   isProjectDir,
   projectDirFrom
 };
-//# sourceMappingURL=xanosdk-project-PETOFVUQ.js.map
+//# sourceMappingURL=xanosdk-project-W45IR3Q7.js.map

package/guides/authoring.md

@@ -553,9 +553,11 @@ query({
   happened by the time the override lands.
 - A `resultStrategy: "replace"` middleware attached `post` rewrites the response at runtime,
   which `InferResponse` can't see — declare `responseShape` on the endpoint.
-- `workspaceConfig` also carries `realtime`, `documentation`, and `swagger`, which are
-  server-shaped and carried verbatim rather than authored. `realtime` there is the **legacy**
-  workspace-level block, not the realtime primitives you author.
+- `workspaceConfig` also carries `realtime`, `documentation`, and `swagger`. `realtime` is
+  server-shaped and carried verbatim rather than authored — it is the **legacy**
+  workspace-level block, not the realtime primitives you author. `documentation` is the
+  authored gate on the hosted docs (omit it to leave the target's alone), and `swagger` is a
+  boolean (default `false`).
 
 **The canonical rate-limit middleware.** Build the per-user key with the filter chain
 (`"prefix" + auth("id")` doesn't exist):
@@ -651,7 +653,8 @@ workspaceConfig({ name: "my-app", env: { STRIPE_KEY: "" } });
 
 ```bash
 # xano/.env — gitignored, preserved across a pull, and read with no flag by every
-# command that compiles a bundle (deploy, export, preflight).
+# command that compiles a bundle (deploy, export, preflight, workspace diff,
+# workspace reset-tables, and release create's comparison).
 STRIPE_KEY=sk_live_...
 ```
 
@@ -886,9 +889,12 @@ with `allRows: true`, which wipes the table and returns the deleted count — th
 longer be reached by forgetting an argument. Reach for `s.db.truncate({ table, reset: true })`
 when the id sequence should restart too.
 
-Deploy is a full replace, so re-deploying re-seeds cleanly — no duplicate rows. Seed
-data travels only in the deploy package (resolved at deploy time); it never enters the
-compiled workspace bundle.
+A deploy without `--keep-data` is a full replace, so it re-seeds cleanly — no duplicate
+rows. The scaffolded `xano:deploy` passes `--keep-data`, which merges and leaves table rows
+alone (`--reset` forces the replace and re-seed). A `--to` merge writes seed rows only with
+`--seed`, and `workspace reset-tables` puts named tables back to their seeds. Seed data
+travels only in the deploy package (resolved at deploy time); it never enters the compiled
+workspace bundle.
 
 For data in a file, use `seedFile`:
 

package/guides/bundle.md

@@ -8,7 +8,7 @@ engine grows a new one.
 A bundle is what `export` writes:
 
 ```bash
-npx xanosdk export ./xano/index.ts --out workspace.json
+npx xanosdk export ./xano/index.ts --out bundle.json
 ```
 
 ```ts

package/guides/cli.md

@@ -26,7 +26,7 @@ xanosdk marketplace remove <toolchain-package>     # uninstall it and drop what
 xanosdk export ./xano/index.ts              # bundle to stdout
 xanosdk export ./xano/index.ts --out ws.json
 xanosdk compile ./xano/functions/get-user.ts  # a single function's JSON
-xanosdk routes ./xano/index.ts              # each query's verb + resolved api:<canonical>/<name> (`paths` is an alias)
+xanosdk routes ./xano/index.ts              # every route, realtime socket/channel and MCP server address (`paths` is an alias)
 
 xanosdk export ./xano/index.ts --strict     # CI: fail the build on any warning, don't just print it
 xanosdk export ./xano/index.ts --no-lock    # build with no xano.lock (one is written by default; refused once one exists)
@@ -53,8 +53,10 @@ xanosdk deploy ./xano/index.ts --ephemeral --expires-hours 8   # the ephemeral's
 xanosdk deploy ./xano/index.ts --ephemeral --keep-data --static ./frontend/dist --static-host docs   # publish to a named static host — merge only: a replace deletes it, and a deploy creates only `default` (create `docs` in the dashboard first)
 xanosdk deploy ./xano/index.ts --ephemeral --static ./frontend/dist --static-routing spa   # override URL resolution, spa|multipage (inferred from the bundle; rarely needed)
 xanosdk deploy ./xano/index.ts --keep-data  # redeploy but keep table rows (merge instead of replace; seeds aren't re-written)
+xanosdk env pull --from workspace   # fill xano/.env from a running backend (default: last deployed); lists what changes and confirms over an existing file (--yes off a terminal)
 xanosdk env set STRIPE_KEY --to workspace --yes   # set ONE env var on a running backend, value piped on stdin (no deploy; never printed)
 xanosdk env unset STRIPE_KEY --to local # clear one (--to workspace|ephemeral[:<name>]|local[:<name>]|tenant:<name>, default: last deployed)
+xanosdk secrets fill                        # mint a token in xano/.secrets.json for every documentation gate that has none (never replaces one)
 xanosdk publish ./frontend/dist             # publish a built frontend alone — no compile, no backend import (default: last deployed)
 xanosdk publish ./frontend/dist --to ephemeral   # …or onto an ephemeral instead (after a local deploy, bare publish goes to the engine)
 xanosdk deploy ./xano/index.ts --static ./frontend/dist   # on the Xano Engine, the engine serves the build at http://<prefix>.localhost:<port>
@@ -117,6 +119,7 @@ xanosdk ephemeral export <name> --format multidoc --path -          # …stream
 xanosdk workspace details                   # which workspace your token is scoped to (instance, id, name)
 xanosdk workspace export --path ws.json     # your REAL workspace as a JSON bundle (`--path -` streams to stdout)
 xanosdk workspace diff ./xano/index.ts --branch staging   # did my release land? which objects on the branch differ from your compile, are missing, or are unexpected (default: live), and which side changed each since the last sync (`changedThere`/`changedHere`/`changedBoth`); exits 2 when anything declared differs or is missing
+xanosdk workspace reset-tables ./xano/index.ts --table <guid> --write   # put named tables back to the seed rows your project compiles (a dry run without --write; every other table is left alone)
 xanosdk workspace branch list               # its branches, and which one is live
 xanosdk workspace branch set-live staging   # promote a branch (also the way back after --backup-branch)
 xanosdk workspace branch delete staging --yes   # remove a non-live branch (a label padded with spaces is found by the trimmed one; one not there exits 0, alreadyGone; the live branch exits 2, SDK_BRANCH_LIVE)
@@ -193,28 +196,31 @@ or needs `--yes` off a terminal; an ephemeral or Xano Engine never asks.
 
 ## Bundle key names vs. the names everything else uses
 
-A bundle's `payload` arrays are keyed by the engine's **storage** name, which for five kinds
-is not the name the SDK, the CLI, or a release plan uses for the same thing. Scripting against
-a bundle means translating:
+A bundle's `payload` arrays are keyed by the engine's **storage** name, which for eight kinds
+is not the name you author it with or the name the CLI prints for it. Scripting against a
+bundle means translating:
 
-| You author / the plan reports | `payload` array |
+| You author / the CLI prints | `payload` array |
 |---|---|
 | `table` | `payload.dbo` |
-| `api_group` | `payload.app` |
+| `apiGroup` | `payload.app` |
+| `workflowTest` | `payload.workflow_test` |
+| `realtimeServer` | `payload.realtime_server` |
+| `realtimeChannel` | `payload.channel` |
+| `realtimeMessage` | `payload.message` |
 | `agent` | `payload.toolset` |
-| `mcp_server` | `payload.toolset` |
-| `toolset` | `payload.tool` |
-| `realtime_channel` | `payload.channel` |
-| `realtime_message` | `payload.message` |
+| `mcpServer` | `payload.toolset` |
 
-Everything else (`query`, `function`, `task`, `trigger`, `middleware`, `microservice`,
-`addon`, `workflow_test`, `workspace`) is keyed the same on both sides.
+A trigger is printed as the factory that authored it (`tableTrigger`, `realtimeTrigger`, …)
+and stored in `payload.trigger`; `workspaceConfig` is stored in `payload.workspace`.
+Everything else (`query`, `function`, `task`, `middleware`, `microservice`, `addon`, `tool`,
+`knowledge`, `prompt`, `resource`) is keyed the same on both sides. CLI input accepts either
+spelling.
 
-Two traps worth naming. A release plan reports operations as `{"type": "table", …}` while the
-bundle it came from stores that object under `payload.dbo` — so a table that released
-correctly looks *missing* if you go looking for `payload.table`. And `agent` and `mcp_server`
-both land in `payload.toolset`, while the kind actually named `toolset` lands in
-`payload.tool`; matching on the word alone will pick the wrong array.
+The trap worth naming: `agent` and `mcpServer` both land in `payload.toolset`, told apart
+only by each row's `type`, while a `tool` lands in `payload.tool`; matching on the word
+"toolset" alone picks the wrong array. A file format keeps the stored spelling too, so a
+`xano.lock` key is `dbo:users`, not `table:users`.
 
 This is also the format `xanosdk lock import` reads, so both directions are user-facing.
 
@@ -461,9 +467,13 @@ import { emitBundle } from "@xano/sdk";        // pure string — browser-safe
 import { writeBundle } from "@xano/sdk/node";  // writes a file — Node only
 ```
 
-**Four entry points, and only the first is the authoring API.** `@xano/sdk` is what you
+**Several entry points, and only the first is the authoring API.** `@xano/sdk` is what you
 define a workspace with; `@xano/sdk/node` adds the filesystem half; `@xano/sdk/codegen`
-is what a generated tree imports; and `@xano/sdk/internal` holds the compiler machinery —
+is what a generated tree imports; `@xano/sdk/bundle` reads a compiled bundle back
+([Reading a compiled bundle](bundle.md)); `@xano/sdk/scaffold` is the theme and framework choices
+`init` accepts, as data; `@xano/sdk/plugin` is the contract a toolchain module compiles against; `@xano/sdk/sveltekit` is the SvelteKit adapter;
+`@xano/sdk/lambda-globals` types the globals a lambda body sees; and `@xano/sdk/internal`
+holds the compiler machinery —
 the per-kind encoders, the kind and statement registries, the bundle serializer, the
 `xano.lock` model. Nothing on `/internal` is needed to author anything, and it is kept off
 the root so an agent scanning the package's exports sees the surface rather than the guts.

package/guides/codegen.md

@@ -20,8 +20,9 @@ or a bundle path. Unlike most commands it has no default: a pull names its sourc
 
 Everything else about the project is unchanged: `--framework` (`react`, `svelte` or `none`), the
 theme flags, `--no-agents-md` and `--web` mean the same thing here as they do without `--from`.
-The three flags that describe the pull itself — `--report`, `--skip-roundtrip` and `--branch` —
-are refused without it rather than silently ignored.
+The flags that describe the pull itself — `--report`, `--skip-roundtrip`, `--branch`,
+`--no-secrets` and `--origin` — are refused without it rather than silently ignored, as is
+`--yes` without `--from` or `--force`.
 
 The target directory decides what is written around `xano/`, as it does for a plain
 [`init`](scaffold.md#no-frontend-and-existing-apps):

package/guides/codes.md

@@ -229,10 +229,10 @@ Printed as `! …` on stderr, and as `{ code, message }` in a `--json` document'
 | `release.seed-rows-not-decoded` | … carries seed rows for …, and a decoded tree carries no rows — they are not in …/. |
 | `release.transfer-cancelled` | Transfer cancelled — nothing was imported. |
 | `routes.cli-skew` | This CLI is another version than the project's installed SDK, so it left the route table for the installed CLI to render. |
-| `routes.mcp-unresolved` | …: leaving out … — … — whose canonical URL token resolves nowhere. |
+| `routes.mcp-unresolved` | An MCP server whose canonical URL token resolves nowhere is left out of the route table (or listing). |
 | `routes.module-failed` | A toolchain module could not generate its section of `routes.gen.ts`; the rest was refreshed and its previous block, if any, was kept. |
 | `routes.not-written` | The route table (`routes.gen.ts`) was not written this run; the line says why and what writes it. |
-| `routes.realtime-unresolved` | …: leaving out … — … — whose canonical URL token resolves nowhere, along with their channels. |
+| `routes.realtime-unresolved` | A realtime server whose canonical URL token resolves nowhere is left out of the route table (or listing), along with its channels. |
 | `secrets.cleartext-export` | … carries … in cleartext — written owner-only (0600); do not commit it. |
 | `secrets.cleartext-stdout` | The export carries … in cleartext — written to stdout, where no file permission protects it; do not commit or log it. |
 | `secrets.doc-token-written` | Documentation tokens: wrote … to `…` — …. |

package/guides/coverage.md

@@ -40,7 +40,7 @@ runtime (Xano SDK only compiles), and generating engine-side numeric ids/timesta
 
 **Deferred (by design)** — folder auto-discovery, and the `service` / `vault` / `branch`
 payload sections. (Round-trip decompile is no longer deferred: that is
-`xanosdk init --from`, in the [CLI guide](cli.md); nor is `workflow_test` — it is a
+`xanosdk init --from`, in [Pulling an existing workspace](codegen.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`,
@@ -59,8 +59,9 @@ can learn the SDK without reading source:
   --help` and the `cli` array in `manifest.json` do, from the same registry that generates
   the shell completions. The written version is the [CLI guide](cli.md).
 - **`llms/*.md`** — one file per surface (object def shapes, statements, values, fields,
-  filters, lambda bodies, what a client pays to import a def, an index of exact error
-  strings, and the legacy names a pulled workspace carries), read only when that surface
+  filters, lambda bodies, triggers, saved tests, the lock file, toolchain modules, what a
+  client pays to import a def, an index of exact error strings, and the legacy names a
+  pulled workspace carries), read only when that surface
   is in play. **`llms-full.txt`** is all
   of them concatenated, for a reader that wants one file rather than two.
 - **`manifest.json`** — the exhaustive reference tier, reached by targeted lookup (grep or

package/guides/deploying.md

@@ -127,7 +127,7 @@ as JSON, while the human-readable progress (and the live URLs) echoes to stderr:
 }
 ```
 
-Present only when they apply: `localEngine` (in place of `ephemeral`), `keepDataSkipped` and the
+Present only when they apply: `engine` (in place of `ephemeral`), `keepDataSkipped` and the
 merge lists (see [Keeping your data between deploys](#keeping-your-data-between-deploys)),
 `static` (`url`; `canonical`, the build's identity, and `verified` when the frontend was
 confirmed live serving it; `staticEnv` — `{ injected, keys, documents, skipped?, reason? }` — when config was
@@ -529,7 +529,6 @@ and `omittedInsertsFail` / `setInsertsFail` when inserts fail; see below),
 `notNullKept`, `pairedColumns` (`{ table, dropped, added }`: a drop beside an add, not a rename),
 `narrowedEnums` (`{ table, column, removed }`), `retargetedRefs` (`{ table, column, from, to }`),
 `indexChanges` (`{ table, index, action, unique }`), `notNullTightened` (`{ table, column, type }`),
-`storageChanges` (`{ table, from, to }`: the table's `useXdo` before and after),
 `removed`, `unseededTables` (new tables whose seed rows the merge did not
 write), `renamedTables` (each `{ from, to }`: renamed through `xanosdk lock rename`, rows kept),
 `unchangedEnv` and `canonicalChanges` (each `{ kind, name, from, to }`: a public URL slug a
@@ -599,9 +598,12 @@ the environment keeps its data. Each refusal is exit 2 and names its remedy:
   refused for every table, empty or seeded — the instance cannot convert a table back to JSON
   storage, and nothing is sent. A `deploy --replace` rebuilds the tables, so it switches either way.
 
-A keep-data refusal's `details` carries `refused` (the reason, a string), `conflicts`, `renames`
+A keep-data refusal's `details` carries `refused` (the reason, a string). For `identityConflict`,
+`renamePending`, `pruneOutOfScope` and `uniqueViolation` it also carries `conflicts`, `renames`
 and `outOfScope` (each a list, empty when it does not apply), `serverCode` when the environment
-itself refused, and `warnings` when the run had some. A `--keep-data` deploy never falls back to a replace.
+itself refused, and `warnings` when the run had some. The others carry `landed: false` and their
+own list: `tableTrigger` names `triggers`, `storageModeChange` names `tables`, and
+`importInProgress` carries `serverCode` and, when there is one, `rerun`. A `--keep-data` deploy never falls back to a replace.
 
 Another import already running on the instance is not a refusal of the project: any deploy
 (`--keep-data`, a replace, `--to`) exits 8 with `SDK_IMPORT_REFUSED`, `details.refused:
@@ -664,7 +666,8 @@ answering its result and logs. It never changes a primitive: tables, endpoints,
 every other object change in `xano/` and ship with `xanosdk deploy`.
 
 `xanosdk init` connects Claude Code (`.mcp.json`) and Cursor (`.cursor/mcp.json`) to it with one
-server, `xano-local`, that launches a bridge:
+server, `xano-local`, that launches a bridge. This is the Claude Code `.mcp.json` entry; Cursor's
+appends `--project ${workspaceFolder}`, since Cursor does not promise to launch it inside the project:
 
 ```json
 { "mcpServers": { "xano-local": { "command": "npx", "args": ["--yes", "--package", "@xano/sdk", "xanosdk", "local", "mcp", "--stdio"] } } }
@@ -777,7 +780,7 @@ pin for your own runs instead of editing `package.json`:
 
 - `--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.
+  `npm run xano:deploy`, which names no engine.
 
 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
@@ -1148,6 +1151,7 @@ publishes beside the merge, but not under `--dry-run`; `--skip-liveness` needs `
 | `--backup-branch[=<label>]` | Snapshot the live branch's logic first. Switching back restores logic only — see below. |
 | `--allow-shared-schema-changes` | Proceed even though table and microservice changes reach every branch. |
 | `--allow-branch-deletion` | Proceed even though `--replace` permanently deletes the workspace's other branches. |
+| `--overwrite` | Deploy over objects changed in Xano since the last deploy or pull, instead of refusing with `SDK_WORKSPACE_CHANGED`. See below. |
 
 #### `--replace` clears by workspace, not by branch
 
@@ -1359,7 +1363,7 @@ xanosdk workspace branch set-live staging    # promote when you are happy
 ```
 
 A promote **always** lands on a branch, named or not: without `--branch` the label is derived
-from the release and the moment (`v1-20260910T200511Z`), and the run prints it. There is no
+from the release and the moment (`v1-20260910T200511Z-3f2a`, four random hex digits last), and the run prints it. There is no
 unnamed landing — a branch the engine leaves unlabelled cannot be selected, promoted or
 deleted afterwards, so the CLI names it rather than letting that happen.
 
@@ -1445,10 +1449,13 @@ either way, and `dryRun` says which it was:
 | `renamedTables`, `droppedColumns`, `retypedColumns`, `narrowedEnums`, `retargetedRefs`, `indexChanges`, `notNullKept`, `notNullTightened`, `storageChanges` | the table effects (see [What a landing does to tables](#what-a-landing-does-to-tables)); `tenant deploy` and `promote` carry the same keys, plus `droppedTables` (`{ table, rows }`), under `tableEffects`. |
 | `unchangedEnv`, `droppedEnv`, `unappliedDocumentation`, `workspaceRename` | the rest of what the plan cannot say. |
 | `workspaceSettingsNotApplied` | workspace settings a `--branch` landing held back (`[]` otherwise). |
+| `syncBaseline` | always present: the sync baseline recorded for the branch it landed on — `null` on a dry run, for a tenant or ephemeral, and when there is no `xano.lock`. |
 
-Present only when they apply: `branchDeletion`, `unnamedPublicUrls`, `staticRemoved`, and on a
-real run `setLive` and `sharedSchemaChanges` (with `--branch`), `backupBranch`, `liveRestored`
-and `static`.
+Present only when they apply: `branchDeletion`, `unnamedPublicUrls`, `staticRemoved`,
+`sharedSchemaChanges` (with `--branch`), on a dry run `seedRows` (under `--seed`: each table's
+seed rows and how many overwrite a live row) and `changedInXano` (objects changed in Xano that the
+real run would refuse to overwrite without `--overwrite`), and on a real run `setLive` (with
+`--branch`), `backupBranch`, `liveRestored` and `static`.
 
 The comparison is deliberately one-sided: a false "changed" costs one import that was
 happening anyway, while a false "unchanged" would silently skip a real release. So anything

package/guides/environment.md

@@ -23,13 +23,13 @@ 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. An origin only (`https://host`): a path, query or fragment is refused. |
 | `XANO_NO_BROWSER` | Set to anything non-empty and `xanosdk 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 `xanosdk login --paste` instead. |
 
-**`xanosdk preflight`** — its own target, deliberately separate from the deploy login
+**`xanosdk preflight`** — an optional override target. With none of these set, `preflight` uses the stored login credential and creates its ephemeral under the workspace that credential pins
 
 | Variable | What it does |
 |---|---|
-| `XANO_VALIDATE_INSTANCE` | Base URL of the instance to validate against (`https://your-instance.xano.io`, or `http://localhost:8080` for local Docker). Required; `--instance <url>` overrides it. |
-| `XANO_VALIDATE_TOKEN` | Meta API bearer token for that instance. Required. |
-| `XANO_VALIDATE_WORKSPACE_ID` | Parent workspace the run's throwaway environment is created under. Defaults to `1`. |
+| `XANO_VALIDATE_INSTANCE` | Base URL of the instance to validate against (`https://your-instance.xano.io`, or `http://localhost:8080` for local Docker). Optional; when any `XANO_VALIDATE_*` is set (or `--instance <url>`, which overrides it) the pair takes over from the login, and both must then be present. |
+| `XANO_VALIDATE_TOKEN` | Meta API bearer token for that instance. Required once the override is in use. |
+| `XANO_VALIDATE_WORKSPACE_ID` | Parent workspace the run's throwaway environment is created under, when the override is in use. Defaults to `1`. |
 
 **Output & diagnostics**
 
@@ -95,7 +95,7 @@ checked-out project never holds a secret it did not fetch on purpose.
 
 | Path | What it is |
 |---|---|
-| `xano/.env` | Where the values live. Gitignored by the scaffold, and preserved across a `xanosdk pull` rather than rewritten. Read with no flag by the commands that compile a bundle: `deploy`, `export`, `preflight`, and `release create` when its optional `--bundle` comparison compiles one. |
+| `xano/.env` | Where the values live. Gitignored by the scaffold, and preserved across a `xanosdk pull` rather than rewritten. Read with no flag by the commands that compile a bundle: `deploy`, `export`, `preflight`, and `release create`, whose convergence comparison compiles the entry unless `--bundle` names one. |
 | `xano/.env.example` | Generated beside it, listing the declared names as commented lines. Committed. Copy it to `xano/.env` on a fresh clone and fill in the values. The lines stay commented on purpose, so an unedited copy meets the refusal below rather than sending empty strings to your backend. |
 
 `xano/` is the scaffold's backend directory. The file is read from the directory of the
@@ -165,7 +165,7 @@ update it too if the change should outlive the next deploy.
 | `--env-var KEY=VALUE` | One value, for this process only. Never written to `xano/.env`, never printed back. Repeatable. Highest precedence: it beats whichever file supplied values, the default `xano/.env` or an explicit `--backend-env-file`. On `export` the value is still compiled into the bundle that command writes. A secret on the command line also lands in shell history and the process table, so prefer `--backend-env-file` in CI. |
 | `--backend-env-file <path>` | Read values from this dotenv-style file **instead of** `xano/.env`. It replaces the default rather than layering over it, so pointing at a CI secret mount cannot also ship a developer's local file. The flip side: a name that only `xano/.env` had is now unsupplied. |
 | `--allow-empty-env=NAME[,NAME]` | Send these declared names empty on purpose, **clearing whatever the target holds for them**. Per-name only; there is deliberately no bare form. |
-| `--allow-empty-doc-token=NAME[,NAME]` | The same, for a documentation token — but it **opens** something: the target's doc-site gate is cleared and those docs become publicly readable. Per-name only, no bare form. |
+| `--allow-empty-doc-token=<scope>` | The same, for a documentation token — but it **opens** something: the target's doc-site gate is cleared and those docs become publicly readable. The scope is `workspace` or an API group's name; it is not comma-split, so repeat the flag for more than one. No bare form. |
 
 **A deploy replaces the workspace's env set.** So a declared name left empty in the config
 that no file and no flag supplies would clear the live value, and `deploy` refuses instead,
@@ -287,9 +287,9 @@ a rename, or to adopt an existing workspace object into code.
 **`xano.lock`** freezes the whole workspace's identities at once — every auto-derived guid,
 plus the `canonical` URL tokens of API groups and toolsets (which the engine otherwise
 randomizes, giving the same code different public URLs per environment). Every command that
-compiles an entry file writes it — `export`, `deploy`, `release`, `preflight`, with no flag —
+compiles an entry file writes it — `export`, `deploy`, `preflight`, with no flag —
 and updates it on every build, atomically, before the bundle. **Commit it next to your code.**
-`npm run xano:check` is the CI guard (`xanosdk export ./xano/index.ts --check --strict`, which implies
+`npm run xano:check` is the CI guard (the `routes --strict` freshness check, then the project typecheck, then `xanosdk export ./xano/index.ts --check --strict`, which implies
 `--frozen-lock`, writes nothing, and needs neither `xano/.env` nor `xano/.secrets.json`): it fails rather than change the lock,
 so an uncommitted identity change is caught in review instead of on a deploy. It also fails
 while the lock carries an entry no exported object matches. That entry is how a rename looks
@@ -333,7 +333,7 @@ explicitly with `--lock=<path>`.
 Precedence at emit is always **explicit in-code value → lock entry → name derivation**.
 
 **When the lock is actually load-bearing.** Because the default derivation is deterministic
-— `md5("<type>:<name>")`, and `md5("query:<group>|<verb>|<name>")` for a query — a project
+— `md5("<payloadKey>:<name>")` (the bundle's payload key: `dbo` for a table, `toolset` for an agent or MCP server), and `md5("query:<group>|<verb>|<name>")` for a query — a project
 that created all of its own objects can regenerate a
 byte-identical lock from its own source. Delete that lock, release again, and the same guids
 come back: the objects match and update in place. For that project the lock is a *cache*, and
@@ -375,7 +375,7 @@ xanosdk lock rename --entry=xano/index.ts table stock goods    # moves stock's i
 xanosdk lock prune --identity-only --yes table:stock --lock=xano/xano.lock   # or just drop it
 ```
 
-`rename`/`adopt` take no entry file, so on their own they look for `xano.lock` in the
+`rename`/`import` take no entry file, so on their own they look for `xano.lock` in the
 **current directory**. Pass `--entry=<path>` to derive it beside the entry the way
 `export`/`deploy`/`prune` do, or `--lock=<path>` to name the file outright. They never
 reach for a lock you did not point them at — when they spot one next door they say so and
@@ -392,8 +392,8 @@ real engine `packageExport`, capturing the live workspace's random guids by `(ty
 so code takes over an existing workspace and the first sync updates in place instead of
 duplicating.
 
-**CI** — `xanosdk export ./xano/index.ts --check --strict` (the scaffolded `npm run xano:check`) runs every
-check an export runs and writes nothing, so it needs no secrets. It implies `--frozen-lock`, which
+**CI** — the scaffolded `npm run xano:check` runs the `routes --strict` freshness check, the project typecheck, and
+`xanosdk export ./xano/index.ts --check --strict`, which runs every check an export runs and writes nothing, so it needs no secrets. It implies `--frozen-lock`, which
 fails instead of changing the lock, so a canonical
 minted in a throwaway container can never silently diverge public URLs. Mint locally, commit
 the lock. It fails on an entry no exported object matches too, which is the state a rename

package/guides/marketplace.md

@@ -48,7 +48,11 @@ is compiled or a workspace is checked.
 
 ```
 ✓ Installed @xano-sdk/auth.
-  Import it in your backend (`xano/index.ts`) and register it onto your workspace.
+  Not registered yet.
+  Add to xano/index.ts:
+    import { registerAuth } from "@xano-sdk/auth";
+    registerAuth(app, { canonical: "authn" });
+  Then run `npx xanosdk export ./xano/index.ts --out /dev/null && npm run xano:routes` to bring xano.lock and the route manifest up to date.
 ```
 
 ```
@@ -116,7 +120,7 @@ The rendering has a fixed shape, filled from the module's own catalogue record:
 ```
 
 The `Installs` rows carry one of `table`, `endpoint`, `function`, `task`, `trigger`, `agent`,
-`mcp`, `middleware`. A toolchain module lists none of them, because it puts nothing on the
+`tool`, `mcp`, `middleware`. A toolchain module lists none of them, because it puts nothing on the
 workspace.
 
 `--prompt` emits the publisher's own wiring instructions, raw and alone, written to be piped
@@ -273,6 +277,7 @@ A module also contributes lines to your `.gitattributes`, in its own marked bloc
 ```
 # xanosdk:begin @xano-sdk/xanoscript
 # xanosdk 1.2.0 — generated; edits inside this block are overwritten
+
 xanoscript/** linguist-generated
 # xanosdk:end @xano-sdk/xanoscript
 ```
@@ -362,10 +367,11 @@ run. A `--frozen-lock` run in that state exits 0 having verified less than it di
 and says nothing. Only the next `install`, `reinstall` or `remove` drops the stale block.
 
 The state that does fail **every** `--frozen-lock` run is the other one: a module still
-declared in `dependencies` but missing from `node_modules`, which is what `npm uninstall
---no-save`, a deleted `node_modules/<pkg>` or a drifted lockfile leaves behind. There the
-project still says the module is expected, so its absence is reported rather than assumed
-away:
+declared in `dependencies` and configured in the `"xanosdk"` block but missing from
+`node_modules`, which is what `npm uninstall --no-save`, a deleted `node_modules/<pkg>` or a
+drifted lockfile leaves behind. There the project still says the module is expected, so its
+absence is reported rather than assumed away (an unconfigured dependency that is missing is
+an ordinary package as far as the loader can tell, and is not reported):
 
 ```
 A toolchain module could not be loaded, so whatever it checks was not checked — and

package/guides/module-contract.md

@@ -128,9 +128,12 @@ your module is only correct against the SDK versions whose shapes it understands
 range out with a floor and a ceiling, as above: the ceiling is the next major, so a module
 built for 1.x loads on every 1.x SDK and is refused on 2.0.
 
-That range is **enforced at load**, on every command that discovers modules. An SDK outside it
+That range is **enforced at load**. On `export`, `deploy`, `preflight` and `init`, an SDK outside it
 is refused by name before your plugin file is imported, naming the range you asked for and the
-version it got. So the floor is the version whose shapes your hooks understand, not an
+version it got. The `routes.gen.ts` writers (`routes --emit`, the marketplace's route refresh,
+`pull`, `generate`) and the marketplace reconcile skip the module with a warning instead: it is
+never imported, a routes writer keeps its previous block, and `routes --emit --strict` still
+fails. So the floor is the version whose shapes your hooks understand, not an
 aspiration — declare it accurately and the SDK will never quietly run your module against a
 contract it was not built for. Ranges are read as `>=` / `>` / `<=` / `<` / `=` comparators,
 `^`, `~`, exact pins and `||` unions of those; a shape outside that subset is not refused, it
@@ -394,7 +397,7 @@ read than it is slow.
 | `BundleContext` | What it carries |
 |---|---|
 | `bundle.payload` | The compiled payload, keyed by payload key (`table`, `query`, `app`, ...). |
-| `entry` | The entry file the bundle came from. **Absent** on the `--bundle <path>` branch. |
+| `entry` | The entry file the bundle came from. **Absent** on the `--bundle <path>` branch, and when `deploy` fetches a remote source (`release:main`). |
 | `cwd` | The project root every relative path resolves against. |
 | `command` | `"export"` or `"deploy"`. |
 | `frozen` | The run is `--frozen-lock` (or `export --check` / `deploy --to … --dry-run`, which imply it): a verification, not a write. |
@@ -403,7 +406,7 @@ read than it is slow.
 
 **`entry` is optional rather than a made-up path** so a plugin may decline the
 `--bundle <path>` branch, where the input is already-serialized text with no entry and no
-registry behind it. A tree rendered from a bundle the project did not compile describes
+registry behind it, and a `deploy` from a fetched source, where nothing local was compiled. A tree rendered from a bundle the project did not compile describes
 something other than the source beside it.
 
 **Under `frozen` a plugin must compare and report, never write.** It is also the mode in which
@@ -470,8 +473,10 @@ const plugin: ToolchainPlugin = {
 
 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.
+`xano:routes`), `init --marketplace` when it writes the project's first manifest, `pull`,
+`generate`, and the refresh `marketplace install`, `reinstall` and `remove` make, so your
+block lands with your module. Not `init --from`: a project it creates has no module installed
+yet, and the first `xano:routes` after an install adds your section.
 
 | `RoutesManifestContext` | What it carries |
 |---|---|

package/guides/object-kinds.md

@@ -14,11 +14,14 @@ and the seven trigger factories below. Signatures and payload keys are in
 the types don't tell you.
 
 **A knowledge item's body is a file, and `mode` is a running cost.** `knowledge()` is the
-markdown a workspace's AI agents read before they act, and it is the one kind whose payload
+markdown shared by every AI that builds this backend — Xano's AI builder, people authoring in
+XanoScript, and your local coding agent, which reads the same `.md` files in the repo (deploy
+and `pull` keep them in sync). An `agent()` run never reads it; put what that agent needs in
+its `llm.systemPrompt`. It is the one kind whose payload
 is prose — so the body is named by path (`knowledgeFile("./runbook.md", import.meta.url)`)
-rather than written as a string, and `refs: knowledgeDir(...)` ships a whole folder the
-agent searches on demand — UTF-8 text files only (other content is refused), and a
-symlink is not followed. What the agent actually receives is decided by `type` and `mode`,
+rather than written as a string, and `refs: knowledgeDir(...)` ships a whole folder Xano's AI
+builder searches on demand — UTF-8 text files only (other content is refused), and a
+symlink is not followed. What the builder actually receives is decided by `type` and `mode`,
 and nothing in the types warns you: an `agents.md` item is injected in full on every turn
 whatever `mode` says, `mode: "always"` spends the body's whole length on every request, and
 the default `mode: "auto"` sends only the name and `description` until a request matches.
@@ -173,7 +176,7 @@ realtimeMessage({
   name: "send",                      // `input` types the message PAYLOAD
   channel: room,                     // the handle carries the server too
   input: { body: input.text({ required: true }) },
-  deliverTo: "channel",              // or "sender" (request/response) / "others"
+  deliverTo: "channel",              // or "sender" (request/response) / "others" / "explicit"
   stack: [s.debug.log({ value: inp("body") })],
 });
 ```