diff --git a/frontends/nextjs/scripts/diagnose-workflows.sh b/frontends/nextjs/scripts/diagnose-workflows.sh
new file mode 100755
index 000000000..3e17b049e
--- /dev/null
+++ b/frontends/nextjs/scripts/diagnose-workflows.sh
@@ -0,0 +1,77 @@
+#!/usr/bin/env bash
+# Diagnose GitHub Actions workflow setup for local execution with act
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/../../.." && pwd)"
+
+echo "🔍 GitHub Actions Workflow Diagnostics"
+echo "======================================="
+echo
+
+# Check if act is installed
+echo "📦 Checking act installation..."
+if ! command -v act &> /dev/null; then
+    echo "❌ act is not installed"
+    echo "   Install with: brew install act"
+    exit 1
+fi
+echo "✅ act version: $(act --version)"
+echo
+
+# Check Docker
+echo "🐳 Checking Docker..."
+if ! command -v docker &> /dev/null; then
+    echo "❌ Docker is not installed"
+    exit 1
+fi
+if ! docker info &> /dev/null; then
+    echo "❌ Docker daemon is not running"
+    exit 1
+fi
+echo "✅ Docker is running"
+echo
+
+# List workflows
+echo "📋 Available workflows in $PROJECT_ROOT/.github/workflows:"
+if [ -d "$PROJECT_ROOT/.github/workflows" ]; then
+    ls -1 "$PROJECT_ROOT/.github/workflows"/*.yml 2>/dev/null | while read -r workflow; do
+        echo "   - $(basename "$workflow")"
+    done
+else
+    echo "❌ No .github/workflows directory found"
+    exit 1
+fi
+echo
+
+# List jobs in main CI workflow
+echo "🏗️  Jobs in ci.yml:"
+if [ -f "$PROJECT_ROOT/.github/workflows/ci.yml" ]; then
+    act -l -W "$PROJECT_ROOT/.github/workflows/ci.yml" 2>/dev/null || echo "   (Failed to parse workflow)"
+else
+    echo "❌ ci.yml not found"
+fi
+echo
+
+# Check for .actrc or .secrets
+echo "🔐 Checking for act configuration..."
+if [ -f "$PROJECT_ROOT/.actrc" ]; then
+    echo "✅ Found .actrc"
+else
+    echo "⚠️  No .actrc found (optional)"
+fi
+
+if [ -f "$PROJECT_ROOT/.secrets" ]; then
+    echo "✅ Found .secrets"
+else
+    echo "⚠️  No .secrets found (optional)"
+fi
+echo
+
+echo "✅ Diagnostics complete!"
+echo
+echo "💡 Tips:"
+echo "   - Run specific job: npm run act:lint"
+echo "   - List all jobs: act -l"
+echo "   - Run with specific platform: act -P ubuntu-latest=catthehacker/ubuntu:act-latest"
diff --git a/frontends/nextjs/scripts/run-act.sh b/frontends/nextjs/scripts/run-act.sh
new file mode 100755
index 000000000..682add4b4
--- /dev/null
+++ b/frontends/nextjs/scripts/run-act.sh
@@ -0,0 +1,78 @@
+#!/usr/bin/env bash
+# Wrapper script to run act with proper configuration
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/../../.." && pwd)"
+
+# Default workflow file
+WORKFLOW="${WORKFLOW:-ci.yml}"
+
+# Check if act is installed
+if ! command -v act &> /dev/null; then
+    echo "❌ act is not installed"
+    echo "   Install with: brew install act"
+    exit 1
+fi
+
+# Parse arguments
+ACT_ARGS=()
+WORKFLOW_FILE=""
+JOB=""
+
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        -w|--workflow)
+            WORKFLOW_FILE="$2"
+            shift 2
+            ;;
+        -j|--job)
+            JOB="$2"
+            shift 2
+            ;;
+        *)
+            ACT_ARGS+=("$1")
+            shift
+            ;;
+    esac
+done
+
+# Set workflow file
+if [ -n "$WORKFLOW_FILE" ]; then
+    WORKFLOW="$WORKFLOW_FILE"
+fi
+
+# Build act command
+ACT_CMD=(act)
+
+# Add workflow file if specified
+if [ -n "$WORKFLOW" ]; then
+    ACT_CMD+=(-W "$PROJECT_ROOT/.github/workflows/$WORKFLOW")
+fi
+
+# Add job if specified
+if [ -n "$JOB" ]; then
+    ACT_CMD+=(-j "$JOB")
+fi
+
+# Add platform specification for better compatibility
+ACT_CMD+=(-P ubuntu-latest=catthehacker/ubuntu:act-latest)
+
+# Add any additional arguments
+ACT_CMD+=("${ACT_ARGS[@]}")
+
+# Add secrets file if it exists
+if [ -f "$PROJECT_ROOT/.secrets" ]; then
+    ACT_CMD+=(--secret-file "$PROJECT_ROOT/.secrets")
+fi
+
+# Add env file if it exists
+if [ -f "$PROJECT_ROOT/.env" ]; then
+    ACT_CMD+=(--env-file "$PROJECT_ROOT/.env")
+fi
+
+# Run act
+echo "🏃 Running: ${ACT_CMD[*]}"
+echo
+"${ACT_CMD[@]}"
diff --git a/frontends/nextjs/scripts/test-workflows.sh b/frontends/nextjs/scripts/test-workflows.sh
new file mode 100755
index 000000000..97fdf65da
--- /dev/null
+++ b/frontends/nextjs/scripts/test-workflows.sh
@@ -0,0 +1,56 @@
+#!/usr/bin/env bash
+# Test GitHub Actions workflows locally using act
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/../../.." && pwd)"
+
+echo "🧪 Testing GitHub Actions Workflows Locally"
+echo "==========================================="
+echo
+
+# Run diagnostics first
+if [ -f "$SCRIPT_DIR/diagnose-workflows.sh" ]; then
+    bash "$SCRIPT_DIR/diagnose-workflows.sh"
+else
+    echo "⚠️  diagnose-workflows.sh not found, skipping diagnostics"
+fi
+
+echo
+echo "🏃 Running workflow tests..."
+echo
+
+# Test lint job
+echo "1️⃣  Testing lint job..."
+if act -W "$PROJECT_ROOT/.github/workflows/ci.yml" -j lint --dryrun; then
+    echo "✅ Lint job syntax valid"
+else
+    echo "❌ Lint job has issues"
+fi
+echo
+
+# Test typecheck job
+echo "2️⃣  Testing typecheck job..."
+if act -W "$PROJECT_ROOT/.github/workflows/ci.yml" -j typecheck --dryrun; then
+    echo "✅ Typecheck job syntax valid"
+else
+    echo "❌ Typecheck job has issues"
+fi
+echo
+
+# Test build job
+echo "3️⃣  Testing build job..."
+if act -W "$PROJECT_ROOT/.github/workflows/ci.yml" -j build --dryrun; then
+    echo "✅ Build job syntax valid"
+else
+    echo "❌ Build job has issues"
+fi
+echo
+
+echo "✅ Workflow test complete!"
+echo
+echo "💡 To actually run workflows (not just validate):"
+echo "   npm run act:lint      # Run lint job"
+echo "   npm run act:typecheck # Run typecheck job"
+echo "   npm run act:build     # Run build job"