diff --git a/.env.example b/.env.example
index 26fd203..b6f1501 100644
--- a/.env.example
+++ b/.env.example
@@ -15,7 +15,12 @@ POSTGRES_PORT=5432
 # REQUIRED: Public URL the backend should advertise in generated instructions/webhook flows.
 # Update this when the backend is served behind a reverse proxy, custom host, or non-default port.
 BASE_URL=http://localhost:8000
-# For remote access, set this to your UI origin (e.g. http://<server-ip>:3000 or https://mc.example.com).
+# Origins the browser is allowed to call the API from.
+# Must match the URL you open Pipeline on in your browser — not the Forgejo URL.
+# For local dev: http://localhost:3000
+# For a deployed instance: https://pipeline.example.com
+# Multiple origins: comma-separated — e.g. https://pipeline.example.com,http://localhost:3000
+# Leave blank to disable CORS headers (only safe when frontend and backend share the same origin).
 CORS_ORIGINS=http://localhost:3000
 DB_AUTO_MIGRATE=true
 LOG_LEVEL=INFO
diff --git a/backend/.env.example b/backend/.env.example
index 355afc4..d688149 100644
--- a/backend/.env.example
+++ b/backend/.env.example
@@ -5,7 +5,12 @@ LOG_USE_UTC=false
 REQUEST_LOG_SLOW_MS=1000
 REQUEST_LOG_INCLUDE_HEALTH=false
 DATABASE_URL=postgresql+psycopg://postgres:postgres@localhost:5432/pipeline
-# For remote access, set this to your UI origin (e.g. http://<server-ip>:3000 or https://mc.example.com).
+# Origins the browser is allowed to call the API from.
+# Must match the URL you open Pipeline on in your browser — not the Forgejo URL.
+# For local dev: http://localhost:3000
+# For a deployed instance: https://pipeline.example.com
+# Multiple origins: comma-separated — e.g. https://pipeline.example.com,http://localhost:3000
+# Leave blank to disable CORS headers (only safe when frontend and backend share the same origin).
 CORS_ORIGINS=http://localhost:3000
 # REQUIRED for gateway provisioning/agent heartbeats. Must be reachable by gateway runtime.
 BASE_URL=
diff --git a/frontend/src/components/git/ForgejoConnectionForm.tsx b/frontend/src/components/git/ForgejoConnectionForm.tsx
index 0a43505..531072c 100644
--- a/frontend/src/components/git/ForgejoConnectionForm.tsx
+++ b/frontend/src/components/git/ForgejoConnectionForm.tsx
@@ -80,8 +80,16 @@ export function ForgejoConnectionForm({
 
         {error && (
           <div className="rounded-xl border border-[color:rgba(248,113,113,0.35)] bg-[color:rgba(248,113,113,0.08)] p-4 text-[color:var(--danger)]">
-            <p className="font-medium">Configuration Error</p>
-            <p className="text-sm">{error}</p>
+            <p className="font-medium">
+              {error === "Failed to fetch"
+                ? "Could not reach Pipeline backend"
+                : "Error"}
+            </p>
+            <p className="text-sm">
+              {error === "Failed to fetch"
+                ? "Pipeline could not connect to its own API. Check that NEXT_PUBLIC_API_URL points to your backend and that your frontend origin is listed in CORS_ORIGINS."
+                : error}
+            </p>
           </div>
         )}