@xanots/sdk 0.0.5 → 0.0.7

package/llms-full.txt

@@ -1,10 +1,19 @@
-# xanots v0.0.5
+# xanots v0.0.7
 
 > TypeScript SDK that compiles a typed Xano workspace into the importable packageExport JSON bundle.
 
-Author a Xano workspace in TypeScript: build typed objects, register them on a
-`new Xano()` instance, and call `.export()` to get one importable bundle. Compile
-with `xanots export ./xano/index.js`.
+Xano is a hosted backend platform: one WORKSPACE serves a managed PostgreSQL
+database, HTTP API endpoints, background tasks, realtime websocket channels, AI
+agents and MCP servers, file storage, and redis. This SDK authors that workspace in
+TypeScript — typed def objects registered on a `workspace(name)` — compiled to one
+importable bundle by `xanots export ./xano/index.ts`, shipped live by `xanots deploy`.
+
+Def modules execute at BUILD time only: `s.*` factories return data, and the engine
+runs the compiled stack per request — statements in order, a statement's `as:`
+naming a runtime variable, `response` the HTTP body. Every dynamic operand is a
+TAGGED value — `ref("x")` a stack variable, `inp("x")` an input, `auth("id")` the
+caller, `c.*` a constant — resolved at request time; JS operators over them do not
+compute (see Gotchas). Requests share no memory — state persists in tables or redis.
 
 Coverage: object kinds 25/31, statement surfaces 214/214, filters 226 (226 typed).
 Not authorable here: branch, market_item, realtime_channel, run.job, run.service, tablemap — these cannot be authored and do not survive a pull; see `coverage.objectKinds.unmodeled` in `manifest.json`.
@@ -15,7 +24,7 @@ below — open the one whose condition matches the task, and skip the rest. For
 exhaustive per-entry detail in NEITHER — a statement's full field schema with engine
 defaults, a filter's complete argument list, the engine `storedName` mapping — do a
 TARGETED lookup in the shipped `manifest.json` (grep or `jq` the one entry you need;
-it is ~55k tokens, so never read it whole). Its top-level keys are `name`, `version`, `description`, `coverage`, `values`, `objectKinds`, `fieldTypes`, `statements`, `filters`, `cli`, `cliGlobalFlags`. `statements` and `filters` are ARRAYS, not maps — SELECT, do not index:
+it is ~65k tokens, so never read it whole). Its top-level keys are `name`, `version`, `description`, `coverage`, `values`, `objectKinds`, `fieldTypes`, `statements`, `filters`, `cli`, `cliGlobalFlags`. `statements` and `filters` are ARRAYS, not maps — SELECT, do not index:
   jq '.statements[] | select(.sPath=="db.get")' manifest.json
   jq '.filters[]    | select(.name=="json_decode")' manifest.json
 Select a statement on `sPath` (the `s.*` path you write), NOT `surface` (the XanoScript term): 24 of 214 differ — `var`→`set_var`, `break`→`foreach_break`, `foreach.remove`→`foreach_remove`, and every `expect.*`.
@@ -24,11 +33,10 @@ Select a statement on `sPath` (the `s.*` path you write), NOT `surface` (the Xan
 
 Each line is a condition on the task. Open the files whose condition matches and
 skip the rest — paths are relative to this file (`node_modules/@xanots/sdk/` once
-installed), so they resolve with a plain file read and always match the version you
-have. `llms-full.txt` is this file and every one below concatenated — for a reader
-that wants one fetch, not for an agent that can open the two files it needs.
+installed), so a plain file read resolves them at the version you have.
+`llms-full.txt` is everything concatenated — one fetch, for a reader that cannot open files.
 
-- [Object kinds](llms/object-kinds.md): Read when you need the full catalog of authorable primitives — which factory builds each, which register method takes it, and which payload key it lands under. Read it too when a `register*` call will not typecheck because the array was built by `.flatMap()`/`.concat()` across modules.
+- [Object kinds](llms/object-kinds.md): Read when deciding WHAT to build — every authorable primitive (tables, endpoints, functions, tasks, agents, MCP, realtime, microservices, …), 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.
 - [Core def shapes](llms/kinds-core.md): Read when authoring a function, query, api group, task, workflow test, middleware, or tool — and for the `response` and `expr` shapes every one of them uses.
 - [Saved unit tests, assertions, and mocks](llms/tests.md): Read when authoring a `workflowTest()` stack, when a query/function/middleware carries `tests`, when a statement should mock a value, or when running a deployed environment's tests.
 - [Agent and MCP def shapes](llms/kinds-agent-mcp.md): Read when the workspace defines an `agent()` or an `mcpServer()`.
@@ -37,12 +45,13 @@ that wants one fetch, not for an agent that can open the two files it needs.
 - [Triggers](llms/triggers.md): Read when authoring any trigger. A trigger's `stack` is a callback rather than the plain array every other kind takes, so the shape does not carry over.
 - [Array and database statements](llms/statements-data.md): Read when the stack reads or writes rows (`s.db.*`), or transforms an array in place (`s.array.map`, `s.array.union`).
 - [Statement runtime behavior](llms/statements-runtime.md): 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.
-- [Auth, cross-object calls, and microservices](llms/statements-calls.md): Read when the stack authenticates, calls another object (`s.function.run`, `s.api.request`, `s.tool.call`), or reaches a microservice.
+- [Auth, cross-object calls, and microservices](llms/statements-calls.md): Read when the stack authenticates (the signup/login/token recipe is here), calls another object (`s.function.run`, `s.api.request`, `s.tool.call`), or reaches a microservice.
 - [Value catalog](llms/values.md): Read when you need a literal, a reference, or a tag you have not used before — `c.*`, `ref`, `inp`, `auth`, `col`, and what each one encodes to.
 - [Column and input types](llms/fields.md): Read when declaring a table column (`f.*`) or a function/query input (`input.*`) — a type's options and accessor methods, and the `s.precondition` error/status contract that rides the same catalog.
 - [Filter catalog](llms/filters.md): Read when piping a value through `fl.*` — the full catalog with each filter's argument types.
