@xanots/sdk 0.0.12 → 0.0.14

package/dist/internal.js

@@ -29,7 +29,7 @@ import {
   taskKind,
   toolKind,
   workflowTestKind
-} from "./chunk-VRNZ2NVV.js";
+} from "./chunk-PJNWOZMT.js";
 import {
   GENERATED_SPECS,
   GENERATED_STATEMENT_NAMES,
@@ -51,7 +51,7 @@ import {
   registerSpec,
   triggerKind,
   workspaceKind
-} from "./chunk-GSP2BY4F.js";
+} from "./chunk-BYQHCCYU.js";
 import {
   IMPLEMENTED_STATEMENTS,
   STATEMENT_SURFACES,
@@ -216,7 +216,7 @@ var KIND_DESCRIPTORS = [
   { kind: "mcp_server", payloadKey: "toolset", authorFactory: "mcpServer", description: "An MCP server exposing a set of tools to external MCP clients.", registerMethod: "registerMcpServers" },
   { kind: "agent", payloadKey: "toolset", authorFactory: "agent", description: "An AI agent: an LLM configuration plus the tools it can call. Invoke it from any stack (query/function/task/tool/trigger) with `s.ai.agent.run` \u2014 no public endpoint; the result is a rich envelope whose completion text is at `.result`.", registerMethod: "registerAgents" },
   { kind: "task", payloadKey: "task", authorFactory: "task", description: "A scheduled background job (cron/interval) that runs a stack on a timer.", registerMethod: "registerTasks" },
-  { kind: "workflow_test", payloadKey: "workflow_test", authorFactory: "workflowTest", description: 'An end-to-end test: a named stack with NO input and NO response that invokes other objects (`s.function.call`, `s.task.call`, `s.api.call`) and asserts on what they bind with `s.expect.*`. `datasource` defaults to `""` (an EMPTY datasource, recommended); naming one makes the engine CLONE that datasource before every run, so pointing a test at production-sized data can be slow enough to fail the run \u2014 `"live"` warns at compile time.', registerMethod: "registerWorkflowTests" },
+  { kind: "workflow_test", payloadKey: "workflow_test", authorFactory: "workflowTest", description: 'An end-to-end test: a named stack with NO input and NO response that invokes other objects (`s.function.call`, `s.task.call`, `s.api.call`) and asserts on what they bind with `s.expect.*`. `datasource` defaults to `""` (an EMPTY datasource, recommended); naming one is the clone trap described in `llms/kinds-core.md`.', registerMethod: "registerWorkflowTests" },
   { kind: "middleware", payloadKey: "middleware", authorFactory: "middleware", description: "A reusable pre/post stack attached to a query/function/task/tool/API group to run before or after its own logic.", registerMethod: "registerMiddleware" },
   { kind: "addon", payloadKey: "addon", authorFactory: "addon", description: "A reusable read fragment that enriches a query result by joining related table data.", registerMethod: "registerAddons" },
   { kind: "realtime_server", payloadKey: "realtime_server", authorFactory: "realtimeServer", description: "A realtime (websocket) server: the canonical-addressed container that owns realtime channels. Off until `enabled: true`. Returns a handle with `getUrl(baseUrl)`/`getPath()` for the client's socket URL (`wss://<host>/ws/<canonical>`).", registerMethod: "registerRealtimeServers" },
@@ -311,12 +311,12 @@ var VALUE_CONSTRUCTORS = [
   { name: "c.blank", signature: '(tag: "const:<type>") => Value', description: `The editor's UNCONFIGURED value box (stored value ""), emitted by codegen for a pulled workspace \u2014 do not author it. NOT a zero or an empty collection: the engine reads "" and "0" differently, so c.blank("const:int") \u2260 c.int(0) and neither canonicalizes into the other. Constant tags except const/const:obj, whose blanks are c.text("")/c.obj(null).` },
   { name: "c.bool", signature: "(b: boolean) => Value", description: 'Boolean constant \u2192 tag "const:bool".' },
   { name: "c.null", signature: '(tag?: "const:null" | "const:obj") => Value', description: `Null constant, stored value "null". Bare c.null() is tag "const:null". c.null("const:obj") is the OBJECT-TYPED null the engine writes into a db.* statement's @meta slot \u2014 different stored bytes from c.obj(null), which is the blank object (value ""), though both evaluate to null. Codegen emits whichever spelling the workspace stored; do not swap one for the other.` },
-  { name: "c.obj", signature: "(o?: Json | null) => Value", description: 'Object constant \u2192 tag "const:obj". A populated one stores an empty {} carrying one `set` filter per key \u2014 the editor\'s form, and the only populated form the engine reads back (a populated JSON string arrives truncated and fails the request with ERROR_FATAL "Unable to decode."). \u26A0 a ZERO-BASED numeric key is an INDEX in the engine\'s data model, so c.obj({"0":"a"}) evaluates to the list ["a"] (a non-zero-based one like {"2":\u2026} survives as a key) \u2014 that is the platform, not this encoding. No argument = the empty object {} \u2014 use this one. Explicit null = the legacy blank form the engine evaluates to null, NOT {}; it exists only so a pulled workspace round-trips, do not author it. Plain JSON literals only \u2014 a nested tagged value (inp/ref/auth/c.*) is rejected; for a computed object response use a record of values, not c.obj.' },
+  { name: "c.obj", signature: "(o?: Json | null) => Value", description: 'Object constant \u2192 tag "const:obj". A populated one stores an empty {} carrying one `set` filter per key \u2014 the editor\'s form, and the only populated form the engine reads back (a populated JSON string arrives truncated and fails the request with ERROR_FATAL "Unable to decode."). \u26A0 a ZERO-BASED numeric key is an INDEX in the engine\'s data model, so c.obj({"0":"a"}) evaluates to the list ["a"] (a non-zero-based one like {"2":\u2026} survives as a key) \u2014 that is the platform, not this encoding. Write c.array([...]) for a list, or prefix the keys ("k0") for an object; `export()` warns. No argument = the empty object {} \u2014 use this one. Explicit null = the legacy blank form the engine evaluates to null, NOT {}; it exists only so a pulled workspace round-trips, do not author it. Plain JSON literals only \u2014 a nested tagged value (inp/ref/auth/c.*) is rejected; for a computed object response use a record of values, not c.obj.' },
   { name: "c.array", signature: "(a: Json[]) => Value", description: 'Array constant (JSON string) \u2192 tag "const:array". Plain JSON literals only \u2014 a nested tagged value is rejected, same as c.obj.' },
   { name: "c.expression", signature: "(source: string) => Value", description: `Xano Expression Engine source, passed through VERBATIM \u2192 tag "const:expr2". The string IS the expression: c.expression('"Hi, " ~ $input.name'), c.expression("$var.price * $var.qty"). \u26A0\uFE0F NOT VALIDATED \u2014 never parsed or type-checked, invisible to InferResponse, and untouched by a rename that updates every typed ref(); a typo surfaces at runtime or as a wrong answer. Use it ONLY for syntax the typed surfaces cannot express (~ concatenation, inline arithmetic, conditionals) \u2014 prefer ref/inp/col, withFilters+fl.*, and obj() (which BUILDS a checked expression). Not the expr() condition builder.` },
   { name: "c.expressionLegacy", signature: "(source: string) => Value", legacy: true, description: "the older `const:expr` expression form, emitted by codegen for workspaces that still hold one \u2014 author `c.expression` instead." },
   { name: "c.now", signature: "() => Value", description: "Current time as epoch-ms \u2014 the engine-native const:epochms constant (no filter). Valid inline as a where/cmp operand. For cutoff math (cutoff = now - max_age) either compare inline or, for reuse/readability, hoist it into an s.set_var and compare against the var." },
-  { name: "obj", signature: "(fields: Record<string, Value | nested>) => ObjValue<typeof fields>", description: 'Dynamic object value \u2192 tag "const:expr2" (an object-literal expression string). The dynamic sibling of c.obj: members may be inp/ref/auth/col values, env()/setting()/sys.*, c.now(), c.* constants, nested records, or arrays \u2014 and each member may carry a FILTER CHAIN (withFilters + fl.*), which renders as the expression pipe `$var.row|get:"a.b"`. That matters most for the null-safe drill: db.get binds null on a miss, so ref(path, { safe: true }) inside an obj() is the normal shape, not a workaround \u2014 you do NOT need a preceding s.set_var to hoist it. The member record rides the return type, so InferResponse resolves each member the way it resolves a top-level response key \u2014 `response: { user: obj({ id: ref("row.id") }) }` derives `{ user: { id: Col | null } }`, and a raw nested object literal (`response: { user: { id: ref("row.id") } }`, auto-wrapped through this) derives the same. A constant record or list has two spellings that both work and render identically: bare (`{ a: 1 }`, `[]`) or `c.obj(...)`/`c.array([...])` \u2014 prefer the bare form. NEST WITH A RAW RECORD, not an inner obj() call: an inner call yields a const:expr2 value, which the expression serializer has no spelling for and THROWS. The legacy blank `c.obj(null)` is refused here (it evaluates to null, not {}) \u2014 write c.null() or c.obj(). Still rejected: a filter ARGUMENT that carries its own chain or is a c.now() (a trailing | binds to the whole value, not one argument, and c.now() needs one), a DISABLED filter (an expression string cannot record that), and the output/response/toolset/reg tags \u2014 build those in a prior step and ref() them. Use for e.g. s.ai.agent.run args.' },
+  { name: "obj", signature: "(fields: Record<string, Value | nested>) => ObjValue<typeof fields>", description: 'Dynamic object value \u2192 tag "const:expr2" (an object-literal expression string). The dynamic sibling of c.obj: members may be inp/ref/auth/col values, env()/setting()/sys.*, c.now(), c.* constants, nested records, or arrays \u2014 and each member may carry a FILTER CHAIN (withFilters + fl.*), which renders as the expression pipe `$var.row|get:"a.b"`. A null-safe ref(path, { safe: true }) works inside an obj() member directly. The member record rides the return type, so InferResponse resolves each member the way it resolves a top-level response key \u2014 `response: { user: obj({ id: ref("row.id") }) }` derives `{ user: { id: Col | null } }`, and a raw nested object literal (`response: { user: { id: ref("row.id") } }`, auto-wrapped through this) derives the same. A constant record or list has two spellings that both work and render identically: bare (`{ a: 1 }`, `[]`) or `c.obj(...)`/`c.array([...])` \u2014 prefer the bare form. NEST WITH A RAW RECORD, not an inner obj() call: an inner call yields a const:expr2 value, which the expression serializer has no spelling for and THROWS. The legacy blank `c.obj(null)` is refused here (it evaluates to null, not {}) \u2014 write c.null() or c.obj(). Still rejected: a filter ARGUMENT that carries its own chain or is a c.now() (a trailing | binds to the whole value, not one argument, and c.now() needs one), a DISABLED filter (an expression string cannot record that), and the output/response/toolset/reg tags \u2014 build those in a prior step and ref() them. Use for e.g. s.ai.agent.run args.' },
   { name: "ref", signature: "(name: string, opts?: { safe?: boolean }) => Value", description: 'Reference a stack variable \u2192 tag "var". Pass { safe: true } for null-safe nested access \u2014 a dotted ref("owner.user_id", { safe: true }) compiles through the get filter so it resolves to null instead of raising "Unable to locate var" when the base is null.' },
   {
     name: "inp",
@@ -774,9 +774,9 @@ function renderTestsSection() {
     "",
     "The run is isolated in ways that make a correct test fail for reasons the failure message does not name.",
     "",
-    "- The run uses an EMPTY datasource, so **no `table({ seed })` rows exist while it runs** and every `db` read misses. A test that buys seeded row 1 fails with its own precondition message, which reads as a wrong id rather than an empty database. Create what the test needs INSIDE the test \u2014 typically a `defineFunction` fixture the stack calls first.",
+    "- The run uses an EMPTY datasource, so **no `table({ seed })` rows exist while it runs** (same as a unit test, above): a read of seeded row 1 fails with its own precondition message, not an empty-database error. Build fixtures INSIDE the test.",
     '- `s.api.call` does NOT raise when the endpoint answers with an error. It BINDS the error envelope (`{code, message}`) to its `as` and carries on, so a later `s.expect.to_be_defined({ expr: ref("r.field") })` reports the ASSERTION while the real failure was the call, four statements up. Assert on the envelope \u2014 `s.expect.to_contain({ expr: ref("r.code"), value: c.text("ERROR_CODE_INPUT_ERROR") })` \u2014 when a call may fail. `s.function.run` raises instead; the two disagree.',
-    '- `s.expect.to_throw({ body, exception? })` runs `body` in an ISOLATED var stack, so a variable bound EARLIER in the test is not visible inside it \u2014 bind what the body needs inside the body. `exception` is a `Value` whose text the raised message must CONTAIN (`c.text("already exists")`, not a bare string); omit it to accept any error.',
+    '- `s.expect.to_throw({ body, exception? })` runs `body` in an ISOLATED var stack, so a variable bound EARLIER in the test is not visible inside it \u2014 bind what the body needs inside the body. An outer one raises `Missing var entry: <name>` there, which the test reports as `to_throw` not matching (`export()` warns). `exception` is a `Value` whose text the raised message must CONTAIN (`c.text("already exists")`, not a bare string); omit it to accept any error.',
     "- `s.expect.to_throw` catches such a call only when the error carries a MESSAGE. `ERROR_CODE_ACCESS_DENIED` arrives with an empty one, so `to_throw` around an auth-refused call reports `to_throw failed - response is ok` \u2014 which reads as a broken auth gate on a gate that works.",
     "- An endpoint's `auth` gate is NOT enforced on `s.api.call`. A `query({ auth: users })` runs anyway and fails only where its stack dereferences `auth(...)`. A stack that never touches `auth(...)` runs unauthenticated and passes.",
     "- Neither `auth.token` nor an `Authorization` entry in `headers` authenticates the call \u2014 a token that answers 200 over real HTTP is refused here. To cover auth-gated logic, move the body into a `defineFunction` taking the user id and `s.function.call` that; the gate itself is not reachable from a workflow test.",
@@ -812,13 +812,13 @@ function renderSections(m) {
     "caller, `c.*` a constant \u2014 resolved at request time; JS operators over them do not",
     "compute (see Gotchas). Requests share no memory \u2014 state persists in tables or redis.",
     "",
-    `Coverage: object kinds ${m.coverage.objectKinds.implemented}/${m.coverage.objectKinds.total}, statement surfaces ${m.coverage.statements.implemented}/${m.coverage.statements.total}, filters ${m.coverage.filters.total} (${m.coverage.filters.typed} typed).`,
     // The shortfall by name: an agent that cannot see WHICH kinds are missing
     // will invent a factory for one. Reasons live in `manifest.json`.
+    `Authorable: statement surfaces ${m.coverage.statements.implemented}/${m.coverage.statements.total}, filters ${m.coverage.filters.total} (${m.coverage.filters.typed} typed).`,
     `Not authorable here: ${m.coverage.objectKinds.unmodeled.map((k) => k.kind).join(", ")} \u2014 these cannot be authored and do not survive a pull; reasons in \`coverage.objectKinds.unmodeled\`.`,
     "",
     "This file is the whole always-read surface: the mental model, the deploy contract,",
-    "every gotcha, and control flow. Per-surface detail lives in the topic files listed",
+    "every cross-cutting gotcha, and control flow. Per-surface detail lives in the topic files listed",
     "below \u2014 open the one whose condition matches the task, skip the rest. For",
     "exhaustive per-entry detail in NEITHER \u2014 a statement's field schema with engine",
     "defaults, a filter's full argument list, the `storedName` mapping \u2014 do a TARGETED",
@@ -903,6 +903,8 @@ function renderSections(m) {
     "but nothing fails on a message no one reads, so in CI and in unattended agent builds",
     "pass `--strict` (`emitBundle(app, { strict: true })` / `app.export({ strict: true })`):",
     "every warning becomes a hard failure. Same bundle bytes either way.",
+    "Before calling the work done: `npm run typecheck`, `xanots export <entry> --strict`,",
+    "`xanots deploy <entry>`, then `xanots test run-all` against what deployed.",
     "",
     "Identity: object guids derive from `(type, name)` \u2014 a query's from `(api group,",
     "verb, name)` \u2014 so renames change identity.",
@@ -948,38 +950,19 @@ function renderSections(m) {
     "",
     "**Frontend wiring.** `--static <dir>` injects the DEPLOYED env's backend URL as",
     "`window.XANO_HOST` into EVERY html document in the build, before the app bundle runs,",
-    "so the frontend needs no rebuild to target an env. Every document, not just the root:",
-    "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;",
-    "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`) \u2014 without it the var reads as undefined, the",
-    "host falls back to '', and every call 404s off the dev server.",
-    '\u26A0 It is INJECTED in bracket form \u2014 `window["XANO_HOST"]="\u2026"` \u2014 so verifying a deploy',
-    "by grepping `window.XANO_HOST` matches nothing and reads as a failed inject. Grep the",
-    "bare `XANO_HOST` token.",
-    "\u26A0 `xanots preflight` ignores the deploy login and reads `XANO_VALIDATE_INSTANCE` /",
-    "`XANO_VALIDATE_TOKEN` (+ optional `XANO_VALIDATE_WORKSPACE_ID`) from the environment.",
-    "**Displaying a stored file.** A file column comes back as `{ path, name, type, size,",
-    "meta, access, url }`. \u26A0 Do NOT use its `url`: on a tenant-scoped environment that field",
-    "addresses the instance host WITHOUT the `/tenant/<name>` segment and 404s, silently \u2014",
-    "as a broken `<img>`, with every API assertion still passing. Build the URL from `path`",
-    "instead: `fileUrl(row.avatar, HOST)` (exported from `@xanots/sdk`) returns `null` for",
-    "an absent file and is correct on an ephemeral and an instance workspace alike.",
-    "\u26A0 A static host serves these files verbatim, so everything injected is PUBLIC \u2014 base",
+    "so the frontend needs no rebuild to target an env. How to read it, local dev, verifying",
+    "the inject, and displaying a stored file: `llms/client.md`.",
+    "\u26A0 A static host serves its files verbatim, so everything injected is PUBLIC \u2014 base",
     "URLs and publishable keys only, never secrets. Secrets go in backend env, read",
     "server-side via `env(name)`.",
+    "\u26A0 `xanots preflight` ignores the deploy login and reads `XANO_VALIDATE_INSTANCE` /",
+    "`XANO_VALIDATE_TOKEN` (+ optional `XANO_VALIDATE_WORKSPACE_ID`) from the environment.",
     "",
     "**Full CLI surface:** `xanots <command> --help` lists every command, flag, and",
     "default; the shipped `manifest.json` carries the same in its `cli` array. This doc",
     "does not duplicate it \u2014 it covers what you must know to AUTHOR a workspace.",
-    "**Recommended style:** reach statements through the `s` namespace",
-    "(`s.db.add`, `s.math.add`, \u2026) \u2014 one discoverable, tab-completable surface. The",
-    "flat factory aliases (`dbAdd`, `dbQuery`, `setVar`, `mathAdd`, \u2026) are exported",
-    "and identical in output; prefer `s.*` in new code so examples stay consistent.",
+    "**Style:** reach statements through the `s` namespace (`s.db.add`, `s.math.add`, \u2026).",
+    "The flat aliases (`dbAdd`, `setVar`, \u2026) are identical in output; prefer `s.*`.",
     ""
   );
   lines.push(
@@ -987,53 +970,71 @@ function renderSections(m) {
     "",
     "Non-obvious authoring rules:",
     "",
+    "### Values and references",
+    "",
     "- **No callback builder.** Flat def-objects + `register*`, not",
     "  `workspace(w => w.table(...))`. `workspace(name)` returns a named `new Xano()`;",
     "  tables are `table({ schema: { col: f.text() } })`.",
-    "- **Foreign key is `f.tableRef(table)`, not `ref`.** `ref(name)` references a",
-    "  stack variable (a value); `f.tableRef` is the column constructor.",
     "- **Reference-helper picker:** `ref` = stack var (`as:` output), `inp` = input,",
     '  `col` = table column (in `db.query` `where`), `auth("id")` = the caller,',
     "  `c.*` = a constant. Pick by what you're pointing at.",
+    "- **Foreign key is `f.tableRef(table)`, not `ref`.** `ref(name)` references a",
+    "  stack variable (a value); `f.tableRef` is the column constructor.",
     "- **Tagged values are DATA \u2014 a JS template literal cannot compose them.** `${ref(...)}`",
     '  (or `"a" + ref(...)`) stringifies the tag object at BUILD time: ``c.text(`Hi ${ref("u.name")}`)``',
     "  type-checks and encodes the literal text `Hi [object Object]`, served verbatim.",
     "  `export()` warns; `--strict` fails. Compose at RUNTIME:",
     '  `withFilters(c.text("Hi "), fl.concat(ref("u.name")))`, an `obj({...})`/record member,',
     "  or `c.expression('\"Hi, \" ~ $var.u.name')`.",
-    "- **`s.api.call` / `s.task.call` / `s.trigger.call` / `s.workflow_test.call` are",
-    "  WORKFLOW-TEST ONLY.** Outside a `workflowTest({...})` stack the engine cannot reach",
-    "  the target, so one in a query/function/task deploys clean and then answers the first",
-    "  real request with `ERROR_FATAL: <Type> does not exist: <type>:<n>` \u2014 and not per",
-    "  host kind, the same call fails identically from a function a query runs.",
-    "  `export()` refuses them. `s.function.call`, `s.tool.call`, `s.middleware.call` and",
-    "  `s.addon.call` run anywhere, as does `s.function.run` (the ordinary function",
-    "  invocation). To share logic between endpoints, put it in a `defineFunction` and",
-    "  `s.function.run` it from both.",
-    "- **`expect.*` is a unit-test assertion; `s.expect.*` is a workflow-test statement.**",
-    "  A statement's `mock` is keyed by TEST NAME; an undeclared name throws. See `llms/tests.md`.",
-    "- **Drilling into a maybe-null `db.get` result 500s \u2014 use `ref(path, { safe: true })`.**",
-    '  `db.get` binds `null` on a no-match, but a nested `ref("owner.user_id")` resolves',
-    '  `$owner.user_id` in one lookup and raises a runtime "Unable to locate var" (HTTP 500)',
-    "  when `owner` is null \u2014 so an ownership/existence guard throws instead of failing",
-    '  cleanly. Either guard existence first (`expr(ref("owner"), "!=", c.null())`,',
-    "  or a `db.has`/`db.query`-count precondition), or drill with the null-safe opt-in:",
-    '  `expr(ref("owner.user_id", { safe: true }), "=", auth("id"))` compiles through the',
-    "  `get` filter and yields `null` (guard reads `false`) rather than 500ing.",
-    "  Works inside `obj({...})` too \u2014 no per-member `s.set_var` hoist needed.",
-    "  \u26A0 EXPRESSION and `obj()` operands ONLY \u2014 never a `db.*` match argument. `null`",
-    "  is not a legal `fieldValue`/`id`, so a chained get (fetch the child row, then",
-    "  fetch its parent to check the owner) fails with HTTP 400 `Missing param:",
-    "  field_value` one statement BEFORE the guard \u2014 the same net effect as the 500,",
-    "  with an internal-sounding status the caller should never see. Only an id",
-    "  matching no row reaches it, so it deploys clean. In the chained case guarding",
-    "  existence first is MANDATORY, not a stylistic alternative: precondition on",
-    '  `expr(ref("ticket"), "!=", c.null())`, then drill WITHOUT `safe` (the base is',
-    "  known non-null by then). `export()` warns on a safe ref in that position.",
-    "  \u26A0 That is for a base that EXISTS and may be null. If the base binds nothing at all",
-    "  (a typo), `{ safe: true }` turns the 500 into a silent `null` and buries the bug \u2014",
-    "  `export()` warns on a `ref()` whose base segment no `as` in that stack binds, with a",
-    "  did-you-mean; fix the name instead.",
+    '- **Declare inputs with `input.<type>()`, read them with `inp("name")`.** `inp()`',
+    "  resolves ONLY against this def's own `input` block \u2014 a value produced earlier in",
+    '  the stack is `ref("var.field")`, not `inp("field")`. An undeclared name fails at',
+    "  runtime with `Unable to locate input` (`export()` warns).",
+    "- **`get_input`/`get_raw_input` read the whole payload**, not one named input",
+    "  (args are `{ as?, encoding?, excludeMiddleware? }` \u2014 no `name`). For a single",
+    '  input use `inp("name")`.',
+    "- **To match every row, omit `where` \u2014 never pass a constant.** `where: c.bool(true)` is",
+    '  not "no filter": a bare scalar literal states no condition and the engine reads the',
+    '  resulting `context.search` as garbage, so it throws. An absent `where` is how "every',
+    '  row" is spelled. A raw `Value` `where` stays the escape hatch for a clause built',
+    '  elsewhere \u2014 `inp("clause")`, `ref("built_where")`, or `c.text("id > 0")`.',
+    "",
+    "### Tables and columns",
+    "",
+    "- **System columns are auto-injected.** `id` + `created_at` are prepended to",
+    "  every table (`system: true` by default); declaring them by hand is redundant.",
+    '  `id` is an `int` PK by default; pass `idType: "uuid"` on the table for a uuid key.',
+    "  Both are valid targets wherever a column name is accepted \u2014 `db.query` `sort`/",
+    "  `output`, a `db.get`/`edit`/`del` `fieldName`, etc. (the column-name type is",
+    '  `keyof schema | "id" | "created_at"`), and both appear in `InferRow<typeof table>`.',
+    "- **A column named `run` is reserved.** The table deploys and reads back fine, then",
+    "  EVERY `s.db.add` into it 400s \u2014 at any column type, with or without a value \u2014 and",
+    "  the error names the column while complaining about the VALUE. Use `run_id`. Exact,",
+    "  case-sensitive, one name: `Run`/`runs`/`run_id` are fine. `--strict` fails on it.",
+    "- **Self-referencing tables** need the bare-name form: inside `tweets`'s own",
+    '  schema, write `f.tableRef("tweets", { type: "int" })` \u2014 the `const tweets`',
+    `  handle isn't assigned yet, so the handle form throws "used before declaration".`,
+    "- **Seed a table's starting rows with `table({ seed })`.** Rows typed against the",
+    '  schema, inline (`seed: [{ name: "\u2026" }]`) or from a file (`seedFile("./seed.json",',
+    "  import.meta.url)`). Only `deploy` ships them, and a re-deploy re-seeds cleanly. Never",
+    "  put secrets in `seed`. Row shape, `id` pinning, and the file rules: `llms/fields.md`.",
+    '- **`f.password()` defaults to `access: "internal"`, so `db.get` does NOT return it.**',
+    '  A login stack that reads `ref("u.password")` after a plain `db.get` fails at runtime',
+    "  with `Unable to locate var: u.password` \u2014 the column is simply absent from the row.",
+    '  Name it in the read\'s `output` to pull it: `s.db.get({ table: users, fieldName: "email",',
+    '  fieldValue: inp("email"), output: ["id", "email", "password"], as: "u" })`, then',
+    "  `s.security.check_password`. `output` OVERRIDES column visibility \u2014 it is the only way to",
+    "  read an `internal` column, and `export()` warns when a stack reads one a `db.get` did not",
+    "  return.",
+    "- **Don't take a password through `input.password` on login \u2014 it double-hashes.**",
+    "  An `f.password()` column hashes on write, and `input.password` *also* hashes the",
+    "  submission on bind, so `s.security.check_password` compares two different hashes",
+    "  and a correct password always fails (`ok:false` on a found row). Take the submitted",
+    "  password as `input.text()` on both signup and login and pass the plaintext straight",
+    "  to `check_password` (which does the comparison hash itself). `export()` warns.",
+    "",
+    "### Reading and writing rows",
+    "",
     "- **DB reads are field-match, not `where`-expr.** `db.get`/`db.edit`/`db.del`/",
     "  `db.has`/`db.patch` match one field: `{ fieldName, fieldValue }` (`fieldName`",
     "  defaults to the PK `id`). Only `db.query` takes a `where`/`additionalWhere`",
@@ -1047,44 +1048,73 @@ function renderSections(m) {
     '  check-in \u2014 use `db.query({ where: [expr(col("habit"), "=", ...), expr(col("date"), "=", ...)], as })`',
     "  (a `where` array is ANDed) and branch on the result, rather than pushing the",
     "  check to the client.",
-    "- **A column named `run` is reserved.** The table deploys and reads back fine, then",
-    "  EVERY `s.db.add` into it 400s \u2014 at any column type, with or without a value \u2014 and",
-    "  the error names the column while complaining about the VALUE. Use `run_id`. Exact,",
-    "  case-sensitive, one name: `Run`/`runs`/`run_id` are fine. `--strict` fails on it.",
-    "- **System columns are auto-injected.** `id` + `created_at` are prepended to",
-    "  every table (`system: true` by default); declaring them by hand is redundant.",
-    '  `id` is an `int` PK by default; pass `idType: "uuid"` on the table for a uuid key.',
-    "  Both are valid targets wherever a column name is accepted \u2014 `db.query` `sort`/",
-    "  `output`, a `db.get`/`edit`/`del` `fieldName`, etc. (the column-name type is",
-    '  `keyof schema | "id" | "created_at"`), and both appear in `InferRow<typeof table>`.',
-    "- **Seed a table's starting rows with `table({ seed })`.** `seed` takes rows",
-    "  typed against the table's schema as a WRITE shape (a column without",
-    "  `required: true`, and the system columns, may be omitted; `null` needs",
-    '  `nullable: true`) \u2014 inline (`seed: [{ name: "\u2026" }]`), a FILE',
-    '  (`seed: seedFile("./seed.json", import.meta.url)`; path resolves against the DECLARING',
-    '  file), or a thunk (`seed: () => import("./seed.json")`, async ok, `.default` unwrapped).',
-    "  Inline rows are TYPED against the schema at compile time; a `seedFile`/thunk seed is",
-    "  NOT \u2014 the JSON is opaque to the typechecker, and the `xanots export`/`deploy` CLI",
-    "  validates it instead, naming the row index, the offending column, and the known",
-    "  columns. \u26A0 Prefer `seedFile` for a file: a thunk's `import()` sits in",
-    "  YOUR module, so a bundler emits the JSON as a served chunk. NEITHER is a secrecy",
-    "  boundary \u2014 a bundler that inlines the asset ships them either way. Never put secrets",
-    "  in `seed`. `deploy --static` REFUSES a build carrying internal/sensitive seed values;",
-    "  `--allow-seed-in-static` overrides for deliberately public demo credentials.",
-    "  Deploy is a full replace, so re-deploying re-seeds",
-    "  cleanly (no duplication). Omit `id` and rows auto-number `1..N` (int PK) or take",
-    "  a stable derived uuid (uuid PK); supplying `id` pins it (engine preserves it,",
-    "  resets an int sequence past the max). All-or-nothing \u2014 mixing explicit and",
-    "  omitted `id` throws. A `system:false` PK is the author's to supply. Pinning is",
-    "  `seed`-only \u2014 `s.db.bulk.add` DROPS `id` unless `allowIdField: true`.",
-    "- **`use_xdo` storage mode.** Workspace setting (`registerWorkspace({ use_xdo })`,",
-    "  default `false`) controlling whether fields are stored as JSON under the `xdo`",
-    "  column (`true`, adds a `gin(xdo)` index) or as real columns (`false`, no gin).",
-    "  Tables inherit it; override per-table with `table({ useXdo })`. Resolved at",
-    "  `export()`, so the workspace and tables can be registered in any order.",
-    "- **Self-referencing tables** need the bare-name form: inside `tweets`'s own",
-    '  schema, write `f.tableRef("tweets", { type: "int" })` \u2014 the `const tweets`',
-    `  handle isn't assigned yet, so the handle form throws "used before declaration".`,
+    "- **Drilling into a maybe-null `db.get` result 500s \u2014 use `ref(path, { safe: true })`.**",
+    '  `db.get` binds `null` on a no-match, but a nested `ref("owner.user_id")` raises a runtime',
+    '  "Unable to locate var" (HTTP 500) when `owner` is null \u2014 an ownership guard throws instead',
+    "  of failing cleanly. Two correct shapes:",
+    '  - Guard existence first \u2014 `s.precondition({ expr: expr(ref("owner"), "!=", c.null()),',
+    '    error_type: "notfound", error: c.text("Not found.") })` \u2014 then drill WITHOUT `safe`.',
+    "  - Or drill null-safe inside an EXPRESSION or `obj()` operand:",
+    '    `expr(ref("owner.user_id", { safe: true }), "=", auth("id"))` yields `null` (the guard',
+    "    reads `false`) instead of 500ing. Works inside `obj({...})` too \u2014 no `s.set_var` hoist needed.",
+    "  \u26A0 EXPRESSION and `obj()` operands ONLY \u2014 never a `db.*` match argument. `null` is not a",
+    "  legal `fieldValue`/`id`, so a chained get (fetch the child row, then its parent to check",
+    "  the owner) fails with HTTP 400 `Missing param: field_value` one statement BEFORE the guard.",
+    "  There guarding existence first is MANDATORY. `export()` warns on a safe ref in that position.",
+    "  \u26A0 That is for a base that EXISTS and may be null. If the base binds nothing at all (a typo),",
+    "  `{ safe: true }` buries the bug as a silent `null` \u2014 `export()` warns with a did-you-mean;",
+    "  fix the name instead.",
+    "",
+    "### Stacks and calls",
+    "",
+    "- **Block specials nest a `body`, not a `stack`.** `s.for`/`s.foreach`/",
+    "  `s.while`/`s.switch`/`s.try_catch`/`s.db.transaction`/`s.expect.to_throw`",
+    "  take their sub-stack as `body` (`try`/`catch`/`finally` for `try_catch`);",
+    "  `s.group(body)` and `s.util.post_process(body)` take it **positionally**.",
+    "  `s.for` is **count-bounded** (`{ as, count: <Value>, body }`), not from/to. See the",
+    "  authored signatures in `llms/statements-data.md`.",
+    "- **`s.api.call` / `s.task.call` / `s.trigger.call` / `s.workflow_test.call` are",
+    "  WORKFLOW-TEST ONLY.** Outside a `workflowTest({...})` stack the engine cannot reach",
+    "  the target, so one in a query/function/task deploys clean and then answers the first",
+    "  real request with `ERROR_FATAL: <Type> does not exist: <type>:<n>` \u2014 and not per",
+    "  host kind, the same call fails identically from a function a query runs.",
+    "  `export()` refuses them. `s.function.call`, `s.tool.call`, `s.middleware.call` and",
+    "  `s.addon.call` run anywhere, as does `s.function.run` (the ordinary function",
+    "  invocation). To share logic between endpoints, put it in a `defineFunction` and",
+    "  `s.function.run` it from both.",
+    "- **`expect.*` is a unit-test assertion; `s.expect.*` is a workflow-test statement.**",
+    "  A statement's `mock` is keyed by TEST NAME; an undeclared name throws. See `llms/tests.md`.",
+    "- **A helper returning `Statement[]` widens the stack and kills `InferResponse`.**",
+    "  Spreading `...requireX()` where the helper is typed `Statement[]` drops the stack's TUPLE",
+    "  type, so EVERY `ref()`/`as` in that stack \u2014 even ones after the spread \u2014 resolves to",
+    "  `unknown` and the response types as `StackTupleWidened`. Nothing fails at the helper; it",
+    "  surfaces where the response is consumed, often a frontend typecheck. Fix: return",
+    "  `statements(s.a(...), s.b(...))` \u2014 its tuple survives the spread. A helper that builds",
+    "  its array in a LOOP cannot be a tuple; declare `responseShape` on the query there.",
+    "- **Build regex-filter patterns with `c.regex(body, flags?)`, never `c.text`.**",
+    "  The regex filters (`regex_test`/`regex_match`/`regex_replace`/\u2026) are PHP `preg_*`: the",
+    "  piped value is the PATTERN and must be delimiter-wrapped, and the ARGUMENT is the subject.",
+    '  Correct: `withFilters(c.regex(/^[a-z-]+$/i), fl.regex_test(inp("slug")))`.',
+    '  - A bare `c.text("^\u2026$")` is an invalid pattern that matches *nothing* for every input,',
+    '    so a precondition on it silently rejects all values. `c.regex(body, "i")` wraps +',
+    "    escapes it for you (a JS `RegExp` too: `c.regex(/^\u2026$/i)`).",
+    "  - Reversed \u2014 subject piped, pattern in the argument \u2014 reads correctly, type-checks, and",
+    "    answers false for EVERY input, so an `if (matches) reject` guard admits what it refuses.",
+    "  - Build time refuses both: `withFilters` throws on a bare `c.text` pattern from ANY position",
+    "    in the chain (a normalizer in front of the regex filter is refused too; nothing upstream",
+    "    adds the delimiters) and on a pattern found in the subject slot; `s.expect.to_match` is the",
+    "    same PATTERN slot, refused both ways; a `ref`/`inp` pattern is passed through untouched.",
+    "    `export()` warns on a reversed pair in stored bytes.",
+    "  - Better still: a native typed input (`input.email`) over hand-rolled validation.",
+    "- **An `auth()`-keyed limiter collapses on any host with no caller identity \u2014 at every**",
+    '  **tier.** `s.redis.ratelimit({ key: withFilters(c.text("rl:"), fl.concat(auth("id"))) })`',
+    "  is the per-user form, but `auth()` is `null` on a public query, a task, or a function,",
+    "  and every caller then shares one bucket. Attaching it once at",
+    "  `apiGroup({ middleware })` or the workspace tier is the tempting DRY move and inherits",
+    "  the same collapse onto every member endpoint. Export warns, naming the tier.",
+    "",
+    "### Identity, build, and deploy",
+    "",
     "- **Same-name siblings collide \u2014 queries excepted: their identity carries group + verb.**",
     "  Guids derive from `(type, name)`, so two functions (or tables, toolsets, \u2026) sharing",
     "  a name derive ONE guid and `export()` throws \u2014 give them DISTINCT names. A QUERY",
@@ -1095,137 +1125,34 @@ function renderSections(m) {
     "  is NOT a lasting fix: a lock entry cannot hold two guids, so `export --lock`",
     "  refuses the pair (`export()` warns even unlocked); it is for pinning identity",
     "  across a rename, not for sharing a name.",
-    "- **`export()` vs `emitBundle()` vs `writeBundle()`:** `writeBundle(app, path)`",
-    "  writes it to disk; `export()` returns the bundle object;",
-    "  `emitBundle()` returns the pretty JSON string. All three run the SAME build-time",
-    "  checks, INCLUDING seed validation of a literal `seed: [...]` array (row shape,",
-    "  unknown column, coercion, enum membership, the all-or-nothing `id` rule). A",
-    '  DEFERRED seed \u2014 a thunk (`() => import("./seed.json")`) or `seedFile()` \u2014 needs an',
-    "  await or the filesystem, so it is materialised and checked only by the",
-    "  `xanots export`/`deploy` CLI path. Seed rows are never emitted into the bundle",
-    "  either way; only `deploy` ships them. The `node:fs` writers",
-    "  (`writeBundle`/`writeArtifact`) and lock-file I/O import from `@xanots/sdk/node`,",
-    "  NOT the browser-safe `@xanots/sdk` entry (a frontend imports defs from it for",
-    "  `getPath()`/`InferInput`).",
-    "  The compiler machinery (per-kind `encode*`, the registries, the bundle serializer,",
-    "  the lock model) is on `@xanots/sdk/internal` and is never needed to author.",
-    "  READING a bundle back is `@xanots/sdk/bundle` \u2014 a statement walker (`2.if.0` paths),",
-    "  a structural hash, `mvp:*` catalog, `tableRefOf`.",
-    "- **Client bundle size / tree-shaking.** `@xanots/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.",
-    "  \u26A0 A FLOOR \u2014 **~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 def, or a much richer",
-    "  one, adds ~2 kB \u2014 so reducing what a def does will not reduce it.",
-    "  Fix: `xanots routes <entry> --emit xano/routes.gen.ts` (`paths` is an accepted alias) \u2014 verbs, paths, and sockets as",
-    '  plain data importing NOTHING, still compile-checked: `routePath("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.",
+    "- **`export()` vs `emitBundle()` vs `writeBundle()`:** `export()` returns the bundle object,",
+    "  `emitBundle()` the pretty JSON string, `writeBundle(app, path)` writes it to disk. All",
+    "  three run the SAME build-time checks, INCLUDING seed validation of a literal `seed: [...]`",
+    "  array (row shape, unknown column, coercion, enum membership, the all-or-nothing `id`",
+    '  rule). A DEFERRED seed \u2014 a thunk (`() => import("./seed.json")`) or `seedFile()` \u2014 is',
+    "  checked only by the `xanots export`/`deploy` CLI path. Seed rows are never emitted into",
+    "  the bundle either way; only `deploy` ships them.",
+    "  - Entry points: the `node:fs` writers (`writeBundle`/`writeArtifact`) and lock-file I/O",
+    "    import from `@xanots/sdk/node`, NOT the browser-safe `@xanots/sdk` entry (a frontend",
+    "    imports defs from it for `getPath()`/`InferInput`). `@xanots/sdk/internal` is the",
+    "    compiler machinery, never needed to author. READING a bundle back is `@xanots/sdk/bundle`",
+    "    \u2014 a statement walker (`2.if.0` paths), a structural hash, `mvp:*` catalog, `tableRefOf`.",
     "- **Intra-workspace imports use `.js` specifiers** (`../tables/links.js`), not",
     "  extensionless \u2014 the defs compile under `moduleResolution: bundler`. Add the `.js`.",
-    "- **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** \u2014 not `tsx -e "import \u2026"`',
-    "  (its CJS-preparse mis-resolves the package `exports` map \u2192 ERR_PACKAGE_PATH_NOT_EXPORTED),",
-    "  and not bare `node file.ts` (chokes on the `.js`-specifier intra-workspace imports the",
-    "  xanots CLI's own loader resolves). Running from outside the project root also breaks",
-    "  the `@xanots/sdk` specifier resolution.",
-    "- **A helper returning `Statement[]` widens the stack and kills `InferResponse`.**",
-    "  Factoring a repeated guard into `function requireX(): Statement[]` and spreading it",
-    '  (`...requireX("d")`) drops the stack\'s TUPLE type, so EVERY `ref()`/`as` in that stack \u2014',
-    "  including ones declared after the spread \u2014 resolves to `unknown` and the query's",
-    "  response types as `StackTupleWidened`. Nothing fails at the helper: the error surfaces",
-    "  wherever the response is consumed, often a frontend package's typecheck. Fix: return",
-    "  `statements(s.a(...), s.b(...))` \u2014 a const-generic identity export whose tuple survives",
-    "  the spread. A helper that builds its array in a LOOP cannot be a tuple; declare",
-    "  `responseShape` on the query there. See `llms/statements-runtime.md`.",
-    "- **Block specials nest a `body`, not a `stack`.** `s.for`/`s.foreach`/",
-    "  `s.while`/`s.switch`/`s.try_catch`/`s.db.transaction`/`s.expect.to_throw`",
-    "  take their sub-stack as `body` (`try`/`catch`/`finally` for `try_catch`);",
-    "  `s.group(body)` and `s.util.post_process(body)` take it **positionally**.",
-    "  `s.for` is **count-bounded** (`{ as, count: <Value>, body }`), not from/to. See the",
-    "  authored signatures in `llms/statements-data.md`.",
-    "- **MCP servers & agents are distinct root kinds** that both persist under the",
-    "  `toolset` payload key (so a same-name pair collides). `mcpServer({...})` exposes",
-    "  tools over MCP (auth is per-tool \u2014 no server-level gate); `agent({...})` carries a",
-    "  typed `llm` block \u2014 and so may an `mcpServer`, since the two are ONE stored",
-    "  object distinguished by `type`. Their `tools` take a `tool()` handle (or name), resolved to the",
-    "  tool's guid like the call family; a raw numeric `id` is an escape hatch.",
-    "- **`task.schedule` is an array** of `{ startsOn, freq?, repeatEnabled?, endsOn?, endsEnabled? }`",
-    "  (`ScheduleDef[]`), not a single `{ type, value }`. `freq` is seconds; `startsOn`/",
-    '  `endsOn` are timestamp strings validated at encode time \u2014 `"2026-01-01T00:00:00Z"`, or',
-    '  the space-separated `"2026-01-01 00:00:00+0000"` a pulled workspace carries. Never',
-    "  epoch numbers, and never zoneless: the engine stores the string verbatim without",
-    "  checking it, so one it cannot parse deploys clean and the task then never fires.",
-    "- **`get_input`/`get_raw_input` read the whole payload**, not one named input",
-    "  (args are `{ as?, encoding?, excludeMiddleware? }` \u2014 no `name`). For a single",
-    '  input use `inp("name")`.',
-    '- **`f.password()` defaults to `access: "internal"`, so `db.get` does NOT return it.**',
-    '  A login stack that reads `ref("u.password")` after a plain `db.get` fails at runtime',
-    "  with `Unable to locate var: u.password` \u2014 the column is simply absent from the row.",
-    '  Name it in the read\'s `output` to pull it: `s.db.get({ table: users, fieldName: "email",',
-    '  fieldValue: inp("email"), output: ["id", "email", "password"], as: "u" })`, then',
-    "  `s.security.check_password`. `output` OVERRIDES column visibility \u2014 it is the only way to",
-    "  read an `internal` column, and `export()` warns when a stack reads one a `db.get` did not",
-    "  return.",
-    "- **Build regex-filter patterns with `c.regex(body, flags?)`, never `c.text`.**",
-    "  The regex filters (`regex_test`/`regex_match`/`regex_replace`/\u2026) are pattern-piped",
-    "  PHP `preg_*`: the piped value is the PATTERN and must be delimiter-wrapped, and the",
-    '  ARGUMENT is the subject. A bare `c.text("^\u2026$")` is an invalid pattern that matches',
-    "  *nothing* for every input, so a precondition on it silently rejects all values.",
-    '  `c.regex(body, "i")` wraps + escapes it for you (a JS `RegExp` too: `c.regex(/^\u2026$/i)`).',
-    "  Reversed \u2014 subject piped, pattern in the argument \u2014 reads correctly, type-checks, and",
-    "  answers false for EVERY input, so an `if (matches) reject` guard admits what it",
-    "  refuses. `withFilters` throws on a bare `c.text` pattern from ANY position in",
-    "  the chain (a normalizer in front of the regex filter is refused too; nothing upstream",
-    "  adds the delimiters) and on a pattern found in the subject slot; `s.expect.to_match`",
-    "  is the same PATTERN slot, refused both ways; a `ref`/`inp` pattern is passed through untouched.",
-    "  `export()` warns on a reversed pair in stored bytes. Better still:",
-    "  a native typed input (`input.email`) over hand-rolled validation.",
-    "- **Compose a rule set as SIBLINGS, not a folded chain.** `and(...rules)` takes any",
-    "  number of terms and encodes flat; `rules.reduce((acc, r) => and(acc, r))` nests one",
-    "  container per rule, which costs quadratic bytes (512 terms: 394 KiB flat, 21 MiB",
-    "  folded) and is refused past 128 levels. Mixed joins: `and(or(...anyOf), ...allOf)`.",
-    '- **Declare inputs with `input.<type>()`, read them with `inp("name")`.** `inp()`',
-    "  resolves ONLY against this def's own `input` block \u2014 a value produced earlier in",
-    '  the stack is `ref("var.field")`, not `inp("field")`. An undeclared name fails at',
-    "  runtime with `Unable to locate input` (`export()` warns).",
-    "- **Don't take a password through `input.password` on login \u2014 it double-hashes.**",
-    "  An `f.password()` column hashes on write, and `input.password` *also* hashes the",
-    "  submission on bind, so `s.security.check_password` compares two different hashes",
-    "  and a correct password always fails (`ok:false` on a found row). Take the submitted",
-    "  password as `input.text()` on both signup and login and pass the plaintext straight",
-    "  to `check_password` (which does the comparison hash itself).",
     "- **Agents authenticate with env vars \u2014 never `xanots login`.** `login` blocks on a",
-    "  browser consent no agent can complete. Set `$XANO_INSTANCE_URL` + `$XANO_WORKSPACE_ID`",
-    "  + `$XANO_META_TOKEN` and run `deploy`/`release` directly: no disk, no rotation, so it",
-    "  survives repeated runs. It outranks every other credential (`--config` and",
-    "  `$XANO_REFRESH_TOKEN` included, each named on stderr when displaced), and setting SOME",
-    "  of the three is a hard error \u2014 a misspelled secret must not fall through to whatever",
-    '  credential the runner has. As a file that triple is `{ "type": "token",',
-    '  "instance_base_url": \u2026, "workspace_id": <n>, "meta_api_token": \u2026 }`. The older',
-    "  `$XANO_REFRESH_TOKEN` + `$XANO_CLIENT_ID` pair still works but ROTATES: single-use.",
+    "  browser consent no agent can complete. Set all three of `$XANO_INSTANCE_URL`,",
+    "  `$XANO_WORKSPACE_ID`, `$XANO_META_TOKEN` and run `deploy`/`release` directly: no disk, no",
+    "  rotation, so it survives repeated runs.",
+    "  - The triple outranks every other credential (`--config` and `$XANO_REFRESH_TOKEN` included,",
+    "    each named on stderr when displaced). Setting SOME of the three is a hard error, so a",
+    "    misspelled secret cannot fall through to whatever credential the runner has.",
+    '  - As a file: `{ "type": "token", "instance_base_url": \u2026, "workspace_id": <n>,',
+    '    "meta_api_token": \u2026 }`. The older `$XANO_REFRESH_TOKEN` + `$XANO_CLIENT_ID` pair still',
+    "    works but ROTATES: single-use.",
     "- **Event-driven objects fire on an EPHEMERAL.** A `task` (scheduled), an `mcpServer`,",
     "  and every trigger \u2014 `tableTrigger` included \u2014 run normally on an ephemeral env, which",
     "  is where `deploy` sends them. So test an event-driven design (screen-on-insert, cron",
     "  cleanup, MCP tool call) by deploying it and letting it run.",
-    '- **Zero-based numeric keys make `c.obj` a LIST.** `c.obj({ "0": "a" })` evaluates to',
-    '  `["a"]`: a numeric key IS an index in the engine\'s data model, so keys that are exactly',
-    "  `0..n-1` come back as a list with HTTP 200 and no error. Write `c.array([...])` when you",
-    '  want the list, or prefix the keys (`"k0"`) when you want an object. A non-zero-based',
-    '  numeric key (`{ "2": \u2026 }`) survives as a key. Export warns.',
-    "- **To match every row, omit `where` \u2014 never pass a constant.** `where: c.bool(true)` is",
-    '  not "no filter": a bare scalar literal states no condition and the engine reads the',
-    '  resulting `context.search` as garbage, so it throws. An absent `where` is how "every',
-    '  row" is spelled. A raw `Value` `where` stays the escape hatch for a clause built',
-    '  elsewhere \u2014 `inp("clause")`, `ref("built_where")`, or `c.text("id > 0")`.',
-    "- **An `auth()`-keyed limiter collapses on any host with no caller identity \u2014 at every**",
-    '  **tier.** `s.redis.ratelimit({ key: withFilters(c.text("rl:"), fl.concat(auth("id"))) })`',
-    "  is the per-user form, but `auth()` is `null` on a public query, a task, or a function,",
-    "  and every caller then shares one bucket. Attaching it once at",
-    "  `apiGroup({ middleware })` or the workspace tier is the tempting DRY move and inherits",
-    "  the same collapse onto every member endpoint. Export warns, naming the tier.",
     ""
   );
   const objectKinds = [];
@@ -1262,8 +1189,18 @@ function renderSections(m) {
     '  - `verb`: `"GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD"` (required), UPPERCASE. Anything else \u2014 most often a lowercase `"post"` \u2014 makes `query()` THROW, because Xano does NOT reject it: it stores the verb as NULL, a null verb serves as GET, and the endpoint then answers on the wrong method while the one you meant 404s `Unable to locate request.`',
     "  - `apiGroup`: an `apiGroup()` def handle (or its name) \u2014 binds by guid, stable across syncs. Raw numeric `apiGroupId?` is the escape hatch and wins if both given.",
     '  - `auth`: `false` (no auth) or an auth-table id; `responseType`: `"standard" | "stream"` (default `standard`) \u2014 any other spelling THROWS, since Xano stores an unrecognized one as NULL and a null buffers as `standard`, so a misspelled stream quietly does not stream.',
-    '  - `name` is the endpoint PATH within the group. A `{param}` segment is a URL PATH PARAM bound to the input of the same name, and segments chain: `name: "blog/{slug}/review/{review_id}"` + `input: { slug: input.text(), review_id: input.int() }`. Read it with `inp("slug")` like any other input. Every `{param}` MUST have a matching input or `query()` THROWS \u2014 Xano treats an unbound marker as inert route text, so the endpoint would answer on the path and see nothing. A `{param}` need NOT be a whole segment (`"blog/post-{slug}"` routes fine), but its type must fit one segment (no object/list/json/file/geo/vector); there are no wildcards or patterns. `required: true` is NOT demanded (the engine\'s editor leaves path inputs unmarked). The CONVERSE is warned, not enforced: an input a `GET`/`DELETE`/`HEAD` looks ONE ROW up by (`s.db.get`/`get_by_id`/`has`/by-field edit/patch/delete) belongs in the path \u2014 `export()` warns `query.path-segment-candidate`. It still serves `?blog_id=1`, but the route is not addressable and `getPath()` types STATIC, so a caller cannot pass the value positionally. A segment is any value naming WHICH resource is wanted, not just an id (`"shop/{country}"`). An input that NARROWS A LIST (`s.db.query`) stays a query-string param. Inputs absent from the path are ordinary query-string/body params. Name charset is ONLY `A-Za-z0-9_-/{}`, max 200: a `.` (`"export.zip"`) is NOT rejected by Xano \u2014 it stores an EMPTY name that deploys clean then 404s forever, so `query()` THROWS. Use `"export_zip"` and set the extension in the response headers.',
-    '  - **Client recipe:** `q.getPath({ params: { slug: "hello" } })` \u2192 `/api:<canonical>/blog/hello` \u2014 never interpolate by hand. `getPath` percent-encodes each value (so `?`/`#`/spaces stay in their segment) and throws on what encoding cannot contain: a `/`, and a value that IS `.`/`..` (a URL parser drops those before routing \u2014 `%2e` counts \u2014 addressing a different endpoint). The keys are typed from the literal `name`, so a typo is a compile error. The HANDLE\'s `q.toSearchParams(input)` drops path params for a GET; the free `query.toSearchParams(input)` has no view of the route and keeps every key.',
+    "  - `name` is the endpoint PATH within the group.",
+    '    - A `{param}` segment is a URL PATH PARAM bound to the input of the same name, and segments chain: `name: "blog/{slug}/review/{review_id}"` + `input: { slug: input.text(), review_id: input.int() }`. Read it with `inp("slug")` like any other input.',
+    "    - Every `{param}` MUST have a matching input or `query()` THROWS \u2014 Xano treats an unbound marker as inert route text, so the endpoint would answer on the path and see nothing.",
+    '    - A `{param}` need NOT be a whole segment (`"blog/post-{slug}"` routes fine), but its type must fit one segment (no object/list/json/file/geo/vector); there are no wildcards or patterns. `required: true` is NOT demanded (the engine\'s editor leaves path inputs unmarked).',
+    '    - The CONVERSE is warned, not enforced: an input a `GET`/`DELETE`/`HEAD` looks ONE ROW up by (`s.db.get`/`get_by_id`/`has`/by-field edit/patch/delete) belongs in the path \u2014 `export()` warns `query.path-segment-candidate`. It still serves `?blog_id=1`, but the route is not addressable and `getPath()` types STATIC, so a caller cannot pass the value positionally. A segment is any value naming WHICH resource is wanted, not just an id (`"shop/{country}"`). An input that NARROWS A LIST (`s.db.query`) stays a query-string param.',
+    "    - Inputs absent from the path are ordinary query-string/body params.",
+    '    - Name charset is ONLY `A-Za-z0-9_-/{}`, max 200: a `.` (`"export.zip"`) is NOT rejected by Xano \u2014 it stores an EMPTY name that deploys clean then 404s forever, so `query()` THROWS. Use `"export_zip"` and set the extension in the response headers.',
+    '  - **Client recipe:** `q.getPath({ params: { slug: "hello" } })` \u2192 `/api:<canonical>/blog/hello` \u2014 never interpolate by hand.',
+    "    - `getPath` percent-encodes each value (so `?`/`#`/spaces stay in their segment) and throws on what encoding cannot contain: a `/`, and a value that IS `.`/`..` (a URL parser drops those before routing \u2014 `%2e` counts \u2014 addressing a different endpoint).",
+    "    - The keys are typed from the literal `name`, so a typo is a compile error.",
+    "    - The HANDLE's `q.toSearchParams(input)` drops path params for a GET; the free `query.toSearchParams(input)` has no view of the route and keeps every key.",
+    "  - What importing a def costs a browser bundle, the `routes.gen.ts` alternative, and how to spot-check a def from Node: `llms/client.md`.",
     "- `apiGroup({ name, guid?, canonical?, description?, docs?, swagger?, apiGroupEnabled?, documentation?, cors? })` \u2014 a query container; register it and bind queries to it via their `apiGroup`.",
     "  - `cors?`: `{ mode?, allowOrigins?: string[], allowHeaders?: string[], allowCredentials?, maxAge?, allowMethods?: { get?, post?, put?, patch?, delete?, head? } }`.",
     '    - `mode?`: `"default"` (the default) | `"custom"` | `"disabled"`, lowercase \u2014 a fourth value THROWS at export (`apiGroup()` itself does not check), because Xano neither rejects nor blanks it: it DROPS THE WHOLE API GROUP on import, so the deploy succeeds and every query in the group 404s. \u26A0 Every OTHER field applies only under `"custom"`: `"default"` serves a FIXED permissive policy (any origin, `allow-headers: *`, `allow-credentials: true`, `max-age: 86400`) and ignores the block, so setting `maxAge`/`allowCredentials`/`allowHeaders` alone changes nothing. `"disabled"` sends no CORS headers at all, so every browser call fails.',
@@ -1315,6 +1252,10 @@ function renderSections(m) {
     "  `ambiguous-condition`.",
     "- A **filtered** operand (`withFilters(...)`) works inline in any condition/`where` (conditional,",
     '  while, `db.query`/addon, \u2026) \u2014 e.g. `cmp(withFilters(col("title"), fl.trim()), "=", inp("q"))`.',
+    "- **Compose a rule set as SIBLINGS, not a folded chain.** `and(...rules)` takes any",
+    "  number of terms and encodes flat; `rules.reduce((acc, r) => and(acc, r))` nests one",
+    "  container per rule, which costs quadratic bytes (512 terms: 394 KiB flat, 21 MiB",
+    "  folded) and is refused past 128 levels. Mixed joins: `and(or(...anyOf), ...allOf)`.",
     '- e.g. `db.query({ table: posts, where: expr(col("author"), "=", auth("id")), as: "rows" })`.',
     ""
   ];
@@ -1336,6 +1277,79 @@ function renderSections(m) {
     '- \u26A0 `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."
   ];
+  const client = [
+    "Importing a def into a browser bundle or a Node script \u2014 for `getPath()`, `getUrl()`, `verb`, or `InferResponse` \u2014 runs its factory calls; these are the costs and the checks.",
+    "",
+    "- **Client bundle size / tree-shaking.** `@xanots/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.",
+    "  \u26A0 A FLOOR \u2014 **~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: `xanots routes <entry> --emit xano/routes.gen.ts` (`paths` is an accepted alias) \u2014 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** \u2014 not `tsx -e "import \u2026"`',
+    "  (its CJS-preparse mis-resolves the package `exports` map \u2192 ERR_PACKAGE_PATH_NOT_EXPORTED),",
+    "  and not bare `node file.ts` (chokes on the `.js`-specifier intra-workspace imports the",
+    "  xanots CLI's own loader resolves). Running from outside the project root also breaks",
+    "  the `@xanots/sdk` specifier resolution.",
+    "",
+    "**Reading the injected backend URL.** `xanots 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;",
+    "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`) \u2014 without it the var reads as undefined, the",
+    "host falls back to '', and every call 404s off the dev server.",
+    '\u26A0 It is INJECTED in bracket form \u2014 `window["XANO_HOST"]="\u2026"` \u2014 so verifying a deploy',
+    "by grepping `window.XANO_HOST` matches nothing and reads as a failed inject. Grep the",
+    "bare `XANO_HOST` token.",
+    "**Displaying a stored file.** A file column comes back as `{ path, name, type, size,",
+    "meta, access, url }`. \u26A0 Do NOT use its `url`: on a tenant-scoped environment that field",
+    "addresses the instance host WITHOUT the `/tenant/<name>` segment and 404s, silently \u2014",
+    "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."
+  ];
+  const errors = [
+    "### Request-time (deployed) failures",
+    "",
+    '- `Unable to locate input: <name>` \u2014 `inp()` names an undeclared input, or an attached middleware reads its own `input` (never bound). Declare it; a stack value is `ref("var.field")`; middleware reads the body with `s.util.get_all_input`. `llms.txt`; `llms/kinds-core.md`.',
+    "- `Unable to locate var: <a.b>` (HTTP 500) \u2014 a dotted `ref` into a null base (a `db.get` miss), or a column absent from the row (`f.password` is `internal`). Guard existence first, or use the null-safe `safe` option; name the column in `output`. `llms.txt`.",
+    "- `Missing var entry: <name>` inside `s.expect.to_throw` \u2014 the body runs in an isolated var stack; bind what it needs inside the body. `llms/tests.md`.",
+    "- `Missing param: field_value` (HTTP 400) \u2014 a `db.*` match argument resolved to `null` (a safe ref, a nullable foreign key). Guard existence before the lookup; an optional FK stores `0` and is read with field-match `db.get`. `llms.txt`; `llms/fields.md`.",
+    "- `Value is less than the minimum value of 1` (HTTP 400) \u2014 `db.get_by_id` given `0`; use field-match `db.get`. `llms/statements-data.md`.",
+    "- `Invalid op: <op>` \u2014 a `cmp` operator (`in`, `like`, \u2026) in a RUNTIME condition, which takes the `expr` set only; write `or(expr(...), expr(...))`. `llms/kinds-core.md`.",
+    "- `Unsupported param format` / `Unsupported parameter reference` \u2014 an aggregate or `eval` `name` that is not a bare column, or a bare `eval` name for a joined column. `llms/statements-data.md`.",
+    "- `ParseError: Invalid value for param` (HTTP 400) \u2014 `contains`/`@>`/`overlaps` on a text column (use `includes`), or a joined column qualified without `tableAlias`. `llms/statements-data.md`.",
+    "- `ERROR_FATAL: <Type> does not exist: <type>:<n>` \u2014 `s.api.call`/`s.task.call`/`s.trigger.call`/`s.workflow_test.call` outside a workflow test; share logic via `defineFunction` + `s.function.run`. `llms.txt`.",
+    '- `ERROR_FATAL "Unable to decode."` \u2014 a populated JSON string where the engine expects `c.obj`\'s form; write `c.obj({...})` or `obj({...})`. `llms/values.md`.',
+    '- `Precondition failed.` in place of your message \u2014 `error` was a bare string; pass `c.text("\u2026")`. `llms/fields.md`.',
+    "- `Param: token - Text filter requires an integer, float, string or boolean value` \u2014 `s.api.call` `auth.token` given a tagged `Value`; it must be a bare string. `llms/statements-calls.md`.",
+    "- Every `s.db.add` into one table 400s naming a column while complaining about its VALUE \u2014 the column is named `run`. `llms.txt`.",
+    '- HTTP 200 with an EMPTY body where `0` was expected \u2014 a bare `returnType: "count"` of zero; wrap it as `{ count: ref("n") }`. `llms/statements-data.md`.',
+    '- A lambda returns error TEXT with HTTP 200 (`Could not resolve "node:crypto"`, an undefined-binding message) \u2014 the body threw; use the preloaded globals, the surface\'s bindings, and `capture`. `llms/lambda.md`.',
+    "- `Unable to locate request.` (404) on an endpoint that deployed \u2014 a lowercase verb, a `.` in the name, or a CORS `mode` typo that dropped the whole API group. `llms/kinds-core.md`.",
+    '- A browser call fails on a missing `access-control-allow-origin` while deploy looks fine \u2014 CORS `mode: "custom"` with `"*"` or an unmatched origin. `llms/kinds-core.md`.',
+    "- A websocket is closed right after the handshake \u2014 a refused `connect` gate: an empty/falsy return, a crash, or a gating trigger with no `response`. `llms/triggers.md`.",
+    "- `to_throw failed - response is ok` around an auth-refused call \u2014 `ERROR_CODE_ACCESS_DENIED` carries no message; the auth gate is not reachable from a workflow test. `llms/tests.md`.",
+    "- Output reads `Hi [object Object]` \u2014 a tagged value inside a JS template literal; compose at runtime with `withFilters` + `fl.concat`. `llms.txt`.",
+    "",
+    "### Build-time and tooling failures",
+    "",
+    '- `must be ES modules` \u2014 package.json says `"type": "commonjs"`; set `"type": "module"`. `llms.txt` Quickstart.',
+    "- A response types as `StackTupleWidened` \u2014 a `Statement[]` helper was spread into the stack; return `statements(...)`. `llms.txt`; `llms/statements-runtime.md`.",
+    '- `ERR_PACKAGE_PATH_NOT_EXPORTED` \u2014 `tsx -e "import \u2026"`, or running from outside the project root; run a real file with `tsx <file.ts>` from the root. `llms/client.md`.',
+    "- `Missing statement: mvp:placeholder` on import \u2014 an unconfigured slot in a pulled tree; replace it with the statement it stands in for. `llms/legacy.md`."
+  ];
   const kindsAgentMcp = [
     "- `mcpServer({ name, guid?, description?, instructions?, docs?, enabled?, canonical?, spec?, tags?, history?, tools?, llm?, output? })` \u2014 an MCP toolset. `llm?`/`output?` are the same blocks `agent()` takes and are usually absent: an MCP server and an agent are ONE stored object distinguished by `type`. Returns a handle with `getPath()`/`getUrl(baseUrl)` for the Streamable-HTTP endpoint \u2014 `getUrl` is NOT idempotent, a `baseUrl` already carrying an `/x2/mcp/<\u2026>/stream` path THROWS, so resolve ONCE from the instance base URL. Fires on an ephemeral.",
     "  - `tools?`: a `ToolsetToolEntry[]`. Pass the `tool()` HANDLES directly (`tools: [saveNote]`), like every other collection in the SDK; use the `{ tool, enabled?, auth? }` wrapper only when a tool needs `enabled: false` or per-tool `auth`. `auth` names an auth **table** (a `table({ auth: true })` handle or its name) \u2014 Xano's ONLY MCP auth surface (per-tool; there is no server-level gate). An entry that names no tool (no handle, no `id`) THROWS at export rather than emitting the `id: 0` null reference it used to; a deliberate raw `id: 0` warns and is carried through, so a pulled workspace still round-trips.",
@@ -1344,7 +1358,8 @@ function renderSections(m) {
     "  - `tools?`: same `ToolsetToolEntry[]` as `mcpServer` \u2014 bare `tool()` handles, or a `{ tool, enabled?, auth? }` wrapper when one needs `enabled`/`auth`.",
     '  - `output?`: `{ schema: Record<string, input.*>, enabled? }` \u2014 structured-output schema. `schema` is a named-field record authored with the `input.*` catalog, exactly like a `defineFunction`/`query` `input:` map (the stored `structuredOutputsSchema` is the same wire shape as function inputs). e.g. `output: { schema: { priority: input.enum(["low","high"]), summary: input.text() } }`. When you pass the agent *handle* to `s.ai.agent.run({ agent })`, `.result` is typed straight from this schema \u2014 no `resultShape` witness needed (the shape is declared once). `resultShape` remains only to override that, or to type an agent referenced by bare name.',
     '  - **Run + read recipe (`s.ai.agent.run`):** bind the run to a var (`s.ai.agent.run({ agent, args, as: "run" })`) \u2014 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") }` \u2014 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 \u2014 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>`."
+    "  - **Marketplace:** for chat history, use `@xanots/chatbot`; for vector RAG, use `@xanots/vector` (`tools: [vector.searchTool]`). Find add-ons with `xanots marketplace search <q>`.",
+    "- Both kinds persist under the `toolset` payload key, so a same-name `agent` + `mcpServer` pair derives ONE guid and `export()` throws \u2014 give them distinct names."
   ];
   const kindsRealtime = [
     "- **Realtime** \u2014 the only three-level chain: `realtimeServer` owns `realtimeChannel`s, which own `realtimeMessage` handlers. Pass the HANDLE, not a name (a channel path is unique only within its server).",
@@ -1365,11 +1380,11 @@ function renderSections(m) {
     '    - `deliverTo?`: `"channel"` (default) | `"sender"` | `"others"` | `"explicit"`. \u26A0 `"explicit"` still delivers to NOBODY \u2014 nothing selects recipients from inside a handler, and `s.realtime.publish` (which originates an event INTO a channel) is not a substitute.',
     '    - Only `"channel"`/`"others"` fan out AND are written to the `conversation` transcript \u2014 a `"sender"` response is invisible to every future joiner.',
     '  - **Both input surfaces read as ordinary inputs:** `inp("body")` for a payload field, `inp("room_id")` for the channel\'s `{room_id}`. No session lookup, no frame parsing.',
-    "    - A path param is bound ONCE at join and read from the connection thereafter, never from the frame \u2014 a sender cannot claim a room it did not join. The same values reach a channel `join`/`leave` trigger's stack.",
+    "    - A path param is bound ONCE at join and read from the connection thereafter, never from the frame \u2014 a sender cannot claim a room it did not join.",
     "  - `s.realtime.get_session({ as })` \u2014 the CALLER's realtime session for the current frame. FLAT shape:",
     '    - `authenticated` bool \xB7 `client_id` text (the AUTHED ROW ID as text, `""` anonymous) \xB7 `dbo_id` int (the auth TABLE\'s id \u2014 NOT the user\'s row id; `0` anonymous \u2014 to look the caller up use `client_id`. `dbo_id` is an int in the same position and typechecks, so a gate that keys on it finds no user and refuses EVERYONE) \xB7 `socket_id` int (transport id) \xB7 `channel` text (resolved path, `""` in a server trigger) \xB7 `params` object (bound path params, `{}` when none \u2014 `ref("session.params.room_id")`) \xB7 `extras` object \xB7 `opened_at` decimal.',
     "    - Works in a realtime MESSAGE stack and in CHANNEL and SERVER trigger stacks; off that path it degrades to an anonymous session.",
-    '    - For a path param prefer `inp("room_id")`. Reach for the session when you need the CONNECTION (identity/extras) \u2014 "who is this sender" on an anonymous-client channel.',
+    '    - For a path param prefer `inp("room_id")` in a MESSAGE; a lifecycle TRIGGER has only the session. Reach for the session when you need the CONNECTION (identity/extras) \u2014 "who is this sender" on an anonymous-client channel.',
     "    - \u26A0 THREE UNRELATED THINGS ARE CALLED A CLIENT ID: `session.client_id` (app-facing identity), `session.socket_id` (transport), and a frame's `options.client_id` (the at_least_once CURSOR handle). Conflating the first and last breaks at_least_once for anonymous clients.",
     "  - `s.realtime.publish({ server, channel, data, message?, authTable?, authId? })` \u2014 the PUSH direction: originate a server-authored event onto a channel from ANY stack, no client frame first.",
     "    - `server` is the handle or its NAME (resolved by name, not guid); `channel` is the FILLED-IN path (`channel.getChannel({ room_id: 42 })`), never the template \u2014 a constant still carrying `{param}` THROWS at author time, and a constant `server`/`channel` naming nothing this workspace registers WARNS at export.",
@@ -1404,7 +1419,7 @@ function renderSections(m) {
     "  - **Conversation frames \u2014 the transcript hydrates the client, so DO NOT build a hydration endpoint.**",
     '    - On a `conversation` channel the replay is PUSHED automatically at join, unasked: `conversation_start` (`payload.count`) \u2192 the last `limit` messages, each a normal `action: "message"` frame carrying its ORIGINAL `type` and `payload` plus `conversation: true` and the original `ts` \u2192 `conversation_end`.',
     "    - So the client needs NO fetch, no `GET /messages`, and no table read to paint the initial view. Render `message` frames identically either way; the backfill paints itself.",
-    "    - \u26A0 `{ enabled: true }` ALONE IS A NO-OP: `limit` defaults to 0, and 0 means RETAIN NONE (not retain everything), so the transcript is never written and never replayed, with no error. ALWAYS PASS `limit`.",
+    "    - \u26A0 `{ enabled: true }` alone is a no-op: `limit` defaults to 0 and 0 means RETAIN NONE (see `conversation` above) \u2014 always pass `limit`.",
     "    - The POST-HANDLER broadcast payload IS the stored transcript row \u2014 a handler must broadcast everything the UI needs to render a past message (author name, id, `created_at`). Nothing else is replayed.",
     '    - Only `deliverTo` `"channel"`/`"others"` are RECORDED, so a `"sender"` response is invisible to every future joiner by construction.',
     "    - The transcript is a capped ring (`limit`, `ttl`), not storage. Persist to a table only for durability, search, or reads BEYOND that window \u2014 never merely to hydrate a joiner.",
@@ -1437,8 +1452,20 @@ function renderSections(m) {
     "errorTrigger}({ name, guid?, description?, active?, tags?, ... })`.",
     "",
     '- `tableTrigger({ name, table?, datasources?, actions?: {insert?,update?,delete?,truncate?}, stack })` \u2014 database/table trigger. `t.new` / `t.old` are the row **after** / **before** the change; `t.action` (`insert|update|delete|truncate`), `t.datasource`. Bind `table` to a `table()` handle and `t.new("col")` / `t.old("col")` are typed to that row (misspelled column = compile error). Nullability follows the enabled actions: insert \u2192 `old` is null, delete \u2192 `new` is null, update \u2192 both, truncate \u2192 neither. Config-only (no response).',
-    "- `realtimeServerTrigger({ name, realtimeServer, actions?: {connect?,disconnect?}, stack?, response?, responseShape? })` \u2014 realtime SERVER lifecycle (a client connecting to / disconnecting from the server, not a message). Inputs: `t.action` (`connect|disconnect`), `t.realtime_server`, `t.client`. Bind `realtimeServer` to a `realtimeServer()` handle (or its name). `connect` GATES the connection \u2014 a denial sends an `error` and CLOSES the socket with code 4401 before it is ever ready, so it is a real front door, not an observer; same return shape as a channel `join` (`{ allowed: c.bool(true) }` or any truthy value admits, EMPTY/FALSY DENIES \u2014 INCLUDING a gating trigger with NO `response`, which returns nothing and so refuses every client). A CRASH DENIES too \u2014 the transport seeds a deny and keeps it on a throw. Both failure modes lock the door, so plan for a self-inflicted LOCKOUT (an unguarded drill into a null `db.get` raises \u2192 everyone refused), not a breach. Gating is OPT-IN: a server with no `connect` trigger accepts every connection. `disconnect` is OBSERVATIONAL (return ignored, throws swallowed \u2014 cleanup must always complete). Both are SERVER-scoped, so `s.realtime.get_session` works but carries no channel path and no bound params.",
-    '- `realtimeChannelTrigger({ name, channel, actions?: {join?,leave?,deliver?}, stack?, response?, responseShape? })` \u2014 realtime CHANNEL lifecycle. Inputs: `t.action` (`join|leave|deliver`), `t.channel`, `t.client`. Bind `channel` to a `realtimeChannel()` handle \u2014 a bare path is NOT accepted (it is unique only within its server). The three actions have DIFFERENT postures, and the posture decides what the stack should return: `join` GATES the join (it runs BEFORE the client becomes a member, so a denial means it never sees a fan-out) \u2014 return `{ allowed: c.bool(true) }` (optional `reason` reaches the client) or any truthy value to admit, and an EMPTY OR FALSY RETURN DENIES, so a stack that just falls through \u2014 or a gating trigger with NO `response` \u2014 refuses everyone, and a CRASH DENIES too. That is the inverse of a normal message (a crashing message still delivers) and of `deliver` below (a gate that fails OPEN). `join`/`leave` bind the channel\'s typed path params as INPUTS, so `inp("room_id")` resolves and the gate decides per room; a SERVER connect/disconnect has no channel, the one place a path param cannot be read; `leave` is OBSERVATIONAL (return ignored, throws swallowed); `deliver` GATES delivery PER RECIPIENT \u2014 the per-viewer redaction tool and the most expensive action here (a stack per recipient per message), and it needs `delivery.perRecipient` on the channel to run at all \u2014 BOTH HALVES are required, so a `deliver` trigger on a channel without the flag NEVER RUNS and every subscriber receives the UNREDACTED payload (no error, no log line); `export()` warns on each half alone. **`deliver`\'s RETURN VALUES DO NOT READ LIKE A FILTER:** ONLY an explicit NULL drops the message for that recipient; an OBJECT replaces that recipient\'s payload; ANYTHING ELSE \u2014 INCLUDING `false`, `0`, `""` \u2014 DELIVERS IT UNCHANGED, as does a crash. So `return false` from a yes/no redaction check SENDS the message it was written to suppress \u2014 return null instead. The delivered payload arrives NESTED, so read `inp("payload").<field>`, and `t.client` is the SENDER while `s.realtime.get_session` describes the RECIPIENT this run is for.',
+    "- `realtimeServerTrigger({ name, realtimeServer, actions?: {connect?,disconnect?}, stack?, response?, responseShape? })` \u2014 realtime SERVER lifecycle (a client connecting to / disconnecting from the server, not a message). Inputs: `t.action` (`connect|disconnect`), `t.realtime_server`, `t.client`. Bind `realtimeServer` to a `realtimeServer()` handle (or its name).",
+    "  - `connect` GATES the connection \u2014 a denial sends an `error` and CLOSES the socket with code 4401 before it is ever ready, so it is a real front door, not an observer; same return shape as a channel `join` below (EMPTY/FALSY DENIES \u2014 INCLUDING a gating trigger with NO `response`, which returns nothing and so refuses every client).",
+    "  - A CRASH DENIES too \u2014 a gate that cannot answer must not admit. Both failure modes lock the door, so plan for a self-inflicted LOCKOUT (an unguarded drill into a null `db.get` raises \u2192 everyone refused), not a breach.",
+    "  - Gating is OPT-IN: a server with no `connect` trigger accepts every connection.",
+    "  - `disconnect` is OBSERVATIONAL (return ignored, throws swallowed \u2014 cleanup must always complete).",
+    "  - Both are SERVER-scoped, so `s.realtime.get_session` works but carries no channel path and no bound params.",
+    "- `realtimeChannelTrigger({ name, channel, actions?: {join?,leave?,deliver?}, stack?, response?, responseShape? })` \u2014 realtime CHANNEL lifecycle. Inputs: `t.action` (`join|leave|deliver`), `t.channel`, `t.payload`, `t.client`. Bind `channel` to a `realtimeChannel()` handle \u2014 a bare path is NOT accepted (it is unique only within its server). The three actions have DIFFERENT postures, and the posture decides what the stack should return:",
+    '  - `join` GATES the join (it runs BEFORE the client becomes a member, so a denial means it never sees a fan-out) \u2014 return `{ allowed: c.bool(true) }` (optional `reason` reaches the client) or any truthy value to admit, and an EMPTY OR FALSY RETURN DENIES, so a stack that just falls through \u2014 or a gating trigger with NO `response` \u2014 refuses everyone, and a CRASH DENIES too. ONCE the object carries an `allowed` key admission needs STRICTLY `true` \u2014 a computed `1`/`"yes"` there DENIES. That is the inverse of a crashing message, which still delivers, and of `deliver` below.',
+    '  - A lifecycle trigger\'s inputs are PINNED to those four, so a channel PATH PARAM is NOT among them \u2014 `inp("room_id")` RAISES, which crashes the gate and so REFUSES every client; take the param from `s.realtime.get_session` (`ref("session.params.room_id")`).',
+    '  - A gate establishes NO auth, so `ref("auth.id")` reads 0 even when authenticated \u2014 identity is `t.client("permissions.dbo_id")` or the session. A SERVER connect/disconnect has no channel, so no params at all.',
+    "  - `leave` is OBSERVATIONAL (return ignored, throws swallowed).",
+    "  - `deliver` GATES delivery PER RECIPIENT \u2014 the per-viewer redaction tool and the most expensive action here (a stack per recipient per message), and it needs `delivery.perRecipient` on the channel to run at all \u2014 BOTH HALVES are required, so a `deliver` trigger on a channel without the flag NEVER RUNS and every subscriber receives the UNREDACTED payload (no error, no log line); `export()` warns on each half alone.",
+    "  - **`deliver`'s RETURN VALUES DO NOT READ LIKE A FILTER:** ONLY an explicit NULL drops the message for that recipient; an OBJECT replaces that recipient's payload; ANYTHING ELSE \u2014 INCLUDING `false`, `0`, `\"\"` \u2014 DELIVERS IT UNCHANGED, as does a crash. So `return false` from a yes/no redaction check SENDS the message it was written to suppress \u2014 return null instead.",
+    '  - The delivered payload arrives NESTED, so read `t.payload("<field>")`, and `t.client` is the SENDER while `s.realtime.get_session` describes the RECIPIENT this run is for.',
     '- `mcpServerTrigger({ name, mcpServer, stack?, response?, responseShape? })` / `agentTrigger({ name, agent, stack?, response?, responseShape? })` \u2014 toolset connection. Bind with the `mcpServer()`/`agent()` def handle (or its name) \u2014 it resolves to the toolset guid at export. Raw numeric `objId` is the escape hatch, rarely right: ids are assigned at import, so a handle passed to `objId` is a type error, and binding nothing deploys a trigger that never fires. Inputs: `t.toolset` (`t.toolset("name")`), `t.tools`. Response-bearing; the default stack copies `toolset`/`tools` into vars and returns them.',
     "- `workspaceTrigger({ name, actions?: {branch_live?,branch_merge?,branch_new?}, stack? })` \u2014 branch lifecycle. Inputs: `t.to_branch`, `t.from_branch`, `t.action`. Config-only.",
     '- `errorTrigger({ name, stack? })` \u2014 error-signature trigger. Inputs: `t.event` (`new|regression|fixed`), `t.id`, `t.signature`, `t.error` (`t.error("code")`/`t.error("message")`), `t.caller`, `t.statement`, `t.actor`, `t.count`, `t.first_seen`, `t.last_seen`, `t.fixed_at`. Config-only.',
@@ -1498,6 +1525,31 @@ function renderSections(m) {
     "queries it.",
     "`{ array: true }` makes any `f.*` scalar a **list column** \u2014 `f.text({ array: true })`",
     "surfaces as `string[]` in `InferRow<typeof table>` (the column analogue of `input.list`).",
+    "**Seed a table's starting rows with `table({ seed })`.** `seed` takes rows",
+    "typed against the table's schema as a WRITE shape (a column without",
+    "`required: true`, and the system columns, may be omitted; `null` needs",
+    '`nullable: true`) \u2014 inline (`seed: [{ name: "\u2026" }]`), a FILE',
+    '(`seed: seedFile("./seed.json", import.meta.url)`; path resolves against the DECLARING',
+    'file), or a thunk (`seed: () => import("./seed.json")`, async ok, `.default` unwrapped).',
+    "Inline rows are TYPED against the schema at compile time; a `seedFile`/thunk seed is",
+    "NOT \u2014 the JSON is opaque to the typechecker, and the `xanots export`/`deploy` CLI",
+    "validates it instead, naming the row index, the offending column, and the known",
+    "columns. \u26A0 Prefer `seedFile` for a file: a thunk's `import()` sits in",
+    "YOUR module, so a bundler emits the JSON as a served chunk. NEITHER is a secrecy",
+    "boundary \u2014 a bundler that inlines the asset ships them either way. Never put secrets",
+    "in `seed`. `deploy --static` REFUSES a build carrying internal/sensitive seed values;",
+    "`--allow-seed-in-static` overrides for deliberately public demo credentials.",
+    "Deploy is a full replace, so re-deploying re-seeds",
+    "cleanly (no duplication). Omit `id` and rows auto-number `1..N` (int PK) or take",
+    "a stable derived uuid (uuid PK); supplying `id` pins it (engine preserves it,",
+    "resets an int sequence past the max). All-or-nothing \u2014 mixing explicit and",
+    "omitted `id` throws. A `system:false` PK is the author's to supply. Pinning is",
+    "`seed`-only \u2014 `s.db.bulk.add` DROPS `id` unless `allowIdField: true`.",
+    "**`use_xdo` storage mode.** Workspace setting (`registerWorkspace({ use_xdo })`,",
+    "default `false`) controlling whether fields are stored as JSON under the `xdo`",
+    "column (`true`, adds a `gin(xdo)` index) or as real columns (`false`, no gin).",
+    "Tables inherit it; override per-table with `table({ useXdo })`. Resolved at",
+    "`export()`, so the workspace and tables can be registered in any order.",
     "A **column `default` must stay within the BMP** \u2014 a 4-byte character (codepoint > U+FFFF,",
     "e.g. an emoji) is mangled into invalid UTF-8 by the engine's default pipeline and is rejected",
     "at export rather than 500ing at deploy (Postgres `22021`); BMP defaults (accents, `\u20AC`, most",
@@ -1586,14 +1638,10 @@ function renderSections(m) {
     "database with a single `s.db.direct_query` UPDATE (`SET clicks = clicks + 1 WHERE \u2026`),",
     "which the DB applies atomically. Reserve the pipeline form for low-contention counters",
     "where a rare lost update is acceptable.",
-    "\u26A0 `direct_query` needs the table's PHYSICAL Postgres name, which the typed surface",
-    "does NOT expose: the engine derives it from ids assigned at import \u2014 not knowable from a",
-    "`table()` def (identity is a name + guid, not the numeric id) \u2014 and `sql_name` persists",
-    "empty. The derived name is also NOT STABLE: a deploy is a full replace, so every table is",
-    "created afresh and the id in its name moves each time, on the same unchanged project. So",
-    "the safe counter drops out of the typed surface: resolve the physical name from",
-    "`information_schema` inside the request that uses it, and never store, cache or hardcode",
-    "one. A typed atomic path needs an engine change.",
+    "\u26A0 `direct_query` needs the table's PHYSICAL Postgres name, which the typed surface does NOT",
+    "expose and which is NOT STABLE across deploys \u2014 resolve it from `information_schema` inside",
+    "the request that uses it, never store or hardcode one (rules under `s.db.direct_query` in",
+    "`llms/statements-data.md`). A typed atomic path needs an engine change.",
     ""
   );
   const argFilters = m.filters.filter((fl) => fl.args?.length);
@@ -1754,12 +1802,27 @@ function renderSections(m) {
     "  - Attaching a typed `addon({ table, output })` handle merges its alias (the last `as` segment) onto the row in `InferResponse`: `{cols}` for `single`, `{cols}[]` for `list`, `number` for `count`, `boolean` for `exists`, and for `aggregate` an array keyed by the `group`/`eval` aliases (`unknown` values; `unknown` when neither is declared).",
     "  - An attachment-level `output` narrows an object/array graft further. A bare-NAME reference grafts `unknown` \u2014 narrow it at the call site.",
     "  - \u26A0 An alias that shadows an existing column on the queried table throws at build time; rename with a `_` prefix.",
-    "- **Middleware attachment** runs a reusable `middleware({...})` before/after a host's own stack. Attach with the host's `middleware: { pre, post }` field on `query`/`function`/`task`/`tool`/`apiGroup` (NOT triggers): each phase is an ordered list of middleware refs (def handle or name), or `{ middleware, active: false }` to keep an entry disabled. Providing a phase **overrides** it (sets the stored `pre_customize`/`post_customize` flag); omitting a phase **inherits** the parent tier's chain \u2014 the engine resolves Query \u2192 API Group \u2192 Workspace at request time (override, not merge; the API-Group tier applies to queries \u2014 functions/tasks/tools have no API-group binding and inherit straight from the workspace). Prefer a def handle over a bare name when the middleware pins an explicit `guid`. `pre: middleware.clear()` (an empty list) overrides with nothing \u2014 stop inheriting. Workspace-level defaults are the terminal tier: `workspaceConfig({ middleware: { query: { pre }, function, task, tool } })` emits the flat `{host}_{phase}` map (no `_customize` flags) \u2014 setting it replaces the whole workspace map, so unlisted hosts are cleared; omit the field to leave existing workspace middleware untouched. Distinct from `s.middleware.call` (inline invoke).",
-    '- **Middleware request context.** A `pre` middleware runs **after** auth resolution, so `auth()` is available inside the middleware when the host is authenticated (its `auth` names an auth table); on a public host `auth()` is `null`. This matters for the canonical use \u2014 a rate limit keyed by `auth("id")`: on an authenticated endpoint the bucket is per-user, but attach the same middleware to a public endpoint and every anonymous caller keys under the same `null` id (one shared bucket), silently. To catch that, `export()` **warns** (never blocks) when a middleware whose stack references `auth()` is directly attached to a host where `auth()` may be null \u2014 a `query` with no auth table, a `task` (scheduled, never authenticated), or a `function`/`tool` (whose auth is caller-dependent). An authenticated query (its own `auth` table set) is skipped. The check is direct-attachment only; a middleware reaching a public query via API-group/workspace tier inheritance is not caught.',
-    '- **Rate-limit recipe (the canonical middleware).** Per-user rate limiting is the most common middleware. Author it with `s.redis.ratelimit` and a **composite key** built via the filter chain \u2014 `"prefix" + auth("id")` does not exist, you build the key: `middleware({ name: "write_rl", exceptionPolicy: "rethrow", stack: [ s.redis.ratelimit({ key: withFilters(c.text("rl:write:"), fl.concat(auth("id"))), max: c.int(10), ttl: c.int(30), error: c.text("Too fast.") }) ] })`. `exceptionPolicy` defaults to `"rethrow"`, which is what makes a tripped limit abort with HTTP 429; `"silent"` would let the over-limit request through. Attach it with `middleware: { pre: [writeRl] }` on an **authenticated** host (its `auth` set) so `auth("id")` keys per-user; on a public host `auth("id")` is null and every caller shares one bucket (`export()` warns \u2014 see request context above). **Shared-bucket rule:** co-attaching one middleware object to N hosts means all N share the *same* key \u21D2 *one* counter \u2014 `max: 10` is a global per-user budget across them, not 10-per-host. Vary the key (fold in the host/action name) for an independent limit per host.',
+    "- **Middleware attachment** runs a reusable `middleware({...})` before/after a host's own stack. Distinct from `s.middleware.call` (inline invoke).",
+    "  - Attach with the host's `middleware: { pre, post }` field on `query`/`function`/`task`/`tool`/`apiGroup` (NOT triggers): each phase is an ordered list of middleware refs (def handle or name), or `{ middleware, active: false }` to keep an entry disabled.",
+    "  - Providing a phase **overrides** it (sets the stored `pre_customize`/`post_customize` flag); omitting a phase **inherits** the parent tier's chain \u2014 the engine resolves Query \u2192 API Group \u2192 Workspace at request time (override, not merge; the API-Group tier applies to queries \u2014 functions/tasks/tools have no API-group binding and inherit straight from the workspace).",
+    "  - Prefer a def handle over a bare name when the middleware pins an explicit `guid`.",
+    "  - `pre: middleware.clear()` (an empty list) overrides with nothing \u2014 stop inheriting.",
+    "  - Workspace-level defaults are the terminal tier: `workspaceConfig({ middleware: { query: { pre }, function, task, tool } })` emits the flat `{host}_{phase}` map (no `_customize` flags) \u2014 setting it replaces the whole workspace map, so unlisted hosts are cleared; omit the field to leave existing workspace middleware untouched.",
+    "- **Middleware request context.** A `pre` middleware runs **after** auth resolution, so `auth()` is available inside the middleware when the host is authenticated (its `auth` names an auth table); on a public host `auth()` is `null`.",
+    '  - This matters for the canonical use \u2014 a rate limit keyed by `auth("id")`: on an authenticated endpoint the bucket is per-user, but attach the same middleware to a public endpoint and every anonymous caller keys under the same `null` id (one shared bucket), silently.',
+    "  - To catch that, `export()` **warns** (never blocks) when a middleware whose stack references `auth()` is directly attached to a host where `auth()` may be null \u2014 a `query` with no auth table, a `task` (scheduled, never authenticated), or a `function`/`tool` (whose auth is caller-dependent). An authenticated query (its own `auth` table set) is skipped.",
+    "  - The check is direct-attachment only; a middleware reaching a public query via API-group/workspace tier inheritance is not caught.",
+    '- **Rate-limit recipe (the canonical middleware).** Per-user rate limiting is the most common middleware. Author it with `s.redis.ratelimit` and a **composite key** built via the filter chain \u2014 `"prefix" + auth("id")` does not exist, you build the key: `middleware({ name: "write_rl", exceptionPolicy: "rethrow", stack: [ s.redis.ratelimit({ key: withFilters(c.text("rl:write:"), fl.concat(auth("id"))), max: c.int(10), ttl: c.int(30), error: c.text("Too fast.") }) ] })`.',
+    '  - `exceptionPolicy` defaults to `"rethrow"`, which is what makes a tripped limit abort with HTTP 429; `"silent"` would let the over-limit request through.',
+    '  - Attach it with `middleware: { pre: [writeRl] }` on an **authenticated** host (its `auth` set) so `auth("id")` keys per-user; on a public host `auth("id")` is null and every caller shares one bucket (`export()` warns \u2014 see request context above).',
+    "  - **Shared-bucket rule:** co-attaching one middleware object to N hosts means all N share the *same* key \u21D2 *one* counter \u2014 `max: 10` is a global per-user budget across them, not 10-per-host. Vary the key (fold in the host/action name) for an independent limit per host.",
     '- **Middleware `exceptionPolicy`** governs what a **throw** in the middleware stack does to the request (XanoTS passes the value through; the Xano engine interprets it). `"rethrow"` is the **default** \u2014 the throw aborts the request and surfaces the authored `error`/status (a tripped `s.redis.ratelimit` \u2192 HTTP 429); the `post` chain still runs. `"silent"` swallows the throw, so a guard set to it is **not enforced** \u2014 advisory middleware only. `"critical"` is `"rethrow"` plus skipping the `post` chain. The only difference between `rethrow` and `critical` is whether `post` runs \u2014 no status or logging change.',
     "",
-    '- **Request history** controls per-object execution capture (the request/task/trigger debugger). Authored as a single scalar `history` field on any primitive: `false` off, `true` on at the default capture depth, a number = capture depth (how many statement executions are recorded per history record \u2014 NOT record retention), `"all"` unlimited. **Omit `history` to inherit** \u2014 the engine resolves object \u2192 container \u2192 workspace at request time (a query inherits from its API group, a tool from its toolset envelope, everything else straight from the workspace). Any authored value stops inheriting for that object. Per-kind defaults (when inheriting): query/task/tool capture ON, function/trigger/middleware OFF; default depth 100. Container tiers are authorable too \u2014 `apiGroup({ history })` sets the `query_*` default its queries inherit, and an agent/mcp_server/toolset `history` sets the `tool_*` default its tools inherit. Workspace-level defaults are the terminal tier: `workspaceConfig({ history: { query, function, task, tool, trigger, middleware } })` emits the flat `{objType}_enabled`/`{objType}_limit` map (no inherit flag) \u2014 setting it is wholesale (unlisted types fall back to their engine default), so declare every default you want to keep; omit the field to leave existing workspace history untouched.',
+    '- **Request history** controls per-object execution capture (the request/task/trigger debugger). Authored as a single scalar `history` field on any primitive: `false` off, `true` on at the default capture depth, a number = capture depth (how many statement executions are recorded per history record \u2014 NOT record retention), `"all"` unlimited.',
+    "  - **Omit `history` to inherit** \u2014 the engine resolves object \u2192 container \u2192 workspace at request time (a query inherits from its API group, a tool from its toolset envelope, everything else straight from the workspace). Any authored value stops inheriting for that object.",
+    "  - Per-kind defaults (when inheriting): query/task/tool capture ON, function/trigger/middleware OFF; default depth 100.",
+    "  - Container tiers are authorable too \u2014 `apiGroup({ history })` sets the `query_*` default its queries inherit, and an agent/mcp_server/toolset `history` sets the `tool_*` default its tools inherit.",
+    "  - Workspace-level defaults are the terminal tier: `workspaceConfig({ history: { query, function, task, tool, trigger, middleware } })` emits the flat `{objType}_enabled`/`{objType}_limit` map (no inherit flag) \u2014 setting it is wholesale (unlisted types fall back to their engine default), so declare every default you want to keep; omit the field to leave existing workspace history untouched.",
     "",
     '- **Workspace environment variables** set a tenant\'s env vars through the workspace object: `workspaceConfig({ env: { STRIPE_KEY: process.env.STRIPE_KEY!, APP_BASE_URL: "https://\u2026" } })`. Author them as a name\u2192value MAP. Read a var back with `env("NAME")` (\u2192 `$env.NAME`), which compiles to tag "setting" with the plain name. Values are SECRETS: prefer sourcing from `process.env` over committing literals, and don\'t commit a compiled bundle with real values. `deploy` REPLACES the tenant\'s env with the declared map; `release` (merge) is ADD-ONLY \u2014 it creates missing keys but does NOT update or remove existing ones, so changing a value in code and releasing leaves the live value unchanged. Omit `env` to leave existing env untouched. The separate `settings` field is a plain object.',
     ""
@@ -1809,8 +1872,20 @@ function renderSections(m) {
     "- `s.security.create_guid({ as? })` \u2014 bind a fresh GUID string. Takes nothing else.",
     "- `s.function.run({ fn, input?, as?, runtime? })` / `s.function.call({ fn, input?, as? })` \u2014 run another function; `input` is keyed by the target's input names.",
     '  - `runtime?` runs it in the BACKGROUND: `{ mode: "async-shared" }` or `{ mode: "async-dedicated", cpu?, memory?, timeout?, maxRetry? }` (resources read at dedicated only). An async call DOES NOT return the result \u2014 it dispatches and continues, so `as` binds nothing; collect with `s.await({ ids })`. Omit for a normal call. Same block on `s.ai.agent.run`.',
-    '- `s.api.call({ api, input?, headers?, auth?, as? })` \u2014 invoke an endpoint. `api` takes the `query()` def HANDLE (or a `{ name, guid }` pair) \u2014 a bare name is refused, because a query\'s identity is composed from its api group, verb, and name. `headers` REPLACES the request headers the callee sees and takes the same shapes as `s.api.request`\'s \u2014 a `{ "Name": value }` record (values may be tagged), a `string[]` of `"Name: value"` lines, or one `Value`. `auth` is `{ token, ignoreExpiration? }`: `token` must be a BARE STRING \u2014 a tagged `Value` deploys clean and then fails the run with `Param: token - Text filter requires an integer, float, string or boolean value`, since the engine stores that slot as plain text and never evaluates it. Neither slot authenticates the call today; see `llms/tests.md` for what a workflow-test run actually sees. WORKFLOW-TEST ONLY (see Gotchas in `llms.txt`) \u2014 elsewhere it deploys clean and 500s the first real request.',
-    '- `s.api.request({ url, method?, params?, headers?, timeout?, follow_location?, verify_host?, verify_peer?, ca_certificate?, certificate?, certificate_pass?, private_key?, private_key_pass?, description?, output?, as? })` \u2014 external HTTP request (`mvp:api_request`). Ergonomic types, each also accepting a dynamic `Value`: `method` suggests the 7 verbs (GET/POST/PUT/DELETE/HEAD/OPTIONS/PATCH), `params` a plain JSON object **or** a FLAT record whose values are tagged `Value`s (`{ count: ref("count") }`, each lifted via a `set` filter \u2014 the same record-of-values shape `response: { key: value }` takes); a tagged value NESTED inside an object or array THROWS at encode, so wrap a structured body in `obj({...})`, which encodes any depth as one `const:expr2` (\u2192 query string for GET/HEAD/OPTIONS, body otherwise), `headers` a `{ "Name": value }` record whose values may be tagged (`{ "x-api-key": env("KEY") }`, each pair joined to a `"Name: value"` line) **or** a `string[]` of full header lines \u2014 prefer a header over a `?key=` query param for a credential \u2014 a URL travels into access logs, proxies and `Referer`. \u26A0 Neither spelling is envelope-safe: the `as` envelope\'s `request` half mirrors `url`, `params` AND `headers`, so never return it raw from a credentialed request \u2014 read `response.result`. A NAME outside the header-token charset is refused, and a LITERAL value carrying a newline is refused; a value may hold `:` and spaces (`Bearer a: b` is a valid value). A TAGGED value cannot be checked at build time, so strip CRLF from caller-controlled input before this slot. Literal pairs lead the emitted array and computed ones follow, so the wire order is not the record\'s key order, `timeout` a `number` in seconds (1\u201386400), and `follow_location`/`verify_host`/`verify_peer` booleans. `description` (Settings tab) and `output` filters (Output tab) ride the envelope. SSL cert interdependencies (certificate\u2194private_key, ca_certificate\u2192verify_peer) are checked at build time when statically provable, else by the engine at runtime. The `as` result is typed as the `{request, response}` envelope (`response.status: number`, `response.result: unknown`), so `InferResponse` resolves a `ref` to it. Same typed result on `webflow.request` and `microservice.request`.',
+    "- `s.api.call({ api, input?, headers?, auth?, as? })` \u2014 invoke an endpoint. WORKFLOW-TEST ONLY (see Gotchas in `llms.txt`).",
+    "  - `api` takes the `query()` def HANDLE (or a `{ name, guid }` pair) \u2014 a bare name is refused, because a query's identity is composed from its api group, verb, and name.",
+    '  - `headers` REPLACES the request headers the callee sees and takes the same shapes as `s.api.request`\'s \u2014 a `{ "Name": value }` record (values may be tagged), a `string[]` of `"Name: value"` lines, or one `Value`.',
+    "  - `auth` is `{ token, ignoreExpiration? }`: `token` must be a BARE STRING \u2014 a tagged `Value` deploys clean and then fails the run with `Param: token - Text filter requires an integer, float, string or boolean value`, since the engine stores that slot as plain text and never evaluates it.",
+    "  - Neither slot authenticates the call today; see `llms/tests.md` for what a workflow-test run actually sees.",
+    "- `s.api.request({ url, method?, params?, headers?, timeout?, follow_location?, verify_host?, verify_peer?, ca_certificate?, certificate?, certificate_pass?, private_key?, private_key_pass?, description?, output?, as? })` \u2014 external HTTP request (`mvp:api_request`). Ergonomic types, each also accepting a dynamic `Value`:",
+    "  - `method` suggests the 7 verbs (GET/POST/PUT/DELETE/HEAD/OPTIONS/PATCH).",
+    '  - `params` a plain JSON object **or** a FLAT record whose values are tagged `Value`s (`{ count: ref("count") }`, each lifted via a `set` filter \u2014 the same record-of-values shape `response: { key: value }` takes); a tagged value NESTED inside an object or array THROWS at encode, so wrap a structured body in `obj({...})`, which encodes any depth as one `const:expr2` (\u2192 query string for GET/HEAD/OPTIONS, body otherwise).',
+    '  - `headers` a `{ "Name": value }` record whose values may be tagged (`{ "x-api-key": env("KEY") }`, each pair joined to a `"Name: value"` line) **or** a `string[]` of full header lines \u2014 prefer a header over a `?key=` query param for a credential \u2014 a URL travels into access logs, proxies and `Referer`.',
+    "  - \u26A0 Neither spelling is envelope-safe: the `as` envelope's `request` half mirrors `url`, `params` AND `headers`, so never return it raw from a credentialed request \u2014 read `response.result`.",
+    "  - A NAME outside the header-token charset is refused, and a LITERAL value carrying a newline is refused; a value may hold `:` and spaces (`Bearer a: b` is a valid value). A TAGGED value cannot be checked at build time, so strip CRLF from caller-controlled input before this slot. Literal pairs lead the emitted array and computed ones follow, so the wire order is not the record's key order.",
+    "  - `timeout` a `number` in seconds (1\u201386400), and `follow_location`/`verify_host`/`verify_peer` booleans.",
+    "  - `description` (Settings tab) and `output` filters (Output tab) ride the envelope. SSL cert interdependencies (certificate\u2194private_key, ca_certificate\u2192verify_peer) are checked at build time when statically provable, else by the engine at runtime.",
+    "  - The `as` result is typed as the `{request, response}` envelope (`response.status: number`, `response.result: unknown`), so `InferResponse` resolves a `ref` to it. Same typed result on `webflow.request` and `microservice.request`.",
     "- `s.stream.from_request({ url, method?, \u2026tls, as? })` \u2014 streaming external HTTP request (`mvp:streaming_api_request`); same typed field surface as `s.api.request` (no description/output envelope). `url` is REQUIRED \u2014 it shares `api.request`'s engine declaration, which has no default.",
     '- `s.util.send_email({ to, subject, message, from?, cc?, bcc?, reply_to?, service_provider?, api_key?, scheduled_at?, as? })` \u2014 send email from the stack. `service_provider` is `"xano"` (the built-in mailer \u2014 needs NO `api_key` and no configuration, and does not require a verified sender) or `"resend"` (pass the key as `api_key: env("RESEND_API_KEY")`). Prefer this over hand-rolling `s.api.request` against a mail provider.',
     "- `s.webflow.request({ path, method?, \u2026tls, as? })` \u2014 Webflow API request (`mvp:connect_webflow_api_request`); like `s.api.request` but addressed by `path` (host is engine-supplied), and `path` is REQUIRED \u2014 the engine rejects an empty one. No `headers`: the engine builds its own from the workspace's Webflow connection and ignores an authored value.",
@@ -1821,9 +1896,18 @@ function renderSections(m) {
     "",
     "Microservices (the `microservice()` def and the statement that calls it):",
     "",
-    "- `microservice({ name, kind, \u2026 })` \u2014 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` \u2014 passing both throws. EARLY SURFACE, expected to change \u2014 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 \u2014 they need not match the microservice name, which is what a stack addresses.",
+    "- `microservice({ name, kind, \u2026 })` \u2014 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` \u2014 passing both throws.",
+    "  - EARLY SURFACE, expected to change \u2014 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 \u2014 they need not match the microservice name, which is what a stack addresses.",
     '- SECRETS RIDE ALONG \u2014 `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 \u2014 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")`.',
-    '- `s.microservice.request({ host, path, port?, method?, params?, headers?, timeout?, follow_location?, as? })` \u2014 in-cluster microservice call (`mvp:microservice_request`); no TLS fields. ONLY `host`+`path` required; the rest default to the engine\'s values (`GET`/`{}`/`[]`/`10`/`true`), always emitted. Pass the `microservice()` DEF as `host` \u2014 it binds by NAME (how the engine resolves it), so a rename fixes every call site and the port is checked before deploy. `port?` folds into `host` as `"name:port"`: a def exposing ONE `servicePort` resolves automatically, SEVERAL requires it. A raw `"name:port"` string works, unvalidated, and is the only way to reach an instance-level microservice. `tenantDeploy: "manual"` on the def imports the row without starting the workload.',
+    "- `s.microservice.request({ host, path, port?, method?, params?, headers?, timeout?, follow_location?, as? })` \u2014 in-cluster microservice call (`mvp:microservice_request`); no TLS fields.",
+    "  - ONLY `host`+`path` required; the rest default to the engine's values (`GET`/`{}`/`[]`/`10`/`true`), always emitted.",
+    "  - Pass the `microservice()` DEF as `host` \u2014 it binds by NAME (how the engine resolves it), so a rename fixes every call site and the port is checked before deploy.",
+    '  - `port?` folds into `host` as `"name:port"`: a def exposing ONE `servicePort` resolves automatically, SEVERAL requires it.',
+    '  - A raw `"name:port"` string works, unvalidated, and is the only way to reach an instance-level microservice.',
+    '  - `tenantDeploy: "manual"` on the def imports the row without starting the workload.',
     "- `s.workflow_test.call({ workflowTest, datasource?, as? })` \u2014 run another workflow test from inside one, which is the only place it runs (see Gotchas in `llms.txt`). The odd one out: NO `input` (a workflow test takes none), and it carries `datasource?` instead \u2014 same clone caveat as the kind's own field.",
     ""
   ];
@@ -1921,6 +2005,8 @@ function renderSections(m) {
     legacy,
     objectKinds,
     kindsCore,
+    client,
+    errors,
     kindsAgentMcp,
     kindsKnowledge,
     kindsRealtime,
@@ -1953,7 +2039,7 @@ function renderDocs(m) {
     {
       path: "llms/object-kinds.md",
       title: "Object kinds",
-      readWhen: "Read when deciding WHAT to build \u2014 every authorable primitive (tables, endpoints, functions, tasks, agents, MCP, realtime, microservices, \u2026), what each is, and which factory + register method build it. Read it too when a `register*` call will not typecheck because the array was built by `.flatMap()`/`.concat()` across modules.",
+      readWhen: "Read when deciding WHAT to build \u2014 every authorable primitive, what each is, and which factory + register method builds it. Also when `register*` will not typecheck an array built by `.flatMap()`/`.concat()`.",
       body: s.objectKinds,
       dropLeadingHeading: true
     },
@@ -1964,10 +2050,22 @@ function renderDocs(m) {
       body: s.kindsCore,
       dropLeadingHeading: true
     },
+    {
+      path: "llms/client.md",
+      title: "Consuming defs from a client",
+      readWhen: "Read when a frontend imports a def (`getPath()`/`InferResponse`) or calls the deployed backend \u2014 what the import costs, `window.XANO_HOST`, local dev, file URLs, and a Node spot-check.",
+      body: s.client
+    },
+    {
+      path: "llms/errors.md",
+      title: "Error index",
+      readWhen: "Read when a request, test, build, or pull fails with a message you did not write \u2014 the string, its cause, and where the fix is.",
+      body: s.errors
+    },
     {
       path: "llms/tests.md",
       title: "Saved unit tests, assertions, and mocks",
-      readWhen: "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.",
+      readWhen: "Read when authoring a `workflowTest()` stack, when a query/function/middleware carries `tests`, when a statement needs a `mock`, or when running a deployed environment's tests.",
       body: s.tests,
       dropLeadingHeading: true
     },
@@ -1980,7 +2078,7 @@ function renderDocs(m) {
     {
       path: "llms/kinds-knowledge.md",
       title: "Knowledge def shape",
-      readWhen: "Read when the workspace defines a `knowledge()` item \u2014 the markdown its AI agents read.",
+      readWhen: "Read when the workspace defines a `knowledge()` item for its AI agents.",
       body: s.kindsKnowledge
     },
     {
@@ -2005,7 +2103,7 @@ function renderDocs(m) {
     {
       path: "llms/statements-runtime.md",
       title: "Statement runtime behavior",
-      readWhen: "Read when you need to know what a statement's `as:` output actually holds, or why a bound variable is not the shape you expected.",
+      readWhen: "Read when you need to know what a statement's `as:` output holds, or why a bound variable is not the shape expected.",
       body: s.stmtRuntime
     },
     {
@@ -2024,7 +2122,7 @@ function renderDocs(m) {
     {
       path: "llms/fields.md",
       title: "Column and input types",
-      readWhen: "Read when declaring a table column (`f.*`) or a function/query input (`input.*`) \u2014 a type's options and accessor methods, and the `s.precondition` error/status contract that rides the same catalog.",
+      readWhen: "Read when declaring a table column (`f.*`) or a function/query input (`input.*`) \u2014 a type's options and methods, and the `s.precondition` error/status contract. Also `table({ seed })` rows and `use_xdo`.",
       body: s.fields,
       dropLeadingHeading: true
     },
@@ -2038,7 +2136,7 @@ function renderDocs(m) {
     {
       path: "llms/lambda.md",
       title: "Lambda bodies (JavaScript)",
-      readWhen: "Read when writing a JavaScript body, or weighing whether to reach for one at all \u2014 `lam.fn`, `fl.lambda`, `fl.reduce`, `s.lambda`. Lambda workers are a bounded shared resource, and each surface binds a different set of identifiers.",
+      readWhen: "Read when writing a JavaScript body, or weighing whether to reach for one at all \u2014 `lam.fn`, `fl.lambda`, `fl.reduce`, `s.lambda`; each surface binds a different set of identifiers.",
       body: s.lambda,
       dropLeadingHeading: true
     },
@@ -2052,14 +2150,14 @@ function renderDocs(m) {
     {
       path: "llms/legacy.md",
       title: "Legacy paradigms and retired statements",
-      readWhen: 'Read when the code was PULLED from an existing Xano instance rather than authored here \u2014 how a codegen\'d tree reads and the three shapes in it that must not be "fixed", plus a `raw({ name: "mvp:\u2026" })` statement, a `realtimeTrigger()`, or any name the catalogs do not list.',
+      readWhen: 'Read when the code was PULLED from an existing Xano instance \u2014 how a codegen\'d tree reads, the shapes in it that must not be "fixed", and any `raw({ name: "mvp:\u2026" })`, `realtimeTrigger()`, or name the catalogs do not list.',
       body: s.legacy,
       dropLeadingHeading: true
     },
     {
       path: "llms/statements-catalog.md",
       title: "Statement catalog",
-      readWhen: "Read for the field signature of a specific statement \u2014 every surface, grouped by `s.*` namespace. Look here after the control-flow core in the router does not cover what you need.",
+      readWhen: "Read for the field signature of a specific statement \u2014 every surface, grouped by `s.*` namespace.",
       body: s.stmtCatalog
     }
   ];