[REVIEW] Add user scenario functionality with staging ground integration

.github/copilot-instructions.md

@@ -494,6 +494,37 @@ npm test -- --coverage     # Generate coverage report
 - Support both fine-grained and classic Personal Access Tokens
 - Implement proper branch and commit workflows
 
+## 🚨 CRITICAL FILE MODIFICATION PROHIBITIONS
+
+**ABSOLUTELY FORBIDDEN**: The following files are CRITICAL to the deployment and routing infrastructure of SGeX Workbench. Copilot agents are **STRICTLY PROHIBITED** from making ANY changes to these files without **EXPLICIT WRITTEN CONSENT** from the repository owner/admin:
+
+### 🚫 GitHub Pages Deployment Workflows
+- **`.github/workflows/branch-deployment.yml`** - Branch deployment workflow
+- **`.github/workflows/landing-page-deployment.yml`** - Landing page deployment workflow
+- **Any other `*.yml` or `*.yaml` files in `.github/workflows/`** - All workflow files
+
+### 🚫 Critical HTML Files  
+- **`public/404.html`** - SPA routing logic for GitHub Pages
+- **`public/index.html`** - Main application entry point
+
+### 🚫 Routing and URL Handling Services
+- **`src/services/routingContextService.js`** - Core routing context service
+- **`src/utils/routeUtils.ts`** - URL parsing and routing utilities
+- **Any file containing URL routing, path processing, or deployment logic**
+
+### ⚠️ Violation Consequences
+- **Automatic rejection** of any PR containing changes to these files without explicit consent
+- **Immediate reversion** of any unauthorized changes
+- **Potential blocking** of future copilot access to the repository
+
+### ✅ Required Process for Changes
+1. **Request explicit consent** from @litlfred (repository owner) in a GitHub comment
+2. **Wait for written approval** before making ANY changes
+3. **Document the explicit consent** in the commit message
+4. **Test extensively** in a separate branch before merging
+
+**Remember**: These files control the entire deployment and routing infrastructure. Unauthorized changes can break the production application for all users.
+
 ## Troubleshooting Common Issues
 
 ### Authentication Issues

.github/workflows/landing-page-deployment.yml

@@ -1,3 +1,24 @@
+# 🚨 COPILOT PROHIBITION WARNING 🚨
+# 
+# THIS FILE IS ABSOLUTELY CRITICAL TO GITHUB PAGES DEPLOYMENT INFRASTRUCTURE
+# 
+# ⛔ COPILOT AGENTS ARE STRICTLY PROHIBITED FROM MAKING ANY CHANGES TO THIS FILE
+# ⛔ WITHOUT EXPLICIT WRITTEN CONSENT FROM THE REPOSITORY OWNER (@litlfred)
+# 
+# This workflow controls landing page deployment to GitHub Pages. Any unauthorized 
+# changes can break the entire production landing page for all users.
+# 
+# 🔒 REQUIRED PROCESS FOR CHANGES:
+# 1. Request explicit consent from @litlfred in a GitHub comment
+# 2. Wait for written approval before making ANY changes  
+# 3. Document the explicit consent in the commit message
+# 4. Test extensively in a separate environment before merging
+# 
+# Violation of this prohibition will result in immediate reversion and 
+# potential blocking of copilot access to this repository.
+# 
+# 🚨 END PROHIBITION WARNING 🚨
+
 name: Deploy Landing Page
 
 on:

.github/workflows/mcp-deployment.yml

