Chat uploads resolve by uploads/<name> for reads, sandbox mounts, and image references (never listings or writes); an unresolved reference image fails the call instead of rendering without it; copilot session-sandbox calls are priced like Function-block sandboxes and report the raw cost beside the billed one; CLI docs regenerated

Author: Sg312

apps/docs/content/docs/cli/blocks.mdx

@@ -39,6 +39,8 @@ sim blocks list [options]
 | `--category <value>` | No | Restrict to one toolbar category. Accepted values: `blocks`, `tools`, `triggers`. |
 | `--capability <value>` | No | Restrict to blocks that can start a workflow — the `triggers` category, blocks declaring `triggerAllowed`, and blocks with trigger-mode fields. Accepted values: `trigger`. |
 | `--source <value>` | No | Restrict to shipped blocks or to this workspace’s deployed custom blocks. Accepted values: `builtin`, `custom`. |
+| `--include-sunset` | No | Include `legacy` and `deprecated` blocks. Off by default: a sunset block keeps executing where it is already placed, but it is not offered for new authoring. Each returned entry carries `sunset.replacedBy`, the block to build with instead. |
+| `--no-include-sunset` | No | Send --include-sunset as false. |
 | `--sort-by <value>` | No | Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order. Accepted values: `id`, `name`, `category`. |
 | `--sort-order <value>` | No | Sort direction. Accepted values: `asc`, `desc`. |
 | `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `100`. |

apps/docs/content/docs/cli/files.mdx

@@ -299,7 +299,7 @@ sim files read <fileId> [options]
 
 | Argument | Required | Description |
 | --- | --- | --- |
-| `fileId` | Yes | File identifier. |
+| `fileId` | Yes | File identifier, or the file’s VFS path: `files/&lt;folder&gt;/&lt;name&gt;`, or `uploads/&lt;name&gt;` for a Chat upload. |
 
 </CommandTable>
 

apps/docs/content/docs/cli/logs.mdx

@@ -51,6 +51,8 @@ sim logs stats [options]
 | `--folder <value...>` | No | Folder path as shown in the app; the leading / is optional (space-separated, or @path / @- with one value per line; @@value for a literal leading @). |
 | `--trigger <value...>` | No | Comma-separated trigger types to include. An empty entry is rejected. The vocabulary is open, so an unrecognized member selects no runs; the literal `all` disables this filter. (space-separated, or @path / @- with one value per line; @@value for a literal leading @). |
 | `--level <value>` | No | Severity level to include. Accepted values: `info`, `error`. |
+| `--include-handled-errors` | No | Whether runs with a handled block error are counted as `handledErrorRuns`, and whether `level=error` also selects them. Off by default: counting them scans each run’s stored trace. |
+| `--no-include-handled-errors` | No | Send --include-handled-errors as false. |
 | `--start-date <value>` | No | Only include runs started at or after this UTC ISO 8601 timestamp, e.g. `2026-08-06T00:00:00Z`. A date without a time, or a timestamp carrying a UTC offset instead of `Z`, is rejected, as is year `0000`, which names no storable instant. |
 | `--end-date <value>` | No | Only include runs started at or before this UTC ISO 8601 timestamp, e.g. `2026-08-06T00:00:00Z`. A date without a time, or a timestamp carrying a UTC offset instead of `Z`, is rejected, as is year `0000`, which names no storable instant. |
 | `--segment-count <value>` | No | Number of equal time buckets to divide the window into, from 1 to 500. It is the ceiling on how many buckets a series carries: with `includeEmpty=true` exactly this many are returned, otherwise only the buckets holding at least one run. Buckets are never narrower than one minute, so on a short window the series extends past the end of the window rather than being compressed, and the trailing buckets are empty. |
@@ -84,6 +86,8 @@ sim logs list [options]
 | `--include-trace-spans` | No | Include trace spans in JSON or YAML output (implies full detail). |
 | `--include-final-output` | No | Include final output in JSON or YAML output (implies full detail). |
 | `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `100`. |
