diff --git a/.github/workflows/docker-build.yml b/.github/workflows/docker-build.yml
index e1b71c9..f520216 100644
--- a/.github/workflows/docker-build.yml
+++ b/.github/workflows/docker-build.yml
@@ -3,6 +3,7 @@ name: Build & Push Docker Image
 on:
   push:
     branches: [ "main", "dev" ]
+    tags: [ "v*" ]
 
 jobs:
   build:
@@ -16,10 +17,18 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v4
 
-      - name: Set variables (safe + lowercase)
+      - name: Set variables (safe + lowercase + tag/branch aware)
         run: |
           REPO="${GITHUB_REPOSITORY,,}"
-          TAG="${GITHUB_REF_NAME}"
+
+          # detect tag vs branch
+          if [[ "${GITHUB_REF_TYPE}" == "tag" ]]; then
+            TAG="${GITHUB_REF_NAME}"
+          else
+            TAG="${GITHUB_REF_NAME}"
+          fi
+
+          # lowercase safety
           TAG=$(echo "$TAG" | tr '[:upper:]' '[:lower:]')
 
           echo "REPO=$REPO" >> $GITHUB_ENV
@@ -29,6 +38,7 @@ jobs:
         run: |
           echo "Repo: $REPO"
           echo "Tag: $TAG"
+          echo "Ref type: $GITHUB_REF_TYPE"
 
       - name: Login to GHCR
         run: echo "${{ secrets.GITHUB_TOKEN }}" | docker login ghcr.io -u ${{ github.actor }} --password-stdin
diff --git a/README.md b/README.md
index 5771cbe..b95d2d3 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,39 @@
-# project_template_ghcr
-This is a simple project template for utilizing ghcr on first pull.
+# 🚀 GitHub Actions Docker Template
+
+A lightweight DevOps starter template for containerized services using GitHub Actions, Docker, and GitHub Container Registry (GHCR).
+
+This template is designed to eliminate manual server builds and provide a fully automated CI/CD pipeline for modern service deployment.
+
+---
+
+## 🧱 Features
+
+- ⚡ Automated CI/CD via GitHub Actions
+- 🐳 Docker-based deployment
+- 📦 Container publishing to GitHub Container Registry (GHCR)
+- 🌿 Branch-based environments (`dev`, `latest-stable`)
+- 🔁 Automatic image tagging based on branch name
+- 🖥️ Server-only runtime (no build required on host)
+- ♻️ Fully reusable template for multiple services
+
+---
+
+## 🌿 Branch Strategy
+
+| Branch          | Purpose            | Image Tag        |
+|----------------|--------------------|------------------|
+| `dev`           | Development        | `dev`            |
+| `main`          | Stable production  | `main`           |
+| `v*` (tags)     | Releases           | `v1.0.0`, etc.   |
+
+---
+
+## 🚀 How to Use This Template
+
+1. Click **"Use this template"** on GitHub
+2. Create a new repository
+3. Clone your new repo:
+
+```bash id="clone1"
+git clone https://github.com/TheMux-42/github-actions-docker-template.git
+cd github-actions-docker-template