diff --git a/BUILD.md b/BUILD.md
index 63061da..8594d57 100644
--- a/BUILD.md
+++ b/BUILD.md
@@ -13,14 +13,14 @@ cloudron build \
   --set-build-service builder.docker.due.ren \
   --build-service-token e3265de06b1d0e7bb38400539012a8433a74c2c96a17955e \
   --set-repository andreasdueren/affine-cloudron \
-  --tag 0.25.5-1
+  --tag 0.25.5-2
 ```
 
 ## Deployment Steps
 1. Remove any previous dev install of AFFiNE on the Cloudron (always reinstall from scratch).
 2. Install the freshly built image:
    ```bash
-cloudron install --location affine.due.ren --image andreasdueren/affine-cloudron:0.25.5-1
+cloudron install --location affine.due.ren --image andreasdueren/affine-cloudron:0.25.5-2
    ```
 3. When prompted, confirm the app info and wait for Cloudron to report success (abort after ~30 seconds if installation stalls or errors to avoid hanging sessions).
 4. Visit `https://affine.due.ren` (or the chosen location) and sign in using Cloudron SSO.
@@ -49,3 +49,4 @@ cloudron install --location affine.due.ren --image andreasdueren/affine-cloudron
   - `AFFINE_COPILOT_GEMINI_API_KEY`, `AFFINE_COPILOT_GEMINI_BASE_URL`
   - `AFFINE_COPILOT_EXA_KEY` for web search
   - `AFFINE_COPILOT_SCENARIOS_JSON` with a JSON payload such as `{"override_enabled":true,"scenarios":{"chat":"gpt-4o-mini"}}`
+- A sample `.env` file is available at `/app/data/copilot.env.example` after install; download/edit it for reference before populating Cloudron env variables.
diff --git a/CloudronManifest.json b/CloudronManifest.json
index ec9017d..883fe8b 100644
--- a/CloudronManifest.json
+++ b/CloudronManifest.json
@@ -5,9 +5,9 @@
   "description": "Next-gen knowledge base that blends docs, whiteboards, and databases for self-hosted teams.",
   "website": "https://affine.pro",
   "contactEmail": "support@affine.pro",
-  "version": "0.25.5-1",
+  "version": "0.25.5-2",
   "upstreamVersion": "0.25.5",
-  "changelog": "Allow copilot configuration via env vars",
+  "changelog": "Add copilot.env.example sample and env overrides",
   "icon": "file://icon.png",
   "manifestVersion": 2,
   "minBoxVersion": "7.0.0",
diff --git a/Dockerfile b/Dockerfile
index 629ddc0..f84fea2 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -42,6 +42,7 @@ COPY run-buddy.sh "$APP_CODE_DIR/run-buddy.sh"
 COPY nginx.conf "$APP_CODE_DIR/nginx.conf"
 COPY supervisord.conf "$APP_CODE_DIR/supervisord.conf"
 COPY config.example.json "$APP_CODE_DIR/config.example.json"
+COPY copilot.env.example "$APP_CODE_DIR/copilot.env.example"
 COPY tmp_data/ "$APP_TMP_DIR/"
 COPY manticore/ "$APP_CODE_DIR/manticore/"
 
diff --git a/copilot.env.example b/copilot.env.example
new file mode 100644
index 0000000..89d4f4e
--- /dev/null
+++ b/copilot.env.example
@@ -0,0 +1,24 @@
+# AFFiNE Copilot sample environment overrides
+# Copy this file to .env (or use Cloudron's env UI) and adjust values.
+
+# Toggle Copilot globally (true/false).
+AFFINE_COPILOT_ENABLED=true
+
+# OpenAI-compatible provider (Official OpenAI, OpenRouter, local proxy, etc.).
+AFFINE_COPILOT_OPENAI_API_KEY=sk-your-openai-key
+AFFINE_COPILOT_OPENAI_BASE_URL=https://api.openai.com/v1
+
+# Anthropic Claude provider.
+AFFINE_COPILOT_ANTHROPIC_API_KEY=sk-ant-your-key
+AFFINE_COPILOT_ANTHROPIC_BASE_URL=https://api.anthropic.com/v1
+
+# Google Gemini provider (API key or reverse proxy).
+AFFINE_COPILOT_GEMINI_API_KEY=your-gemini-key
+AFFINE_COPILOT_GEMINI_BASE_URL=https://generativelanguage.googleapis.com/v1beta
+
+# Optional Exa web search key for Copilot browsing.
+AFFINE_COPILOT_EXA_KEY=exa-key
+
+# Override the scenario/model mapping by providing JSON.
+# Example keeps override_enabled true and customizes a few models.
+AFFINE_COPILOT_SCENARIOS_JSON={"override_enabled":true,"scenarios":{"chat":"gpt-4o-mini","coding":"claude-3-5-sonnet-20241022","embedding":"text-embedding-3-large","quick_text_generation":"gpt-4o-mini"}}
diff --git a/start.sh b/start.sh
index e717cfb..e5e61a3 100644
--- a/start.sh
+++ b/start.sh
@@ -46,6 +46,13 @@ prepare_data_dirs() {
     cp "$APP_TMP_DIR/config/config.json" "$APP_DATA_DIR/config/config.json"
   fi
 
+  local sample_env_src="$APP_CODE_DIR/copilot.env.example"
+  local sample_env_dest="$APP_DATA_DIR/copilot.env.example"
+  if [ -f "$sample_env_src" ] && [ ! -f "$sample_env_dest" ]; then
+    cp "$sample_env_src" "$sample_env_dest"
+    chown cloudron:cloudron "$sample_env_dest"
+  fi
+
   local storage_contents=""
   if [ -d "$APP_DATA_DIR/storage" ]; then
     storage_contents=$(ls -A "$APP_DATA_DIR/storage" 2>/dev/null || true)