ci: Bump version to 0.20.2 [skip ci]

feat: implement PM2 namespace isolation for improved process management
- Updated TypeScript configuration to include test files. - Modified Vitest configuration to include test files from both src and tests directories. - Added ADR-063 documenting the decision and implementation of PM2 namespaces. - Created implementation report detailing the migration to PM2 namespaces. - Developed migration script for transitioning to namespaced PM2 processes. - Updated ecosystem configuration files to define namespaces for production, test, and development environments. - Enhanced workflow files to include namespace flags in all PM2 commands. - Verified migration with comprehensive tests ensuring all processes are correctly namespaced.
2026-02-20 03:52:28 +05:00 · 2026-02-19 14:51:18 -08:00 · 2026-02-19 14:51:17 -08:00 · 2026-02-19 11:28:52 +05:00 · 2026-02-19 11:27:23 +05:00 · 2026-02-18 22:25:56 -08:00
216 changed files with 38355 additions and 9369 deletions
--- a/.env.example
+++ b/.env.example
@@ -59,6 +59,8 @@ GITHUB_CLIENT_SECRET=
 # AI/ML Services
 # ===================
 # REQUIRED: Google Gemini API key for flyer OCR processing
+# NOTE: Test/staging environment deliberately OMITS this to preserve free API quota.
+#       Production has a working key. Deploy warnings in test are expected and safe to ignore.
 GEMINI_API_KEY=your-gemini-api-key

 # ===================