+| `--include-handled-errors` | No | Whether `level=error` also selects runs that finished at `info` after a block error was recovered by an error path. Off by default: such a run succeeded, so it is an error only to a caller auditing error handling. Every row reports `hasHandledErrors` whether or not this is set. Job runs carry no block trace, so the flag never widens that branch. |
+| `--no-include-handled-errors` | No | Send --include-handled-errors as false. |
 | `--status <value>` | No | Comma-separated execution statuses to include, from `pending` \| `running` \| `paused` \| `redacting` \| `completed` \| `failed` \| `cancelled`. An empty entry is rejected. ANDed with `level`, which reports severity rather than lifecycle. |
 | `--workflow-name <value>` | No | Case-insensitive substring match against the run's workflow name. Runs whose workflow has been deleted match nothing, because the name is no longer joinable. |
 | `--include-job-runs` | No | Whether Chat and Sim-agent job runs join the sequence alongside workflow runs. Job runs report `kind: "job"`, carry no `workflow` summary, and never carry a cost ledger. They are dropped entirely — not partially matched — whenever a filter they cannot answer is set: by workflow, workflow name, folder, model, or status. A filter therefore never means two different things across the union. Accepted only when sorting by `startedAt`: job runs record cost as a document and no comparable status, so they cannot participate in the other orderings. |

apps/docs/content/docs/cli/reference.mdx

@@ -310,6 +310,8 @@ sim blocks list [options]
 | `--category <value>` | No | Restrict to one toolbar category. Accepted values: `blocks`, `tools`, `triggers`. |
 | `--capability <value>` | No | Restrict to blocks that can start a workflow — the `triggers` category, blocks declaring `triggerAllowed`, and blocks with trigger-mode fields. Accepted values: `trigger`. |
 | `--source <value>` | No | Restrict to shipped blocks or to this workspace’s deployed custom blocks. Accepted values: `builtin`, `custom`. |
+| `--include-sunset` | No | Include `legacy` and `deprecated` blocks. Off by default: a sunset block keeps executing where it is already placed, but it is not offered for new authoring. Each returned entry carries `sunset.replacedBy`, the block to build with instead. |
+| `--no-include-sunset` | No | Send --include-sunset as false. |
 | `--sort-by <value>` | No | Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order. Accepted values: `id`, `name`, `category`. |
 | `--sort-order <value>` | No | Sort direction. Accepted values: `asc`, `desc`. |
 | `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `100`. |
@@ -997,7 +999,7 @@ sim files read <fileId> [options]
 
 | Argument | Required | Description |
 | --- | --- | --- |
-| `fileId` | Yes | File identifier. |
+| `fileId` | Yes | File identifier, or the file’s VFS path: `files/&lt;folder&gt;/&lt;name&gt;`, or `uploads/&lt;name&gt;` for a Chat upload. |
 
 </CommandTable>
 
@@ -2441,6 +2443,8 @@ sim logs stats [options]
 | `--folder <value...>` | No | Folder path as shown in the app; the leading / is optional (space-separated, or @path / @- with one value per line; @@value for a literal leading @). |
 | `--trigger <value...>` | No | Comma-separated trigger types to include. An empty entry is rejected. The vocabulary is open, so an unrecognized member selects no runs; the literal `all` disables this filter. (space-separated, or @path / @- with one value per line; @@value for a literal leading @). |
 | `--level <value>` | No | Severity level to include. Accepted values: `info`, `error`. |
+| `--include-handled-errors` | No | Whether runs with a handled block error are counted as `handledErrorRuns`, and whether `level=error` also selects them. Off by default: counting them scans each run’s stored trace. |
+| `--no-include-handled-errors` | No | Send --include-handled-errors as false. |
 | `--start-date <value>` | No | Only include runs started at or after this UTC ISO 8601 timestamp, e.g. `2026-08-06T00:00:00Z`. A date without a time, or a timestamp carrying a UTC offset instead of `Z`, is rejected, as is year `0000`, which names no storable instant. |
 | `--end-date <value>` | No | Only include runs started at or before this UTC ISO 8601 timestamp, e.g. `2026-08-06T00:00:00Z`. A date without a time, or a timestamp carrying a UTC offset instead of `Z`, is rejected, as is year `0000`, which names no storable instant. |
 | `--segment-count <value>` | No | Number of equal time buckets to divide the window into, from 1 to 500. It is the ceiling on how many buckets a series carries: with `includeEmpty=true` exactly this many are returned, otherwise only the buckets holding at least one run. Buckets are never narrower than one minute, so on a short window the series extends past the end of the window rather than being compressed, and the trailing buckets are empty. |
@@ -2476,6 +2480,8 @@ sim logs list [options]
 | `--include-trace-spans` | No | Include trace spans in JSON or YAML output (implies full detail). |
 | `--include-final-output` | No | Include final output in JSON or YAML output (implies full detail). |
 | `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `100`. |
