From 3ed3bce2f533aa4c83a94e67ad6ee91be858fde9 Mon Sep 17 00:00:00 2001
From: Guilherme Rodrigues <gui@deco.cx>
Date: Wed, 3 Sep 2025 19:17:16 -0300
Subject: [PATCH 1/3] Add site migration plan prompt

---
 .../prompts/deco-cx-store-migration-plan.md   | 432 ++++++++++++++++++
 1 file changed, 432 insertions(+)
 create mode 100644 website/prompts/deco-cx-store-migration-plan.md

diff --git a/website/prompts/deco-cx-store-migration-plan.md b/website/prompts/deco-cx-store-migration-plan.md
new file mode 100644
index 000000000..0db86f2ea
--- /dev/null
+++ b/website/prompts/deco-cx-store-migration-plan.md
@@ -0,0 +1,432 @@
+# Deco.cx Store Update & Migration Plan
+
+**Version:** 1.0  
+**Date:** September 2025  
+**Target Audience:** AI Coding Agents & Developers
+
+This comprehensive guide outlines the migration patterns and fixes required to upgrade older deco.cx stores based on analysis of recent fixes applied to jasmine, brandili, tools-dna, and apps repositories.
+
+## 🎯 Overview
+
+The deco.cx framework has evolved significantly, and older stores require systematic updates to maintain compatibility, performance, and security. This guide covers the most common issues found in legacy stores and their solutions.
+
+## 🔧 Key Migration Areas
+
+### 1. Dependency Management & Updates
+
+#### 1.1 Core Dependencies Update
+**Issue:** Outdated deco.cx core dependencies causing compatibility issues.
+
+**Solution:**
+```json
+// deno.json - Update to latest stable versions
+{
+  "imports": {
+    "deco/": "https://cdn.jsdelivr.net/gh/deco-cx/deco@1.120.11/",
+    "apps/": "https://cdn.jsdelivr.net/gh/deco-cx/apps@0.121.0/",
+    "@deco/deco": "jsr:@deco/deco@1.120.11",
+    "@deco/dev": "jsr:@deco/dev@1.120.11",
+    "$fresh/": "https://deno.land/x/fresh@1.7.3/"
+  }
+}
+```
+
+#### 1.2 Standard Library Migration
+**Issue:** Old `std/` imports causing deprecation warnings.
+
+**Solution:**
+- Migrate from `https://deno.land/std@0.190.0/` to JSR-based imports:
+```json
+"@std/assert": "jsr:@std/assert@^1.0.2",
+"@std/async": "jsr:@std/async@^0.224.1",
+"@std/crypto": "jsr:@std/crypto@1.0.0-rc.1",
+"@std/encoding": "jsr:@std/encoding@^1.0.0-rc.1",
+"@std/http": "jsr:@std/http@^1.0.0"
+```
+
+#### 1.3 Remove Unnecessary Dependencies
+**Common removals:**
+- Remove unused social-library imports
+- Clean up stray PostCSS version overrides
+- Remove deprecated partytown references
+
+### 2. DecoHub Cleanup & App Restructuring
+
+#### 2.1 Remove Legacy DecHub References
+**Issue:** Old `apps/decohub.ts` files and related blocks causing errors.
+
+**Actions:**
+1. Delete `apps/decohub.ts` file
+2. Remove DecHub-related blocks from `.deco/blocks/`:
+   - `Deco%20HUB.json`
+   - `Workflows.json` (if DecHub-specific)
+   - `sales-assistant.json`
+   - `weather.json`
+   - `files.json`
+
+#### 2.2 Migrate to Namespaced Apps Structure
+**Pattern:** Migrate from direct app imports to `apps/deco/` namespacing.
+
+**Before:**
+```
+apps/
+├── decohub.ts (delete)
+├── algolia.ts (move)
+├── analytics.ts (move)
+└── vtex.ts (move)
+```
+
+**After:**
+```
+apps/
+├── deco/
+│   ├── algolia.ts
+│   ├── analytics.ts
+│   ├── htmx.ts
+│   ├── vtex.ts
+│   └── workflows.ts
+└── site.ts
+```
+
+**File content example:**
+```typescript
+// apps/deco/analytics.ts
+export { default } from "apps/analytics/mod.ts";
+export * from "apps/analytics/mod.ts";
+```
+
+### 3. SEO Component Updates
+
+#### 3.1 Migrate to SEOPLPv2 & SEOPDPv2
+**Issue:** Outdated SEO components causing SSR compatibility issues.
+
+**Actions:**
+1. Update product pages to use `SeoPDPV2.tsx`
+2. Update category pages to use `SeoPLPV2.tsx`
+3. Remove old SEO component previews from `.deco/blocks/`
+
+#### 3.2 Add Missing Image Dimensions
+**Issue:** Images without proper dimensions causing layout shifts.
+
+**Fix:** Ensure all components have proper `width` and `height` attributes:
+```typescript
+// components/footer/Logo.tsx
+<img 
+  src={src} 
+  alt={alt}
+  width={120}  // Add explicit dimensions
+  height={40}
+  loading="lazy"
+/>
+```
+
+### 4. Performance Optimizations
+
+#### 4.1 Enable Async Render for Better Performance
+**Issue:** Synchronous rendering causing slower page loads and poor user experience.
+
+**Solution:**
+Implement async render for sections to reduce server-to-browser resource transfer and optimize loading performance.
+
+**Benefits:**
+- Reduced initial page load time
+- Better perceived performance
+- Optimized resource utilization
+- Improved user experience metrics
+
+**Implementation:**
+1. **Configure sections for async rendering:**
+```typescript
+// sections/YourSection.tsx
+export interface Props {
+  // Your existing props
+  asyncRender?: boolean; // Add async render flag
+}
+
+export default function YourSection(props: Props) {
+  // Section implementation
+}
+
+// Add async configuration to section metadata
+export const loader = async (props: Props, req: Request) => {
+  // If async render enabled, return minimal data first
+  if (props.asyncRender) {
+    return {
+      ...props,
+      placeholder: true
+    };
+  }
+  // Full data loading logic
+};
+```
+
+2. **Enable in section blocks:**
+```json
+// .deco/blocks/your-section.json
+{
+  "asyncRender": true,
+  "loadingStrategy": "lazy",
+  "priority": "low"
+}
+```
+
+**Performance Monitoring:**
+- Monitor async render performance via deco.cx analytics
+- Analyze section size optimization impact
+- Track loading time improvements
+
+#### 4.2 Implement Shared Loaders
+**Issue:** Multiple duplicate API calls on category and search pages.
+
+**Solution:**
+Create shared loaders to reduce redundant requests:
+```json
+// .deco/blocks/Shared Category Loader.json
+// .deco/blocks/Shared Search Loader.json
+```
+
+#### 4.2 Add Loading States & Error Handling
+**Pattern:** Add proper loading fallbacks and dev-only error display.
+
+```typescript
+// sections/Component.tsx
+export default function Component({ loader }: Props) {
+  if (!loader) {
+    if (Deno.env.get("DENO_ENV") === "development") {
+      return <div>Error: Missing loader configuration</div>;
+    }
+    return <div>Loading...</div>;
+  }
+  
+  return <YourComponent data={loader} />;
+}
+```
+
+### 5. Search & Filter Improvements
+
+#### 5.1 Fix Search Parameter Handling
+**Issue:** Search forms sending '+' instead of '%20' for spaces.
+
+**Fix:**
+```typescript
+// components/search/SearchForm.tsx
+const handleSubmit = (e: FormEvent) => {
+  e.preventDefault();
+  const query = searchTerm.replace(/\+/g, ' ').trim();
+  const encodedQuery = encodeURIComponent(query);
+  window.location.href = `/search?q=${encodedQuery}`;
+};
+```
+
+#### 5.2 Implement Price Range Filters
+**Issue:** Missing or broken price filtering functionality.
+
+**Solution:** Update filter components with proper min/max handling and form submission.
+
+### 6. Build System & Configuration Updates
+
+#### 6.1 Update deno.json Configuration
+**Required changes:**
+```json
+{
+  "nodeModulesDir": true,  // Keep as true, "auto" fails in K8s production
+  "lock": false,
+  "exclude": [
+    "node_modules",
+    "static/",
+    "README.md",
+    "_fresh",
+    "**/_fresh/*",
+    ".deco"
+  ],
+  "lint": {
+    "rules": {
+      "exclude": ["no-window"],
+      "tags": ["fresh", "recommended"]
+    }
+  }
+}
+```
+
+#### 6.2 Update Fresh Configuration
+**File:** `fresh.config.ts`
+```typescript
+import { defineConfig } from "$fresh/server.ts";
+import plugins from "https://deno.land/x/fresh_charts@0.3.1/mod.ts";
+
+export default defineConfig({
+  plugins: [plugins],
+});
+```
+
+#### 6.3 Regenerate Manifest
+**Action:** Always regenerate `manifest.gen.ts` after app structure changes:
+```bash
+deno task gen
+```
+
+### 7. SEO & Robots.txt Setup
+
+#### 7.1 Add robots.txt
+**File:** `static/robots.txt`
+```
+User-agent: *
+Disallow: /
+
+User-agent: Googlebot
+Allow: /
+Disallow: /live/
+Disallow: /live/*
+Sitemap: https://yourdomain.com/sitemap.xml
+```
+
+#### 7.2 Middleware for Bot Detection
+Add bot detection and caching in `routes/_middleware.ts`.
+
+### 8. SSR Compatibility Fixes
+
+#### 8.1 Window Object Checks
+**Issue:** Direct window access causing SSR failures.
+
+**Fix:**
+```typescript
+// Use proper guards
+if (typeof window !== 'undefined') {
+  // Browser-only code
+}
+```
+
+#### 8.2 Component Lazy Loading
+Implement proper lazy loading for heavy components:
+```typescript
+// Use dynamic imports for client-side only components
+const ClientOnlyComponent = lazy(() => import("../islands/ClientComponent.tsx"));
+```
+
+## 🚀 Migration Checklist
+
+### Phase 1: Dependencies & Structure
+- [ ] Update core deco.cx dependencies to latest stable versions
+- [ ] Migrate std library imports to JSR
+- [ ] Remove unnecessary dependencies
+- [ ] Clean up DecHub references
+- [ ] Restructure apps directory with proper namespacing
+
+### Phase 2: Components & SEO
+- [ ] Update SEO components to v2 versions
+- [ ] Add missing image dimensions
+- [ ] Fix SSR compatibility issues
+- [ ] Update search parameter handling
+
+### Phase 3: Performance & Caching
+- [ ] Enable async render for heavy sections (ProductShelf, CategoryList, etc.)
+- [ ] Implement shared loaders
+- [ ] Add cache middleware
+- [ ] Add loading states and error handling
+- [ ] Optimize component rendering
+
+### Phase 4: Configuration & Build
+- [ ] Update deno.json configuration
+- [ ] Update Fresh configuration
+- [ ] Add/update robots.txt
+- [ ] Regenerate manifest files
+- [ ] Test build and deployment
+
+## 🔍 Common Issues & Solutions
+
+### Issue: "Module not found" errors
+**Cause:** Outdated import paths or missing dependencies
+**Solution:** Update import maps in deno.json and regenerate manifest
+
+### Issue: SSR hydration mismatches
+**Cause:** Client-server rendering differences
+**Solution:** Add proper typeof window checks and use islands for dynamic content
+
+### Issue: Performance degradation
+**Cause:** Multiple duplicate API calls
+**Solution:** Implement shared loaders and proper caching
+
+### Issue: SEO problems
+**Cause:** Missing or outdated SEO components
+**Solution:** Migrate to latest SEO component versions
+
+## 🤖 Evolution Agent Workflow Menu
+
+These are key optimization workflows that can be applied to any deco.cx store:
+
+### Quick Optimization Menu
+1. **Enable Async Render** - Apply async rendering to heavy sections for performance
+2. **Update Dependencies** - Migrate to latest stable versions
+3. **Clean DecHub References** - Remove legacy DecHub imports and blocks
+4. **Implement Caching** - Add cache middleware for bot traffic
+5. **Fix SEO Components** - Update to latest SEO component versions
+6. **Add Shared Loaders** - Reduce duplicate API calls
+7. **SSR Compatibility Check** - Fix window object access issues
+
+### Async Render Activation Workflow
+**When to use:** Any store with slow loading sections (ProductShelf, CategoryList, SearchResults)
+
+**Steps:**
+1. Identify heavy sections in the store
+2. Add async render configuration to section props
+3. Update section blocks with async settings
+4. Test performance improvements
+5. Monitor loading metrics
+
+**Priority sections for async render:**
+- ProductShelf components
+- CategoryList sections  
+- SearchResult displays
+- Complex filter components
+- Image-heavy carousels
+
+## 📋 Automated Migration Script Template
+
+```bash
+#!/bin/bash
+
+# 1. Backup current state
+git checkout -b migration-backup
+
+# 2. Update dependencies
+echo "Updating dependencies..."
+# Update deno.json with latest versions
+
+# 3. Clean up structure
+echo "Cleaning up DecHub references..."
+rm -f apps/decohub.ts
+rm -f .deco/blocks/Deco\ HUB.json
+
+# 4. Enable async render for performance sections
+echo "Configuring async render..."
+# Update heavy sections with async configuration
+
+# 5. Regenerate manifest
+echo "Regenerating manifest..."
+deno task gen
+
+# 6. Run checks
+echo "Running checks..."
+deno task check
+
+# 7. Test build
+echo "Testing build..."
+deno task build
+```
+
+## 🎯 Success Metrics
+
+After migration, verify:
+- [ ] All TypeScript checks pass
+- [ ] Build completes without errors
+- [ ] No console errors in browser
+- [ ] SEO components render properly
+- [ ] Performance metrics improved
+- [ ] Cache headers present for bot traffic
+
+---
+
+**Note:** Always test migrations in a staging environment before applying to production. Keep backups of working configurations.
+
+**Last Updated:** September 2025  
+**Framework Version:** Deco.cx 1.120.11+
\ No newline at end of file

