@xano/sdk 1.0.5 → 1.0.7

package/llms/client.md

@@ -1,6 +1,6 @@
 # Consuming defs from a client
 
-> Read when a frontend imports a def (`getPath()`/`InferResponse`) or calls the deployed backend — what the import costs, `window.XANO_HOST`, local dev, file URLs, and a Node spot-check.
+> Read when a frontend calls the deployed backend or imports a def — request types and zod schemas without the import, its cost, `window.XANO_HOST`, local dev, file URLs, a Node spot-check.
 
 Importing a def into a browser bundle or a Node script — for `getPath()`, `getUrl()`, `verb`, or `InferResponse` — runs its factory calls; these are the costs and the checks.
 
@@ -15,6 +15,16 @@ Importing a def into a browser bundle or a Node script — for `getPath()`, `get
   plain data importing NOTHING, still compile-checked: `routePath("GET blog/{slug}", { slug })`
   `channelPath("rooms/{room_id}", { room_id })`, `socketUrl("chat", baseUrl)` (tenant base
   URLs lifted to `wss://h/ws/<tenant>:<canonical>`). A rename is a type error, not a 404.
+- **Request types without the def.** `routes.gen.ts` also exports types-only `RouteInputs`,
+  `ChannelInputs`, `MessageInputs` (and `MessageName`), keyed like `ROUTES`, `CHANNELS`, and
+  `"<channel key> <message name>"`: `type NewListing = RouteInputs["POST listings"]`. A
+  frontend types bodies, channel params and payloads from these, not `InferInput` on a def;
+  keep `InferInput` in code that already imports defs. They match `InferInput`, except a
+  `dbLink` input appears as the linked table's columns (what the server accepts). Responses
+  are not in the file: `InferResponse` on an `import type` of the def.
+  Runtime validation: `xanosdk marketplace install zod` adds `@xano-sdk/zod`, which writes
+  `ROUTE_SCHEMAS`/`CHANNEL_SCHEMAS`/`MESSAGE_SCHEMAS` into the file under the same keys, each
+  checked against its type at typecheck; the file then imports `zod`, never `@xano/sdk`.
 - **Verifying a def outside a bundler.** Inside a bundler (Vite/webpack) importing a
   query def to read `getPath()`/`verb` works directly. To spot-check from Node, run a REAL
   file with `tsx <file.ts>` **from inside the project root** — not `tsx -e "import …"`

package/llms/filters.md

@@ -27,6 +27,10 @@ with `c.obj`/`c.array`. Any argument also takes a runtime value (`inp`, `ref`, a
 `withFilters` chain) — inside `obj()`/`expr()` an argument cannot carry its own filter
 chain, so compute it in a prior `set_var`. The arg types below name each argument's
 ENGINE type, not the JS type you may pass.
+`fl.add`/`fl.sub`/`fl.mul` keep an INT when both operands are ints (`2 × 3` is `6`, not
+`6.0`) and give a decimal only when either operand is one — the `decimal` return type
+below covers both, so an int pipeline needs no `fl.to_int()`. `fl.div` is an int only
+when it divides exactly.
 To add to a numeric column (counter, stock, balance), use `s.db.increment`
 (`llms/statements-data.md`) — one atomic UPDATE. A pipeline read-modify-write is NOT
 atomic (concurrent writers lose updates), and `col("clicks")` does NOT resolve to the

package/llms/kinds-core.md

@@ -25,7 +25,7 @@ to survive a rename).
     - `getPath` percent-encodes each value (so `?`/`#`/spaces stay in their segment) and throws on what encoding cannot contain: a `/`, and a segment that becomes `.`/`..` as sent (a URL parser drops those before routing, addressing a different endpoint).
     - The keys are typed from the literal `name`, so a typo is a compile error.
     - `q.toSearchParams(input)` drops GET path params (free `query.toSearchParams` keeps them); lists send `k[]=a&k[]=b` (`k=a&k=b` binds only `b`).
