@xanots/sdk 0.0.3 → 0.0.5

package/guides/typed-frontend.md

@@ -0,0 +1,201 @@
+# The typed frontend surface
+
+Every type and helper a frontend gets from a deployed def — path resolution, input and response inference, and the two ways to pay for it.
+
+## Endpoint names, path params, and encoding
+
+- **URL path params** → name the endpoint with `{param}` segments and declare an input per
+  segment. `getPath({ params })` fills them, with the keys typed from the name itself:
+
+  ```ts
+  const getPost = query({
+    name: "blog/{slug}/review/{review_id}",       // segments chain; no wildcards
+    verb: "GET",
+    apiGroup: api,
+    input: { slug: input.text(), review_id: input.int(), verbose: input.bool() },
+    stack: [s.db.get({ table: post, fieldName: "slug", fieldValue: inp("slug"), as: "row" })],
+    response: ref("row"),
+  });
+
+  getPost.getPath({ params: { slug: "hello", review_id: 7 } });
+  // → "/api:<canonical>/blog/hello/review/7"
+  getPost.toSearchParams({ verbose: true });      // → "verbose=true" (path params dropped)
+  ```
+
+  Every `{param}` must have a matching input or `query()` throws — Xano treats an unbound
+  marker as inert route text, so the endpoint would answer on the path and see nothing.
+  Inputs that aren't in the path (`verbose`) stay ordinary query-string params. Never
+  interpolate the path by hand: `getPath` percent-encodes each value, so a `?`, `#` or space
+  stays inside its segment instead of restructuring the URL, and it throws on the two values
+  encoding can't contain — one holding `/`, and one that *is* `.` or `..` (a URL parser drops
+  those before routing, addressing a different endpoint). `realtimeChannel()` paths work
+  identically, minus the encoding: a channel address is matched literally, not parsed as a URL.
+- **`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
+  trip. It auto-derives the common shapes with no codegen: an object-literal response yields
+  those keys, and a query that returns a variable filled by a db op derives that op's result —
+  the full row for `db.add`/`db.edit`/`db.patch`/`db.add_or_edit` (→ `Row` — each binds the
+  full written row rather than null, so it stays non-nullable; a genuine miss throws instead of
+  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
+  (`output: ["id", "meta.url"]`, on a statement or an addon); the narrowing keys off the
+  path's root, since an object column's sub-keys aren't declared in the schema.
+  Where the shape isn't statically knowable — a value reshaped by a filter/lambda, built by
+  control flow, or from an op the engine itself leaves untyped (`db.del`, `db.bulk.add`/`bulk.update`,
+  raw `direct_query`) — it resolves to `unknown`; declare `responseShape` to close it.
+  In an object-literal response the **keys** are always known, but a **value** is typed only
+  when it traces to a binding: `response: { success: c.bool(true) }` derives
+  `{ success: unknown }`, not `{ success: boolean }`. A constant carries no reference to
+  follow. Reach for `responseShape` when a client needs those keys typed.
+  A **nested** member resolves by those same rules, to any depth, in either spelling —
+  `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
+  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
+  the **target** fixes every caller at once. A target named by *string* has no def to read and
+  stays `unknown`, as does an async `s.function.run` (it binds a job handle, not the result).
+  The same derivation runs on every response-bearing kind — `query()`, `defineFunction()`,
+  `realtimeMessage()`, `tool()`, `middleware()`, and the response-bearing triggers — and each
+  of them takes `responseShape`. A trigger builds its stack and response through *callbacks*
+  (`stack: (t) => [...]`), and the trace follows through them. This matters most where a
+  handler's response is the only type a client has: a realtime message's broadcast payload,
+  or a channel `deliver` trigger's return, which is that recipient's copy of the message.
+
+```ts
+import { listPosts, getPost } from "../xano/index.js";
+import type { InferResponse } from "@xanots/sdk";
+
+type Posts = InferResponse<typeof listPosts>;   // Post[]      — derived from the db.query it returns
+type Post  = InferResponse<typeof getPost>;      // Post | null — a db.get misses to null
+```
+
+For a **computed or multi-key object response**, author it as a *record of values* —
+`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
+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)`).
+
+When a response is filtered, computed, or otherwise opaque to the static walk, declare it once
+on the query and every caller derives from that single source of truth:
+
+```ts
+const getPost = query({
+  verb: "GET", apiGroup: blog, name: "get_post",
+  input: { id: input.int({ required: true }) },
+  stack: [s.db.query({ table: post, where: expr(col("id"), "=", inp("id")), as: "rows" })],
+  // A filtered response is opaque to the static walk, so derivation is `unknown`.
+  response: withFilters(ref("rows"), fl.first()),
+  responseShape: null as InferRow<typeof post> | null,   // declare the real shape once
+});
+type MaybePost = InferResponse<typeof getPost>;           // InferRow<typeof post> | null
+```
+
+(A plain `response: ref("row")` off a `s.db.get` needs no `responseShape` — it already
+derives `InferRow<typeof post> | null`, since `db.get` misses to `null`.)
+
+**Factoring statements into a helper.** The trace walks the stack's *tuple*, so spreading a
+helper typed `Statement[]` widens the stack and nothing in it resolves any more — the response
+types as `StackTupleWidened`, which names the cause. Return `statements(...)` from the helper
+and the tuple survives the spread:
+
+```ts
+import { statements } from "@xanots/sdk";
+
+function assertOk(v: string) {                 // no `: Statement[]` annotation
+  return statements(s.lambda({ ... }), s.precondition({ ... }));
+}
+
+stack: [...assertOk("res"), s.db.add({ table: post, row, as: "created" })],
+response: ref("created"),                      // still traced
+```
+
+Fixed arity only — a helper that builds its array in a loop can't be a tuple, so declare
+`responseShape` there.
+
+This mirrors how the Xano engine itself derives an endpoint's response schema (a static walk of
+the stack), so what you get in the type is what the endpoint actually returns — and it degrades
+to `unknown` in exactly the cases the engine can't resolve either.
+
+A GET endpoint carries its inputs in the query string rather than a JSON body:
+
+```ts
+import { getSnippet } from "../xano/index.js";
+import { query, type InferInput } from "@xanots/sdk";
+
+const BASE = "https://your-instance.xano.io";
+
+async function fetchSnippet(id: number) {
+  const params = { id } satisfies InferInput<typeof getSnippet>;   // { id: number }
+  const res = await fetch(`${BASE}${getSnippet.getPath()}?${query.toSearchParams(params)}`);
+  return res.json();
+}
+```
+
+The `@xanots/sdk` entry has **zero Node dependencies**, so importing your workspace
+graph into a browser bundle just works. The `node:fs`-backed emitters live in the
+separate `@xanots/sdk/node` entry a frontend never pulls in.
+
+## Bundle size, and the route manifest
+
+**Bundle size & tree-shaking.** `@xanots/sdk` is `sideEffects: false`, so a bundler drops
+the SDK exports your frontend doesn't use. But importing a query **def** for its `getPath()`
+also pulls whatever its `stack` builds — the `s.*`/`c.*` factory *calls* run at module load
+to construct the def, so they can't be tree-shaken out. Types are free (`InferInput`/
+`InferRow` erase to nothing — use `import type`). That cost is a **floor**, not a function of
+how lean the def is. Measured on a Vite lib build against the published package: one
+`apiGroup` + one empty `query`, imported for a single `getPath()`, is **289 kB minified
+(57 kB gzipped)** against 56 B for a hand-written path string. A realistic def — two
+tables, a foreign key, a typed input, a `db.query` with a `where` and a sort, plus a
+second endpoint — measures 290 kB. That 1 kB spread is the point: the floor is the SDK
+runtime itself, so splitting modules or simplifying a def does not move it, and the cost
+is paid by importing any def at all.
+
+**Generate a route manifest instead.** It keeps the derived-not-hardcoded contract at
+almost no bundle cost:
+
+```bash
+xanots paths ./xano/index.ts --emit xano/routes.gen.ts
+```
+
+The emitted file is plain data plus one interpolator and imports nothing at all — the same
+app builds to 1.3 kB, a 214x saving, with no SDK code in the output. Route names and their `{param}` keys are still checked at compile
+time, so a backend rename is a compile error rather than a 404:
+
+```ts
+import { routePath, ROUTES } from "../xano/routes.gen";
+
+fetch(BASE + routePath("blog/{slug}", { slug }), { method: ROUTES["blog/{slug}"].verb });
+```
+
+Realtime is in the same file when the workspace has any: `socketUrl(server, baseUrl)` for the
+websocket URL and `channelPath(channel, params)` for the path a frame's `channel` field takes,
+both keyed and `{param}`-checked exactly like the routes. `socketUrl` is the equivalent of
+`realtimeServer().getUrl()` down to the tenant rule — a base URL that names a tenant
+(`https://host/tenant/ab-cd`, what deploy injects as `window.XANO_HOST`) is rewritten to the
+socket's own `wss://host/ws/ab-cd:<canonical>` form, which is the one address a frontend has no
+way to reconstruct. Resolve once, from the `https://` base — feeding a resolved socket URL back
+in as a `baseUrl` throws rather than append a second `/ws/…`:
+
+```ts
+import { socketUrl, channelPath } from "../xano/routes.gen";
+
+const ws = new WebSocket(socketUrl("chat", window.XANO_HOST), token);
+ws.send(JSON.stringify({ action: "join", channel: channelPath("rooms/{room_id}", { room_id }) }));
+```
+
+Add `--strict` in CI to fail when the committed manifest is out of date. A hand-typed
+`ROUTES` table is the option that gives up both the bundle saving and the rename safety.

