@xanots/sdk 0.0.3 → 0.0.4

package/guides/deploying.md

@@ -0,0 +1,340 @@
+# Signing in & deploying
+
+Authentication, ephemeral environments, static hosting, releasing to production, and validating against a live instance.
+
+## Signing in & deploying (in depth)
+
+**Sign in once** with `xanots login`. It runs the standard authorization-code + PKCE
+browser flow (powered by the OpenID-certified [`openid-client`](https://github.com/panva/openid-client)):
+opens your browser, you approve, and the CLI captures the redirect on a `127.0.0.1`
+callback. On first use it dynamically registers its own OAuth client (RFC 7591) so the
+authorize step never depends on the server tolerating an arbitrary loopback port; the
+registration is cached in `~/.xano/xanots-clients.json`. The instance you're bound to is
+read from the token's own `aud` claim.
+
+`login` also **pins the numeric workspace** you consented to into the credential, so every
+later command acts on exactly that workspace without looking it up again. There is **no
+`--workspace` flag** — a credential addresses exactly one instance and one workspace. Run
+`xanots workspace details` to see which.
+
+The credential caches by default in a **shared** `~/.xanots/auth.json`, reusable
+from **any** project directory — so a single `xanots login` covers all your projects.
+Override the OAuth host with `--origin`/`$XANO_ORIGIN` and the loopback port with `--port`.
+
+Running `login` again when a usable credential is already cached prints what you're
+signed in to and stops, rather than spending another browser round trip — pass `--force`
+to sign in anyway. That guard is also what keeps `login` from silently replacing a
+hand-authored `type: "token"` credential (below).
+
+**Credential formats.** `auth.json` holds one credential, discriminated by `type`:
+
+```jsonc
+// type: "oauth" — written by `xanots login`. Do not hand-edit.
+{ "type": "oauth", "instance": "https://your-instance.xano.io", "workspace_id": 3, /* …tokens… */ }
+```
+
+```jsonc
+// type: "token" — WRITE THIS YOURSELF. A meta API bearer token for the same
+// meta APIs, for automation. No login flow, no refresh, no rotation.
+{
+  "type": "token",
+  "instance_base_url": "https://your-instance.xano.io",
+  "workspace_id": 3,
+  "meta_api_token": "your-meta-api-token"
+}
+```
+
+Both formats work at **either** location (project-local `./.xano/auth.json` or global
+`~/.xanots/auth.json`) on the same precedence ladder below, and both determine the same
+thing: one instance, one workspace. A `token` credential is never created, refreshed, or
+revoked by the CLI — `xanots logout` just deletes the file, and the token itself stays
+valid until you revoke it wherever you minted it. Save it with owner-only permissions
+(`chmod 600`) and keep it out of git.
+
+> **Upgrading:** this format is a break. An `auth.json` written before it is rejected with a
+> message naming the fix — run `xanots login` again.
+
+**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
+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
+`--config`/`$XANO_CONFIG` always wins over everything.
+
+`deploy <file>` runs the exact same pipeline as `export` (including `xano.lock`
+seeding), then create-or-refreshes the target environment and imports the compiled
+workspace into it as a full replace. `deploy --bundle <path>` skips the compile and uploads a
+bundle a previous `export` wrote (handy in CI). A **projected, secret-free summary** prints to stdout
+as JSON — `baseUrl` plus the workspace `id`/`name`, and the static URL (plus a `verified`
+boolean reporting whether the frontend was confirmed live) when `--static` is used — while the
+human-readable progress (and the live URLs) echoes to stderr. The raw
+workspace blob is deliberately never dumped: it carries per-tenant secrets that must not land
+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.
+
+**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
+`/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
+it's the primary action).
+
+**Liveness verification** — the build endpoint returning `200` only means the archive was
+*accepted*; the edge may still be starting a cold host (which `503`s for tens of seconds) or
+briefly routing the previous build. So after the upload the CLI polls the deployed URL until
+the static server reports it is serving **this** build — its `X-Xano-Canonical` response header
+matches the canonical returned for the build just pushed — then prints `Frontend is live`. It
+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
+skip the wait entirely — useful for fast iterative deploys or when the deployed URL isn't
+reachable from the machine running the CLI.
+
+**Config injection** — before archiving, the deploy rewrites EVERY `.html` document in the
+build, inserting an inline `<script>` at the top of `<head>` that assigns each config value to a
+`window.<KEY>` global (so it runs before the app bundle). The backend URL is seeded
+automatically as `window.XANO_HOST` (from the backend deploy's own response), and
+`--static-env KEY=VALUE` (repeatable) merges in extra keys, overriding the seed on a name
+clash. A static host has no server runtime — it serves these files verbatim — so injected
+values are **public**: base URLs and *publishable* keys only, never secrets (those go in
+backend env, read via `env(name)`). Rewriting every document, not just the root, is what a
+prerendered build needs: it serves a different document per route, so a root-only injection
+leaves every deep link and refresh running with the global unset — and the page still renders.
+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.
+
+> **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
+> your latest deploy can hold the old HTML — including a *pre-injection* `<script>`-less
+> version — for up to an hour. If `window.XANO_HOST` looks missing, it's almost always this:
+> hard-reload (Cmd/Ctrl+Shift+R) or open DevTools with "Disable cache" checked. When
+> verifying from a script or agent, append a throwaway query param so you never read a cached
+> 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
+back**: it exits with code `3` and a resumable message telling you to re-run with `--static`
+to retry just that step.
+
+`deploy` reuses cached tokens and **refreshes them automatically** when the access token
+expires (Xano rotates the refresh token on every use; the new one is persisted). A rejected
+refresh (`invalid_grant`) clears the stale cache and tells you to `xanots login` again.
+
+**CI & agents** run non-interactively. The credential to reach for is the **meta credential
+as three environment variables** — the `type: "token"` record above, with no file:
+
+```bash
+XANO_INSTANCE_URL=https://your-instance.xano.io \
+XANO_WORKSPACE_ID=3 \
+XANO_META_TOKEN=your-meta-api-token \
+  npx xanots deploy ./xano/index.ts
+```
+
+Nothing is read from or written to disk, and nothing rotates, so the same three secrets keep
+working run after run — which is what makes this the right shape for a CI job. It **outranks
+every other credential**, including an explicit `--config` path and `$XANO_REFRESH_TOKEN`;
+whichever it displaces is named on stderr, so it never wins silently.
+
+All three are required **together**. Setting some but not others is a hard error naming the
+rest, rather than a quiet fallback to another credential — a workflow with one misspelled
+secret must not deploy against whatever happens to be on the runner.
+
+> **Automated agents:** do **not** invoke `xanots login` — it blocks on interactive browser
+> consent. Use the three variables above.
+>
+> The older `$XANO_REFRESH_TOKEN` + `$XANO_CLIENT_ID` pair still works (both copied once
+> from `auth.json` after a local `xanots login`; the target instance is read from the refresh
+> token's `aud` and the workspace resolved per run), but Xano **rotates refresh tokens on
+> 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)
+
+`xanots validate` 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:
+
+1. **Import accepts** — the engine actually accepts the bundle (malformed-but-shaped output is rejected here).
+2. **Round-trip parity** — the workspace the engine stores, re-exported in the same bundle format, matches your compiled JSON after normalization (full object logic included). Every authored kind is diffed — tables, functions, queries, triggers, tasks, and more — each object matched by identity and reported per kind.
+3. **Runtime** (`--runtime`) — each deployed function actually runs on the engine, with logs surfaced on failure.
+
+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
+routes around.
+
+It is non-destructive: nothing you own is written to. Each run creates its own
+ephemeral environment, imports into that, and deletes it afterwards — including when
+the import is rejected or a transport error is thrown. The environment carries a
+short expiry, so even a killed process leaves nothing permanent behind. A fresh
+environment per run is also what makes the diff trustworthy: the objects read back
+can only have come from this bundle, never from what a previous run left.
+
+**Setup** — copy `.env.example` to `.env` (gitignored) and fill in a base URL +
+token. Switching between a cloud dev instance and a local Docker one is just a
+different `XANO_VALIDATE_INSTANCE`:
+
+```bash
+# .env
+XANO_VALIDATE_INSTANCE=https://your-instance.xano.io   # or http://localhost:8080 for local Docker
+XANO_VALIDATE_TOKEN=your-meta-bearer-token
+# XANO_VALIDATE_WORKSPACE_ID=…                          # optional; PARENT workspace the run's env is created under (default 1)
+```
+
+```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
+```
+
+Config comes from the environment (a `.env` is autoloaded; a real env var wins),
+`--instance` overrides per run, and the token is env-only — never a flag. This
+harness is deliberately separate from the `auth.json` credential the rest of the
+CLI uses. A non-zero exit means a check failed; `--verbose` prints full diffs and raw
+engine detail instead of a projected summary.
+
+
+## Wiring the frontend to the backend
+
+**Wiring the frontend to the backend.** The deploy bakes the environment's backend URL into
+every HTML document in your build automatically, as a `window.XANO_HOST` global evaluated
+*before* your app bundle — every document, so a prerendered build's deep links and refreshes
+boot with the same backend the root does. So read it at runtime with a build-time fallback and you never have to
+know the URL ahead of time:
+
+```ts
+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.
+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;
+those belong in backend env, read server-side via `env(name)`.
+
+**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
+every assertion about the response still passes. Build the URL from `path` and the host you
+already have:
+
+```ts
+import { fileUrl } from "@xanots/sdk";
+
+<img src={fileUrl(row.avatar, HOST) ?? ""} />   // null for an absent file
+```
+
+**Verifying the injection:** the served `index.html` writes the global in **bracket
+notation** — `window["XANO_HOST"]="…";` — so grep for the bare token `XANO_HOST`, not the
+exact string `window.XANO_HOST` (the dot form is valid to *read* the global in your app,
+
+
+## Deploy targets, and what a release changes
+
+**Two targets**, so the dev loop and the production step stay distinct:
+
+| 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 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. |
+
+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.
+
+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
+your code defines and leaves the rest of the workspace — including every row in every
+table — alone.
+
+| `release` flag | What it does to your workspace |
+|---|---|
+| *(none)* | Adds new objects, updates existing ones. Nothing is deleted, no rows are written. |
+| `--dry-run` | Prints the plan and exits without sending anything. |
+| `--prune` | Also deletes objects **this project released** and no longer defines. Requires `xano.lock` — see below. |
+| `--reset-data` | Empties every table the bundle carries. |
+| `--seed` | Writes the bundle's table rows. Combine with `--reset-data` to reset **and** re-seed. |
+| `--replace` | The disposable-environment behavior: wipe the workspace and import in its place. |
+
+**An unchanged project is a no-op.** Before importing, the release compares the bundle it is
+about to send against the workspace it is about to send it to, object by object. When every
+object is already there, nothing is sent: the plan prints `no changes`, the JSON summary
+reports `"upToDate": true` with `"operations": 0`, and no `updated_at` moves. That makes
+`release` usable as a reconcile step — safe to run on a schedule, in CI on every merge, or
+behind a "make production match main" button.
+
+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
+it cannot prove equal counts as changed, and it is skipped entirely for `--replace` (which
+mints fresh identities) and for `--seed`/`--reset-data` (which write table rows, about which
+the comparison knows nothing). Under `--prune`, an object the workspace holds and the project
+no longer defines is work to do, so that is not a no-op either.
+
+Anything destructive is **previewed first** — the CLI fetches the plan, prints what would
+change, and asks. `--yes` skips the prompt for CI but never skips the preview. Start with
+`xanots release ./xano/index.ts --dry-run` to see the plan without committing to it.
+
+> ⚠️ `--prune` removes tables this project released and no longer defines, and a removed
+> table takes its rows with it — no flag prevents that. The preview reports it explicitly;
+> read it before confirming.
+
+**`--prune` is scoped to what this project released**, and `xano.lock` is what defines that
+scope: it holds an entry for every object the project has ever exported. A planned deletion
+with no lock entry is an object the project never created — a table built in the UI, another
+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
+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
+from a table schema and releasing destroys the column and every value in it. The server's
+plan calls that a routine in-place update, so the release compares your schema against the
+live workspace, names each column that would be dropped, and asks before doing it — on an
+ordinary release, with no destructive flag passed.
+
+**Environment variables are add-only on a release.** A merge creates keys that do not exist
+yet and leaves existing ones as they are, so changing a value in code and releasing will not
+change it on the workspace. The preview names any key it will decline to update. To change
+one, set it on the workspace directly, or use `--replace` (which rebuilds the workspace).
+
+A merge matches objects by the stable identity your project assigns them, so it only
+recognizes a workspace it has released to before. Releasing into one built by hand — or
+populated by `--replace`, which assigns its own — matches nothing: every object is a
+create, and with `--prune` the workspace is emptied and rebuilt rather than updated. The
+preview says so in as many words when it happens. To adopt objects that are already there,
+pin their `guid` on the matching defs first. Deploys are **authenticated over OAuth** — sign in once,
+and the CLI refreshes tokens automatically. The target instance comes from your token
+(never a stray flag), and the CLI prints what it's about to do before it touches anything.
+
+**CI & agents** run fully headless from two env vars — no browser needed:
+
+```bash
+XANO_REFRESH_TOKEN=… XANO_CLIENT_ID=… npx @xanots/sdk deploy --bundle ws.json
+```
+
+> ⚠️ 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

package/guides/environment.md

@@ -0,0 +1,132 @@
+# Environment & identity
+
+The environment variables XanoTS reads, and how `xano.lock` pins object identity across deploys.
+
+## Environment variables
+
+Every variable the CLI and SDK read. All are optional — the defaults in the right column
+are what you get when the variable is unset.
+
+**Authentication** (see [Signing in & deploying](deploying.md) for the full precedence ladder)
+
+| Variable | What it does |
+|---|---|
+| `XANO_INSTANCE_URL` | Instance origin for the meta credential (CI, agents), e.g. `https://your-instance.xano.io`. Set with `XANO_WORKSPACE_ID` + `XANO_META_TOKEN` — all three together, or none. |
+| `XANO_WORKSPACE_ID` | Numeric workspace the meta credential acts on. |
+| `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 `auth.json` after a local `xanots login`. |
+| `XANO_CONFIG` | Explicit path to the credential file. Wins over `--local` and over both default locations — the same thing `--config <path>` does. |
+| `XANO_GLOBAL_CONFIG` | Moves the **shared** credential cache off `~/.xanots/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/xanots-clients.json`. That file holds the `client_id` minted per auth host + redirect URI, not a credential. |
+| `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 once you visit the URL. For a machine that has no browser to launch, or a remote shell. |
+
+**`xanots validate`** — its own target, deliberately separate from the deploy login
+
+| 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`. |
+
+**Output & diagnostics**
+
+| Variable | What it does |
+|---|---|
+| `XANOTS_DEBUG` | Appends the untouched underlying error to a failure message, instead of only the mapped explanation. |
+| `NO_COLOR` | Suppresses ANSI color on the stderr progress output ([no-color.org](https://no-color.org)). Color is off by default whenever stderr is not a TTY. |
+| `FORCE_COLOR` | Forces color on even when stderr is not a TTY; `FORCE_COLOR=0` forces it off and beats `NO_COLOR`'s absence either way. |
+
+**Update notifier**
+
+| Variable | What it does |
+|---|---|
+| `XANOTS_NO_UPDATE_CHECK` | Turns the once-a-day "a newer version is out" notice off. |
+| `NO_UPDATE_NOTIFIER` | The de-facto convention, honored identically. `CI` being set also silences the notice. |
+| `XANOTS_INSTALL_MODE` | `global` or `local` — pins whether the notice suggests `npm i -g` or a project-local upgrade, instead of detecting it. |
+| `XANOTS_UPDATE_REGISTRY` | Registry URL the check reads, instead of the npm endpoint for `@xanots/sdk`. |
+| `XANOTS_UPDATE_CACHE` | Moves the check's cache file off `~/.xanots/update-check.json`. |
+
+**Escape hatches**
+
+| Variable | What it does |
+|---|---|
+| `XANOTS_MARKETPLACE_URL` | Base URL the `xanots marketplace` reads hit, instead of the published catalogue. Repoints the three read verbs without waiting for a release. |
+| `XANOTS_PROVE_DIFF` | A file path. Codegen appends one JSON line per statement that fell back to `raw()` — the arm that declined and the key paths where the re-encode disagreed. The decline *reason* is on the report either way; this adds the machine-readable detail. |
+
+> `process.env` read inside a **workspace definition** is a different thing entirely: it
+> resolves at export time and bakes the literal into the bundle. For a value the deployed
+> stack reads at runtime, use `workspaceConfig({ env })` + `env("NAME")`.
+
+## Identity & the xano.lock file
+
+Every top-level object carries a stable `guid` — Xano's identity anchor. On a sync import
+the engine matches an incoming object to an existing one **by guid** and updates it in
+place; no match means a new object. So re-running `export`/`deploy` on the same code maps
+cleanly onto the same workspace — **no duplicates**. By default the guid derives from the
+object's `name`; set an explicit `guid` to pin identity across a rename, or to adopt an
+existing workspace object into code.
+
+The opt-in **`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).
+Create it once with `xanots export ./xano/index.ts --lock`; from then on it's read automatically and
+updated on every export (written atomically before the bundle). **Commit it next to your
+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.
+
+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>")` — 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
+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`.
+  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.
+
+For those entries the lock is irreplaceable, and losing it means the next release matches
+nothing and creates a duplicate of every diverged object. A workspace adopted wholesale from
+the UI can be almost entirely divergent, so treat *that* lock as the critical artifact.
+Either way, commit it — the cache is worth having, and you generally will not know which
+entries have diverged without looking.
+
+**Renames** — with a lock, a rename in code no longer means delete+create on sync. The
+export warns about the orphaned entry and names the fix-up:
+
+```bash
+# code: defineFunction({ name: "signup" }) → { name: "register" }
+xanots export ./xano/index.ts             # stderr: lock entry "function:signup" matches no exported object…
+xanots lock rename --entry=xano/index.ts function signup register
+xanots export ./xano/index.ts             # emits signup's original guid under "register" → engine renames in place
+```
+
+`rename`/`adopt` 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
+stop, rather than writing a file you did not name.
+
+**After `--replace`** — a replace rebuilds the workspace with fresh engine identities, so the
+lock is stale the moment it finishes and the next ordinary release would match nothing and
+try to create everything. `xanots release ./xano/index.ts --replace` now re-pins the lock from the rebuilt
+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
+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.
+
+**CI** — `xanots export ./xano/index.ts --frozen-lock` 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.