-  - Browser bundle cost, the `routes.gen.ts` alternative, and spot-checking a def from Node: `llms/client.md`.
+  - Browser bundle cost, the `routes.gen.ts` alternative (paths and request types), and spot-checking a def from Node: `llms/client.md`.
 - `apiGroup({ name, guid?, canonical?, description?, docs?, swagger?, apiGroupEnabled?, documentation?, cors?, middleware? })` — a query container; queries bind to it via their `apiGroup`. `canonical` holds only letters, digits, `_` and `-` (it is the `<canonical>` of `/api:<canonical>`); anything else THROWS at build.
   - `documentation?`: `{ require_token? }` — the gate on this group's hosted docs. `require_token: true` IS the declaration; the token lives in `xano/.secrets.json` under this group's guid, and a literal `token` FAILS the export. ⚠ ALWAYS emitted, present or not: an absent key is written as the engine default on import, so omitting the block CLEARS an existing gate (the opposite of the `workspaceConfig` rule). `swagger: true` publishes the docs; `require_token` gates them only alongside a non-empty token, so `swagger: true` with no gate makes the whole group readable by anyone with the URL — export warns once per build and `--strict` fails; `diagnostics: { allow: ["api-group.docs-public"] }` accepts it. A declared gate with NO token drops the block, so those bytes clear it: export FAILS under `swagger: true`, and with `swagger` off warns and completes.
   - `cors?`: `{ mode?, allowOrigins?: string[], allowHeaders?: string[], allowCredentials?, maxAge?, allowMethods?: { get?, post?, put?, patch?, delete?, head? } }`.

package/llms/statements-data.md

@@ -4,7 +4,7 @@
 
 Array blocks (an `if`/`transform` is applied per item):
 
-- `s.array.map({ source, as?, transform? })` — `transform` is either a per-item `Value` expression (each item maps to that value) or a **record of values** (each item maps to an object with those keys), or a list of `{ key, value }` pairs, for a key computed per item or two rows sharing one. Use `ref("$this")` for the item and `ref("$index")` for its position. These are THIS statement's own bindings, in a value expression — not the JavaScript lambda contract (see **Lambda bodies**), which binds a different set per surface and is written with `lam.fn`.
+- `s.array.map({ source, as?, transform? })` — `transform` is either a per-item `Value` expression (each item maps to that value) or a **record of values** (each item maps to an object with those keys), or a list of `{ key, value }` pairs, for a key computed per item or two rows sharing one. Use `ref("$this")` for the item and `ref("$index")` for its position. A `transform` value, filter arguments included, can read `ref("$this.<path>")` and any outer stack variable or input. These are THIS statement's own bindings, in a value expression — not the JavaScript lambda contract (see **Lambda bodies**), which binds a different set per surface and is written with `lam.fn`.
 - `s.array.union({ source, with, as?, transform? })` — set-union two arrays. `with` is REQUIRED; omitted → `Unable to locate input: `.
 
 DB reads/writes (`table` is a def handle or name; `fieldName` defaults to the
@@ -58,7 +58,8 @@ primary key `id`):
   - Template placeholders are Twig over the request scope: `{{ $input.name }}` for an input, `{{ $var.name }}` for a stack variable. ⚠ A BARE `{{ name }}` renders as the empty string — HTTP 200, no error, a query that silently ran with a blank where the value belonged. A bound `?` arg carries a VALUE without the template at all.
   - ⚠ A table's PHYSICAL name is **not stable across deploys**. A deploy is a full replace, so every table is created afresh and the id in its name moves every time — the same unchanged project redeployed three times gave one table three different names. Never store, cache, hardcode or fixture one: resolve it from `information_schema` inside the same request that uses it.
 - `s.db.external.<engine>.direct_query({ sql, connectionString, responseType?, args?, parser?, as? })` — same shape against an EXTERNAL database; `<engine>` is `postgres`/`mysql`/`mssql`/`oracle`/`snowflake`. `connectionString` is a `Value` — reach for `env(...)`, not a literal — stored as `context.connection_string_flex`. A bare string stores the older `context.connection_string` instead (an env-var name unless it looks like a URL); each form round-trips as itself.
-- `s.db.transaction({ body, as? })` — run a `Statement[]` atomically. `as` binds whatever the block returned.
+- `s.db.transaction({ body })` — run a `Statement[]` atomically. It returns nothing, so it takes no `as`: read what the body binds. An `s.return` in the body ends the WHOLE stack with that value, and the writes before it commit.
+  - The body shares the enclosing stack: a variable it binds (`as: "order"` on an `s.db.add`) is still bound AFTER the transaction.
 - `s.db.bulk.add({ table, items, allowIdField?, as? })` / `s.db.bulk.update` / `s.db.bulk.patch` — `items` is an array `Value`.
   - ⚠ `bulk.add` **drops `id` on every row unless `allowIdField: true`** (silently, next sequence value instead) — the opposite of `seed`, where `id` pins. Rows referenced by a foreign key need `allowIdField: true`; literal `items` carrying `id` without it throw. `bulk.update`/`patch` keep `id` (their match key).
   - ⚠ **`bulk.update` is a whole-row REPLACE: every column an item OMITS is zeroed** (`""`/`0`/`null`), HTTP 200, no error — `{ id: 7, status: "done" }` blanks the rest of row 7. **Use `s.db.bulk.patch`** for the partial write "update these rows" means. `export()` warns on a STATIC `items` missing columns (`--strict` fails); a `ref`/`inp` `items` is uninspectable.