package/llms/kinds-knowledge.md

@@ -0,0 +1,20 @@
+# Knowledge def shape
+
+> Read when the workspace defines a `knowledge()` item — the markdown its AI agents read.
+
+- `knowledge({ name, description?, type?, mode?, enabled?, body, refs?, guid?, tags? })` — markdown the workspace's AI agents read before they act. 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 as reference files, recursively, POSIX-relative paths preserved. Keep the body OUT of that directory: everything under it is collected, so a body beside its refs would ship as one of its own reference files.
+  - `type?`: `"skill"` (default) | `"doc"` | `"agents.md"`. `skill` and `doc` differ in how they are filed, not in what an agent receives.
+  - `mode?`: `"auto"` (default) | `"always"` | `"referenced"`.
+  - `enabled?` defaults `true`. A disabled item is stored and never reaches an agent.
+
+### What reaches the agent
+
+- `type: "agents.md"` — full body on EVERY turn, whatever `mode` says. At most ONE per workspace; a second is an export error. Setting `mode` on one warns, because nothing reads it.
+- `mode: "always"` — full body on every turn.
+- `mode: "referenced"` — full body only on turns whose message names the item (bare name or `@name`).
+- `mode: "auto"` — name and `description` only; the agent loads the body when a request matches.
+- Reference files are never injected wholesale — an agent searches them on demand. That is what makes a large `mode: "auto"` item cheap.
+- ⚠ `mode: "always"` on a long body spends its whole length on every request, and nothing in the types says so. `"auto"` is the default for that reason. For an `auto` item `description` is ALL the agent sees until it decides to load the body, so write it to be matched against a request rather than as a title.
+- `name` takes letters, digits, and `/ _ - { } . ` or a space; anything else is an export error.

