fix(v2,cli): second audit pass over the v2 API and CLI

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

@@ -15,6 +15,8 @@ Every command below also accepts the [global options](/cli/commands#global-optio
 sim audit-logs get <auditLogId> [options]
 ```
 
+Get Audit Log (personal API key required)
+
 **Arguments**
 
 <CommandTable>
@@ -41,6 +43,8 @@ sim audit-logs get <auditLogId> [options]
 sim audit-logs list [options]
 ```
 
+List Audit Logs (personal API key required)
+
 **Options**
 
 <CommandTable>

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

@@ -24,7 +24,7 @@ https://www.sim.ai/cli/auth?request=…&scope=platform
 Waiting for approval…
 
 ✓ Logged in. Key stored in /Users/you/.sim/credentials
-  Personal key, defaulting to ws_abc123. Override per command with --workspace.
+  Personal key, defaulting to 2f6d0b1c-8a34-4d92-b7e5-31c8a0f45d67. Override per command with --workspace.
 ```
 
 There is no loopback listener, so this works over SSH and inside containers.
@@ -47,7 +47,7 @@ profile's default `workspace`; it does **not** restrict the key to that
 workspace. Target another workspace the key can reach with `--workspace`:
 
 ```bash
-sim workflows list --workspace ws_other
+sim workflows list --workspace 9b4c7e02-1d58-4f36-a0c9-6e2b85df413a
 ```
 
 `sim login --workspace <id>` preselects a workspace in the picker, and
@@ -58,7 +58,7 @@ a workspace profile:
 
 ```bash
 sim workspaces list
-sim profile add acme --workspace ws_acme
+sim profile add acme --workspace 7e2d9c14-6b83-4a55-8f01-c4d3e9a76b28
 sim --profile acme whoami
 ```
 
@@ -108,9 +108,9 @@ config file:
 
 ```bash
 export SIM_API_KEY="sim_…"
-export SIM_WORKSPACE="ws_abc123"
+export SIM_WORKSPACE="2f6d0b1c-8a34-4d92-b7e5-31c8a0f45d67"
 
-sim workflows run wf_7Yb2 --input '{"source":"nightly"}' --output json
+sim workflows run 3a9e21d8-5f47-4c0b-b2ea-91d7c6034ef8 --input '{"source":"nightly"}' --output json
 ```
 
 Create the key in Sim under **Settings → API keys**. Store it as a secret in your
@@ -130,7 +130,7 @@ jobs:
         with:
           node-version: '20'
       - run: npm install -g sim
-      - run: sim workflows run wf_7Yb2 --output json
+      - run: sim workflows run 3a9e21d8-5f47-4c0b-b2ea-91d7c6034ef8 --output json
         env:
           SIM_API_KEY: ${{ secrets.SIM_API_KEY }}
           SIM_WORKSPACE: ${{ vars.SIM_WORKSPACE }}
@@ -151,8 +151,8 @@ sim workflows list --profile prod
 Use workspace profiles when one personal key should target several workspaces:
 
 ```bash
-sim profile add marketing --workspace ws_marketing
-sim profile add support --workspace ws_support
+sim profile add marketing --workspace c3a70e58-9f21-4d6b-b842-05e7f19c6a3d
+sim profile add support --workspace e0d94b17-3c62-45af-9718-b6a2c8035f4e
 
 sim workflows list --profile marketing
 sim workflows list --profile support

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

@@ -31,6 +31,8 @@ Show billing status and current-period credit usage (credits and storage require
 sim billing logs [options]
 ```
 
+List credit usage events (a personal API key reports only your own events; a workspace API key reports every member's)
+
 **Options**
 
 <CommandTable>

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

@@ -28,14 +28,14 @@ sim profiles     # list them; * marks the active one
 Add a profile for another workspace without creating or copying an API key:
 
 ```bash
-sim profile add acme --workspace ws_acme
+sim profile add acme --workspace 7e2d9c14-6b83-4a55-8f01-c4d3e9a76b28
 ```
 
 ## Setting defaults
 
 ```bash
 sim configure --set-endpoint http://localhost:3000 --profile dev
-sim configure --set-workspace ws_local --profile dev
+sim configure --set-workspace 5c81f3a6-0e27-4b94-8d15-a7f60c39b2e8 --profile dev
 sim configure --set-output json
 ```
 
@@ -76,16 +76,16 @@ repo:
 ```ini title="~/.sim/config"
 [default]
 endpoint = https://www.sim.ai
-workspace = ws_abc123
+workspace = 2f6d0b1c-8a34-4d92-b7e5-31c8a0f45d67
 output = table
 
 [profile dev]
 endpoint = http://localhost:3000
-workspace = ws_local
+workspace = 5c81f3a6-0e27-4b94-8d15-a7f60c39b2e8
 
 [profile acme]
 auth_profile = default
-workspace = ws_acme
+workspace = 7e2d9c14-6b83-4a55-8f01-c4d3e9a76b28
 ```
 
 Keys live in `~/.sim/credentials`, written `0600`:
@@ -132,17 +132,17 @@ filesystem at all.
 Workspace-scoped commands need a workspace:
 
 ```bash
-sim tables list --workspace ws_other
-sim configure --set-workspace ws_abc123
-export SIM_WORKSPACE=ws_abc123
+sim tables list --workspace 9b4c7e02-1d58-4f36-a0c9-6e2b85df413a
+sim configure --set-workspace 2f6d0b1c-8a34-4d92-b7e5-31c8a0f45d67
+export SIM_WORKSPACE=2f6d0b1c-8a34-4d92-b7e5-31c8a0f45d67
 ```
 
 For a reusable selection, create a workspace profile backed by the current
 stored login:
 
 ```bash
 sim workspaces list
-sim profile add acme --workspace ws_acme
+sim profile add acme --workspace 7e2d9c14-6b83-4a55-8f01-c4d3e9a76b28
 sim --profile acme tables list
 ```
 

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

@@ -15,6 +15,8 @@ Every command below also accepts the [global options](/cli/commands#global-optio
 sim credentials delete <credentialId> [options]
 ```
 
+Disconnect Credential (personal API key required)
+
 **Arguments**
 
 <CommandTable>
@@ -78,6 +80,8 @@ sim credentials list [options]
 sim credentials update <credentialId> [options]
 ```
 
+Update Credential (personal API key required)
+
 **Arguments**
 
 <CommandTable>

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

@@ -21,7 +21,7 @@ sim files batch-delete [options]
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--file-ids <value...>` | Yes | File identifiers to update. (space-separated, or @path / @- with one value per line). |
+| `--file-ids <value...>` | Yes | File identifiers to update. (space-separated, or @path / @- with one value per line; @@value for a literal leading @). |
 | `-y, --yes` | Yes | Confirm this destructive operation. |
 
 </CommandTable>
@@ -107,7 +107,7 @@ Also available as `sim files folders ls`.
 | `--search <value>` | No | Case-insensitive substring match against the folder name. |
 | `--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: `name`, `createdAt`, `updatedAt`. |
 | `--sort-order <value>` | No | Sort direction. Accepted values: `asc`, `desc`. |
-| `--scope <value>` | No | Which lifecycle set to list: `active` (default) returns live folders only; `archived` returns folders a recursive `DELETE` soft-deleted, which is how a caller finds a path to hand to `POST /api/v2/files/folders/restore`. Authorization is identical for both. Accepted values: `active`, `archived`. |
+| `--scope <value>` | No | Which lifecycle set to list: `active` (default) returns live folders only; `archived` returns folders a recursive delete soft-deleted, which is how a caller finds a path to hand to the folder restore. Authorization is identical for both. Accepted values: `active`, `archived`. |
 
 </CommandTable>
 
@@ -194,7 +194,7 @@ sim files describe <fileId> [options]
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--scope <value>` | No | Which lifecycle set to read from: `active` (default) resolves live files only and returns `404` for a file a `DELETE` soft-deleted; `archived` also resolves soft-deleted files, so metadata stays readable before `POST /files/&#123;fileId&#125;/restore`. Authorization is identical for both. Accepted values: `active`, `archived`. |
+| `--scope <value>` | No | Which lifecycle set to read from: `active` (default) resolves live files only and returns `404` for a file a delete soft-deleted; `archived` also resolves soft-deleted files, so metadata stays readable before the file is restored. Authorization is identical for both. Accepted values: `active`, `archived`. |
 
 </CommandTable>
 
@@ -220,6 +220,8 @@ sim files share get <fileId>
 sim files share set <fileId> [options]
 ```
 
+Enable or disable sharing for a file (personal API key required)
+
 **Arguments**
 
 <CommandTable>
@@ -239,7 +241,7 @@ sim files share set <fileId> [options]
 | `--is-active <true\|false>` | Yes | Whether the share should resolve. Disabling preserves the token and the whole access configuration, so re-enabling restores the share as it was; enabling rewrites the credentials the resulting mode does not use. Accepted values: `true`, `false`. |
 | `--auth-type <value>` | No | How access to the share is gated. The stored mode is kept when omitted. Enabling `public` clears the stored password and empties `allowedEmails`; `password` empties `allowedEmails`; `email` and `sso` clear the stored password. Accepted values: `public`, `password`, `email`, `sso`. |
 | `--password <value>` | No | Password for a password-gated share. Kept when omitted; enabling `password` with neither a supplied nor a stored password is a 400. |
-| `--allowed-emails <value...>` | No | Allowed addresses or `@domain` patterns for email and SSO shares. Kept when omitted; enabling `email` or `sso` with an empty resulting list is a 400. (space-separated, or @path / @- with one value per line). |
+| `--allowed-emails <value...>` | No | Allowed addresses or `@domain` patterns for email and SSO shares. Kept when omitted; enabling `email` or `sso` with an empty resulting list is a 400. (space-separated, or @path / @- with one value per line; @@value for a literal leading @). |
 
 </CommandTable>
 
@@ -258,7 +260,7 @@ sim files list [options]
 | `--folder <value>` | No | Folder path as shown in the app; the leading / is optional. |
 | `--recursive` | No | Whether the folder filter includes files in subfolders. Defaults to true when a search is set, false otherwise, so listing a folder shows that folder while searching one looks through everything in it. Ignored when no folder filter is set, which already spans the workspace. |
 | `--no-recursive` | No | Send --recursive as false. |
-| `--scope <value>` | No | Which lifecycle set to list: `active` (default) for live files, `archived` for files a `DELETE` soft-deleted. `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 files, `archived` for files a delete soft-deleted. `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`. |
 | `--search <value>` | No | Case-insensitive substring match against the file name. |
 | `--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: `name`, `size`, `uploadedAt`, `updatedAt`. |
 | `--sort-order <value>` | No | Sort direction. Accepted values: `asc`, `desc`. |
@@ -280,7 +282,7 @@ Also available as `sim files mv`.
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--file-ids <value...>` | Yes | File identifiers to update. (space-separated, or @path / @- with one value per line). |
+| `--file-ids <value...>` | Yes | File identifiers to update. (space-separated, or @path / @- with one value per line; @@value for a literal leading @). |
 | `--to <value>` | No | Destination folder path; omit for root. |
 
 </CommandTable>

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

@@ -77,17 +77,17 @@ sim workflows list
 ```
 
 ```
-ID      NAME           FOLDER     DEPLOYED  RUNS  LAST RUN
-wf_7Yb2 Refund triage  /Support   yes       412   2026-08-15 14:02:11
-wf_9Kd4 Weekly digest  /Reporting no        18    2026-08-11 09:00:04
+ID                                    NAME           FOLDER     DEPLOYED  RUNS  LAST RUN
+3a9e21d8-5f47-4c0b-b2ea-91d7c6034ef8  Refund triage  /Support   yes       412   2026-08-15 14:02:11
+b8c0d247-9e13-4a86-97f5-2ad4e1638c09  Weekly digest  /Reporting no        18    2026-08-11 09:00:04
 ```
 </Step>
 
 <Step>
 ### Run one
 
 ```bash
-sim workflows run wf_7Yb2 --input '{"ticketId":"T-4821"}'
+sim workflows run 3a9e21d8-5f47-4c0b-b2ea-91d7c6034ef8 --input '{"ticketId":"T-4821"}'
 ```
 
 A workflow must be deployed before it can be run. Deploy from the editor, or
@@ -106,8 +106,8 @@ sim <resource> [sub-resource] <verb> [arguments] [options]
 
 ```bash
 sim workflows list
-sim tables rows query tbl_123 --limit 50
-sim knowledge documents upload kb_123 ./handbook.pdf
+sim tables rows query tbl_9f3c1a05d4b7426e8c2f0917ab35de64 --limit 50
+sim knowledge documents upload 4c1b7f60-2d55-4a3e-9c18-70b6ea2f9d31 ./handbook.pdf
 ```
 
 Resource groups are plural, and each also accepts its singular spelling —
@@ -146,8 +146,10 @@ sim tables rows query --help
 | [`workflow-mcp-servers`](/cli/workflow-mcp-servers) | Publish workflows as MCP tools for outside agents |
 | [`meta`](/cli/meta) | Check what this API supports and which limits apply |
 
-The [command reference](/cli/commands) documents every subcommand, argument, and
-flag, and is generated from the CLI itself.
+The [command overview](/cli/commands) has the global options and the commands
+that take no resource; the [complete reference](/cli/reference) documents every
+subcommand, argument, and flag on one page. Both are generated from the CLI
+itself.
 
 ## Where to go next
 
@@ -156,4 +158,5 @@ flag, and is generated from the CLI itself.
 - [Output formats](/cli/output) — `table`, `json`, `yaml`, and `text`, and when to use each
 - [Scripting](/cli/scripting) — piping, file inputs, exit codes, and automation recipes
 - [Troubleshooting](/cli/troubleshooting) — what each error means, and how to resolve it
-- [Command reference](/cli/commands) — every command, argument, and flag
+- [Command overview](/cli/commands) — global options, the command groups, and the commands that take no resource
+- [Complete reference](/cli/reference) — every command, argument, and flag on a single page