diff --git a/DOCKER_HUB.md b/DOCKER_HUB.md
index ae9cfce..0db209c 100644
--- a/DOCKER_HUB.md
+++ b/DOCKER_HUB.md
@@ -17,6 +17,21 @@ All variants support `linux/amd64` and `linux/arm64`.
 
 ## Quick Start
 
+For a fully-configured environment with persistent state (opencode config, mempalace memory, neovim plugins, bash history) surviving container recreation, use docker-compose. **You don't need to clone the repo** — just grab two template files:
+
+```bash
+mkdir -p ~/opencode-devbox && cd ~/opencode-devbox
+curl -O https://gitea.jordbo.se/joakimp/opencode-devbox/raw/branch/main/docker-compose.yml
+curl -fsSL https://gitea.jordbo.se/joakimp/opencode-devbox/raw/branch/main/.env.example -o .env
+# Edit .env — set OPENCODE_PROVIDER, the matching API key,
+# WORKSPACE_PATH, GIT_USER_NAME, GIT_USER_EMAIL.
+docker compose run --rm devbox
+```
+
+This drops you straight into opencode with your project mounted at `/workspace`. Use `bash` as the command (e.g. `docker compose run --rm devbox bash`) to land in a shell first — useful for `aws sso login`, `pi` (on `*-with-pi` variants), or multi-harness workflows.
+
+**One-shot run, no persistence:**
+
 ```bash
 docker run -it --rm \
   -e ANTHROPIC_API_KEY=your-key \
@@ -28,22 +43,7 @@ docker run -it --rm \
   joakimp/opencode-devbox:latest
 ```
 
-Drops you straight into opencode with your project mounted at `/workspace`.
-
-For an interactive shell first (useful for AWS SSO login, multi-harness workflows, or just `bash`):
-
-```bash
-docker run -it --rm \
-  -e ANTHROPIC_API_KEY=your-key \
-  -e OPENCODE_PROVIDER=anthropic \
-  -v ~/projects:/workspace \
-  -v ~/.ssh:/home/developer/.ssh:ro \
-  joakimp/opencode-devbox:latest bash
-```
-
-Then run `opencode`, `pi` (on `*-with-pi` variants), or `aws sso login` from the shell.
-
-For docker-compose users, the source repo provides `docker-compose.yml`, `.env.example`, and a one-liner `docker compose up -d` workflow with named volumes pre-wired.
+Full setup guide — authentication for each provider (Anthropic, OpenAI, Bedrock SSO + static), persistence model, build args, troubleshooting: <https://gitea.jordbo.se/joakimp/opencode-devbox#readme>
 
 ## What's Inside
 
diff --git a/README.md b/README.md
index c45d44c..c49ea0d 100644
--- a/README.md
+++ b/README.md
@@ -8,8 +8,28 @@ The official `ghcr.io/anomalyco/opencode` image (now archived) was Alpine-based
 
 ## Quick Start
 
+**Just want to run it?** No git clone needed — grab the two template files:
+
+```bash
+mkdir -p ~/opencode-devbox && cd ~/opencode-devbox
+
+# Pull docker-compose.yml and the .env template
+curl -O https://gitea.jordbo.se/joakimp/opencode-devbox/raw/branch/main/docker-compose.yml
+curl -fsSL https://gitea.jordbo.se/joakimp/opencode-devbox/raw/branch/main/.env.example -o .env
+
+# Edit .env — at minimum: OPENCODE_PROVIDER, the matching API key,
+# WORKSPACE_PATH, GIT_USER_NAME, GIT_USER_EMAIL.
+$EDITOR .env
+
+# Pull and run
+docker compose run --rm devbox
+```
+
+This pulls `joakimp/opencode-devbox:latest` from Docker Hub, mounts `WORKSPACE_PATH` at `/workspace`, and drops you straight into opencode. Use `bash` instead of (no command) to land in a shell first — useful for `aws sso login`, `pi`, `omos`, etc.
+
+**Want to hack on the image itself, follow upstream changes, or rebuild from source?** Clone the repo:
+
 ```bash
-# Clone
 git clone ssh://gitea.jordbo.se:2222/joakimp/opencode-devbox.git
 cd opencode-devbox
 
@@ -17,7 +37,7 @@ cd opencode-devbox
 cp .env.example .env
 # Edit .env with your provider, API key, workspace path, git config
 
-# Install git hooks (secret scanning)
+# Install git hooks (secret scanning) before committing
 brew install gitleaks  # macOS / Linuxbrew
 ./setup-hooks.sh
 
diff --git a/scripts/generate-dockerhub-md.py b/scripts/generate-dockerhub-md.py
index 49af6bc..aaad3d2 100755
--- a/scripts/generate-dockerhub-md.py
+++ b/scripts/generate-dockerhub-md.py
@@ -71,6 +71,21 @@ All variants support `linux/amd64` and `linux/arm64`.
 
 ## Quick Start
 
+For a fully-configured environment with persistent state (opencode config, mempalace memory, neovim plugins, bash history) surviving container recreation, use docker-compose. **You don't need to clone the repo** — just grab two template files:
+
+```bash
+mkdir -p ~/opencode-devbox && cd ~/opencode-devbox
+curl -O https://gitea.jordbo.se/joakimp/opencode-devbox/raw/branch/main/docker-compose.yml
+curl -fsSL https://gitea.jordbo.se/joakimp/opencode-devbox/raw/branch/main/.env.example -o .env
+# Edit .env — set OPENCODE_PROVIDER, the matching API key,
+# WORKSPACE_PATH, GIT_USER_NAME, GIT_USER_EMAIL.
+docker compose run --rm devbox
+```
+
+This drops you straight into opencode with your project mounted at `/workspace`. Use `bash` as the command (e.g. `docker compose run --rm devbox bash`) to land in a shell first — useful for `aws sso login`, `pi` (on `*-with-pi` variants), or multi-harness workflows.
+
+**One-shot run, no persistence:**
+
 ```bash
 docker run -it --rm \\
   -e ANTHROPIC_API_KEY=your-key \\
@@ -82,22 +97,7 @@ docker run -it --rm \\
   joakimp/opencode-devbox:latest
 ```
 
-Drops you straight into opencode with your project mounted at `/workspace`.
-
-For an interactive shell first (useful for AWS SSO login, multi-harness workflows, or just `bash`):
-
-```bash
-docker run -it --rm \\
-  -e ANTHROPIC_API_KEY=your-key \\
-  -e OPENCODE_PROVIDER=anthropic \\
-  -v ~/projects:/workspace \\
-  -v ~/.ssh:/home/developer/.ssh:ro \\
-  joakimp/opencode-devbox:latest bash
-```
-
-Then run `opencode`, `pi` (on `*-with-pi` variants), or `aws sso login` from the shell.
-
-For docker-compose users, the source repo provides `docker-compose.yml`, `.env.example`, and a one-liner `docker compose up -d` workflow with named volumes pre-wired.
+Full setup guide — authentication for each provider (Anthropic, OpenAI, Bedrock SSO + static), persistence model, build args, troubleshooting: <{GITEA}#readme>
 
 ## What's Inside