Merge pull request #24 from ShieldTech-Ltd/feature/judge-demo-decision-receipt

feat: add judge-ready decision rehearsal demo

Author: TFT444

PITCH_STAGE_GUIDE.md

@@ -8,11 +8,11 @@
 
 ## 📋 Pre-Presentation Stage Checklist
 
-- [x] **Live Vercel Deployment**: App live at `https://finpulse-ai.vercel.app` (or local backup `http://localhost:8080`).
-- [x] **Express REST API Server**: Node.js backend running on port 3000 with FCA Warning List DB.
+- [x] **Live Vercel Deployment**: App live at `https://finpulse-ai-one.vercel.app` (or local backup `http://localhost:3000`).
+- [x] **Express REST API Server**: Educational API with claim-pattern checks, decision rehearsal and receipt generation.
 - [x] **Stage Demo Preset Bar**: 1-Click presets ready for zero-friction stage scoring.
-- [x] **PWA Mobile Offline Readiness**: ServiceWorker `sw.js` cached for zero-latency presentation.
-- [x] **Stage QR Code**: Embedded on Slide 1 for instant judge phone scanning.
+- [ ] **Offline Backup**: Keep a tested local copy open before taking the stage.
+- [ ] **Stage QR Code**: Add the final production URL to Slide 1 after deployment.
 
 ---
 
@@ -22,14 +22,14 @@
 | :--- | :--- | :--- | :--- |
 | **0:00 - 0:10** | Slide 1 (Title + QR Code) | Stage Entrance | Invite judges to scan the QR code on screen to open FinPulse AI live on their phones. |
 | **0:10 - 0:45** | Slide 2 (Maya Persona) | The Problem Hook | Tell the story of Maya, 21, opening her first payslip in London confused by tax codes, targeted by 50x leverage TikTok scams. |
-| **0:45 - 2:15** | **LIVE WORKING APP DEMO** | 90-Sec Demo | Click **`⚡ 50x Forex Scam`** -> Show **95% RED FLAG SCORE** & FCA Warning List match. Show **Payslip Pension Match (+£70/mo)** and **5-Yr Compound Sandbox**. |
-| **2:15 - 3:15** | Slide 3 (B2B ROI & Metrics) | Business Model | Show Bank B2B Portal: **£1.42M FCA Fine Savings (18.9x ROI)** under FCA FG22/5 rules. |
+| **0:45 - 2:15** | **LIVE WORKING APP DEMO** | 90-Sec Demo | Select **50x Forex Scam** -> check claim-risk indicators -> enter Maya's £250 rental-deposit context -> reveal the 1% leverage downside -> answer the comprehension check -> generate the private Decision Receipt. |
+| **2:15 - 3:15** | Slide 3 (B2B Outcome Concept) | Business Model | Show how a partner could measure anonymous completion and comprehension outcomes. Clearly label the dashboard as a concept, not compliance proof. |
 | **3:15 - 4:00** | Slide 4 (Vision & Close) | The Close | *"Duolingo for Money + AI Anti-Scam Shield. Join us in building investors, not gamblers."* |
 
 ---
 
 ## ⚔️ Q&A Defense Quick Reference
 
-1. **FCA Regulated Advice Boundary**: *"FinPulse AI provides financial capability education & scam math under FCA FG22/5 guidance, not regulated personal advice."*
-2. **Anti-Scraping Defense**: *"We use client-side OCR, user transcript submissions, and official platform API metadata endpoints — no fragile web scraping."*
-3. **Bank Buyer ROI**: *"Banks pay out of their FCA Consumer Duty compliance budget to satisfy legal mandates and prevent enforcement fines."*
+1. **FCA Regulated Advice Boundary**: *"FinPulse provides educational pattern checks and decision rehearsal, not financial advice, firm authorisation checks or scam determinations."*
+2. **Input Boundary**: *"For this prototype, the user pastes a claim or transcript. Real image and video OCR are intentionally outside the demo scope."*
+3. **Bank Buyer Hypothesis**: *"We would test whether banks, employers and universities will fund access as financial-capability infrastructure. Consumer Duty makes customer understanding relevant, but FinPulse does not itself prove compliance."*