package/llms/toolchain.md

@@ -14,3 +14,15 @@ shipped defaults. `marketplace reinstall <pkg>` re-asks with the current setting
 defaults and re-enables a disabled one; `marketplace remove <pkg>` drops block, lines and
 dependency together — a plain `npm uninstall` leaves the block, and a package it names
 that is no longer installed fails every `--frozen-lock` run.
+
+**A module's section of `xano/routes.gen.ts`.** A module with a `routesManifest` hook (types:
+`@xano/sdk/plugin`) writes a block between `// xanosdk:begin <pkg>` and `// xanosdk:end <pkg>`
+after the core sections, on every write of the file (`routes --emit`, `xano:routes`, `pull`,
+`generate`, `marketplace install|reinstall|remove`). Edits inside the block are overwritten.
+Install also adds the module's non-SDK peers (e.g. `zod`) as direct dependencies.
+The hook is synchronous and pure: given
+the request inputs under the manifest's keys and its config, it returns `{ imports?, source }`,
+imports as bare package names (`@xano/sdk*`, relative and `node:` are refused). A module that
+fails to load or throws leaves its previous block as it was, with a warning naming it, and the
+core sections still refresh; under `routes --emit --strict` it is fatal. `@xano-sdk/zod`
+(`xanosdk marketplace install zod`) is one: it adds `ROUTE_SCHEMAS` and its siblings.

package/llms-full.txt

@@ -1,4 +1,4 @@
-# xanosdk v1.0.5
+# xanosdk v1.0.7
 
 > TypeScript SDK that compiles a typed Xano workspace into the importable packageExport JSON bundle.
 
@@ -39,7 +39,7 @@ plain file read resolves them at the version you have.
 
 - [Object kinds](llms/object-kinds.md): Read when deciding WHAT to build — every authorable primitive, what each is, and which factory + register method builds it. Also when `register*` will not typecheck an array built by `.flatMap()`/`.concat()`.
 - [Core def shapes](llms/kinds-core.md): Read when authoring a function, query, api group, task, workflow test, middleware, tool, or addon — and for the `response` and `expr` shapes every one of them uses.
-- [Consuming defs from a client](llms/client.md): Read when a frontend imports a def (`getPath()`/`InferResponse`) or calls the deployed backend — what the import costs, `window.XANO_HOST`, local dev, file URLs, and a Node spot-check.
+- [Consuming defs from a client](llms/client.md): Read when a frontend calls the deployed backend or imports a def — request types and zod schemas without the import, its cost, `window.XANO_HOST`, local dev, file URLs, a Node spot-check.
 - [Toolchain modules](llms/toolchain.md): Read when `package.json` has a `"xanosdk"` block or you run `xanosdk marketplace`.
 - [Error index](llms/errors.md): Read when a request, test, build, or pull fails with a message you did not write — the string, its cause, and where the fix is.
 - [Saved unit tests, assertions, and mocks](llms/tests.md): Read when authoring a `workflowTest()` stack, when a query/function/middleware carries `tests`, when a statement needs a `mock`, or when running a deployed environment's tests.
@@ -436,7 +436,7 @@ Non-obvious authoring rules:
   checked only by the `xanosdk export`/`deploy` CLI path. Only `deploy` ships seed rows.
   - Entry points: the `node:fs` writers (`writeBundle`/`writeArtifact`) and lock-file I/O
     import from `@xano/sdk/node`, NOT the browser-safe `@xano/sdk` entry (a frontend
-    imports defs from it for `getPath()`/`InferInput`). `@xano/sdk/internal` is the
+    imports from it; request types come from `routes.gen.ts`). `@xano/sdk/internal` is the
     compiler machinery, never needed to author. READING a bundle back is `@xano/sdk/bundle`
     — a statement walker (`2.if.0` paths), a structural hash, `mvp:*` catalog, `tableRefOf`.
 - **Intra-workspace imports use `.js` specifiers** (`../tables/links.js`), not
@@ -554,7 +554,7 @@ to survive a rename).
     - `getPath` percent-encodes each value (so `?`/`#`/spaces stay in their segment) and throws on what encoding cannot contain: a `/`, and a segment that becomes `.`/`..` as sent (a URL parser drops those before routing, addressing a different endpoint).
     - The keys are typed from the literal `name`, so a typo is a compile error.
     - `q.toSearchParams(input)` drops GET path params (free `query.toSearchParams` keeps them); lists send `k[]=a&k[]=b` (`k=a&k=b` binds only `b`).