-- [Lambda bodies (JavaScript)](llms/lambda.md): Read when writing a JavaScript body, or weighing whether to reach for one at all — `lam.fn`, `fl.lambda`, `fl.reduce`, `s.lambda`. Lambda workers are a bounded shared resource, each surface binds a different set of identifiers, and the hazards are not guessable.
-- [Legacy paradigms and retired statements](llms/legacy.md): Read when the code was PULLED from an existing Xano instance rather than authored here — how a codegen'd tree reads and the three shapes in it that must not be "fixed", plus a `raw({ name: "mvp:…" })` statement, a `realtimeTrigger()`, or any name the catalogs do not list. None of the retired names are authorable for new code.
+- [Lambda bodies (JavaScript)](llms/lambda.md): Read when writing a JavaScript body, or weighing whether to reach for one at all — `lam.fn`, `fl.lambda`, `fl.reduce`, `s.lambda`. Lambda workers are a bounded shared resource, and each surface binds a different set of identifiers.
+- [Lock file](llms/lock.md): Read when a `xano.lock` exists or should — renaming/pruning/adopting identities, seeding the lock programmatically, or asking which commands write it.
+- [Legacy paradigms and retired statements](llms/legacy.md): Read when the code was PULLED from an existing Xano instance rather than authored here — how a codegen'd tree reads and the three shapes in it that must not be "fixed", plus a `raw({ name: "mvp:…" })` statement, a `realtimeTrigger()`, or any name the catalogs do not list.
 - [Statement catalog](llms/statements-catalog.md): Read for the field signature of a specific statement — every surface, grouped by `s.*` namespace. Look here after the control-flow core in the router does not cover what you need.
 
 ## Quickstart
@@ -116,26 +125,18 @@ but nothing fails on a message no one reads, so in CI and in unattended agent bu
 pass `--strict` (`emitBundle(app, { strict: true })` / `app.export({ strict: true })`):
 every warning becomes a hard failure. Same bundle bytes either way.
 
-Identity: object guids derive from `(type, name)`, so renames change identity.
-`xanots export <entry> --lock` freezes every guid + api-group/toolset canonical in a lock
-file written BESIDE THE ENTRY FILE — `xano/xano.lock` for the standard scaffold, NOT the
-project root — which you commit (auto-read once present; CI guard `--frozen-lock` fails
-instead of changing the lock). Fix-up subcommands:
-`xanots lock rename <kind> <old> <new>` (kind = payloadKey or table/api_group),
-`xanots lock prune <entry-file> [keys…] --yes` — finding orphans RUNS the entry's module scope
-(env assertions included); `--no-verify --yes <kind:name>…` prunes named keys with no evaluation
-and no orphan check,
-`xanots lock adopt <live-bundle.json> [--yes]` — all accept `--lock=<path>`.
-Programmatic use: call `seedLockOverrides(readLockFile(path))` BEFORE importing
-any def module — references bake guids at import time, so late seeding is a
-silent no-op (`resetLockOverrides` exists for tests).
-Development workflow: opt in EARLY — run `xanots export ./xano/index.ts --lock` once and COMMIT
-`xano.lock` beside the entry file; every later export then keeps identities
-stable across renames and environments. To rename an object: rename in code,
-export (stderr prints the exact fix-up), run `xanots lock rename <kind> <old>
-<new>`, export again — the original guid is emitted under the new name, so the
-engine renames in place instead of delete+create. Taking over an existing
-workspace: `xanots lock adopt <its-packageExport.json>` first, then export.
+Identity: object guids derive from `(type, name)` — a query's from `(api group,
+verb, name)` — so renames change identity.
+Opt in EARLY: `xanots export ./xano/index.ts --lock` freezes every guid +
+api-group/toolset canonical in a lock file written BESIDE THE ENTRY FILE —
+`xano/xano.lock` for the standard scaffold, NOT the project root — which you COMMIT
+(auto-read once present; CI guard `--frozen-lock` fails instead of changing it).
+To rename an object: rename in code, export (stderr prints the exact fix-up), run
+`xanots lock rename <kind> <old> <new>`, export again — the original guid is emitted
+under the new name, so the engine renames in place instead of delete+create. Taking
+over an existing workspace: `xanots lock adopt <its-packageExport.json>` first, then
+export. Pruning, programmatic seeding, and which commands write the lock:
+`llms/lock.md`.
 
 ## Deploy
 
@@ -166,14 +167,6 @@ production workspace, but confirm with the user before the first run.
   (previewed against live). `--prune` deletes only what `xano.lock` records this
   project released, and refuses without a lock.
 
-Nothing from a DEPLOY is written back into `xano.lock` (an ephemeral/sandbox is a
-separate workspace, so its identities must not pollute yours). The one write-back is
-`release --replace`, which mints fresh identities in the workspace the lock describes:
-it re-pins the lock from the rebuilt workspace, because otherwise the next release
-matches nothing and duplicates every object. Deploying an ENTRY
-FILE still updates the local lock via the shared compile step, exactly as `export`
-does — only when a lock exists or `--lock` is passed.
-
 **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:
@@ -221,6 +214,12 @@ Non-obvious authoring rules:
 - **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.
+- **Tagged values are DATA — 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
@@ -301,15 +300,16 @@ Non-obvious authoring rules:
 - **Self-referencing tables** need the bare-name form: inside `tweets`'s own
   schema, write `f.tableRef("tweets", { type: "int" })` — the `const tweets`
   handle isn't assigned yet, so the handle form throws "used before declaration".
-- **Same-name siblings collide.** Object guids derive from `(type, name)` and
-  ignore a query's `verb`, so a `GET` and `POST` both named `posts` clash;
-  `export()` throws on the collision — give them DISTINCT names (`posts` and
-  `posts/create`; the verb still carries the semantics). A distinct explicit
-  `guid` on each clears that throw but is NOT a lasting fix: a lock entry is
-  keyed by `(type, name)` too and cannot hold two guids, so `export --lock`
-  refuses the pair — and a committed lock is the recommended workflow.
-  `export()` warns on a same-name pair even unlocked. An explicit `guid` is
-  for pinning identity across a rename, not for sharing a name.
+- **Same-name siblings collide — queries excepted: their identity carries group + verb.**
+  Guids derive from `(type, name)`, so two functions (or tables, toolsets, …) sharing
+  a name derive ONE guid and `export()` throws — give them DISTINCT names. A QUERY
+  derives from `(api group, verb, name)`, the engine's own uniqueness: `GET items` +
+  `POST items`, and `items` across two groups, coexist, and the lock keys the same
+  composed identity (`query:blog|GET|items`) — changing a query's verb or group
+  changes its identity. An explicit `guid` on a colliding pair clears the throw but
+  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
@@ -485,7 +485,7 @@ Control flow & blocks (each nests a sub-stack; block specials name it `body`):
 
 # Object kinds
 
-> Read when you need the full catalog of authorable primitives — which factory builds each, which register method takes it, and which payload key it lands under. Read it too when a `register*` call will not typecheck because the array was built by `.flatMap()`/`.concat()` across modules.
+> Read when deciding WHAT to build — every authorable primitive (tables, endpoints, functions, tasks, agents, MCP, realtime, microservices, …), 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.
 
 Author with the factory, register on the Xano instance, lands under the payload key. Each line ends with a one-liner on what the primitive is.
 
@@ -512,7 +512,7 @@ Author with the factory, register on the Xano instance, lands under the payload
 - realtime_server: `realtimeServer` → `Xano.registerRealtimeServers` → payload `realtime_server` — 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>`).
 - channel: `realtimeChannel` → `Xano.registerRealtimeChannels` → payload `channel` — A realtime channel: a joinable path on a realtime server (`rooms/{room_id}`) with typed path params, join/publish policy, a client-visible conversation transcript, and delivery semantics. Owns message handlers. Returns a handle with `getChannel(params)` for the path a client joins.
 - message: `realtimeMessage` → `Xano.registerRealtimeMessages` → payload `message` — A realtime message handler: a named message type on a channel with its own typed payload and stack — the realtime analogue of a query. Pass the `realtimeChannel()` handle as `channel` and the owning server comes with it.
