From 94da41dc52662aa790f8e63f87d9d0e9b982eae6 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Sun, 4 Jan 2026 16:02:28 +0000
Subject: [PATCH] docs: document sandbox image recovery

---
 CHANGELOG.md   |  1 +
 docs/docker.md | 15 +++++++++++++++
 docs/doctor.md |  5 +++++
 3 files changed, 21 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 16b3c53c1..bf571fa50 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -18,6 +18,7 @@
 
 ### Fixes
 - Doctor migrates legacy Clawdis config/service installs and normalizes sandbox Docker names.
+- Doctor checks sandbox image availability and offers to build or fall back to legacy images.
 - Presence beacons keep node lists fresh; Instances view stays accurate.
 - Block streaming/chunking reliability (Telegram/Discord ordering, fewer duplicates).
 - WhatsApp GIF playback for MP4-based GIFs.
diff --git a/docs/docker.md b/docs/docker.md
index f6ed8ca49..1f87e324b 100644
--- a/docs/docker.md
+++ b/docs/docker.md
@@ -141,6 +141,21 @@ scripts/sandbox-setup.sh
 
 This builds `clawdbot-sandbox:bookworm-slim` using `Dockerfile.sandbox`.
 
+### Sandbox common image (optional)
+If you want a sandbox image with common build tooling (Node, Go, Rust, etc.), build the common image:
+
+```bash
+scripts/sandbox-common-setup.sh
+```
+
+This builds `clawdbot-sandbox-common:bookworm-slim`. To use it:
+
+```json5
+{
+  agent: { sandbox: { docker: { image: "clawdbot-sandbox-common:bookworm-slim" } } }
+}
+```
+
 ### Sandbox browser image
 
 To run the browser tool inside the sandbox, build the browser image:
diff --git a/docs/doctor.md b/docs/doctor.md
index 12b80252e..f6b599a59 100644
--- a/docs/doctor.md
+++ b/docs/doctor.md
@@ -12,8 +12,13 @@ read_when:
 - Runs a health check and offers to restart the gateway if it looks unhealthy.
 - Prints a skills status summary (eligible/missing/blocked).
 - Detects deprecated config keys and offers to migrate them.
+- Migrates legacy `~/.clawdis/clawdis.json` when no Clawdbot config exists.
+- Checks sandbox Docker images when sandboxing is enabled (offers to build or switch to legacy names).
 - Detects legacy Clawdis services (launchd/systemd/schtasks) and offers to migrate them.
 
+## Legacy config file migration
+If `~/.clawdis/clawdis.json` exists and `~/.clawdbot/clawdbot.json` does not, doctor will migrate the file and normalize old paths/image names.
+
 ## Legacy config migrations
 When the config contains deprecated keys, other commands will refuse to run and ask you to run `clawdbot doctor`.
 Doctor will: