Document custom mount targets for additional sandbox workspaces (#26476)

Document how to mount additional sandbox workspaces at a chosen path
with the CLI or an environment file. Include target restrictions and
clarify that mounting at the host path remains the default.

Validation: Formatting and scoped Markdown and Vale checks pass for all
four changed pages. CLI examples were not run because `sbx` was
unavailable.

content/manuals/ai/sandboxes/architecture.md

@@ -27,11 +27,12 @@ current directory when you don't pass a path. The sandbox sees your actual
 host files, so changes in either direction are instant with no sync process
 involved.
 
-A directly mounted workspace appears at the same absolute path as on your
-host. Preserving absolute paths means error messages, configuration files, and
-build outputs all reference paths you can find on your host. The agent sees the
-same directory structure, which reduces confusion when debugging or reviewing
-changes.
+By default, a directly mounted workspace appears at the same absolute path as
+on your host. Preserving absolute paths means error messages, configuration
+files, and build outputs all reference paths you can find on your host. The
+agent sees the same directory structure, which reduces confusion when debugging
+or reviewing changes. You can choose a different sandbox path for
+[additional workspaces](usage.md#multiple-workspaces).
 
 Clone mode uses a third storage layout. The host repository is mounted
 read-only at `/run/sandbox/source`, and the agent works in a private clone

content/manuals/ai/sandboxes/configuration/environment-files.md

@@ -688,10 +688,25 @@ You can override `workspace.clone` for one `create` or `run` invocation with
 Each additional workspace is mounted after the primary workspace. Relative
 paths resolve from the directory of the environment file that declares them.
 
-| Field      | Type    | Required | Default | Description                   |
-| ---------- | ------- | -------- | ------- | ----------------------------- |
-| `path`     | string  | Yes      | None    | Directory to mount            |
-| `readOnly` | boolean | No       | `false` | Mount the directory read-only |
+| Field      | Type    | Required | Default                      | Description                            |
+| ---------- | ------- | -------- | ---------------------------- | -------------------------------------- |
+| `path`     | string  | Yes      | None                         | Directory to mount                     |
+| `target`   | string  | No       | Host path inside the sandbox | Absolute POSIX path inside the sandbox |
+| `readOnly` | boolean | No       | `false`                      | Mount the directory read-only          |
+
+For example, mount a shared library directory read-only at a chosen path:
+
+```yaml
+workspace: .
+additionalWorkspaces:
+  - path: ../shared-libs
+    target: /workspace/libs
+    readOnly: true
+```
+
+Omit `target` to use the host path inside the sandbox. The same
+[target restrictions](../usage.md#multiple-workspaces) apply as with
+`sbx create` and `sbx run`.
 
 ### `mounts`
 

content/manuals/ai/sandboxes/integrations/_index.md

@@ -125,11 +125,13 @@ client. An interactive SSH shell starts in the sandbox workspace, matching
 home directory, `/home/agent`. Select the intended folder explicitly in the
 editor instead of relying on its initial location.
 
-For a sandbox with a primary workspace, each workspace path appears inside the
-sandbox at the same absolute path as on the host. For example, if you pass
-`/Users/bob/src/my-project`, select that path in the remote folder picker. For
-a mountless sandbox that uses a Docker-provided agent template, select
-`/home/agent/workspace`.
+In the remote folder picker, select the workspace's path inside the sandbox.
+A workspace mounted from `/Users/bob/src/my-project` uses that same path by
+default. A custom mount target such as `/workspace/data` is the path to open
+in the editor.
+
+Docker-provided agent templates use `/home/agent/workspace` as the workspace
+folder for mountless sandboxes.
 
 ## Connect a specific tool
 

content/manuals/ai/sandboxes/usage.md

@@ -347,14 +347,30 @@ The first path is the primary workspace — the agent starts here, and the
 sandbox's in-container Git clone is populated from this directory if you
 use `--clone`. Extra workspaces are always mounted directly.
 
-Each workspace path appears inside the sandbox at the same absolute path as on
-the host. Append `:ro` to mount an extra workspace read-only — useful for
+By default, each directly mounted workspace appears at the same absolute path
+as on the host. Append `:ro` to mount an extra workspace read-only — useful for
 reference material or shared libraries the agent shouldn't modify:
 
 ```console
 $ sbx run claude ~/project-a ~/shared-libs:ro ~/docs:ro
 ```
 
+To choose a sandbox path for an additional workspace, use
+`PATH:TARGET[:ro]` with `sbx run` or `sbx create`:
+
+```console
+$ sbx run claude ~/project-a ~/shared-libs:/workspace/libs:ro
+```
+
+This mounts `~/shared-libs` read-only at `/workspace/libs` inside the sandbox.
+The primary workspace doesn't accept a target.
+
+The target must be an absolute POSIX path other than `/`, without colons or
+NUL bytes. Choose a distinct target for each additional workspace. Targets
+must not match the primary workspace path or a reserved skills path. In clone
+mode, they must also stay outside the clone directory and must not match
+`/run/sandbox/source`.
+
 You can also run separate projects side-by-side. Remove unused sandboxes when
 you're done to reclaim disk space: