fix(api): align descriptions across resource families

Author: waleedlatif1

.agents/skills/v2-api-conventions/SKILL.md

@@ -155,6 +155,8 @@ Use the [API description conventions](../../../apps/sim/lib/api/contracts/v2/ope
 
 Keep archive versus permanent-delete behavior, replacement versus partial-update semantics, partial success, retry safety, redaction, and asynchronous completion explicit. Verify these claims against the implementation. Describe observable behavior without exposing storage formats, locking mechanisms, internal identifiers, deployment architecture, or implementation history unless that detail changes how the caller must use the API.
 
+Reuse wording across resource families when behavior matches: “Omitted fields remain unchanged,” “Archive,” and “permanently delete.” Prefer “during the request” or “asynchronously” to “settled inline.” Preserve real semantic differences; do not standardize them away.
+
 Put field-specific rules in the source schema and reuse shared authentication and pagination wording. Shared schema descriptions also feed CLI help, so refer to related operation names rather than HTTP paths. Regenerate OpenAPI, CLI metadata, and CLI docs after changing their source descriptions; never hand-edit generated output.
 
 ## Rule 6 — a transient failure says when to come back

apps/docs/openapi-v2-files-audit.json

@@ -43,7 +43,7 @@
       "get": {
         "operationId": "listFiles",
         "summary": "List Files",
-        "description": "List workspace files with search, sorting, folder filtering, and opaque cursor pagination. Defaults to active files; pass `scope=archived` to page over soft-deleted ones. Workspace folder trees exceeding 10,000 folders return `413`.\n\nOAuth scope: `api:read`.",
+        "description": "List active workspace files with folder filtering, search, sorting, and cursor pagination. Use `scope=archived` to find files available for restoration. Workspace folder trees exceeding 10,000 folders return `413`.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "files.list",
         "x-oauth-scope": "api:read",
         "tags": ["Files"],
@@ -449,7 +449,7 @@
       "delete": {
         "operationId": "abortFileUpload",
         "summary": "Abort File Upload",
-        "description": "Abort an active upload session and release provider-side multipart state.\n\nOAuth scope: `api:write`.",
+        "description": "Abort an incomplete upload session and discard its uploaded data. Completed uploads cannot be aborted.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "files.upload.cancel",
         "x-oauth-scope": "api:write",
         "tags": ["Files"],
@@ -1407,7 +1407,7 @@
       "get": {
         "operationId": "getFile",
         "summary": "Get File Metadata",
-        "description": "Get file metadata together with the nullable current public-share state.\n\nOAuth scope: `api:read`.",
+        "description": "Get file metadata and its public-share configuration. The `share` field is null when the file has never been shared.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "files.read_metadata",
         "x-oauth-scope": "api:read",
         "tags": ["Files"],
@@ -1754,7 +1754,7 @@
       "post": {
         "operationId": "moveFileItems",
         "summary": "Move Files",
-        "description": "Move up to 1,000 files to a canonical folder path or the workspace root.\n\nOAuth scope: `api:write`.",
+        "description": "Move up to 1,000 files to a folder path or the workspace root.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "files.move",
         "x-oauth-scope": "api:write",
         "tags": ["Files"],
@@ -2169,7 +2169,7 @@
       "get": {
         "operationId": "searchFileContent",
         "summary": "Search File Content",
-        "description": "Search indexed text in active workspace files and return matching lines with file IDs and line numbers. `folderPaths` limits both results and the coverage reported by `complete` and `indexStatus`. Because indexing is asynchronous, a missing term is unknown rather than absent when `complete` is false. `truncated` means additional matches exist beyond `maxResults`.\n\nOAuth scope: `api:read`.",
+        "description": "Search indexed text in active workspace files and return matching lines with file IDs and line numbers. `folderPaths` limits both results and reported coverage. Missing matches are inconclusive if `complete` is false or `indexStatus.skippedFiles` or `indexStatus.partialFiles` is nonzero. `truncated` means additional matches exist beyond `maxResults`.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "files.search_content",
         "x-oauth-scope": "api:read",
         "tags": ["Files"],
@@ -2542,7 +2542,7 @@
       "post": {
         "operationId": "createFilesFolder",
         "summary": "Create Folder",
-        "description": "Create a canonical folder path in a workspace.\n\nOAuth scope: `api:write`.",
+        "description": "Create a folder at the supplied workspace path.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "files.folders.create",
         "x-oauth-scope": "api:write",
         "tags": ["Files"],
@@ -2614,7 +2614,7 @@
       "patch": {
         "operationId": "relocateFilesFolder",
         "summary": "Rename or Move Folder",
-        "description": "Rename or move a folder and atomically rewrite descendant canonical paths.\n\nOAuth scope: `api:write`.",
+        "description": "Rename or move a folder and atomically update all descendant paths.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "files.folders.update",
         "x-oauth-scope": "api:write",
         "tags": ["Files"],
@@ -2686,7 +2686,7 @@
       "delete": {
         "operationId": "deleteFilesFolder",
         "summary": "Delete Folder",
-        "description": "Delete a folder, optionally including every nested file and folder.\n\nOAuth scope: `api:write`.",
+        "description": "Archive an empty folder, or set `recursive=true` to archive its files and subfolders. Use Restore Folder to recover the archived contents.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "files.folders.delete",
         "x-oauth-scope": "api:write",
         "tags": ["Files"],
@@ -4204,7 +4204,7 @@
         ],
         "additionalProperties": false,
         "title": "File metadata",
-        "description": "Workspace file metadata enriched with nullable public-share state."
+        "description": "Workspace file metadata and current public-share configuration."
       },
       "V2FileMetadataResponse": {
         "type": "object",

apps/docs/openapi-v2-knowledge.json

@@ -190,7 +190,7 @@
       "post": {
         "operationId": "createKnowledgeBase",
         "summary": "Create Knowledge Base",
-        "description": "Create a knowledge base in a workspace with optional folder placement and chunking configuration. An unknown `folderPath` is a `404`. Workspace folder trees exceeding 10,000 folders return `413`.\n\nOAuth scope: `api:write`.",
+        "description": "Create a knowledge base in a workspace with optional folder placement and chunking configuration. An unknown `folderPath` returns `404`. Workspace folder trees exceeding 10,000 folders return `413`.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "knowledge.create",
         "x-oauth-scope": "api:write",
         "tags": ["Knowledge Bases"],
@@ -343,7 +343,7 @@
       "patch": {
         "operationId": "updateKnowledgeBase",
         "summary": "Update Knowledge Base",
-        "description": "Update a knowledge base name, description, chunking configuration, or folder placement. Workspace folder trees exceeding 10,000 folders return `413`.\n\nOAuth scope: `api:write`.",
+        "description": "Update a knowledge base's name, description, chunking configuration, or folder placement. Workspace folder trees exceeding 10,000 folders return `413`.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "knowledge.update",
         "x-oauth-scope": "api:write",
         "tags": ["Knowledge Bases"],
@@ -506,7 +506,7 @@
       "get": {
         "operationId": "listKnowledgeConnectors",
         "summary": "List Knowledge Connectors",
-        "description": "List external sources connected to a knowledge base with opaque cursor pagination. Stored API keys and encrypted secret material are never returned. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.",
+        "description": "List external sources connected to a knowledge base with cursor pagination. Stored API keys are never returned. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "knowledge.connectors.list",
         "x-oauth-scope": "api:read",
         "tags": ["Knowledge Bases"],
@@ -631,7 +631,7 @@
       "post": {
         "operationId": "createKnowledgeConnector",
         "summary": "Create Knowledge Connector",
-        "description": "Validate and connect an external source, then queue its initial synchronization. The apiKey field is write-only and is never returned. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
+        "description": "Validate and connect an external source, then queue its initial synchronization. The `apiKey` field is never returned. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "knowledge.connectors.create",
         "x-oauth-scope": "api:write",
         "tags": ["Knowledge Bases"],
@@ -718,7 +718,7 @@
       "get": {
         "operationId": "getKnowledgeConnector",
         "summary": "Get Knowledge Connector",
-        "description": "Get one connector and its ten most recent synchronization attempts. Stored API keys and encrypted secret material are never returned. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.",
+        "description": "Get one connector and its ten most recent synchronization attempts. Stored API keys are never returned. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "knowledge.connectors.read",
         "x-oauth-scope": "api:read",
         "tags": ["Knowledge Bases"],
@@ -1391,7 +1391,7 @@
       "get": {
         "operationId": "listKnowledgeTags",
         "summary": "List Tags",
-        "description": "List the knowledge base's tag vocabulary: each tag's display name, the slot it is stored in, and its field type. Filters and document reads use display names; document writes address slots. Returns the complete set in one page; `nextCursor` is always null.\n\nOAuth scope: `api:read`.",
+        "description": "List the knowledge base's tag definitions with display names, write slots, and field types. Filters and document reads use display names; document writes use slots. Returns the complete set in one page; `nextCursor` is always null.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "knowledge.tags.list",
         "x-oauth-scope": "api:read",
         "tags": ["Knowledge Bases"],
@@ -2160,7 +2160,7 @@
       "delete": {
         "operationId": "abortKnowledgeDocumentUpload",
         "summary": "Abort Document Upload",
-        "description": "Abort an incomplete upload and discard provider-side multipart state.\n\nOAuth scope: `api:write`.",
+        "description": "Abort an incomplete upload session and discard its uploaded data. Completed uploads cannot be aborted.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "knowledge.documents.upload.cancel",
         "x-oauth-scope": "api:write",
         "tags": ["Knowledge Bases"],
@@ -2489,7 +2489,7 @@
       "get": {
         "operationId": "getKnowledgeDocument",
         "summary": "Get Document",
-        "description": "Get document detail, processing state, and connector provenance.\n\nOAuth scope: `api:read`.",
+        "description": "Get document metadata, processing status, and source connector details.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "knowledge.documents.read",
         "x-oauth-scope": "api:read",
         "tags": ["Knowledge Bases"],
@@ -2576,7 +2576,7 @@
       "patch": {
         "operationId": "updateKnowledgeDocument",
         "summary": "Update Document",
-        "description": "Rename a document, change search availability, update tag slots, or requeue processing. Omitted fields remain unchanged; indexing state is read-only. Use List Tags to resolve names to slots and Get Document for connector provenance, which this response omits. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
+        "description": "Rename a document, change search availability, update tag slots, or requeue processing. Omitted fields remain unchanged; indexing state is read-only. Use List Tags to resolve names to slots and Get Document for source connector details, which this response omits. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "knowledge.documents.update",
         "x-oauth-scope": "api:write",
         "tags": ["Knowledge Bases"],
@@ -3017,7 +3017,7 @@
       "delete": {
         "operationId": "deleteKnowledgeFolder",
         "summary": "Delete Folder",
-        "description": "Delete a folder, optionally including nested folders and knowledge bases.\n\nOAuth scope: `api:write`.",
+        "description": "Archive an empty folder, or set `recursive=true` to archive its subfolders and knowledge bases. Use Restore Knowledge Base to recover knowledge bases.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "knowledge.folders.delete",
         "x-oauth-scope": "api:write",
         "tags": ["Knowledge Bases"],

apps/docs/openapi-v2-logs.json

@@ -39,7 +39,7 @@
       "get": {
         "operationId": "listLogs",
         "summary": "List Logs",
-        "description": "List logs with filters, selectable detail, sorting, and cursor pagination. `includeJobRuns=true` includes chat and Sim-agent jobs only with `sortBy=startedAt`, because other orderings are unsupported. `files` contains only run-produced files; use the files API for input attachments. Expired runs are hard-deleted. Retention is 30 days from run start on Free, unbounded on Pro and Team, and configured per organization on Enterprise with an optional workspace override. Workspace folder trees exceeding 10,000 folders return `413`.\n\nOAuth scope: `api:read`.",
+        "description": "List logs with filters, selectable detail, sorting, and cursor pagination. `includeJobRuns=true` includes chat and Sim-agent jobs only with `sortBy=startedAt`, because other orderings are unsupported. `files` contains only run-produced files; use the files API for input attachments. Expired runs are permanently deleted. Retention is 30 days from run start on Free, unlimited on Pro and Team, and configured per organization on Enterprise with workspace overrides. Workspace folder trees exceeding 10,000 folders return `413`.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "logs.list",
         "x-oauth-scope": "api:read",
         "tags": ["Logs"],
@@ -356,7 +356,7 @@
       "get": {
         "operationId": "getLog",
         "summary": "Get Log",
-        "description": "Get a run's workflow graph, trace spans, final output, and cost. Trace spans expire separately, so an empty `traceSpans` array does not prove none were recorded. Expired runs are hard-deleted. Retention is 30 days from run start on Free, unbounded on Pro and Team, and configured per organization on Enterprise with an optional workspace override. Workspace folder trees exceeding 10,000 folders return `413`.\n\nOAuth scope: `api:read`.",
+        "description": "Get a run's workflow graph, trace spans, final output, and cost. Trace spans expire separately, so an empty `traceSpans` array does not prove none were recorded. Expired runs are permanently deleted. Retention is 30 days from run start on Free, unlimited on Pro and Team, and configured per organization on Enterprise with workspace overrides. Workspace folder trees exceeding 10,000 folders return `413`.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "logs.read_detail",
         "x-oauth-scope": "api:read",
         "tags": ["Logs"],
@@ -428,7 +428,7 @@
       "get": {
         "operationId": "getLogStats",
         "summary": "Get Log Statistics",
-        "description": "Get run counts, success and error counts, and latency by workspace or workflow. Default bounds span recorded runs, or the last 24 hours when empty. Buckets may extend past the end. Folder filters include descendants; `workflowsTruncated` affects series, not totals. Expired runs are hard-deleted. Retention is 30 days from run start on Free, unbounded on Pro and Team, and configured per organization on Enterprise with an optional workspace override. Workspace folder trees exceeding 10,000 folders return `413`.\n\nOAuth scope: `api:read`.",
+        "description": "Get run counts, success and error counts, and latency by workspace or workflow. Default bounds span recorded runs, or the last 24 hours when empty. Buckets may extend past the end. Folder filters include descendants; `workflowsTruncated` affects series, not totals. Expired runs are permanently deleted. Retention is 30 days from run start on Free, unlimited on Pro and Team, and configured per organization on Enterprise with workspace overrides. Workspace folder trees exceeding 10,000 folders return `413`.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "logs.read_stats",
         "x-oauth-scope": "api:read",
         "tags": ["Logs"],