-  - Browser bundle cost, the `routes.gen.ts` alternative, and spot-checking a def from Node: `llms/client.md`.
+  - Browser bundle cost, the `routes.gen.ts` alternative (paths and request types), and spot-checking a def from Node: `llms/client.md`.
 - `apiGroup({ name, guid?, canonical?, description?, docs?, swagger?, apiGroupEnabled?, documentation?, cors?, middleware? })` — a query container; queries bind to it via their `apiGroup`. `canonical` holds only letters, digits, `_` and `-` (it is the `<canonical>` of `/api:<canonical>`); anything else THROWS at build.
   - `documentation?`: `{ require_token? }` — the gate on this group's hosted docs. `require_token: true` IS the declaration; the token lives in `xano/.secrets.json` under this group's guid, and a literal `token` FAILS the export. ⚠ ALWAYS emitted, present or not: an absent key is written as the engine default on import, so omitting the block CLEARS an existing gate (the opposite of the `workspaceConfig` rule). `swagger: true` publishes the docs; `require_token` gates them only alongside a non-empty token, so `swagger: true` with no gate makes the whole group readable by anyone with the URL — export warns once per build and `--strict` fails; `diagnostics: { allow: ["api-group.docs-public"] }` accepts it. A declared gate with NO token drops the block, so those bytes clear it: export FAILS under `swagger: true`, and with `swagger` off warns and completes.
   - `cors?`: `{ mode?, allowOrigins?: string[], allowHeaders?: string[], allowCredentials?, maxAge?, allowMethods?: { get?, post?, put?, patch?, delete?, head? } }`.
@@ -630,7 +630,7 @@ surface — `s.conditional`/`s.while` `when` (incl. each `elif` branch), and
 
 # Consuming defs from a client
 
-> Read when a frontend imports a def (`getPath()`/`InferResponse`) or calls the deployed backend — what the import costs, `window.XANO_HOST`, local dev, file URLs, and a Node spot-check.
+> Read when a frontend calls the deployed backend or imports a def — request types and zod schemas without the import, its cost, `window.XANO_HOST`, local dev, file URLs, a Node spot-check.
 
 Importing a def into a browser bundle or a Node script — for `getPath()`, `getUrl()`, `verb`, or `InferResponse` — runs its factory calls; these are the costs and the checks.
 
@@ -645,6 +645,16 @@ Importing a def into a browser bundle or a Node script — for `getPath()`, `get
   plain data importing NOTHING, still compile-checked: `routePath("GET blog/{slug}", { slug })`
   `channelPath("rooms/{room_id}", { room_id })`, `socketUrl("chat", baseUrl)` (tenant base
   URLs lifted to `wss://h/ws/<tenant>:<canonical>`). A rename is a type error, not a 404.
+- **Request types without the def.** `routes.gen.ts` also exports types-only `RouteInputs`,
+  `ChannelInputs`, `MessageInputs` (and `MessageName`), keyed like `ROUTES`, `CHANNELS`, and
+  `"<channel key> <message name>"`: `type NewListing = RouteInputs["POST listings"]`. A
+  frontend types bodies, channel params and payloads from these, not `InferInput` on a def;
+  keep `InferInput` in code that already imports defs. They match `InferInput`, except a
+  `dbLink` input appears as the linked table's columns (what the server accepts). Responses
+  are not in the file: `InferResponse` on an `import type` of the def.
+  Runtime validation: `xanosdk marketplace install zod` adds `@xano-sdk/zod`, which writes
+  `ROUTE_SCHEMAS`/`CHANNEL_SCHEMAS`/`MESSAGE_SCHEMAS` into the file under the same keys, each
+  checked against its type at typecheck; the file then imports `zod`, never `@xano/sdk`.
 - **Verifying a def outside a bundler.** Inside a bundler (Vite/webpack) importing a
   query def to read `getPath()`/`verb` works directly. To spot-check from Node, run a REAL
   file with `tsx <file.ts>` **from inside the project root** — not `tsx -e "import …"`
@@ -708,6 +718,18 @@ defaults and re-enables a disabled one; `marketplace remove <pkg>` drops block,
 dependency together — a plain `npm uninstall` leaves the block, and a package it names
 that is no longer installed fails every `--frozen-lock` run.
 
+**A module's section of `xano/routes.gen.ts`.** A module with a `routesManifest` hook (types:
+`@xano/sdk/plugin`) writes a block between `// xanosdk:begin <pkg>` and `// xanosdk:end <pkg>`
+after the core sections, on every write of the file (`routes --emit`, `xano:routes`, `pull`,
+`generate`, `marketplace install|reinstall|remove`). Edits inside the block are overwritten.
+Install also adds the module's non-SDK peers (e.g. `zod`) as direct dependencies.
+The hook is synchronous and pure: given
+the request inputs under the manifest's keys and its config, it returns `{ imports?, source }`,
+imports as bare package names (`@xano/sdk*`, relative and `node:` are refused). A module that
+fails to load or throws leaves its previous block as it was, with a warning naming it, and the
+core sections still refresh; under `routes --emit --strict` it is fatal. `@xano-sdk/zod`
+(`xanosdk marketplace install zod`) is one: it adds `ROUTE_SCHEMAS` and its siblings.
+
 # Error index
 
 > Read when a request, test, build, or pull fails with a message you did not write — the string, its cause, and where the fix is.