-- microservice: `microservice` → `Xano.registerMicroservices` → payload `microservice` — A container workload deployed alongside the workspace, called from a stack with `s.microservice.request`. Two mutually exclusive shapes via `kind`: `builtin` declares containers (image/ports/resources/env/command/args) plus optional `ingresses`, and `helm` points at a chart and its `values` — passing both throws. EARLY SURFACE, expected to change — every export of a workspace declaring one prints a notice saying so. `configs`/`volumes` are typed and `@deprecated` but NOT deployable: the engine rejects an import carrying either, so `export()` fails the build rather than letting the deploy fatal. Put a value the workload reads in a container's `env`, and storage in a container's own `volumes` (`emptyDir`/`persistent`/`config`). Container names are free-form — they need not match the microservice name, which is what a stack addresses. SECRETS RIDE ALONG — `chart.values` and `registryAuth.dockerconfigjson` are carried into the bundle, and into a pulled tree, verbatim (they must be, or a pulled microservice could not be redeployed). Both are stored strings with NO deploy-time indirection: `process.env.X` in the def resolves at EXPORT and writes the literal into the bundle, so it is not a way to keep the credential out. Either leave `registryAuth` unset (public image, or a credential attached outside this workspace) or treat the bundle and any pulled tree as secret material — keep them out of git, or rotate after. Export prints a notice per microservice carrying either field; `--strict` does not promote it. For a secret a STACK reads, the mapped surface is `workspaceConfig({ env })` + `env("NAME")`.
+- microservice: `microservice` → `Xano.registerMicroservices` → payload `microservice` — A container workload deployed alongside the workspace, called from a stack with `s.microservice.request`. Def shapes (`builtin` containers vs a `helm` chart) and the SECRET-handling rules its config carries: `llms/statements-calls.md`.
 - knowledge: `knowledge` → `Xano.registerKnowledge` → payload `knowledge` — Markdown the workspace's AI agents read before they act — an `agents.md` of standing instructions, a `skill`, or a `doc`. The body is a real markdown FILE via `knowledgeFile("./x.md", import.meta.url)`, and `mode` decides how much of it reaches the agent.
 - workspace: `workspaceConfig` → `Xano.registerWorkspace` → payload `workspace` — Workspace-level configuration such as default middleware chains and request-history defaults per host kind.
 
@@ -523,7 +523,8 @@ Author with the factory, register on the Xano instance, lands under the payload
 The def-object passed to each factory. `?` = optional. `input` is keyed by
 input name (`input.<type>(opts?)`); `stack` is `Statement[]` (`s.*`); `response`
 is a `ResponseDef` (see **Responses** below). Object identity is `guid?` —
-omit it and it derives from `name` (set it to survive a rename).
+omit it and it derives from `name` (for a query, from group + verb + name; set it
+to survive a rename).
 
 - `defineFunction({ name, guid?, description?, docs?, workspace?, input?, stack?, response?, tests? })`
 - `query({ name, verb, apiGroup?, guid?, auth?, input?, stack?, response?, responseType?, apiEnabled?, disabled?, cache?, description?, docs?, tests?, example? })`
@@ -796,7 +797,8 @@ primary key `id`):
 - `s.db.del({ table, fieldName?, fieldValue, as? })` — delete by field match.
 - `s.db.add({ table, row?, data?, output?, as? })` — insert; `row` is a partial keyed by column.
   - A row CELL takes a tagged `Value`, a nested object of sub-keys, or a bare JS literal typed against that column: `row: { is_hidden: true, notes: "…" }` encodes exactly as `{ is_hidden: c.bool(true), notes: c.text("…") }`. The tag comes from the COLUMN, not the literal — `10` on an `f.decimal()` column is `const:decimal`, not `const:int` — so a literal contradicting its column is a compile error on a `f.*`-schema table (`{ is_hidden: "yes" }` on an `f.bool()` column) and throws at encode on a raw-`ColumnDef[]` one. An `f.enum()` column keeps its member union. A column with no literal form — obj/json/list/geo/vector/file — still needs `c.obj`/`c.array`.