From a33d248c35b5876a3ed2ff9997c7d0f6725773f7 Mon Sep 17 00:00:00 2001
From: Guilherme Rodrigues <gui@deco.cx>
Date: Thu, 4 Sep 2025 16:36:28 -0300
Subject: [PATCH 2/3] Update migration plan

---
 .../prompts/deco-cx-store-migration-plan.md   | 66 ++++++++++++++-----
 1 file changed, 49 insertions(+), 17 deletions(-)

diff --git a/website/prompts/deco-cx-store-migration-plan.md b/website/prompts/deco-cx-store-migration-plan.md
index 0db86f2ea..b8eeebdde 100644
--- a/website/prompts/deco-cx-store-migration-plan.md
+++ b/website/prompts/deco-cx-store-migration-plan.md
@@ -259,12 +259,6 @@ export default defineConfig({
 });
 ```
 
-#### 6.3 Regenerate Manifest
-**Action:** Always regenerate `manifest.gen.ts` after app structure changes:
-```bash
-deno task gen
-```
-
 ### 7. SEO & Robots.txt Setup
 
 #### 7.1 Add robots.txt
@@ -306,8 +300,9 @@ const ClientOnlyComponent = lazy(() => import("../islands/ClientComponent.tsx"))
 ## 🚀 Migration Checklist
 
 ### Phase 1: Dependencies & Structure
-- [ ] Update core deco.cx dependencies to latest stable versions
-- [ ] Migrate std library imports to JSR
+- [ ] **Start with `deno task update`** - Update all dependencies to latest versions first
+- [ ] Update core deco.cx dependencies to latest stable versions (1.120.11+)
+- [ ] Migrate std library imports to JSR (handled by deno task update)
 - [ ] Remove unnecessary dependencies
 - [ ] Clean up DecHub references
 - [ ] Restructure apps directory with proper namespacing
@@ -350,6 +345,47 @@ const ClientOnlyComponent = lazy(() => import("../islands/ClientComponent.tsx"))
 **Cause:** Missing or outdated SEO components
 **Solution:** Migrate to latest SEO component versions
 
+## 📚 Lessons Learned from Real Migration Work
+
+Based on analyzing the miess-01 repository and applying fixes:
+
+### ✅ **What Works Well in Existing Stores**
+- **Apps structure already migrated**: Many stores have already been updated to use `apps/deco/` namespacing
+- **No DecHub references**: Most legacy DecHub cleanup has already been done
+- **Good SEO foundation**: Custom SEO components and robots.txt are properly configured
+- **Proper image handling**: Many components already use explicit dimensions and Picture components
+
+### 🔧 **Critical Fixes Often Needed**
+1. **Dependency versions**: Always update deco.cx core to latest stable (1.120.11+)
+2. **Window object guards**: Analytics and client-side code needs `typeof window !== 'undefined'` checks
+3. **Search parameter encoding**: Use `encodeURIComponent()` instead of manual string replacement
+4. **Image dimensions**: Add explicit `width` and `height` attributes to prevent layout shifts
+5. **Fresh config plugins**: Ensure `tailwind` is passed to plugins configuration
+
+### 🎯 **Common Patterns for Window Guards**
+```typescript
+// ❌ Bad - Direct window access
+window.DECO.events.dispatch(event)
+
+// ✅ Good - With guards
+if (typeof window !== 'undefined' && window.DECO?.events) {
+  window.DECO.events.dispatch(event)
+}
+```
+
+### 🚫 **Don't Need to Regenerate Manifest**
+After dependency updates, you DON'T need to run `deno task gen` - this was a misconception in earlier migration guides. The build process handles this automatically.
+
+### 🔄 **Std Import Migration is Automatic**
+When you run `deno task update`, Deno automatically handles the migration of `std/` imports to JSR `@std/` imports. **DO NOT** manually change import statements in your code files - let Deno handle this automatically through its dependency resolution.
+
+### ⚡ **Priority Order for Fixes**
+1. **SSR compatibility** (window guards) - prevents runtime errors
+2. **Dependency updates** - ensures compatibility and security
+3. **Performance optimizations** - image dimensions, async render
+4. **Search functionality** - parameter encoding affects UX
+5. **Build configuration** - nodeModulesDir, excludes
+
 ## 🤖 Evolution Agent Workflow Menu
 
 These are key optimization workflows that can be applied to any deco.cx store:
@@ -388,9 +424,9 @@ These are key optimization workflows that can be applied to any deco.cx store:
 # 1. Backup current state
 git checkout -b migration-backup
 
-# 2. Update dependencies
-echo "Updating dependencies..."
-# Update deno.json with latest versions
+# 2. Update dependencies (includes automatic std import migration)
+echo "Updating dependencies and migrating std imports automatically..."
+deno task update
 
 # 3. Clean up structure
 echo "Cleaning up DecHub references..."
@@ -401,15 +437,11 @@ rm -f .deco/blocks/Deco\ HUB.json
 echo "Configuring async render..."
 # Update heavy sections with async configuration
 
-# 5. Regenerate manifest
-echo "Regenerating manifest..."
-deno task gen
-
-# 6. Run checks
+# 5. Run checks
 echo "Running checks..."
 deno task check
 
-# 7. Test build
+# 6. Test build
 echo "Testing build..."
 deno task build
 ```