@@ -997,7 +1019,7 @@ off); a trigger's own failure reaches the error log only while it is on.
 
 Array blocks (an `if`/`transform` is applied per item):
 
-- `s.array.map({ source, as?, transform? })` — `transform` is either a per-item `Value` expression (each item maps to that value) or a **record of values** (each item maps to an object with those keys), or a list of `{ key, value }` pairs, for a key computed per item or two rows sharing one. Use `ref("$this")` for the item and `ref("$index")` for its position. These are THIS statement's own bindings, in a value expression — not the JavaScript lambda contract (see **Lambda bodies**), which binds a different set per surface and is written with `lam.fn`.
+- `s.array.map({ source, as?, transform? })` — `transform` is either a per-item `Value` expression (each item maps to that value) or a **record of values** (each item maps to an object with those keys), or a list of `{ key, value }` pairs, for a key computed per item or two rows sharing one. Use `ref("$this")` for the item and `ref("$index")` for its position. A `transform` value, filter arguments included, can read `ref("$this.<path>")` and any outer stack variable or input. These are THIS statement's own bindings, in a value expression — not the JavaScript lambda contract (see **Lambda bodies**), which binds a different set per surface and is written with `lam.fn`.
 - `s.array.union({ source, with, as?, transform? })` — set-union two arrays. `with` is REQUIRED; omitted → `Unable to locate input: `.
 
 DB reads/writes (`table` is a def handle or name; `fieldName` defaults to the
@@ -1051,7 +1073,8 @@ primary key `id`):
   - Template placeholders are Twig over the request scope: `{{ $input.name }}` for an input, `{{ $var.name }}` for a stack variable. ⚠ A BARE `{{ name }}` renders as the empty string — HTTP 200, no error, a query that silently ran with a blank where the value belonged. A bound `?` arg carries a VALUE without the template at all.
   - ⚠ A table's PHYSICAL name is **not stable across deploys**. A deploy is a full replace, so every table is created afresh and the id in its name moves every time — the same unchanged project redeployed three times gave one table three different names. Never store, cache, hardcode or fixture one: resolve it from `information_schema` inside the same request that uses it.
 - `s.db.external.<engine>.direct_query({ sql, connectionString, responseType?, args?, parser?, as? })` — same shape against an EXTERNAL database; `<engine>` is `postgres`/`mysql`/`mssql`/`oracle`/`snowflake`. `connectionString` is a `Value` — reach for `env(...)`, not a literal — stored as `context.connection_string_flex`. A bare string stores the older `context.connection_string` instead (an env-var name unless it looks like a URL); each form round-trips as itself.
-- `s.db.transaction({ body, as? })` — run a `Statement[]` atomically. `as` binds whatever the block returned.
+- `s.db.transaction({ body })` — run a `Statement[]` atomically. It returns nothing, so it takes no `as`: read what the body binds. An `s.return` in the body ends the WHOLE stack with that value, and the writes before it commit.
+  - The body shares the enclosing stack: a variable it binds (`as: "order"` on an `s.db.add`) is still bound AFTER the transaction.
 - `s.db.bulk.add({ table, items, allowIdField?, as? })` / `s.db.bulk.update` / `s.db.bulk.patch` — `items` is an array `Value`.
   - ⚠ `bulk.add` **drops `id` on every row unless `allowIdField: true`** (silently, next sequence value instead) — the opposite of `seed`, where `id` pins. Rows referenced by a foreign key need `allowIdField: true`; literal `items` carrying `id` without it throw. `bulk.update`/`patch` keep `id` (their match key).
   - ⚠ **`bulk.update` is a whole-row REPLACE: every column an item OMITS is zeroed** (`""`/`0`/`null`), HTTP 200, no error — `{ id: 7, status: "done" }` blanks the rest of row 7. **Use `s.db.bulk.patch`** for the partial write "update these rows" means. `export()` warns on a STATIC `items` missing columns (`--strict` fails); a `ref`/`inp` `items` is uninspectable.
@@ -1428,6 +1451,10 @@ with `c.obj`/`c.array`. Any argument also takes a runtime value (`inp`, `ref`, a
 `withFilters` chain) — inside `obj()`/`expr()` an argument cannot carry its own filter
 chain, so compute it in a prior `set_var`. The arg types below name each argument's
 ENGINE type, not the JS type you may pass.
