@xano/sdk 1.0.12 → 1.0.13

package/guides/module-contract.md

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

package/guides/object-kinds.md

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

package/guides/scaffold.md

@@ -9,7 +9,10 @@ backend alone — see [No frontend, and existing apps](#no-frontend-and-existing
 (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),
+agent brief, which every coding agent reads and `init` writes by default, and the
+`.mcp.json` / `.cursor/mcp.json` configs that connect agents to the `xano-local`
+MCP server), `--ai <preset|none>` (for scripted callers: `none` is `--no-agents-md`, and
+any other value writes the one `AGENTS.md` every agent reads),
 `--marketplace <pkg>` (repeatable, comma-separated; installs add-ons and
 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`
@@ -109,11 +112,12 @@ the add-on puts on your workspace, what you have to supply, and the
 `xano/index.ts` registration to copy. Piped, it emits JSON; `--prompt` emits
 instructions written to be handed straight to a coding agent.
 
-That is `npm install` with two additions: add-ons are discoverable from `xanosdk
---help`, and the command refuses before npm runs when you are not standing in a
-project — the mistake npm answers by silently writing to the wrong `package.json`.
-The package name is passed through exactly as typed, so version specifiers, tags,
-and third-party packages all work.
+`install` resolves its argument through the marketplace before npm runs — a module's
+package or its slug (`auth`), keeping any version or tag — and refuses a name the
+marketplace does not list with **exit 8**; local paths, `file:`, tarball and git specs
+install as given. It also refuses before npm runs when you are not standing in a project,
+and reconciles afterwards, asking any toolchain module that arrived its questions. See
+[Installing](marketplace.md#installing).
 
 ## No frontend, and existing apps
 
@@ -123,7 +127,8 @@ is a **new** project, and `--framework` decides its frontend. Any other director
 
 **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
+dependencies, `.gitignore`, `.gitattributes`, the CI check, a README, `AGENTS.md`, and the
+`.mcp.json` / `.cursor/mcp.json` agent configs. 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
@@ -143,6 +148,11 @@ no `frontend/` and no root `tsconfig.json`; `xano/` type-checks under its own
 - 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.
+- The `xano-local` MCP server merged by key into `.mcp.json` and `.cursor/mcp.json` (created
+  when missing): the other servers a config declares are kept. A config that already declares
+  `xano-local`, or is not valid JSON, is left alone and is not a clash; a symlinked one is
+  skipped. `--no-agents-md` skips both. See
+  [Connecting a coding agent](deploying.md#connecting-a-coding-agent).
 - 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.
 
@@ -177,17 +187,19 @@ The workflow installs with the project's package manager (npm, pnpm, yarn or bun
 `init` detected it), frozen to the committed lockfile, then runs `xano:check` on every push
 and pull request. In a monorepo workspace member it installs at the workspace root and checks
 in the member's directory; move the file to the repository root's `.github/workflows/`, the
-only place GitHub reads it. That script
-runs `xanosdk export ./xano/index.ts --check --strict`: every check an export runs (a build warning fails it), under
+only place GitHub reads it. That script runs three steps in order:
+`xanosdk routes ./xano/index.ts --emit xano/routes.gen.ts --strict`, which fails when the
+committed route manifest the frontend takes its paths from is stale or missing; the project's
+typecheck (`tsc` on React, `svelte-kit sync && svelte-check` on Svelte, `tsc -p xano` with no
+frontend, each followed by `tsc -p xano/lambdas`); and
+`xanosdk export ./xano/index.ts --check --strict`: every check an export runs (a build warning fails it), under
 `--frozen-lock`, writing nothing — no bundle, no lock. Because nothing is written, it
 reads no `xano/.env` or `xano/.secrets.json`, so the workflow needs no repository
 secrets, even for an API group whose docs are token-gated. It fails instead of
 rewriting when `xano.lock` disagrees with the source, naming what would change. A
 project with nothing to record yet (a fresh scaffold) passes without a lock. It also fails while the lock
 carries an entry no exported object matches — the state a rename leaves until
-`lock rename` moves the identity across, or `lock prune` drops it. It first runs
-`xanosdk routes ./xano/index.ts --emit xano/routes.gen.ts --strict`, which fails when
-the committed route manifest the frontend takes its paths from is stale or missing.
+`lock rename` moves the identity across, or `lock prune` drops it.
 `dev`, `build` and `typecheck` regenerate that file, so after adding or renaming an
 endpoint run `npm run xano:routes` (or any of them) and commit it. `init --from` and
 `pull` write it with the decoded backend, and `init --marketplace` writes it (and

package/guides/typed-frontend.md

@@ -36,6 +36,9 @@ Every type and helper a frontend gets from a deployed def — path resolution, i
   one group and verb that a single path can reach (`query.route-shadowed`). Make the paths
   disjoint (`"runs/by-id/{id}"`), or declare a numeric param `input.int({ required: true })`:
   only a REQUIRED int/decimal segment matches digits only, and an optional one matches any text.
+
+## Inferring the response type
+
 - **`InferRow<typeof post>`** → the table's row type. Rename or retype a column and every
   consumer breaks at compile time — exactly where you want it.
 - **`InferResponse<typeof someQuery>`** → the endpoint's **response** type, closing the round
@@ -46,9 +49,6 @@ Every type and helper a frontend gets from a deployed def — path resolution, i
   yielding null — `NotFound`/404 for `edit`/`patch`, a unique-constraint error for `add`, while
   `add_or_edit` upserts and never misses), `Row | null` for `db.get` (it binds
   `null` on a miss rather than throwing — handle the not-found path), a row list for
-
-## Inferring the response type
-
   `db.query`/`db.bulk.patch` (→ `Row[]`), a `boolean` for `db.has`, a `number` count for
   `db.bulk.delete`, and a `get`/`query` `output: [...]` selection narrows to a `Pick` (still
   `| null` for `get`). A dotted entry selects sub-keys of an object column
@@ -64,7 +64,7 @@ Every type and helper a frontend gets from a deployed def — path resolution, i
   `response: { user: obj({ id: ref("row.id") }) }` and the raw literal
   `response: { user: { id: ref("row.id") } }` both derive `{ user: { id: number | null } }`.
   A **call** carries the shape across: `s.function.call`/`s.function.run`, `s.tool.call` and
-  `s.api.call` (workflow-test only, above) given a def **handle** bind their `as` with the
+  `s.api.call` (workflow-test only — see [Object kinds](object-kinds.md)) given a def **handle** bind their `as` with the
   target's own `InferResponse`,
   so `ref("discount_result.discount_cents")` in the caller types to that field instead of
   `unknown`. What the target resolves to is what propagates, so declaring `responseShape` on
@@ -89,7 +89,7 @@ For a **computed or multi-key object response**, author it as a *record of value
 `response: { success: c.bool(true), id: inp("id") }` — **not** `c.obj({ ... })`. `c.obj` builds a
 *constant*, so a tagged value nested inside it would serialize as internal representation the
 engine can't decode (a runtime 500); nesting one is now a compile error that points you at the
-record form (issue #42). A **nested plain object** in a record
+record form. A **nested plain object** in a record
 response (`response: { user: { id: ref("u"), age: 3 } }`) is auto-wrapped for you — no manual
 `obj({ ... })` — and raw literals in a call/agent `input` map coerce too
 (`s.function.run({ fn, input: { max_age_days: 3 } })` — no `c.int(3)`).
@@ -250,7 +250,8 @@ const connectUrl = mcpUrl("notes_mcp", XANO_HOST); // https://host/x2/mcp/<canon
 ```
 
 Run `xanosdk routes ./xano/index.ts` without `--emit` to see every address the file carries:
-each route, socket, channel and MCP server, with the call that builds it.
+each route in its `api:<canonical>/<name>` form, and each socket, channel and MCP server with
+the call that builds it.
 
 **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

package/llms/kinds-knowledge.md

@@ -1,8 +1,8 @@
 # Knowledge def shape
 
-> Read when the workspace defines a `knowledge()` item for its AI agents.
+> Read when the workspace defines a `knowledge()` item.
 
-- `knowledge({ name, description?, type?, mode?, enabled?, body, refs?, guid?, tags? })` — markdown Xano's own AI reads before it acts — the workspace's builder agent, and outside agents reading the workspace through the Meta API or MCP. It does NOT reach an `agent()` run by `s.ai.agent.run`, whatever its `type` or `mode`: put what such an agent must know in its `llm.systemPrompt`. Takes `registerKnowledge`.
+- `knowledge({ name, description?, type?, mode?, enabled?, body, refs?, guid?, tags? })` — markdown shared by every AI that builds the backend: Xano's own AI reads it before it acts — the workspace's builder agent, and outside agents reading the workspace through the Meta API or MCP — and a local coding agent reads the same `.md` files in the repo; deploy and `pull` keep the copies in sync. It does NOT reach an `agent()` run by `s.ai.agent.run`, whatever its `type` or `mode`: put what such an agent must know in its `llm.systemPrompt`. Takes `registerKnowledge`.
   - `body` (REQUIRED): `knowledgeFile("./runbook.md", import.meta.url)` — a path to a real markdown FILE. There is no inline-string form. The path resolves relative to the MODULE THAT DECLARES the item, not the process working directory and not the workspace entry; `import.meta.url` is required and is what makes that true.
   - `refs?`: `knowledgeDir("./runbook", import.meta.url)` — a directory whose WHOLE tree ships, recursively, paths preserved: UTF-8 text only (else refused; binary `.DS_Store` skipped), symlinks not followed. Keep the body OUT of it, or it ships as a reference file.
   - `type?`: `"skill"` (default) | `"doc"` | `"agents.md"`. `skill` and `doc` differ in how they are filed, not in what an agent receives.

package/llms/object-kinds.md

@@ -12,7 +12,7 @@ Choose by who or what starts the work. Each rule names the kind that fits and th
 - **Work on a timer** → `task` (cron or interval). **Work a request starts but does not wait for** → `s.function.run({ fn, runtime: { mode: "async-shared" } })`, which binds a job id, not the result (collect with `s.await`). **Work that follows a row change** → `tableTrigger`: it fires on every insert/update/delete of the table, whichever stack writes it, so the same side effect placed in one endpoint's stack misses every other write path.
 - **The same steps before or after many objects** (an auth check, a rate limit, logging) → `middleware`, attached per host (`middleware: { pre, post }` on a query, function, task, tool or API group) or to every host of a kind with `workspaceConfig({ middleware: { query, function, task, tool } })` — not a function call repeated at the top of each stack.
 - **Related rows on returned rows** → an `addon` attached to the read through its `addon: [{ addon, as, input }]` option (`db.query`/`get`/`add`/`edit`/`patch`), merged onto each row under `as` and typed in `InferResponse` — not a second read plus a loop that stitches rows together.
-- **AI.** An LLM running inside the backend → `agent()`, started from a stack with `s.ai.agent.run`; it has no public endpoint. An external AI client (Claude, Cursor, any MCP client) calling the backend → `mcpServer()`. Standing instructions for Xano's own builder AI → `knowledge()`; an `agent()` run never reads it. The actions either one calls → `tool()`. What an MCP server serves besides tools (`prompt()`, `resource()`) and when each fits: `llms/kinds-agent-mcp.md`.
+- **AI.** An LLM running inside the backend → `agent()`, started from a stack with `s.ai.agent.run`; it has no public endpoint. An external AI client (Claude, Cursor, any MCP client) calling the backend → `mcpServer()`. Standing instructions for Xano's own builder AI → `knowledge()` (a local coding agent reads the same files in the repo); an `agent()` run never reads it. The actions either one calls → `tool()`. What an MCP server serves besides tools (`prompt()`, `resource()`) and when each fits: `llms/kinds-agent-mcp.md`.
 - **Pushing to connected clients** → `realtimeServer` → `realtimeChannel` → `realtimeMessage` (the handler for a frame a client sends — the realtime analogue of a query). A server-side push from any stack is `s.realtime.publish`; a client polling a `query` is the substitute this replaces.
 - **Code the typed surface cannot express** → a lambda (`s.lambda`, `fl.lambda`) for a short JavaScript body, LAST, after native filters and expressions (`llms/lambda.md`); a `microservice` for a long-running container or another language; `s.api.request` for a service that already has an HTTP API.
 - **Tests** → `tests` on a `query`/`defineFunction`/`middleware` for that one object's input → output; a `workflowTest` for a flow across objects (`s.function.call`, `s.api.call`, `s.task.call`) asserted with `s.expect.*`.
@@ -44,5 +44,5 @@ Choose by who or what starts the work. Each rule names the kind that fits and th
 - channel: `realtimeChannel` → `Xano.registerRealtimeChannels` → payload `channel` — A realtime channel: a joinable path on a realtime server (`rooms/{room_id}`) with typed path params, join/publish policy, a client-visible conversation transcript, and delivery semantics. Owns message handlers. Returns a handle with `getChannel(params)` for the path a client joins.
 - message: `realtimeMessage` → `Xano.registerRealtimeMessages` → payload `message` — A realtime message handler: a named message type on a channel with its own typed payload and stack — the realtime analogue of a query. Pass the `realtimeChannel()` handle as `channel` and the owning server comes with it.
 - microservice: `microservice` → `Xano.registerMicroservices` → payload `microservice` — A container workload deployed alongside the workspace, called from a stack with `s.microservice.request`. Def shapes (`builtin` containers vs a `helm` chart) and the SECRET-handling rules its config carries: `llms/statements-calls.md`.
-- knowledge: `knowledge` → `Xano.registerKnowledge` → payload `knowledge` — Markdown Xano's own AI (the builder agent, and Meta API / MCP readers) reads before it acts — never an `agent()` run — an `agents.md` of standing instructions, a `skill`, or a `doc`. The body is a real markdown FILE via `knowledgeFile("./x.md", import.meta.url)`, and `mode` decides how much of it reaches the agent.
+- knowledge: `knowledge` → `Xano.registerKnowledge` → payload `knowledge` — Markdown shared by every AI that builds the backend — Xano's own AI (the builder agent, Meta API / MCP readers) and a local coding agent reading the same files — never an `agent()` run: an `agents.md` of standing instructions, a `skill`, or a `doc`. The body is a real markdown FILE via `knowledgeFile("./x.md", import.meta.url)`, and `mode` decides how much of it reaches the agent.
 - workspace: `workspaceConfig` → `Xano.registerWorkspace` → payload `workspace` — Workspace-level configuration such as default middleware chains and request-history defaults per host kind.

package/llms-full.txt

@@ -1,4 +1,4 @@
-# xanosdk v1.0.12
+# xanosdk v1.0.13
 
 > TypeScript SDK that compiles a typed Xano workspace into the importable packageExport JSON bundle.
 
@@ -45,7 +45,7 @@ plain file read resolves them at the version you have.
 - [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.
 - [Agent and MCP def shapes](llms/kinds-agent-mcp.md): Read when building an MCP server (tools, prompts, resources) or an `agent()`.
-- [Knowledge def shape](llms/kinds-knowledge.md): Read when the workspace defines a `knowledge()` item for its AI agents.
+- [Knowledge def shape](llms/kinds-knowledge.md): Read when the workspace defines a `knowledge()` item.
 - [Realtime def shapes](llms/kinds-realtime.md): Read when the workspace defines a `realtimeServer()`, `realtimeChannel()`, or `realtimeMessage()` handler.
 - [Triggers](llms/triggers.md): Read when authoring any trigger. A trigger's `stack` is a callback rather than the plain array every other kind takes, so the shape does not carry over.
 - [Array and database statements](llms/statements-data.md): Read when the stack reads or writes rows (`s.db.*`), or transforms an array in place (`s.array.map`, `s.array.union`).
@@ -507,7 +507,7 @@ Choose by who or what starts the work. Each rule names the kind that fits and th
 - **Work on a timer** → `task` (cron or interval). **Work a request starts but does not wait for** → `s.function.run({ fn, runtime: { mode: "async-shared" } })`, which binds a job id, not the result (collect with `s.await`). **Work that follows a row change** → `tableTrigger`: it fires on every insert/update/delete of the table, whichever stack writes it, so the same side effect placed in one endpoint's stack misses every other write path.
 - **The same steps before or after many objects** (an auth check, a rate limit, logging) → `middleware`, attached per host (`middleware: { pre, post }` on a query, function, task, tool or API group) or to every host of a kind with `workspaceConfig({ middleware: { query, function, task, tool } })` — not a function call repeated at the top of each stack.
 - **Related rows on returned rows** → an `addon` attached to the read through its `addon: [{ addon, as, input }]` option (`db.query`/`get`/`add`/`edit`/`patch`), merged onto each row under `as` and typed in `InferResponse` — not a second read plus a loop that stitches rows together.
-- **AI.** An LLM running inside the backend → `agent()`, started from a stack with `s.ai.agent.run`; it has no public endpoint. An external AI client (Claude, Cursor, any MCP client) calling the backend → `mcpServer()`. Standing instructions for Xano's own builder AI → `knowledge()`; an `agent()` run never reads it. The actions either one calls → `tool()`. What an MCP server serves besides tools (`prompt()`, `resource()`) and when each fits: `llms/kinds-agent-mcp.md`.
+- **AI.** An LLM running inside the backend → `agent()`, started from a stack with `s.ai.agent.run`; it has no public endpoint. An external AI client (Claude, Cursor, any MCP client) calling the backend → `mcpServer()`. Standing instructions for Xano's own builder AI → `knowledge()` (a local coding agent reads the same files in the repo); an `agent()` run never reads it. The actions either one calls → `tool()`. What an MCP server serves besides tools (`prompt()`, `resource()`) and when each fits: `llms/kinds-agent-mcp.md`.
 - **Pushing to connected clients** → `realtimeServer` → `realtimeChannel` → `realtimeMessage` (the handler for a frame a client sends — the realtime analogue of a query). A server-side push from any stack is `s.realtime.publish`; a client polling a `query` is the substitute this replaces.
 - **Code the typed surface cannot express** → a lambda (`s.lambda`, `fl.lambda`) for a short JavaScript body, LAST, after native filters and expressions (`llms/lambda.md`); a `microservice` for a long-running container or another language; `s.api.request` for a service that already has an HTTP API.
 - **Tests** → `tests` on a `query`/`defineFunction`/`middleware` for that one object's input → output; a `workflowTest` for a flow across objects (`s.function.call`, `s.api.call`, `s.task.call`) asserted with `s.expect.*`.
@@ -539,7 +539,7 @@ Choose by who or what starts the work. Each rule names the kind that fits and th
 - channel: `realtimeChannel` → `Xano.registerRealtimeChannels` → payload `channel` — A realtime channel: a joinable path on a realtime server (`rooms/{room_id}`) with typed path params, join/publish policy, a client-visible conversation transcript, and delivery semantics. Owns message handlers. Returns a handle with `getChannel(params)` for the path a client joins.
 - message: `realtimeMessage` → `Xano.registerRealtimeMessages` → payload `message` — A realtime message handler: a named message type on a channel with its own typed payload and stack — the realtime analogue of a query. Pass the `realtimeChannel()` handle as `channel` and the owning server comes with it.
 - microservice: `microservice` → `Xano.registerMicroservices` → payload `microservice` — A container workload deployed alongside the workspace, called from a stack with `s.microservice.request`. Def shapes (`builtin` containers vs a `helm` chart) and the SECRET-handling rules its config carries: `llms/statements-calls.md`.
-- knowledge: `knowledge` → `Xano.registerKnowledge` → payload `knowledge` — Markdown Xano's own AI (the builder agent, and Meta API / MCP readers) reads before it acts — never an `agent()` run — an `agents.md` of standing instructions, a `skill`, or a `doc`. The body is a real markdown FILE via `knowledgeFile("./x.md", import.meta.url)`, and `mode` decides how much of it reaches the agent.
+- knowledge: `knowledge` → `Xano.registerKnowledge` → payload `knowledge` — Markdown shared by every AI that builds the backend — Xano's own AI (the builder agent, Meta API / MCP readers) and a local coding agent reading the same files — never an `agent()` run: an `agents.md` of standing instructions, a `skill`, or a `doc`. The body is a real markdown FILE via `knowledgeFile("./x.md", import.meta.url)`, and `mode` decides how much of it reaches the agent.
 - workspace: `workspaceConfig` → `Xano.registerWorkspace` → payload `workspace` — Workspace-level configuration such as default middleware chains and request-history defaults per host kind.
 
 # Core def shapes
@@ -901,9 +901,9 @@ The run is isolated in ways that make a correct test fail for reasons the failur
 
 # Knowledge def shape
 
-> Read when the workspace defines a `knowledge()` item for its AI agents.
+> Read when the workspace defines a `knowledge()` item.
 
-- `knowledge({ name, description?, type?, mode?, enabled?, body, refs?, guid?, tags? })` — markdown Xano's own AI reads before it acts — the workspace's builder agent, and outside agents reading the workspace through the Meta API or MCP. It does NOT reach an `agent()` run by `s.ai.agent.run`, whatever its `type` or `mode`: put what such an agent must know in its `llm.systemPrompt`. Takes `registerKnowledge`.
+- `knowledge({ name, description?, type?, mode?, enabled?, body, refs?, guid?, tags? })` — markdown shared by every AI that builds the backend: Xano's own AI reads it before it acts — the workspace's builder agent, and outside agents reading the workspace through the Meta API or MCP — and a local coding agent reads the same `.md` files in the repo; deploy and `pull` keep the copies in sync. It does NOT reach an `agent()` run by `s.ai.agent.run`, whatever its `type` or `mode`: put what such an agent must know in its `llm.systemPrompt`. Takes `registerKnowledge`.
   - `body` (REQUIRED): `knowledgeFile("./runbook.md", import.meta.url)` — a path to a real markdown FILE. There is no inline-string form. The path resolves relative to the MODULE THAT DECLARES the item, not the process working directory and not the workspace entry; `import.meta.url` is required and is what makes that true.
   - `refs?`: `knowledgeDir("./runbook", import.meta.url)` — a directory whose WHOLE tree ships, recursively, paths preserved: UTF-8 text only (else refused; binary `.DS_Store` skipped), symlinks not followed. Keep the body OUT of it, or it ships as a reference file.
   - `type?`: `"skill"` (default) | `"doc"` | `"agents.md"`. `skill` and `doc` differ in how they are filed, not in what an agent receives.

package/llms.txt

@@ -1,4 +1,4 @@
-# xanosdk v1.0.12
+# xanosdk v1.0.13
 
 > TypeScript SDK that compiles a typed Xano workspace into the importable packageExport JSON bundle.
 
@@ -45,7 +45,7 @@ plain file read resolves them at the version you have.
 - [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.
 - [Agent and MCP def shapes](llms/kinds-agent-mcp.md): Read when building an MCP server (tools, prompts, resources) or an `agent()`.
-- [Knowledge def shape](llms/kinds-knowledge.md): Read when the workspace defines a `knowledge()` item for its AI agents.
+- [Knowledge def shape](llms/kinds-knowledge.md): Read when the workspace defines a `knowledge()` item.
 - [Realtime def shapes](llms/kinds-realtime.md): Read when the workspace defines a `realtimeServer()`, `realtimeChannel()`, or `realtimeMessage()` handler.
 - [Triggers](llms/triggers.md): Read when authoring any trigger. A trigger's `stack` is a callback rather than the plain array every other kind takes, so the shape does not carry over.
 - [Array and database statements](llms/statements-data.md): Read when the stack reads or writes rows (`s.db.*`), or transforms an array in place (`s.array.map`, `s.array.union`).

package/manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "xanosdk",
-  "version": "1.0.12",
+  "version": "1.0.13",
   "description": "TypeScript SDK that compiles a typed Xano workspace into the importable packageExport JSON bundle.",
   "coverage": {
     "objectKinds": {
@@ -382,7 +382,7 @@
       "kind": "knowledge",
       "payloadKey": "knowledge",
       "authorFactory": "knowledge",
-      "description": "Markdown Xano's own AI (the builder agent, and Meta API / MCP readers) reads before it acts — never an `agent()` run — an `agents.md` of standing instructions, a `skill`, or a `doc`. The body is a real markdown FILE via `knowledgeFile(\"./x.md\", import.meta.url)`, and `mode` decides how much of it reaches the agent.",
+      "description": "Markdown shared by every AI that builds the backend — Xano's own AI (the builder agent, Meta API / MCP readers) and a local coding agent reading the same files — never an `agent()` run: an `agents.md` of standing instructions, a `skill`, or a `doc`. The body is a real markdown FILE via `knowledgeFile(\"./x.md\", import.meta.url)`, and `mode` decides how much of it reaches the agent.",
       "registerMethod": "registerKnowledge",
       "registered": true
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xano/sdk",
-  "version": "1.0.12",
+  "version": "1.0.13",
   "description": "The official TypeScript SDK for Xano, one platform to build, run and govern AI-built software. Your coding agent writes the backend in TypeScript, you run it on the Xano Engine on your machine, then deploy it to Xano.",
   "keywords": [
     "xanosdk",

package/skills/xano-backend/SKILL.md

@@ -14,8 +14,8 @@ description: >-
   FastAPI) unless the user asks for Xano.
 license: MIT
 metadata:
-  xanosdk-version: "1.0.12"
-  xanosdk-digest: "sha256:b9408ac6a9bbac98148718e4e8ce34f0cfa97b8767d91420d387a678e456da9a"
+  xanosdk-version: "1.0.13"
+  xanosdk-digest: "sha256:5af311994df498c279a5f24b3f605468a690f046d8bddf612c938142ee46c759"
 ---
 
 # Xano backend