@soat/cli 0.20.4 → 0.21.0

package/dist/index.mjs

@@ -13,7 +13,7 @@ import { load } from "js-yaml";
 import * as os from "node:os";
 
 //#region package.json
-var version = "0.20.4";
+var version = "0.21.0";
 
 //#endregion
 //#region src/cli-wrappers/wrappers/formations.ts
@@ -1184,17 +1184,23 @@ var routes = {
   "create-agent-generation": {
     serviceClass: "Agents",
     operationId: "createAgentGeneration",
-    description: "Sends messages to the agent, resolves its tools, and runs the AI model loop. Supports streaming via `stream: true`. Client tools pause the generation and return `requires_action`.",
+    description: "Sends messages to the agent, resolves its tools, and runs the AI model loop. Background by default: returns `202 Accepted` with a `generation_id` to poll via `GET /api/v1/generations/{generation_id}`. Pass `?wait=true` to block and receive the result inline, where client tools pause the generation and return `requires_action`. Streaming (`stream: true`) implies waiting.",
     moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/agents",
     httpMethod: "post",
     pathParams: ["agent_id"],
-    queryParams: [],
+    queryParams: ["wait"],
     flags: [{
       "name": "agent_id",
       "description": "",
       "required": true,
       "type": "string",
       "in": "path"
+    }, {
+      "name": "wait",
+      "description": "When omitted or `false` (default), the generation runs in the background and `202 Accepted` is returned immediately with a `generation_id` to poll. Pass `true` to block until the generation settles and receive the result. Mutually exclusive with `stream: true`. A `soat` tool call always waits.",
+      "required": false,
+      "type": "boolean",
+      "in": "query"
     }, {
       "name": "messages",
       "description": "",
@@ -1407,12 +1413,18 @@ var routes = {
       "required": true,
       "type": "integer",
       "in": "body"
+    }, {
+      "name": "promotion_gate",
+      "description": "Eval to gate promotion on. It must belong to this project and evaluate this agent; anything else is a `400`. Omit it, or send null, for a rollout that can be promoted at will.",
+      "required": false,
+      "type": "string",
+      "in": "body"
     }]
   },
   "promote-agent-release": {
     serviceClass: "AgentVersions",
     operationId: "promoteAgentRelease",
-    description: "Makes the canary version's config the agent's live config and clears the release. The canary is pinned by version, so an edit that landed mid-rollout is not promoted in its place — it stays an unreleased draft in the version history.",
+    description: "Makes the canary version's config the agent's live config and clears the release. The canary is pinned by version, so an edit that landed mid-rollout is not promoted in its place — it stays an unreleased draft in the version history. When the release carries a `promotion_gate`, the eval it names must have a run that finished `completed` with `passed: true` **and** was pinned to the canary version (`agent_version`); otherwise the call is a `409` and the rollout is left running untouched. The run that cleared the gate is recorded as `eval_run_id` on the version that goes live.",
     moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/agents",
     httpMethod: "post",
     pathParams: ["agent_id"],
@@ -1592,7 +1604,7 @@ var routes = {
   "delete-ai-provider": {
     serviceClass: "AIProviders",
     operationId: "deleteAiProvider",
-    description: "Deletes an AI provider configuration. Live references — chats, agents, discussions, 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, usage/generation records, and discussion participants — also block with `409` unless `force=true`, which deletes the provider's price overrides and unlinks (nulls) its usage and participant history, preserving those rows. 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 — 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 (nulls) its usage history, preserving those rows. 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://soat.ttoss.dev/docs/modules/ai-providers",
     httpMethod: "delete",
     pathParams: ["ai_provider_id"],
@@ -1605,12 +1617,28 @@ var routes = {
       "in": "path"
     }, {
       "name": "force",
-      "description": "When `true`, delete the provider's price overrides and unlink its usage/participant history so a provider with only soft dependents can be removed. Has no effect on live references (chats, agents, discussions, 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 (chats, agents, model routes), which always block deletion.\n",
       "required": false,
       "type": "boolean",
       "in": "query"
     }]
   },
+  "list-ai-provider-models": {
+    serviceClass: "AIProviders",
+    operationId: "listAiProviderModels",
+    description: "Asks the provider which models it can run, using this provider record's own credentials and configuration, and returns provider-native model ids — the same strings `default_model` and an agent's `model` carry. Which models are reachable is a property of the credential, not of the provider type: a Vertex provider sees only the publisher models its Google Cloud project and location serve, and a Bedrock provider only the foundation models enabled in its region. Reading the list is how a caller avoids pinning a model that fails at generation time. Not every provider type can answer. `azure` lists deployments an operator named rather than models, and `ollama` lists whatever was pulled onto that host, so both return `400 MODEL_LISTING_UNSUPPORTED`.",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/ai-providers",
+    httpMethod: "get",
+    pathParams: ["ai_provider_id"],
+    queryParams: [],
+    flags: [{
+      "name": "ai_provider_id",
+      "description": "AI Provider ID",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }]
+  },
   "get-ai-provider-prices": {
     serviceClass: "AIProviders",
     operationId: "getAiProviderPrices",
@@ -2416,17 +2444,23 @@ var routes = {
   "generate-conversation-message": {
     serviceClass: "Conversations",
     operationId: "generateConversationMessage",
-    description: "Generates the next message using the specified actor's linked agent or chat. On `completed`, the reply is persisted as a new ConversationMessage authored by that actor. On `requires_action`, nothing is persisted; the caller must submit tool outputs via the Agents module and re-invoke generate.",
+    description: "Generates the next message using the specified actor's linked agent or chat. Background by default: returns `202 Accepted` immediately and the reply lands as a new ConversationMessage when it completes — poll `GET /api/v1/conversations/{conversation_id}/messages` for it. Pass `?wait=true` to block and receive the result inline. On `completed`, the reply is persisted as a new ConversationMessage authored by that actor. On `requires_action`, nothing is persisted; the caller must submit tool outputs via the Agents module and re-invoke generate — so a flow using client tools should pass `?wait=true`.",
     moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/conversations",
     httpMethod: "post",
     pathParams: ["conversation_id"],
-    queryParams: [],
+    queryParams: ["wait"],
     flags: [{
       "name": "conversation_id",
       "description": "",
       "required": true,
       "type": "string",
       "in": "path"
+    }, {
+      "name": "wait",
+      "description": "When omitted or `false` (default), the generation runs in the background and `202 Accepted` is returned immediately. Pass `true` to block until the generation settles and receive the result. A `soat` tool call always waits.",
+      "required": false,
+      "type": "boolean",
+      "in": "query"
     }, {
       "name": "agent_id",
       "description": "ID of the agent that will produce the next message.",
@@ -2523,11 +2557,11 @@ var routes = {
       "in": "path"
     }]
   },
-  "list-discussions": {
-    serviceClass: "Discussions",
-    operationId: "listDiscussions",
-    description: "Returns all discussions the caller has access to. If project_id is provided, returns only discussions in that project.",
-    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/discussions",
+  "list-documents": {
+    serviceClass: "Documents",
+    operationId: "listDocuments",
+    description: "Returns all documents the caller has access to. If projectId is provided, returns only documents in that project. project keys are scoped to a single project automatically. JWT users without projectId receive documents across all their accessible projects.",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/documents",
     httpMethod: "get",
     pathParams: [],
     queryParams: ["project_id", "limit", "offset"],
@@ -2551,243 +2585,383 @@ var routes = {
       "in": "query"
     }]
   },
-  "create-discussion": {
-    serviceClass: "Discussions",
-    operationId: "createDiscussion",
-    description: "Creates a new discussion config. project keys infer the project from the key's scope; JWT callers must supply project_id.",
-    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/discussions",
+  "create-document": {
+    serviceClass: "Documents",
+    operationId: "createDocument",
+    description: "Creates a new text document and generates an embedding vector for semantic search. project keys automatically infer the project from the key's scope; JWT callers must supply projectId.",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/documents",
     httpMethod: "post",
     pathParams: [],
     queryParams: [],
     flags: [{
       "name": "project_id",
-      "description": "Project ID. Required for JWT auth; omit when using a project key.",
+      "description": "Project ID. Required for JWT auth; omit when using an project key.",
       "required": false,
       "type": "string",
       "in": "body"
     }, {
-      "name": "name",
+      "name": "content",
       "description": "",
       "required": true,
       "type": "string",
       "in": "body"
     }, {
-      "name": "description",
-      "description": "",
+      "name": "path",
+      "description": "Logical path within the project (e.g. /reports/q1.txt). Defaults to /filename if omitted.",
       "required": false,
       "type": "string",
       "in": "body"
     }, {
-      "name": "ai_provider_id",
-      "description": "Default AI provider participants and synthesis fall back to. Optional: omit it to inherit the project's `default_model_route_id`, which gives every turn provider failover. Omitting it returns `400` when the project has no default.",
+      "name": "filename",
+      "description": "",
       "required": false,
       "type": "string",
       "in": "body"
     }, {
-      "name": "model",
-      "description": "Default model (falls back to the provider's default_model).",
+      "name": "title",
+      "description": "Document title",
       "required": false,
       "type": "string",
       "in": "body"
     }, {
-      "name": "max_rounds",
-      "description": "",
+      "name": "metadata",
+      "description": "Arbitrary metadata object. Unlike other body fields, keys are stored and returned verbatim in the casing supplied — they are not converted between snake_case and camelCase.",
       "required": false,
-      "type": "integer",
+      "type": "object",
       "in": "body"
     }, {
-      "name": "synthesis",
-      "description": "Override for the final synthesis pass that weighs the deliberation into a single outcome.",
+      "name": "tags",
+      "description": "Key-value tags",
       "required": false,
       "type": "object",
       "in": "body"
     }, {
-      "name": "tags",
-      "description": "",
+      "name": "chunk_strategy",
+      "description": "How to split the content into embeddable chunks. `whole` (default) stores the content as a single chunk; `size` splits into fixed-size character windows with overlap. `page` is equivalent to `whole` for plain text.",
       "required": false,
-      "type": "object",
+      "type": "string",
       "in": "body"
     }, {
-      "name": "participants",
-      "description": "",
+      "name": "chunk_size",
+      "description": "Window size in characters when `chunk_strategy=size`. Defaults to 1000.",
       "required": false,
-      "type": "array",
+      "type": "integer",
+      "in": "body"
+    }, {
+      "name": "chunk_overlap",
+      "description": "Overlap in characters between consecutive windows when `chunk_strategy=size`. Defaults to 200.",
+      "required": false,
+      "type": "integer",
       "in": "body"
     }]
   },
-  "get-discussion-run": {
-    serviceClass: "Discussions",
-    operationId: "getDiscussionRun",
-    description: "Returns a single discussion run, including its outcome, transcript conversation, and outcome document.",
-    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/discussions",
-    httpMethod: "get",
-    pathParams: ["run_id"],
-    queryParams: [],
+  "ingest-document": {
+    serviceClass: "Documents",
+    operationId: "ingestDocument",
+    description: "Parses an already-uploaded file and creates one Document split into one or more embedded chunks. The source format is detected from the file's content type: PDFs are parsed page-by-page; `text/plain` and `text/markdown` files are read as a single source. How the source is chunked is controlled by `chunk_strategy`. A file can only back one Document — a second call with the same `file_id` returns `409 FILE_ALREADY_INGESTED`. To re-process an already-ingested file (e.g. with a different `chunk_strategy`), use `POST /documents/{document_id}/ingest`; to ingest the same source under a different path, upload a new copy of the file first.",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/documents",
+    httpMethod: "post",
+    pathParams: [],
+    queryParams: ["wait"],
     flags: [{
-      "name": "run_id",
-      "description": "Discussion run ID",
+      "name": "wait",
+      "description": "When omitted or `false` (default), processing runs in the background and `202 Accepted` is returned immediately with `status=pending`. Pass `true` to block until processing completes and receive `201 Created` with `status=ready`.",
+      "required": false,
+      "type": "boolean",
+      "in": "query"
+    }, {
+      "name": "file_id",
+      "description": "ID of the uploaded file. Must be one of application/pdf, text/plain, text/markdown.",
       "required": true,
       "type": "string",
-      "in": "path"
+      "in": "body"
+    }, {
+      "name": "project_id",
+      "description": "Project ID. Required for JWT auth; omit when using a project key.",
+      "required": false,
+      "type": "string",
+      "in": "body"
+    }, {
+      "name": "path_prefix",
+      "description": "Path prefix under which to store the document (e.g. /docs/). The filename is appended automatically.",
+      "required": false,
+      "type": "string",
+      "in": "body"
+    }, {
+      "name": "tags",
+      "description": "Key-value tags to attach to the document.",
+      "required": false,
+      "type": "object",
+      "in": "body"
+    }, {
+      "name": "chunk_strategy",
+      "description": "How to split the source into chunks. `page` (default) creates one chunk per non-empty page (PDF); for non-paged sources it yields a single chunk. `whole` joins everything into one chunk. `size` splits into fixed-size character windows with overlap.",
+      "required": false,
+      "type": "string",
+      "in": "body"
+    }, {
+      "name": "chunk_size",
+      "description": "Window size in characters when `chunk_strategy=size`. Defaults to 1000.",
+      "required": false,
+      "type": "integer",
+      "in": "body"
+    }, {
+      "name": "chunk_overlap",
+      "description": "Overlap in characters between consecutive windows when `chunk_strategy=size`. Defaults to 200.",
+      "required": false,
+      "type": "integer",
+      "in": "body"
     }]
   },
-  "get-discussion": {
-    serviceClass: "Discussions",
-    operationId: "getDiscussion",
-    description: "Returns a discussion config with its participants.",
-    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/discussions",
+  "get-document": {
+    serviceClass: "Documents",
+    operationId: "getDocument",
+    description: "Returns a document with its text content",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/documents",
     httpMethod: "get",
-    pathParams: ["discussion_id"],
+    pathParams: ["document_id"],
     queryParams: [],
     flags: [{
-      "name": "discussion_id",
-      "description": "Discussion ID",
+      "name": "document_id",
+      "description": "Document ID",
       "required": true,
       "type": "string",
       "in": "path"
     }]
   },
-  "update-discussion": {
-    serviceClass: "Discussions",
-    operationId: "updateDiscussion",
-    description: "Updates a discussion. Providing participants replaces the full set (not merged).",
-    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/discussions",
+  "update-document": {
+    serviceClass: "Documents",
+    operationId: "updateDocument",
+    description: "Updates document content, title, path, metadata, or tags. Supplying `path` moves the document to a new logical path within the project.",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/documents",
     httpMethod: "patch",
-    pathParams: ["discussion_id"],
+    pathParams: ["document_id"],
     queryParams: [],
     flags: [{
-      "name": "discussion_id",
-      "description": "Discussion ID",
+      "name": "document_id",
+      "description": "Document ID",
       "required": true,
       "type": "string",
       "in": "path"
     }, {
-      "name": "name",
-      "description": "",
-      "required": false,
-      "type": "string",
-      "in": "body"
-    }, {
-      "name": "description",
-      "description": "",
+      "name": "content",
+      "description": "New text content",
       "required": false,
       "type": "string",
       "in": "body"
     }, {
-      "name": "ai_provider_id",
-      "description": "Repins the default AI provider. An explicit `null` unpins the discussion onto the project's `default_model_route_id`, and returns `400` when the project has no default.",
+      "name": "title",
+      "description": "New title",
       "required": false,
       "type": "string",
       "in": "body"
     }, {
-      "name": "model",
-      "description": "",
+      "name": "path",
+      "description": "Logical path within the project (e.g. /reports/q1.txt). Pass null to clear.",
       "required": false,
       "type": "string",
       "in": "body"
     }, {
-      "name": "max_rounds",
-      "description": "",
-      "required": false,
-      "type": "integer",
-      "in": "body"
-    }, {
-      "name": "synthesis",
-      "description": "Override for the final synthesis pass that weighs the deliberation into a single outcome.",
+      "name": "metadata",
+      "description": "Arbitrary metadata object. Unlike other body fields, keys are stored and returned verbatim in the casing supplied — they are not converted between snake_case and camelCase.",
       "required": false,
       "type": "object",
       "in": "body"
     }, {
       "name": "tags",
-      "description": "",
+      "description": "Key-value tags",
       "required": false,
       "type": "object",
       "in": "body"
-    }, {
-      "name": "participants",
-      "description": "",
-      "required": false,
-      "type": "array",
-      "in": "body"
     }]
   },
-  "delete-discussion": {
-    serviceClass: "Discussions",
-    operationId: "deleteDiscussion",
-    description: "Deletes a discussion config and its participants.",
-    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/discussions",
+  "delete-document": {
+    serviceClass: "Documents",
+    operationId: "deleteDocument",
+    description: "Deletes a document and its underlying file",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/documents",
     httpMethod: "delete",
-    pathParams: ["discussion_id"],
+    pathParams: ["document_id"],
     queryParams: [],
     flags: [{
-      "name": "discussion_id",
-      "description": "Discussion ID",
+      "name": "document_id",
+      "description": "Document ID",
       "required": true,
       "type": "string",
       "in": "path"
     }]
   },
-  "list-discussion-runs": {
-    serviceClass: "Discussions",
-    operationId: "listDiscussionRuns",
-    description: "Returns the run history of a discussion, most recent first.",
-    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/discussions",
+  "get-document-status": {
+    serviceClass: "Documents",
+    operationId: "getDocumentStatus",
+    description: "Returns a lightweight ingestion status payload for polling — `status`, `chunk_count`, `total_pages`, and (when failed) `error`. Unlike `GET /documents/{document_id}`, it never returns the assembled chunk content, so it is cheap to poll on large documents. A document whose ingestion has stalled (no progress past the configured timeout) is transitioned to `failed` with `error=INGESTION_TIMEOUT` on read.",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/documents",
     httpMethod: "get",
-    pathParams: ["discussion_id"],
-    queryParams: ["limit", "offset"],
+    pathParams: ["document_id"],
+    queryParams: [],
+    flags: [{
+      "name": "document_id",
+      "description": "Document ID",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }]
+  },
+  "reingest-document": {
+    serviceClass: "Documents",
+    operationId: "reingestDocument",
+    description: "Re-runs ingestion for an existing document against its already-stored source file. Existing chunks are discarded and the document is reset to `status=pending` before re-processing. Use this to recover a document stuck in `processing`/`failed` or to re-chunk with a different strategy without re-uploading the file. Background by default (`202`); pass `?wait=true` to run synchronously (`201`).",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/documents",
+    httpMethod: "post",
+    pathParams: ["document_id"],
+    queryParams: ["wait"],
     flags: [{
-      "name": "discussion_id",
-      "description": "Discussion ID",
+      "name": "document_id",
+      "description": "Document ID",
       "required": true,
       "type": "string",
       "in": "path"
     }, {
-      "name": "limit",
-      "description": "",
+      "name": "wait",
+      "description": "When omitted or `false` (default), processing runs in the background and `202 Accepted` is returned immediately with `status=pending`. Pass `true` to block until processing completes and receive `201 Created` with `status=ready`.",
       "required": false,
-      "type": "integer",
+      "type": "boolean",
       "in": "query"
     }, {
-      "name": "offset",
-      "description": "",
+      "name": "chunk_strategy",
+      "description": "How to split the source into chunks. Defaults to `page`.",
+      "required": false,
+      "type": "string",
+      "in": "body"
+    }, {
+      "name": "chunk_size",
+      "description": "Window size in characters when `chunk_strategy=size`. Defaults to 1000.",
       "required": false,
       "type": "integer",
-      "in": "query"
+      "in": "body"
+    }, {
+      "name": "chunk_overlap",
+      "description": "Overlap in characters between consecutive windows when `chunk_strategy=size`. Defaults to 200.",
+      "required": false,
+      "type": "integer",
+      "in": "body"
     }]
   },
-  "create-discussion-run": {
-    serviceClass: "Discussions",
-    operationId: "createDiscussionRun",
-    description: "Runs the discussion synchronously over the given topic and returns the completed run, whose outcome inlines the synthesized text. The run's transcript is persisted as a conversation and the outcome as a document.",
-    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/discussions",
+  "complete-ingestion-callback": {
+    serviceClass: "Documents",
+    operationId: "completeIngestionCallback",
+    description: "Token-authed callback for a tool converter that deferred conversion by returning `{ \"status\": \"pending\" }` (see the Ingestion Rules module docs). Not IAM-gated — the external converter is not a SOAT principal, so it authenticates with the single-use token minted for this document and ingestion attempt (delivered as `callback.token` / embedded in `callback.url` in the original converter invocation). Accepted only while the document is still awaiting that exact attempt; rejected with `409` if the attempt already completed, timed out, or was superseded by a re-ingest.",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/documents",
     httpMethod: "post",
-    pathParams: ["discussion_id"],
-    queryParams: [],
+    pathParams: ["document_id"],
+    queryParams: ["token"],
     flags: [{
-      "name": "discussion_id",
-      "description": "Discussion ID",
+      "name": "document_id",
+      "description": "Document ID",
       "required": true,
       "type": "string",
       "in": "path"
     }, {
-      "name": "topic",
-      "description": "The question or subject the participants deliberate on.",
+      "name": "token",
+      "description": "Single-use signed token from the original `callback.token`",
       "required": true,
       "type": "string",
+      "in": "query"
+    }, {
+      "name": "text",
+      "description": "",
+      "required": false,
+      "type": "string",
+      "in": "body"
+    }, {
+      "name": "pages",
+      "description": "",
+      "required": false,
+      "type": "array",
       "in": "body"
     }]
   },
-  "list-documents": {
+  "get-document-tags": {
     serviceClass: "Documents",
-    operationId: "listDocuments",
-    description: "Returns all documents the caller has access to. If projectId is provided, returns only documents in that project. project keys are scoped to a single project automatically. JWT users without projectId receive documents across all their accessible projects.",
+    operationId: "getDocumentTags",
+    description: "Returns all tags attached to the document",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/documents",
+    httpMethod: "get",
+    pathParams: ["document_id"],
+    queryParams: [],
+    flags: [{
+      "name": "document_id",
+      "description": "Document ID",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }]
+  },
+  "replace-document-tags": {
+    serviceClass: "Documents",
+    operationId: "replaceDocumentTags",
+    description: "Replaces all tags on the document with the provided tags (not merged)",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/documents",
+    httpMethod: "put",
+    pathParams: ["document_id"],
+    queryParams: [],
+    flags: [{
+      "name": "document_id",
+      "description": "Document ID",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }]
+  },
+  "merge-document-tags": {
+    serviceClass: "Documents",
+    operationId: "mergeDocumentTags",
+    description: "Merges provided tags with existing tags (existing tags are preserved unless overridden)",
     moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/documents",
+    httpMethod: "patch",
+    pathParams: ["document_id"],
+    queryParams: [],
+    flags: [{
+      "name": "document_id",
+      "description": "Document ID",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }]
+  },
+  "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.",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/embeddings",
+    httpMethod: "post",
+    pathParams: [],
+    queryParams: [],
+    flags: [{
+      "name": "input",
+      "description": "Single text to embed.",
+      "required": false,
+      "type": "string",
+      "in": "body"
+    }, {
+      "name": "inputs",
+      "description": "Batch of texts to embed.",
+      "required": false,
+      "type": "array",
+      "in": "body"
+    }]
+  },
+  "list-datasets": {
+    serviceClass: "Evaluations",
+    operationId: "listDatasets",
+    description: "Returns the datasets defined in a project",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/evaluations",
     httpMethod: "get",
     pathParams: [],
     queryParams: ["project_id", "limit", "offset"],
     flags: [{
       "name": "project_id",
-      "description": "Project ID (optional)",
+      "description": "Project ID (required if not using project key auth)",
       "required": false,
       "type": "string",
       "in": "query"
@@ -2805,370 +2979,508 @@ var routes = {
       "in": "query"
     }]
   },
-  "create-document": {
-    serviceClass: "Documents",
-    operationId: "createDocument",
-    description: "Creates a new text document and generates an embedding vector for semantic search. project keys automatically infer the project from the key's scope; JWT callers must supply projectId.",
-    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/documents",
+  "create-dataset": {
+    serviceClass: "Evaluations",
+    operationId: "createDataset",
+    description: "Creates a project-scoped dataset — a named collection of test cases an eval runs an agent against. Names are unique per project. Datasets are operator-owned **fixtures**. The platform's content purge never deletes or mutates a dataset item, so erasing a generation cannot silently stop a test suite from being runnable.",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/evaluations",
     httpMethod: "post",
     pathParams: [],
     queryParams: [],
     flags: [{
       "name": "project_id",
-      "description": "Project ID. Required for JWT auth; omit when using an project key.",
+      "description": "Project ID (required if not using project key auth)",
       "required": false,
       "type": "string",
       "in": "body"
     }, {
-      "name": "content",
-      "description": "",
+      "name": "name",
+      "description": "Unique name within the project",
       "required": true,
       "type": "string",
       "in": "body"
     }, {
-      "name": "path",
-      "description": "Logical path within the project (e.g. /reports/q1.txt). Defaults to /filename if omitted.",
+      "name": "description",
+      "description": "What this suite covers",
       "required": false,
       "type": "string",
       "in": "body"
+    }]
+  },
+  "get-dataset": {
+    serviceClass: "Evaluations",
+    operationId: "getDataset",
+    description: "Returns a specific dataset",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/evaluations",
+    httpMethod: "get",
+    pathParams: ["dataset_id"],
+    queryParams: [],
+    flags: [{
+      "name": "dataset_id",
+      "description": "Dataset ID",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }]
+  },
+  "update-dataset": {
+    serviceClass: "Evaluations",
+    operationId: "updateDataset",
+    description: "Updates a dataset's name and/or description",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/evaluations",
+    httpMethod: "put",
+    pathParams: ["dataset_id"],
+    queryParams: [],
+    flags: [{
+      "name": "dataset_id",
+      "description": "Dataset ID",
+      "required": true,
+      "type": "string",
+      "in": "path"
     }, {
-      "name": "filename",
+      "name": "name",
       "description": "",
       "required": false,
       "type": "string",
       "in": "body"
     }, {
-      "name": "title",
-      "description": "Document title",
+      "name": "description",
+      "description": "",
+      "required": false,
+      "type": "string",
+      "in": "body"
+    }]
+  },
+  "delete-dataset": {
+    serviceClass: "Evaluations",
+    operationId: "deleteDataset",
+    description: "Deletes a dataset, its items, and every eval bound to it. Results of runs that already scored those items keep their frozen copies of the input and expected output.",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/evaluations",
+    httpMethod: "delete",
+    pathParams: ["dataset_id"],
+    queryParams: [],
+    flags: [{
+      "name": "dataset_id",
+      "description": "Dataset ID",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }]
+  },
+  "list-dataset-items": {
+    serviceClass: "Evaluations",
+    operationId: "listDatasetItems",
+    description: "Returns the test cases in a dataset, oldest first",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/evaluations",
+    httpMethod: "get",
+    pathParams: ["dataset_id"],
+    queryParams: ["limit", "offset"],
+    flags: [{
+      "name": "dataset_id",
+      "description": "Dataset ID",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }, {
+      "name": "limit",
+      "description": "Maximum number of results to return",
+      "required": false,
+      "type": "integer",
+      "in": "query"
+    }, {
+      "name": "offset",
+      "description": "Number of results to skip",
+      "required": false,
+      "type": "integer",
+      "in": "query"
+    }]
+  },
+  "create-dataset-item": {
+    serviceClass: "Evaluations",
+    operationId: "createDatasetItem",
+    description: "Adds one test case. `input` is replayed verbatim as the generation's messages, so it must be a non-empty array of `{ role, content }`.",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/evaluations",
+    httpMethod: "post",
+    pathParams: ["dataset_id"],
+    queryParams: [],
+    flags: [{
+      "name": "dataset_id",
+      "description": "Dataset ID",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }, {
+      "name": "input",
+      "description": "Messages replayed verbatim as the generation's input",
+      "required": true,
+      "type": "array",
+      "in": "body"
+    }, {
+      "name": "expected_output",
+      "description": "Reference answer for exact_match / llm_judge scorers",
       "required": false,
       "type": "string",
       "in": "body"
     }, {
       "name": "metadata",
-      "description": "Arbitrary metadata object. Unlike other body fields, keys are stored and returned verbatim in the casing supplied — they are not converted between snake_case and camelCase.",
+      "description": "Free-form tags, opaque to the platform",
       "required": false,
       "type": "object",
       "in": "body"
+    }]
+  },
+  "update-dataset-item": {
+    serviceClass: "Evaluations",
+    operationId: "updateDatasetItem",
+    description: "Updates a test case. Runs that already scored it are unaffected — each result carries its own frozen copy of the input and expected output.",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/evaluations",
+    httpMethod: "put",
+    pathParams: ["dataset_id", "item_id"],
+    queryParams: [],
+    flags: [{
+      "name": "dataset_id",
+      "description": "Dataset ID",
+      "required": true,
+      "type": "string",
+      "in": "path"
     }, {
-      "name": "tags",
-      "description": "Key-value tags",
+      "name": "item_id",
+      "description": "Dataset item ID",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }, {
+      "name": "input",
+      "description": "Messages replayed verbatim as the generation's input",
+      "required": false,
+      "type": "array",
+      "in": "body"
+    }, {
+      "name": "expected_output",
+      "description": "",
+      "required": false,
+      "type": "string",
+      "in": "body"
+    }, {
+      "name": "metadata",
+      "description": "",
       "required": false,
       "type": "object",
       "in": "body"
+    }]
+  },
+  "delete-dataset-item": {
+    serviceClass: "Evaluations",
+    operationId: "deleteDatasetItem",
+    description: "Deletes a test case. Results of runs that already scored it stay readable; their `dataset_item_id` becomes null.",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/evaluations",
+    httpMethod: "delete",
+    pathParams: ["dataset_id", "item_id"],
+    queryParams: [],
+    flags: [{
+      "name": "dataset_id",
+      "description": "Dataset ID",
+      "required": true,
+      "type": "string",
+      "in": "path"
     }, {
-      "name": "chunk_strategy",
-      "description": "How to split the content into embeddable chunks. `whole` (default) stores the content as a single chunk; `size` splits into fixed-size character windows with overlap. `page` is equivalent to `whole` for plain text.",
+      "name": "item_id",
+      "description": "Dataset item ID",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }]
+  },
+  "list-evals": {
+    serviceClass: "Evaluations",
+    operationId: "listEvals",
+    description: "Returns the evals defined in a project",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/evaluations",
+    httpMethod: "get",
+    pathParams: [],
+    queryParams: ["project_id", "limit", "offset"],
+    flags: [{
+      "name": "project_id",
+      "description": "Project ID (required if not using project key auth)",
       "required": false,
       "type": "string",
-      "in": "body"
+      "in": "query"
     }, {
-      "name": "chunk_size",
-      "description": "Window size in characters when `chunk_strategy=size`. Defaults to 1000.",
+      "name": "limit",
+      "description": "Maximum number of results to return",
       "required": false,
       "type": "integer",
-      "in": "body"
+      "in": "query"
     }, {
-      "name": "chunk_overlap",
-      "description": "Overlap in characters between consecutive windows when `chunk_strategy=size`. Defaults to 200.",
+      "name": "offset",
+      "description": "Number of results to skip",
       "required": false,
       "type": "integer",
-      "in": "body"
+      "in": "query"
     }]
   },
-  "ingest-document": {
-    serviceClass: "Documents",
-    operationId: "ingestDocument",
-    description: "Parses an already-uploaded file and creates one Document split into one or more embedded chunks. The source format is detected from the file's content type: PDFs are parsed page-by-page; `text/plain` and `text/markdown` files are read as a single source. How the source is chunked is controlled by `chunk_strategy`. A file can only back one Document — a second call with the same `file_id` returns `409 FILE_ALREADY_INGESTED`. To re-process an already-ingested file (e.g. with a different `chunk_strategy`), use `POST /documents/{document_id}/ingest`; to ingest the same source under a different path, upload a new copy of the file first.",
-    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/documents",
+  "create-eval": {
+    serviceClass: "Evaluations",
+    operationId: "createEval",
+    description: "Binds an agent under test to a dataset and a list of scorers. The agent and the dataset must belong to the same project as the eval; a cross-project reference is rejected with 400. Scorer config is frozen here rather than read from the agent at run time, so two runs of the same eval are always judged by the same criteria and their comparison measures the agent instead of the config drifting underneath it. Each scorer `type` may appear at most once.",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/evaluations",
     httpMethod: "post",
     pathParams: [],
-    queryParams: ["async"],
+    queryParams: [],
     flags: [{
-      "name": "async",
-      "description": "When omitted or `true` (default), processing runs in the background and `202 Accepted` is returned immediately with `status=pending`. Pass `false` to run synchronously and receive `201 Created` with `status=ready`.",
-      "required": false,
-      "type": "boolean",
-      "in": "query"
-    }, {
-      "name": "file_id",
-      "description": "ID of the uploaded file. Must be one of application/pdf, text/plain, text/markdown.",
-      "required": true,
-      "type": "string",
-      "in": "body"
-    }, {
       "name": "project_id",
-      "description": "Project ID. Required for JWT auth; omit when using a project key.",
+      "description": "Project ID (required if not using project key auth)",
       "required": false,
       "type": "string",
       "in": "body"
     }, {
-      "name": "path_prefix",
-      "description": "Path prefix under which to store the document (e.g. /docs/). The filename is appended automatically.",
-      "required": false,
+      "name": "name",
+      "description": "Unique name within the project",
+      "required": true,
       "type": "string",
       "in": "body"
     }, {
-      "name": "tags",
-      "description": "Key-value tags to attach to the document.",
-      "required": false,
-      "type": "object",
+      "name": "agent_id",
+      "description": "The agent under test",
+      "required": true,
+      "type": "string",
       "in": "body"
     }, {
-      "name": "chunk_strategy",
-      "description": "How to split the source into chunks. `page` (default) creates one chunk per non-empty page (PDF); for non-paged sources it yields a single chunk. `whole` joins everything into one chunk. `size` splits into fixed-size character windows with overlap.",
-      "required": false,
+      "name": "dataset_id",
+      "description": "The dataset to run it against",
+      "required": true,
       "type": "string",
       "in": "body"
     }, {
-      "name": "chunk_size",
-      "description": "Window size in characters when `chunk_strategy=size`. Defaults to 1000.",
-      "required": false,
-      "type": "integer",
+      "name": "scorers",
+      "description": "Scorer configs, a discriminated union on `type`. Each type may appear at most once. Every scorer produces `{ score: 0–1, passed: boolean }`; binary scorers emit 0 or 1.\n\n`exact_match` compares the trimmed output text to `expected_output`. `contains` looks for `value` in the output text. `json_logic` evaluates `expression` over `{ input, output, object, expected, item.metadata }`, where `object` is the structured output (absent when the agent has no `output_schema`). `output_schema` validates the structured output against the scorer's own `schema`, falling back to the agent's; it requires the agent to carry an `output_schema`, because without one the platform emits no structured output and every item would score 0.\n\n`llm_judge` grades the output with a model completion, returning a continuous score plus its `reasoning`. Its `pass_threshold` is required: a continuous score says nothing about where \"good enough\" is, and a defaulted cutoff would silently decide the gate.",
+      "required": true,
+      "type": "array",
       "in": "body"
     }, {
-      "name": "chunk_overlap",
-      "description": "Overlap in characters between consecutive windows when `chunk_strategy=size`. Defaults to 200.",
+      "name": "pass_threshold",
+      "description": "0–1. The run passes iff its pass rate — passed items over non-errored items — is at least this. Null reports scores without gating on them.",
       "required": false,
-      "type": "integer",
+      "type": "number",
       "in": "body"
     }]
   },
-  "get-document": {
-    serviceClass: "Documents",
-    operationId: "getDocument",
-    description: "Returns a document with its text content",
-    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/documents",
+  "get-eval": {
+    serviceClass: "Evaluations",
+    operationId: "getEval",
+    description: "Returns a specific eval",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/evaluations",
     httpMethod: "get",
-    pathParams: ["document_id"],
+    pathParams: ["eval_id"],
     queryParams: [],
     flags: [{
-      "name": "document_id",
-      "description": "Document ID",
+      "name": "eval_id",
+      "description": "Eval ID",
       "required": true,
       "type": "string",
       "in": "path"
     }]
   },
-  "update-document": {
-    serviceClass: "Documents",
-    operationId: "updateDocument",
-    description: "Updates document content, title, path, metadata, or tags. Supplying `path` moves the document to a new logical path within the project.",
-    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/documents",
-    httpMethod: "patch",
-    pathParams: ["document_id"],
+  "update-eval": {
+    serviceClass: "Evaluations",
+    operationId: "updateEval",
+    description: "Updates an eval. Changing `agent_id` re-validates the scorers against the new agent, since an `output_schema` scorer that was legal against the old one may not be.",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/evaluations",
+    httpMethod: "put",
+    pathParams: ["eval_id"],
     queryParams: [],
     flags: [{
-      "name": "document_id",
-      "description": "Document ID",
+      "name": "eval_id",
+      "description": "Eval ID",
       "required": true,
       "type": "string",
       "in": "path"
     }, {
-      "name": "content",
-      "description": "New text content",
+      "name": "name",
+      "description": "",
       "required": false,
       "type": "string",
       "in": "body"
     }, {
-      "name": "title",
-      "description": "New title",
+      "name": "agent_id",
+      "description": "",
       "required": false,
       "type": "string",
       "in": "body"
     }, {
-      "name": "path",
-      "description": "Logical path within the project (e.g. /reports/q1.txt). Pass null to clear.",
+      "name": "dataset_id",
+      "description": "",
       "required": false,
       "type": "string",
       "in": "body"
     }, {
-      "name": "metadata",
-      "description": "Arbitrary metadata object. Unlike other body fields, keys are stored and returned verbatim in the casing supplied — they are not converted between snake_case and camelCase.",
+      "name": "scorers",
+      "description": "Scorer configs, a discriminated union on `type`. Each type may appear at most once. Every scorer produces `{ score: 0–1, passed: boolean }`; binary scorers emit 0 or 1.\n\n`exact_match` compares the trimmed output text to `expected_output`. `contains` looks for `value` in the output text. `json_logic` evaluates `expression` over `{ input, output, object, expected, item.metadata }`, where `object` is the structured output (absent when the agent has no `output_schema`). `output_schema` validates the structured output against the scorer's own `schema`, falling back to the agent's; it requires the agent to carry an `output_schema`, because without one the platform emits no structured output and every item would score 0.\n\n`llm_judge` grades the output with a model completion, returning a continuous score plus its `reasoning`. Its `pass_threshold` is required: a continuous score says nothing about where \"good enough\" is, and a defaulted cutoff would silently decide the gate.",
       "required": false,
-      "type": "object",
+      "type": "array",
       "in": "body"
     }, {
-      "name": "tags",
-      "description": "Key-value tags",
+      "name": "pass_threshold",
+      "description": "",
       "required": false,
-      "type": "object",
+      "type": "number",
       "in": "body"
     }]
   },
-  "delete-document": {
-    serviceClass: "Documents",
-    operationId: "deleteDocument",
-    description: "Deletes a document and its underlying file",
-    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/documents",
+  "delete-eval": {
+    serviceClass: "Evaluations",
+    operationId: "deleteEval",
+    description: "Deletes an eval, its runs, and their results",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/evaluations",
     httpMethod: "delete",
-    pathParams: ["document_id"],
+    pathParams: ["eval_id"],
     queryParams: [],
     flags: [{
-      "name": "document_id",
-      "description": "Document ID",
+      "name": "eval_id",
+      "description": "Eval ID",
       "required": true,
       "type": "string",
       "in": "path"
     }]
   },
-  "get-document-status": {
-    serviceClass: "Documents",
-    operationId: "getDocumentStatus",
-    description: "Returns a lightweight ingestion status payload for polling — `status`, `chunk_count`, `total_pages`, and (when failed) `error`. Unlike `GET /documents/{document_id}`, it never returns the assembled chunk content, so it is cheap to poll on large documents. A document whose ingestion has stalled (no progress past the configured timeout) is transitioned to `failed` with `error=INGESTION_TIMEOUT` on read.",
-    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/documents",
+  "list-eval-runs": {
+    serviceClass: "Evaluations",
+    operationId: "listEvalRuns",
+    description: "Returns an eval's runs, newest first",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/evaluations",
     httpMethod: "get",
-    pathParams: ["document_id"],
-    queryParams: [],
+    pathParams: ["eval_id"],
+    queryParams: ["limit", "offset"],
     flags: [{
-      "name": "document_id",
-      "description": "Document ID",
+      "name": "eval_id",
+      "description": "Eval ID",
       "required": true,
       "type": "string",
       "in": "path"
+    }, {
+      "name": "limit",
+      "description": "Maximum number of results to return",
+      "required": false,
+      "type": "integer",
+      "in": "query"
+    }, {
+      "name": "offset",
+      "description": "Number of results to skip",
+      "required": false,
+      "type": "integer",
+      "in": "query"
     }]
   },
-  "reingest-document": {
-    serviceClass: "Documents",
-    operationId: "reingestDocument",
-    description: "Re-runs ingestion for an existing document against its already-stored source file. Existing chunks are discarded and the document is reset to `status=pending` before re-processing. Use this to recover a document stuck in `processing`/`failed` or to re-chunk with a different strategy without re-uploading the file. Async by default (`202`); pass `?async=false` to run synchronously (`201`).",
-    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/documents",
+  "start-eval-run": {
+    serviceClass: "Evaluations",
+    operationId: "startEvalRun",
+    description: "Runs the eval against its dataset, creating one real agent generation per item and scoring the outputs. `wait: true` executes the run synchronously and returns it terminal, with its scores. The dataset is capped at 25 items for a synchronous run; a larger one is rejected with 400 rather than partially scored. `wait: false` (the default) enqueues one task per item and returns immediately with `status: \"queued\"`. A worker executes the items and the run settles itself; poll `GET /evals/{eval_id}/runs/{eval_run_id}` for the terminal status, or subscribe to the `eval_run.completed` webhook. There is no item cap on a queued run. The whole run is pinned to **one** agent version, stamped on `agent_version`: pass one explicitly to evaluate a canary before promoting it, or omit it to use the active release's stable version (or the live draft when no release is in effect). Without the pin, release assignment would bucket each item independently and blend two configs into a single score. With `baseline_run_id`, the finished run's `aggregate_scores.baseline` carries per-scorer deltas against that run, computed over the items present and scorable in **both** runs, with the divergence counted. A delta over a shifted dataset is therefore never presented as a clean comparison.",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/evaluations",
     httpMethod: "post",
-    pathParams: ["document_id"],
-    queryParams: ["async"],
+    pathParams: ["eval_id"],
+    queryParams: [],
     flags: [{
-      "name": "document_id",
-      "description": "Document ID",
+      "name": "eval_id",
+      "description": "Eval ID",
       "required": true,
       "type": "string",
       "in": "path"
     }, {
-      "name": "async",
-      "description": "When omitted or `true` (default), processing runs in the background and `202 Accepted` is returned immediately with `status=pending`. Pass `false` to run synchronously and receive `201 Created` with `status=ready`.",
+      "name": "wait",
+      "description": "True runs the eval synchronously (25-item cap) and returns a terminal run with its scores. False — the default — enqueues the items and returns a `queued` run immediately.",
       "required": false,
       "type": "boolean",
-      "in": "query"
-    }, {
-      "name": "chunk_strategy",
-      "description": "How to split the source into chunks. Defaults to `page`.",
-      "required": false,
-      "type": "string",
       "in": "body"
     }, {
-      "name": "chunk_size",
-      "description": "Window size in characters when `chunk_strategy=size`. Defaults to 1000.",
+      "name": "agent_version",
+      "description": "An archived agent version to evaluate. Defaults to the active release's stable version, or the live draft version when no release is in effect.",
       "required": false,
       "type": "integer",
       "in": "body"
     }, {
-      "name": "chunk_overlap",
-      "description": "Overlap in characters between consecutive windows when `chunk_strategy=size`. Defaults to 200.",
+      "name": "baseline_run_id",
+      "description": "A terminal run of the same eval to compare against. The finished run's `aggregate_scores.baseline` reports per-scorer deltas over the item intersection. A run of a different eval is rejected with 400.",
       "required": false,
-      "type": "integer",
+      "type": "string",
       "in": "body"
     }]
   },
-  "complete-ingestion-callback": {
-    serviceClass: "Documents",
-    operationId: "completeIngestionCallback",
-    description: "Token-authed callback for a tool converter that deferred conversion by returning `{ \"status\": \"pending\" }` (see the Ingestion Rules module docs). Not IAM-gated — the external converter is not a SOAT principal, so it authenticates with the single-use token minted for this document and ingestion attempt (delivered as `callback.token` / embedded in `callback.url` in the original converter invocation). Accepted only while the document is still awaiting that exact attempt; rejected with `409` if the attempt already completed, timed out, or was superseded by a re-ingest.",
-    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/documents",
-    httpMethod: "post",
-    pathParams: ["document_id"],
-    queryParams: ["token"],
+  "get-eval-run": {
+    serviceClass: "Evaluations",
+    operationId: "getEvalRun",
+    description: "Returns a run's status, counts, and aggregate scores",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/evaluations",
+    httpMethod: "get",
+    pathParams: ["eval_id", "eval_run_id"],
+    queryParams: [],
     flags: [{
-      "name": "document_id",
-      "description": "Document ID",
+      "name": "eval_id",
+      "description": "Eval ID",
       "required": true,
       "type": "string",
       "in": "path"
     }, {
-      "name": "token",
-      "description": "Single-use signed token from the original `callback.token`",
+      "name": "eval_run_id",
+      "description": "Eval run ID",
       "required": true,
       "type": "string",
-      "in": "query"
-    }, {
-      "name": "text",
-      "description": "",
-      "required": false,
-      "type": "string",
-      "in": "body"
-    }, {
-      "name": "pages",
-      "description": "",
-      "required": false,
-      "type": "array",
-      "in": "body"
+      "in": "path"
     }]
   },
-  "get-document-tags": {
-    serviceClass: "Documents",
-    operationId: "getDocumentTags",
-    description: "Returns all tags attached to the document",
-    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/documents",
+  "list-eval-results": {
+    serviceClass: "Evaluations",
+    operationId: "listEvalResults",
+    description: "Returns the per-item results of a run, oldest first",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/evaluations",
     httpMethod: "get",
-    pathParams: ["document_id"],
-    queryParams: [],
+    pathParams: ["eval_id", "eval_run_id"],
+    queryParams: ["limit", "offset"],
     flags: [{
-      "name": "document_id",
-      "description": "Document ID",
+      "name": "eval_id",
+      "description": "Eval ID",
       "required": true,
       "type": "string",
       "in": "path"
-    }]
-  },
-  "replace-document-tags": {
-    serviceClass: "Documents",
-    operationId: "replaceDocumentTags",
-    description: "Replaces all tags on the document with the provided tags (not merged)",
-    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/documents",
-    httpMethod: "put",
-    pathParams: ["document_id"],
-    queryParams: [],
-    flags: [{
-      "name": "document_id",
-      "description": "Document ID",
+    }, {
+      "name": "eval_run_id",
+      "description": "Eval run ID",
       "required": true,
       "type": "string",
       "in": "path"
+    }, {
+      "name": "limit",
+      "description": "Maximum number of results to return",
+      "required": false,
+      "type": "integer",
+      "in": "query"
+    }, {
+      "name": "offset",
+      "description": "Number of results to skip",
+      "required": false,
+      "type": "integer",
+      "in": "query"
     }]
   },
-  "merge-document-tags": {
-    serviceClass: "Documents",
-    operationId: "mergeDocumentTags",
-    description: "Merges provided tags with existing tags (existing tags are preserved unless overridden)",
-    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/documents",
-    httpMethod: "patch",
-    pathParams: ["document_id"],
+  "cancel-eval-run": {
+    serviceClass: "Evaluations",
+    operationId: "cancelEvalRun",
+    description: "Cancels a queued or running run: its outstanding item tasks are dropped so it stops consuming provider budget, and the run settles as `canceled`. Results already written are kept — they are real measurements of generations that were really paid for — and `completed_count` / `errored_count` report what ran. `aggregate_scores` is deliberately left null: a partial roll-up in the same field a completed run uses would read as a whole-dataset verdict. A run that has already finished is rejected with 400.",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/evaluations",
+    httpMethod: "post",
+    pathParams: ["eval_id", "eval_run_id"],
     queryParams: [],
     flags: [{
-      "name": "document_id",
-      "description": "Document ID",
+      "name": "eval_id",
+      "description": "Eval ID",
       "required": true,
       "type": "string",
       "in": "path"
-    }]
-  },
-  "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.",
-    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/embeddings",
-    httpMethod: "post",
-    pathParams: [],
-    queryParams: [],
-    flags: [{
-      "name": "input",
-      "description": "Single text to embed.",
-      "required": false,
-      "type": "string",
-      "in": "body"
     }, {
-      "name": "inputs",
-      "description": "Batch of texts to embed.",
-      "required": false,
-      "type": "array",
-      "in": "body"
+      "name": "eval_run_id",
+      "description": "Eval run ID",
+      "required": true,
+      "type": "string",
+      "in": "path"
     }]
   },
   "list-exceptions": {
@@ -6128,11 +6440,11 @@ var routes = {
   "generate-session-response": {
     serviceClass: "Sessions",
     operationId: "generateSessionResponse",
-    description: "Triggers the agent to generate a response based on the current conversation. Returns the assistant reply or a requires_action status if the agent needs client tool outputs. Pass ?async=true for a 202 accepted response when you do not need to wait for the result.",
+    description: "Triggers the agent to generate a response based on the current conversation. Background by default: returns `202 Accepted` immediately while the generation runs. Pass ?wait=true to block and receive the assistant reply (or a requires_action status if the agent needs client tool outputs) in the response.",
     moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/sessions",
     httpMethod: "post",
     pathParams: ["session_id"],
-    queryParams: ["async"],
+    queryParams: ["wait"],
     flags: [{
       "name": "session_id",
       "description": "Session public ID",
@@ -6140,8 +6452,8 @@ var routes = {
       "type": "string",
       "in": "path"
     }, {
-      "name": "async",
-      "description": "When true, generation runs in the background and 202 is returned immediately",
+      "name": "wait",
+      "description": "When omitted or `false` (default), generation runs in the background and `202 Accepted` is returned immediately. Pass `true` to block until the generation settles and receive the result.",
       "required": false,
       "type": "boolean",
       "in": "query"
@@ -7034,7 +7346,7 @@ var routes = {
   "fire-trigger": {
     serviceClass: "Triggers",
     operationId: "fireTrigger",
-    description: "Fires a trigger synchronously and returns the terminal firing record.",
+    description: "Fires a trigger synchronously and returns the terminal firing record. The firing itself always settles here; an `eval` target's run is queued rather than executed inline, so the record names a `queued` run to poll.",
     moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/triggers",
     httpMethod: "post",
     pathParams: ["trigger_id"],
@@ -7047,7 +7359,7 @@ var routes = {
       "in": "path"
     }, {
       "name": "input",
-      "description": "Fire-time input, shallow-merged over the trigger's static input",
+      "description": "Fire-time input, shallow-merged over the trigger's static input. For `eval` targets it may carry `agent_version` and `baseline_run_id`.",
       "required": false,
       "type": "object",
       "in": "body"