diff --git a/DOCKER_HUB.md b/DOCKER_HUB.md
index f279a6f..8d8f0c8 100644
--- a/DOCKER_HUB.md
+++ b/DOCKER_HUB.md
@@ -103,18 +103,28 @@ opencode
 | `GIT_USER_NAME` | Git commit author name |
 | `GIT_USER_EMAIL` | Git commit author email |
 
-## Volumes
+## Data Storage and Persistence
 
-| Host Path | Container Path | Purpose |
-|---|---|---|
-| Your project directory | `/workspace` | Code you want to work on |
-| `~/.ssh` | `/home/developer/.ssh:ro` | SSH keys for git (read-only) |
-| (optional) `~/.aws` | `/home/developer/.aws:ro` | AWS credentials/config |
-| (optional) Custom config | `/home/developer/.config/opencode/opencode.json:ro` | Full opencode config with MCP servers, etc. |
+Understanding what survives container restarts and what doesn't:
+
+| Path in container | Source | Survives restart? | Contains |
+|---|---|---|---|
+| `/workspace` | Host bind mount | ✅ Yes — lives on host | Your project files |
+| `/home/developer/.ssh` | Host bind mount (ro) | ✅ Yes — lives on host | SSH keys |
+| `/home/developer/.local/share/opencode` | Named volume (if configured) | ✅ Yes — Docker volume | Session history, memory, auth tokens |
+| `/home/developer/.config/opencode/opencode.json` | Generated by entrypoint | ❌ No — regenerated each start | Provider config, MCP server definitions |
+| `/home/developer/.aws` | Host bind mount (if configured) | ✅ Yes — lives on host | AWS credentials/SSO cache |
+
+### Key points
+
+- **Project files** (`/workspace`) are always safe — they're your host filesystem.
+- **opencode config** is auto-generated from `OPENCODE_PROVIDER` env var on each start. It only sets provider and model — no MCP servers. To persist MCP server config, mount your own config file (see Custom opencode Config below).
+- **opencode data** (session history, memory) is lost with `--rm` unless you add a named volume.
+- **AWS SSO tokens** are stored inside the container and lost on restart. Re-run `aws sso login` after restarting.
 
 ### Persisting opencode data
 
-To keep opencode state (session history, memory) between runs, add a named volume:
+Add a named volume to keep session history and memory between runs:
 
 ```bash
 docker run -it --rm \
diff --git a/README.md b/README.md
index 751056c..44d83fe 100644
--- a/README.md
+++ b/README.md
@@ -197,6 +197,20 @@ Container (Debian bookworm)
 └── /workspace ← your code lives here
 ```
 
+### Data persistence
+
+| Path in container | Source | Survives `--rm`? | Contains |
+|---|---|---|---|
+| `/workspace` | Host bind mount | ✅ Yes | Your project files |
+| `/home/developer/.ssh` | Host bind mount (ro) | ✅ Yes | SSH keys |
+| `/home/developer/.local/share/opencode` | Named volume `devbox-data` | ✅ Yes | Session history, memory |
+| `/home/developer/.config/opencode/opencode.json` | Generated by entrypoint | ❌ No | Provider/model config |
+| `/home/developer/.aws` | Not mounted by default | ❌ No | AWS SSO tokens |
+
+**opencode config** (`opencode.json`) is auto-generated from `OPENCODE_PROVIDER` on each start. It sets provider and model only — no MCP servers. To use MCP servers or custom settings, mount your own config file (see Custom opencode config above).
+
+To persist AWS SSO sessions across restarts, uncomment the `~/.aws` volume mount in `docker-compose.yml`.
+
 ## License
 
 MIT