@xano/sdk 1.0.5 → 1.0.7

package/guides/README.md

@@ -6,13 +6,13 @@ typed, so your editor's autocomplete is usually the faster lookup — tab-comple
 
 | Guide | What's in it |
 |---|---|
-| [The scaffolded project](scaffold.md) | What `xanosdk init` writes, the two frontend presets, add-ons, SvelteKit rules |
+| [The scaffolded project](scaffold.md) | What `xanosdk init` writes, the two frontend presets, no frontend, existing apps, add-ons, SvelteKit rules |
 | [Project structure](project-structure.md) | How a `xano/` project is laid out, and why registration is explicit |
 | [The marketplace](marketplace.md) | Finding add-ons, the two kinds of module, and the install/reinstall/remove lifecycle |
 | [The module contract](module-contract.md) | Building an add-on: the manifest fields, the plugin types, every hook, and what is refused |
 | [Object kinds](object-kinds.md) | Every authorable kind, and splitting a workspace across microservices |
 | [Authoring reference](authoring.md) | Tables and fields, statements, values, inputs, middleware, request history |
-| [CLI](cli.md) | Every command, shell completion, and what failures look like |
+| [CLI](cli.md) | Every command, the agent skill, shell completion, and what failures look like |
 | [Warning and error codes](codes.md) | Every code the CLI and the build emit, with what it means (generated) |
 | [Signing in & deploying](deploying.md) | Auth, ephemerals, `--static`, releasing to production, `xanosdk preflight` |
 | [Environment & identity](environment.md) | Every environment variable, and how `xano.lock` pins identity |

package/guides/cli.md

@@ -9,6 +9,8 @@ with `@xano/sdk` installed, run them as `npx xanosdk …`; anywhere else, `npx @
 ```bash
 xanosdk init my-app                         # scaffold a full project (frontend/ + xano/)
 xanosdk init my-app --framework svelte      # SvelteKit instead of the default React
+xanosdk init my-api --framework none        # a new project with the backend only (no frontend/)
+xanosdk init                                # inside an existing app: add xano/ and the xano:* scripts, no frontend (lists clashes and writes nothing; --force overwrites)
 xanosdk init my-app --no-agents-md --no-install  # skip AGENTS.md and npm install
 xanosdk init my-app --theme zinc-blue --dark toggle --icons tabler  # the look
 xanosdk init my-app --marketplace @xano-sdk/auth,@xano-sdk/vector  # install add-ons AND register them
@@ -62,6 +64,8 @@ xanosdk deploy ./xano/index.ts --local=~/Downloads/engine.tar.gz   # override: r
 XANOSDK_ENGINE_OVERRIDE=v0.1.8 npm run xano:deploy   # the same override for every deploy in the shell
 xanosdk local list                   # Xano Engines on this machine, marking the ones xanosdk started
 xanosdk local token                  # print its meta API bearer: XANO_META_TOKEN=$(xanosdk local token)
+xanosdk local mcp                    # how a coding agent connects to its MCP server (url, command, config); never the bearer
+xanosdk local mcp --stdio            # the bridge an agent's .mcp.json launches: follows restarts, brings the current bearer
 xanosdk local stop <name>            # stop one (--all: every one xanosdk started, and what a crashed one left running)
 xanosdk local update                 # move this project's pinned engine to the latest (--version <v>: that one) and restart it — commit package.json
 xanosdk local cache list             # each cached engine version, its size, and the engines running on it
@@ -112,7 +116,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); exits 2 when anything declared differs or is missing
+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 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)
@@ -133,11 +137,14 @@ xanosdk logout                              # revoke the active profile and remo
 xanosdk version                             # print the installed @xano/sdk version
 xanosdk upgrade --check                     # is a newer @xano/sdk published? exits 7 if so, 0 if current
 xanosdk upgrade                             # install it: globally (npm i -g) for a global CLI; in a project, into the block that lists it (--save-prod or --save-dev)
