fix(cli): close follow-up gaps (#7137)

* chore: run the orphaned migration-safety test, and stop publishing real-looking ids

One of the eight script tests was reachable from no entrypoint, so it had
never run in CI — it passes, it was simply never invoked. This is the second
time that hand-maintained list has drifted from the files beside it; the
audit runner's own header records the first. The guard against a third is a
`check:*` script rather than a test, because the runner derives its list
from that namespace and so picks the guard up by name — a test would have
had to be hand-added to the very list it guards.

A published spec sat outside the generator's manifest and so outside its
drift check, and carried six example ids with the texture of real generated
ones rather than the pandigital placeholders the rest of the repo uses. The
new check globs the directory instead of reading the manifest, since the
manifest is what omitted the file. The one pre-existing borderline id is
allowlisted with a reason: loosening the threshold to admit it would have
hidden one of the six.

* fix(cli): close the gaps black-box testing the shipped CLI found

`sim profiles <anything>` still exited 0, so a probe reading the exit code
to ask whether a command exists was told yes — the one group the earlier
guard missed. The exemption was written for commands that are both a group
and a leaf, but only `files restore` takes an operand; `profiles` takes
none. Registering its listing as a default subcommand puts it back among
the pure dispatchers the existing guard already covers, so the guard itself
did not need widening.

Three commands refuse a workspace API key and said nothing, while their
menu siblings said so — reading as though they accept one. They are
hand-written, so they never reached the code that appends the note. That
note now comes from a helper taking the operation, so a command names the
operation it invokes and the two cannot disagree, and a test fails if a
hand-written command ever calls a restricted operation without it.

A blank numeric value in a request body still became a real zero, the same
coercion already fixed for query strings: the guard keyed off the slot when
the distinction is the field's declared type. Twenty-one fields across
fifteen operations were affected. An empty body string still clears a
description.

Blank values for the root endpoint, workspace and profile flags fell back
to what was configured instead of being refused, and a whitespace workspace
was accepted verbatim. A hand-written profile name carrying padding listed
as reachable but resolved to defaults rather than erroring. Two schema
descriptions named request fields that no flag spells, and a rejected value
was echoed unredacted by four messages while their siblings redacted it.

A write now re-emits a section header it was not asked to touch byte for
byte. The blank-line normalisation around it is left alone: making the
writer position-faithful is a change to its model, not a fix.

* fix(scripts): match example uuids case-insensitively in the spec audit

The pattern only recognised lowercase hex, so an uppercase id in a
published spec was never examined and the audit reported success without
having looked at it.

Matching case-insensitively is not enough on its own: hex is
case-insensitive, so a mixed-case id counts `A` and `a` as two digits and
reports twenty distinct ones rather than sixteen. That inflated count
clears the threshold the texture test uses to recognise a hand-authored
placeholder, so a real id could have passed for one. The allowlist is an
exact-string lookup and would likewise have missed an uppercase spelling of
an entry. Both checks and the lookup now take a normalised id, while the
finding still reports the spelling as it appears in the file.

* fix(cli): stop a refusal being swallowed, and gate example ids by name

A blank root flag was refused everywhere except `profiles`, where the catch
that lets a broken profile still list absorbed it and the command exited 0
after printing the table. The refusal now carries its own error class, which
is what the listing rethrows on — the two are distinguished by type rather
than by matching message text, and a genuinely broken profile still lists.

The unknown-profile message redacted the name the caller typed but not the
suggestion or the list of configured names beside it, which come from the
same file and are equally attacker-influenced once it has been hand-edited.
Those are redacted now, as is every other message in these two files that
quotes a name read out of the config, and the profile listing flattens the
names it renders the way it already flattened the error column.

The example-id audit judged a uuid by its digit texture, on the premise that
a real one essentially never looks hand-authored. Measured against ten
million generated ids, 0.81% of them do — one in 124, where this change
alone replaced six. Requiring each digit exactly twice takes that to zero
but rejects all fourteen placeholders now in the specs, so it is no cheaper
than the alternative. The audit now holds the eighteen ids the specs
actually use, which is one file rather than the twenty-seven a reserved
format would touch, and a new id fails until someone lists it — which is the
review the check exists to force.

* fix(scripts): match the uuid sentinels exactly rather than by shape

Accepting any id built from at most two distinct hex digits let something
through that was never on the approved list. A generated id essentially
never has that shape, so the practical risk was small — but this check had
just stopped being a shape test and become a list, and a structural
exception is the one thing that undoes that. The two ids it exists for are
the nil and max sentinels, and both are matched by value now.

apps/docs/content/docs/en/cli/credentials.mdx

@@ -123,6 +123,8 @@ Update Credential (personal API key required)
 sim credentials create <providerId> [options]
 ```
 
+Create a service-account credential using its discovered provider schema (personal API key required)
+
 **Arguments**
 
 <CommandTable>
@@ -152,6 +154,8 @@ sim credentials create <providerId> [options]
 sim credentials connect <providerId> [options]
 ```
 
+Create a short-lived link for connecting an OAuth provider (personal API key required)
+
 **Arguments**
 
 <CommandTable>
@@ -178,6 +182,8 @@ sim credentials connect <providerId> [options]
 sim credentials reconnect <credentialId>
 ```
 
+Create a short-lived link for reconnecting an OAuth credential (personal API key required)
+
 **Arguments**
 
 <CommandTable>

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

@@ -85,10 +85,10 @@ sim logs list [options]
 | `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `100`. |
 | `--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 (`workflowIds`, `workflowName`, `folderPaths`, `model`, or `status`), so a filter never means two different things across the union. Accepted only under `sortBy=startedAt`: job runs record cost as a document and no comparable status, so they cannot participate in the other orderings. |
+| `--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. |
 | `--no-include-job-runs` | No | Send --include-job-runs as false. |
 | `--run-id <value>` | No | Exact run identifier to match. |
-| `--sort-by <value>` | No | Field used to sort the result. `durationMs` and `cost` are null until a run settles; those runs order as though the value were below every recorded one, so they trail an ascending page and lead a descending one. Only `startedAt` can order Chat and Sim-agent job runs, so any other value is rejected together with `includeJobRuns=true`. Accepted values: `startedAt`, `durationMs`, `cost`, `status`. |
+| `--sort-by <value>` | No | Field used to sort the result. `durationMs` and `cost` are null until a run settles; those runs order as though the value were below every recorded one, so they trail an ascending page and lead a descending one. Only `startedAt` can order Chat and Sim-agent job runs, so any other value is rejected when job runs are included. Accepted values: `startedAt`, `durationMs`, `cost`, `status`. |
 | `--sort-order <value>` | No | Sort direction. Accepted values: `asc`, `desc`. |
 | `--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 @). |
 

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

@@ -479,7 +479,7 @@ sim credentials update <credentialId> [options]
 
 ### sim credentials create
 
-Create a service-account credential using its discovered provider schema
+Create a service-account credential using its discovered provider schema (personal API key required)
 
 ```bash
 sim credentials create <providerId> [options]
@@ -510,7 +510,7 @@ sim credentials create <providerId> [options]
 
 ### sim credentials connect
 
-Create a short-lived link for connecting an OAuth provider
+Create a short-lived link for connecting an OAuth provider (personal API key required)
 
 ```bash
 sim credentials connect <providerId> [options]
@@ -538,7 +538,7 @@ sim credentials connect <providerId> [options]
 
 ### sim credentials reconnect
 
-Create a short-lived link for reconnecting an OAuth credential
+Create a short-lived link for reconnecting an OAuth credential (personal API key required)
 
 ```bash
 sim credentials reconnect <credentialId>
@@ -2475,10 +2475,10 @@ sim logs list [options]
 | `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `100`. |
 | `--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 (`workflowIds`, `workflowName`, `folderPaths`, `model`, or `status`), so a filter never means two different things across the union. Accepted only under `sortBy=startedAt`: job runs record cost as a document and no comparable status, so they cannot participate in the other orderings. |
+| `--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. |
 | `--no-include-job-runs` | No | Send --include-job-runs as false. |
 | `--run-id <value>` | No | Exact run identifier to match. |
-| `--sort-by <value>` | No | Field used to sort the result. `durationMs` and `cost` are null until a run settles; those runs order as though the value were below every recorded one, so they trail an ascending page and lead a descending one. Only `startedAt` can order Chat and Sim-agent job runs, so any other value is rejected together with `includeJobRuns=true`. Accepted values: `startedAt`, `durationMs`, `cost`, `status`. |
+| `--sort-by <value>` | No | Field used to sort the result. `durationMs` and `cost` are null until a run settles; those runs order as though the value were below every recorded one, so they trail an ascending page and lead a descending one. Only `startedAt` can order Chat and Sim-agent job runs, so any other value is rejected when job runs are included. Accepted values: `startedAt`, `durationMs`, `cost`, `status`. |
 | `--sort-order <value>` | No | Sort direction. Accepted values: `asc`, `desc`. |
 | `--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 @). |
 