+`fl.add`/`fl.sub`/`fl.mul` keep an INT when both operands are ints (`2 × 3` is `6`, not
+`6.0`) and give a decimal only when either operand is one — the `decimal` return type
+below covers both, so an int pipeline needs no `fl.to_int()`. `fl.div` is an int only
+when it divides exactly.
 To add to a numeric column (counter, stock, balance), use `s.db.increment`
 (`llms/statements-data.md`) — one atomic UPDATE. A pipeline read-modify-write is NOT
 atomic (concurrent writers lose updates), and `col("clicks")` does NOT resolve to the

package/llms.txt

@@ -1,4 +1,4 @@
-# xanosdk v1.0.5
+# xanosdk v1.0.7
 
 > TypeScript SDK that compiles a typed Xano workspace into the importable packageExport JSON bundle.
 
@@ -39,7 +39,7 @@ plain file read resolves them at the version you have.
 
 - [Object kinds](llms/object-kinds.md): Read when deciding WHAT to build — every authorable primitive, what each is, and which factory + register method builds it. Also when `register*` will not typecheck an array built by `.flatMap()`/`.concat()`.
 - [Core def shapes](llms/kinds-core.md): Read when authoring a function, query, api group, task, workflow test, middleware, tool, or addon — and for the `response` and `expr` shapes every one of them uses.
-- [Consuming defs from a client](llms/client.md): Read when a frontend imports a def (`getPath()`/`InferResponse`) or calls the deployed backend — what the import costs, `window.XANO_HOST`, local dev, file URLs, and a Node spot-check.
+- [Consuming defs from a client](llms/client.md): Read when a frontend calls the deployed backend or imports a def — request types and zod schemas without the import, its cost, `window.XANO_HOST`, local dev, file URLs, a Node spot-check.
 - [Toolchain modules](llms/toolchain.md): Read when `package.json` has a `"xanosdk"` block or you run `xanosdk marketplace`.
 - [Error index](llms/errors.md): Read when a request, test, build, or pull fails with a message you did not write — the string, its cause, and where the fix is.
 - [Saved unit tests, assertions, and mocks](llms/tests.md): Read when authoring a `workflowTest()` stack, when a query/function/middleware carries `tests`, when a statement needs a `mock`, or when running a deployed environment's tests.
@@ -436,7 +436,7 @@ Non-obvious authoring rules:
   checked only by the `xanosdk export`/`deploy` CLI path. Only `deploy` ships seed rows.
   - Entry points: the `node:fs` writers (`writeBundle`/`writeArtifact`) and lock-file I/O
     import from `@xano/sdk/node`, NOT the browser-safe `@xano/sdk` entry (a frontend
-    imports defs from it for `getPath()`/`InferInput`). `@xano/sdk/internal` is the
+    imports from it; request types come from `routes.gen.ts`). `@xano/sdk/internal` is the
     compiler machinery, never needed to author. READING a bundle back is `@xano/sdk/bundle`
     — a statement walker (`2.if.0` paths), a structural hash, `mvp:*` catalog, `tableRefOf`.
 - **Intra-workspace imports use `.js` specifiers** (`../tables/links.js`), not

