nueces · nueces · Jul 23, 2026 · Jul 23, 2026 · Jul 23, 2026 · Jul 23, 2026
diff --git a/README.md b/README.md
diff --git a/docs/build-local-debian-pi-image.md b/docs/build-local-debian-pi-image.md
@@ -36,11 +36,7 @@ src/sbx/image/resources/Containers/
 
 The build command reads these packaged resources with `importlib.resources` and combines them into a temporary Containerfile. Docker layer caching still makes the base OS layer reusable across tooling changes.
 
-Because Pi and uv tools are installed for `agent`, the matching `sbx` config should use:
-
-```toml
-run_user = "agent"
-```
+Because Pi and uv tools are installed for `agent`, the generated manifest defaults `run_user` to `agent`; the first project config records that effective user automatically.
 
 ## 2. Install the tools
 
@@ -95,8 +91,8 @@ The subcommand also writes a local image manifest:
 List built images:
 
 ```bash
-sbx image ls
-sbx image ls --json
+sbx image list
+sbx image list --json
 ```
 
 The builder downloads the reviewed SmolVM kernel recipe and Moby checker from pinned commit URLs, verifies each file's SHA-256 before use, and then compiles a Docker-capable QEMU kernel from a separately SHA-256-verified Linux source tarball. It stores the kernel as `vmlinux.bin`. Builds therefore require access to GitHub, kernel.org, and package repositories.
@@ -123,7 +119,8 @@ Example manifest:
   "sbx": {
     "agent": "pi",
     "features": ["docker"],
-    "launch_command": "pi"
+    "launch_command": "pi",
+    "run_user": "agent"
   }
 }
 ```
@@ -135,12 +132,13 @@ Use the built image and write the selected project settings:
 ```bash
 sbx run the-quest \
   --image '~/.smolvm/images/sbx' \
-  --run-user agent \
   --project-path . \
   --writable-mounts \
   --write-config
 ```
 
+The curated image manifest selects `run_user = "agent"` when CLI and project configuration do not select a user. `--project-path .` remains explicit because it creates a writable host mount.
+
 The suggested `.sbx.toml` is:
 
 ```toml
@@ -258,7 +256,7 @@ The image likely references an incompatible or older kernel. Rebuild it with the
 
 ### VM starts but SSH readiness times out
 
-If a cold boot reports that `wait_for_ssh` timed out, but `sbx ls -a` shows the VM as `running`, the guest may simply need more time before SSH is ready. Retry:
+If a cold boot reports that `wait_for_ssh` timed out, but `sbx ls` shows the VM as `running`, the guest may simply need more time before SSH is ready. Retry:
 
 ```bash
 sbx run

diff --git a/docs/current-local-image-usage.md b/docs/current-local-image-usage.md
@@ -48,12 +48,13 @@ The local image manifest is `smolvm-image.json`:
   "sbx": {
     "agent": "pi",
     "features": ["docker"],
-    "launch_command": "pi"
+    "launch_command": "pi",
+    "run_user": "agent"
   }
 }
 ```
 
-`sbx` reads this manifest to locate the kernel/rootfs, validate the configured agent, and list image features with `sbx image ls`.
+`sbx` reads this manifest to locate the kernel/rootfs, validate the configured agent, default the guest user when CLI/config omit it, and list image features with `sbx image list`. CLI and `[sbx].run_user` override the manifest value.
 
 ## Runtime flow
 
@@ -81,7 +82,7 @@ When `sbx run` starts a missing VM from this image, `sbx`:
 3. creates a SmolVM `VMConfig` using those paths and `comm_channel="ssh"`;
 4. starts the VM through the SmolVM SDK;
 5. waits for SSH readiness;
-6. prepares `run_user`, safe Git config, auth callback forwarding, and project cwd as configured;
+6. prepares the configured or manifest-defaulted `run_user`, safe Git config, auth callback forwarding, and project cwd;
 7. launches the configured agent command, usually `pi`.
 
 In code this path is handled by `src/sbx/cli.py` in `_start_local_image()`.

