carbondirect
diff --git a/‎.github/ISSUE_TEMPLATE/documentation-feedback.yml‎
Lines changed: 2 additions & 2 deletions b/‎.github/ISSUE_TEMPLATE/documentation-feedback.yml‎
Lines changed: 2 additions & 2 deletions
diff --git a/‎.github/WORKFLOWS.md‎
Lines changed: 63 additions & 1 deletion b/‎.github/WORKFLOWS.md‎
Lines changed: 63 additions & 1 deletion
diff --git a/‎.github/workflows/build-deploy.yml‎
Lines changed: 24 additions & 18 deletions b/‎.github/workflows/build-deploy.yml‎
Lines changed: 24 additions & 18 deletions
@@ -3,7 +3,7 @@ description: Report feedback on BOOST documentation (HTML, PDF, ERD Navigator, o
 title: "[DOCS] "
 labels: ["documentation", "feedback"]
 assignees:
-  - pwt-cd
+  - ptittmann
 body:
   - type: markdown
     attributes:
@@ -143,4 +143,4 @@ body:
         
         **Note for Schema-specific feedback**: Please include the specific entity name and field if applicable.
         
-        **Thank you** for taking the time to review and provide feedback on the BOOST documentation!
+        **Thank you** for taking the time to review and provide feedback on the BOOST documentation!
@@ -9,9 +9,10 @@ The BOOST repository uses GitHub Actions to automate documentation building, val
 ### Key Features
 - **🐳 Docker Containerization**: All builds use `ghcr.io/carbondirect/boost/boost-builder:latest` for 4-6x faster execution
 - **🚀 Automatic Releases**: All semantic version tags trigger full release packages  
-- **✅ Schema Validation**: Comprehensive validation of 33+ entity schemas
+- **✅ Schema Validation**: Comprehensive validation of 35+ entity schemas
 - **📄 Multi-Format Output**: HTML, PDF, and interactive ERD Navigator generation
 - **🔍 Version Analysis**: Intelligent version type detection and appropriate release handling
+- **🏷️ Automated Versioning**: Git-based version nomenclature with complete traceability
 
 ## 📋 Workflow Summary
 
@@ -22,6 +23,67 @@ The BOOST repository uses GitHub Actions to automate documentation building, val
 | [📚 Build Documentation](#build-documentation) | Push to branches | Build development docs & deploy | ✅ Docker | ~2-3 min |
 | [🐳 Docker Image Builder](#docker-image-builder) | Dockerfile changes | Build & push container images | ❌ Native | ~5-8 min |
 
+## 🏷️ Version Nomenclature in CI/CD
+
+All BOOST workflows use automated Git-based versioning for complete traceability and reproducible builds.
+
+### **Version Format: `v3.1.3-5-gaac45b1`**
+
+Every build automatically extracts and uses version information following the Git describe format:
+
+| Component | Example | Purpose | Source |
+|-----------|---------|---------|---------|
+| **Base Tag** | `v3.1.3` | Latest semantic version release | Git tags |
+| **Commit Count** | `-5` | Development commits since release | Git history |
+| **Commit Hash** | `-gaac45b1` | Exact code state identifier | Git SHA |
+
+### **Version Extraction Workflow**
+
+#### **Production Builds** (Release & Main Branch)
+```bash
+# 1. Extract version outside Docker container (git access)
+VERSION=$(git describe --tags --always)
+
+# 2. Pass to containerized build via environment variable
+export RELEASE_VERSION="$VERSION"
+
+# 3. Container uses pre-extracted version (no git dependency)
+echo "Building with version: $RELEASE_VERSION"
+```
+
+#### **Development Builds** (Feature Branches)
+```bash
+# Similar process but with development-specific naming
+VERSION="${BASE_TAG}-dev-${SHORT_HASH}"
+
+# Example: v3.1.3-dev-aac45b1 for untagged development
+```
+
+### **Version Usage Across Workflows**
+
+| Workflow | Version Source | Format Example | Usage |
+|----------|---------------|----------------|-------|
+| **Release** | Git tags | `v3.1.3` | GitHub release naming, artifact tagging |
+| **Development** | Git describe | `v3.1.3-5-gaac45b1` | Build identification, artifact naming |
+| **Docker Image** | Git commits | `main-aac45b1` | Container tagging, cache keys |
+
+### **Traceability Benefits**
+
+- **🎯 Exact Reproduction**: Any build can be reproduced with the commit hash
+- **📋 Issue Debugging**: Full version context for troubleshooting
+- **🚀 Release Tracking**: Clear development progress between releases
+- **🔍 Artifact Linking**: Direct connection between builds and source code
+- **📊 Build Analytics**: Version-based performance and success tracking
+
+### **Integration with Documentation**
+
+- **HTML Headers**: Include version for user reference
+- **PDF Metadata**: Embed version for document tracking
+- **Build Logs**: Log version for debugging and audit trails
+- **Artifact Names**: Use version in downloadable package names
+
+This automated versioning ensures every BOOST documentation build has complete provenance tracking from source code to final deliverable.
+
 ## 🏷️ Release Documentation
 
 **File**: `.github/workflows/release.yml`  
 
@@ -131,16 +131,22 @@ jobs:
           echo "🔍 Running comprehensive schema validation..."
           python3 ../../../.github/scripts/validate-schemas.py
 
-      - name: Build HTML documentation
+      - name: Fix container dependencies
+        run: |
+          echo "🔧 Installing missing container dependencies..."
+          pip3 install -r /usr/local/lib/python3.10/dist-packages/requirements.txt || echo "⚠️ Requirements file not found, continuing..."
+          pip3 install pycairo || echo "⚠️ pycairo installation failed, attempting build anyway..."
+
+      - name: Build documentation (HTML and PDF)
         working-directory: drafts/current/specifications
         run: |
-          echo "🏗️ Building HTML documentation..."
+          echo "🏗️ Building documentation with consolidated build system..."
           echo "📋 Branch: ${{ github.ref_name }}"
           echo "🎯 Build type: ${{ github.ref == 'refs/heads/main' && 'Production (with deployment)' || 'Development (build only)' }}"
           echo "🔧 Using version: $RELEASE_VERSION"
           echo "📦 Version source: Pre-extracted outside Docker container"
-          chmod +x build-all.sh
-          ./build-all.sh
+          chmod +x build.sh
+          ./build.sh
 
       - name: Validate build output
         working-directory: drafts/current/specifications
@@ -201,11 +207,11 @@ jobs:
         run: |
           echo "📄 Validating PDF generation for ${{ github.ref_name }} branch..."
           
-          # Check if PDF was generated by build-all.sh
+          # Check if PDF was generated by consolidated build system
           if [ -f "build/boost-spec.pdf" ]; then
             PDF_SIZE=$(wc -c < "build/boost-spec.pdf" | numfmt --to=iec-i --suffix=B)
             PDF_PAGES=$(pdfinfo build/boost-spec.pdf 2>/dev/null | grep Pages | awk '{print $2}' || echo 'Unknown')
-            echo "✅ PDF generated by unified build system:"
+            echo "✅ PDF generated by consolidated build system:"
             echo "   📄 File: build/boost-spec.pdf"
             echo "   📊 Size: $PDF_SIZE"
             echo "   📚 Pages: $PDF_PAGES"
@@ -335,38 +341,38 @@ jobs:
           find build-output -type f -name "*.html" -o -name "*.pdf" -o -name "*.md" | head -10
           
           # Copy main HTML documentation
-          if [ -f "build-output/specifications/boost-spec.html" ]; then
-            cp build-output/specifications/boost-spec.html ./pages-content/
+          if [ -f "build-output/drafts/current/specifications/boost-spec.html" ]; then
+            cp build-output/drafts/current/specifications/boost-spec.html ./pages-content/
             echo "✅ Copied boost-spec.html"
           else
-            echo "❌ boost-spec.html not found at build-output/specifications/boost-spec.html"
+            echo "❌ boost-spec.html not found at build-output/drafts/current/specifications/boost-spec.html"
             exit 1
           fi
           
           # Copy ERD navigator if it exists
-          if [ -d "build-output/specifications/erd-navigator" ]; then
-            cp -r build-output/specifications/erd-navigator ./pages-content/
+          if [ -d "build-output/drafts/current/specifications/erd-navigator" ]; then
+            cp -r build-output/drafts/current/specifications/erd-navigator ./pages-content/
             echo "✅ Copied ERD navigator"
           fi
           
           # Copy build report if it exists
-          if [ -f "build-output/specifications/build-report.md" ]; then
-            cp build-output/specifications/build-report.md ./pages-content/
+          if [ -f "build-output/drafts/current/specifications/build-report.md" ]; then
+            cp build-output/drafts/current/specifications/build-report.md ./pages-content/
             echo "✅ Copied build report"
           fi
           
           # Copy PDF if it exists
-          if [ -f "build-output/specifications/boost-spec.pdf" ]; then
-            cp build-output/specifications/boost-spec.pdf ./pages-content/
+          if [ -f "build-output/drafts/current/specifications/boost-spec.pdf" ]; then
+            cp build-output/drafts/current/specifications/boost-spec.pdf ./pages-content/
             echo "✅ Copied PDF documentation"
           fi
           
           # Copy schema files (for direct access to individual schema files)
-          if [ -d "build-output/schema" ]; then
-            cp -r build-output/schema ./pages-content/
+          if [ -d "build-output/drafts/current/schema" ]; then
+            cp -r build-output/drafts/current/schema ./pages-content/
             echo "✅ Copied schema directory (individual files accessible)"
           else
-            echo "❌ Schema directory not found at build-output/schema"
+            echo "❌ Schema directory not found at build-output/drafts/current/schema"
             # Debug: show what's actually in the build output
             echo "📋 Available paths in build-output:"
             find build-output -name "schema" -type d