package/manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "xanosdk",
-  "version": "1.0.5",
+  "version": "1.0.7",
   "description": "TypeScript SDK that compiles a typed Xano workspace into the importable packageExport JSON bundle.",
   "coverage": {
     "objectKinds": {
@@ -8997,6 +8997,48 @@
     }
   ],
   "cli": [
+    {
+      "command": "agent-skill install",
+      "flags": [
+        {
+          "flag": "--agent <id>",
+          "description": "Which agent to act for, instead of the ones detected (repeatable): claude-code, agents (the shared ~/.agents directory), codex, cursor, copilot, gemini, amp, opencode"
+        },
+        {
+          "flag": "--dry-run",
+          "description": "Report what would change and write nothing"
+        },
+        {
+          "flag": "--force",
+          "description": "Replace a copy that was edited since it was installed"
+        }
+      ],
+      "description": "Write the skill into the user-level skill directory of each detected agent; an edited copy is left alone unless --force"
+    },
+    {
+      "command": "agent-skill status",
+      "flags": [
+        {
+          "flag": "--agent <id>",
+          "description": "Which agent to act for, instead of the ones detected (repeatable): claude-code, agents (the shared ~/.agents directory), codex, cursor, copilot, gemini, amp, opencode"
+        }
+      ],
+      "description": "Report each copy as current, stale, edited or absent"
+    },
+    {
+      "command": "agent-skill uninstall",
+      "flags": [
+        {
+          "flag": "--agent <id>",
+          "description": "Which agent to act for, instead of the ones detected (repeatable): claude-code, agents (the shared ~/.agents directory), codex, cursor, copilot, gemini, amp, opencode"
+        },
+        {
+          "flag": "--dry-run",
+          "description": "Report what would be removed and remove nothing"
+        }
+      ],
+      "description": "Remove the copies install wrote; an edited copy is reported and kept"
+    },
     {
       "command": "compile",
       "args": "<file>",
@@ -9655,10 +9697,11 @@
         },
         {
           "flag": "--framework <id>",
-          "description": "Frontend framework to scaffold: react (default), svelte",
+          "description": "Frontend to scaffold in a new project: react (default), svelte, or none for the backend only. A non-empty directory always gets the backend only",
           "values": [
             "react",
-            "svelte"
+            "svelte",
+            "none"
           ]
         },
         {
@@ -9777,7 +9820,7 @@
         },
         {
           "flag": "--force",
-          "description": "Write into a non-empty target directory. Over an existing project it lists every file it would overwrite and confirms first (--yes without a terminal); files the scaffold does not write are kept"
+          "description": "Write over what clashes when adding the backend to a non-empty target directory: an existing xano/, a file init would write, a xano:* script with another command. It lists every file and script it would overwrite and confirms first (--yes without a terminal); files the scaffold does not write are kept"
         },
         {
           "flag": "--no-install",
@@ -9851,7 +9894,7 @@
           ]
         }
       ],
-      "description": "Scaffold a Xano SDK project — empty, or filled from an existing backend"
+      "description": "Scaffold a Xano SDK project — empty, or filled from an existing backend. In a non-empty directory, add the backend to the project there"
     },
     {
       "command": "local cache",
@@ -9876,6 +9919,21 @@
       "command": "local list",
       "description": "List Xano Engines on this machine, marking the ones xanosdk started"
     },
+    {
+      "command": "local mcp",
+      "args": "[name]",
+      "flags": [
+        {
+          "flag": "--stdio",
+          "description": "Run as an MCP stdio server that forwards to the live engine with its current bearer — the command a coding agent's MCP config launches"
+        },
+        {
+          "flag": "--project <dir>",
+          "description": "The project whose engine to reach, when the agent launches the bridge outside it (default: the current directory)"
+        }
+      ],
+      "description": "Print how a coding agent connects to a Xano Engine's MCP server (look at the backend, seed rows, run functions, tasks, triggers, endpoints and tests); `--stdio` runs the bridge the agent's MCP config launches (default: the engine this project deployed to)"
+    },
     {
       "command": "local stop",
       "args": "<name>",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xano/sdk",
-  "version": "1.0.5",
+  "version": "1.0.7",
   "description": "Xano SDK — your Xano backend as TypeScript. `xanosdk deploy` ships your typed workspace (and an optional static frontend) to a live, auto-expiring ephemeral environment and prints its URL. init → deploy → URL.",
   "keywords": [
     "xanosdk",
@@ -86,6 +86,7 @@
     "llms-full.txt",
     "llms",
     "guides",
+    "skills",
     "README.md",
     "CHANGELOG.md"
   ],
@@ -107,6 +108,8 @@
     "audit:output-flag": "tsx scripts/audit-output-flag.ts",
     "audit:decode-coverage": "tsx scripts/audit-decode-coverage.ts",
     "audit:dts": "npm run build && tsx scripts/audit-dts.ts",
+    "eval:skill-trigger": "tsx scripts/eval-skill-trigger.ts",
+    "eval:skill-scenarios": "tsx scripts/eval-skill-scenarios.ts",
     "manifest": "tsx scripts/manifest.ts",
     "codes": "tsx scripts/codes.ts",
     "changelog": "tsx scripts/changelog.ts",
@@ -152,7 +155,7 @@
     "eslint": "^9.0.0",
     "gpt-tokenizer": "^3.4.0",
     "tsup": "^8.0.0",
-    "tsx": "^4.22.4",
+    "tsx": "^4.23.15",
     "typescript": "^5.5.0",
     "vitest": "^4.1.11"
   },