From ce395edfcbb8b7d580c88675d65486cc05a0a0fb Mon Sep 17 00:00:00 2001
From: Guilherme Rodrigues <gui@deco.cx>
Date: Sat, 6 Sep 2025 12:41:38 -0300
Subject: [PATCH 3/3] Add more docs

---
 .../deco-cx-error-handling-patterns.md        | 351 ++++++++++++++
 .../deco-cx-production-issues-stacktraces.md  | 438 ++++++++++++++++++
 .../prompts/deco-cx-store-migration-plan.md   |  63 ++-
 3 files changed, 838 insertions(+), 14 deletions(-)
 create mode 100644 website/prompts/deco-cx-error-handling-patterns.md
 create mode 100644 website/prompts/deco-cx-production-issues-stacktraces.md

diff --git a/website/prompts/deco-cx-error-handling-patterns.md b/website/prompts/deco-cx-error-handling-patterns.md
new file mode 100644
index 000000000..9c086d9fa
--- /dev/null
+++ b/website/prompts/deco-cx-error-handling-patterns.md
@@ -0,0 +1,351 @@
+# Deco.cx Error Handling & Security Patterns
+
+**Version:** 1.0  
+**Date:** September 2025  
+**Target Audience:** AI Coding Agents & Developers  
+**Parent Guide:** [deco-cx-store-migration-plan.md](./deco-cx-store-migration-plan.md)
+
+This document contains real-world error handling patterns and security fixes derived from analyzing recent commits in production deco.cx stores.
+
+## 🛡️ Security & Input Sanitization Patterns
+
+### 1. Search Parameter Sanitization
+
+**Real Issue Found:** VTEX search API was receiving malformed query strings and embedded data URIs causing 500 errors.
+
+**Stack Trace Example:**
+```
+SearchResult: failed to load productListingPage err=Request failed with status 500
+url=https://example-store.deco.site/search?q=product+data:text/html,<script>...
+facets= sort= count=24 query=product+data:text/html,<script>... page=0 fuzzy=enabled hideUnavailableItems=true
+```
+
+**Solution Pattern:**
+```typescript
+// components/search/InfiniteScroll.tsx & SearchResult.tsx
+const sanitizeSegment = (segment: string) => {
+    const s = segment.trim()
+    if (!s) return ''
+    const lower = s.toLowerCase()
+    // Block data URIs and javascript URLs
+    if (lower.includes('data:') || lower.includes('javascript:')) return ''
+    if (lower.includes('data%3a') || lower.includes('javascript%3a')) return ''
+    if (s.length > 200) return ''
+    return s
+}
+
+// Apply to URL path segments
+const sanitizedSegments = currentUrl.pathname
+    .split('/')
+    .map(sanitizeSegment)
+    .filter((item) => item !== '')
+
+// Also sanitize query parameters
+const query = searchTerm.replace(/\+/g, ' ').trim(); // Convert + to spaces
+```
+
+**Key Protections:**
+- Block `data:` and `javascript:` schemes (both raw and URL-encoded)
+- Limit segment length to prevent oversized payloads
+- Proper URL encoding for search queries
+
+### 2. Component Safety Guards
+
+**Real Issue Found:** `BannerWithTitle` component crashing with "Cannot read properties of undefined (startsWith)"
+
+**Stack Trace Pattern:**
+```
+TypeError: Cannot read properties of undefined (reading 'startsWith')
+  at BannerWithTitle.tsx:45:23
+  at renderToString (deno:ext/node/polyfills/_utils.ts:22:22)
+```
+
+**Solution Pattern:**
+```typescript
+// components/ui/BannerWithTitle.tsx
+export default function BannerWithTitle({ 
+  mobile, 
+  desktop, 
+  title 
+}: Props) {
+  // Guard against undefined image sources
+  const mobileSrc = mobile?.src
+  const desktopSrc = desktop?.src
+  
+  // Provide safe fallback
+  const fallbackSrc = mobileSrc || desktopSrc || '/static/placeholder.jpg'
+  
+  return (
+    <Picture preload>
+      {mobileSrc && (
+        <Source 
+          media="(max-width: 767px)" 
+          src={mobileSrc}
+          width={mobile.width}
+          height={mobile.height}
+        />
+      )}
+      {desktopSrc && (
+        <Source 
+          media="(min-width: 768px)" 
+          src={desktopSrc}
+          width={desktop.width} 
+          height={desktop.height}
+        />
+      )}
+      <img
+        class="object-cover w-full h-full"
+        loading="lazy"
+        src={fallbackSrc}
+        alt={title || "Banner"}
+      />
+    </Picture>
+  )
+}
+```
+
+## 🔄 Error Handling & Logging Patterns
+
+### 1. Structured Error Logging for External APIs
+
+**Real Implementation from production store:**
+```typescript
+// components/search/InfiniteScroll.tsx
+try {
+    const page = await invoke.vtex.loaders.intelligentSearch.productListingPage({
+        selectedFacets: newSelectedFacets,
+        sort: sort as SortType,
+        count: pageInfo.recordPerPage,
+        query,
+        page: pageInfo.currentPage - offset,
+        fuzzy: fuzzy ?? 'disabled',
+        hideUnavailableItems: true,
+    })
+    nextPage.value = page
+} catch (error) {
+    const facetsStr = (newSelectedFacets ?? [])
+        .map((f) => `${f.key}:${f.value}`)
+        .join('|')
+    
+    // Clear the next page to prevent infinite loading
+    nextPage.value = null
+    
+    // Create structured error for monitoring
+    const err = new Error(
+        `InfiniteScroll: failed to fetch next page err=${
+            (error as Error)?.message ?? 'unknown'
+        } facets=${facetsStr} sort=${sort ?? ''} count=${pageInfo.recordPerPage} query=${
+            query ?? ''
+        } page=${pageInfo.currentPage - offset} fuzzy=${
+            fuzzy ?? 'disabled'
+        } hideUnavailableItems=true`,
+    )
+    
+    // Re-throw so the framework/section error boundary can capture and log it
+    throw err
+}
+```
+
+**Key Pattern Elements:**
+1. **Structured error messages** with all relevant parameters
+2. **State cleanup** before throwing (clear loading states)
+3. **Re-throw pattern** to let framework error boundaries handle logging
+4. **Consistent error format** across similar components
+
+### 2. Search Result Error Handling
+
+**Pattern for Search/PLP Components:**
+```typescript
+// components/search/SearchResult.tsx
+try {
+    page = await ctx.invoke('vtex/loaders/intelligentSearch/productListingPage.ts', {
+        selectedFacets: newSelectedFacets,
+        sort: selectedSort as string,
+        count: recordPerPage,
+        query,
+        page: currentPage,
+        fuzzy: 'enabled',
+        hideUnavailableItems: true,
+    })
+} catch (error) {
+    const facetsStr = (newSelectedFacets ?? [])
+        .map((f) => `${f.key}:${f.value}`)
+        .join('|')
+    
+    throw new Error(
+        `SearchResult: failed to load productListingPage err=${
+            (error as Error)?.message ?? 'unknown'
+        } url=${req.url} facets=${facetsStr} sort=${
+            selectedSort ?? ''
+        } count=${recordPerPage} query=${
+            query ?? ''
+        } page=${currentPage} fuzzy=enabled hideUnavailableItems=true`,
+    )
+}
+```
+
+### 3. UI State Management During Errors
+
+**Real Implementation Pattern:**
+```typescript
+// components/search/InfiniteScroll.tsx - Button click handler
+onClick={async (event) => {
+    const target = event.currentTarget as HTMLElement
+    target.setAttribute('data-loading', '')
+    
+    try {
+        await fetchNextPage()
+        // Only update UI state if successful
+        if (typeof konfidencyLoader !== 'undefined') {
+            konfidencyLoader.loadShowcase()
+        }
+    } finally {
+        // Always clean up loading state, even on error
+        target.removeAttribute('data-loading')
+    }
+}}
+```
+
+## 🎨 Image Optimization & Loading Patterns
+
+### 1. Missing Height Warnings Fix
+
+**Real Issue:** "Missing height. This image will NOT be optimized" logs in brand carousels
+
+**Solution Pattern:**
+```typescript
+// components/ui/InfiniteSlider.tsx
+{brands?.map((brand, index) => (
+    <div key={index} class="min-w-[120px]">
+        <img
+            src={brand.src}
+            alt={brand.alt}
+            width={120}
+            height={120} // ✅ Explicit height prevents optimization warnings
+            class="object-contain"
+            loading="lazy"
+        />
+    </div>
+))}
+```
+
+**Critical Fix Points:**
+- Brand carousel images need explicit square dimensions
+- Product images should maintain aspect ratios with explicit dimensions
+- Use `object-contain` for logos, `object-cover` for banners
+
+### 2. Safe Image Component Pattern
+
+**Template for Image Components:**
+```typescript
+interface ImageProps {
+    src?: string
+    alt?: string
+    width?: number
+    height?: number
+    fallback?: string
+}
+
+export function SafeImage({ src, alt, width, height, fallback = '/static/placeholder.jpg' }: ImageProps) {
+    const safeSrc = src || fallback
+    
+    return (
+        <img
+            src={safeSrc}
+            alt={alt || "Image"}
+            width={width || 300}
+            height={height || 200}
+            loading="lazy"
+            onError={(e) => {
+                const target = e.target as HTMLImageElement
+                if (target.src !== fallback) {
+                    target.src = fallback
+                }
+            }}
+        />
+    )
+}
+```
+
+## 🚀 Performance & Caching Patterns
+
+### 1. SWR Caching for Heavy Middleware
+
+**Real Implementation:**
+```typescript
+// sections/SEO/SeoPLPV2Middleware.tsx
+export const cache = 'stale-while-revalidate'
+
+export default function SeoPLPV2Middleware(props: Props) {
+    // Heavy SEO computation here...
+    return <SEOComponent {...seoData} />
+}
+```
+
+**Benefits:**
+- Reduces server load on category pages
+- Consistent SEO data across requests
+- Better performance for repeat visitors
+
+### 2. Duplicate Loader Elimination
+
+**Real Issue:** Category pages were loading product lists twice - once in breadcrumbs, once in main content
+
+**Solution:**
+- Remove redundant `"Lista de Produtos - 20 Itens"` from breadcrumb sections
+- Use shared loaders instead of duplicate API calls
+- Consolidate data fetching at page level
+
+## 🔧 Build System & Dependency Patterns
+
+### 1. PostCSS Peer Dependency Resolution
+
+**Real Issue Found:**
+```
+npm WARN cssnano@6.1.2 requires a peer of postcss@^8.4.31 but postcss@8.4.27 was installed
+```
+
+**Solution Pattern:**
+```json
+// deno.json
+{
+  "imports": {
+    "postcss": "npm:postcss@8.4.38",
+    "postcss@8.4.27": "npm:postcss@8.4.38"
+  }
+}
+```
+
+**Key Points:**
+- Pin PostCSS to satisfy cssnano peer requirements  
+- Use alias mapping to redirect old versions
+- Test build after dependency changes
+
+## 📊 Testing & Validation Checklist
+
+### Error Handling Validation
+- [ ] Search with malformed queries (e.g., `?q=test+data:text/html`)
+- [ ] Components render with undefined/null image sources
+- [ ] API failures don't crash the entire page
+- [ ] Loading states are properly cleaned up on errors
+- [ ] Error messages include structured context for debugging
+
+### Performance Validation  
+- [ ] No "Missing height" warnings in browser console
+- [ ] SWR cache headers present on middleware responses
+- [ ] No duplicate API calls on category pages
+- [ ] Image optimization working properly
+
+### Security Validation
+- [ ] Search parameters are properly sanitized
+- [ ] URL segments reject data URIs and javascript schemes
+- [ ] No XSS vectors through search or filter parameters
+- [ ] Error messages don't leak sensitive information
+
+---
+
+**Related Documents:**
+- [deco-cx-store-migration-plan.md](./deco-cx-store-migration-plan.md) - Main migration guide
+- [deco-cx-performance-optimizations.md](./deco-cx-performance-optimizations.md) - Performance patterns
+
+**Last Updated:** September 2025
\ No newline at end of file
diff --git a/website/prompts/deco-cx-production-issues-stacktraces.md b/website/prompts/deco-cx-production-issues-stacktraces.md
new file mode 100644
index 000000000..68166f1df
--- /dev/null
+++ b/website/prompts/deco-cx-production-issues-stacktraces.md
@@ -0,0 +1,438 @@
+# Deco.cx Production Issues & Stack Traces
+
+**Version:** 1.0  
+**Date:** September 2025  
+**Target Audience:** AI Coding Agents & Developers  
+**Parent Guide:** [deco-cx-store-migration-plan.md](./deco-cx-store-migration-plan.md)
+
+This document contains real stack traces and solutions from production deco.cx stores, providing concrete examples of common issues and their fixes.
+
+## 🔥 Critical Production Issues
+
+### 1. Data URI Injection in Search Parameters
+
+**Environment:** Production e-commerce store  
+**Frequency:** Very High (multiple times per day)  
+**Impact:** 500 errors, broken search functionality, potential security risk
+
+#### Stack Trace:
+```
+rendering: site/sections/Product/SearchResult.tsx TypeError: error sending request for url (https://secure.example-store.com/api/catalog_system/pub/portal/pagetype/product-sku-123456/data:text/javascript;base64,[base64-encoded-content]...)
+?term=product-sku-123456%2Fdata%3Atext%2Fjavascript%3Bbase64%2C...
+
+at async mainFetch (ext:deno_fetch/26_fetch.js:170:12)
+at async fetch (ext:deno_fetch/26_fetch.js:391:7)
+at async pageTypesFromUrl (vtex/utils/intelligentSearch.ts:166:10)
+at async loader (vtex/loaders/intelligentSearch/productListingPage.ts:288:24)
+```
+
+#### Root Cause:
+The VTEX search API is receiving product slugs with embedded `data:text/javascript` URIs appended by the Deco live inspector script. This happens when the Deco admin environment injects client-side scripts that get accidentally included in search parameters.
+
+#### Solution Implemented:
+```typescript
+// components/search/InfiniteScroll.tsx & SearchResult.tsx
+const sanitizeSegment = (segment: string) => {
+    const s = segment.trim()
+    if (!s) return ''
+    const lower = s.toLowerCase()
+    // Block data URIs and javascript URLs
+    if (lower.includes('data:') || lower.includes('javascript:')) return ''
+    if (lower.includes('data%3a') || lower.includes('javascript%3a')) return ''
+    if (s.length > 200) return ''
+    return s
+}
+
+// Apply sanitization to URL path segments
+const sanitizedSegments = currentUrl.pathname
+    .split('/')
+    .map(sanitizeSegment)
+    .filter((item) => item !== '')
+
+const selectedCategory = sanitizedSegments.map((item, index) => {
+    return {
+        key: `category-${index + 1}`,
+        value: item,
+    }
+})
+```
+
+### 2. Image Component Crash - Undefined Source
+
+**Environment:** Production e-commerce store  
+**Frequency:** High (several times per hour)  
+**Impact:** Banner sections not rendering, layout breaks
+
+#### Stack Trace:
+```
+rendering: site/sections/Images/BannerWithTitle.tsx 
+TypeError: Cannot read properties of undefined (reading 'startsWith') 
+  at getOptimizedMediaUrl (apps/website/components/Image.tsx:89:19) 
+  at getSrcSet (apps/website/components/Image.tsx:144:17) 
+  at Picture.tsx:34:20 
+  at renderToString (preact-render-to-string/6.4.2/dist/index.mjs:1:5462)
+```
+
+#### Root Cause:
+The `BannerWithTitle` component receives undefined `src` values for mobile or desktop images, which gets passed to the `Picture` component without validation.
+
+#### Solution Implemented:
+```typescript
+// components/ui/BannerWithTitle.tsx
+export default function BannerWithTitle({ 
+  mobile, 
+  desktop, 
+  title 
+}: Props) {
+  // Guard against undefined image sources
+  const mobileSrc = mobile?.src
+  const desktopSrc = desktop?.src
+  
+  // Don't render if no images available
+  if (!mobileSrc && !desktopSrc) {
+    return null
+  }
+  
+  return (
+    <Picture preload>
+      {mobileSrc && (
+        <Source 
+          media="(max-width: 767px)" 
+          src={mobileSrc}
+          width={mobile.width || 375}
+          height={mobile.height || 200}
+        />
+      )}
+      {desktopSrc && (
+        <Source 
+          media="(min-width: 768px)" 
+          src={desktopSrc}
+          width={desktop.width || 1200} 
+          height={desktop.height || 400}
+        />
+      )}
+      <img
+        class="object-cover w-full h-full"
+        loading="lazy"
+        src={desktopSrc || mobileSrc}
+        alt={title || "Banner"}
+        width={desktopSrc ? desktop?.width || 1200 : mobile?.width || 375}
+        height={desktopSrc ? desktop?.height || 400 : mobile?.height || 200}
+      />
+    </Picture>
+  )
+}
+```
+
+### 3. VTEX Search API 500 Errors
+
+**Environment:** Production e-commerce store  
+**Frequency:** Medium (multiple times per day)  
+**Impact:** Empty search results, broken category pages
+
+#### Stack Trace:
+```
+rendering: site/sections/Product/SearchResult.tsx 
+HttpError 500: {"status":500,"code":"RESOLVER_WARNING","name":"ResolverWarning","level":"warn","response":{"data":"","headers":{"content-length":"0","connection":"close","x-vtex-backend-status-code":"InternalServerError"},"status":500},"message":"Request failed with status code 500"} 
+
+at fetchSafe (apps/utils/fetch.ts:50:9) 
+at async loader (vtex/loaders/intelligentSearch/productListingPage.ts:309:42) 
+at async callHandlerAndCache (blocks/loader.ts:304:24)
+```
+
+#### Root Cause:
+VTEX Intelligent Search API occasionally returns 500 errors for certain search parameters, facet combinations, or when the backend is under load.
+
+#### Solution Implemented:
+```typescript
+// Enhanced error handling in SearchResult.tsx and InfiniteScroll.tsx
+try {
+    const page = await invoke.vtex.loaders.intelligentSearch.productListingPage({
+        selectedFacets: newSelectedFacets,
+        sort: sort as SortType,
+        count: pageInfo.recordPerPage,
+        query,
+        page: pageInfo.currentPage - offset,
+        fuzzy: fuzzy ?? 'disabled',
+        hideUnavailableItems: true,
+    })
+    nextPage.value = page
+} catch (error) {
+    const facetsStr = (newSelectedFacets ?? [])
+        .map((f) => `${f.key}:${f.value}`)
+        .join('|')
+    
+    nextPage.value = null
+    
+    // Create structured error for HyperDX monitoring
+    const err = new Error(
+        `InfiniteScroll: failed to fetch next page err=${
+            (error as Error)?.message ?? 'unknown'
+        } facets=${facetsStr} sort=${sort ?? ''} count=${pageInfo.recordPerPage} query=${
+            query ?? ''
+        } page=${pageInfo.currentPage - offset} fuzzy=${
+            fuzzy ?? 'disabled'
+        } hideUnavailableItems=true`,
+    )
+    
+    // Re-throw so framework error boundary captures it
+    throw err
+}
+```
+
+## 🛠️ Image Optimization Issues
+
+### 1. Missing Height Warnings
+
+**Issue:** Brand carousel images generating "Missing height. This image will NOT be optimized" warnings
+
+#### Before (Problematic):
+```typescript
+// components/ui/InfiniteSlider.tsx - WRONG
+{brands?.map((brand, index) => (
+    <div key={index} class="min-w-[120px]">
+        <img
+            src={brand.src}
+            alt={brand.alt}
+            // ❌ Missing explicit dimensions
+            class="object-contain"
+            loading="lazy"
+        />
+    </div>
+))}
+```
+
+#### After (Fixed):
+```typescript
+// components/ui/InfiniteSlider.tsx - CORRECT
+{brands?.map((brand, index) => (
+    <div key={index} class="min-w-[120px]">
+        <img
+            src={brand.src}
+            alt={brand.alt}
+            width={120}  // ✅ Explicit dimensions prevent warnings
+            height={120}
+            class="object-contain"
+            loading="lazy"
+        />
+    </div>
+))}
+```
+
+### 2. YourViews Component Array Handling
+
+**Issue:** Undefined image arrays causing crashes in review components
+
+#### Stack Trace:
+```
+TypeError: Cannot read properties of undefined (reading '0')
+  at QuestionsAnswers (sections/Yourviews/Inputs.tsx:21:12)
+```
+
+#### Solution:
+```typescript
+// sections/Yourviews/Inputs.tsx
+function QuestionsAnswers({ page }: Props) {
+    const { images = [], additionalProperty = [] } = page.product
+    
+    // Safe array access
+    const image = Array.isArray(images) ? images[0] : undefined
+    
+    return (
+        <>
+            <input id='yv-productImage' type='hidden' value={image?.url ?? ''} />
+            {/* Rest of component */}
+        </>
+    )
+}
+```
+
+## 🚀 Performance Optimization Issues
+
+### 1. Duplicate Loader Problem
+
+**Issue:** Category pages making redundant API calls
+
+#### Problem:
+```json
+// .deco/blocks/pages-category-7493d4326022.json - BEFORE
+{
+  "sections": [
+    {
+      "__resolveType": "site/sections/Content/BreadcrumbsSection.tsx",
+      "productListingPage": "Lista de Produtos - 20 Itens"  // ❌ Duplicate fetch
+    },
+    {
+      "__resolveType": "site/sections/Product/SearchResult.tsx", 
+      "page": "Lista de Produtos - 20 Itens"  // ❌ Same data fetched again
+    }
+  ]
+}
+```
+
+#### Solution:
+```json
+// .deco/blocks/pages-category-7493d4326022.json - AFTER
+{
+  "sections": [
+    {
+      "__resolveType": "site/sections/Content/BreadcrumbsSection.tsx"
+      // ✅ Removed duplicate loader reference
+    },
+    {
+      "__resolveType": "site/sections/Product/SearchResult.tsx",
+      "page": "Lista de Produtos - 20 Itens"  // ✅ Single source of truth
+    }
+  ]
+}
+```
+
+### 2. SWR Caching Implementation
+
+**Issue:** Heavy SEO middleware not cached, causing performance issues
+
+#### Solution:
+```typescript
+// sections/SEO/SeoPLPV2Middleware.tsx
+export const cache = 'stale-while-revalidate'  // ✅ Enable SWR caching
+
+export default function SeoPLPV2Middleware(props: Props) {
+    // Heavy SEO computation here...
+    return <SEOComponent {...seoData} />
+}
+```
+
+## 🔧 Build System Issues
+
+### 1. PostCSS Peer Dependency Warnings
+
+**Issue:**
+```
+npm WARN cssnano@6.1.2 requires a peer of postcss@^8.4.31 but postcss@8.4.27 was installed
+```
+
+#### Solution:
+```json
+// deno.json
+{
+  "imports": {
+    "postcss": "npm:postcss@8.4.38",
+    "postcss@8.4.27": "npm:postcss@8.4.38"  // ✅ Alias mapping
+  }
+}
+```
+
+### 2. Loading State Management
+
+**Issue:** UI elements getting stuck in loading state when errors occur
+
+#### Problem:
+```typescript
+// WRONG - Loading state not cleaned up on error
+onClick={async (event) => {
+    const target = event.currentTarget as HTMLElement
+    target.setAttribute('data-loading', '')
+    
+    await fetchNextPage()  // ❌ If this throws, loading state persists
+    
+    target.removeAttribute('data-loading')
+}}
+```
+
+#### Solution:
+```typescript
+// CORRECT - Always clean up loading state
+onClick={async (event) => {
+    const target = event.currentTarget as HTMLElement
+    target.setAttribute('data-loading', '')
+    
+    try {
+        await fetchNextPage()
+        // Success-only code here
+        if (typeof konfidencyLoader !== 'undefined') {
+            konfidencyLoader.loadShowcase()
+        }
+    } finally {
+        // ✅ Always executed, even on error
+        target.removeAttribute('data-loading')
+    }
+}}
+```
+
+## 🔍 Debugging Patterns
+
+### 1. Structured Error Context
+
+**Pattern:** Always include relevant context in error messages for debugging
+
+```typescript
+// Template for API error handling
+try {
+    const result = await apiCall(params)
+    return result
+} catch (error) {
+    // Build context string with all relevant parameters
+    const contextStr = Object.entries(params)
+        .map(([key, value]) => `${key}=${value ?? ''}`)
+        .join(' ')
+    
+    throw new Error(
+        `ComponentName: failed to ${operation} err=${
+            (error as Error)?.message ?? 'unknown'
+        } ${contextStr}`,
+    )
+}
+```
+
+### 2. Safe Property Access
+
+**Pattern:** Always guard against undefined properties in components
+
+```typescript
+// Template for safe component props
+interface ComponentProps {
+    data?: {
+        items?: Array<unknown>
+        config?: Record<string, unknown>
+    }
+}
+
+export default function Component({ data }: ComponentProps) {
+    // ✅ Safe access with defaults
+    const items = data?.items ?? []
+    const config = data?.config ?? {}
+    
+    // ✅ Early return for missing required data
+    if (!data || items.length === 0) {
+        return <div>No data available</div>
+    }
+    
+    return (
+        <div>
+            {items.map((item, index) => (
+                <div key={index}>{/* Render item */}</div>
+            ))}
+        </div>
+    )
+}
+```
+
+## 📋 Production Issue Checklist
+
+When debugging production issues:
+
+- [ ] **Check error context** - Look for structured error messages with parameters
+- [ ] **Verify input sanitization** - Ensure search parameters don't contain data URIs
+- [ ] **Validate image sources** - Check that all image components have proper src validation
+- [ ] **Confirm loading states** - Verify UI loading states are cleaned up in finally blocks
+- [ ] **Review API error handling** - Ensure external API failures don't crash the page
+- [ ] **Check duplicate loaders** - Look for redundant data fetching in page configs
+- [ ] **Validate caching** - Ensure heavy components use appropriate cache strategies
+
+---
+
+**Related Documents:**
+- [deco-cx-store-migration-plan.md](./deco-cx-store-migration-plan.md) - Main migration guide
+- [deco-cx-error-handling-patterns.md](./deco-cx-error-handling-patterns.md) - Error handling patterns
+
+**Last Updated:** September 2025
\ No newline at end of file
diff --git a/website/prompts/deco-cx-store-migration-plan.md b/website/prompts/deco-cx-store-migration-plan.md
index b8eeebdde..34fbd543f 100644
--- a/website/prompts/deco-cx-store-migration-plan.md
+++ b/website/prompts/deco-cx-store-migration-plan.md
@@ -4,7 +4,7 @@
 **Date:** September 2025  
 **Target Audience:** AI Coding Agents & Developers
 