@@ -0,0 +1,186 @@
+name: Deploy MCP Server to Fly.io (Dev)
+
+on:
+  # Manual trigger for dev deployments
+  workflow_dispatch:
+    inputs:
+      branch:
+        description: 'Branch to deploy (defaults to current branch)'
+        required: false
+        type: string
+        default: ''
+      force_deployment:
+        description: 'Force deployment even if no changes detected'
+        required: false
+        type: boolean
+        default: false
+
+  # Automatic deployment on push to main (dev environment only)
+  push:
+    branches:
+      - main
+    paths:
+      - 'services/dak-faq-mcp/**'
+      - '.github/workflows/mcp-deployment.yml'
+
+  # Automatic deployment on PR merge (dev environment only)
+  pull_request:
+    types: [closed]
+    branches:
+      - main
+    paths:
+      - 'services/dak-faq-mcp/**'
+
+permissions:
+  contents: read
+  id-token: write
+
+env:
+  FLY_APP_NAME: sgex-mcp-dev
+  ENVIRONMENT: dev
+
+jobs:
+  deploy:
+    name: Deploy MCP Server (Dev)
+    runs-on: ubuntu-latest
+
+    # Only run on merged PRs or manual/push triggers
+    if: github.event_name != 'pull_request' || github.event.pull_request.merged == true
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v5
+        with:
+          ref: ${{ inputs.branch || github.ref }}
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v5
+        with:
+          node-version: '18'
+          cache: 'npm'
+          cache-dependency-path: 'services/dak-faq-mcp/package-lock.json'
+
+      - name: Install MCP service dependencies
+        working-directory: services/dak-faq-mcp
+        run: npm ci
+
+      - name: Build MCP service
+        working-directory: services/dak-faq-mcp
+        run: npm run build
+
+      - name: Run tests (if available)
+        working-directory: services/dak-faq-mcp
+        run: |
+          if npm run test --if-present; then
+            echo "✅ Tests passed"
+          else
+            echo "⚠️ No tests found or tests failed"
+          fi
+        continue-on-error: true
+
+      - name: Set up Fly.io CLI
+        uses: superfly/flyctl-actions/setup-flyctl@master
+
+      - name: Update fly.toml for dev environment
+        working-directory: services/dak-faq-mcp
+        run: |
+          # Ensure fly.toml uses correct app name for dev
+          sed "s/app = \"sgex-mcp-dev\"/app = \"${{ env.FLY_APP_NAME }}\"/" fly.toml > fly-dev.toml
+          mv fly-dev.toml fly.toml
+
+          echo "📋 Updated fly.toml for dev environment:"
+          cat fly.toml
+
+      - name: Deploy to Fly.io (Dev)
+        working-directory: services/dak-faq-mcp
+        env:
+          FLY_API_TOKEN: ${{ secrets.FLYIO_API_TOKEN }}
+        run: |
+          echo "🚀 Deploying ${{ env.FLY_APP_NAME }} to Fly.io..."
+
+          # Deploy the application
+          flyctl deploy --app ${{ env.FLY_APP_NAME }} --build-only || flyctl launch --now --name ${{ env.FLY_APP_NAME }}
+
+          # Set dev environment secrets (only update if they exist)
+          if [ -n "${{ secrets.FLYIO_CLIENT_ID_DEV }}" ]; then
+            echo "🔑 Setting GitHub OAuth secrets for dev environment..."
+            flyctl secrets set \
+              GITHUB_CLIENT_ID="${{ secrets.FLYIO_CLIENT_ID_DEV }}" \
+              GITHUB_CLIENT_SECRET="${{ secrets.FLYIO_CLIENT_SECRET_DEV }}" \
+              GITHUB_TOKEN="${{ secrets.FLYIO_GH_PAT_DEV }}" \
+              CORS_ORIGIN="https://litlfred.github.io" \
+              --app ${{ env.FLY_APP_NAME }}
+          else
+            echo "⚠️ GitHub OAuth secrets not configured for dev environment"
+            echo "Please set the following secrets in GitHub repository settings:"
+            echo "- FLYIO_CLIENT_ID_DEV"
+            echo "- FLYIO_CLIENT_SECRET_DEV"
+            echo "- FLYIO_GH_PAT_DEV"
+          fi
+
+          # Final deployment with secrets
+          flyctl deploy --app ${{ env.FLY_APP_NAME }}
+
+      - name: Verify deployment
+        working-directory: services/dak-faq-mcp
+        run: |
+          echo "🏥 Verifying deployment health..."
+
+          # Wait for deployment to be ready
+          sleep 30
+
+          # Get app URL
+          APP_URL="https://${{ env.FLY_APP_NAME }}.fly.dev"
+          echo "🌐 Testing deployment at: $APP_URL"
+
+          # Test health endpoint
+          if curl -f -s "$APP_URL/health" > /dev/null; then
+            echo "✅ Health check passed"
+            curl -s "$APP_URL/health" | jq .
+          else
+            echo "❌ Health check failed"
+            flyctl logs --app ${{ env.FLY_APP_NAME }} || true
+            exit 1
+          fi
+
+          # Test API info endpoint
+          echo "📋 API Information:"
+          curl -s "$APP_URL/" | jq .security.oauth_configured || true
+
+      - name: Post deployment summary
+        if: always()
+        run: |
+          echo "## 🚀 MCP Development Deployment Summary" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "**Environment:** Development" >> $GITHUB_STEP_SUMMARY
+          echo "**App Name:** ${{ env.FLY_APP_NAME }}" >> $GITHUB_STEP_SUMMARY
+          echo "**URL:** https://${{ env.FLY_APP_NAME }}.fly.dev" >> $GITHUB_STEP_SUMMARY
+          echo "**Branch:** ${{ inputs.branch || github.ref_name }}" >> $GITHUB_STEP_SUMMARY
+          echo "**Commit:** ${{ github.sha }}" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+
+          if [ "${{ job.status }}" = "success" ]; then
+            echo "✅ **Status:** Development deployment successful" >> $GITHUB_STEP_SUMMARY
+            echo "" >> $GITHUB_STEP_SUMMARY
+            echo "### 📋 Available Endpoints" >> $GITHUB_STEP_SUMMARY
+            echo "- Health: https://${{ env.FLY_APP_NAME }}.fly.dev/health" >> $GITHUB_STEP_SUMMARY
+            echo "- API Info: https://${{ env.FLY_APP_NAME }}.fly.dev/" >> $GITHUB_STEP_SUMMARY
+            echo "- OAuth: https://${{ env.FLY_APP_NAME }}.fly.dev/auth/github" >> $GITHUB_STEP_SUMMARY
+          else
+            echo "❌ **Status:** Development deployment failed" >> $GITHUB_STEP_SUMMARY
+            echo "" >> $GITHUB_STEP_SUMMARY
+            echo "Check the workflow logs for details." >> $GITHUB_STEP_SUMMARY
+          fi
+
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "### 🔧 Management Commands" >> $GITHUB_STEP_SUMMARY
+          echo '```bash' >> $GITHUB_STEP_SUMMARY
+          echo "# View logs" >> $GITHUB_STEP_SUMMARY
+          echo "flyctl logs --app ${{ env.FLY_APP_NAME }}" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "# View status" >> $GITHUB_STEP_SUMMARY
+          echo "flyctl status --app ${{ env.FLY_APP_NAME }}" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "# Scale resources" >> $GITHUB_STEP_SUMMARY
+          echo "flyctl scale memory 512 --app ${{ env.FLY_APP_NAME }}" >> $GITHUB_STEP_SUMMARY
+          echo '```' >> $GITHUB_STEP_SUMMARY