diff --git a/docs/ergonomics.md b/docs/ergonomics.md
@@ -44,6 +44,7 @@ If a command needs a sandbox name and neither a positional name nor `[sbx].name`
 | `shell` | Open an interactive shell for inspection/debugging. |
 | `stop` | Stop without deleting VM state. |
 | `rm` | Delete VM state. |
+| `ls` / `list` | List all sandboxes; `--running` filters to running VMs. |
 | `doctor` | Diagnose host backend and project/config state. |
 | `network ...` | Expert helpers for auth callback tunnels and network status. |
 
@@ -76,7 +77,7 @@ Examples of command/action concerns that should generally not be required in con
 - `--force`
 - `--debug`
 
-Some session defaults, such as `stop_on_exit`, `auth_port`, or `git_config`, can live in config because they affect repeated project workflow behavior.
+Security and forwarding policy such as `auth_port`, `copy_host_credentials`, and `git_config` lives only in config so recreation is reproducible. `copy_host_credentials` remains false by default.
 
 ## Existing VM reuse
 
@@ -126,12 +127,11 @@ Behavior:
 - If `./.sbx.toml` exists, never modify it by default.
 - If `./.sbx.toml` exists and `--write-config` is passed, add missing durable keys only.
 - Never overwrite existing values.
-- `--no-write-config` disables automatic config creation for that invocation.
 
 Example:
 
 ```bash
-sbx run --name the-quest --image ~/.smolvm/images/sbx --memory 8192 --cpus 4 --disk-size 40960 --project-path . --run-user agent
+sbx run the-quest --image ~/.smolvm/images/sbx --memory 8192 --cpus 4 --disk-size 40960 --project-path .
 ```
 
 could create:
@@ -147,7 +147,7 @@ project_path = "."
 run_user = "agent"
 ```
 
-After that, project workflows become:
+On initial creation, `sbx` prints the generated config and the next `run`, `shell`, `stop`, and `rm` commands. After that, project workflows become:
 
 ```bash
 sbx run

diff --git a/docs/git-config-forwarding.md b/docs/git-config-forwarding.md
@@ -11,20 +11,13 @@ Git config forwarding is enabled by default:
 git_config = true
 ```
 
-Disable it with:
+Disable it reproducibly in project configuration:
 
 ```toml
 [sbx]
 git_config = false
 ```
 
-or per command:
-
-```bash
-sbx run --no-git-config
-sbx shell --no-git-config
-```
-
 ## Copied keys
 
 Only these global Git config keys are copied:

diff --git a/docs/network-command-roadmap.md b/docs/network-command-roadmap.md
@@ -10,16 +10,16 @@ sbx network ...
 
 ## Current commands
 
-### `sbx network forward [NAME] SPEC...`
+### `sbx network forward [--name NAME] SPEC...`
 
-Forwards host TCP ports to a running sandbox in the foreground. Press Ctrl-C to stop all forwards.
+Forwards host TCP ports to a running sandbox in the foreground. It uses `[sbx].name` unless `--name` selects another VM. Press Ctrl-C to stop all forwards.
 
 ```bash
 sbx network forward 3000
 sbx network forward 8080:3000
 sbx network forward 0.0.0.0:3000:3000
 sbx network forward 3000 8080:80
-sbx network forward my-sbx 3000 8080:80
+sbx network forward --name the-quest 3000 8080:80
 ```
 
 `SPEC` is one of:
@@ -53,7 +53,7 @@ Auth callback: active
 Auth detail: pid 12345, localhost:1455 -> guest:1455
 ```
 
-If the auth callback port is listening but the process is not tracked by `sbx`, status reports:
+Use `sbx network status --json` for machine-readable status. If the auth callback port is listening but the process is not tracked by `sbx`, status reports:
 
 ```text
 Auth callback: busy/untracked