docs: update shared skills behavior for sbx v0.43.0

content/manuals/ai/sandboxes/architecture.md

@@ -51,8 +51,9 @@ a directly mounted workspace live on the host instead.
 Each sandbox maintains its own Docker daemon state, image cache, and package
 installations. Multiple sandboxes don't share images or layers. The
 [shared agent skills store](workflows/agent-skills.md) is an exception:
-supported agents mount the same host-side store read-write unless you opt out
-when creating the sandbox.
+sandboxes created for supported agents mount the same host-side store read-only
+by default. Use `--skills` or `skills.defaultMode` to choose another mode at
+creation. Existing sandboxes retain their mounts until recreated.
 
 Each sandbox consumes disk space for its VM image, Docker images, container
 layers, and volumes, and this grows as you build images and install packages.

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

@@ -28,9 +28,10 @@ What crosses the boundary into the VM:
   outbound HTTP requests. The raw credential values never enter the VM.
 - **Network access:** outbound TCP connections to destinations allowed by
   [network policy](defaults/) are proxied through the host.
-- **Shared agent skills:** a persistent host-side store is mounted read-write
-  at the agent's skills directory unless you opt out when creating the
-  sandbox. Supported agents in other sandboxes mount the same store.
+- Shared agent skills: sandboxes created for supported agents mount a
+  persistent host-side store read-only by default at the agent's skills
+  directory. Use `--skills` or `skills.defaultMode` to choose another mode at
+  creation. Existing sandboxes retain their mounts until recreated.
 - **MCP gateway traffic:** supported agents connect to a host-side MCP gateway
   endpoint. The gateway brokers access to registered MCP servers.
 
@@ -40,8 +41,8 @@ What crosses the boundary back to the host:
   direct mount.
 - **Outbound TCP connections:** sent to allowed destinations through the host
   proxy.
-- **Shared skill changes:** written to the host-side store and visible to other
-  sandboxes that share it.
+- Shared skill changes: sandboxes with `readwrite` access can write to the
+  host-side store. These changes are visible to other sandboxes that share it.
 
 Outside the workspace and shared skills store, the agent cannot access your
 host filesystem. It also cannot access your host Docker daemon, your host
@@ -113,8 +114,9 @@ that defaults to Docker Hub only. See
 [Restrict kit sources](../customize/kits.md#restrict-kit-sources).
 
 Shared agent skills create a narrow exception to cross-sandbox isolation. The
-store is mounted read-write, so one sandbox can modify instructions or scripts
-that an agent later uses in another sandbox. This doesn't expose the rest of
+store can be mounted with `readwrite` access, so one sandbox can modify
+instructions or scripts that an agent later uses in another sandbox, including
+one with `readonly` access. This doesn't expose the rest of
 the host filesystem or create a direct network path between sandboxes, but it
 does put participating sandboxes in the same trust boundary. See
 [Share agent skills](../workflows/agent-skills.md) for details and the

content/manuals/ai/sandboxes/security/defaults.md

@@ -39,10 +39,12 @@ workspace modes and what to review after a direct-mount session.
 
 ## Shared skills defaults
 
-Sandboxes for supported agents mount a persistent shared skills store
-read-write by default. Every sandbox that uses the store can change skills that
-other participating sandboxes may load. Use `--no-share-skills` when creating a
-sandbox to keep it outside this shared trust boundary. See
+Sandboxes created for supported agents mount a persistent shared skills store
+read-only by default. The `skills.defaultMode` setting can change this default,
+and `--skills` overrides it for a sandbox at creation. A sandbox with `readwrite` access can change skills that other
+participating sandboxes load, including those with `readonly` access. Use
+`--skills=off` when creating a sandbox to omit the shared store. Existing
+sandboxes retain their mounts until recreated. See
 [Share agent skills](../workflows/agent-skills.md).
 
 ## Credential defaults

content/manuals/ai/sandboxes/workflows/agent-skills.md

@@ -120,29 +120,45 @@ repository, so `sbx skills update` won't refresh it.
 
 Running `sbx reset` clears the shared store.
 
-Sandboxes created with `sbx` version 0.37.0 or later for a supported agent are
-configured to mount the store read-write by default. These sandboxes mount the
-current contents of the store each time they start, so you can install skills
-before or after creating them. To create a sandbox without the shared store,
-use `--no-share-skills`:
+Sandboxes created for a supported agent mount the shared store read-only by
+default. These sandboxes mount the contents of the store each time they start,
+so you can install skills before or after creating them.
+
+Use `--skills` with `sbx run` or `sbx create` to choose the access mode when
+creating a sandbox:
+
+- `readonly`: Mount the store so the agent can read skills but cannot modify them.
+- `readwrite`: Mount the store so the agent can read and modify shared skills.
+- `off`: Omit the shared store mount.
+
+For example, create a sandbox without the shared store:
+
+```console
+$ sbx run --skills=off claude
+```
+
+To change the default for future sandboxes, set `skills.defaultMode` to `off`,
+`readonly`, or `readwrite`:
 
 ```console
-$ sbx run --no-share-skills claude
+$ sbx settings set skills.defaultMode readonly
 ```
 
-Upgrading `sbx` does not enable shared skills for sandboxes created with an
-earlier version. Remove and recreate those sandboxes after upgrading. The
-`--no-share-skills` option also only applies when the sandbox is created. To
-turn off shared skills for an existing sandbox, remove it and recreate it with
-the option.
+When no mode is specified, the daemon uses `skills.defaultMode`, whose built-in
+value is `readonly`. An explicit `--skills` value overrides that default.
+
+The mode is applied only when a sandbox is created. Upgrading `sbx` or changing
+`skills.defaultMode` leaves existing sandbox mounts unchanged. Remove and
+recreate a sandbox to change its mode. Sandboxes created without shared skills
+also need to be recreated to mount the store.
 
 > [!WARNING]
-> The shared skills store is mounted read-write. A sandbox can modify any skill
-> in the store, and another sandbox can later load the modified instructions or
-> run the modified scripts. The store is dedicated sandbox state, so this does
-> not by itself execute the modified skill on your host. It does put every
-> sandbox that shares the store in the same trust boundary. Use
-> `--no-share-skills` to keep a sandbox outside that boundary.
+> A sandbox with `readwrite` access can modify skills that other sandboxes load,
+> including sandboxes with `readonly` access. Read-only access prevents writes
+> from that sandbox but does not isolate it from changes to the store. The store
+> is dedicated sandbox state, so this does not by itself execute modified skills
+> on your host. Use `--skills=off` when creating a sandbox to keep it outside
+> this shared trust boundary.
 
 Some agents scan for skills when a session starts. If installed skills don't
 appear in an existing session, start another agent session.