-  - `null` is accepted on EVERY column, including ones that refuse every other literal, and encodes `const:null` — a write OF null, not the same as omitting the key (omitted takes the column's type default on `add`: `[]` for a list, `{}` for obj/json, else `null`; on `edit` it is left untouched). A column's `nullable` is not consulted; the engine refuses a null it forbids.
+  - `null` is accepted on EVERY column, including ones that refuse every other literal, and encodes `const:null` — a write OF null, not the same as omitting the key. A column's `nullable` is not consulted at encode; the engine refuses a null it forbids.
+  - Omitting a key on `add` writes the column's type default — declared `default` if set, `[]` for a list, `{}` for obj/json, else `null`. That `null` is EMITTED, not what the row holds: the engine applies the column's nullability, so a `nullable` column keeps `null` and a non-nullable one lands on its type's zero value (`""`, `0`, `false`). Set the cell when the stored value matters. On `edit` an omitted key keeps its stored value.
   - An `f.password()` cell takes the PLAINTEXT — the column hashes on write, so a pre-hashed value, or a hashing filter on the cell, stores a hash of a hash that `security.check_password` can never match.
 - `s.db.edit({ table, fieldName?, fieldValue, row?, data?, output?, as? })` — update by field match.
 - `s.db.patch({ table, fieldName?, fieldValue, data, output?, as? })` — merge a partial (`data` is an object value).
@@ -888,25 +890,32 @@ Runtime behavior (what the `as:` output holds, and misses):
 
 # Auth, cross-object calls, and microservices
 
-> Read when the stack authenticates, calls another object (`s.function.run`, `s.api.request`, `s.tool.call`), or reaches a microservice.
+> Read when the stack authenticates (the signup/login/token recipe is here), calls another object (`s.function.run`, `s.api.request`, `s.tool.call`), or reaches a microservice.
 
 Auth & calls:
 
 - `s.security.create_auth_token({ table, id, extras?, expiration?, as? })` — `extras` defaults to `{}`, `expiration` to `86400`s (`0` = never).
+- **Marketplace first:** `@xanots/auth` registers a complete auth surface — signup/login/me endpoints plus their `user`/`account`/`event_log` tables — via `registerAuth(ws, { canonical: "authn" })`. Authentication only, not authorization. Inspect with `xanots marketplace details @xanots/auth --prompt`.
+- **The auth loop end to end** — what that module implements; author it directly for a custom flow. An auth TABLE (`table({ auth: true })`) backs identity; a PUBLIC login query verifies and mints a token; every protected query names that table as `auth:` and reads the caller with `auth(...)`.
+  - Signup: `s.db.add({ table: users, row: { email: inp("email"), password: inp("password") } })` — the `f.password()` column hashes on write; take the submission as `input.text()` on signup AND login (see Gotchas on double-hashing).
+  - Login: `s.db.get({ table: users, fieldName: "email", fieldValue: inp("email"), output: ["id", "password"], as: "u" })` — the `output` naming `password` is REQUIRED (the column is `access: "internal"` and absent from the row otherwise) → `s.precondition({ expr: expr(ref("u", { safe: true }), "!=", c.null()), error: c.text("No such user."), error_type: "notfound" })` → `s.security.check_password({ text_password: inp("password"), hash_password: ref("u.password"), as: "ok" })` → precondition on `ok` → `s.security.create_auth_token({ table: users, id: ref("u.id"), as: "token" })` → `response: { token: ref("token") }`.
+  - Client: send it as an `Authorization: Bearer <token>` header. A `query({ auth: users })` refuses a request without a valid one before its stack runs; inside the stack `auth("id")` is the caller's row id (`response: { id: auth("id") }` is the whole `me` endpoint).
 - `s.security.create_guid({ as? })` — bind a fresh GUID string. Takes nothing else.
 - `s.function.run({ fn, input?, as?, runtime? })` / `s.function.call({ fn, input?, as? })` — 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 — 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? })` — invoke an endpoint. `headers` REPLACES the request headers the callee sees and takes the same shapes as `s.api.request`'s — 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 — 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`) — elsewhere it deploys clean and 500s the first real request.
+- `s.api.call({ api, input?, headers?, auth?, as? })` — invoke an endpoint. `api` takes the `query()` def HANDLE (or a `{ name, guid }` pair) — 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 — 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 — 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`) — 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? })` — 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 — 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` (→ 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 — prefer a header over a `?key=` query param for a credential — a URL travels into access logs, proxies and `Referer`. ⚠ 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 — 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–86400), and `follow_location`/`verify_host`/`verify_peer` booleans. `description` (Settings tab) and `output` filters (Output tab) ride the envelope. SSL cert interdependencies (certificate↔private_key, ca_certificate→verify_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?, …tls, as? })` — streaming external HTTP request (`mvp:streaming_api_request`); same typed field surface as `s.api.request` (no description/output envelope). `url` is REQUIRED — it shares `api.request`'s engine declaration, which has no default.
 - `s.webflow.request({ path, method?, …tls, as? })` — Webflow API request (`mvp:connect_webflow_api_request`); like `s.api.request` but addressed by `path` (host is engine-supplied), and `path` is REQUIRED — the engine rejects an empty one. No `headers`: the engine builds its own from the workspace's Webflow connection and ignores an authored value.
 - `s.task.call` / `s.tool.call` / `s.trigger.call` / `s.middleware.call` / `s.addon.call` — same `{ <target>, input?, as? }` shape against the named kind. `s.task.call` and `s.trigger.call` are WORKFLOW-TEST ONLY (see Gotchas in `llms.txt`); `s.tool.call`, `s.middleware.call` and `s.addon.call` run from any stack.
