@xano/sdk 1.0.6 → 1.0.8

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
@@ -133,6 +137,9 @@ 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`)
@@ -320,6 +327,68 @@ caret) and restamps the managed blocks in your
 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

@@ -28,6 +28,7 @@ Match on the code, never on the message text: messages are reworded, codes are n
 | `SDK_SEED_IN_STATIC` | A static build carries seed values from non-public columns (`details.leaks[]`); nothing was published. |
 | `SDK_SHARED_SCHEMA_CHANGE` | A promote would alter tables live serves from (`details.reason: "shared-schema-changes"`, `details.changes[]`), or could not read them (`"tables-unreadable"`); `--allow-shared-schema-changes` lands it. Exit 2. |
 | `SDK_USAGE` | The input is wrong — a command line, a def or a value the build or the command refuses as written — a confirmation was needed off a terminal (`details.reason: "needs-confirmation"`), or the named backend is in another workspace (`details.reason: "wrong-workspace"`, `details.heldIn`). Exit 1. |
+| `SDK_WORKSPACE_CHANGED` | A `deploy --to workspace` would overwrite objects changed in Xano since the last sync (`details.reason: "workspace-changed"`, `details.objects[]`, `details.changedThere[]`, `details.changedBoth[]`, `details.baseline`); pull first, or `--overwrite` deploys over them. Exit 2. |
 
 ## CLI warnings
 
@@ -62,6 +63,7 @@ Printed as `! …` on stderr, and as `{ code, message }` in a `--json` document'
 | `deploy.ephemeral-write` | Says which ephemeral this deploy writes to. |
 | `deploy.import-failed-backup` | The import failed. Your pre-deploy snapshot is on branch "…". |
 | `deploy.open-no-url` | --open had no URL to open — the deploy reported none. |
+| `deploy.overwrite-changed` | `--overwrite`: … object… changed in Xano since the last sync … overwritten: |
 | `deploy.replace-wipe` | `--replace` wipes … before importing — including table data and history. |
 | `deploy.rows-written` | Table rows from the bundle … written. |
 | `deploy.tenant-write` | This deploy writes to a target that is not an ephemeral, named in the message. |
@@ -133,6 +135,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): |
@@ -278,7 +281,7 @@ Raised while a workspace compiles (`export`, `deploy`, `release`, …). A warnin
 
 | Code | Meaning |
 |---|---|
-| `agent.args-placeholder-unpassed` | … "…": `s.ai.agent.run` of agent "…" passes args …, but the agent's prompt reads `{{ $args… }}`, which this run never passes, so it resolves to nothing. |
+| `agent.args-placeholder-unpassed` | …: `s.ai.agent.run` of agent "…" passes args …, but the agent's prompt reads `{{ $args… }}`, which this run never passes, so it resolves to nothing. |
 | `agent.literal-api-key` | agent "…" spells its `llm.apiKey` literally. |
 | `api-group.cors-no-methods` | apiGroup "…": `cors.mode: "custom"` enables no `allowMethods`, so no `access-control-allow-methods` is sent and a preflight has nothing to approve. |
 | `api-group.cors-no-origins` | apiGroup "…": `cors.mode: "custom"` with an empty `allowOrigins` matches no request, so responses carry NO `access-control-*` headers and every browser call… |
@@ -366,6 +369,7 @@ Raised while a workspace compiles (`export`, `deploy`, `release`, …). A warnin
 | `search.request-only-filter` | … pipes a search operand through `…`, which evaluates only in the request. |
 | `seed.invalid` | A seed row does not match its table's columns. |
 | `seed.public-seed` | Table "…" declares publicSeed but has no `seed`: there are no seed values to declare public. |
+| `stack.agent-tools-off` | …: `s.ai.agent.run` of agent "…" leaves `allowToolExecution` unset, so the agent runs with its tools off: it sees them but never calls one, and answers as if… |
 | `stack.auth-no-caller` | … "…" reads `auth()`, but …: it deploys clean and never holds the caller's identity. |
 | `stack.auth-null-host` | … "…": an `s.redis.ratelimit` in its stack keys off auth(), where …. |
 | `stack.blank-table` | … has … (…) bound to no table (`table: null`) — … nothing when run. |

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
@@ -1267,7 +1295,7 @@ xanosdk workspace diff ./xano/index.ts --json
 }
 ```
 
