@soat/cli 0.5.4 → 0.5.6

package/dist/esm/index.js

@@ -8,20 +8,21 @@ var __name = (target, value) => __defProp(target, "name", {
 // src/index.ts
 import { createHmac, timingSafeEqual } from "crypto";
 import { createServer } from "http";
-import input from "@inquirer/input";
-import password from "@inquirer/password";
+import * as nodePath from "path";
+import { fileURLToPath } from "url";
 import * as sdk from "@soat/sdk";
 import { program } from "commander";
 
 // package.json
 var package_default = {
   name: "@soat/cli",
-  version: "0.5.4",
+  version: "0.5.6",
   type: "module",
   scripts: {
     generate: "tsx scripts/generate.ts",
-    lint: "eslint src",
-    typecheck: "tsc --noEmit",
+    lint: "eslint src tests",
+    test: "jest --config tests/unit/jest.config.ts --coverage=false",
+    typecheck: "tsc --noEmit && tsc --noEmit -p tests/tsconfig.json",
     build: "pnpm generate && tsup"
   },
   dependencies: {
@@ -29,15 +30,16 @@ var package_default = {
     "@inquirer/password": "^5.0.12",
     "@soat/sdk": "workspace:*",
     "@ttoss/logger": "^0.8.10",
-    commander: "^14.0.3"
+    commander: "^14.0.3",
+    "js-yaml": "^4.1.1"
   },
   devDependencies: {
     "@ttoss/config": "^1.37.10",
+    "@ttoss/test-utils": "^4.2.10",
     "@types/jest": "^30.0.0",
     "@types/js-yaml": "^4.0.9",
     "@types/node": "^24",
     jest: "^30.3.0",
-    "js-yaml": "^4.1.1",
     tsup: "^8.5.1",
     tsx: "^4.21.0"
   },
@@ -55,15 +57,268 @@ var package_default = {
   }
 };
 
-// src/config.ts
+// src/cli-wrappers/wrappers/agentFormations.ts
 import * as fs from "fs";
+import yaml from "js-yaml";
+var FORMATION_COMMANDS = ["validate-agent-formation", "plan-agent-formation", "create-agent-formation", "update-agent-formation"];
+var TEMPLATE_PATH_FLAG = "template-path";
+var TEMPLATE_FILE_FLAG = "template-file";
+var ENV_FILE_FLAG = "env-file";
+var PARAMETER_FLAG = "parameter";
+var TEMPLATE_FIELD = "template";
+var PARAMETERS_FIELD = "parameters";
+var parseEnvFile = /* @__PURE__ */__name(args => {
+  const {
+    envPath
+  } = args;
+  let content;
+  try {
+    content = fs.readFileSync(envPath, "utf8");
+  } catch {
+    throw new Error(`Unable to read env file: ${envPath}`);
+  }
+  const vars = {};
+  for (const rawLine of content.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith("#")) continue;
+    const withoutExport = line.startsWith("export ") ? line.slice("export ".length).trim() : line;
+    const eqIdx = withoutExport.indexOf("=");
+    if (eqIdx <= 0) continue;
+    const key = withoutExport.slice(0, eqIdx).trim();
+    let value = withoutExport.slice(eqIdx + 1).trim();
+    if (value.startsWith('"') && value.endsWith('"') || value.startsWith("'") && value.endsWith("'")) {
+      value = value.slice(1, -1);
+    }
+    vars[key] = value;
+  }
+  return vars;
+}, "parseEnvFile");
+var readTemplateFromPath = /* @__PURE__ */__name(args => {
+  const {
+    templatePath
+  } = args;
+  let content;
+  try {
+    content = fs.readFileSync(templatePath, "utf8");
+  } catch {
+    throw new Error(`Unable to read template file: ${templatePath}`);
+  }
+  const trimmed = content.trim();
+  if (!trimmed) {
+    throw new Error(`Template file is empty: ${templatePath}`);
+  }
+  try {
+    return JSON.parse(trimmed);
+  } catch {}
+  try {
+    return yaml.load(trimmed);
+  } catch {
+    throw new Error(`Template file must contain valid JSON or YAML: ${templatePath}`);
+  }
+}, "readTemplateFromPath");
+var resolveEnvRef = /* @__PURE__ */__name(args => {
+  const {
+    value,
+    env
+  } = args;
+  const simple = /^\$([A-Za-z_][A-Za-z0-9_]*)$/.exec(value);
+  if (simple) {
+    const resolved = env[simple[1]];
+    if (resolved === void 0) {
+      throw new Error(`Missing environment variable: ${simple[1]}`);
+    }
+    return resolved;
+  }
+  const bracketed = /^\$\{([A-Za-z_][A-Za-z0-9_]*)\}$/.exec(value);
+  if (bracketed) {
+    const resolved = env[bracketed[1]];
+    if (resolved === void 0) {
+      throw new Error(`Missing environment variable: ${bracketed[1]}`);
+    }
+    return resolved;
+  }
+  return value;
+}, "resolveEnvRef");
+var agentFormationsWrapper = {
+  id: "agent-formations-wrapper",
+  commands: FORMATION_COMMANDS,
+  helpFlags: [{
+    name: "template-path",
+    description: "Path to template file (JSON or YAML). Alias: --template-file",
+    required: false,
+    type: "string"
+  }, {
+    name: "parameter",
+    description: "Template parameter in key=value format (repeatable). Values may reference env vars ($VAR)",
+    required: false,
+    type: "string"
+  }, {
+    name: "env-file",
+    description: "Path to .env file for parameter variable substitution",
+    required: false,
+    type: "string"
+  }],
+  // eslint-disable-next-line complexity
+  apply: /* @__PURE__ */__name(({
+    context
+  }) => {
+    const forcedBody = {};
+    const flags = {
+      single: {
+        ...context.parsedFlags.single
+      },
+      repeated: {
+        ...context.parsedFlags.repeated
+      }
+    };
+    const templatePath = flags.single[TEMPLATE_PATH_FLAG];
+    const templateFile = flags.single[TEMPLATE_FILE_FLAG];
+    const templateInline = flags.single[TEMPLATE_FIELD];
+    const parametersInline = flags.single[PARAMETERS_FIELD];
+    const parameterValues = flags.repeated[PARAMETER_FLAG] ?? [];
+    const envFile = flags.single[ENV_FILE_FLAG];
+    if (templatePath && templateFile) {
+      throw new Error(`Use either --${TEMPLATE_PATH_FLAG} or --${TEMPLATE_FILE_FLAG}, not both.`);
+    }
+    const effectiveTemplatePath = templatePath ?? templateFile;
+    if (templateInline && effectiveTemplatePath) {
+      throw new Error(`Use either --${TEMPLATE_FIELD} or --${TEMPLATE_PATH_FLAG}, not both.`);
+    }
+    if (parametersInline && parameterValues.length > 0) {
+      throw new Error(`Use either --${PARAMETERS_FIELD} or repeatable --${PARAMETER_FLAG}, not both.`);
+    }
+    let envFileVars = {};
+    if (envFile) {
+      envFileVars = parseEnvFile({
+        envPath: envFile
+      });
+    }
+    const mergedEnv = {
+      ...envFileVars,
+      ...process.env
+    };
+    if (effectiveTemplatePath) {
+      forcedBody[TEMPLATE_FIELD] = readTemplateFromPath({
+        templatePath: effectiveTemplatePath
+      });
+    }
+    if (parameterValues.length > 0) {
+      const resolvedParameters = {};
+      for (const pair of parameterValues) {
+        const eqIdx = pair.indexOf("=");
+        if (eqIdx <= 0) {
+          throw new Error(`Invalid --${PARAMETER_FLAG} value "${pair}". Expected key=value.`);
+        }
+        const key = pair.slice(0, eqIdx).trim();
+        const rawValue = pair.slice(eqIdx + 1);
+        if (!key) {
+          throw new Error(`Invalid --${PARAMETER_FLAG} value "${pair}". Parameter key cannot be empty.`);
+        }
+        resolvedParameters[key] = resolveEnvRef({
+          value: rawValue,
+          env: mergedEnv
+        });
+      }
+      forcedBody[PARAMETERS_FIELD] = resolvedParameters;
+    }
+    delete flags.single[TEMPLATE_PATH_FLAG];
+    delete flags.single[TEMPLATE_FILE_FLAG];
+    delete flags.single[ENV_FILE_FLAG];
+    delete flags.single[PARAMETER_FLAG];
+    delete flags.repeated[PARAMETER_FLAG];
+    return {
+      flags,
+      forcedBody
+    };
+  }, "apply")
+};
+
+// src/cli-wrappers/flagParser.ts
+var parseUnknownWithRepeats = /* @__PURE__ */__name(args => {
+  const {
+    cliArgs
+  } = args;
+  const single = {};
+  const repeated = {};
+  for (let i = 0; i < cliArgs.length; i++) {
+    const arg = cliArgs[i];
+    if (!arg?.startsWith("--")) continue;
+    const inlineSplitIdx = arg.indexOf("=");
+    const hasInlineValue = inlineSplitIdx > 2;
+    const key = hasInlineValue ? arg.slice(2, inlineSplitIdx) : arg.slice(2);
+    let value;
+    if (hasInlineValue) {
+      value = arg.slice(inlineSplitIdx + 1);
+    } else {
+      const next = cliArgs[i + 1];
+      if (next !== void 0 && !next.startsWith("--")) {
+        value = next;
+        i++;
+      } else {
+        value = "true";
+      }
+    }
+    single[key] = value;
+    if (!repeated[key]) {
+      repeated[key] = [];
+    }
+    repeated[key].push(value);
+  }
+  return {
+    single,
+    repeated
+  };
+}, "parseUnknownWithRepeats");
+
+// src/cli-wrappers/index.ts
+var WRAPPERS = [agentFormationsWrapper];
+var resolveWrapperForCommand = /* @__PURE__ */__name(args => {
+  const {
+    commandName
+  } = args;
+  return WRAPPERS.find(wrapper => {
+    return wrapper.commands.includes(commandName);
+  });
+}, "resolveWrapperForCommand");
+var applyWrapperForCommand = /* @__PURE__ */__name(args => {
+  const {
+    commandName,
+    route,
+    parsedFlags
+  } = args;
+  const wrapper = resolveWrapperForCommand({
+    commandName
+  });
+  if (!wrapper) {
+    return {
+      flags: parsedFlags,
+      forcedBody: {}
+    };
+  }
+  return wrapper.apply({
+    context: {
+      commandName,
+      route,
+      parsedFlags
+    }
+  });
+}, "applyWrapperForCommand");
+var getWrapperHelpFlags = /* @__PURE__ */__name(commandName => {
+  const wrapper = WRAPPERS.find(w => {
+    return w.commands.includes(commandName);
+  });
+  return wrapper?.helpFlags ?? [];
+}, "getWrapperHelpFlags");
+
+// src/config.ts
+import * as fs2 from "fs";
 import * as os from "os";
 import * as path from "path";
 import { createClient, createConfig } from "@soat/sdk";
 var CONFIG_FILE = path.join(os.homedir(), ".soat", "config.json");
 var readConfig = /* @__PURE__ */__name(() => {
   try {
-    return JSON.parse(fs.readFileSync(CONFIG_FILE, "utf8"));
+    return JSON.parse(fs2.readFileSync(CONFIG_FILE, "utf8"));
   } catch {
     return {};
   }
@@ -71,10 +326,10 @@ var readConfig = /* @__PURE__ */__name(() => {
 var writeProfile = /* @__PURE__ */__name((name, profile) => {
   const config = readConfig();
   config[name] = profile;
-  fs.mkdirSync(path.dirname(CONFIG_FILE), {
+  fs2.mkdirSync(path.dirname(CONFIG_FILE), {
     recursive: true
   });
-  fs.writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2));
+  fs2.writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2));
 }, "writeProfile");
 var resolveClient = /* @__PURE__ */__name(profileName => {
   const envBaseUrl = process.env["SOAT_BASE_URL"];
@@ -112,940 +367,2870 @@ var routes = {
   "list-actors": {
     serviceClass: "Actors",
     operationId: "listActors",
-    description: "List actors",
+    description: "Returns all actors the caller has access to. If projectId is provided, returns only actors in that project. project keys are scoped to a single project automatically. JWT users without projectId receive actors across all their accessible projects.",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/actors",
     pathParams: [],
-    queryParams: ["project_id", "external_id", "limit", "offset"]
+    queryParams: ["project_id", "external_id", "limit", "offset"],
+    flags: [{
+      "name": "project_id",
+      "description": "Project ID (optional)",
+      "required": false,
+      "type": "string",
+      "in": "query"
+    }, {
+      "name": "external_id",
+      "description": "External ID to filter by (e.g. WhatsApp phone number)",
+      "required": false,
+      "type": "string",
+      "in": "query"
+    }, {
+      "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-actor": {
     serviceClass: "Actors",
     operationId: "createActor",
-    description: "Create an actor",
+    description: "Creates a new actor. project keys automatically infer the project from the key's scope; JWT callers must supply projectId.",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/actors",
     pathParams: [],
-    queryParams: []
+    queryParams: [],
+    flags: [{
+      "name": "project_id",
+      "description": "Project ID. Required for JWT auth; omit when using an project key.",
+      "required": false,
+      "type": "string",
+      "in": "body"
+    }, {
+      "name": "name",
+      "description": "",
+      "required": true,
+      "type": "string",
+      "in": "body"
+    }, {
+      "name": "external_id",
+      "description": "Optional external identifier (e.g. WhatsApp phone number). If provided and an actor with this externalId already exists in the project, the existing actor is returned (idempotent \u2014 200 OK).",
+      "required": false,
+      "type": "string",
+      "in": "body"
+    }, {
+      "name": "memory_id",
+      "description": "Memory ID to link to this actor. Mutually exclusive with auto_create_memory.",
+      "required": false,
+      "type": "string",
+      "in": "body"
+    }, {
+      "name": "auto_create_memory",
+      "description": "When true, automatically creates a new memory container for this actor and links it. Ignored if memory_id is set. With external_id (idempotent), memory is only created on first creation.",
+      "required": false,
+      "type": "boolean",
+      "in": "body"
+    }]
   },
   "get-actor": {
     serviceClass: "Actors",
     operationId: "getActor",
-    description: "Get an actor by ID",
+    description: "Returns an actor by its ID",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/actors",
     pathParams: ["actor_id"],
-    queryParams: []
+    queryParams: [],
+    flags: [{
+      "name": "actor_id",
+      "description": "Actor ID",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }]
   },
   "update-actor": {
     serviceClass: "Actors",
     operationId: "updateActor",
-    description: "Update an actor",
+    description: "Updates an actor's properties",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/actors",
     pathParams: ["actor_id"],
-    queryParams: []
+    queryParams: [],
+    flags: [{
+      "name": "actor_id",
+      "description": "Actor ID",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }, {
+      "name": "name",
+      "description": "",
+      "required": false,
+      "type": "string",
+      "in": "body"
+    }, {
+      "name": "instructions",
+      "description": "Persona-specific instructions",
+      "required": false,
+      "type": "string",
+      "in": "body"
+    }, {
+      "name": "memory_id",
+      "description": "Memory ID to link to this actor. Set to null to unlink.",
+      "required": false,
+      "type": "string",
+      "in": "body"
+    }, {
+      "name": "tags",
+      "description": "",
+      "required": false,
+      "type": "object",
+      "in": "body"
+    }]
   },
   "delete-actor": {
     serviceClass: "Actors",
     operationId: "deleteActor",
-    description: "Delete an actor",
+    description: "Deletes an actor by its ID",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/actors",
     pathParams: ["actor_id"],
-    queryParams: []
+    queryParams: [],
+    flags: [{
+      "name": "actor_id",
+      "description": "Actor ID",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }]
   },
   "get-actor-tags": {
     serviceClass: "Actors",
     operationId: "getActorTags",
-    description: "Get actor tags",
+    description: "Returns all tags attached to the actor",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/actors",
     pathParams: ["actor_id"],
-    queryParams: []
+    queryParams: [],
+    flags: [{
+      "name": "actor_id",
+      "description": "Actor ID",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }]
   },
   "replace-actor-tags": {
     serviceClass: "Actors",
     operationId: "replaceActorTags",
-    description: "Replace actor tags",
+    description: "Replaces all tags on the actor with the provided tags (not merged)",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/actors",
     pathParams: ["actor_id"],
-    queryParams: []
+    queryParams: [],
+    flags: [{
+      "name": "actor_id",
+      "description": "Actor ID",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }]
   },
   "merge-actor-tags": {
     serviceClass: "Actors",
     operationId: "mergeActorTags",
-    description: "Merge actor tags",
+    description: "Merges provided tags with existing tags (existing tags are preserved unless overridden)",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/actors",
     pathParams: ["actor_id"],
-    queryParams: []
+    queryParams: [],
+    flags: [{
+      "name": "actor_id",
+      "description": "Actor ID",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }]
   },
   "validate-agent-formation": {
     serviceClass: "AgentFormations",
     operationId: "validateAgentFormation",
-    description: "Validate a formation template",
+    description: "Validates a formation template without creating any resources. Returns a list of errors and warnings. Accepts the template as a JSON object or as a YAML/JSON string.",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/agent-formations",
     pathParams: [],
-    queryParams: []
+    queryParams: [],
+    flags: [{
+      "name": "template",
+      "description": "",
+      "required": true,
+      "type": "string",
+      "in": "body"
+    }]
   },
   "plan-agent-formation": {
     serviceClass: "AgentFormations",
     operationId: "planAgentFormation",
-    description: "Plan a formation deployment",
+    description: "Computes a diff between the desired template and the current stack state without making any changes. Returns the list of planned actions.",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/agent-formations",
     pathParams: [],
-    queryParams: []
+    queryParams: [],
+    flags: [{
+      "name": "project_id",
+      "description": "Project ID",
+      "required": true,
+      "type": "string",
+      "in": "body"
+    }, {
+      "name": "formation_id",
+      "description": "Existing formation ID to compare against. Omit for new formation planning.",
+      "required": false,
+      "type": "string",
+      "in": "body"
+    }, {
+      "name": "template",
+      "description": "",
+      "required": true,
+      "type": "string",
+      "in": "body"
+    }, {
+      "name": "parameters",
+      "description": "Runtime parameter values that override or supply template parameter defaults. Keys must match parameter names declared in `template.parameters`.\n",
+      "required": false,
+      "type": "object",
+      "in": "body"
+    }]
   },
   "list-agent-formations": {
     serviceClass: "AgentFormations",
     operationId: "listAgentFormations",
-    description: "List agent formations",
+    description: "Returns all formation stacks for a project",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/agent-formations",
     pathParams: [],
-    queryParams: ["project_id"]
+    queryParams: ["project_id"],
+    flags: [{
+      "name": "project_id",
+      "description": "Project ID (required if not using project key auth)",
+      "required": false,
+      "type": "string",
+      "in": "query"
+    }]
   },
   "create-agent-formation": {
     serviceClass: "AgentFormations",
     operationId: "createAgentFormation",
-    description: "Create a new agent formation",
+    description: "Validates the template, creates the formation record, then provisions all declared resources in dependency order.",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/agent-formations",
     pathParams: [],
-    queryParams: []
+    queryParams: [],
+    flags: [{
+      "name": "project_id",
+      "description": "Project ID",
+      "required": true,
+      "type": "string",
+      "in": "body"
+    }, {
+      "name": "name",
+      "description": "Human-readable name for the formation stack",
+      "required": true,
+      "type": "string",
+      "in": "body"
+    }, {
+      "name": "template",
+      "description": "",
+      "required": true,
+      "type": "string",
+      "in": "body"
+    }, {
+      "name": "parameters",
+      "description": "Runtime parameter values that override or supply template parameter defaults. Keys must match parameter names declared in `template.parameters`. Required parameters (those without a default) must be provided here.\n",
+      "required": false,
+      "type": "object",
+      "in": "body"
+    }, {
+      "name": "metadata",
+      "description": "",
+      "required": false,
+      "type": "object",
+      "in": "body"
+    }]
   },
   "get-agent-formation": {
     serviceClass: "AgentFormations",
     operationId: "getAgentFormation",
-    description: "Get a specific agent formation",
+    description: "Returns the formation stack including its current resources.",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/agent-formations",
     pathParams: ["formation_id"],
-    queryParams: []
+    queryParams: [],
+    flags: [{
+      "name": "formation_id",
+      "description": "",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }]
   },
   "update-agent-formation": {
     serviceClass: "AgentFormations",
     operationId: "updateAgentFormation",
-    description: "Update an agent formation",
+    description: "Applies a new template to the formation. Resources are created, updated, or deleted to reconcile the current state with the desired state.",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/agent-formations",
     pathParams: ["formation_id"],
-    queryParams: []
+    queryParams: [],
+    flags: [{
+      "name": "formation_id",
+      "description": "",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }, {
+      "name": "template",
+      "description": "",
+      "required": false,
+      "type": "string",
+      "in": "body"
+    }, {
+      "name": "parameters",
+      "description": "Runtime parameter values that override or supply template parameter defaults. Keys must match parameter names declared in `template.parameters`. Required parameters (those without a default) must be provided here.\n",
+      "required": false,
+      "type": "object",
+      "in": "body"
+    }, {
+      "name": "metadata",
+      "description": "",
+      "required": false,
+      "type": "object",
+      "in": "body"
+    }]
   },
   "delete-agent-formation": {
     serviceClass: "AgentFormations",
     operationId: "deleteAgentFormation",
-    description: "Delete an agent formation",
+    description: "Deletes the formation stack and all its managed resources in reverse dependency order.",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/agent-formations",
     pathParams: ["formation_id"],
-    queryParams: []
+    queryParams: [],
+    flags: [{
+      "name": "formation_id",
+      "description": "",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }]
   },
   "list-agent-formation-events": {
     serviceClass: "AgentFormations",
     operationId: "listAgentFormationEvents",
-    description: "List formation operation events",
+    description: "Returns all operations (create, update, delete) with their event logs for the formation, ordered chronologically.",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/agent-formations",
     pathParams: ["formation_id"],
-    queryParams: []
+    queryParams: [],
+    flags: [{
+      "name": "formation_id",
+      "description": "",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }]
   },
   "list-agent-tools": {
     serviceClass: "AgentTools",
     operationId: "listAgentTools",
-    description: "List agent tools",
+    description: "Returns all agent tools in the project.",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/agents",
     pathParams: [],
-    queryParams: ["project_id"]
+    queryParams: ["project_id"],
+    flags: [{
+      "name": "project_id",
+      "description": "Project public ID to filter by",
+      "required": false,
+      "type": "string",
+      "in": "query"
+    }]
   },
   "create-agent-tool": {
     serviceClass: "AgentTools",
     operationId: "createAgentTool",
-    description: "Create an agent tool",
+    description: "Creates a new agent tool in the project.",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/agents",
     pathParams: [],
-    queryParams: []
+    queryParams: [],
+    flags: []
   },
   "get-agent-tool": {
     serviceClass: "AgentTools",
     operationId: "getAgentTool",
-    description: "Get an agent tool",
+    description: "Returns a single agent tool by ID.",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/agents",
     pathParams: ["tool_id"],
-    queryParams: []
+    queryParams: [],
+    flags: [{
+      "name": "tool_id",
+      "description": "",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }]
   },
   "update-agent-tool": {
     serviceClass: "AgentTools",
     operationId: "updateAgentTool",
-    description: "Update an agent tool",
+    description: "Updates an existing agent tool.",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/agents",
     pathParams: ["tool_id"],
-    queryParams: []
+    queryParams: [],
+    flags: [{
+      "name": "tool_id",
+      "description": "",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }]
   },
   "delete-agent-tool": {
     serviceClass: "AgentTools",
     operationId: "deleteAgentTool",
-    description: "Delete an agent tool",
+    description: "Deletes an agent tool by ID.",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/agents",
     pathParams: ["tool_id"],
-    queryParams: []
+    queryParams: [],
+    flags: [{
+      "name": "tool_id",
+      "description": "",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }]
   },
   "list-agents": {
     serviceClass: "Agents",
     operationId: "listAgents",
-    description: "List agents",
+    description: "Returns all agents in the project.",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/agents",
     pathParams: [],
-    queryParams: ["project_id"]
+    queryParams: ["project_id"],
+    flags: [{
+      "name": "project_id",
+      "description": "Project public ID to filter by",
+      "required": false,
+      "type": "string",
+      "in": "query"
+    }]
   },
   "create-agent": {
     serviceClass: "Agents",
     operationId: "createAgent",
-    description: "Create an agent",
+    description: "Creates a new agent bound to an AI provider.",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/agents",
     pathParams: [],
-    queryParams: []
+    queryParams: [],
+    flags: []
   },
   "get-agent": {
     serviceClass: "Agents",
     operationId: "getAgent",
-    description: "Get an agent",
+    description: "Returns a single agent by ID.",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/agents",
     pathParams: ["agent_id"],
-    queryParams: []
+    queryParams: [],
+    flags: [{
+      "name": "agent_id",
+      "description": "",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }]
   },
   "update-agent": {
     serviceClass: "Agents",
     operationId: "updateAgent",
-    description: "Update an agent",
+    description: "Updates an existing agent.",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/agents",
     pathParams: ["agent_id"],
-    queryParams: []
+    queryParams: [],
+    flags: [{
+      "name": "agent_id",
+      "description": "",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }]
   },
   "delete-agent": {
     serviceClass: "Agents",
     operationId: "deleteAgent",
-    description: "Delete an agent",
+    description: "Deletes an agent by ID.",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/agents",
     pathParams: ["agent_id"],
-    queryParams: []
+    queryParams: [],
+    flags: [{
+      "name": "agent_id",
+      "description": "",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }]
   },
   "create-agent-generation": {
     serviceClass: "Agents",
     operationId: "createAgentGeneration",
-    description: "Run an agent generation",
+    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`.",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/agents",
     pathParams: ["agent_id"],
-    queryParams: []
+    queryParams: [],
+    flags: [{
+      "name": "agent_id",
+      "description": "",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }]
   },
   "submit-agent-tool-outputs": {
     serviceClass: "Agents",
     operationId: "submitAgentToolOutputs",
-    description: "Submit tool outputs for a paused generation",
+    description: "Resumes a generation that was paused due to client tool calls. Provide tool outputs for each pending tool call.",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/agents",
     pathParams: ["agent_id", "generation_id"],
-    queryParams: []
+    queryParams: [],
+    flags: [{
+      "name": "agent_id",
+      "description": "",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }, {
+      "name": "generation_id",
+      "description": "",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }]
   },
   "create-agent-actor": {
     serviceClass: "Agents",
     operationId: "createAgentActor",
-    description: "Create an actor for an agent",
+    description: "Creates a new actor associated with the specified agent",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/agents",
     pathParams: ["agent_id"],
-    queryParams: []
+    queryParams: [],
+    flags: [{
+      "name": "agent_id",
+      "description": "Agent ID",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }, {
+      "name": "name",
+      "description": "",
+      "required": true,
+      "type": "string",
+      "in": "body"
+    }, {
+      "name": "type",
+      "description": "Optional actor type",
+      "required": false,
+      "type": "string",
+      "in": "body"
+    }, {
+      "name": "external_id",
+      "description": "Optional external identifier",
+      "required": false,
+      "type": "string",
+      "in": "body"
+    }, {
+      "name": "tags",
+      "description": "",
+      "required": false,
+      "type": "object",
+      "in": "body"
+    }]
   },
   "list-ai-providers": {
     serviceClass: "AIProviders",
     operationId: "listAiProviders",
-    description: "List AI providers",
+    description: "Returns a list of AI provider configurations for a project",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/ai-providers",
     pathParams: [],
-    queryParams: ["project_id", "limit", "offset"]
+    queryParams: ["project_id", "limit", "offset"],
+    flags: [{
+      "name": "project_id",
+      "description": "Project ID (required if not using project key auth)",
+      "required": false,
+      "type": "string",
+      "in": "query"
+    }, {
+      "name": "limit",
+      "description": "Number of results per page",
+      "required": false,
+      "type": "integer",
+      "in": "query"
+    }, {
+      "name": "offset",
+      "description": "Number of results to skip",
+      "required": false,
+      "type": "integer",
+      "in": "query"
+    }]
   },
   "create-ai-provider": {
     serviceClass: "AIProviders",
     operationId: "createAiProvider",
-    description: "Create an AI provider",
+    description: "Creates a new LLM provider configuration",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/ai-providers",
     pathParams: [],
-    queryParams: []
+    queryParams: [],
+    flags: [{
+      "name": "project_id",
+      "description": "Project ID (required if not using project key auth)",
+      "required": false,
+      "type": "string",
+      "in": "body"
+    }, {
+      "name": "name",
+      "description": "Provider configuration name",
+      "required": true,
+      "type": "string",
+      "in": "body"
+    }, {
+      "name": "provider",
+      "description": "LLM provider",
+      "required": true,
+      "type": "string",
+      "in": "body"
+    }, {
+      "name": "default_model",
+      "description": "Default model to use",
+      "required": true,
+      "type": "string",
+      "in": "body"
+    }, {
+      "name": "secret_id",
+      "description": "Secret ID containing API credentials",
+      "required": false,
+      "type": "string",
+      "in": "body"
+    }, {
+      "name": "base_url",
+      "description": "Custom base URL for the provider",
+      "required": false,
+      "type": "string",
+      "in": "body"
+    }, {
+      "name": "config",
+      "description": "Additional provider-specific configuration",
+      "required": false,
+      "type": "object",
+      "in": "body"
+    }]
   },
   "get-ai-provider": {
     serviceClass: "AIProviders",
     operationId: "getAiProvider",
-    description: "Get an AI provider",
+    description: "Returns a specific AI provider configuration",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/ai-providers",
     pathParams: ["ai_provider_id"],
-    queryParams: []
+    queryParams: [],
+    flags: [{
+      "name": "ai_provider_id",
+      "description": "AI Provider ID",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }]
   },
   "update-ai-provider": {
     serviceClass: "AIProviders",
     operationId: "updateAiProvider",
-    description: "Update an AI provider",
+    description: "Updates an AI provider configuration",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/ai-providers",
     pathParams: ["ai_provider_id"],
-    queryParams: []
+    queryParams: [],
+    flags: [{
+      "name": "ai_provider_id",
+      "description": "AI Provider ID",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }, {
+      "name": "name",
+      "description": "",
+      "required": false,
+      "type": "string",
+      "in": "body"
+    }, {
+      "name": "default_model",
+      "description": "",
+      "required": false,
+      "type": "string",
+      "in": "body"
+    }, {
+      "name": "secret_id",
+      "description": "",
+      "required": false,
+      "type": "string",
+      "in": "body"
+    }, {
+      "name": "base_url",
+      "description": "",
+      "required": false,
+      "type": "string",
+      "in": "body"
+    }, {
+      "name": "config",
+      "description": "",
+      "required": false,
+      "type": "object",
+      "in": "body"
+    }]
   },
   "delete-ai-provider": {
     serviceClass: "AIProviders",
     operationId: "deleteAiProvider",
-    description: "Delete an AI provider",
+    description: "Deletes an AI provider configuration",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/ai-providers",
     pathParams: ["ai_provider_id"],
-    queryParams: []
+    queryParams: [],
+    flags: [{
+      "name": "ai_provider_id",
+      "description": "AI Provider ID",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }]
   },
   "list-api-keys": {
     serviceClass: "APIKeys",
     operationId: "listApiKeys",
-    description: "List API keys",
+    description: "Lists API keys accessible to the caller. - JWT admin: returns all API keys. - JWT regular user: returns only the user's own API keys. - API key scoped to a project: returns only API keys scoped to that project.",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/api-keys",
     pathParams: [],
-    queryParams: []
+    queryParams: [],
+    flags: []
   },
   "create-api-key": {
     serviceClass: "APIKeys",
     operationId: "createApiKey",
-    description: "Create an API key",
+    description: "Creates a new API key for the authenticated user. - If `project_id` is provided, the key is scoped to that project. - If `policy_ids` is provided, the key's effective permissions are the intersection of the user's policies and the key's policies. - If neither is provided, the key inherits the user's full permissions.",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/api-keys",
     pathParams: [],
-    queryParams: []
+    queryParams: [],
+    flags: [{
+      "name": "name",
+      "description": "Key name for identification",
+      "required": true,
+      "type": "string",
+      "in": "body"
+    }, {
+      "name": "project_id",
+      "description": "Optional project ID to scope this key to a specific project",
+      "required": false,
+      "type": "string",
+      "in": "body"
+    }, {
+      "name": "policy_ids",
+      "description": "Optional list of policy IDs to attach. Key permissions become the intersection of user policies and these policies.",
+      "required": false,
+      "type": "array",
+      "in": "body"
+    }]
   },
   "get-api-key": {
     serviceClass: "APIKeys",
     operationId: "getApiKey",
-    description: "Get an API key",
+    description: "Returns details of an API key. Only the owner or an admin can access it.",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/api-keys",
     pathParams: ["api_key_id"],
-    queryParams: []
+    queryParams: [],
+    flags: [{
+      "name": "api_key_id",
+      "description": "API key public ID (key_ prefix)",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }]
   },
   "update-api-key": {
     serviceClass: "APIKeys",
     operationId: "updateApiKey",
-    description: "Update an API key",
+    description: "Updates an API key's name, project scope, or policies. Only the owner or an admin can update it.",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/api-keys",
     pathParams: ["api_key_id"],
-    queryParams: []
+    queryParams: [],
+    flags: [{
+      "name": "api_key_id",
+      "description": "API key public ID (key_ prefix)",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }, {
+      "name": "name",
+      "description": "",
+      "required": false,
+      "type": "string",
+      "in": "body"
+    }, {
+      "name": "project_id",
+      "description": "Set to null to remove project scope",
+      "required": false,
+      "type": "string",
+      "in": "body"
+    }, {
+      "name": "policy_ids",
+      "description": "Replace the key's policy list (empty array removes all)",
+      "required": false,
+      "type": "array",
+      "in": "body"
+    }]
   },
   "delete-api-key": {
     serviceClass: "APIKeys",
     operationId: "deleteApiKey",
-    description: "Delete an API key",
+    description: "Deletes an API key. Only the owner or an admin can delete it.",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/api-keys",
     pathParams: ["api_key_id"],
-    queryParams: []
+    queryParams: [],
+    flags: [{
+      "name": "api_key_id",
+      "description": "API key public ID (key_ prefix)",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }]
   },
   "list-chats": {
     serviceClass: "Chats",
     operationId: "listChats",
-    description: "List chats",
+    description: "Returns all chats in the project.",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/chats",
     pathParams: [],
-    queryParams: ["project_id"]
+    queryParams: ["project_id"],
+    flags: [{
+      "name": "project_id",
+      "description": "Project public ID to filter by",
+      "required": false,
+      "type": "string",
+      "in": "query"
+    }]
   },
   "create-chat": {
     serviceClass: "Chats",
     operationId: "createChat",
-    description: "Create a chat",
+    description: "Creates a new chat resource bound to an AI provider.",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/chats",
     pathParams: [],
-    queryParams: []
+    queryParams: [],
+    flags: []
   },
   "get-chat": {
     serviceClass: "Chats",
     operationId: "getChat",
-    description: "Get a chat",
+    description: "Returns a single chat by ID.",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/chats",
     pathParams: ["chat_id"],
-    queryParams: []
+    queryParams: [],
+    flags: [{
+      "name": "chat_id",
+      "description": "",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }]
   },
   "delete-chat": {
     serviceClass: "Chats",
     operationId: "deleteChat",
-    description: "Delete a chat",
+    description: "Deletes a chat by ID.",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/chats",
     pathParams: ["chat_id"],
-    queryParams: []
+    queryParams: [],
+    flags: [{
+      "name": "chat_id",
+      "description": "",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }]
   },
   "create-chat-completion-for-chat": {
     serviceClass: "Chats",
     operationId: "createChatCompletionForChat",
-    description: "Create a chat completion for a stored chat",
+    description: "Runs a completion using the AI provider and settings stored in the chat. Pass `stream: true` for SSE streaming. A system message in `messages` overrides the chat's stored system message for this call only. Messages may use `documentId` instead of `content`.",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/chats",
     pathParams: ["chat_id"],
-    queryParams: []
+    queryParams: [],
+    flags: [{
+      "name": "chat_id",
+      "description": "",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }]
   },
   "create-chat-completion": {
     serviceClass: "Chats",
     operationId: "createChatCompletion",
-    description: "Create a chat completion (stateless)",
+    description: "OpenAI Chat Completions-compatible endpoint. Resolves the AI provider from `ai_provider_id`, decrypts its secret, and calls the appropriate Vercel AI SDK provider. `ai_provider_id` is required \u2014 there is no server-side model fallback.",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/chats",
     pathParams: [],
-    queryParams: []
+    queryParams: [],
+    flags: []
   },
   "create-chat-actor": {
     serviceClass: "Chats",
     operationId: "createChatActor",
-    description: "Create an actor for a chat",
+    description: "Creates a new actor associated with the specified chat",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/chats",
     pathParams: ["chat_id"],
-    queryParams: []
+    queryParams: [],
+    flags: [{
+      "name": "chat_id",
+      "description": "Chat ID",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }, {
+      "name": "name",
+      "description": "",
+      "required": true,
+      "type": "string",
+      "in": "body"
+    }, {
+      "name": "type",
+      "description": "Optional actor type",
+      "required": false,
+      "type": "string",
+      "in": "body"
+    }, {
+      "name": "external_id",
+      "description": "Optional external identifier",
+      "required": false,
+      "type": "string",
+      "in": "body"
+    }, {
+      "name": "tags",
+      "description": "",
+      "required": false,
+      "type": "object",
+      "in": "body"
+    }]
   },
   "list-conversations": {
     serviceClass: "Conversations",
     operationId: "listConversations",
-    description: "List conversations",
+    description: "Returns all conversations the caller has access to. If projectId is provided, returns only conversations in that project. project keys are scoped to a single project automatically.",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/conversations",
     pathParams: [],
-    queryParams: ["project_id", "actor_id", "limit", "offset"]
+    queryParams: ["project_id", "actor_id", "limit", "offset"],
+    flags: [{
+      "name": "project_id",
+      "description": "Project ID (optional)",
+      "required": false,
+      "type": "string",
+      "in": "query"
+    }, {
+      "name": "actor_id",
+      "description": "Filter by actor ID",
+      "required": false,
+      "type": "string",
+      "in": "query"
+    }, {
+      "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-conversation": {
     serviceClass: "Conversations",
     operationId: "createConversation",
-    description: "Create a conversation",
+    description: "Creates a new conversation. project keys automatically infer the project from the key's scope; JWT callers must supply projectId.",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/conversations",
     pathParams: [],
-    queryParams: []
+    queryParams: [],
+    flags: [{
+      "name": "project_id",
+      "description": "Project ID. Required for JWT auth; omit when using an project key.",
+      "required": false,
+      "type": "string",
+      "in": "body"
+    }, {
+      "name": "status",
+      "description": "Initial conversation status",
+      "required": false,
+      "type": "string",
+      "in": "body"
+    }, {
+      "name": "name",
+      "description": "Optional name for the conversation",
+      "required": false,
+      "type": "string",
+      "in": "body"
+    }, {
+      "name": "actor_id",
+      "description": "Actor ID to associate with this conversation",
+      "required": false,
+      "type": "string",
+      "in": "body"
+    }]
   },
   "get-conversation": {
     serviceClass: "Conversations",
     operationId: "getConversation",
-    description: "Get a conversation by ID",
+    description: "Returns a conversation by its ID",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/conversations",
     pathParams: ["conversation_id"],
-    queryParams: []
+    queryParams: [],
+    flags: [{
+      "name": "conversation_id",
+      "description": "Conversation ID",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }]
   },
   "update-conversation": {
     serviceClass: "Conversations",
     operationId: "updateConversation",
-    description: "Update a conversation",
+    description: "Updates the status of a conversation",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/conversations",
     pathParams: ["conversation_id"],
-    queryParams: []
+    queryParams: [],
+    flags: [{
+      "name": "conversation_id",
+      "description": "Conversation ID",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }, {
+      "name": "status",
+      "description": "New conversation status",
+      "required": true,
+      "type": "string",
+      "in": "body"
+    }]
   },
   "delete-conversation": {
     serviceClass: "Conversations",
     operationId: "deleteConversation",
-    description: "Delete a conversation",
+    description: "Deletes a conversation by its ID",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/conversations",
     pathParams: ["conversation_id"],
-    queryParams: []
+    queryParams: [],
+    flags: [{
+      "name": "conversation_id",
+      "description": "Conversation ID",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }]
   },
   "list-conversation-messages": {
     serviceClass: "Conversations",
     operationId: "listConversationMessages",
-    description: "List conversation messages",
+    description: "Returns all messages (documents) attached to a conversation, ordered by position",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/conversations",
     pathParams: ["conversation_id"],
-    queryParams: ["limit", "offset"]
+    queryParams: ["limit", "offset"],
+    flags: [{
+      "name": "conversation_id",
+      "description": "Conversation 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"
+    }]
   },
   "add-conversation-message": {
     serviceClass: "Conversations",
     operationId: "addConversationMessage",
-    description: "Add a message to a conversation",
+    description: "Creates a document from the message text and attaches it to the conversation at the given position. If position is omitted, it is appended at the end.",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/conversations",
     pathParams: ["conversation_id"],
-    queryParams: []
+    queryParams: [],
+    flags: [{
+      "name": "conversation_id",
+      "description": "Conversation ID",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }, {
+      "name": "message",
+      "description": "Message text content to add to the conversation",
+      "required": true,
+      "type": "string",
+      "in": "body"
+    }, {
+      "name": "role",
+      "description": "Role of the message sender",
+      "required": true,
+      "type": "string",
+      "in": "body"
+    }, {
+      "name": "actor_id",
+      "description": "Optional actor ID to associate with this message (user identity)",
+      "required": false,
+      "type": "string",
+      "in": "body"
+    }, {
+      "name": "position",
+      "description": "Zero-based position. Defaults to MAX+1 (append).",
+      "required": false,
+      "type": "integer",
+      "in": "body"
+    }, {
+      "name": "metadata",
+      "description": "Optional structured metadata to attach to the message (e.g. phone number, channel). Stored as-is and injected into the AI prompt context.",
+      "required": false,
+      "type": "object",
+      "in": "body"
+    }]
   },
   "generate-conversation-message": {
     serviceClass: "Conversations",
     operationId: "generateConversationMessage",
-    description: "Generate the next message in a conversation",
+    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.",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/conversations",
     pathParams: ["conversation_id"],
-    queryParams: []
+    queryParams: [],
+    flags: [{
+      "name": "conversation_id",
+      "description": "",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }, {
+      "name": "agent_id",
+      "description": "ID of the agent that will produce the next message.",
+      "required": true,
+      "type": "string",
+      "in": "body"
+    }, {
+      "name": "model",
+      "description": "Optional model override.",
+      "required": false,
+      "type": "string",
+      "in": "body"
+    }, {
+      "name": "stream",
+      "description": "If true, stream tokens via SSE. NOT IMPLEMENTED in v1 \u2014 returns 501.",
+      "required": false,
+      "type": "boolean",
+      "in": "body"
+    }, {
+      "name": "tool_context",
+      "description": "Key-value pairs injected as context headers into all tool call requests made during this generation.",
+      "required": false,
+      "type": "object",
+      "in": "body"
+    }]
   },
   "list-conversation-actors": {
     serviceClass: "Conversations",
     operationId: "listConversationActors",
-    description: "List actors in a conversation",
+    description: "Returns all distinct actors who have sent at least one message in the conversation",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/conversations",
     pathParams: ["conversation_id"],
-    queryParams: []
+    queryParams: [],
+    flags: [{
+      "name": "conversation_id",
+      "description": "Conversation ID",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }]
   },
   "remove-conversation-message": {
     serviceClass: "Conversations",
     operationId: "removeConversationMessage",
-    description: "Remove a message from a conversation",
+    description: "Removes a document from a conversation",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/conversations",
     pathParams: ["conversation_id", "document_id"],
-    queryParams: []
+    queryParams: [],
+    flags: [{
+      "name": "conversation_id",
+      "description": "Conversation ID",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }, {
+      "name": "document_id",
+      "description": "Document ID",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }]
   },
   "get-conversation-tags": {
     serviceClass: "Conversations",
     operationId: "getConversationTags",
-    description: "Get conversation tags",
+    description: "Returns all tags attached to the conversation",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/conversations",
     pathParams: ["conversation_id"],
-    queryParams: []
+    queryParams: [],
+    flags: [{
+      "name": "conversation_id",
+      "description": "Conversation ID",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }]
   },
   "replace-conversation-tags": {
     serviceClass: "Conversations",
     operationId: "replaceConversationTags",
-    description: "Replace conversation tags",
+    description: "Replaces all tags on the conversation with the provided tags",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/conversations",
     pathParams: ["conversation_id"],
-    queryParams: []
+    queryParams: [],
+    flags: [{
+      "name": "conversation_id",
+      "description": "Conversation ID",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }]
   },
   "merge-conversation-tags": {
     serviceClass: "Conversations",
     operationId: "mergeConversationTags",
-    description: "Merge conversation tags",
+    description: "Merges provided tags with existing tags",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/conversations",
     pathParams: ["conversation_id"],
-    queryParams: []
+    queryParams: [],
+    flags: [{
+      "name": "conversation_id",
+      "description": "Conversation ID",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }]
   },
   "list-documents": {
     serviceClass: "Documents",
     operationId: "listDocuments",
-    description: "List documents",
+    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",
     pathParams: [],
-    queryParams: ["project_id"]
+    queryParams: ["project_id"],
+    flags: [{
+      "name": "project_id",
+      "description": "Project ID (optional)",
+      "required": false,
+      "type": "string",
+      "in": "query"
+    }]
   },
   "create-document": {
     serviceClass: "Documents",
     operationId: "createDocument",
-    description: "Create a document",
+    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",
     pathParams: [],
-    queryParams: []
+    queryParams: [],
+    flags: [{
+      "name": "project_id",
+      "description": "Project ID. Required for JWT auth; omit when using an project key.",
+      "required": false,
+      "type": "string",
+      "in": "body"
+    }, {
+      "name": "content",
+      "description": "",
+      "required": true,
+      "type": "string",
+      "in": "body"
+    }, {
+      "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": "filename",
+      "description": "",
+      "required": false,
+      "type": "string",
+      "in": "body"
+    }]
   },
   "get-document": {
     serviceClass: "Documents",
     operationId: "getDocument",
-    description: "Get a document by ID",
+    description: "Returns a document with its text content",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/documents",
     pathParams: ["document_id"],
-    queryParams: []
+    queryParams: [],
+    flags: [{
+      "name": "document_id",
+      "description": "Document ID",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }]
   },
   "update-document": {
     serviceClass: "Documents",
     operationId: "updateDocument",
-    description: "Update a document",
+    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",
     pathParams: ["document_id"],
-    queryParams: []
+    queryParams: [],
+    flags: [{
+      "name": "document_id",
+      "description": "Document ID",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }, {
+      "name": "content",
+      "description": "New text content",
+      "required": false,
+      "type": "string",
+      "in": "body"
+    }, {
+      "name": "title",
+      "description": "New title",
+      "required": false,
+      "type": "string",
+      "in": "body"
+    }, {
+      "name": "path",
+      "description": "Logical path within the project (e.g. /reports/q1.txt). Pass null to clear.",
+      "required": false,
+      "type": "string",
+      "in": "body"
+    }, {
+      "name": "metadata",
+      "description": "Arbitrary metadata object",
+      "required": false,
+      "type": "object",
+      "in": "body"
+    }, {
+      "name": "tags",
+      "description": "Key-value tags",
+      "required": false,
+      "type": "object",
+      "in": "body"
+    }]
   },
   "delete-document": {
     serviceClass: "Documents",
     operationId: "deleteDocument",
-    description: "Delete a document",
+    description: "Deletes a document and its underlying file",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/documents",
     pathParams: ["document_id"],
-    queryParams: []
+    queryParams: [],
+    flags: [{
+      "name": "document_id",
+      "description": "Document ID",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }]
   },
   "get-document-tags": {
     serviceClass: "Documents",
     operationId: "getDocumentTags",
-    description: "Get document tags",
+    description: "Returns all tags attached to the document",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/documents",
     pathParams: ["document_id"],
-    queryParams: []
+    queryParams: [],
+    flags: [{
+      "name": "document_id",
+      "description": "Document ID",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }]
   },
   "replace-document-tags": {
     serviceClass: "Documents",
     operationId: "replaceDocumentTags",
-    description: "Replace document tags",
+    description: "Replaces all tags on the document with the provided tags (not merged)",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/documents",
     pathParams: ["document_id"],
-    queryParams: []
+    queryParams: [],
+    flags: [{
+      "name": "document_id",
+      "description": "Document ID",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }]
   },
   "merge-document-tags": {
     serviceClass: "Documents",
     operationId: "mergeDocumentTags",
-    description: "Merge document tags",
+    description: "Merges provided tags with existing tags (existing tags are preserved unless overridden)",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/documents",
     pathParams: ["document_id"],
-    queryParams: []
+    queryParams: [],
+    flags: [{
+      "name": "document_id",
+      "description": "Document ID",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }]
   },
   "list-files": {
     serviceClass: "Files",
     operationId: "listFiles",
-    description: "List all files",
+    description: "Returns a list of all stored files",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/files",
     pathParams: [],
-    queryParams: ["project_id", "limit", "offset"]
+    queryParams: ["project_id", "limit", "offset"],
+    flags: [{
+      "name": "project_id",
+      "description": "Filter files by project ID",
+      "required": false,
+      "type": "string",
+      "in": "query"
+    }, {
+      "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-file": {
     serviceClass: "Files",
     operationId: "createFile",
-    description: "Create a file",
+    description: "Creates a new file record in the system",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/files",
     pathParams: [],
-    queryParams: []
+    queryParams: [],
+    flags: [{
+      "name": "project_id",
+      "description": "Public ID of the project",
+      "required": true,
+      "type": "string",
+      "in": "body"
+    }, {
+      "name": "path",
+      "description": "Logical path within the project (e.g. /images/logo.png). Defaults to /filename if omitted.",
+      "required": false,
+      "type": "string",
+      "in": "body"
+    }, {
+      "name": "filename",
+      "description": "Name of the file",
+      "required": false,
+      "type": "string",
+      "in": "body"
+    }, {
+      "name": "content_type",
+      "description": "MIME type of the file",
+      "required": false,
+      "type": "string",
+      "in": "body"
+    }, {
+      "name": "size",
+      "description": "File size in bytes",
+      "required": false,
+      "type": "integer",
+      "in": "body"
+    }, {
+      "name": "storage_type",
+      "description": "Storage backend type",
+      "required": true,
+      "type": "string",
+      "in": "body"
+    }, {
+      "name": "storage_path",
+      "description": "Path where the file is stored",
+      "required": true,
+      "type": "string",
+      "in": "body"
+    }, {
+      "name": "metadata",
+      "description": "JSON string with additional metadata",
+      "required": false,
+      "type": "string",
+      "in": "body"
+    }]
   },
   "upload-file": {
     serviceClass: "Files",
     operationId: "uploadFile",
-    description: "Upload a file",
+    description: "Uploads a file to the server and stores it in the configured storage directory",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/files",
     pathParams: [],
-    queryParams: []
+    queryParams: [],
+    flags: []
   },
   "upload-file-base64": {
     serviceClass: "Files",
     operationId: "uploadFileBase64",
-    description: "Upload a file using base64 encoding",
+    description: "Uploads a file to the server using base64-encoded content",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/files",
     pathParams: [],
-    queryParams: []
+    queryParams: [],
+    flags: []
   },
   "get-file": {
     serviceClass: "Files",
     operationId: "getFile",
-    description: "Get a file by ID",
+    description: "Returns the data and metadata of a specific file",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/files",
     pathParams: ["file_id"],
-    queryParams: []
+    queryParams: [],
+    flags: [{
+      "name": "file_id",
+      "description": "File ID",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }]
   },
   "delete-file": {
     serviceClass: "Files",
     operationId: "deleteFile",
-    description: "Delete a file",
+    description: "Removes a file from the system by ID",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/files",
     pathParams: ["file_id"],
-    queryParams: []
+    queryParams: [],
+    flags: [{
+      "name": "file_id",
+      "description": "ID of the file to delete",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }]
   },
   "download-file": {
     serviceClass: "Files",
     operationId: "downloadFile",
-    description: "Download a file",
+    description: "Streams the file content to the client",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/files",
     pathParams: ["file_id"],
-    queryParams: []
+    queryParams: [],
+    flags: [{
+      "name": "file_id",
+      "description": "File ID",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }]
   },
   "update-file-metadata": {
     serviceClass: "Files",
     operationId: "updateFileMetadata",
-    description: "Update file metadata",
+    description: "Updates the metadata field of a file",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/files",
     pathParams: ["file_id"],
-    queryParams: []
+    queryParams: [],
+    flags: [{
+      "name": "file_id",
+      "description": "File ID",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }, {
+      "name": "metadata",
+      "description": "New metadata as a JSON string",
+      "required": false,
+      "type": "string",
+      "in": "body"
+    }, {
+      "name": "filename",
+      "description": "New filename for the file",
+      "required": false,
+      "type": "string",
+      "in": "body"
+    }]
   },
   "download-file-base64": {
     serviceClass: "Files",
     operationId: "downloadFileBase64",
-    description: "Download file as base64",
+    description: "Returns the file content encoded as base64",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/files",
     pathParams: ["file_id"],
-    queryParams: []
+    queryParams: [],
+    flags: [{
+      "name": "file_id",
+      "description": "File ID",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }]
   },
   "get-file-tags": {
     serviceClass: "Files",
     operationId: "getFileTags",
-    description: "Get file tags",
+    description: "Returns all tags attached to the file",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/files",
     pathParams: ["file_id"],
-    queryParams: []
+    queryParams: [],
+    flags: [{
+      "name": "file_id",
+      "description": "File ID",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }]
   },
   "replace-file-tags": {
     serviceClass: "Files",
     operationId: "replaceFileTags",
-    description: "Replace file tags",
+    description: "Replaces all tags on the file with the provided tags",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/files",
     pathParams: ["file_id"],
-    queryParams: []
+    queryParams: [],
+    flags: [{
+      "name": "file_id",
+      "description": "File ID",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }]
   },
   "merge-file-tags": {
     serviceClass: "Files",
     operationId: "mergeFileTags",
-    description: "Merge file tags",
+    description: "Merges provided tags with existing tags",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/files",
     pathParams: ["file_id"],
-    queryParams: []
+    queryParams: [],
+    flags: [{
+      "name": "file_id",
+      "description": "File ID",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }]
   },
   "search-knowledge": {
     serviceClass: "Knowledge",
     operationId: "searchKnowledge",
-    description: "Search knowledge",
+    description: "Searches across documents and memory entries using semantic search, file paths, document IDs, or memory IDs/tags. At least one of `query`, `document_paths`, `document_ids`, `memory_ids`, or `memory_tags` must be provided.",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/knowledge",
     pathParams: [],
-    queryParams: []
+    queryParams: [],
+    flags: [{
+      "name": "project_id",
+      "description": "Limit search to a specific project",
+      "required": false,
+      "type": "string",
+      "in": "body"
+    }, {
+      "name": "query",
+      "description": "Semantic search query text",
+      "required": false,
+      "type": "string",
+      "in": "body"
+    }, {
+      "name": "min_score",
+      "description": "Minimum similarity score (0\u20131). Results with lower scores are excluded. Only applies when `query` is provided.",
+      "required": false,
+      "type": "number",
+      "in": "body"
+    }, {
+      "name": "limit",
+      "description": "Maximum number of results to return (default 10)",
+      "required": false,
+      "type": "integer",
+      "in": "body"
+    }, {
+      "name": "memory_ids",
+      "description": "Search entries within these specific memories",
+      "required": false,
+      "type": "array",
+      "in": "body"
+    }, {
+      "name": "memory_tags",
+      "description": "Search entries in memories whose tags match any of these patterns (glob supported)",
+      "required": false,
+      "type": "array",
+      "in": "body"
+    }, {
+      "name": "document_paths",
+      "description": "Filter results to documents whose file path starts with one of these prefixes",
+      "required": false,
+      "type": "array",
+      "in": "body"
+    }, {
+      "name": "document_ids",
+      "description": "Filter results to specific document IDs",
+      "required": false,
+      "type": "array",
+      "in": "body"
+    }]
   },
   "list-memories": {
     serviceClass: "Memories",
     operationId: "listMemories",
-    description: "List memories",
+    description: "Returns a list of memory configurations for a project",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/memories",
     pathParams: [],
-    queryParams: ["project_id", "tags"]
+    queryParams: ["project_id", "tags"],
+    flags: [{
+      "name": "project_id",
+      "description": "Project ID (required if not using project key auth)",
+      "required": false,
+      "type": "string",
+      "in": "query"
+    }, {
+      "name": "tags",
+      "description": "Filter memories by tag patterns. Supports glob syntax (`*` matches any substring, `?` matches any single character). Multiple values are ORed \u2014 a memory is returned if any of its tags match any of the provided patterns. Omit to return all memories.\n",
+      "required": false,
+      "type": "array",
+      "in": "query"
+    }]
   },
   "create-memory": {
     serviceClass: "Memories",
     operationId: "createMemory",
-    description: "Create a memory",
+    description: "Creates a new memory configuration in a project",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/memories",
     pathParams: [],
-    queryParams: []
+    queryParams: [],
+    flags: [{
+      "name": "project_id",
+      "description": "Project ID (required if not using project key auth)",
+      "required": false,
+      "type": "string",
+      "in": "body"
+    }, {
+      "name": "name",
+      "description": "Memory name",
+      "required": true,
+      "type": "string",
+      "in": "body"
+    }, {
+      "name": "description",
+      "description": "Optional description",
+      "required": false,
+      "type": "string",
+      "in": "body"
+    }, {
+      "name": "tags",
+      "description": "Optional list of tags for filtering in knowledge search",
+      "required": false,
+      "type": "array",
+      "in": "body"
+    }]
   },
   "get-memory": {
     serviceClass: "Memories",
     operationId: "getMemory",
-    description: "Get a memory",
+    description: "Returns a single memory configuration by ID",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/memories",
     pathParams: ["memory_id"],
-    queryParams: []
+    queryParams: [],
+    flags: [{
+      "name": "memory_id",
+      "description": "",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }]
   },
   "update-memory": {
     serviceClass: "Memories",
     operationId: "updateMemory",
-    description: "Update a memory",
+    description: "Updates an existing memory configuration",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/memories",
     pathParams: ["memory_id"],
-    queryParams: []
+    queryParams: [],
+    flags: [{
+      "name": "memory_id",
+      "description": "",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }, {
+      "name": "name",
+      "description": "Memory name",
+      "required": false,
+      "type": "string",
+      "in": "body"
+    }, {
+      "name": "description",
+      "description": "Optional description",
+      "required": false,
+      "type": "string",
+      "in": "body"
+    }, {
+      "name": "tags",
+      "description": "Optional list of tags for filtering in knowledge search",
+      "required": false,
+      "type": "array",
+      "in": "body"
+    }]
   },
   "delete-memory": {
     serviceClass: "Memories",
     operationId: "deleteMemory",
-    description: "Delete a memory",
+    description: "Deletes a memory configuration",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/memories",
     pathParams: ["memory_id"],
-    queryParams: []
+    queryParams: [],
+    flags: [{
+      "name": "memory_id",
+      "description": "",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }]
   },
   "list-memory-entries": {
     serviceClass: "MemoryEntries",
     operationId: "listMemoryEntries",
-    description: "List memory entries",
+    description: "Returns all entries in a memory container",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/memoryEntries",
     pathParams: ["memory_id"],
-    queryParams: []
+    queryParams: [],
+    flags: [{
+      "name": "memory_id",
+      "description": "",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }]
   },
   "create-memory-entry": {
     serviceClass: "MemoryEntries",
     operationId: "createMemoryEntry",
-    description: "Create a memory entry",
+    description: "Creates a new entry in the specified memory container. Automatically generates an embedding for semantic search.",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/memoryEntries",
     pathParams: ["memory_id"],
-    queryParams: []
+    queryParams: [],
+    flags: [{
+      "name": "memory_id",
+      "description": "",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }, {
+      "name": "content",
+      "description": "The text content of the memory entry",
+      "required": true,
+      "type": "string",
+      "in": "body"
+    }, {
+      "name": "source",
+      "description": "How this entry was created",
+      "required": false,
+      "type": "string",
+      "in": "body"
+    }, {
+      "name": "duplicate_threshold",
+      "description": "Cosine similarity score at or above which the incoming content is considered a duplicate and skipped (default 0.95)",
+      "required": false,
+      "type": "number",
+      "in": "body"
+    }, {
+      "name": "update_threshold",
+      "description": "Cosine similarity score at or above which the incoming content is appended to the existing entry (default 0.75)",
+      "required": false,
+      "type": "number",
+      "in": "body"
+    }]
   },
   "get-memory-entry": {
     serviceClass: "MemoryEntries",
     operationId: "getMemoryEntry",
-    description: "Get a memory entry",
+    description: "Returns a single memory entry by ID",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/memoryEntries",
     pathParams: ["memory_id", "entry_id"],
-    queryParams: []
+    queryParams: [],
+    flags: [{
+      "name": "memory_id",
+      "description": "",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }, {
+      "name": "entry_id",
+      "description": "",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }]
   },
   "update-memory-entry": {
     serviceClass: "MemoryEntries",
     operationId: "updateMemoryEntry",
-    description: "Update a memory entry",
+    description: "Updates an existing memory entry. Regenerates the embedding if content changes.",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/memoryEntries",
     pathParams: ["memory_id", "entry_id"],
-    queryParams: []
+    queryParams: [],
+    flags: [{
+      "name": "memory_id",
+      "description": "",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }, {
+      "name": "entry_id",
+      "description": "",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }, {
+      "name": "content",
+      "description": "Updated text content",
+      "required": false,
+      "type": "string",
+      "in": "body"
+    }]
   },
   "delete-memory-entry": {
     serviceClass: "MemoryEntries",
     operationId: "deleteMemoryEntry",
-    description: "Delete a memory entry",
+    description: "Deletes a memory entry",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/memoryEntries",
     pathParams: ["memory_id", "entry_id"],
-    queryParams: []
+    queryParams: [],
+    flags: [{
+      "name": "memory_id",
+      "description": "",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }, {
+      "name": "entry_id",
+      "description": "",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }]
   },
   "list-policies": {
     serviceClass: "Policies",
     operationId: "listPolicies",
-    description: "List all policies",
+    description: "Returns a list of all global policies. Requires admin role.",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/policies",
     pathParams: [],
-    queryParams: []
+    queryParams: [],
+    flags: []
   },
   "create-policy": {
     serviceClass: "Policies",
     operationId: "createPolicy",
-    description: "Create a policy",
+    description: "Creates a new global policy. Requires admin role.",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/policies",
     pathParams: [],
-    queryParams: []
+    queryParams: [],
+    flags: [{
+      "name": "name",
+      "description": "",
+      "required": false,
+      "type": "string",
+      "in": "body"
+    }, {
+      "name": "description",
+      "description": "",
+      "required": false,
+      "type": "string",
+      "in": "body"
+    }, {
+      "name": "document",
+      "description": "",
+      "required": true,
+      "type": "string",
+      "in": "body"
+    }]
   },
   "get-policy": {
     serviceClass: "Policies",
     operationId: "getPolicy",
-    description: "Get a policy",
+    description: "Returns details of a specific policy. Requires admin role.",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/policies",
     pathParams: ["policy_id"],
-    queryParams: []
+    queryParams: [],
+    flags: [{
+      "name": "policy_id",
+      "description": "Policy public ID (pol_ prefix)",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }]
   },
   "update-policy": {
     serviceClass: "Policies",
     operationId: "updatePolicy",
-    description: "Update a policy",
+    description: "Updates an existing global policy. Requires admin role.",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/policies",
     pathParams: ["policy_id"],
-    queryParams: []
+    queryParams: [],
+    flags: [{
+      "name": "policy_id",
+      "description": "Policy public ID (pol_ prefix)",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }, {
+      "name": "name",
+      "description": "",
+      "required": false,
+      "type": "string",
+      "in": "body"
+    }, {
+      "name": "description",
+      "description": "",
+      "required": false,
+      "type": "string",
+      "in": "body"
+    }, {
+      "name": "document",
+      "description": "",
+      "required": true,
+      "type": "string",
+      "in": "body"
+    }]
   },
   "delete-policy": {
     serviceClass: "Policies",
     operationId: "deletePolicy",
-    description: "Delete a policy",
+    description: "Deletes a global policy. Requires admin role.",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/policies",
     pathParams: ["policy_id"],
-    queryParams: []
+    queryParams: [],
+    flags: [{
+      "name": "policy_id",
+      "description": "Policy public ID (pol_ prefix)",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }]
   },
   "create-project": {
     serviceClass: "Projects",
     operationId: "createProject",
-    description: "Create a project",
+    description: "Creates a new project. Requires admin role.",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/projects",
     pathParams: [],
-    queryParams: []
+    queryParams: [],
+    flags: [{
+      "name": "name",
+      "description": "",
+      "required": true,
+      "type": "string",
+      "in": "body"
+    }]
   },
   "get-project": {
     serviceClass: "Projects",
     operationId: "getProject",
-    description: "Get a project",
+    description: "Returns details of a specific project.",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/projects",
     pathParams: ["project_id"],
-    queryParams: []
+    queryParams: [],
+    flags: [{
+      "name": "project_id",
+      "description": "Project public ID (proj_ prefix)",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }]
   },
   "delete-project": {
     serviceClass: "Projects",
     operationId: "deleteProject",
-    description: "Delete a project",
+    description: "Deletes a project. Requires admin role.",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/projects",
     pathParams: ["project_id"],
-    queryParams: []
+    queryParams: [],
+    flags: [{
+      "name": "project_id",
+      "description": "Project public ID (proj_ prefix)",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }]
   },
   "list-secrets": {
     serviceClass: "Secrets",
     operationId: "listSecrets",
-    description: "List secrets",
+    description: "Returns a list of secrets for a project",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/secrets",
     pathParams: [],
-    queryParams: ["project_id", "limit", "offset"]
+    queryParams: ["project_id", "limit", "offset"],
+    flags: [{
+      "name": "project_id",
+      "description": "Project ID (required if not using project key auth)",
+      "required": false,
+      "type": "string",
+      "in": "query"
+    }, {
+      "name": "limit",
+      "description": "Number of results per page",
+      "required": false,
+      "type": "integer",
+      "in": "query"
+    }, {
+      "name": "offset",
+      "description": "Number of results to skip",
+      "required": false,
+      "type": "integer",
+      "in": "query"
+    }]
   },
   "create-secret": {
     serviceClass: "Secrets",
     operationId: "createSecret",
-    description: "Create a secret",
+    description: "Creates a new encrypted secret in a project",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/secrets",
     pathParams: [],
-    queryParams: []
+    queryParams: [],
+    flags: [{
+      "name": "project_id",
+      "description": "Project ID (required if not using project key auth)",
+      "required": false,
+      "type": "string",
+      "in": "body"
+    }, {
+      "name": "name",
+      "description": "Secret name",
+      "required": true,
+      "type": "string",
+      "in": "body"
+    }, {
+      "name": "value",
+      "description": "Secret value (will be encrypted)",
+      "required": true,
+      "type": "string",
+      "in": "body"
+    }]
   },
   "get-secret": {
     serviceClass: "Secrets",
     operationId: "getSecret",
-    description: "Get a secret",
+    description: "Returns a specific secret",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/secrets",
     pathParams: ["secret_id"],
-    queryParams: []
+    queryParams: [],
+    flags: [{
+      "name": "secret_id",
+      "description": "Secret ID",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }]
   },
   "update-secret": {
     serviceClass: "Secrets",
     operationId: "updateSecret",
-    description: "Update a secret",
+    description: "Updates a secret's name and/or value",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/secrets",
     pathParams: ["secret_id"],
-    queryParams: []
+    queryParams: [],
+    flags: [{
+      "name": "secret_id",
+      "description": "Secret ID",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }, {
+      "name": "name",
+      "description": "New secret name",
+      "required": false,
+      "type": "string",
+      "in": "body"
+    }, {
+      "name": "value",
+      "description": "New secret value",
+      "required": false,
+      "type": "string",
+      "in": "body"
+    }]
   },
   "delete-secret": {
     serviceClass: "Secrets",
     operationId: "deleteSecret",
-    description: "Delete a secret",
+    description: "Deletes a secret",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/secrets",
     pathParams: ["secret_id"],
-    queryParams: []
+    queryParams: [],
+    flags: [{
+      "name": "secret_id",
+      "description": "Secret ID",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }]
   },
   "list-agent-sessions": {
     serviceClass: "Sessions",
     operationId: "listAgentSessions",
-    description: "List sessions",
+    description: "Returns sessions for the specified agent, optionally filtered by actorId and status.",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/sessions",
     pathParams: ["agent_id"],
-    queryParams: ["actor_id", "status", "limit", "offset"]
+    queryParams: ["actor_id", "status", "limit", "offset"],
+    flags: [{
+      "name": "agent_id",
+      "description": "Agent public ID",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }, {
+      "name": "actor_id",
+      "description": "Filter by actor public ID",
+      "required": false,
+      "type": "string",
+      "in": "query"
+    }, {
+      "name": "status",
+      "description": "Filter by session status (open or closed)",
+      "required": false,
+      "type": "string",
+      "in": "query"
+    }, {
+      "name": "limit",
+      "description": "",
+      "required": false,
+      "type": "integer",
+      "in": "query"
+    }, {
+      "name": "offset",
+      "description": "",
+      "required": false,
+      "type": "integer",
+      "in": "query"
+    }]
   },
   "create-agent-session": {
     serviceClass: "Sessions",
     operationId: "createAgentSession",
-    description: "Create a session",
+    description: "Creates a new session for the specified agent. Internally creates a conversation and two actors (agent + user) so the caller only needs this single call to start interacting with the agent.",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/sessions",
     pathParams: ["agent_id"],
-    queryParams: []
+    queryParams: [],
+    flags: [{
+      "name": "agent_id",
+      "description": "Agent public ID",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }]
   },
   "get-agent-session": {
     serviceClass: "Sessions",
     operationId: "getAgentSession",
-    description: "Get a session",
+    description: "Returns details of a single session.",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/sessions",
     pathParams: ["agent_id", "session_id"],
-    queryParams: []
+    queryParams: [],
+    flags: [{
+      "name": "agent_id",
+      "description": "Agent public ID",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }, {
+      "name": "session_id",
+      "description": "Session public ID",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }]
   },
   "update-session": {
     serviceClass: "Sessions",
     operationId: "updateSession",
-    description: "Update a session",
+    description: "Updates the session name and/or status.",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/sessions",
     pathParams: ["agent_id", "session_id"],
-    queryParams: []
+    queryParams: [],
+    flags: [{
+      "name": "agent_id",
+      "description": "Agent public ID",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }, {
+      "name": "session_id",
+      "description": "Session public ID",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }]
   },
   "delete-agent-session": {
     serviceClass: "Sessions",
     operationId: "deleteAgentSession",
-    description: "Delete a session",
+    description: "Deletes the session and its underlying conversation and actors.",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/sessions",
     pathParams: ["agent_id", "session_id"],
-    queryParams: []
+    queryParams: [],
+    flags: [{
+      "name": "agent_id",
+      "description": "Agent public ID",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }, {
+      "name": "session_id",
+      "description": "Session public ID",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }]
   },
   "list-agent-session-messages": {
     serviceClass: "Sessions",
     operationId: "listAgentSessionMessages",
-    description: "List session messages",
+    description: "Returns messages in the session with simplified roles (user/assistant) instead of raw actor IDs.",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/sessions",
     pathParams: ["agent_id", "session_id"],
-    queryParams: ["limit", "offset"]
+    queryParams: ["limit", "offset"],
+    flags: [{
+      "name": "agent_id",
+      "description": "Agent public ID",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }, {
+      "name": "session_id",
+      "description": "Session public ID",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }, {
+      "name": "limit",
+      "description": "",
+      "required": false,
+      "type": "integer",
+      "in": "query"
+    }, {
+      "name": "offset",
+      "description": "",
+      "required": false,
+      "type": "integer",
+      "in": "query"
+    }]
   },
   "add-session-message": {
     serviceClass: "Sessions",
     operationId: "addSessionMessage",
-    description: "Add a user message",
+    description: "Saves a user message to the session. When autoGenerate is enabled on the session and no generation is currently in progress, generation is triggered automatically and the response mirrors GenerateSessionResponse. Otherwise returns the saved user message.",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/sessions",
     pathParams: ["agent_id", "session_id"],
-    queryParams: []
+    queryParams: [],
+    flags: [{
+      "name": "agent_id",
+      "description": "Agent public ID",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }, {
+      "name": "session_id",
+      "description": "Session public ID",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }]
   },
   "generate-session-response": {
     serviceClass: "Sessions",
     operationId: "generateSessionResponse",
-    description: "Trigger agent generation",
+    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.",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/sessions",
     pathParams: ["agent_id", "session_id"],
-    queryParams: ["async"]
+    queryParams: ["async"],
+    flags: [{
+      "name": "agent_id",
+      "description": "Agent public ID",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }, {
+      "name": "session_id",
+      "description": "Session public ID",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }, {
+      "name": "async",
+      "description": "When true, generation runs in the background and 202 is returned immediately",
+      "required": false,
+      "type": "boolean",
+      "in": "query"
+    }]
   },
   "submit-session-tool-outputs": {
     serviceClass: "Sessions",
     operationId: "submitSessionToolOutputs",
-    description: "Submit tool outputs",
+    description: "Submits client tool outputs for a generation that returned requires_action. The agent continues its loop and returns the final or next requires_action result.",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/sessions",
     pathParams: ["agent_id", "session_id"],
-    queryParams: []
+    queryParams: [],
+    flags: [{
+      "name": "agent_id",
+      "description": "Agent public ID",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }, {
+      "name": "session_id",
+      "description": "Session public ID",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }]
   },
   "get-session-tags": {
     serviceClass: "Sessions",
     operationId: "getSessionTags",
-    description: "Get session tags",
+    description: "Returns the session's tags object.",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/sessions",
     pathParams: ["agent_id", "session_id"],
-    queryParams: []
+    queryParams: [],
+    flags: [{
+      "name": "agent_id",
+      "description": "Agent public ID",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }, {
+      "name": "session_id",
+      "description": "Session public ID",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }]
   },
   "replace-session-tags": {
     serviceClass: "Sessions",
     operationId: "replaceSessionTags",
-    description: "Replace session tags",
+    description: "Replaces all tags on the session.",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/sessions",
     pathParams: ["agent_id", "session_id"],
-    queryParams: []
+    queryParams: [],
+    flags: [{
+      "name": "agent_id",
+      "description": "Agent public ID",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }, {
+      "name": "session_id",
+      "description": "Session public ID",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }]
   },
   "merge-session-tags": {
     serviceClass: "Sessions",
     operationId: "mergeSessionTags",
-    description: "Merge session tags",
+    description: "Merges the provided tags into the session's existing tags.",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/sessions",
     pathParams: ["agent_id", "session_id"],
-    queryParams: []
+    queryParams: [],
+    flags: [{
+      "name": "agent_id",
+      "description": "Agent public ID",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }, {
+      "name": "session_id",
+      "description": "Session public ID",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }]
   },
   "list-traces": {
     serviceClass: "Traces",
     operationId: "listTraces",
-    description: "List traces",
+    description: "Returns a paginated list of execution traces for the project.",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/traces",
     pathParams: [],
-    queryParams: ["project_id", "limit", "offset"]
+    queryParams: ["project_id", "limit", "offset"],
+    flags: [{
+      "name": "project_id",
+      "description": "Project public ID to filter by",
+      "required": false,
+      "type": "string",
+      "in": "query"
+    }, {
+      "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"
+    }]
   },
   "get-trace": {
     serviceClass: "Traces",
     operationId: "getTrace",
-    description: "Get a trace",
+    description: "Returns a single trace by ID.",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/traces",
     pathParams: ["trace_id"],
-    queryParams: []
+    queryParams: [],
+    flags: [{
+      "name": "trace_id",
+      "description": "Public ID of the trace",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }]
   },
   "get-trace-tree": {
     serviceClass: "Traces",
     operationId: "getTraceTree",
-    description: "Get trace tree",
+    description: "Returns the full execution tree rooted at the given trace (or its root if the given trace is a child). Each node represents one agent's execution session. The `children` array contains traces triggered by sub-agent tool calls from that trace.",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/traces",
     pathParams: ["trace_id"],
-    queryParams: []
+    queryParams: [],
+    flags: [{
+      "name": "trace_id",
+      "description": "Public ID of any trace in the tree (root or child)",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }]
   },
   "list-users": {
     serviceClass: "Users",
     operationId: "listUsers",
-    description: "List all users",
+    description: "Returns a list of all users",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/users",
     pathParams: [],
-    queryParams: []
+    queryParams: [],
+    flags: []
   },
   "create-user": {
     serviceClass: "Users",
     operationId: "createUser",
-    description: "Create a user",
+    description: "Creates a new user in the system",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/users",
     pathParams: [],
-    queryParams: []
+    queryParams: [],
+    flags: [{
+      "name": "username",
+      "description": "",
+      "required": true,
+      "type": "string",
+      "in": "body"
+    }, {
+      "name": "password",
+      "description": "",
+      "required": true,
+      "type": "string",
+      "in": "body"
+    }, {
+      "name": "role",
+      "description": "",
+      "required": false,
+      "type": "string",
+      "in": "body"
+    }]
   },
   "get-user": {
     serviceClass: "Users",
     operationId: "getUser",
-    description: "Get a user by ID",
+    description: "Returns the data of a specific user",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/users",
     pathParams: ["user_id"],
-    queryParams: []
+    queryParams: [],
+    flags: [{
+      "name": "user_id",
+      "description": "User ID",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }]
   },
   "delete-user": {
     serviceClass: "Users",
     operationId: "deleteUser",
-    description: "Delete a user by ID",
+    description: "Deletes a specific user",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/users",
     pathParams: ["user_id"],
-    queryParams: []
+    queryParams: [],
+    flags: [{
+      "name": "user_id",
+      "description": "User ID",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }]
   },
   "bootstrap-user": {
     serviceClass: "Users",
     operationId: "bootstrapUser",
-    description: "Create the first admin user",
+    description: "Creates the first admin user. Returns 409 if any user already exists.",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/users",
     pathParams: [],
-    queryParams: []
+    queryParams: [],
+    flags: [{
+      "name": "username",
+      "description": "",
+      "required": true,
+      "type": "string",
+      "in": "body"
+    }, {
+      "name": "password",
+      "description": "",
+      "required": true,
+      "type": "string",
+      "in": "body"
+    }]
   },
   "login-user": {
     serviceClass: "Users",
     operationId: "loginUser",
-    description: "Login user",
+    description: "Authenticates a user and returns a JWT token",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/users",
     pathParams: [],
-    queryParams: []
+    queryParams: [],
+    flags: [{
+      "name": "username",
+      "description": "",
+      "required": true,
+      "type": "string",
+      "in": "body"
+    }, {
+      "name": "password",
+      "description": "",
+      "required": true,
+      "type": "string",
+      "in": "body"
+    }]
   },
   "get-user-policies": {
     serviceClass: "Users",
     operationId: "getUserPolicies",
-    description: "Get policies attached to a user",
+    description: "Returns the list of policies attached to a user. Requires admin role.",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/users",
     pathParams: ["user_id"],
-    queryParams: []
+    queryParams: [],
+    flags: [{
+      "name": "user_id",
+      "description": "User public ID (usr_ prefix)",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }]
   },
   "attach-user-policies": {
     serviceClass: "Users",
     operationId: "attachUserPolicies",
-    description: "Attach policies to a user",
+    description: "Replaces the user's policy list with the provided policy IDs. Requires admin role.",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/users",
     pathParams: ["user_id"],
-    queryParams: []
+    queryParams: [],
+    flags: [{
+      "name": "user_id",
+      "description": "User public ID (usr_ prefix)",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }, {
+      "name": "policy_ids",
+      "description": "List of policy public IDs to attach (replaces existing)",
+      "required": true,
+      "type": "array",
+      "in": "body"
+    }]
   },
   "list-webhooks": {
     serviceClass: "Webhooks",
     operationId: "listWebhooks",
-    description: "List webhooks for a project",
+    description: "Lists all webhooks configured for the specified project",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/webhooks",
     pathParams: ["project_id"],
-    queryParams: []
+    queryParams: [],
+    flags: [{
+      "name": "project_id",
+      "description": "",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }]
   },
   "create-webhook": {
     serviceClass: "Webhooks",
     operationId: "createWebhook",
-    description: "Create a webhook",
+    description: "Creates a new webhook for the specified project",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/webhooks",
     pathParams: ["project_id"],
-    queryParams: []
+    queryParams: [],
+    flags: [{
+      "name": "project_id",
+      "description": "",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }]
   },
   "get-webhook": {
     serviceClass: "Webhooks",
     operationId: "getWebhook",
-    description: "Get a webhook",
+    description: "Retrieves the details of a specific webhook",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/webhooks",
     pathParams: ["project_id", "webhook_id"],
-    queryParams: []
+    queryParams: [],
+    flags: [{
+      "name": "project_id",
+      "description": "",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }, {
+      "name": "webhook_id",
+      "description": "",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }]
   },
   "update-webhook": {
     serviceClass: "Webhooks",
     operationId: "updateWebhook",
-    description: "Update a webhook",
+    description: "Updates an existing webhook's configuration",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/webhooks",
     pathParams: ["project_id", "webhook_id"],
-    queryParams: []
+    queryParams: [],
+    flags: [{
+      "name": "project_id",
+      "description": "",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }, {
+      "name": "webhook_id",
+      "description": "",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }]
   },
   "delete-webhook": {
     serviceClass: "Webhooks",
     operationId: "deleteWebhook",
-    description: "Delete a webhook",
+    description: "Deletes a webhook and stops all event deliveries",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/webhooks",
     pathParams: ["project_id", "webhook_id"],
-    queryParams: []
+    queryParams: [],
+    flags: [{
+      "name": "project_id",
+      "description": "",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }, {
+      "name": "webhook_id",
+      "description": "",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }]
   },
   "list-webhook-deliveries": {
     serviceClass: "Webhooks",
     operationId: "listWebhookDeliveries",
-    description: "List deliveries for a webhook",
+    description: "Lists all event deliveries for a specific webhook",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/webhooks",
     pathParams: ["project_id", "webhook_id"],
-    queryParams: ["limit", "offset"]
+    queryParams: ["limit", "offset"],
+    flags: [{
+      "name": "project_id",
+      "description": "",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }, {
+      "name": "webhook_id",
+      "description": "",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }, {
+      "name": "limit",
+      "description": "",
+      "required": false,
+      "type": "integer",
+      "in": "query"
+    }, {
+      "name": "offset",
+      "description": "",
+      "required": false,
+      "type": "integer",
+      "in": "query"
+    }]
   },
   "get-webhook-delivery": {
     serviceClass: "Webhooks",
     operationId: "getWebhookDelivery",
-    description: "Get a delivery",
+    description: "Retrieves the details of a specific webhook delivery",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/webhooks",
     pathParams: ["project_id", "webhook_id", "delivery_id"],
-    queryParams: []
+    queryParams: [],
+    flags: [{
+      "name": "project_id",
+      "description": "",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }, {
+      "name": "webhook_id",
+      "description": "",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }, {
+      "name": "delivery_id",
+      "description": "",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }]
   },
   "rotate-webhook-secret": {
     serviceClass: "Webhooks",
     operationId: "rotateWebhookSecret",
-    description: "Rotate webhook secret",
+    description: "Rotates the secret key for the specified webhook",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/webhooks",
     pathParams: ["project_id", "webhook_id"],
-    queryParams: []
+    queryParams: [],
+    flags: [{
+      "name": "project_id",
+      "description": "",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }, {
+      "name": "webhook_id",
+      "description": "",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }]
   }
 };
 
@@ -1058,23 +3243,6 @@ var toCanonical = /* @__PURE__ */__name(s => {
 var kebabToSnake = /* @__PURE__ */__name(s => {
   return s.replace(/-/g, "_");
 }, "kebabToSnake");
-var parseUnknown = /* @__PURE__ */__name(args => {
-  const result = {};
-  for (let i = 0; i < args.length; i++) {
-    const arg = args[i];
-    if (arg?.startsWith("--")) {
-      const key = arg.slice(2);
-      const val = args[i + 1];
-      if (val !== void 0 && !val.startsWith("--")) {
-        result[key] = val;
-        i++;
-      } else {
-        result[key] = "true";
-      }
-    }
-  }
-  return result;
-}, "parseUnknown");
 var parseFlagValue = /* @__PURE__ */__name(value => {
   const trimmed = value.trim();
   if (trimmed.startsWith("{") || trimmed.startsWith("[") || trimmed === "true" || trimmed === "false" || trimmed === "null" || /^-?\d+(\.\d+)?$/.test(trimmed)) {
@@ -1103,7 +3271,13 @@ var resolveServiceClass = /* @__PURE__ */__name(serviceClassName => {
   return void 0;
 }, "resolveServiceClass");
 program.name("soat").description("SOAT CLI").version(package_default.version).option("-p, --profile <name>", "config profile to use");
+program.addHelpText("after", "\nTip: Run `soat <command> --help` to see command-specific flags and docs.");
 program.command("configure").description("Save credentials to a named profile (~/.soat/config.json)").option("-p, --profile <name>", "profile name", "default").action(async opts => {
+  const [{
+    default: input
+  }, {
+    default: password
+  }] = await Promise.all([import("@inquirer/input"), import("@inquirer/password")]);
   const baseUrl = await input({
     message: "Base URL:"
   });
@@ -1237,7 +3411,7 @@ program.command("listen").description("Start a local webhook listener for testin
     });
   });
 });
-program.argument("[command]", "API command in kebab-case (e.g. list-actors)").argument("[args...]").allowUnknownOption().action(async commandName => {
+program.argument("[command]", "API command in kebab-case (e.g. list-actors)").argument("[args...]").allowUnknownOption().passThroughOptions().action(async commandName => {
   if (!commandName) {
     program.help();
     return;
@@ -1250,7 +3424,40 @@ program.argument("[command]", "API command in kebab-case (e.g. list-actors)").ar
   }
   const rawIdx = process.argv.indexOf(commandName);
   const rawArgs = rawIdx >= 0 ? process.argv.slice(rawIdx + 1) : [];
-  const flags = parseUnknown(rawArgs);
+  if (rawArgs.includes("--help") || rawArgs.includes("-h")) {
+    const wrapperFlags = getWrapperHelpFlags(commandName);
+    const allFlags = [...route.flags, ...wrapperFlags.map(f => {
+      return {
+        ...f,
+        in: "wrapper"
+      };
+    })];
+    console.log(`
+Usage: soat ${commandName} [flags]
+`);
+    console.log(`  ${route.description}
+`);
+    console.log(`  Module docs: ${route.moduleDocsUrl}
+`);
+    if (allFlags.length > 0) {
+      console.log("Flags:");
+      for (const f of allFlags) {
+        const req = f.required ? " [required]" : "";
+        const desc = f.description ? `  ${f.description}` : "";
+        console.log(`  --${f.name}  <${f.type}>${req}${desc}`);
+      }
+    }
+    process.exit(0);
+  }
+  const parsedFlags = parseUnknownWithRepeats({
+    cliArgs: rawArgs
+  });
+  const wrapped = applyWrapperForCommand({
+    commandName,
+    route,
+    parsedFlags
+  });
+  const flags = wrapped.flags.single;
   const pathArgs = {};
   const queryArgs = {};
   const bodyArgs = {};
@@ -1287,6 +3494,9 @@ program.argument("[command]", "API command in kebab-case (e.g. list-actors)").ar
   const callOpts = {
     client
   };
+  if (Object.keys(wrapped.forcedBody).length) {
+    Object.assign(bodyArgs, wrapped.forcedBody);
+  }
   if (Object.keys(pathArgs).length) callOpts["path"] = pathArgs;
   if (Object.keys(queryArgs).length) callOpts["query"] = queryArgs;
   if (Object.keys(bodyArgs).length) callOpts["body"] = bodyArgs;
@@ -1305,4 +3515,20 @@ program.argument("[command]", "API command in kebab-case (e.g. list-actors)").ar
   }
   console.log(JSON.stringify(result.data, null, 2));
 });
-program.parse();
+var runCli = /* @__PURE__ */__name(async args => {
+  const previousArgv = process.argv;
+  process.argv = args;
+  try {
+    await program.parseAsync(args);
+  } finally {
+    process.argv = previousArgv;
+  }
+}, "runCli");
+var isMainModule = (() => {
+  if (!process.argv[1]) return false;
+  return nodePath.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+})();
+if (isMainModule) {
+  void runCli(process.argv);
+}
+export { runCli };