package/llms/object-kinds.md

@@ -28,4 +28,5 @@ Author with the factory, register on the Xano instance, lands under the payload
 - 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`. Two mutually exclusive shapes via `kind`: `builtin` declares containers (image/ports/resources/env/command/args) plus optional `ingresses`, and `helm` points at a chart and its `values` — passing both throws. EARLY SURFACE, expected to change — every export of a workspace declaring one prints a notice saying so. `configs`/`volumes` are typed and `@deprecated` but NOT deployable: the engine rejects an import carrying either, so `export()` fails the build rather than letting the deploy fatal. Put a value the workload reads in a container's `env`, and storage in a container's own `volumes` (`emptyDir`/`persistent`/`config`). Container names are free-form — they need not match the microservice name, which is what a stack addresses. SECRETS RIDE ALONG — `chart.values` and `registryAuth.dockerconfigjson` are carried into the bundle, and into a pulled tree, verbatim (they must be, or a pulled microservice could not be redeployed). Both are stored strings with NO deploy-time indirection: `process.env.X` in the def resolves at EXPORT and writes the literal into the bundle, so it is not a way to keep the credential out. Either leave `registryAuth` unset (public image, or a credential attached outside this workspace) or treat the bundle and any pulled tree as secret material — keep them out of git, or rotate after. Export prints a notice per microservice carrying either field; `--strict` does not promote it. For a secret a STACK reads, the mapped surface is `workspaceConfig({ env })` + `env("NAME")`.
+- knowledge: `knowledge` → `Xano.registerKnowledge` → payload `knowledge` — Markdown the workspace's AI agents read before they act — 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 @@
-# xanots v0.0.3
+# xanots v0.0.5
 
 > TypeScript SDK that compiles a typed Xano workspace into the importable packageExport JSON bundle.
 
@@ -6,7 +6,7 @@ Author a Xano workspace in TypeScript: build typed objects, register them on a
 `new Xano()` instance, and call `.export()` to get one importable bundle. Compile
 with `xanots export ./xano/index.js`.
 
-Coverage: object kinds 24/30, statement surfaces 214/214, filters 226 (226 typed).
+Coverage: object kinds 25/31, statement surfaces 214/214, filters 226 (226 typed).
 Not authorable here: branch, market_item, realtime_channel, run.job, run.service, tablemap — these cannot be authored and do not survive a pull; see `coverage.objectKinds.unmodeled` in `manifest.json`.
 
 This file is the whole always-read surface: the mental model, the deploy contract,
@@ -32,6 +32,7 @@ that wants one fetch, not for an agent that can open the two files it needs.
 - [Core def shapes](llms/kinds-core.md): Read when authoring a function, query, api group, task, workflow test, middleware, or tool — and for the `response` and `expr` shapes every one of them uses.
 - [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 should mock a value, or when running a deployed environment's tests.
 - [Agent and MCP def shapes](llms/kinds-agent-mcp.md): Read when the workspace defines an `agent()` or an `mcpServer()`.
+- [Knowledge def shape](llms/kinds-knowledge.md): Read when the workspace defines a `knowledge()` item — the markdown its AI agents read.
 - [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`).