+xanosdk agent-skill install                 # put the xano-backend skill into each coding agent detected on this machine (--agent <id> to pick)
+xanosdk agent-skill status                  # each copy: current, stale, edited or absent
+xanosdk agent-skill uninstall               # remove the copies install wrote (an edited copy is kept)
 xanosdk help                                # grouped command reference (also the no-arg default)
 xanosdk <command> --help                    # that command's usage, subcommands, and flags (`xanosdk deploy --help`)
 xanosdk <noun> <verb> --help                # scoped to one verb (`xanosdk workspace export --help`)
 xanosdk <command> --json                    # force JSON on stdout (otherwise: whenever stdout isn't a terminal)
-xanosdk <command> --no-refresh              # don't refresh the managed block in AGENTS.md (a build that writes nothing outside its output)
+xanosdk <command> --no-refresh              # don't refresh the managed blocks in AGENTS.md and the README (a build that writes nothing outside its output)
 xanosdk completion zsh                      # shell completion script (also bash, fish) — see below
 
 xanosdk preflight ./xano/index.ts           # import into a live instance, diff each object back (needs auth + a throwaway tenant)
@@ -314,12 +321,74 @@ as `installed`. The install matches how this CLI is installed (`npm i -g` for a
 project, `--save-prod` when `@xano/sdk` is in `dependencies`, as a scaffold puts it, else
 `--save-dev`) — and for a project-local install it
 then restores the `@xano/sdk` range your project was scaffolded with (npm rewrites it to a
-caret) and restamps the managed block in your
-agent files so the guidance matches the version you now have. Set `XANOSDK_INSTALL_MODE` to
+caret) and restamps the managed blocks in your
+`AGENTS.md` and README so what they say matches the version you now have. Set `XANOSDK_INSTALL_MODE` to
 `global` or `local` to override the detection. Run through `npx` (or `pnpm dlx`, `yarn dlx`, `bunx`)
 outside a project, it installs nothing (`status: "not-installed"`): that copy is temporary,
 and `npx @xano/sdk@latest` already runs the newest release.
 