package/skills/xano-backend/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: xano-backend
+description: >-
+  Builds and runs application backends on Xano, authored as TypeScript with
+  @xano/sdk: database tables, REST API endpoints, user authentication,
+  server-side logic, scheduled and background jobs, webhooks, file storage and
+  realtime. Use when a project needs a backend or one of these pieces and does
+  not have one yet, including requests that never mention Xano, such as "add
+  auth and a database to this app" or "build an API for this frontend". Also
+  use in any project with a xano/ directory or an @xano/sdk dependency. Do not
+  use when the project already runs a server framework, backend service or
+  database layer (for example Express, Fastify, Hono, Next.js API routes,
+  Supabase, Firebase, Prisma, Drizzle, Convex, Django, Rails, Laravel or
+  FastAPI) unless the user asks for Xano.
+license: MIT
+metadata:
+  xanosdk-version: "1.0.7"
+  xanosdk-digest: "sha256:335ffa095690ba305b28ede608a35590cb247a0b0954b41d2eda3046ed051fae"
+---
+
+# Xano backend
+
+Xano runs the backend: database tables, API endpoints, authentication, server-side
+logic, scheduled tasks, triggers and webhooks, file storage and realtime. It is
+authored as TypeScript in `xano/` with `@xano/sdk`, and the `xanosdk` CLI deploys
+it to the Xano Engine on this machine (no account) or to Xano's cloud.
+
+Work through the steps in order. Stop at the first one that ends the task.
+
+## 1. Is this already a Xano project?
+
+Look at the project root: the directory holding `package.json`, else the
+repository root.
+
+- `xano/` exists, or `package.json` lists `@xano/sdk`: read `AGENTS.md` and
+  follow it. Do not run `init`. This skill ends here.
+  - No `AGENTS.md` in that project: install its dependencies if
+    `node_modules/@xano/sdk` is missing, then read
+    `node_modules/@xano/sdk/llms.txt` in full and follow it instead.
+
+## 2. Does the project already have another backend?
+
+Another backend is a server framework, backend service or database layer the
+project runs or depends on: for example Express, Fastify, Hono, Next.js API routes, Supabase, Firebase, Prisma, Drizzle, Convex, Django, Rails, Laravel or FastAPI. These are
+examples, not the whole set. Check the dependency manifests (`package.json`,
+`requirements.txt`, `pyproject.toml`, `Gemfile`, `composer.json`) and the
+server entry points.
+
+- Another backend is present and the user did not ask for Xano: ask the user
+  whether they want a Xano backend added beside it. Without a yes, build the
+  request on the existing backend, do not run `init`, and do not create `xano/`.
+
+## 3. Confirm Xano
+
+- The user has not named Xano: say that you will set up the backend with Xano
+  (`@xano/sdk`, TypeScript in `xano/`, running locally on the Xano Engine), and
+  wait for a yes before step 4. Without one, stop using this skill.
+- The user named Xano: continue.
+
+## 4. Run init
+
+Run it at the project root. Which form:
+
+- The directory has files (an existing app): `init` adds only the backend. It
+  writes `xano/` and merges what the backend needs into `package.json`, and
+  writes no frontend.
+
+  ```bash
+  npx @xano/sdk init --json
+  ```
+
+- The directory is empty and the user asked only for a backend:
+
+  ```bash
+  npx @xano/sdk init --framework none --json
+  ```
+
+- The directory is empty and the user asked for an app: `npx @xano/sdk init --json`
+  writes a frontend and the backend.
+
+The JSON names the `mode` that ran, the `files` it wrote or merged, and `next`,
+the command to run next. When `init` refuses and lists clashes, show the list to
+the user. Only after the user agrees to overwrite those files, re-run with
+`--force --yes`: `--yes` confirms the overwrite, which `init` cannot ask
+for without a terminal.
+
+## 5. Deploy
+
+Run the command in `next`. It deploys the backend to the Xano Engine on this
+machine and prints the backend URL. No account is needed.
+
+The Xano Engine runs on macOS on Apple Silicon and on Linux (x64, arm64). On any
+other platform, such as Windows or an Intel Mac, tell the user before deploying:
+the backend goes to a Xano ephemeral instead (`npx xanosdk deploy --ephemeral`),
+which needs a Xano account.
+
+Only a human can do these. Stop and ask the user, then continue once they are
+done:
+
+- Creating a Xano account.
+- Signing in: `npx xanosdk login` opens a browser consent. Ask the user to run it
+  in their own terminal. Do not run it yourself.
+
+## 6. Verify
+
+- `npm run xano:check` passes.
+- A request to the backend URL the deploy printed gets a response.
+  `npx xanosdk status` prints that URL again.
+
+## 7. Hand off
+
+Read `AGENTS.md`, which `init` wrote, and follow it for all further backend work.
+Before writing code in `xano/`, read `node_modules/@xano/sdk/llms.txt`.
+
+Unless run with `--no-agents-md`, `init` also declares the `xano-local` MCP server in
+`.mcp.json` and `.cursor/mcp.json`: the deployed backend's tables, rows and runs,
+which `AGENTS.md` describes. `npx xanosdk local mcp` prints the server block for any
+other agent. It is not loaded into a session that was already running. Tell the user
+to restart the agent, or reconnect its MCP servers, to use it.