+| `--include-handled-errors` | No | Whether `level=error` also selects runs that finished at `info` after a block error was recovered by an error path. Off by default: such a run succeeded, so it is an error only to a caller auditing error handling. Every row reports `hasHandledErrors` whether or not this is set. Job runs carry no block trace, so the flag never widens that branch. |
+| `--no-include-handled-errors` | No | Send --include-handled-errors as false. |
 | `--status <value>` | No | Comma-separated execution statuses to include, from `pending` \| `running` \| `paused` \| `redacting` \| `completed` \| `failed` \| `cancelled`. An empty entry is rejected. ANDed with `level`, which reports severity rather than lifecycle. |
 | `--workflow-name <value>` | No | Case-insensitive substring match against the run's workflow name. Runs whose workflow has been deleted match nothing, because the name is no longer joinable. |
 | `--include-job-runs` | No | Whether Chat and Sim-agent job runs join the sequence alongside workflow runs. Job runs report `kind: "job"`, carry no `workflow` summary, and never carry a cost ledger. They are dropped entirely — not partially matched — whenever a filter they cannot answer is set: by workflow, workflow name, folder, model, or status. A filter therefore never means two different things across the union. Accepted only when sorting by `startedAt`: job runs record cost as a document and no comparable status, so they cannot participate in the other orderings. |
@@ -4108,7 +4114,7 @@ sim tables delete <tableId> [options]
 
 ### sim tables enrichment get
 
-Get Enrichment Run Detail
+Get Row Group Run
 
 ```bash
 sim tables enrichment get <tableId> <rowId> <groupId>

apps/docs/content/docs/cli/tables.mdx

@@ -1041,7 +1041,7 @@ sim tables delete <tableId> [options]
 
 </CommandTable>
 
-## Get enrichment run detail
+## Get row group run
 
 ```bash
 sim tables enrichment get <tableId> <rowId> <groupId>

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