-- `changedThere`: pull before you deploy, or the deploy overwrites that edit.
+- `changedThere`: pull before you deploy. `deploy --to workspace` refuses to overwrite it (see below).
 - `changedHere`: deploy it.
 - `changedBoth`: reconcile by hand.
 - `unclassified`: the baseline cannot tell. The object has no baseline entry, both sides
@@ -1295,6 +1323,22 @@ A few things to know about the baseline:
   next sync records a new baseline.
 - On a merge conflict in `xano.lock`, keep either side's baseline for a branch, or delete it.
 
+#### The deploy guard
+
+`deploy --to workspace` reads the same baseline before it writes. When an object it would
+overwrite is in `changedThere` or `changedBoth`, it refuses with exit 2 and
+`SDK_WORKSPACE_CHANGED`. The refusal's `details.objects` lists those objects, and
+`details.changedThere`, `details.changedBoth` and `details.baseline` say how each was classified.
+Pull the change into the project and commit it, then deploy again. To deploy over it anyway, pass
+`--overwrite`; the run warns (`deploy.overwrite-changed`) and names what it overwrote. A
+`--dry-run` refuses nothing: it warns and lists the objects under `changedInXano`.
+
+The guard counts only what the deploy writes. A merge leaves an object that only the branch holds
+alone, so an object added in Xano is refused over only under `--prune` or `--replace`, which
+delete it. Nothing is refused when the branch has no baseline, over an `unclassified`
+difference, or on a `--branch` deploy to a branch that does not exist yet. It reads the branch
+once, before the confirmation, so an edit made in Xano after that read is not caught.
+
 ### Deploying to a branch
 
 `--branch <label>` stages on a Xano branch instead of the live one, which is the safer shape

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/llms/errors.md

@@ -34,7 +34,7 @@
 - A response types as `StackTupleWidened` — a `Statement[]` helper was spread into the stack; return `statements(...)`. `llms.txt`; `llms/statements-runtime.md`.
 - `ERR_PACKAGE_PATH_NOT_EXPORTED` — `tsx -e "import …"`, or running from outside the project root; run a real file with `tsx <file.ts>` from the root. `llms/client.md`.
 - `Missing statement: mvp:placeholder` on import — an unconfigured slot in a pulled tree; replace it with the statement it stands in for. `llms/legacy.md`.
