@xano/sdk 1.0.0

package/guides/scaffold.md

@@ -0,0 +1,351 @@
+# The scaffolded project
+
+What `xanosdk init` writes, the two frontend presets, theming, add-ons, and the SvelteKit prerendering rules.
+
+## init flags and add-ons
+
+`init` flags: `--framework <react|svelte>` (default: `react`), `--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),
+`--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`.
+The starter backend is empty but already compiles and deploys — grow it from the
+walkthrough in `xano/EXAMPLE.md`.
+
+A scaffold ships `@xano/sdk` and nothing else from the `@xano-sdk` scope. Add-ons
+install on demand:
+
+```bash
+xanosdk marketplace list                      # every published add-on
+xanosdk marketplace search auth               # …or narrow by keyword
+xanosdk marketplace details @xano-sdk/auth      # what it installs + how to register it
+xanosdk marketplace install @xano-sdk/auth      # add it to the project you're in
+```
+
+The three read verbs hit a public catalogue, so they work before you log in.
+Every add-on is optional and none is assumed by anything in the scaffold —
+install one when you need it. [The marketplace](marketplace.md) covers all six
+verbs, what each one does to a project, and how an add-on is configured.
+
+`init` takes the same package names, so a project can be scaffolded with its
+add-ons already wired:
+
+```bash
+xanosdk init my-app --framework react --marketplace @xano-sdk/auth,@xano-sdk/vector
+```
+
+That installs each package **and** writes its registration into `xano/index.ts`.
+Installing alone would leave dependencies nothing imports — a different project
+wearing the same name. A module declares how it registers in its own
+`package.json` (`"xanosdk": { "register": "registerAuth" }`); one that has not
+adopted the field is read for a single `register*` export, and two of those
+without the field is a refusal rather than a guess.
+
+The field is also where a module declares what its register call needs
+(`"options"`). An add-on whose call takes an option nothing has declared — a URL
+into your own frontend, your own role model — is installed but left
+**unregistered**, named in `xano/index.ts` with the call to uncomment once you
+have the value. A scaffold that compiles with an add-on switched off beats one
+that does not compile at all.
+
+Each `--marketplace` name is resolved through the marketplace first, exactly as
+`xanosdk marketplace install` resolves it: a module's package or its slug
+(`--marketplace auth` installs `@xano-sdk/auth`, never npm's unrelated `auth`). A
+name the marketplace does not list stops `init` with **exit 8** before it writes
+anything. So does a package name the npm registry does not have — the same rule
+`--framework` and `--theme` follow, so a typo costs nothing and leaves nothing to
+clean up. The check asks about the NAME, from the
+directory the install will run in, so it reads the same `.npmrc` the install
+does. (A package published minutes ago can 404 until the registry replicates
+it; if the name is right, retry.) A version or tag that does not resolve is not
+its business — that falls through to the install, whose error says which.
+A local path (`./my-module`, `file:../my-module`) is read from where you typed it.
+Under `--no-install` only a directory holding a `package.json` can be recorded (as
+`file:`); a tarball, URL or git spec is refused, since its name is unknown until installed.
+
+An install that fails for any other reason — an unreachable registry, a proxy —
+is not fatal: the scaffold is written without that add-on, npm's own diagnosis
+is printed, and the run ends on `Project ready, without 1 add-on.` with **exit
+code 2**. The project is usable; add the missing package with `xanosdk
+marketplace install <package>`. `--from` and `--marketplace` do not compose, and
+saying both is a usage error rather than a silently add-on-less project.
+
+When the project's OWN `npm install` fails (with or without add-ons), `init` also
+exits **2**: every file is written and correct, but nothing in the project can be
+loaded until its dependencies are, so the run does not end on `Project ready.`.
+Fix what npm reported and run `npm install` in the project — nothing needs to be
+scaffolded again.
+
+Declaring `"options"` is all or nothing: it states what the whole argument is,
+and is taken at its word without the function being read. A module that needs an
+option only you can answer omits the key rather than declaring the rest, which is
+what lets the CLI find the argument and leave the module out.
+
+`@xano-sdk/auth` is **authentication, not authorization** — user/login/signup
+tables and the endpoints over them. It ships no roles, permissions, or route
+guards, so it is not the RBAC answer. Its `user` table has a `role` column, but
+the tokens it mints carry no role claim, so a check on the token finds nothing.
+Check the caller's row instead: spread `...guard.role(userTable, "admin")` into
+the stack of each query whose `auth` is `userTable`. It loads the caller's row,
+rejects a missing one (401), then checks the role (403).
+
+`details` is the one to reach for when wiring an add-on: it prints the objects
+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.
+
+## 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).
+
+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
+over a contributor's `core.autocrlf` rather than over a real change.
+
+The workflow installs with the project's package manager (npm, pnpm, yarn or bun, as
+`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
+`--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.
+`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
+`xano/xano.lock`) for an add-on that brings endpoints, so each of those passes the check
+as it stands. It installs with
+`npm ci` whenever a lockfile is committed, since `package.json` allows a
+`@xano/sdk` range that the lock pins and an open install would rebuild derived
+state with a newer patch, failing the check on a change that touched nothing.
+
+**Regenerate after any merge.** A clean merge is not evidence that derived state is
+correct: two branches that change different objects merge with no conflict while one
+side's derived files were written before the other's source change existed. Nothing
+in git can see it, because at the text level the two sides never touched the same
+file — the check is what catches it. Pair the workflow with "Require branches to be
+up to date before merging" so a pull request approved against an older base is
+re-checked before it lands.
+
+## Toolchain modules
+
+A **toolchain module** extends the CLI rather than the workspace. It adds no tables
+or endpoints and is never registered in `xano/index.ts`; instead it contributes
+questions, lines for the files above, and hooks that run on `export` and `deploy` —
+after the compile, before anything is uploaded. Its per-project settings live in this
+project's `package.json` under `"xanosdk"`, keyed by package name, so a choice made
+once survives to every later run.
+
+Those questions are asked wherever the project is reconciled — at `init`, and in a
+project that already exists. **`xanosdk marketplace install <package>` is not just
+`npm install`:** it runs the module's questionnaire and writes both its settings and
+the `.gitattributes` lines it contributes. A module that arrived any other way — a
+plain `npm install`, a merged pull request, a `git pull` that changed
+`package.json` — is configured by running `xanosdk marketplace install` on it; until
+then `export` and `deploy` report it as installed but never configured, and it runs
+on its own defaults.
+
+**`xanosdk marketplace reinstall <package>`** re-asks the questions, offering this
+project's current settings as the defaults, and switches a module back on if it was
+turned off. **`xanosdk marketplace remove <package>`** uninstalls it and drops its
+settings and its contributed lines together. A plain `npm uninstall` leaves the
+`"xanosdk"` block behind, and a package that block names but that is no longer
+installed fails every `--frozen-lock` run until you run `reinstall` or `remove`.
+
+A module that owns a generated directory also contributes the `.gitattributes`
+lines that make it render and diff like source, and its own check rides on the
+same `--frozen-lock` run, so a stale tree fails CI beside a stale lock.
+
+Never hand-edit a file a module generates, and never hand-resolve a conflict in one.
+The correct content is whatever the source renders to, so the only valid resolution
+is to re-run the export.
+
+Writing one is [The module contract](module-contract.md): the manifest fields, the
+`@xano/sdk/plugin` types, every hook, and the shapes the SDK refuses.
+
+## Choosing in a browser
+
+`--web` collects the same choices against a live preview instead of on the
+command line:
+
+```bash
+xanosdk init my-app --web
+```
+
+It is a launcher, not a second scaffolder: a configurator is downloaded on
+demand, serves a local page, and finishes by running `init` with the flags your
+choices imply — printing the equivalent command so the project stays
+reproducible from a script. Everything after `--web` is passed to it untouched,
+including `--help`, which is why that one form reaches the network. `xanosdk help
+init` stays offline, like `init` itself.
+
+Because the configurator is fetched at run time, `--web` needs the npm registry
+before it can start. `init` on its own reaches out only to install the new
+project's dependencies, which `--no-install` skips — `--marketplace` add-ons
+included: they are added to `package.json` without being installed, and wired
+into `xano/index.ts` by hand after `npm install`.
+
+## The frontend preset
+
+To point `npm run dev` at a real backend, copy `.env.example` to `.env.local` — both
+live at the **project root**, next to `vite.config.ts` — and set `VITE_XANO_HOST` to a
+deployed URL. Deployed builds don't need it: `xanosdk deploy <entry> --static <dir>` injects the
+backend URL as `window.XANO_HOST`, which takes precedence.
+
+The frontend ships `Button` and `Card` already vendored, plus a pre-configured
+`components.json`, so `npx shadcn@latest add dialog form input` (or
+`npx shadcn-svelte@latest add …` on a Svelte scaffold) works immediately — no
+`init` step for either CLI. Components are copied into your repo rather than
+installed, so you own and edit them directly. [Lucide](https://lucide.dev/icons)
+is installed on both scaffolds — `lucide-react` on React, `@lucide/svelte` on
+Svelte — and the landing page already uses it.
+
+## Theming
+
+shadcn components carry no colors of their own: they are Tailwind utilities over
+a fixed set of semantic tokens (`--primary`, `--muted-foreground`, `--border`,
+the `--chart-*` ramp, the `--sidebar-*` set). Those tokens live at the top of
+`frontend/src/index.css`, which is the whole theme — Tailwind v4 keeps it in CSS,
+and there is no `tailwind.config.js`. That one stylesheet backs both frameworks.
+
+`init` renders it from a theme you choose, using shadcn's own two-part model:
+
+```bash
+xanosdk init my-app --theme zinc-blue     # a base color, plus an accent over it
+xanosdk init my-app --theme stone         # a base color alone
+xanosdk init my-app --theme zinc --radius 0
+```
+
+Base colors — the full token set: `neutral` (default), `stone`, `zinc`, `mauve`,
+`olive`, `mist`, `taupe`. Accents — a partial override of `primary`, `secondary`,
+the chart ramp, and the sidebar primary: `amber`, `blue`, `cyan`, `emerald`,
+`fuchsia`, `green`, `indigo`, `lime`, `orange`, `pink`, `purple`, `red`, `rose`,
+`sky`, `teal`, `violet`, `yellow`. The values are shadcn's, verbatim, so
+`--theme zinc-blue` is what ui.shadcn.com hands out for the same pair.
+
+`--theme` also takes any shadcn **registry theme** — its own, a third-party
+generator's, or your team's:
+
+```bash
+xanosdk init my-app --theme https://ui.shadcn.com/r/themes/slate.json
+xanosdk init my-app --theme ./brand-theme.json
+```
+
+`--radius <len>` overrides the corner radius (a bare number is rem). Everything
+else about the project is identical whichever theme you pick, and you can change
+your mind later by editing the token values — or by applying another theme over
+them with `npx shadcn@latest add <registry-theme-url>`.
+
+### Dark mode
+
+Every theme ships a complete dark palette. `--dark` decides what turns it on:
+
+- `system` (default) — an inline script in the HTML entry applies the OS setting
+  before first paint, so the page never flashes light first. No UI.
+- `toggle` — that, plus `frontend/src/lib/theme.ts` (the persisted mode) and a
+  mode toggle on the landing page cycling system → light → dark.
+- `off` — light only. The `.dark` block is still there and still complete.
+
+Whichever you pick, style with the token classes (`bg-primary`,
+`text-muted-foreground`) rather than raw palette classes like `bg-gray-100`:
+raw ones ignore the theme and are unreadable in dark mode. The scaffolded AI
+instruction files say so too.
+
+### Typefaces and icons
+
+Fonts are opt-in and **self-hosted**: each choice installs an `@fontsource`
+package rather than linking Google's CDN, which would be a third-party request
+on every page load of your app, a failure behind a firewall, and a privacy
+question someone inherits later.
+
+```bash
+xanosdk init my-app --font geist --font-heading instrument-serif --icons tabler
+```
+
+- `--font <id>` — body text (Tailwind's `--font-sans`, which v4 also uses as the
+  page default). Sans faces only: `geist`, `inter`, `figtree`, `manrope`,
+  `dm-sans`, `space-grotesk`, `outfit`, and 10 more.
+- `--font-mono <id>` — code. `jetbrains-mono` or `geist-mono`.
+- `--font-heading <id>` — headings. Accepts **any** face, sans or serif, since a
+  display serif over a sans body is the reason the slot exists. It emits a
+  base-layer rule, so headings pick it up without touching every `<h1>`.
+- Omit a slot and it keeps Tailwind's default stack, installing nothing for it.
+
+An unknown id fails at `init` naming the slot it was resolving, so `--font-mono
+inter` is an error rather than a proportional face quietly rendering your code
+blocks.
+
+`--icons <id>` picks the icon set: `lucide` (default), `tabler`, or `phosphor`.
+The binding covers the dark-mode toggle's icons as well as the landing page's —
+without that, `--icons tabler --dark toggle` would emit a toggle importing a
+library the project no longer installs, a build failure from a flag with nothing
+to do with dark mode.
+
+> On a Svelte scaffold `npm run typecheck` runs `svelte-kit sync && svelte-check`
+> (after `xano:routes`) rather than `tsc`. It checks the backend and the components together — `tsc`
+> cannot read `.svelte` files at all.
+
+> **The SvelteKit scaffold prerenders every route.** `frontend/src/routes/+layout.ts`
+> sets `prerender = true`, so each route becomes its own HTML document at build
+> time and loads as a real page. Pages live in `frontend/src/routes/`, and `files`
+> in the `sveltekit()` plugin config keeps the project single-rooted with `xano/`
+> as a peer. That config lives in `vite.config.ts` — there is no
+> `svelte.config.js`, matching where SvelteKit's own scaffold now puts it.
+>
+> There is still no server at runtime — Xano is the backend and `deploy --static`
+> ships to a host with no runtime, so `+page.server.ts`, form actions, and server
+> `load` have nothing to run on, and the build does not stop you. Treat them as
+> unavailable rather than trusting a green build.
+>
+> Two things follow from prerendering. Because it renders at build time,
+> module-scope `window`/`document` access fails the **build** rather than the
+> browser — use `onMount`, or guard with `browser`. And a dynamic route like
+> `/posts/[id]` **fails the build** until it says how it renders. For rows
+> created at runtime (the usual detail page), render it in the browser:
+>
+> ```ts
+> // frontend/src/routes/posts/[id]/+page.ts
+> export const prerender = false;
+> ```
+>
+> The scaffold builds with the SDK's adapter (`@xano/sdk/sveltekit`), which then
+> writes `404.html` as the app shell: the host answers `/posts/42` with it, and it
+> boots the app and renders the route, so a reload or a deep link works (with a
+> 404 status). `export const entries = () => [{ id: "1" }]` fits only ids known at
+> build time — no other id gets a page. While every route is prerendered,
+> unmatched paths get a real 404 from `frontend/src/routes/404/+page.svelte`,
+> which prerenders to `404.html`. It has to be a route: SvelteKit never
+> prerenders `+error.svelte` to a file.
+>
+> One more build-time check comes with prerendering: a hash link to an id that is
+> not on the page it renders on — `<a href="#pricing">` with no `id="pricing"` —
+> **fails the build**, naming the route and the id. A hash nav in
+> `+layout.svelte` is exempt on `/404` only, since that route inherits the layout
+> and by definition carries none of the page's sections.

package/guides/typed-frontend.md

@@ -0,0 +1,242 @@
+# 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 });      // → URLSearchParams; String(...) is "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.
+- **Sibling routes must not overlap.** Xano serves the first route that matches, in creation
+  order, and a literal route gets no priority over a `{param}` one. So `"runs/{id}"` created
+  before `"runs/trend"` answers `GET /runs/trend` itself. `export()` refuses any two routes in
+  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.
+- **`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, and a `c.*` constant **value**
+  types like an `s.set_var` of it: `response: { success: c.bool(true) }` derives
+  `{ success: boolean }`.
+  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 "@xano/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/{id}",   // one row → address it in the path
+  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 "@xano/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 "@xano/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();
+}
+```
+
+`toSearchParams` sends a list as `tags[]=a&tags[]=b` and an object as `range[min]=1`
+(a list of objects indexes each item: `items[0][id]=1`; a list of lists goes as one
+JSON value, `lol=[[1,2],[3]]`). A list item that sends nothing (`null`, `{}`) throws,
+naming it. A repeated plain key (`tags=a&tags=b`) reaches the endpoint as its last
+value only, so don't hand-roll it.
+
+The `@xano/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 `@xano/sdk/node` entry a frontend never pulls in.
+
+## Bundle size, and the route manifest
+
+**Bundle size & tree-shaking.** `@xano/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 **267 kB minified
+(65 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 269 kB. That 2 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
+xanosdk routes ./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 ~200x saving, with no SDK code in the output. Route keys and their
+`{param}` names 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("GET blog/{slug}", { slug }), {
+  method: ROUTES["GET blog/{slug}"].verb,
+});
+```
+
+A route key is `"<VERB> <name>"`, which is the endpoint identity the engine itself uses —
+so verb-differentiated siblings are ordinary, and a REST-shaped group emits without
+renaming anything:
+
+```ts
+routePath("GET listings");                  // list
+routePath("POST listings");                 // create
+routePath("PATCH listings/{id}", { id });   // update
+```
+
+The verb comes first so the key is stable: adding a `POST` sibling never renames the `GET`
+that was already there. When two api groups hold the same verb AND name (a `v1` and a `v2`
+both serving `GET vehicles`), each of those endpoints is keyed by its group's name instead,
+`"<group>:<VERB> <name>"`, and every other key stays short:
+
+```ts
+routePath("v1:GET vehicles");
+routePath("v2:GET vehicles");
+routePath("GET vehicles");   // compile error: "... is in more than one api group - use v1:GET vehicles or v2:GET vehicles"
+```
+
+Adding the second group's endpoint is what renames the first one's key, so its call sites
+stop compiling rather than silently addressing one group of the two.
+
+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. A channel path two servers both own
+is keyed by server, `"<server>:<path>"` (`channelPath("staff:lobby")`), and the bare path is a
+compile error naming both keys, as with api groups. `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";
+import { XANO_HOST } from "./lib/api"; // a string: the injected URL, else VITE_XANO_HOST
+
+const ws = new WebSocket(socketUrl("chat", 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/client.md

@@ -0,0 +1,63 @@
+# Consuming defs from a client
+
+> Read when a frontend imports a def (`getPath()`/`InferResponse`) or calls the deployed backend — what the import costs, `window.XANO_HOST`, local dev, file URLs, and a Node spot-check.
+
+Importing a def into a browser bundle or a Node script — for `getPath()`, `getUrl()`, `verb`, or `InferResponse` — runs its factory calls; these are the costs and the checks.
+
+- **Client bundle size / tree-shaking.** `@xano/sdk` is `sideEffects: false` and pulls
+  no Node built-ins, so a bundler drops unused SDK exports. But importing a **def** for its
+  `getPath()`/`verb`/`getUrl()`/`getChannel()` also pulls whatever its `stack` references:
+  the `s.*`/`c.*` factory CALLS run at module load to BUILD it. Types are free.
+  ⚠ A FLOOR — **~267 kB minified (~65 kB gzipped)** for the FIRST def; splitting modules
+  never removes it. The floor is the RUNTIME, not the def: a second or much richer def
+  adds ~2 kB, so trimming a def does not shrink it.
+  Fix: `xanosdk routes <entry> --emit xano/routes.gen.ts` (`paths` is an accepted alias) — verbs, paths, and sockets as
+  plain data importing NOTHING, still compile-checked: `routePath("GET blog/{slug}", { slug })`
+  `channelPath("rooms/{room_id}", { room_id })`, `socketUrl("chat", baseUrl)` (tenant base
+  URLs lifted to `wss://h/ws/<tenant>:<canonical>`). A rename is a type error, not a 404.
+- **Verifying a def outside a bundler.** Inside a bundler (Vite/webpack) importing a
+  query def to read `getPath()`/`verb` works directly. To spot-check from Node, run a REAL
+  file with `tsx <file.ts>` **from inside the project root** — not `tsx -e "import …"`
+  (its CJS-preparse mis-resolves the package `exports` map → ERR_PACKAGE_PATH_NOT_EXPORTED),
+  and not bare `node file.ts` (chokes on the `.js`-specifier intra-workspace imports the
+  xanosdk CLI's own loader resolves). Running from outside the project root also breaks
+  the `@xano/sdk` specifier resolution.
+
+**Reading the injected backend URL.** `xanosdk deploy <entry> --static <dir>` writes the deployed env's URL
+into every html document: a prerendered build serves a different one per
+route, and a route without the global renders fine while every call goes to the wrong
+origin. Read it at runtime with a build-time fallback:
+  const HOST = (typeof window !== 'undefined' && window.XANO_HOST) || import.meta.env.VITE_XANO_HOST;
+The scaffold's `lib/api.ts` types it (`interface Window { XANO_HOST?: string }` — `undefined` in dev)
+and exports this as a `string`, `XANO_HOST`; outside a scaffold declare the global yourself.
+In LOCAL DEV there is no injected global, so the fallback is what answers: set
+`VITE_XANO_HOST` in a `.env.local` beside `.env.example` at the PROJECT ROOT. The
+scaffold's vite config sets `envDir` there (its `root` is `frontend/`, and Vite
+resolves `.env` files against `root`) — without it the var reads as undefined, the
+host falls back to '', and every call 404s off the dev server.
+⚠ It is INJECTED in bracket form — `window["XANO_HOST"]="…"` — so verifying a deploy
+by grepping `window.XANO_HOST` matches nothing and reads as a failed inject. Grep the
+bare `XANO_HOST` token.
+**Frontend without the backend.** `xanosdk publish <dir> [--to <backend>]` uploads an
+already-built directory and nothing else — no compile, no import (scaffold script
+`npm run xano:deploy:frontend`). `publish` does not reach a local engine: after a local-engine
+deploy, pass `--to ephemeral`, or give the engine the frontend with
+`xanosdk deploy <entry> --local-engine --static <dir>` (served at `http://<prefix>.localhost:<port>`).
+**Server-rendered SvelteKit.** `adapter()` from `@xano/sdk/sveltekit` (needs `esbuild`) writes
+the static half at the build's root plus a server half in `.xano-ssr/`. A local engine renders every
+path that is not a file through it (`load` reads the engine's own URL as `XANO_HOST` from
+`$env/dynamic/private`; a rendered page gets the deploy's `window.XANO_HOST` too). Any other host
+is not sent `.xano-ssr/`: it serves the static half and answers other paths with the `404.html`
+shell, where a route with a server `load` fails (no `__data.json`). A scaffolded project configures
+SvelteKit in `vite.config.ts`'s `sveltekit({ adapter })`, where `svelte.config.js` is ignored.
+⚠ `.xano-ssr/server.js` inlines `$env/static/private` values; it is never served (`/.xano-ssr/` answers 404).
+The injected `XANO_HOST` is the DESTINATION's URL, so one build published to two
+destinations serves two different documents. `--release <name>` checks only that the
+release exists; `--branch <label>` (workspace only) refuses unless that label is LIVE —
+a label match, not a content comparison. `--json` reports `published` and `verified` separately.
+**Displaying a stored file.** A file column comes back as `{ path, name, type, size,
+meta, access, url }`. ⚠ Do NOT use its `url`: on a tenant-scoped environment that field
+addresses the instance host WITHOUT the `/tenant/<name>` segment and 404s, silently —
+as a broken `<img>`, with every API assertion still passing. Build the URL from `path`
+instead: `fileUrl(row.avatar, HOST)` returns `null` for
+an absent file and is correct on an ephemeral and an instance workspace alike.