docs: expand DEVELOPMENT.md with advanced setup guide

- Enhances documentation with comprehensive project integration details
- Adds extensive example justfile with update and version management
- Includes checks for submodule presence before build operations
- Adds detailed GitHub workflow configuration examples
- Expands troubleshooting section with common issues and solutions

Author: flexiondotorg

docs/DEVELOPMENT.md

@@ -43,15 +43,90 @@ Wrap this in a `just setup` recipe for consistent developer experience.
 ### Example justfile
 
 ```just
-# First-time setup: init submodule + download FFmpeg libraries
+# Check ffmpeg-statigo submodule is present
+_check-submodule:
+    #!/usr/bin/env bash
+    if [ ! -f "third_party/ffmpeg-statigo/go.mod" ]; then
+        echo "Error: ffmpeg-statigo submodule not initialised. Run 'just setup' first."
+        exit 1
+    fi
+    if [ ! -f "third_party/ffmpeg-statigo/lib/$(go env GOOS)_$(go env GOARCH)/libffmpeg.a" ]; then
+        echo "Error: ffmpeg-statigo library not downloaded. Run 'just setup' first."
+        exit 1
+    fi
+
+# Get latest stable ffmpeg-statigo release tag from GitHub
+_get-latest-tag:
+    #!/usr/bin/env bash
+    if command -v jq &> /dev/null; then
+        curl -s https://api.github.com/repos/linuxmatters/ffmpeg-statigo/releases | \
+            jq -r '[.[] | select(.prerelease == false and .draft == false and (.tag_name | startswith("v")))][0].tag_name'
+    else
+        curl -s https://api.github.com/repos/linuxmatters/ffmpeg-statigo/releases | \
+            grep -B5 '"prerelease": false' | grep '"tag_name"' | grep -v 'lib-' | head -1 | cut -d'"' -f4
+    fi
+
+# Setup or update ffmpeg-statigo submodule and library
 setup:
+    #!/usr/bin/env bash
+    set -e
+    echo "Configuring git for submodule-friendly pulls..."
     git config pull.ff only
     git config submodule.recurse true
-    git submodule update --init --recursive
+
+    # Get latest stable release tag
+    TAG=$(just _get-latest-tag)
+    if [ -z "$TAG" ] || [ "$TAG" = "null" ]; then
+        echo "Error: Could not fetch latest release tag"
+        exit 1
+    fi
+
+    # Initialise submodule if not already present
+    if [ ! -f "third_party/ffmpeg-statigo/go.mod" ]; then
+        echo "Initialising ffmpeg-statigo submodule..."
+        git submodule update --init --recursive
+    fi
+
+    # Check current version
+    cd third_party/ffmpeg-statigo
+    git fetch --tags
+    CURRENT=$(git describe --tags --exact-match 2>/dev/null || echo "")
+
+    if [ "$CURRENT" = "$TAG" ]; then
+        echo "ffmpeg-statigo already at latest version ($TAG)"
+        cd ../..
+    else
+        if [ -n "$CURRENT" ]; then
+            echo "Updating ffmpeg-statigo from $CURRENT to $TAG..."
+        else
+            echo "Setting up ffmpeg-statigo $TAG..."
+        fi
+        git checkout "$TAG"
+        cd ../..
+
+        # Remove old library to force re-download
+        rm -f third_party/ffmpeg-statigo/lib/*/libffmpeg.a
+
+        # Stage the submodule change
+        git add third_party/ffmpeg-statigo
+    fi
+
+    # Download libraries (will skip if correct version already exists)
+    echo "Checking ffmpeg-statigo libraries..."
     cd third_party/ffmpeg-statigo && go run ./cmd/download-lib
+    cd ../..
+
+    # Check if there are staged changes to commit
+    if git diff --cached --quiet third_party/ffmpeg-statigo; then
+        echo "Setup complete!"
+    else
+        echo ""
+        echo "Setup complete! Submodule updated to $TAG"
+        echo "Don't forget to commit: git commit -m 'chore: update ffmpeg-statigo to $TAG'"
+    fi
 
 # Build the project
-build:
+build: _check-submodule
     CGO_ENABLED=1 go build -o myapp ./cmd/myapp
 ```