@shaykec/app-agent 1.0.8 → 1.0.10

package/.cursor/skills/exploratory-tester/SKILL.md

@@ -0,0 +1,223 @@
+---
+name: exploratory-tester
+description: Screenshot and accessibility-tree driven exploratory testing. Does NOT read source code — tests the app purely through what the AI sees on screen and what the accessibility tree reveals. Discovers visual bugs, accessibility issues, UX problems, and content issues that structured testing misses.
+---
+
+# Exploratory Tester Skill
+
+Use this skill to test the app by exploring it visually — using screenshots and the accessibility/element tree as your only inputs. You do NOT read source code. You test what a real user would see and interact with.
+
+## When to Use
+
+- As Phase 2 of the `--deep-test` pipeline
+- Runs in parallel with structured testing (Phase 3) on a separate simulator
+- After the app is built and installed on a simulator
+
+## Context You Need
+
+- **Platform** — `ios`, `android`, or `react-native`
+- **Bundle ID / Package name** — e.g., `com.pawspa.app`
+- **Simulator/device name** — the `deviceName` for your assigned simulator
+- **App directory** — path under `output/` (only for writing the bug report, NOT for reading code)
+
+**IMPORTANT:** You must NOT read source code files (Views, ViewModels, Models, etc.). Your only inputs are what `inspect()` gives you — screenshots and the element tree. This forces you to test like a real user.
+
+## Instructions
+
+### Phase A — Screen Discovery
+
+Start by launching the app and discovering all reachable screens:
+
+1. **Launch the app:**
+   ```
+   inspect({ platform: "{platform}", app: "{bundleId}", deviceName: "{sim}" })
+   ```
+
+2. **Wait 3-5 seconds** for the app to fully render, then `inspect()` again.
+
+3. **Map the tab bar** — identify all tabs from the element tree. Record their labels.
+
+4. **Visit each tab** — tap each tab, `inspect()` on each to capture the screen and element tree.
+
+5. **Discover sub-screens** — from each tab, tap list items, buttons, and links to discover detail screens, modals, forms. Keep a visited-screens list to avoid loops.
+
+6. **Build a screen map:**
+   ```
+   Tab 1 ("Home") → HomeScreen → DetailScreen (from list item)
+   Tab 2 ("Explore") → ExploreScreen → DetailScreen (from search result)
+   Tab 3 ("Favorites") → FavoritesScreen
+   Tab 4 ("Profile") → ProfileScreen → SettingsScreen
+   ```
+
+### Phase B — Per-Screen Exploratory Audit
+
+For **each discovered screen**, perform the following audit:
+
+#### B1 — Visual Analysis (from screenshot)
+
+After each `inspect()`, analyze what you see:
+
+- **Layout correctness:**
+  - No overlapping text or elements
+  - No cut-off labels or truncated content that loses meaning
+  - Proper spacing between elements (not cramped, not too sparse)
+  - Content aligned correctly (left-aligned text, centered headers, etc.)
+  - No elements extending beyond screen bounds
+
+- **Content quality:**
+  - Real domain-specific text (not "Lorem ipsum", "Item 1", "Product", "Template")
+  - Images appear to be loaded (no broken image placeholders, no empty squares)
+  - Icons match their context (not generic or mismatched)
+  - Consistent typography across the screen
+
+- **Design consistency:**
+  - Colors match between elements on the same screen
+  - Typography hierarchy makes sense (headers larger than body text)
+  - Consistent spacing and padding across similar elements
+  - Navigation bar style is consistent across screens
+
+- **Template leftover detection:**
+  - Look for ANY generic text that doesn't match the app's domain
+  - Common leftovers: "ShopTemplate", "TrackTemplate", "SocialTemplate", "Template", "Example", "Sample", "Demo", "Test Item", "Lorem", "Placeholder"
+  - Check headers, list items, buttons, placeholders, empty state text
+
+#### B2 — Accessibility Tree Audit
+
+Parse the element tree from `inspect()` and audit:
+
+- **Labels on interactive elements:**
+  - Every button must have a non-empty accessibility label
+  - Every link/tappable element must have a descriptive label
+  - Labels should describe the action, not just "button" or "element"
+
+- **Image descriptions:**
+  - Images should have accessibility descriptions
+  - Decorative images can be marked as such, but content images need descriptions
+
+- **Form field labels:**
+  - Text fields must have associated labels or placeholder text
+  - Pickers and selectors must be labeled
+
+- **Orphaned elements:**
+  - Elements in the a11y tree that are not visible on screen (hidden but accessible)
+  - Elements visible on screen but not in the a11y tree (visible but not accessible)
+
+- **Touch target sizes:**
+  - Interactive elements should be at least 44x44pt (iOS) or 48x48dp (Android)
+  - Flag any buttons or tappable elements that appear too small
+
+#### B3 — Interactive Exploration
+
+Interact with EVERY discoverable element and observe what happens:
+
+1. **Tap every button** — verify something happens (navigation, modal, state change, animation). Record any buttons that do nothing ("dead buttons").
+
+2. **Type into every text field:**
+   - Normal text: verify it appears correctly
+   - Edge cases: empty submit, very long text (50+ characters), special characters (@#$%)
+   - Search fields: type a query and verify results update
+
+3. **Toggle every switch/checkbox** — verify state changes visually.
+
+4. **Scroll every list:**
+   - Scroll to the bottom — verify all items render
+   - Scroll back to the top — verify the header/nav bar is intact (no overlap bugs)
+
+5. **Try unexpected interactions:**
+   - Swipe on non-swipeable areas — should not cause crashes or weird behavior
+   - Double-tap buttons — should not trigger the action twice (unless intentional)
+   - Tap on non-interactive text — should not crash
+
+6. **Test navigation depth:**
+   - Navigate 3+ levels deep (tab → list item → detail → sub-detail)
+   - Navigate back all the way — verify each screen restores correctly
+   - Verify the back button works at every level
+
+7. **Test state persistence:**
+   - Toggle a favorite, navigate away, come back — is it still toggled?
+   - Enter text in a form, switch tabs, come back — is the text preserved?
+   - Scroll down in a list, switch tabs, come back — is the scroll position preserved?
+
+8. **Test tab switching:**
+   - Switch between all tabs rapidly
+   - Verify each tab shows its correct content (not stale data from another tab)
+   - Verify the selected tab indicator updates correctly
+
+#### B4 — After-Interaction Comparison
+
+After completing interactions on a screen:
+
+1. `inspect()` again to capture the post-interaction state
+2. Compare the element tree with the pre-interaction tree
+3. Flag any unexpected changes:
+   - Elements that disappeared when they shouldn't have
+   - New elements that appeared unexpectedly
+   - Element labels that changed incorrectly
+   - Count mismatches (e.g., list had 5 items, now has 4)
+
+### Phase C — Bug Classification and Reporting
+
+For each issue discovered, classify it:
+
+| Tag | Category | Description | Severity Guide |
+|-----|----------|-------------|----------------|
+| `[VISUAL]` | Visual | Layout, overlap, truncation, wrong colors | Medium if minor, High if content is unreadable |
+| `[A11Y]` | Accessibility | Missing labels, unreachable elements, small targets | Medium for labels, High for unreachable elements |
+| `[UX]` | User Experience | Dead buttons, confusing navigation, unexpected behavior | High for dead buttons, Medium for confusing flows |
+| `[CONTENT]` | Content | Template leftovers, placeholder text, wrong domain text | High for template leftovers, Medium for placeholders |
+| `[STATE]` | State | State not updating, data not persisting, stale views | High for data loss, Medium for stale views |
+| `[CRASH]` | Crash | App crashes on interaction | Critical (P0) |
+
+Format each bug as:
+
+```markdown
+### BUG-{NNN}: [{SEVERITY}][EXPLORATORY][{TAG}] {Short description}
+- **Screen:** {screen name}
+- **Element:** {element description from a11y tree}
+- **Steps to reproduce:** {what you tapped/typed/swiped}
+- **Expected:** {what should happen}
+- **Actual:** {what actually happened}
+- **Screenshot context:** {brief description of what the screenshot showed}
+```
+
+### Phase D — Write Bug Report Section
+
+Append your findings to `output/{app-name}/reports/11-bug-report.md`. If the file doesn't exist, create it. Use this structure:
+
+```markdown
+# Bug Report — Exploratory Testing
+
+## Summary
+- Screens discovered: {N}
+- Screens audited: {N}
+- Total interactive elements found: {N}
+- Total interactions performed: {N}
+- Bugs found: {N}
+  - Critical (P0): {N}
+  - High (P1): {N}
+  - Medium (P2): {N}
+  - Low (P3): {N}
+
+## Accessibility Summary
+- Elements with labels: {N}/{total}
+- Elements missing labels: {N}
+- Images with descriptions: {N}/{total}
+- Touch targets below minimum: {N}
+
+## Screen Map
+{screen discovery tree from Phase A}
+
+## Bugs
+{all bugs from Phase C}
+```
+
+## Important Rules
+
+- **DO NOT read source code** — your inputs are ONLY screenshots and the element tree from `inspect()`
+- **DO NOT follow a test plan** — explore freely based on what you see
+- **Test EVERY interactive element** you discover in the element tree
+- Use ai-tester MCP tools (`inspect`, `act`, `assert`, `wait`) for ALL interaction — NOT shell commands
+- If the app crashes, document it as a P0/Critical bug and try to restart
+- You are testing on a SINGLE assigned simulator — use the provided `deviceName` in all MCP calls
+- Write your findings to the bug report — do NOT fix bugs (that's the bug-fixer skill's job)
+- Be thorough: an element tree with 20 buttons means you tap all 20 buttons

package/.cursor/skills/ios-customizer/SKILL.md

@@ -9,7 +9,7 @@ Use this skill to perform deep iOS/SwiftUI customization on a cloned template.
 
 ## When to Use
 
-- At Step 8 of the AppAgent workflow, when the platform is iOS
+- At Step 5 of the AppAgent workflow, when the platform is iOS
 - After AppConfig, mock data, and design tokens are already in place
 - When you need to modify SwiftUI views, navigation, and themes
 
@@ -100,7 +100,21 @@ iOS templates use a `Colors.swift` theme file:
 - Use semantic colors where possible (`Color.primary`, `Color.secondary`)
 - Apply corner radius and spacing tokens from the design brief
 
-### Step 4.5 — Generate App Launcher Icon
+### Step 4.5 — Visual Polish Application
+
+Apply the **Visual Polish Plan** from the customization manifest. This step is MANDATORY for every build — it makes apps feel handcrafted rather than template-like.
+
+1. **Shadows**: Apply `.cardShadow()` to every card, list item card, and elevated surface. Use `.elevatedShadow()` for FABs and floating buttons. If no `.cardShadow()` modifier exists, add `shadow(color:radius:x:y:)` directly using the manifest's shadow tokens.
+2. **Gradients**: Apply `LinearGradient` to hero sections (detail screen headers, banner areas) and primary CTA buttons per the manifest's gradient usage plan. Use `Color.appPrimary` → `Color.appSecondary` for primary gradient.
+3. **Press feedback**: Ensure all `Button` and tappable elements use `.scaleOnPress()` or `ButtonStyle` with scale animation (scale to 0.95 on press, spring return). For key interactions (favorite toggle, submit), add `UIImpactFeedbackGenerator(style: .light).impactOccurred()`.
+4. **Staggered animations**: Ensure all `ForEach` / `LazyVStack` list views apply `.staggeredAppear(index:)` to each item. This gives lists a lively cascading entrance.
+5. **Empty states**: Enhance empty state views — add a gradient circle background behind the icon (e.g., `Circle().fill(LinearGradient(...)).frame(width: 80, height: 80)` behind the SF Symbol), and add `.slideIn()` animation to the entire empty state composition.
+6. **Glass/blur**: Apply `.ultraThinMaterial` or `.regularMaterial` to sheet backgrounds and overlay views. Use `.background(.ultraThinMaterial)` on navigation bars where appropriate.
+7. **Haptic feedback**: Add `UIImpactFeedbackGenerator` calls to favorite toggles, pull-to-refresh completions, and primary action buttons.
+
+Verify visual hierarchy: hero elements (large images, gradients) stand out > section headers > cards (with shadows) > inline text.
+
+### Step 4.6 — Generate App Launcher Icon
 
 Generate a domain-specific app icon using the manifest's **App Launcher Icon** section:
 
@@ -229,26 +243,47 @@ If the customization manifest includes an **"Animation & Sensory Plan"** section
 3. **Apply the modifiers** using the imported module code:
 
 ```swift
-// MicroInteractions — press feedback
+// Built-in press feedback (always available)
 Button("Add to Cart") { ... }
     .scaleOnPress()
-    .hapticFeedback(.impact(.medium))
+    .hapticFeedback(.medium)
+
+// Built-in staggered list items (always available)
+ForEach(items.indices, id: \.self) { index in
+    ItemRow(item: items[index])
+        .staggeredAppear(index: index)
+}
+
+// Built-in shadow (always available)
+CardView(item: item)
+    .cardShadow()
 
-// ScrollEffects — parallax header
+// Built-in slide animation (always available)
+EmptyStateView()
+    .slideIn()
+
+// Built-in shimmer for loading placeholders (always available)
+RoundedRectangle(cornerRadius: 8)
+    .fill(Color(.systemGray5))
+    .frame(height: 60)
+    .shimmer()
+
+// Built-in pulse for live indicators (always available)
+Circle().fill(.red).frame(width: 8, height: 8)
+    .pulse()
+
+// Built-in heart bounce for favorites (always available)
+Image(systemName: isFavorite ? "heart.fill" : "heart")
+    .heartBounce(isActive: isFavorite)
+
+// ScrollEffects module — parallax header (if module integrated)
 ScrollView {
     ParallaxHeaderView(height: 280) {
         AsyncImage(url: item.imageURL)
     }
-    // content below
-}
-
-// AnimatedTransitions — staggered list items
-ForEach(items.indices, id: \.self) { index in
-    ItemRow(item: items[index])
-        .staggeredAppearance(index: index)
 }
 
-// CelebrationEffects — success overlay
+// CelebrationEffects module — success overlay (if module integrated)
 .celebrationOverlay(isPresented: $showCelebration, style: .confetti)
 ```
 
@@ -262,7 +297,7 @@ Write the report to `output/{app-name}/reports/05-customization.md` (append iOS
 ```markdown
 # Customization Report
 
-**Step:** 8
+**Step:** 5
 **Skill:** ios-customizer
 **Timestamp:** {ISO 8601}
 **Result:** PASS
@@ -312,7 +347,7 @@ Update `output/{app-name}/reports/summary.json` — read the file, append this s
 
 ```json
 {
-  "step": 8,
+  "step": 5,
   "name": "ios-customization",
   "startedAt": "{ISO 8601 timestamp}",
   "durationSeconds": 0,

package/.cursor/skills/module-integrator/SKILL.md

@@ -9,7 +9,7 @@ Integrate selected shared modules into the app by reading their reference implem
 
 ## Context You Need
 
-- **Module selection report** — `output/{app-name}/reports/02b-module-selection.md` — lists which modules were selected
+- **Catalog analysis report** — `output/{app-name}/reports/02-catalog-analysis.md` — lists which template and modules were selected
 - **Customization manifest** — `output/{app-name}/reports/customization-manifest.md` — contains the module integration plan with placement decisions
 - **Platform** — `ios` or `android`
 - **App name and bundle ID** — for adapting imports and identifiers
@@ -19,7 +19,7 @@ Integrate selected shared modules into the app by reading their reference implem
 
 ### Step 1 — Read the Module Selection Report
 
-Read `output/{app-name}/reports/02b-module-selection.md` to get the list of selected modules. Read the "Module Integration Plan" section from the customization manifest to understand where each module connects.
+Read the "Module Selection" section from `output/{app-name}/reports/02-catalog-analysis.md` to get the list of selected modules. Read the "Module Integration Plan" section from the customization manifest to understand where each module connects.
 
 ### Step 2 — For Each Selected Module, Integrate It
 

package/.cursor/skills/output-validator/SKILL.md

@@ -101,7 +101,7 @@ Mark all animation issues as `[WARN]` — they affect quality but are not build-
 
 Verify that the reports directory has the expected files:
 - `01-prompt-validation.md` exists
-- `02-template-selection.md` exists
+- `02-catalog-analysis.md` exists
 - `03-design-brand.md` exists
 - `04-content-brief.md` exists
 - `05-customization.md` exists

package/.cursor/skills/react-native-customizer/SKILL.md

@@ -133,12 +133,29 @@ const lightColors = {
 };
 ```
 
-### Step 5 — Data Layer & Mock Data
+### Step 4.5 — Visual Polish Application
 
-Templates use a `MockDataProvider.ts` that implements `DataRepository` interface:
+Apply the **Visual Polish Plan** from the customization manifest. This step is MANDATORY — it makes apps feel handcrafted rather than template-like.
+
+1. **Shadows**: Apply shadow styles to every card and elevated surface. Use platform-aware styles: `shadowColor`, `shadowOffset`, `shadowOpacity`, `shadowRadius` (iOS) and `elevation` (Android). Create a `cardShadow` style object and spread it into card `StyleSheet` definitions.
+2. **Gradients**: Use `expo-linear-gradient` `LinearGradient` component for hero sections (detail screen headers, banner areas) and primary CTA buttons. Apply `colors={[colors.primary, colors.secondary]}` with `start/end` props for direction.
+3. **Press feedback**: Ensure all `TouchableOpacity` elements use `activeOpacity={0.85}` and add a scale animation on press using `Animated.spring()` (scale to 0.95, spring back). Wrap common buttons in a `ScaleButton` component.
+4. **Staggered animations**: Ensure all `FlatList` items use `useStaggeredAppear(index)` hook for animated entrance. Apply the returned `animatedStyle` to each item's `Animated.View` wrapper.
+5. **Empty states**: Enhance empty state components — add a gradient circle background behind the icon (using `LinearGradient` + `borderRadius: 40`), and add slide-in animation with `useSlideIn()`.
+6. **Blur/glass**: Use `expo-blur` `BlurView` for modal/sheet backgrounds where supported. Fall back to semi-transparent background.
+7. **Haptic feedback**: Use `expo-haptics` or React Native `Vibration` API on favorite toggles and primary actions.
+
+Verify visual hierarchy: hero elements > section headers > cards (with shadows) > inline text.
+
+### Step 5 — Data Layer & Offline Infrastructure
+
+Templates include an **offline-first data layer**. Understand these components:
 
 **Files you should NOT modify** (generic infrastructure):
 - `src/data/DataRepository.ts` — interface definition
+- `src/data/NetworkMonitor.ts` — connectivity detection
+- `src/data/LocalPersistence.ts` — JSON file persistence
+- `src/components/OfflineBanner.tsx` — offline status banner
 - `src/theme/ThemeContext.tsx` — theme provider
 
 **Files you MAY need to update** (domain-specific):
@@ -147,25 +164,29 @@ Templates use a `MockDataProvider.ts` that implements `DataRepository` interface
   - All CRUD methods work with correct entity types
   - Subscription/onChange pattern is working
   - Reset method references correct defaults
+- `src/data/SyncManager.ts` — if entity types were renamed, update domain methods
 
 **ViewModel patterns** (how screens consume data):
 
-ViewModels are custom React hooks that use MockDataProvider:
+ViewModels are custom React hooks that use the `DataRepository` interface via `DataSourceResolver`, not `MockDataProvider` directly:
 ```tsx
+import { DataSourceResolver } from '../data/DataSourceResolver';
+
 export function useHomeViewModel() {
+  const repository = DataSourceResolver.repository;
   const [items, setItems] = useState<Item[]>([]);
   const [isLoading, setIsLoading] = useState(true);
 
   useEffect(() => {
     loadData();
-    const unsubscribe = MockDataProvider.subscribe(() => {
-      setItems(MockDataProvider.getItems());
+    const unsubscribe = repository.subscribe(() => {
+      setItems(repository.getItems());
     });
     return unsubscribe;
   }, []);
 
   const loadData = () => {
-    setItems(MockDataProvider.getItems());
+    setItems(repository.getItems());
     setIsLoading(false);
   };
 
@@ -173,6 +194,16 @@ export function useHomeViewModel() {
 }
 ```
 
+When customizing ViewModels, ALWAYS use `DataSourceResolver.repository`, never `MockDataProvider` directly. This ensures the app works with any data source (mock, localStorage, Firebase, Supabase, custom API).
+
+**OfflineBanner integration** — add to main navigation screens:
+```tsx
+<View style={{ flex: 1 }}>
+  <OfflineBanner />
+  {/* ... rest of screen content */}
+</View>
+```
+
 ### Step 6 — Data Layer Verification
 
 Verify the data layer uses correct patterns:
@@ -193,9 +224,36 @@ export interface DataRepository {
 }
 ```
 
+**MockDataProvider (implements DataRepository):**
+```tsx
+class MockDataProvider implements DataRepository {
+  private static instance: MockDataProvider;
+  private listeners: Set<() => void> = new Set();
+
+  getItems(): Item[] { ... }
+  addItem(item: Item): void { ... }
+  subscribe(callback: () => void): () => void { ... }
+  reset(): void { ... }  // Reset to defaults
+}
+```
+
+**DataSourceResolver:**
+```tsx
+export class DataSourceResolver {
+  static get repository(): DataRepository {
+    switch (AppConfig.DataSource.active) {
+      case 'localStorage': return MockDataProvider.getInstance(); // TODO: LocalStorageProvider
+      case 'mock': return MockDataProvider.getInstance();
+    }
+  }
+}
+```
+
 Verify:
-- MockDataProvider implements all DataRepository methods
-- ViewModel hooks use MockDataProvider correctly
+- DataRepository interface matches MockDataProvider's public methods
+- MockDataProvider implements DataRepository
+- DataSourceResolver returns the correct implementation
+- ViewModel hooks use `DataSourceResolver.repository`, not `MockDataProvider` directly
 - Seed data matches the new domain
 - CRUD methods reference correct entity types
 
@@ -208,35 +266,59 @@ If the customization manifest includes an **"Animation & Sensory Plan"** section
 3. **Apply the modifiers** using the imported module hooks/components:
 
 ```typescript
-// MicroInteractions — press feedback
-import { useScaleOnPress, useStaggeredAppearance } from '../shared/MicroInteractions';
-import { useHapticEngine } from '../shared/HapticEngine';
-
-const { animatedStyle, handlers } = useScaleOnPress();
-const haptic = useHapticEngine();
+// Built-in hooks (always available in animation/useAnimatedList)
+import { useScaleOnPress, useStaggeredAppear, useSlideIn, cardShadowStyle, useShimmer, usePulse, useHeartBounce } from '../animation/useAnimatedList';
 
-<Animated.View style={animatedStyle} {...handlers}>
-  <TouchableOpacity onPress={() => { haptic.impact('medium'); doAction(); }}>
+// Press feedback
+const { style: pressStyle, onPressIn, onPressOut } = useScaleOnPress();
+<Animated.View style={pressStyle}>
+  <Pressable onPressIn={onPressIn} onPressOut={onPressOut} onPress={doAction}>
     <Text>Add to Cart</Text>
-  </TouchableOpacity>
+  </Pressable>
 </Animated.View>
 
-// ScrollEffects — parallax header
-import { ParallaxHeader } from '../shared/ScrollEffects';
+// Staggered list items
+const animStyle = useStaggeredAppear(index);
+<Animated.View style={animStyle}><ItemCard item={item} /></Animated.View>
 
-<ParallaxHeader height={280} imageSource={item.imageUrl}>
-  {/* content below */}
-</ParallaxHeader>
+// Card shadow
+<View style={[styles.card, cardShadowStyle()]}>{/* content */}</View>
 
-// CelebrationEffects — success overlay
-import { CelebrationOverlay } from '../shared/CelebrationEffects';
+// Slide-in animation
+const slideStyle = useSlideIn();
+<Animated.View style={slideStyle}><EmptyState /></Animated.View>
 
+// Shimmer for loading placeholders
+const shimmerStyle = useShimmer();
+<Animated.View style={[styles.placeholder, shimmerStyle]} />
+
+// Pulse for live indicators
+const pulseStyle = usePulse();
+<Animated.View style={[styles.dot, pulseStyle]} />
+
+// Heart bounce for favorite toggles
+const heartStyle = useHeartBounce(isFavorite);
+<Animated.View style={heartStyle}><HeartIcon /></Animated.View>
+
+// Modules (if integrated)
+import { ParallaxHeader } from '../shared/ScrollEffects';
+<ParallaxHeader height={280} imageSource={item.imageUrl} />
+
+import { CelebrationOverlay } from '../shared/CelebrationEffects';
 <CelebrationOverlay isActive={showCelebration} style="confetti" />
 ```
 
 4. **Wrap all applied animations** with `useMotionPreferences` checks if MotionPreferences is integrated
 5. **Do NOT add animation modifiers** to screens not listed in the manifest
 
+### Step 6.7 — App Icon (if applicable)
+
+React Native apps target both iOS and Android. App icon customization is handled per-platform:
+- **iOS**: If `scripts/generate-app-icon.swift` exists, run it with the SF Symbol and background color from the manifest
+- **Android**: If `templates/android/ICON_VECTORS.md` exists, update `android/app/src/main/res/drawable/ic_launcher_foreground.xml` and `ic_launcher_background` color
+
+If the scripts/resources are not available, skip — the template's default icons will be used.
+
 ## Report Output
 
 Write the report to `output/{app-name}/reports/05-customization.md`:
@@ -269,6 +351,12 @@ React Native (TypeScript)
 - Empty states: {count}
 - CTAs updated: {count}
 
+## Offline Infrastructure
+
+- OfflineBanner integrated: {yes/no}
+- SyncManager methods updated: {list or "no changes needed"}
+- Data persistence verified: {yes/no}
+
 ## Animation Modifiers Applied
 
 - {modifier}: applied to {screen} — {description}
@@ -324,8 +412,10 @@ Templates include `testID` props on all interactive elements and a `TESTING_MANI
 - ONLY edit files under `output/` — never touch `templates/`
 - Ensure all imports resolve after your changes
 - Preserve `MockDataProvider` CRUD methods and `reset()` function
+- Do NOT modify NetworkMonitor, LocalPersistence, or OfflineBanner
+- Ensure OfflineBanner is integrated into main navigation screens
 - Use `testID` props on ALL interactive elements
-- Follow `{screen}_{element}_{role}` convention for new test IDs
+- Follow `{screen}_{element}_{role}` convention for new test IDs (see `templates/TEST_ID_CONVENTIONS.md`)
 - Use `StyleSheet.create()` for styles, not inline objects
 - Use functional components with TypeScript
 - Keep React Navigation structure intact