-- `s.action.call({ action, package?, input?, as? })` / `s.action.package.call(…)` — invoke a marketplace action; `package` is its slug.
+- `s.action.call({ actionId, input?, registry?, as? })` / `s.action.package.call({ traceId, versionId, slug, input?, registry?, as? })` — invoke an installed action. Ids are SUPPLIED, never derived from a name: an action is installed onto the instance, so its identity is assigned at install and differs per instance — read them off a call in a pulled workspace. The package form needs all three parts; they are one composite and two of them address nothing. `registry` is the action's own settings, `input` the per-call arguments.
 - `s.cloud.job({ image, command, args?, secret?, template?, await?, as? })` — launch a containerized job. `image`/`command` are REQUIRED; omitted → `Missing param`. ⚠ `await` is SECONDS (default 60), not a boolean.
 - `s.cloud.job.status({ id, as? })` · `s.cloud.job.await({ ids, timeout, as? })` — poll one job, or block on several (`ids` a list `Value`, `timeout` in seconds; both required).
 
 Microservices (the `microservice()` def and the statement that calls it):
 
+- `microservice({ name, kind, … })` — two mutually exclusive shapes via `kind`: `builtin` declares containers (image/ports/resources/env/command/args) plus optional `ingresses`, and `helm` points at a chart and its `values` — passing both throws. EARLY SURFACE, expected to change — every export of a workspace declaring one prints a notice saying so. `configs`/`volumes` are typed and `@deprecated` but NOT deployable: the engine rejects an import carrying either, so `export()` fails the build rather than letting the deploy fatal. Put a value the workload reads in a container's `env`, and storage in a container's own `volumes` (`emptyDir`/`persistent`/`config`). Container names are free-form — they need not match the microservice name, which is what a stack addresses.
+- SECRETS RIDE ALONG — `chart.values` and `registryAuth.dockerconfigjson` are carried into the bundle, and into a pulled tree, verbatim (they must be, or a pulled microservice could not be redeployed). Both are stored strings with NO deploy-time indirection: `process.env.X` in the def resolves at EXPORT and writes the literal into the bundle, so it is not a way to keep the credential out. Either leave `registryAuth` unset (public image, or a credential attached outside this workspace) or treat the bundle and any pulled tree as secret material — keep them out of git, or rotate after. Export prints a notice per microservice carrying either field; `--strict` does not promote it. For a secret a STACK reads, the mapped surface is `workspaceConfig({ env })` + `env("NAME")`.
 - `s.microservice.request({ host, path, port?, method?, params?, headers?, timeout?, follow_location?, as? })` — 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` — 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? })` — 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 — same clone caveat as the kind's own field.
 
@@ -999,6 +1008,14 @@ the entry's own name. `hidden: ["created_at"]` drops columns from that expansion
 `input.list(element)` for arrays — wrap any element constructor, e.g.
 `input.list(input.text())` or `input.list(input.object({ id: f.int() }))`. Prefer the
 typed forms over `input.json()` when the shape is known.
+**A file reaches a column in two steps.** `input.file` is the RAW upload (the request's
+multipart/base64 bytes) and cannot be written to a file column directly: store it first —
+`s.storage.create_image({ as: "img", value: ref("input.avatar"), access: "public" })`
+(the request input bag is read as a dotted `ref("input.<name>")` here) — then write
+`ref("img")` into the `f.image()` cell with `s.db.add`/`edit`. `access` defaults to
+`"public"` (a guessable URL): pass `"private"` and hand out `s.storage.sign_private_url`
+results for anything user-scoped. `create_video`/`create_audio`/`create_attachment` are
+the same shape for the other file columns.
 **Typed inputs validate/coerce on bind, before your stack runs** — so reach for the
 specific type instead of hand-rolling checks. `input.email({ required: true })` rejects a
 malformed address with a 400 (and trims; add `methods: ["lower"]` to downcase) — no
@@ -1231,7 +1248,7 @@ Variadic filters — they take arguments, but no declared list, so the count is
 
 # Lambda bodies (JavaScript)
 
-> Read when writing a JavaScript body, or weighing whether to reach for one at all — `lam.fn`, `fl.lambda`, `fl.reduce`, `s.lambda`. Lambda workers are a bounded shared resource, each surface binds a different set of identifiers, and the hazards are not guessable.
+> Read when writing a JavaScript body, or weighing whether to reach for one at all — `lam.fn`, `fl.lambda`, `fl.reduce`, `s.lambda`. Lambda workers are a bounded shared resource, and each surface binds a different set of identifiers.
 
 **A lambda is an escape hatch, not a default.** The body runs outside the request's own
 runtime, and a workspace has a BOUNDED pool of lambda workers every lambda in it shares
@@ -1341,9 +1358,42 @@ Four hazards and the dependency route, all live-verified:
 
 TypeScript annotations survive in the body, and top-level `await` works.
 
