@thierrynakoa/fire-flow 12.2.1 → 13.0.1

package/skills-library/deployment-security/PYINSTALLER_CUDA_WHISPER_BUNDLING.md

@@ -0,0 +1,236 @@
+# PyInstaller + CUDA/faster-whisper Bundling — Solution & Implementation
+
+## The Problem
+
+Packaging a Python desktop app that uses **faster-whisper** (CTranslate2 backend with CUDA GPU acceleration) into a distributable Windows `.exe` via PyInstaller. The build either crashes at runtime with missing DLLs, fails to find the Whisper model, or silently falls back to CPU because CUDA libraries weren't bundled.
+
+### Why It Was Hard
+
+- CTranslate2 ships CUDA/cuDNN DLLs as binary extensions that PyInstaller doesn't auto-detect
+- `faster-whisper` has implicit imports PyInstaller's analysis misses
+- `sounddevice` bundles PortAudio as data files, not standard Python imports
+- `pynput`, `pystray`, and `keyboard` all have platform-specific backends (`_win32`) that need explicit hidden imports
+- The `anthropic` SDK pulls in `httpx`/`httpcore`/`anyio` — deep async dependency chains
+- `--onefile` mode is a trap: CUDA DLLs are 500MB+ and extract to temp on every launch
+
+### Impact
+
+- App won't start (missing DLL errors)
+- Whisper transcription fails or runs on CPU (10x slower) instead of GPU
+- End users get cryptic `ModuleNotFoundError` at runtime
+- Build appears to succeed but the exe is broken
+
+---
+
+## The Solution
+
+### Root Cause
+
+PyInstaller's static analysis can't trace binary extensions loaded via `ctypes`, platform-dispatched backends (e.g., `pystray._win32`), or data files shipped alongside packages. You must explicitly collect these.
+
+### The Spec File Pattern
+
+```python
+# -*- mode: python ; coding: utf-8 -*-
+"""PyInstaller spec for apps using faster-whisper with CUDA."""
+from PyInstaller.utils.hooks import collect_data_files, collect_dynamic_libs
+
+block_cipher = None
+
+# KEY INSIGHT: collect_dynamic_libs grabs ALL .dll/.so from the package
+# This catches CUDA, cuDNN, and CTranslate2 backend libraries
+ctranslate2_binaries = collect_dynamic_libs('ctranslate2')
+
+# sounddevice ships PortAudio as data files, not binaries
+sounddevice_data = collect_data_files('sounddevice')
+
+# faster-whisper may include tokenizer assets
+faster_whisper_data = collect_data_files('faster_whisper')
+
+a = Analysis(
+    ['src/your_app/__main__.py'],
+    binaries=ctranslate2_binaries,
+    datas=(
+        sounddevice_data
+        + faster_whisper_data
+        + [('assets', 'assets')]  # your app's data files
+    ),
+    hiddenimports=[
+        # -- CUDA transcription backend --
+        'ctranslate2',
+        'faster_whisper',
+
+        # -- Audio --
+        'sounddevice',
+        '_sounddevice_data',
+
+        # -- Global hotkeys (if using keyboard lib) --
+        'keyboard',
+
+        # -- pynput (platform-specific backends) --
+        'pynput.keyboard._win32',
+        'pynput.mouse._win32',
+
+        # -- System tray (platform-specific) --
+        'pystray._win32',
+
+        # -- Anthropic SDK + HTTP stack --
+        'anthropic',
+        'httpx', 'httpcore', 'h11',
+        'sniffio', 'anyio', 'anyio._backends._asyncio',
+
+        # -- Config --
+        'yaml',
+
+        # -- Image handling (Pillow, used by pystray) --
+        'PIL', 'PIL.Image',
+
+        # -- GUI --
+        'tkinter', 'tkinter.ttk', 'tkinter.font',
+        'tkinter.scrolledtext', 'tkinter.messagebox',
+
+        # -- Other --
+        'numpy', 'winsound', 'pyperclip',
+    ],
+    excludes=['pytest', 'setuptools', 'pip', 'wheel'],
+    cipher=block_cipher,
+    noarchive=False,
+)
+
+pyz = PYZ(a.pure, a.zipped_data, cipher=block_cipher)
+
+# IMPORTANT: Use onedir, not onefile. CUDA DLLs are too large.
+exe = EXE(
+    pyz, a.scripts, [],
+    exclude_binaries=True,
+    name='YourApp',
+    console=False,     # GUI/tray app — no console window
+    upx=False,         # Don't compress — CUDA DLLs don't compress well
+)
+
+coll = COLLECT(
+    exe, a.binaries, a.zipfiles, a.datas,
+    strip=False, upx=False,
+    name='YourApp',
+)
+```
+
+### Critical Decisions Explained
+
+| Decision | Why |
+|----------|-----|
+| `--onedir` not `--onefile` | CUDA DLLs are 500MB+. Onefile extracts to temp on every launch — 30s+ startup |
+| `upx=False` | UPX breaks CUDA DLLs and provides minimal savings on binary extensions |
+| `console=False` | Tray/GUI apps shouldn't show a console window |
+| `collect_dynamic_libs('ctranslate2')` | The **key** line — grabs CUDA + cuDNN wrapper DLLs |
+| `collect_data_files('sounddevice')` | PortAudio is shipped as data, not a Python import |
+| Platform-specific hidden imports | `pystray._win32`, `pynput.keyboard._win32` — PyInstaller can't detect dispatch |
+
+### Frozen Mode Detection (for autostart, paths, etc.)
+
+```python
+import sys
+
+if getattr(sys, 'frozen', False):
+    # Running as PyInstaller bundle
+    app_dir = sys._MEIPASS          # Extracted temp dir (onefile) or bundle dir (onedir)
+    exe_path = sys.executable       # The actual .exe path
+else:
+    # Running from source
+    app_dir = os.path.dirname(__file__)
+    exe_path = sys.executable       # Python interpreter
+```
+
+### Build Script (Windows)
+
+```bat
+@echo off
+call .venv\Scripts\activate.bat
+pip install pyinstaller>=6.0 >nul 2>&1
+pyinstaller voice-bridge.spec --clean --noconfirm
+```
+
+---
+
+## Testing the Fix
+
+### Build Verification
+```bash
+# Build completes without errors
+pyinstaller your-app.spec --clean --noconfirm
+
+# Output directory exists with exe + DLLs
+dir dist\YourApp\YourApp.exe
+dir dist\YourApp\*.dll | find /c ".dll"   # Should show CUDA DLLs
+```
+
+### Runtime Verification
+```
+1. Launch dist\YourApp\YourApp.exe
+2. Verify tray icon appears (pystray works)
+3. Trigger audio recording (sounddevice works)
+4. Trigger transcription (faster-whisper + CUDA works)
+5. Check GPU is used: look for "Model loaded on cuda" in logs
+```
+
+### Common Runtime Errors and Fixes
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| `ModuleNotFoundError: ctranslate2` | Missing hidden import | Add `'ctranslate2'` to hiddenimports |
+| `Could not load library cudnn` | cuDNN DLLs not bundled | Verify `collect_dynamic_libs('ctranslate2')` is in binaries |
+| `No module named 'pystray._win32'` | Platform backend not found | Add `'pystray._win32'` to hiddenimports |
+| `PortAudio not found` | sounddevice data not bundled | Add `collect_data_files('sounddevice')` to datas |
+| `httpcore not found` | anthropic SDK dependency chain | Add `'httpx', 'httpcore', 'h11'` to hiddenimports |
+| App starts but GPU not used | CUDA DLLs missing at runtime | Check `dist/YourApp/` for `cublas*.dll`, `cudnn*.dll` |
+
+---
+
+## Prevention
+
+1. **Always use `collect_dynamic_libs`** for packages with native extensions (ctranslate2, torch, onnxruntime)
+2. **Always use `collect_data_files`** for packages that ship non-Python data (sounddevice, transformers)
+3. **Test the frozen build immediately** — don't assume build success = runtime success
+4. **Log which device** your ML model loads on (cuda vs cpu) so you can catch silent fallbacks
+5. **Use `--onedir`** for CUDA apps — `--onefile` is a trap
+
+---
+
+## Related Patterns
+
+- GPU fallback pattern: try CUDA, catch exception, fall back to CPU with logging
+- Frozen path detection: `getattr(sys, 'frozen', False)` for all path-dependent code
+- Windows autostart with registry: different commands for frozen vs source
+
+---
+
+## Common Mistakes to Avoid
+
+- Using `--onefile` with CUDA libraries (30s+ startup, temp extraction issues)
+- Forgetting platform-specific backends (pystray, pynput on Windows)
+- Not testing the actual .exe (build succeeding doesn't mean runtime works)
+- Using `upx=True` which breaks CUDA DLLs
+- Assuming PyInstaller traces `ctypes.cdll.LoadLibrary` calls (it doesn't)
+
+---
+
+## Resources
+
+- [PyInstaller hooks documentation](https://pyinstaller.org/en/stable/hooks.html)
+- [faster-whisper GitHub](https://github.com/SYSTRAN/faster-whisper)
+- [CTranslate2 packaging](https://github.com/OpenNMT/CTranslate2)
+
+---
+
+## Time to Implement
+
+**30-60 minutes** for initial spec file creation and testing. Most time spent on iterating hidden imports after runtime errors.
+
+## Difficulty Level
+
+Stars: 4/5 — Requires understanding of PyInstaller internals, CUDA library loading, and platform-specific Python package dispatch. Hard to debug because errors only appear at runtime in the frozen build.
+
+---
+
+**Author Notes:**
+The #1 insight: `collect_dynamic_libs('ctranslate2')` is the magic line. Without it, you get a build that succeeds but an exe that crashes. The second insight: always use `--onedir` for ML/CUDA apps. The `--onefile` mode is tempting but creates a terrible user experience with multi-hundred-MB temp extractions on every launch.

package/skills-library/deployment-security/SECURITY.md

@@ -0,0 +1,41 @@
+<!-- BEGIN MICROSOFT SECURITY.MD V0.0.7 BLOCK -->
+
+## Security
+
+Microsoft takes the security of our software products and services seriously, which includes all source code repositories managed through our GitHub organizations, which include [Microsoft](https://github.com/Microsoft), [Azure](https://github.com/Azure), [DotNet](https://github.com/dotnet), [AspNet](https://github.com/aspnet), [Xamarin](https://github.com/xamarin), and [our GitHub organizations](https://opensource.microsoft.com/).
+
+If you believe you have found a security vulnerability in any Microsoft-owned repository that meets [Microsoft's definition of a security vulnerability](https://aka.ms/opensource/security/definition), please report it to us as described below.
+
+## Reporting Security Issues
+
+**Please do not report security vulnerabilities through public GitHub issues.**
+
+Instead, please report them to the Microsoft Security Response Center (MSRC) at [https://msrc.microsoft.com/create-report](https://aka.ms/opensource/security/create-report).
+
+If you prefer to submit without logging in, send email to [secure@microsoft.com](mailto:secure@microsoft.com).  If possible, encrypt your message with our PGP key; please download it from the [Microsoft Security Response Center PGP Key page](https://aka.ms/opensource/security/pgpkey).
+
+You should receive a response within 24 hours. If for some reason you do not, please follow up via email to ensure we received your original message. Additional information can be found at [microsoft.com/msrc](https://aka.ms/opensource/security/msrc). 
+
+Please include the requested information listed below (as much as you can provide) to help us better understand the nature and scope of the possible issue:
+
+  * Type of issue (e.g. buffer overflow, SQL injection, cross-site scripting, etc.)
+  * Full paths of source file(s) related to the manifestation of the issue
+  * The location of the affected source code (tag/branch/commit or direct URL)
+  * Any special configuration required to reproduce the issue
+  * Step-by-step instructions to reproduce the issue
+  * Proof-of-concept or exploit code (if possible)
+  * Impact of the issue, including how an attacker might exploit the issue
+
+This information will help us triage your report more quickly.
+
+If you are reporting for a bug bounty, more complete reports can contribute to a higher bounty award. Please visit our [Microsoft Bug Bounty Program](https://aka.ms/opensource/security/bounty) page for more details about our active programs.
+
+## Preferred Languages
+
+We prefer all communications to be in English.
+
+## Policy
+
+Microsoft follows the principle of [Coordinated Vulnerability Disclosure](https://aka.ms/opensource/security/cvd).
+
+<!-- END MICROSOFT SECURITY.MD BLOCK -->

package/skills-library/deployment-security/SMTP_SSL_HOSTNAME_MISMATCH_SHARED_HOSTING.md

@@ -0,0 +1,220 @@
+# SMTP SSL Certificate Hostname Mismatch on Shared Hosting - Solution
+
+## The Problem
+
+When sending emails (e.g., verification emails) from a Node.js application on shared hosting, you get an SSL certificate error:
+
+```
+Hostname/IP does not match certificate's altnames:
+Host: mail.yourdomain.com. is not in the cert's altnames:
+DNS:autoconfig.server1.hostingprovider.com,
+DNS:mail.server1.hostingprovider.com,
+DNS:server1.hostingprovider.com,
+...
+```
+
+### Why It Was Hard
+
+- The error message is confusing - it lists hostnames that ARE valid, not what's wrong
+- Many developers assume they need to disable SSL entirely (insecure)
+- The `rejectUnauthorized: false` setting doesn't always work as expected
+- Understanding shared hosting SSL certificate architecture isn't obvious
+- Multiple potential solutions exist, unclear which is best
+
+### Impact
+
+- Email verification fails for new users
+- Password reset emails don't send
+- Any transactional email fails
+- Users cannot complete registration/enrollment flows
+
+---
+
+## The Solution
+
+### Root Cause
+
+On shared hosting, your mail subdomain `mail.yourdomain.com` is a DNS alias pointing to the hosting provider's actual mail server (e.g., `mail.server1.hostingprovider.com`).
+
+The SSL certificate on that server covers the **provider's hostnames**, not your domain's hostname. When nodemailer connects to `mail.yourdomain.com`, SSL verification fails because that hostname isn't in the certificate.
+
+### Two Solutions
+
+#### Option A: Use the Provider's Mail Server Hostname (Quick Fix)
+
+Change your `EMAIL_HOST` environment variable to use the hostname that's actually in the certificate:
+
+```bash
+# Instead of:
+EMAIL_HOST=mail.yourdomain.com
+
+# Use:
+EMAIL_HOST=mail.server1.hostingprovider.com
+```
+
+**How to find the correct hostname:**
+Look at the error message - it lists all valid hostnames. Find the one that starts with `mail.` (e.g., `mail.server1.hostingprovider.com`).
+
+**Why this works:**
+- You connect to the hostname that matches the certificate (SSL passes)
+- You still authenticate with your email credentials (`user@yourdomain.com`)
+- Emails are still sent FROM your domain (controlled by `EMAIL_FROM`)
+- Recipients see your domain, not the provider's
+
+#### Option B: Install SSL Certificate for Your Mail Subdomain (Proper Fix)
+
+Get an SSL certificate that covers `mail.yourdomain.com`:
+
+1. **In cPanel:** Go to SSL/TLS Status or AutoSSL
+2. **Find your mail subdomain** in the list
+3. **Issue/install a certificate** for `mail.yourdomain.com`
+4. After installation, keep `EMAIL_HOST=mail.yourdomain.com`
+
+This is cleaner but requires:
+- Purchasing or provisioning an SSL cert
+- Access to cPanel/hosting control panel
+- Waiting for cert issuance (can take minutes to hours)
+
+---
+
+## Code Implementation
+
+### Nodemailer Configuration with TLS Fallback
+
+```javascript
+// server/config/email.js
+import nodemailer from 'nodemailer';
+
+const createTransporter = () => {
+  const config = {
+    host: process.env.EMAIL_HOST,
+    port: parseInt(process.env.EMAIL_PORT || '465'),
+    secure: process.env.EMAIL_PORT === '465',
+    auth: {
+      user: process.env.EMAIL_USER,
+      pass: process.env.EMAIL_PASSWORD
+    }
+  };
+
+  // Allow hostname-mismatched certs for shared hosting
+  // Set EMAIL_TLS_REJECT_UNAUTHORIZED=false to enable this
+  const rejectUnauthorized = process.env.EMAIL_TLS_REJECT_UNAUTHORIZED !== 'false';
+
+  config.tls = {
+    rejectUnauthorized,
+  };
+
+  return nodemailer.createTransport(config);
+};
+```
+
+### Environment Variables
+
+```bash
+# .env file
+
+# Option A: Use provider's hostname (recommended for shared hosting)
+EMAIL_HOST=mail.server1.hostingprovider.com
+EMAIL_PORT=465
+EMAIL_USER=noreply@yourdomain.com
+EMAIL_PASSWORD=your-email-password
+EMAIL_FROM="Your App <noreply@yourdomain.com>"
+
+# Optional: Disable TLS verification (less secure fallback)
+# Only use if Option A doesn't work
+EMAIL_TLS_REJECT_UNAUTHORIZED=false
+```
+
+---
+
+## Testing the Fix
+
+### Before Fix
+```
+Error: Hostname/IP does not match certificate's altnames
+Email sending: FAILED
+```
+
+### After Fix (Option A)
+```
+[EmailService] Connecting to mail.server1.hostingprovider.com:465
+[EmailService] Email sent successfully: <message-id@yourdomain.com>
+Email sending: SUCCESS
+```
+
+### Verification Steps
+
+1. SSH into server
+2. Update `.env` with new `EMAIL_HOST`
+3. Restart application: `pm2 restart all`
+4. Test email sending (e.g., trigger verification email)
+5. Check logs for success message
+
+---
+
+## Prevention
+
+1. **Document your hosting's mail server hostname** - Keep it in deployment docs
+2. **Use environment variables** - Never hardcode mail server hostnames
+3. **Add TLS fallback option** - Include `EMAIL_TLS_REJECT_UNAUTHORIZED` in your config
+4. **Test email in staging** - Before deploying to production
+
+---
+
+## Related Patterns
+
+- [env-file-management-production-local.md](./env-file-management-production-local.md) - Environment variable management
+- [deployment-changes-not-applying.md](./deployment-changes-not-applying.md) - Debugging deployment issues
+
+---
+
+## Common Mistakes to Avoid
+
+- **Setting `rejectUnauthorized: false` blindly** - This disables ALL certificate verification. Use Option A instead.
+- **Assuming your domain has its own mail cert** - On shared hosting, it usually doesn't.
+- **Not restarting PM2 after .env changes** - PM2 caches environment variables.
+- **Using `pm2 restart` instead of `pm2 delete && pm2 start`** - Sometimes restart doesn't reload env vars.
+
+---
+
+## Hosting Provider Examples
+
+| Provider | Typical Mail Hostname |
+|----------|----------------------|
+| cPanel shared | `mail.serverX.provider.com` |
+| Hostinger | `smtp.hostinger.com` |
+| Bluehost | `mail.yourdomain.com` (usually has cert) |
+| GoDaddy | `smtpout.secureserver.net` |
+| SiteGround | `mail.yourdomain.com` (usually has cert) |
+
+**Always check the error message** - it tells you exactly which hostnames are valid.
+
+---
+
+## Resources
+
+- [Nodemailer TLS Options](https://nodemailer.com/smtp/#tls-options)
+- [Let's Encrypt for cPanel](https://docs.cpanel.net/knowledge-base/security/ssl-tls/)
+- [Understanding SSL Certificate SANs](https://www.ssl.com/faqs/what-is-a-san-certificate/)
+
+---
+
+## Time to Implement
+
+**Option A:** 5 minutes (just change env var)
+**Option B:** 15-60 minutes (depends on SSL provisioning time)
+
+## Difficulty Level
+
+**Diagnosis:** 3/5 - Error message is confusing
+**Fix:** 1/5 - Just an env var change once you understand the issue
+
+---
+
+**Author Notes:**
+
+This issue is extremely common on shared hosting but poorly documented. The key insight is understanding that `mail.yourdomain.com` is just a DNS alias - the actual server uses the hosting provider's certificate.
+
+The error message actually gives you the solution - it lists all the valid hostnames. Look for the one starting with `mail.` and use that as your `EMAIL_HOST`.
+
+Don't waste time trying to make `rejectUnauthorized: false` work. Just use the correct hostname. It's simpler, more secure, and works reliably.

package/skills-library/deployment-security/SPA_SEO_OPTIMIZATION_CPANEL.md

@@ -0,0 +1,200 @@
+# React SPA SEO Optimization on cPanel Shared Hosting
+
+## The Problem
+
+Client-side React SPAs render zero content for search engine crawlers. Google sees:
+- Title: "Loading..." or generic title
+- Content: 0 words, 0 headings, 0 links
+- No structured data, no OG tags, no sitemap
+
+This results in Grade F (40-50/100) on SEO audits.
+
+### Why It Was Hard
+
+- SPA architecture fundamentally conflicts with SEO — content is JavaScript-rendered
+- cPanel shared hosting with nginx reverse proxy adds complexity for security headers
+- `.htaccess` rules must coexist with WebSocket proxy, API proxy, and PHP handler rules
+- `cp -rf dist/*` during deployment silently skips dotfiles (`.htaccess`)
+- No SSR/pre-rendering infrastructure available on shared hosting
+
+### Impact
+
+- Zero Google visibility — site effectively invisible to search engines
+- No rich results (missing structured data)
+- No social sharing previews (missing OG tags)
+- Security headers only on API routes (Express/Helmet), not on static files
+
+---
+
+## The Solution
+
+### Strategy: Quick Wins Without SSR
+
+Instead of adding SSR infrastructure, use these techniques to go from Grade F → Grade C:
+
+1. **Static SEO in `index.html`** — title, description, canonical, OG tags, JSON-LD
+2. **`<noscript>` fallback** — crawlable HTML with nav, content sections, footer
+3. **Visible SEO footer** — privacy/legal links outside `<noscript>` (hidden by React on mount)
+4. **Static `sitemap.xml`** — list all public routes for crawler discovery
+5. **`.htaccess` security headers** — CSP, HSTS, X-Frame-Options for Apache-served files
+6. **CSP `<meta http-equiv>` fallback** — browsers honor CSP via meta tag
+7. **Vite code splitting** — `manualChunks` to reduce main bundle size
+
+### Implementation
+
+#### 1. index.html — Complete SEO Head
+
+```html
+<head>
+  <title>Site Name - Description (under 60 chars)</title>
+  <meta name="description" content="Under 160 chars..." />
+  <link rel="canonical" href="https://yoursite.com/" />
+
+  <!-- Robot Control -->
+  <meta name="robots" content="index, follow, noarchive, nocache, noimageindex" />
+
+  <!-- CSP meta fallback (for static hosting without HTTP header control) -->
+  <meta http-equiv="Content-Security-Policy" content="default-src 'self'; ..." />
+
+  <!-- Open Graph -->
+  <meta property="og:type" content="website" />
+  <meta property="og:title" content="..." />
+  <meta property="og:image" content="https://yoursite.com/og-image.jpg" />
+
+  <!-- JSON-LD Structured Data -->
+  <script type="application/ld+json">
+  { "@context": "https://schema.org", "@type": "EducationalOrganization", ... }
+  </script>
+</head>
+```
+
+#### 2. Noscript Fallback + SEO Footer
+
+```html
+<body>
+  <div id="root"></div>
+
+  <!-- Visible to crawlers, removed by React on mount -->
+  <footer id="seo-footer" class="text-xs text-gray-500 text-center p-4">
+    <a href="/privacy">Privacy Policy</a> |
+    <a href="/terms">Terms of Service</a>
+  </footer>
+
+  <noscript>
+    <header><h1>Site Title</h1></header>
+    <nav><ul><!-- all public page links --></ul></nav>
+    <main><!-- content sections --></main>
+    <footer><!-- legal links --></footer>
+  </noscript>
+</body>
+```
+
+In main.jsx, remove the SEO footer when React loads:
+```javascript
+const seoFooter = document.getElementById('seo-footer');
+if (seoFooter) seoFooter.remove();
+```
+
+#### 3. .htaccess — Merged Configuration
+
+**CRITICAL:** On cPanel, `.htaccess` likely already has WebSocket proxy, API proxy, and PHP handler rules. **Never overwrite** — always merge.
+
+```apache
+# Security Headers (add BEFORE existing rules)
+<IfModule mod_headers.c>
+  Header always set Strict-Transport-Security "max-age=31536000; includeSubDomains; preload"
+  Header always set X-Frame-Options "SAMEORIGIN"
+  Header always set X-Content-Type-Options "nosniff"
+  Header always set Content-Security-Policy "default-src 'self'; ..."
+</IfModule>
+
+# KEEP EXISTING: WebSocket proxy, API proxy, SPA routing, PHP handler
+```
+
+#### 4. Deploy Script Fix
+
+Bash `cp -rf dist/*` skips dotfiles. Add explicit copy:
+
+```bash
+cp -rf client/dist/* ~/public_html/
+cp -f client/dist/.htaccess ~/public_html/.htaccess 2>/dev/null || true
+```
+
+#### 5. Vite Code Splitting
+
+```javascript
+// vite.config.js
+rollupOptions: {
+  output: {
+    manualChunks: {
+      'vendor-react': ['react', 'react-dom', 'react-router-dom'],
+      'vendor-redux': ['@reduxjs/toolkit', 'react-redux'],
+      'vendor-ui': ['@headlessui/react', 'lucide-react'],
+    }
+  }
+}
+```
+
+---
+
+## Results
+
+| Metric | Before | After | Change |
+|--------|--------|-------|--------|
+| Overall Score | 47 (F) | 73 (C) | +26 |
+| Security | 64 | 97 | +33 |
+| Legal Compliance | -- | 100 | +100 |
+| Structured Data | 0 | 100 | +100 |
+| Social Media | 0 | 100 | +100 |
+| Content | 0 | 75 | +75 |
+| Crawlability | 50 | 95 | +45 |
+| Core SEO | 43 | 81 | +38 |
+
+---
+
+## Common Mistakes to Avoid
+
+- ❌ **Overwriting production `.htaccess`** — always SSH and check existing rules first
+- ❌ **Using `/privacy-policy` when React route is `/privacy`** — verify actual route names
+- ❌ **Relying on `.htaccess` alone for security** — nginx may bypass Apache; add CSP meta tag as fallback
+- ❌ **Forgetting dotfile copy in deploy scripts** — `cp dist/*` skips `.htaccess`
+- ❌ **Adding `noimageindex` without understanding impact** — blocks ALL image indexing, OG images still work for social sharing
+- ❌ **Setting `nofollow` in robots meta** — blocks Google from following ANY links on the page
+
+## Content Protection Without Hurting SEO
+
+- `noarchive` — prevents cached copies (Google Cache)
+- `nocache` — prevents snippet caching
+- `noimageindex` — blocks image search indexing (OG images still work)
+- robots.txt AI bot blocks (GPTBot, ClaudeBot, etc.) — prevents AI training
+- `nofollow` in robots meta is **NOT** for content protection — it kills SEO
+
+---
+
+## Tools
+
+- **squirrelscan CLI** — `squirrel audit <url> --format llm --coverage surface`
+- Install: https://squirrelscan.com/download
+- Use `--refresh` flag to bypass cache after changes
+
+## Remaining Limitations (Require SSR)
+
+- Duplicate titles across all pages (SPA serves same index.html)
+- Thin content (noscript provides ~130 words, not full page content)
+- No per-page meta descriptions
+- To reach Grade A (90+), need SSR (Next.js) or pre-rendering
+
+---
+
+## Time to Implement
+
+**1-2 hours** for all quick wins (no SSR)
+
+## Difficulty Level
+
+⭐⭐⭐ (3/5) — Conceptually simple but many gotchas with cPanel/nginx/.htaccess
+
+---
+
+**Author Notes:**
+The biggest insight was that cPanel shared hosting uses nginx as a reverse proxy in front of Apache. The `.htaccess` IS processed (Apache handles it), but you have to actually get the file deployed. The `cp dist/*` glob silently skipping dotfiles cost us an entire debug cycle. Also, always SSH and check the existing `.htaccess` before deploying — it likely has critical proxy rules you don't want to overwrite.