fix(sandboxes): scope comment handling to manifest input and keep the shared conflict example generic

Author: icecrasher321

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

@@ -2761,9 +2761,9 @@ sim sandboxes create [options]
 | --- | --- | --- |
 | `--name <value>` | Yes | Display name, unique within the workspace; 1 to 64 characters. |
 | `--language <value>` | Yes | Dependency ecosystem: `javascript` installs from npm, `python` from PyPI. Accepted values: `javascript`, `python`. |
-| `--dependencies <value...>` | No | Package specifiers installed into the sandbox, one per entry. An entry starting with `#` is a comment and is skipped. (space-separated, or @path / @- with one value per line, blank lines and # comments ignored; @@value for a literal leading @). |
+| `--dependencies <value...>` | No | Package specifiers installed into the sandbox, one per entry. (space-separated, or @path / @- with one value per line; in a file, blank lines and # comments are ignored; @@value for a literal leading @). |
 | `--cli-tools <value...>` | No | Pinned managed CLI ids installed into the sandbox, at most 10, no duplicates. (space-separated, or @path / @- with one value per line; @@value for a literal leading @). |
-| `--system-packages <value...>` | No | Debian packages installed into the sandbox, one per entry. (space-separated, or @path / @- with one value per line, blank lines and # comments ignored; @@value for a literal leading @). |
+| `--system-packages <value...>` | No | Debian packages installed into the sandbox, one per entry. (space-separated, or @path / @- with one value per line; in a file, blank lines and # comments are ignored; @@value for a literal leading @). |
 
 </CommandTable>
 
@@ -2860,9 +2860,9 @@ sim sandboxes update <sandboxId> [options]
 | --- | --- | --- |
 | `--name <value>` | No | New display name, unique within the workspace; 1 to 64 characters. |
 | `--language <value>` | No | Replacement dependency ecosystem. The whole spec is revalidated against it, so a Python dependency list does not survive a switch to JavaScript. Accepted values: `javascript`, `python`. |
-| `--dependencies <value...>` | No | Replacement package list; replaces the whole list. (space-separated, or @path / @- with one value per line, blank lines and # comments ignored; @@value for a literal leading @). |
+| `--dependencies <value...>` | No | Replacement package list; replaces the whole list. (space-separated, or @path / @- with one value per line; in a file, blank lines and # comments are ignored; @@value for a literal leading @). |
 | `--cli-tools <value...>` | No | Replacement managed CLI list; replaces the whole list. (space-separated, or @path / @- with one value per line; @@value for a literal leading @). |
-| `--system-packages <value...>` | No | Replacement Debian package list; replaces the whole list. (space-separated, or @path / @- with one value per line, blank lines and # comments ignored; @@value for a literal leading @). |
+| `--system-packages <value...>` | No | Replacement Debian package list; replaces the whole list. (space-separated, or @path / @- with one value per line; in a file, blank lines and # comments are ignored; @@value for a literal leading @). |
 
 </CommandTable>
 

apps/docs/content/docs/cli/sandboxes.mdx

@@ -25,9 +25,9 @@ Create Sandbox (personal API key required)
 | --- | --- | --- |
 | `--name <value>` | Yes | Display name, unique within the workspace; 1 to 64 characters. |
 | `--language <value>` | Yes | Dependency ecosystem: `javascript` installs from npm, `python` from PyPI. Accepted values: `javascript`, `python`. |
-| `--dependencies <value...>` | No | Package specifiers installed into the sandbox, one per entry. An entry starting with `#` is a comment and is skipped. (space-separated, or @path / @- with one value per line, blank lines and # comments ignored; @@value for a literal leading @). |
+| `--dependencies <value...>` | No | Package specifiers installed into the sandbox, one per entry. (space-separated, or @path / @- with one value per line; in a file, blank lines and # comments are ignored; @@value for a literal leading @). |
 | `--cli-tools <value...>` | No | Pinned managed CLI ids installed into the sandbox, at most 10, no duplicates. (space-separated, or @path / @- with one value per line; @@value for a literal leading @). |
-| `--system-packages <value...>` | No | Debian packages installed into the sandbox, one per entry. (space-separated, or @path / @- with one value per line, blank lines and # comments ignored; @@value for a literal leading @). |
+| `--system-packages <value...>` | No | Debian packages installed into the sandbox, one per entry. (space-separated, or @path / @- with one value per line; in a file, blank lines and # comments are ignored; @@value for a literal leading @). |
 
 </CommandTable>
 
@@ -120,8 +120,8 @@ Update Sandbox (personal API key required)
 | --- | --- | --- |
 | `--name <value>` | No | New display name, unique within the workspace; 1 to 64 characters. |
 | `--language <value>` | No | Replacement dependency ecosystem. The whole spec is revalidated against it, so a Python dependency list does not survive a switch to JavaScript. Accepted values: `javascript`, `python`. |
-| `--dependencies <value...>` | No | Replacement package list; replaces the whole list. (space-separated, or @path / @- with one value per line, blank lines and # comments ignored; @@value for a literal leading @). |
+| `--dependencies <value...>` | No | Replacement package list; replaces the whole list. (space-separated, or @path / @- with one value per line; in a file, blank lines and # comments are ignored; @@value for a literal leading @). |
 | `--cli-tools <value...>` | No | Replacement managed CLI list; replaces the whole list. (space-separated, or @path / @- with one value per line; @@value for a literal leading @). |
-| `--system-packages <value...>` | No | Replacement Debian package list; replaces the whole list. (space-separated, or @path / @- with one value per line, blank lines and # comments ignored; @@value for a literal leading @). |
+| `--system-packages <value...>` | No | Replacement Debian package list; replaces the whole list. (space-separated, or @path / @- with one value per line; in a file, blank lines and # comments are ignored; @@value for a literal leading @). |
 
 </CommandTable>

apps/docs/openapi-v2-resources.json

@@ -2373,7 +2373,7 @@
       "delete": {
         "operationId": "deleteSandbox",
         "summary": "Delete Sandbox",
-        "description": "Delete a sandbox. Function blocks that still select it fail closed at run time until they are re-pointed. Any prebuilt image is released once nothing else shares it. Requires a workspace admin on a Max or Enterprise plan; a lower plan is refused with `403` and `error.details.code` `WORKSPACE_PLAN_CAPABILITY_REQUIRED`. A workspace API key is rejected with `403`; use a personal API key.",
+        "description": "Delete a sandbox. Function blocks that still select it fail closed at run time until they are re-pointed. Where the deployment prebuilds dependency images, the sandbox's image is released once nothing else shares it; a runtime-install deployment, or a spec with nothing to install, had no image and nothing is released. Requires a workspace admin on a Max or Enterprise plan; a lower plan is refused with `403` and `error.details.code` `WORKSPACE_PLAN_CAPABILITY_REQUIRED`. A workspace API key is rejected with `403`; use a personal API key.",
         "tags": ["Sandboxes"],
         "parameters": [
           {
@@ -4774,7 +4774,7 @@
             "example": {
               "error": {
                 "code": "CONFLICT",
-                "message": "A resource with this name already exists in this workspace"
+                "message": "The request conflicts with the current state of the resource"
               }
             }
           }
@@ -6809,7 +6809,7 @@
             "items": {
               "type": "string"
             },
-            "description": "Package specifiers installed into the sandbox, one per entry. An entry starting with `#` is a comment and is skipped."
+            "description": "Package specifiers installed into the sandbox, one per entry."
           },
           "cliTools": {
             "type": "array",
@@ -7044,7 +7044,7 @@
           },
           "dependencies": {
             "default": [],
-            "description": "Package specifiers installed into the sandbox, one per entry. An entry starting with `#` is a comment and is skipped.",
+            "description": "Package specifiers installed into the sandbox, one per entry.",
             "maxItems": 1000,
             "type": "array",
             "items": {

apps/sim/lib/api/contracts/v2/openapi/resources.ts

@@ -1371,7 +1371,7 @@ const declaredRoutes = [
     resourceOperation('Sandboxes', {
       operationId: 'deleteSandbox',
       summary: 'Delete Sandbox',
-      description: `Delete a sandbox. Function blocks that still select it fail closed at run time until they are re-pointed. Any prebuilt image is released once nothing else shares it. ${SANDBOX_ADMIN_PLAN_NOTE} ${WORKSPACE_API_KEY_DENIED}`,
+      description: `Delete a sandbox. Function blocks that still select it fail closed at run time until they are re-pointed. Where the deployment prebuilds dependency images, the sandbox's image is released once nothing else shares it; a runtime-install deployment, or a spec with nothing to install, had no image and nothing is released. ${SANDBOX_ADMIN_PLAN_NOTE} ${WORKSPACE_API_KEY_DENIED}`,
       errors: RESOURCE_ERRORS,
       success: { description: 'The sandbox was deleted.' },
     }),
@@ -2157,13 +2157,12 @@ export const resourcesOpenApiDocument = defineOpenApiDocument({
   headers: V2_COMMON_HEADERS,
   errorSchema: V2_ERROR_SCHEMA,
   /**
-   * Every `409` in this document is a name collision — an MCP server, skill,
-   * custom tool, sandbox, credential, or secret whose name is already taken in
-   * the workspace — so the shared example names that remedy rather than one
-   * resource's.
+   * Most `409`s in this document are name collisions, but MCP tool discovery
+   * raises one for a stored OAuth grant that must be reauthorized, so the shared
+   * example stays generic and each operation's description names its own cause.
    */
   errorResponses: withErrorExamples({
-    Conflict: { message: 'A resource with this name already exists in this workspace' },
+    Conflict: { message: 'The request conflicts with the current state of the resource' },
   }),
   routes,
 })

apps/sim/lib/api/contracts/v2/sandboxes.ts

@@ -33,8 +33,7 @@ import {
 
 const LANGUAGE_DESCRIPTION =
   'Dependency ecosystem: `javascript` installs from npm, `python` from PyPI.'
-const DEPENDENCIES_DESCRIPTION =
-  'Package specifiers installed into the sandbox, one per entry. An entry starting with `#` is a comment and is skipped.'
+const DEPENDENCIES_DESCRIPTION = 'Package specifiers installed into the sandbox, one per entry.'
 const CLI_TOOLS_DESCRIPTION =
   'Pinned managed CLI ids installed into the sandbox, at most 10, no duplicates.'
 const SYSTEM_PACKAGES_DESCRIPTION = 'Debian packages installed into the sandbox, one per entry.'

packages/sim-cli/src/generated/v2-api.ts

@@ -10383,8 +10383,7 @@ export const V2_OPERATIONS = {
       dependencies: {
         kind: 'array',
         default: [],
-        describe:
-          'Package specifiers installed into the sandbox, one per entry. An entry starting with `#` is a comment and is skipped.',
+        describe: 'Package specifiers installed into the sandbox, one per entry.',
       },
       cliTools: {
         kind: 'array',

packages/sim-cli/src/runtime/options.ts

@@ -168,7 +168,7 @@ function addFieldOption(
   const describe = `${documented}${
     takesList
       ? flag.manifest
-        ? ' (space-separated, or @path / @- with one value per line, blank lines and # comments ignored; @@value for a literal leading @)'
+        ? ' (space-separated, or @path / @- with one value per line; in a file, blank lines and # comments are ignored; @@value for a literal leading @)'
         : ' (space-separated, or @path / @- with one value per line; @@value for a literal leading @)'
       : wantsJson
         ? ' (JSON, or @path / @- to read a file or stdin)'