README.md

@@ -5,6 +5,7 @@ FinPulse AI is an educational financial-literacy and scam-awareness prototype bu
 It demonstrates:
 
 - plain-language checks for common high-risk promotion patterns;
+- a guided pre-decision rehearsal with missing-context questions, a personalised downside scenario, a comprehension check and a private Decision Receipt;
 - a simplified UK payslip learning calculator;
 - hypothetical investment stress-test visualisations;
 - gamified financial-literacy lessons;
@@ -14,6 +15,16 @@ It demonstrates:
 
 FinPulse AI does not provide financial advice, determine whether a firm is authorised, perform real image/video OCR, certify financial capability, or establish FCA Consumer Duty compliance. Outputs are educational prompts produced by deterministic rules. Verify firms directly through the official FCA Register and Warning List, and verify tax results against current HMRC guidance.
 
+## 90-second judge demo
+
+1. Select **50x Forex Scam** and run **Check Claim Risk Indicators**.
+2. Keep Maya's example amount and rental-deposit reason, then select **Rehearse Maya's Decision**.
+3. Show the missing context and personalised leverage downside.
+4. Answer **It magnifies losses as well as gains**.
+5. Generate the private Decision Receipt and close on the independent-verification next step.
+
+The receipt records educational completion only. It intentionally stores neither the pasted claim nor Maya's personal reason.
+
 The public deployment stores only short-lived, non-identifying demo events in memory. It intentionally has no durable customer database. Partner telemetry routes are hidden unless `ADMIN_API_TOKEN` is configured. The app does not mirror the FCA Warning List because its former RSS URL currently redirects to a missing page; users are sent to the official live list instead. A production service would additionally require authenticated users, tenant isolation, consent and retention controls, a durable managed datastore, monitoring, regulatory review, and independent security testing.
 
 ## Local development

app.js

@@ -2,9 +2,7 @@
    FinPulse AI - Commercial Platform Logic (Real Enterprise REST API Connected)
    ========================================================================== */
 