@@ -512,6 +513,7 @@ Author with the factory, register on the Xano instance, lands under the payload
 - 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`. Two mutually exclusive shapes via `kind`: `builtin` declares containers (image/ports/resources/env/command/args) plus optional `ingresses`, and `helm` points at a chart and its `values` — passing both throws. EARLY SURFACE, expected to change — every export of a workspace declaring one prints a notice saying so. `configs`/`volumes` are typed and `@deprecated` but NOT deployable: the engine rejects an import carrying either, so `export()` fails the build rather than letting the deploy fatal. Put a value the workload reads in a container's `env`, and storage in a container's own `volumes` (`emptyDir`/`persistent`/`config`). Container names are free-form — they need not match the microservice name, which is what a stack addresses. SECRETS RIDE ALONG — `chart.values` and `registryAuth.dockerconfigjson` are carried into the bundle, and into a pulled tree, verbatim (they must be, or a pulled microservice could not be redeployed). Both are stored strings with NO deploy-time indirection: `process.env.X` in the def resolves at EXPORT and writes the literal into the bundle, so it is not a way to keep the credential out. Either leave `registryAuth` unset (public image, or a credential attached outside this workspace) or treat the bundle and any pulled tree as secret material — keep them out of git, or rotate after. Export prints a notice per microservice carrying either field; `--strict` does not promote it. For a secret a STACK reads, the mapped surface is `workspaceConfig({ env })` + `env("NAME")`.
+- knowledge: `knowledge` → `Xano.registerKnowledge` → payload `knowledge` — Markdown the workspace's AI agents read before they act — 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
@@ -655,6 +657,27 @@ The run is isolated in ways that make a correct test fail for reasons the failur
   - **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({ name, value: 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 }}`. Tool-call / per-step data (when tools ran) rides `.toolCalls` / `.steps` on the same envelope — both optional, absent or empty when no tools executed.
   - **Marketplace:** for chat history, use `@xanots/chatbot`; for vector RAG, use `@xanots/vector` (`tools: [vector.searchTool]`). Find add-ons with `xanots marketplace search <q>`.
 