-- A CLI command fails under `--json` or piped (unless stdout carries data): stdout is `{ ok: false, error: { code, message, exitCode, details?, suggestion? } }`, as does a failed release write. Codes: `SDK_SEED_IN_STATIC` (`details.leaks[]` → `publicSeed`), `SDK_EXPORT_INVALID` (`details.diagnostics[]`, `--strict` too), `SDK_DRIFT`, `SDK_BRANCH_TAKEN`, `SDK_BRANCH_LIVE`, `SDK_RELEASE_NAME_TAKEN`, `SDK_RELEASE_FILES_NOT_CARRIED`, `SDK_LIVE_BRANCH_MISMATCH` (`details.conflictsWith`), `SDK_IDENTITY_CONFLICT`, `SDK_KIND_CONFLICT`, `SDK_PRUNE_OUT_OF_SCOPE`, `SDK_IMPORT_REFUSED`, `SDK_SHARED_SCHEMA_CHANGE`, `SDK_CONSTRAINT_VIOLATION`, `SDK_CREDENTIAL_REJECTED` (`details`: `{ profile, credentialType, instance, workspaceId, signIn }`; ids null on a refused env refresh), `SDK_USAGE` (`details.reason: "needs-confirmation"`: run its `Re-run as`), `SDK_ERROR`. Landing refusal `details.refused`: identityConflict, renamePending, kindConflict, uniqueViolation, tableTrigger, importInProgress, importRefused, pruneOutOfScope. `warnings[]` / `details.warnings` / `accepted[]` entries: `{ code, message, subject? }` (`subject`: the def's `{ kind, name }`). Backend documents add `selector` and `workspaceId`.
+- A CLI command fails under `--json` or piped (unless stdout carries data): stdout is `{ ok: false, error: { code, message, exitCode, details?, suggestion? } }`, as does a failed release write. Codes: `SDK_SEED_IN_STATIC` (`details.leaks[]` → `publicSeed`), `SDK_EXPORT_INVALID` (`details.diagnostics[]`, `--strict` too), `SDK_DRIFT`, `SDK_BRANCH_TAKEN`, `SDK_BRANCH_LIVE`, `SDK_RELEASE_NAME_TAKEN`, `SDK_RELEASE_FILES_NOT_CARRIED`, `SDK_LIVE_BRANCH_MISMATCH` (`details.conflictsWith`), `SDK_IDENTITY_CONFLICT`, `SDK_KIND_CONFLICT`, `SDK_PRUNE_OUT_OF_SCOPE`, `SDK_IMPORT_REFUSED`, `SDK_SHARED_SCHEMA_CHANGE`, `SDK_CONSTRAINT_VIOLATION`, `SDK_CREDENTIAL_REJECTED` (`details`: `{ profile, credentialType, instance, workspaceId, signIn }`; ids null on a refused env refresh), `SDK_WORKSPACE_CHANGED` (deploy over objects edited in Xano since the last sync; `details.objects`; pull first or `--overwrite`), `SDK_USAGE` (`details.reason: "needs-confirmation"`: run its `Re-run as`), `SDK_ERROR`. Landing refusal `details.refused`: identityConflict, renamePending, kindConflict, uniqueViolation, tableTrigger, importInProgress, importRefused, pruneOutOfScope. `warnings[]` / `details.warnings` / `accepted[]` entries: `{ code, message, subject? }` (`subject`: the def's `{ kind, name }`). Backend documents add `selector` and `workspaceId`.
 - A CLI command reports `could not reach <url>: fetch failed (<code>)` — blocked egress, not a bad credential; fix it before `xanosdk login`, which rotates a single-use refresh token.
 
 ### CLI exit codes

package/llms/kinds-agent-mcp.md

@@ -25,6 +25,6 @@
   - `llm` (REQUIRED): typed provider settings, a discriminated union on `type` (`"xano-free" | "anthropic" | "openai" | "google-genai"`). Shared fields: `systemPrompt?`, `maxSteps?` (default `5`), and `prompt?` XOR `messages?` (genuinely exclusive: both is a type error and throws — the engine stores ONE `prompt_type`, so one would be dropped); plus provider fields (`apiKey?`, `model?`, `temperature?`, `reasoningEffort?`, …). String fields accept Twig placeholders — `{{ $args.x }}` for run inputs (the `args` of `s.ai.agent.run`), `{{ $env.NAME }}` for env vars.
   - `tools?`: same `ToolsetToolEntry[]` as `mcpServer` — bare `tool()` handles, or a `{ tool, enabled?, auth? }` wrapper when one needs `enabled`/`auth`. A tool reading `auth()` MUST use the wrapper naming the auth table — a bare handle runs it with no caller (see `mcpServer`'s `tools?`).
   - `output?`: `{ schema: Record<string, input.*>, enabled? }` — structured-output schema. `schema` is a named-field record authored with the `input.*` catalog, exactly like a `defineFunction`/`query` `input:` map (the stored `structuredOutputsSchema` is the same wire shape as function inputs). e.g. `output: { schema: { priority: input.enum(["low","high"]), summary: input.text() } }`. When you pass the agent *handle* to `s.ai.agent.run({ agent })`, `.result` is typed straight from this schema — no `resultShape` witness needed (the shape is declared once). `resultShape` remains only to override that, or to type an agent referenced by bare name.
-  - **Run + read recipe (`s.ai.agent.run`):** bind the run to a var (`s.ai.agent.run({ agent, args, as: "run" })`) — it produces a rich envelope, and the completion is at **`.result`**. Read one structured field with a dotted ref (`response: ref("run.result.priority")`) or the whole completion (`ref("run.result")`, typed from `output.schema`); persist it in a later step the same way (`s.set_var("summary", ref("run.result.summary"))`). `args` is a plain object of run inputs (`{ topic: inp("topic") }` — raw literals are fine, e.g. `{ max_steps: 3 }`) surfaced to the agent as `{{ $args.topic }}`. `.toolCalls` is the FINAL step's calls only (often `[]`); every call is a `.steps[].content[]` entry of `type: "tool-call"`.
+  - **Run + read recipe (`s.ai.agent.run`):** bind the run to a var (`s.ai.agent.run({ agent, args, allowToolExecution: c.bool(true), as: "run" })`) — it produces a rich envelope, and the completion is at **`.result`**. Read one structured field with a dotted ref (`response: ref("run.result.priority")`) or the whole completion (`ref("run.result")`, typed from `output.schema`); persist it in a later step the same way (`s.set_var("summary", ref("run.result.summary"))`). `args` is a plain object of run inputs (`{ topic: inp("topic") }` — raw literals are fine, e.g. `{ max_steps: 3 }`) surfaced to the agent as `{{ $args.topic }}`. `.toolCalls` is the FINAL step's calls only (often `[]`); every call is a `.steps[].content[]` entry of `type: "tool-call"`. ⚠ An agent with tools needs `allowToolExecution: c.bool(true)` on the run: unset, its tools are OFF and it answers without them (warns `stack.agent-tools-off`).
   - **Marketplace:** for chat history, use `@xano-sdk/chatbot`; for vector RAG, use `@xano-sdk/vector` (`tools: [vector.searchTool]`). Find add-ons with `xanosdk marketplace search <q>`.
 - Both kinds persist under the `toolset` payload key, so a same-name `agent` + `mcpServer` pair derives ONE guid and `export()` throws — give them distinct names.

package/llms-full.txt

@@ -1,4 +1,4 @@
-# xanosdk v1.0.6
+# xanosdk v1.0.8
 
 > TypeScript SDK that compiles a typed Xano workspace into the importable packageExport JSON bundle.
 
@@ -766,7 +766,7 @@ core sections still refresh; under `routes --emit --strict` it is fatal. `@xano-
 - A response types as `StackTupleWidened` — a `Statement[]` helper was spread into the stack; return `statements(...)`. `llms.txt`; `llms/statements-runtime.md`.
 - `ERR_PACKAGE_PATH_NOT_EXPORTED` — `tsx -e "import …"`, or running from outside the project root; run a real file with `tsx <file.ts>` from the root. `llms/client.md`.
 - `Missing statement: mvp:placeholder` on import — an unconfigured slot in a pulled tree; replace it with the statement it stands in for. `llms/legacy.md`.
-- A CLI command fails under `--json` or piped (unless stdout carries data): stdout is `{ ok: false, error: { code, message, exitCode, details?, suggestion? } }`, as does a failed release write. Codes: `SDK_SEED_IN_STATIC` (`details.leaks[]` → `publicSeed`), `SDK_EXPORT_INVALID` (`details.diagnostics[]`, `--strict` too), `SDK_DRIFT`, `SDK_BRANCH_TAKEN`, `SDK_BRANCH_LIVE`, `SDK_RELEASE_NAME_TAKEN`, `SDK_RELEASE_FILES_NOT_CARRIED`, `SDK_LIVE_BRANCH_MISMATCH` (`details.conflictsWith`), `SDK_IDENTITY_CONFLICT`, `SDK_KIND_CONFLICT`, `SDK_PRUNE_OUT_OF_SCOPE`, `SDK_IMPORT_REFUSED`, `SDK_SHARED_SCHEMA_CHANGE`, `SDK_CONSTRAINT_VIOLATION`, `SDK_CREDENTIAL_REJECTED` (`details`: `{ profile, credentialType, instance, workspaceId, signIn }`; ids null on a refused env refresh), `SDK_USAGE` (`details.reason: "needs-confirmation"`: run its `Re-run as`), `SDK_ERROR`. Landing refusal `details.refused`: identityConflict, renamePending, kindConflict, uniqueViolation, tableTrigger, importInProgress, importRefused, pruneOutOfScope. `warnings[]` / `details.warnings` / `accepted[]` entries: `{ code, message, subject? }` (`subject`: the def's `{ kind, name }`). Backend documents add `selector` and `workspaceId`.
+- A CLI command fails under `--json` or piped (unless stdout carries data): stdout is `{ ok: false, error: { code, message, exitCode, details?, suggestion? } }`, as does a failed release write. Codes: `SDK_SEED_IN_STATIC` (`details.leaks[]` → `publicSeed`), `SDK_EXPORT_INVALID` (`details.diagnostics[]`, `--strict` too), `SDK_DRIFT`, `SDK_BRANCH_TAKEN`, `SDK_BRANCH_LIVE`, `SDK_RELEASE_NAME_TAKEN`, `SDK_RELEASE_FILES_NOT_CARRIED`, `SDK_LIVE_BRANCH_MISMATCH` (`details.conflictsWith`), `SDK_IDENTITY_CONFLICT`, `SDK_KIND_CONFLICT`, `SDK_PRUNE_OUT_OF_SCOPE`, `SDK_IMPORT_REFUSED`, `SDK_SHARED_SCHEMA_CHANGE`, `SDK_CONSTRAINT_VIOLATION`, `SDK_CREDENTIAL_REJECTED` (`details`: `{ profile, credentialType, instance, workspaceId, signIn }`; ids null on a refused env refresh), `SDK_WORKSPACE_CHANGED` (deploy over objects edited in Xano since the last sync; `details.objects`; pull first or `--overwrite`), `SDK_USAGE` (`details.reason: "needs-confirmation"`: run its `Re-run as`), `SDK_ERROR`. Landing refusal `details.refused`: identityConflict, renamePending, kindConflict, uniqueViolation, tableTrigger, importInProgress, importRefused, pruneOutOfScope. `warnings[]` / `details.warnings` / `accepted[]` entries: `{ code, message, subject? }` (`subject`: the def's `{ kind, name }`). Backend documents add `selector` and `workspaceId`.
 - A CLI command reports `could not reach <url>: fetch failed (<code>)` — blocked egress, not a bad credential; fix it before `xanosdk login`, which rotates a single-use refresh token.
 
 ### CLI exit codes
@@ -874,7 +874,7 @@ The run is isolated in ways that make a correct test fail for reasons the failur
   - `llm` (REQUIRED): typed provider settings, a discriminated union on `type` (`"xano-free" | "anthropic" | "openai" | "google-genai"`). Shared fields: `systemPrompt?`, `maxSteps?` (default `5`), and `prompt?` XOR `messages?` (genuinely exclusive: both is a type error and throws — the engine stores ONE `prompt_type`, so one would be dropped); plus provider fields (`apiKey?`, `model?`, `temperature?`, `reasoningEffort?`, …). String fields accept Twig placeholders — `{{ $args.x }}` for run inputs (the `args` of `s.ai.agent.run`), `{{ $env.NAME }}` for env vars.
   - `tools?`: same `ToolsetToolEntry[]` as `mcpServer` — bare `tool()` handles, or a `{ tool, enabled?, auth? }` wrapper when one needs `enabled`/`auth`. A tool reading `auth()` MUST use the wrapper naming the auth table — a bare handle runs it with no caller (see `mcpServer`'s `tools?`).
   - `output?`: `{ schema: Record<string, input.*>, enabled? }` — structured-output schema. `schema` is a named-field record authored with the `input.*` catalog, exactly like a `defineFunction`/`query` `input:` map (the stored `structuredOutputsSchema` is the same wire shape as function inputs). e.g. `output: { schema: { priority: input.enum(["low","high"]), summary: input.text() } }`. When you pass the agent *handle* to `s.ai.agent.run({ agent })`, `.result` is typed straight from this schema — no `resultShape` witness needed (the shape is declared once). `resultShape` remains only to override that, or to type an agent referenced by bare name.
-  - **Run + read recipe (`s.ai.agent.run`):** bind the run to a var (`s.ai.agent.run({ agent, args, as: "run" })`) — it produces a rich envelope, and the completion is at **`.result`**. Read one structured field with a dotted ref (`response: ref("run.result.priority")`) or the whole completion (`ref("run.result")`, typed from `output.schema`); persist it in a later step the same way (`s.set_var("summary", ref("run.result.summary"))`). `args` is a plain object of run inputs (`{ topic: inp("topic") }` — raw literals are fine, e.g. `{ max_steps: 3 }`) surfaced to the agent as `{{ $args.topic }}`. `.toolCalls` is the FINAL step's calls only (often `[]`); every call is a `.steps[].content[]` entry of `type: "tool-call"`.
+  - **Run + read recipe (`s.ai.agent.run`):** bind the run to a var (`s.ai.agent.run({ agent, args, allowToolExecution: c.bool(true), as: "run" })`) — it produces a rich envelope, and the completion is at **`.result`**. Read one structured field with a dotted ref (`response: ref("run.result.priority")`) or the whole completion (`ref("run.result")`, typed from `output.schema`); persist it in a later step the same way (`s.set_var("summary", ref("run.result.summary"))`). `args` is a plain object of run inputs (`{ topic: inp("topic") }` — raw literals are fine, e.g. `{ max_steps: 3 }`) surfaced to the agent as `{{ $args.topic }}`. `.toolCalls` is the FINAL step's calls only (often `[]`); every call is a `.steps[].content[]` entry of `type: "tool-call"`. ⚠ An agent with tools needs `allowToolExecution: c.bool(true)` on the run: unset, its tools are OFF and it answers without them (warns `stack.agent-tools-off`).
   - **Marketplace:** for chat history, use `@xano-sdk/chatbot`; for vector RAG, use `@xano-sdk/vector` (`tools: [vector.searchTool]`). Find add-ons with `xanosdk marketplace search <q>`.
 - Both kinds persist under the `toolset` payload key, so a same-name `agent` + `mcpServer` pair derives ONE guid and `export()` throws — give them distinct names.
 

package/llms.txt

@@ -1,4 +1,4 @@
-# xanosdk v1.0.6
+# xanosdk v1.0.8
 
 > TypeScript SDK that compiles a typed Xano workspace into the importable packageExport JSON bundle.
 

package/manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "xanosdk",
-  "version": "1.0.6",
+  "version": "1.0.8",
   "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>",
@@ -9076,6 +9118,10 @@
           "flag": "--allow-shared-schema-changes",
           "description": "Proceed even though table/microservice changes reach every branch — only with --to"
         },
+        {
+          "flag": "--overwrite",
+          "description": "Deploy over objects changed in Xano since the last deploy or pull (see `workspace diff`) — only with --to"
+        },
         {
           "flag": "--allow-branch-deletion",
           "description": "Acknowledge that --replace permanently deletes the workspace's other branches — only with --to"
@@ -9655,10 +9701,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 +9824,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 +9898,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 +9923,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.6",
+  "version": "1.0.8",
   "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"
   },