From 5575ae69a81f8be3d7ef8db4c807bd0fda4d81ae Mon Sep 17 00:00:00 2001
From: Florian BRUNIAUX <florian@bruniaux.com>
Date: Thu, 15 Jan 2026 08:18:32 +0100
Subject: [PATCH] feat: add VERSION file as single source of truth + sync
 script

- Create VERSION file (3.6.0) as the canonical version source
- Add scripts/sync-version.sh for automated version synchronization
- Fix version inconsistencies in cheatsheet.md and ultimate-guide.md
- Script supports --check mode for CI validation

Usage: ./scripts/sync-version.sh [--check]

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 VERSION                 |  1 +
 guide/cheatsheet.md     |  2 +-
 guide/ultimate-guide.md |  4 +-
 scripts/sync-version.sh | 81 +++++++++++++++++++++++++++++++++++++++++
 4 files changed, 85 insertions(+), 3 deletions(-)
 create mode 100644 VERSION
 create mode 100755 scripts/sync-version.sh

diff --git a/VERSION b/VERSION
new file mode 100644
index 0000000..40c341b
--- /dev/null
+++ b/VERSION
@@ -0,0 +1 @@
+3.6.0
diff --git a/guide/cheatsheet.md b/guide/cheatsheet.md
index 9c86c4c..b211fc4 100644
--- a/guide/cheatsheet.md
+++ b/guide/cheatsheet.md
@@ -6,7 +6,7 @@
 
 **Written with**: Claude (Anthropic)
 
-**Version**: 3.5.0 | **Last Updated**: January 2026
+**Version**: 3.6.0 | **Last Updated**: January 2026
 
 ---
 
diff --git a/guide/ultimate-guide.md b/guide/ultimate-guide.md
index 0a1b8a4..78e8f54 100644
--- a/guide/ultimate-guide.md
+++ b/guide/ultimate-guide.md
@@ -10,7 +10,7 @@
 
 **Last updated**: January 2026
 
-**Version**: 3.5.0
+**Version**: 3.6.0
 
 ---
 
@@ -9515,4 +9515,4 @@ Thumbs.db
 
 **Contributions**: Issues and PRs welcome.
 
-**Last updated**: January 2026 | **Version**: 3.0.7
+**Last updated**: January 2026 | **Version**: 3.6.0
diff --git a/scripts/sync-version.sh b/scripts/sync-version.sh
new file mode 100755
index 0000000..f8a8d53
--- /dev/null
+++ b/scripts/sync-version.sh
@@ -0,0 +1,81 @@
+#!/bin/bash
+# sync-version.sh - Sync version from VERSION file to all documentation
+# Usage: ./scripts/sync-version.sh [--check]
+#   --check : Only check, don't modify (exit 1 if mismatch)
+
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+cd "$REPO_ROOT"
+
+# Read source of truth
+if [[ ! -f VERSION ]]; then
+  echo "❌ VERSION file not found"
+  exit 1
+fi
+
+VERSION=$(cat VERSION | tr -d '[:space:]')
+CHECK_ONLY=false
+ERRORS=0
+
+if [[ "${1:-}" == "--check" ]]; then
+  CHECK_ONLY=true
+fi
+
+echo "=== Version Sync ==="
+echo "Source: VERSION → $VERSION"
+echo ""
+
+# Function to check/update a file
+check_file() {
+  local file="$1"
+
+  if [[ ! -f "$file" ]]; then
+    echo "⚠️  $file not found"
+    return
+  fi
+
+  # Find version numbers in file (3.x.x pattern only)
+  local old_versions=$(grep -oE '3\.[0-9]+\.[0-9]+' "$file" 2>/dev/null | sort -u | grep -v "^${VERSION}$" || true)
+
+  if [[ -n "$old_versions" ]]; then
+    echo "📍 $file: found outdated versions"
+    for v in $old_versions; do
+      echo "   - $v → $VERSION"
+    done
+
+    if $CHECK_ONLY; then
+      ERRORS=$((ERRORS + 1))
+    else
+      # Replace all old 3.x.x versions with current version
+      for v in $old_versions; do
+        # macOS compatible sed
+        sed -i '' "s/$v/$VERSION/g" "$file"
+      done
+      echo "✅ $file: updated"
+    fi
+  else
+    # Check if file contains current version
+    if grep -q "$VERSION" "$file" 2>/dev/null; then
+      echo "✅ $file: OK ($VERSION)"
+    else
+      echo "⚠️  $file: no version found"
+    fi
+  fi
+}
+
+# Check main files
+check_file "README.md"
+check_file "guide/cheatsheet.md"
+check_file "guide/ultimate-guide.md"
+check_file "machine-readable/reference.yaml"
+
+echo ""
+
+if $CHECK_ONLY && [[ $ERRORS -gt 0 ]]; then
+  echo "❌ $ERRORS file(s) need version update"
+  echo "Run: ./scripts/sync-version.sh"
+  exit 1
+fi
+
+echo "✅ Done"