.github/workflows/pr-workflow-failure-notifier.yml

@@ -1,3 +1,21 @@
+# 🚨 COPILOT PROHIBITION WARNING 🚨
+# 
+# THIS FILE IS CRITICAL TO DEPLOYMENT WORKFLOW MONITORING AND PR MANAGEMENT
+# 
+# ⛔ COPILOT AGENTS ARE STRICTLY PROHIBITED FROM MAKING ANY CHANGES TO THIS FILE
+# ⛔ WITHOUT EXPLICIT WRITTEN CONSENT FROM THE REPOSITORY OWNER (@litlfred)
+# 
+# This workflow monitors deployment failures and manages PR notifications.
+# Changes can disrupt the deployment feedback system and PR management.
+# 
+# 🔒 REQUIRED PROCESS FOR CHANGES:
+# 1. Request explicit consent from @litlfred in a GitHub comment
+# 2. Wait for written approval before making ANY changes  
+# 3. Document the explicit consent in the commit message
+# 4. Test extensively in a separate environment before merging
+# 
+# 🚨 END PROHIBITION WARNING 🚨
+
 name: PR Workflow Failure Notifier
 
 # This workflow runs after any workflow fails and posts a rich comment on the associated PR

.github/workflows/review.yml

@@ -1,3 +1,22 @@
+# 🚨 COPILOT PROHIBITION WARNING 🚨
+# 
+# THIS FILE IS CRITICAL TO PR APPROVAL AND DEPLOYMENT AUTOMATION
+# 
+# ⛔ COPILOT AGENTS ARE STRICTLY PROHIBITED FROM MAKING ANY CHANGES TO THIS FILE
+# ⛔ WITHOUT EXPLICIT WRITTEN CONSENT FROM THE REPOSITORY OWNER (@litlfred)
+# 
+# This workflow handles automatic deployment upon PR approval and integrates
+# with the deployment infrastructure. Changes can disrupt the review and
+# deployment process.
+# 
+# 🔒 REQUIRED PROCESS FOR CHANGES:
+# 1. Request explicit consent from @litlfred in a GitHub comment
+# 2. Wait for written approval before making ANY changes  
+# 3. Document the explicit consent in the commit message
+# 4. Test extensively in a separate environment before merging
+# 
+# 🚨 END PROHIBITION WARNING 🚨
+
 name: PR Review Deployment
 
 on:

