From 3380cdebb48d986b7e22e8c1b86c69f5961683d5 Mon Sep 17 00:00:00 2001
From: "Viktor H. Ingre" <viktor.ingre@codeoof.com>
Date: Mon, 8 Dec 2025 08:10:29 +0100
Subject: [PATCH 1/8] docs: update documentation for clarity and remove
 duplicates

- Rewrote QUICKSTART.md: Focused on 5-min setup with Option A/B, removed outdated content
- Updated SETUP_GUIDE.md: Added references to QUICKSTART, removed duplicates, expanded detail
- Completely rewrote QUICK_REFERENCE.md: Removed setup instructions, focused on daily usage for established projects
- Updated SUMMARY.md: Reorganized with docs guide at top, removed top-level files from template structure
- Added LICENSE to docs/git-auto-release/ for template clarity
- Updated all cross-references: QUICKSTART (setup), QUICK_REFERENCE (daily use), clear separation
- Added LICENSE reference to docs README

Changes ensure clear distinction between:
- Initial setup (QUICKSTART)
- Daily usage (QUICK_REFERENCE)
- No duplicate content across documentation
---
 docs/git-auto-release/LICENSE              |  21 +
 docs/git-auto-release/PROJECT_STRUCTURE.md |  41 +-
 docs/git-auto-release/QUICKSTART.md        | 302 ++++-------
 docs/git-auto-release/QUICK_REFERENCE.md   | 561 ++++++++++++---------
 docs/git-auto-release/README.md            |  14 +-
 docs/git-auto-release/SETUP_GUIDE.md       | 293 ++++++-----
 docs/git-auto-release/SUMMARY.md           | 344 ++++---------
 7 files changed, 725 insertions(+), 851 deletions(-)
 create mode 100644 docs/git-auto-release/LICENSE

diff --git a/docs/git-auto-release/LICENSE b/docs/git-auto-release/LICENSE
new file mode 100644
index 0000000..7bd7afe
--- /dev/null
+++ b/docs/git-auto-release/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 CodeOOf
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/docs/git-auto-release/PROJECT_STRUCTURE.md b/docs/git-auto-release/PROJECT_STRUCTURE.md
index aa248e5..0b13209 100644
--- a/docs/git-auto-release/PROJECT_STRUCTURE.md
+++ b/docs/git-auto-release/PROJECT_STRUCTURE.md
@@ -10,7 +10,7 @@ Git-Auto-Release/
 │   ├── SETUP_GUIDE.md            # Complete setup instructions
 │   ├── WORKFLOW_EXAMPLES.md      # Real-world usage examples
 │   ├── CUSTOMIZATION.md          # How to customize the template
-│   └── QUICK_REFERENCE.md        # Fast command reference
+│   └── QUICK_REFERENCE.md        # Daily usage cheat sheet
 ├── BRANCH_STRATEGY.md            # Detailed branch strategy
 ├── LICENSE                       # MIT License
 ├── README.md                     # Main project documentation
@@ -123,13 +123,15 @@ Git-Auto-Release/
   - Branch strategy adjustments
 
 #### `QUICK_REFERENCE.md`
-- **Purpose**: Fast command reference
+- **Purpose**: Daily usage command cheat sheet (for established projects)
 - **Contents**:
-  - Common commands
+  - Decision tree for daily tasks
+  - Workflow commands (feature, bugfix, hotfix, release)
   - Version progression tables
-  - Commit message formats
-  - Troubleshooting commands
-  - Quick links
+  - Commit message examples
+  - Git command reference
+  - Troubleshooting quick fixes
+- **Note**: For initial setup, see `QUICKSTART.md`
 
 ---
 
@@ -193,10 +195,11 @@ README.md (overview)
     ├── Quick start
     ├── → BRANCH_STRATEGY.md (detailed strategy)
     └── → docs/
-        ├── SETUP_GUIDE.md (how to set up)
-        ├── WORKFLOW_EXAMPLES.md (how to use)
-        ├── CUSTOMIZATION.md (how to customize)
-        └── QUICK_REFERENCE.md (fast reference)
+        ├── QUICKSTART.md (initial setup)
+        ├── SETUP_GUIDE.md (detailed configuration)
+        ├── WORKFLOW_EXAMPLES.md (step-by-step scenarios)
+        ├── CUSTOMIZATION.md (advanced customization)
+        └── QUICK_REFERENCE.md (daily usage cheat sheet)
 ```
 
 ---
@@ -206,16 +209,17 @@ README.md (overview)
 ### For Template Users
 
 1. **Read**: `README.md` for overview
-2. **Follow**: `docs/SETUP_GUIDE.md` for setup
-3. **Reference**: `docs/QUICK_REFERENCE.md` for daily use
-4. **Customize**: `.github/workflows/ci-cd-versioned.yml`
+2. **Setup**: `docs/QUICKSTART.md` for fast initial setup (5 min)
+3. **Configure**: `docs/SETUP_GUIDE.md` for detailed configuration
+4. **Daily Use**: `docs/QUICK_REFERENCE.md` for commands and workflows
+5. **Customize**: `.github/workflows/ci-cd-versioned.yml` as needed
 
 ### For Contributors
 
 1. **Read**: `CONTRIBUTING.md`
 2. **Reference**: `BRANCH_STRATEGY.md`
 3. **Follow**: Commit conventions
-4. **Use**: `docs/QUICK_REFERENCE.md` for commands
+4. **Use**: `docs/QUICK_REFERENCE.md` for daily commands
 
 ### For Maintainers
 
@@ -296,10 +300,11 @@ README.md (overview)
 
 ## Quick Navigation
 
-- **Getting Started**: [README.md](../README.md)
-- **Setup**: [docs/SETUP_GUIDE.md](SETUP_GUIDE.md)
-- **Customization**: [docs/CUSTOMIZATION.md](CUSTOMIZATION.md)
-- **Quick Reference**: [docs/QUICK_REFERENCE.md](QUICK_REFERENCE.md)
+- **Getting Started**: [README.md](README.md)
+- **Fast Setup**: [docs/QUICKSTART.md](QUICKSTART.md) - 5 minute setup
+- **Detailed Setup**: [docs/SETUP_GUIDE.md](SETUP_GUIDE.md) - Full configuration
+- **Daily Usage**: [docs/QUICK_REFERENCE.md](QUICK_REFERENCE.md) - Command cheat sheet
+- **Customization**: [docs/CUSTOMIZATION.md](CUSTOMIZATION.md) - Advanced topics
 
 ---
 
diff --git a/docs/git-auto-release/QUICKSTART.md b/docs/git-auto-release/QUICKSTART.md
index 55dbe8c..4b6b239 100644
--- a/docs/git-auto-release/QUICKSTART.md
+++ b/docs/git-auto-release/QUICKSTART.md
@@ -1,286 +1,174 @@
 # 🚀 Quick Start - Git Auto Release
 
-📖 **Navigation**: [← README](README.md) | **Quick Start** | [Setup Guide →](docs/SETUP_GUIDE.md)
+📖 **Navigation**: [← README](README.md) | **Quick Start** | [Setup Guide →](SETUP_GUIDE.md)
 
-Get up and running with automated versioning in under 10 minutes!
+Get automated versioning running in **under 5 minutes**!
 
 ---
 
 ## Step 1: Get the Template (1 min)
 
-### Option A: Use Template on GitHub
-1. Click **"Use this template"** button
+### Option A: Use Template on GitHub (Recommended)
+
+1. Click **"Use this template"** on GitHub
 2. Name your repository
-3. Click **"Create repository from template"**
-4. Clone your new repo
+3. Create repository
+4. Clone it:
 
-### Option B: Clone Directly
 ```bash
-git clone https://github.com/CodeOOf/Git-Auto-Release.git my-project
-cd my-project
-rm -rf .git
-git init
+git clone https://github.com/YOUR_USERNAME/YOUR_REPO.git
+cd YOUR_REPO
 ```
 
----
-
-## Step 2: Make It Your Own (2 min)
-
-### Reorganize Documentation
+### Option B: Clone and Customize
 
 ```bash
-# Create the template documentation folder
-mkdir -p docs/git-auto-release
-
-# Move all template documentation
-mv README.md docs/git-auto-release/
-mv QUICKSTART.md docs/git-auto-release/
-mv BRANCH_STRATEGY.md docs/git-auto-release/
-mv CONTRIBUTING.md docs/git-auto-release/
-
-# Use the project README template
-mv README.template.md README.md
-
-# Note: Keep docs/SETUP_GUIDE.md, docs/WORKFLOW_EXAMPLES.md, etc. in docs/git-auto-release/
-# They are already referenced correctly
-```
-
-### Update Your README
-
-Edit `README.md` with your project details:
-- Project name and description
-- Setup instructions
-- Documentation links
-
-**The template documentation is now in `docs/git-auto-release/`** - you can keep it, move it, or delete it later.
-
----
+# Clone with your project name
+git clone https://github.com/CodeOOf/Git-Auto-Release.git my-project
+cd my-project
 
-## Step 3: Configure Initial Version (1 min)
+# Remove Git history
+rm -rf .git
 
-```bash
-# Set your starting version
+# Set initial version
 echo "0.1.0" > VERSION
-git add VERSION
-git commit -m "chore: set initial version"
-```
 
----
+# Replace template files with your own
+rm README.md CONTRIBUTING.md
+mv README.template.md README.md
+mv CONTRIBUTING.template.md CONTRIBUTING.md
 
-## Step 3: Create Required Branches (2 min)
+# Edit README.md and CONTRIBUTING.md with your project details
 
-```bash
-# Create and push main branch
-git branch -M main
+# Initialize new Git repo
+git init
+git checkout -b main
+git add .
+git commit -m "chore: initialize project from Git-Auto-Release template"
+
+# Add your remote and push
 git remote add origin https://github.com/YOUR_USERNAME/YOUR_REPO.git
 git push -u origin main
 
-# Create and push release branch
+# Create release branch
 git checkout -b release
 git push -u origin release
-
-# Go back to main for development
 git checkout main
 ```
 
-**Note**: Alpha and beta branches are created as needed for major releases. Feature branches are created from main.
-
 ---
 
-## Step 4: Set Up Branch Protection (3 min)
+## Step 2: Branch Protection (2 min)
 
-Go to **GitHub → Your Repo → Settings → Branches**:
+**GitHub → Settings → Branches → Add rule:**
 
-### Protect `main` branch:
-1. Click **"Add branch protection rule"**
-2. Branch name: `main`
-3. Check ✅ **Require pull request before merging**
-4. Set **1** required approval
-5. Check ✅ **Require status checks to pass**
-6. Click **"Create"**
+**`main` branch:**
+- ✅ Require pull request
+- ✅ Require 1 approval
+- ✅ Require status checks
 
-### Protect `release` branch:
-1. Click **"Add branch protection rule"** again
-2. Branch name: `release`
-3. Check ✅ **Require pull request before merging**
-4. Set **2** required approvals
-5. Click **"Create"**
+**`release` branch:**
+- ✅ Require pull request  
+- ✅ Require 2 approvals
 
 ---
 
-## Step 5: Test Your Setup (3 min)
+## Step 3: Test It (2 min)
 
 ```bash
-# Create a test feature from main
-git checkout main
-git pull origin main
+# Create feature
 git checkout -b feature/test-automation
-
-# Make a change
-echo "# Test Feature" > test.md
+echo "# Test" > test.md
 git add test.md
-git commit -m "feat(test): verify automated versioning works"
-
-# Push and create PR
+git commit -m "feat: add test feature"
 git push origin feature/test-automation
 ```
 
 **On GitHub:**
-1. Go to **Pull Requests** tab
-2. Click **"New pull request"**
-3. Base: `main` ← Compare: `feature/test-automation`
-4. Create PR
-5. Wait for checks to pass
-6. Merge!
-
----
-## Step 6: See the Magic! ✨
+- Create PR: `feature/test-automation` → `main`
+- Merge it
 
-### View Build Version
-Check the GitHub Actions logs - you'll see version like `v0.1.0+abc123`
+**Result:**
+- VERSION updates to `0.2.0-beta`
+- Tag `v0.2.0-beta` created automatically
 
-### Check Your First Tag
-After the merge to main completes:
 ```bash
-git fetch --tags
-git tag -l
-# You should see: v0.2.0-beta
-```
-
----
-
-## 🎉 Done! You're Ready!
-
-### What You've Accomplished:
-- ✅ Set up automated versioning
-- ✅ Created proper branch structure
-- ✅ Configured branch protection
-- ✅ Tested the workflow
-- ✅ Created your first version tag
-
-### Next Steps:
-
-**For Daily Development:**
-```bash
-# Create features from main
+# Verify
 git checkout main