+# Knowledge def shape
+
+> Read when the workspace defines a `knowledge()` item — the markdown its AI agents read.
+
+- `knowledge({ name, description?, type?, mode?, enabled?, body, refs?, guid?, tags? })` — markdown the workspace's AI agents read before they act. 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 as reference files, recursively, POSIX-relative paths preserved. Keep the body OUT of that directory: everything under it is collected, so a body beside its refs would ship as one of its own reference files.
+  - `type?`: `"skill"` (default) | `"doc"` | `"agents.md"`. `skill` and `doc` differ in how they are filed, not in what an agent receives.
+  - `mode?`: `"auto"` (default) | `"always"` | `"referenced"`.
+  - `enabled?` defaults `true`. A disabled item is stored and never reaches an agent.
+
+### What reaches the agent
+
+- `type: "agents.md"` — full body on EVERY turn, whatever `mode` says. At most ONE per workspace; a second is an export error. Setting `mode` on one warns, because nothing reads it.
+- `mode: "always"` — full body on every turn.
+- `mode: "referenced"` — full body only on turns whose message names the item (bare name or `@name`).
+- `mode: "auto"` — name and `description` only; the agent loads the body when a request matches.
+- Reference files are never injected wholesale — an agent searches them on demand. That is what makes a large `mode: "auto"` item cheap.
+- ⚠ `mode: "always"` on a long body spends its whole length on every request, and nothing in the types says so. `"auto"` is the default for that reason. For an `auto` item `description` is ALL the agent sees until it decides to load the body, so write it to be matched against a request rather than as a title.
+- `name` takes letters, digits, and `/ _ - { } . ` or a space; anything else is an export error.
+
 # Realtime def shapes
 
 > Read when the workspace defines a `realtimeServer()`, `realtimeChannel()`, or `realtimeMessage()` handler.

package/llms.txt

@@ -1,4 +1,4 @@
-# xanots v0.0.3
+# xanots v0.0.5
 
 > TypeScript SDK that compiles a typed Xano workspace into the importable packageExport JSON bundle.
 
@@ -6,7 +6,7 @@ Author a Xano workspace in TypeScript: build typed objects, register them on a
 `new Xano()` instance, and call `.export()` to get one importable bundle. Compile
 with `xanots export ./xano/index.js`.
 
-Coverage: object kinds 24/30, statement surfaces 214/214, filters 226 (226 typed).
+Coverage: object kinds 25/31, statement surfaces 214/214, filters 226 (226 typed).
 Not authorable here: branch, market_item, realtime_channel, run.job, run.service, tablemap — these cannot be authored and do not survive a pull; see `coverage.objectKinds.unmodeled` in `manifest.json`.
 
 This file is the whole always-read surface: the mental model, the deploy contract,
