@xanots/sdk 0.0.5 → 0.0.7

package/dist/{upgrade-command-M2DZ3ZPD.js → upgrade-command-TZYSGXP7.js}

@@ -7,25 +7,25 @@ import {
 } from "./chunk-NUQCEOKA.js";
 import {
   refreshAgentFiles
-} from "./chunk-D6OGU2AI.js";
-import "./chunk-7SISR3CS.js";
+} from "./chunk-QIWBCS7N.js";
+import "./chunk-4PE4ZAB7.js";
 import {
   runNpm
 } from "./chunk-ZSYZTGJH.js";
 import {
   sdkDep
-} from "./chunk-QUUB7HYK.js";
-import "./chunk-6DHJVLYP.js";
+} from "./chunk-P5C2YKAM.js";
+import "./chunk-Q77KNEUL.js";
 import {
   checkForUpgrade,
   detectInstallMode,
   registryUrl,
   suppressUpdateNotice,
   upgradeCommand
-} from "./chunk-ZGA5MUNC.js";
-import "./chunk-MS3BRZAZ.js";
-import "./chunk-IVP6TS26.js";
-import "./chunk-MFIHIS6B.js";
+} from "./chunk-FDKR4YMN.js";
+import "./chunk-CL2H2WYE.js";
+import "./chunk-JQLR64UC.js";
+import "./chunk-OYMR5AMJ.js";
 import "./chunk-GNPVYOPB.js";
 import {
   blank,
@@ -35,12 +35,12 @@ import {
   success,
   warn
 } from "./chunk-EZG76F7R.js";
-import "./chunk-BPEEGJJA.js";
-import "./chunk-F5T45NAM.js";
-import "./chunk-YUPQOLFX.js";
+import "./chunk-FAWNUE2U.js";
+import "./chunk-OKNSR7MT.js";
+import "./chunk-NJGNUVXR.js";
 import "./chunk-WHOJWOSV.js";
 import "./chunk-5XZ744TS.js";
-import "./chunk-YUBJLB6G.js";
+import "./chunk-7JDT4PBU.js";
 
 // src/emit/upgrade-command.ts
 import { readFileSync, writeFileSync } from "fs";
@@ -174,4 +174,4 @@ function messageOf(err) {
 export {
   runUpgradeCommand
 };
-//# sourceMappingURL=upgrade-command-M2DZ3ZPD.js.map
+//# sourceMappingURL=upgrade-command-TZYSGXP7.js.map

package/dist/{validate-command-CIBQJND7.js → validate-command-MMXEVHH3.js}

@@ -1,10 +1,10 @@
 import {
   assertBundleInput,
   loadBundleText
-} from "./chunk-QA5ICJ4M.js";
-import "./chunk-MS3BRZAZ.js";
-import "./chunk-IVP6TS26.js";
-import "./chunk-MFIHIS6B.js";
+} from "./chunk-7BUTRVKA.js";
+import "./chunk-CL2H2WYE.js";
+import "./chunk-JQLR64UC.js";
+import "./chunk-OYMR5AMJ.js";
 import "./chunk-GNPVYOPB.js";
 import {
   blank,
@@ -14,19 +14,19 @@ import {
   success,
   warn
 } from "./chunk-EZG76F7R.js";
-import "./chunk-BPEEGJJA.js";
-import "./chunk-F5T45NAM.js";
-import "./chunk-YUPQOLFX.js";
+import "./chunk-FAWNUE2U.js";
+import "./chunk-OKNSR7MT.js";
+import "./chunk-NJGNUVXR.js";
 import "./chunk-WHOJWOSV.js";
 import "./chunk-5XZ744TS.js";
-import "./chunk-YUBJLB6G.js";
+import "./chunk-7JDT4PBU.js";
 
 // src/emit/validate-command.ts
 var EXIT_VALIDATION_FAILED = 2;
 async function runValidateCommand(args) {
   assertBundleInput(args, { command: "validate" });
   const { resolveValidateConfig, verifyToken } = await import("./config-NL33PN4D.js");
-  const { MetaClient } = await import("./meta-client-OW5WKWW7.js");
+  const { MetaClient } = await import("./meta-client-57ZWVHST.js");
   const config = resolveValidateConfig({ instance: args.instance });
   const who = await verifyToken(config);
   const host = new URL(config.instance).host;
@@ -119,4 +119,4 @@ function fmt(v) {
 export {
   runValidateCommand
 };
-//# sourceMappingURL=validate-command-CIBQJND7.js.map
+//# sourceMappingURL=validate-command-MMXEVHH3.js.map

package/dist/{workspace-command-HZS43PHJ.js → workspace-command-X6L7HTXO.js}

@@ -1,12 +1,12 @@
 import {
   fetchWorkspaceBundle,
   runCodegenCommand
-} from "./chunk-OARSPAIE.js";
+} from "./chunk-5PDOAR77.js";
 import "./chunk-ZOYMZZ3S.js";
 import {
   resolveOutputTarget
-} from "./chunk-AAFBSOSD.js";
-import "./chunk-OR43PDCW.js";
+} from "./chunk-JQJPFUZI.js";
+import "./chunk-3EYUR3TX.js";
 import {
   printMicroserviceSection,
   readMicroservices
@@ -14,35 +14,35 @@ import {
 import {
   ENV_WORKSPACE,
   getAccessToken
-} from "./chunk-SG4UBJ47.js";
-import "./chunk-LLWK6H77.js";
+} from "./chunk-3QW5NFZJ.js";
+import "./chunk-BKDJN76G.js";
 import "./chunk-QTNO2WD6.js";
 import "./chunk-ZUTSMMAG.js";
 import "./chunk-X4DVXBFY.js";
-import "./chunk-KXCPZUUM.js";
+import "./chunk-DBHE35JM.js";
 import {
   isMachineOutput,
   writeJson
 } from "./chunk-NUQCEOKA.js";
-import "./chunk-7SISR3CS.js";
+import "./chunk-4PE4ZAB7.js";
 import "./chunk-ZSYZTGJH.js";
 import {
   fetchOrExplain,
   httpFailure
 } from "./chunk-3IGNIP6R.js";
-import "./chunk-PXXLBXOP.js";
+import "./chunk-JAVB27HL.js";
 import "./chunk-LU7TRWMC.js";
-import "./chunk-WGDAOOXG.js";
-import "./chunk-QUUB7HYK.js";
-import "./chunk-6DHJVLYP.js";
+import "./chunk-MU3O43L2.js";
+import "./chunk-P5C2YKAM.js";
+import "./chunk-Q77KNEUL.js";
 import "./chunk-4BXJGVZ3.js";
-import "./chunk-CYJ7R3AD.js";
-import "./chunk-MS3BRZAZ.js";
+import "./chunk-2V3JUXTF.js";
+import "./chunk-CL2H2WYE.js";
 import {
   removedSubcommand,
   unknownSubcommand
-} from "./chunk-IVP6TS26.js";
-import "./chunk-MFIHIS6B.js";
+} from "./chunk-JQLR64UC.js";
+import "./chunk-OYMR5AMJ.js";
 import "./chunk-GNPVYOPB.js";
 import {
   formatFields,
@@ -50,12 +50,12 @@ import {
   step,
   success
 } from "./chunk-EZG76F7R.js";
-import "./chunk-BPEEGJJA.js";
-import "./chunk-F5T45NAM.js";
-import "./chunk-YUPQOLFX.js";
+import "./chunk-FAWNUE2U.js";
+import "./chunk-OKNSR7MT.js";
+import "./chunk-NJGNUVXR.js";
 import "./chunk-WHOJWOSV.js";
 import "./chunk-5XZ744TS.js";
-import "./chunk-YUBJLB6G.js";
+import "./chunk-7JDT4PBU.js";
 
 // src/emit/workspace-command.ts
 import { writeFileSync } from "fs";
@@ -69,6 +69,10 @@ async function runWorkspaceCommand(args) {
       return runExport(args);
     case "codegen":
       return runCodegenCommand(args, { kind: "workspace" });
+    case "branch": {
+      const { runBranchCommand } = await import("./branch-commands-PBQ36L4A.js");
+      return runBranchCommand(args);
+    }
     case "deploy":
       throw removedSubcommand("workspace", "deploy");
     default:
@@ -156,4 +160,4 @@ async function runExport(args) {
 export {
   runWorkspaceCommand
 };
-//# sourceMappingURL=workspace-command-HZS43PHJ.js.map
+//# sourceMappingURL=workspace-command-X6L7HTXO.js.map

package/guides/environment.md

@@ -65,8 +65,10 @@ Every top-level object carries a stable `guid` — Xano's identity anchor. On a
 the engine matches an incoming object to an existing one **by guid** and updates it in
 place; no match means a new object. So re-running `export`/`deploy` on the same code maps
 cleanly onto the same workspace — **no duplicates**. By default the guid derives from the
-object's `name`; set an explicit `guid` to pin identity across a rename, or to adopt an
-existing workspace object into code.
+object's `name` — for a **query**, from its api group, verb, and name together, which is
+the engine's own uniqueness for an endpoint, so `GET items` and `POST items` are distinct
+objects and a path may repeat across groups. Set an explicit `guid` to pin identity across
+a rename, or to adopt an existing workspace object into code.
 
 The opt-in **`xano.lock`** freezes the whole workspace's identities at once — every
 auto-derived guid, plus the `canonical` URL tokens of API groups and toolsets (which the
@@ -81,7 +83,8 @@ guard. Adopt it early either way: once identities have drifted, the only way bac
 Precedence at emit is always **explicit in-code value → lock entry → name derivation**.
 
 **When the lock is actually load-bearing.** Because the default derivation is deterministic
-— `md5("<type>:<name>")` — a project that created all of its own objects can regenerate a
+— `md5("<type>:<name>")`, and `md5("query:<group>|<verb>|<name>")` for a query — a project
+that created all of its own objects can regenerate a
 byte-identical lock from its own source. Delete that lock, release again, and the same guids
 come back: the objects match and update in place. For that project the lock is a *cache*, and
 losing it costs nothing.

package/guides/scaffold.md

@@ -12,8 +12,9 @@ What `xanots init` writes, the two frontend presets, theming, add-ons, and the S
 `--marketplace <pkg>` (repeatable, comma-separated; installs add-ons and
 registers them — below), `--force` (scaffold into a non-empty folder),
 `--no-install` (skip `npm install`).
-In a terminal, `init` prompts for the framework, the theme, and the AI files;
-every prompt has a default, so pressing enter three times is a valid answer.
+In a terminal, `init` prompts for the framework and the AI files; every prompt
+has a default, so pressing enter twice is a valid answer. The look is never
+prompted for — it comes from the flags above, or from `xanots onboard`.
 The starter backend is empty but already compiles and deploys — grow it from the
 walkthrough in `xano/EXAMPLE.md`.
 

package/llms/fields.md

@@ -57,6 +57,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

package/llms/kinds-core.md

@@ -5,7 +5,8 @@
 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? })`

package/llms/lambda.md

@@ -1,6 +1,6 @@
 # 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

package/llms/legacy.md

@@ -1,6 +1,6 @@
 # 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/lock.md

@@ -0,0 +1,32 @@
+# 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.

package/llms/object-kinds.md

@@ -1,6 +1,6 @@
 # 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.
 
@@ -27,6 +27,6 @@ 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.

package/llms/statements-calls.md

@@ -1,23 +1,30 @@
 # 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.

package/llms/statements-data.md

@@ -16,7 +16,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).