From 505c4262c6710c239b27ba1d8ae7761917c330f6 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Fri, 2 Jan 2026 20:58:50 +0100
Subject: [PATCH] docs: note optional docker setup

---
 README.md      |  2 +-
 docs/docker.md | 49 +++++++++++++++++++++++++++++++++++++++++++++++++
 docs/setup.md  |  1 +
 docs/test.md   |  2 ++
 4 files changed, 53 insertions(+), 1 deletion(-)
 create mode 100644 docs/docker.md

diff --git a/README.md b/README.md
index 9f0dfd62d..c7388a05d 100644
--- a/README.md
+++ b/README.md
@@ -20,7 +20,7 @@ It answers you on the surfaces you already use (WhatsApp, Telegram, Discord, iMe
 
 If you want a private, single-user assistant that feels local, fast, and always-on, this is it.
 
-Website: https://clawd.me · Docs: [`docs/index.md`](docs/index.md) · FAQ: [`docs/faq.md`](docs/faq.md) · Wizard: [`docs/wizard.md`](docs/wizard.md) · Discord: https://discord.gg/qkhbAGHRBT
+Website: https://clawd.me · Docs: [`docs/index.md`](docs/index.md) · FAQ: [`docs/faq.md`](docs/faq.md) · Wizard: [`docs/wizard.md`](docs/wizard.md) · Docker (optional): [`docs/docker.md`](docs/docker.md) · Discord: https://discord.gg/qkhbAGHRBT
 
 Preferred setup: run the onboarding wizard (`clawdis onboard`). It walks through gateway, workspace, providers, and skills. The CLI wizard is the recommended path and works on **macOS, Windows, and Linux**.
 
diff --git a/docs/docker.md b/docs/docker.md
new file mode 100644
index 000000000..e5d544190
--- /dev/null
+++ b/docs/docker.md
@@ -0,0 +1,49 @@
+---
+summary: "Optional Docker-based setup and onboarding for Clawdis"
+read_when:
+  - You want a containerized gateway instead of local installs
+  - You are validating the Docker flow
+---
+
+# Docker (optional)
+
+Docker is **optional**. Use it only if you want a containerized gateway or to validate the Docker flow.
+
+## Quick start (recommended)
+
+From the repo root:
+
+```bash
+./docker-setup.sh
+```
+
+This script:
+- builds the image
+- runs the onboarding wizard
+- runs WhatsApp login
+- starts the gateway via Docker Compose
+
+It writes config/workspace on the host:
+- `~/.clawdis/`
+- `~/clawd`
+
+## Manual flow (compose)
+
+```bash
+docker build -t clawdis:local -f Dockerfile .
+docker compose run --rm clawdis-cli onboard
+docker compose run --rm clawdis-cli login
+docker compose up -d clawdis-gateway
+```
+
+## E2E smoke test (Docker)
+
+```bash
+scripts/e2e/onboard-docker.sh
+```
+
+## Notes
+
+- Gateway bind defaults to `lan` for container use.
+- Health check:
+  `docker compose exec clawdis-gateway node dist/index.js health --token "$CLAWDIS_GATEWAY_TOKEN"`
diff --git a/docs/setup.md b/docs/setup.md
index c2a95f70a..614d197b6 100644
--- a/docs/setup.md
+++ b/docs/setup.md
@@ -17,6 +17,7 @@ Last updated: 2026-01-01
 ## Prereqs (from source)
 - Node `>=22`
 - `pnpm`
+- Docker (optional; only for containerized setup/e2e — see `docs/docker.md`)
 
 ## Tailoring strategy (so updates don’t hurt)
 
diff --git a/docs/test.md b/docs/test.md
index e4118e399..80c99c91e 100644
--- a/docs/test.md
+++ b/docs/test.md
@@ -23,6 +23,8 @@ Last run (2025-12-31, 20 runs):
 
 ## Onboarding E2E (Docker)
 
+Docker is optional; this is only needed for containerized onboarding smoke tests.
+
 Full cold-start flow in a clean Linux container:
 
 ```bash