feat(ci): implement flat-file automated documentation architecture

.github/workflows/changelog.yml

@@ -5,11 +5,14 @@ on:
     types: [published]
   push:
     tags:
-      - 'v*.*.*'
+      - 'v*.*.*'      # Matches v1.0.0, v2.14.2, etc.
+      - '*.*.*'       # Matches 1.0.0 (no v prefix)
+      - 'v*.*.*-*'    # Matches v1.0.1-alpha.1, v1.2.0-beta.3, v2.0.0-rc.1
+      - '*.*.*-*'     # Matches 1.0.1-alpha.1 (no v prefix)
 
 jobs:
   generate-changelog:
-    runs-on: ubuntu-latest  # Ensure this is here and aligned
+    runs-on: ubuntu-latest
 
     concurrency:
       group: auto-changelog-${{ github.ref_name }}
@@ -41,58 +44,82 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
-      - name: Scaffold Versioned CLI Documentation System
+      - name: Generate Flat Version File & Update README
         env:
           CHANGELOG: ${{ steps.github_release.outputs.changelog }}
         run: |
           VERSION="${{ github.ref_name }}"
-          TARGET_DIR="docs/${VERSION}"
-          TEMPLATE_DIR=".github/docs-template"
+          VERSION_FILE="docs/${VERSION}.md"
 
-          # 1. Create the unique versioned directory hierarchy
-          mkdir -p "$TARGET_DIR"
+          # 1. Create the standalone version document right in the root of docs/
+          echo "# KDM CLI Documentation - ${VERSION}" > "$VERSION_FILE"
+          echo "Published on: $(date +'%Y-%m-%d')" >> "$VERSION_FILE"
+          echo "" >> "$VERSION_FILE"
+          printf '%s\n' "$CHANGELOG" >> "$VERSION_FILE"
 
-          # 2. If a core template folder exists, copy its entire structural hierarchy over
-          if [ -d "$TEMPLATE_DIR" ]; then
-            shopt -s dotglob nullglob
-            template_items=("$TEMPLATE_DIR"/*)
-            if [ ${`#template_items`[@]} -gt 0 ]; then
-              cp -r "${template_items[@]}" "$TARGET_DIR"/
-            fi
-            # 3. Recursively inject the mandatory Version string into every markdown file copied
-            find "$TARGET_DIR" -type f -name "*.md" -exec sh -c '
-              for file; do
-                if ! grep -Fq "**Version:** '"$VERSION"'" "$file"; then
-                  printf "\n---\n**Version:** %s\n" "'"$VERSION"'" >> "$file"
-                fi
-              done
-            ' _ {} +
-          else
-            # Fallback structure if the template directory isn't initialized yet
-            mkdir -p "$TARGET_DIR/config" "$TARGET_DIR/health" "$TARGET_DIR/logs" "$TARGET_DIR/show" "$TARGET_DIR/watch"
-          fi
+          # 2. Build the new dynamic landing page in a temporary file
+          TEMP_README=$(mktemp)
+
+          echo "# Documentation (Latest: ${VERSION})" > "$TEMP_README"
+          echo "" >> "$TEMP_README"
+
+          # 3. Embed the raw content of the new version directly into the README
+          cat "$VERSION_FILE" >> "$TEMP_README"
+
+          echo "" >> "$TEMP_README"
+          echo "---" >> "$TEMP_README"
+          echo "## Version History" >> "$TEMP_README"
+          echo "" >> "$TEMP_README"
+
+          # 4. Safely extract, sort, and process all version documentation files
+          # shopt -s nullglob ensures an unmatched glob pattern expands to nothing rather than its literal string
+          shopt -s nullglob
+
+          # Ingest all docs/*.md files, filter out README.md, version-sort in reverse chronological order
+          mapfile -t version_files < <(printf '%s\n' docs/*.md | grep -v '^docs/README\.md$' | sort -V -r)
 
-          # 4. Generate the dedicated version README.md using the Release Engine Changelog output
-          VERSION_README="$TARGET_DIR/README.md"
-          echo -e "# KDM CLI Documentation - ${VERSION}\n" > "$VERSION_README"
-          echo -e "Published on: $(date +'%Y-%m-%d')\n" >> "$VERSION_README"
-          printf '%s\n' "$CHANGELOG" >> "$VERSION_README"
-          printf '\n---\n**Version Information:** %s\n' "$VERSION" >> "$VERSION_README"
+          # 5. Loop through the array buffer safely without breaking on empty sets or spaces
+          for file in "${version_files[@]}"; do
+            # Double check the file exists to catch empty arrays securely
+            [ -f "$file" ] || continue
+            V_NAME=$(basename "$file" .md)
+            echo "* [$V_NAME]($V_NAME.md)" >> "$TEMP_README"
+          done
+
+          # 6. Overwrite the main docs/README.md with our cleanly compiled template
+          mv "$TEMP_README" docs/README.md
 
       - name: Commit and Push Changes
         run: |
           git config --local user.email "github-actions[bot]@users.noreply.github.com"
           git config --local user.name "github-actions[bot]"
 
           git checkout ${{ github.event.repository.default_branch }}
-          git pull origin ${{ github.event.repository.default_branch }} --ff-only
+          git checkout ${{ github.event.repository.default_branch }}
+
+          # Retry fast-forward pull up to 3 times with exponential backoff
+          max_attempts=3
+          attempt=1
+          while [ $attempt -le $max_attempts ]; do
+            if git pull origin ${{ github.event.repository.default_branch }} --ff-only; then
+              break
+            fi
+            if [ $attempt -eq $max_attempts ]; then
+              echo "ERROR: Failed to fast-forward after $max_attempts attempts"
+              echo "Manual intervention required - docs/ has conflicts"
+              exit 1
+            fi
+            echo "Fast-forward failed (attempt $attempt/$max_attempts), retrying in $((2**attempt))s..."
+            sleep $((2**attempt))
+            ((attempt++))
+          done
 
-          # Track and stage the entire documentation change block
           git add docs/
+
           if git diff --cached --quiet; then
             echo "No documentation changes to commit."
             exit 0
           fi
 
-          git commit -m "docs: auto-scaffold documentation architecture for ${{ github.ref_name }} [skip ci]"
+          git commit -m "docs: auto-scaffold flat documentation for ${{ github.ref_name }} [skip ci]"
           git push origin HEAD:${{ github.event.repository.default_branch }}