--- a/.gitattributes
+++ b/.gitattributes
@@ -0,0 +1,93 @@
+# .gitattributes
+#
+# Optimize Gitea performance by excluding generated and vendored files
+# from language statistics and indexing.
+#
+# See: https://github.com/github/linguist/blob/master/docs/overrides.md
+
+# =============================================================================
+# Vendored Dependencies
+# =============================================================================
+node_modules/** linguist-vendored
+
+# =============================================================================
+# Generated Files - Coverage Reports
+# =============================================================================
+coverage/** linguist-generated
+.coverage/** linguist-generated
+public/coverage/** linguist-generated
+.nyc_output/** linguist-generated
+
+# =============================================================================
+# Generated Files - Build Artifacts
+# =============================================================================
+dist/** linguist-generated
+build/** linguist-generated
+
+# =============================================================================
+# Generated Files - Test Results
+# =============================================================================
+test-results/** linguist-generated
+playwright-report/** linguist-generated
+playwright-report-visual/** linguist-generated
+.vitest-results/** linguist-generated
+
+# =============================================================================
+# Generated Files - TSOA OpenAPI Spec & Routes
+# =============================================================================
+src/routes/routes.ts linguist-generated
+public/swagger.json linguist-generated
+
+# =============================================================================
+# Documentation Files
+# =============================================================================
+*.md linguist-documentation
+
+# =============================================================================
+# Line Ending Normalization
+# =============================================================================
+# Ensure consistent line endings across platforms
+* text=auto
+
+# Shell scripts should always use LF
+*.sh text eol=lf
+
+# Windows batch files should use CRLF
+*.bat text eol=crlf
+*.cmd text eol=crlf
+
+# SQL files should use LF
+*.sql text eol=lf
+
+# Configuration files
+*.json text
+*.yml text
+*.yaml text
+*.toml text
+*.ini text
+
+# Source code
+*.ts text
+*.tsx text
+*.js text
+*.jsx text
+*.cjs text
+*.mjs text
+*.css text
+*.scss text
+*.html text
+
+# =============================================================================
+# Binary Files (explicit binary to prevent corruption)
+# =============================================================================
+*.png binary
+*.jpg binary
+*.jpeg binary
+*.gif binary
+*.ico binary
+*.pdf binary
+*.woff binary
+*.woff2 binary
+*.ttf binary
+*.eot binary
+*.otf binary
--- a/.gitea/workflows/deploy-to-prod.yml
+++ b/.gitea/workflows/deploy-to-prod.yml
@@ -86,6 +86,12 @@ jobs:
            echo "✅ Schema is up to date. No changes detected."
          fi

+      - name: Generate TSOA OpenAPI Spec and Routes
+        run: |
+          echo "Generating TSOA OpenAPI specification and route handlers..."
+          npm run tsoa:build
+          echo "✅ TSOA files generated successfully"
+
      - name: Build React Application for Production
        # Source Maps (ADR-015): If SENTRY_AUTH_TOKEN is set, the @sentry/vite-plugin will:
        # 1. Generate hidden source maps during build
@@ -119,13 +125,93 @@ jobs:

      - name: Deploy Application to Production Server
        run: |
-          echo "Deploying application files to /var/www/flyer-crawler.projectium.com..."
+          echo "========================================="
+          echo "DEPLOYING TO PRODUCTION SERVER"
+          echo "========================================="
          APP_PATH="/var/www/flyer-crawler.projectium.com"
+
+          # ========================================
+          # LAYER 1: PRE-FLIGHT SAFETY CHECKS
+          # ========================================
+          echo ""
+          echo "--- Pre-Flight Safety Checks ---"
+
+          # Check 1: Verify we're in a git repository
+          if ! git rev-parse --git-dir > /dev/null 2>&1; then
+            echo "❌ FATAL: Not in a git repository! Aborting to prevent data loss."
+            exit 1
+          fi
+          echo "✅ Git repository verified"
+
+          # Check 2: Verify critical files exist before deployment
+          if [ ! -f "package.json" ] || [ ! -f "server.ts" ]; then
+            echo "❌ FATAL: Critical files missing (package.json or server.ts). Aborting."
+            exit 1
+          fi
+          echo "✅ Critical files verified"
+
+          # Check 3: Verify we have actual content to deploy (prevent empty checkout)
+          FILE_COUNT=$(find . -type f | wc -l)
+          if [ "$FILE_COUNT" -lt 10 ]; then
+            echo "❌ FATAL: Suspiciously few files ($FILE_COUNT). Aborting to prevent catastrophic deletion."
+            exit 1
+          fi
+          echo "✅ File count verified: $FILE_COUNT files ready to deploy"
+
+          # ========================================
+          # LAYER 2: STOP PM2 BEFORE FILE OPERATIONS
+          # ========================================
+          echo ""
+          echo "--- Stopping PM2 Processes ---"
+          pm2 stop flyer-crawler-api flyer-crawler-worker flyer-crawler-analytics-worker --namespace flyer-crawler-prod || echo "No production processes to stop"
+          pm2 list --namespace flyer-crawler-prod
+
+          # ========================================
+          # LAYER 3: SAFE RSYNC WITH COMPREHENSIVE EXCLUDES
+          # ========================================
+          echo ""
+          echo "--- Deploying Application Files ---"
          mkdir -p "$APP_PATH"
          mkdir -p "$APP_PATH/flyer-images/icons" "$APP_PATH/flyer-images/archive"
-          rsync -avz --delete --exclude 'node_modules' --exclude '.git' --exclude 'dist' --exclude 'flyer-images' ./ "$APP_PATH/"
-          rsync -avz dist/ "$APP_PATH"
-          echo "Application deployment complete."
+
+          # Deploy backend with critical file exclusions
+          rsync -avz --delete \
+            --exclude 'node_modules' \
+            --exclude '.git' \
+            --exclude 'dist' \
+            --exclude 'flyer-images' \
+            --exclude 'ecosystem.config.cjs' \
+            --exclude 'ecosystem-test.config.cjs' \
+            --exclude 'ecosystem.dev.config.cjs' \
+            --exclude '.env.*' \
+            --exclude 'coverage' \
+            --exclude '.coverage' \
+            --exclude 'test-results' \
+            --exclude 'playwright-report' \
+            --exclude 'playwright-report-visual' \
+            ./ "$APP_PATH/" 2>&1 | tail -20
+
+          echo "✅ Backend files deployed ($(find "$APP_PATH" -type f | wc -l) files)"
+
+          # Deploy frontend assets
+          rsync -avz dist/ "$APP_PATH" 2>&1 | tail -10
+          echo "✅ Frontend assets deployed"
+
+          echo ""
+          echo "========================================="
+          echo "DEPLOYMENT COMPLETE"
+          echo "========================================="
+
+      - name: Log Workflow Metadata
+        run: |
+          echo "=== WORKFLOW METADATA ==="
+          echo "Workflow file: deploy-to-prod.yml"
+          echo "Workflow file hash: $(sha256sum .gitea/workflows/deploy-to-prod.yml | cut -d' ' -f1)"
+          echo "Git commit: $(git rev-parse HEAD)"
+          echo "Git branch: $(git rev-parse --abbrev-ref HEAD)"
+          echo "Timestamp: $(date -u '+%Y-%m-%d %H:%M:%S UTC')"
+          echo "Actor: ${{ gitea.actor }}"
+          echo "=== END METADATA ==="

      - name: Install Backend Dependencies and Restart Production Server
        env:
@@ -165,9 +251,78 @@ jobs:
          cd /var/www/flyer-crawler.projectium.com
          npm install --omit=dev

-          # --- Cleanup Errored Processes ---
-          echo "Cleaning up errored or stopped PM2 processes..."
-          node -e "const exec = require('child_process').execSync; try { const list = JSON.parse(exec('pm2 jlist').toString()); list.forEach(p => { if (p.pm2_env.status === 'errored' || p.pm2_env.status === 'stopped') { console.log('Deleting ' + p.pm2_env.status + ' process: ' + p.name + ' (' + p.pm2_env.pm_id + ')'); try { exec('pm2 delete ' + p.pm2_env.pm_id); } catch(e) { console.error('Failed to delete ' + p.pm2_env.pm_id); } } }); } catch (e) { console.error('Error cleaning up processes:', e); }"
+          # === PRE-CLEANUP PM2 STATE LOGGING ===
+          echo "=== PRE-CLEANUP PM2 STATE ==="
+          pm2 jlist --namespace flyer-crawler-prod
+          echo "=== END PRE-CLEANUP STATE ==="
+
+          # --- Cleanup Errored Processes with Defense-in-Depth Safeguards ---
+          echo "Cleaning up errored or stopped PRODUCTION PM2 processes..."
+          node -e "
+            const exec = require('child_process').execSync;
+            try {
+              const list = JSON.parse(exec('pm2 jlist --namespace flyer-crawler-prod').toString());
+              const prodProcesses = ['flyer-crawler-api', 'flyer-crawler-worker', 'flyer-crawler-analytics-worker'];
+
+              // Filter for processes that match our criteria
+              const targetProcesses = list.filter(p =>
+                (p.pm2_env.status === 'errored' || p.pm2_env.status === 'stopped') &&
+                prodProcesses.includes(p.name)
+              );
+
+              // SAFEGUARD 1: Process count validation
+              const totalProcesses = list.length;
+              if (targetProcesses.length === totalProcesses && totalProcesses > 3) {
+                console.error('SAFETY ABORT: Filter would delete ALL processes!');
+                console.error('Total processes: ' + totalProcesses + ', Target processes: ' + targetProcesses.length);
+                console.error('This indicates a potential filter bug. Aborting cleanup.');
+                process.exit(1);
+              }
+
+              // SAFEGUARD 2: Explicit name verification
+              console.log('Found ' + targetProcesses.length + ' PRODUCTION processes to clean:');
+              targetProcesses.forEach(p => {
+                console.log('  - ' + p.name + ' (status: ' + p.pm2_env.status + ', pm_id: ' + p.pm2_env.pm_id + ')');
+              });
+
+              // Perform the cleanup
+              targetProcesses.forEach(p => {
+                console.log('Deleting ' + p.pm2_env.status + ' production process: ' + p.name + ' (' + p.pm2_env.pm_id + ')');
+                try {
+                  exec('pm2 delete ' + p.pm2_env.pm_id + ' --namespace flyer-crawler-prod');
+                } catch(e) {
+                  console.error('Failed to delete ' + p.pm2_env.pm_id);
+                }
+              });
+
+              console.log('Production process cleanup complete.');
+            } catch (e) {
+              console.error('Error cleaning up processes:', e);
+            }
+          "
+
+          # Save PM2 process list after cleanup to persist deletions
+          echo "Saving PM2 process list after cleanup..."
+          pm2 save --namespace flyer-crawler-prod
+
+          # === POST-CLEANUP VERIFICATION ===
+          echo "=== POST-CLEANUP VERIFICATION ==="
+          pm2 jlist --namespace flyer-crawler-prod | node -e "
+            try {
+              const list = JSON.parse(require('fs').readFileSync(0, 'utf-8'));
+              const prodProcesses = list.filter(p => p.name && p.name.startsWith('flyer-crawler-') && !p.name.endsWith('-test') && !p.name.endsWith('-dev'));
+              console.log('Production processes after cleanup:');
+              prodProcesses.forEach(p => {
+                console.log('  ' + p.name + ': ' + p.pm2_env.status);
+              });
+              if (prodProcesses.length === 0) {
+                console.log('  (no production processes currently running)');
+              }
+            } catch (e) {
+              console.error('Failed to parse PM2 output:', e.message);
+            }
+          "
+          echo "=== END POST-CLEANUP VERIFICATION ==="

          # --- Version Check Logic ---
          # Get the version from the newly deployed package.json
@@ -176,7 +331,7 @@ jobs:

          # Get the running version from PM2 for the main API process
          # We use a small node script to parse the JSON output from pm2 jlist
-          RUNNING_VERSION=$(pm2 jlist | node -e "try { const list = JSON.parse(require('fs').readFileSync(0, 'utf-8')); const app = list.find(p => p.name === 'flyer-crawler-api'); console.log(app ? app.pm2_env.version : ''); } catch(e) { console.log(''); }")
+          RUNNING_VERSION=$(pm2 jlist --namespace flyer-crawler-prod | node -e "try { const list = JSON.parse(require('fs').readFileSync(0, 'utf-8')); const app = list.find(p => p.name === 'flyer-crawler-api'); console.log(app ? app.pm2_env.version : ''); } catch(e) { console.log(''); }")
          echo "Running PM2 Version: $RUNNING_VERSION"

          if [ "${{ gitea.event.inputs.force_reload }}" == "true" ] || [ "$NEW_VERSION" != "$RUNNING_VERSION" ] || [ -z "$RUNNING_VERSION" ]; then
@@ -185,7 +340,7 @@ jobs:
            else
              echo "Version mismatch (Running: $RUNNING_VERSION -> Deployed: $NEW_VERSION) or app not running. Reloading PM2..."
            fi
-            pm2 startOrReload ecosystem.config.cjs --update-env && pm2 save
+            pm2 startOrReload ecosystem.config.cjs --update-env --namespace flyer-crawler-prod && pm2 save --namespace flyer-crawler-prod
            echo "Production backend server reloaded successfully."
          else
            echo "Version $NEW_VERSION is already running. Skipping PM2 reload."
@@ -215,14 +370,14 @@ jobs:
          sleep 5 # Wait a few seconds for the app to start and log its output.

          # Resolve the PM2 ID dynamically to ensure we target the correct process
-          PM2_ID=$(pm2 jlist | node -e "try { const list = JSON.parse(require('fs').readFileSync(0, 'utf-8')); const app = list.find(p => p.name === 'flyer-crawler-api'); console.log(app ? app.pm2_env.pm_id : ''); } catch(e) { console.log(''); }")
+          PM2_ID=$(pm2 jlist --namespace flyer-crawler-prod | node -e "try { const list = JSON.parse(require('fs').readFileSync(0, 'utf-8')); const app = list.find(p => p.name === 'flyer-crawler-api'); console.log(app ? app.pm2_env.pm_id : ''); } catch(e) { console.log(''); }")

          if [ -n "$PM2_ID" ]; then
            echo "Found process ID: $PM2_ID"
-            pm2 describe "$PM2_ID" || echo "Failed to describe process $PM2_ID"
-            pm2 logs "$PM2_ID" --lines 20 --nostream || echo "Failed to get logs for $PM2_ID"
-            pm2 env "$PM2_ID" || echo "Failed to get env for $PM2_ID"
+            pm2 describe "$PM2_ID" --namespace flyer-crawler-prod || echo "Failed to describe process $PM2_ID"
+            pm2 logs "$PM2_ID" --lines 20 --nostream --namespace flyer-crawler-prod || echo "Failed to get logs for $PM2_ID"
+            pm2 env "$PM2_ID" --namespace flyer-crawler-prod || echo "Failed to get env for $PM2_ID"
          else
            echo "Could not find process 'flyer-crawler-api' in pm2 list."
-            pm2 list # Fallback to listing everything to help debug
+            pm2 list --namespace flyer-crawler-prod # Fallback to listing everything to help debug
          fi
--- a/.gitea/workflows/deploy-to-test.yml
+++ b/.gitea/workflows/deploy-to-test.yml
--- a/.gitea/workflows/manual-db-restore.yml
+++ b/.gitea/workflows/manual-db-restore.yml
@@ -56,9 +56,10 @@ jobs:

      - name: Step 1 - Stop Application Server
        run: |
-          echo "Stopping all PM2 processes to release database connections..."
-          pm2 stop all || echo "PM2 processes were not running."
-          echo "✅ Application server stopped."
+          echo "Stopping PRODUCTION PM2 processes to release database connections..."
+          pm2 stop flyer-crawler-api flyer-crawler-worker flyer-crawler-analytics-worker --namespace flyer-crawler-prod || echo "Production PM2 processes were not running."
+          pm2 save --namespace flyer-crawler-prod
+          echo "✅ Production application server stopped and saved."

      - name: Step 2 - Drop and Recreate Database
        run: |
@@ -91,5 +92,5 @@ jobs:
        run: |
          echo "Restarting application server..."
          cd /var/www/flyer-crawler.projectium.com
-          pm2 startOrReload ecosystem.config.cjs --env production && pm2 save
+          pm2 startOrReload ecosystem.config.cjs --env production --namespace flyer-crawler-prod && pm2 save --namespace flyer-crawler-prod
          echo "✅ Application server restarted."
--- a/.gitea/workflows/manual-deploy-major.yml
+++ b/.gitea/workflows/manual-deploy-major.yml
@@ -85,6 +85,12 @@ jobs:
            echo "✅ Schema is up to date. No changes detected."
          fi

+      - name: Generate TSOA OpenAPI Spec and Routes
+        run: |
+          echo "Generating TSOA OpenAPI specification and route handlers..."
+          npm run tsoa:build
+          echo "✅ TSOA files generated successfully"
+
      - name: Build React Application for Production
        run: |
          if [ -z "${{ secrets.VITE_GOOGLE_GENAI_API_KEY }}" ]; then
@@ -109,6 +115,17 @@ jobs:
          rsync -avz dist/ "$APP_PATH"
          echo "Application deployment complete."

+      - name: Log Workflow Metadata
+        run: |
+          echo "=== WORKFLOW METADATA ==="
+          echo "Workflow file: manual-deploy-major.yml"
+          echo "Workflow file hash: $(sha256sum .gitea/workflows/manual-deploy-major.yml | cut -d' ' -f1)"
+          echo "Git commit: $(git rev-parse HEAD)"
+          echo "Git branch: $(git rev-parse --abbrev-ref HEAD)"
+          echo "Timestamp: $(date -u '+%Y-%m-%d %H:%M:%S UTC')"
+          echo "Actor: ${{ gitea.actor }}"
+          echo "=== END METADATA ==="
+
      - name: Install Backend Dependencies and Restart Production Server
        env:
          # --- Production Secrets Injection ---
@@ -138,9 +155,78 @@ jobs:
          cd /var/www/flyer-crawler.projectium.com
          npm install --omit=dev

-          # --- Cleanup Errored Processes ---
-          echo "Cleaning up errored or stopped PM2 processes..."
-          node -e "const exec = require('child_process').execSync; try { const list = JSON.parse(exec('pm2 jlist').toString()); list.forEach(p => { if (p.pm2_env.status === 'errored' || p.pm2_env.status === 'stopped') { console.log('Deleting ' + p.pm2_env.status + ' process: ' + p.name + ' (' + p.pm2_env.pm_id + ')'); try { exec('pm2 delete ' + p.pm2_env.pm_id); } catch(e) { console.error('Failed to delete ' + p.pm2_env.pm_id); } } }); } catch (e) { console.error('Error cleaning up processes:', e); }"
+          # === PRE-CLEANUP PM2 STATE LOGGING ===
+          echo "=== PRE-CLEANUP PM2 STATE ==="
+          pm2 jlist --namespace flyer-crawler-prod
+          echo "=== END PRE-CLEANUP STATE ==="
+
+          # --- Cleanup Errored Processes with Defense-in-Depth Safeguards ---
+          echo "Cleaning up errored or stopped PRODUCTION PM2 processes..."
+          node -e "
+            const exec = require('child_process').execSync;
+            try {
+              const list = JSON.parse(exec('pm2 jlist --namespace flyer-crawler-prod').toString());
+              const prodProcesses = ['flyer-crawler-api', 'flyer-crawler-worker', 'flyer-crawler-analytics-worker'];
+
+              // Filter for processes that match our criteria
+              const targetProcesses = list.filter(p =>
+                (p.pm2_env.status === 'errored' || p.pm2_env.status === 'stopped') &&
+                prodProcesses.includes(p.name)
+              );
+
+              // SAFEGUARD 1: Process count validation
+              const totalProcesses = list.length;
+              if (targetProcesses.length === totalProcesses && totalProcesses > 3) {
+                console.error('SAFETY ABORT: Filter would delete ALL processes!');
+                console.error('Total processes: ' + totalProcesses + ', Target processes: ' + targetProcesses.length);
+                console.error('This indicates a potential filter bug. Aborting cleanup.');
+                process.exit(1);
+              }
+
+              // SAFEGUARD 2: Explicit name verification
+              console.log('Found ' + targetProcesses.length + ' PRODUCTION processes to clean:');
+              targetProcesses.forEach(p => {
+                console.log('  - ' + p.name + ' (status: ' + p.pm2_env.status + ', pm_id: ' + p.pm2_env.pm_id + ')');
+              });
+
+              // Perform the cleanup
+              targetProcesses.forEach(p => {
+                console.log('Deleting ' + p.pm2_env.status + ' production process: ' + p.name + ' (' + p.pm2_env.pm_id + ')');
+                try {
+                  exec('pm2 delete ' + p.pm2_env.pm_id + ' --namespace flyer-crawler-prod');
+                } catch(e) {
+                  console.error('Failed to delete ' + p.pm2_env.pm_id);
+                }
+              });
+
+              console.log('Production process cleanup complete.');
+            } catch (e) {
+              console.error('Error cleaning up processes:', e);
+            }
+          "
+
+          # Save PM2 process list after cleanup to persist deletions
+          echo "Saving PM2 process list after cleanup..."
+          pm2 save --namespace flyer-crawler-prod
+
+          # === POST-CLEANUP VERIFICATION ===
+          echo "=== POST-CLEANUP VERIFICATION ==="
+          pm2 jlist --namespace flyer-crawler-prod | node -e "
+            try {
+              const list = JSON.parse(require('fs').readFileSync(0, 'utf-8'));
+              const prodProcesses = list.filter(p => p.name && p.name.startsWith('flyer-crawler-') && !p.name.endsWith('-test') && !p.name.endsWith('-dev'));
+              console.log('Production processes after cleanup:');
+              prodProcesses.forEach(p => {
+                console.log('  ' + p.name + ': ' + p.pm2_env.status);
+              });
+              if (prodProcesses.length === 0) {
+                console.log('  (no production processes currently running)');
+              }
+            } catch (e) {
+              console.error('Failed to parse PM2 output:', e.message);
+            }
+          "
+          echo "=== END POST-CLEANUP VERIFICATION ==="

          # --- Version Check Logic ---
          # Get the version from the newly deployed package.json
@@ -149,7 +235,7 @@ jobs:

          # Get the running version from PM2 for the main API process
          # We use a small node script to parse the JSON output from pm2 jlist
-          RUNNING_VERSION=$(pm2 jlist | node -e "try { const list = JSON.parse(require('fs').readFileSync(0, 'utf-8')); const app = list.find(p => p.name === 'flyer-crawler-api'); console.log(app ? app.pm2_env.version : ''); } catch(e) { console.log(''); }")
+          RUNNING_VERSION=$(pm2 jlist --namespace flyer-crawler-prod | node -e "try { const list = JSON.parse(require('fs').readFileSync(0, 'utf-8')); const app = list.find(p => p.name === 'flyer-crawler-api'); console.log(app ? app.pm2_env.version : ''); } catch(e) { console.log(''); }")
          echo "Running PM2 Version: $RUNNING_VERSION"

          if [ "${{ gitea.event.inputs.force_reload }}" == "true" ] || [ "$NEW_VERSION" != "$RUNNING_VERSION" ] || [ -z "$RUNNING_VERSION" ]; then
@@ -158,7 +244,7 @@ jobs:
            else
              echo "Version mismatch (Running: $RUNNING_VERSION -> Deployed: $NEW_VERSION) or app not running. Reloading PM2..."
            fi
-            pm2 startOrReload ecosystem.config.cjs --env production --update-env && pm2 save
+            pm2 startOrReload ecosystem.config.cjs --env production --update-env --namespace flyer-crawler-prod && pm2 save --namespace flyer-crawler-prod
            echo "Production backend server reloaded successfully."
          else
            echo "Version $NEW_VERSION is already running. Skipping PM2 reload."
@@ -181,6 +267,6 @@ jobs:
        run: |
          echo "--- Displaying recent PM2 logs for flyer-crawler-api ---"
          sleep 5
-          pm2 describe flyer-crawler-api || echo "Could not find production pm2 process."
-          pm2 logs flyer-crawler-api --lines 20 --nostream || echo "Could not find production pm2 process."
-          pm2 env flyer-crawler-api || echo "Could not find production pm2 process."
+          pm2 describe flyer-crawler-api --namespace flyer-crawler-prod || echo "Could not find production pm2 process."
+          pm2 logs flyer-crawler-api --lines 20 --nostream --namespace flyer-crawler-prod || echo "Could not find production pm2 process."
+          pm2 env flyer-crawler-api --namespace flyer-crawler-prod || echo "Could not find production pm2 process."
--- a/.gitea/workflows/pm2-diagnostics.yml
+++ b/.gitea/workflows/pm2-diagnostics.yml
@@ -0,0 +1,258 @@
+# .gitea/workflows/pm2-diagnostics.yml
+#
+# Comprehensive PM2 diagnostics to identify crash causes and problematic projects
+name: PM2 Diagnostics
+
+on:
+  workflow_dispatch:
+    inputs:
+      capture_interval:
+        description: 'Seconds between PM2 state captures (default: 5)'
+        required: false
+        default: '5'
+      duration:
+        description: 'Total monitoring duration in seconds (default: 60)'
+        required: false
+        default: '60'
+
+jobs:
+  pm2-diagnostics:
+    runs-on: projectium.com
+
+    steps:
+      - name: PM2 Current State Snapshot
+        run: |
+          echo "========================================="
+          echo "PM2 CURRENT STATE SNAPSHOT"
+          echo "========================================="
+          echo ""
+          echo "=== Production Namespace (flyer-crawler-prod) ==="
+          echo "--- PM2 List (Human Readable) ---"
+          pm2 list --namespace flyer-crawler-prod
+          echo ""
+          echo "--- PM2 List (JSON) ---"
+          pm2 jlist --namespace flyer-crawler-prod > /tmp/pm2-state-initial-prod.json
+          cat /tmp/pm2-state-initial-prod.json | jq '.'
+          echo ""
+          echo "=== Test Namespace (flyer-crawler-test) ==="
+          echo "--- PM2 List (Human Readable) ---"
+          pm2 list --namespace flyer-crawler-test
+          echo ""
+          echo "--- PM2 List (JSON) ---"
+          pm2 jlist --namespace flyer-crawler-test > /tmp/pm2-state-initial-test.json
+          cat /tmp/pm2-state-initial-test.json | jq '.'
+          echo ""
+          echo "=== All Namespaces Combined ==="
+          echo "--- PM2 List (All) ---"
+          pm2 list
+          echo ""
+          echo "--- PM2 Daemon Info ---"
+          pm2 info pm2-logrotate || echo "pm2-logrotate not found"
+          echo ""
+          echo "--- PM2 Version ---"
+          pm2 --version
+          echo ""
+          echo "--- Node Version ---"
+          node --version
+
+      - name: PM2 Process Working Directories
+        run: |
+          echo "========================================="
+          echo "PROCESS WORKING DIRECTORIES"
+          echo "========================================="
+          echo ""
+          echo "=== Production Namespace (flyer-crawler-prod) ==="
+          pm2 jlist --namespace flyer-crawler-prod | jq -r '.[] | "Process: \(.name) | CWD: \(.pm2_env.pm_cwd) | Exists: \(if .pm2_env.pm_cwd then "checking..." else "N/A" end)"'
+          echo ""
+          echo "--- Checking if CWDs still exist ---"
+          pm2 jlist --namespace flyer-crawler-prod | jq -r '.[].pm2_env.pm_cwd' | while read cwd; do
+            if [ -n "$cwd" ] && [ "$cwd" != "null" ]; then
+              if [ -d "$cwd" ]; then
+                echo "✅ EXISTS: $cwd"
+              else
+                echo "❌ MISSING: $cwd (THIS WILL CAUSE CRASHES!)"
+              fi
+            fi
+          done
+          echo ""
+          echo "=== Test Namespace (flyer-crawler-test) ==="
+          pm2 jlist --namespace flyer-crawler-test | jq -r '.[] | "Process: \(.name) | CWD: \(.pm2_env.pm_cwd) | Exists: \(if .pm2_env.pm_cwd then "checking..." else "N/A" end)"'
+          echo ""
+          echo "--- Checking if CWDs still exist ---"
+          pm2 jlist --namespace flyer-crawler-test | jq -r '.[].pm2_env.pm_cwd' | while read cwd; do
+            if [ -n "$cwd" ] && [ "$cwd" != "null" ]; then
+              if [ -d "$cwd" ]; then
+                echo "✅ EXISTS: $cwd"
+              else
+                echo "❌ MISSING: $cwd (THIS WILL CAUSE CRASHES!)"
+              fi
+            fi
+          done
+
+      - name: PM2 Log Analysis
+        run: |
+          echo "========================================="
+          echo "PM2 LOG ANALYSIS"
+          echo "========================================="
+          echo ""
+          echo "--- PM2 Daemon Log (Last 100 Lines) ---"
+          tail -100 /home/gitea-runner/.pm2/pm2.log
+          echo ""
+          echo "--- Searching for ENOENT errors ---"
+          grep -i "ENOENT\|no such file or directory\|uv_cwd" /home/gitea-runner/.pm2/pm2.log || echo "No ENOENT errors found"
+          echo ""
+          echo "--- Searching for crash patterns ---"
+          grep -i "crash\|error\|exception" /home/gitea-runner/.pm2/pm2.log | tail -50 || echo "No crashes found"
+
+      - name: Identify All PM2-Managed Projects
+        run: |
+          echo "========================================="
+          echo "ALL PM2-MANAGED PROJECTS"
+          echo "========================================="
+          echo ""
+          echo "=== Production Namespace (flyer-crawler-prod) ==="
+          pm2 jlist --namespace flyer-crawler-prod | jq -r '.[] | "[\(.pm_id)] \(.name) - v\(.pm2_env.version // "N/A") - \(.pm2_env.status) - CWD: \(.pm2_env.pm_cwd)"'
+          echo ""
+          echo "--- Projects by CWD ---"
+          pm2 jlist --namespace flyer-crawler-prod | jq -r '.[].pm2_env.pm_cwd' | sort -u
+          echo ""
+          echo "=== Test Namespace (flyer-crawler-test) ==="
+          pm2 jlist --namespace flyer-crawler-test | jq -r '.[] | "[\(.pm_id)] \(.name) - v\(.pm2_env.version // "N/A") - \(.pm2_env.status) - CWD: \(.pm2_env.pm_cwd)"'
+          echo ""
+          echo "--- Projects by CWD ---"
+          pm2 jlist --namespace flyer-crawler-test | jq -r '.[].pm2_env.pm_cwd' | sort -u
+          echo ""
+          echo "=== All Namespaces (for reference) ==="
+          pm2 jlist | jq -r '.[] | "[\(.pm_id)] \(.name) [ns: \(.pm2_env.namespace // "default")] - \(.pm2_env.status)"'
+          echo ""
+          echo "--- Checking which projects might interfere ---"
+          for dir in /var/www/*; do
+            if [ -d "$dir" ]; then
+              echo ""
+              echo "Directory: $dir"
+              ls -la "$dir" | grep -E "ecosystem|package.json|node_modules" || echo "  No PM2/Node files"
+            fi
+          done
+
+      - name: Monitor PM2 State Over Time
+        run: |
+          echo "========================================="
+          echo "PM2 STATE MONITORING"
+          echo "========================================="
+          echo "Monitoring PM2 for ${{ gitea.event.inputs.duration }} seconds..."
+          echo "Capturing state every ${{ gitea.event.inputs.capture_interval }} seconds"
+          echo ""
+
+          INTERVAL=${{ gitea.event.inputs.capture_interval }}
+          DURATION=${{ gitea.event.inputs.duration }}
+          COUNT=$((DURATION / INTERVAL))
+
+          for i in $(seq 1 $COUNT); do
+            echo "--- Capture $i at $(date) ---"
+            echo ""
+            echo "=== Production Namespace (flyer-crawler-prod) ==="
+            pm2 jlist --namespace flyer-crawler-prod | jq -r '.[] | "\(.name): \(.pm2_env.status) (restarts: \(.pm2_env.restart_time))"'
+
+            # Check for crashes in production
+            CRASHED_PROD=$(pm2 jlist --namespace flyer-crawler-prod | jq '[.[] | select(.pm2_env.status == "errored" or .pm2_env.status == "stopped")] | length')
+            if [ "$CRASHED_PROD" -gt 0 ]; then
+              echo "⚠️  WARNING: $CRASHED_PROD PRODUCTION process(es) in crashed state!"
+              pm2 jlist --namespace flyer-crawler-prod | jq -r '.[] | select(.pm2_env.status == "errored" or .pm2_env.status == "stopped") | "  - \(.name): \(.pm2_env.status)"'
+            fi
+
+            echo ""
+            echo "=== Test Namespace (flyer-crawler-test) ==="
+            pm2 jlist --namespace flyer-crawler-test | jq -r '.[] | "\(.name): \(.pm2_env.status) (restarts: \(.pm2_env.restart_time))"'
+
+            # Check for crashes in test
+            CRASHED_TEST=$(pm2 jlist --namespace flyer-crawler-test | jq '[.[] | select(.pm2_env.status == "errored" or .pm2_env.status == "stopped")] | length')
+            if [ "$CRASHED_TEST" -gt 0 ]; then
+              echo "⚠️  WARNING: $CRASHED_TEST TEST process(es) in crashed state!"
+              pm2 jlist --namespace flyer-crawler-test | jq -r '.[] | select(.pm2_env.status == "errored" or .pm2_env.status == "stopped") | "  - \(.name): \(.pm2_env.status)"'
+            fi
+
+            echo ""
+            sleep $INTERVAL
+          done
+
+      - name: PM2 Dump File Analysis
+        run: |
+          echo "========================================="
+          echo "PM2 DUMP FILE ANALYSIS"
+          echo "========================================="
+          echo "--- Dump file location ---"
+          ls -lh /home/gitea-runner/.pm2/dump.pm2
+          echo ""
+          echo "--- Dump file contents ---"
+          cat /home/gitea-runner/.pm2/dump.pm2 | jq '.'
+          echo ""
+          echo "--- Processes in dump ---"
+          cat /home/gitea-runner/.pm2/dump.pm2 | jq -r '.apps[] | "\(.name) at \(.pm_cwd)"'
+
+      - name: Check for Rogue Deployment Scripts
+        run: |
+          echo "========================================="
+          echo "DEPLOYMENT SCRIPT ANALYSIS"
+          echo "========================================="
+          echo "Checking for scripts that might delete directories..."
+          echo ""
+          for project in flyer-crawler stock-alert; do
+            for env in "" "-test"; do
+              DIR="/var/www/$project$env.projectium.com"
+              if [ -d "$DIR" ]; then
+                echo "--- Project: $project$env ---"
+                echo "Location: $DIR"
+                if [ -f "$DIR/.gitea/workflows/deploy-to-test.yml" ]; then
+                  echo "Has deploy-to-test workflow"
+                  grep -n "rsync.*--delete\|rm -rf" "$DIR/.gitea/workflows/deploy-to-test.yml" | head -5 || echo "No dangerous commands found"
+                fi
+                if [ -f "$DIR/.gitea/workflows/deploy-to-prod.yml" ]; then
+                  echo "Has deploy-to-prod workflow"
+                  grep -n "rsync.*--delete\|rm -rf" "$DIR/.gitea/workflows/deploy-to-prod.yml" | head -5 || echo "No dangerous commands found"
+                fi
+                echo ""
+              fi
+            done
+          done
+
+      - name: Generate Diagnostic Report
+        run: |
+          echo "========================================="
+          echo "DIAGNOSTIC SUMMARY"
+          echo "========================================="
+          echo ""
+          echo "=== Production Namespace (flyer-crawler-prod) ==="
+          echo "Total processes: $(pm2 jlist --namespace flyer-crawler-prod | jq 'length')"
+          echo "Online: $(pm2 jlist --namespace flyer-crawler-prod | jq '[.[] | select(.pm2_env.status == "online")] | length')"
+          echo "Stopped: $(pm2 jlist --namespace flyer-crawler-prod | jq '[.[] | select(.pm2_env.status == "stopped")] | length')"
+          echo "Errored: $(pm2 jlist --namespace flyer-crawler-prod | jq '[.[] | select(.pm2_env.status == "errored")] | length')"
+          echo ""
+          echo "Flyer-crawler PROD processes:"
+          pm2 jlist --namespace flyer-crawler-prod | jq -r '.[] | select(.name | contains("flyer-crawler")) | "  \(.name): \(.pm2_env.status)"'
+          echo ""
+          echo "=== Test Namespace (flyer-crawler-test) ==="
+          echo "Total processes: $(pm2 jlist --namespace flyer-crawler-test | jq 'length')"
+          echo "Online: $(pm2 jlist --namespace flyer-crawler-test | jq '[.[] | select(.pm2_env.status == "online")] | length')"
+          echo "Stopped: $(pm2 jlist --namespace flyer-crawler-test | jq '[.[] | select(.pm2_env.status == "stopped")] | length')"
+          echo "Errored: $(pm2 jlist --namespace flyer-crawler-test | jq '[.[] | select(.pm2_env.status == "errored")] | length')"
+          echo ""
+          echo "Flyer-crawler TEST processes:"
+          pm2 jlist --namespace flyer-crawler-test | jq -r '.[] | select(.name | contains("flyer-crawler")) | "  \(.name): \(.pm2_env.status)"'
+          echo ""
+          echo "=== All Namespaces Summary ==="
+          echo "Total PM2 processes (all): $(pm2 jlist | jq 'length')"
+          echo ""
+          echo "Stock-alert processes (separate project):"
+          pm2 jlist | jq -r '.[] | select(.name | contains("stock-alert")) | "  \(.name): \(.pm2_env.status) [ns: \(.pm2_env.namespace // "default")]"'
+          echo ""
+          echo "Other processes:"
+          pm2 jlist | jq -r '.[] | select(.name | contains("flyer-crawler") | not) | select(.name | contains("stock-alert") | not) | "  \(.name): \(.pm2_env.status) [ns: \(.pm2_env.namespace // "default")]"'
+          echo ""
+          echo "========================================="
+          echo "RECOMMENDATIONS"
+          echo "========================================="
+          echo "1. Check for missing CWDs (marked with ❌ above)"
+          echo "2. Review PM2 daemon log for ENOENT errors"
+          echo "3. Verify no deployments are running rsync --delete while processes are online"
+          echo "4. Use namespace-specific commands: pm2 list --namespace flyer-crawler-prod"
+          echo "5. Avoid pm2 restart all - use namespace targeting instead"
--- a/.gitea/workflows/restart-pm2.yml
+++ b/.gitea/workflows/restart-pm2.yml
@@ -0,0 +1,107 @@
+# .gitea/workflows/restart-pm2.yml
+#
+# Manual workflow to restart PM2 processes and verify their status.
+# Useful for recovering from PM2 daemon crashes or process issues.
+name: Restart PM2 Processes
+
+on:
+  workflow_dispatch:
+    inputs:
+      environment:
+        description: 'Environment to restart (test, production, or both)'
+        required: true
+        default: 'test'
+        type: choice
+        options:
+          - test
+          - production
+          - both
+
+jobs:
+  restart-pm2:
+    runs-on: projectium.com
+
+    steps:
+      - name: Validate Environment Input
+        run: |
+          echo "Restarting PM2 processes for environment: ${{ gitea.event.inputs.environment }}"
+
+      - name: Restart Test Environment
+        if: gitea.event.inputs.environment == 'test' || gitea.event.inputs.environment == 'both'
+        run: |
+          echo "=== RESTARTING TEST ENVIRONMENT ==="
+          cd /var/www/flyer-crawler-test.projectium.com
+
+          echo "--- Current PM2 State (Before Restart) ---"
+          pm2 list --namespace flyer-crawler-test
+
+          echo "--- Restarting Test Processes ---"
+          pm2 restart flyer-crawler-api-test flyer-crawler-worker-test flyer-crawler-analytics-worker-test --namespace flyer-crawler-test || {
+            echo "Restart failed, attempting to start processes..."
+            pm2 start ecosystem-test.config.cjs --namespace flyer-crawler-test
+          }
+
+          echo "--- Saving PM2 Process List ---"
+          pm2 save --namespace flyer-crawler-test
+
+          echo "--- Waiting 3 seconds for processes to stabilize ---"
+          sleep 3
+
+          echo "=== TEST ENVIRONMENT STATUS ==="
+          pm2 ps --namespace flyer-crawler-test
+
+      - name: Restart Production Environment
+        if: gitea.event.inputs.environment == 'production' || gitea.event.inputs.environment == 'both'
+        run: |
+          echo "=== RESTARTING PRODUCTION ENVIRONMENT ==="
+          cd /var/www/flyer-crawler.projectium.com
+
+          echo "--- Current PM2 State (Before Restart) ---"
+          pm2 list --namespace flyer-crawler-prod
+
+          echo "--- Restarting Production Processes ---"
+          pm2 restart flyer-crawler-api flyer-crawler-worker flyer-crawler-analytics-worker --namespace flyer-crawler-prod || {
+            echo "Restart failed, attempting to start processes..."
+            pm2 start ecosystem.config.cjs --namespace flyer-crawler-prod
+          }
+
+          echo "--- Saving PM2 Process List ---"
+          pm2 save --namespace flyer-crawler-prod
+
+          echo "--- Waiting 3 seconds for processes to stabilize ---"
+          sleep 3
+
+          echo "=== PRODUCTION ENVIRONMENT STATUS ==="
+          pm2 ps --namespace flyer-crawler-prod
+
+      - name: Final PM2 Status (All Processes)
+        run: |
+          echo "========================================="
+          echo "FINAL PM2 STATUS - ALL PROCESSES"
+          echo "========================================="
+
+          if [ "${{ gitea.event.inputs.environment }}" = "test" ]; then
+            echo "--- Test Namespace ---"
+            pm2 ps --namespace flyer-crawler-test
+            echo ""
+            echo "--- PM2 Logs (Last 20 Lines) ---"
+            pm2 logs --namespace flyer-crawler-test --lines 20 --nostream || echo "No logs available"
+          elif [ "${{ gitea.event.inputs.environment }}" = "production" ]; then
+            echo "--- Production Namespace ---"
+            pm2 ps --namespace flyer-crawler-prod
+            echo ""
+            echo "--- PM2 Logs (Last 20 Lines) ---"
+            pm2 logs --namespace flyer-crawler-prod --lines 20 --nostream || echo "No logs available"
+          else
+            echo "--- Test Namespace ---"
+            pm2 ps --namespace flyer-crawler-test
+            echo ""
+            echo "--- Production Namespace ---"
+            pm2 ps --namespace flyer-crawler-prod
+            echo ""
+            echo "--- PM2 Logs - Test (Last 10 Lines) ---"
+            pm2 logs --namespace flyer-crawler-test --lines 10 --nostream || echo "No logs available"
+            echo ""
+            echo "--- PM2 Logs - Production (Last 10 Lines) ---"
+            pm2 logs --namespace flyer-crawler-prod --lines 10 --nostream || echo "No logs available"
+          fi
--- a/.gitea/workflows/sync-test-version.yml
+++ b/.gitea/workflows/sync-test-version.yml
@@ -0,0 +1,100 @@
+# .gitea/workflows/sync-test-version.yml
+#
+# Lightweight workflow to sync version numbers from production to test environment.
+# This runs after successful production deployments to update test PM2 metadata
+# without re-running the full test suite, build, and deployment pipeline.
+#
+# Duration: ~30 seconds (vs 5+ minutes for full test deployment)
+name: Sync Test Version
+
+on:
+  workflow_run:
+    workflows: ["Deploy to Production"]
+    types:
+      - completed
+    branches:
+      - main
+
+jobs:
+  sync-version:
+    runs-on: projectium.com
+    # Only run if the production deployment succeeded
+    if: ${{ gitea.event.workflow_run.conclusion == 'success' }}
+
+    steps:
+      - name: Checkout Latest Code
+        uses: actions/checkout@v3
+        with:
+          fetch-depth: 1 # Shallow clone, we only need latest commit
+
+      - name: Update Test Package Version
+        run: |
+          echo "========================================="
+          echo "SYNCING VERSION TO TEST ENVIRONMENT"
+          echo "========================================="
+
+          APP_PATH="/var/www/flyer-crawler-test.projectium.com"
+
+          # Get version from this repo's package.json
+          NEW_VERSION=$(node -p "require('./package.json').version")
+          echo "Production version: $NEW_VERSION"
+
+          # Get current test version
+          if [ -f "$APP_PATH/package.json" ]; then
+            CURRENT_VERSION=$(node -p "require('$APP_PATH/package.json').version")
+            echo "Current test version: $CURRENT_VERSION"
+          else
+            CURRENT_VERSION="unknown"
+            echo "Test package.json not found"
+          fi
+
+          # Only update if versions differ
+          if [ "$NEW_VERSION" != "$CURRENT_VERSION" ]; then
+            echo "Updating test package.json to version $NEW_VERSION..."
+
+            # Update just the version field in test's package.json
+            cd "$APP_PATH"
+            npm version "$NEW_VERSION" --no-git-tag-version --allow-same-version
+
+            echo "✅ Test package.json updated to $NEW_VERSION"
+          else
+            echo "ℹ️  Versions already match, no update needed"
+          fi
+
+      - name: Restart Test PM2 Processes
+        run: |
+          echo "Restarting test PM2 processes to refresh version metadata..."
+
+          # Restart with --update-env to pick up new package.json version
+          pm2 --namespace flyer-crawler-test restart flyer-crawler-api-test flyer-crawler-worker-test flyer-crawler-analytics-worker-test --update-env && pm2 --namespace flyer-crawler-test save
+
+          echo "✅ Test PM2 processes restarted and saved"
+
+          # Show current state
+          echo ""
+          echo "--- Current PM2 State ---"
+          pm2 --namespace flyer-crawler-test list
+
+          # Verify version in PM2 metadata
+          echo ""
+          echo "--- Verifying Version in PM2 ---"
+          pm2 --namespace flyer-crawler-test jlist | node -e "
+            try {
+              const list = JSON.parse(require('fs').readFileSync(0, 'utf-8'));
+              const testProcesses = list.filter(p => p.name && p.name.endsWith('-test'));
+              testProcesses.forEach(p => {
+                console.log(p.name + ': v' + (p.pm2_env.version || 'unknown') + ' (' + p.pm2_env.status + ')');
+              });
+            } catch(e) {
+              console.error('Failed to parse PM2 output');
+            }
+          "
+
+      - name: Summary
+        run: |
+          echo "========================================="
+          echo "VERSION SYNC COMPLETE"
+          echo "========================================="
+          echo "Test environment version updated to match production"
+          echo "No tests run, no builds performed"
+          echo "Duration: ~30 seconds"
--- a/.gitignore
+++ b/.gitignore
@@ -14,6 +14,10 @@ dist-ssr
 .env
 *.tsbuildinfo

+# tsoa generated files (regenerated on build)
+src/routes/tsoa-generated.ts
+src/config/tsoa-spec.json
+
 # Test coverage
 coverage
 .nyc_output
--- a/.husky/pre-commit.disabled
+++ b/.husky/pre-commit.disabled
--- a/.nvmrc
+++ b/.nvmrc
@@ -0,0 +1 @@
+22
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -45,6 +45,129 @@ Out-of-sync = test failures.
 - Maximum 3 fix commands at a time (errors may cascade)
 - Always verify after fixes complete

+### PM2 Namespace Isolation (Production/Test Servers)
+
+**CRITICAL**: Production and test environments share the same PM2 daemon on the server.
+
+Flyer-crawler uses PM2 namespaces to isolate test and production processes:
+
+| Namespace             | Purpose                   | Config File                 |
+| --------------------- | ------------------------- | --------------------------- |
+| `flyer-crawler-prod`  | Production environment    | `ecosystem.config.cjs`      |
+| `flyer-crawler-test`  | Test environment          | `ecosystem-test.config.cjs` |
+| `flyer-crawler-dev`   | Development container     | `ecosystem.dev.config.cjs`  |
+
+This prevents `pm2 save` race conditions during simultaneous deployments. See [ADR-063](docs/adr/0063-pm2-namespace-implementation.md) for details.
+
+**See also**: [PM2 Process Isolation Incidents](#pm2-process-isolation-incidents) for past incidents and response procedures.
+
+| Environment | Processes                                                                                    | Namespace             |
+| ----------- | -------------------------------------------------------------------------------------------- | --------------------- |
+| Production  | `flyer-crawler-api`, `flyer-crawler-worker`, `flyer-crawler-analytics-worker`                | `flyer-crawler-prod`  |
+| Test        | `flyer-crawler-api-test`, `flyer-crawler-worker-test`, `flyer-crawler-analytics-worker-test` | `flyer-crawler-test`  |
+| Development | `flyer-crawler-api-dev`, `flyer-crawler-worker-dev`, `flyer-crawler-vite-dev`                | `flyer-crawler-dev`   |
+
+**Deployment Scripts MUST:**
+
+- ✅ Use `--namespace` flag for all PM2 commands to scope to correct environment
+- ✅ Filter PM2 commands by exact process names or name patterns (e.g., `endsWith('-test')`)
+- ❌ NEVER use `pm2 stop all`, `pm2 delete all`, or `pm2 restart all` without namespace
+- ❌ NEVER delete/stop processes based solely on status without name filtering
+- ✅ Always verify process names match the target environment before any operation
+
+**Examples:**
+
+```bash
+# ✅ CORRECT - Production commands with namespace
+pm2 start ecosystem.config.cjs --namespace flyer-crawler-prod
+pm2 stop flyer-crawler-api flyer-crawler-worker --namespace flyer-crawler-prod
+pm2 restart all --namespace flyer-crawler-prod && pm2 save --namespace flyer-crawler-prod
+pm2 logs --namespace flyer-crawler-prod
+
+# ✅ CORRECT - Test commands with namespace
+pm2 start ecosystem-test.config.cjs --namespace flyer-crawler-test
+pm2 status --namespace flyer-crawler-test
+pm2 delete all --namespace flyer-crawler-test && pm2 save --namespace flyer-crawler-test
+
+# ✅ CORRECT - Dev container commands with namespace
+pm2 start ecosystem.dev.config.cjs --namespace flyer-crawler-dev
+pm2 logs --namespace flyer-crawler-dev
+
+# ✅ CORRECT - Test cleanup (filter by namespace + name pattern)
+# Only delete test processes that are errored/stopped
+list.forEach(p => {
+  if ((p.pm2_env.status === 'errored' || p.pm2_env.status === 'stopped') &&
+      p.name && p.name.endsWith('-test') &&
+      p.pm2_env.namespace === 'flyer-crawler-test') {
+    exec('pm2 delete ' + p.pm2_env.pm_id + ' --namespace flyer-crawler-test');
+  }
+});
+exec('pm2 save --namespace flyer-crawler-test');
+
+# ❌ WRONG - Missing namespace (affects all environments)
+pm2 stop all
+pm2 delete all
+pm2 restart all
+
+# ❌ WRONG - No name/namespace filtering (could delete test processes during prod deploy)
+if (p.pm2_env.status === 'errored') {
+  exec('pm2 delete ' + p.pm2_env.pm_id);
+}
+```
+
+### PM2 Save Requirement (CRITICAL)
+
+**CRITICAL**: Every `pm2 start`, `pm2 restart`, `pm2 stop`, or `pm2 delete` command MUST be immediately followed by `pm2 save` with the same namespace.
+
+Without `pm2 save`, processes become ephemeral and will disappear on:
+
+- PM2 daemon restarts
+- Server reboots
+- Internal PM2 reconciliation events
+
+**Pattern:**
+
+```bash
+# ✅ CORRECT - Save after every state change (with namespace)
+pm2 start ecosystem.config.cjs --namespace flyer-crawler-prod && pm2 save --namespace flyer-crawler-prod
+pm2 restart my-app --namespace flyer-crawler-prod && pm2 save --namespace flyer-crawler-prod
+pm2 stop my-app --namespace flyer-crawler-test && pm2 save --namespace flyer-crawler-test
+pm2 delete my-app --namespace flyer-crawler-test && pm2 save --namespace flyer-crawler-test
+
+# ❌ WRONG - Missing save (processes become ephemeral)
+pm2 start ecosystem.config.cjs --namespace flyer-crawler-prod
+pm2 restart my-app --namespace flyer-crawler-prod
+
+# ❌ WRONG - Missing namespace (affects wrong environment)
+pm2 start ecosystem.config.cjs && pm2 save
+```
+
+**In Cleanup Scripts:**
+
+```javascript
+// ✅ CORRECT - Save after cleanup loop completes (with namespace)
+const namespace = 'flyer-crawler-test';
+targetProcesses.forEach((p) => {
+  exec(`pm2 delete ${p.pm2_env.pm_id} --namespace ${namespace}`);
+});
+exec(`pm2 save --namespace ${namespace}`); // Persist all deletions
+
+// ❌ WRONG - Missing save and namespace
+targetProcesses.forEach((p) => {
+  exec('pm2 delete ' + p.pm2_env.pm_id);
+});
+```
+
+**Why This Matters:**
+
+PM2 maintains an in-memory process list. The `pm2 save` command writes this list to `~/.pm2/dump.pm2`, which PM2 uses to resurrect processes after daemon restarts. Without it, your carefully managed process state is lost. Using namespaces ensures that `pm2 save` in one environment does not affect another.
+
+**See Also:**
+
+- [ADR-014: Containerization and Deployment Strategy](docs/adr/0014-containerization-and-deployment-strategy.md)
+- [ADR-061: PM2 Process Isolation Safeguards](docs/adr/0061-pm2-process-isolation-safeguards.md)
+- [ADR-063: PM2 Namespace Implementation](docs/adr/0063-pm2-namespace-implementation.md)
+
 ### Communication Style

 Ask before assuming. Never assume:
@@ -58,7 +181,7 @@ Ask before assuming. Never assume:
 1. **Memory**: `mcp__memory__read_graph` - Recall project context, credentials, known issues
 2. **Git**: `git log --oneline -10` - Recent changes
 3. **Containers**: `mcp__podman__container_list` - Running state
-4. **PM2 Status**: `podman exec flyer-crawler-dev pm2 status` - Process health (API, Worker, Vite)
+4. **PM2 Status**: `podman exec flyer-crawler-dev pm2 status --namespace flyer-crawler-dev` - Process health (API, Worker, Vite)

 ---

@@ -66,15 +189,17 @@ Ask before assuming. Never assume:

 ### Essential Commands

-| Command                                                      | Description           |
-| ------------------------------------------------------------ | --------------------- |
-| `podman exec -it flyer-crawler-dev npm test`                 | Run all tests         |
-| `podman exec -it flyer-crawler-dev npm run test:unit`        | Unit tests only       |
-| `podman exec -it flyer-crawler-dev npm run type-check`       | TypeScript check      |
-| `podman exec -it flyer-crawler-dev npm run test:integration` | Integration tests     |
-| `podman exec -it flyer-crawler-dev pm2 status`               | PM2 process status    |
-| `podman exec -it flyer-crawler-dev pm2 logs`                 | View all PM2 logs     |
-| `podman exec -it flyer-crawler-dev pm2 restart all`          | Restart all processes |
+| Command                                                                              | Description              |
+| ------------------------------------------------------------------------------------ | ------------------------ |
+| `podman exec -it flyer-crawler-dev npm test`                                         | Run all tests            |
+| `podman exec -it flyer-crawler-dev npm run test:unit`                                | Unit tests only          |
+| `podman exec -it flyer-crawler-dev npm run type-check`                               | TypeScript check         |
+| `podman exec -it flyer-crawler-dev npm run test:integration`                         | Integration tests        |
+| `podman exec -it flyer-crawler-dev pm2 status --namespace flyer-crawler-dev`         | PM2 process status (dev) |
+| `podman exec -it flyer-crawler-dev pm2 logs --namespace flyer-crawler-dev`           | View PM2 logs (dev)      |
+| `podman exec -it flyer-crawler-dev pm2 restart all --namespace flyer-crawler-dev`    | Restart all (dev)        |
+| `pm2 status --namespace flyer-crawler-prod`                                          | PM2 status (production)  |
+| `pm2 status --namespace flyer-crawler-test`                                          | PM2 status (test)        |

 ### Key Patterns (with file locations)

@@ -246,6 +371,39 @@ Common issues with solutions:

 **Full Details**: See test issues section at end of this document or [docs/development/TESTING.md](docs/development/TESTING.md)

+### PM2 Process Isolation Incidents
+
+**CRITICAL**: PM2 process cleanup scripts can affect all PM2 processes if not properly filtered.
+
+**Incident**: 2026-02-17 Production Deployment (v0.15.0)
+
+- **Impact**: ALL PM2 processes on production server were killed
+- **Affected**: stock-alert.projectium.com and all other PM2-managed applications
+- **Root Cause**: Under investigation (see [incident report](docs/operations/INCIDENT-2026-02-17-PM2-PROCESS-KILL.md))
+- **Status**: Safeguards added to prevent recurrence
+
+**Prevention Measures** (implemented):
+
+1. Name-based filtering (exact match or pattern-based)
+2. Pre-cleanup process list logging
+3. Process count validation (abort if filtering all processes)
+4. Explicit name verification in logs
+5. Post-cleanup verification
+6. Workflow version hash logging
+
+**If PM2 Incident Occurs**:
+
+- **DO NOT** attempt another deployment immediately
+- Follow the [PM2 Incident Response Runbook](docs/operations/PM2-INCIDENT-RESPONSE.md)
+- Manually restore affected processes
+- Investigate workflow execution logs before next deployment
+
+**Related Documentation**:
+
+- [PM2 Namespace Isolation](#pm2-namespace-isolation-productiontest-servers) (existing section)
+- [Incident Report 2026-02-17](docs/operations/INCIDENT-2026-02-17-PM2-PROCESS-KILL.md)
+- [PM2 Incident Response Runbook](docs/operations/PM2-INCIDENT-RESPONSE.md)
+
 ### Git Bash Path Conversion (Windows)

 Git Bash auto-converts Unix paths, breaking container commands.
--- a/README.md
+++ b/README.md
@@ -49,8 +49,8 @@ npm run dev

 The application will be available at:

- **Frontend**: http://localhost:5173
- **Backend API**: http://localhost:3001
+- **Frontend**: <http://localhost:5173>
+- **Backend API**: <http://localhost:3001>

 See [docs/getting-started/INSTALL.md](docs/getting-started/INSTALL.md) for detailed setup instructions including:

@@ -88,7 +88,7 @@ See [docs/development/TESTING.md](docs/development/TESTING.md) for testing guide
 | [⚙️ Installation Guide](docs/getting-started/INSTALL.md)  | Local development setup with Podman     |
 | [🏗️ Architecture Overview](docs/architecture/DATABASE.md) | System design, database, authentication |
 | [💻 Development Guide](docs/development/TESTING.md)       | Testing, debugging, code patterns       |
-| [🚀 Deployment Guide](docs/operations/DEPLOYMENT.md)      | Production setup, NGINX, PM2            |
+| [🚀 Deployment Guide](docs/operations/DEPLOYMENT.md)      | Production setup, NGINX, PM2 namespaces |
 | [🤖 AI Agent Guides](docs/subagents/OVERVIEW.md)          | Working with Claude Code subagents      |

 ### Quick References
@@ -126,13 +126,13 @@ See [INSTALL.md](INSTALL.md) for the complete list.

 ## Scripts

-| Command              | Description                      |
-| -------------------- | -------------------------------- |
-| `npm run dev`        | Start development server         |
-| `npm run build`      | Build for production             |
-| `npm run start:prod` | Start production server with PM2 |
-| `npm run test`       | Run test suite                   |
-| `npm run seed`       | Seed development user accounts   |
+| Command              | Description                                                  |
+| -------------------- | ------------------------------------------------------------ |
+| `npm run dev`        | Start development server                                     |
+| `npm run build`      | Build for production                                         |
+| `npm run start:prod` | Start production server with PM2 (uses namespace isolation)  |
+| `npm run test`       | Run test suite                                               |
+| `npm run seed`       | Seed development user accounts                               |

 ---

--- a/docs/MANUAL_TESTING_PLAN.md
+++ b/docs/MANUAL_TESTING_PLAN.md
@@ -56,7 +56,7 @@ podman exec -it flyer-crawler-dev npm run dev:container

 **Pass/Fail**: [ ]

-**Notes**: **********************\_\_\_**********************
+**Notes**: \***\*\*\*\*\***\*\*\***\*\*\*\*\***\_\_\_\***\*\*\*\*\***\*\*\***\*\*\*\*\***

 ---

@@ -90,7 +90,7 @@ podman exec -it flyer-crawler-dev npm run dev:container

 **Pass/Fail**: [ ]

-**Notes**: **********************\_\_\_**********************
+**Notes**: \***\*\*\*\*\***\*\*\***\*\*\*\*\***\_\_\_\***\*\*\*\*\***\*\*\***\*\*\*\*\***

 ---

@@ -114,7 +114,7 @@ podman exec -it flyer-crawler-dev npm run dev:container

 **Pass/Fail**: [ ]

-**Notes**: **********************\_\_\_**********************
+**Notes**: \***\*\*\*\*\***\*\*\***\*\*\*\*\***\_\_\_\***\*\*\*\*\***\*\*\***\*\*\*\*\***

 ---

@@ -138,7 +138,7 @@ podman exec -it flyer-crawler-dev npm run dev:container

 **Pass/Fail**: [ ]

-**Notes**: **********************\_\_\_**********************
+**Notes**: \***\*\*\*\*\***\*\*\***\*\*\*\*\***\_\_\_\***\*\*\*\*\***\*\*\***\*\*\*\*\***

 ---

@@ -161,7 +161,7 @@ podman exec -it flyer-crawler-dev npm run dev:container

 **Pass/Fail**: [ ]

-**Notes**: **********************\_\_\_**********************
+**Notes**: \***\*\*\*\*\***\*\*\***\*\*\*\*\***\_\_\_\***\*\*\*\*\***\*\*\***\*\*\*\*\***

 ---

@@ -189,7 +189,7 @@ podman exec -it flyer-crawler-dev npm run dev:container

 **Pass/Fail**: [ ]

-**Notes**: **********************\_\_\_**********************
+**Notes**: \***\*\*\*\*\***\*\*\***\*\*\*\*\***\_\_\_\***\*\*\*\*\***\*\*\***\*\*\*\*\***

 ---

@@ -211,7 +211,7 @@ podman exec -it flyer-crawler-dev npm run dev:container

 **Pass/Fail**: [ ]

-**Notes**: **********************\_\_\_**********************
+**Notes**: \***\*\*\*\*\***\*\*\***\*\*\*\*\***\_\_\_\***\*\*\*\*\***\*\*\***\*\*\*\*\***

 ---

@@ -234,7 +234,7 @@ podman exec -it flyer-crawler-dev npm run dev:container

 **Pass/Fail**: [ ]

-**Notes**: **********************\_\_\_**********************
+**Notes**: \***\*\*\*\*\***\*\*\***\*\*\*\*\***\_\_\_\***\*\*\*\*\***\*\*\***\*\*\*\*\***

 ---

@@ -259,7 +259,7 @@ podman exec -it flyer-crawler-dev npm run dev:container

 **Pass/Fail**: [ ]

-**Notes**: **********************\_\_\_**********************
+**Notes**: \***\*\*\*\*\***\*\*\***\*\*\*\*\***\_\_\_\***\*\*\*\*\***\*\*\***\*\*\*\*\***

 ---

@@ -284,7 +284,7 @@ podman exec -it flyer-crawler-dev npm run dev:container

 **Pass/Fail**: [ ]

-**Notes**: **********************\_\_\_**********************
+**Notes**: \***\*\*\*\*\***\*\*\***\*\*\*\*\***\_\_\_\***\*\*\*\*\***\*\*\***\*\*\*\*\***

 ---

@@ -307,7 +307,7 @@ podman exec -it flyer-crawler-dev npm run dev:container

 **Pass/Fail**: [ ]

-**Notes**: **********************\_\_\_**********************
+**Notes**: \***\*\*\*\*\***\*\*\***\*\*\*\*\***\_\_\_\***\*\*\*\*\***\*\*\***\*\*\*\*\***

 ---

@@ -330,7 +330,7 @@ podman exec -it flyer-crawler-dev npm run dev:container

 **Pass/Fail**: [ ]

-**Notes**: **********************\_\_\_**********************
+**Notes**: \***\*\*\*\*\***\*\*\***\*\*\*\*\***\_\_\_\***\*\*\*\*\***\*\*\***\*\*\*\*\***

 ---

@@ -355,7 +355,7 @@ podman exec -it flyer-crawler-dev npm run dev:container

 **Pass/Fail**: [ ]

-**Notes**: **********************\_\_\_**********************
+**Notes**: \***\*\*\*\*\***\*\*\***\*\*\*\*\***\_\_\_\***\*\*\*\*\***\*\*\***\*\*\*\*\***

 ---

@@ -379,7 +379,7 @@ podman exec -it flyer-crawler-dev npm run dev:container

 **Pass/Fail**: [ ]

-**Notes**: **********************\_\_\_**********************
+**Notes**: \***\*\*\*\*\***\*\*\***\*\*\*\*\***\_\_\_\***\*\*\*\*\***\*\*\***\*\*\*\*\***

 ---

@@ -425,7 +425,7 @@ podman exec -it flyer-crawler-dev npm run dev:container

 **Pass/Fail**: [ ]

-**Notes**: **********************\_\_\_**********************
+**Notes**: \***\*\*\*\*\***\*\*\***\*\*\*\*\***\_\_\_\***\*\*\*\*\***\*\*\***\*\*\*\*\***

 ---

@@ -448,7 +448,7 @@ podman exec -it flyer-crawler-dev npm run dev:container

 **Pass/Fail**: [ ]

-**Notes**: **********************\_\_\_**********************
+**Notes**: \***\*\*\*\*\***\*\*\***\*\*\*\*\***\_\_\_\***\*\*\*\*\***\*\*\***\*\*\*\*\***

 ---

@@ -476,7 +476,7 @@ podman exec -it flyer-crawler-dev npm run dev:container

 **Pass/Fail**: [ ]

-**Notes**: **********************\_\_\_**********************
+**Notes**: \***\*\*\*\*\***\*\*\***\*\*\*\*\***\_\_\_\***\*\*\*\*\***\*\*\***\*\*\*\*\***

 ---

@@ -502,7 +502,7 @@ podman exec -it flyer-crawler-dev npm run dev:container

 **Pass/Fail**: [ ]

-**Notes**: **********************\_\_\_**********************
+**Notes**: \***\*\*\*\*\***\*\*\***\*\*\*\*\***\_\_\_\***\*\*\*\*\***\*\*\***\*\*\*\*\***

 ---

@@ -529,7 +529,7 @@ podman exec -it flyer-crawler-dev npm run dev:container

 **Pass/Fail**: [ ]

-**Notes**: **********************\_\_\_**********************
+**Notes**: \***\*\*\*\*\***\*\*\***\*\*\*\*\***\_\_\_\***\*\*\*\*\***\*\*\***\*\*\*\*\***

 ---

@@ -555,7 +555,7 @@ podman exec -it flyer-crawler-dev npm run dev:container

 **Pass/Fail**: [ ]

-**Notes**: **********************\_\_\_**********************
+**Notes**: \***\*\*\*\*\***\*\*\***\*\*\*\*\***\_\_\_\***\*\*\*\*\***\*\*\***\*\*\*\*\***

 ---

@@ -579,7 +579,7 @@ podman exec -it flyer-crawler-dev npm run dev:container

 **Pass/Fail**: [ ]

-**Notes**: **********************\_\_\_**********************
+**Notes**: \***\*\*\*\*\***\*\*\***\*\*\*\*\***\_\_\_\***\*\*\*\*\***\*\*\***\*\*\*\*\***

 ---

@@ -612,7 +612,7 @@ podman exec -it flyer-crawler-dev npm run dev:container

 **Pass/Fail**: [ ]

-**Notes**: **********************\_\_\_**********************
+**Notes**: \***\*\*\*\*\***\*\*\***\*\*\*\*\***\_\_\_\***\*\*\*\*\***\*\*\***\*\*\*\*\***

 ---

@@ -637,7 +637,7 @@ podman exec -it flyer-crawler-dev npm run dev:container

 **Pass/Fail**: [ ]

-**Notes**: **********************\_\_\_**********************
+**Notes**: \***\*\*\*\*\***\*\*\***\*\*\*\*\***\_\_\_\***\*\*\*\*\***\*\*\***\*\*\*\*\***

 ---

@@ -656,7 +656,7 @@ podman exec -it flyer-crawler-dev npm run dev:container

 **Pass/Fail**: [ ]

-**Notes**: **********************\_\_\_**********************
+**Notes**: \***\*\*\*\*\***\*\*\***\*\*\*\*\***\_\_\_\***\*\*\*\*\***\*\*\***\*\*\*\*\***

 ---

@@ -681,7 +681,7 @@ podman exec -it flyer-crawler-dev npm run dev:container

 **Pass/Fail**: [ ]

-**Notes**: **********************\_\_\_**********************
+**Notes**: \***\*\*\*\*\***\*\*\***\*\*\*\*\***\_\_\_\***\*\*\*\*\***\*\*\***\*\*\*\*\***

 ---

@@ -705,7 +705,7 @@ podman exec -it flyer-crawler-dev npm run dev:container

 **Pass/Fail**: [ ]

-**Notes**: **********************\_\_\_**********************
+**Notes**: \***\*\*\*\*\***\*\*\***\*\*\*\*\***\_\_\_\***\*\*\*\*\***\*\*\***\*\*\*\*\***

 ---

@@ -757,7 +757,7 @@ podman exec -it flyer-crawler-dev npm run dev:container

 **Pass/Fail**: [ ]

-**Measurements**: **********************\_\_\_**********************
+**Measurements**: \***\*\*\*\*\***\*\*\***\*\*\*\*\***\_\_\_\***\*\*\*\*\***\*\*\***\*\*\*\*\***

 ---

@@ -765,7 +765,7 @@ podman exec -it flyer-crawler-dev npm run dev:container

 ### Test 8.1: Chrome/Edge

-**Browser Version**: ******\_\_\_******
+**Browser Version**: **\*\***\_\_\_**\*\***

 **Tests to Run**:

@@ -775,13 +775,13 @@ podman exec -it flyer-crawler-dev npm run dev:container

 **Pass/Fail**: [ ]

-**Notes**: **********************\_\_\_**********************
+**Notes**: \***\*\*\*\*\***\*\*\***\*\*\*\*\***\_\_\_\***\*\*\*\*\***\*\*\***\*\*\*\*\***

 ---

 ### Test 8.2: Firefox

-**Browser Version**: ******\_\_\_******
+**Browser Version**: **\*\***\_\_\_**\*\***

 **Tests to Run**:

@@ -791,13 +791,13 @@ podman exec -it flyer-crawler-dev npm run dev:container

 **Pass/Fail**: [ ]

-**Notes**: **********************\_\_\_**********************
+**Notes**: \***\*\*\*\*\***\*\*\***\*\*\*\*\***\_\_\_\***\*\*\*\*\***\*\*\***\*\*\*\*\***

 ---

 ### Test 8.3: Safari (macOS/iOS)

-**Browser Version**: ******\_\_\_******
+**Browser Version**: **\*\***\_\_\_**\*\***

 **Tests to Run**:

@@ -807,7 +807,7 @@ podman exec -it flyer-crawler-dev npm run dev:container

 **Pass/Fail**: [ ]

-**Notes**: **********************\_\_\_**********************
+**Notes**: \***\*\*\*\*\***\*\*\***\*\*\*\*\***\_\_\_\***\*\*\*\*\***\*\*\***\*\*\*\*\***

 ---

@@ -849,8 +849,8 @@ podman exec -it flyer-crawler-dev npm run dev:container

 ## Sign-Off

-**Tester Name**: **********************\_\_\_**********************
-**Date Completed**: **********************\_\_\_**********************
+**Tester Name**: \***\*\*\*\*\***\*\*\***\*\*\*\*\***\_\_\_\***\*\*\*\*\***\*\*\***\*\*\*\*\***
+**Date Completed**: \***\*\*\*\*\***\*\*\***\*\*\*\*\***\_\_\_\***\*\*\*\*\***\*\*\***\*\*\*\*\***
 **Overall Status**: [ ] PASS [ ] PASS WITH ISSUES [ ] FAIL

 **Ready for Production**: [ ] YES [ ] NO [ ] WITH FIXES
--- a/docs/QUICK_TEST_CHECKLIST.md
+++ b/docs/QUICK_TEST_CHECKLIST.md
@@ -208,7 +208,7 @@ Press F12 or Ctrl+Shift+I

 **Result**: [ ] PASS [ ] FAIL

-**Errors found**: ******************\_\_\_******************
+**Errors found**: **\*\*\*\***\*\***\*\*\*\***\_\_\_**\*\*\*\***\*\***\*\*\*\***

 ---

@@ -224,7 +224,7 @@ Check for:

 **Result**: [ ] PASS [ ] FAIL

-**Issues found**: ******************\_\_\_******************
+**Issues found**: **\*\*\*\***\*\***\*\*\*\***\_\_\_**\*\*\*\***\*\***\*\*\*\***

 ---

@@ -272,4 +272,4 @@ Check for:
 2. ***
 3. ***

-**Sign-off**: ********\_\_\_******** **Date**: ****\_\_\_****
+**Sign-off**: **\*\*\*\***\_\_\_**\*\*\*\*** **Date**: \***\*\_\_\_\*\***
--- a/docs/README.md
+++ b/docs/README.md
@@ -47,6 +47,16 @@ Production operations and deployment:
 - [Logstash Troubleshooting](operations/LOGSTASH-TROUBLESHOOTING.md) - Debugging logs
 - [Monitoring](operations/MONITORING.md) - Bugsink, health checks, observability

+**PM2 Management**:
+
+- [PM2 Namespace Completion Report](operations/PM2-NAMESPACE-COMPLETION-REPORT.md) - PM2 namespace implementation project summary
+- [PM2 Incident Response Runbook](operations/PM2-INCIDENT-RESPONSE.md) - Step-by-step procedures for PM2 incidents
+- [PM2 Crash Debugging](operations/PM2-CRASH-DEBUGGING.md) - Troubleshooting PM2 crashes
+
+**Incident Reports**:
+
+- [2026-02-17 PM2 Process Kill](operations/INCIDENT-2026-02-17-PM2-PROCESS-KILL.md) - ALL PM2 processes killed during v0.15.0 deployment (Mitigated)
+
 **NGINX Reference Configs** (in repository root):

 - `etc-nginx-sites-available-flyer-crawler.projectium.com` - Production server config
--- a/docs/adr/0009-caching-strategy-for-read-heavy-operations.md
+++ b/docs/adr/0009-caching-strategy-for-read-heavy-operations.md
@@ -39,15 +39,15 @@ All cache operations are fail-safe - cache failures do not break the application

 Different data types use different TTL values based on volatility:

-| Data Type           | TTL       | Rationale                              |
-| ------------------- | --------- | -------------------------------------- |
-| Brands/Stores       | 1 hour    | Rarely changes, safe to cache longer   |
-| Flyer lists         | 5 minutes | Changes when new flyers are added      |
-| Individual flyers   | 10 minutes| Stable once created                    |
-| Flyer items         | 10 minutes| Stable once created                    |
-| Statistics          | 5 minutes | Can be slightly stale                  |
-| Frequent sales      | 15 minutes| Aggregated data, updated periodically  |
-| Categories          | 1 hour    | Rarely changes                         |
+| Data Type         | TTL        | Rationale                             |
+| ----------------- | ---------- | ------------------------------------- |
+| Brands/Stores     | 1 hour     | Rarely changes, safe to cache longer  |
+| Flyer lists       | 5 minutes  | Changes when new flyers are added     |
+| Individual flyers | 10 minutes | Stable once created                   |
+| Flyer items       | 10 minutes | Stable once created                   |
+| Statistics        | 5 minutes  | Can be slightly stale                 |
+| Frequent sales    | 15 minutes | Aggregated data, updated periodically |
+| Categories        | 1 hour     | Rarely changes                        |

 ### Cache Key Strategy

@@ -64,11 +64,11 @@ Cache keys follow a consistent prefix pattern for pattern-based invalidation:

 The following repository methods implement server-side caching:

-| Method | Cache Key Pattern | TTL |
-| ------ | ----------------- | --- |
-| `FlyerRepository.getAllBrands()` | `cache:brands` | 1 hour |
-| `FlyerRepository.getFlyers()` | `cache:flyers:{limit}:{offset}` | 5 minutes |
-| `FlyerRepository.getFlyerItems()` | `cache:flyer-items:{flyerId}` | 10 minutes |
+| Method                            | Cache Key Pattern               | TTL        |
+| --------------------------------- | ------------------------------- | ---------- |
+| `FlyerRepository.getAllBrands()`  | `cache:brands`                  | 1 hour     |
+| `FlyerRepository.getFlyers()`     | `cache:flyers:{limit}:{offset}` | 5 minutes  |
+| `FlyerRepository.getFlyerItems()` | `cache:flyer-items:{flyerId}`   | 10 minutes |

 ### Cache Invalidation

@@ -86,14 +86,14 @@ The following repository methods implement server-side caching:

 TanStack React Query provides client-side caching with configurable stale times:

-| Query Type        | Stale Time  |
-| ----------------- | ----------- |
-| Categories        | 1 hour      |
-| Master Items      | 10 minutes  |
-| Flyer Items       | 5 minutes   |
-| Flyers            | 2 minutes   |
-| Shopping Lists    | 1 minute    |
-| Activity Log      | 30 seconds  |
+| Query Type     | Stale Time |
+| -------------- | ---------- |
+| Categories     | 1 hour     |
+| Master Items   | 10 minutes |
+| Flyer Items    | 5 minutes  |
+| Flyers         | 2 minutes  |
+| Shopping Lists | 1 minute   |
+| Activity Log   | 30 seconds |

 ### Multi-Layer Cache Architecture

--- a/docs/adr/0012-frontend-component-library-and-design-system.md
+++ b/docs/adr/0012-frontend-component-library-and-design-system.md
@@ -80,13 +80,13 @@ src/

 **Common Utility Patterns**:

-| Pattern | Classes |
-| ------- | ------- |
-| Card container | `bg-white dark:bg-gray-800 rounded-lg shadow-md p-6` |
-| Primary button | `bg-brand-primary hover:bg-brand-dark text-white rounded-lg px-4 py-2` |
-| Secondary button | `bg-gray-100 dark:bg-gray-700 text-gray-700 dark:text-gray-200` |
-| Input field | `border border-gray-300 dark:border-gray-600 rounded-md px-3 py-2` |
-| Focus ring | `focus:outline-none focus:ring-2 focus:ring-brand-primary` |
+| Pattern          | Classes                                                                |
+| ---------------- | ---------------------------------------------------------------------- |
+| Card container   | `bg-white dark:bg-gray-800 rounded-lg shadow-md p-6`                   |
+| Primary button   | `bg-brand-primary hover:bg-brand-dark text-white rounded-lg px-4 py-2` |
+| Secondary button | `bg-gray-100 dark:bg-gray-700 text-gray-700 dark:text-gray-200`        |
+| Input field      | `border border-gray-300 dark:border-gray-600 rounded-md px-3 py-2`     |
+| Focus ring       | `focus:outline-none focus:ring-2 focus:ring-brand-primary`             |

 ### Color System

@@ -187,13 +187,13 @@ export const CheckCircleIcon: React.FC<IconProps> = ({ title, ...props }) => (

 **Context Providers** (see ADR-005):

-| Provider | Purpose |
-| -------- | ------- |
-| `AuthProvider` | Authentication state |
-| `ModalProvider` | Modal open/close state |
-| `FlyersProvider` | Flyer data |
-| `MasterItemsProvider` | Grocery items |
-| `UserDataProvider` | User-specific data |
+| Provider              | Purpose                |
+| --------------------- | ---------------------- |
+| `AuthProvider`        | Authentication state   |
+| `ModalProvider`       | Modal open/close state |
+| `FlyersProvider`      | Flyer data             |
+| `MasterItemsProvider` | Grocery items          |
+| `UserDataProvider`    | User-specific data     |

 **Provider Hierarchy** in `AppProviders.tsx`:

--- a/docs/adr/0014-containerization-and-deployment-strategy.md
+++ b/docs/adr/0014-containerization-and-deployment-strategy.md
@@ -249,26 +249,39 @@ module.exports = {

 ### PM2 Commands Reference

+**CRITICAL**: Every `pm2 start`, `pm2 restart`, `pm2 stop`, or `pm2 delete` command MUST be immediately followed by `pm2 save`. Without this, processes become ephemeral and will disappear on PM2 daemon restarts, server reboots, or internal reconciliation events.
+
 ```bash
-# Start/reload with environment
+# ✅ CORRECT - Start/reload with environment and save
+pm2 startOrReload ecosystem.config.cjs --env production --update-env && pm2 save
+
+# ✅ CORRECT - Restart and save
+pm2 restart flyer-crawler-api && pm2 save
+
+# ✅ CORRECT - Stop and save
+pm2 stop flyer-crawler-api && pm2 save
+
+# ✅ CORRECT - Delete and save
+pm2 delete flyer-crawler-api && pm2 save
+
+# ❌ WRONG - Missing save (processes become ephemeral)
 pm2 startOrReload ecosystem.config.cjs --env production --update-env

-# Save process list for startup
-pm2 save
-
-# View logs
+# View logs (read-only operation, no save needed)
 pm2 logs flyer-crawler-api --lines 50

-# Monitor processes
+# Monitor processes (read-only operation, no save needed)
 pm2 monit

-# List all processes
+# List all processes (read-only operation, no save needed)
 pm2 list

-# Describe process details
+# Describe process details (read-only operation, no save needed)
 pm2 describe flyer-crawler-api
 ```

+**Why This Matters**: PM2 maintains an in-memory process list. The `pm2 save` command writes this list to `~/.pm2/dump.pm2`, which PM2 uses to resurrect processes after daemon restarts. Without it, your carefully managed process state is lost.
+
 ### Resource Limits

 | Process          | Memory Limit | Restart Delay            | Kill Timeout |
--- a/Show More
+++ b/Show More
Author	SHA1	Message	Date
Gitea Actions	e02716c092	ci: Bump version to 0.20.2 [skip ci]	2026-02-20 03:52:28 +05:00
Torben Sorensen	66e6d2fdbc	feat: implement PM2 namespace isolation for improved process management All checks were successful Deploy to Test Environment / deploy-to-test (push) Successful in 29m56s Details - Updated TypeScript configuration to include test files. - Modified Vitest configuration to include test files from both src and tests directories. - Added ADR-063 documenting the decision and implementation of PM2 namespaces. - Created implementation report detailing the migration to PM2 namespaces. - Developed migration script for transitioning to namespaced PM2 processes. - Updated ecosystem configuration files to define namespaces for production, test, and development environments. - Enhanced workflow files to include namespace flags in all PM2 commands. - Verified migration with comprehensive tests ensuring all processes are correctly namespaced.	2026-02-19 14:51:18 -08:00
Torben Sorensen	82a38b4e2a	feat: implement PM2 namespace isolation for improved process management - Updated TypeScript configuration to include test files. - Modified Vitest configuration to include test files from both src and tests directories. - Added ADR-063 documenting the decision and implementation of PM2 namespaces. - Created implementation report detailing the migration to PM2 namespaces. - Developed migration script for transitioning to namespaced PM2 processes. - Updated ecosystem configuration files to define namespaces for production, test, and development environments. - Enhanced workflow files to include namespace flags in all PM2 commands. - Verified migration with comprehensive tests ensuring all processes are correctly namespaced.	2026-02-19 14:51:17 -08:00
Gitea Actions	f6f4415aeb	style: auto-format code via Prettier [skip ci]	2026-02-19 11:28:52 +05:00
Gitea Actions	0c23aa4c5e	ci: Bump version to 0.20.1 [skip ci]	2026-02-19 11:27:23 +05:00
Torben Sorensen	07125fc99d	feat: complete PM2 namespace implementation (100%) All checks were successful Deploy to Test Environment / deploy-to-test (push) Successful in 56m40s Details Add missing namespace flags to pm2 save commands and comprehensive tests to ensure complete isolation between production, test, and dev environments. ## Changes Made ### Workflow Fixes - restart-pm2.yml: Add --namespace flags to pm2 save (lines 45, 69) - manual-db-restore.yml: Add --namespace flag to pm2 save (line 95) ### Test Enhancements - Add 6 new tests to validate ALL pm2 save commands have namespace flags - Total test suite: 89 tests (all passing) - Specific validation for each workflow file ### Documentation - Create comprehensive PM2 Namespace Completion Report - Update docs/README.md with PM2 Management section - Cross-reference with ADR-063 and migration script ## Benefits - Eliminates pm2 save race conditions between environments - Enables safe parallel test and production deployments - Simplifies process management with namespace isolation - Prevents incidents like 2026-02-17 PM2 process kill ## Test Results All 89 tests pass: - 21 ecosystem config tests - 38 workflow file tests - 6 pm2 save validation tests - 15 migration script tests - 15 documentation tests - 3 end-to-end consistency tests Verified in dev container with vitest. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>	2026-02-18 22:25:56 -08:00
Torben Sorensen	626aa80799	feat: add extensive PM2 logging to test deployment workflow Some checks failed Deploy to Test Environment / deploy-to-test (push) Failing after 1h4m43s Details Add comprehensive before/after logging for all PM2 commands to diagnose test process startup issues. Each PM2 operation now includes: - Pre-command state (process list, JSON details, timestamps) - Command execution with captured exit codes - Post-command verification with expected vs actual comparison - Clear success/warning/error indicators (✅/⚠️/❌) Enhanced sections: 1. Stop Test Server Before Tests - delete commands with verification 2. LAYER 2: Stop PM2 Before File Operations - stop commands + port checks 3. PM2 Cleanup - errored/stopped process removal with safety checks 4. PM2 Start/Reload - critical section with stability checks 5. Final Verification - comprehensive status + logs + environment This addresses reported issues where PM2 test processes fail to start by providing detailed diagnostics at every deployment stage. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>	2026-02-18 18:33:36 -08:00
Gitea Actions	4025f29c5c	ci: Bump version to 0.20.0 for production release [skip ci]	2026-02-19 07:26:46 +05:00
Gitea Actions	e9e3b14050	ci: Bump version to 0.19.3 [skip ci]	2026-02-19 06:41:32 +05:00
Torben Sorensen	507e89ea4e	minor commit to test pm2 again All checks were successful Deploy to Test Environment / deploy-to-test (push) Successful in 27m43s Details	2026-02-18 17:27:45 -08:00
Gitea Actions	1efe42090b	ci: Bump version to 0.19.2 [skip ci]	2026-02-19 05:54:34 +05:00
Torben Sorensen	97cc14288b	optimize giteas performance with language detection All checks were successful Deploy to Test Environment / deploy-to-test (push) Successful in 25m51s Details	2026-02-18 16:53:16 -08:00
Gitea Actions	96251ec2cc	ci: Bump version to 0.19.1 [skip ci]	2026-02-19 04:45:22 +05:00
Torben Sorensen	fe79522ea4	pm2 save fix + test work All checks were successful Deploy to Test Environment / deploy-to-test (push) Successful in 27m44s Details	2026-02-18 15:43:20 -08:00
Gitea Actions	743216ef1b	ci: Bump version to 0.19.0 for production release [skip ci]	2026-02-19 02:54:09 +05:00
Gitea Actions	c53295a371	ci: Bump version to 0.18.1 [skip ci]	2026-02-19 02:03:05 +05:00
Torben Sorensen	c18efb1b60	fix: add PORT=3001 to production PM2 config to prevent EADDRINUSE crashes All checks were successful Deploy to Test Environment / deploy-to-test (push) Successful in 32m55s Details Root cause: server.ts defaults to port 3001 when PORT env var is not set. PM2 cluster mode shares a single port across all instances, but the PORT env variable was missing from ecosystem.config.cjs, causing port binding conflicts. Fix: Added PORT: '3001' to production API env configuration in ecosystem.config.cjs. Test environment already had PORT: 3002 set. Port allocation on projectium.com: - 3000: Gitea (system) - 3001: flyer-crawler production - 3002: flyer-crawler test - 3003: stock-alert production - 3004: stock-alert test Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>	2026-02-18 12:55:39 -08:00
Gitea Actions	822805e4c4	ci: Bump version to 0.18.0 for production release [skip ci]	2026-02-19 01:26:11 +05:00
Gitea Actions	6fd690890b	style: auto-format code via Prettier [skip ci]	2026-02-19 00:36:02 +05:00
Gitea Actions	5fd836190c	ci: Bump version to 0.17.1 [skip ci]	2026-02-19 00:34:08 +05:00
Torben Sorensen	441467eb8a	feat: add lightweight version sync workflow (ADR-062) All checks were successful Deploy to Test Environment / deploy-to-test (push) Successful in 26m39s Details Implements efficient version synchronization between production and test environments without running the full test deployment pipeline. Problem: - Production version bumps triggered full 5-7 minute test deployment - Wasteful: 95% less CPU, 99.8% less file I/O needed - Code already tested when originally pushed to main Solution (matching stock-alert architecture): - New sync-test-version.yml workflow (~30 seconds) - Triggers automatically after successful production deployment - Updates only package.json in test directory - Restarts PM2 with --update-env to refresh version metadata Benefits: - 90% faster (30 sec vs 5-7 min) - Saves ~20 minutes/month of CI time - Clean separation: no conditionals polluting deploy-to-test.yml - Same end state, optimized path Changes: - Added .gitea/workflows/sync-test-version.yml (new workflow) - Added docs/adr/0062-lightweight-version-sync-workflow.md (decision record) - Updated docs/adr/index.md (ADR catalog) - Cleaned up duplicate TSOA generation step in deploy-to-test.yml Architecture: - deploy-to-test.yml: unchanged (runs on code changes) - deploy-to-prod.yml: unchanged (no explicit trigger needed) - sync-test-version.yml: auto-triggers via workflow_run Related: - Inspired by stock-alert project optimization (commit 021f9c8) - ADR-061: PM2 Process Isolation Safeguards Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>	2026-02-18 11:33:05 -08:00
Torben Sorensen	59bfc859d7	fix: add TSOA build step to all deployment workflows CRITICAL FIX: Production deployment was failing because tsoa-spec.json is a gitignored generated file that was missing on the server. Root cause: - server.ts imports './src/config/tsoa-spec.json' (line 30) - File is generated by TSOA but gitignored - Deployment workflows never ran 'npm run tsoa:build' - Server crashed on startup with ERR_MODULE_NOT_FOUND Changes: - Add "Generate TSOA OpenAPI Spec and Routes" step to: - deploy-to-prod.yml - deploy-to-test.yml - manual-deploy-major.yml - Runs after 'npm ci' but before React build - Generates both tsoa-spec.json and tsoa-generated routes Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>	2026-02-18 11:33:04 -08:00
Gitea Actions	b989405a53	ci: Bump version to 0.17.0 for production release [skip ci]	2026-02-18 23:40:09 +05:00
Gitea Actions	6af2533e9e	ci: Bump version to 0.16.4 [skip ci]	2026-02-18 23:04:08 +05:00
Torben Sorensen	f434a5846a	fix: apply three-layer rsync safety system to prevent PM2 crashes All checks were successful Deploy to Test Environment / deploy-to-test (push) Successful in 24m17s Details CRITICAL FIX: Prevents rsync --delete from removing PM2 config files Root Cause: - rsync --delete was removing ecosystem.config.cjs and .env. files - This caused PM2 daemon corruption affecting ALL projects on shared server - Same vulnerability that crashed stock-alert PM2 processes Three-Layer Safety System: 1. Pre-flight checks (git repo, critical files, file count validation) 2. Stop PM2 before file operations (prevent ENOENT/uv_cwd errors) 3. Comprehensive rsync excludes (ecosystem configs, .env files, coverage) Changes: - deploy-to-prod.yml: Added safety system to production deployment - deploy-to-test.yml: Added safety system to test deployment Files excluded from rsync --delete: - ecosystem.config.cjs (PM2 configuration) - .env (environment secrets) - coverage, .nyc_output, .vitest-results (test artifacts) - .vscode, .idea (IDE files) Prevents: - PM2 daemon crashes across all projects - Process CWD (working directory) deletion - Cross-project interference on shared PM2 daemon Related: - Stock-alert fix that identified this vulnerability - PM2 Process Isolation documentation (CLAUDE.md) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>	2026-02-18 09:58:29 -08:00
Gitea Actions	aea368677f	ci: Bump version to 0.16.3 [skip ci]	2026-02-18 22:51:45 +05:00
Torben Sorensen	cd8ee92813	debug: add PM2 crash debugging tools Some checks failed Deploy to Test Environment / deploy-to-test (push) Has been cancelled Details	2026-02-18 09:43:40 -08:00
Gitea Actions	cf2cc5b832	ci: Bump version to 0.16.2 [skip ci]	2026-02-18 15:01:02 +05:00
Torben Sorensen	d2db3562bb	test deploy All checks were successful Deploy to Test Environment / deploy-to-test (push) Successful in 24m32s Details	2026-02-18 01:35:16 -08:00
Gitea Actions	0532b4b22e	style: auto-format code via Prettier [skip ci]	2026-02-18 14:06:10 +05:00
Gitea Actions	e767ccbb21	ci: Bump version to 0.16.1 [skip ci]	2026-02-18 14:04:40 +05:00
Torben Sorensen	1ff813f495	job to fix pm2 All checks were successful Deploy to Test Environment / deploy-to-test (push) Successful in 24m45s Details	2026-02-18 00:54:08 -08:00
Torben Sorensen	204fe4394a	oh god maybe pm2 finally workin Some checks are pending Deploy to Test Environment / deploy-to-test (push) Has started running Details	2026-02-17 23:54:27 -08:00
Gitea Actions	029b621632	ci: Bump version to 0.16.0 for production release [skip ci]	2026-02-18 11:21:36 +05:00
Gitea Actions	0656ab3ae7	style: auto-format code via Prettier [skip ci]	2026-02-18 10:48:03 +05:00
Gitea Actions	ae0bb9e04d	ci: Bump version to 0.15.2 [skip ci]	2026-02-18 10:46:29 +05:00
Torben Sorensen	b83c37b977	deploy fixes All checks were successful Deploy to Test Environment / deploy-to-test (push) Successful in 25m45s Details	2026-02-17 21:44:34 -08:00
Gitea Actions	69ae23a1ae	ci: Bump version to 0.15.1 [skip ci]	2026-02-18 09:50:16 +05:00
Torben Sorensen	c059b30201	PM2 Process Isolation All checks were successful Deploy to Test Environment / deploy-to-test (push) Successful in 30m15s Details	2026-02-17 20:49:01 -08:00
Gitea Actions	93ad624658	ci: Bump version to 0.15.0 for production release [skip ci]	2026-02-18 07:40:36 +05:00
Gitea Actions	7dd4f21071	ci: Bump version to 0.14.4 [skip ci]	2026-02-18 06:27:20 +05:00
Torben Sorensen	174b637a0a	even more typescript fixes All checks were successful Deploy to Test Environment / deploy-to-test (push) Successful in 25m5s Details	2026-02-17 17:20:54 -08:00
Gitea Actions	4f80baf466	ci: Bump version to 0.14.3 [skip ci]	2026-02-17 10:03:15 +05:00
Torben Sorensen	8450b5e22f	Generate TSOA Spec and Routes Some checks failed Deploy to Test Environment / deploy-to-test (push) Failing after 2m32s Details	2026-02-16 21:01:30 -08:00
Gitea Actions	e4d830ab90	ci: Bump version to 0.14.2 [skip ci]	2026-02-13 23:35:46 +05:00
Torben Sorensen	b6a62a036f	be specific about pm2 processes Some checks failed Deploy to Test Environment / deploy-to-test (push) Failing after 3m31s Details	2026-02-13 10:19:28 -08:00
Torben Sorensen	2d2cd52011	Massive Dependency Modernization Project Some checks failed Deploy to Test Environment / deploy-to-test (push) Failing after 3m58s Details	2026-02-13 00:34:22 -08:00
Torben Sorensen	379b8bf532	fix tour / whats new collision Some checks failed Deploy to Test Environment / deploy-to-test (push) Has been cancelled Details	2026-02-12 11:05:47 -08:00
Gitea Actions	d06a1952a0	ci: Bump version to 0.14.1 [skip ci]	2026-02-12 17:37:36 +05:00
Torben Sorensen	4d323a51ca	fix tour / whats new collision All checks were successful Deploy to Test Environment / deploy-to-test (push) Successful in 49m39s Details	2026-02-12 04:29:43 -08:00
Gitea Actions	ee15c67429	ci: Bump version to 0.14.0 for production release [skip ci]	2026-02-12 16:16:16 +05:00