+## Adding the backend to an existing app
+
+`init` decides what to write from its target directory. An empty or missing directory is a
+**new** project: a full app, `react` unless `--framework` says otherwise, with a framework
+prompt on a terminal whose choices include "No frontend" (`--framework none`, the backend
+alone). Any other directory is an **existing** project: `init` writes `xano/` and merges the
+`xano:*` scripts and the backend's dependencies into its `package.json`, with no prompt and no
+frontend. [The scaffolded project](scaffold.md#no-frontend-and-existing-apps) lists exactly
+what each mode writes and merges.
+
+Each of these is a **clash**: an existing `xano/`, any other file `init` would write that is
+already there, and a `xano:*` script the project defines with another command. `init` lists
+every clash and writes nothing. `--force` lists what it would overwrite and asks first
+(`--yes` answers without a terminal).
+
+`--framework react` or `--framework svelte` is refused in an existing project, and the
+frontend-only flags (`--theme`, `--radius`, `--dark`, `--font`, `--font-mono`,
+`--font-heading`, `--icons`) are refused wherever no frontend is written, rather than
+silently ignored. `init --from` follows the same two modes
+([Pulling an existing workspace](codegen.md#running-it)).
+
+```bash
+xanosdk init --json   # inside the app; then run the command in `next`
+```
+
+`init --json` reports `mode` (`new` or `existing`), `files` (every file it wrote or merged
+into, relative to the project) and `next` (the command to run next: the install when one is
+still needed, then `xano:deploy`).
+
+## The agent skill
+
+`xano-backend` is an agent skill for coding agents such as Claude Code, Codex and Cursor: it
+tells the agent when to set up a Xano backend and hands it to `init`, then to the project's
+`AGENTS.md` and `llms.txt`. It is not a `knowledge()` def; those are docs your workspace's own
+AI agents read. The package ships it at `skills/xano-backend/SKILL.md`.
+
+```bash
+xanosdk agent-skill install                       # every coding agent detected on this machine
+xanosdk agent-skill install --agent claude-code   # …or name one (repeatable)
+xanosdk agent-skill install --dry-run             # report what would change, write nothing
+xanosdk agent-skill status --json                 # each copy, as data
+xanosdk agent-skill uninstall
+```
+
+It writes at most two copies. Claude Code reads `~/.claude/skills/xano-backend/SKILL.md`
+(under `$CLAUDE_CONFIG_DIR` when that is set). Codex, Cursor, Copilot, Gemini CLI, Amp and
+OpenCode read the shared `~/.agents/skills/xano-backend/SKILL.md`. An agent is detected by its
+home config directory; `--agent` takes `claude-code`, `agents` (the shared directory),
+`codex`, `cursor`, `copilot`, `gemini`, `amp` or `opencode` instead. When no agent is detected
+and none is named, `install` refuses.
+
+Each copy carries the SDK version and a digest. `status` reports a copy as **current**,
+**stale** (an older version, unedited), **edited** (changed since it was installed) or
+**absent**. `install` writes a missing or stale copy and leaves a current one unchanged; it
+leaves an edited copy alone unless `--force`. `uninstall` removes only unedited copies. A
+symlinked skill directory belongs to another installer, and neither command touches it.
+Nothing prompts, so both run unattended; `--json` reports one entry per target.
+
+The skill also installs without the CLI, from the public repository:
+`npx skills add xano-sdk/sdk`, or in Claude Code `/plugin marketplace add xano-sdk/sdk`
+followed by `/plugin install xano@xano-sdk`.
+
 ## Checking what an installed SDK can do
 
 A tool that drives the CLI, such as an editor extension or a CI step, should check that the

package/guides/codegen.md

@@ -18,10 +18,27 @@ xanosdk init my-app --from ./ws.json          # a bundle already on disk — off
 `workspace`, `ephemeral[:<name>]`, `local[:<name>]`, `tenant:<name>`, `release:<name>` —
 or a bundle path. Unlike most commands it has no default: a pull names its source.
 
-Everything else about the project is unchanged: `--framework`, 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.
+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 target directory decides what is written around `xano/`, as it does for a plain
+[`init`](scaffold.md#no-frontend-and-existing-apps):
+
+- **Empty or missing:** a new project, with the frontend `--framework` names (`none` for the
+  backend alone).
+- **A previous pull** (`xano/.xanosdk-codegen.json` is there): `xano/` is refreshed in place —
+  see [Verification, and the decode report](#verification-and-the-decode-report) below.
+- **Anything else:** an existing app, which gets the backend only. The decoded `xano/` is
+  written, and the `xano:*` scripts and the backend's dependencies are merged into its
+  `package.json`. An existing `xano/`, a file the pull would write, or a `xano:*` script with
+  another command is a clash: all of them are listed and nothing is read or written unless
+  `--force`. `--framework react|svelte` and the frontend-only flags are refused.
+
+```bash
+cd my-existing-app && npx @xano/sdk init --from workspace   # add the pulled backend to this app
+```
 
 ### Just the tree: `generate`
 
@@ -168,7 +185,8 @@ are listed), then updated from the new tree, so `export --check` passes after it
 over a `xano/` no decode wrote follows the same rules.
 
 > ⚠️ **`xano/` is your source once pulled — commit it.** A refresh overwrites the files it
-> decodes, so commit before one (a directory that isn't a previous pull still needs `--force`).
+> decodes, so commit before one (an existing `xano/` that isn't a previous pull is a clash, and
+> needs `--force`).
 > It carries schema only — no table rows or stored files.
 > `xanosdk deploy` sends it to the Xano Engine on this machine (`--ephemeral`: a disposable
 > ephemeral environment) as a *full replace*;

package/guides/codes.md

@@ -35,7 +35,7 @@ Printed as `! …` on stderr, and as `{ code, message }` in a `--json` document'
 
 | Code | Meaning |
 |---|---|
-| `agents.refresh-failed` | A managed agent file (AGENTS.md, …) could not be refreshed; the compile itself went on. |
+| `agents.refresh-failed` | A managed block (AGENTS.md, the README's Built-with footer) could not be refreshed; the compile itself went on. |
 | `agents.symlink` | … is a symlink — left it and its target untouched. |
 | `branch.deletion` | … will be permanently deleted and CANNOT be recovered: |
 | `branch.inventory-unknown` | The branch inventory could not be read, so what this wipe destroys is UNKNOWN. |
@@ -133,6 +133,7 @@ Printed as `! …` on stderr, and as `{ code, message }` in a `--json` document'
 | `logout.revoke-failed` | Did not revoke …: … The token was not sent. |
 | `logout.shared-file` | Clearing … in the shared credential file … — this affects every project that reuses it. |
 | `logout.unreadable` | Could not read … (…). |
+| `merge.symlink` | … is a symlink — left it and its target untouched. |
 | `microservice.failed` | Some microservices failed to start: |
 | `microservice.starting` | Microservices are still starting (…/… ready) — they should come up shortly: |
 | `microservice.status-unreadable` | Could not read microservice status (the backend deployed fine): |
@@ -142,7 +143,9 @@ Printed as `! …` on stderr, and as `{ code, message }` in a `--json` document'
 | `module.install-failed` | … failed — the module was not added. |
 | `module.kind-unknown` | … does not declare a module kind we recognize, so it is read as an ordinary package. |
 | `module.legacy-peer-deps` | Installed with --legacy-peer-deps: …. |
-| `module.load-failed` | Could not load …/index.ts to update what the module left behind (…). |
+| `module.load-failed` | Could not load …/index.ts to … (…). |
+| `module.peer-mismatch` | The project already declares a peer a toolchain module needs, and the installed version falls outside the module's range; it was left as it is. |
+| `module.peer-not-added` | A peer a toolchain module needs could not be added as a direct dependency; the line names the command that adds it. |
 | `module.peer-unresolved` | … declares a peer range this project does not satisfy; --legacy-peer-deps did not resolve it either. |
 | `module.removed-from-marketplace` | … has been removed from the marketplace. |
 | `module.sdk-skew` | … requires `@xano/sdk` … — the module was not added. |
@@ -224,6 +227,7 @@ 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.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. |
 | `secrets.cleartext-export` | … carries … in cleartext — written owner-only (0600); do not commit it. |
@@ -248,6 +252,7 @@ Printed as `! …` on stderr, and as `{ code, message }` in a `--json` document'
 | `static.teardown-unknown` | Could not read …'s static hosting, so this cannot say whether a frontend serves there — this replace takes down any that does. |
 | `static.unconfirmed-live` | Could not confirm the frontend is live within the wait window — the build uploaded and should come online shortly. |
 | `static.upload-failed` | The static-host upload failed — the backend deploy stands: |
+| `sync.record-failed` | The … succeeded, but its sync baseline could not be recorded in …: … |
 | `tenant.deploy-partial` | The deploy stopped partway: … release "…" declares… — answered as a NOT NULL violation, though the release makes no field required: the value converts to nul… |
 | `tenant.deploy-unconfirmed` | Compare its `deployedAt` and `deployedReleaseId` with what they were before this deploy (deployedAt …, deployedReleaseId …). |
 | `tenant.identities-unchecked` | Whether this release's names and pinned public URL slugs are free on … was not checked — …. |
@@ -309,6 +314,7 @@ Raised while a workspace compiles (`export`, `deploy`, `release`, …). A warnin
 | `field.email-default-invalid` | The `default` at … is …, which is not an email address — every insert or request that leaves the field out is refused "Invalid email format.". |
 | `field.enum-default-not-a-value` | The `default` at … is …, which is not one of the enum's values (…) — a value no request can send back. |
 | `field.input-default-invalid` | The `default` at … is …, which … — every request that leaves the input out is refused. |
+| `field.input-required-default-ignored` | The `default` at …, input "…" is …, but the input is `required: true` — the engine refuses a request that leaves a required input out ("Missing param") befor… |
 | `field.vector-not-nullable` | table "…", column "…" is a vector with `nullable: false` and no default — an empty default becomes NULL only on a nullable column, and `''` is not a vector,… |
 | `function.reserved-input-name` | function "…": the input name `…` is reserved by the engine — a call passes its arguments keyed by input name, and the engine skips a `…` key when it evaluate… |
 | `guard.role-unsatisfiable` | A guard.role on a table passed by name checks a column the table lacks, or a role its enum column cannot hold. |

package/guides/coverage.md

@@ -72,3 +72,8 @@ can learn the SDK without reading source:
 Both derive from the SDK's own sources of truth (so they can't drift), regenerate with
 `npm run manifest`, and are available at runtime via `buildManifest()` / `renderLlmsTxt()`,
 both exported from `@xano/sdk/internal`.
+
+The package also ships the `xano-backend` agent skill at `skills/xano-backend/SKILL.md`. It
+carries no reference of its own: it tells a coding agent when to set up a Xano backend, runs it
+through `init` and the first deploy, and hands it to the project's `AGENTS.md` and `llms.txt`.
+Installing it is in the [CLI guide](cli.md#the-agent-skill).

package/guides/deploying.md

@@ -652,6 +652,34 @@ re-importing the backend. One command cannot serve it and refuses it by name: `r
 | `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. |
 
+#### Connecting a coding agent
+
+The Xano Engine serves an MCP server for coding agents, and a local deploy prints where. It is
+for looking at the deployed backend (objects, table schemas, rows, run history), seeding and
+editing rows, and running functions, tasks, triggers, endpoints and tests by hand, each
+answering its result and logs. It never changes a primitive: tables, endpoints, functions and
+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:
+
+```json
+{ "mcpServers": { "xano-local": { "command": "npx", "args": ["--yes", "--package", "@xano/sdk", "xanosdk", "local", "mcp", "--stdio"] } } }
+```
+
+Nothing has to be started or installed by hand: the agent launches the server itself, using the
+project's own `@xano/sdk` when it is installed and fetching it when it is not (a fresh clone opened
+before `npm install`). The config holds no url and no token. The engine may come back on a new port after a restart and
+always mints a new bearer, so the bridge looks both up when it needs them, and again when the
+engine stops answering or refuses the bearer. Before the first deploy the server connects and
+lists no tools; once an engine is up it tells the agent its tools changed. A call cut off after
+it reached the engine is reported as unknown, never sent twice. `xanosdk local mcp` prints the
+details and each agent's config line, and `init` in an existing project adds the server beside
+the ones a config already declares. An engine too old to serve MCP says so on deploy, and
+`xanosdk local update` moves the project to one that does. Claude Code asks once before it
+starts a project's server; a Cursor version that does not pick up the tool change needs the
+`xano-local` server refreshed in its MCP settings after the first deploy.
+
 #### A frontend on the Xano Engine, and server rendering
 
 `xanosdk deploy <entry> --local --static <dir>` publishes a built frontend to the
@@ -1243,6 +1271,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/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/scaffold.md

@@ -1,27 +1,29 @@
 # The scaffolded project
 
-What `xanosdk init` writes, the two frontend presets, theming, add-ons, and the SvelteKit prerendering rules.
+What `xanosdk init` writes, the two frontend presets, a project with no frontend, adding the backend to an existing app, theming, add-ons, and the SvelteKit prerendering rules.
 
 ## init flags and add-ons
 
-`init` flags: `--framework <react|svelte>` (default: `react`), `--name <name>`
+`init` flags: `--framework <react|svelte|none>` (default: `react`; `none` writes the
+backend alone — see [No frontend, and existing apps](#no-frontend-and-existing-apps)), `--name <name>`
 (default: the folder name), `--theme <id>` / `--radius <len>` / `--dark <mode>` /
 `--font <id>` / `--font-mono <id>` / `--font-heading <id>` / `--icons <id>`
 (the look — see [Theming](#theming)), `--no-agents-md` (skip the `AGENTS.md`
 agent brief, which every coding agent reads and `init` writes by default),
 `--marketplace <pkg>` (repeatable, comma-separated; installs add-ons and
-registers them — below), `--force` (scaffold into a non-empty folder; over an
-existing project it lists the files it would overwrite and asks, `--yes` answering
-without a terminal — files it does not write are kept),
+registers them — below), `--force` (write over what clashes when adding the backend to
+a non-empty folder; it lists the files and scripts it would overwrite and asks, `--yes`
+answering without a terminal — files it does not write are kept),
 `--no-install` (skip `npm install`), `--web` (choose all of the above in a
 browser instead — see [Choosing in a browser](#choosing-in-a-browser)),
 `--from <source>` (fill `xano/` from an existing backend — any
 [backend spelling](cli.md#naming-a-backend) or a bundle path — rather than the
 starter — see [Pulling an existing workspace](codegen.md); over an existing `xano/` it lists
 what it replaces and asks, and `--yes` answers without a terminal).
-In a terminal, `init` prompts for the framework; the prompt has a default, so
-pressing enter is a valid answer. The look is never
-prompted for — it comes from the flags above, or from `--web`.
+In a terminal, `init` prompts for the framework in an empty or missing folder
+(React, Svelte, or "No frontend"); the prompt has a default, so pressing enter is a
+valid answer. A folder that already has files gets no prompt and no frontend. The look
+is never prompted for — it comes from the flags above, or from `--web`.
 The starter backend is empty but already compiles and deploys — grow it from the
 walkthrough in `xano/EXAMPLE.md`.
 
@@ -113,10 +115,59 @@ project — the mistake npm answers by silently writing to the wrong `package.js
 The package name is passed through exactly as typed, so version specifiers, tags,
 and third-party packages all work.
 
+## No frontend, and existing apps
+
+`init` reads its target directory before it writes anything. An empty or missing directory
+is a **new** project, and `--framework` decides its frontend. Any other directory is an
+**existing** project, which has its own app and gets the backend only.
+
+**A new project with `--framework none`** (or "No frontend" at the prompt) gets everything
+above except the frontend: `xano/`, a `package.json` with only the backend's scripts and
+dependencies, `.gitignore`, `.gitattributes`, the CI check, a README and `AGENTS.md`. There is
+no `frontend/` and no root `tsconfig.json`; `xano/` type-checks under its own
+`xano/tsconfig.json`, and `npm run xano:typecheck` checks it and its lambdas.
+`xano:deploy:ephemeral` deploys the backend alone, and there is no `dev`, `build` or
+`xano:deploy:frontend`.
+
+**An existing project** (any non-empty directory) gets:
+
+- `xano/`, the same starter a new project gets. When the project's `package.json` is not
+  `"type": "module"` (Next.js and `npm init -y` write one that is not), `init` also writes
+  `xano/package.json` holding only `{"type": "module"}`, so `xano/` loads as ES modules
+  without changing the project's own type.
+- The `xano:*` scripts and the backend's dependencies merged into `package.json`. The
+  project's entries win: a dependency it already has keeps its range, a script it already
+  has keeps its command, and no other key changes (an add-on's settings under `"xanosdk"`
+  aside). The file keeps its indentation and line endings. A project with no
+  `package.json` gets one holding only what the backend needs.
+- A marked block in `.gitignore` (created when missing) and in `AGENTS.md`, added or
+  refreshed in place; the rest of each file is left as it was. A symlinked `AGENTS.md` is left
+  alone, and `--no-agents-md` skips it.
+- No frontend, README, CI workflow or root `tsconfig.json`. The line-ending rule goes in
+  `xano/.gitattributes`, scoped to `xano/`, so the project's own files are not renormalized.
+
+What would be written over is a **clash**: an existing `xano/`, any other file `init` writes
+that is already there, and a `xano:*` script the project defines with a different command (the
+same command is no clash). `init` lists every clash and writes nothing; `--force` lists what it
+overwrites and asks first. A `package.json` that is not valid JSON is refused, since there is
+nothing to merge into.
+
+`--framework react` or `--framework svelte` in a non-empty directory is refused, as are the
+frontend-only flags (`--theme`, `--radius`, `--dark`, `--font`, `--font-mono`,
+`--font-heading`, `--icons`) wherever no frontend is written. After the merge, `npm run
+xano:deploy` runs the backend on the Xano Engine as it does in a new project.
+
+If the project's own root `tsconfig.json` includes every `.ts` file (Next.js's does), add
+`"xano/lambdas"` to its `exclude` before adding the first lambda: the lambda globals
+type-check only under `xano/lambdas/tsconfig.json`. `init` leaves that file alone, and the
+`AGENTS.md` it writes says the same.
+
 ## Git and CI
 
-`init` writes a `.gitattributes` and a `.github/workflows/check.yml` (`xanosdk-<dir>.yml`
-below the repository root, so moving it up never replaces another workflow).
+A new project gets a `.gitattributes` and a `.github/workflows/check.yml` (`xanosdk-<dir>.yml`
+below the repository root, so moving it up never replaces another workflow). An existing
+project gets no workflow, and its line-ending rule is scoped to `xano/`; run
+`npm run xano:check` from its own CI.
 
 The attributes file normalizes line endings, so any generated artifact the project
 commits is byte-identical on every checkout and a `--frozen-lock` check cannot fail

package/guides/typed-frontend.md

@@ -238,5 +238,42 @@ const ws = new WebSocket(socketUrl("chat", XANO_HOST), token);
 ws.send(JSON.stringify({ action: "join", channel: channelPath("rooms/{room_id}", { room_id }) }));
 ```
 
+**Request types come from the same file.** It exports four types-only maps, keyed exactly
+like the runtime tables they sit beside, so a frontend types what it sends without importing a
+def at all:
+
+| Type | Keyed by | Holds |
+|---|---|---|
+| `RouteInputs` | the `ROUTES` key (`"POST listings"`, `"v1:GET vehicles"`) | the endpoint's inputs, path params included |
+| `ChannelInputs` | the `CHANNELS` key (`"rooms/{room_id}"`) | the channel's path params |
+| `MessageInputs` | `"<channel key> <message name>"` (`"rooms/{room_id} send"`) | the message's payload |
+| `MessageName` | | every `MessageInputs` key |
+
+```ts
+import { ROUTES, routePath, type RouteInputs } from "../xano/routes.gen";
+
+type NewListing = RouteInputs["POST listings"];
+
+fetch(BASE + routePath("POST listings"), {
+  method: ROUTES["POST listings"].verb,
+  headers: { "content-type": "application/json" },
+  body: JSON.stringify({ title, price } satisfies NewListing),
+});
+```
+
+Each type agrees with `InferInput<typeof def>` for the same endpoint — required and optional
+keys, `null`, enums, nested objects and lists — so code that already imports a def can keep
+using `InferInput`. The one difference is a database-link input (`input.dbLink(table)`): the
+manifest types it as the linked table's columns, which is what the server accepts, where
+`InferInput` shows an opaque marker under the link's name. Responses are not in the manifest;
+type them with `InferResponse` on an `import type` of the def.
+
+These are types, so they add nothing to a bundle. For runtime validation, install
+`@xano-sdk/zod` (`npx xanosdk marketplace install zod`): it writes `ROUTE_SCHEMAS`,
+`CHANNEL_SCHEMAS` and `MESSAGE_SCHEMAS` into the same file under the same keys
+(`ROUTE_SCHEMAS["POST listings"].parse(body)`), each checked against its type when you
+typecheck, so a schema cannot drift from the type it validates. The file then imports `zod`,
+and still never `@xano/sdk`.
+
 Add `--strict` in CI to fail when the committed manifest is out of date. A hand-typed
 `ROUTES` table is the option that gives up both the bundle saving and the rename safety.