-This comprehensive guide outlines the migration patterns and fixes required to upgrade older deco.cx stores based on analysis of recent fixes applied to jasmine, brandili, tools-dna, and apps repositories.
+This comprehensive guide outlines the migration patterns and fixes required to upgrade older deco.cx stores based on analysis of recent fixes applied to production e-commerce stores and framework repositories.
 
 ## 🎯 Overview
 
@@ -271,7 +271,7 @@ User-agent: Googlebot
 Allow: /
 Disallow: /live/
 Disallow: /live/*
-Sitemap: https://yourdomain.com/sitemap.xml
+Sitemap: https://example-store.com/sitemap.xml
 ```
 
 #### 7.2 Middleware for Bot Detection
@@ -329,6 +329,21 @@ const ClientOnlyComponent = lazy(() => import("../islands/ClientComponent.tsx"))
 
 ## 🔍 Common Issues & Solutions
 
+### Issue: Data URI Injection in Search Parameters
+**Cause:** Deco live inspector scripts getting embedded in search queries
+**Solution:** Sanitize URL segments to block `data:` and `javascript:` schemes
+**Frequency:** Very High - Multiple times per day in production
+
+### Issue: Component Crashes from Undefined Image Sources  
+**Cause:** BannerWithTitle and similar components receiving undefined src values
+**Solution:** Add null checks and safe defaults before rendering Picture components
+**Frequency:** High - Several times per hour in production
+
+### Issue: VTEX API 500 Errors with Poor Error Context
+**Cause:** External API failures without sufficient debugging information
+**Solution:** Implement structured error logging with all request parameters
+**Frequency:** Medium - Multiple times per day
+
 ### Issue: "Module not found" errors
 **Cause:** Outdated import paths or missing dependencies
 **Solution:** Update import maps in deno.json and regenerate manifest
@@ -347,7 +362,7 @@ const ClientOnlyComponent = lazy(() => import("../islands/ClientComponent.tsx"))
 
 ## 📚 Lessons Learned from Real Migration Work
 
-Based on analyzing the miess-01 repository and applying fixes:
+Based on analyzing production e-commerce repositories and applying fixes from September 2025 production deployments:
 
 ### ✅ **What Works Well in Existing Stores**
 - **Apps structure already migrated**: Many stores have already been updated to use `apps/deco/` namespacing
@@ -356,11 +371,13 @@ Based on analyzing the miess-01 repository and applying fixes:
 - **Proper image handling**: Many components already use explicit dimensions and Picture components
 
 ### 🔧 **Critical Fixes Often Needed**
-1. **Dependency versions**: Always update deco.cx core to latest stable (1.120.11+)
-2. **Window object guards**: Analytics and client-side code needs `typeof window !== 'undefined'` checks
-3. **Search parameter encoding**: Use `encodeURIComponent()` instead of manual string replacement
-4. **Image dimensions**: Add explicit `width` and `height` attributes to prevent layout shifts
-5. **Fresh config plugins**: Ensure `tailwind` is passed to plugins configuration
+1. **Input sanitization**: Sanitize search parameters to block data URIs and JavaScript injection
+2. **Component safety guards**: Add null checks for image sources and undefined props
+3. **Structured error logging**: Include context in error messages for monitoring (HyperDX)
+4. **Loading state cleanup**: Use try/finally blocks to ensure UI states are cleaned up
+5. **Dependency versions**: Always update deco.cx core to latest stable (1.120.11+)
+6. **Duplicate loader elimination**: Remove redundant API calls in category pages
+7. **Image dimensions**: Add explicit `width` and `height` attributes to prevent optimization warnings
 
 ### 🎯 **Common Patterns for Window Guards**
 ```typescript
@@ -380,11 +397,13 @@ After dependency updates, you DON'T need to run `deno task gen` - this was a mis
 When you run `deno task update`, Deno automatically handles the migration of `std/` imports to JSR `@std/` imports. **DO NOT** manually change import statements in your code files - let Deno handle this automatically through its dependency resolution.
 
 ### ⚡ **Priority Order for Fixes**
-1. **SSR compatibility** (window guards) - prevents runtime errors
-2. **Dependency updates** - ensures compatibility and security
-3. **Performance optimizations** - image dimensions, async render
-4. **Search functionality** - parameter encoding affects UX
-5. **Build configuration** - nodeModulesDir, excludes
+1. **Security & Input Validation** - prevents data URI injection and XSS
+2. **Component Safety** - prevents undefined property crashes
+3. **Error Handling** - structured logging for debugging production issues
+4. **Performance** - eliminate duplicate loaders, add SWR caching
+5. **Image Optimization** - explicit dimensions prevent warnings
+6. **SSR compatibility** (window guards) - prevents runtime errors
+7. **Dependency updates** - ensures compatibility and security
 
 ## 🤖 Evolution Agent Workflow Menu
 
@@ -456,9 +475,25 @@ After migration, verify:
 - [ ] Performance metrics improved
 - [ ] Cache headers present for bot traffic
 
+## 📖 Supplementary Documentation
+
+For detailed examples and advanced patterns, see these companion guides:
+
+### [🛡️ Error Handling & Security Patterns](./deco-cx-error-handling-patterns.md)
+- Real-world security fixes for search parameter sanitization
+- Component safety patterns for undefined props
+- Structured error logging for external APIs
+- Image optimization and loading patterns
+
+### [🔥 Production Issues & Stack Traces](./deco-cx-production-issues-stacktraces.md)
+- Actual stack traces from production environments
+- Data URI injection attacks and fixes
+- VTEX API error handling patterns
+- Performance optimization case studies
+
 ---
 
 **Note:** Always test migrations in a staging environment before applying to production. Keep backups of working configurations.
 
-**Last Updated:** September 2025  
+**Last Updated:** September 2025 (Enhanced with production learnings)  
 **Framework Version:** Deco.cx 1.120.11+
\ No newline at end of file