@@ -2743,7 +2743,7 @@ sim secrets list [options]
 
 ### sim secrets set
 
-Create or replace a named secret
+Create or replace a named secret (personal API key required)
 
 ```bash
 sim secrets set <name> [options]
@@ -5410,7 +5410,7 @@ sim workflows list [options]
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--scope <value>` | No | Which lifecycle set to list: `active` (default) for live workflows, `archived` for workflows a `DELETE` archived. `folderPath` resolves against active folders only, so pairing it with `scope=archived` returns an empty page when the containing folder was archived too. Accepted values: `active`, `archived`. |
+| `--scope <value>` | No | Which lifecycle set to list: `active` (default) for live workflows, `archived` for workflows a `DELETE` archived. The folder filter resolves against active folders only, so pairing it with `archived` returns an empty page when the containing folder was archived too. Accepted values: `active`, `archived`. |
 | `--folder <value>` | No | Folder path as shown in the app; the leading / is optional. |
 | `--deployed-only` | No | Return only workflows with an active deployment when true. |
 | `--no-deployed-only` | No | Send --deployed-only as false. |

apps/docs/content/docs/en/cli/secrets.mdx

@@ -66,6 +66,8 @@ List Secrets (personal API key required)
 sim secrets set <name> [options]
 ```
 
+Create or replace a named secret (personal API key required)
+
 **Arguments**
 
 <CommandTable>

apps/docs/content/docs/en/cli/workflows.mdx

@@ -767,7 +767,7 @@ sim workflows list [options]
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--scope <value>` | No | Which lifecycle set to list: `active` (default) for live workflows, `archived` for workflows a `DELETE` archived. `folderPath` resolves against active folders only, so pairing it with `scope=archived` returns an empty page when the containing folder was archived too. Accepted values: `active`, `archived`. |
+| `--scope <value>` | No | Which lifecycle set to list: `active` (default) for live workflows, `archived` for workflows a `DELETE` archived. The folder filter resolves against active folders only, so pairing it with `archived` returns an empty page when the containing folder was archived too. Accepted values: `active`, `archived`. |
 | `--folder <value>` | No | Folder path as shown in the app; the leading / is optional. |
 | `--deployed-only` | No | Return only workflows with an active deployment when true. |
 | `--no-deployed-only` | No | Send --deployed-only as false. |