.gitignore

@@ -10,6 +10,10 @@ yarn-error.log*
 /.next
 _site/
 
+# TypeScript build artifacts
+*.d.ts.map
+*.js.map
+
 # Environment variables
 .env
 .env.local
@@ -107,3 +111,4 @@ test-pr-feedback-improvements.md
 
 # Deployment structure (generated by CI/CD)
 sgex/public/404-complex-backup.html
+scripts/__pycache__/

BRANCH_DEPLOYMENT_FIX.md

@@ -34,8 +34,8 @@ on:
 When a commit is pushed to any feature branch with an open PR:
 
 1. ✅ `branch-deployment.yml` triggers and builds the preview
-2. ✅ `pr-commit-feedback.yml` triggers and provides PR feedback
-3. ✅ PR gets immediate "build in progress" comment
+2. ✅ **PR gets immediate "build started" notification** (posted at workflow start)
+3. ✅ `pr-commit-feedback.yml` triggers and provides PR feedback
 4. ✅ PR gets updated with deployment success/failure status
 5. ✅ PR includes clickable links to preview URLs and build logs
 
@@ -49,25 +49,65 @@ The fix maintains proper coordination between workflows:
 
 ### Testing
 
-Added comprehensive tests in `src/tests/BranchDeploymentWorkflowTriggers.test.js` to verify:
+Added comprehensive tests to verify the deployment workflow:
 
+**Branch Deployment Triggers** (`src/tests/BranchDeploymentWorkflowTriggers.test.js`):
 - ✅ Workflow triggers on all branches except excluded ones
 - ✅ PR feedback workflow coordination works correctly
 - ✅ YAML configuration is syntactically valid
 - ✅ Integration logic works as expected
 
+**Build Start Notification** (`src/tests/BuildStartNotification.test.js`):
+- ✅ Build start notification step exists in workflow
+- ✅ Notification is positioned immediately after checkout
+- ✅ Notification comes before all build/test/deploy steps
+- ✅ Uses correct GitHub Script action
+- ✅ Handles errors gracefully without failing workflow
+- ✅ Message includes commit SHA with clickable link
+- ✅ Finds and posts to associated PR correctly
+- ✅ Workflow has proper permissions for PR comments
+
+### Build Started Notification Enhancement
+
+As part of improving developer feedback, the `branch-deployment.yml` workflow now posts an immediate notification to PRs when the build starts. This provides instant visibility into the deployment process.
+
+**Notification Format:**
+```
+Build started for commit [`abc1234`](https://github.com/litlfred/sgex/commit/full-sha)
+```
+
+**Key Features:**
+- Posted immediately after repository checkout, before any build steps
+- Includes shortened commit SHA (7 characters) for readability
+- Links directly to the full commit on GitHub
+- Gracefully handles cases where no PR exists (e.g., direct pushes)
+- Does not fail the workflow if posting fails
+
+**Implementation:**
+- New step: "Post build started notification to PR"
+- Position: Immediately after "Checkout repository" step
+- Uses: `actions/github-script@v8` for GitHub API interaction
+- Error handling: Try-catch block to prevent workflow failures
+
 ### Related Issues
 
 This fix addresses the deployment automation issues mentioned in:
 - #769: Surgical improvements to publishing workflows
 - #642: PR conversation feedback deployment preview buttons
 - #640: Improve PR deployment feedback
 - #636: Improve PR feedback on commits
+- **Build start notification**: Move PR build start notification to earliest possible point
 
 ### Files Changed
 
-- `.github/workflows/branch-deployment.yml` - Removed branch restriction
-- `src/tests/BranchDeploymentWorkflowTriggers.test.js` - Added test coverage
+**Workflow Files:**
+- `.github/workflows/branch-deployment.yml` 
+  - Removed branch restriction to enable feature branch deployments
+  - Added "Post build started notification to PR" step at workflow start
+
+**Test Files:**
+- `src/tests/BranchDeploymentWorkflowTriggers.test.js` - Test workflow triggers and configuration
+- `src/tests/BuildStartNotification.test.js` - Test build start notification functionality
 
 ### Impact