@deepraxis/cli 0.1.0-dev.e57ae6a → 0.1.0-dev.ea77ce8

package/dist/praxis.js

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 
 // src/main.ts
-import { readFile } from "node:fs/promises";
-import { spawn } from "node:child_process";
+import { readFile as readFile2 } from "node:fs/promises";
+import { spawn as spawn2 } from "node:child_process";
 import { createInterface } from "node:readline";
 
 // ../../packages/sdk/typescript/src/operations.generated.ts
@@ -10,6 +10,8 @@ var operations = [
   {
     resource: "agent.agents",
     method: "list",
+    summary: "List agents",
+    description: "List the agents of the workspace behind your API key, newest first, in pages of at most 100 (default 20). Use it to find an agent id before creating a session; to read one agent use agents.retrieve, to see its history use agents.versions.list. Archived agents are hidden unless include_archived is true. Filter kind=personal for durable-computer agents or kind=service for per-session environments. Pass next_page from the response as page to read the next page; a null next_page means the end.",
     http: "GET",
     path: "/agent/v1/agents",
     streaming: "no",
@@ -65,6 +67,8 @@ var operations = [
   {
     resource: "agent.agents",
     method: "create",
+    summary: "Create agent",
+    description: 'Create a reusable agent definition, then pass its returned id to sessions.create to start a conversation. The definition includes model, system prompt, tools, MCP servers and an optional multiagent roster. It is saved as version 1; real updates create new versions. Unlike Anthropic Managed Agents, nonempty skills attachments and custom tool entries return 400; the native skill tool is separate from the skills field. Use tools: [{type: "agent_toolset_20260401"}] for built-in tools including codemode, skill and agent; inspect toolsets.list for names and schemas, and keep bash enabled for native additions. To offer only some tools, set default_config: {enabled: false} and list the tools to keep in configs, e.g. tools: [{type: "agent_toolset_20260401", default_config: {enabled: false}, configs: [{name: "codemode", enabled: true}, {name: "bash", enabled: true, permission_policy: {type: "always_ask"}}]}]; every tool not listed, including todo_write, enter_plan_mode, ask_user_question and goal_read, follows default_config, and the response echoes it. codemode runs through bash, so enabling codemode while bash is disabled returns 400. Optional mcp_toolset entries pair with mcp_servers. model accepts platform model IDs such as deepseek-flash, not only the Claude IDs in the protocol examples. model.settings.reasoning sets default thinking; other extra model controls return 400. Example: {"name":"helper","model":{"id":"deepseek-flash"},"tools":[{"type":"agent_toolset_20260401"}]}.',
     http: "POST",
     path: "/agent/v1/agents",
     streaming: "no",
@@ -186,6 +190,8 @@ across all toolsets allowed.`
   {
     resource: "agent.agents",
     method: "retrieve",
+    summary: "Get agent",
+    description: "Read one agent by id, at its latest version or, with version, at a specific earlier version. The response lists every native tool with its resolved configuration in one agent_toolset_20260401 entry, so it can be sent back unchanged to agents.update. Use agents.versions.list to enumerate versions.",
     http: "GET",
     path: "/agent/v1/agents/{agent_id}",
     streaming: "no",
@@ -208,6 +214,8 @@ across all toolsets allowed.`
   {
     resource: "agent.agents",
     method: "update",
+    summary: "Update agent",
+    description: "Update an agent. Send the current version in the body for optimistic concurrency: a stale version returns 409, and an update that changes nothing keeps the version number. Any real change saves a new version; existing sessions keep the version they were created with. Omitted fields keep their value. multiagent takes null or a coordinator roster; subagent_model keeps its value when omitted and is cleared by null. Archived agents cannot be updated. Unlike Anthropic Managed Agents, nonempty skills attachments and custom tools return 400; use the native skill tool for available runtime skills.",
     http: "POST",
     path: "/agent/v1/agents/{agent_id}",
     streaming: "no",
@@ -347,6 +355,8 @@ current version; omit to apply the update unconditionally.`
   {
     resource: "agent.agents",
     method: "archive",
+    summary: "Archive agent",
+    description: "Archive an agent so it can no longer be updated and no new session can be created from it (AGENT_ARCHIVED). The agent and all of its versions stay readable. Use it to retire an agent you no longer want to run; it does not delete anything.",
     http: "POST",
     path: "/agent/v1/agents/{agent_id}/archive",
     streaming: "no",
@@ -362,6 +372,8 @@ current version; omit to apply the update unconditionally.`
   {
     resource: "agent.agents.versions",
     method: "list",
+    summary: "List agent versions",
+    description: "List the saved versions of one agent, in pages of at most 100 (default 20). Each item is the full agent definition at that version, so you can compare what changed between versions. Use agents.retrieve with version to read a single one; agent_id comes from agents.list or agents.create.",
     http: "GET",
     path: "/agent/v1/agents/{agent_id}/versions",
     streaming: "no",
@@ -390,6 +402,10 @@ current version; omit to apply the update unconditionally.`
   {
     resource: "agent.computers",
     method: "list",
+    summary: "ComputersList",
+    description: `Tenant-owned durable computer resource.
+
+Praxis extension: MA only has session-scoped temporary containers and memory_stores, not durable browsable computers. Archived files remain readable, but new sessions cannot bind them. environment_id is an optional recipe reference; computers start with a light sandbox and expose the public SDK sandbox_id. Lists include archived computers.`,
     http: "GET",
     path: "/agent/v1/computers",
     streaming: "no",
@@ -413,6 +429,10 @@ current version; omit to apply the update unconditionally.`
   {
     resource: "agent.computers",
     method: "create",
+    summary: "ComputersCreate",
+    description: `Tenant-owned durable computer resource.
+
+Praxis extension: MA only has session-scoped temporary containers and memory_stores, not durable browsable computers. Archived files remain readable, but new sessions cannot bind them. environment_id is an optional recipe reference; computers start with a light sandbox and expose the public SDK sandbox_id. Lists include archived computers.`,
     http: "POST",
     path: "/agent/v1/computers",
     streaming: "no",
@@ -440,6 +460,10 @@ current version; omit to apply the update unconditionally.`
   {
     resource: "agent.computers",
     method: "delete",
+    summary: "Delete Archived Computer",
+    description: `Permanently delete an archived explicit computer and its files and code runs.
+
+Own-face superset: Managed Agents has no persistent Computer deletion lifecycle. Only archived computers can be deleted. Active computers return 400 COMPUTER_ACTIVE (archive first). Destroy storage before removing registration. Success returns id and type=computer_deleted; missing or foreign computers return 404.`,
     http: "DELETE",
     path: "/agent/v1/computers/{computer_id}",
     streaming: "no",
@@ -455,6 +479,10 @@ current version; omit to apply the update unconditionally.`
   {
     resource: "agent.computers",
     method: "retrieve",
+    summary: "ComputersRetrieve",
+    description: `Tenant-owned durable computer resource.
+
+Praxis extension: MA only has session-scoped temporary containers and memory_stores, not durable browsable computers. Archived files remain readable, but new sessions cannot bind them. environment_id is an optional recipe reference; computers start with a light sandbox and expose the public SDK sandbox_id. Lists include archived computers.`,
     http: "GET",
     path: "/agent/v1/computers/{computer_id}",
     streaming: "no",
@@ -470,6 +498,10 @@ current version; omit to apply the update unconditionally.`
   {
     resource: "agent.computers",
     method: "update",
+    summary: "ComputersUpdate",
+    description: `Tenant-owned durable computer resource.
+
+Praxis extension: MA only has session-scoped temporary containers and memory_stores, not durable browsable computers. Archived files remain readable, but new sessions cannot bind them. environment_id is an optional recipe reference; computers start with a light sandbox and expose the public SDK sandbox_id. Lists include archived computers.`,
     http: "POST",
     path: "/agent/v1/computers/{computer_id}",
     streaming: "no",
@@ -496,6 +528,10 @@ current version; omit to apply the update unconditionally.`
   {
     resource: "agent.computers",
     method: "archive",
+    summary: "ComputersArchive",
+    description: `Tenant-owned durable computer resource.
+
+Praxis extension: MA only has session-scoped temporary containers and memory_stores, not durable browsable computers. Archived files remain readable, but new sessions cannot bind them. environment_id is an optional recipe reference; computers start with a light sandbox and expose the public SDK sandbox_id. Lists include archived computers.`,
     http: "POST",
     path: "/agent/v1/computers/{computer_id}/archive",
     streaming: "no",
@@ -511,6 +547,10 @@ current version; omit to apply the update unconditionally.`
   {
     resource: "agent.computers.attachments",
     method: "create",
+    summary: "Upload Computer Attachment",
+    description: `Upload raw bytes into /attachments and return the same FileInfo as the file list.
+
+Own-face superset: Managed Agents has no persistent Computer attachment directory. User uploads overwrite the same name; agents retain read-only access. Run-token uploads return 403 READ_ONLY. name is one filename of at most 255 UTF-8 bytes; MIME is inferred from the extension; custom Content-Type is not persisted and digest may be absent. Limit 16 MiB (413); invalid names return 400. Archived computers accept uploads; foreign computers return 404.`,
     http: "POST",
     path: "/agent/v1/computers/{computer_id}/attachments",
     streaming: "no",
@@ -537,6 +577,10 @@ current version; omit to apply the update unconditionally.`
   {
     resource: "agent.computers",
     method: "connect",
+    summary: "Connect computer",
+    description: `Resume the computer and issue a sandbox connection.
+
+Own-face extension: Managed Agents has no persistent Computer connection. Returns the public SDK sandbox_id, envd_access_token and template_id. Archived computers remain accessible; foreign or absent computers return 404. Never cache credentials.`,
     http: "POST",
     path: "/agent/v1/computers/{computer_id}/connect",
     streaming: "no",
@@ -552,6 +596,10 @@ current version; omit to apply the update unconditionally.`
   {
     resource: "agent.computers.files",
     method: "list",
+    summary: "ComputersFilesList",
+    description: `Tenant-owned durable computer resource.
+
+Praxis extension: MA only has session-scoped temporary containers and memory_stores, not durable browsable computers. Archived files remain readable, but new sessions cannot bind them. environment_id is an optional recipe reference; computers start with a light sandbox and expose the public SDK sandbox_id. Lists include archived computers.`,
     http: "GET",
     path: "/agent/v1/computers/{computer_id}/files",
     streaming: "no",
@@ -574,6 +622,10 @@ current version; omit to apply the update unconditionally.`
   {
     resource: "agent.computers.files",
     method: "retrieveContent",
+    summary: "ComputersFilesContent",
+    description: `Tenant-owned durable computer resource.
+
+Praxis extension: MA only has session-scoped temporary containers and memory_stores, not durable browsable computers. Archived files remain readable, but new sessions cannot bind them. environment_id is an optional recipe reference; computers start with a light sandbox and expose the public SDK sandbox_id. Lists include archived computers.`,
     http: "GET",
     path: "/agent/v1/computers/{computer_id}/files/content",
     streaming: "no",
@@ -596,6 +648,8 @@ current version; omit to apply the update unconditionally.`
   {
     resource: "agent.deploymentRuns",
     method: "list",
+    summary: "List deployment runs",
+    description: "List deployment runs newest first. Filter by deployment_id, has_error, trigger_type (manual or schedule) and created_at[gt|gte|lt|lte]. The default limit is 20, maximum 100; pass next_page as page with the same filters to continue. Each record identifies the resolved agent version and either its session or creation error.",
     http: "GET",
     path: "/agent/v1/deployment_runs",
     streaming: "no",
@@ -669,6 +723,8 @@ current version; omit to apply the update unconditionally.`
   {
     resource: "agent.deploymentRuns",
     method: "retrieve",
+    summary: "Get deployment run",
+    description: "Read a deployment run by the drun_ id returned by deployments.run or deployment_runs.list. Exactly one of session_id and error is non-null. Scheduled runs include scheduled_at in trigger_context. Foreign or absent ids return 404.",
     http: "GET",
     path: "/agent/v1/deployment_runs/{deployment_run_id}",
     streaming: "no",
@@ -684,6 +740,8 @@ current version; omit to apply the update unconditionally.`
   {
     resource: "agent.deployments",
     method: "list",
+    summary: "List deployments",
+    description: "List stored deployments newest first. Filter by agent_id, status, or inclusive created_at bounds; status and include_archived cannot be combined, even when include_archived is false. The default limit is 20, maximum 100; pass next_page as page to continue. Archived deployments are hidden by default. Schedules show up to five future wall-clock occurrences, also while paused; archived schedules show none.",
     http: "GET",
     path: "/agent/v1/deployments",
     streaming: "no",
@@ -746,6 +804,8 @@ archived).`
   {
     resource: "agent.deployments",
     method: "create",
+    summary: "Create deployment",
+    description: "Freeze session parameters as a deployment; this operation does not open a session. Pass an agent id or versioned reference, a name, 1–50 user.message initial events and an environment_id from environments.list. Unlike Anthropic Managed Agents, /agent/v1 also accepts agent_with_overrides (model, permission_mode and cwd) and target=computer for personal agents, with environment_id omitted. Cron schedules use five POSIX fields and an IANA timezone. File resources are accepted. Supports vault_ids, up to 50, owned by the current organization and not archived; credential injection is deferred to a later version. Active schedules run every minute when due; session creation errors pause the deployment. Unsupported tools, mcp_servers, system and skills overrides return 400.",
     http: "POST",
     path: "/agent/v1/deployments",
     streaming: "no",
@@ -834,6 +894,8 @@ created from this deployment. Maximum 50.`
   {
     resource: "agent.deployments",
     method: "retrieve",
+    summary: "Get deployment",
+    description: "Read a stored deployment by its depl_ id from deployments.create or deployments.list. The agent reference has a concrete version; own-face overrides are echoed unchanged. This read recomputes upcoming schedule times and does not execute the deployment. Foreign or absent ids return 404.",
     http: "GET",
     path: "/agent/v1/deployments/{deployment_id}",
     streaming: "no",
@@ -849,6 +911,8 @@ created from this deployment. Maximum 50.`
   {
     resource: "agent.deployments",
     method: "update",
+    summary: "Update deployment",
+    description: "Partially update a deployment. Omitted fields keep their values; a supplied agent id re-pins the latest version, or supply a versioned reference. Metadata merges string values and deletes keys set to null. Null clears schedule, resources and description; name, environment_id and initial_events cannot be cleared. Archived deployments return 409. Overrides apply to new sessions; updating a schedule recalculates its next occurrence.",
     http: "POST",
     path: "/agent/v1/deployments/{deployment_id}",
     streaming: "no",
@@ -945,6 +1009,8 @@ null to clear. Maximum 50.`
   {
     resource: "agent.deployments",
     method: "archive",
+    summary: "Archive deployment",
+    description: "Archive a deployment by its depl_ id. Repeated calls are idempotent; archived deployments remain readable and have no upcoming schedule times. Subsequent update, pause and unpause calls return 409. This operation does not create a deployment run.",
     http: "POST",
     path: "/agent/v1/deployments/{deployment_id}/archive",
     streaming: "no",
@@ -960,6 +1026,8 @@ null to clear. Maximum 50.`
   {
     resource: "agent.deployments",
     method: "pause",
+    summary: "Pause deployment",
+    description: "Pause an active deployment and set paused_reason to {type: manual}. Repeated pause calls are idempotent; archived deployments return 409. Upcoming schedule times remain visible while paused; no run is executed.",
     http: "POST",
     path: "/agent/v1/deployments/{deployment_id}/pause",
     streaming: "no",
@@ -975,6 +1043,8 @@ null to clear. Maximum 50.`
   {
     resource: "agent.deployments.run",
     method: "create",
+    summary: "Run deployment",
+    description: "Create one session from an active deployment using its pinned agent version and stored parameters. Pass the depl_ id from deployments.create or deployments.list; no request body is needed. Returns a drun_ record with exactly one of session_id or error populated. Creation errors automatically pause the deployment; paused or archived deployments return 409 without a run. Unlike the own face, the compatible face rejects computer targets with 400.",
     http: "POST",
     path: "/agent/v1/deployments/{deployment_id}/run",
     streaming: "no",
@@ -990,6 +1060,8 @@ null to clear. Maximum 50.`
   {
     resource: "agent.deployments.unpause",
     method: "create",
+    summary: "Unpause deployment",
+    description: "Resume a paused deployment and clear paused_reason. Repeated unpause calls on an active deployment are idempotent; archived deployments return 409. This operation changes resource state only and does not execute a run.",
     http: "POST",
     path: "/agent/v1/deployments/{deployment_id}/unpause",
     streaming: "no",
@@ -1002,9 +1074,52 @@ null to clear. Maximum 50.`
     ],
     query: []
   },
+  {
+    resource: "agent.embedTokens",
+    method: "list",
+    summary: "List Embed Tokens",
+    description: `List embed token issuance records in your organization.
+
+Includes expired and revoked grants; returns neither token nor token_id. Sorts by created_at, then grant id, both descending. agent_id accepts agent_ or agt_; external_user_id matches exactly. limit is 1–100 (default 20). Reuse next_page as page with the same filters and organization; a mismatch returns 400. End-user credentials return 404.`,
+    http: "GET",
+    path: "/agent/v1/embed_tokens",
+    streaming: "no",
+    pagination: false,
+    pathParams: [],
+    query: [
+      {
+        name: "agent_id",
+        type: "string",
+        required: false,
+        description: "Filter by service agent identifier (agent_ or agt_ prefix)."
+      },
+      {
+        name: "external_user_id",
+        type: "string",
+        required: false,
+        description: "Exact host user identifier supplied at issuance."
+      },
+      {
+        name: "limit",
+        type: "integer",
+        required: false,
+        description: "Maximum records per page; defaults to 20."
+      },
+      {
+        name: "page",
+        type: "string",
+        required: false,
+        description: "next_page from a previous response with the same filters."
+      }
+    ]
+  },
   {
     resource: "agent.embedTokens",
     method: "create",
+    summary: "Create Embed Token",
+    description: `Issue a short-lived credential on your backend for an end user of a service agent.
+
+Requires an active service agent in your organization with an embed policy. Pins the requested version or the latest version and snapshots the policy environment, vaults and resources; metadata comes from the request. Blocked users cannot receive tokens. Keep your API key on the backend and pass only the returned token to the frontend. Every call creates a new grant; issuance is not idempotent. The hosted field is not supported.`,
     http: "POST",
     path: "/agent/v1/embed_tokens",
     streaming: "no",
@@ -1073,9 +1188,30 @@ null to clear. Maximum 50.`
       ]
     }
   },
+  {
+    resource: "agent.embedTokens.revoke",
+    method: "create",
+    summary: "Revoke Embed Token",
+    description: `Revoke an embed token and close its open event streams.
+
+Use an id from issuance or listing. Revokes the credential before setting revoked_at; upstream failure leaves it unset. Streams receive session.error (EMBED_TOKEN_REVOKED), then close immediately; other credentials are unaffected. Idempotent; repeats return the original revoked record without another revocation or audit. Missing or foreign grants and end-user credentials return 404.`,
+    http: "POST",
+    path: "/agent/v1/embed_tokens/{id}/revoke",
+    streaming: "no",
+    pagination: false,
+    pathParams: [
+      {
+        name: "id",
+        sdkName: "id"
+      }
+    ],
+    query: []
+  },
   {
     resource: "agent.environments",
     method: "list",
+    summary: "List environments",
+    description: "List execution environments: the built-in recipes and the tenant-owned cloud environments that a session can run in. Archived environments are hidden unless include_archived is true. Pages hold at most 100 items (default 20); pass next_page as page to continue. Use the returned id as environment_id when creating a session.",
     http: "GET",
     path: "/agent/v1/environments",
     streaming: "no",
@@ -1109,6 +1245,8 @@ null to clear. Maximum 50.`
   {
     resource: "agent.environments",
     method: "create",
+    summary: "Create environment",
+    description: "Create a tenant-owned cloud environment: a sandbox recipe (packages to install and networking policy) that sessions can select through environment_id. Package installation happens when the session's sandbox is created; a failed install terminates that session with ENVIRONMENT_PACKAGE_INSTALL_FAILED. Limited networking is applied at sandbox creation. Unlike Anthropic Managed Agents, self_hosted environments, scope and cross-session package caching are not supported.",
     http: "POST",
     path: "/agent/v1/environments",
     streaming: "no",
@@ -1161,6 +1299,8 @@ rejected. If not specified, defaults based on organization type.`
   {
     resource: "agent.environments",
     method: "retrieve",
+    summary: "Get environment",
+    description: "Read one environment's configuration and status by id. Built-in environments are readable but never editable; tenant-owned ones can be updated or archived. environment_id comes from environments.list or environments.create.",
     http: "GET",
     path: "/agent/v1/environments/{environment_id}",
     streaming: "no",
@@ -1176,6 +1316,8 @@ rejected. If not specified, defaults based on organization type.`
   {
     resource: "agent.environments",
     method: "update",
+    summary: "Update environment",
+    description: "Update the configuration of a tenant-owned cloud environment. Built-in environments are read-only. Package installation and limited networking are applied when a session's sandbox is created. Omitted fields keep their value.",
     http: "POST",
     path: "/agent/v1/environments/{environment_id}",
     streaming: "no",
@@ -1233,6 +1375,8 @@ owning account only.`
   {
     resource: "agent.environments",
     method: "archive",
+    summary: "Archive environment",
+    description: "Soft-archive a tenant-owned cloud environment so it can no longer be used to create new sessions. Built-in environments are read-only and cannot be archived.",
     http: "POST",
     path: "/agent/v1/environments/{environment_id}/archive",
     streaming: "no",
@@ -1248,6 +1392,8 @@ owning account only.`
   {
     resource: "agent.sessions",
     method: "list",
+    summary: "List sessions",
+    description: "List sessions of the workspace behind your API key, newest first, in pages of at most 100 (default 20). Unlike Anthropic Managed Agents, only limit, page, agent_id and deployment_id are honored; the other filters declared here (agent_version, created_at ranges, memory_store_id, include_archived, order, statuses) are not supported and return 400. Use the returned id with sessions.retrieve or sessions.events.list; pass next_page as page for the next page.",
     http: "GET",
     path: "/agent/v1/sessions",
     streaming: "no",
@@ -1352,6 +1498,8 @@ owning account only.`
   {
     resource: "agent.sessions",
     method: "create",
+    summary: "Create session",
+    description: `Create a session: one conversation with an agent, running on a machine. Pass agent as an agent id (latest version) or {id, version, type:"agent"}. Unlike Anthropic Managed Agents, omit environment_id to get a light machine, unless computer_id (explicit, or the agent's default) selects a Computer; pass environment_id for a sandbox recipe. Optional model must be one of the agent's allowed models; optional thinking is {effort: low|medium|high|xhigh|none} or null, where null inherits the agent default and then the model default (none requires the model to allow disabling thinking). Selections are saved before initial_events run; invalid ones return 400 invalid_request_error. Inline agent overrides are not supported. Supports vault_ids, up to 50, owned by the current organization and not archived; credential injection is deferred to a later version. Omitted budget defaults to USD 20; null removes the limit, and a limit object uses a positive integer string of USD cents. Up to 500 file resources can be attached. Use initial_events to send a first user.message in this request, or send messages afterwards with sessions.events.send. The returned status can still be idle before initial events run; read agent.message and the subsequent session.status_idle event to confirm completion.`,
     http: "POST",
     path: "/agent/v1/sessions",
     streaming: "no",
@@ -1454,6 +1602,8 @@ offsets ("+08:00") and unknown names return 400. Never stored in
   {
     resource: "agent.sessions",
     method: "retrieve",
+    summary: "Get session",
+    description: "Read one session by id: its agent snapshot, status, model and thinking selection, resources, title, metadata and, for a fork, forked_from. Use it to poll status; to read what happened use sessions.events.list. This response does not include a machine object or sandbox id. With no environment_id or Computer selected at creation, the session starts on a light machine; no environment lookup or provisioning is needed for a codemode calculation.",
     http: "GET",
     path: "/agent/v1/sessions/{session_id}",
     streaming: "no",
@@ -1469,6 +1619,8 @@ offsets ("+08:00") and unknown names return 400. Never stored in
   {
     resource: "agent.sessions",
     method: "update",
+    summary: "Update session",
+    description: "Update a session's title, metadata, model or thinking selection. metadata follows patch semantics: a string value sets the key, null deletes it, a null metadata clears all keys, untouched keys stay. model must be allowed by the session's agent version; thinking is {effort} or null (null restores inheritance); a model-only change clears a session thinking that the new model does not support, and combined changes are validated against the new model, with the previous selection kept on a 400. Changes apply from the next turn, not to a turn already running. Agent overrides are not supported (400 naming the field). Supports vault_ids, up to 50, owned by the current organization and not archived; credential injection is deferred to a later version. A budget limit must exceed consumed cost; null removes it permanently for this session. Updating an archived session returns 409.",
     http: "POST",
     path: "/agent/v1/sessions/{session_id}",
     streaming: "no",
@@ -1533,6 +1685,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "agent.sessions",
     method: "archive",
+    summary: "Archive session",
+    description: "Archive a session. An archived session refuses new messages with 400 invalid_request_error, while its details and event history stay readable. Archiving again is idempotent and archived_at keeps the first archive time. Use it when a conversation is finished; it does not delete anything.",
     http: "POST",
     path: "/agent/v1/sessions/{session_id}/archive",
     streaming: "no",
@@ -1548,6 +1702,10 @@ delete it. Omit the field to preserve.`
   {
     resource: "agent.sessions.backgroundTasks",
     method: "list",
+    summary: "List Session Background Tasks (Extension)",
+    description: `List running and ended background tasks for a session.
+
+Own-face extension. Returns { data: BackgroundTask[] }. Each task has id, kind, title, thread_id, status, started_at, ended_at, cancellable, notified_at and trigger_count. Subagent rows link to their child thread via thread_id; other kinds have null. kind is an open string; tolerate unknown kinds. Status is running, result_pending, completed, failed, cancelled or lost. Only completed tasks with pending delivery are result_pending. Timestamps are RFC3339; ended_at is null while running. notified_at is the admission time of the latest system notification batch, or null. trigger_count counts admitted monitor event batches, or is null without records and for other kinds. Only supported running tasks without stop intent are cancellable. Missing or inaccessible sessions return 404.`,
     http: "GET",
     path: "/agent/v1/sessions/{session_id}/background_tasks",
     streaming: "no",
@@ -1563,6 +1721,10 @@ delete it. Omit the field to preserve.`
   {
     resource: "agent.sessions.backgroundTasks",
     method: "retrieveOutput",
+    summary: "Get Background Task Output (Extension)",
+    description: `Read a byte page of task output without waking the sandbox.
+
+Own-face extension. offset defaults to 0; max_bytes defaults to 65536 and must be between 1 and 262144. Returns text, next_offset and eof. Offsets count UTF-8 bytes, not characters; partial trailing characters are retained for the next read. eof describes the current log, which may grow while running. A paused or missing sandbox returns empty text, the original offset, eof=true and unavailable=true, without waking it. Reading does not acknowledge model result delivery. Missing or inaccessible sessions or tasks return 404; invalid ranges return 400.`,
     http: "GET",
     path: "/agent/v1/sessions/{session_id}/background_tasks/{task_id}/output",
     streaming: "no",
@@ -1595,6 +1757,10 @@ delete it. Omit the field to preserve.`
   {
     resource: "agent.sessions.backgroundTasks",
     method: "stop",
+    summary: "Stop Background Task (Extension)",
+    description: `Request termination of a running task and return its current state.
+
+Own-face extension. No request body is required. Uses the same stop implementation as TaskStop: records stop_requested_at and signals the process group. Returns BackgroundTask with the same fields as the list operation. Until termination is observed, status may remain running with cancellable=false. An ended or unsupported task returns 409. Missing or inaccessible sessions or tasks return 404.`,
     http: "POST",
     path: "/agent/v1/sessions/{session_id}/background_tasks/{task_id}/stop",
     streaming: "no",
@@ -1614,6 +1780,10 @@ delete it. Omit the field to preserve.`
   {
     resource: "agent.sessions",
     method: "compact",
+    summary: "Compact Session (Extension)",
+    description: `Request session context compaction and retrieve an operation receipt.
+
+Available only on /agent/v1. The body may be omitted or {}. Optional instructions must be a string and is forwarded unchanged. Idempotency-Key is forwarded unchanged; a UUID is generated when absent. Returns { type: session_compaction, id, status, reason? }, where id is the operation ID. queued/running return 202; skipped/succeeded/failed return 200. Non-string instructions return 400 invalid_request_error. Missing or inaccessible managed sessions return 404 not_found_error.`,
     http: "POST",
     path: "/agent/v1/sessions/{session_id}/compact",
     streaming: "no",
@@ -1640,6 +1810,10 @@ delete it. Omit the field to preserve.`
   {
     resource: "agent.sessions",
     method: "retrieveCompact",
+    summary: "Get Session Compaction (Extension)",
+    description: `Read session compaction status by operation ID.
+
+Available only on /agent/v1. Returns { type: session_compaction, id, status, reason? } with HTTP 200 for every status. A missing operation or inaccessible session returns 404 not_found_error.`,
     http: "GET",
     path: "/agent/v1/sessions/{session_id}/compact/{operation_id}",
     streaming: "no",
@@ -1659,6 +1833,10 @@ delete it. Omit the field to preserve.`
   {
     resource: "agent.sessions.compactions",
     method: "list",
+    summary: "List Session Compactions (Extension)",
+    description: `Read session compaction history and summaries.
+
+Available only on /agent/v1. Returns { data: [...] }. Each entry contains type, id, event_id, trigger, status, model, compacted_message_count, input_tokens_before, input_tokens_after, summary, error and created_at, as recorded by the service. Missing or inaccessible managed sessions return 404 not_found_error.`,
     http: "GET",
     path: "/agent/v1/sessions/{session_id}/compactions",
     streaming: "no",
@@ -1674,6 +1852,10 @@ delete it. Omit the field to preserve.`
   {
     resource: "agent.sessions",
     method: "retrieveContext",
+    summary: "Get Session Context (Extension)",
+    description: `Read the latest context measurement and the currently selected model’s window and compaction thresholds.
+
+Praxis extension available only on /agent/v1, following Claude Agent SDK getContextUsage() with snake_case fields. detail is summary: the latest actual model usage takes precedence, and local estimates apportion source totals; used categories sum to total_tokens. Only nonzero sources appear. Classify rows by kind (used/free/buffer/deferred). key is a stable source identifier extension; clients must tolerate unknown keys and new sources, falling back to name. MCP tools group by server, plugin blocks by id, and compaction summaries are counted separately. excluded_items is currently zero. Before measurement, total_tokens, total_tokens_source and measured_at are null, categories is empty, and details are zero or empty arrays. Model selection recalculates max_tokens, auto_compact_threshold and free/buffer while preserving the latest measurement. is_auto_compact_enabled is false for unknown capacity or a tripped compaction breaker. For example model.thinking is {efforts: [high, xhigh], can_disable: true, default_effort: high}. model.thinking contains efforts, can_disable and nullable default_effort; the entire thinking value is null when capability is unknown. Missing or inaccessible sessions return 404.`,
     http: "GET",
     path: "/agent/v1/sessions/{session_id}/context",
     streaming: "no",
@@ -1689,6 +1871,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "agent.sessions.events",
     method: "list",
+    summary: "List session events",
+    description: "Read the event history of a session as a page of events, oldest first by default (order=desc for newest first). Use it after sending a message to collect the reply, to find tool calls that wait for approval (session.status_idle with stop_reason requires_action lists their event_ids), or to audit a run; to follow a running session live use sessions.events.stream instead. Filter by types and by a created_at range on processed_at; pages hold at most 100 events (default 20) and next_page continues. A failed run emits session.error before session.status_terminated. Native history also includes user.steer, user.withdraw, system.notification, session.forked, session.goal_changed and session.goal_verification; these are not accepted by the /anthropic/v1 event-type filter.",
     http: "GET",
     path: "/agent/v1/sessions/{session_id}/events",
     streaming: "no",
@@ -1758,6 +1942,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "agent.sessions.events",
     method: "send",
+    summary: "Send session events",
+    description: 'Send events to a session: user.message (exactly one nonempty text block), user.interrupt, user.tool_confirmation to allow or deny a pending tool call, user.steer to inject a queued user.message into a turn that is still running, and user.withdraw to retract a queued message. The response only acknowledges the inputs; read replies with sessions.events.list or sessions.events.stream. A message sent while the session waits for tool approval is queued (processed_at null) and runs in order after the approval is resolved. Archived sessions reject new messages. To approve, read a pending agent.tool_use or agent.mcp_tool_use event and send {type: "user.tool_confirmation", tool_use_id: <that event id>, result: "allow"} (or deny); include session_thread_id for a child approval. Native confirmations also accept updated_permissions, answers and annotations, which /anthropic/v1 rejects.',
     http: "POST",
     path: "/agent/v1/sessions/{session_id}/events",
     streaming: "no",
@@ -1785,6 +1971,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "agent.sessions.events",
     method: "stream",
+    summary: "Stream session events",
+    description: "Open a Server-Sent Events stream of a session's events in real time. Use it to show a reply as it is produced; to read past events use sessions.events.list. Send a message through sessions.events.send in another request while the stream is open. Closing the stream only drops your subscription and does not stop the agent. Pass event_deltas[]=agent.message, agent.thinking or agent.tool_use to also receive event_start / event_delta previews before the final event.",
     http: "GET",
     path: "/agent/v1/sessions/{session_id}/events/stream",
     streaming: "always",
@@ -1812,6 +2000,10 @@ delete it. Omit the field to preserve.`
   {
     resource: "agent.sessions",
     method: "fork",
+    summary: "Fork Session (Extension)",
+    description: `Create an independent session at the last assistant message of a successfully completed turn.
+
+Available only on /agent/v1. Use the message_id field from own-face events, not the event id. Copies every message and part through the target, including tool calls and results. The parent is unchanged; another running turn does not prevent forking an earlier completed turn. The new root session appears in the session list with the same agent version, current model and thinking settings, and cwd working directory. Its title is the parent title plus “ 的分支”. If the parent has a sandbox, the new session owns an independent fork including a memory snapshot. Inherited running tasks are terminated, ring targets are replaced with the new session only, and its background-task table starts empty. Without a parent sandbox, creation remains lazy. Returns 201 with the same Session shape as retrieval. forked_from is {session_id, message_id}, or null for ordinary sessions. Imported history ends with session.forked containing forked_from_session_id and forked_from_message_id. These fields and this event are own-face only. Invalid requests return 400; ineligible targets return 409 FORK_TARGET_INVALID; missing sessions or sessions belonging to another caller return 404. Initialization failures leave the child unpublished and reclaim the forked sandbox.`,
     http: "POST",
     path: "/agent/v1/sessions/{session_id}/fork",
     streaming: "no",
@@ -1838,6 +2030,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "agent.sessions.resources",
     method: "list",
+    summary: "List session resources",
+    description: "List the extra resources (file references) attached to a session, oldest first, at most 1000 per page (default 1000). Use the returned id with sessions.resources.retrieve or sessions.resources.delete; next_page continues a truncated list.",
     http: "GET",
     path: "/agent/v1/sessions/{session_id}/resources",
     streaming: "no",
@@ -1866,6 +2060,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "agent.sessions.resources",
     method: "create",
+    summary: "Add session resource",
+    description: "Attach a file resource to a session by file_id, up to 500 per session. The file must exist and belong to your tenant. It is mounted under /mnt/session/uploads/<file_id> unless mount_path is given; custom paths are rooted there and parent traversal is rejected. File content is immutable through this API, and synchronizing it into a running sandbox is not implemented in this version.",
     http: "POST",
     path: "/agent/v1/sessions/{session_id}/resources",
     streaming: "no",
@@ -1908,6 +2104,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "agent.sessions.resources",
     method: "delete",
+    summary: "Delete session resource",
+    description: "Detach a resource from a session. Only the reference is removed; the underlying file is not deleted. The response is {id, type: session_resource_deleted}. resource_id comes from sessions.resources.list or the add call.",
     http: "DELETE",
     path: "/agent/v1/sessions/{session_id}/resources/{resource_id}",
     streaming: "no",
@@ -1935,6 +2133,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "agent.sessions.resources",
     method: "retrieve",
+    summary: "Get session resource",
+    description: "Read one resource attached to a session: its type, file_id, mount_path and timestamps. resource_id comes from sessions.resources.list or sessions.resources.add.",
     http: "GET",
     path: "/agent/v1/sessions/{session_id}/resources/{resource_id}",
     streaming: "no",
@@ -1959,9 +2159,78 @@ delete it. Omit the field to preserve.`
       }
     ]
   },
+  {
+    resource: "agent.sessions.runs",
+    method: "deleteFeedback",
+    summary: "Delete Run Feedback",
+    description: `Remove the rating and comment for a run.
+
+Own-face extension. Use the session id from session creation or listing and the run_id from its events. Requires a readable session and a run belonging to it. Idempotent; returns 204 even when no feedback exists. End users can delete feedback only for their own sessions. Does not delete the run or messages, enter model context, or start another run.`,
+    http: "DELETE",
+    path: "/agent/v1/sessions/{session_id}/runs/{run_id}/feedback",
+    streaming: "no",
+    pagination: false,
+    pathParams: [
+      {
+        name: "session_id",
+        sdkName: "session_id"
+      },
+      {
+        name: "run_id",
+        sdkName: "run_id"
+      }
+    ],
+    query: []
+  },
+  {
+    resource: "agent.sessions.runs.feedback",
+    method: "create",
+    summary: "Set Run Feedback",
+    description: `Submit thumbs up or thumbs down for a run, with an optional comment.
+
+Own-face extension. Use a readable session and a run_id from its events. Each submission replaces the previous rating and comment; omitted or null comment clears it, while created_at is preserved. Comments allow at most 2000 Unicode characters. End users can submit only for their own sessions. Feedback never enters model context or starts a run. For example, submit {"rating":"positive","comment":"Helpful"}. POST follows Managed Agents resource update conventions; the resource remains unique per session and run.`,
+    http: "POST",
+    path: "/agent/v1/sessions/{session_id}/runs/{run_id}/feedback",
+    streaming: "no",
+    pagination: false,
+    pathParams: [
+      {
+        name: "session_id",
+        sdkName: "session_id"
+      },
+      {
+        name: "run_id",
+        sdkName: "run_id"
+      }
+    ],
+    query: [],
+    body: {
+      required: true,
+      fields: [
+        {
+          name: "rating",
+          type: "string",
+          enum: [
+            "positive",
+            "negative"
+          ],
+          required: true,
+          description: "positive means thumbs up; negative means thumbs down for this run."
+        },
+        {
+          name: "comment",
+          type: "string",
+          required: false,
+          description: "Optional comment, at most 2000 Unicode characters. Omit or send null to clear the previous comment."
+        }
+      ]
+    }
+  },
   {
     resource: "agent.sessions.threads",
     method: "list",
+    summary: "List session threads",
+    description: "List the execution threads of a session: the primary thread plus every child thread started by subagents or advisors, in created_at order. Child threads reference the primary through parent_thread_id. Pages hold at most 100 threads (default 20). Use a thread id with sessions.threads.retrieve, sessions.threads.events.list or sessions.threads.events.stream.",
     http: "GET",
     path: "/agent/v1/sessions/{session_id}/threads",
     streaming: "no",
@@ -1990,6 +2259,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "agent.sessions.threads",
     method: "retrieve",
+    summary: "Get session thread",
+    description: "Read one execution thread of a session, field for field the same as its list item. Thread ids that are unknown, malformed or belong to another session all return 404, so existence is not revealed. thread_id comes from sessions.threads.list or from the session_thread_id of a session.thread_created event.",
     http: "GET",
     path: "/agent/v1/sessions/{session_id}/threads/{thread_id}",
     streaming: "no",
@@ -2017,6 +2288,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "agent.sessions.threads",
     method: "archive",
+    summary: "Archive session thread",
+    description: "Archive one execution thread. Archiving the primary thread archives the session; archiving a child archives only that child, leaving the parent and its siblings untouched. An archived child has status terminated and archived_at set, receives no new events and keeps its history readable.",
     http: "POST",
     path: "/agent/v1/sessions/{session_id}/threads/{thread_id}/archive",
     streaming: "no",
@@ -2044,6 +2317,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "agent.sessions.threads.events",
     method: "list",
+    summary: "List session thread events",
+    description: "Read the event history of one execution thread: the session itself for the primary thread, or the child session for a child thread. It accepts the same filters, ordering and paging as sessions.events.list and returns the same data + next_page envelope. Child approvals carry session_thread_id so you can route a confirmation to the owning thread.",
     http: "GET",
     path: "/agent/v1/sessions/{session_id}/threads/{thread_id}/events",
     streaming: "no",
@@ -2083,6 +2358,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "agent.sessions.threads",
     method: "stream",
+    summary: "Stream session thread events",
+    description: "Open a Server-Sent Events stream of one execution thread's live events, using the same implementation as sessions.events.stream; a read-only WebSocket is also available on this path. The parent session stream additionally carries child creation, status and message events. Pass event_deltas[]=agent.message, agent.thinking or agent.tool_use for incremental previews.",
     http: "GET",
     path: "/agent/v1/sessions/{session_id}/threads/{thread_id}/stream",
     streaming: "always",
@@ -2121,6 +2398,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "agent.toolsets",
     method: "list",
+    summary: "List Toolsets",
+    description: "Discover tool names, input schemas, read-only status and default permission policies before configuring an agent. The catalog is read-only: enable tools through agents.create or agents.update. agent_toolset_20260401 includes bash, edit, glob, grep, read, write, web_search, web_fetch, task_output, task_stop, monitor, agent, send_message, codemode and skill, plus todo_write, enter_plan_mode, ask_user_question and goal_read, which are listed so they can be switched off. Native additions require bash enabled; codemode requires bash (enabling it with bash disabled returns 400; keep bash enabled with permission_policy always_ask to restrict it); send_message also requires agent. To keep only some tools, set default_config.enabled to false and enable the wanted tools in configs; unlisted tools follow default_config. The catalog includes plugin names and versions. Sessions created through /anthropic/v1 expose only the eight official tools.",
     http: "GET",
     path: "/agent/v1/toolsets",
     streaming: "no",
@@ -2131,6 +2410,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "application.assets.upload",
     method: "create",
+    summary: "Upload assets",
+    description: "Upload one batch: files maps hash to base64 content. The last batch returns the completion token.",
     http: "POST",
     path: "/application/v1/assets/upload",
     streaming: "no",
@@ -2158,6 +2439,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "application.subdomain",
     method: "retrieve",
+    summary: "Get account subdomain",
+    description: "Return the account subdomain used in every Worker URL. A default is created on first use.",
     http: "GET",
     path: "/application/v1/subdomain",
     streaming: "no",
@@ -2168,6 +2451,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "application.subdomain",
     method: "update",
+    summary: "Change account subdomain",
+    description: "Change the account subdomain. Every Worker moves to the new address at once; old addresses stop resolving.",
     http: "PUT",
     path: "/application/v1/subdomain",
     streaming: "no",
@@ -2189,6 +2474,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "application.workers",
     method: "list",
+    summary: "List Workers",
+    description: "List Workers in your account. Filter by status or by label with label.<key>=<value>.",
     http: "GET",
     path: "/application/v1/workers",
     streaming: "no",
@@ -2218,6 +2505,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "application.workers",
     method: "create",
+    summary: "Create Worker",
+    description: "Create a Worker. It serves nothing until a version is deployed.",
     http: "POST",
     path: "/application/v1/workers",
     streaming: "no",
@@ -2264,6 +2553,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "application.workers",
     method: "delete",
+    summary: "Delete Worker",
+    description: "Soft-delete a Worker. Unlike Cloudflare, deletion is reversible: it stops serving at once and can be restored with RestoreWorker for 7 days, after which it is purged.",
     http: "DELETE",
     path: "/application/v1/workers/{worker_id}",
     streaming: "no",
@@ -2279,6 +2570,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "application.workers",
     method: "retrieve",
+    summary: "Get Worker",
+    description: "Get a Worker. expand returns related objects in the same response.",
     http: "GET",
     path: "/application/v1/workers/{worker_id}",
     streaming: "no",
@@ -2301,6 +2594,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "application.workers",
     method: "update",
+    summary: "Update Worker",
+    description: "Change name, tags, observability, subdomain or labels. Omitted fields stay unchanged.",
     http: "PATCH",
     path: "/application/v1/workers/{worker_id}",
     streaming: "no",
@@ -2352,6 +2647,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "application.workers.assetsUploadSession",
     method: "create",
+    summary: "Create asset upload session",
+    description: "Declare the static file manifest. The answer lists the hashes still missing, grouped into upload batches, and an upload token.",
     http: "POST",
     path: "/application/v1/workers/{worker_id}/assets-upload-session",
     streaming: "no",
@@ -2378,6 +2675,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "application.workers.components",
     method: "list",
+    summary: "List components",
+    description: "List the databases, namespaces and buckets this Worker owns.",
     http: "GET",
     path: "/application/v1/workers/{worker_id}/components",
     streaming: "no",
@@ -2393,6 +2692,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "application.workers.deployments",
     method: "list",
+    summary: "List deployments",
+    description: "List the deployments of a Worker, newest first; the first active one is serving. Page with next_cursor.",
     http: "GET",
     path: "/application/v1/workers/{worker_id}/deployments",
     streaming: "no",
@@ -2421,6 +2722,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "application.workers.deployments",
     method: "create",
+    summary: "Create deployment",
+    description: "Deploy one version to serve the Worker. Unlike Cloudflare, a deployment holds exactly one version at 100 percent (no gradual rollout), so strategy must be percentage. Deployment is asynchronous; poll the deployment until praxis.status is active or failed.",
     http: "POST",
     path: "/application/v1/workers/{worker_id}/deployments",
     streaming: "no",
@@ -2469,6 +2772,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "application.workers.deployments",
     method: "retrieve",
+    summary: "Get deployment",
+    description: "Get one deployment with its status and upload progress; poll this after CreateDeployment until praxis.status is active or failed.",
     http: "GET",
     path: "/application/v1/workers/{worker_id}/deployments/{deployment_id}",
     streaming: "no",
@@ -2488,6 +2793,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "application.workers.events",
     method: "list",
+    summary: "List events",
+    description: "List lifecycle events of a Worker in sequence order.",
     http: "GET",
     path: "/application/v1/workers/{worker_id}/events",
     streaming: "no",
@@ -2516,6 +2823,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "application.workers.grants",
     method: "list",
+    summary: "List grants",
+    description: "List resources this Worker's platform token may access.",
     http: "GET",
     path: "/application/v1/workers/{worker_id}/grants",
     streaming: "no",
@@ -2531,6 +2840,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "application.workers.grants",
     method: "create",
+    summary: "Create grant",
+    description: "Let this Worker's platform token access one of your databases, folders or knowledge bases.",
     http: "POST",
     path: "/application/v1/workers/{worker_id}/grants",
     streaming: "no",
@@ -2567,6 +2878,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "application.workers.grants",
     method: "delete",
+    summary: "Delete grant",
+    description: "Revoke a grant so this Worker's platform token can no longer access the granted resource. Takes effect for new requests at once.",
     http: "DELETE",
     path: "/application/v1/workers/{worker_id}/grants/{grant_id}",
     streaming: "no",
@@ -2586,6 +2899,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "application.workers",
     method: "restore",
+    summary: "Restore Worker",
+    description: "Bring back a soft-deleted Worker within 7 days of deletion, with its versions and deployments. Cloudflare has no equivalent.",
     http: "POST",
     path: "/application/v1/workers/{worker_id}/restore",
     streaming: "no",
@@ -2601,6 +2916,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "application.workers.secrets",
     method: "list",
+    summary: "List secrets",
+    description: "List secret names and sources. Values are never returned.",
     http: "GET",
     path: "/application/v1/workers/{worker_id}/secrets",
     streaming: "no",
@@ -2616,6 +2933,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "application.workers.secrets",
     method: "delete",
+    summary: "Delete secret",
+    description: "Delete a secret. Unlike Cloudflare, this derives a new version without it and deploys that version.",
     http: "DELETE",
     path: "/application/v1/workers/{worker_id}/secrets/{name}",
     streaming: "no",
@@ -2635,6 +2954,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "application.workers.secrets",
     method: "update",
+    summary: "Put secret",
+    description: "Create or replace a secret by value or vault reference. Unlike Cloudflare, this derives a new version from the current one and deploys it, so the change is live only once that deployment is active.",
     http: "PUT",
     path: "/application/v1/workers/{worker_id}/secrets/{name}",
     streaming: "no",
@@ -2665,6 +2986,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "application.workers.versions",
     method: "list",
+    summary: "List versions",
+    description: "List the versions of a Worker, newest first, to pick one to deploy or inspect. Page with next_cursor.",
     http: "GET",
     path: "/application/v1/workers/{worker_id}/versions",
     streaming: "no",
@@ -2693,6 +3016,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "application.workers.versions",
     method: "create",
+    summary: "Create version",
+    description: "Upload code and bindings as a new version; a version serves nothing until deployed. Set deploy true to create the pending deployment in the same call. Rejected binding types return UNSUPPORTED.",
     http: "POST",
     path: "/application/v1/workers/{worker_id}/versions",
     streaming: "no",
@@ -2770,6 +3095,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "application.workers.versions",
     method: "retrieve",
+    summary: "Get version",
+    description: "Get one version of a Worker with its modules, bindings and asset settings; secret values are never returned.",
     http: "GET",
     path: "/application/v1/workers/{worker_id}/versions/{version_id}",
     streaming: "no",
@@ -2789,6 +3116,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "automation.actions",
     method: "list",
+    summary: "List actions",
+    description: "Discover callable Actions and their ns/name references without executing them. Combine each returned namespace and name as ns/name; Action calls use the current revision and do not accept @version or @tag. Filter by name or description; results include seven-day statistics and revision summaries without implementation source. Archived actions are excluded by default.",
     http: "GET",
     path: "/automation/v1/actions",
     streaming: "no",
@@ -2872,6 +3201,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "automation.actions",
     method: "create",
+    summary: "Create an action",
+    description: "Create an action definition and its first revision, folding names to lowercase. Duplicate names within the tenant return NAME_TAKEN; the praxis namespace is read-only.",
     http: "POST",
     path: "/automation/v1/actions",
     streaming: "no",
@@ -2954,6 +3285,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "automation.actions",
     method: "retrieve",
+    summary: "Get an action",
+    description: "Read the action and its full current implementation. The response ETag is the current revision ID for conditional updates.",
     http: "GET",
     path: "/automation/v1/actions/{ns}/{name}",
     streaming: "no",
@@ -2973,6 +3306,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "automation.actions",
     method: "update",
+    summary: "Update an action",
+    description: "Update after checking compatibility against the current and five recent revisions. Widening inputs and narrowing outputs are compatible, including length, item count, property count, type (integer/number), and multipleOf (the new input factor divides the old one; the reverse holds for outputs). dry_run=true returns only CompatResult and may omit If-Match; a supplied header is still checked, and * matches any existing representation. Normal updates require If-Match and return ActionDef with ETag; previews return no ETag. Omitted optional fields retain their existing values only for description and labels; when constructing a new revision, errors defaults to [], omitted annotations keys to false, timeout_ms to 30000, and message to null. Incompatible normal updates return 422 SCHEMA_INCOMPATIBLE with issues; unchanged contents retain the existing revision.",
     http: "PUT",
     path: "/automation/v1/actions/{ns}/{name}",
     streaming: "no",
@@ -3059,6 +3394,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "automation.actions",
     method: "archive",
+    summary: "Archive an action",
+    description: "Archive the action while retaining its name and history, hiding it from the default list. The response includes dependents_count.",
     http: "POST",
     path: "/automation/v1/actions/{ns}/{name}/archive",
     streaming: "no",
@@ -3082,6 +3419,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "automation.actions.dependents",
     method: "list",
+    summary: "List action dependents",
+    description: "List orchestrations referencing this action. The search covers scripts and workflows in their drafts or latest versions.",
     http: "GET",
     path: "/automation/v1/actions/{ns}/{name}/dependents",
     streaming: "no",
@@ -3114,6 +3453,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "automation.actions.invocations",
     method: "list",
+    summary: "List action invocations",
+    description: "List this action’s invocations, filtering by status, revision, calling definition and time. Results identify the run and call site.",
     http: "GET",
     path: "/automation/v1/actions/{ns}/{name}/invocations",
     streaming: "no",
@@ -3187,6 +3528,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "automation.actions",
     method: "restore",
+    summary: "Restore an action",
+    description: "Restore an archived action to the default list. Its current revision is preserved.",
     http: "POST",
     path: "/automation/v1/actions/{ns}/{name}/restore",
     streaming: "no",
@@ -3210,6 +3553,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "automation.actions.revisions",
     method: "list",
+    summary: "List action revisions",
+    description: "List revisions newest first with rollback eligibility. Results include the current marker and compatibility issues. Lists omit source by default; only expand=source includes full source, and other values return 400. Detail endpoints retain full source.",
     http: "GET",
     path: "/automation/v1/actions/{ns}/{name}/revisions",
     streaming: "no",
@@ -3251,6 +3596,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "automation.actions.revisions",
     method: "retrieve",
+    summary: "Get an action revision",
+    description: "Read a specific revision with its full implementation and rollback compatibility result. A missing revision returns VERSION_NOT_FOUND. Details always return full source.",
     http: "GET",
     path: "/automation/v1/actions/{ns}/{name}/revisions/{revision}",
     streaming: "no",
@@ -3274,6 +3621,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "automation.actions",
     method: "rollback",
+    summary: "Roll back an action",
+    description: "Create a compatible new revision from historical contents. Compatibility is checked against the current and five recent historical revisions. The current pointer does not revert to the old ID. Optional If-Match accepts the current revision or *; * matches any existing representation.",
     http: "POST",
     path: "/automation/v1/actions/{ns}/{name}/rollback",
     streaming: "no",
@@ -3310,6 +3659,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "automation.hooks",
     method: "send",
+    summary: "Receive a webhook",
+    description: "No API key is needed: the URL token authenticates requests. Invalid tokens, absent triggers, wrong kinds and inactive time windows return 404; a paused trigger (circuit breaker after 5 consecutive failures, or manual pause) returns 409 TRIGGER_PAUSED whose message gives the reason and whose hint gives the way back, POST /automation/v1/triggers/{id}/resume. Raw bodies are limited to 512 KiB; serialized run input, including raw and parsed copies, must fit within 1 MiB. Exceeding either limit returns 413 synchronously without recording a firing; webhook-id deduplicates for 24 hours. A 202 with outcome=accepted acknowledges receipt; the final outcome is updated later, and repeats return deduped. Invalid JSON yields body=null; other UTF-8 is text and non-UTF-8 is base64. The envelope contains body, raw_body, raw_body_encoding, allowlisted headers, webhook_id and received_at. raw_body preserves exact bytes with utf8 or base64 encoding for caller-side signature verification.",
     http: "POST",
     path: "/automation/v1/hooks/{trigger_id}/{token}",
     streaming: "no",
@@ -3333,6 +3684,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "automation.resolve",
     method: "retrieve",
+    summary: "Resolve a run target",
+    description: "Resolve ns/name@tag, an exact version or a version range to a runnable exact version. Omitting @ selects latest; archived targets are rejected and no match returns NO_MATCHING_VERSION.",
     http: "GET",
     path: "/automation/v1/resolve",
     streaming: "no",
@@ -3350,6 +3703,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "automation.runs",
     method: "list",
+    summary: "List runs",
+    description: "Filter tenant runs and list them newest first. Filters include multiple statuses, target, origin, labels[k] and a creation-time lower bound. q matches a run ID exactly when it starts with run_; otherwise it matches a definition-name prefix. Large input/output values are null in lists with input_truncated/output_truncated true; get run details for full values.",
     http: "GET",
     path: "/automation/v1/runs",
     streaming: "no",
@@ -3505,6 +3860,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "automation.runs",
     method: "create",
+    summary: "Create a run",
+    description: "Execute a published script or workflow with target, or test unpublished code directly with source and language (ts for TypeScript, yaml for workflow YAML), without first saving or publishing a definition. target and source are mutually exclusive; target accepts ns/name@version, @tag or @range and defaults to latest when @ is omitted. Source/input validation precedes run creation, so a separate validate call is optional. input defaults to {} and must match the input schema and fit within 1 MiB. wait is 0–60 seconds (default 0): a terminal run returns 200, otherwise 202. Use the returned id with praxis.automation.runs.retrieve and inspect status, output and error; acceptance does not mean successful completion. Idempotency-Key is scoped to tenant, method and path for 24 hours, excluding wait from the fingerprint; replay returns the current run with Idempotent-Replayed: true, changed contents return 422 and an in-flight request returns 409. New non-deterministic run IDs contain 78 characters (run_ + 10-character base36 millisecond timestamp + 64-character hexadecimal DO ID), compared with 46 for legacy random IDs. Historical and deterministic IDs remain valid; same-millisecond order is not guaranteed. Minimal body: {\"source\":\"export default async () => ({ok: true});\",\"language\":\"ts\",\"wait\":10}.",
     http: "POST",
     path: "/automation/v1/runs",
     streaming: "no",
@@ -3519,6 +3876,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "automation.runs",
     method: "retrieve",
+    summary: "Get a run",
+    description: "Read status, output and error for the id returned by praxis.automation.runs.create; output needs no expand option. A completed status confirms success; faulted and cancelled are terminal without successful completion. Optionally expand calls, tasks, task groups, logs or source in the same request. Pass wait (seconds, 0–60) to hold the request until the run is terminal or the time is up, instead of polling. Expanded pages hold at most 200 entries; use the ledger endpoints and cursors for subsequent pages. Workflow raise errors preserve the full type URI, status, title and detail; only internal platform exceptions are runtime errors.",
     http: "GET",
     path: "/automation/v1/runs/{id}",
     streaming: "no",
@@ -3555,6 +3914,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "automation.runs.artifacts",
     method: "list",
+    summary: "List run artifacts",
+    description: "Read run artifacts and their file references. Entries follow ledger order and include content types, sizes and associated steps.",
     http: "GET",
     path: "/automation/v1/runs/{id}/artifacts",
     streaming: "no",
@@ -3583,6 +3944,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "automation.runs.calls",
     method: "list",
+    summary: "List run calls",
+    description: "Page through the call ledger with execution results. Entries follow ledger order and include targets, argument/result previews, statuses and durations. Script runs read the call ledger; a workflow run records its action calls on its tasks, so this lists the action tasks (skipped ones excluded), matching counters.action_calls.",
     http: "GET",
     path: "/automation/v1/runs/{id}/calls",
     streaming: "no",
@@ -3611,6 +3974,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "automation.runs",
     method: "cancel",
+    summary: "Cancel a run",
+    description: "Request run cancellation and return 202. Workflows terminate, while scripts receive an abort request followed by forced termination after a grace period. Terminal runs return 409 RUN_INVALID_STATE; cancellation propagates to attached children, not detached children. Optional reason contains 1–500 characters and is stored as Run.cancel_message; cancel_reason remains user.",
     http: "POST",
     path: "/automation/v1/runs/{id}/cancel",
     streaming: "no",
@@ -3637,6 +4002,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "automation.runs",
     method: "events",
+    summary: "Read run events",
+    description: "Read the CloudEvents ledger or subscribe to live events. Return a CloudEvents ledger page by default; Accept: text/event-stream opens a live stream with ai.praxis.automation.run.status, ai.praxis.automation.run.progress, ai.praxis.automation.call.started, ai.praxis.automation.call.completed, ai.praxis.automation.task.started, ai.praxis.automation.task.completed and ai.praxis.automation.wait.created, ai.praxis.automation.wait.resolved event names. id is the resume cursor and Last-Event-ID takes precedence over cursor; : ping arrives every 20 seconds and event: end closes the stream after a terminal run.",
     http: "GET",
     path: "/automation/v1/runs/{id}/events",
     streaming: "always",
@@ -3665,6 +4032,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "automation.runs",
     method: "logs",
+    summary: "Read run logs",
+    description: "Return a log page within the 30-day retention window by default. Accept: text/event-stream opens a live stream using event: log; id is the resume cursor and Last-Event-ID takes precedence over cursor. : ping arrives every 20 seconds and event: end closes the stream after a terminal run.",
     http: "GET",
     path: "/automation/v1/runs/{id}/logs",
     streaming: "always",
@@ -3693,6 +4062,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "automation.runs",
     method: "rerun",
+    summary: "Rerun a run",
+    description: "Create a new root run from the original exact version or ad hoc source, retaining labels and setting rerun_of. Override input or omit it to reuse the original input; archived targets and run tokens are rejected.",
     http: "POST",
     path: "/automation/v1/runs/{id}/rerun",
     streaming: "no",
@@ -3719,6 +4090,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "automation.runs",
     method: "resume",
+    summary: "Resume a run",
+    description: "Resume only a suspended workflow to its prior running or waiting state. It remains suspended if concurrency slots are unavailable; scripts do not support this operation.",
     http: "POST",
     path: "/automation/v1/runs/{id}/resume",
     streaming: "no",
@@ -3738,6 +4111,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "automation.runs",
     method: "retrieveSource",
+    summary: "Get run source",
+    description: "Read the source and digest used by the run. Results include the language and SHA-256 digest, for both ad hoc and published-definition runs.",
     http: "GET",
     path: "/automation/v1/runs/{id}/source",
     streaming: "no",
@@ -3753,6 +4128,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "automation.runs",
     method: "suspend",
+    summary: "Suspend a run",
+    description: "Suspend only a running or waiting workflow. Scripts return OPERATION_NOT_SUPPORTED; other states return RUN_INVALID_STATE.",
     http: "POST",
     path: "/automation/v1/runs/{id}/suspend",
     streaming: "no",
@@ -3772,6 +4149,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "automation.runs.tasks",
     method: "list",
+    summary: "List run tasks",
+    description: "Page through the task ledger. include=planned adds unexecuted top-level steps; group_by=reference aggregates count, status and duration by task reference.",
     http: "GET",
     path: "/automation/v1/runs/{id}/tasks",
     streaming: "no",
@@ -3818,6 +4197,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "automation.runs.waits",
     method: "list",
+    summary: "List run waits",
+    description: "List current and historical waits in ledger order. Wait types include event, timer and child.",
     http: "GET",
     path: "/automation/v1/runs/{id}/waits",
     streaming: "no",
@@ -3846,6 +4227,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "automation.runs.waits",
     method: "complete",
+    summary: "Complete a run wait",
+    description: "Complete only an event wait with a payload of at most 32 KiB satisfying its filter; timer and child waits cannot be completed manually. Reusing the same id and payload returns replayed=true; other repeats return WAIT_ALREADY_RESOLVED and expired waits return WAIT_EXPIRED.",
     http: "POST",
     path: "/automation/v1/runs/{id}/waits/{wait_id}/complete",
     streaming: "no",
@@ -3882,6 +4265,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "automation.scripts",
     method: "list",
+    summary: "List scripts",
+    description: "List visible script summaries, latest versions, tags and seven-day statistics. Archived entries are excluded by default.",
     http: "GET",
     path: "/automation/v1/scripts",
     streaming: "no",
@@ -3953,6 +4338,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "automation.scripts",
     method: "create",
+    summary: "Create a script",
+    description: 'Save a TypeScript script as an editable draft for later reuse; this does not publish or start a run. Choose your own namespace without registering it first; praxis is read-only. Scripts and workflows share names within the tenant; a duplicate returns NAME_TAKEN. The draft is a source string with a default-exported function, for example `export default async (input: {name: string}) => ({greeting: "Hello, " + input.name});`. To test it, pass that source and language=ts to praxis.automation.runs.create without publishing. To publish later, use the returned draft.revision as expected_draft_revision.',
     http: "POST",
     path: "/automation/v1/scripts",
     streaming: "no",
@@ -3998,6 +4385,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "automation.scripts",
     method: "retrieve",
+    summary: "Get a script",
+    description: "Read script details and draft source. The ETag is the draft revision to use in If-Match for updates.",
     http: "GET",
     path: "/automation/v1/scripts/{ns}/{name}",
     streaming: "no",
@@ -4017,6 +4406,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "automation.scripts",
     method: "update",
+    summary: "Update a script draft",
+    description: "Update description, labels or draft with the current draft revision in If-Match. Even metadata-only updates create a new draft revision.",
     http: "PATCH",
     path: "/automation/v1/scripts/{ns}/{name}",
     streaming: "no",
@@ -4059,6 +4450,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "automation.scripts",
     method: "archive",
+    summary: "Archive a script",
+    description: "Keep the name, versions and draft while archiving. The default list hides it and new target resolution and run requests reject the archived target.",
     http: "POST",
     path: "/automation/v1/scripts/{ns}/{name}/archive",
     streaming: "no",
@@ -4082,6 +4475,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "automation.scripts.distTags",
     method: "list",
+    summary: "List script tags",
+    description: "Read the exact version for each distribution tag. Results include the update time and updater.",
     http: "GET",
     path: "/automation/v1/scripts/{ns}/{name}/dist-tags",
     streaming: "no",
@@ -4101,6 +4496,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "automation.scripts.distTags",
     method: "delete",
+    summary: "Delete a script tag",
+    description: "Delete a distribution tag while retaining versions. latest cannot be deleted, versions and ranges are invalid tags, and deleting an absent valid tag is repeatable.",
     http: "DELETE",
     path: "/automation/v1/scripts/{ns}/{name}/dist-tags/{tag}",
     streaming: "no",
@@ -4124,6 +4521,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "automation.scripts.distTags",
     method: "set",
+    summary: "Set a script tag",
+    description: "Point a distribution tag at an existing exact version; tags cannot be versions or version ranges. Moving latest can roll back a release and synchronizes workflow schedules.",
     http: "PUT",
     path: "/automation/v1/scripts/{ns}/{name}/dist-tags/{tag}",
     streaming: "no",
@@ -4158,6 +4557,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "automation.scripts",
     method: "restore",
+    summary: "Restore a script",
+    description: "Restore an archived definition with its versions and tags. The name is retained.",
     http: "POST",
     path: "/automation/v1/scripts/{ns}/{name}/restore",
     streaming: "no",
@@ -4181,6 +4582,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "automation.scripts.versions",
     method: "list",
+    summary: "List script versions",
+    description: "Page through immutable schemas and locked dependencies in descending semantic-version order. Lists omit source by default; only expand=source includes full source, and other values return 400. Detail endpoints retain full source.",
     http: "GET",
     path: "/automation/v1/scripts/{ns}/{name}/versions",
     streaming: "no",
@@ -4225,6 +4628,8 @@ delete it. Omit the field to preserve.`
     aliases: [
       "publish"
     ],
+    summary: "Publish a script version",
+    description: "Publish a saved definition from its draft or an ad hoc run as a reusable version for named runs or triggers, validating the definition and locking dependencies. To test unpublished code, use praxis.automation.runs.create with source and language instead. Use draft.revision from create or retrieve as expected_draft_revision. The draft must match expected_draft_revision; an ad hoc run requires from_run and expected_source_sha256. The same version and contents return the existing version; different contents return VERSION_EXISTS, prereleases require an explicit tag (not latest, URL-safe characters only, not a version or range; violations return TAG_REQUIRED or TAG_INVALID with the complete rules in hint), and invalid definitions return DEFINITION_INVALID. Stable releases automatically advance latest only above the highest existing stable version; workflows becoming latest synchronize their declared schedule. Publishing removes +build metadata from the version number.",
     http: "POST",
     path: "/automation/v1/scripts/{ns}/{name}/versions",
     streaming: "no",
@@ -4248,6 +4653,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "automation.scripts.versions",
     method: "retrieve",
+    summary: "Get a script version",
+    description: "Read source, input/output schemas and deprecation details for an exact version. Missing versions return VERSION_NOT_FOUND. Details always return full source. version accepts an exact version or dist-tag; a range returns 400 with a hint to use /resolve.",
     http: "GET",
     path: "/automation/v1/scripts/{ns}/{name}/versions/{version}",
     streaming: "no",
@@ -4271,6 +4678,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "automation.scripts.versions",
     method: "deprecate",
+    summary: "Deprecate a script version",
+    description: "Record a deprecation message; an empty message removes deprecation without changing the version source.",
     http: "POST",
     path: "/automation/v1/scripts/{ns}/{name}/versions/{version}/deprecate",
     streaming: "no",
@@ -4305,6 +4714,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "automation.targets",
     method: "list",
+    summary: "Search automation definitions",
+    description: "Search visible targets and page in ascending name order. Archived targets are excluded by default; optionally select published scripts and workflows.",
     http: "GET",
     path: "/automation/v1/targets",
     streaming: "no",
@@ -4376,6 +4787,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "automation.triggers",
     method: "list",
+    summary: "List triggers",
+    description: "Page through tenant triggers by target, kind and state. ns/name matches all tags or versions of that target; ns/name@spec matches exactly.",
     http: "GET",
     path: "/automation/v1/triggers",
     streaming: "no",
@@ -4447,6 +4860,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "automation.triggers",
     method: "create",
+    summary: "Create a trigger",
+    description: "Schedule recurring or one-time runs, or start runs from a webhook, for a published script or workflow. For one immediate run without a persistent trigger, use praxis.automation.runs.create. There may be at most 100 enabled triggers per tenant. Targets accept only exact versions or tags; webhook_url is returned only when creating a webhook or rotating its URL, so save it securely.",
     http: "POST",
     path: "/automation/v1/triggers",
     streaming: "no",
@@ -4548,6 +4963,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "automation.triggers",
     method: "preview",
+    summary: "Preview a trigger schedule",
+    description: "Validate a schedule and preview up to five future firing times. The timezone is validated and a readable description is returned, without creating a trigger or run.",
     http: "POST",
     path: "/automation/v1/triggers/preview",
     streaming: "no",
@@ -4575,6 +4992,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "automation.triggers",
     method: "delete",
+    summary: "Delete a trigger",
+    description: "Delete the trigger and its firing history, returning 204. Runs already started are unaffected. Definition-managed triggers return 409 TRIGGER_MANAGED; remove schedule from the workflow and publish it again.",
     http: "DELETE",
     path: "/automation/v1/triggers/{id}",
     streaming: "no",
@@ -4590,6 +5009,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "automation.triggers",
     method: "retrieve",
+    summary: "Get a trigger",
+    description: "Read schedule, state, upcoming times and latest firing. Use the ETag to update; the full webhook URL is not returned again.",
     http: "GET",
     path: "/automation/v1/triggers/{id}",
     streaming: "no",
@@ -4605,6 +5026,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "automation.triggers",
     method: "update",
+    summary: "Update a trigger",
+    description: "Update configuration with If-Match matching the current ETag, revalidating target input and schedule. kind is immutable and definition-managed triggers reject updates with TRIGGER_MANAGED.",
     http: "PATCH",
     path: "/automation/v1/triggers/{id}",
     streaming: "no",
@@ -4711,6 +5134,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "automation.triggers",
     method: "fire",
+    summary: "Fire a trigger now",
+    description: "Fire once now and return a Firing, subject to current state, catchup window and overlap rules. Run-launch failures are recorded in the firing error.",
     http: "POST",
     path: "/automation/v1/triggers/{id}/fire",
     streaming: "no",
@@ -4726,6 +5151,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "automation.triggers.firings",
     method: "list",
+    summary: "List trigger firings",
+    description: "Read the last 30 days of firings newest first. Results include resolved versions, run IDs and failure details.",
     http: "GET",
     path: "/automation/v1/triggers/{id}/firings",
     streaming: "no",
@@ -4775,6 +5202,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "automation.triggers",
     method: "pause",
+    summary: "Pause a trigger",
+    description: "Pause new firings without terminating existing runs. Definition-managed triggers can also be paused.",
     http: "POST",
     path: "/automation/v1/triggers/{id}/pause",
     streaming: "no",
@@ -4790,6 +5219,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "automation.triggers",
     method: "resume",
+    summary: "Resume a trigger",
+    description: "Resume firings and reset consecutive failures. Triggers past their end time or finished one-time schedules remain expired; a full enabled-trigger quota returns TRIGGER_LIMIT.",
     http: "POST",
     path: "/automation/v1/triggers/{id}/resume",
     streaming: "no",
@@ -4805,6 +5236,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "automation.triggers",
     method: "rotateWebhook",
+    summary: "Rotate a webhook URL",
+    description: "For webhook triggers only: invalidate the old token immediately and return a new full webhook_url. Later detail reads do not reveal the full URL.",
     http: "POST",
     path: "/automation/v1/triggers/{id}/rotate-webhook",
     streaming: "no",
@@ -4820,6 +5253,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "automation.validate",
     method: "create",
+    summary: "Validate a definition",
+    description: "Check source without executing it when you need diagnostics, inferred schemas or references. This is optional before praxis.automation.runs.create, which also validates source before execution. Actions, scripts and workflows are supported; results include validity without saving. Invalid source is reported with valid=false. Script/action output schemas are inferred from return types: Promise unwrapping, Record, intersections and Date. Unknown types yield an empty schema and a warning in warnings. Source diagnostics use /source or /implementation/source with 1-based line/column. For kind=action the same admission checks as action creation apply (no external imports, platform operations only as direct call(praxis/<api>.<op>, input) calls, no agent or automation calls), so source that validates is not rejected at creation.",
     http: "POST",
     path: "/automation/v1/validate",
     streaming: "no",
@@ -4852,6 +5287,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "automation.workflows",
     method: "list",
+    summary: "List workflows",
+    description: "List visible workflow summaries, latest versions, tags and seven-day statistics. Archived entries are excluded by default.",
     http: "GET",
     path: "/automation/v1/workflows",
     streaming: "no",
@@ -4923,6 +5360,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "automation.workflows",
     method: "create",
+    summary: "Create a workflow",
+    description: "Save a YAML workflow as an editable draft without publishing or starting a run. Choose your own namespace without registering it first; praxis is read-only. To test the draft, send its source and language=yaml to praxis.automation.runs.create. Scripts and workflows share names within the tenant; a duplicate returns NAME_TAKEN. run.workflow accepts ns/name@range or {namespace, name, version, input}; run.script uses the same reference shape as a platform extension. Object namespace, name and version are required; version accepts an exact version, dist-tag or range, locked at publication. Object input defaults to {} and supports expressions; string references retain task-level with. run.await defaults to true and returns the child output. With false, the child uses detach and the task immediately returns {run_id}; parent cancellation does not cascade. Inline script.code returns DEFINITION_INVALID with a detail asking you to save a script and reference it first. raise.error retains its type URI, status, title and detail in the run error.",
     http: "POST",
     path: "/automation/v1/workflows",
     streaming: "no",
@@ -4968,6 +5407,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "automation.workflows",
     method: "retrieve",
+    summary: "Get a workflow",
+    description: "Read workflow details and draft source. The ETag is the draft revision to use in If-Match for updates.",
     http: "GET",
     path: "/automation/v1/workflows/{ns}/{name}",
     streaming: "no",
@@ -4987,6 +5428,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "automation.workflows",
     method: "update",
+    summary: "Update a workflow draft",
+    description: "Update description, labels or draft with the current draft revision in If-Match. Even metadata-only updates create a new draft revision.",
     http: "PATCH",
     path: "/automation/v1/workflows/{ns}/{name}",
     streaming: "no",
@@ -5029,6 +5472,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "automation.workflows",
     method: "archive",
+    summary: "Archive a workflow",
+    description: "Keep the name, versions and draft while archiving. The default list hides it and new target resolution and run requests reject the archived target.",
     http: "POST",
     path: "/automation/v1/workflows/{ns}/{name}/archive",
     streaming: "no",
@@ -5052,6 +5497,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "automation.workflows.distTags",
     method: "list",
+    summary: "List workflow tags",
+    description: "Read the exact version for each distribution tag. Results include the update time and updater.",
     http: "GET",
     path: "/automation/v1/workflows/{ns}/{name}/dist-tags",
     streaming: "no",
@@ -5071,6 +5518,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "automation.workflows.distTags",
     method: "delete",
+    summary: "Delete a workflow tag",
+    description: "Delete a distribution tag while retaining versions. latest cannot be deleted, versions and ranges are invalid tags, and deleting an absent valid tag is repeatable.",
     http: "DELETE",
     path: "/automation/v1/workflows/{ns}/{name}/dist-tags/{tag}",
     streaming: "no",
@@ -5094,6 +5543,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "automation.workflows.distTags",
     method: "set",
+    summary: "Set a workflow tag",
+    description: "Point a distribution tag at an existing exact version; tags cannot be versions or version ranges. Moving latest can roll back a release and synchronizes workflow schedules.",
     http: "PUT",
     path: "/automation/v1/workflows/{ns}/{name}/dist-tags/{tag}",
     streaming: "no",
@@ -5128,6 +5579,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "automation.workflows",
     method: "restore",
+    summary: "Restore a workflow",
+    description: "Restore an archived definition with its versions and tags. The name is retained.",
     http: "POST",
     path: "/automation/v1/workflows/{ns}/{name}/restore",
     streaming: "no",
@@ -5151,6 +5604,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "automation.workflows.versions",
     method: "list",
+    summary: "List workflow versions",
+    description: "Page through immutable schemas and locked dependencies in descending semantic-version order. Lists omit source by default; only expand=source includes full source, and other values return 400. Detail endpoints retain full source.",
     http: "GET",
     path: "/automation/v1/workflows/{ns}/{name}/versions",
     streaming: "no",
@@ -5195,6 +5650,8 @@ delete it. Omit the field to preserve.`
     aliases: [
       "publish"
     ],
+    summary: "Publish a workflow version",
+    description: "Publish a saved definition from its draft or an ad hoc run as a reusable version for named runs or triggers, validating the definition and locking dependencies. To test unpublished code, use praxis.automation.runs.create with source and language instead. Use draft.revision from create or retrieve as expected_draft_revision. The draft must match expected_draft_revision; an ad hoc run requires from_run and expected_source_sha256. The same version and contents return the existing version; different contents return VERSION_EXISTS, prereleases require an explicit tag (not latest, URL-safe characters only, not a version or range; violations return TAG_REQUIRED or TAG_INVALID with the complete rules in hint), and invalid definitions return DEFINITION_INVALID. Stable releases automatically advance latest only above the highest existing stable version; workflows becoming latest synchronize their declared schedule. String and object run.workflow/run.script references share version resolution and dependency locking. Publishing removes +build metadata from the version number.",
     http: "POST",
     path: "/automation/v1/workflows/{ns}/{name}/versions",
     streaming: "no",
@@ -5218,6 +5675,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "automation.workflows.versions",
     method: "retrieve",
+    summary: "Get a workflow version",
+    description: "Read source, input/output schemas and deprecation details for an exact version. Missing versions return VERSION_NOT_FOUND. Details always return full source. version accepts an exact version or dist-tag; a range returns 400 with a hint to use /resolve.",
     http: "GET",
     path: "/automation/v1/workflows/{ns}/{name}/versions/{version}",
     streaming: "no",
@@ -5241,6 +5700,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "automation.workflows.versions",
     method: "deprecate",
+    summary: "Deprecate a workflow version",
+    description: "Record a deprecation message; an empty message removes deprecation without changing the version source.",
     http: "POST",
     path: "/automation/v1/workflows/{ns}/{name}/versions/{version}/deprecate",
     streaming: "no",
@@ -5275,6 +5736,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "browser.connect",
     method: "retrieve",
+    summary: "连接云端浏览器",
+    description: "CDP WebSocket：不填 session 或 name 时新开；session 连接已有会话；name 有就连接、没有就新开。session 与 name 不可同时提供。新建参数在连接已有会话时忽略。使用 Authorization: Bearer API_KEY，或直接使用创建会话返回的带 signingKey 的 connectUrl。连上后发送 CDP 命令 Praxis.getSession，获取 sessionId、liveViewUrl、consoleUrl。",
     http: "GET",
     path: "/browser/v1/connect",
     streaming: "no",
@@ -5340,6 +5803,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "browser.contexts",
     method: "list",
+    summary: "列出浏览器上下文",
+    description: "分页列出当前账户保存的登录态，按登录态 ID 升序排列。每项返回名称、标签及保存内容的统计信息；将 nextCursor 原样传入读取下一页，直到其为 null。",
     http: "GET",
     path: "/browser/v1/contexts",
     streaming: "no",
@@ -5363,6 +5828,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "browser.contexts",
     method: "create",
+    summary: "创建浏览器上下文",
+    description: "创建空的浏览器登录态，用于在会话之间保存 cookie 和 localStorage。将返回的 id 传入 browserSettings.context.id，并设置 persist=true 才会保存会话中的更新。",
     http: "POST",
     path: "/browser/v1/contexts",
     streaming: "no",
@@ -5396,6 +5863,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "browser.contexts",
     method: "delete",
+    summary: "删除浏览器上下文",
+    description: "删除当前账户的指定登录态及其保存内容，成功返回 deleted=true。登录态存在有效写入租约时返回 409 CONTEXT_LOCKED，应在写入会话结束并释放租约后重试。",
     http: "DELETE",
     path: "/browser/v1/contexts/{contextId}",
     streaming: "no",
@@ -5411,6 +5880,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "browser.contexts",
     method: "retrieve",
+    summary: "读取浏览器上下文",
+    description: "读取当前账户的指定登录态元数据、保存内容统计及写入租约持有者，不返回 cookie 或 localStorage 内容。contextId 使用创建或列表返回的 id；不存在或不属于当前账户时返回 404。",
     http: "GET",
     path: "/browser/v1/contexts/{contextId}",
     streaming: "no",
@@ -5426,6 +5897,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "browser.contexts",
     method: "update",
+    summary: "更新浏览器上下文",
+    description: "更新登录态的名称和标签并返回更新后的对象，不修改已保存的 cookie 或 localStorage。省略字段保留原值；空名称清除名称，传入 labels 会整体替换标签，空对象清除标签。",
     http: "PUT",
     path: "/browser/v1/contexts/{contextId}",
     streaming: "no",
@@ -5458,6 +5931,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "browser.live",
     method: "retrieve",
+    summary: "打开实时浏览器画面",
+    description: "使用 debug 返回的完整实时观看地址打开浏览器画面，成功后跳转到对应会话或标签页。必须保留地址中的 t 凭证，无需额外 API Key；链接失效时重新调用 debug 获取地址。",
     http: "GET",
     path: "/browser/v1/live/{sessionId}/{pageId}",
     streaming: "no",
@@ -5484,6 +5959,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "browser.seleniumUnsupported",
     method: "retrieve",
+    summary: "读取 Selenium 不支持提示",
+    description: "seleniumRemoteUrl 指向此地址；不支持 Selenium，请使用 Playwright 或 Puppeteer。",
     http: "GET",
     path: "/browser/v1/selenium-unsupported",
     streaming: "no",
@@ -5494,6 +5971,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "browser.sessions",
     method: "list",
+    summary: "列出浏览器会话",
+    description: "分页列出当前账户的浏览器会话，按创建时刻及 ID 降序排列。可组合状态、名称、标签和用户元数据筛选；将返回的 nextCursor 原样传入以继续读取。",
     http: "GET",
     path: "/browser/v1/sessions",
     streaming: "no",
@@ -5548,6 +6027,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "browser.sessions",
     method: "create",
+    summary: "创建浏览器会话",
+    description: "创建云端 Chrome，返回自带凭证的 connectUrl。API 会话默认断开后结束；最长 6 小时。",
     http: "POST",
     path: "/browser/v1/sessions",
     streaming: "no",
@@ -5623,6 +6104,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "browser.sessions",
     method: "retrieve",
+    summary: "读取浏览器会话",
+    description: "读取当前账户的指定会话及其最新状态，sessionId 使用创建或列表返回的 id。expand=debug,events 可同时取得实时观看地址和事件首页；不存在或不属于当前账户时返回 404。",
     http: "GET",
     path: "/browser/v1/sessions/{sessionId}",
     streaming: "no",
@@ -5645,6 +6128,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "browser.sessions",
     method: "update",
+    summary: "关闭浏览器会话",
+    description: '关闭指定浏览器会话，返回关闭后的会话对象。请求体为 {"status":"REQUEST_RELEASE"}；若返回 409 SESSION_INVALID_STATE，可再次读取会话确认状态；已结束的会话可重复请求关闭。',
     http: "POST",
     path: "/browser/v1/sessions/{sessionId}",
     streaming: "no",
@@ -5674,6 +6159,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "browser.sessions",
     method: "retrieveDebug",
+    summary: "读取调试地址",
+    description: "读取当前会话及各标签页的实时观看地址和 CDP 连接地址。直接使用返回的完整链接，保留查询凭证；会话不在运行状态时 pages 为空，返回地址不代表会话仍可连接。",
     http: "GET",
     path: "/browser/v1/sessions/{sessionId}/debug",
     streaming: "no",
@@ -5689,6 +6176,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "browser.sessions.events",
     method: "list",
+    summary: "列出会话事件",
+    description: "按事件序号升序读取指定会话的事件账本，包含生命周期和接管等事件，不包含页面点击或输入内容。可按 types 筛选，并将 nextCursor 原样传入读取后续页。",
     http: "GET",
     path: "/browser/v1/sessions/{sessionId}/events",
     streaming: "no",
@@ -5723,6 +6212,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "browser.sessions.handoff",
     method: "create",
+    summary: "请求人工接管",
+    description: "为运行中的会话发起人工接管请求，返回接管请求事件。请求尚未过期或完成时，CDP 客户端的 Input.* 指令会被拒绝；再次请求会替换已有的接管说明和到期时刻。",
     http: "POST",
     path: "/browser/v1/sessions/{sessionId}/handoff",
     streaming: "no",
@@ -5755,6 +6246,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "browser.sessions.handoff",
     method: "complete",
+    summary: "完成人工接管",
+    description: "完成运行中会话的待处理人工接管，清除接管请求并返回完成事件，客户端可恢复发送 Input.* 指令。没有请求或请求已过期时返回 409 HANDOFF_NOT_PENDING。",
     http: "POST",
     path: "/browser/v1/sessions/{sessionId}/handoff/complete",
     streaming: "no",
@@ -5770,6 +6263,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "browser.sessions",
     method: "stream",
+    summary: "订阅会话动态",
+    description: "SSE：event 为 snapshot、session、pages、action、event 或 end，data 为对应 JSON。先发送 snapshot 快照，再推送实时变化和 ping 注释；end 后关闭。不支持按 Last-Event-ID 历史重放。",
     http: "GET",
     path: "/browser/v1/sessions/{sessionId}/stream",
     streaming: "always",
@@ -5785,6 +6280,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "browser.sessions.viewer",
     method: "create",
+    summary: "更新查看者心跳",
+    description: "登记运行中会话的观看者仍在线，以免无人连接时因空闲被释放。观看页面可见期间为同一观看者重复发送相同 viewerId；停止观看后停止发送，过期心跳不再计为在线。",
     http: "POST",
     path: "/browser/v1/sessions/{sessionId}/viewer",
     streaming: "no",
@@ -5811,6 +6308,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "database.databases",
     method: "list",
+    summary: "List databases",
+    description: "Find databases owned by your tenant and obtain their ids for schema or row operations. Excludes deleting by default. status=active or status=deleting selects that state; invalid values return 400 INVALID_PARAMS.",
     http: "GET",
     path: "/database/v1/databases",
     streaming: "no",
@@ -5850,6 +6349,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "database.databases",
     method: "create",
+    summary: "Create database",
+    description: "Creates an empty database for the caller and returns it with status active (HTTP 201); add tables next with praxis.database.databases.tables.create. name is required and is 1–64 visible characters after trimming. labels are optional string tags (at most 64; each key starts with a lowercase letter and uses up to 63 characters of a-z 0-9 _ -; each value is up to 63 characters of a-z 0-9 _ -) that databaseListDatabases can filter on. If initialization fails the call returns 503 CAPACITY and the half-created database is left with status failed; retry by calling create again, which makes a new database. Unlike Supabase, this creates a SQLite-backed database without a PostgreSQL connection or SQL execution endpoint. Use a Praxis credential; access is scoped to its tenant, not to Supabase Auth users or RLS policies.",
     http: "POST",
     path: "/database/v1/databases",
     streaming: "no",
@@ -5877,6 +6378,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "database.databases",
     method: "delete",
+    summary: "Delete database",
+    description: "Soft-delete a database when it should stop accepting schema and row operations. Idempotently enters deleting with a seven-day purge_at. GET remains available; child operations return 409 until restored.",
     http: "DELETE",
     path: "/database/v1/databases/{database_id}",
     streaming: "no",
@@ -5892,6 +6395,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "database.databases",
     method: "retrieve",
+    summary: "Get database",
+    description: "Returns one database by id, including a database in the deleting state (purge_at then shows when it will be permanently removed). Call it before table or row operations to confirm status is active: schema and row calls on a deleting database return 409 DATABASE_INVALID_STATE. size_bytes is refreshed from live storage at most once every five seconds. A purged or unknown id returns 404 DATABASE_NOT_FOUND.",
     http: "GET",
     path: "/database/v1/databases/{database_id}",
     streaming: "no",
@@ -5907,6 +6412,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "database.databases",
     method: "update",
+    summary: "Update database",
+    description: "Renames an active database and/or replaces its labels; send only the keys you want to change. labels is replaced as a whole, not merged, so include every label you want to keep. A body without name or labels, or with values equal to the current ones, changes nothing and leaves updated_at as is. A database in the deleting state returns 409 DATABASE_INVALID_STATE; restore it first with databaseRestoreDatabase.",
     http: "PATCH",
     path: "/database/v1/databases/{database_id}",
     streaming: "no",
@@ -5939,6 +6446,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "database.databases.events",
     method: "list",
+    summary: "List events",
+    description: "Read lifecycle and schema events, including while the database is deleting. next_cursor is an opaque string cursor (do not do arithmetic on it): pass it as after_seq for asc or before_seq for desc. Supplying both cursors returns 400 INVALID_PARAMS. Unlike Supabase Realtime, this is paged lifecycle and schema history, not a subscription or a row-change feed; row inserts, updates and deletes do not appear here.",
     http: "GET",
     path: "/database/v1/databases/{database_id}/events",
     streaming: "no",
@@ -5983,6 +6492,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "database.databases.purge",
     method: "create",
+    summary: "Permanently purge database",
+    description: "Immediately and irreversibly purges a deleting database. Active databases return 409; absent or already purged databases return 404.",
     http: "POST",
     path: "/database/v1/databases/{database_id}/purge",
     streaming: "no",
@@ -5998,6 +6509,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "database.databases.rest",
     method: "delete",
+    summary: "Delete rows",
+    description: "Deletes the rows matched by the filter query parameters (the same filters as databaseSelect); with no filter every row of the table matches. Deletion is immediate and cannot be undone. A row that a link field of another table still references makes the whole call fail with 409 REFERENCE_RESTRICT and nothing is deleted. The default response is 204 with no body; send Prefer: return=representation to get HTTP 200 with the deleted rows.",
     http: "DELETE",
     path: "/database/v1/databases/{database_id}/rest/{table}",
     streaming: "no",
@@ -6084,6 +6597,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "database.databases.rest",
     method: "retrieve",
+    summary: "Select rows",
+    description: "Read matching rows with filters, selected columns and ordering. Returns at most 1000 rows per request, including when limit is omitted. Content-Range reports the actual returned interval and the total when count is requested. PATCH and DELETE are not subject to this read cap. Unlike Supabase, casts, aggregates, spread and join modifiers are unsupported. Each table supports up to 1,000,000 rows. Query budget: 8,000 ms with a shared 3,000,000-row safety ceiling. Create indexes on filtered or sorted fields, or narrow the request when it exceeds its budget. Synchronous SQLite aggregates use candidate-row throughput estimates before execution; deployed Workers freeze clocks during synchronous CPU work, so the timer is not a guaranteed server-side interrupt. Count preferences: without filters, exact, planned and estimated all use SQLite's exact b-tree count. With filters, exact counts within budget; planned skips counting and reports an unknown total (Content-Range: 0-24/*); estimated attempts exact counting only when the preflight budget allows it, otherwise reports an unknown total. Preference-Applied echoes the requested count mode. Error table: QUERY_CANCELED / PostgREST 57014 is HTTP 500, retryable=false: Query timed out: index filtered or sorted fields, or narrow the range. DATABASE_INVALID_STATE is HTTP 409 for operations on a deleting database. Cleared or nonexistent databases return DATABASE_NOT_FOUND / HTTP 404. The count is an HTTP Content-Range response header, not a JSON property. Praxis SDK/codemode methods return the body only; a page length is not a total unless you know all matches fit in that page.",
     http: "GET",
     path: "/database/v1/databases/{database_id}/rest/{table}",
     streaming: "no",
@@ -6170,6 +6685,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "database.databases.rest",
     method: "head",
+    summary: "Count rows",
+    description: "Inspect the HTTP row count and range without retrieving row data; send Prefer: count=exact for a filtered count. Returns no body and does not fetch or serialize row data. A known count determines the interval using limit/offset or Range with a default and maximum page size of 1000. Without a count preference, or when the selected count mode cannot supply a total, Content-Range is */*. Singular Accept still validates page cardinality. Unlike Supabase, planned and estimated counts do not use PostgreSQL planner estimates. Count preferences: without filters, exact, planned and estimated all use SQLite's exact b-tree count. With filters, exact counts within budget; planned skips counting and reports an unknown total (Content-Range: 0-24/*); estimated attempts exact counting only when the preflight budget allows it, otherwise reports an unknown total. Preference-Applied echoes the requested count mode. Praxis SDK/codemode methods return only the empty body, not the Content-Range response header; use an HTTP client when you need that header.",
     http: "HEAD",
     path: "/database/v1/databases/{database_id}/rest/{table}",
     streaming: "no",
@@ -6256,6 +6773,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "database.databases.rest",
     method: "update",
+    summary: "Update rows",
+    description: "Updates the rows matched by the filter query parameters (the same filters as databaseSelect); with no filter every row of the table matches. The JSON object body lists only the fields to change, other fields keep their values, and id cannot be changed. Values are validated against the field types and the required and unique settings (400 VALIDATION_FAILED, 409 UNIQUE_VIOLATION). The default response is 204 with no body; send Prefer: return=representation to get HTTP 200 with the updated rows. Each changed row's _version increases by one.",
     http: "PATCH",
     path: "/database/v1/databases/{database_id}/rest/{table}",
     streaming: "no",
@@ -6346,6 +6865,10 @@ delete it. Omit the field to preserve.`
   {
     resource: "database.databases.rest",
     method: "create",
+    summary: "Insert rows",
+    description: `Insert rows into an existing table after defining its fields; at most 500 rows per request. Each request is atomic: any failure rolls back the entire batch. There are no transactions across requests.
+Rows are filled to the union of their keys with null; send Prefer: missing=default to use field defaults for missing keys.
+The default is return=minimal: success returns HTTP 201 with an empty body. Send Prefer: return=representation to return the inserted rows. Unlike Supabase, upsert conflicts can target only id or one unique field, not a composite key. Each table supports up to 1,000,000 rows.`,
     http: "POST",
     path: "/database/v1/databases/{database_id}/rest/{table}",
     streaming: "no",
@@ -6436,6 +6959,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "database.databases",
     method: "restore",
+    summary: "Restore database",
+    description: "Recover a soft-deleted database within its seven-day recovery window. Restore before purge_at. An empty body is accepted. Active databases return 409; purged databases return 404.",
     http: "POST",
     path: "/database/v1/databases/{database_id}/restore",
     streaming: "no",
@@ -6451,6 +6976,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "database.databases.tables",
     method: "list",
+    summary: "List tables",
+    description: "Lists every table of an active database with its field definitions. A database holds at most 50 tables, so the single page contains all of them and next_cursor is always null. Use databaseGetTable instead when you also need row_count for one table.",
     http: "GET",
     path: "/database/v1/databases/{database_id}/tables",
     streaming: "no",
@@ -6466,6 +6993,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "database.databases.tables",
     method: "create",
+    summary: "Create table",
+    description: "Creates a table together with its initial fields in one call and returns it (HTTP 201) with generated tbl_ and fld_ ids. name must match ^[a-z_][a-z0-9_]{0,62}$ and be unused in this database (duplicate: 409 UNIQUE_VIOLATION). fields is required and may be an empty array; fields can also be added later with databaseAddField. Limits: 50 tables per database, 64 fields per table, and 16 indexed or unique fields per table; exceeding one returns 400 LIMIT_EXCEEDED. Every row also has a system id column, which is not declared as a field. Insert data afterwards with databaseInsert. Unlike Supabase, define schema with this table API and the field APIs; PostgreSQL DDL and SQL migration files cannot be submitted. Each table supports up to 1,000,000 rows.",
     http: "POST",
     path: "/database/v1/databases/{database_id}/tables",
     streaming: "no",
@@ -6505,6 +7034,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "database.databases.tables",
     method: "delete",
+    summary: "Delete table",
+    description: "Permanently drops a table with all of its rows; the deletion is immediate and has no recovery window or undo. Refused with 409 REFERENCE_RESTRICT while a link field of another table points at this table, so delete or change those fields first. Returns {deleted: true}. A table name can be reused afterwards.",
     http: "DELETE",
     path: "/database/v1/databases/{database_id}/tables/{table}",
     streaming: "no",
@@ -6524,6 +7055,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "database.databases.tables",
     method: "retrieve",
+    summary: "Get table",
+    description: "Returns one table by id or name with its field definitions, schema_revision and row_count. row_count is only returned by this operation, not by list or create. Use field ids from this response for stable references because field names can be renamed; an unknown table returns 404 TABLE_NOT_FOUND.",
     http: "GET",
     path: "/database/v1/databases/{database_id}/tables/{table}",
     streaming: "no",
@@ -6543,6 +7076,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "database.databases.tables",
     method: "update",
+    summary: "Update table",
+    description: "Renames a table and/or changes its description; send only the keys to change, and send description null to clear it. The new name must follow ^[a-z_][a-z0-9_]{0,62}$ and be unused (409 UNIQUE_VIOLATION); ids are stable, so renaming never rewrites row data. A body with no changes or values equal to the current ones does not bump schema_revision. Fields cannot be changed here; use databaseAddField, databaseUpdateField and databaseDeleteField.",
     http: "PATCH",
     path: "/database/v1/databases/{database_id}/tables/{table}",
     streaming: "no",
@@ -6579,6 +7114,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "database.databases.tables.fields",
     method: "create",
+    summary: "Add field",
+    description: "Adds one field to an existing table and returns the updated table (HTTP 201). Required inputs are name (lowercase letters, digits and underscores; id and names starting with _ are reserved) and type (string, integer, number, boolean, datetime, json or link); json needs options.schema and link needs options.linked_table_id and options.multiple. Adding a required field to a table that already has rows needs a default, otherwise the call fails with 400 VALIDATION_FAILED; a default is written into every existing row. Scalar fields are indexed by default, while json and link fields cannot be indexed. Limits: 64 fields and 16 indexed or unique fields per table (400 LIMIT_EXCEEDED). Unlike Supabase, schema evolution uses field definitions rather than ALTER TABLE statements or SQL migrations.",
     http: "POST",
     path: "/database/v1/databases/{database_id}/tables/{table}/fields",
     streaming: "no",
@@ -6602,6 +7139,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "database.databases.tables.fields",
     method: "delete",
+    summary: "Delete field",
+    description: "Deletes one field definition from a table and returns the updated table; the deletion is immediate and has no recovery window. Look the field up by id or name. The field's index, if any, is dropped with it, and the name can be reused afterwards. Unknown fields return 400 FIELD_NOT_FOUND.",
     http: "DELETE",
     path: "/database/v1/databases/{database_id}/tables/{table}/fields/{field}",
     streaming: "no",
@@ -6625,6 +7164,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "database.databases.tables.fields",
     method: "update",
+    summary: "Update field",
+    description: "Changes a field's name, description, required flag, indexed flag, default or json options.schema and returns the updated table. The field type, a link field's linked_table_id and the unique flag cannot be changed (400 FIELD_TYPE_IMMUTABLE or INVALID_PARAMS). Setting required to true fails with 400 VALIDATION_FAILED while existing rows hold null for the field. A new json schema constrains only later writes; existing rows are not revalidated. Renaming never rewrites row data, and a request that changes nothing does not bump schema_revision. Unlike Supabase, field types and uniqueness cannot be altered through SQL migrations; use the supported field settings described here.",
     http: "PATCH",
     path: "/database/v1/databases/{database_id}/tables/{table}/fields/{field}",
     streaming: "no",
@@ -6689,6 +7230,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "file.files",
     method: "list",
+    summary: "List files",
+    description: "List live files owned by your tenant, optionally filtered by purpose or session scope_id. Results default to descending creation order with a limit of 10000. Page using after or before with a file ID from the list; these cursors are mutually exclusive. Deleted and expired files are excluded.",
     http: "GET",
     path: "/file/v1/files",
     streaming: "no",
@@ -6741,6 +7284,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "file.files",
     method: "create",
+    summary: "Upload file",
+    description: 'Upload a file to reuse in conversations or attach to a knowledge base. Unlike OpenAI Files, uploads must be nonempty and at most 104857600 bytes, and only user_data, assistants and vision purposes are accepted. Send file bytes as a multipart file part, not a filename or file ID; in the SDK use a File or Blob, for example new File(["Return within 23 days."], "policy.txt", { type: "text/plain" }). Content determines the MIME type. Supported uploads include PDF, DOCX/XLSX/PPTX, PNG/JPEG/GIF/WebP, MP3/WAV/FLAC/OGG/M4A, MP4/WebM, and UTF-8 JSON/NDJSON/CSV/Markdown/plain text; empty, unsupported, oversized files and unsupported purposes return 400. OpenAI Uploads chunking is not supported. The purpose vision accepts only PNG, JPEG, GIF and WebP, while conversation images require user_data. The returned ID belongs to your tenant; upload alone does not ingest the file into Knowledge. Knowledge attachment has a lower limit of 100000000 bytes. Optionally set expires_after[anchor]=created_at with expires_after[seconds] (3600–2592000), or praxis[expires_in_seconds] (3600–7776000), never both. Without expiry, the file persists until deleted.',
     http: "POST",
     path: "/file/v1/files",
     streaming: "no",
@@ -6786,6 +7331,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "file.files",
     method: "delete",
+    summary: "Delete file",
+    description: "Delete a tenant-owned file. New metadata/content reads return not found. Already-authorized downloads may finish.",
     http: "DELETE",
     path: "/file/v1/files/{file_id}",
     streaming: "no",
@@ -6801,6 +7348,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "file.files",
     method: "retrieve",
+    summary: "Retrieve file",
+    description: "Retrieve metadata for a live file owned by your tenant. Use its file_dp_ ID from upload or list. Missing, deleted, expired and other-tenant files return 404; use the content endpoint to download the bytes.",
     http: "GET",
     path: "/file/v1/files/{file_id}",
     streaming: "no",
@@ -6816,6 +7365,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "file.files",
     method: "retrieveContent",
+    summary: "Retrieve file content",
+    description: "Download the original bytes of a live file owned by your tenant. Supply its file_dp_ ID from upload or list. A single byte Range can return a partial response; a range outside the file returns 416. Missing, deleted, expired and other-tenant files return 404.",
     http: "GET",
     path: "/file/v1/files/{file_id}/content",
     streaming: "no",
@@ -6831,6 +7382,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "knowledge.vectorStores",
     method: "list",
+    summary: "List knowledge bases",
+    description: "Lists knowledge bases visible to the caller, newest first by default. Use last_id as after to read the next page; for example, ?limit=20.",
     http: "GET",
     path: "/knowledge/v1/vector_stores",
     streaming: "no",
@@ -6880,6 +7433,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "knowledge.vectorStores",
     method: "create",
+    summary: "Create knowledge base",
+    description: 'Create a knowledge base, optionally starting ingestion of uploaded file_ids in the same call; no separate attachment or batch is needed for those files. Use the returned id with vectorStores.files.retrieve to poll each attachment until completed, failed or cancelled; store status=completed alone does not mean every file succeeded. Unlike OpenAI vector stores, each file is limited to 100000000 bytes and each account to 100 active/nondeleted stores. Minimal body: {"name":"Refund policies"}.',
     http: "POST",
     path: "/knowledge/v1/vector_stores",
     streaming: "no",
@@ -6938,6 +7493,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "knowledge.vectorStores",
     method: "delete",
+    summary: "Delete knowledge base",
+    description: "Remove a knowledge base from active use while keeping a recovery window. Unlike OpenAI vector stores, native DELETE returns the store with status=deleting and ISO purge_at, retains it for 7 days and is idempotent on repeat. Retrieve remains 200; object operations return 409. Use restore before purge_at to recover it, or purge to remove it irreversibly.",
     http: "DELETE",
     path: "/knowledge/v1/vector_stores/{vector_store_id}",
     streaming: "no",
@@ -6953,6 +7510,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "knowledge.vectorStores",
     method: "retrieve",
+    summary: "Retrieve knowledge base",
+    description: "Retrieves a knowledge base using an id returned by create or list. Add ?expand=files to include the first page of attached files. Soft-deleted stores remain readable with status=deleting until purged.",
     http: "GET",
     path: "/knowledge/v1/vector_stores/{vector_store_id}",
     streaming: "no",
@@ -6989,6 +7548,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "knowledge.vectorStores",
     method: "update",
+    summary: "Update knowledge base",
+    description: 'Updates an active knowledge base using its returned id. Omitted fields stay unchanged; metadata replaces the whole map. Example body: {"name":"Refund policies"}.',
     http: "POST",
     path: "/knowledge/v1/vector_stores/{vector_store_id}",
     streaming: "no",
@@ -7033,6 +7594,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "knowledge.vectorStores.events",
     method: "list",
+    summary: "List events",
+    description: "Reads events for this knowledge base in increasing sequence order, including while soft-deleted. Pass next_seq as after_seq to continue; null next_seq marks the current end. Example: ?after_seq=0&limit=20.",
     http: "GET",
     path: "/knowledge/v1/vector_stores/{vector_store_id}/events",
     streaming: "no",
@@ -7061,6 +7624,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "knowledge.vectorStores.fileBatches",
     method: "create",
+    summary: "Create file batch",
+    description: "Attaches existing Files as a batch for asynchronous ingestion. Supply exactly one of file_ids or files; files allows per-file settings. Existing attachments are reused. Read the returned batch id to monitor status.",
     http: "POST",
     path: "/knowledge/v1/vector_stores/{vector_store_id}/file_batches",
     streaming: "no",
@@ -7080,6 +7645,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "knowledge.vectorStores.fileBatches",
     method: "retrieve",
+    summary: "Retrieve file batch",
+    description: "Retrieves a batch created in this knowledge base, including current status and file counts. Use the batch id returned by batch creation to monitor ingestion.",
     http: "GET",
     path: "/knowledge/v1/vector_stores/{vector_store_id}/file_batches/{batch_id}",
     streaming: "no",
@@ -7099,6 +7666,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "knowledge.vectorStores.fileBatches",
     method: "cancel",
+    summary: "Cancel file batch",
+    description: "Cancels only in-progress batches and pending files. Completed, failed and cancelled batches return unchanged (200, idempotent).",
     http: "POST",
     path: "/knowledge/v1/vector_stores/{vector_store_id}/file_batches/{batch_id}/cancel",
     streaming: "no",
@@ -7118,6 +7687,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "knowledge.vectorStores.fileBatches.files",
     method: "list",
+    summary: "List batch files",
+    description: "Lists files still attached from the identified batch, newest attachment first by default. Use the batch creation id and ?filter=failed to inspect failures; last_id is the next after cursor.",
     http: "GET",
     path: "/knowledge/v1/vector_stores/{vector_store_id}/file_batches/{batch_id}/files",
     streaming: "no",
@@ -7178,6 +7749,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "knowledge.vectorStores.files",
     method: "list",
+    summary: "List files",
+    description: "Lists attached files and their ingestion status, newest attachment first by default. Use last_id as after to continue; ?filter=failed selects files that can be retried.",
     http: "GET",
     path: "/knowledge/v1/vector_stores/{vector_store_id}/files",
     streaming: "no",
@@ -7234,6 +7807,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "knowledge.vectorStores.files",
     method: "create",
+    summary: "Add file",
+    description: "Attach an uploaded File for asynchronous ingestion, then poll this attachment until status is completed, failed or cancelled before searching. Unlike OpenAI vector stores, the file limit is 100000000 bytes; chunk sizes use estimated tokens rather than a model tokenizer. Text, Markdown, CSV, JSON, HTML, PDF, DOCX, PPTX, XLSX and PNG/JPEG/GIF/WebP images can be extracted; audio and video uploads are not knowledge documents. Images may yield generated descriptions rather than verbatim OCR. auto chunking resolves to static 800/400; explicit sizes are 100–4096 with overlap at most half the size. Each store holds at most 10000 attached files. Reattaching the same file returns its existing record without applying new attributes or chunking; inspect last_error after failure.",
     http: "POST",
     path: "/knowledge/v1/vector_stores/{vector_store_id}/files",
     streaming: "no",
@@ -7272,6 +7847,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "knowledge.vectorStores.files",
     method: "delete",
+    summary: "Remove file",
+    description: "Removes the file from search immediately; does not delete the original File.",
     http: "DELETE",
     path: "/knowledge/v1/vector_stores/{vector_store_id}/files/{file_id}",
     streaming: "no",
@@ -7291,6 +7868,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "knowledge.vectorStores.files",
     method: "retrieve",
+    summary: "Retrieve file",
+    description: "Retrieves an attached file using the id returned by attachment or file listing. Poll this operation until status leaves in_progress to observe the ingestion outcome.",
     http: "GET",
     path: "/knowledge/v1/vector_stores/{vector_store_id}/files/{file_id}",
     streaming: "no",
@@ -7310,6 +7889,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "knowledge.vectorStores.files",
     method: "update",
+    summary: "Update file attributes",
+    description: 'Replaces search-filter attributes of an existing attachment without reingesting its content. Use an attached file id. Example body: {"attributes":{"category":"refund"}}; null clears the attributes.',
     http: "POST",
     path: "/knowledge/v1/vector_stores/{vector_store_id}/files/{file_id}",
     streaming: "no",
@@ -7340,6 +7921,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "knowledge.vectorStores.files",
     method: "retrieveContent",
+    summary: "Read extracted content",
+    description: "Extracted text chunks may overlap. Image content can be a generated description rather than verbatim OCR.",
     http: "GET",
     path: "/knowledge/v1/vector_stores/{vector_store_id}/files/{file_id}/content",
     streaming: "no",
@@ -7359,6 +7942,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "knowledge.vectorStores.files.retry",
     method: "create",
+    summary: "Retry failed file",
+    description: "Retries only failed files; other states return 409 FILE_INVALID_STATE. Retry after failure has not yet been observed in the documented run.",
     http: "POST",
     path: "/knowledge/v1/vector_stores/{vector_store_id}/files/{file_id}/retry",
     streaming: "no",
@@ -7378,6 +7963,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "knowledge.vectorStores.files.segments",
     method: "list",
+    summary: "List file segments",
+    description: "Lists the stored chunks of an attached file, ordered by increasing segment index by default. Use the attachment id and last_id as after to continue; returned chunk ids can be retrieved individually.",
     http: "GET",
     path: "/knowledge/v1/vector_stores/{vector_store_id}/files/{file_id}/segments",
     streaming: "no",
@@ -7426,6 +8013,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "knowledge.vectorStores.purge",
     method: "create",
+    summary: "Permanently purge knowledge base",
+    description: "Immediately and irreversibly clears a deleting store using the retention cleanup path. Active stores return 409; absent stores return 404. Empty body is allowed.",
     http: "POST",
     path: "/knowledge/v1/vector_stores/{vector_store_id}/purge",
     streaming: "no",
@@ -7441,6 +8030,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "knowledge.vectorStores",
     method: "restore",
+    summary: "Restore knowledge base",
+    description: "Restores a deleting store within 7 days. Active stores return 409 VECTOR_STORE_INVALID_STATE; absent stores return 404. Empty body is allowed.",
     http: "POST",
     path: "/knowledge/v1/vector_stores/{vector_store_id}/restore",
     streaming: "no",
@@ -7456,6 +8047,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "knowledge.vectorStores.search",
     method: "create",
+    summary: "Search knowledge base",
+    description: 'Search ingested text to answer a question or find supporting passages. Native results contain one chunk each, so file_id can repeat; max_num_results counts chunks (1–50, default 10), while the compatible URL groups results by file. Unlike OpenAI vector stores, next_page is always null even when has_more is true. Only completed attachments are searchable. For keyword-only retrieval set ranking_options.hybrid_search to {"embedding_weight":0,"text_weight":1}; omit rewrite_query or set it to false to avoid query rewriting. Unlike OpenAI, ranker auto does not rerank; only default-2024-11-15 requests reranking. Set praxis.explain=true to inspect scores and use returned content[].chunk_id to retrieve a segment.',
     http: "POST",
     path: "/knowledge/v1/vector_stores/{vector_store_id}/search",
     streaming: "no",
@@ -7518,6 +8111,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "knowledge.vectorStores.segments",
     method: "retrieve",
+    summary: "Retrieve segment",
+    description: "Retrieves one chunk and its term statistics. Take chunk_id from segment listing or native search content; the chunk must belong to this knowledge base.",
     http: "GET",
     path: "/knowledge/v1/vector_stores/{vector_store_id}/segments/{chunk_id}",
     streaming: "no",
@@ -7537,6 +8132,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "media.libraries",
     method: "list",
+    summary: "List libraries",
+    description: "List libraries owned by the caller, newest first. By default, deleting and deleted libraries are excluded; use status=deleting to find libraries awaiting purge. All supplied label pairs must match.",
     http: "GET",
     path: "/media/v1/libraries",
     streaming: "no",
@@ -7576,6 +8173,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "media.libraries",
     method: "create",
+    summary: "Create library",
+    description: "Create a library owned by the caller with a name, optional labels and understanding settings. Understanding is enabled by default; the returned id is used for subsequent asset operations.",
     http: "POST",
     path: "/media/v1/libraries",
     streaming: "no",
@@ -7615,6 +8214,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "media.libraries",
     method: "delete",
+    summary: "Delete library",
+    description: "Soft-delete an active library, returning its deleting status and purge_at deadline. Asset operations and delivery become unavailable; the library can be restored before purge_at. Repeated deletion while deleting returns the current library.",
     http: "DELETE",
     path: "/media/v1/libraries/{library_id}",
     streaming: "no",
@@ -7630,6 +8231,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "media.libraries",
     method: "retrieve",
+    summary: "Get library",
+    description: "Read a caller-owned library’s current settings, usage and lifecycle status. A deleting library remains readable; missing, foreign or purged libraries return LIBRARY_NOT_FOUND.",
     http: "GET",
     path: "/media/v1/libraries/{library_id}",
     streaming: "no",
@@ -7645,6 +8248,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "media.libraries",
     method: "update",
+    summary: "Update library",
+    description: "Update an active library’s supplied settings. Labels replace the complete map; understanding settings and model roles merge with current values. Changing the embedding model is rejected while assets exist.",
     http: "PATCH",
     path: "/media/v1/libraries/{library_id}",
     streaming: "no",
@@ -7689,6 +8294,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "media.libraries.assets",
     method: "list",
+    summary: "List assets",
+    description: "List assets in an active library, newest first, optionally filtering by exact folder and stored resource type. Continue using next_cursor; video includes audio-only assets.",
     http: "GET",
     path: "/media/v1/libraries/{library_id}/assets",
     streaming: "no",
@@ -7734,6 +8341,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "media.libraries.assets",
     method: "create",
+    summary: "Upload asset",
+    description: "Upload content into an active library and return a Cloudinary-compatible resource. Use file for a multipart file, data URI, public HTTPS URL or same-owner file identifier. Reusing public_id overwrites by default; overwrite=false returns the existing resource. Chunk uploads require both chunk headers.",
     http: "POST",
     path: "/media/v1/libraries/{library_id}/assets",
     streaming: "no",
@@ -7845,6 +8454,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "media.libraries.assets.import",
     method: "create",
+    summary: "Import file",
+    description: "Copy source content into an active library using upload options and return the full native Asset. The imported asset is independent of the source after copying. Reusing public_id follows overwrite semantics.",
     http: "POST",
     path: "/media/v1/libraries/{library_id}/assets/import",
     streaming: "no",
@@ -7954,6 +8565,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "media.libraries.assets",
     method: "delete",
+    summary: "Delete asset",
+    description: "Delete an asset from the library so it is no longer readable, searchable or deliverable. This removes the asset rather than placing it in the library’s restoration window; a missing asset returns ASSET_NOT_FOUND.",
     http: "DELETE",
     path: "/media/v1/libraries/{library_id}/assets/{asset_id}",
     streaming: "no",
@@ -7973,6 +8586,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "media.libraries.assets",
     method: "retrieve",
+    summary: "Get asset",
+    description: "Read a non-deleted asset by its asset_id in an active library, including content hashes, processing progress and available previews. Missing or deleted assets return ASSET_NOT_FOUND.",
     http: "GET",
     path: "/media/v1/libraries/{library_id}/assets/{asset_id}",
     streaming: "no",
@@ -7992,6 +8607,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "media.libraries.assets",
     method: "update",
+    summary: "Update asset",
+    description: "Update an asset’s supplied metadata fields. Tags and context replace their current collections; an empty collection clears them. Moving asset_folder or changing display_name preserves public_id and delivery URLs.",
     http: "PATCH",
     path: "/media/v1/libraries/{library_id}/assets/{asset_id}",
     streaming: "no",
@@ -8041,6 +8658,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "media.libraries.assets.reprocess",
     method: "create",
+    summary: "Reprocess asset",
+    description: "Queue reprocessing of the asset’s current version and return its updated state immediately. Omit kinds to retry failed tasks; explicit kinds rerun applicable completed tasks. Replaced understandings become superseded, and processing finishes asynchronously.",
     http: "POST",
     path: "/media/v1/libraries/{library_id}/assets/{asset_id}/reprocess",
     streaming: "no",
@@ -8078,6 +8697,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "media.libraries.assets.understandings",
     method: "list",
+    summary: "List understandings",
+    description: "List an asset’s understanding results in creation order. By default only current, non-superseded results are returned; use include_superseded=true for history or kind to select an output type.",
     http: "GET",
     path: "/media/v1/libraries/{library_id}/assets/{asset_id}/understandings",
     streaming: "no",
@@ -8129,6 +8750,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "media.libraries.assets",
     method: "batch",
+    summary: "Batch assets alias",
+    description: "Alias of batch creation. Apply one metadata or deletion action to ids or a frozen expression selection asynchronously; poll the returned job id to inspect completion and item failures.",
     http: "POST",
     path: "/media/v1/libraries/{library_id}/assets:batch",
     streaming: "no",
@@ -8155,6 +8778,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "media.libraries.batches",
     method: "create",
+    summary: "Create batch",
+    description: "Create an asynchronous batch for tagging, untagging, replacing context, moving or deleting assets. Select ids or an expression; selection is frozen at creation. Poll the returned job id for completion and per-item failures.",
     http: "POST",
     path: "/media/v1/libraries/{library_id}/batches",
     streaming: "no",
@@ -8181,6 +8806,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "media.libraries.batches",
     method: "retrieve",
+    summary: "Get batch",
+    description: "Read a batch job’s status, successful and failed item counts, and a bounded list of failed items. Use the id returned by batch creation; a job outside this library is not found.",
     http: "GET",
     path: "/media/v1/libraries/{library_id}/batches/{job_id}",
     streaming: "no",
@@ -8200,6 +8827,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "media.libraries.events",
     method: "list",
+    summary: "List events",
+    description: "Read library events in sequence order, including while the library is deleting. Page forward with asc and after_seq, or backward with desc and before_seq; never combine the two sequence cursors.",
     http: "GET",
     path: "/media/v1/libraries/{library_id}/events",
     streaming: "no",
@@ -8244,6 +8873,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "media.libraries.folders",
     method: "list",
+    summary: "List folders",
+    description: "List all immediate child folders under parent, or under the root when parent is omitted. Counts include descendant assets. The result is unpaginated; limit and cursor are rejected.",
     http: "GET",
     path: "/media/v1/libraries/{library_id}/folders",
     streaming: "no",
@@ -8266,6 +8897,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "media.libraries.jobs",
     method: "retrieve",
+    summary: "Get job alias",
+    description: "Alias of batch retrieval. Read the job returned by a batch request, including terminal status, successful and failed counts, and individual failure codes.",
     http: "GET",
     path: "/media/v1/libraries/{library_id}/jobs/{job_id}",
     streaming: "no",
@@ -8285,6 +8918,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "media.libraries.purge",
     method: "create",
+    summary: "Purge library",
+    description: "Permanently remove a library that is already deleting, without waiting for purge_at. Its assets and related resources are removed and cannot be restored; first soft-delete an active library.",
     http: "POST",
     path: "/media/v1/libraries/{library_id}/purge",
     streaming: "no",
@@ -8300,6 +8935,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "media.libraries",
     method: "restore",
+    summary: "Restore library",
+    description: "Restore a deleting library before its purge_at deadline. The library becomes active again and deleted_at and purge_at are cleared; expired or non-deleting libraries cannot be restored.",
     http: "POST",
     path: "/media/v1/libraries/{library_id}/restore",
     streaming: "no",
@@ -8315,6 +8952,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "media.libraries.search",
     method: "create",
+    summary: "Semantic search alias",
+    description: "Alias of semantic search. Search assets with a nonblank text query, optional expression filter and top_k; hybrid combines semantic and keyword matches, while semantic uses vector similarity only.",
     http: "POST",
     path: "/media/v1/libraries/{library_id}/search",
     streaming: "no",
@@ -8363,6 +9002,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "media.libraries.search.expression",
     method: "create",
+    summary: "Expression search",
+    description: "Search active assets using the supported filter-expression syntax, sorting and cursor pagination. Empty expression matches all assets. Tags and context require with_field; inspect the exactness flags before treating counts as complete.",
     http: "POST",
     path: "/media/v1/libraries/{library_id}/search/expression",
     streaming: "no",
@@ -8432,6 +9073,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "media.libraries.search.semantic",
     method: "create",
+    summary: "Semantic search",
+    description: "Search assets with a nonblank text query and optional expression filter. Hybrid mode combines semantic and keyword matches; semantic mode uses vector similarity only. Results are ranked and limited by top_k.",
     http: "POST",
     path: "/media/v1/libraries/{library_id}/search/semantic",
     streaming: "no",
@@ -8480,6 +9123,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "media.libraries.search.visual",
     method: "create",
+    summary: "Visual search",
+    description: "Find visually similar assets using exactly one of asset_id or an inline base64 image. The library must support image search; an asset query needs a current image embedding and excludes that source asset from results.",
     http: "POST",
     path: "/media/v1/libraries/{library_id}/search/visual",
     streaming: "no",
@@ -8524,6 +9169,12 @@ delete it. Omit the field to preserve.`
   {
     resource: "meta.health",
     method: "retrieve",
+    summary: "Health Check",
+    description: `Liveness probe for the public API edge. Public, no authentication, not billed, not rate limited.
+Returns the plain text \`ok\` with HTTP 200 while the API worker can serve requests; any other
+status or a timeout means the edge itself is unavailable. It does not check individual
+services (model, agent, automation…); call the operation you need and read its error instead.
+`,
     http: "GET",
     path: "/meta/v1/health",
     streaming: "no",
@@ -8534,6 +9185,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "meta.methods",
     method: "list",
+    summary: "Search platform methods",
+    description: "Find the SDK / codemode method that does what you need. Public, no authentication, not billed.\nCall this before writing code against an unfamiliar capability, then call\n`GET /meta/v1/methods/{name}` for the full TypeScript declaration of the method you pick.\nMatching ignores word order and case: `list agents` and `agents list` both rank\n`praxis.agent.agents.list` first. Results are ranked by relevance over the method name,\nsummary and description. Without `q`, methods are sorted by name; use `after_id` from `last_id` to retrieve the next page.\nThe catalog covers platform methods (`praxis.*`) only; MCP tools of a session are not included.\n",
     http: "GET",
     path: "/meta/v1/methods",
     streaming: "no",
@@ -8563,6 +9216,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "meta.methods",
     method: "retrieve",
+    summary: "Retrieve a platform method",
+    description: "Full description of one platform method: what it does, how to call it, and the complete\nTypeScript declaration of its arguments and result. Public, no authentication, not billed.\nThe declaration is never truncated; copy field names and enum values from it instead of\nguessing. Take `name` from `GET /meta/v1/methods?q=<words>`. An unknown name returns 404\nMETHOD_NOT_FOUND whose `hint` lists up to three similar names.\n",
     http: "GET",
     path: "/meta/v1/methods/{name}",
     streaming: "no",
@@ -8578,6 +9233,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "model.audio.speech",
     method: "create",
+    summary: "Generate speech",
+    description: 'Synthesize speech from text and return the complete audio as the response body. Use it for text-to-speech; to turn audio into text use createAudioTranscription. model is a speech model such as melotts or aura-2-en (list them with listModels?type=speech). MeloTTS supports response_format wav only and takes lang (en default, fr, es, zh; ja and ko currently error) and no voice; Aura takes a native speaker name in voice (default luna) and supports mp3, opus, flac, wav and pcm (pcm is raw signed 16-bit little-endian audio at 24 kHz). Unlike OpenAI, voice names such as alloy are not aliases for Aura speakers. Non-default speed, instructions and stream_format sse are not representable and return 400 input_not_representable. No transcoding is done: when response_format is omitted the format the upstream produced is returned. Minimal request: {"model":"melotts","input":"Hello","lang":"en","response_format":"wav"}.',
     http: "POST",
     path: "/model/v1/audio/speech",
     streaming: "no",
@@ -8715,6 +9372,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "model.audio.transcriptions",
     method: "create",
+    summary: "Transcribe audio",
+    description: "Transcribe an uploaded audio file into text. Use it for speech-to-text; to synthesize speech use createAudioSpeech. Send multipart/form-data with model (for example whisper-large-v3-turbo or qwen3-asr-flash; list them with listModels?type=transcription) and file. response_format json (default) and text work on both models; verbose_json with segment timestamps works on whisper-large-v3-turbo only; srt and vtt return 400. Parameters a model cannot represent, such as temperature, return 400 input_not_representable, and when no model route is available the call answers 503. The response is JSON with text (plus language, duration and segments for verbose_json) or plain text for response_format text.",
     http: "POST",
     path: "/model/v1/audio/transcriptions",
     streaming: "no",
@@ -8782,6 +9441,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "model.chat.completions",
     method: "create",
+    summary: "Create Chat Completion",
+    description: "OpenAI-compatible chat completions on the model domain's own face. providerOptions.praxis carries model-level fallback (models), request-level BYOK credentials (byok, falling back to platform credentials on failure), and credential-gated provider selection (order/only). Responses report providerMetadata.praxis {generationId, cost, credential, model}.",
     http: "POST",
     path: "/model/v1/chat/completions",
     streaming: "optional",
@@ -9182,6 +9843,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "model.conversations",
     method: "create",
+    summary: "Create Conversation",
+    description: "Create a stored conversation, optionally with initial items and metadata, to reuse context across Responses calls. Pass its returned id as conversation when creating a response.",
     http: "POST",
     path: "/model/v1/conversations",
     streaming: "no",
@@ -9210,6 +9873,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "model.conversations",
     method: "delete",
+    summary: "Delete Conversation",
+    description: "Delete a conversation on the model domain's own face.",
     http: "DELETE",
     path: "/model/v1/conversations/{conversation_id}",
     streaming: "no",
@@ -9225,6 +9890,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "model.conversations",
     method: "retrieve",
+    summary: "Retrieve Conversation",
+    description: "Retrieve a conversation by id on the model domain's own face.",
     http: "GET",
     path: "/model/v1/conversations/{conversation_id}",
     streaming: "no",
@@ -9240,6 +9907,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "model.conversations",
     method: "update",
+    summary: "Update Conversation",
+    description: "Replace a conversation's metadata on the model domain's own face.",
     http: "POST",
     path: "/model/v1/conversations/{conversation_id}",
     streaming: "no",
@@ -9266,6 +9935,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "model.conversations.items",
     method: "list",
+    summary: "List Conversation Items",
+    description: "List a conversation's items on the model domain's own face.",
     http: "GET",
     path: "/model/v1/conversations/{conversation_id}/items",
     streaming: "no",
@@ -9281,6 +9952,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "model.conversations.items",
     method: "create",
+    summary: "Create Conversation Items",
+    description: "Add items to a conversation on the model domain's own face.",
     http: "POST",
     path: "/model/v1/conversations/{conversation_id}/items",
     streaming: "no",
@@ -9308,6 +9981,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "model.conversations.items",
     method: "delete",
+    summary: "Delete Conversation Item",
+    description: "Delete a single conversation item on the model domain's own face.",
     http: "DELETE",
     path: "/model/v1/conversations/{conversation_id}/items/{item_id}",
     streaming: "no",
@@ -9327,6 +10002,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "model.conversations.items",
     method: "retrieve",
+    summary: "Retrieve Conversation Item",
+    description: "Retrieve a single conversation item on the model domain's own face.",
     http: "GET",
     path: "/model/v1/conversations/{conversation_id}/items/{item_id}",
     streaming: "no",
@@ -9346,6 +10023,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "model.embeddings",
     method: "create",
+    summary: "Create Embedding",
+    description: "OpenAI-compatible embeddings on the model domain's own face. providerOptions.praxis is currently supported on POST /chat/completions only; sending it here answers 400.",
     http: "POST",
     path: "/model/v1/embeddings",
     streaming: "no",
@@ -9419,6 +10098,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "model.generation",
     method: "retrieve",
+    summary: "Get Generation",
+    description: "Verify the settled customer charge in USD, usage and latency for one model call. Pass the X-Praxis-Generation-Id response header or chat providerMetadata.praxis.generationId as id to praxis.model.generation.retrieve; a completion id is not a generation id. The record may take a few seconds to appear: retry a recent call's 404 shortly, without repeating the paid inference. An unknown id and another account's id also return 404; a null cost is not proof of a free call.",
     http: "GET",
     path: "/model/v1/generation",
     streaming: "no",
@@ -9436,6 +10117,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "model.images.edits",
     method: "create",
+    summary: "Edit Image",
+    description: "Edit one or more images from a text prompt, using multipart files or JSON data-URL images. Unlike OpenAI, mask is currently unavailable and returns 400; omit it and use a model supporting the requested size and image count. providerOptions.praxis is currently supported on POST /chat/completions only; sending it here answers 400.",
     http: "POST",
     path: "/model/v1/images/edits",
     streaming: "no",
@@ -9489,6 +10172,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "model.images.generations",
     method: "create",
+    summary: "Create Image",
+    description: "Generate images from a text prompt using a catalog image model. Unlike OpenAI, response_format accepts b64_json only; url returns 400. Read the selected model's support notes for sizes, quality and output format before requesting them. providerOptions.praxis is currently supported on POST /chat/completions only; sending it here answers 400.",
     http: "POST",
     path: "/model/v1/images/generations",
     streaming: "no",
@@ -9567,6 +10252,8 @@ delete it. Omit the field to preserve.`
   {
     resource: "model.messages",
     method: "create",
+    summary: "Create Message",
+    description: "Anthropic Messages API on the model domain's own face (Anthropic SDK base URL …/model; x-api-key or Bearer). providerOptions.praxis is currently supported on POST /chat/completions only; sending it here answers 400.",
     http: "POST",
     path: "/model/v1/messages",
     streaming: "optional",
@@ -9855,6 +10542,8 @@ for more details.`
   {
     resource: "model.messages",
     method: "countTokens",
+    summary: "Count Tokens",
+    description: "Anthropic token counting on the model domain's own face. Qualified native counts are marked x-praxis-token-count=exact; bundled OpenAI text tokenization and family-calibrated request estimates are marked estimated (partial; accuracy varies by family and input type).",
     http: "POST",
     path: "/model/v1/messages/count_tokens",
     streaming: "no",
@@ -10013,6 +10702,8 @@ for more details.`
   {
     resource: "model.models",
     method: "list",
+    summary: "List Models",
+    description: "Choose a model before making an inference call: list published ids, capabilities, supported_apis and prices without credentials. Unlike OpenAI, the catalog spans multiple protocols and includes per-unit USD prices; pricing.input and pricing.output are per token, not per million tokens, and a missing price is not zero. Filter with type=language for dialogue or type=embedding for vectors, and supported_api for the required protocol. Use each returned id unchanged, including any creator prefix; inspect tags for tools and field support for model-specific tool_choice or response_format limits. The response is the full matching catalog, not a paginated page.",
     http: "GET",
     path: "/model/v1/models",
     streaming: "no",
@@ -10081,6 +10772,8 @@ for more details.`
   {
     resource: "model.models",
     method: "retrieve",
+    summary: "Retrieve Model",
+    description: "Read capabilities, supported_apis and per-unit prices for one model before using it. Pass an exact id returned by praxis.model.models.list, including any creator prefix such as deepseek/deepseek-v4-pro. The object is identical to its catalog entry and requires no credentials; an unknown id returns 404.",
     http: "GET",
     path: "/model/v1/models/{model}",
     streaming: "no",
@@ -10096,6 +10789,8 @@ for more details.`
   {
     resource: "model.ocr",
     method: "create",
+    summary: "Extract document text",
+    description: "Mistral-shaped OCR on the model domain's own face. Accepts HTTPS or base64 data URLs for documents and images. Optional features depend on the selected model; unsupported options return 400. providerOptions.praxis is currently supported on POST /chat/completions only; sending it here answers 400.",
     http: "POST",
     path: "/model/v1/ocr",
     streaming: "no",
@@ -10204,6 +10899,8 @@ for more details.`
   {
     resource: "model.rerank",
     method: "create",
+    summary: "Rerank documents",
+    description: "Rank a list of documents by relevance to a query and return the best matches with scores. Use it to reorder retrieval results before you pass them to a language model; it does not generate text. Send model (a reranking model; list them with listModels?type=reranking), query and documents as an array of plain strings (object documents return 400). top_n limits how many results come back (at least 1; omit it to rank every document). Each result carries index, the zero-based position of the document in your documents array, and relevance_score from 0 to 1; results are sorted best first. Any field other than model, query, documents and top_n returns 400 input_not_representable, and 503 means no model route is available.",
     http: "POST",
     path: "/model/v1/rerank",
     streaming: "no",
@@ -10275,6 +10972,8 @@ for more details.`
   {
     resource: "model.responses",
     method: "create",
+    summary: "Create Response",
+    description: "OpenAI Responses API on the model domain's own face (OpenAI SDK base URL …/model/v1). providerOptions.praxis is currently supported on POST /chat/completions only; sending it here answers 400.",
     http: "POST",
     path: "/model/v1/responses",
     streaming: "optional",
@@ -10500,6 +11199,8 @@ for more details.`
   {
     resource: "model.responses",
     method: "compact",
+    summary: "Compact Response",
+    description: "Request context compaction for a response. Unlike OpenAI, this operation is unavailable and returns 501; do not use it to prepare a subsequent inference call.",
     http: "POST",
     path: "/model/v1/responses/compact",
     streaming: "no",
@@ -10514,6 +11215,8 @@ for more details.`
   {
     resource: "model.responses.inputTokens",
     method: "create",
+    summary: "Count Response Input Tokens",
+    description: "Request an input-token count for Responses input. Unlike OpenAI, this operation is unavailable and returns 501; use the documented Messages token-count operation only when its input shape and estimation limits fit your task.",
     http: "POST",
     path: "/model/v1/responses/input_tokens",
     streaming: "no",
@@ -10528,6 +11231,8 @@ for more details.`
   {
     resource: "model.responses",
     method: "delete",
+    summary: "Delete Response",
+    description: "Delete a stored response by its id when you no longer need to retrieve it. The response will no longer be available for later retrieval.",
     http: "DELETE",
     path: "/model/v1/responses/{response_id}",
     streaming: "no",
@@ -10543,6 +11248,8 @@ for more details.`
   {
     resource: "model.responses",
     method: "retrieve",
+    summary: "Retrieve Response",
+    description: "Read a stored response by its id from creation. A response created with store=false, an expired response, an unknown id or another account's response returns 404.",
     http: "GET",
     path: "/model/v1/responses/{response_id}",
     streaming: "no",
@@ -10558,6 +11265,8 @@ for more details.`
   {
     resource: "model.responses",
     method: "cancel",
+    summary: "Cancel Response",
+    description: "Cancel an in-progress background response using its id from creation. Unlike OpenAI, cancellation cannot guarantee that upstream compute stops; usage is settled for the output received. Repeating cancellation returns the terminal response; a synchronous response can return 400 native_responses_operation_unsupported or 404 if absent.",
     http: "POST",
     path: "/model/v1/responses/{response_id}/cancel",
     streaming: "no",
@@ -10573,6 +11282,8 @@ for more details.`
   {
     resource: "model.responses.inputItems",
     method: "list",
+    summary: "List Response Input Items",
+    description: "Read the input items of a stored response using its id from creation. Use the returned items to inspect the input that produced that response.",
     http: "GET",
     path: "/model/v1/responses/{response_id}/input_items",
     streaming: "no",
@@ -10588,6 +11299,8 @@ for more details.`
   {
     resource: "model.videos",
     method: "list",
+    summary: "List videos",
+    description: "OpenAI video API with OpenRouter request and response extensions.",
     http: "GET",
     path: "/model/v1/videos",
     streaming: "no",
@@ -10621,6 +11334,8 @@ for more details.`
   {
     resource: "model.videos",
     method: "create",
+    summary: "Create video",
+    description: "OpenAI video API with OpenRouter request and response extensions.",
     http: "POST",
     path: "/model/v1/videos",
     streaming: "no",
@@ -10723,6 +11438,8 @@ for more details.`
   {
     resource: "model.videos",
     method: "delete",
+    summary: "Delete video",
+    description: "OpenAI video API with OpenRouter request and response extensions.",
     http: "DELETE",
     path: "/model/v1/videos/{video_id}",
     streaming: "no",
@@ -10738,6 +11455,8 @@ for more details.`
   {
     resource: "model.videos",
     method: "retrieve",
+    summary: "Retrieve video",
+    description: "OpenAI video API with OpenRouter request and response extensions.",
     http: "GET",
     path: "/model/v1/videos/{video_id}",
     streaming: "no",
@@ -10753,6 +11472,8 @@ for more details.`
   {
     resource: "model.videos",
     method: "retrieveContent",
+    summary: "Download video",
+    description: "OpenAI video API with OpenRouter request and response extensions.",
     http: "GET",
     path: "/model/v1/videos/{video_id}/content",
     streaming: "no",
@@ -10786,6 +11507,8 @@ for more details.`
   {
     resource: "model.videos",
     method: "remix",
+    summary: "Remix video",
+    description: "Not supported in this release; always returns 400.",
     http: "POST",
     path: "/model/v1/videos/{video_id}/remix",
     streaming: "no",
@@ -10801,6 +11524,9 @@ for more details.`
   {
     resource: "organization.charges",
     method: "list",
+    summary: "Export Organization Charges",
+    description: `FOCUS 1.3 subset export, one JSON record per line (application/x-ndjson), one record per usage event, paginating the window day by day server-side. The sum of BilledCost over all lines equals the costs endpoint's total for the same window.
+`,
     http: "GET",
     path: "/organization/v1/charges",
     streaming: "no",
@@ -10824,6 +11550,9 @@ for more details.`
   {
     resource: "organization.costs",
     method: "list",
+    summary: "List Organization Costs",
+    description: `Billed cost per time bucket per group (AWS GetCostAndUsage shape). Buckets are whole UTC hour/day periods; a window is answered over the aligned envelope covering it. Amounts are exact decimal strings in the currency the organization was charged in (BillingCurrency, CNY or USD); a group charged in two currencies is two results. estimated is always false: charges are final when they are recorded. Windows span at most 93 days; longer ranges belong to the charges export.
+`,
     http: "GET",
     path: "/organization/v1/costs",
     streaming: "no",
@@ -10884,6 +11613,9 @@ for more details.`
   {
     resource: "organization.events",
     method: "list",
+    summary: "List Organization Usage Events",
+    description: `Usage events newest first, one opaque cursor page at a time; a page never duplicates or skips an event. Every item carries its metering lines (meter, display name, consumed quantity and unit, mapped from the billing measurements); the per-line price split (list unit price, pricing unit, billed cost) rides only the single event — fetch /organization/v1/events/{id} for it.
+`,
     http: "GET",
     path: "/organization/v1/events",
     streaming: "no",
@@ -10919,6 +11651,9 @@ for more details.`
   {
     resource: "organization.events",
     method: "retrieve",
+    summary: "Get One Organization Usage Event",
+    description: `One event with its usage line (meter display name, consumed quantity and unit, billed cost; ListUnitPrice and PricingUnit are null because billing prices an event as a whole), its settlement status and x_Charges, the transactions that paid it (promotional balance is taken before cash). A nonexistent id and another organization's id are indistinguishable: both answer the same 404 problem body except X-Request-Id.
+`,
     http: "GET",
     path: "/organization/v1/events/{id}",
     streaming: "no",
@@ -10934,6 +11669,8 @@ for more details.`
   {
     resource: "organization.feedback",
     method: "create",
+    summary: "Report a problem with the Praxis platform",
+    description: `Report a problem with the Praxis platform when an API fails, documentation is unclear, or a capability is missing. AI callers in codemode should include the original error text in message, the X-Request-Id or error event ID in associated_event_id, and relevant session, agent, model, or request IDs in contexts. Continue the user's task after reporting. Each successful call stores feedback and returns its id; repeated calls create separate reports. The authenticated principal determines the reporter; any reporter supplied in the body is ignored. Machine tokens force source to codemode. Requires a valid API key, Console session, or machine token. Minimal body: {"message":"The API documentation does not explain this error."}.`,
     http: "POST",
     path: "/organization/v1/feedback",
     streaming: "no",
@@ -11008,6 +11745,9 @@ for more details.`
   {
     resource: "organization.usage",
     method: "list",
+    summary: "List Organization Usage",
+    description: `Consumed quantity per time bucket per group. Buckets are whole UTC hour/day periods covering the requested window. Each result carries exactly one ConsumedQuantity + ConsumedUnit — quantities of different units are never added together.
+`,
     http: "GET",
     path: "/organization/v1/usage",
     streaming: "no",
@@ -11068,6 +11808,8 @@ for more details.`
   {
     resource: "sandbox.sandboxes",
     method: "list",
+    summary: "List sandboxes (v2)",
+    description: "List your running and paused sandboxes with paging and filters. Use it to find a sandboxID before connecting to, pausing or killing a sandbox. Filter by state, template (id or alias), name, metadata (key=value pairs joined with &) and startedAfter; order sorts by start time (default newest first); limit is 1 to 100 (default 100). When more results exist the response carries an x-next-token header; send it back as nextToken for the next page. To read one sandbox use getSandbox.",
     http: "GET",
     path: "/sandbox/v1/sandboxes",
     streaming: "no",
@@ -11136,6 +11878,8 @@ for more details.`
   {
     resource: "sandbox.sandboxes",
     method: "create",
+    summary: "Create sandbox (v2)",
+    description: "Start an isolated environment using a templateID from templates.list, then retain sandboxID for lifecycle calls. Unlike E2B, templateID resolves to your ready Environment or a public Base; omit it to use the default base template (`base`), as the E2B SDK does. timeout is seconds from creation and defaults to 300. envVars supplies environment variables and metadata stores your string labels. All system communication is secured; use the returned envdAccessToken for files and commands through the envd data plane, not the management methods. Never print that token.",
     http: "POST",
     path: "/sandbox/v1/sandboxes",
     streaming: "no",
@@ -11224,6 +11968,8 @@ for more details.`
   {
     resource: "sandbox.sandboxes",
     method: "delete",
+    summary: "Kill sandbox",
+    description: "Kill a sandbox: stop it and release its resources for good. Use it when you are done with the sandbox; to keep its state for later use pause it instead with pauseSandbox. Success answers 204 with no body, and a killed sandbox answers 404 afterwards.",
     http: "DELETE",
     path: "/sandbox/v1/sandboxes/{sandboxID}",
     streaming: "no",
@@ -11239,6 +11985,8 @@ for more details.`
   {
     resource: "sandbox.sandboxes",
     method: "retrieve",
+    summary: "Sandbox",
+    description: "Read one sandbox: its state (running or paused), template, resources, start time and expiry (endAt), plus the access token for its data plane when it is running. Use it to poll the state or the remaining lifetime of a sandbox; to find sandboxes use listSandboxes. An unknown id or another team's sandbox answers 404.",
     http: "GET",
     path: "/sandbox/v1/sandboxes/{sandboxID}",
     streaming: "no",
@@ -11254,6 +12002,8 @@ for more details.`
   {
     resource: "sandbox.sandboxes",
     method: "update",
+    summary: "Rename a sandbox",
+    description: "Rename your sandbox. Names are trimmed, must contain 1–64 characters after trimming, and must be unique within your team. Only name may be changed. Returns the updated sandbox detail, as GET does. Killed or unavailable sandboxes return 404.",
     http: "PATCH",
     path: "/sandbox/v1/sandboxes/{sandboxID}",
     streaming: "no",
@@ -11280,6 +12030,8 @@ for more details.`
   {
     resource: "sandbox.sandboxes",
     method: "connect",
+    summary: "Connect sandbox (v2)",
+    description: "Reconnect to an existing sandbox and resume it if paused. The optional timeout is seconds from now and defaults to 300; a later existing deadline is preserved. A running sandbox returns 200 and a resumed sandbox returns 201. Read sandboxID, domain and envdAccessToken from the response for subsequent data-plane access; never treat connecting as executing a command.",
     http: "POST",
     path: "/sandbox/v1/sandboxes/{sandboxID}/connect",
     streaming: "no",
@@ -11312,6 +12064,8 @@ for more details.`
   {
     resource: "sandbox.sandboxes",
     method: "extend",
+    summary: "Extend a running sandbox without shortening its deadline",
+    description: "Extend a running sandbox only when it needs a later expiry; this never resumes a paused sandbox. Timeout is seconds from now, not added to the prior deadline, and must be 900, 1800 or 3600. Returns 409 for paused, expired, or non-extending requests.",
     http: "POST",
     path: "/sandbox/v1/sandboxes/{sandboxID}/extend",
     streaming: "no",
@@ -11343,6 +12097,8 @@ for more details.`
   {
     resource: "sandbox.sandboxes",
     method: "fork",
+    summary: "Fork sandbox",
+    description: "Fork the sandbox: checkpoint the running sandbox in place (it is briefly paused, snapshotted with its full memory state, and resumed on its node, keeping its ID and expiration untouched) and create count new sandboxes from that snapshot. Returns one result per requested fork, each carrying either the created sandbox or the error that prevented it from starting. A non-201 status means the request failed before any fork was attempted.",
     http: "POST",
     path: "/sandbox/v1/sandboxes/{sandboxID}/fork",
     streaming: "no",
@@ -11375,6 +12131,8 @@ for more details.`
   {
     resource: "sandbox.sandboxes.logs",
     method: "list",
+    summary: "Sandbox logs (v2)",
+    description: "Read the log lines of a sandbox. Use it to debug what ran inside a sandbox. cursor is a start timestamp in milliseconds, direction chooses forward or backward from it, level sets the lowest level to return, search is a case-sensitive substring filter (at most 256 characters) and limit caps the count (at most 1000, default 1000). To continue, pass the timestamp of the last entry as the next cursor.",
     http: "GET",
     path: "/sandbox/v1/sandboxes/{sandboxID}/logs",
     streaming: "no",
@@ -11431,6 +12189,8 @@ for more details.`
   {
     resource: "sandbox.sandboxes.metrics",
     method: "list",
+    summary: "Sandbox metrics",
+    description: "Read CPU, memory and disk usage over the requested interval; start and end are Unix seconds. Unlike E2B, light sandboxes do not provide metrics; check the returned capabilities before requesting them.",
     http: "GET",
     path: "/sandbox/v1/sandboxes/{sandboxID}/metrics",
     streaming: "no",
@@ -11459,6 +12219,8 @@ for more details.`
   {
     resource: "sandbox.sandboxes",
     method: "updateNetwork",
+    summary: "Update sandbox network",
+    description: "Update the network configuration for a running sandbox. Replaces the current egress rules with the provided configuration. Omitting field clears it.",
     http: "PUT",
     path: "/sandbox/v1/sandboxes/{sandboxID}/network",
     streaming: "no",
@@ -11512,6 +12274,8 @@ for more details.`
   {
     resource: "sandbox.sandboxes",
     method: "pause",
+    summary: "Pause sandbox",
+    description: "Suspend a running sandbox for later connection; use delete to discard it instead. Unlike E2B, light sandboxes preserve disk rather than memory, and persistent sandboxes can resume on data-plane traffic even when autoResume is false. Inspect paused state with the management retrieve operation to avoid waking the sandbox. Explicitly ephemeral sandboxes cannot pause. memory defaults to true, but only a memory-capable sandbox preserves running processes; memory=false saves disk state and resumes with a cold boot. Success returns 204; connect resumes the saved sandbox.",
     http: "POST",
     path: "/sandbox/v1/sandboxes/{sandboxID}/pause",
     streaming: "no",
@@ -11538,6 +12302,8 @@ for more details.`
   {
     resource: "sandbox.sandboxes.processes",
     method: "list",
+    summary: "List live processes and retained observations",
+    description: "Inspect live processes and retained observations; this does not start a command. Praxis observation, not complete provider history. Only a witnessed exit event establishes exitCode; disconnects and restarts leave gaps and unknown state. Output retains at most 1 MiB/1024 chunks per process and 4 MiB/4096 chunks per instance across 256 observations. Truncation is explicit. Output data is base64; timestamps are Unix milliseconds. Reading never resumes a paused sandbox.",
     http: "GET",
     path: "/sandbox/v1/sandboxes/{sandboxID}/processes",
     streaming: "no",
@@ -11565,6 +12331,8 @@ for more details.`
   {
     resource: "sandbox.sandboxes.processes",
     method: "retrieveOutput",
+    summary: "Read bounded observed process output",
+    description: "Read retained stdout and stderr chunks for a processID returned by processes.list. Praxis observation, not complete provider history. Only a witnessed exit event establishes exitCode; disconnects and restarts leave gaps and unknown state. Output retains at most 1 MiB/1024 chunks per process and 4 MiB/4096 chunks per instance across 256 observations. Truncation is explicit. Output data is base64; timestamps are Unix milliseconds. Reading never resumes a paused sandbox.",
     http: "GET",
     path: "/sandbox/v1/sandboxes/{sandboxID}/processes/{processID}/output",
     streaming: "no",
@@ -11584,6 +12352,8 @@ for more details.`
   {
     resource: "sandbox.sandboxes.snapshots",
     method: "create",
+    summary: "Create snapshot",
+    description: "Create a persistent snapshot from the sandbox's current state. Snapshots can be used to create new sandboxes and persist beyond the original sandbox's lifetime.",
     http: "POST",
     path: "/sandbox/v1/sandboxes/{sandboxID}/snapshots",
     streaming: "no",
@@ -11610,6 +12380,8 @@ for more details.`
   {
     resource: "sandbox.sandboxes",
     method: "timeout",
+    summary: "Set sandbox timeout",
+    description: "Set the timeout for the sandbox. The sandbox will expire x seconds from the time of the request. Calling this method multiple times overwrites the TTL, each time using the current timestamp as the starting point to measure the timeout duration.",
     http: "POST",
     path: "/sandbox/v1/sandboxes/{sandboxID}/timeout",
     streaming: "no",
@@ -11636,6 +12408,8 @@ for more details.`
   {
     resource: "sandbox.sandboxes.upgrade",
     method: "create",
+    summary: "Upgrade to a full sandbox",
+    description: "Move a light sandbox to a full environment when its capabilities are insufficient. Stops active processes and terminals, migrates files, and preserves the sandbox ID and name. Reconnect with the new envdAccessToken. A failed migration preserves source files but does not restart terminated processes.",
     http: "POST",
     path: "/sandbox/v1/sandboxes/{sandboxID}/upgrade",
     streaming: "no",
@@ -11662,6 +12436,8 @@ for more details.`
   {
     resource: "sandbox.sandboxes.commands",
     method: "run",
+    summary: "Run a command in the sandbox",
+    description: 'Execute a shell command and wait for stdout, stderr and exitCode. Supply cmd, optional cwd and envs, and timeoutMs (1–60000 milliseconds, default 60000). Unlike E2B, this endpoint is synchronous only: no background mode, callbacks or unlimited timeout; output is bounded to 1 MiB including stream framing. Nonzero exit codes return 200 with the result. A timeout returns COMMAND_TIMEOUT (504); transport timeout does not confirm process termination, so do not blindly retry commands with side effects. Example body: {"cmd":"echo hi"}.',
     http: "POST",
     path: "/sandbox/v1/sandboxes/{sandbox_id}/commands",
     streaming: "no",
@@ -11706,6 +12482,8 @@ for more details.`
   {
     resource: "sandbox.sandboxes.files",
     method: "remove",
+    summary: "Remove a file or directory in the sandbox",
+    description: "Remove an unneeded file or recursively remove a directory and its contents. This permanently deletes the selected path; read any needed content first. Returns 204 after removal.",
     http: "DELETE",
     path: "/sandbox/v1/sandboxes/{sandbox_id}/files",
     streaming: "no",
@@ -11728,6 +12506,8 @@ for more details.`
   {
     resource: "sandbox.sandboxes.files",
     method: "read",
+    summary: "Read a file in the sandbox",
+    description: "Read UTF-8 file content when a command needs input or produced a text artifact. Returns a JSON string. Unlike E2B, this endpoint supports text only and rejects output above 1 MiB; binary and streaming reads are unavailable.",
     http: "GET",
     path: "/sandbox/v1/sandboxes/{sandbox_id}/files",
     streaming: "no",
@@ -11750,6 +12530,8 @@ for more details.`
   {
     resource: "sandbox.sandboxes.files",
     method: "write",
+    summary: "Write a file in the sandbox",
+    description: 'Write a file in the sandbox before running a command. Replaces the target content and creates missing parent directories. Unlike E2B, this endpoint accepts one UTF-8 text file per request, at most 1 MiB; binary and batch writes are unavailable. Example body: {"path":"/tmp/hello.txt","data":"hello"}.',
     http: "PUT",
     path: "/sandbox/v1/sandboxes/{sandbox_id}/files",
     streaming: "no",
@@ -11782,6 +12564,8 @@ for more details.`
   {
     resource: "sandbox.sandboxes.files",
     method: "list",
+    summary: "List files in a sandbox directory",
+    description: "Inspect a directory to find paths to read or remove. Returns immediate children with name, path, type and size. Unlike E2B, recursive depth is unavailable and responses are limited to 1 MiB.",
     http: "GET",
     path: "/sandbox/v1/sandboxes/{sandbox_id}/files:list",
     streaming: "no",
@@ -11804,6 +12588,8 @@ for more details.`
   {
     resource: "sandbox.sandboxes.files",
     method: "makeDir",
+    summary: "Create a directory in the sandbox",
+    description: "Create a directory and missing parent directories before writing files. Returns true when created or false when the path already exists. Supply the path as a query parameter.",
     http: "POST",
     path: "/sandbox/v1/sandboxes/{sandbox_id}/files:makeDir",
     streaming: "no",
@@ -11826,6 +12612,8 @@ for more details.`
   {
     resource: "sandbox.snapshots",
     method: "list",
+    summary: "List snapshots",
+    description: "List the snapshots you created, one cursor page at a time. Use it to find a snapshot id before you create a sandbox from it or delete it. Filter by sandboxID (the source sandbox) or by name or snapshot id, optionally tag-qualified; limit is 1 to 100 (default 100). When more results exist send the cursor from the response back as nextToken.",
     http: "GET",
     path: "/sandbox/v1/snapshots",
     streaming: "no",
@@ -11861,6 +12649,8 @@ for more details.`
   {
     resource: "sandbox.snapshots",
     method: "delete",
+    summary: "Delete template",
+    description: "Delete one of your snapshots. Sandboxes already created from it keep running; no new sandbox can be created from it afterwards. Success answers 204. A snapshot that does not exist or belongs to someone else answers 404.",
     http: "DELETE",
     path: "/sandbox/v1/snapshots/{snapshotID}",
     streaming: "no",
@@ -11876,6 +12666,8 @@ for more details.`
   {
     resource: "sandbox.templates",
     method: "list",
+    summary: "List templates (v2)",
+    description: "Choose a templateID before creating a sandbox. Unlike E2B, this catalog lists your ready Environments and public Bases; use a returned ID or alias; `base` is the default template that create uses when templateID is omitted. Page through results using nextToken.",
     http: "GET",
     path: "/sandbox/v1/templates",
     streaming: "no",
@@ -11905,6 +12697,8 @@ for more details.`
   {
     resource: "sandbox.volumes",
     method: "list",
+    summary: "List team volumes",
+    description: "List the volumes of your team. Use it to find a volumeID before reading or deleting a volume, or to attach a volume to a sandbox by name when you create it.",
     http: "GET",
     path: "/sandbox/v1/volumes",
     streaming: "no",
@@ -11915,6 +12709,8 @@ for more details.`
   {
     resource: "sandbox.volumes",
     method: "create",
+    summary: "Create team volume",
+    description: "Create a team volume: persistent storage that can be mounted into sandboxes and outlives them. Send the volume name; the response returns the volume id and name. Use getVolume to read it back and deleteVolume to remove it.",
     http: "POST",
     path: "/sandbox/v1/volumes",
     streaming: "no",
@@ -11936,6 +12732,8 @@ for more details.`
   {
     resource: "sandbox.volumes",
     method: "delete",
+    summary: "Delete team volume",
+    description: "Delete a team volume and its data permanently. Use it only when no sandbox needs the volume any more; the data cannot be recovered. Success answers 204; an unknown id answers 404.",
     http: "DELETE",
     path: "/sandbox/v1/volumes/{volumeID}",
     streaming: "no",
@@ -11951,6 +12749,8 @@ for more details.`
   {
     resource: "sandbox.volumes",
     method: "retrieve",
+    summary: "Team volume",
+    description: "Read one team volume by id. Use it to confirm a volume exists and to read its name before mounting it in a sandbox. An unknown id answers 404.",
     http: "GET",
     path: "/sandbox/v1/volumes/{volumeID}",
     streaming: "no",
@@ -11966,6 +12766,8 @@ for more details.`
   {
     resource: "search.crawl",
     method: "create",
+    summary: "Initiate a web crawl from a base URL",
+    description: "Tavily Crawl is a graph-based website traversal tool that can explore hundreds of paths in parallel with built-in extraction and intelligent discovery.",
     http: "POST",
     path: "/search/v1/crawl",
     streaming: "no",
@@ -12095,6 +12897,8 @@ for more details.`
   {
     resource: "search.extract",
     method: "create",
+    summary: "Retrieve raw web content from specified URLs",
+    description: "Extract content from one URL or batch up to 20 URLs in one request. Successful URLs appear in results; per-URL failures appear in failed_results. Check both arrays even when the response is HTTP 200. Request options apply to every URL in the batch.",
     http: "POST",
     path: "/search/v1/extract",
     streaming: "no",
@@ -12172,6 +12976,8 @@ for more details.`
   {
     resource: "search.map",
     method: "create",
+    summary: "Initiate a web mapping from a base URL",
+    description: "Tavily Map traverses websites like a graph and can explore hundreds of paths in parallel with intelligent discovery to generate comprehensive site maps.",
     http: "POST",
     path: "/search/v1/map",
     streaming: "no",
@@ -12263,6 +13069,8 @@ for more details.`
   {
     resource: "search.search",
     method: "create",
+    summary: "Search for data based on a query",
+    description: "Search the web and return ranked results with extracted content. Use it to answer questions with current information; to read the full text of known URLs use searchExtract, to walk a site use searchCrawl and to list a site's URLs use searchMap. query is required. topic chooses general, news or finance; time_range limits results to the last day, week, month or year; country boosts results from one country (topic general only). Each result carries title, url, content and a relevance score, and the response can include a generated answer, images and follow-up questions when requested.",
     http: "POST",
     path: "/search/v1/search",
     streaming: "no",
@@ -12623,6 +13431,8 @@ for more details.`
   {
     resource: "vault.authorizations",
     method: "create",
+    summary: "Create authorization",
+    description: "Connect an OAuth service to an active vault using either an OAuth template or a resource URL. Unlike Anthropic mcp_oauth credential creation, this flow obtains tokens through user consent rather than accepting an auth token bundle; compatible mcp_oauth creation and updates return 501. Open connect_url, then poll praxis.vault.authorizations.retrieve until completed, failed or expired; only completed supplies the resulting secret_id. This stores a credential but does not enable vault-backed MCP authentication in Agent sessions.",
     http: "POST",
     path: "/vault/v1/authorizations",
     streaming: "no",
@@ -12666,6 +13476,8 @@ for more details.`
   {
     resource: "vault.authorizations",
     method: "retrieveCallback",
+    summary: "Authorization callback",
+    description: "Receive the authorization server's OAuth callback with single-use state and an authorization code or error. Completion creates or updates an OAuth secret; the browser is redirected to return_url when provided, otherwise shown a result page.",
     http: "GET",
     path: "/vault/v1/authorizations/callback",
     streaming: "no",
@@ -12676,6 +13488,8 @@ for more details.`
   {
     resource: "vault.authorizations",
     method: "retrieve",
+    summary: "Get authorization",
+    description: "Retrieve an authorization belonging to your account, including its current status and resulting secret_id. An unfinished authorization past expires_at is reported as expired.",
     http: "GET",
     path: "/vault/v1/authorizations/{authorization_id}",
     streaming: "no",
@@ -12691,6 +13505,8 @@ for more details.`
   {
     resource: "vault.connect",
     method: "retrieve",
+    summary: "Connect page",
+    description: "Display the user consent page for a connect_url token without requiring an API key. The page shows the requester, resource host and requested scopes before the user continues or denies.",
     http: "GET",
     path: "/vault/v1/connect/{token}",
     streaming: "no",
@@ -12706,6 +13522,8 @@ for more details.`
   {
     resource: "vault.connect.continue",
     method: "create",
+    summary: "Continue authorization",
+    description: "Consume a pending authorization's one-time connect token and redirect the browser to the authorization server. Expired or already used links cannot start another authorization flow.",
     http: "POST",
     path: "/vault/v1/connect/{token}/continue",
     streaming: "no",
@@ -12721,6 +13539,8 @@ for more details.`
   {
     resource: "vault.connect.deny",
     method: "create",
+    summary: "Deny authorization",
+    description: "Consume a pending authorization's one-time connect token and mark it failed with access_denied. Redirect to the configured return URL, or display a result page when none was supplied.",
     http: "POST",
     path: "/vault/v1/connect/{token}/deny",
     streaming: "no",
@@ -12736,6 +13556,8 @@ for more details.`
   {
     resource: "vault.oauth",
     method: "retrieveClientMetadata",
+    summary: "OAuth client metadata",
+    description: "Return the public OAuth client metadata used by authorization servers that support CIMD. The document declares the Praxis client identity and callback URL; no API key is required.",
     http: "GET",
     path: "/vault/v1/oauth/client.json",
     streaming: "no",
@@ -12746,6 +13568,8 @@ for more details.`
   {
     resource: "vault.settings.returnUrls",
     method: "list",
+    summary: "Get return URLs",
+    description: "Read your account's allowlist of OAuth return URLs. The list is empty until configured, and authorization return_url values must match an entry exactly.",
     http: "GET",
     path: "/vault/v1/settings/return_urls",
     streaming: "no",
@@ -12756,6 +13580,8 @@ for more details.`
   {
     resource: "vault.settings.returnUrls",
     method: "update",
+    summary: "Set return URLs",
+    description: "Replace your account's complete allowlist of OAuth return URLs. Entries are deduplicated after validation; an empty array clears the allowlist.",
     http: "PUT",
     path: "/vault/v1/settings/return_urls",
     streaming: "no",
@@ -12778,6 +13604,8 @@ for more details.`
   {
     resource: "vault.templates",
     method: "list",
+    summary: "List templates",
+    description: "List templates for manually supplied static secrets and OAuth authorizations. Templates provide suggested names and allowed hosts; they are not stored secrets.",
     http: "GET",
     path: "/vault/v1/templates",
     streaming: "no",
@@ -12788,6 +13616,8 @@ for more details.`
   {
     resource: "vault.vaults",
     method: "list",
+    summary: "List vaults",
+    description: "List vaults belonging to your account, newest first. Archived vaults are excluded unless include_archived is true; use next_cursor to request another page.",
     http: "GET",
     path: "/vault/v1/vaults",
     streaming: "no",
@@ -12817,6 +13647,8 @@ for more details.`
   {
     resource: "vault.vaults",
     method: "create",
+    summary: "Create vault",
+    description: "Create an empty, active vault to hold credentials for your account, with a display name and optional metadata. Use its returned id as vault_id when creating secrets or OAuth authorizations. Unlike Anthropic, Agent sessions do not accept nonempty vault_ids; storing a credential or adding its ID to metadata does not enable vault-backed MCP authentication. Application vault references are also unavailable; praxis_vault_ref version bindings and secret writes with a vault source return 501, so creating a vault does not yet enable either consumer.",
     http: "POST",
     path: "/vault/v1/vaults",
     streaming: "no",
@@ -12844,6 +13676,8 @@ for more details.`
   {
     resource: "vault.vaults",
     method: "delete",
+    summary: "Delete vault",
+    description: "Permanently delete a vault, its secrets, authorizations and previous audit events. Only a vault deletion event remains; the deleted vault can no longer be retrieved.",
     http: "DELETE",
     path: "/vault/v1/vaults/{vault_id}",
     streaming: "no",
@@ -12859,6 +13693,8 @@ for more details.`
   {
     resource: "vault.vaults",
     method: "retrieve",
+    summary: "Get vault",
+    description: "Retrieve a vault belonging to your account, including archived vaults and secret counts. Missing or other accounts' vaults return VAULT_NOT_FOUND.",
     http: "GET",
     path: "/vault/v1/vaults/{vault_id}",
     streaming: "no",
@@ -12874,6 +13710,8 @@ for more details.`
   {
     resource: "vault.vaults",
     method: "update",
+    summary: "Update vault",
+    description: "Update an active vault's display name or patch its metadata. Omitted fields are preserved; archived vaults cannot be updated.",
     http: "POST",
     path: "/vault/v1/vaults/{vault_id}",
     streaming: "no",
@@ -12906,6 +13744,8 @@ for more details.`
   {
     resource: "vault.vaults",
     method: "archive",
+    summary: "Archive vault",
+    description: "Archive a vault and all its remaining secrets, erasing their values while retaining metadata and audit history. An already archived vault is returned unchanged.",
     http: "POST",
     path: "/vault/v1/vaults/{vault_id}/archive",
     streaming: "no",
@@ -12921,6 +13761,8 @@ for more details.`
   {
     resource: "vault.vaults.events",
     method: "list",
+    summary: "List events",
+    description: "List a vault's audit events, newest first, without secret values. Filter by secret ID or name; a name includes archived and deleted secrets that carried it. An unknown secret returns an empty page.",
     http: "GET",
     path: "/vault/v1/vaults/{vault_id}/events",
     streaming: "no",
@@ -12955,6 +13797,8 @@ for more details.`
   {
     resource: "vault.vaults.secrets",
     method: "list",
+    summary: "List secrets",
+    description: "List secret metadata in a vault, newest first, without returning values. Archived secrets are excluded unless include_archived is true.",
     http: "GET",
     path: "/vault/v1/vaults/{vault_id}/secrets",
     streaming: "no",
@@ -12989,6 +13833,8 @@ for more details.`
   {
     resource: "vault.vaults.secrets",
     method: "create",
+    summary: "Create secret",
+    description: "Store a manually supplied token in an active vault for use on requests to its allowed_hosts. Unlike Anthropic credentials, this native operation takes name, value and allowed_hosts directly and creates only static secrets; use praxis.vault.authorizations.create for OAuth. Its name must be unused by any non-archived secret in that vault; the response contains metadata but never the supplied value. Application praxis_vault_ref bindings declare vault_id and secret (the secret name), but currently return 501; do not copy the value into a plain-text binding or metadata as a substitute.",
     http: "POST",
     path: "/vault/v1/vaults/{vault_id}/secrets",
     streaming: "no",
@@ -13061,6 +13907,8 @@ for more details.`
   {
     resource: "vault.vaults.secrets",
     method: "delete",
+    summary: "Delete secret",
+    description: "Permanently delete a secret and its previous audit events. A deletion event retaining the secret ID and name remains, and other secrets are unchanged.",
     http: "DELETE",
     path: "/vault/v1/vaults/{vault_id}/secrets/{secret}",
     streaming: "no",
@@ -13080,6 +13928,8 @@ for more details.`
   {
     resource: "vault.vaults.secrets",
     method: "retrieve",
+    summary: "Get secret",
+    description: "Inspect a secret's kind, allowed_hosts, status and version without reading its value. Unlike Anthropic credential lookup by ID, this native operation accepts either the name or the vsec_ ID returned by secret creation or listing. A name selects a non-archived secret; use the secret ID to retrieve an archived secret.",
     http: "GET",
     path: "/vault/v1/vaults/{vault_id}/secrets/{secret}",
     streaming: "no",
@@ -13099,6 +13949,8 @@ for more details.`
   {
     resource: "vault.vaults.secrets",
     method: "update",
+    summary: "Update secret",
+    description: "Rotate a non-archived secret in an active vault by supplying value, or patch its hosts, description or metadata. Unlike Anthropic credential updates, this native operation accepts the replacement value directly, without an auth object. Each supplied value increments version, even if unchanged, and can recover an OAuth secret from refresh_failed; the secret ID, name and kind stay unchanged. Omit value for a metadata-only edit; existing references do not need a new secret ID or name.",
     http: "POST",
     path: "/vault/v1/vaults/{vault_id}/secrets/{secret}",
     streaming: "no",
@@ -13148,6 +14000,8 @@ for more details.`
   {
     resource: "vault.vaults.secrets",
     method: "archive",
+    summary: "Archive secret",
+    description: "Archive a secret, erase its value and release its name for reuse. Metadata and audit history remain; use its ID for subsequent reads or repeated archive requests.",
     http: "POST",
     path: "/vault/v1/vaults/{vault_id}/secrets/{secret}/archive",
     streaming: "no",
@@ -13167,6 +14021,8 @@ for more details.`
   {
     resource: "vault.vaults.secrets.refresh",
     method: "create",
+    summary: "Refresh secret",
+    description: "Request an OAuth secret refresh and return its current metadata without token values. Refresh may be skipped if already in progress, unavailable or in refresh_failed; inspect the returned status and oauth fields.",
     http: "POST",
     path: "/vault/v1/vaults/{vault_id}/secrets/{secret}/refresh",
     streaming: "no",
@@ -13200,6 +14056,8 @@ for more details.`
   {
     resource: "vault.vaults.secrets.validate",
     method: "create",
+    summary: "Validate secret",
+    description: "Probe an OAuth secret's resource with its access token, attempting refresh first if the token has expired. Return the validation verdict and sanitized HTTP summaries; static secrets are unsupported.",
     http: "POST",
     path: "/vault/v1/vaults/{vault_id}/secrets/{secret}/validate",
     streaming: "no",
@@ -13219,6 +14077,8 @@ for more details.`
   {
     resource: "vault.vaults.secrets",
     method: "import",
+    summary: "Import secrets",
+    description: "Import lines or dotenv text into an active vault, reporting success or failure for each entry. Existing names have their values replaced; their hosts change only when that line supplies allowed_hosts. Shared hosts apply only to newly created secrets.",
     http: "POST",
     path: "/vault/v1/vaults/{vault_id}/secrets:import",
     streaming: "no",
@@ -13259,6 +14119,8 @@ for more details.`
   {
     resource: "vault.vaults",
     method: "check",
+    summary: "Check vaults",
+    description: "Check the availability of each supplied vault ID in request order. Missing, malformed and other accounts' IDs all return not_found; duplicate IDs are preserved.",
     http: "POST",
     path: "/vault/v1/vaults:check",
     streaming: "no",
@@ -14102,6 +14964,49 @@ var createClient = (config = {}) => {
 var client = createClient(createConfig({ baseUrl: "https://api.deepraxis.com" }));
 
 // ../../packages/sdk/typescript/src/generated/sdk.gen.ts
+var deleteRunFeedback = (options) => (options.client ?? client).delete({
+  security: [{
+    key: "BearerAuth",
+    scheme: "bearer",
+    type: "http"
+  }, {
+    key: "ApiKeyAuth",
+    name: "X-API-Key",
+    type: "apiKey"
+  }],
+  url: "/agent/v1/sessions/{session_id}/runs/{run_id}/feedback",
+  ...options
+});
+var setRunFeedback = (options) => (options.client ?? client).post({
+  security: [{
+    key: "BearerAuth",
+    scheme: "bearer",
+    type: "http"
+  }, {
+    key: "ApiKeyAuth",
+    name: "X-API-Key",
+    type: "apiKey"
+  }],
+  url: "/agent/v1/sessions/{session_id}/runs/{run_id}/feedback",
+  ...options,
+  headers: {
+    "Content-Type": "application/json",
+    ...options.headers
+  }
+});
+var listEmbedTokens = (options) => (options?.client ?? client).get({
+  security: [{
+    key: "BearerAuth",
+    scheme: "bearer",
+    type: "http"
+  }, {
+    key: "ApiKeyAuth",
+    name: "X-API-Key",
+    type: "apiKey"
+  }],
+  url: "/agent/v1/embed_tokens",
+  ...options
+});
 var createEmbedToken = (options) => (options.client ?? client).post({
   security: [{
     key: "BearerAuth",
@@ -14119,6 +15024,19 @@ var createEmbedToken = (options) => (options.client ?? client).post({
     ...options.headers
   }
 });
+var revokeEmbedToken = (options) => (options.client ?? client).post({
+  security: [{
+    key: "BearerAuth",
+    scheme: "bearer",
+    type: "http"
+  }, {
+    key: "ApiKeyAuth",
+    name: "X-API-Key",
+    type: "apiKey"
+  }],
+  url: "/agent/v1/embed_tokens/{id}/revoke",
+  ...options
+});
 var computersList = (options) => (options?.client ?? client).get({
   security: [{
     key: "BearerAuth",
@@ -18936,7 +19854,11 @@ function createAgent(transport) {
       update: bind(transport, deploymentsUpdate)
     },
     embedTokens: {
-      create: bind(transport, createEmbedToken)
+      create: bind(transport, createEmbedToken),
+      list: bind(transport, listEmbedTokens),
+      revoke: {
+        create: bind(transport, revokeEmbedToken)
+      }
     },
     environments: {
       archive: bind(transport, environmentsArchive),
@@ -18973,6 +19895,12 @@ function createAgent(transport) {
       retrieve: bind(transport, sessionsRetrieve),
       retrieveCompact: bind(transport, getSessionCompaction),
       retrieveContext: bind(transport, getSessionContext),
+      runs: {
+        deleteFeedback: bind(transport, deleteRunFeedback),
+        feedback: {
+          create: bind(transport, setRunFeedback)
+        }
+      },
       threads: {
         archive: bind(transport, aliasOperation(sessionsThreadsArchive, { query: { session_id: "query_session_id" } })),
         events: {
@@ -20175,7 +21103,7 @@ function commandTree(operations2) {
       const key = words.join(" ");
       if (seen.has(key))
         throw new Error(`Command collision: ${key}; add a reasoned command-overrides.ts entry`);
-      if (["login", "logout", "whoami", "org", "api"].includes(words[0]))
+      if (["login", "logout", "whoami", "org", "api", "skill"].includes(words[0]))
         throw new Error(`Reserved command: ${key}`);
       seen.add(key);
       commands.push({ words, op, ...method !== op.method ? { alias: method } : {} });
@@ -20337,7 +21265,12 @@ function convert(value, spec) {
   return result;
 }
 function globalsOf(parsed) {
-  return Object.fromEntries(globalOptions.filter((s) => parsed.flags[s.name]).map((s) => [s.name, convert(parsed.flags[s.name][0], s)]));
+  const flags = Object.fromEntries(globalOptions.filter((s) => parsed.flags[s.name]).map((s) => [s.name, convert(parsed.flags[s.name][0], s)]));
+  if (flags.all && flags.limit !== undefined)
+    throw new UsageError("--all and --limit cannot be used together");
+  if (typeof flags.limit === "number" && flags.limit < 0)
+    throw new UsageError("--limit must be non-negative");
+  return flags;
 }
 async function readData(value, ports) {
   if (value === undefined)
@@ -20391,7 +21324,9 @@ function bindArgs(parsed, op, data) {
       (opts[spec.location] ??= {})[spec.sdkName] = value;
   }
   for (const name of ["limit", "cursor"]) {
-    const field = op.query.find((f) => f.name === name);
+    if (name === "limit" && !op.pagination)
+      continue;
+    const field = op.query.find((f) => name === "limit" ? /^(limit|page_size|pageSize)$/.test(f.name) : f.name === name);
     if (globals[name] !== undefined && field) {
       const key = field.sdkName ?? field.name;
       (opts.query ??= {})[key] ??= convert(String(globals[name]), { name, type: field.type, enum: field.enum });
@@ -20463,7 +21398,7 @@ function help(commands, prefix, command) {
   const matching = commands.filter((c) => prefix.every((w, i) => c.words[i] === w));
   const children = [...new Set(matching.map((c) => c.words[prefix.length]).filter(Boolean))].sort();
   if (!prefix.length)
-    children.unshift("login", "logout", "whoami", "org", "api");
+    children.unshift("login", "logout", "whoami", "org", "api", "skill");
   return [
     `praxis${prefix.length ? " " + prefix.join(" ") : ""} <command> [options]`,
     "",
@@ -20504,6 +21439,82 @@ function environment(vars = process.env) {
 import { chmodSync, closeSync, existsSync, mkdirSync, openSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
+
+// src/auth/secret-store.ts
+import { spawn } from "node:child_process";
+var runSecretCommand = (file, args, input) => new Promise((resolve) => {
+  const child = spawn(file, [...args], { stdio: ["pipe", "pipe", "pipe"], timeout: 1e4 });
+  const chunks = [];
+  child.stdout.on("data", (chunk) => chunks.push(Buffer.from(chunk)));
+  child.stderr.resume();
+  child.stdin.on("error", () => {});
+  child.once("error", (error) => resolve({ code: null, stdout: "", missing: error.code === "ENOENT" }));
+  child.once("close", (code) => resolve({ code, stdout: Buffer.concat(chunks).toString("utf8") }));
+  child.stdin.end(input);
+});
+var unavailable = () => new Error("System keychain unavailable");
+var unavailableSecretStore = {
+  async get() {
+    throw unavailable();
+  },
+  async set() {
+    throw unavailable();
+  },
+  async delete() {
+    return false;
+  }
+};
+function selectSecretStore(env, injected) {
+  return injected ?? (env.PRAXIS_CREDENTIAL_STORE === "file" ? unavailableSecretStore : undefined);
+}
+function systemSecretStore(options = {}) {
+  const platform = options.platform ?? process.platform;
+  const run = options.run ?? runSecretCommand;
+  const service = options.service ?? "praxis-cli";
+  if (!["darwin", "linux"].includes(platform))
+    return unavailableSecretStore;
+  const validate = (key) => {
+    if (!/^[a-zA-Z0-9_-]+$/.test(service) || !/^[a-zA-Z0-9_-]+$/.test(key))
+      throw unavailable();
+  };
+  return {
+    async get(key) {
+      validate(key);
+      const result = platform === "darwin" ? await run("security", ["find-generic-password", "-s", service, "-a", key, "-w"]) : await run("secret-tool", ["lookup", "service", service, "account", key]);
+      if (result.code === 0)
+        return result.stdout.replace(/\r?\n$/, "");
+      if (result.code === (platform === "darwin" ? 44 : 1))
+        return null;
+      throw unavailable();
+    },
+    async set(key, value) {
+      validate(key);
+      let result;
+      if (platform === "darwin") {
+        const input = `add-generic-password -U -s ${service} -a ${key} -X ${Buffer.from(value, "utf8").toString("hex")}
+`;
+        if (Buffer.byteLength(input) >= 4096)
+          throw unavailable();
+        result = await run("security", ["-i"], input);
+      } else {
+        result = await run("secret-tool", ["store", `--label=${service}`, "service", service, "account", key], value);
+      }
+      if (result.code !== 0)
+        throw unavailable();
+    },
+    async delete(key) {
+      validate(key);
+      const result = platform === "darwin" ? await run("security", ["delete-generic-password", "-s", service, "-a", key]) : await run("secret-tool", ["clear", "service", service, "account", key]);
+      if (result.code === 0)
+        return true;
+      if (result.missing || result.code === (platform === "darwin" ? 44 : 1))
+        return false;
+      throw unavailable();
+    }
+  };
+}
+
+// src/auth/token-store.ts
 var CLIENT_ID = "praxis-cli";
 var SCOPE = "openid profile email offline_access";
 function tokenPath(env, home = homedir()) {
@@ -20531,6 +21542,59 @@ function deleteTokens(path) {
   rmSync(path);
   return true;
 }
+function createTokenStore(env, path = tokenPath(env), secret = systemSecretStore()) {
+  let location;
+  const session = {
+    location: () => location,
+    async load() {
+      const file = loadTokens(path);
+      if (file) {
+        await session.save(file);
+        return file;
+      }
+      try {
+        const raw = await secret.get(env);
+        if (!raw)
+          return null;
+        const value = JSON.parse(raw);
+        if (typeof value.access_token !== "string" || typeof value.expires_at !== "number")
+          return null;
+        location = "keychain";
+        return value;
+      } catch {
+        return null;
+      }
+    },
+    async save(tokens) {
+      try {
+        await secret.set(env, JSON.stringify(tokens));
+      } catch {
+        saveTokens(path, tokens);
+        return location = `file ${path}`;
+      }
+      deleteTokens(path);
+      return location = "keychain";
+    },
+    async delete() {
+      let removed = false;
+      try {
+        removed = await secret.delete(env);
+      } finally {
+        removed = deleteTokens(path) || removed;
+        location = undefined;
+      }
+      return removed;
+    }
+  };
+  const transaction = (run) => withLock(`${path}.lock`, () => run(session));
+  return {
+    location: session.location,
+    transaction,
+    load: () => transaction((s) => s.load()),
+    save: (tokens) => transaction((s) => s.save(tokens)),
+    delete: () => transaction((s) => s.delete())
+  };
+}
 function toStored(tokens, now, previous) {
   const refresh = tokens.refresh_token ?? previous?.refresh_token;
   return { ...previous?.organization_id ? { organization_id: previous.organization_id } : {}, access_token: tokens.access_token, ...refresh ? { refresh_token: refresh } : {}, expires_at: now + (tokens.expires_in ?? 900) * 1000 };
@@ -20553,13 +21617,9 @@ async function currentAccessToken(options) {
   const now = options.now ?? Date.now;
   const path = options.path ?? tokenPath(options.env);
   const fresh = (t) => t !== null && t.expires_at - REFRESH_SKEW_MS > now();
-  const stored = loadTokens(path);
-  if (!stored)
-    return null;
-  if (fresh(stored))
-    return stored.access_token;
-  return withLock(`${path}.lock`, async () => {
-    const current = loadTokens(path);
+  const store = options.store ?? createTokenStore(options.env, path, options.secretStore);
+  return store.transaction(async (session) => {
+    const current = await session.load();
     if (!current)
       return null;
     if (fresh(current))
@@ -20567,7 +21627,7 @@ async function currentAccessToken(options) {
     const refreshed = await refreshTokens(current, options.accountUrl, options.fetch, now());
     if (!refreshed)
       return null;
-    saveTokens(path, refreshed);
+    await session.save(refreshed);
     return refreshed.access_token;
   });
 }
@@ -20629,6 +21689,7 @@ function jwtFetch(fetchImpl, token) {
 }
 function credentials(config, vars, ports) {
   const path = ports.path ?? tokenPath(config.env);
+  const store = ports.store ?? createTokenStore(config.env, path, ports.secretStore);
   const apiKey = vars.PRAXIS_API_KEY;
   const remember = ports.remember ?? (() => {});
   if (apiKey)
@@ -20641,13 +21702,13 @@ function credentials(config, vars, ports) {
       throw new UsageError("The API Key determines the organization; listing or switching login organizations is unavailable.", "Unset PRAXIS_API_KEY and run `praxis login`, then retry the org command.");
   };
   async function exchange(organizationId) {
-    const stored = loadTokens(path);
+    const stored = await store.load();
     if (stored) {
       remember(stored.access_token);
       if (stored.refresh_token)
         remember(stored.refresh_token);
     }
-    const opaque = await currentAccessToken({ env: config.env, accountUrl: config.accountUrl, path, now: ports.now, fetch: (url, init) => ports.fetch(url, { ...init, signal: AbortSignal.timeout(1e4), redirect: "error" }) });
+    const opaque = await currentAccessToken({ env: config.env, accountUrl: config.accountUrl, path, store, now: ports.now, fetch: (url, init) => ports.fetch(url, { ...init, signal: AbortSignal.timeout(1e4), redirect: "error" }) });
     if (!opaque)
       throw new PraxisError({ code: "NOT_LOGGED_IN", message: "Not logged in or login has expired." });
     remember(opaque);
@@ -20655,7 +21716,7 @@ function credentials(config, vars, ports) {
     if (!result.access_token || !Number.isFinite(result.claims?.exp) || result.claims.exp * 1000 <= ports.now())
       throw new PraxisError({ code: "INVALID_RESPONSE", message: "Invalid OAuth exchange response" });
     remember(result.access_token);
-    return { source: "login", token: result.access_token, expiresAt: result.claims.exp * 1000, organizationId: result.claims.org ?? organizationId };
+    return { source: "login", storedIn: store.location(), token: result.access_token, expiresAt: result.claims.exp * 1000, organizationId: result.claims.org ?? organizationId };
   }
   async function get(org) {
     if (apiKey) {
@@ -20663,7 +21724,7 @@ function credentials(config, vars, ports) {
         throw new UsageError("--org cannot override an API Key organization", "Remove --org or unset PRAXIS_API_KEY and run `praxis login`.");
       return { source: "api-key", token: apiKey };
     }
-    const stored = loadTokens(path);
+    const stored = await store.load();
     const selected = org ?? stored?.organization_id;
     const opaqueFresh = stored !== null && stored.expires_at - 30000 > ports.now();
     if (opaqueFresh && cached && cachedOrg === selected && cached.expiresAt - 30000 > ports.now())
@@ -20695,11 +21756,11 @@ function credentials(config, vars, ports) {
     async switchOrganization(organizationId) {
       requireLogin();
       const credential = await exchange(organizationId);
-      await withLock(`${path}.lock`, async () => {
-        const stored = loadTokens(path);
+      await store.transaction(async (session) => {
+        const stored = await session.load();
         if (!stored)
           throw new PraxisError({ code: "NOT_LOGGED_IN", message: "Logged out." });
-        saveTokens(path, { ...stored, organization_id: organizationId });
+        await session.save({ ...stored, organization_id: organizationId });
       });
       cached = credential;
       cachedOrg = organizationId;
@@ -20708,6 +21769,97 @@ function credentials(config, vars, ports) {
   };
 }
 
+// src/commands/skill.ts
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { join as join2 } from "node:path";
+function commandSummary(command) {
+  if (command.op.summary?.trim())
+    return command.op.summary.replace(/[\r\n]+/g, " ");
+  const description = (command.op.description ?? "").trim().replace(/!?\[([^\]]*)\]\([^)]*\)/g, "$1").replace(/\[([^\]]+)\]\[[^\]]*\]/g, "$1").replace(/<[^>]*>/g, "").replace(/^\s*(?:#{1,6}\s+|>\s*|[-+*]\s+|\d+\.\s+)/gm, "").replace(/(\*\*|__|~~)(.*?)\1/g, "$2").replace(/(?<!\w)([*_])([^\n]+?)\1(?!\w)/g, "$2").replace(/`+/g, "").split(/[.。\r\n]/, 1)[0].trim();
+  if (description) {
+    const chars = [...description];
+    return chars.length > 120 ? chars.slice(0, 119).join("") + "…" : description;
+  }
+  const words = [...command.words];
+  const verb = (words.pop() ?? "use").replace(/-/g, " ");
+  if (verb === "list" && words.length && !words.at(-1).endsWith("s"))
+    words[words.length - 1] += "s";
+  return `${verb[0].toUpperCase()}${verb.slice(1)} ${words.join(" ")}`.trim();
+}
+function skillDocument(commands) {
+  const lines = [
+    "---",
+    "name: praxis-cli",
+    "description: Use the Praxis CLI to discover and call Deepraxis API operations, manage login, and inspect resources from an AI agent.",
+    "---",
+    "",
+    "# Praxis CLI",
+    "",
+    "## General rules",
+    "",
+    "- Select the environment only with `PRAXIS_ENV`; there is no `--env` option. The dev package defaults to develop.",
+    "- Authenticate with `PRAXIS_API_KEY` or `praxis login`. API keys determine the organization; login sessions can use `--org <organization_id>`.",
+    "- AI mode is enabled automatically in supported agent environments. Use `--format agent` to select it explicitly.",
+    "- Use `--json` for the complete JSON response without presentation truncation. Successful JSON output goes to stdout; errors go to stderr.",
+    "- Supply bodies with `--data JSON`, `--data @file.json`, or `--data -` for stdin. Scalar field options override matching JSON fields. Structured fields require `--data`.",
+    "- Deletion requires `--yes` in AI mode. Confirm the intended resource before using it.",
+    "- Use `--limit N` to limit a server page for SDK-paginated commands. Other lists apply it only to displayed rows; `--param-limit` still sends the API parameter when available. `--all` follows supported pagination and cannot be combined with `--limit`.",
+    "- Error JSON has an `error` object: `code` identifies the failure, `message` describes it, `hint` suggests recovery, `env` identifies the environment, `command` identifies the command, `status` is the HTTP status, and `request_id` correlates diagnostics. Unavailable fields are null. Exit codes: 0 success, 1 runtime/API error, 2 usage error.",
+    "- Append `--help` to a command for its optional parameters. Required scalar body options below can also be supplied as fields in `--data`.",
+    "",
+    "## Account and CLI",
+    "",
+    "praxis login — Sign in with a browser device code.",
+    "praxis logout — Remove the saved login from the keychain and fallback file.",
+    "praxis whoami — Show the signed-in identity and credential storage location.",
+    "praxis org list — List organizations available to the login.",
+    "praxis org switch <organization_id> — Switch the login organization.",
+    "praxis api <METHOD> <path> — Call an API path directly. (--data for a request body)",
+    "praxis skill — Print this skill; use --install <dir> to write <dir>/praxis-cli/SKILL.md."
+  ];
+  let domain;
+  for (const command of commands) {
+    if (command.words[0] !== domain) {
+      domain = command.words[0];
+      lines.push("", `## ${domain}`, "");
+    }
+    const target = targetParam(command.op);
+    const options = operationOptions(command.op);
+    const required = options.filter((option) => option.required).map((option) => `--${option.name} <${option.type}>`);
+    const structured = command.op.body?.fields.filter((field) => field.required && !options.some((option) => option.location === "body" && option.field === field)) ?? [];
+    if (structured.length)
+      required.push(`--data <JSON with ${structured.map((field) => field.sdkName ?? field.name).join(", ")}>`);
+    else if (command.op.body?.required && !options.some((option) => option.location === "body" && option.required))
+      required.push("--data <JSON>");
+    lines.push(`praxis ${command.words.join(" ")}${target ? ` <${target.sdkName}>` : ""} — ${commandSummary(command)}${required.length ? ` (${required.join(" ")})` : ""}`);
+  }
+  return lines.join(`
+`) + `
+`;
+}
+async function installSkill(dir, document) {
+  const path = join2(dir, "praxis-cli", "SKILL.md");
+  let overwritten = false;
+  try {
+    await readFile(path);
+    overwritten = true;
+  } catch (error) {
+    if (error.code !== "ENOENT")
+      throw error;
+  }
+  await mkdir(join2(dir, "praxis-cli"), { recursive: true });
+  await writeFile(path, document, "utf8");
+  return { path, overwritten };
+}
+
+// src/output/limit.ts
+function clientList(items, op, limit, mode) {
+  if (mode !== "json" && !op.pagination && limit !== undefined && items.length > limit) {
+    return { items: items.slice(0, limit), total: items.length };
+  }
+  return { items };
+}
+
 // src/auth/device-flow.ts
 var MIN_INTERVAL_MS = 1000;
 var SLOW_DOWN_STEP_MS = 5000;
@@ -20784,7 +21936,9 @@ Enter code: ${code.user_code}` });
   ports.remember(flow.tokens.access_token);
   if (flow.tokens.refresh_token)
     ports.remember(flow.tokens.refresh_token);
-  saveTokens(path, toStored(flow.tokens, ports.now()));
+  const location = await (ports.store ?? createTokenStore(config.env, path)).save(toStored(flow.tokens, ports.now()));
+  if (location !== "keychain")
+    ports.emit({ kind: "message", channel: "stderr", text: "stored in a file (no system keychain available)" });
   ports.emit({ kind: "message", text: `Logged in (${config.env}).` });
 }
 async function whoami(auth, env, org) {
@@ -20795,6 +21949,7 @@ async function whoami(auth, env, org) {
     organization: me.active_organization_id ?? credential.organizationId ?? null,
     env,
     source: credential.source,
+    ...credential.storedIn ? { "stored in": credential.storedIn } : {},
     expires_at: credential.expiresAt ? new Date(credential.expiresAt).toISOString() : null,
     ...credential.source === "api-key" ? { note: "The API key determines the organization." } : {}
   };
@@ -21130,7 +22285,7 @@ function renderHuman(result, ctx) {
       return {
         stdout: result.items.length ? table(result.items, ctx, out) : out.dim(`No ${plain(resource)}${/(s|x|ch|sh)$/.test(resource) ? "es" : "s"}.`) + `
 `,
-        stderr: err.dim(`${count(result.items.length, "item")}${result.nextCursor ? ` · next: ${ctx.nextCommand ?? "praxis --help"}` : ""}`) + `
+        stderr: err.dim(`${result.total !== undefined ? `${result.items.length} of ${result.total} items` : count(result.items.length, "item")}${result.nextCursor ? ` · next: ${ctx.nextCommand ?? "praxis --help"}` : ""}`) + `
 `
       };
     case "object": {
@@ -21202,7 +22357,7 @@ ${usage ? `usage: ${JSON.stringify(usage)}
     case "list": {
       const columns = columnsFor(result.items);
       const lines = columns.length ? ["|" + columns.map(cell).join("|") + "|", "|" + columns.map(() => "---").join("|") + "|", ...result.items.map((item) => "|" + columns.map((key) => cell(timestamp(key, record(item)[key]) ?? scalar(record(item)[key]))).join("|") + "|")] : [];
-      lines.push(`${result.items.length} rows; ${result.nextCursor ? `more: \`${ctx.nextCommand ?? "praxis --help"}\`` : "end"}`);
+      lines.push(result.total !== undefined ? `${result.items.length} of ${result.total} rows; more: \`${ctx.moreCommand ?? "praxis --help"}\`` : `${result.items.length} rows; ${result.nextCursor ? `more: \`${ctx.nextCommand ?? "praxis --help"}\`` : "end"}`);
       return { stdout: lines.join(`
 `) + `
 ` };
@@ -21230,7 +22385,7 @@ function render(result, ctx) {
   else if (result.kind === "stream-event" && result.done)
     output = {};
   else {
-    const data = result.kind === "object" ? result.data : result.kind === "stream-event" ? result.event : { data: result.items, ...result.nextCursor !== undefined ? { next_cursor: result.nextCursor } : {} };
+    const data = result.kind === "object" ? result.data : result.kind === "stream-event" ? result.event : result.raw ?? { data: result.items, ...result.nextCursor !== undefined ? { next_cursor: result.nextCursor } : {} };
     output = { stdout: JSON.stringify(data ?? null) + `
 ` };
   }
@@ -21251,6 +22406,18 @@ function quote(value) {
 function commandLine(words) {
   return ["praxis", ...words.map(quote)].join(" ");
 }
+function unlimitedCommand(words, parsed) {
+  const args = [...words];
+  for (const [key, values] of Object.entries(parsed.flags)) {
+    if (key === "limit")
+      continue;
+    for (const value of values)
+      args.push(`--${key}=${value}`);
+  }
+  if (parsed.positional.length)
+    args.push("--", ...parsed.positional);
+  return commandLine(args);
+}
 function nextPageCommand(command, parsed, cursor) {
   const query = operationOptions(command.op).find((s) => s.location === "query" && /^(cursor|nextToken|nextCursor|pageToken|page_token|after)$/.test(s.field?.name ?? ""));
   const flag = query?.name ?? "cursor";
@@ -21398,9 +22565,9 @@ function startProgress(ctx, write = (text) => writeOutput({ stderr: text })) {
 }
 
 // src/main.ts
-var version = "0.1.0-dev.e57ae6a";
+var version = "0.1.0-dev.ea77ce8";
 var commands = commandTree(operations);
-var manual = [["login"], ["logout"], ["whoami"], ["org", "list"], ["org", "switch"], ["api"]];
+var manual = [["login"], ["logout"], ["whoami"], ["org", "list"], ["org", "switch"], ["api"], ["skill"]];
 function route(argv) {
   const words = [], args = [];
   for (let i = 0;i < argv.length; i++) {
@@ -21430,7 +22597,7 @@ var defaults = {
   stdoutIsTTY: Boolean(process.stdout.isTTY),
   stderrIsTTY: Boolean(process.stderr.isTTY),
   columns: process.stdout.columns ?? 100,
-  readFile: (path) => readFile(path, "utf8"),
+  readFile: (path) => readFile2(path, "utf8"),
   async readStdin() {
     const chunks = [];
     for await (const chunk of process.stdin)
@@ -21452,7 +22619,7 @@ var defaults = {
         return;
       const cmd = process.platform === "darwin" ? ["open", url] : process.platform === "win32" ? ["rundll32", "url.dll,FileProtocolHandler", url] : ["xdg-open", url];
       await new Promise((resolve, reject) => {
-        const child = spawn(cmd[0], cmd.slice(1), { stdio: "ignore" });
+        const child = spawn2(cmd[0], cmd.slice(1), { stdio: "ignore" });
         child.once("error", reject);
         child.once("close", () => resolve());
       });
@@ -21489,7 +22656,7 @@ async function main(argv, injected = {}) {
     const selected = route(argv);
     ctx.command = commandLine(selected.words);
     ctx.resource = selected.words.at(-2) ?? selected.words[0];
-    const specs = [...globalOptions, ...selected.command ? [...operationOptions(selected.command.op), ...selected.command.op.body ? [dataOption] : []] : selected.words[0] === "api" ? [dataOption] : []];
+    const specs = [...globalOptions, ...selected.command ? [...operationOptions(selected.command.op), ...selected.command.op.body ? [dataOption] : []] : selected.words[0] === "api" ? [dataOption] : selected.words[0] === "skill" ? [{ name: "install", type: "string" }] : []];
     const outputFlags = globalsOf(parseArgs(outputModeArgs(selected.args, specs), globalOptions));
     ctx.json = Boolean(outputFlags.json);
     Object.assign(ctx, decideOutputMode({ format: outputFlags.format, json: ctx.json, stdoutIsTTY: ports.stdoutIsTTY, env: ports.env }));
@@ -21514,6 +22681,11 @@ Examples:
   praxis org list` : help(commands, selected.words) });
       return 0;
     }
+    if (flags.help && selected.words[0] === "skill") {
+      emit({ kind: "message", channel: "stdout", text: `praxis skill [--install <dir>]
+Print the AI skill or write <dir>/praxis-cli/SKILL.md.` });
+      return 0;
+    }
     if (flags.help) {
       emit({ kind: "message", channel: "stdout", text: selected.command ? help(commands, selected.words, selected.command) : `praxis ${selected.words.join(" ")}${selected.words[0] === "api" ? " <METHOD> <path> [--data JSON|@file|-]" : selected.words[1] === "switch" ? " <organization_id>" : ""}
 ${globalOptions.map((s) => "--" + s.name).join(" ")}
@@ -21522,7 +22694,22 @@ Examples:
   praxis ${selected.words.join(" ")}${selected.words[0] === "api" ? " GET /model/v1/models" : selected.words[1] === "switch" ? " <organization_id>" : ""}` });
       return 0;
     }
+    if (selected.words[0] === "skill") {
+      if (parsed.positional.length)
+        throw new UsageError("skill expects no positional arguments");
+      const document = skillDocument(commands);
+      const dir = parsed.flags.install?.[0];
+      if (typeof dir === "string") {
+        if (!dir.trim())
+          throw new UsageError("--install requires a directory");
+        const result = await installSkill(dir, document);
+        emit({ kind: "message", text: `${result.overwritten ? "Overwrote" : "Installed"} ${result.path}` });
+      } else
+        emit({ kind: "message", channel: "stdout", text: document.trimEnd() });
+      return 0;
+    }
     const path = ports.tokenPath ?? tokenPath(config.env);
+    const store = createTokenStore(config.env, path, selectSecretStore(ports.env, ports.secretStore));
     const wireFetch = async (input, init) => {
       const request = new Request(input, init);
       request.headers.set("User-Agent", `praxis-cli/${version}${ctx.mode === "agent" ? ` agent/${ctx.agentName ?? "unknown"}` : ""}`);
@@ -21532,7 +22719,7 @@ Examples:
       }
       return ports.fetch(request);
     };
-    const auth = credentials(config, ports.env, { fetch: wireFetch, now: ports.now, path, remember: (s) => {
+    const auth = credentials(config, ports.env, { fetch: wireFetch, now: ports.now, path, store, remember: (s) => {
       secrets.push(s);
     } });
     const org = flags.org;
@@ -21558,6 +22745,12 @@ Examples:
         owner = owner[part];
       const result = await owner[op.method](opts);
       const name2 = `${op.resource}.${op.method}`;
+      const list = (items) => {
+        const view = clientList(items, op, flags.limit, ctx.mode);
+        if ("total" in view)
+          ctx.moreCommand = unlimitedCommand(selected.words, parsed);
+        return view;
+      };
       const id = record(result).id ?? record(result).sandboxID ?? ctx.targetId;
       if (typeof id === "string")
         ctx.nextCommands = nextCommands(commands, selected.command, opts, id, org);
@@ -21571,16 +22764,16 @@ Examples:
             items.push(item);
           emit({ kind: "list", items, nextCursor: null, op: name2 });
         } else
-          emit({ kind: "list", items: result.data, nextCursor: result.next_cursor, op: name2 });
+          emit({ kind: "list", ...list(result.data), nextCursor: result.next_cursor, op: name2 });
       } else if (result && Symbol.asyncIterator in Object(result)) {
         for await (const event of result)
           emit({ kind: "stream-event", event, op: name2 });
         if (ctx.mode !== "json" && modelStream(name2))
           emit({ kind: "stream-event", event: null, done: true, op: name2 });
       } else if (result && Array.isArray(result.data))
-        emit({ kind: "list", items: result.data, nextCursor: result.next_cursor ?? result.nextToken, op: name2 });
+        emit({ kind: "list", ...list(result.data), ...ctx.mode === "json" ? { raw: result } : {}, nextCursor: result.next_cursor ?? result.nextToken, op: name2 });
       else if (Array.isArray(result) && ctx.mode !== "json")
-        emit({ kind: "list", items: result, op: name2 });
+        emit({ kind: "list", ...list(result), op: name2 });
       else
         emit({ kind: "object", data: result, op: name2 });
       return 0;
@@ -21595,10 +22788,10 @@ Examples:
       case "login":
         if (flags["no-input"] || quiet)
           throw new UsageError("login requires displaying a device code", "Remove --no-input / --quiet or set PRAXIS_API_KEY for scripts.");
-        await login(config, path, { ...ports, fetch: wireFetch, emit, remember: (s) => secrets.push(s) });
+        await login(config, path, { ...ports, store, fetch: wireFetch, emit, remember: (s) => secrets.push(s) });
         break;
       case "logout":
-        emit({ kind: "message", text: deleteTokens(path) ? "Logged out." : "Not logged in." });
+        emit({ kind: "message", text: await store.delete() ? "Logged out." : "Not logged in." });
         break;
       case "whoami":
         emit({ kind: "object", data: await whoami(auth, config.env, org) });