@@ -32,6 +32,7 @@ that wants one fetch, not for an agent that can open the two files it needs.
 - [Core def shapes](llms/kinds-core.md): Read when authoring a function, query, api group, task, workflow test, middleware, or tool — and for the `response` and `expr` shapes every one of them uses.
 - [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 should mock a value, or when running a deployed environment's tests.
 - [Agent and MCP def shapes](llms/kinds-agent-mcp.md): Read when the workspace defines an `agent()` or an `mcpServer()`.
+- [Knowledge def shape](llms/kinds-knowledge.md): Read when the workspace defines a `knowledge()` item — the markdown its AI agents read.
 - [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,11 +1,11 @@
 {
   "name": "xanots",
-  "version": "0.0.3",
+  "version": "0.0.5",
   "description": "TypeScript SDK that compiles a typed Xano workspace into the importable packageExport JSON bundle.",
   "coverage": {
     "objectKinds": {
-      "implemented": 24,
-      "total": 30,
+      "implemented": 25,
+      "total": 31,
       "unmodeled": [
         {
           "kind": "branch",
@@ -361,6 +361,14 @@
       "registerMethod": "registerMicroservices",
       "registered": true
     },
+    {
+      "kind": "knowledge",
+      "payloadKey": "knowledge",
+      "authorFactory": "knowledge",
+      "description": "Markdown the workspace's AI agents read before they act — 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
+    },
     {
       "kind": "workspace",
       "payloadKey": "workspace",
@@ -9068,9 +9076,13 @@
           "flag": "--local",
           "description": "Use the project-local ./.xano/auth.json instead of the shared cache"
         },
+        {
+          "flag": "--paste",
+          "description": "Sign in without the loopback callback: open the printed URL in any browser and paste the redirect back. For a host whose 127.0.0.1 the browser cannot reach — remote shell, container, Codespace. Needs a terminal."
+        },
         {
           "flag": "--port <n>",
-          "description": "Fixed loopback callback port (default: ephemeral)"
+          "description": "Loopback callback port (default: 47100)"
         },
         {
           "flag": "--scope \"<list>\"",
@@ -9134,6 +9146,11 @@
       "args": "<string>",
       "description": "Search add-ons by keyword across name, tagline and description"
     },
+    {
+      "command": "onboard",
+      "args": "[dir]",
+      "description": "Pick a framework, theme and add-ons in a browser, then scaffold"
+    },
     {
       "command": "paths",
       "args": "<file>",
@@ -9507,6 +9524,16 @@
       ],
       "description": "Run every test in an environment and report pass/fail"
     },
+    {
+      "command": "upgrade",
+      "flags": [
+        {
+          "flag": "--check",
+          "description": "Report whether an upgrade is available and exit 7, without installing it"
+        }
+      ],
+      "description": "Install the latest @xanots/sdk, or report an available upgrade with --check"
+    },
     {
       "command": "validate",
       "args": "<file>",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xanots/sdk",
-  "version": "0.0.3",
+  "version": "0.0.5",
   "description": "XanoTS — your Xano backend as TypeScript. `xanots 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": [
     "xanots",
@@ -61,7 +61,9 @@
     "llms.txt",
     "llms-full.txt",
     "llms",
-    "README.md"
+    "guides",
+    "README.md",
+    "CHANGELOG.md"
   ],
   "scripts": {
     "build": "tsup",
@@ -78,6 +80,7 @@
     "audit:output-flag": "tsx scripts/audit-output-flag.ts",
     "audit:decode-coverage": "tsx scripts/audit-decode-coverage.ts",
     "manifest": "tsx scripts/manifest.ts",
+    "changelog": "tsx scripts/changelog.ts",
     "measure:llms": "tsx scripts/measure-llms.ts",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",

package/dist/chunk-WUSKBXXD.js

@@ -1,25 +0,0 @@
-// src/emit/npm.ts
-import { spawnSync } from "child_process";
-function npmBinary() {
-  return process.platform === "win32" ? "npm.cmd" : "npm";
-}
-function runNpm(args, cwd) {
-  const res = spawnSync(npmBinary(), [...args], { cwd, stdio: "inherit" });
-  return res.status ?? 1;
-}
-function runNpmCapturingStderr(args, cwd) {
-  const res = spawnSync(npmBinary(), [...args], {
-    cwd,
-    stdio: ["inherit", "inherit", "pipe"],
-    encoding: "utf8"
-  });
-  const stderr = res.stderr ?? "";
-  if (stderr !== "") process.stderr.write(stderr);
-  return { status: res.status ?? 1, stderr };
-}
-
-export {
-  runNpm,
-  runNpmCapturingStderr
-};
-//# sourceMappingURL=chunk-WUSKBXXD.js.map

package/dist/chunk-ZO3HJOCJ.js

@@ -1,29 +0,0 @@
-import {
-  UsageError
-} from "./chunk-6USV65XA.js";
-import {
-  style
-} from "./chunk-EZG76F7R.js";
-
-// src/emit/prompt.ts
-import { createInterface } from "readline";
-async function confirm(message, opts) {
-  if (process.stdin.isTTY !== true) {
-    throw new UsageError(
-      `Cannot ask for confirmation: stdin is not a terminal. Re-run with ${opts.flag} to confirm without being asked.`,
-      { helpFor: opts.helpFor }
-    );
-  }
-  const rl = createInterface({ input: process.stdin, output: process.stderr });
-  try {
-    const answer = await new Promise((res) => rl.question(`${style.yellow("?")} ${message} (y/N) `, res));
-    return /^y(es)?$/i.test(answer.trim());
-  } finally {
-    rl.close();
-  }
-}
-
-export {
-  confirm
-};
-//# sourceMappingURL=chunk-ZO3HJOCJ.js.map

package/dist/codegen-command-FIADGXRN.js

@@ -1,42 +0,0 @@
-import {
-  blameGeneratedFile,
-  fetchWorkspaceBundle,
-  isMissingDependencyError,
-  runCodegenCommand,
-  verifyCrashEntry
-} from "./chunk-2V4YE6QC.js";
-import "./chunk-P3TTMWUP.js";
-import "./chunk-QTNO2WD6.js";
-import "./chunk-ZUTSMMAG.js";
-import "./chunk-HQ2CBRVI.js";
-import "./chunk-CMZLPTGW.js";
-import "./chunk-WUSKBXXD.js";
-import "./chunk-3IGNIP6R.js";
-import "./chunk-C56BC2FY.js";
-import "./chunk-7REDODS2.js";
-import "./chunk-X4DVXBFY.js";
-import "./chunk-F6JCFRKO.js";
-import "./chunk-LU7TRWMC.js";
-import "./chunk-YZ4GU6F5.js";
-import "./chunk-6DHJVLYP.js";
-import "./chunk-4BXJGVZ3.js";
-import "./chunk-U3G2UW65.js";
-import "./chunk-3NFUWXOC.js";
-import "./chunk-6USV65XA.js";
-import "./chunk-HJPTWBLH.js";
-import "./chunk-EZG76F7R.js";
-import "./chunk-GNPVYOPB.js";
-import "./chunk-55VHDNW5.js";
-import "./chunk-DYCLVQXW.js";
-import "./chunk-5L4X5LS6.js";
-import "./chunk-WHOJWOSV.js";
-import "./chunk-5XZ744TS.js";
-import "./chunk-4HT3BNZ7.js";
-export {
-  blameGeneratedFile,
-  fetchWorkspaceBundle,
-  isMissingDependencyError,
-  runCodegenCommand,
-  verifyCrashEntry
-};
-//# sourceMappingURL=codegen-command-FIADGXRN.js.map

package/dist/init-command-LOK75W64.js

@@ -1,29 +0,0 @@
-import {
-  projectShellFiles,
-  runInitCommand,
-  sanitizeAppName
-} from "./chunk-HQ2CBRVI.js";
-import {
-  resolveAiFlags
-} from "./chunk-CMZLPTGW.js";
-import "./chunk-WUSKBXXD.js";
-import "./chunk-YZ4GU6F5.js";
-import "./chunk-6DHJVLYP.js";
-import "./chunk-3NFUWXOC.js";
-import "./chunk-6USV65XA.js";
-import "./chunk-HJPTWBLH.js";
-import "./chunk-EZG76F7R.js";
-import "./chunk-GNPVYOPB.js";
-import "./chunk-55VHDNW5.js";
-import "./chunk-DYCLVQXW.js";
-import "./chunk-5L4X5LS6.js";
-import "./chunk-WHOJWOSV.js";
-import "./chunk-5XZ744TS.js";
-import "./chunk-4HT3BNZ7.js";
-export {
-  projectShellFiles,
-  resolveAiFlags,
-  runInitCommand,
-  sanitizeAppName
-};
-//# sourceMappingURL=init-command-LOK75W64.js.map