diff --git a/Dockerfile b/Dockerfile
index 6b8157d..23399a6 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -1,7 +1,7 @@
 # =====================================================================
 # Stage 1: Build the Astro static site
 # =====================================================================
-FROM node:20-alpine AS builder
+FROM node:22-alpine AS builder
 
 WORKDIR /app
 
diff --git a/docs/ci-setup.md b/docs/ci-setup.md
index 023593e..770f1b5 100644
--- a/docs/ci-setup.md
+++ b/docs/ci-setup.md
@@ -73,6 +73,20 @@ curl -sS -X POST \
 A 2xx response = the panel accepted the trigger. The service will start
 rebuilding/redploying in the EasyPanel dashboard.
 
+## Common failure: "No start command could be found" (nixpacks)
+
+Astro builds to static files in `dist/` — there is no Node server to run.
+Nixpacks tries to find a `start` command and fails. The Dockerfile in
+this repo handles this with a two-stage build (node:22-alpine build +
+nginx:1.27-alpine serve).
+
+## Common failure: "Node.js v20.x is not supported by Astro"
+
+Astro 6 requires Node `>=22.12.0`. The Dockerfile uses `node:22-alpine`.
+If you see this error, the panel is probably reading a stale `node:20`
+cached image. Push an empty commit to force a rebuild, or clear the
+panel's image cache from the EasyPanel UI.
+
 ## Common failure: "Failed to sync changes" (HTTP 500)
 
 This is a **server-side** error, not a payload problem. It usually means: