docs: restructure documentation for clarity and eliminate duplicates

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

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.
 

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.

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        # Fast command reference
-├── 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,33 +139,54 @@ Git-Auto-Release/
   - Deployment integration
   - Branch strategy adjustments
 
-#### `QUICK_REFERENCE.md`
-- **Purpose**: Fast command reference
+#### `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**:
-  - Common commands
+  - 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 formats
-  - Troubleshooting commands
-  - Quick links
+  - Commit message format (Conventional Commits)
+  - Git command reference
+  - Troubleshooting quick fixes
+  - 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
 
 ---
 
@@ -191,12 +229,16 @@ GitHub Releases (artifacts)
 ```
 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)
+    └── → 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)
+        ├── PROJECT_STRUCTURE.md (this file)
+        └── LICENSE (template license)
 ```
 
 ---
@@ -206,39 +248,41 @@ 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/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 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
 
 ---
 
 ## Customization Points
 
 ### 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: 0.1.0)
 
 ### Usually Keep As-Is
 
@@ -259,23 +303,25 @@ 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
 
 ---
 
 ## Adding New Files
 
 ### 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
 
@@ -296,10 +342,13 @@ 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) - 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
 
 ---