+# Lock file
+
+> Read when a `xano.lock` exists or should — renaming/pruning/adopting identities, seeding the lock programmatically, or asking which commands write it.
+
+`xano.lock` pins each object's guid and each api-group/toolset canonical, so renames
+stay renames (guids otherwise derive from `(type, name)`; a query's from `(api group,
+verb, name)`). Created by `xanots export <entry> --lock`, auto-read once present,
+committed. A query's entry is keyed by that composed identity —
+`query:<group>|<verb>|<name>` — the same seed its guid derives from; a legacy
+`query:<name>` entry keeps pinning and is migrated by the next locked export (the
+old key drops automatically once its guid re-lands under the composed one).
+
+- `xanots lock rename <kind> <old> <new>` — `kind` is the payload key (or `table`/`api_group`).
+  Run it after renaming in code; the next export emits the original guid under the new name.
+- `xanots lock prune <entry-file> [keys…] --yes` — drops orphaned entries. Finding orphans
+  RUNS the entry's module scope (env assertions included); `--no-verify --yes <kind:name>…`
+  prunes named keys with no evaluation and no orphan check.
+- `xanots lock adopt <live-bundle.json> [--yes]` — seed the lock from an engine
+  packageExport when taking over an existing workspace.
+- Every lock subcommand accepts `--lock=<path>`. `rename`/`adopt` take no entry file, so
+  from outside the lock's directory pass `--lock` (or `--entry=<entry-file>` to derive it).
+- Programmatic use: call `seedLockOverrides(readLockFile(path))` BEFORE importing any def
+  module — references bake guids at import time, so late seeding is a silent no-op
+  (`resetLockOverrides` exists for tests).
+
+What writes the lock: `export`/`deploy` of an ENTRY FILE update it via the shared compile
+step — only when a lock exists or `--lock` is passed. Nothing from a DEPLOY is written
+back beyond that (an ephemeral/sandbox is a separate workspace, so its identities must
+not pollute yours). The one write-back is `release --replace`, which mints fresh
+identities in the workspace the lock describes: it re-pins the lock from the rebuilt
+workspace, because otherwise the next release matches nothing and duplicates every
+object. CI: `--frozen-lock` fails instead of changing the lock.
+
 # Legacy paradigms and retired statements
 
-> Read when the code was PULLED from an existing Xano instance rather than authored here — how a codegen'd tree reads and the three shapes in it that must not be "fixed", plus a `raw({ name: "mvp:…" })` statement, a `realtimeTrigger()`, or any name the catalogs do not list. None of the retired names are authorable for new code.
+> Read when the code was PULLED from an existing Xano instance rather than authored here — how a codegen'd tree reads and the three shapes in it that must not be "fixed", plus a `raw({ name: "mvp:…" })` statement, a `realtimeTrigger()`, or any name the catalogs do not list.
 
 Older paradigms this SDK still supports and still emits when it decodes an existing
 workspace. **Do not author these.** They are listed by name only so you recognize them

package/llms.txt

@@ -1,10 +1,19 @@
-# xanots v0.0.5
+# xanots v0.0.7
 
 > TypeScript SDK that compiles a typed Xano workspace into the importable packageExport JSON bundle.
 
-Author a Xano workspace in TypeScript: build typed objects, register them on a
-`new Xano()` instance, and call `.export()` to get one importable bundle. Compile
-with `xanots export ./xano/index.js`.
+Xano is a hosted backend platform: one WORKSPACE serves a managed PostgreSQL
+database, HTTP API endpoints, background tasks, realtime websocket channels, AI
+agents and MCP servers, file storage, and redis. This SDK authors that workspace in
+TypeScript — typed def objects registered on a `workspace(name)` — compiled to one
+importable bundle by `xanots export ./xano/index.ts`, shipped live by `xanots deploy`.
+
+Def modules execute at BUILD time only: `s.*` factories return data, and the engine
+runs the compiled stack per request — statements in order, a statement's `as:`
+naming a runtime variable, `response` the HTTP body. Every dynamic operand is a
+TAGGED value — `ref("x")` a stack variable, `inp("x")` an input, `auth("id")` the
+caller, `c.*` a constant — resolved at request time; JS operators over them do not
+compute (see Gotchas). Requests share no memory — state persists in tables or redis.
 
 Coverage: object kinds 25/31, statement surfaces 214/214, filters 226 (226 typed).
 Not authorable here: branch, market_item, realtime_channel, run.job, run.service, tablemap — these cannot be authored and do not survive a pull; see `coverage.objectKinds.unmodeled` in `manifest.json`.
@@ -15,7 +24,7 @@ below — open the one whose condition matches the task, and skip the rest. For
 exhaustive per-entry detail in NEITHER — a statement's full field schema with engine
 defaults, a filter's complete argument list, the engine `storedName` mapping — do a
 TARGETED lookup in the shipped `manifest.json` (grep or `jq` the one entry you need;
-it is ~55k tokens, so never read it whole). Its top-level keys are `name`, `version`, `description`, `coverage`, `values`, `objectKinds`, `fieldTypes`, `statements`, `filters`, `cli`, `cliGlobalFlags`. `statements` and `filters` are ARRAYS, not maps — SELECT, do not index:
+it is ~65k tokens, so never read it whole). Its top-level keys are `name`, `version`, `description`, `coverage`, `values`, `objectKinds`, `fieldTypes`, `statements`, `filters`, `cli`, `cliGlobalFlags`. `statements` and `filters` are ARRAYS, not maps — SELECT, do not index:
   jq '.statements[] | select(.sPath=="db.get")' manifest.json
   jq '.filters[]    | select(.name=="json_decode")' manifest.json
 Select a statement on `sPath` (the `s.*` path you write), NOT `surface` (the XanoScript term): 24 of 214 differ — `var`→`set_var`, `break`→`foreach_break`, `foreach.remove`→`foreach_remove`, and every `expect.*`.
@@ -24,11 +33,10 @@ Select a statement on `sPath` (the `s.*` path you write), NOT `surface` (the Xan
 
 Each line is a condition on the task. Open the files whose condition matches and
 skip the rest — paths are relative to this file (`node_modules/@xanots/sdk/` once
-installed), so they resolve with a plain file read and always match the version you
-have. `llms-full.txt` is this file and every one below concatenated — for a reader
-that wants one fetch, not for an agent that can open the two files it needs.
+installed), so a plain file read resolves them at the version you have.
+`llms-full.txt` is everything concatenated — one fetch, for a reader that cannot open files.
 
-- [Object kinds](llms/object-kinds.md): Read when you need the full catalog of authorable primitives — which factory builds each, which register method takes it, and which payload key it lands under. Read it too when a `register*` call will not typecheck because the array was built by `.flatMap()`/`.concat()` across modules.
+- [Object kinds](llms/object-kinds.md): Read when deciding WHAT to build — every authorable primitive (tables, endpoints, functions, tasks, agents, MCP, realtime, microservices, …), 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.
 - [Core def shapes](llms/kinds-core.md): Read when authoring a function, query, api group, task, workflow test, middleware, or tool — and for the `response` and `expr` shapes every one of them uses.
 - [Saved unit tests, assertions, and mocks](llms/tests.md): Read when authoring a `workflowTest()` stack, when a query/function/middleware carries `tests`, when a statement should mock a value, or when running a deployed environment's tests.
 - [Agent and MCP def shapes](llms/kinds-agent-mcp.md): Read when the workspace defines an `agent()` or an `mcpServer()`.
@@ -37,12 +45,13 @@ that wants one fetch, not for an agent that can open the two files it needs.
 - [Triggers](llms/triggers.md): Read when authoring any trigger. A trigger's `stack` is a callback rather than the plain array every other kind takes, so the shape does not carry over.
 - [Array and database statements](llms/statements-data.md): Read when the stack reads or writes rows (`s.db.*`), or transforms an array in place (`s.array.map`, `s.array.union`).
 - [Statement runtime behavior](llms/statements-runtime.md): 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.
-- [Auth, cross-object calls, and microservices](llms/statements-calls.md): Read when the stack authenticates, calls another object (`s.function.run`, `s.api.request`, `s.tool.call`), or reaches a microservice.
+- [Auth, cross-object calls, and microservices](llms/statements-calls.md): Read when the stack authenticates (the signup/login/token recipe is here), calls another object (`s.function.run`, `s.api.request`, `s.tool.call`), or reaches a microservice.
 - [Value catalog](llms/values.md): Read when you need a literal, a reference, or a tag you have not used before — `c.*`, `ref`, `inp`, `auth`, `col`, and what each one encodes to.
 - [Column and input types](llms/fields.md): Read when declaring a table column (`f.*`) or a function/query input (`input.*`) — a type's options and accessor methods, and the `s.precondition` error/status contract that rides the same catalog.
 - [Filter catalog](llms/filters.md): Read when piping a value through `fl.*` — the full catalog with each filter's argument types.
-- [Lambda bodies (JavaScript)](llms/lambda.md): Read when writing a JavaScript body, or weighing whether to reach for one at all — `lam.fn`, `fl.lambda`, `fl.reduce`, `s.lambda`. Lambda workers are a bounded shared resource, each surface binds a different set of identifiers, and the hazards are not guessable.
-- [Legacy paradigms and retired statements](llms/legacy.md): Read when the code was PULLED from an existing Xano instance rather than authored here — how a codegen'd tree reads and the three shapes in it that must not be "fixed", plus a `raw({ name: "mvp:…" })` statement, a `realtimeTrigger()`, or any name the catalogs do not list. None of the retired names are authorable for new code.
+- [Lambda bodies (JavaScript)](llms/lambda.md): Read when writing a JavaScript body, or weighing whether to reach for one at all — `lam.fn`, `fl.lambda`, `fl.reduce`, `s.lambda`. Lambda workers are a bounded shared resource, and each surface binds a different set of identifiers.
+- [Lock file](llms/lock.md): Read when a `xano.lock` exists or should — renaming/pruning/adopting identities, seeding the lock programmatically, or asking which commands write it.
+- [Legacy paradigms and retired statements](llms/legacy.md): Read when the code was PULLED from an existing Xano instance rather than authored here — how a codegen'd tree reads and the three shapes in it that must not be "fixed", plus a `raw({ name: "mvp:…" })` statement, a `realtimeTrigger()`, or any name the catalogs do not list.
 - [Statement catalog](llms/statements-catalog.md): Read for the field signature of a specific statement — every surface, grouped by `s.*` namespace. Look here after the control-flow core in the router does not cover what you need.
 
 ## Quickstart
@@ -116,26 +125,18 @@ but nothing fails on a message no one reads, so in CI and in unattended agent bu
 pass `--strict` (`emitBundle(app, { strict: true })` / `app.export({ strict: true })`):
 every warning becomes a hard failure. Same bundle bytes either way.
 
-Identity: object guids derive from `(type, name)`, so renames change identity.
-`xanots export <entry> --lock` freezes every guid + api-group/toolset canonical in a lock
-file written BESIDE THE ENTRY FILE — `xano/xano.lock` for the standard scaffold, NOT the
-project root — which you commit (auto-read once present; CI guard `--frozen-lock` fails
-instead of changing the lock). Fix-up subcommands:
-`xanots lock rename <kind> <old> <new>` (kind = payloadKey or table/api_group),
-`xanots lock prune <entry-file> [keys…] --yes` — finding orphans RUNS the entry's module scope
-(env assertions included); `--no-verify --yes <kind:name>…` prunes named keys with no evaluation
-and no orphan check,
-`xanots lock adopt <live-bundle.json> [--yes]` — all accept `--lock=<path>`.
-Programmatic use: call `seedLockOverrides(readLockFile(path))` BEFORE importing
-any def module — references bake guids at import time, so late seeding is a
-silent no-op (`resetLockOverrides` exists for tests).
-Development workflow: opt in EARLY — run `xanots export ./xano/index.ts --lock` once and COMMIT
-`xano.lock` beside the entry file; every later export then keeps identities
-stable across renames and environments. To rename an object: rename in code,
-export (stderr prints the exact fix-up), run `xanots lock rename <kind> <old>
-<new>`, export again — the original guid is emitted under the new name, so the
-engine renames in place instead of delete+create. Taking over an existing
-workspace: `xanots lock adopt <its-packageExport.json>` first, then export.
+Identity: object guids derive from `(type, name)` — a query's from `(api group,
+verb, name)` — so renames change identity.
+Opt in EARLY: `xanots export ./xano/index.ts --lock` freezes every guid +
+api-group/toolset canonical in a lock file written BESIDE THE ENTRY FILE —
+`xano/xano.lock` for the standard scaffold, NOT the project root — which you COMMIT
+(auto-read once present; CI guard `--frozen-lock` fails instead of changing it).
+To rename an object: rename in code, export (stderr prints the exact fix-up), run
+`xanots lock rename <kind> <old> <new>`, export again — the original guid is emitted
+under the new name, so the engine renames in place instead of delete+create. Taking
+over an existing workspace: `xanots lock adopt <its-packageExport.json>` first, then
+export. Pruning, programmatic seeding, and which commands write the lock:
+`llms/lock.md`.
 
 ## Deploy
 
@@ -166,14 +167,6 @@ production workspace, but confirm with the user before the first run.
   (previewed against live). `--prune` deletes only what `xano.lock` records this
   project released, and refuses without a lock.
 
-Nothing from a DEPLOY is written back into `xano.lock` (an ephemeral/sandbox is a
-separate workspace, so its identities must not pollute yours). The one write-back is
-`release --replace`, which mints fresh identities in the workspace the lock describes:
-it re-pins the lock from the rebuilt workspace, because otherwise the next release
-matches nothing and duplicates every object. Deploying an ENTRY
-FILE still updates the local lock via the shared compile step, exactly as `export`
-does — only when a lock exists or `--lock` is passed.
-
 **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:
@@ -221,6 +214,12 @@ Non-obvious authoring rules:
 - **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.
+- **Tagged values are DATA — 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
@@ -301,15 +300,16 @@ Non-obvious authoring rules:
 - **Self-referencing tables** need the bare-name form: inside `tweets`'s own
   schema, write `f.tableRef("tweets", { type: "int" })` — the `const tweets`
   handle isn't assigned yet, so the handle form throws "used before declaration".
-- **Same-name siblings collide.** Object guids derive from `(type, name)` and
-  ignore a query's `verb`, so a `GET` and `POST` both named `posts` clash;
-  `export()` throws on the collision — give them DISTINCT names (`posts` and
-  `posts/create`; the verb still carries the semantics). A distinct explicit
-  `guid` on each clears that throw but is NOT a lasting fix: a lock entry is
-  keyed by `(type, name)` too and cannot hold two guids, so `export --lock`
-  refuses the pair — and a committed lock is the recommended workflow.
-  `export()` warns on a same-name pair even unlocked. An explicit `guid` is
-  for pinning identity across a rename, not for sharing a name.
+- **Same-name siblings collide — queries excepted: their identity carries group + verb.**
+  Guids derive from `(type, name)`, so two functions (or tables, toolsets, …) sharing
+  a name derive ONE guid and `export()` throws — give them DISTINCT names. A QUERY
+  derives from `(api group, verb, name)`, the engine's own uniqueness: `GET items` +
+  `POST items`, and `items` across two groups, coexist, and the lock keys the same
+  composed identity (`query:blog|GET|items`) — changing a query's verb or group
+  changes its identity. An explicit `guid` on a colliding pair clears the throw but
+  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

package/manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "xanots",
-  "version": "0.0.5",
+  "version": "0.0.7",
   "description": "TypeScript SDK that compiles a typed Xano workspace into the importable packageExport JSON bundle.",
   "coverage": {
     "objectKinds": {
@@ -357,7 +357,7 @@
       "kind": "microservice",
       "payloadKey": "microservice",
       "authorFactory": "microservice",
-      "description": "A container workload deployed alongside the workspace, called from a stack with `s.microservice.request`. Two mutually exclusive shapes via `kind`: `builtin` declares containers (image/ports/resources/env/command/args) plus optional `ingresses`, and `helm` points at a chart and its `values` — passing both throws. EARLY SURFACE, expected to change — every export of a workspace declaring one prints a notice saying so. `configs`/`volumes` are typed and `@deprecated` but NOT deployable: the engine rejects an import carrying either, so `export()` fails the build rather than letting the deploy fatal. Put a value the workload reads in a container's `env`, and storage in a container's own `volumes` (`emptyDir`/`persistent`/`config`). Container names are free-form — they need not match the microservice name, which is what a stack addresses. SECRETS RIDE ALONG — `chart.values` and `registryAuth.dockerconfigjson` are carried into the bundle, and into a pulled tree, verbatim (they must be, or a pulled microservice could not be redeployed). Both are stored strings with NO deploy-time indirection: `process.env.X` in the def resolves at EXPORT and writes the literal into the bundle, so it is not a way to keep the credential out. Either leave `registryAuth` unset (public image, or a credential attached outside this workspace) or treat the bundle and any pulled tree as secret material — keep them out of git, or rotate after. Export prints a notice per microservice carrying either field; `--strict` does not promote it. For a secret a STACK reads, the mapped surface is `workspaceConfig({ env })` + `env(\"NAME\")`.",
+      "description": "A container workload deployed alongside the workspace, called from a stack with `s.microservice.request`. Def shapes (`builtin` containers vs a `helm` chart) and the SECRET-handling rules its config carries: `llms/statements-calls.md`.",
       "registerMethod": "registerMicroservices",
       "registered": true
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xanots/sdk",
-  "version": "0.0.5",
+  "version": "0.0.7",
   "description": "XanoTS — your Xano backend as TypeScript. `xanots deploy` ships your typed workspace (and an optional static frontend) to a live, auto-expiring ephemeral environment and prints its URL. init → deploy → URL.",
   "keywords": [
     "xanots",

package/dist/init-command-NCRPVFGE.js

@@ -1,30 +0,0 @@
-import {
-  projectShellFiles,
-  runInitCommand,
-  sanitizeAppName
-} from "./chunk-KXCPZUUM.js";
-import {
-  resolveAiFlags
-} from "./chunk-7SISR3CS.js";
-import "./chunk-ZSYZTGJH.js";
-import "./chunk-WGDAOOXG.js";
-import "./chunk-QUUB7HYK.js";
-import "./chunk-6DHJVLYP.js";
-import "./chunk-MS3BRZAZ.js";
-import "./chunk-IVP6TS26.js";
-import "./chunk-MFIHIS6B.js";
-import "./chunk-GNPVYOPB.js";
-import "./chunk-EZG76F7R.js";
-import "./chunk-BPEEGJJA.js";
-import "./chunk-F5T45NAM.js";
-import "./chunk-YUPQOLFX.js";
-import "./chunk-WHOJWOSV.js";
-import "./chunk-5XZ744TS.js";
-import "./chunk-YUBJLB6G.js";
-export {
-  projectShellFiles,
-  resolveAiFlags,
-  runInitCommand,
-  sanitizeAppName
-};
-//# sourceMappingURL=init-command-NCRPVFGE.js.map