diff --git a/.gitea/workflows/cd.yml b/.gitea/workflows/cd.yml
index 519443a..900875e 100644
--- a/.gitea/workflows/cd.yml
+++ b/.gitea/workflows/cd.yml
@@ -4,6 +4,10 @@ name: CD
   push:
     branches: [main]
     tags: ["v*"]
+    # Docs-only pushes don't change the image — skip the build/deploy roll.
+    # (Only applies to branch pushes; tag pushes always trigger.)
+    paths-ignore:
+      - 'docs/**'
 
 env:
   IMAGE: gitea-mcp
diff --git a/HOW_GITEA_MCP_WORKS.md b/docs/HOW_GITEA_MCP_WORKS.md
similarity index 100%
rename from HOW_GITEA_MCP_WORKS.md
rename to docs/HOW_GITEA_MCP_WORKS.md