@xanots/sdk 0.0.3 → 0.0.5

package/guides/object-kinds.md

@@ -0,0 +1,376 @@
+# Object kinds
+
+Every object kind XanoTS can author, and how to split a workspace across microservices.
+
+## Object kinds
+
+Every top-level Xano object is a registered kind with a factory and a `Xano.register*`
+method: `defineFunction`, `table`, `query`, `apiGroup`, `tool`, `mcpServer`, `agent`,
+`task`, `workflowTest`, `middleware`, `addon`, `realtimeServer`, `realtimeChannel`,
+`realtimeMessage`, `knowledge`, `microservice` (its own section below), `workspaceConfig`,
+and the seven trigger factories below. Signatures and payload keys are in
+`llms/object-kinds.md` and `llms/triggers.md`; what follows is what
+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
+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. What the agent 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.
+Write that `description` to be matched against a request rather than as a title. Full shape
+in `llms/kinds-knowledge.md`.
+
+**Triggers take a callback stack.** `stack: (t) => [...]`, not the plain array every other
+kind uses — because a trigger's inputs are **implied by its type** (fixed by Xano, not
+editable) and injected automatically. So triggers take no `input` field, and the typed
+handle `t` is the only way to read them (`response: (t) => ...` on response-bearing types).
+The seven types are `tableTrigger`, `realtimeServerTrigger`, `realtimeChannelTrigger`,
+`mcpServerTrigger`, `agentTrigger`, `workspaceTrigger`, and `errorTrigger`; they share one
+stored envelope discriminated by `obj_type`.
+
+```ts
+tableTrigger({
+  name: "on-user-insert",
+  table: users,
+  actions: { insert: true },
+  // Optional row filter, evaluated by the DATABASE before the stack runs — so it
+  // names the SQL pseudo-tables with col(), NOT the t handle. Rejected with
+  // `truncate`; insert cannot read OLD.*, delete cannot read NEW.*.
+  search: cmp(col("NEW.email"), "!=", c.text("")),
+  stack: (t) => [
+    // t.new("email") is typed to the row; t.action is the op; t.old is null (insert-only).
+    s.db.add({ table: auditLog, row: { email: t.new("email"), event: t.action } }),
+  ],
+});
+```
+
+**A workflow test is an end-to-end test, and its `datasource` is the trap.** `workflowTest`
+takes no `input` and no `response` — it calls other objects and asserts on what they bind.
+Leave `datasource` off: the default `""` runs against an **empty** datasource. Naming one
+makes the engine **clone** that datasource before every run, so pointing a test at
+production-sized data is slow enough to fail the run outright. `"live"` warns at compile
+time; every other name is your call.
+
+Empty means empty: **no `table({ seed })` rows exist while the test runs**, so every `db`
+read misses unless the test creates what it needs first — typically a `defineFunction`
+fixture the stack calls before anything else. A test written against a seeded row fails
+with your own precondition message, which reads as a wrong id rather than an empty
+database. A failing `s.api.call` is the other surprise: it **binds the error envelope**
+(`{code, message}`) to its `as` and carries on rather than raising, so a later assertion
+gets blamed for a call that failed several statements earlier — assert on `ref("r.code")`
+when a call may fail. `llms/tests.md` carries the rest, including what `s.api.call` can and
+cannot do about authentication.
+
+```ts
+workflowTest({
+  name: "signup_works",
+  tags: ["smoke"],
+  // datasource omitted on purpose — "" is an EMPTY datasource, not "no datasource".
+  stack: [
+    s.function.call({ fn: createUser, input: { email: "a@b.c" }, as: "created" }),
+    s.expect.to_be_defined({ expr: ref("created") }),
+    s.expect.to_equal({ expr: ref("created.status"), value: c.text("ok") }),
+    // A regex assertion takes a PATTERN, so build it with `c.regex(...)`.
+    s.expect.to_match({ expr: ref("created.id"), value: c.regex("^usr_[a-z0-9]+$") }),
+  ],
+});
+```
+
+**Saved unit tests are a different thing, and they hang off the object.** A `query`,
+`defineFunction` or `middleware` takes a `tests` array — the tests the Xano editor shows.
+Each is a named set of inputs run against *that* object, asserted with the top-level
+`expect.*` helpers. (`s.expect.*` — see [Authoring reference](authoring.md) — builds a
+*statement* for a workflow-test stack;
+`expect.*` builds a record stored on a test. They are not interchangeable, and the types
+enforce it.) Any statement in the stack can return a **mock** instead of doing its work,
+keyed by test name — and only while that named test runs, so a mock changes nothing about
+a normal request.
+
+A unit test's `datasource` is the same trap as a workflow test's, with the same default:
+`""` is an **empty** datasource, so **no `table({ seed })` rows are visible while a unit
+test runs** either. Every `db` read misses, and an assertion on the first row fails against
+a deployment whose endpoint returns those rows over HTTP a second later. Create what the
+test needs inside the run — a `defineFunction` fixture the stack calls first — or `mock`
+the read.
+
+```ts
+query({
+  name: "score",
+  verb: "POST",
+  input: { score: input.int({ required: true }) },
+  tests: [
+    {
+      name: "adds one",
+      input: { score: c.int(1) },
+      // Subject first — argument order is the assertion.
+      expect: [expect.to_equal(resp(), c.int(2))],
+    },
+  ],
+  stack: [
+    // Returns 2 while "adds one" runs; does nothing on a real request. A name
+    // no test declares throws at compile time.
+    s.set_var("total", c.expression("$input.score + 1"), {
+      mock: { "adds one": c.int(2) },
+    }),
+  ],
+  response: ref("total"),
+});
+```
+
+A pull brings tests back, along with a query's saved request/response `example`. The one
+thing it withholds is a test's auth `token` — that is an expiring credential rather than
+authored configuration, so `xanots codegen` reports it as a deliberate omission instead of
+writing it into a committed tree.
+
+**Four of the `Run …` statements only run inside a workflow test.** `s.api.call`,
+`s.task.call`, `s.trigger.call` and `s.workflow_test.call` are resolved by the engine at
+run time, and outside a `workflowTest` stack it cannot reach the target — so one of them in
+a query, function or task type-checks, exports, imports and **deploys clean**, then answers
+the first real request
+with `ERROR_FATAL: <Type> does not exist`. It is not per host kind: the same call fails
+identically from a function that a query runs. `xanots export` refuses them outside a
+workflow test. `s.function.call`, `s.tool.call`, `s.middleware.call` and `s.addon.call` run
+from any stack, as does `s.function.run` — the ordinary way to invoke a function. To share
+logic between two endpoints, put it in a `defineFunction` and `s.function.run` it from both.
+
+**`s.expect.to_match` takes a regex PATTERN, not text.** The engine runs it through PHP
+`preg_*`, which reads the first character as the delimiter — so a `c.text("^usr_.*$")` there
+is a pattern the engine cannot run, and the assertion fails against the very string it was
+written for. `c.regex("^usr_.*$")` (or `c.regex(/^usr_.*$/)`) wraps and escapes it; a bare
+`c.text` pattern is refused at compile time and pointed here. A `ref`/`inp` pattern, whose
+text isn't visible to the check, is passed through untouched.
+
+**Realtime** — the only three-level containment chain in the SDK: `realtimeServer` owns
+`realtimeChannel`s, which own `realtimeMessage` handlers (a message is the realtime
+analogue of a query — its own typed payload and stack). Pass the **handle**, not a name: a
+channel path is unique only within its server. A channel's `input` types its **path** params
+(`rooms/{room_id}`); a message's `input` types the message **payload**. A server is off
+until `enabled: true`.
+
+```ts
+const chat = realtimeServer({ name: "chat", enabled: true });
+
+const room = realtimeChannel({
+  name: "rooms/{room_id}",           // `input` types the PATH params
+  server: chat,
+  input: { room_id: input.int() },
+  publish: { who: "authenticated" },
+  conversation: { enabled: true, limit: 50 },   // client-visible transcript
+});
+
+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"
+  stack: [s.debug.log({ value: inp("body") })],
+});
+```
+
+The client side is derived too, the same way `query().getPath()` works — `chat.getUrl(BASE)`
+builds the socket URL (`wss://…/ws/<canonical>`, with a tenant base URL translated into the
+socket's `/ws/<tenant>:<canonical>` form) and `room.getChannel({ room_id: 42 })` builds the
+path a client joins. Both throw rather than guess. In a **browser bundle**, reach for the
+generated manifest's `socketUrl`/`channelPath` instead — same addresses, same checks, without
+importing the defs (see
+[The payoff: a type-safe frontend, for free](#the-payoff-a-type-safe-frontend-for-free)).
+
+Five traps account for most realtime bugs. The full wire protocol — every server frame,
+the presence roster shape, the at-least-once client contract — is in `llms/kinds-realtime.md`.
+
+- **An empty return denies, and so does a crash.** `connect` and `join` are gates: return
+  `{ allowed: c.bool(true) }` or any truthy value to admit. A stack that falls through, or a gating
+  trigger with no `response`, refuses everyone — and a raise refuses too, because the gate is
+  seeded with a deny it keeps when the stack throws. Both failure modes lock the door, so the
+  risk to plan for is a self-inflicted lockout, not a breach: guard every drill inside a gate
+  with `ref(path, { safe: true })`, since `db.get` binds `null` on a miss. `export()` warns on
+  the missing `response`; nothing can warn about the raise. Gating is opt-in — a server with
+  no `connect` trigger admits everyone.
+- **Only `null` drops a message.** In a `deliver` trigger (per recipient) and in a message
+  handler, `false`/`0`/`""` all deliver the message unchanged, and a crash broadcasts the
+  sender's original unvalidated payload. Return `null` to suppress. So a redaction check
+  written as a boolean sends the very message it was meant to hide. Per-viewer redaction
+  also takes **two objects**: the `deliver` trigger *and* `delivery: { perRecipient: true }`
+  on its channel. Either half alone delivers the payload unchanged to everyone, so a gate
+  whose return semantics are perfect still ships unredacted if the flag is missing — and the
+  flag costs a stack per recipient per message, so it is opt-in. `export()` warns on both
+  halves.
+- **`conversation: { enabled: true }` alone stores nothing.** `limit` defaults to `0`, and
+  `0` means retain none. Always pass a `limit`. What a handler broadcasts *is* the stored
+  row, so broadcast everything a future joiner needs to render it.
+- **An idle socket is reaped after ~10 minutes.** A listen-only client (feed, dashboard,
+  presence sidebar) must send `{ action: "ping" }` or any frame periodically, or it silently
+  drops and reconnects forever.
+- **`s.realtime.publish` is the push direction, and it is fail-soft.** It bypasses the
+  channel's `publish.who` (authorization belongs in your stack), does not invoke the named
+  message's handler, and swallows a missing or disabled server — a mis-targeted publish is
+  silent. Pass the server handle and a filled-in path (`room.getChannel({ room_id: 42 })`),
+  never the template — a constant channel still carrying `{param}` throws at author time, and
+  a constant server or channel naming nothing this workspace registers warns at export.
+
+**The superseded realtime layer.** Xano has had two realtime generations and they reuse the
+same words. `realtimeTrigger(...)` and `s.api.realtime_event(...)` belong to the old
+workspace-global layer; they are supported only so `codegen` can bring back a workspace that
+holds them, and they are named in `llms/legacy.md` rather than in the authoring catalogs.
+Aiming `s.api.realtime_event` at a current-layer channel publishes into the void — use
+`s.realtime.publish({ server, channel, data })`, which names the owning server and so can
+resolve the channel.
+
+**MCP servers & agents** — both persist under the `toolset` payload key, so an `mcpServer`
+and an `agent` **sharing a name collide**. A `tool({...})` is its own kind, referenced by
+handle from either.
+
+```ts
+// Auth is PER-TOOL and works like a query's: name an auth table({ auth: true }).
+mcpServer({ name: "books", tools: [{ tool: searchTool, auth: users }] });
+
+const assistant = agent({
+  name: "assistant",
+  llm: { type: "xano-free", systemPrompt: "Be helpful.", prompt: "Answer the question." },
+  // Pass the handles directly; the `{ tool, enabled?, auth? }` wrapper (above)
+  // is only for per-tool auth or `enabled: false`.
+  tools: [searchTool],
+});
+
+// Agents have NO public endpoint — invoke them in-stack from any host with a stack.
+query({
+  name: "ask", verb: "POST", apiGroup: api,
+  input: { question: input.text({ required: true }) },
+  stack: [s.ai.agent.run({ agent: assistant, args: obj({ question: inp("question") }), as: "answer" })],
+  response: { text: ref("answer.result") },
+});
+```
+
+- **The run result is an envelope, not the completion.** The model's text is at **`.result`**
+  — `ref("answer")` is the whole metadata object (`finishReason`, `steps`, …). Both are
+  typed, so `InferResponse` reflects either.
+- **`llm` is a provider-discriminated union** — `anthropic` / `openai` / `google-genai` /
+  `xano-free` (which needs no API key) — each with its provider's typed fields.
+- **Structured output types the call site.** Author `output: { schema: { … } }` on the agent
+  with the `input.*` catalog and `.result` is typed from it wherever the handle is passed —
+  no second witness. The type-only `resultShape` is only for overriding that, or for an
+  agent referenced by bare name.
+- **String settings are Twig-templated at run time.** The `args` you pass to
+  `s.ai.agent.run` become `{{ $args }}` (env vars are `{{ $env.NAME }}`), which is how an
+  endpoint's inputs reach the prompt. Numeric and boolean fields are not templated. Build a
+  dynamic arg with `obj({...})`, not `c.obj`.
+- **`mcpServer().getUrl(HOST)`** derives the Streamable-HTTP endpoint from the def, the same
+  contract as `query.getPath()`. Resolve once — handing the result back in as a `HOST` throws
+  rather than append a second endpoint path. Agents expose only `getCanonical()`.
+
+**Background execution.** `s.function.run` and `s.ai.agent.run` take a `runtime` block
+(`{ mode: "async-shared" }`, or `"async-dedicated"` with `cpu`/`memory`/`timeout`/`maxRetry`)
+that moves the call off the request path. This is **not** a performance knob: Xano rewrites
+an async call to a statement that dispatches and continues, so it does not return the
+function's result — don't bind `as` expecting a value. Collect results later with
+`s.await({ ids })`.
+
+## Microservices
+
+A microservice is a container workload deployed alongside the workspace and called from a
+stack with `s.microservice.request`. Two mutually exclusive shapes chosen by `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.
+
+```ts
+export const echo = microservice({
+  name: "echo",
+  deployment: {
+    replicas: 2,
+    containers: [{
+      name: "echo",
+      image: "ealen/echo-server:latest",
+      ports: [{ servicePort: "8080", containerPort: "80" }],
+      resources: { cpu: "50m", ram: "256Mi" },
+    }],
+  },
+});
+```
+
+Call it by passing the def itself. `port` folds into the single `"name:port"` host string
+the engine reads, and is optional — a microservice exposing exactly one `servicePort`
+resolves to it, and one exposing several requires it. A port the microservice doesn't expose
+is a type error where the def's ports are known, and a build-time throw otherwise:
+
+```ts
+s.microservice.request({ as: "res", host: echo, path: "/health" });
+```
+
+Only `host` and `path` are required. `method`, `params`, `headers`, `timeout`, and
+`follow_location` default to the engine's own values (`GET`, `{}`, `[]`, `10`, `true`) and are
+always written — this statement's schema requires them, so they can't be left off the wire;
+you just don't have to type them.
+
+`host` binds by name, not by guid, because that is how the engine resolves it — so renaming
+a microservice fixes every call site at once. A plain `"name:port"` string is also accepted
+and is the only way to reach an instance-level microservice, which isn't a workspace object;
+nothing checks that spelling, so prefer the def wherever there is one.
+
+A container takes time to come up, so `xanots deploy` waits for it: after the import it
+reads each microservice and reports whether it is ready, still starting, or failed, then
+lists them. Skip the wait with `--no-verify`. The same report is available any time from
+`xanots ephemeral get <env>`, `xanots sandbox details`, and `xanots workspace details`.
+
+Two outcomes, and only one of them is a warning:
+
+- **The engine reports the microservice broken** (an image that won't pull, a container that
+  won't start) — the deploy **exits 4**. Waiting longer cannot change that answer, and a URL
+  and a ✓ printed over a dead workload is not a successful deploy. This is the default; there
+  is no flag to turn it off.
+- **It simply hasn't reported ready by the end of the wait** — a warning, exit `0`. The
+  backend is live and a slow container usually follows moments later. Pass
+  **`--require-microservices`** to make that exit 4 too, which is what CI wants: nobody is
+  there to find out whether "should come up shortly" happened.
+
+Exit 4 is the microservice sibling of exit 3 (a `--static` upload that failed while the
+backend deploy stood): the import committed, and something it deployed is not serving. The
+URL and the JSON summary still print either way — the exit code is what carries the
+difference.
+
+`tenantDeploy: "manual"` rows are reported but never waited on — nothing starts them for you.
+Reach for it when the row should exist without a workload behind it; `examples/sandbox` uses
+it so deploying the examples doesn't wait on containers.
+
+Container names are free-form: they need not match the microservice's own name, and nothing
+about addressing depends on them. A stack reaches the **microservice** name (plus a
+`servicePort`), whichever containers sit behind it, so a multi-container workload names each
+one for what it is.
+
+**This surface is early and expected to change**, and every export of a workspace declaring a
+microservice prints a notice saying so — the docs are read before writing, which is not where
+you are when it matters. `configs` and `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 minutes in, after provisioning has begun. Declare a value
+the workload reads as a container `env` entry, and storage as a container `volumes` entry
+(`emptyDir`, `persistent`, or `config`). Both fields stay typed so a pulled workspace holding
+one still decodes.
+
+Two fields carry secrets into the bundle — and into a pulled tree — verbatim:
+`chart.values` and `registryAuth.dockerconfigjson`, because otherwise a pulled microservice
+could not be redeployed.
+
+**What "out of band" can and cannot mean here.** Both are stored strings the engine keeps
+exactly as given, with no deploy-time indirection — no `env()` form, no template the tenant
+resolves. So the spelling that looks safe is the wrong one:
+
+```ts
+// WRONG — `process.env` resolves at EXPORT time. The literal credential is written
+// into workspace.json, and into git with it.
+microservice({ name: "app", registryAuth: { dockerconfigjson: process.env.REGISTRY_JSON! } });
+```
+
+Two honest options, both about where the bytes live rather than about hiding them:
+
+1. **Leave `registryAuth` unset** — a public image, or a pull credential attached to the
+   microservice outside this workspace. Nothing then carries a credential.
+2. **Accept that the tree is secret-bearing** — keep `workspace.json` and any pulled tree out
+   of git, or rotate the credential once it lands there.
+
+Export prints a notice naming every microservice whose bundle bytes carry either field, so
+this can't happen quietly; `--strict` does **not** promote it, since shipping a
+private-registry workload is a legitimate end state. When what you actually need is a secret
+your *stack* reads, the mapped surface is `workspaceConfig({ env })` + `env("NAME")` — see
+[Middleware, request history &amp; env vars](#middleware-request-history--env-vars).

package/guides/project-structure.md

@@ -0,0 +1,43 @@
+# Project structure
+
+How a XanoTS project is laid out on disk, and why registration is explicit.
+
+Lay objects out however you like and register them explicitly — there's no folder
+auto-discovery magic (deliberately):
+
+```
+xano/
+├── function/     get_user.ts         export const getUser = defineFunction({...})
+├── table/        table.ts            export const user = table({...})
+│   └── trigger/  on_insert.ts        export const onInsert = tableTrigger({...})
+├── query/        public.ts           export const publicApi = apiGroup({...})
+│                 public/posts_GET.ts export const posts = query({...})
+├── agent/        assistant.ts        export const assistant = agent({...})
+├── realtime_server/ chat.ts               export const chat = realtimeServer({...})
+│                 chat/room.ts              export const room = realtimeChannel({...})
+│                 chat/room/send.ts         export const send = realtimeMessage({...})
+├── workspace.ts                      export const workspaceSettings = workspaceConfig({...})
+└── index.ts      workspace("my-app").registerTables([...]).registerFunctions([...])…
+```
+
+Objects nest under whatever owns them. Anything with children — an API group, a
+realtime server, a channel — is a file named for itself sitting *beside* the folder
+holding its children, so `chat.ts` opens in a tab you can tell apart and a group with
+no queries needs no folder at all. Realtime is the deepest, being the only three-level
+hierarchy in a workspace — server, then channel, then message — and a trigger sits in
+a `trigger/` folder at whichever level it fires on.
+
+Paths are lower case throughout — an HTTP verb is the one exception, because it is
+the method rather than a word. Bindings keep the object's own casing, so a file name
+and the symbol it exports can differ.
+
+That is the shape `xanots codegen` writes, and its `index.ts` re-exports every object
+by name — import from the tree's root rather than from a file, since a file path moves
+when an object's parent or its `_shared.ts` placement changes. Hand-authored projects are
+free to use any other layout; only `index.ts` registering the objects matters.
+
+`workspace("my-app")` is the natural entry point — sugar for
+`new Xano().registerWorkspace({ name: "my-app" })`, returning the same chainable registry.
+Authoring is **declarative def-objects** passed to factories; there is no callback/chaining
+builder. `xano.export()` returns the importable `packageExport` bundle, and
+`xanots export`/`deploy` read the module's default export.

package/guides/scaffold.md

@@ -0,0 +1,198 @@
+# The scaffolded project
+
+What `xanots 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)), `--ai <claude|codex|cursor|none>`
+(repeatable; writes `CLAUDE.md`/`AGENTS.md`/Cursor rules — none by default),
+`--marketplace <pkg>` (repeatable, comma-separated; installs add-ons and
+registers them — below), `--force` (scaffold into a non-empty folder),
+`--no-install` (skip `npm install`).
+In a terminal, `init` prompts for the framework, the theme, and the AI files;
+every prompt has a default, so pressing enter three times is a valid answer.
+The starter backend is empty but already compiles and deploys — grow it from the
+walkthrough in `xano/EXAMPLE.md`.
+
+A scaffold ships `@xanots/sdk` and nothing else from the `@xanots` scope. Add-ons
+install on demand:
+
+```bash
+xanots marketplace list                      # every published add-on
+xanots marketplace search auth               # …or narrow by keyword
+xanots marketplace details @xanots/auth      # what it installs + how to register it
+xanots marketplace install @xanots/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.
+
+`init` takes the same package names, so a project can be scaffolded with its
+add-ons already wired:
+
+```bash
+xanots init my-app --framework react --marketplace @xanots/auth,@xanots/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` (`"xanots": { "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.
+
+`@xanots/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. Build role guards natively: a role column
+on the auth table, then a `s.precondition` on each endpoint gating
+`auth("role")`.
+
+`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 `xanots
+--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.
+
+## 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: `xanots 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
+xanots init my-app --theme zinc-blue     # a base color, plus an accent over it
+xanots init my-app --theme stone         # a base color alone
+xanots 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
+xanots init my-app --theme https://ui.shadcn.com/r/themes/slate.json
+xanots 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
+xanots 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`
+> 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** unless it declares which ids exist:
+>
+> ```ts
+> // frontend/src/routes/posts/[id]/+page.ts
+> export const entries = () => [{ id: "1" }, { id: "2" }];
+> ```
+>
+> That is deliberate — a loud build error beats shipping a page that 404s for
+> real users. 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, so that
+> alone would ship no `404.html` and every unknown path would serve the home page
+> with a 200 instead.
+>
+> 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.