@naturali/cli 0.209.2 → 0.209.4

package/dist/index.mjs

@@ -17,7 +17,7 @@ var __exportAll = (all, no_symbols) => {
 };
 //#endregion
 //#region package.json
-var version = "0.209.2";
+var version = "0.209.4";
 //#endregion
 //#region ../sdk/src/generated/core/bodySerializer.gen.ts
 const serializeFormDataPair = (data, key, value) => {
@@ -807,6 +807,8 @@ var Channels = class {
 	*
 	* `actor_id` binds an actor of this project, so the address speaks as the same actor your own sessions use. A changed actor deletes the address's conversations and their sessions — a session's actor is fixed — and the next message opens a fresh one; the actor naturali created for the address is deleted with them. An actor you bind is never deleted here.
 	*
+	* An identifier no channel kind produces is `400`.
+	*
 	*/
 	static setAddress(options) {
 		return (options.client ?? client).put({
@@ -913,7 +915,7 @@ var Channels = class {
 	/**
 	* Read the whole route table
 	*
-	* Every route across every channel in the project, one read — the table is small by construction (CHANNELS-ROUTING.md §3.6), so this is unpaginated.
+	* Every route across every channel in the project, one read — the table is small by construction, so this is unpaginated.
 	*
 	*/
 	static listProjectChannelRoutes(options) {
@@ -937,7 +939,7 @@ var Channels = class {
 	* Connect a channel
 	*
 	* Connect a channel. The required fields depend on `channel`; no credential is ever returned.
-	* **Discord** (`channel: discord`) — supply `application_id` and `bot_token`, plus the `modes` selecting which Gateway flows to serve (direct messages, and/or @mention-opens-a-thread). The token is checked with Discord first: `400 invalid_bot_token` when Discord rejects it, `400 application_mismatch` when it belongs to another application. Returns `501` when the deployment has no `CHANNEL_TOKEN_KEY` configured.
+	* **Discord** (`channel: discord`) — supply `application_id` and `bot_token`, plus the `modes` selecting which Gateway flows to serve (direct messages, and/or @mention-opens-a-thread). The token is checked with Discord first: `400 invalid_bot_token` when Discord rejects it, `400 application_mismatch` when it belongs to another application. Returns `501` when this deployment does not enable Discord channels.
 	* **WhatsApp** (default) — one of two credential paths, both filling the same write-only secret:
 	* * **BYOT** (`credential_source: byot`, default) — supply
 	* `phone_number_id` and `access_token` from your own Meta app.
@@ -1508,7 +1510,7 @@ var AiProviders = class {
 	*
 	* Deletes an AI provider configuration.
 	*
-	* Live references — chats, agents, and model routes whose targets name this provider — always block deletion with `409 AI_PROVIDER_HAS_DEPENDENTS`; `force` does not override them, so delete or repoint those resources first. Soft dependents — price overrides and usage/generation records — also block with `409` unless `force=true`, which deletes the provider's price overrides and unlinks its usage history, preserving those rows: each usage event keeps the provider's id as its `ai_provider_id`. The `409` body's `error.meta` reports the counts, a sample of offending IDs, and a `forcible` flag that is `true` when a `force=true` retry would succeed.
+	* Live references — agents and model routes whose targets name this provider — always block deletion with `409 AI_PROVIDER_HAS_DEPENDENTS`; `force` does not override them, so delete or repoint those resources first. Soft dependents — price overrides and usage/generation records — also block with `409` unless `force=true`, which deletes the provider's price overrides and unlinks its usage history, preserving those rows: each usage event keeps the provider's id as its `ai_provider_id`. The `409` body's `error.meta` reports the counts, a sample of offending IDs, and a `forcible` flag that is `true` when a `force=true` retry would succeed.
 	*
 	*/
 	static deleteAiProvider(options) {
@@ -1970,7 +1972,7 @@ var Auth = class {
 	/**
 	* Refresh a session
 	*
-	* Exchanges a valid refresh token for a new access JWT and a rotated refresh token, taken from the body or from the `refresh_token` cookie set at sign-in — a browser sends an empty body and the cookie carries the credential. Refresh tokens are single-use; presenting a previously-rotated token is treated as reuse and revokes the whole session family (createRefreshRotation reuse detection), except within a few seconds of the rotation, where it is treated as two tabs racing on one cookie and rotated again.
+	* Exchanges a valid refresh token for a new access JWT and a rotated refresh token, taken from the body or from the `refresh_token` cookie set at sign-in — a browser sends an empty body and the cookie carries the credential. Refresh tokens are single-use; presenting a previously-rotated token is treated as reuse and revokes the whole session family, except within a few seconds of the rotation, where it is treated as two tabs racing on one cookie and rotated again.
 	*
 	*/
 	static refreshSession(options) {
@@ -2645,10 +2647,7 @@ var Embeddings = class {
 	* Provide `input` for a single text or `inputs` for a batch. At least one is required.
 	* Returns `embedding` when `input` is used, and `embeddings` when `inputs` is used.
 	*
-	* `project_id` names the project the call's token usage is metered against, so
-	* embedding spend reaches the usage rollup and the project's `cost_usd` / `tokens`
-	* quotas. A project-scoped credential supplies its own project; a call that names
-	* none and is bound to none is `400 VALIDATION_FAILED`.
+	* The call's token usage is metered against the project in the path, so embedding spend reaches the usage rollup and the project's `cost_usd` / `tokens` quotas. A body `project_id` is ignored.
 	*
 	*/
 	static createEmbeddings(options) {
@@ -3699,7 +3698,7 @@ var Listings = class {
 	* Update a listing
 	*
 	* Change the title or description, or pause and resume the listing.
-	* `state: suspended` stops the listing for every installing project at once; their installs are kept. `state: listed` resumes a listing you suspended, provided naturali had listed it; nobody reinstalls. A listing naturali suspended cannot be resumed here, and an invalid move answers `409 invalid_listing_state`.
+	* `state: suspended` stops a `listed` listing for every installing project at once; their installs are kept. `state: listed` resumes a listing you suspended, provided naturali had listed it; nobody reinstalls. A listing naturali suspended cannot be resumed here, and an invalid move answers `409 invalid_listing_state`.
 	*
 	*/
 	static updateListing(options) {
@@ -4303,8 +4302,8 @@ var Orchestrations = class {
 	/**
 	* Get orchestration queue stats
 	*
-	* Returns a point-in-time snapshot of the orchestration run queue: how many tasks are waiting to be claimed (`queue_depth`), how many are currently claimed with a valid lease (`claimed_tasks`), the age of the oldest waiting task, recent claim-latency percentiles over a rolling in-process window. The per-project breakdown is listed by `GET /v1/projects/{project_id}/orchestrations/queue/stats/projects`. Intended for admin/operator policies; guarded by `orchestrations:GetQueueStats`.
-	* Every figure is scoped to what the caller may see. A project-scoped caller gets `queue_depth` and `claimed_tasks` summed over their own projects, and `null` for `oldest_queued_age_seconds` and the `claim_latency_ms` percentiles — both describe the whole deployment and cannot be narrowed, so they are withheld rather than approximated. An unrestricted caller (the action granted on every project) gets the deployment-wide figures.
+	* Returns a point-in-time snapshot of the orchestration run queue: how many tasks are waiting to be claimed (`queue_depth`), how many are currently claimed with a valid lease (`claimed_tasks`), the age of the oldest waiting task, recent claim-latency percentiles over a rolling in-process window. The per-project breakdown is listed by `GET /v1/projects/{project_id}/orchestrations/queue/stats/projects`.
+	* Every figure is scoped to what the caller may see. A project-scoped caller gets `queue_depth` and `claimed_tasks` summed over their own projects, and `null` for `oldest_queued_age_seconds` and the `claim_latency_ms` percentiles — both describe the whole deployment and cannot be narrowed, so they are withheld rather than approximated.
 	*
 	*/
 	static getQueueStats(options) {
@@ -4325,7 +4324,7 @@ var Orchestrations = class {
 	/**
 	* List the projects with queued orchestration work
 	*
-	* One row per project with any queued or claimed task, ordered by project ID: the per-project breakdown of `GET /v1/projects/{project_id}/orchestrations/queue/stats`. A project-scoped caller sees its own projects only. Guarded by `orchestrations:GetQueueStats`.
+	* One row per project with any queued or claimed task, ordered by project ID: the per-project breakdown of `GET /v1/projects/{project_id}/orchestrations/queue/stats`. A project-scoped caller sees its own projects only.
 	*
 	*/
 	static listQueueStatsProjects(options) {
@@ -5894,7 +5893,7 @@ var Triggers = class {
 	/**
 	* Update a trigger
 	*
-	* Updates an existing trigger's configuration. The type is immutable. Changing `target_type` or `target_id` re-checks the target-start action (`orchestrations:StartRun`, `agents:CreateAgentGeneration` or `tools:CallTool`) against the resulting target, because a firing runs with the trigger creator's authority rather than the updater's. A caller who could not start the new target is answered `403` and the trigger keeps the target it had.
+	* Updates an existing trigger's configuration. The type is immutable. Changing `target_type` or `target_id` re-checks that the caller may start the resulting target, because a firing runs with the trigger creator's authority rather than the updater's. A caller who could not start the new target is answered `403` and the trigger keeps the target it had.
 	*
 	*/
 	static updateTrigger(options) {
@@ -7886,7 +7885,7 @@ const routes = {
 	"set-address": {
 		serviceClass: "Channels",
 		operationId: "setAddress",
-		description: "Upserts the address with its `action`, the actor it speaks as, or both; a field left out is left alone. `action: null` forgets the exception and defers back to the route table; any other `action` requires the same fields a route or channel default would (`agent_id` for `agent`, `text` for `message`). `actor_id` binds an actor of this project, so the address speaks as the same actor your own sessions use. A changed actor deletes the address's conversations and their sessions — a session's actor is fixed — and the next message opens a fresh one; the actor naturali created for the address is deleted with them. An actor you bind is never deleted here.",
+		description: "Upserts the address with its `action`, the actor it speaks as, or both; a field left out is left alone. `action: null` forgets the exception and defers back to the route table; any other `action` requires the same fields a route or channel default would (`agent_id` for `agent`, `text` for `message`). `actor_id` binds an actor of this project, so the address speaks as the same actor your own sessions use. A changed actor deletes the address's conversations and their sessions — a session's actor is fixed — and the next message opens a fresh one; the actor naturali created for the address is deleted with them. An actor you bind is never deleted here. An identifier no channel kind produces is `400`.",
 		moduleDocsUrl: "https://naturali.ai/docs/modules/addresses",
 		httpMethod: "put",
 		pathParams: ["project_id", "identifier"],
@@ -8035,7 +8034,7 @@ const routes = {
 		serviceClass: "Admin",
 		operationId: "listUsers",
 		description: "A cursor page of every account, newest first, each with the plan it is on and the balance of its credit ledger. Needs the `admin` role. `email` narrows the page to one account. It matches the whole address case-insensitively and takes no wildcards: an operator looking for `Ana@Acme.com` finds a row stored as `ana@acme.com`, and there is no substring search across customers' addresses. An account with no subscription reads as `free` with a balance of `0`: the absence of a row is the free plan, and the least-privileged rung is also what any unresolvable lookup should answer.",
-		moduleDocsUrl: "https://naturali.ai/docs/modules/admin",
+		moduleDocsUrl: "https://naturali.ai/docs",
 		httpMethod: "get",
 		pathParams: [],
 		queryParams: [
@@ -8073,7 +8072,7 @@ const routes = {
 		serviceClass: "Admin",
 		operationId: "setUserRoles",
 		description: "Replaces the platform roles of any user. Needs the `admin` role, and each role that changes needs the caller to hold the role that grants it (today `admin` grants `admin`). Values outside the catalog are rejected with a 400, and a caller cannot remove their own `admin` role.",
-		moduleDocsUrl: "https://naturali.ai/docs/modules/admin",
+		moduleDocsUrl: "https://naturali.ai/docs",
 		httpMethod: "put",
 		pathParams: ["user_id"],
 		queryParams: [],
@@ -8097,7 +8096,7 @@ const routes = {
 		serviceClass: "Admin",
 		operationId: "listUserPlanHistory",
 		description: "A cursor page of the account's plan history, newest first, and the rung it is on now. Needs the `admin` role. The history is append-only, so this is the record of who put the account where and why — nothing edits or removes a line. `plan` at the top level is the same value every entitlement check resolves, so one response answers both \"what plan is this?\" and \"how did it get there?\".",
-		moduleDocsUrl: "https://naturali.ai/docs/modules/admin",
+		moduleDocsUrl: "https://naturali.ai/docs",
 		httpMethod: "get",
 		pathParams: ["user_id"],
 		queryParams: ["limit", "cursor"],
@@ -8131,7 +8130,7 @@ const routes = {
 		serviceClass: "Admin",
 		operationId: "grantUserPlan",
 		description: "Puts the account on a rung of the infra ladder. Needs the `admin` role. `PUT` because an account is on exactly one rung at a time, but the change is **recorded rather than overwritten**: the plan history is append-only and the newest line is the account's plan. Setting the rung it already holds still writes a line — a re-confirmation is an act worth a record, and the `reason` given with it would otherwise have nowhere to go. Read the history back with `GET` on this path. An upgrade takes effect at once. A downgrade is the same call with a lower rung and takes effect when the month turns: until then `plan` stays the rung held and `next_plan` names the new one. At the turn, active channels past the new rung's allowance are disabled, oldest first; an upgrade re-enables them. A rung whose content-retention window a contract sets — `enterprise` — **requires `retention_days`**, since nothing else can answer what that window is and an unanswered one bounds nothing. Every other rung sets its own and refuses the field.",
-		moduleDocsUrl: "https://naturali.ai/docs/modules/admin",
+		moduleDocsUrl: "https://naturali.ai/docs",
 		httpMethod: "put",
 		pathParams: ["user_id"],
 		queryParams: [],
@@ -8172,7 +8171,7 @@ const routes = {
 		serviceClass: "Admin",
 		operationId: "listUserCredits",
 		description: "A cursor page of the account's credit lines, newest first, with the balance they sum to. Needs the `admin` role — including for the account's own owner, who reads their own balance at `GET /v1/users/me/billing` rather than here. That answers what is left; this is the line-by-line record behind it. What an operator reads it for is writing a correction: the line that was wrong stays on the record, so it has to be legible before it can be compensated for.",
-		moduleDocsUrl: "https://naturali.ai/docs/modules/admin",
+		moduleDocsUrl: "https://naturali.ai/docs",
 		httpMethod: "get",
 		pathParams: ["user_id"],
 		queryParams: [
@@ -8217,7 +8216,7 @@ const routes = {
 		serviceClass: "Admin",
 		operationId: "grantUserCredit",
 		description: "Writes one line to the account's credit ledger and answers with the balance it produced. Needs the `admin` role. The ledger is append-only and the balance is its sum — there is no balance to set and no line to edit or delete. A mistake is corrected by writing a **negative** `amount_usd`, which leaves the wrong line on the record beside the one that compensates for it. `kind` is required. Money received and credit given away report differently — one is revenue, the other customer-acquisition cost — so the line says which it is rather than defaulting to one of them. The balance this moves is not yet a ceiling anything enforces; turning it into one is a separate mechanism.",
-		moduleDocsUrl: "https://naturali.ai/docs/modules/admin",
+		moduleDocsUrl: "https://naturali.ai/docs",
 		httpMethod: "post",
 		pathParams: ["user_id"],
 		queryParams: [],
@@ -8258,7 +8257,7 @@ const routes = {
 		serviceClass: "Admin",
 		operationId: "getUserUsage",
 		description: "The same answer `GET /v1/users/me/usage` gives the account itself: runs, indexed storage and the plan-capped counts, per project and against the rung. Needs the `admin` role.",
-		moduleDocsUrl: "https://naturali.ai/docs/modules/admin",
+		moduleDocsUrl: "https://naturali.ai/docs",
 		httpMethod: "get",
 		pathParams: ["user_id"],
 		queryParams: [],
@@ -8276,7 +8275,7 @@ const routes = {
 		serviceClass: "Admin",
 		operationId: "getAdminPriceBook",
 		description: "The upstream runtime's global default prices — the rows carrying neither a provider nor a project, which is all the upstream listing returns, so no tenant's own rates appear here. These are a cost basis, not a tariff: what a customer pays is the plan they bought plus the multiplier in PRICING.md section 3, applied when spend is reconciled. This is the read behind the storage-rate assertion at boot and the pinned embedding rate.",
-		moduleDocsUrl: "https://naturali.ai/docs/modules/admin",
+		moduleDocsUrl: "https://naturali.ai/docs",
 		httpMethod: "get",
 		pathParams: [],
 		queryParams: [],
@@ -8288,7 +8287,7 @@ const routes = {
 		serviceClass: "Admin",
 		operationId: "listUserStatements",
 		description: "The same statements the account reads at `GET /v1/users/me/statements`, for an operator to bill from. Needs the `admin` role.",
-		moduleDocsUrl: "https://naturali.ai/docs/modules/admin",
+		moduleDocsUrl: "https://naturali.ai/docs",
 		httpMethod: "get",
 		pathParams: ["user_id"],
 		queryParams: ["limit", "cursor"],
@@ -8322,7 +8321,7 @@ const routes = {
 		serviceClass: "Admin",
 		operationId: "listAdminListings",
 		description: "Every listing in one state, newest first — `in_review` by default, the queue an operator works through.",
-		moduleDocsUrl: "https://naturali.ai/docs/modules/admin",
+		moduleDocsUrl: "https://naturali.ai/docs",
 		httpMethod: "get",
 		pathParams: [],
 		queryParams: [
@@ -8360,7 +8359,7 @@ const routes = {
 		serviceClass: "Admin",
 		operationId: "setAdminListingState",
 		description: "List a listing in review or one that is suspended, send one in review back to `draft`, or suspend any listing. A listing an operator suspends cannot be resumed by its publisher. An invalid move answers `409 invalid_listing_state`.",
-		moduleDocsUrl: "https://naturali.ai/docs/modules/admin",
+		moduleDocsUrl: "https://naturali.ai/docs",
 		httpMethod: "put",
 		pathParams: ["listing_id"],
 		queryParams: [],
@@ -8595,7 +8594,7 @@ const routes = {
 			},
 			{
 				"name": "version_label",
-				"description": "Optional tag for the config version this write archives (e.g. `initial`). Annotates the version only — it is not stored on the agent and is not part of the config, so labelling a change is never itself a change.",
+				"description": "Optional tag for the config version this write creates (e.g. `initial`). Annotates the version only — it is not stored on the agent and is not part of the config, so labelling a change is never itself a change.",
 				"required": false,
 				"type": "string",
 				"in": "body"
@@ -8821,7 +8820,7 @@ const routes = {
 			},
 			{
 				"name": "version_label",
-				"description": "Optional tag for the config version this write archives (e.g. `pre-tone-change`). Annotates the version only — it is not stored on the agent and is not part of the config, so labelling a change is never itself a change. Ignored when the write changes nothing, since no version is created.",
+				"description": "Optional tag for the config version this write creates (e.g. `tone-change`). Annotates the version only — it is not stored on the agent and is not part of the config, so labelling a change is never itself a change. Ignored when the write changes nothing, since no version is created.",
 				"required": false,
 				"type": "string",
 				"in": "body"
@@ -9030,7 +9029,7 @@ const routes = {
 			},
 			{
 				"name": "version_label",
-				"description": "Optional tag for the config version this write archives (e.g. `pre-tone-change`). Annotates the version only — it is not stored on the agent and is not part of the config, so labelling a change is never itself a change. Ignored when the write changes nothing, since no version is created.",
+				"description": "Optional tag for the config version this write creates (e.g. `tone-change`). Annotates the version only — it is not stored on the agent and is not part of the config, so labelling a change is never itself a change. Ignored when the write changes nothing, since no version is created.",
 				"required": false,
 				"type": "string",
 				"in": "body"
@@ -9667,7 +9666,7 @@ const routes = {
 	"delete-ai-provider": {
 		serviceClass: "AIProviders",
 		operationId: "deleteAiProvider",
-		description: "Deletes an AI provider configuration. Live references — chats, agents, and model routes whose targets name this provider — always block deletion with `409 AI_PROVIDER_HAS_DEPENDENTS`; `force` does not override them, so delete or repoint those resources first. Soft dependents — price overrides and usage/generation records — also block with `409` unless `force=true`, which deletes the provider's price overrides and unlinks its usage history, preserving those rows: each usage event keeps the provider's id as its `ai_provider_id`. The `409` body's `error.meta` reports the counts, a sample of offending IDs, and a `forcible` flag that is `true` when a `force=true` retry would succeed.",
+		description: "Deletes an AI provider configuration. Live references — agents and model routes whose targets name this provider — always block deletion with `409 AI_PROVIDER_HAS_DEPENDENTS`; `force` does not override them, so delete or repoint those resources first. Soft dependents — price overrides and usage/generation records — also block with `409` unless `force=true`, which deletes the provider's price overrides and unlinks its usage history, preserving those rows: each usage event keeps the provider's id as its `ai_provider_id`. The `409` body's `error.meta` reports the counts, a sample of offending IDs, and a `forcible` flag that is `true` when a `force=true` retry would succeed.",
 		moduleDocsUrl: "https://naturali.ai/docs/modules/ai-providers",
 		httpMethod: "delete",
 		pathParams: ["project_id", "ai_provider_id"],
@@ -9691,7 +9690,7 @@ const routes = {
 			},
 			{
 				"name": "force",
-				"description": "When `true`, delete the provider's price overrides and unlink its usage history so a provider with only soft dependents can be removed. Has no effect on live references (chats, agents, model routes), which always block deletion.\n",
+				"description": "When `true`, delete the provider's price overrides and unlink its usage history so a provider with only soft dependents can be removed. Has no effect on live references (agents, model routes), which always block deletion.\n",
 				"required": false,
 				"type": "boolean",
 				"in": "query"
@@ -10127,7 +10126,7 @@ const routes = {
 			},
 			{
 				"name": "arguments",
-				"description": "Edited arguments to execute instead of the proposed ones. Editing composes a new call, so it additionally requires permission to make that call: `tools:CallTool` on the tool, and for a `builtin` proposal the action's own IAM action.",
+				"description": "Edited arguments to execute instead of the proposed ones. Editing composes a new call to the tool. Refused on an item with no `proposed_action`.",
 				"required": false,
 				"type": "object",
 				"in": "body"
@@ -10641,7 +10640,7 @@ const routes = {
 	"refresh-session": {
 		serviceClass: "Auth",
 		operationId: "refreshSession",
-		description: "Exchanges a valid refresh token for a new access JWT and a rotated refresh token, taken from the body or from the `refresh_token` cookie set at sign-in — a browser sends an empty body and the cookie carries the credential. Refresh tokens are single-use; presenting a previously-rotated token is treated as reuse and revokes the whole session family (createRefreshRotation reuse detection), except within a few seconds of the rotation, where it is treated as two tabs racing on one cookie and rotated again.",
+		description: "Exchanges a valid refresh token for a new access JWT and a rotated refresh token, taken from the body or from the `refresh_token` cookie set at sign-in — a browser sends an empty body and the cookie carries the credential. Refresh tokens are single-use; presenting a previously-rotated token is treated as reuse and revokes the whole session family, except within a few seconds of the rotation, where it is treated as two tabs racing on one cookie and rotated again.",
 		moduleDocsUrl: "https://naturali.ai/docs/modules/auth",
 		httpMethod: "post",
 		pathParams: [],
@@ -11094,7 +11093,7 @@ const routes = {
 	"list-project-channel-routes": {
 		serviceClass: "Channels",
 		operationId: "listProjectChannelRoutes",
-		description: "Every route across every channel in the project, one read — the table is small by construction (CHANNELS-ROUTING.md §3.6), so this is unpaginated.",
+		description: "Every route across every channel in the project, one read — the table is small by construction, so this is unpaginated.",
 		moduleDocsUrl: "https://naturali.ai/docs/modules/channel-routes",
 		httpMethod: "get",
 		pathParams: ["project_id"],
@@ -11146,7 +11145,7 @@ const routes = {
 	"create-channel": {
 		serviceClass: "Channels",
 		operationId: "createChannel",
-		description: "Connect a channel. The required fields depend on `channel`; no credential is ever returned. **Discord** (`channel: discord`) — supply `application_id` and `bot_token`, plus the `modes` selecting which Gateway flows to serve (direct messages, and/or @mention-opens-a-thread). The token is checked with Discord first: `400 invalid_bot_token` when Discord rejects it, `400 application_mismatch` when it belongs to another application. Returns `501` when the deployment has no `CHANNEL_TOKEN_KEY` configured. **WhatsApp** (default) — one of two credential paths, both filling the same write-only secret: * **BYOT** (`credential_source: byot`, default) — supply `phone_number_id` and `access_token` from your own Meta app. * **Embedded signup** (`credential_source: embedded_signup`) — supply `code` and `waba_id` from the Meta popup; naturali exchanges the `code` for the token, subscribes its app to the WABA and registers the number for sending when it is not yet, so the customer never hands over a token. Returns `501` on deployments where Meta App credentials are not configured. The project's plan limits how many channels it may hold. At the limit this responds `403` with `plan_limit_reached`, whose `details` carry the `plan` and the `limit`, before any credential is acquired. Only `active` channels count, so disabling one frees allowance without deleting it.",
+		description: "Connect a channel. The required fields depend on `channel`; no credential is ever returned. **Discord** (`channel: discord`) — supply `application_id` and `bot_token`, plus the `modes` selecting which Gateway flows to serve (direct messages, and/or @mention-opens-a-thread). The token is checked with Discord first: `400 invalid_bot_token` when Discord rejects it, `400 application_mismatch` when it belongs to another application. Returns `501` when this deployment does not enable Discord channels. **WhatsApp** (default) — one of two credential paths, both filling the same write-only secret: * **BYOT** (`credential_source: byot`, default) — supply `phone_number_id` and `access_token` from your own Meta app. * **Embedded signup** (`credential_source: embedded_signup`) — supply `code` and `waba_id` from the Meta popup; naturali exchanges the `code` for the token, subscribes its app to the WABA and registers the number for sending when it is not yet, so the customer never hands over a token. Returns `501` on deployments where Meta App credentials are not configured. The project's plan limits how many channels it may hold. At the limit this responds `403` with `plan_limit_reached`, whose `details` carry the `plan` and the `limit`, before any credential is acquired. Only `active` channels count, so disabling one frees allowance without deleting it.",
 		moduleDocsUrl: "https://naturali.ai/docs/modules/channels",
 		httpMethod: "post",
 		pathParams: ["project_id"],
@@ -11212,7 +11211,7 @@ const routes = {
 			},
 			{
 				"name": "code",
-				"description": "Required for `embedded_signup`. The short-lived authorization code from the Meta popup; naturali exchanges it for the access token server-side. Never stored or returned.\n",
+				"description": "Required for `embedded_signup`. The short-lived authorization code from the Meta popup; naturali exchanges it for the access token server-side. Never stored or returned. A code Meta rejects (malformed, expired or already used) is `400 invalid_signup_code`.\n",
 				"required": false,
 				"type": "string",
 				"in": "body"
@@ -12333,7 +12332,7 @@ const routes = {
 			},
 			{
 				"name": "version_label",
-				"description": "Optional tag for the version this write archives. Ignored when the write changes no question, since no version is archived.",
+				"description": "Optional tag for the version this write creates. Ignored when the write changes no question, since no version is archived.",
 				"required": false,
 				"type": "string",
 				"in": "body"
@@ -12793,7 +12792,7 @@ const routes = {
 			},
 			{
 				"name": "filename",
-				"description": "",
+				"description": "Download name. Defaults to the leaf of `path`.",
 				"required": false,
 				"type": "string",
 				"in": "body"
@@ -13251,7 +13250,7 @@ const routes = {
 			},
 			{
 				"name": "version_label",
-				"description": "Optional tag for the tombstone version this write archives.",
+				"description": "Optional tag for the tombstone version this write creates.",
 				"required": false,
 				"type": "string",
 				"in": "body"
@@ -13553,7 +13552,7 @@ const routes = {
 	"create-embeddings": {
 		serviceClass: "Embeddings",
 		operationId: "createEmbeddings",
-		description: "Generates embedding vectors for one or more text inputs using the server's configured embedding model. Provide `input` for a single text or `inputs` for a batch. At least one is required. Returns `embedding` when `input` is used, and `embeddings` when `inputs` is used. `project_id` names the project the call's token usage is metered against, so embedding spend reaches the usage rollup and the project's `cost_usd` / `tokens` quotas. A project-scoped credential supplies its own project; a call that names none and is bound to none is `400 VALIDATION_FAILED`.",
+		description: "Generates embedding vectors for one or more text inputs using the server's configured embedding model. Provide `input` for a single text or `inputs` for a batch. At least one is required. Returns `embedding` when `input` is used, and `embeddings` when `inputs` is used. The call's token usage is metered against the project in the path, so embedding spend reaches the usage rollup and the project's `cost_usd` / `tokens` quotas. A body `project_id` is ignored.",
 		moduleDocsUrl: "https://naturali.ai/docs/modules/embeddings",
 		httpMethod: "post",
 		pathParams: ["project_id"],
@@ -13570,7 +13569,7 @@ const routes = {
 			},
 			{
 				"name": "input",
-				"description": "Single text to embed.",
+				"description": "Single text to embed. An empty string is `400 VALIDATION_FAILED`.",
 				"required": false,
 				"type": "string",
 				"in": "body"
@@ -15638,7 +15637,7 @@ const routes = {
 			},
 			{
 				"name": "version_label",
-				"description": "Optional tag for the config version this write archives (e.g. `initial`). Annotates the version only — it is not stored on the guardrail and is not part of the config, so labelling a change is never itself a change.",
+				"description": "Optional tag for the config version this write creates (e.g. `initial`). Annotates the version only — it is not stored on the guardrail and is not part of the config, so labelling a change is never itself a change.",
 				"required": false,
 				"type": "string",
 				"in": "body"
@@ -15738,7 +15737,7 @@ const routes = {
 			},
 			{
 				"name": "version_label",
-				"description": "Optional tag for the config version this write archives (e.g. `pre-tightening`). Annotates the version only — it is not stored on the guardrail and is not part of the config, so labelling a change is never itself a change. Ignored when the write changes no policy, since no version is created.",
+				"description": "Optional tag for the config version this write creates (e.g. `tightened`). Annotates the version only — it is not stored on the guardrail and is not part of the config, so labelling a change is never itself a change. Ignored when the write changes no policy, since no version is created.",
 				"required": false,
 				"type": "string",
 				"in": "body"
@@ -16235,7 +16234,7 @@ const routes = {
 		serviceClass: "Installs",
 		operationId: "listInstalls",
 		description: "The listings the project installed, newest first.",
-		moduleDocsUrl: "https://naturali.ai/docs/modules/installs",
+		moduleDocsUrl: "https://naturali.ai/docs/modules/marketplace",
 		httpMethod: "get",
 		pathParams: ["project_id"],
 		queryParams: ["limit", "cursor"],
@@ -16269,7 +16268,7 @@ const routes = {
 		serviceClass: "Installs",
 		operationId: "createInstall",
 		description: "Install a listing by its id. A listed entry, a draft and a listing in review all install; a suspended one answers `409 listing_suspended`. Installing again answers the existing install. After the publisher removed this project's access, installing answers `403 install_blocked`.",
-		moduleDocsUrl: "https://naturali.ai/docs/modules/installs",
+		moduleDocsUrl: "https://naturali.ai/docs/modules/marketplace",
 		httpMethod: "post",
 		pathParams: ["project_id"],
 		queryParams: [],
@@ -16293,7 +16292,7 @@ const routes = {
 		serviceClass: "Installs",
 		operationId: "getInstall",
 		description: "One of the project's installs.",
-		moduleDocsUrl: "https://naturali.ai/docs/modules/installs",
+		moduleDocsUrl: "https://naturali.ai/docs/modules/marketplace",
 		httpMethod: "get",
 		pathParams: ["project_id", "install_id"],
 		queryParams: [],
@@ -16317,7 +16316,7 @@ const routes = {
 		serviceClass: "Installs",
 		operationId: "deleteInstall",
 		description: "Remove the install. While the project's agents, ingestion rules or other resources still name the installed resource, this answers `409 install_in_use` with them in `details.references`; `force=true` uninstalls anyway and those resources stop reaching it. A `blocked` install, and the install managed conversion uses, answer `403`.",
-		moduleDocsUrl: "https://naturali.ai/docs/modules/installs",
+		moduleDocsUrl: "https://naturali.ai/docs/modules/marketplace",
 		httpMethod: "delete",
 		pathParams: ["project_id", "install_id"],
 		queryParams: ["force"],
@@ -16381,14 +16380,14 @@ const routes = {
 			},
 			{
 				"name": "rrf_k",
-				"description": "The `k` in the reciprocal rank fusion term `1 / (k + rank)`, which sets how steeply a result's contribution decays with its position in each ranked list. A smaller value weights the very top of each list more heavily. Defaults to the deployment's `KNOWLEDGE_RRF_K`, itself 60 by default. Only applies when `query` is provided.",
+				"description": "The `k` in the reciprocal rank fusion term `1 / (k + rank)`, which sets how steeply a result's contribution decays with its position in each ranked list. A smaller value weights the very top of each list more heavily. Defaults to 60. Only applies when `query` is provided.",
 				"required": false,
 				"type": "integer",
 				"in": "body"
 			},
 			{
 				"name": "recency_half_life_days",
-				"description": "Half-life, in days, of a recency decay applied to **memory store** results after fusion: a result's `score` is multiplied by `2 ^ (-age_in_days / recency_half_life_days)`, where age is measured from its `updated_at`. Document results are never decayed. `0` — the default, and the default of the deployment's `KNOWLEDGE_RECENCY_HALF_LIFE_DAYS` — disables the blend entirely; it is a switch, not a lower bound, and sending `0` turns off a deployment-wide decay for this one request. Accepts fractions (`0.5` is twelve hours). How many ranks a given half-life costs depends on `rrf_k`. Only applies when `query` is provided. **No value is known to be safe in general**: every half-life measured against the reference corpus that lifted recency-sensitive queries also cost relevance-sensitive ones, which is why this ships disabled. Measure against your own corpus before setting it — see the Retrieval Quality guide.",
+				"description": "Half-life, in days, of a recency decay applied to **memory store** results after fusion: a result's `score` is multiplied by `2 ^ (-age_in_days / recency_half_life_days)`, where age is measured from its `updated_at`. Document results are never decayed. `0`, the default, disables the blend entirely. Accepts fractions (`0.5` is twelve hours). How many ranks a given half-life costs depends on `rrf_k`. Only applies when `query` is provided. **No value is known to be safe in general**: every half-life measured against the reference corpus that lifted recency-sensitive queries also cost relevance-sensitive ones, which is why this ships disabled. Measure against your own corpus before setting it.",
 				"required": false,
 				"type": "number",
 				"in": "body"
@@ -16455,7 +16454,7 @@ const routes = {
 		serviceClass: "Listings",
 		operationId: "listPublicListings",
 		description: "Every listed entry, newest first. `interface` is what an installing project sees of the resource, read live from the publisher.",
-		moduleDocsUrl: "https://naturali.ai/docs/modules/listings",
+		moduleDocsUrl: "https://naturali.ai/docs/modules/marketplace",
 		httpMethod: "get",
 		pathParams: [],
 		queryParams: ["limit", "cursor"],
@@ -16479,7 +16478,7 @@ const routes = {
 		serviceClass: "Listings",
 		operationId: "getPublicListing",
 		description: "One listed entry. A listing that is not listed answers `404`.",
-		moduleDocsUrl: "https://naturali.ai/docs/modules/listings",
+		moduleDocsUrl: "https://naturali.ai/docs/modules/marketplace",
 		httpMethod: "get",
 		pathParams: ["listing_id"],
 		queryParams: [],
@@ -16497,7 +16496,7 @@ const routes = {
 		serviceClass: "Listings",
 		operationId: "listListings",
 		description: "The listings the project publishes, newest first.",
-		moduleDocsUrl: "https://naturali.ai/docs/modules/listings",
+		moduleDocsUrl: "https://naturali.ai/docs/modules/marketplace",
 		httpMethod: "get",
 		pathParams: ["project_id"],
 		queryParams: ["limit", "cursor"],
@@ -16531,7 +16530,7 @@ const routes = {
 		serviceClass: "Listings",
 		operationId: "createListing",
 		description: "Publish one of the project's tools or agents as a `draft`. Any project member may publish. An agent on a naturali model whose model has no price answers `503 model_not_priced`. A resource that does not exist in the project answers `400 resource_not_found`, and one that already has a listing `409 listing_exists`.",
-		moduleDocsUrl: "https://naturali.ai/docs/modules/listings",
+		moduleDocsUrl: "https://naturali.ai/docs/modules/marketplace",
 		httpMethod: "post",
 		pathParams: ["project_id"],
 		queryParams: [],
@@ -16586,7 +16585,7 @@ const routes = {
 		serviceClass: "Listings",
 		operationId: "getListing",
 		description: "One of the project's listings.",
-		moduleDocsUrl: "https://naturali.ai/docs/modules/listings",
+		moduleDocsUrl: "https://naturali.ai/docs/modules/marketplace",
 		httpMethod: "get",
 		pathParams: ["project_id", "listing_id"],
 		queryParams: [],
@@ -16609,8 +16608,8 @@ const routes = {
 	"update-listing": {
 		serviceClass: "Listings",
 		operationId: "updateListing",
-		description: "Change the title or description, or pause and resume the listing. `state: suspended` stops the listing for every installing project at once; their installs are kept. `state: listed` resumes a listing you suspended, provided naturali had listed it; nobody reinstalls. A listing naturali suspended cannot be resumed here, and an invalid move answers `409 invalid_listing_state`.",
-		moduleDocsUrl: "https://naturali.ai/docs/modules/listings",
+		description: "Change the title or description, or pause and resume the listing. `state: suspended` stops a `listed` listing for every installing project at once; their installs are kept. `state: listed` resumes a listing you suspended, provided naturali had listed it; nobody reinstalls. A listing naturali suspended cannot be resumed here, and an invalid move answers `409 invalid_listing_state`.",
+		moduleDocsUrl: "https://naturali.ai/docs/modules/marketplace",
 		httpMethod: "patch",
 		pathParams: ["project_id", "listing_id"],
 		queryParams: [],
@@ -16665,7 +16664,7 @@ const routes = {
 		serviceClass: "Listings",
 		operationId: "deleteListing",
 		description: "Remove a listing and stop sharing its resource. Refused with `409 listing_has_installs` while any project holds an install, in any state: remove each one first, which takes two deletes of `/installs/{install_id}` for an `active` or `suspended` install. The listing's price stops applying from the next minute, and a later listing of the same resource starts from no price. The tool or agent itself is not touched.",
-		moduleDocsUrl: "https://naturali.ai/docs/modules/listings",
+		moduleDocsUrl: "https://naturali.ai/docs/modules/marketplace",
 		httpMethod: "delete",
 		pathParams: ["project_id", "listing_id"],
 		queryParams: [],
@@ -16689,7 +16688,7 @@ const routes = {
 		serviceClass: "Listings",
 		operationId: "submitListing",
 		description: "Move a `draft` listing to `in_review`. naturali lists it in the marketplace or sends it back to `draft`. Any other state answers `409 invalid_listing_state`.",
-		moduleDocsUrl: "https://naturali.ai/docs/modules/listings",
+		moduleDocsUrl: "https://naturali.ai/docs/modules/marketplace",
 		httpMethod: "post",
 		pathParams: ["project_id", "listing_id"],
 		queryParams: [],
@@ -16713,7 +16712,7 @@ const routes = {
 		serviceClass: "Listings",
 		operationId: "listListingInstalls",
 		description: "Each project that installed the listing, with its usage this billing cycle as last sampled. Never the content of a call.",
-		moduleDocsUrl: "https://naturali.ai/docs/modules/listings",
+		moduleDocsUrl: "https://naturali.ai/docs/modules/marketplace",
 		httpMethod: "get",
 		pathParams: ["project_id", "listing_id"],
 		queryParams: ["limit", "cursor"],
@@ -16754,7 +16753,7 @@ const routes = {
 		serviceClass: "Listings",
 		operationId: "deleteListingInstall",
 		description: "Cut one installing project off. An `active` or `suspended` install becomes `blocked`, and that project cannot install the listing again. Deleting a `blocked` install removes it, which lets that project install again.",
-		moduleDocsUrl: "https://naturali.ai/docs/modules/listings",
+		moduleDocsUrl: "https://naturali.ai/docs/modules/marketplace",
 		httpMethod: "delete",
 		pathParams: [
 			"project_id",
@@ -18564,7 +18563,7 @@ const routes = {
 	"get-queue-stats": {
 		serviceClass: "Orchestrations",
 		operationId: "getQueueStats",
-		description: "Returns a point-in-time snapshot of the orchestration run queue: how many tasks are waiting to be claimed (`queue_depth`), how many are currently claimed with a valid lease (`claimed_tasks`), the age of the oldest waiting task, recent claim-latency percentiles over a rolling in-process window. The per-project breakdown is listed by `GET /v1/projects/{project_id}/orchestrations/queue/stats/projects`. Intended for admin/operator policies; guarded by `orchestrations:GetQueueStats`. Every figure is scoped to what the caller may see. A project-scoped caller gets `queue_depth` and `claimed_tasks` summed over their own projects, and `null` for `oldest_queued_age_seconds` and the `claim_latency_ms` percentiles — both describe the whole deployment and cannot be narrowed, so they are withheld rather than approximated. An unrestricted caller (the action granted on every project) gets the deployment-wide figures.",
+		description: "Returns a point-in-time snapshot of the orchestration run queue: how many tasks are waiting to be claimed (`queue_depth`), how many are currently claimed with a valid lease (`claimed_tasks`), the age of the oldest waiting task, recent claim-latency percentiles over a rolling in-process window. The per-project breakdown is listed by `GET /v1/projects/{project_id}/orchestrations/queue/stats/projects`. Every figure is scoped to what the caller may see. A project-scoped caller gets `queue_depth` and `claimed_tasks` summed over their own projects, and `null` for `oldest_queued_age_seconds` and the `claim_latency_ms` percentiles — both describe the whole deployment and cannot be narrowed, so they are withheld rather than approximated.",
 		moduleDocsUrl: "https://naturali.ai/docs/modules/orchestrations",
 		httpMethod: "get",
 		pathParams: ["project_id"],
@@ -18582,7 +18581,7 @@ const routes = {
 	"list-queue-stats-projects": {
 		serviceClass: "Orchestrations",
 		operationId: "listQueueStatsProjects",
-		description: "One row per project with any queued or claimed task, ordered by project ID: the per-project breakdown of `GET /v1/projects/{project_id}/orchestrations/queue/stats`. A project-scoped caller sees its own projects only. Guarded by `orchestrations:GetQueueStats`.",
+		description: "One row per project with any queued or claimed task, ordered by project ID: the per-project breakdown of `GET /v1/projects/{project_id}/orchestrations/queue/stats`. A project-scoped caller sees its own projects only.",
 		moduleDocsUrl: "https://naturali.ai/docs/modules/orchestrations",
 		httpMethod: "get",
 		pathParams: ["project_id"],
@@ -18720,7 +18719,7 @@ const routes = {
 			},
 			{
 				"name": "version_label",
-				"description": "Optional tag for the version this write archives, e.g. `pre-rewire`. Ignored when the write changes no graph field, since no version is archived.",
+				"description": "Optional tag for the version this write creates, e.g. `rewired`. Ignored when the write changes no graph field, since no version is archived.",
 				"required": false,
 				"type": "string",
 				"in": "body"
@@ -19403,7 +19402,7 @@ const routes = {
 			},
 			{
 				"name": "version_label",
-				"description": "Optional tag for the version this write archives. Ignored when the write changes no definition, since no version is archived.",
+				"description": "Optional tag for the version this write creates. Ignored when the write changes no definition, since no version is archived.",
 				"required": false,
 				"type": "string",
 				"in": "body"
@@ -22915,7 +22914,7 @@ const routes = {
 			},
 			{
 				"name": "execute",
-				"description": "Execution config for http tools. Supported fields: `url` (required), `method` (default `POST`), `headers`, `body_mode` and `response_mode`. The `url` may contain `{paramName}` placeholders (e.g. `/users/{userId}`) that are replaced at call time with the corresponding tool argument value (URL-encoded). Arguments consumed as path parameters are excluded from the query string and request body. `body_mode` is `json` (default) or `multipart`. In `multipart` mode the merged tool arguments are sent as a `multipart/form-data` body: scalar fields become plain form fields and a field shaped like `{ content_type, filename, data_base64 }` is decoded from base64 and attached as a file part (the hardcoded `Content-Type: application/json` is dropped so `fetch` sets the multipart boundary itself). `response_mode` is `json` (default: the body parsed as JSON, else returned as text) or `base64`, which returns a 2xx body as `{ content_type, filename, data_base64 }` — the same file shape `multipart` accepts, so a pipeline step can relay a downloaded file. `filename` comes from `Content-Disposition` and is omitted when the target names none; a body over `TOOL_RESPONSE_MAX_BYTES` is `502 TOOL_RESPONSE_TOO_LARGE`.\n\n`auth` adds a computed request credential, for targets whose `Authorization` value cannot be expressed as a static header. Supported `auth.type` values:\n\n- `aws_sigv4` — signs the request with AWS Signature Version 4. Requires `region`, `service`, `access_key_id` and `secret_access_key`; `session_token` is optional (temporary credentials). Incompatible with `body_mode: multipart`, whose body bytes are not known at signing time.\n- `gcp_service_account` — mints a Google OAuth 2.0 access token from a signed service account assertion and sends it as a bearer token. Requires `credentials` (the service account key file JSON, as a string) and `scopes` (a non-empty array). Tokens are cached per service account and scope set until shortly before they expire.\n\nCredential fields accept `{{secret:...}}` references and should use them — a tool is readable by anyone who can `GET /tools`, and the stored reference is what is echoed back, never the resolved value.\n\nA credential slot takes a reference, never a literal: a literal `secret_access_key`, `session_token` or `credentials` under `auth`, a literal credential-named `headers` value (`Authorization`, `Cookie`, or a name containing `api-key`/`token`/`secret`/`password`), or a `url` carrying a password or a literal credential-named query parameter (those names, plus `key` and `sig`/`signature`) is refused with `400 LITERAL_CREDENTIAL`, `meta.paths` naming each one. A stored literal reads back as `{\"no_echo\": true}` (a `url` holding one is masked whole), an object rather than a string so a read-edit-write round trip fails the schema check instead of writing the placeholder in as the credential. A value carrying a `{{secret:...}}` reference is the wiring, not the credential, and stays readable.\n\n`headers` values additionally accept `{{context:<key>}}` references, resolved per call from the caller's `tool_context`, so a per-user credential can be placed in the real header the target expects (`Authorization: Bearer {{context:ocaToken}}`) instead of only in an `X-Naturali-Context-<key>` header. Valid **only** inside `headers` — a context value is caller-supplied, so it may not steer the `url` — and a key missing from the `tool_context` at call time fails the tool call with `MISSING_TOOL_CONTEXT_KEY` rather than sending an empty credential. See the Tool Context reference.\n",
+				"description": "Execution config for http tools. An `http` tool without a non-empty `url` is `400 VALIDATION_FAILED`, on create and on an update that would leave it without one. Supported fields: `url` (required), `method` (default `POST`), `headers`, `body_mode` and `response_mode`. The `url` may contain `{paramName}` placeholders (e.g. `/users/{userId}`) that are replaced at call time with the corresponding tool argument value (URL-encoded). Arguments consumed as path parameters are excluded from the query string and request body. `body_mode` is `json` (default) or `multipart`. In `multipart` mode the merged tool arguments are sent as a `multipart/form-data` body: scalar fields become plain form fields and a field shaped like `{ content_type, filename, data_base64 }` is decoded from base64 and attached as a file part (the hardcoded `Content-Type: application/json` is dropped so `fetch` sets the multipart boundary itself). `response_mode` is `json` (default: the body parsed as JSON, else returned as text) or `base64`, which returns a 2xx body as `{ content_type, filename, data_base64 }` — the same file shape `multipart` accepts, so a pipeline step can relay a downloaded file. `filename` comes from `Content-Disposition` and is omitted when the target names none; a body over `TOOL_RESPONSE_MAX_BYTES` is `502 TOOL_RESPONSE_TOO_LARGE`.\n\n`auth` adds a computed request credential, for targets whose `Authorization` value cannot be expressed as a static header. Supported `auth.type` values:\n\n- `aws_sigv4` — signs the request with AWS Signature Version 4. Requires `region`, `service`, `access_key_id` and `secret_access_key`; `session_token` is optional (temporary credentials). Incompatible with `body_mode: multipart`, whose body bytes are not known at signing time.\n- `gcp_service_account` — mints a Google OAuth 2.0 access token from a signed service account assertion and sends it as a bearer token. Requires `credentials` (the service account key file JSON, as a string) and `scopes` (a non-empty array). Tokens are cached per service account and scope set until shortly before they expire.\n\nCredential fields accept `{{secret:...}}` references and should use them — a tool is readable by anyone who can `GET /tools`, and the stored reference is what is echoed back, never the resolved value.\n\nA credential slot takes a reference, never a literal: a literal `secret_access_key`, `session_token` or `credentials` under `auth`, a literal credential-named `headers` value (`Authorization`, `Cookie`, or a name containing `api-key`/`token`/`secret`/`password`), or a `url` carrying a password or a literal credential-named query parameter (those names, plus `key` and `sig`/`signature`) is refused with `400 LITERAL_CREDENTIAL`, `meta.paths` naming each one. A stored literal reads back as `{\"no_echo\": true}` (a `url` holding one is masked whole), an object rather than a string so a read-edit-write round trip fails the schema check instead of writing the placeholder in as the credential. A value carrying a `{{secret:...}}` reference is the wiring, not the credential, and stays readable.\n\n`headers` values additionally accept `{{context:<key>}}` references, resolved per call from the caller's `tool_context`, so a per-user credential can be placed in the real header the target expects (`Authorization: Bearer {{context:ocaToken}}`) instead of only in an `X-Naturali-Context-<key>` header. Valid **only** inside `headers` — a context value is caller-supplied, so it may not steer the `url` — and a key missing from the `tool_context` at call time fails the tool call with `MISSING_TOOL_CONTEXT_KEY` rather than sending an empty credential. See the Tool Context reference.\n",
 				"required": false,
 				"type": "object",
 				"in": "body"
@@ -23057,7 +23056,7 @@ const routes = {
 			},
 			{
 				"name": "execute",
-				"description": "Execution config for http tools. Supported fields: `url` (required), `method` (default `POST`), `headers`, `body_mode` and `response_mode`. The `url` may contain `{paramName}` placeholders (e.g. `/users/{userId}`) that are replaced at call time with the corresponding tool argument value (URL-encoded). Arguments consumed as path parameters are excluded from the query string and request body. `body_mode` is `json` (default) or `multipart`. In `multipart` mode the merged tool arguments are sent as a `multipart/form-data` body: scalar fields become plain form fields and a field shaped like `{ content_type, filename, data_base64 }` is decoded from base64 and attached as a file part (the hardcoded `Content-Type: application/json` is dropped so `fetch` sets the multipart boundary itself). `response_mode` is `json` (default: the body parsed as JSON, else returned as text) or `base64`, which returns a 2xx body as `{ content_type, filename, data_base64 }` — the same file shape `multipart` accepts, so a pipeline step can relay a downloaded file. `filename` comes from `Content-Disposition` and is omitted when the target names none; a body over `TOOL_RESPONSE_MAX_BYTES` is `502 TOOL_RESPONSE_TOO_LARGE`.\n\n`auth` adds a computed request credential, for targets whose `Authorization` value cannot be expressed as a static header. Supported `auth.type` values:\n\n- `aws_sigv4` — signs the request with AWS Signature Version 4. Requires `region`, `service`, `access_key_id` and `secret_access_key`; `session_token` is optional (temporary credentials). Incompatible with `body_mode: multipart`, whose body bytes are not known at signing time.\n- `gcp_service_account` — mints a Google OAuth 2.0 access token from a signed service account assertion and sends it as a bearer token. Requires `credentials` (the service account key file JSON, as a string) and `scopes` (a non-empty array). Tokens are cached per service account and scope set until shortly before they expire.\n\nCredential fields accept `{{secret:...}}` references and should use them — a tool is readable by anyone who can `GET /tools`, and the stored reference is what is echoed back, never the resolved value.\n\nA credential slot takes a reference, never a literal: a literal `secret_access_key`, `session_token` or `credentials` under `auth`, a literal credential-named `headers` value (`Authorization`, `Cookie`, or a name containing `api-key`/`token`/`secret`/`password`), or a `url` carrying a password or a literal credential-named query parameter (those names, plus `key` and `sig`/`signature`) is refused with `400 LITERAL_CREDENTIAL`, `meta.paths` naming each one. A stored literal reads back as `{\"no_echo\": true}` (a `url` holding one is masked whole), an object rather than a string so a read-edit-write round trip fails the schema check instead of writing the placeholder in as the credential. A value carrying a `{{secret:...}}` reference is the wiring, not the credential, and stays readable.\n\n`headers` values additionally accept `{{context:<key>}}` references, resolved per call from the caller's `tool_context`, so a per-user credential can be placed in the real header the target expects (`Authorization: Bearer {{context:ocaToken}}`) instead of only in an `X-Naturali-Context-<key>` header. Valid **only** inside `headers` — a context value is caller-supplied, so it may not steer the `url` — and a key missing from the `tool_context` at call time fails the tool call with `MISSING_TOOL_CONTEXT_KEY` rather than sending an empty credential. See the Tool Context reference.\n",
+				"description": "Execution config for http tools. An `http` tool without a non-empty `url` is `400 VALIDATION_FAILED`, on create and on an update that would leave it without one. Supported fields: `url` (required), `method` (default `POST`), `headers`, `body_mode` and `response_mode`. The `url` may contain `{paramName}` placeholders (e.g. `/users/{userId}`) that are replaced at call time with the corresponding tool argument value (URL-encoded). Arguments consumed as path parameters are excluded from the query string and request body. `body_mode` is `json` (default) or `multipart`. In `multipart` mode the merged tool arguments are sent as a `multipart/form-data` body: scalar fields become plain form fields and a field shaped like `{ content_type, filename, data_base64 }` is decoded from base64 and attached as a file part (the hardcoded `Content-Type: application/json` is dropped so `fetch` sets the multipart boundary itself). `response_mode` is `json` (default: the body parsed as JSON, else returned as text) or `base64`, which returns a 2xx body as `{ content_type, filename, data_base64 }` — the same file shape `multipart` accepts, so a pipeline step can relay a downloaded file. `filename` comes from `Content-Disposition` and is omitted when the target names none; a body over `TOOL_RESPONSE_MAX_BYTES` is `502 TOOL_RESPONSE_TOO_LARGE`.\n\n`auth` adds a computed request credential, for targets whose `Authorization` value cannot be expressed as a static header. Supported `auth.type` values:\n\n- `aws_sigv4` — signs the request with AWS Signature Version 4. Requires `region`, `service`, `access_key_id` and `secret_access_key`; `session_token` is optional (temporary credentials). Incompatible with `body_mode: multipart`, whose body bytes are not known at signing time.\n- `gcp_service_account` — mints a Google OAuth 2.0 access token from a signed service account assertion and sends it as a bearer token. Requires `credentials` (the service account key file JSON, as a string) and `scopes` (a non-empty array). Tokens are cached per service account and scope set until shortly before they expire.\n\nCredential fields accept `{{secret:...}}` references and should use them — a tool is readable by anyone who can `GET /tools`, and the stored reference is what is echoed back, never the resolved value.\n\nA credential slot takes a reference, never a literal: a literal `secret_access_key`, `session_token` or `credentials` under `auth`, a literal credential-named `headers` value (`Authorization`, `Cookie`, or a name containing `api-key`/`token`/`secret`/`password`), or a `url` carrying a password or a literal credential-named query parameter (those names, plus `key` and `sig`/`signature`) is refused with `400 LITERAL_CREDENTIAL`, `meta.paths` naming each one. A stored literal reads back as `{\"no_echo\": true}` (a `url` holding one is masked whole), an object rather than a string so a read-edit-write round trip fails the schema check instead of writing the placeholder in as the credential. A value carrying a `{{secret:...}}` reference is the wiring, not the credential, and stays readable.\n\n`headers` values additionally accept `{{context:<key>}}` references, resolved per call from the caller's `tool_context`, so a per-user credential can be placed in the real header the target expects (`Authorization: Bearer {{context:ocaToken}}`) instead of only in an `X-Naturali-Context-<key>` header. Valid **only** inside `headers` — a context value is caller-supplied, so it may not steer the `url` — and a key missing from the `tool_context` at call time fails the tool call with `MISSING_TOOL_CONTEXT_KEY` rather than sending an empty credential. See the Tool Context reference.\n",
 				"required": false,
 				"type": "object",
 				"in": "body"
@@ -23537,7 +23536,7 @@ const routes = {
 	"update-trigger": {
 		serviceClass: "Triggers",
 		operationId: "updateTrigger",
-		description: "Updates an existing trigger's configuration. The type is immutable. Changing `target_type` or `target_id` re-checks the target-start action (`orchestrations:StartRun`, `agents:CreateAgentGeneration` or `tools:CallTool`) against the resulting target, because a firing runs with the trigger creator's authority rather than the updater's. A caller who could not start the new target is answered `403` and the trigger keeps the target it had.",
+		description: "Updates an existing trigger's configuration. The type is immutable. Changing `target_type` or `target_id` re-checks that the caller may start the resulting target, because a firing runs with the trigger creator's authority rather than the updater's. A caller who could not start the new target is answered `403` and the trigger keeps the target it had.",
 		moduleDocsUrl: "https://naturali.ai/docs/modules/triggers",
 		httpMethod: "patch",
 		pathParams: ["project_id", "trigger_id"],
@@ -24685,7 +24684,7 @@ const routes = {
 			},
 			{
 				"name": "version_label",
-				"description": "Optional tag for the version this write archives, e.g. `pre-rewire`. Ignored when the write changes no definition field, since no version is archived.",
+				"description": "Optional tag for the version this write creates, e.g. `rewired`. Ignored when the write changes no definition field, since no version is archived.",
 				"required": false,
 				"type": "string",
 				"in": "body"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@naturali/cli",
-  "version": "0.209.2",
+  "version": "0.209.4",
   "description": "Command-line interface for the naturali.ai API, generated from its OpenAPI specs",
   "keywords": [
     "naturali",
@@ -31,7 +31,7 @@
     "yaml": "^2.9.1"
   },
   "devDependencies": {
-    "@naturali/sdk": "0.209.2",
+    "@naturali/sdk": "0.209.4",
     "@ttoss/openapi-codegen": "^0.10.0",
     "@types/node": "^26.5.1",
     "tsdown": "^0.23.0",