-git pull origin main
-git checkout -b feature/my-feature
-git commit -m "feat(module): add feature"
-# PR to main → merge → auto-tag (v0.X.0-beta)
-
-# Release features to production
-# PR: main → release → auto-tag (v0.X.0) + GitHub Release
+git pull
+cat VERSION        # Shows: 0.2.0-beta
+git tag -l         # Shows: v0.2.0-beta
 ```
 
 ---
 
-## Next Steps
+## 🎉 Done! You're Automated!
 
-- 📚 **Branch Strategy**: [`BRANCH_STRATEGY.md`](BRANCH_STRATEGY.md)
-- 📋 **Workflow Examples**: [`WORKFLOW_EXAMPLES.md`](WORKFLOW_EXAMPLES.md)
-- ⚡ **Quick Reference**: [`QUICK_REFERENCE.md`](QUICK_REFERENCE.md)
-- 🎨 **Customization**: [`CUSTOMIZATION.md`](CUSTOMIZATION.md)
+### What Happens Automatically:
+
+| Action | Result |
+|--------|--------|
+| `feature/*` → `main` | MINOR bump: `v0.2.0-beta` |
+| `bugfix/*` → `main` | PATCH bump: `v0.1.1-beta` |
+| `main` → `release` | Release: `v0.2.0` + GitHub Release |
 
 ---
 
-## Common First Tasks
+## Daily Usage
 
-### Add a Feature
+### Add Feature
 ```bash
-git checkout main
-git pull origin main
-git checkout -b feature/user-login
-# ... develop ...
-git commit -m "feat(auth): add user login"
-git push origin feature/user-login
-# Create PR to main
+git checkout main && git pull
+git checkout -b feature/my-feature
+# ... code ...
+git commit -m "feat(scope): description"
+git push origin feature/my-feature
+# Create PR → main → merge → auto-tagged!
 ```
 
-### Fix a Bug
+### Fix Bug
 ```bash
-git checkout main
-git pull origin main
-git checkout -b bugfix/fix-validation
-# ... fix bug ...
-git commit -m "fix(validation): handle empty input"
-git push origin bugfix/fix-validation
-# Create PR to main
+git checkout main && git pull
+git checkout -b bugfix/fix-issue
+# ... fix ...
+git commit -m "fix(scope): description"
+git push origin bugfix/fix-issue
+# Create PR → main → merge → auto-tagged!
 ```
 
-### Make a Production Release
+### Release Production
 ```bash
-# 1. Develop features on feature/* branches from main
-# 2. Merge features to main (creates v0.X.0-beta tags)
-# 3. Test on staging
-# 4. PR: main → release (creates v0.X.0 tag + GitHub Release)
+# Create PR: main → release
+# Merge → Creates v0.2.0 tag + GitHub Release
 ```
 
 ---
 
-## Customization (Optional)
-
-### For Node.js Projects
-Edit `.github/workflows/ci-cd-versioned.yml`:
-```yaml
-- name: Setup Node
-  uses: actions/setup-node@v4
-  with:
-    node-version: '20'
-    
-- name: Install
-  run: npm ci
-  
-- name: Build
-  run: npm run build
-  
-- name: Test
-  run: npm test
-```
-
-### For Python Projects
-```yaml
-- name: Setup Python
-  uses: actions/setup-python@v5
-  with:
-    python-version: '3.11'
-    
-- name: Install
-  run: pip install -r requirements.txt
-  
-- name: Test
-  run: pytest
-```
+## Commit Format
 
-See [`docs/CUSTOMIZATION.md`](docs/CUSTOMIZATION.md) for more languages!
+Use [Conventional Commits](https://www.conventionalcommits.org/):
 
----
-
-## Need Help?
+```
+<type>: <description>
+```
 
-- 📚 **Read the docs**: [`docs/`](docs/) folder
-- ❓ **FAQ**: [`README.md#faq`](README.md#-faq)
-- 🐛 **Issues**: [GitHub Issues](https://github.com/CodeOOf/Git-Auto-Release/issues)
-- 💬 **Discussions**: [GitHub Discussions](https://github.com/CodeOOf/Git-Auto-Release/discussions)
+**Types:**
+- `feat:` - New feature (MINOR bump)
+- `fix:` - Bug fix (PATCH bump)
+- `docs:` - Documentation
+- `chore:` - Maintenance
+- `test:` - Tests
 
 ---
 
-## Version Progression Cheat Sheet
-
-| Action | Version Change | Example |
-|--------|---------------|---------|  
-| Feature merged | 0.1.0 → 0.2.0-beta | feature/* → main |
-| Bug merged | 0.1.0 → 0.1.1-beta | bugfix/* → main |
-| Release to prod | 0.2.0-beta → 0.2.0 | main → release |
-| Hotfix | 1.0.0 → 1.0.1 | hotfix → release |
-| Major release | 0.9.0 → 1.0.0-alpha | alpha → main |
-
----
+## Next Steps
 
-**That's it! Start automating your releases! 🚀**
+- 📚 [Branch Strategy](BRANCH_STRATEGY.md) - Detailed branching model
+- ⚡ [Quick Reference](QUICK_REFERENCE.md) - Daily workflow commands (after setup)
+- 🎨 [Customization](CUSTOMIZATION.md) - Adapt to your stack
+- 📋 [Workflow Examples](WORKFLOW_EXAMPLES.md) - Real scenarios
 
 ---
 
-**Time to First Tag**: < 10 minutes  
-**Time to Production Release**: < 30 minutes  
-**Maintenance Time**: Zero - it's all automated! ✨
+**⏱️ Time to First Tag**: ~5 minutes  
+**🔄 Maintenance**: Zero - fully automated! ✨
diff --git a/docs/git-auto-release/QUICK_REFERENCE.md b/docs/git-auto-release/QUICK_REFERENCE.md
index f69a050..0118f4b 100644
--- a/docs/git-auto-release/QUICK_REFERENCE.md
+++ b/docs/git-auto-release/QUICK_REFERENCE.md
@@ -1,33 +1,34 @@
 # Quick Reference Guide
 
-📖 **Navigation**: [← README](../README.md) | [Customization Guide](CUSTOMIZATION.md) | **Quick Reference**
+📖 **Navigation**: [← README](README.md) | [Quickstart](QUICKSTART.md) | **Quick Reference**
 
-Fast reference for Git Auto Release commands and workflows.
+> **🎯 For initial setup**, see [QUICKSTART.md](QUICKSTART.md)  
+> **This guide is for daily usage** after Git-Auto-Release is established in your project.
 
 ---
 
-## 🚀 Quick Decision Guide
+## 🚀 Quick Decision Tree
 
-**Need help choosing the right workflow?** Use this flowchart:
+**What do you need to do today?**
 
 ```mermaid
 flowchart TD
-    Start{What do I need?}
+    Start{What's your task?}
     
     Feature[Add a feature]
     Bug[Fix a bug]
-    Breaking[Make breaking changes]
-    Emergency[Emergency production fix]
+    Breaking[Breaking change]
+    Emergency[Production emergency]
     
     Start --> Feature
     Start --> Bug
     Start --> Breaking
     Start --> Emergency
     
-    Feature -->|feature/* from main| FeatureFlow[feature/* → main → release<br/>MINOR version bump]
-    Bug -->|bugfix/* from main| BugFlow[bugfix/* → main → release<br/>PATCH version bump]
-    Breaking -->|alpha from main| BreakingFlow[alpha → main → release<br/>Optional: beta for testing<br/>MAJOR version bump]
-    Emergency -->|hotfix from release| EmergencyFlow[hotfix → release<br/>PATCH version bump<br/>Auto-syncs to all branches]
+    Feature -->|feature/* from main| FeatureFlow[Create feature/* branch<br/>Commit with feat:<br/>PR to main → MINOR bump]
+    Bug -->|bugfix/* from main| BugFlow[Create bugfix/* branch<br/>Commit with fix:<br/>PR to main → PATCH bump]
+    Breaking -->|alpha from main| BreakingFlow[Work on alpha branch<br/>Commit with feat!:<br/>PR to main → MAJOR bump]
+    Emergency -->|hotfix from release| EmergencyFlow[Create hotfix branch<br/>Commit with fix:<br/>PR to release → PATCH bump]
     
     style Start fill:#3498db,color:#fff
     style Feature fill:#2ecc71,color:#fff
@@ -36,380 +37,436 @@ flowchart TD
     style Emergency fill:#e74c3c,color:#fff
 ```
 
-### Quick Actions
-
-- **Adding a feature?** → See [Feature Development Workflow](WORKFLOW_EXAMPLES.md#1-feature-development)
-- **Fixing a bug?** → See [Bug Fix Workflow](WORKFLOW_EXAMPLES.md#2-bug-fixes)
-- **Making breaking changes?** → See [Branch Strategy: Alpha Branch](BRANCH_STRATEGY.md#alpha-branch-optional) and [Major Release Workflow](WORKFLOW_EXAMPLES.md#4-major-release-breaking-changes)
-- **Emergency production fix?** → See [Hotfix Workflow](WORKFLOW_EXAMPLES.md#7-hotfix-production-emergency)
+**Quick links to detailed workflows:**
+- 🎨 [Feature Development](WORKFLOW_EXAMPLES.md#1-feature-development)
+- 🐛 [Bug Fixes](WORKFLOW_EXAMPLES.md#2-bug-fixes)
+- 💥 [Breaking Changes](WORKFLOW_EXAMPLES.md#4-major-release-breaking-changes)
+- 🚨 [Hotfix Emergency](WORKFLOW_EXAMPLES.md#7-hotfix-production-emergency)
 
 ---
 
-## Common Commands
-
-### Initial Setup
+## 📋 Daily Workflow Commands
+---
 
-```bash
-# Clone template
-git clone https://github.com/CodeOOf/Git-Auto-Release.git my-project
-cd my-project
-
-# Set version
-echo "0.1.0" > VERSION
-
-# Create branches
-git checkout -b alpha
-git push -u origin main alpha
-git checkout -b release
-git push -u origin release
-```
+## 📋 Daily Workflow Commands
 
-### Feature Development
+### Feature Development (MINOR bump)
 
 ```bash
 # Start feature
 git checkout main
 git pull origin main
-git checkout -b feature/my-feature
+git checkout -b feature/my-awesome-feature
 
-# Commit
+# Work and commit (use conventional commits)
 git add .
-git commit -m "feat(module): add feature description"
+git commit -m "feat(module): add awesome feature"
 
-# Push and create PR
-git push origin feature/my-feature
-# Open PR: feature/my-feature → main
+# Push and create PR to main
+git push origin feature/my-awesome-feature
+# Create PR: feature/my-awesome-feature → main
 ```
 
-### Bug Fix
+**Result after merge**: `v0.2.0-beta` tag created, VERSION updated
+
+---
+
+### Bug Fix (PATCH bump)
 
 ```bash
 # Start bugfix
 git checkout main
-git checkout -b bugfix/123-fix-issue
+git pull origin main
+git checkout -b bugfix/fix-critical-issue
+
+# Work and commit
+git add .
+git commit -m "fix(module): resolve critical issue"
+
+# Push and create PR to main
+git push origin bugfix/fix-critical-issue
+# Create PR: bugfix/fix-critical-issue → main
+```
+
+**Result after merge**: `v0.1.1-beta` tag created, VERSION updated
+
+---
 
-# Commit
-git commit -m "fix(module): fix issue description"
+### Production Release
 
-# Push and create PR
-git push origin bugfix/123-fix-issue
-# Open PR: bugfix/123-fix-issue → main
+```bash
+# Release tested beta to production
+# Create PR: main → release
+
+# On GitHub:
+# 1. Create PR from main to release
+# 2. Get 2 approvals (review carefully!)
+# 3. Merge PR
 ```
 
-### Hotfix (Emergency)
+**Result after merge**: `v0.2.0` tag created, GitHub Release published, VERSION updated
+
+---
+
+### Hotfix Emergency (PATCH bump)
 
 ```bash
-# Start hotfix
+# Start hotfix from release
 git checkout release
 git pull origin release
 git checkout -b hotfix
 
-# Commit
-git commit -m "fix(critical): emergency fix"
+# Fix and commit
+git add .
+git commit -m "fix(critical): emergency production fix"
 
-# Push and create PR
+# Push and create PR to release
 git push origin hotfix
-# Open PR: hotfix → release
+# Create PR: hotfix → release
 ```
 
-### Major Release
+**Result after merge**: 
+- `v1.0.1` tag created and released
+- VERSION updated
+- Changes auto-sync to main and all active branches
 
-```bash
-# 1. Merge alpha → main
-# Creates tag: v1.0.0-alpha
+---
 
-# 2. Test on beta branch (auto-created)
-git checkout beta
-# Make fixes if needed
+---
 
-# 3. Merge beta → main
-# Creates tag: v1.0.0-beta
+## 📊 Version Progression Cheat Sheet
 
-# 4. Merge main → release
-# Creates tag: v1.0.0 (production)
-```
+### Standard Version Bumps
 
----
+| Merge Action | Current | Next Version | Tag Created | Notes |
+|--------------|---------|--------------|-------------|-------|
+| feature/* → main | 0.1.0 | 0.2.0-beta | v0.2.0-beta | MINOR bump |
+| bugfix/* → main | 0.1.0 | 0.1.1-beta | v0.1.1-beta | PATCH bump |
+| main → release | 1.0.0-beta | 1.0.0 | v1.0.0 | Production release |
+| hotfix → release | 1.0.0 | 1.0.1 | v1.0.1 | Emergency fix |
 
-## Version Progression
+### Major Release Progression
 
-| Action | Current | Next Version | Tag Created |
-|--------|---------|--------------|-------------|
-| Merge feature → main | 0.1.0 | 0.2.0-beta | v0.2.0-beta |
-| Merge bugfix → main | 0.1.0 | 0.1.1-beta | v0.1.1-beta |
-| Merge bugfix → main (during beta) | 1.0.0-beta | 1.0.0-beta.1 | v1.0.0-beta.1 |
-| Merge alpha → main | 0.9.0 | 1.0.0-alpha | v1.0.0-alpha |
-| Merge main → release | 1.0.0-beta | 1.0.0 | v1.0.0 |
-| Merge hotfix → release | 1.0.0 | 1.0.1 | v1.0.1 |
+| Step | Merge Action | Version Created | Tag | Branch Created |
+|------|--------------|-----------------|-----|----------------|
+| 1 | alpha → main | 1.0.0-alpha | v1.0.0-alpha | beta (auto) |
+| 2 | beta → main | 1.0.0-beta | v1.0.0-beta | - |
+| 3 | main → release | 1.0.0 | v1.0.0 | - |
 
----
+### Beta Refinement (During Major Release)
 
-## Build Versions (No Tags)
+| Merge Action | Current | Next Version | Tag Created |
+|--------------|---------|--------------|-------------|
+| bugfix/* → main | 1.0.0-beta | 1.0.0-beta.1 | v1.0.0-beta.1 |
+| bugfix/* → main | 1.0.0-beta.1 | 1.0.0-beta.2 | v1.0.0-beta.2 |
 
-| Branch | Push Version Example |
-|--------|---------------------|
-| alpha | v0.1.0+a3f2b1c8 |
-| beta | v1.0.0-alpha+7f82b432 |
-| feature/* | v0.1.0+c8d92a14 |
-| bugfix/* | v0.1.0+f14e2c91 |
-| hotfix | v1.0.0-hotfix.1 |
+### Build Versions (Development, No Tags)
+
+| Branch Type | Version Format | Example |
+|-------------|----------------|---------|
+| feature/* | base+commit | v0.1.0+c8d92a14 |
+| bugfix/* | base+commit | v0.1.0+f14e2c91 |
+| alpha | base+commit | v0.1.0+a3f2b1c8 |
+| hotfix | base-hotfix.N | v1.0.0-hotfix.1 |
+
+---
 
 ---
 
-## Commit Message Format
+## ✍️ Commit Message Format
 
 ```
-type(scope): description
+type(scope): short description
 
-[optional body]
+[optional body explaining what and why]
 
-[optional footer]
+[optional footer with breaking changes or issue refs]
 ```
 
-### Types
+### Commit Types Reference
 
-| Type | Description | Version Impact |
-|------|-------------|----------------|
-| `feat` | New feature | MINOR bump when merged to main |
-| `fix` | Bug fix | PATCH bump when merged to main |
-| `feat!` | Breaking change | MAJOR bump when merged to main |
-| `docs` | Documentation | No version bump |
-| `style` | Formatting | No version bump |
-| `refactor` | Code restructure | No version bump |
-| `test` | Tests | No version bump |
-| `chore` | Maintenance | No version bump |
+| Type | Use For | Example |
+|------|---------|---------|
+| `feat` | New features | `feat(auth): add OAuth2 support` |
+| `fix` | Bug fixes | `fix(api): handle null responses correctly` |
+| `feat!` | Breaking changes | `feat!(api): redesign REST endpoints to GraphQL` |
+| `docs` | Documentation only | `docs(readme): update installation instructions` |
+| `style` | Code formatting | `style(app): fix indentation in main.js` |
+| `refactor` | Code restructuring | `refactor(auth): simplify token validation` |
+| `perf` | Performance improvements | `perf(db): optimize query performance` |
+| `test` | Adding tests | `test(auth): add token validation tests` |
+| `chore` | Maintenance tasks | `chore(deps): update dependencies` |
 
-### Examples
+### More Examples
 
 ```bash
-feat(auth): add OAuth2 support
-fix(api): handle null responses
-feat!(api): redesign REST to GraphQL
-docs(readme): update installation steps
-test(auth): add token validation tests
-chore(deps): update dependencies
-```
+# Feature with details
+git commit -m "feat(dashboard): add user analytics chart
 
----
+- Added chart component with D3.js
+- Integrated with analytics API
+- Added date range selector"
 
-## Branch Protection Rules
+# Bug fix with issue reference
+git commit -m "fix(login): prevent duplicate submissions
 
-### `main` Branch
+Closes #123"
 
-- ✅ Require PR before merging
-- ✅ Require 1 approval
-- ✅ Require status checks: `Build & Test`, `Calculate Version`
-- ✅ Require conversation resolution
+# Breaking change with migration notes
+git commit -m "feat!(api)!: change authentication to JWT
 
-### `release` Branch
+BREAKING CHANGE: API now requires JWT tokens instead of API keys.
+Clients must update to use Authorization: Bearer <token> header."
+```
 
-- ✅ Require PR before merging
-- ✅ Require 2 approvals
-- ✅ Require status checks: `Calculate Version`
-- ✅ Require conversation resolution
+> **💡 Important**: Version bumps are determined by **branch type**, not commit messages!
+> - `feature/*` → main = MINOR bump
+> - `bugfix/*` → main = PATCH bump  
+> - `alpha` → main = MAJOR bump
+> - `hotfix` → release = PATCH bump
+>
+> Use conventional commits for clarity and changelog generation, not versioning control.
 
 ---
 
-## GitHub Actions Workflow
+---
 
-### Triggers
+## 🛠️ Common Git Commands
 
-| Event | Branches | Action |
-|-------|----------|--------|
-| Push | All branches | Build, test, calculate version |
-| PR | main, alpha, release | Build, test, show version |
-| Merge to main | - | Create tag, update VERSION |
-| Merge to release | - | Create tag, release, update VERSION |
+### Branch Management
 
-### Jobs
+```bash
+# View all branches (local and remote)
+git branch -a
 
-1. **version** - Calculate semantic version
-2. **build** - Build and test code
-3. **docker** - Build and push Docker images (optional)
-4. **release** - Create GitHub release (release branch only)
-5. **update-version** - Update VERSION file
+# Switch branches and pull latest
+git checkout main
+git pull origin main
 
----
+# Delete merged feature branch
+git branch -d feature/my-feature
+git push origin --delete feature/my-feature
 
-## Troubleshooting
+# Sync your fork with upstream
+git fetch upstream
+git checkout main
+git merge upstream/main
+```
 
-### Workflow Not Running
+### Tag Operations
 
 ```bash
-# Check workflow file
-cat .github/workflows/ci-cd-versioned.yml
+# View all tags
+git tag -l
 
-# Check GitHub Actions settings
-# Settings → Actions → General → Enable
+# View tags matching pattern
+git tag -l "v1.*"
+
+# Fetch latest tags from remote
+git fetch --tags
+
+# View tag details
+git show v1.0.0
+
+# Checkout specific tag
+git checkout v1.0.0
 ```
 
-### Wrong Version Calculated
+### Commit History
 
 ```bash
-# Check VERSION file
-cat VERSION
+# View pretty commit history
+git log --oneline --graph --all
 
-# Check branch name pattern
-git branch --show-current
+# View commits by author
+git log --author="YourName"
 
-# Check CI logs for version calculation
-```
+# View commits in date range
+git log --since="2024-01-01" --until="2024-12-31"
 
-### Merge Conflicts in VERSION
+# Search commits by message
+git log --grep="fix(auth)"
 
-```bash
-# Always use higher version
-git checkout --theirs VERSION
-git add VERSION
-git commit
+# View file history
+git log --follow -- path/to/file
 ```
 
-### Tag Already Exists
+### Undoing Changes
 
 ```bash
-# Delete tag locally and remotely
-git tag -d v1.0.0
-git push origin :refs/tags/v1.0.0
+# Undo last commit (keep changes staged)
+git reset --soft HEAD~1
+
+# Undo last commit (keep changes unstaged)
+git reset HEAD~1
 
-# Re-run the merge
+# Discard local changes to file
+git checkout -- path/to/file
+
+# Discard all local changes
+git reset --hard HEAD
+
+# Amend last commit message
+git commit --amend -m "new message"
+
+# Amend last commit (add forgotten files)
+git add forgotten-file.txt
+git commit --amend --no-edit
 ```
 
-### CI Fails on Test
+### Interactive Rebase (Clean Up Commits)
 
 ```bash
-# Run tests locally
-npm test
+# Squash last 3 commits before PR
+git rebase -i HEAD~3
 
-# Check logs in GitHub Actions
-# Actions → Latest workflow run → Build & Test
+# In the editor:
+# - Change 'pick' to 'squash' for commits to combine
+# - Save and close
+# - Edit combined commit message
 ```
 
 ---
 
-## Useful Git Commands
+---
 
-```bash
-# View all branches
-git branch -a
+## 🔧 Troubleshooting Quick Fixes
 
-# View all tags
-git tag -l
+### Workflow Not Running
 
-# Fetch latest tags
-git fetch --tags
+```bash
+# 1. Verify workflow file exists
+ls .github/workflows/ci-cd-versioned.yml
 
-# View tag details
-git show v1.0.0
+# 2. Check GitHub Actions is enabled
+# Go to: Settings → Actions → General → Enable
 
-# View commit history
-git log --oneline --graph --all
+# 3. Check branch protection allows workflow
+# Settings → Branches → Edit protection rules
+```
 
-# Sync with upstream
-git fetch upstream
-git merge upstream/alpha
+### Wrong Version Calculated
 
-# Squash commits before PR
-git rebase -i HEAD~3
+```bash
+# Check current VERSION
+cat VERSION
 
-# Undo last commit (keep changes)
-git reset --soft HEAD~1
+# Verify branch name pattern
+git branch --show-current
 
-# View file at specific tag
-git show v1.0.0:VERSION
+# Expected patterns:
+# - feature/name  → MINOR bump
+# - bugfix/name   → PATCH bump  
+# - alpha         → MAJOR bump
+# - hotfix        → PATCH bump
+
+# View CI logs for version calculation
+# GitHub → Actions → Latest run → Calculate Version job
 ```
 
----
+### Merge Conflicts in VERSION
 
-## Configuration Files
+```bash
+# Always choose the higher version
+git checkout --theirs VERSION
+git add VERSION
+git commit
 
-### `.github/workflows/ci-cd-versioned.yml`
-Main CI/CD workflow
+# Or manually edit VERSION to higher number
+echo "1.2.3" > VERSION
+git add VERSION
+git commit
+```
 
-### `VERSION`
-Current version (e.g., `0.1.0`)
+### Tag Already Exists
 
-### `BRANCH_STRATEGY.md`
-Detailed branch strategy documentation
+```bash
+# Delete tag locally
+git tag -d v1.0.0
 
-### `README.md`
-Project overview and documentation
+# Delete tag remotely
+git push origin :refs/tags/v1.0.0
 
----
+# Force push the corrected commit
+# (Only if safe to do so!)
+git push --force-with-lease
+```
 
-## Quick Links
+### CI Tests Fail
 
-- [Full Setup Guide](../docs/SETUP_GUIDE.md)
-- [Workflow Examples](../docs/WORKFLOW_EXAMPLES.md)
-- [Customization Guide](../docs/CUSTOMIZATION.md)
-- [Branch Strategy](../BRANCH_STRATEGY.md)
+```bash
+# Run tests locally first
+npm test
+# or
+python -m pytest
+# or
+cargo test
 
----
+# Check specific job logs
+# GitHub → Actions → Failed run → Click failing job
 
-## Common Workflows
+# Re-run failed jobs
+# GitHub → Actions → Failed run → Re-run failed jobs
+```
 
-### Release a Feature
+### Branch Protection Blocks Merge
 
 ```bash
-feature/* → main (via PR) → v0.2.0-beta tag
-main → release (via PR) → v0.2.0 tag + Release
+# Ensure all required checks pass
+# - Build & Test must be green
+# - Calculate Version must complete
+# - Required reviews must be approved
+# - All conversations must be resolved
+
+# View protection rules
+# Settings → Branches → Branch protection rules
 ```
 
-### Release a Hotfix
+---
 
-```bash
-hotfix → release (via PR) → v1.0.1 tag + Release
-# Auto-syncs to main and all active branches
-```
+## 📁 Key Files Reference
 
-### Major Version Release
+| File | Purpose | When to Edit |
+|------|---------|--------------|
+| `VERSION` | Current semantic version | Never manually (auto-updated by CI) |
+| `.github/workflows/ci-cd-versioned.yml` | CI/CD automation | When customizing workflow |
+| `BRANCH_STRATEGY.md` | Branch rules and flows | Reference only |
+| `README.md` | Project overview | Update for your project |
 
-```bash
-alpha → main (via PR) → v1.0.0-alpha tag
-# Beta branch created
-beta → main (via PR) → v1.0.0-beta tag
-main → release (via PR) → v1.0.0 tag + Release
-```
+> **⚠️ Warning**: Never manually edit `VERSION` file unless fixing a CI issue. The workflow manages it automatically.
 
 ---
 
-## 📝 Commit Message Conventions
+## 🔗 Documentation Links
 
-**Use conventional commits for better organization** (version bumps are determined by the branch being merged, not individual commits):
+### Getting Started
+- 🚀 [Quickstart](QUICKSTART.md) - Initial setup (5 minutes)
+- 📘 [Setup Guide](SETUP_GUIDE.md) - Detailed configuration
 
-```mermaid
-flowchart LR
-    feat["feat(auth): add login"]
-    fix["fix(api): handle null"]
-    breaking["feat!(api): redesign"]
-    docs["docs(readme): update"]
-    chore["chore(deps): update"]
-    
-    feat -->|Best Practice| bp1["Use for new features"]
-    fix -->|Best Practice| bp2["Use for bug fixes"]
-    breaking -->|Best Practice| bp3["Use for breaking changes"]
-    docs -->|Best Practice| bp4["Use for documentation"]
-    chore -->|Best Practice| bp5["Use for maintenance"]
-    
-    style feat fill:#2ecc71,color:#fff
-    style fix fill:#f39c12,color:#fff
-    style breaking fill:#e74c3c,color:#fff
-    style docs fill:#95a5a6,color:#fff
-    style chore fill:#95a5a6,color:#fff
-    style bp1 fill:#3498db,color:#fff
-    style bp2 fill:#3498db,color:#fff
-    style bp3 fill:#3498db,color:#fff
-    style bp4 fill:#95a5a6,color:#fff
-    style bp5 fill:#95a5a6,color:#fff
-```
+### Daily Usage  
+- ⚡ **Quick Reference** (this page) - Command cheat sheet
+- 📖 [Workflow Examples](WORKFLOW_EXAMPLES.md) - Step-by-step scenarios
+- 🌳 [Branch Strategy](BRANCH_STRATEGY.md) - Branch rules and flows
 
-**Important**: Version bumps are determined by **which branch is merged**, not individual commit messages:
-- `feature/*` → main = MINOR bump (regardless of commit messages)
-- `bugfix/*` → main = PATCH bump (regardless of commit messages)
-- `alpha` → main = MAJOR bump (regardless of commit messages)
-- `hotfix` → release = PATCH bump (regardless of commit messages)
+### Advanced
+- 🎨 [Customization Guide](CUSTOMIZATION.md) - Adapt to your needs
+- 📂 [Project Structure](PROJECT_STRUCTURE.md) - File organization
+- 📋 [Summary](SUMMARY.md) - High-level overview
+
+---
 
-Commit messages should follow [Conventional Commits](https://www.conventionalcommits.org/) for clarity and changelog generation, but they don't control versioning.
+## 💡 Pro Tips
+
+1. **Commit Often**: Small, focused commits are easier to review and revert
+2. **Branch Names**: Use descriptive names like `feature/user-authentication` not `feature/fix`
+3. **PR Descriptions**: Link related issues with `Closes #123` or `Fixes #456`
+4. **Review Tags**: Check tags regularly with `git fetch --tags && git tag -l`
+5. **Test Locally**: Always run tests before pushing with `npm test` or equivalent
+6. **Clean Branches**: Delete merged branches to keep repo tidy
+7. **Read CI Logs**: When workflow fails, read the logs - they're usually clear about what's wrong
 
 ---
 
-**Print this guide for quick reference!** 📋
+**📌 Bookmark this page for daily reference!**
+
+
diff --git a/docs/git-auto-release/README.md b/docs/git-auto-release/README.md
index bf59db3..e9f4f44 100644
--- a/docs/git-auto-release/README.md
+++ b/docs/git-auto-release/README.md
@@ -11,7 +11,7 @@ Complete documentation for setting up and using automated Git versioning and rel
 ### Getting Started
 - **[Quick Start Guide](QUICKSTART.md)** - Get up and running in 10 minutes
 - **[Setup Guide](SETUP_GUIDE.md)** - Complete installation and configuration
-- **[Quick Reference](QUICK_REFERENCE.md)** - Commands and version progression cheat sheet
+- **[Quick Reference](QUICK_REFERENCE.md)** - Daily workflow commands and version cheat sheet (for established projects)
 
 ### Core Concepts
 - **[Branch Strategy](BRANCH_STRATEGY.md)** - Detailed branching model and workflows
@@ -26,7 +26,7 @@ Complete documentation for setting up and using automated Git versioning and rel
 > - **Branch diagrams** in [Branch Strategy](BRANCH_STRATEGY.md)
 > - **Workflow flowcharts** in [Workflow Examples](WORKFLOW_EXAMPLES.md)
 > - **CI/CD architecture** in [Setup Guide](SETUP_GUIDE.md)
-> - **Quick decision tree** in [Quick Reference](QUICK_REFERENCE.md)
+> - **Quick decision tree** in [Quick Reference](QUICK_REFERENCE.md) (for daily usage)
 
 ### Additional Resources
 - **[Summary](SUMMARY.md)** - Quick overview
@@ -167,12 +167,20 @@ This template uses **GitHub Actions** as reference but works with:
 
 ---
 
+## 📄 License
+
+This template is released under the **MIT License** - see [LICENSE](LICENSE) for full details.
+
+You are free to use, modify, and distribute this template in any project (commercial or personal). **Your projects built with this template can use any license you choose.**
+
+---
+
 ## 📞 Need Help?
 
 - 📖 Read the [Setup Guide](SETUP_GUIDE.md)
 - 🐛 Check [GitHub Issues](https://github.com/CodeOOf/Git-Auto-Release/issues)
 - 💬 Join [Discussions](https://github.com/CodeOOf/Git-Auto-Release/discussions)
-- ⚡ Use [Quick Reference](QUICK_REFERENCE.md) for common commands
+- ⚡ Use [Quick Reference](QUICK_REFERENCE.md) for daily workflow commands
 
 ---
 
diff --git a/docs/git-auto-release/SETUP_GUIDE.md b/docs/git-auto-release/SETUP_GUIDE.md
index e54695e..17be981 100644
--- a/docs/git-auto-release/SETUP_GUIDE.md
+++ b/docs/git-auto-release/SETUP_GUIDE.md
@@ -1,102 +1,125 @@
 # Setup Guide
 
-📖 **Navigation**: [← README](../README.md) | [Quick Start](../QUICKSTART.md) | **Setup Guide** | [Workflow Examples →](WORKFLOW_EXAMPLES.md)
+📖 **Navigation**: [← README](README.md) | [Quick Start](QUICKSTART.md) | **Setup Guide** | [Workflow Examples →](WORKFLOW_EXAMPLES.md)
 
-Complete step-by-step guide to set up Git Auto Release in your project.
+**Detailed configuration guide for Git Auto Release.**
+
+> 💡 **Just want to get started?** See [Quick Start Guide](QUICKSTART.md) for a 5-minute setup.
+
+This guide provides in-depth setup instructions, advanced configuration options, and platform-specific customizations.
 
 ---
 
 ## Table of Contents
 
-1. [Initial Repository Setup](#1-initial-repository-setup)
-2. [Organize Template Documentation](#2-organize-template-documentation)
+1. [Prerequisites](#1-prerequisites)
+2. [Initial Setup](#2-initial-setup)
 3. [Configure Branch Protection](#3-configure-branch-protection)
-4. [Configure Git Commit Signing](#4-configure-git-commit-signing-optional-but-recommended)
+4. [Configure Git Commit Signing](#4-configure-git-commit-signing-optional)
 5. [Customize the Workflow](#5-customize-the-workflow)
 6. [Test Your Setup](#6-test-your-setup)
 7. [Troubleshooting](#7-troubleshooting)
 
 ---
 
-## 1. Initial Repository Setup
+## 1. Prerequisites
+
+- Git installed locally
+- GitHub account (or GitLab/Bitbucket)
+- Basic understanding of Git branches and pull requests
+- Familiarity with GitHub Actions (or equivalent CI/CD)
+
+---
+
+## 2. Initial Setup
+
+> 📚 **For quick setup instructions**, see [Quick Start Guide](QUICKSTART.md).
+
+This section provides detailed explanations for both setup methods.
+
+### Understanding the Template Structure
+
+The template includes:
+- **VERSION file**: Tracks current version (starts at `1.0.0-beta` after alpha merge)
+- **README.template.md**: Your project README starter
+- **CONTRIBUTING.template.md**: Contribution guidelines starter
+- **.github/workflows/ci-cd-versioned.yml**: Automated versioning workflow
+- **docs/git-auto-release/**: All template documentation
 
-### Option A: Use This Template on GitHub
+### Option A: Use GitHub Template (Recommended)
 
-1. Click **"Use this template"** button on GitHub
-2. Name your new repository
-3. Clone your new repository:
+**Advantages:**
+- ✅ Fastest setup
+- ✅ Preserves all branches automatically
+- ✅ GitHub handles initialization
+
+**Steps:**
+1. Click **"Use this template"** on GitHub
+2. Name your repository
+3. Create repository
+4. Clone locally:
    ```bash
    git clone https://github.com/YOUR_USERNAME/YOUR_REPO.git
    cd YOUR_REPO
    ```
 
-### Option B: Clone and Reinitialize
+### Option B: Manual Clone and Setup
+
+**Advantages:**
+- ✅ Full control over repository initialization
+- ✅ Can customize before first commit
+- ✅ Good for offline or private setups
 
+**Steps:**
 ```bash
-# Clone the template
+# Clone with your project name
 git clone https://github.com/CodeOOf/Git-Auto-Release.git my-project
 cd my-project
 
-# Remove existing git history
+# Remove Git history
 rm -rf .git
 
-# Initialize new repository
+# Set initial version
+echo "0.1.0" > VERSION
+
+# Replace template files
+rm README.md CONTRIBUTING.md
+mv README.template.md README.md
+mv CONTRIBUTING.template.md CONTRIBUTING.md
+
+# Edit README.md and CONTRIBUTING.md with your project details
+
+# Initialize Git
 git init
+git checkout -b main
 git add .
-git commit -m "Initial commit from Git Auto Release template"
+git commit -m "chore: initialize project from Git-Auto-Release template"
 
-# Connect to your remote repository
+# Add remote and push
 git remote add origin https://github.com/YOUR_USERNAME/YOUR_REPO.git
 git push -u origin main
-```
-
----
 
-## 2. Organize Template Documentation
-
-**Make this template your own by separating template docs from your project docs.**
-
-### Move Template Documentation
-
-```bash
-# Create template documentation folder
-mkdir -p docs/git-auto-release
-
-# Move template files
-mv README.md docs/git-auto-release/
-mv QUICKSTART.md docs/git-auto-release/
-mv BRANCH_STRATEGY.md docs/git-auto-release/
-
-# Setup and workflow docs are already in docs/, move them too
-mv docs/SETUP_GUIDE.md docs/git-auto-release/
-mv docs/WORKFLOW_EXAMPLES.md docs/git-auto-release/
-mv docs/CUSTOMIZATION.md docs/git-auto-release/
-mv docs/QUICK_REFERENCE.md docs/git-auto-release/
-
-# Optional: Move contributing guide
-mv CONTRIBUTING.md docs/git-auto-release/ 2>/dev/null || true
-
-# Use the project README template
-mv README.template.md README.md
-
-# Commit the reorganization
-git add .
-git commit -m "chore: organize template documentation"
-git push
+# Create release branch
+git checkout -b release
+git push -u origin release
+git checkout main
 ```
 
-### Customize Your Project README
+### Customize Your Project Files
+
+After setup, edit these files:
 
-Edit `README.md` with:
-- Your project name and description
-- Project-specific setup instructions
-- Links to your documentation
-- Reference to version automation: `docs/git-auto-release/README.md`
+**README.md:**
+- Project name and description
+- Installation instructions
+- Usage examples
+- Link to template docs: `docs/git-auto-release/`
 
-**Result:** Template documentation is now isolated in `docs/git-auto-release/`. You can:
-- Keep it for team reference
-- Move it to `docs/archive/` later
-- Delete it once familiar with the workflow
+**CONTRIBUTING.md:**
+- Contribution guidelines
+- Code of conduct
+- Development setup
+- Commit message conventions
 
 ---
 
@@ -125,108 +148,108 @@ graph TB
     style release fill:#e74c3c,color:#fff
 ```
 
-**Protection Levels:**
-- **feature/** branches: No protection (development freedom)
-- **alpha**: Optional protection with status checks
-- **main**: Protected with 1 approval, all status checks required
-- **release**: Highly protected with 2 approvals, critical status checks
-
----
-
-Navigate to your repository's branch protection settings (location varies by platform):
-- **GitHub**: Settings → Branches → Add branch protection rule
-- **GitLab**: Settings → Repository → Protected Branches
-- **Bitbucket**: Repository Settings → Branch Permissions
+## 3. Configure Branch Protection
 
-### Set Your Initial Version
+> 📚 **Quick setup**: See [Quick Start Guide - Branch Protection](QUICKSTART.md#step-2-branch-protection-2-min) for basic configuration.
 
-Edit the `VERSION` file:
+This section provides detailed protection rules and platform-specific instructions.
 
-```bash
-echo "0.1.0" > VERSION
-git add VERSION
-git commit -m "chore: set initial version to 0.1.0"
-git push
-```
+**Protect your branches to ensure code quality and version control integrity.**
 
-### Create Required Branches
+### 🔐 Branch Protection Overview
 
-```bash
-# Create and push release branch
-git checkout main
-git checkout -b release
-git push -u origin release
+**Visual representation of recommended protection levels:**
 
-# Return to main
-git checkout main
+```mermaid
+graph TB
+    feature[feature/my-feature<br/>No protection<br/>✅ Push directly]
+    bugfix[bugfix/my-fix<br/>No protection<br/>✅ Push directly]
+    alpha[alpha<br/>Optional protection<br/>Status checks recommended]
+    beta[beta<br/>Auto-created<br/>No direct commits]
+    main[main<br/>✅ Protected<br/>✅ Require PR<br/>⭐ 1 Approval<br/>✅ Status checks]
+    release[release<br/>✅✅ Highly Protected<br/>✅ Require PR<br/>⭐⭐ 2 Approvals<br/>✅ Status checks]
+    
+    feature -->|PR| main
+    bugfix -->|PR| main
+    alpha -->|PR| main
+    beta -->|PR| main
+    main -->|PR| release
+    
+    style feature fill:#2ecc71,color:#fff
+    style bugfix fill:#2ecc71,color:#fff
+    style alpha fill:#9b59b6,color:#fff
+    style beta fill:#3498db,color:#fff
+    style main fill:#3498db,color:#fff
+    style release fill:#e74c3c,color:#fff
 ```
 
-**Note**: The `alpha` and `beta` branches are optional and only needed when working on breaking changes (MAJOR version bumps). Create them when needed:
+**Protection Levels:**
+- **feature/**, **bugfix/** branches: No protection (development freedom)
+- **alpha**: Optional protection with status checks (for breaking changes)
+- **beta**: Auto-created from main, no direct commits
+- **main**: Protected with 1 approval, all status checks required
+- **release**: Highly protected with 2 approvals, production-ready
 
-```bash
-# Only create alpha/beta when working on breaking changes
-git checkout main
-git checkout -b alpha
-git push -u origin alpha
-```
+---
 
-### Protect the `main` Branch
+### Platform-Specific Setup
 
-Configure the following for `main` branch:
+Navigate to branch protection settings:
+- **GitHub**: Settings → Branches → Add branch protection rule
+- **GitLab**: Settings → Repository → Protected Branches
+- **Bitbucket**: Repository Settings → Branch Permissions
 
-   **Pull Request/Merge Request Settings:**
-   - ✅ **Require a pull/merge request before merging**
-   - ✅ **Require approvals**: 1+
-   - ✅ **Dismiss stale approvals when new commits are pushed** (if available)
-   - ✅ **Require approval of the most recent reviewable push** (if available)
+### Protect the `main` Branch
 
-   **Status Checks:**
-   - ✅ **Require status checks to pass before merging**
-   - ✅ **Require branches to be up to date before merging**
-   - Add required checks (adjust names based on your CI/CD setup):
-     - `Build & Test`
-     - `Calculate Version`
+**Rule name/pattern:** `main`
 
-   **Additional Settings:**
-   - ✅ **Require conversation resolution before merging**
-   - ✅ **Do not allow bypassing the above settings**
+**Required settings:**
+- ✅ **Require pull request before merging**
+- ✅ **Require approvals**: 1
+- ✅ **Require status checks to pass**
+  - Required checks:
+    - `Build & Test` (placeholder job)
+    - `Calculate Version` (from version job)
+- ✅ **Require branches to be up to date**
+- ✅ **Require conversation resolution before merging**
+- ✅ **Do not allow bypassing settings**
 
-6. Click **Create**
+**Optional but recommended:**
+- ✅ **Dismiss stale approvals when new commits pushed**
+- ✅ **Require approval of most recent push**
 
 ### Protect the `release` Branch
 
-1. Click **Add branch protection rule** again
-2. Branch name pattern: `release`
-3. Configure the following:
-
-   **Pull Request Settings:**
-   - ✅ **Require a pull request before merging**
-   - ✅ **Require approvals**: 2 (higher for production)
-   - ✅ **Dismiss stale pull request approvals when new commits are pushed**
+**Rule name/pattern:** `release`
 
-   **Status Checks:**
-   - ✅ **Require status checks to pass before merging**
-   - ✅ **Require branches to be up to date before merging**
-   - Add required checks:
-     - `Calculate Version`
+**Required settings:**
+- ✅ **Require pull request before merging**
+- ✅ **Require approvals**: 2 (higher for production)
+- ✅ **Require status checks to pass**
+  - Required checks:
+    - `Calculate Version`
+- ✅ **Require branches to be up to date**  
+- ✅ **Require conversation resolution**
+- ✅ **Do not allow bypassing settings**
 
-   **Additional Settings:**
-   - ✅ **Require conversation resolution before merging**
-   - ✅ **Do not allow bypassing the above settings**
-
-4. Click **Create**
+**Additional protection:**
+- ✅ **Dismiss stale approvals when new commits pushed**
+- ✅ **Restrict who can push** (optional: only maintainers)
 
 ### Optional: Protect `alpha` Branch
 
-For stricter control over pre-release code:
+For stricter control over breaking changes:
+
+**Rule name/pattern:** `alpha`
 
-1. Add protection for `alpha`
-2. **Require status checks**: `Build & Test`
-3. Consider requiring 1 approval for feature merges
+**Settings:**
+- ✅ **Require status checks**: `Build & Test`
+- Consider requiring 1 approval for feature merges
+- Useful for teams working on major version changes
 
 ---
 
-## 4. Configure Git Commit Signing (Optional but Recommended)
+## 4. Configure Git Commit Signing (Optional)
 
 Secure your commits with GPG signing for better traceability and security.
 
diff --git a/docs/git-auto-release/SUMMARY.md b/docs/git-auto-release/SUMMARY.md
index f6fc651..e7e62ba 100644
--- a/docs/git-auto-release/SUMMARY.md
+++ b/docs/git-auto-release/SUMMARY.md
@@ -1,271 +1,144 @@
-# Git-Auto-Release Template - Project Summary
+# Git-Auto-Release Template - Overview
 
-**Status**: ✅ Complete and Ready to Use
+**A GitHub Actions template for fully automated semantic versioning and release management.**
 
 ---
 
-## What Has Been Organized
+## 🎯 What Is This?
 
-This repository is now a **complete, production-ready template** for automating Git version control and release management. Everything in the branch strategy document has been implemented and documented.
+Git-Auto-Release automates your version control workflow using GitHub Actions:
 
----
-
-## 🎯 Project Purpose
-
-Git-Auto-Release is a **GitHub Actions template** that provides:
-
-1. **100% Automated Versioning**: No manual VERSION file updates needed
-2. **Branch-Based Version Bumping**: Automatic MAJOR/MINOR/PATCH based on merge source
-3. **Pre-Release Management**: Alpha, beta, and release candidate tags
-4. **Production Releases**: Automated GitHub releases with changelogs
-5. **Semantic Versioning Compliance**: Strict adherence to semver 2.0.0
+1. **Automatic Version Bumping**: MAJOR/MINOR/PATCH based on branch merges
+2. **Semantic Versioning**: Full semver 2.0.0 compliance with pre-release tags
+3. **Branch-Based Strategy**: Parallel branching model with clear promotion paths
+4. **Zero Maintenance**: No manual VERSION file edits or tag creation
+5. **Production Ready**: Includes GitHub Releases, changelogs, and optional Docker support
 
 ---
 
-## 📁 Complete Project Structure
+## 📚 Documentation Guide
 
-```
-Git-Auto-Release/
-├── .github/
-│   └── workflows/
-│       └── ci-cd-versioned.yml    ✅ Complete CI/CD automation
-├── docs/
-│   ├── README.md                  ✅ Documentation index
-│   ├── SETUP_GUIDE.md            ✅ Step-by-step setup
-│   ├── WORKFLOW_EXAMPLES.md      ✅ Real-world scenarios
-│   ├── CUSTOMIZATION.md          ✅ Adaptation guide
-│   ├── QUICK_REFERENCE.md        ✅ Fast command reference
-│   └── PROJECT_STRUCTURE.md      ✅ Structure overview
-├── BRANCH_STRATEGY.md            ✅ Complete strategy with diagrams
-├── CONTRIBUTING.md               ✅ How to contribute to template
-├── LICENSE                       ✅ MIT License
-├── README.md                     ✅ Comprehensive project docs
-└── VERSION                       ✅ Current version (0.1.0)
-```
+### Getting Started
+- 🚀 **[QUICKSTART.md](QUICKSTART.md)** - Get running in 5 minutes (Option A: GitHub template, Option B: Manual setup)
+- 📘 **[SETUP_GUIDE.md](SETUP_GUIDE.md)** - Detailed configuration and advanced options
 
----
+### Daily Usage (For Established Projects)
+- ⚡ **[QUICK_REFERENCE.md](QUICK_REFERENCE.md)** - Command cheat sheet and decision tree
+- 📖 **[WORKFLOW_EXAMPLES.md](WORKFLOW_EXAMPLES.md)** - Real-world step-by-step scenarios
 
-## ✨ Key Features Implemented
-
-### 1. Automated CI/CD Workflow
-- ✅ Version calculation based on branch and merge context
-- ✅ Automatic tag creation
-- ✅ VERSION file auto-updates
-- ✅ GitHub release generation
-- ✅ Docker build support (optional)
-- ✅ Build and test automation
-
-### 2. Branch Strategy
-- ✅ Four-tier branching model (release → main → beta → alpha)
-- ✅ Feature and bugfix branches
-- ✅ Hotfix support
-- ✅ Clear promotion paths
-
-### 3. Version Automation
-- ✅ MAJOR bump: `alpha` → `main` merges
-- ✅ MINOR bump: `feature/*` → `main` merges
-- ✅ PATCH bump: `bugfix/*` → `main` or `hotfix` → `release` merges
-- ✅ Pre-release tags: `-alpha`, `-beta`, `-rc.N`
-- ✅ Build metadata: `+SHA`
-
-### 4. Documentation
-- ✅ Comprehensive README with quick start
-- ✅ Detailed setup guide with screenshots
-- ✅ Real-world workflow examples
-- ✅ Customization guide for different languages
-- ✅ Quick reference for daily use
-- ✅ Project structure documentation
-
-### 5. Examples
-- ✅ Node.js/npm project configuration
-- ✅ Python project configuration
-- ✅ Docker configuration
-- ✅ Git ignore patterns
-- ✅ Contribution guidelines template
+### Understanding & Customization
+- 🌳 **[BRANCH_STRATEGY.md](BRANCH_STRATEGY.md)** - Parallel branching model explained
+- 🎨 **[CUSTOMIZATION.md](CUSTOMIZATION.md)** - Adapt for GitLab, Bitbucket, Jenkins, etc.
+- 📂 **[PROJECT_STRUCTURE.md](PROJECT_STRUCTURE.md)** - Template file organization
 
 ---
 
-## 🚀 How to Use This Template
-
-### Quick Start (5 minutes)
-
-```bash
-# 1. Use template or clone
-git clone https://github.com/CodeOOf/Git-Auto-Release.git my-project
-cd my-project
+## 📁 What You Get (Template Files)
 
-# 2. Set initial version
-echo "0.1.0" > VERSION
+When you use this template, you receive:
 
-# 3. Create branches
-git checkout -b alpha
-git push origin main alpha
-git checkout -b release
-git push origin release
-
-# 4. Configure GitHub (Settings → Branches)
-# - Add protection for main (1 approval required)
-# - Add protection for release (2 approvals required)
-
-# 5. Start developing!
-git checkout alpha
-git checkout -b feature/my-first-feature
-# ... make changes ...
-git commit -m "feat(core): add amazing feature"
-git push origin feature/my-first-feature
-# Open PR to alpha on GitHub
+```
+Your-Project/
+├── .github/workflows/
+│   └── ci-cd-versioned.yml          # Automated versioning workflow
+├── docs/git-auto-release/           # All template documentation (keep, archive, or remove)
+├── README.template.md              # Starter for your project README
+├── CONTRIBUTING.template.md        # Starter for your contribution guidelines
+├── CHECKLIST.md                    # Implementation checklist
+└── VERSION                         # Semantic version tracker (auto-managed)
 ```
 
-### Complete Setup (~15 minutes)
-
-Follow the comprehensive guide: [`docs/SETUP_GUIDE.md`](docs/SETUP_GUIDE.md)
+**Note**: Template documentation is in `docs/git-auto-release/` - you can keep it for reference, move to archive, or delete once familiar.
 
 ---
 
-## 📚 Documentation Overview
+## ✨ Key Features
 
-### For New Users
-1. **Start here**: [`README.md`](README.md) - Overview and quick start
-2. **Setup**: [`docs/SETUP_GUIDE.md`](docs/SETUP_GUIDE.md) - Complete setup instructions
-3. **Learn**: [`docs/WORKFLOW_EXAMPLES.md`](docs/WORKFLOW_EXAMPLES.md) - How to use
+### Automated Versioning
+- ✅ **MAJOR bump**: `alpha` → `main` (breaking changes)
+- ✅ **MINOR bump**: `feature/*` → `main` (new features)
+- ✅ **PATCH bump**: `bugfix/*` → `main` (bug fixes)
+- ✅ **Pre-release tags**: `-alpha`, `-beta` suffixes
+- ✅ **Build metadata**: `+SHA` for dev builds
 
-### For Daily Use
-- **Quick Reference**: [`docs/QUICK_REFERENCE.md`](docs/QUICK_REFERENCE.md) - Commands and workflows
-- **Branch Strategy**: [`BRANCH_STRATEGY.md`](BRANCH_STRATEGY.md) - Detailed rules
+### Branch Strategy
+- ✅ **Parallel branching**: All branches from `main` (except hotfix from `release`)
+- ✅ **Alpha branch**: For breaking changes only
+- ✅ **Beta branch**: Auto-created after alpha merge
+- ✅ **Release branch**: Production-ready code
+- ✅ **Hotfix support**: Emergency production fixes
 
-### For Customization
-- **Customization Guide**: [`docs/CUSTOMIZATION.md`](docs/CUSTOMIZATION.md) - Adapt for your needs
+### CI/CD Automation
+- ✅ **Merge commit detection**: Supports both merge and squash merges
+- ✅ **VERSION file updates**: Automatic after PR merges
+- ✅ **Tag creation**: Auto-tagged with proper semver
+- ✅ **GitHub Releases**: Generated with changelogs
+- ✅ **Branch syncing**: Keeps branches up-to-date
 
-### For Contributors
-- **Contributing**: [`CONTRIBUTING.md`](CONTRIBUTING.md) - How to contribute
-- **Project Structure**: [`docs/PROJECT_STRUCTURE.md`](docs/PROJECT_STRUCTURE.md) - Understanding the layout
+### Template Design
+- ✅ **Placeholder build steps**: Customize for your stack
+- ✅ **Commented examples**: Docker, deployment guides
+- ✅ **Platform-agnostic**: Works with any language
+- ✅ **Documentation included**: All template docs in `docs/git-auto-release/`
 
 ---
 
-## 🎨 What Makes This Special
-
-### Complete Automation
-- **No manual version updates**: CI/CD handles everything
-- **No manual tag creation**: Automatic based on merges
-- **No manual releases**: GitHub releases auto-generated
+## 🎨 Version Flow Example
 
-### Clear Strategy
-- **Predictable version bumps**: Based on branch type
-- **Safe production releases**: Multiple review stages
-- **Emergency hotfix support**: Fast-track for critical issues
-
-### Comprehensive Documentation
-- **Step-by-step guides**: For every scenario
-- **Real examples**: Node.js, Python, Docker
-- **Quick reference**: For daily tasks
-- **Troubleshooting**: Common issues and solutions
+```
+feature/login → main
+  ├─ Merge: Creates v0.2.0-beta tag
+  └─ Result: Ready for staging/testing
 
-### Flexibility
-- **Language agnostic**: Works with any project type
-- **Customizable**: Adapt version logic, build steps, deployment
-- **Optional features**: Remove Docker builds, add custom jobs
+main → release (when ready)
+  ├─ Merge: Creates v0.2.0 tag + GitHub Release
+  └─ Result: Production release
+```
 
 ---
 
-## ✅ Alignment with Branch Strategy
-
-Every requirement from `BRANCH_STRATEGY.md` is implemented:
+## 📊 Version Bump Summary
 
-| Requirement | Implementation | Status |
-|------------|----------------|--------|
-| Four-tier branching | release → main → beta → alpha | ✅ |
-| Automatic version bumping | Based on merge source | ✅ |
-| Pre-release tags | -alpha, -beta, -rc.N | ✅ |
-| VERSION file management | Auto-updated by CI/CD | ✅ |
-| Major release flow | alpha → main → beta → main → release | ✅ |
-| Minor release flow | feature/* → alpha → main → release | ✅ |
-| Patch release flow | bugfix/* → alpha → main → release | ✅ |
-| Hotfix support | hotfix → release → sync | ✅ |
-| Commit conventions | Conventional commits | ✅ |
-| Branch protection | Documented in setup guide | ✅ |
+| Action | From | To | Tag Created |
+|--------|------|-----|-------------|
+| Merge `feature/*` to `main` | 0.1.0 | 0.2.0-beta | v0.2.0-beta |
+| Merge `bugfix/*` to `main` | 0.1.0-beta | 0.1.1-beta | v0.1.1-beta |
+| Merge `alpha` to `main` | 0.9.0 | 1.0.0-alpha | v1.0.0-alpha |
+| Merge `beta` to `main` | 1.0.0-alpha | 1.0.0-beta | v1.0.0-beta |
+| Merge `main` to `release` | 0.2.0-beta | 0.2.0 | v0.2.0 + Release |
+| Merge `hotfix` to `release` | 1.0.0 | 1.0.1 | v1.0.1 + Release |
 
 ---
 
-## 🔧 Customization Options
-
-The template is **ready to use as-is** but can be customized:
+## 🛠️ Customization Points
 
 ### Easy Customizations
-- ✏️ Change build/test commands for your language
-- ✏️ Remove Docker builds if not needed
-- ✏️ Adjust release notes format
-- ✏️ Add deployment steps
+- Change placeholder build/test commands for your language
+- Remove Docker examples if not needed
+- Adjust branch protection rules
+- Modify release notes format
 
 ### Advanced Customizations
-- 🔬 Modify version bump logic
-- 🔬 Add custom pre-release suffixes
-- 🔬 Support monorepo structure
-- 🔬 Add additional branch tiers
+- Adapt workflow for GitLab CI, Bitbucket Pipelines, Jenkins
+- Change version bump logic
+- Add deployment steps
+- Integrate with external tools
 
-See [`docs/CUSTOMIZATION.md`](docs/CUSTOMIZATION.md) for details.
+See [CUSTOMIZATION.md](CUSTOMIZATION.md) for platform-specific guides.
 
 ---
 
-## 🎯 Use Cases
+## 🎯 Common Use Cases
 
 Perfect for:
-- ✅ **SaaS applications**: Clear staging → production path
-- ✅ **Open source projects**: Transparent release process
-- ✅ **Enterprise software**: Controlled, auditable releases
+- ✅ **SaaS applications**: Clear staging → production promotion path
+- ✅ **Open source projects**: Transparent and predictable releases
+- ✅ **Enterprise software**: Controlled, auditable version control
 - ✅ **Microservices**: Consistent versioning across services
-- ✅ **APIs**: Breaking changes clearly marked
-- ✅ **Libraries**: Semantic versioning for dependents
-
----
-
-## 📊 Version Progression Example
-
-Starting from `0.1.0`:
-
-```
-Developer merges feature → alpha → main
-  → Tag: v0.2.0-beta
-  → VERSION: 0.2.0-beta
-
-Developer merges main → release
-  → Tag: v0.2.0 (production)
-  → VERSION: 0.2.0
-  → GitHub Release created
-
-Developer merges bugfix → alpha → main → release
-  → Tag: v0.2.1
-  → VERSION: 0.2.1
-
-Developer merges alpha → main (breaking change)
-  → Tag: v1.0.0-alpha
-  → VERSION: 1.0.0-alpha
-  → Beta branch created
-
-Developer stabilizes on beta → merges to main
-  → Tag: v1.0.0-beta
-  → VERSION: 1.0.0-beta
-
-Developer merges main → release
-  → Tag: v1.0.0 (major release!)
-  → VERSION: 1.0.0
-  → Celebration! 🎉
-```
-
----
-
-## 🐛 Known Limitations
-
-- **GitHub Actions only**: Not compatible with other CI/CD platforms (but logic can be adapted)
-- **Single VERSION file**: Monorepos need customization
-- **Git-based**: Requires Git workflow (obviously!)
+- ✅ **APIs**: Breaking changes clearly marked with MAJOR bumps
+- ✅ **Libraries**: Semantic versioning for package dependents
 
 ---
-
-## 🙏 Credits
-
-Inspired by:
-- [Semantic Versioning 2.0.0](https://semver.org/)
-- [Git Flow](https://nvie.com/posts/a-successful-git-branching-model/)
 - [Conventional Commits](https://www.conventionalcommits.org/)
 - [GitHub Flow](https://docs.github.com/en/get-started/quickstart/github-flow)
 
@@ -299,30 +172,29 @@ Inspired by:
 
 ## 📄 License
 
-MIT License - Use freely in any project!
+This template is released under the **MIT License** - see [LICENSE](LICENSE) for full text.
 
----
+You are free to:
+- ✅ Use this template for commercial or personal projects
+- ✅ Modify and adapt to your needs  
+- ✅ Distribute and share
+
+**Your project built with this template can use any license you choose.**
 
-## 🎉 Summary
+---
 
-**Git-Auto-Release is now:**
-- ✅ Fully organized
-- ✅ Completely documented
-- ✅ Ready for production use
-- ✅ Easy to customize
-- ✅ Well-tested architecture
+## 🤝 Contributing & Support
 
-**The template provides:**
-- 🤖 100% automated version management
-- 🌳 Clear, reproducible branch strategy
-- 📦 Automatic releases and tagging
-- 📚 Comprehensive documentation
-- 🎨 Flexible customization
+**Contributions welcome!** See [CONTRIBUTING.md](../../CONTRIBUTING.md) for guidelines.
 
-**Start using it today to automate your release process!** 🚀
+**Need help?**
+- 📖 Documentation: Complete guides in [docs/git-auto-release/](.)
+- 🐛 Issues: [GitHub Issues](https://github.com/CodeOOf/Git-Auto-Release/issues)
+- 💬 Discussions: [GitHub Discussions](https://github.com/CodeOOf/Git-Auto-Release/discussions)
 
 ---
 
-**Created**: December 2025  
-**Status**: Production Ready  
-**Version**: 0.1.0 (template itself follows its own strategy!)
+**⏱️ Setup Time**: ~5 minutes  
+**🔄 Maintenance**: Zero - fully automated!  
+**💪 Production Ready**: Use immediately!
+

From c288a332f6424812d65ec66adc0a5af60ccf8935 Mon Sep 17 00:00:00 2001
From: "Viktor H. Ingre" <viktor.ingre@codeoof.com>
Date: Mon, 8 Dec 2025 08:36:47 +0100
Subject: [PATCH 2/8] Update docs/git-auto-release/QUICK_REFERENCE.md

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
---
 docs/git-auto-release/QUICK_REFERENCE.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/git-auto-release/QUICK_REFERENCE.md b/docs/git-auto-release/QUICK_REFERENCE.md
index 0118f4b..ce03890 100644
--- a/docs/git-auto-release/QUICK_REFERENCE.md
+++ b/docs/git-auto-release/QUICK_REFERENCE.md
@@ -213,7 +213,7 @@ git commit -m "fix(login): prevent duplicate submissions
 Closes #123"
 
 # Breaking change with migration notes
-git commit -m "feat!(api)!: change authentication to JWT
+git commit -m "feat!(api): change authentication to JWT
 
 BREAKING CHANGE: API now requires JWT tokens instead of API keys.
 Clients must update to use Authorization: Bearer <token> header."

From 70f8c7d22a64eb6b2edada5cea3ed66c7b8eb199 Mon Sep 17 00:00:00 2001
From: "Viktor H. Ingre" <viktor.ingre@codeoof.com>
Date: Mon, 8 Dec 2025 08:36:56 +0100
Subject: [PATCH 3/8] Update docs/git-auto-release/QUICK_REFERENCE.md

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
---
 docs/git-auto-release/QUICK_REFERENCE.md | 2 --
 1 file changed, 2 deletions(-)

diff --git a/docs/git-auto-release/QUICK_REFERENCE.md b/docs/git-auto-release/QUICK_REFERENCE.md
index ce03890..19c12bc 100644
--- a/docs/git-auto-release/QUICK_REFERENCE.md
+++ b/docs/git-auto-release/QUICK_REFERENCE.md
@@ -468,5 +468,3 @@ cargo test
 ---
 
 **📌 Bookmark this page for daily reference!**
-
-

From e038fb76e062aff7188156e685dcb27b941af11e Mon Sep 17 00:00:00 2001
From: "Viktor H. Ingre" <viktor.ingre@codeoof.com>
Date: Mon, 8 Dec 2025 08:37:26 +0100
Subject: [PATCH 4/8] Update docs/git-auto-release/QUICK_REFERENCE.md

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
---
 docs/git-auto-release/QUICK_REFERENCE.md | 2 --
 1 file changed, 2 deletions(-)

diff --git a/docs/git-auto-release/QUICK_REFERENCE.md b/docs/git-auto-release/QUICK_REFERENCE.md
index 19c12bc..addf19e 100644
--- a/docs/git-auto-release/QUICK_REFERENCE.md
+++ b/docs/git-auto-release/QUICK_REFERENCE.md
@@ -132,8 +132,6 @@ git push origin hotfix
 
 ---
 
----
-
 ## 📊 Version Progression Cheat Sheet
 
 ### Standard Version Bumps

From d7a36219547e645ce3451627ea03dc9d26f5964d Mon Sep 17 00:00:00 2001
From: "Viktor H. Ingre" <viktor.ingre@codeoof.com>
Date: Mon, 8 Dec 2025 08:37:47 +0100
Subject: [PATCH 5/8] Update docs/git-auto-release/QUICK_REFERENCE.md

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
---
 docs/git-auto-release/QUICK_REFERENCE.md | 1 -
 1 file changed, 1 deletion(-)

diff --git a/docs/git-auto-release/QUICK_REFERENCE.md b/docs/git-auto-release/QUICK_REFERENCE.md
index addf19e..3d2f30b 100644
--- a/docs/git-auto-release/QUICK_REFERENCE.md
+++ b/docs/git-auto-release/QUICK_REFERENCE.md
@@ -227,7 +227,6 @@ Clients must update to use Authorization: Bearer <token> header."
 
 ---
 
----
 
 ## 🛠️ Common Git Commands
 

From 3696de3aecd92c303b9d5c0a66a3aa418d758f27 Mon Sep 17 00:00:00 2001
From: "Viktor H. Ingre" <viktor.ingre@codeoof.com>
Date: Mon, 8 Dec 2025 08:37:58 +0100
Subject: [PATCH 6/8] Update docs/git-auto-release/QUICK_REFERENCE.md

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
---
 docs/git-auto-release/QUICK_REFERENCE.md | 2 --
 1 file changed, 2 deletions(-)

diff --git a/docs/git-auto-release/QUICK_REFERENCE.md b/docs/git-auto-release/QUICK_REFERENCE.md
index 3d2f30b..c799279 100644
--- a/docs/git-auto-release/QUICK_REFERENCE.md
+++ b/docs/git-auto-release/QUICK_REFERENCE.md
@@ -169,8 +169,6 @@ git push origin hotfix
 
 ---
 
----
-
 ## ✍️ Commit Message Format
 
 ```

From 943864d2050f7679888dcec7fd4e9d5462ea37a6 Mon Sep 17 00:00:00 2001
From: "Viktor H. Ingre" <viktor.ingre@codeoof.com>
Date: Tue, 9 Dec 2025 08:23:48 +0100
Subject: [PATCH 7/8] docs: restructure documentation and clarify major beta
 release behavior

- Merged SUMMARY.md into REFERENCE_GUIDE.md for comprehensive single reference
- Renamed QUICK_REFERENCE.md to REFERENCE_GUIDE.md to reflect comprehensive content
- Updated all cross-references across documentation files
- Clarified major beta release (X.0.0-beta) vs regular beta tags distinction
- Added detailed FAQ about handling breaking changes during major beta
- Updated PROJECT_STRUCTURE.md to reflect actual current file structure
- Removed duplicate commit message documentation from QUICKSTART and BRANCH_STRATEGY
- Added LICENSE file to docs/git-auto-release/
- Consolidated documentation for single source of truth

Key clarification: .N increments only apply during major beta releases (VERSION = X.0.0-beta).
Regular feature/bugfix merges continue to create normal beta version tags (e.g., v0.2.0-beta, v0.1.1-beta).
---
 docs/git-auto-release/BRANCH_STRATEGY.md   |  48 +-
 docs/git-auto-release/CUSTOMIZATION.md     |   2 +-
 docs/git-auto-release/PROJECT_STRUCTURE.md | 176 +++--
 docs/git-auto-release/QUICKSTART.md        |  15 +-
 docs/git-auto-release/QUICK_REFERENCE.md   | 465 ------------
 docs/git-auto-release/README.md            |  12 +-
 docs/git-auto-release/REFERENCE_GUIDE.md   | 821 +++++++++++++++++++++
 docs/git-auto-release/SUMMARY.md           | 200 -----
 docs/git-auto-release/WORKFLOW_EXAMPLES.md |  34 +-
 9 files changed, 985 insertions(+), 788 deletions(-)
 delete mode 100644 docs/git-auto-release/QUICK_REFERENCE.md
 create mode 100644 docs/git-auto-release/REFERENCE_GUIDE.md
 delete mode 100644 docs/git-auto-release/SUMMARY.md

diff --git a/docs/git-auto-release/BRANCH_STRATEGY.md b/docs/git-auto-release/BRANCH_STRATEGY.md
index 8103914..145be82 100644
--- a/docs/git-auto-release/BRANCH_STRATEGY.md
+++ b/docs/git-auto-release/BRANCH_STRATEGY.md
@@ -132,9 +132,12 @@ The CI/CD pipeline (`.github/workflows/ci-cd-versioned.yml`) **automatically** c
 #### Version Bump Logic
 - **Major bump**: When `alpha` branch merges to `main` → `vX.Y.Z` becomes `vX+1.0.0-alpha` (automatic tag created)
   - Then create `beta` branch from main for stabilization
-  - `beta` → `main` merge adds `-beta` suffix to already-bumped version
+  - `beta` → `main` merge adds `-beta` suffix to already-bumped version → `vX.0.0-beta` (major beta release)
 - **Minor bump**: When `feature/*` branch merges to `main` → `vX.Y.Z` becomes `vX.Y+1.0-beta` (automatic tag)
-- **Patch bump**: When `bugfix/*` merges to `main` or `hotfix` merges to `release` → `vX.Y.Z` becomes `vX.Y.Z+1` (automatic tag)
+- **Patch bump**: When `bugfix/*` merges to `main` or `hotfix` merges to `release` → `vX.Y.Z` becomes `vX.Y.Z+1-beta` (automatic tag)
+- **Build metadata increment (.N)**: During **major beta release** (VERSION = `X.0.0-beta`), ANY merge to main (`feature/*` OR `bugfix/*`) increments build metadata → `vX.0.0-beta.N` (e.g., `v1.0.0-beta.1`, `v1.0.0-beta.2`)
+  - **Important**: During major beta, there can be NO additional major/minor bumps until released
+  - **Alpha merges during major beta are NOT allowed** - breaking changes require releasing current major version first, then starting new major cycle
 
 
 #### VERSION File Usage
@@ -144,8 +147,10 @@ The CI/CD pipeline (`.github/workflows/ci-cd-versioned.yml`) **automatically** c
 - **Note**: `-rc` suffix appears during PRs to `release` branch and is temporarily persisted to VERSION during merge, then becomes clean version
 - **Automatically updated by CI/CD** after successful merges:
   - `alpha` → `main`: VERSION becomes `X+1.0.0-alpha`
-  - `feature/*` → `main`: VERSION becomes `X.Y+1.0-beta`
-  - `bugfix/*` → `main`: VERSION becomes `X.Y.Z+1-beta`
+  - `beta` branch → `main`: VERSION becomes `X.0.0-beta` (major beta release)
+  - `feature/*` → `main`: VERSION becomes `X.Y+1.0-beta` (regular feature beta tag)
+  - `bugfix/*` → `main`: VERSION becomes `X.Y.Z+1-beta` (regular bugfix beta tag)
+  - ANY merge → `main` during **major beta** (VERSION = `X.0.0-beta`): VERSION becomes `X.0.0-beta.N` (build metadata increment)
   - `hotfix` → `release`: VERSION becomes `X.Y.Z+1-rc.N` then `X.Y.Z+1` (clean)
   - `main` → `release`: VERSION becomes `X.Y.Z-rc.N` then `X.Y.Z` (clean)
 - **No manual intervention required** - CI/CD manages VERSION throughout entire release lifecycle
@@ -160,19 +165,23 @@ The CI/CD pipeline (`.github/workflows/ci-cd-versioned.yml`) **automatically** c
 | `beta` (push) | `vX.Y.Z-alpha+SHA` | - | `v1.0.0-alpha+8d92k127` |
 | `beta` (merged to main) | - | `vX.Y.Z-beta` | `v1.0.0-beta` (VERSION becomes 1.0.0-beta) |
 | `feature/*` (push) | `vX.Y.Z+SHA` | - | `v0.1.0+21AF26D3` |
-| `feature/*` (merged to main) | - | `vX.Y+1.0-beta` | `v0.2.0-beta` (VERSION becomes 0.2.0-beta)  |
+| `feature/*` (merged to main) | - | `vX.Y+1.0-beta` | `v0.2.0-beta` (VERSION becomes 0.2.0-beta) **normal version bump**  |
+| `feature/*` (merged to main during major beta) | - | `vX.0.0-beta.N` | `v1.0.0-beta.1` (VERSION becomes 1.0.0-beta.1) **if VERSION=1.0.0-beta** |
 | `bugfix/*` (push) | `vX.Y.Z+SHA` | - | `v0.1.0+21AF26D3` |
-| `bugfix/*` (merged to main) | - | `vX.Y.Z+1-beta` | `v0.1.1-beta` (VERSION becomes 0.1.1-beta) |
+| `bugfix/*` (merged to main) | - | `vX.Y.Z+1-beta` | `v0.1.1-beta` (VERSION becomes 0.1.1-beta) **normal version bump** |
+| `bugfix/*` (merged to main during major beta) | - | `vX.0.0-beta.N` | `v1.0.0-beta.2` (VERSION becomes 1.0.0-beta.2) **if VERSION=1.0.0-beta.N** |
 | `hotfix` (push) | `vX.Y.Z-hotfix.N` | - | `v0.1.0-hotfix.1` |
 | `hotfix` (merged to release) | `vX.Y.Z+1-rc.N` | `vX.Y.Z+1` | `v0.1.1-rc.1` → `v0.1.1` (VERSION becomes 0.1.1-rc.1 -> 0.1.1) |
 | `main` (merged to release) | `vX.Y.Z-rc.N` | `vX.Y.Z` | `v0.1.0-rc.1` → `v0.1.0` (VERSION becomes 0.1.0-rc.1 -> 0.1.0) |
 
 **Version Bumping Philosophy**:
 - **Automatic**: CI/CD detects PR source branch and bumps MAJOR (from `alpha`→main), MINOR (from `feature/*`→main), or PATCH (from `bugfix/*`→main or `hotfix`→release)
+- **Major Beta Rule**: During **major beta release** (VERSION = `X.0.0-beta` from beta branch merge), ALL merges to main (feature OR bugfix) increment build metadata (.N) instead of bumping version - no new major/minor bumps allowed until released to production
+- **Regular Beta Tags**: Feature and bugfix merges outside of major beta releases continue to bump versions normally with `-beta` suffix (e.g., `v0.2.0-beta`, `v0.3.0-beta`, `v0.1.1-beta`)
 - **Automatic**: `VERSION` file updated by CI/CD after every merge to `main` or `release` with appropriate suffix (-alpha, -beta, -rc, or clean)
-- **Build metadata**: SHA and pre-release identifiers appended automatically
+- **Build metadata**: SHA and pre-release identifiers appended automatically; `.N` increments during major beta refinement
 - **Full automation**: No manual VERSION updates needed at any stage
-- **Major flow**: alpha→main auto-bumps and tags vX+1.0.0-alpha, updates VERSION to `X+1.0.0-alpha` → create beta branch → stabilize → beta→main tags vX+1.0.0-beta, updates VERSION to `X+1.0.0-beta` → main→release tags vX+1.0.0, updates VERSION to `X+1.0.0`
+- **Major flow**: alpha→main auto-bumps and tags vX+1.0.0-alpha, updates VERSION to `X+1.0.0-alpha` → create beta branch → stabilize → beta→main tags vX+1.0.0-beta, updates VERSION to `X+1.0.0-beta` → ANY merge to main during beta becomes vX+1.0.0-beta.N → main→release tags vX+1.0.0, updates VERSION to `X+1.0.0`
 
 #### 🎯 Version Bump Decision Tree
 
@@ -394,29 +403,6 @@ git push origin beta
 
 ---
 
-## Commit Messages
-
-Format: `type(scope): description (REQ-ID)`
-
-**Types**:
-- `feat`: New feature
-- `fix`: Bug fix
-- `docs`: Documentation
-- `test`: Tests
-- `refactor`: Code restructuring
-- `chore`: Maintenance
-
-**Examples**:
-```
-feat(auth): add LDAP authentication mode (FR-02)
-fix(api): handle null JWT claims (SEC-01)
-test(auth): add token expiration tests (SEC-02)
-docs(readme): update deployment instructions
-refactor(auth): simplify mode switching logic
-```
-
----
-
 ## Release Process
 
 ### Production Release
diff --git a/docs/git-auto-release/CUSTOMIZATION.md b/docs/git-auto-release/CUSTOMIZATION.md
index edd53e8..7820331 100644
--- a/docs/git-auto-release/CUSTOMIZATION.md
+++ b/docs/git-auto-release/CUSTOMIZATION.md
@@ -1,6 +1,6 @@
 # Customization Guide
 
-📖 **Navigation**: [← README](../README.md) | [Branch Strategy](../BRANCH_STRATEGY.md) | [Workflow Examples](WORKFLOW_EXAMPLES.md) | **Customization Guide** | [Quick Reference →](QUICK_REFERENCE.md)
+📖 **Navigation**: [← README](../README.md) | [Branch Strategy](../BRANCH_STRATEGY.md) | [Workflow Examples](WORKFLOW_EXAMPLES.md) | **Customization Guide** | [Reference Guide →](REFERENCE_GUIDE.md)
 
 Learn how to adapt the Git-Auto-Release template to different CI/CD platforms and customize the automation pipeline.
 
diff --git a/docs/git-auto-release/PROJECT_STRUCTURE.md b/docs/git-auto-release/PROJECT_STRUCTURE.md
index 0b13209..7c84759 100644
--- a/docs/git-auto-release/PROJECT_STRUCTURE.md
+++ b/docs/git-auto-release/PROJECT_STRUCTURE.md
@@ -4,17 +4,25 @@
 Git-Auto-Release/
 ├── .github/
 │   └── workflows/
-│       └── ci-cd-versioned.yml    # Main CI/CD workflow
+│       └── ci-cd-versioned.yml          # Main CI/CD workflow
 ├── docs/
-│   ├── README.md                  # Documentation index
-│   ├── SETUP_GUIDE.md            # Complete setup instructions
-│   ├── WORKFLOW_EXAMPLES.md      # Real-world usage examples
-│   ├── CUSTOMIZATION.md          # How to customize the template
-│   └── QUICK_REFERENCE.md        # Daily usage cheat sheet
-├── BRANCH_STRATEGY.md            # Detailed branch strategy
-├── LICENSE                       # MIT License
-├── README.md                     # Main project documentation
-└── VERSION                       # Current version (e.g., 0.1.0)
+│   └── git-auto-release/
+│       ├── BRANCH_STRATEGY.md           # Detailed branch strategy
+│       ├── CUSTOMIZATION.md             # How to customize the template
+│       ├── LICENSE                      # MIT License (template license)
+│       ├── PROJECT_STRUCTURE.md         # This file - project structure guide
+│       ├── QUICKSTART.md                # 5-minute initial setup guide
+│       ├── README.md                    # Documentation index
+│       ├── REFERENCE_GUIDE.md           # Comprehensive reference guide
+│       ├── SETUP_GUIDE.md               # Complete setup instructions
+│       └── WORKFLOW_EXAMPLES.md         # Real-world usage examples
+├── CHECKLIST.md                         # Pre-release checklist
+├── CONTRIBUTING.md                      # Contribution guidelines
+├── CONTRIBUTING.template.md             # Template for user projects
+├── LICENSE                              # MIT License (repository license)
+├── README.md                            # Main project documentation
+├── README.template.md                   # Template for user projects
+└── VERSION                              # Current version (e.g., 1.0.0-beta)
 ```
 
 ---
@@ -39,15 +47,24 @@ Git-Auto-Release/
   - Setup instructions
   - FAQ
 
-#### `BRANCH_STRATEGY.md`
-- **Purpose**: Detailed branch strategy documentation
+#### `CHECKLIST.md`
+- **Purpose**: Pre-release checklist
+- **Location**: Root directory
+- **Usage**: Verify all steps before major releases
+
+#### `CONTRIBUTING.md` & `CONTRIBUTING.template.md`
+- **Purpose**: Contribution guidelines (template provides starting point for user projects)
+- **Location**: Root directory
 - **Contents**:
-  - Branch types and purposes
-  - Version bump logic
-  - Release flows (major, minor, patch, hotfix)
-  - Mermaid diagrams
-  - Commit message conventions
-  - Workflow details
+  - Code of conduct
+  - Development workflow
+  - PR process
+  - Branch strategy reference
+
+#### `README.template.md`
+- **Purpose**: Template README for user projects
+- **Location**: Root directory
+- **Usage**: Copy and customize for your project
 
 #### `LICENSE`
 - **Purpose**: MIT License
@@ -122,35 +139,54 @@ Git-Auto-Release/
   - Deployment integration
   - Branch strategy adjustments
 
-#### `QUICK_REFERENCE.md`
-- **Purpose**: Daily usage command cheat sheet (for established projects)
+#### `QUICKSTART.md`
+- **Purpose**: Fast 5-minute initial setup guide
+- **Location**: docs/git-auto-release/
+- **Contents**:
+  - Quick repository setup
+  - Essential commands
+  - Basic commit format
+  - Next steps
+- **Note**: For daily usage reference, see `REFERENCE_GUIDE.md`
+
+#### `REFERENCE_GUIDE.md`
+- **Purpose**: Comprehensive reference guide (for established projects)
+- **Location**: docs/git-auto-release/
 - **Contents**:
+  - What is this template?
+  - Key features and use cases
   - Decision tree for daily tasks
   - Workflow commands (feature, bugfix, hotfix, release)
   - Version progression tables
-  - Commit message examples
+  - Commit message format (Conventional Commits)
   - Git command reference
   - Troubleshooting quick fixes
-- **Note**: For initial setup, see `QUICKSTART.md`
+  - FAQ (13+ common questions)
+  - Customization points
+  - License & support
 
----
+#### `BRANCH_STRATEGY.md`
+- **Purpose**: Detailed branch strategy documentation
+- **Location**: docs/git-auto-release/
+- **Contents**:
+  - Branch types and purposes
+  - Version bump logic
+  - Release flows (major, minor, patch, hotfix)
+  - Mermaid diagrams
+  - Workflow details
+- **Note**: Commit message conventions are in `REFERENCE_GUIDE.md`
 
-#### `Dockerfile`
-- **Purpose**: Example Docker configuration
-- **Usage**: Copy and customize for your application
+#### `PROJECT_STRUCTURE.md`
+- **Purpose**: This file - explains project organization
+- **Location**: docs/git-auto-release/
+- **Contents**: File structure, descriptions, and relationships
+
+#### `LICENSE`
+- **Purpose**: MIT License for the template itself
+- **Location**: docs/git-auto-release/
+- **Note**: Your projects can use any license you choose
 
-#### `.gitignore`
-- **Purpose**: Recommended Git ignore patterns
-- **Usage**: Copy to your project root
 
-#### `CONTRIBUTING.md`
-- **Purpose**: Template for contribution guidelines
-- **Contents**:
-  - Code of conduct
-  - Development workflow
-  - Commit message guidelines
-  - PR process
-  - Branch strategy for contributors
 
 ---
 
@@ -193,13 +229,16 @@ GitHub Releases (artifacts)
 ```
 README.md (overview)
     ├── Quick start
-    ├── → BRANCH_STRATEGY.md (detailed strategy)
-    └── → docs/
-        ├── QUICKSTART.md (initial setup)
+    └── → docs/git-auto-release/
+        ├── README.md (documentation index)
+        ├── QUICKSTART.md (5-minute setup)
+        ├── REFERENCE_GUIDE.md (comprehensive reference + FAQ)
+        ├── BRANCH_STRATEGY.md (detailed strategy)
         ├── SETUP_GUIDE.md (detailed configuration)
         ├── WORKFLOW_EXAMPLES.md (step-by-step scenarios)
         ├── CUSTOMIZATION.md (advanced customization)
-        └── QUICK_REFERENCE.md (daily usage cheat sheet)
+        ├── PROJECT_STRUCTURE.md (this file)
+        └── LICENSE (template license)
 ```
 
 ---
@@ -209,24 +248,25 @@ README.md (overview)
 ### For Template Users
 
 1. **Read**: `README.md` for overview
-2. **Setup**: `docs/QUICKSTART.md` for fast initial setup (5 min)
-3. **Configure**: `docs/SETUP_GUIDE.md` for detailed configuration
-4. **Daily Use**: `docs/QUICK_REFERENCE.md` for commands and workflows
+2. **Setup**: `docs/git-auto-release/QUICKSTART.md` for fast initial setup (5 min)
+3. **Reference**: `docs/git-auto-release/REFERENCE_GUIDE.md` for daily commands and FAQ
+4. **Configure**: `docs/git-auto-release/SETUP_GUIDE.md` for detailed configuration
 5. **Customize**: `.github/workflows/ci-cd-versioned.yml` as needed
 
 ### For Contributors
 
-1. **Read**: `CONTRIBUTING.md`
-2. **Reference**: `BRANCH_STRATEGY.md`
-3. **Follow**: Commit conventions
-4. **Use**: `docs/QUICK_REFERENCE.md` for daily commands
+1. **Read**: `CONTRIBUTING.md` (root directory)
+2. **Reference**: `docs/git-auto-release/BRANCH_STRATEGY.md`
+3. **Follow**: Commit conventions in `docs/git-auto-release/REFERENCE_GUIDE.md`
+4. **Use**: `docs/git-auto-release/REFERENCE_GUIDE.md` for daily commands
 
 ### For Maintainers
 
-1. **Understand**: `BRANCH_STRATEGY.md` thoroughly
+1. **Understand**: `docs/git-auto-release/BRANCH_STRATEGY.md` thoroughly
 2. **Monitor**: GitHub Actions workflows
 3. **Review**: PRs according to strategy
 4. **Manage**: VERSION file (automatic)
+5. **Check**: `CHECKLIST.md` before major releases
 
 ---
 
@@ -234,15 +274,15 @@ README.md (overview)
 
 ### Must Customize
 
-1. **README.md**: Update project name, description, badges
-2. **ci-cd-versioned.yml**: Adjust build/test commands
-3. **CONTRIBUTING.md**: Update project-specific details
+1. **README.md**: Use `README.template.md` as starting point
+2. **.github/workflows/ci-cd-versioned.yml**: Adjust build/test commands
+3. **CONTRIBUTING.md**: Use `CONTRIBUTING.template.md` for your project
 
 ### Optional Customization
 
-1. **ci-cd-versioned.yml**: Docker builds, deployment steps
-2. **BRANCH_STRATEGY.md**: Adjust to your team's needs
-3. **VERSION**: Set initial version
+1. **.github/workflows/ci-cd-versioned.yml**: Docker builds, deployment steps
+2. **docs/git-auto-release/BRANCH_STRATEGY.md**: Adjust to your team's needs
+3. **VERSION**: Set initial version (default: 1.0.0-beta)
 
 ### Usually Keep As-Is
 
@@ -263,13 +303,14 @@ README.md (overview)
 ### Updated by Maintainers
 
 - `README.md` - Project-specific updates
-- `BRANCH_STRATEGY.md` - Strategy adjustments
-- `docs/*.md` - Documentation improvements
-- `ci-cd-versioned.yml` - Workflow enhancements
+- `docs/git-auto-release/*.md` - Documentation improvements
+- `.github/workflows/ci-cd-versioned.yml` - Workflow enhancements
+- `CHECKLIST.md` - Pre-release checklist updates
 
 ### Updated by Contributors
 
-- `docs/*.md` - Documentation fixes/improvements
+- `docs/git-auto-release/*.md` - Documentation fixes/improvements
+- `CONTRIBUTING.md` - Contribution guideline improvements
 
 ---
 
@@ -277,9 +318,10 @@ README.md (overview)
 
 ### Adding New Documentation
 
-1. Create file in `docs/`
-2. Link from `docs/README.md`
+1. Create file in `docs/git-auto-release/`
+2. Link from `docs/git-auto-release/README.md`
 3. Link from main `README.md` if relevant
+4. Update `PROJECT_STRUCTURE.md` to document it
 
 ### Adding New Workflows
 
@@ -300,11 +342,13 @@ README.md (overview)
 
 ## Quick Navigation
 
-- **Getting Started**: [README.md](README.md)
-- **Fast Setup**: [docs/QUICKSTART.md](QUICKSTART.md) - 5 minute setup
-- **Detailed Setup**: [docs/SETUP_GUIDE.md](SETUP_GUIDE.md) - Full configuration
-- **Daily Usage**: [docs/QUICK_REFERENCE.md](QUICK_REFERENCE.md) - Command cheat sheet
-- **Customization**: [docs/CUSTOMIZATION.md](CUSTOMIZATION.md) - Advanced topics
+- **Getting Started**: [README.md](../../README.md) - Main overview
+- **Documentation Index**: [docs/git-auto-release/README.md](README.md)
+- **Fast Setup**: [QUICKSTART.md](QUICKSTART.md) - 5 minute setup
+- **Daily Usage**: [REFERENCE_GUIDE.md](REFERENCE_GUIDE.md) - Comprehensive reference + FAQ
+- **Branch Strategy**: [BRANCH_STRATEGY.md](BRANCH_STRATEGY.md) - Detailed branching model
+- **Detailed Setup**: [SETUP_GUIDE.md](SETUP_GUIDE.md) - Full configuration
+- **Customization**: [CUSTOMIZATION.md](CUSTOMIZATION.md) - Advanced topics
 
 ---
 
diff --git a/docs/git-auto-release/QUICKSTART.md b/docs/git-auto-release/QUICKSTART.md
index 4b6b239..6dd803f 100644
--- a/docs/git-auto-release/QUICKSTART.md
+++ b/docs/git-auto-release/QUICKSTART.md
@@ -146,25 +146,22 @@ git push origin bugfix/fix-issue
 
 ## Commit Format
 
-Use [Conventional Commits](https://www.conventionalcommits.org/):
+Use structured commit messages for clarity:
 
 ```
-<type>: <description>
+<type>(scope): <description>
 ```
 
-**Types:**
-- `feat:` - New feature (MINOR bump)
-- `fix:` - Bug fix (PATCH bump)
-- `docs:` - Documentation
-- `chore:` - Maintenance
-- `test:` - Tests
+**Example**: `feat(auth): add OAuth2 support`
+
+> 📖 **For detailed commit guidelines, types, and examples**, see [Reference Guide - Commit Message Format](REFERENCE_GUIDE.md#️-commit-message-format)
 
 ---
 
 ## Next Steps
 
+- ⚡ [Reference Guide](REFERENCE_GUIDE.md) - Daily workflow commands and FAQ
 - 📚 [Branch Strategy](BRANCH_STRATEGY.md) - Detailed branching model
-- ⚡ [Quick Reference](QUICK_REFERENCE.md) - Daily workflow commands (after setup)
 - 🎨 [Customization](CUSTOMIZATION.md) - Adapt to your stack
 - 📋 [Workflow Examples](WORKFLOW_EXAMPLES.md) - Real scenarios
 
diff --git a/docs/git-auto-release/QUICK_REFERENCE.md b/docs/git-auto-release/QUICK_REFERENCE.md
deleted file mode 100644
index c799279..0000000
--- a/docs/git-auto-release/QUICK_REFERENCE.md
+++ /dev/null
@@ -1,465 +0,0 @@
-# Quick Reference Guide
-
-📖 **Navigation**: [← README](README.md) | [Quickstart](QUICKSTART.md) | **Quick Reference**
-
-> **🎯 For initial setup**, see [QUICKSTART.md](QUICKSTART.md)  
-> **This guide is for daily usage** after Git-Auto-Release is established in your project.
-
----
-
-## 🚀 Quick Decision Tree
-
-**What do you need to do today?**
-
-```mermaid
-flowchart TD
-    Start{What's your task?}
-    
-    Feature[Add a feature]
-    Bug[Fix a bug]
-    Breaking[Breaking change]
-    Emergency[Production emergency]
-    
-    Start --> Feature
-    Start --> Bug
-    Start --> Breaking
-    Start --> Emergency
-    
-    Feature -->|feature/* from main| FeatureFlow[Create feature/* branch<br/>Commit with feat:<br/>PR to main → MINOR bump]
-    Bug -->|bugfix/* from main| BugFlow[Create bugfix/* branch<br/>Commit with fix:<br/>PR to main → PATCH bump]
-    Breaking -->|alpha from main| BreakingFlow[Work on alpha branch<br/>Commit with feat!:<br/>PR to main → MAJOR bump]
-    Emergency -->|hotfix from release| EmergencyFlow[Create hotfix branch<br/>Commit with fix:<br/>PR to release → PATCH bump]
-    
-    style Start fill:#3498db,color:#fff
-    style Feature fill:#2ecc71,color:#fff
-    style Bug fill:#f39c12,color:#fff
-    style Breaking fill:#9b59b6,color:#fff
-    style Emergency fill:#e74c3c,color:#fff
-```
-
-**Quick links to detailed workflows:**
-- 🎨 [Feature Development](WORKFLOW_EXAMPLES.md#1-feature-development)
-- 🐛 [Bug Fixes](WORKFLOW_EXAMPLES.md#2-bug-fixes)
-- 💥 [Breaking Changes](WORKFLOW_EXAMPLES.md#4-major-release-breaking-changes)
-- 🚨 [Hotfix Emergency](WORKFLOW_EXAMPLES.md#7-hotfix-production-emergency)
-
----
-
-## 📋 Daily Workflow Commands
----
-
-## 📋 Daily Workflow Commands
-
-### Feature Development (MINOR bump)
-
-```bash
-# Start feature
-git checkout main
-git pull origin main
-git checkout -b feature/my-awesome-feature
-
-# Work and commit (use conventional commits)
-git add .
-git commit -m "feat(module): add awesome feature"
-
-# Push and create PR to main
-git push origin feature/my-awesome-feature
-# Create PR: feature/my-awesome-feature → main
-```
-
-**Result after merge**: `v0.2.0-beta` tag created, VERSION updated
-
----
-
-### Bug Fix (PATCH bump)
-
-```bash
-# Start bugfix
-git checkout main
-git pull origin main
-git checkout -b bugfix/fix-critical-issue
-
-# Work and commit
-git add .
-git commit -m "fix(module): resolve critical issue"
-
-# Push and create PR to main
-git push origin bugfix/fix-critical-issue
-# Create PR: bugfix/fix-critical-issue → main
-```
-
-**Result after merge**: `v0.1.1-beta` tag created, VERSION updated
-
----
-
-### Production Release
-
-```bash
-# Release tested beta to production
-# Create PR: main → release
-
-# On GitHub:
-# 1. Create PR from main to release
-# 2. Get 2 approvals (review carefully!)
-# 3. Merge PR
-```
-
-**Result after merge**: `v0.2.0` tag created, GitHub Release published, VERSION updated
-
----
-
-### Hotfix Emergency (PATCH bump)
-
-```bash
-# Start hotfix from release
-git checkout release
-git pull origin release
-git checkout -b hotfix
-
-# Fix and commit
-git add .
-git commit -m "fix(critical): emergency production fix"
-
-# Push and create PR to release
-git push origin hotfix
-# Create PR: hotfix → release
-```
-
-**Result after merge**: 
-- `v1.0.1` tag created and released
-- VERSION updated
-- Changes auto-sync to main and all active branches
-
----
-
-## 📊 Version Progression Cheat Sheet
-
-### Standard Version Bumps
-
-| Merge Action | Current | Next Version | Tag Created | Notes |
-|--------------|---------|--------------|-------------|-------|
-| feature/* → main | 0.1.0 | 0.2.0-beta | v0.2.0-beta | MINOR bump |
-| bugfix/* → main | 0.1.0 | 0.1.1-beta | v0.1.1-beta | PATCH bump |
-| main → release | 1.0.0-beta | 1.0.0 | v1.0.0 | Production release |
-| hotfix → release | 1.0.0 | 1.0.1 | v1.0.1 | Emergency fix |
-
-### Major Release Progression
-
-| Step | Merge Action | Version Created | Tag | Branch Created |
-|------|--------------|-----------------|-----|----------------|
-| 1 | alpha → main | 1.0.0-alpha | v1.0.0-alpha | beta (auto) |
-| 2 | beta → main | 1.0.0-beta | v1.0.0-beta | - |
-| 3 | main → release | 1.0.0 | v1.0.0 | - |
-
-### Beta Refinement (During Major Release)
-
-| Merge Action | Current | Next Version | Tag Created |
-|--------------|---------|--------------|-------------|
-| bugfix/* → main | 1.0.0-beta | 1.0.0-beta.1 | v1.0.0-beta.1 |
-| bugfix/* → main | 1.0.0-beta.1 | 1.0.0-beta.2 | v1.0.0-beta.2 |
-
-### Build Versions (Development, No Tags)
-
-| Branch Type | Version Format | Example |
-|-------------|----------------|---------|
-| feature/* | base+commit | v0.1.0+c8d92a14 |
-| bugfix/* | base+commit | v0.1.0+f14e2c91 |
-| alpha | base+commit | v0.1.0+a3f2b1c8 |
-| hotfix | base-hotfix.N | v1.0.0-hotfix.1 |
-
----
-
-## ✍️ Commit Message Format
-
-```
-type(scope): short description
-
-[optional body explaining what and why]
-
-[optional footer with breaking changes or issue refs]
-```
-
-### Commit Types Reference
-
-| Type | Use For | Example |
-|------|---------|---------|
-| `feat` | New features | `feat(auth): add OAuth2 support` |
-| `fix` | Bug fixes | `fix(api): handle null responses correctly` |
-| `feat!` | Breaking changes | `feat!(api): redesign REST endpoints to GraphQL` |
-| `docs` | Documentation only | `docs(readme): update installation instructions` |
-| `style` | Code formatting | `style(app): fix indentation in main.js` |
-| `refactor` | Code restructuring | `refactor(auth): simplify token validation` |
-| `perf` | Performance improvements | `perf(db): optimize query performance` |
-| `test` | Adding tests | `test(auth): add token validation tests` |
-| `chore` | Maintenance tasks | `chore(deps): update dependencies` |
-
-### More Examples
-
-```bash
-# Feature with details
-git commit -m "feat(dashboard): add user analytics chart
-
-- Added chart component with D3.js
-- Integrated with analytics API
-- Added date range selector"
-
-# Bug fix with issue reference
-git commit -m "fix(login): prevent duplicate submissions
-
-Closes #123"
-
-# Breaking change with migration notes
-git commit -m "feat!(api): change authentication to JWT
-
-BREAKING CHANGE: API now requires JWT tokens instead of API keys.
-Clients must update to use Authorization: Bearer <token> header."
-```
-
-> **💡 Important**: Version bumps are determined by **branch type**, not commit messages!
-> - `feature/*` → main = MINOR bump
-> - `bugfix/*` → main = PATCH bump  
-> - `alpha` → main = MAJOR bump
-> - `hotfix` → release = PATCH bump
->
-> Use conventional commits for clarity and changelog generation, not versioning control.
-
----
-
-
-## 🛠️ Common Git Commands
-
-### Branch Management
-
-```bash
-# View all branches (local and remote)
-git branch -a
-
-# Switch branches and pull latest
-git checkout main
-git pull origin main
-
-# Delete merged feature branch
-git branch -d feature/my-feature
-git push origin --delete feature/my-feature
-
-# Sync your fork with upstream
-git fetch upstream
-git checkout main
-git merge upstream/main
-```
-
-### Tag Operations
-
-```bash
-# View all tags
-git tag -l
-
-# View tags matching pattern
-git tag -l "v1.*"
-
-# Fetch latest tags from remote
-git fetch --tags
-
-# View tag details
-git show v1.0.0
-
-# Checkout specific tag
-git checkout v1.0.0
-```
-
-### Commit History
-
-```bash
-# View pretty commit history
-git log --oneline --graph --all
-
-# View commits by author
-git log --author="YourName"
-
-# View commits in date range
-git log --since="2024-01-01" --until="2024-12-31"
-
-# Search commits by message
-git log --grep="fix(auth)"
-
-# View file history
-git log --follow -- path/to/file
-```
-
-### Undoing Changes
-
-```bash
-# Undo last commit (keep changes staged)
-git reset --soft HEAD~1
-
-# Undo last commit (keep changes unstaged)
-git reset HEAD~1
-
-# Discard local changes to file
-git checkout -- path/to/file
-
-# Discard all local changes
-git reset --hard HEAD
-
-# Amend last commit message
-git commit --amend -m "new message"
-
-# Amend last commit (add forgotten files)
-git add forgotten-file.txt
-git commit --amend --no-edit
-```
-
-### Interactive Rebase (Clean Up Commits)
-
-```bash
-# Squash last 3 commits before PR
-git rebase -i HEAD~3
-
-# In the editor:
-# - Change 'pick' to 'squash' for commits to combine
-# - Save and close
-# - Edit combined commit message
-```
-
----
-
----
-
-## 🔧 Troubleshooting Quick Fixes
-
-### Workflow Not Running
-
-```bash
-# 1. Verify workflow file exists
-ls .github/workflows/ci-cd-versioned.yml
-
-# 2. Check GitHub Actions is enabled
-# Go to: Settings → Actions → General → Enable
-
-# 3. Check branch protection allows workflow
-# Settings → Branches → Edit protection rules
-```
-
-### Wrong Version Calculated
-
-```bash
-# Check current VERSION
-cat VERSION
-
-# Verify branch name pattern
-git branch --show-current
-
-# Expected patterns:
-# - feature/name  → MINOR bump
-# - bugfix/name   → PATCH bump  
-# - alpha         → MAJOR bump
-# - hotfix        → PATCH bump
-
-# View CI logs for version calculation
-# GitHub → Actions → Latest run → Calculate Version job
-```
-
-### Merge Conflicts in VERSION
-
-```bash
-# Always choose the higher version
-git checkout --theirs VERSION
-git add VERSION
-git commit
-
-# Or manually edit VERSION to higher number
-echo "1.2.3" > VERSION
-git add VERSION
-git commit
-```
-
-### Tag Already Exists
-
-```bash
-# Delete tag locally
-git tag -d v1.0.0
-
-# Delete tag remotely
-git push origin :refs/tags/v1.0.0
-
-# Force push the corrected commit
-# (Only if safe to do so!)
-git push --force-with-lease
-```
-
-### CI Tests Fail
-
-```bash
-# Run tests locally first
-npm test
-# or
-python -m pytest
-# or
-cargo test
-
-# Check specific job logs
-# GitHub → Actions → Failed run → Click failing job
-
-# Re-run failed jobs
-# GitHub → Actions → Failed run → Re-run failed jobs
-```
-
-### Branch Protection Blocks Merge
-
-```bash
-# Ensure all required checks pass
-# - Build & Test must be green
-# - Calculate Version must complete
-# - Required reviews must be approved
-# - All conversations must be resolved
-
-# View protection rules
-# Settings → Branches → Branch protection rules
-```
-
----
-
-## 📁 Key Files Reference
-
-| File | Purpose | When to Edit |
-|------|---------|--------------|
-| `VERSION` | Current semantic version | Never manually (auto-updated by CI) |
-| `.github/workflows/ci-cd-versioned.yml` | CI/CD automation | When customizing workflow |
-| `BRANCH_STRATEGY.md` | Branch rules and flows | Reference only |
-| `README.md` | Project overview | Update for your project |
-
-> **⚠️ Warning**: Never manually edit `VERSION` file unless fixing a CI issue. The workflow manages it automatically.
-
----
-
-## 🔗 Documentation Links
-
-### Getting Started
-- 🚀 [Quickstart](QUICKSTART.md) - Initial setup (5 minutes)
-- 📘 [Setup Guide](SETUP_GUIDE.md) - Detailed configuration
-
-### Daily Usage  
-- ⚡ **Quick Reference** (this page) - Command cheat sheet
-- 📖 [Workflow Examples](WORKFLOW_EXAMPLES.md) - Step-by-step scenarios
-- 🌳 [Branch Strategy](BRANCH_STRATEGY.md) - Branch rules and flows
-
-### Advanced
-- 🎨 [Customization Guide](CUSTOMIZATION.md) - Adapt to your needs
-- 📂 [Project Structure](PROJECT_STRUCTURE.md) - File organization
-- 📋 [Summary](SUMMARY.md) - High-level overview
-
----
-
-## 💡 Pro Tips
-
-1. **Commit Often**: Small, focused commits are easier to review and revert
-2. **Branch Names**: Use descriptive names like `feature/user-authentication` not `feature/fix`
-3. **PR Descriptions**: Link related issues with `Closes #123` or `Fixes #456`
-4. **Review Tags**: Check tags regularly with `git fetch --tags && git tag -l`
-5. **Test Locally**: Always run tests before pushing with `npm test` or equivalent
-6. **Clean Branches**: Delete merged branches to keep repo tidy
-7. **Read CI Logs**: When workflow fails, read the logs - they're usually clear about what's wrong
-
----
-
-**📌 Bookmark this page for daily reference!**
diff --git a/docs/git-auto-release/README.md b/docs/git-auto-release/README.md
index e9f4f44..faa102e 100644
--- a/docs/git-auto-release/README.md
+++ b/docs/git-auto-release/README.md
@@ -4,6 +4,8 @@
 
 Complete documentation for setting up and using automated Git versioning and releases.
 
+> **❓ Have questions?** Check the [FAQ in Reference Guide](REFERENCE_GUIDE.md#-frequently-asked-questions)
+
 ---
 
 ## 📚 Documentation Index
@@ -11,7 +13,8 @@ Complete documentation for setting up and using automated Git versioning and rel
 ### Getting Started
 - **[Quick Start Guide](QUICKSTART.md)** - Get up and running in 10 minutes
 - **[Setup Guide](SETUP_GUIDE.md)** - Complete installation and configuration
-- **[Quick Reference](QUICK_REFERENCE.md)** - Daily workflow commands and version cheat sheet (for established projects)
+- **[Reference Guide](REFERENCE_GUIDE.md)** - Comprehensive reference with daily workflow commands and version cheat sheet (for established projects)
+  - **[FAQ](REFERENCE_GUIDE.md#-frequently-asked-questions)** - Common questions and troubleshooting
 
 ### Core Concepts
 - **[Branch Strategy](BRANCH_STRATEGY.md)** - Detailed branching model and workflows
@@ -26,10 +29,7 @@ Complete documentation for setting up and using automated Git versioning and rel
 > - **Branch diagrams** in [Branch Strategy](BRANCH_STRATEGY.md)
 > - **Workflow flowcharts** in [Workflow Examples](WORKFLOW_EXAMPLES.md)
 > - **CI/CD architecture** in [Setup Guide](SETUP_GUIDE.md)
-> - **Quick decision tree** in [Quick Reference](QUICK_REFERENCE.md) (for daily usage)
-
-### Additional Resources
-- **[Summary](SUMMARY.md)** - Quick overview
+> - **Quick decision tree** in [Reference Guide](REFERENCE_GUIDE.md) (for daily usage)
 
 ---
 
@@ -180,7 +180,7 @@ You are free to use, modify, and distribute this template in any project (commer
 - 📖 Read the [Setup Guide](SETUP_GUIDE.md)
 - 🐛 Check [GitHub Issues](https://github.com/CodeOOf/Git-Auto-Release/issues)
 - 💬 Join [Discussions](https://github.com/CodeOOf/Git-Auto-Release/discussions)
-- ⚡ Use [Quick Reference](QUICK_REFERENCE.md) for daily workflow commands
+- ⚡ Use [Reference Guide](REFERENCE_GUIDE.md) for daily workflow commands
 
 ---
 
diff --git a/docs/git-auto-release/REFERENCE_GUIDE.md b/docs/git-auto-release/REFERENCE_GUIDE.md
new file mode 100644
index 0000000..372b36c
--- /dev/null
+++ b/docs/git-auto-release/REFERENCE_GUIDE.md
@@ -0,0 +1,821 @@
+# Reference Guide
+
+📖 **Navigation**: [← README](README.md) | [Quickstart](QUICKSTART.md) | **Reference Guide**
+
+**A comprehensive reference guide for Git-Auto-Release - fully automated semantic versioning and release management.**
+
+> **🎯 For initial setup**, see [QUICKSTART.md](QUICKSTART.md)  
+> **This guide is for daily usage** after Git-Auto-Release is established in your project.
+
+---
+
+## 📑 Table of Contents
+
+- [What Is This?](#-what-is-this)
+- [What You Get (Template Files)](#-what-you-get-template-files)
+- [Key Features](#-key-features)
+- [Quick Decision Tree](#-quick-decision-tree)
+- [Daily Workflow Commands](#-daily-workflow-commands)
+- [Version Progression Cheat Sheet](#-version-progression-cheat-sheet)
+- [Commit Message Format](#️-commit-message-format)
+- [Common Git Commands](#️-common-git-commands)
+- [Troubleshooting Quick Fixes](#-troubleshooting-quick-fixes)
+- [Key Files Reference](#-key-files-reference)
+- [Documentation Links](#-documentation-links)
+- [Common Use Cases](#-common-use-cases)
+- [Customization Points](#️-customization-points)
+- [Pro Tips](#-pro-tips)
+- [FAQ](#-frequently-asked-questions)
+- [License & Support](#-license--support)
+
+---
+
+## 🎯 What Is This?
+
+Git-Auto-Release automates your version control workflow using GitHub Actions:
+
+1. **Automatic Version Bumping**: MAJOR/MINOR/PATCH based on branch merges
+2. **Semantic Versioning**: Full semver 2.0.0 compliance with pre-release tags
+3. **Branch-Based Strategy**: Parallel branching model with clear promotion paths
+4. **Zero Maintenance**: No manual VERSION file edits or tag creation
+5. **Production Ready**: Includes GitHub Releases, changelogs, and optional Docker support
+
+---
+
+## 📁 What You Get (Template Files)
+
+When you use this template, you receive:
+
+```
+Your-Project/
+├── .github/workflows/
+│   └── ci-cd-versioned.yml          # Automated versioning workflow
+├── docs/git-auto-release/           # All template documentation (keep, archive, or remove)
+├── README.template.md              # Starter for your project README
+├── CONTRIBUTING.template.md        # Starter for your contribution guidelines
+├── CHECKLIST.md                    # Implementation checklist
+└── VERSION                         # Semantic version tracker (auto-managed)
+```
+
+**Note**: Template documentation is in `docs/git-auto-release/` - you can keep it for reference, move to archive, or delete once familiar.
+
+---
+
+## ✨ Key Features
+
+### Automated Versioning
+- ✅ **MAJOR bump**: `alpha` → `main` (breaking changes)
+- ✅ **MINOR bump**: `feature/*` → `main` (new features)
+- ✅ **PATCH bump**: `bugfix/*` → `main` (bug fixes)
+- ✅ **Pre-release tags**: `-alpha`, `-beta` suffixes
+- ✅ **Build metadata**: `+SHA` for dev builds
+
+### Branch Strategy
+- ✅ **Parallel branching**: All branches from `main` (except hotfix from `release`)
+- ✅ **Alpha branch**: For breaking changes only
+- ✅ **Beta branch**: Auto-created after alpha merge
+- ✅ **Release branch**: Production-ready code
+- ✅ **Hotfix support**: Emergency production fixes
+
+### CI/CD Automation
+- ✅ **Merge commit detection**: Supports both merge and squash merges
+- ✅ **VERSION file updates**: Automatic after PR merges
+- ✅ **Tag creation**: Auto-tagged with proper semver
+- ✅ **GitHub Releases**: Generated with changelogs
+- ✅ **Branch syncing**: Keeps branches up-to-date
+
+### Template Design
+- ✅ **Placeholder build steps**: Customize for your stack
+- ✅ **Commented examples**: Docker, deployment guides
+- ✅ **Platform-agnostic**: Works with any language
+- ✅ **Documentation included**: All template docs in `docs/git-auto-release/`
+
+---
+
+## 🚀 Quick Decision Tree
+
+**What do you need to do today?**
+
+```mermaid
+flowchart TD
+    Start{What's your task?}
+    
+    Feature[Add a feature]
+    Bug[Fix a bug]
+    Breaking[Breaking change]
+    Emergency[Production emergency]
+    
+    Start --> Feature
+    Start --> Bug
+    Start --> Breaking
+    Start --> Emergency
+    
+    Feature -->|feature/* from main| FeatureFlow[Create feature/* branch<br/>Commit with feat:<br/>PR to main → MINOR bump]
+    Bug -->|bugfix/* from main| BugFlow[Create bugfix/* branch<br/>Commit with fix:<br/>PR to main → PATCH bump]
+    Breaking -->|alpha from main| BreakingFlow[Work on alpha branch<br/>Commit with feat!:<br/>PR to main → MAJOR bump]
+    Emergency -->|hotfix from release| EmergencyFlow[Create hotfix branch<br/>Commit with fix:<br/>PR to release → PATCH bump]
+    
+    style Start fill:#3498db,color:#fff
+    style Feature fill:#2ecc71,color:#fff
+    style Bug fill:#f39c12,color:#fff
+    style Breaking fill:#9b59b6,color:#fff
+    style Emergency fill:#e74c3c,color:#fff
+```
+
+**Quick links to detailed workflows:**
+- 🎨 [Feature Development](WORKFLOW_EXAMPLES.md#1-feature-development)
+- 🐛 [Bug Fixes](WORKFLOW_EXAMPLES.md#2-bug-fixes)
+- 💥 [Breaking Changes](WORKFLOW_EXAMPLES.md#4-major-release-breaking-changes)
+- 🚨 [Hotfix Emergency](WORKFLOW_EXAMPLES.md#7-hotfix-production-emergency)
+
+---
+
+## 📋 Daily Workflow Commands
+
+### Feature Development (MINOR bump)
+
+```bash
+# Start feature
+git checkout main
+git pull origin main
+git checkout -b feature/my-awesome-feature
+
+# Work and commit (use conventional commits)
+git add .
+git commit -m "feat(module): add awesome feature"
+
+# Push and create PR to main
+git push origin feature/my-awesome-feature
+# Create PR: feature/my-awesome-feature → main
+```
+
+**Result after merge**: `v0.2.0-beta` tag created, VERSION updated
+
+---
+
+### Bug Fix (PATCH bump)
+
+```bash
+# Start bugfix
+git checkout main
+git pull origin main
+git checkout -b bugfix/fix-critical-issue
+
+# Work and commit
+git add .
+git commit -m "fix(module): resolve critical issue"
+
+# Push and create PR to main
+git push origin bugfix/fix-critical-issue
+# Create PR: bugfix/fix-critical-issue → main
+```
+
+**Result after merge**: `v0.1.1-beta` tag created, VERSION updated
+
+---
+
+### Production Release
+
+```bash
+# Release tested beta to production
+# Create PR: main → release
+
+# On GitHub:
+# 1. Create PR from main to release
+# 2. Get 2 approvals (review carefully!)
+# 3. Merge PR
+```
+
+**Result after merge**: `v0.2.0` tag created, GitHub Release published, VERSION updated
+
+---
+
+### Hotfix Emergency (PATCH bump)
+
+```bash
+# Start hotfix from release
+git checkout release
+git pull origin release
+git checkout -b hotfix
+
+# Fix and commit
+git add .
+git commit -m "fix(critical): emergency production fix"
+
+# Push and create PR to release
+git push origin hotfix
+# Create PR: hotfix → release
+```
+
+**Result after merge**: 
+- `v1.0.1` tag created and released
+- VERSION updated
+- Changes auto-sync to main and all active branches
+
+---
+
+---
+
+## 📊 Version Progression Cheat Sheet
+
+### Standard Version Bumps
+
+| Merge Action | Current | Next Version | Tag Created | Notes |
+|--------------|---------|--------------|-------------|-------|
+| feature/* → main | 0.1.0 | 0.2.0-beta | v0.2.0-beta | MINOR bump |
+| bugfix/* → main | 0.1.0 | 0.1.1-beta | v0.1.1-beta | PATCH bump |
+| main → release | 1.0.0-beta | 1.0.0 | v1.0.0 | Production release |
+| hotfix → release | 1.0.0 | 1.0.1 | v1.0.1 | Emergency fix |
+
+### Major Release Progression
+
+| Step | Merge Action | Version Created | Tag | Branch Created |
+|------|--------------|-----------------|-----|----------------|
+| 1 | alpha → main | 1.0.0-alpha | v1.0.0-alpha | beta (auto) |
+| 2 | beta → main | 1.0.0-beta | v1.0.0-beta | - |
+| 3 | main → release | 1.0.0 | v1.0.0 | - |
+
+### Beta Refinement (During Major Beta Release)
+
+| Merge Action | Current | Next Version | Tag Created | Notes |
+|--------------|---------|--------------|-------------|-------|
+| feature/* → main | 1.0.0-beta | 1.0.0-beta.1 | v1.0.0-beta.1 | .N increment (no new minor bump) |
+| bugfix/* → main | 1.0.0-beta.1 | 1.0.0-beta.2 | v1.0.0-beta.2 | .N increment |
+| feature/* → main | 1.0.0-beta.2 | 1.0.0-beta.3 | v1.0.0-beta.3 | .N increment (no new minor bump) |
+| bugfix/* → main | 1.0.0-beta.3 | 1.0.0-beta.4 | v1.0.0-beta.4 | .N increment |
+
+**Key Rule**: During a **major beta release** (VERSION = `X.0.0-beta` from beta branch merge), ALL subsequent merges to main result in `.N` increments. Regular feature/bugfix merges outside of major releases continue to bump versions normally (e.g., `v0.2.0-beta`, `v0.3.0-beta`, `v0.1.1-beta`).
+
+### Build Versions (Development, No Tags)
+
+| Branch Type | Version Format | Example |
+|-------------|----------------|---------|
+| feature/* | base+commit | v0.1.0+c8d92a14 |
+| bugfix/* | base+commit | v0.1.0+f14e2c91 |
+| alpha | base+commit | v0.1.0+a3f2b1c8 |
+| hotfix | base-hotfix.N | v1.0.0-hotfix.1 |
+
+---
+
+---
+
+## ✍️ Commit Message Format
+
+Following [Conventional Commits](https://www.conventionalcommits.org/) specification for structured, semantic commit messages:
+
+```
+type(scope): short description
+
+[optional body explaining what and why]
+
+[optional footer with breaking changes or issue refs]
+```
+
+### Commit Types Reference
+
+| Type | Use For | Example |
+|------|---------|---------|
+| `feat` | New features | `feat(auth): add OAuth2 support` |
+| `fix` | Bug fixes | `fix(api): handle null responses correctly` |
+| `feat!` | Breaking changes | `feat!(api): redesign REST endpoints to GraphQL` |
+| `docs` | Documentation only | `docs(readme): update installation instructions` |
+| `style` | Code formatting | `style(app): fix indentation in main.js` |
+| `refactor` | Code restructuring | `refactor(auth): simplify token validation` |
+| `perf` | Performance improvements | `perf(db): optimize query performance` |
+| `test` | Adding tests | `test(auth): add token validation tests` |
+| `chore` | Maintenance tasks | `chore(deps): update dependencies` |
+
+### More Examples
+
+```bash
+# Feature with details
+git commit -m "feat(dashboard): add user analytics chart
+
+- Added chart component with D3.js
+- Integrated with analytics API
+- Added date range selector"
+
+# Bug fix with issue reference
+git commit -m "fix(login): prevent duplicate submissions
+
+Closes #123"
+
+# Breaking change with migration notes
+git commit -m "feat!(api)!: change authentication to JWT
+
+BREAKING CHANGE: API now requires JWT tokens instead of API keys.
+Clients must update to use Authorization: Bearer <token> header."
+```
+
+> **💡 Important**: Version bumps are determined by **branch type**, not commit messages!
+> - `feature/*` → main = MINOR bump → `vX.Y+1.0-beta` (normal beta tag)
+> - `bugfix/*` → main = PATCH bump → `vX.Y.Z+1-beta` (normal beta tag)
+> - `alpha` → main = MAJOR bump → `vX+1.0.0-alpha` (creates beta branch)
+> - `beta` branch → main = `vX.0.0-beta` (major beta release)
+> - ANY merge → main during **major beta** (VERSION = `X.0.0-beta`) = `.N` increment (e.g., v1.0.0-beta.1, .2, .3)
+> - `hotfix` → release = PATCH bump
+>
+> **During major beta release only**: No new major/minor bumps allowed - all changes get `.N` increments!
+>
+> Use conventional commits for clarity and changelog generation, not versioning control.
+
+---
+
+---
+
+## 🛠️ Common Git Commands
+
+### Branch Management
+
+```bash
+# View all branches (local and remote)
+git branch -a
+
+# Switch branches and pull latest
+git checkout main
+git pull origin main
+
+# Delete merged feature branch
+git branch -d feature/my-feature
+git push origin --delete feature/my-feature
+
+# Sync your fork with upstream
+git fetch upstream
+git checkout main
+git merge upstream/main
+```
+
+### Tag Operations
+
+```bash
+# View all tags
+git tag -l
+
+# View tags matching pattern
+git tag -l "v1.*"
+
+# Fetch latest tags from remote
+git fetch --tags
+
+# View tag details
+git show v1.0.0
+
+# Checkout specific tag
+git checkout v1.0.0
+```
+
+### Commit History
+
+```bash
+# View pretty commit history
+git log --oneline --graph --all
+
+# View commits by author
+git log --author="YourName"
+
+# View commits in date range
+git log --since="2024-01-01" --until="2024-12-31"
+
+# Search commits by message
+git log --grep="fix(auth)"
+
+# View file history
+git log --follow -- path/to/file
+```
+
+### Undoing Changes
+
+```bash
+# Undo last commit (keep changes staged)
+git reset --soft HEAD~1
+
+# Undo last commit (keep changes unstaged)
+git reset HEAD~1
+
+# Discard local changes to file
+git checkout -- path/to/file
+
+# Discard all local changes
+git reset --hard HEAD
+
+# Amend last commit message
+git commit --amend -m "new message"
+
+# Amend last commit (add forgotten files)
+git add forgotten-file.txt
+git commit --amend --no-edit
+```
+
+### Interactive Rebase (Clean Up Commits)
+
+```bash
+# Squash last 3 commits before PR
+git rebase -i HEAD~3
+
+# In the editor:
+# - Change 'pick' to 'squash' for commits to combine
+# - Save and close
+# - Edit combined commit message
+```
+
+---
+
+---
+
+## 🔧 Troubleshooting Quick Fixes
+
+### Workflow Not Running
+
+```bash
+# 1. Verify workflow file exists
+ls .github/workflows/ci-cd-versioned.yml
+
+# 2. Check GitHub Actions is enabled
+# Go to: Settings → Actions → General → Enable
+
+# 3. Check branch protection allows workflow
+# Settings → Branches → Edit protection rules
+```
+
+### Wrong Version Calculated
+
+```bash
+# Check current VERSION
+cat VERSION
+
+# Verify branch name pattern
+git branch --show-current
+
+# Expected patterns:
+# - feature/name  → MINOR bump
+# - bugfix/name   → PATCH bump  
+# - alpha         → MAJOR bump
+# - hotfix        → PATCH bump
+
+# View CI logs for version calculation
+# GitHub → Actions → Latest run → Calculate Version job
+```
+
+### Merge Conflicts in VERSION
+
+```bash
+# Always choose the higher version
+git checkout --theirs VERSION
+git add VERSION
+git commit
+
+# Or manually edit VERSION to higher number
+echo "1.2.3" > VERSION
+git add VERSION
+git commit
+```
+
+### Tag Already Exists
+
+```bash
+# Delete tag locally
+git tag -d v1.0.0
+
+# Delete tag remotely
+git push origin :refs/tags/v1.0.0
+
+# Force push the corrected commit
+# (Only if safe to do so!)
+git push --force-with-lease
+```
+
+### CI Tests Fail
+
+```bash
+# Run tests locally first
+npm test
+# or
+python -m pytest
+# or
+cargo test
+
+# Check specific job logs
+# GitHub → Actions → Failed run → Click failing job
+
+# Re-run failed jobs
+# GitHub → Actions → Failed run → Re-run failed jobs
+```
+
+### Branch Protection Blocks Merge
+
+```bash
+# Ensure all required checks pass
+# - Build & Test must be green
+# - Calculate Version must complete
+# - Required reviews must be approved
+# - All conversations must be resolved
+
+# View protection rules
+# Settings → Branches → Branch protection rules
+```
+
+---
+
+## 📁 Key Files Reference
+
+| File | Purpose | When to Edit |
+|------|---------|--------------|
+| `VERSION` | Current semantic version | Never manually (auto-updated by CI) |
+| `.github/workflows/ci-cd-versioned.yml` | CI/CD automation | When customizing workflow |
+| `BRANCH_STRATEGY.md` | Branch rules and flows | Reference only |
+| `README.md` | Project overview | Update for your project |
+
+> **⚠️ Warning**: Never manually edit `VERSION` file unless fixing a CI issue. The workflow manages it automatically.
+
+---
+
+## 🔗 Documentation Links
+
+### Getting Started
+- 🚀 [Quickstart](QUICKSTART.md) - Initial setup (5 minutes)
+- 📘 [Setup Guide](SETUP_GUIDE.md) - Detailed configuration
+
+### Daily Usage  
+- ⚡ **Reference Guide** (this page) - Comprehensive reference
+- 📖 [Workflow Examples](WORKFLOW_EXAMPLES.md) - Step-by-step scenarios
+- 🌳 [Branch Strategy](BRANCH_STRATEGY.md) - Branch rules and flows
+
+### Advanced
+- 🎨 [Customization Guide](CUSTOMIZATION.md) - Adapt to your needs
+- 📂 [Project Structure](PROJECT_STRUCTURE.md) - File organization
+
+---
+
+## 🎯 Common Use Cases
+
+Perfect for:
+- ✅ **SaaS applications**: Clear staging → production promotion path
+- ✅ **Open source projects**: Transparent and predictable releases
+- ✅ **Enterprise software**: Controlled, auditable version control
+- ✅ **Microservices**: Consistent versioning across services
+- ✅ **APIs**: Breaking changes clearly marked with MAJOR bumps
+- ✅ **Libraries**: Semantic versioning for package dependents
+
+---
+
+## 🛠️ Customization Points
+
+### Easy Customizations
+- Change placeholder build/test commands for your language
+- Remove Docker examples if not needed
+- Adjust branch protection rules
+- Modify release notes format
+
+### Advanced Customizations
+- Adapt workflow for GitLab CI, Bitbucket Pipelines, Jenkins
+- Change version bump logic
+- Add deployment steps
+- Integrate with external tools
+
+See [CUSTOMIZATION.md](CUSTOMIZATION.md) for platform-specific guides.
+
+---
+
+## 💡 Pro Tips
+
+1. **Commit Often**: Small, focused commits are easier to review and revert
+2. **Branch Names**: Use descriptive names like `feature/user-authentication` not `feature/fix`
+3. **PR Descriptions**: Link related issues with `Closes #123` or `Fixes #456`
+4. **Review Tags**: Check tags regularly with `git fetch --tags && git tag -l`
+5. **Test Locally**: Always run tests before pushing with `npm test` or equivalent
+6. **Clean Branches**: Delete merged branches to keep repo tidy
+7. **Read CI Logs**: When workflow fails, read the logs - they're usually clear about what's wrong
+
+---
+
+## ❓ Frequently Asked Questions
+
+### How do I fix "VERSION file has conflicts"?
+
+Always choose the higher version number:
+```bash
+git checkout --theirs VERSION
+git add VERSION
+git commit
+```
+
+### Can I manually edit the VERSION file?
+
+**No**, unless you're fixing a CI issue. The workflow automatically manages VERSION after every merge. Manual edits will be overwritten.
+
+### What if I accidentally merged to the wrong branch?
+
+1. Revert the merge commit:
+   ```bash
+   git revert -m 1 <merge-commit-hash>
+   git push
+   ```
+2. Create PR to the correct branch
+3. Delete any incorrect tags if created
+
+### How do I skip CI for a commit?
+
+Add `[skip ci]` or `[ci skip]` to your commit message:
+```bash
+git commit -m "docs: update README [skip ci]"
+```
+
+### Why is my PR showing the wrong version?
+
+Check your branch name matches the pattern:
+- `feature/*` → MINOR bump
+- `bugfix/*` → PATCH bump
+- `alpha` → MAJOR bump
+- `hotfix` → PATCH bump (from release)
+
+### Can I use this with monorepos?
+
+Yes, but requires customization. See [CUSTOMIZATION.md](CUSTOMIZATION.md) for monorepo configuration examples.
+
+### How do I change the version bump logic?
+
+Edit `.github/workflows/ci-cd-versioned.yml` in the version calculation job. See [CUSTOMIZATION.md](CUSTOMIZATION.md) for details.
+
+### What if I need to release multiple features together?
+
+Merge all feature branches to `main` first (each gets a beta tag), then when ready, merge `main` → `release` for one production release.
+
+### My feature became a breaking change mid-development. What do I do?
+
+If you realize your feature branch will introduce breaking changes:
+
+1. **Create alpha branch** (if it doesn't exist):
+   ```bash
+   git checkout main
+   git checkout -b alpha
+   git push -u origin alpha
+   ```
+
+2. **Merge your feature branch into alpha**:
+   ```bash
+   git checkout alpha
+   git merge feature/your-feature
+   # Or create PR: feature/your-feature → alpha
+   ```
+
+3. **Continue development on alpha**:
+   ```bash
+   git checkout alpha
+   # Make more changes
+   git commit -m "feat!: breaking change description"
+   git push origin alpha
+   ```
+
+4. **When ready, merge alpha → main** for v1.0.0-alpha tag
+
+**Note**: Use `feat!:` in commit messages to mark breaking changes clearly for changelog generation.
+
+### Can I use squash merges?
+
+Yes! The workflow detects both regular merges (2 parents) and squash merges (PR# in commit message).
+
+### How do I rollback a release?
+
+1. **For beta/alpha**: Revert the merge to main
+2. **For production**: Create a hotfix branch from release with the fix, or revert and create new release
+
+### Why did my workflow fail with "tag already exists"?
+
+Someone may have manually created the tag. Delete it and re-run:
+```bash
+git tag -d v1.0.0
+git push origin :refs/tags/v1.0.0
+```
+
+### Can I customize the tag format?
+
+Yes, edit the workflow's tag creation step. Default is `v{VERSION}` (e.g., v1.0.0).
+
+### Can I merge alpha (breaking changes) during a major beta release?
+
+**No, alpha merges to main are NOT allowed during a major beta release.** Here's why and what to do:
+
+**Why Not?**
+- A major version bump is the highest possible version increment
+- Once you're in a major beta release (e.g., VERSION = `1.0.0-beta` from beta branch merge), you've already claimed that major version
+- There cannot be two major bumps in parallel - you can't have `v1.0.0-beta` and start `v2.0.0-alpha` simultaneously
+- During major beta release (VERSION = `X.0.0-beta`), ALL merges to main (feature or bugfix) must increment build metadata (`.N`) only
+
+**Note**: Regular feature/bugfix merges outside of major beta releases continue to create normal beta tags: `v0.2.0-beta`, `v0.3.0-beta`, etc.
+
+**What To Do If You Have Breaking Changes During Beta?**
+
+**Option 1: Delay Breaking Changes (Recommended)**
+1. Complete current beta and release to production (`v1.0.0`)
+2. Then create alpha branch for breaking changes
+3. Merge alpha → main for `v2.0.0-alpha`
+4. Create new beta branch and proceed with `v2.0.0-beta`
+
+**Option 2: Abandon Current Major Beta and Restart**
+1. If the major beta is not production-ready and needs major changes, preserve the work in alpha but remove it from main:
+   ```bash
+   # Step 1: Create alpha branch from current main (preserves all the work)
+   git checkout main
+   git checkout -b alpha
+   git push -u origin alpha
+   
+   # Step 2: Reset main to before the major version bump
+   # Find the commit hash before alpha was originally merged to main
+   git log --oneline main  # Find the commit before the alpha merge
+   git checkout main
+   git reset --hard <commit-hash-before-alpha-merge>
+   
+   # Step 3: Verify and restore VERSION file to pre-alpha state
+   # VERSION should now be back to what it was (e.g., 0.x.x)
+   cat VERSION  # Verify it's correct (e.g., 0.5.0, not 1.0.0-alpha)
+   
+   # Push the reset
+   git push origin main --force  # ⚠️ Use with caution, coordinate with team
+   
+   # Step 4: Delete all major beta tags (work continues in alpha, tags removed)
+   git tag -d v1.0.0-alpha v1.0.0-beta
+   git push origin :refs/tags/v1.0.0-alpha :refs/tags/v1.0.0-beta
+   
+   # Step 5: Continue development in alpha
+   git checkout alpha
+   # All the work from the beta is preserved here
+   # VERSION in alpha still contains 1.0.0-beta (or latest .N version)
+   git merge feature/your-breaking-change  # Add more breaking changes if needed
+   git commit -m "feat!: incorporate additional breaking changes"
+   git push origin alpha
+   
+   # When ready, restart the major release process:
+   # Create PR: alpha → main (will create v1.0.0-alpha, update VERSION to 1.0.0-alpha, and create beta branch)
+   ```
+   
+   **⚠️ Important**: This approach uses `git reset --hard` and force push, which rewrites main's history. The work continues in alpha as if the merge to main never happened. VERSION in main reverts to pre-alpha state, while VERSION in alpha retains the major version. Coordinate with your team!
+
+**Option 3: Start New Alpha for Next Major Version**
+1. If you need breaking changes but current major beta must still be released:
+   ```bash
+   # Step 1: Create new alpha branch for next major version (v2.x.x)
+   git checkout main
+   git checkout -b alpha
+   git push -u origin alpha
+   
+   # Step 2: Develop breaking changes in this new alpha
+   git checkout alpha
+   git merge feature/your-breaking-change
+   git commit -m "feat!: breaking changes for v2.0.0"
+   git push origin alpha
+   # Note: VERSION in alpha still shows current main version (e.g., 1.0.0-beta.N)
+   # It will be bumped to 2.0.0-alpha when merged to main
+   
+   # Step 3: Complete and release current major beta first
+   # Continue with v1.0.0-beta → v1.0.0 release process
+   # Create PR: main → release (produces v1.0.0, VERSION becomes 1.0.0)
+   
+   # Step 4: AFTER v1.0.0 is released, merge new alpha
+   # Only then can you merge: alpha → main
+   # This will create v2.0.0-alpha and update VERSION to 2.0.0-alpha
+   ```
+   
+   **Important**: The new alpha branch CANNOT be merged to main until the current major version is released to production. This ensures version integrity and prevents conflicting major version bumps. VERSION in main must reach production (X.0.0) before starting the next major cycle (X+1.0.0-alpha).
+
+**Remember**: During a **major beta release** (VERSION = `X.0.0-beta`), the version represents a contract. Once you're in `v1.0.0-beta`, you're committed to releasing `v1.0.0` (or abandoning it). Breaking changes mean a new major version cycle.
+
+### How do I test workflow changes safely?
+
+1. Create a test repository
+2. Copy your modified workflow
+3. Test all merge scenarios
+4. Once confirmed, apply to production repo
+
+---
+
+## 📄 License & Support
+
+### License
+
+This template is released under the **MIT License** - see [LICENSE](LICENSE) for full text.
+
+You are free to:
+- ✅ Use this template for commercial or personal projects
+- ✅ Modify and adapt to your needs  
+- ✅ Distribute and share
+
+**Your project built with this template can use any license you choose.**
+
+### Support & Contributing
+
+**Contributions welcome!** See [CONTRIBUTING.md](../../CONTRIBUTING.md) for guidelines.
+
+**Need help?**
+- 📖 Documentation: Complete guides in [docs/git-auto-release/](.)
+- 🐛 Issues: [GitHub Issues](https://github.com/CodeOOf/Git-Auto-Release/issues)
+- 💬 Discussions: [GitHub Discussions](https://github.com/CodeOOf/Git-Auto-Release/discussions)
+
+---
+
+**📌 Bookmark this page for daily reference!**
+
+**⏱️ Setup Time**: ~5 minutes | **🔄 Maintenance**: Zero - fully automated! | **💪 Production Ready**: Use immediately!
+
+
+
+
diff --git a/docs/git-auto-release/SUMMARY.md b/docs/git-auto-release/SUMMARY.md
deleted file mode 100644
index e7e62ba..0000000
--- a/docs/git-auto-release/SUMMARY.md
+++ /dev/null
@@ -1,200 +0,0 @@
-# Git-Auto-Release Template - Overview
-
-**A GitHub Actions template for fully automated semantic versioning and release management.**
-
----
-
-## 🎯 What Is This?
-
-Git-Auto-Release automates your version control workflow using GitHub Actions:
-
-1. **Automatic Version Bumping**: MAJOR/MINOR/PATCH based on branch merges
-2. **Semantic Versioning**: Full semver 2.0.0 compliance with pre-release tags
-3. **Branch-Based Strategy**: Parallel branching model with clear promotion paths
-4. **Zero Maintenance**: No manual VERSION file edits or tag creation
-5. **Production Ready**: Includes GitHub Releases, changelogs, and optional Docker support
-
----
-
-## 📚 Documentation Guide
-
-### Getting Started
-- 🚀 **[QUICKSTART.md](QUICKSTART.md)** - Get running in 5 minutes (Option A: GitHub template, Option B: Manual setup)
-- 📘 **[SETUP_GUIDE.md](SETUP_GUIDE.md)** - Detailed configuration and advanced options
-
-### Daily Usage (For Established Projects)
-- ⚡ **[QUICK_REFERENCE.md](QUICK_REFERENCE.md)** - Command cheat sheet and decision tree
-- 📖 **[WORKFLOW_EXAMPLES.md](WORKFLOW_EXAMPLES.md)** - Real-world step-by-step scenarios
-
-### Understanding & Customization
-- 🌳 **[BRANCH_STRATEGY.md](BRANCH_STRATEGY.md)** - Parallel branching model explained
-- 🎨 **[CUSTOMIZATION.md](CUSTOMIZATION.md)** - Adapt for GitLab, Bitbucket, Jenkins, etc.
-- 📂 **[PROJECT_STRUCTURE.md](PROJECT_STRUCTURE.md)** - Template file organization
-
----
-
-## 📁 What You Get (Template Files)
-
-When you use this template, you receive:
-
-```
-Your-Project/
-├── .github/workflows/
-│   └── ci-cd-versioned.yml          # Automated versioning workflow
-├── docs/git-auto-release/           # All template documentation (keep, archive, or remove)
-├── README.template.md              # Starter for your project README
-├── CONTRIBUTING.template.md        # Starter for your contribution guidelines
-├── CHECKLIST.md                    # Implementation checklist
-└── VERSION                         # Semantic version tracker (auto-managed)
-```
-
-**Note**: Template documentation is in `docs/git-auto-release/` - you can keep it for reference, move to archive, or delete once familiar.
-
----
-
-## ✨ Key Features
-
-### Automated Versioning
-- ✅ **MAJOR bump**: `alpha` → `main` (breaking changes)
-- ✅ **MINOR bump**: `feature/*` → `main` (new features)
-- ✅ **PATCH bump**: `bugfix/*` → `main` (bug fixes)
-- ✅ **Pre-release tags**: `-alpha`, `-beta` suffixes
-- ✅ **Build metadata**: `+SHA` for dev builds
-
-### Branch Strategy
-- ✅ **Parallel branching**: All branches from `main` (except hotfix from `release`)
-- ✅ **Alpha branch**: For breaking changes only
-- ✅ **Beta branch**: Auto-created after alpha merge
-- ✅ **Release branch**: Production-ready code
-- ✅ **Hotfix support**: Emergency production fixes
-
-### CI/CD Automation
-- ✅ **Merge commit detection**: Supports both merge and squash merges
-- ✅ **VERSION file updates**: Automatic after PR merges
-- ✅ **Tag creation**: Auto-tagged with proper semver
-- ✅ **GitHub Releases**: Generated with changelogs
-- ✅ **Branch syncing**: Keeps branches up-to-date
-
-### Template Design
-- ✅ **Placeholder build steps**: Customize for your stack
-- ✅ **Commented examples**: Docker, deployment guides
-- ✅ **Platform-agnostic**: Works with any language
-- ✅ **Documentation included**: All template docs in `docs/git-auto-release/`
-
----
-
-## 🎨 Version Flow Example
-
-```
-feature/login → main
-  ├─ Merge: Creates v0.2.0-beta tag
-  └─ Result: Ready for staging/testing
-
-main → release (when ready)
-  ├─ Merge: Creates v0.2.0 tag + GitHub Release
-  └─ Result: Production release
-```
-
----
-
-## 📊 Version Bump Summary
-
-| Action | From | To | Tag Created |
-|--------|------|-----|-------------|
-| Merge `feature/*` to `main` | 0.1.0 | 0.2.0-beta | v0.2.0-beta |
-| Merge `bugfix/*` to `main` | 0.1.0-beta | 0.1.1-beta | v0.1.1-beta |
-| Merge `alpha` to `main` | 0.9.0 | 1.0.0-alpha | v1.0.0-alpha |
-| Merge `beta` to `main` | 1.0.0-alpha | 1.0.0-beta | v1.0.0-beta |
-| Merge `main` to `release` | 0.2.0-beta | 0.2.0 | v0.2.0 + Release |
-| Merge `hotfix` to `release` | 1.0.0 | 1.0.1 | v1.0.1 + Release |
-
----
-
-## 🛠️ Customization Points
-
-### Easy Customizations
-- Change placeholder build/test commands for your language
-- Remove Docker examples if not needed
-- Adjust branch protection rules
-- Modify release notes format
-
-### Advanced Customizations
-- Adapt workflow for GitLab CI, Bitbucket Pipelines, Jenkins
-- Change version bump logic
-- Add deployment steps
-- Integrate with external tools
-
-See [CUSTOMIZATION.md](CUSTOMIZATION.md) for platform-specific guides.
-
----
-
-## 🎯 Common Use Cases
-
-Perfect for:
-- ✅ **SaaS applications**: Clear staging → production promotion path
-- ✅ **Open source projects**: Transparent and predictable releases
-- ✅ **Enterprise software**: Controlled, auditable version control
-- ✅ **Microservices**: Consistent versioning across services
-- ✅ **APIs**: Breaking changes clearly marked with MAJOR bumps
-- ✅ **Libraries**: Semantic versioning for package dependents
-
----
-- [Conventional Commits](https://www.conventionalcommits.org/)
-- [GitHub Flow](https://docs.github.com/en/get-started/quickstart/github-flow)
-
----
-
-## 📝 Next Steps
-
-### For This Repository (Template Itself)
-
-1. ✅ **Set up GitHub Actions** - Enable workflows
-2. ✅ **Create initial branches** - main, alpha, release
-3. ✅ **Add branch protection** - Follow setup guide
-4. ✅ **Test the workflow** - Make a test feature
-
-### For Template Users
-
-1. **Use this template** - Click "Use this template" on GitHub
-2. **Follow setup guide** - [`docs/SETUP_GUIDE.md`](docs/SETUP_GUIDE.md)
-3. **Customize** - Adapt for your project
-4. **Start developing** - Create features with automated releases!
-
----
-
-## 📞 Support
-
-- **Documentation**: All guides in [`docs/`](docs/)
-- **Issues**: [GitHub Issues](https://github.com/CodeOOf/Git-Auto-Release/issues)
-- **Discussions**: [GitHub Discussions](https://github.com/CodeOOf/Git-Auto-Release/discussions)
-
----
-
-## 📄 License
-
-This template is released under the **MIT License** - see [LICENSE](LICENSE) for full text.
-
-You are free to:
-- ✅ Use this template for commercial or personal projects
-- ✅ Modify and adapt to your needs  
-- ✅ Distribute and share
-
-**Your project built with this template can use any license you choose.**
-
----
-
-## 🤝 Contributing & Support
-
-**Contributions welcome!** See [CONTRIBUTING.md](../../CONTRIBUTING.md) for guidelines.
-
-**Need help?**
-- 📖 Documentation: Complete guides in [docs/git-auto-release/](.)
-- 🐛 Issues: [GitHub Issues](https://github.com/CodeOOf/Git-Auto-Release/issues)
-- 💬 Discussions: [GitHub Discussions](https://github.com/CodeOOf/Git-Auto-Release/discussions)
-
----
-
-**⏱️ Setup Time**: ~5 minutes  
-**🔄 Maintenance**: Zero - fully automated!  
-**💪 Production Ready**: Use immediately!
-
diff --git a/docs/git-auto-release/WORKFLOW_EXAMPLES.md b/docs/git-auto-release/WORKFLOW_EXAMPLES.md
index bfcc76e..ed2e3ce 100644
--- a/docs/git-auto-release/WORKFLOW_EXAMPLES.md
+++ b/docs/git-auto-release/WORKFLOW_EXAMPLES.md
@@ -178,17 +178,20 @@ git push origin bugfix/123-fix-login-timeout
 
 ---
 
-## 3. Beta Testing with Bugfixes
+## 3. Major Beta Release with Refinements
 
-**Scenario:** You have `v1.0.0-beta` on main and QA finds bugs during testing
+**Scenario:** You have `v1.0.0-beta` (major beta release from beta branch merge) on main and need to add more changes during testing
 
-This workflow uses build metadata (`.1`, `.2`, etc.) to track bugfixes during beta/alpha testing without changing the base version.
+This workflow uses build metadata (`.1`, `.2`, etc.) to track ANY changes during a **major beta release** without changing the base version. **Important**: During major beta (VERSION = `X.0.0-beta`), ALL merges to main (whether from `feature/*` or `bugfix/*`) result in `.N` increments - no new version bumps are allowed.
+
+**Note**: Regular feature/bugfix merges outside of major beta releases continue to bump versions normally: `v0.2.0-beta`, `v0.3.0-beta`, `v0.1.1-beta`, etc.
 
 ### Initial State
 
 ```bash
 # Current VERSION: 1.0.0-beta
-# A feature was merged, creating v1.0.0-beta tag
+# (This came from beta branch → main merge after alpha → main)
+# Now in major beta release cycle
 ```
 
 ### QA Finds Bug #1
@@ -228,15 +231,26 @@ git push origin bugfix/beta-api-validation
 - VERSION updated to: `1.0.0-beta.2`
 - Build metadata incremented again
 
-### Multiple Beta Fixes
+### Multiple Beta Refinements (During Major Beta)
 
 ```bash
-# Each bugfix/* merge to main during beta/alpha phase:
-# v1.0.0-beta       (initial feature merge)
-# v1.0.0-beta.1     (first bugfix)
-# v1.0.0-beta.2     (second bugfix)
-# v1.0.0-beta.3     (third bugfix)
+# ANY merge to main during MAJOR beta (VERSION = X.0.0-beta) results in .N increments:
+# v1.0.0-beta       (beta branch → main: major beta release starts)
+# v1.0.0-beta.1     (first bugfix/* merge)
+# v1.0.0-beta.2     (second bugfix/* merge)
+# v1.0.0-beta.3     (feature/* merge - NO minor bump, just .N increment!)
+# v1.0.0-beta.4     (another bugfix/* merge)
+# v1.0.0-beta.5     (another feature/* merge - still just .N increment!)
 # ... and so on
+
+# Important: During major beta, no new major/minor bumps allowed!
+# VERSION must stay at X.0.0-beta until released to production.
+# This is because major version bump is the highest increment possible.
+
+# Compare to regular beta tags (outside major release cycle):
+# v0.2.0-beta       (feature/* → main: normal MINOR bump with -beta suffix)
+# v0.3.0-beta       (feature/* → main: normal MINOR bump with -beta suffix)
+# v0.3.1-beta       (bugfix/* → main: normal PATCH bump with -beta suffix)
 ```
 
 ### Release to Production

From 8bbbf94e6c0687dca718fb770b01f929d7320d12 Mon Sep 17 00:00:00 2001
From: "Viktor H. Ingre" <viktor.ingre@codeoof.com>
Date: Tue, 9 Dec 2025 08:46:02 +0100
Subject: [PATCH 8/8] docs: fix anchor links and file paths for cross-platform
 compatibility

- Replace emoji-based anchor links with plain text for better Markdown renderer compatibility
- Fix FAQ anchor: #-frequently-asked-questions -> #frequently-asked-questions
- Fix commit format anchor: #-commit-message-format -> #commit-message-format
- Clarify VERSION file progression in SETUP_GUIDE.md
- Fix default VERSION value in PROJECT_STRUCTURE.md (1.0.0-beta -> 0.1.0)
- Correct navigation paths in CUSTOMIZATION.md (remove incorrect ../ prefix)
---
 docs/git-auto-release/CUSTOMIZATION.md     | 2 +-
 docs/git-auto-release/PROJECT_STRUCTURE.md | 2 +-
 docs/git-auto-release/QUICKSTART.md        | 2 +-
 docs/git-auto-release/README.md            | 4 ++--
 docs/git-auto-release/REFERENCE_GUIDE.md   | 4 ++--
 docs/git-auto-release/SETUP_GUIDE.md       | 2 +-
 6 files changed, 8 insertions(+), 8 deletions(-)

diff --git a/docs/git-auto-release/CUSTOMIZATION.md b/docs/git-auto-release/CUSTOMIZATION.md
index 7820331..106642d 100644
--- a/docs/git-auto-release/CUSTOMIZATION.md
+++ b/docs/git-auto-release/CUSTOMIZATION.md
@@ -1,6 +1,6 @@
 # Customization Guide
 
-📖 **Navigation**: [← README](../README.md) | [Branch Strategy](../BRANCH_STRATEGY.md) | [Workflow Examples](WORKFLOW_EXAMPLES.md) | **Customization Guide** | [Reference Guide →](REFERENCE_GUIDE.md)
+📖 **Navigation**: [← README](README.md) | [Branch Strategy](BRANCH_STRATEGY.md) | [Workflow Examples](WORKFLOW_EXAMPLES.md) | **Customization Guide** | [Reference Guide →](REFERENCE_GUIDE.md)
 
 Learn how to adapt the Git-Auto-Release template to different CI/CD platforms and customize the automation pipeline.
 
diff --git a/docs/git-auto-release/PROJECT_STRUCTURE.md b/docs/git-auto-release/PROJECT_STRUCTURE.md
index 7c84759..697bded 100644
--- a/docs/git-auto-release/PROJECT_STRUCTURE.md
+++ b/docs/git-auto-release/PROJECT_STRUCTURE.md
@@ -282,7 +282,7 @@ README.md (overview)
 
 1. **.github/workflows/ci-cd-versioned.yml**: Docker builds, deployment steps
 2. **docs/git-auto-release/BRANCH_STRATEGY.md**: Adjust to your team's needs
-3. **VERSION**: Set initial version (default: 1.0.0-beta)
+3. **VERSION**: Set initial version (default: 0.1.0)
 
 ### Usually Keep As-Is
 
diff --git a/docs/git-auto-release/QUICKSTART.md b/docs/git-auto-release/QUICKSTART.md
index 6dd803f..3024501 100644
--- a/docs/git-auto-release/QUICKSTART.md
+++ b/docs/git-auto-release/QUICKSTART.md
@@ -154,7 +154,7 @@ Use structured commit messages for clarity:
 
 **Example**: `feat(auth): add OAuth2 support`
 
-> 📖 **For detailed commit guidelines, types, and examples**, see [Reference Guide - Commit Message Format](REFERENCE_GUIDE.md#️-commit-message-format)
+> 📖 **For detailed commit guidelines, types, and examples**, see [Reference Guide - Commit Message Format](REFERENCE_GUIDE.md#commit-message-format)
 
 ---
 
diff --git a/docs/git-auto-release/README.md b/docs/git-auto-release/README.md
index faa102e..1bc1f6e 100644
--- a/docs/git-auto-release/README.md
+++ b/docs/git-auto-release/README.md
@@ -4,7 +4,7 @@
 
 Complete documentation for setting up and using automated Git versioning and releases.
 
-> **❓ Have questions?** Check the [FAQ in Reference Guide](REFERENCE_GUIDE.md#-frequently-asked-questions)
+> **❓ Have questions?** Check the [FAQ in Reference Guide](REFERENCE_GUIDE.md#frequently-asked-questions)
 
 ---
 
@@ -14,7 +14,7 @@ Complete documentation for setting up and using automated Git versioning and rel
 - **[Quick Start Guide](QUICKSTART.md)** - Get up and running in 10 minutes
 - **[Setup Guide](SETUP_GUIDE.md)** - Complete installation and configuration
 - **[Reference Guide](REFERENCE_GUIDE.md)** - Comprehensive reference with daily workflow commands and version cheat sheet (for established projects)
-  - **[FAQ](REFERENCE_GUIDE.md#-frequently-asked-questions)** - Common questions and troubleshooting
+  - **[FAQ](REFERENCE_GUIDE.md#frequently-asked-questions)** - Common questions and troubleshooting
 
 ### Core Concepts
 - **[Branch Strategy](BRANCH_STRATEGY.md)** - Detailed branching model and workflows
diff --git a/docs/git-auto-release/REFERENCE_GUIDE.md b/docs/git-auto-release/REFERENCE_GUIDE.md
index 372b36c..9903568 100644
--- a/docs/git-auto-release/REFERENCE_GUIDE.md
+++ b/docs/git-auto-release/REFERENCE_GUIDE.md
@@ -17,7 +17,7 @@
 - [Quick Decision Tree](#-quick-decision-tree)
 - [Daily Workflow Commands](#-daily-workflow-commands)
 - [Version Progression Cheat Sheet](#-version-progression-cheat-sheet)
-- [Commit Message Format](#️-commit-message-format)
+- [Commit Message Format](#commit-message-format)
 - [Common Git Commands](#️-common-git-commands)
 - [Troubleshooting Quick Fixes](#-troubleshooting-quick-fixes)
 - [Key Files Reference](#-key-files-reference)
@@ -25,7 +25,7 @@
 - [Common Use Cases](#-common-use-cases)
 - [Customization Points](#️-customization-points)
 - [Pro Tips](#-pro-tips)
-- [FAQ](#-frequently-asked-questions)
+- [FAQ](#frequently-asked-questions)
 - [License & Support](#-license--support)
 
 ---
diff --git a/docs/git-auto-release/SETUP_GUIDE.md b/docs/git-auto-release/SETUP_GUIDE.md
index 17be981..3f2accb 100644
--- a/docs/git-auto-release/SETUP_GUIDE.md
+++ b/docs/git-auto-release/SETUP_GUIDE.md
@@ -40,7 +40,7 @@ This section provides detailed explanations for both setup methods.
 ### Understanding the Template Structure
 
 The template includes:
-- **VERSION file**: Tracks current version (starts at `1.0.0-beta` after alpha merge)
+- **VERSION file**: Tracks current version (e.g., starts at `0.1.0`, becomes `1.0.0-beta` after alpha merge)
 - **README.template.md**: Your project README starter
 - **CONTRIBUTING.template.md**: Contribution guidelines starter
 - **.github/workflows/ci-cd-versioned.yml**: Automated versioning workflow