apps/docs/openapi-core.json

@@ -211,7 +211,7 @@
             "description": "Comma-separated block-output selectors. A bare `blockId` returns that block's full output; a dot-path like `blockId.field` or `blockId.nested.path` returns just that value. Results are returned in the `blockOutputs` map keyed by the selector string.",
             "schema": {
               "type": "string",
-              "example": "c1b90bce-8a82-42a5-b6a5-5762846c2eaf,c1b90bce-8a82-42a5-b6a5-5762846c2eaf.waitDuration"
+              "example": "a6f0c8d2-3e57-4b19-8d4a-1c9e2f6b0a35,a6f0c8d2-3e57-4b19-8d4a-1c9e2f6b0a35.waitDuration"
             }
           }
         ],
@@ -227,8 +227,8 @@
                   "completed": {
                     "summary": "Completed run",
                     "value": {
-                      "executionId": "9254f1c9-5a11-4a12-91e3-8065293f3609",
-                      "workflowId": "81f661e1-d704-4861-b5c1-5bb3cf57e6a7",
+                      "executionId": "e4f8d2b6-9a1c-4e3d-8b7f-5c0a2d9e6f13",
+                      "workflowId": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36",
                       "status": "completed",
                       "trigger": "api",
                       "level": "info",
@@ -247,8 +247,8 @@
                   "paused": {
                     "summary": "Currently paused run",
                     "value": {
-                      "executionId": "772749f6-ee81-414c-a2c3-671549dd62b8",
-                      "workflowId": "81f661e1-d704-4861-b5c1-5bb3cf57e6a7",
+                      "executionId": "d5e1a3c7-8f60-4b29-9c4d-2a6e0f8b3d17",
+                      "workflowId": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36",
                       "status": "paused",
                       "trigger": "manual",
                       "level": "info",
@@ -259,8 +259,8 @@
                         "pausedAt": "2026-05-15T22:25:57.216Z",
                         "resumeAt": "2026-05-16T18:25:57.200Z",
                         "pauseKind": "time",
-                        "blockedOnBlockId": "c1b90bce-8a82-42a5-b6a5-5762846c2eaf",
-                        "pausedExecutionId": "438bf05b-bd3c-4011-b78e-b19c112eeb66",
+                        "blockedOnBlockId": "a6f0c8d2-3e57-4b19-8d4a-1c9e2f6b0a35",
+                        "pausedExecutionId": "9d3b7f10-2c8e-4a56-b0f4-6e1a8c5d2b97",
                         "pausePointCount": 1,
                         "resumedCount": 0
                       },
@@ -275,8 +275,8 @@
                   "failed": {
                     "summary": "Failed run",
                     "value": {
-                      "executionId": "3ccfdeed-a63c-4e86-98e2-8bec723bca52",
-                      "workflowId": "81f661e1-d704-4861-b5c1-5bb3cf57e6a7",
+                      "executionId": "b8c2e60f-1a47-4d35-9e8b-3f0d5a7c2e19",
+                      "workflowId": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36",
                       "status": "failed",
                       "trigger": "api",
                       "level": "error",
@@ -1537,12 +1537,12 @@
           "executionId": {
             "type": "string",
             "description": "The unique identifier of the execution.",
-            "example": "9254f1c9-5a11-4a12-91e3-8065293f3609"
+            "example": "e4f8d2b6-9a1c-4e3d-8b7f-5c0a2d9e6f13"
           },
           "workflowId": {
             "type": "string",
             "description": "The unique identifier of the workflow.",
-            "example": "81f661e1-d704-4861-b5c1-5bb3cf57e6a7"
+            "example": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36"
           },
           "status": {
             "type": "string",
@@ -1610,12 +1610,12 @@
                 "type": "string",
                 "nullable": true,
                 "description": "The block currently blocking resume.",
-                "example": "c1b90bce-8a82-42a5-b6a5-5762846c2eaf"
+                "example": "a6f0c8d2-3e57-4b19-8d4a-1c9e2f6b0a35"
               },
               "pausedExecutionId": {
                 "type": "string",
                 "description": "ID of the paused-execution row, useful for cross-referencing with the human-in-the-loop endpoints.",
-                "example": "438bf05b-bd3c-4011-b78e-b19c112eeb66"
+                "example": "9d3b7f10-2c8e-4a56-b0f4-6e1a8c5d2b97"
               },
               "pausePointCount": {
                 "type": "integer",
@@ -1659,8 +1659,8 @@
             "description": "Per-block outputs keyed by the selector string. Returned only when `?selectedOutputs` is set.",
             "additionalProperties": true,
             "example": {
-              "c1b90bce-8a82-42a5-b6a5-5762846c2eaf.waitDuration": 60000,
-              "c1b90bce-8a82-42a5-b6a5-5762846c2eaf.status": "completed"
+              "a6f0c8d2-3e57-4b19-8d4a-1c9e2f6b0a35.waitDuration": 60000,
+              "a6f0c8d2-3e57-4b19-8d4a-1c9e2f6b0a35.status": "completed"
             }
           }
         }

apps/docs/openapi-v2-logs.json

@@ -244,9 +244,9 @@
             "name": "includeJobRuns",
             "in": "query",
             "required": false,
-            "description": "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 (`workflowIds`, `workflowName`, `folderPaths`, `model`, or `status`), so a filter never means two different things across the union. Accepted only under `sortBy=startedAt`: job runs record cost as a document and no comparable status, so they cannot participate in the other orderings.",
+            "description": "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.",
             "schema": {
-              "description": "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 (`workflowIds`, `workflowName`, `folderPaths`, `model`, or `status`), so a filter never means two different things across the union. Accepted only under `sortBy=startedAt`: job runs record cost as a document and no comparable status, so they cannot participate in the other orderings.",
+              "description": "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.",
               "type": "boolean"
             }
           },
@@ -267,10 +267,10 @@
             "name": "sortBy",
             "in": "query",
             "required": false,
-            "description": "Field used to sort the result. `durationMs` and `cost` are null until a run settles; those runs order as though the value were below every recorded one, so they trail an ascending page and lead a descending one. Only `startedAt` can order Chat and Sim-agent job runs, so any other value is rejected together with `includeJobRuns=true`.",
+            "description": "Field used to sort the result. `durationMs` and `cost` are null until a run settles; those runs order as though the value were below every recorded one, so they trail an ascending page and lead a descending one. Only `startedAt` can order Chat and Sim-agent job runs, so any other value is rejected when job runs are included.",
             "schema": {
               "default": "startedAt",
-              "description": "Field used to sort the result. `durationMs` and `cost` are null until a run settles; those runs order as though the value were below every recorded one, so they trail an ascending page and lead a descending one. Only `startedAt` can order Chat and Sim-agent job runs, so any other value is rejected together with `includeJobRuns=true`.",
+              "description": "Field used to sort the result. `durationMs` and `cost` are null until a run settles; those runs order as though the value were below every recorded one, so they trail an ascending page and lead a descending one. Only `startedAt` can order Chat and Sim-agent job runs, so any other value is rejected when job runs are included.",
               "type": "string",
               "enum": ["startedAt", "durationMs", "cost", "status"]
             }

apps/docs/openapi-v2-workflows.json

@@ -59,10 +59,10 @@
             "name": "scope",
             "in": "query",
             "required": false,
-            "description": "Which lifecycle set to list: `active` (default) for live workflows, `archived` for workflows a `DELETE` archived. `folderPath` resolves against active folders only, so pairing it with `scope=archived` returns an empty page when the containing folder was archived too.",
+            "description": "Which lifecycle set to list: `active` (default) for live workflows, `archived` for workflows a `DELETE` archived. The folder filter resolves against active folders only, so pairing it with `archived` returns an empty page when the containing folder was archived too.",
             "schema": {
               "default": "active",
-              "description": "Which lifecycle set to list: `active` (default) for live workflows, `archived` for workflows a `DELETE` archived. `folderPath` resolves against active folders only, so pairing it with `scope=archived` returns an empty page when the containing folder was archived too.",
+              "description": "Which lifecycle set to list: `active` (default) for live workflows, `archived` for workflows a `DELETE` archived. The folder filter resolves against active folders only, so pairing it with `archived` returns an empty page when the containing folder was archived too.",
               "type": "string",
               "enum": ["active", "archived"]
             }