-const API_BASE_URL = (window.location.hostname === 'localhost' || window.location.hostname === '127.0.0.1')
-    ? 'http://localhost:3000/api/v1' 
-    : '/api/v1';
+const API_BASE_URL = '/api/v1';
 
 document.addEventListener('DOMContentLoaded', () => {
 
@@ -158,8 +156,8 @@ document.addEventListener('DOMContentLoaded', () => {
                 "The creator earns money from broker affiliate links when you lose your deposit.",
                 "Unregulated offshore broker — no FCA protection or FSCS guarantee."
             ],
-            reality: "FCA data shows 82% of retail traders using forex leverage lose their entire initial deposit within 30 days. Real wealth comes from low-cost index compounding, not signal groups.",
-            verdict: "DO NOT FOLLOW THIS ADVICE. High risk of complete capital destruction."
+            reality: "Leverage magnifies losses as well as gains. At 100x leverage, a move of roughly 1% against a position could put the full amount at risk, before fees and platform rules.",
+            verdict: "EDUCATIONAL CHECK: Verify the firm, evidence, costs and downside independently before deciding."
         },
         crypto: {
             text: "This new low-cap meme token is launching on DEX today! Guaranteed 100x gains before liquidity lock. Buy now or cry later! 💎🙌",
@@ -171,8 +169,8 @@ document.addEventListener('DOMContentLoaded', () => {
                 "High creator token concentration: developers can dump holdings and drain liquidity pool.",
                 "Fake hype generated by paid bot accounts on X and Telegram."
             ],
-            reality: "Over 97% of DEX meme tokens launched daily become inactive or worthless within 14 days. Treat crypto sandbox trading as high-risk speculation.",
-            verdict: "HIGH RISK SPECULATION. Only gamble money you are 100% prepared to write off."
+            reality: "A token promotion does not demonstrate liquidity, contract safety, ownership concentration or the ability to sell. Those facts require independent verification.",
+            verdict: "EDUCATIONAL CHECK: Missing evidence is not proof of safety or fraud. Pause and verify independently."
         },
         bnpl: {
             text: "Why pay £120 for clothes today when you can split it into 4 easy interest-free payments? It's basically free money and doesn't affect anything! 🛍️✨",
@@ -184,8 +182,8 @@ document.addEventListener('DOMContentLoaded', () => {
                 "Missing payments triggers missed payment markers reported to UK Credit Reference Agencies.",
                 "Can severely impact your future mortgage or tenancy application suitability."
             ],
-            reality: "BNPL is a credit product, not free money. Missing a £15 payment can harm your ability to rent an apartment 2 years later.",
-            verdict: "USE WITH CAUTION. Track all installments as real debt commitments."
+            reality: "BNPL is a credit commitment, not free money. Several small instalments can overlap and reduce next month's available cash.",
+            verdict: "EDUCATIONAL CHECK: Add every instalment to next month's committed spending before deciding."
         },
         index: {
             text: "Invest £150 a month into a low-cost, broadly diversified Global Index ETF (like S&P 500 or FTSE All-World) and let compound growth build long-term wealth over 10+ years.",
@@ -196,8 +194,8 @@ document.addEventListener('DOMContentLoaded', () => {
                 "Short-term price fluctuations will occur during market dips.",
                 "Requires long-term patience (5-10+ year time horizon)."
             ],
-            reality: "Historically, broad market index funds have delivered ~7-10% annualized returns over multi-decade periods with zero reliance on timing the market.",
-            verdict: "SOLID FINANCIAL EDUCATION PRACTICE. Encourages investor mindset over gambling."
+            reality: "Diversification can spread company-specific risk, but investment values can still fall and past performance does not guarantee future returns.",
+            verdict: "EDUCATIONAL CHECK: Fees, time horizon, diversification and downside still require consideration."
         }
     };
 
@@ -271,7 +269,13 @@ document.addEventListener('DOMContentLoaded', () => {
     function renderApiScorecard(sc, auditId) {
         document.getElementById('metric-score').innerText = `${sc.scamScore}%`;
         document.getElementById('metric-risk').innerText = `${sc.riskLevel} RISK`;
-        document.getElementById('metric-monetization').innerText = sc.fcaStatus;
+        document.getElementById('metric-monetization').innerText = sc.fcaStatus === 'WARNING_UNAUTHORISED_FIRM'
+            ? 'Warning-list pattern match'
+            : 'Use official FCA checks';
+
+        const riskBadge = document.getElementById('risk-badge');
+        riskBadge.className = `risk-badge ${sc.riskLevel === 'RED' ? 'risk-high' : sc.riskLevel === 'AMBER' ? 'risk-medium' : 'risk-low'}`;
+        riskBadge.innerHTML = `<i class="fa-solid fa-triangle-exclamation"></i> ${sc.riskLevel === 'GREEN' ? 'NO COMMON HIGH-RISK PHRASE DETECTED' : `${sc.riskLevel} CLAIM-RISK INDICATORS`}`;
 
         const flagsContainer = document.getElementById('flags-container');
         flagsContainer.innerHTML = '';
@@ -289,7 +293,7 @@ document.addEventListener('DOMContentLoaded', () => {
         }
 
         document.getElementById('reality-box-text').innerText = sc.mathReality;
-        document.getElementById('verdict-text').innerText = `[API AUDIT LOG ${auditId}] FCA Status: ${sc.fcaStatus}. Evaluated by FinPulse AI REST Server.`;
+        document.getElementById('verdict-text').innerText = `Pattern check ${auditId}: ${sc.fcaStatus}. This is not a scam determination or financial advice.`;
     }
 
     function runBSScan(data) {
@@ -309,6 +313,118 @@ document.addEventListener('DOMContentLoaded', () => {
         document.getElementById('verdict-text').innerText = data.verdict;
     }
 
+    // --- Guided claim-to-Decision-Receipt demo ---
+    const rehearseBtn = document.getElementById('rehearse-btn');
+    const receiptBtn = document.getElementById('receipt-btn');
+    const rehearsalResults = document.getElementById('rehearsal-results');
+    const decisionReceipt = document.getElementById('decision-receipt');
+    const decisionError = document.getElementById('decision-error');
+    let activeRehearsal = null;
+    let selectedComprehensionOption = null;
+
+    if (rehearseBtn) {
+        rehearseBtn.addEventListener('click', async () => {
+            const amount = Number(document.getElementById('decision-amount').value);
+            const reason = document.getElementById('decision-reason').value.trim();
+            decisionError.classList.add('hidden');
+            rehearseBtn.disabled = true;
+            rehearseBtn.innerHTML = '<i class="fa-solid fa-spinner fa-spin"></i> Rehearsing downside...';
+
+            try {
+                const response = await fetch(`${API_BASE_URL}/rehearsal`, {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json' },
+                    body: JSON.stringify({ claimText: claimInput.value, amount, reason })
+                });
+                const data = await response.json();
+                if (!response.ok) throw new Error(data.error || 'Unable to run the rehearsal.');
+
+                activeRehearsal = { ...data, amount };
+                selectedComprehensionOption = null;
+                renderRehearsal(data);
+            } catch (error) {
+                decisionError.textContent = error.message;
+                decisionError.classList.remove('hidden');
+            } finally {
+                rehearseBtn.disabled = false;
+                rehearseBtn.innerHTML = '<i class="fa-solid fa-shield-heart"></i> Rehearse Maya\'s Decision';
+            }
+        });
+    }
+
+    function renderRehearsal(data) {
+        const missingList = document.getElementById('missing-context-list');
+        missingList.innerHTML = '';
+        data.missingContext.forEach(item => {
+            const li = document.createElement('li');
+            li.textContent = item;
+            missingList.appendChild(li);
+        });
+        document.getElementById('downside-scenario').textContent = data.downsideScenario;
+        document.getElementById('comprehension-question').textContent = data.comprehension.question;
+
+        const options = document.getElementById('comprehension-options');
+        options.innerHTML = '';
+        data.comprehension.options.forEach((option, index) => {
+            const button = document.createElement('button');
+            button.type = 'button';
+            button.className = 'receipt-option';
+            button.textContent = option;
+            button.addEventListener('click', () => {
+                options.querySelectorAll('.receipt-option').forEach(item => item.classList.remove('selected'));
+                button.classList.add('selected');
+                selectedComprehensionOption = index;
+                receiptBtn.disabled = false;
+            });
+            options.appendChild(button);
+        });
+
+        receiptBtn.disabled = true;
+        rehearsalResults.classList.remove('hidden');
+        decisionReceipt.classList.add('hidden');
+        document.querySelectorAll('.flow-step').forEach((step, index) => step.classList.toggle('active', index < 3));
+        rehearsalResults.scrollIntoView({ behavior: 'smooth', block: 'start' });
+    }
+
+    if (receiptBtn) {
+        receiptBtn.addEventListener('click', async () => {
+            if (!activeRehearsal || selectedComprehensionOption === null) return;
+            receiptBtn.disabled = true;
+            try {
+                const response = await fetch(`${API_BASE_URL}/decision-receipt`, {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json' },
+                    body: JSON.stringify({
+                        rehearsalId: activeRehearsal.rehearsalId,
+                        amount: activeRehearsal.amount,
+                        selectedOption: selectedComprehensionOption
+                    })
+                });
+                const data = await response.json();
+                if (!response.ok) throw new Error(data.error || 'Unable to create the receipt.');
+                renderDecisionReceipt(data);
+            } catch (error) {
+                decisionError.textContent = error.message;
+                decisionError.classList.remove('hidden');
+                receiptBtn.disabled = false;
+            }
+        });
+    }
+
+    function renderDecisionReceipt(data) {
+        document.getElementById('receipt-id').textContent = data.receiptId;
+        document.getElementById('receipt-created').textContent = new Date(data.createdAt).toLocaleString('en-GB');
+        document.getElementById('receipt-amount').textContent = `£${activeRehearsal.amount.toLocaleString('en-GB')}`;
+        document.getElementById('receipt-next-step').textContent = data.nextStep;
+        document.getElementById('receipt-privacy').textContent = data.privacy;
+        const status = document.getElementById('receipt-status');
+        status.textContent = data.learningStatus === 'CORE_RISK_UNDERSTOOD' ? 'Core risk understood' : 'Review recommended';
+        status.className = `receipt-status ${data.learningStatus === 'CORE_RISK_UNDERSTOOD' ? 'understood' : 'review'}`;
+        decisionReceipt.classList.remove('hidden');
+        document.querySelectorAll('.flow-step').forEach(step => step.classList.add('active'));
+        decisionReceipt.scrollIntoView({ behavior: 'smooth', block: 'center' });
+    }
+
     // --- 3. UK Payslip Decoder Engine (HMRC API Connected) ---
     const salarySlider = document.getElementById('salary-slider');
     const salaryDisplay = document.getElementById('salary-display');
@@ -360,13 +476,17 @@ document.addEventListener('DOMContentLoaded', () => {
     }
 
     function renderPayslipResults(s) {
-        document.getElementById('pay-gross').innerText = `£${s.grossSalaryMonthly.toLocaleString()}`;
-        document.getElementById('pay-tax').innerText = `-£${s.payeTaxMonthly.toLocaleString()}`;
-        document.getElementById('pay-ni').innerText = `-£${s.nationalInsuranceMonthly.toLocaleString()}`;
-        document.getElementById('pay-student').innerText = `-£${s.studentLoanMonthly.toLocaleString()}`;
-        document.getElementById('pay-pension').innerText = `-£${s.employeePensionMonthly.toLocaleString()}`;
-        document.getElementById('pay-match').innerText = `+£${s.freeEmployerPensionMatchMonthly.toLocaleString()}`;
-        document.getElementById('pay-net').innerText = `£${s.netTakeHomeMonthly.toLocaleString()}`;
+        document.getElementById('ps-gross').innerText = `£${s.grossSalaryMonthly.toLocaleString()}`;
+        document.getElementById('ps-tax').innerText = `-£${s.payeTaxMonthly.toLocaleString()}`;
+        document.getElementById('ps-ni').innerText = `-£${s.nationalInsuranceMonthly.toLocaleString()}`;
+        document.getElementById('ps-student-loan').innerText = `-£${s.studentLoanMonthly.toLocaleString()}`;
+        document.getElementById('ps-pension').innerText = `-£${s.employeePensionMonthly.toLocaleString()}`;
+        document.getElementById('ps-net-pay').innerText = `£${s.netTakeHomeMonthly.toLocaleString()}`;
+        document.getElementById('ps-total-deductions').innerText = `£${(s.payeTaxMonthly + s.nationalInsuranceMonthly + s.studentLoanMonthly + s.employeePensionMonthly).toLocaleString()}`;
+        document.getElementById('ps-pension-label').innerText = `Employee Pension (${appState.pensionPct}%)`;
+        document.getElementById('ps-tax-code').innerText = taxCodeSelect ? taxCodeSelect.value : '1257L';
+        const payslipTip = document.getElementById('payslip-tip');
+        if (payslipTip) payslipTip.textContent = `Illustrative employer contribution: £${s.freeEmployerPensionMatchMonthly.toLocaleString()}/month. Check your scheme rules before deciding.`;
 
         if (document.getElementById('annual-net-summary')) {
             document.getElementById('annual-net-summary').innerText = `Annual Net Take-Home Pay: £${s.netTakeHomeAnnual.toLocaleString()}`;