@@ -728,20 +728,19 @@
       "get": {
         "operationId": "readFileText",
         "summary": "Read File Text",
-        "description": "Return a file's text content, parsed out of the stored bytes. This reads the file; it writes nothing — `POST /api/v2/files/{fileId}/unzip` is the endpoint that unzips an archive into the workspace. Answers `400` for a type no parser supports, naming the raw-bytes download as the escape hatch, and `413` for a file above the extraction ceiling. A generated document is extracted from its compiled artifact rather than its generation source, so one still compiling answers `409` and is worth retrying. **`degraded: true` means text extraction did not fully succeed and the returned text may be incomplete or synthesized from the file's raw bytes. Do not treat it as authoritative content.** The legacy `.doc` and `.ppt` parsers deliberately return best-effort content rather than failing, so this flag — not an error status — is how a partial extraction is reported. `truncated` separately reports that a parser limit stopped extraction early.",
+        "description": "Return a file's text content, parsed out of the stored bytes. `{fileId}` is the file's id or its VFS path (`files/<folder>/<name>`; `uploads/<name>` for a Chat upload, which no listing shows), and the response echoes the canonical `path` that was read. This reads the file; it writes nothing — `POST /api/v2/files/{fileId}/unzip` is the endpoint that unzips an archive into the workspace. Answers `400` for a type no parser supports, naming the raw-bytes download as the escape hatch, and `413` for a file above the extraction ceiling. A generated document is extracted from its compiled artifact rather than its generation source, so one still compiling answers `409` and is worth retrying. **`degraded: true` means text extraction did not fully succeed and the returned text may be incomplete or synthesized from the file's raw bytes. Do not treat it as authoritative content.** The legacy `.doc` and `.ppt` parsers deliberately return best-effort content rather than failing, so this flag — not an error status — is how a partial extraction is reported. `truncated` separately reports that a parser limit stopped extraction early.",
         "tags": ["Files"],
         "parameters": [
           {
             "name": "fileId",
             "in": "path",
             "required": true,
-            "description": "File identifier.",
+            "description": "File identifier, or the file’s VFS path: `files/<folder>/<name>`, or `uploads/<name>` for a Chat upload.",
             "schema": {
               "type": "string",
               "minLength": 1,
-              "maxLength": 128,
-              "pattern": "^[A-Za-z0-9_-]+$",
-              "description": "File identifier."
+              "maxLength": 4096,
+              "description": "File identifier, or the file’s VFS path: `files/<folder>/<name>`, or `uploads/<name>` for a Chat upload."
             }
           },
           {
@@ -3357,6 +3356,10 @@
             "type": "string",
             "description": "File name, including its extension."
           },
+          "path": {
+            "type": "string",
+            "description": "Canonical VFS path of the file that was read: `files/…`, or `uploads/<name>` for a Chat upload."
+          },
           "type": {
             "type": "string",
             "description": "Stored MIME type of the source file."
@@ -3400,6 +3403,7 @@
         "required": [
           "fileId",
           "name",
+          "path",
           "type",
           "text",
           "truncated",

apps/sim/app/api/v2/files/[fileId]/text/route.test.ts

@@ -77,6 +77,7 @@ describe('GET /api/v2/files/[fileId]/text', () => {
       data: {
         fileId: FILE_ID,
         name: 'notes.txt',
+        path: 'files/notes.txt',
         type: 'text/plain',
         text: 'hello there!',
         truncated: false,
@@ -133,11 +134,46 @@ describe('GET /api/v2/files/[fileId]/text', () => {
 
     expect(mocks.readText).toHaveBeenCalledWith(
       expect.objectContaining({
-        input: { fileId: FILE_ID, assertedWorkspaceId: WORKSPACE_ID, maxBytes: 4096 },
+        input: { workspaceId: WORKSPACE_ID, reference: FILE_ID, maxBytes: 4096 },
       })
     )
   })
 
+  /**
+   * A Chat upload is absent from every listing, so the `uploads/<name>` path its
+   * upload notice names is the only handle the model has. The path parameter
+   * therefore carries a VFS reference, not only an id, and the response echoes
+   * the canonical path that was read so the model sees the name it was told.
+   */
+  it('accepts a VFS path as the file reference and echoes the path read', async () => {
+    mocks.readText.mockResolvedValueOnce(
+      result({
+        file: { id: 'wf_upload', name: 'face (2).png', type: 'image/png', vfsNamespace: 'uploads' },
+      })
+    )
+
+    const response = await GET(textRequest(), {
+      params: Promise.resolve({ fileId: 'uploads/face%20(2).png' }),
+    })
+    const body = await response.json()
+
+    expect(response.status).toBe(200)
+    expect(mocks.readText).toHaveBeenCalledWith(
+      expect.objectContaining({
+        input: {
+          workspaceId: WORKSPACE_ID,
+          reference: 'uploads/face%20(2).png',
+          maxBytes: undefined,
+        },
+      })
+    )
+    expect(body.data).toMatchObject({
+      fileId: 'wf_upload',
+      name: 'face (2).png',
+      path: 'uploads/face%20(2).png',
+    })
+  })
+
   it('rejects a query with an undeclared key', async () => {
     const response = await GET(textRequest(`workspaceId=${WORKSPACE_ID}&format=html`), context)
 

apps/sim/app/api/v2/files/[fileId]/text/route.ts

@@ -1,5 +1,6 @@
 import { v2ReadFileTextContract } from '@/lib/api/contracts/v2/files'
 import { defineV2JsonRoute, v2ApiKeyAuth, v2RateLimits } from '@/lib/api/server/routes'
+import { workspaceFileVfsPath } from '@/lib/uploads/contexts/workspace/workspace-file-manager'
 import { v2FileErrorPolicies } from '@/lib/workspace-files/api'
 import { fileOperations } from '@/lib/workspace-files/application/operations'
 import { readWorkspaceFileText } from '@/lib/workspace-files/application/read-workspace-file-text'
@@ -9,6 +10,10 @@ export const dynamic = 'force-dynamic'
 /**
  * GET /api/v2/files/[fileId]/text — extract a file's text.
  *
+ * `[fileId]` is a file id or the file's VFS path, so a Chat upload — absent from
+ * every listing — is readable by the `uploads/<name>` path its upload notice
+ * names. The response echoes the canonical path that was read.
+ *
  * Runs on the existing `files.read_content` operation: extracting text reads
  * exactly the bytes that operation already authorizes.
  *
@@ -28,15 +33,16 @@ export const GET = defineV2JsonRoute({
   rateLimit: v2RateLimits.publicApi,
   errorPolicy: v2FileErrorPolicies.concealResourceAuthorization,
   mapInput: ({ params, query }) => ({
-    fileId: params.fileId,
-    assertedWorkspaceId: query.workspaceId,
+    workspaceId: query.workspaceId,
+    reference: params.fileId,
     maxBytes: query.maxBytes,
   }),
   useCase: readWorkspaceFileText,
   present: ({ file, text, truncated, degraded, degradedReason, byteCount }) => ({
     data: {
       fileId: file.id,
       name: file.name,
+      path: workspaceFileVfsPath(file),
       type: file.type,
       text,
       truncated,