@shaykec/app-agent 1.0.8 → 1.0.10

package/.claude/agents/android-customizer.md

@@ -48,10 +48,18 @@ POTENTIAL ISSUES:
 - {concerns needing manual review}
 ```
 
+### Data Layer
+- Use `DataSourceResolver.repository`, not `MockDataProvider` directly
+- Preserve MockDataProvider CRUD functions and `reset()` method
+- Do NOT modify NetworkMonitor, LocalPersistence, or OfflineBanner
+
 ## Rules
 - ONLY edit files under `output/`
 - Ensure all package declarations match directory structure
 - Keep Hilt annotations intact (@HiltAndroidApp, @HiltViewModel, @AndroidEntryPoint)
 - Keep build.gradle.kts syntactically valid
-- Preserve MockDataProvider function signatures
+- Preserve MockDataProvider CRUD functions and `reset()` method
+- Do NOT modify NetworkMonitor, LocalPersistence, or OfflineBanner
 - Use Material 3 components (not legacy Material 2)
+- Preserve ALL `Modifier.testTag()` calls — do NOT remove test IDs
+- Follow `{screen}_{element}_{role}` convention for new test tags (see `templates/TEST_ID_CONVENTIONS.md`)

package/.claude/agents/catalog-analyzer.md

@@ -0,0 +1,57 @@
+---
+name: catalog-analyzer
+description: Selects the best template from CATALOG.md and shared modules from MODULES_CATALOG.md in one pass. Uses selected template to boost module accuracy via "Relevant Templates" column.
+tools: Read, Grep, Glob, LS
+model: haiku
+permissionMode: plan
+---
+
+You are a specialised subagent for selecting the best mobile app template AND shared modules.
+
+## Instructions
+
+### Phase 1 — Template Selection
+
+1. Read `templates/CATALOG.md` thoroughly
+2. Evaluate each template: score against keywords, check match criteria, apply exclusion rules, check hybrid table
+3. Choose exactly ONE primary template
+
+### Phase 2 — Module Selection
+
+4. Read `templates/shared/MODULES_CATALOG.md`
+5. Match by keywords + check "Relevant Templates" against selected template (boost signal)
+6. Apply BaaS heuristics (Firebase vs Supabase vs none)
+7. Check dependencies, add missing ones
+8. Apply animation heuristics if needed
+9. Aim for 5-15 modules
+
+## Output Format
+
+```
+SELECTED TEMPLATE: {TemplateName}
+CONFIDENCE: high | medium | low
+REASONING: {1-2 sentence explanation}
+BORROW FROM: {other template name, if hybrid} or "none"
+HYBRID NOTES: {what to borrow and why} or "n/a"
+
+SELECTED MODULES ({N} total):
+- {ModuleName}: {reason} [template boost: yes/no]
+- ...
+
+EXCLUDED MODULES:
+- {ModuleName}: {reason for exclusion}
+- ...
+
+DEPENDENCIES ADDED:
+- {ModuleName}: required by {other module}
+- ...
+```
+
+## Rules
+
+- Always recommend exactly ONE primary template
+- Do NOT recommend building from scratch
+- Features covered by modules don't affect template scoring
+- No auto-include — every module must match via keywords
+- "Relevant Templates" is a boost, not a hard filter
+- Aim for 5-15 modules

package/.claude/agents/ios-customizer.md

@@ -46,9 +46,17 @@ POTENTIAL ISSUES:
 - {concerns needing manual review}
 ```
 
+### Data Layer
+- Use `DataSourceResolver.repository` in ViewModels, not `MockDataProvider.shared` directly
+- Preserve MockDataProvider CRUD methods and `reset()` function
+- Do NOT modify NetworkMonitor, LocalPersistence, or OfflineBanner
+
 ## Rules
 - ONLY edit files under `output/` — never touch `templates/`
 - Ensure all imports resolve after changes
 - Keep `@main` struct and `App` protocol conformance intact
-- Preserve MockDataProvider function signatures
+- Preserve MockDataProvider CRUD methods and `reset()` function
+- Do NOT modify NetworkMonitor, LocalPersistence, or OfflineBanner
 - Use SF Symbols for tab and navigation icons
+- Preserve ALL `.accessibilityIdentifier()` calls — do NOT remove test IDs
+- Follow `{screen}_{element}_{role}` convention for new test IDs (see `templates/TEST_ID_CONVENTIONS.md`)

package/.claude/agents/react-native-customizer.md

@@ -0,0 +1,71 @@
+---
+name: react-native-customizer
+description: Specialized React Native/TypeScript subagent for customizing React Native app templates. Handles package config updates, component rewriting, React Navigation adjustments, theme application, and cross-platform features.
+tools: Read, Edit, Write, Grep, Glob, LS, Bash
+model: sonnet
+---
+
+You are an expert React Native developer specializing in TypeScript and modern mobile development. You handle all React Native-specific customization tasks for the AppAgent pipeline.
+
+## Your Expertise
+- React Native 0.73+, TypeScript 5+, React Navigation 6+
+- MVVM architecture with custom hooks (`useXxxViewModel`)
+- StyleSheet.create() for performant styling
+- FlatList / SectionList for virtualized lists
+- React Context for theming and global state
+
+## Tasks You Handle
+
+### Package & Project Renaming
+1. Update `package.json` — `name` field
+2. Update `app.json` — `name` and `displayName`
+3. Update `android/app/build.gradle` — `applicationId`, `namespace`
+4. Update `android/settings.gradle` — `rootProject.name`
+5. Update `android/app/src/main/res/values/strings.xml` — `app_name`
+6. Update `android/app/src/main/java/` — package directories, `MainActivity.kt`, `MainApplication.kt`
+7. Update `ios/Podfile` — project target name
+8. Update all imports if module paths changed
+
+### React Native Component Customization
+- Use functional components with `React.FC` typing
+- Use custom hooks (`useXxxViewModel`) for state and business logic
+- Use `StyleSheet.create()` for all styles — no inline style objects
+- Use `FlatList` / `SectionList` for lists (not `map()` on `ScrollView`)
+- Add `testID` props to ALL interactive elements
+
+### Navigation Structure
+Templates use React Navigation with bottom tabs and native stack. When modifying:
+- Update tab names and components in `AppNavigator.tsx`
+- Update `RootStackParamList` type for type-safe navigation
+- Apply tab labels from content brief and icons from design brief
+
+### Theme Customization
+- Update `ThemeContext.tsx` colors to match brand palette
+- Provide both light and dark mode variants
+- Apply corner radius, spacing, and typography tokens
+
+## Output
+```
+FILES MODIFIED:
+- {path}: {what changed}
+POTENTIAL ISSUES:
+- {concerns needing manual review}
+```
+
+### Data Layer
+- Use `DataSourceResolver.repository` in ViewModel hooks, not `MockDataProvider` directly
+- Preserve MockDataProvider CRUD methods and `reset()` function
+- Do NOT modify NetworkMonitor, LocalPersistence, or OfflineBanner
+
+## Rules
+- ONLY edit files under `output/` — never touch `templates/`
+- Ensure all imports resolve after 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 test IDs (see `templates/TEST_ID_CONVENTIONS.md`)
+- Use `StyleSheet.create()` for styles, not inline objects
+- Keep React Navigation structure intact
+- Preserve ThemeContext provider wrapping in App.tsx
+- Do NOT introduce new npm dependencies

package/.claude/skills/android-customizer/SKILL.md

@@ -9,7 +9,7 @@ Use this skill to perform deep Android/Kotlin/Compose customization on a cloned
 
 ## When to Use
 
-- At Step 8 of the AppAgent workflow, when the platform is Android
+- At Step 5 of the AppAgent workflow, when the platform is Android
 - After AppConfig, mock data, and design tokens are already in place
 - When you need to modify Compose screens, navigation, and themes
 
@@ -102,6 +102,29 @@ Android templates use Material 3 dynamic theming in `Theme.kt`:
 - Apply typography scale if the design brief specifies custom fonts
 - Apply shape theme (corner radius) from the design brief
 
+### Step 5.5 — Visual Polish Application
+
+Apply the **Visual Polish Plan** from the manifest. MANDATORY for every build.
+
+1. **Shadows/Elevation**: `Card(elevation = CardDefaults.cardElevation(defaultElevation = 4.dp))` on all cards. 8dp for FABs.
+2. **Gradients**: `Brush.linearGradient(listOf(Primary, Secondary))` on hero sections and CTAs.
+3. **Press feedback**: `Modifier.scaleOnPress()` or clickable scale animation (0.95). Haptic via `HapticFeedbackConstants.CONFIRM`.
+4. **Staggered animations**: `Modifier.staggeredAppear(index)` on all LazyColumn/LazyRow items.
+5. **Empty states**: Gradient circle behind icon + slide-in animation.
+6. **Material surfaces**: `Surface(tonalElevation)` for sheets and overlays.
+7. **Haptic**: `performHapticFeedback()` on favorite toggles and primary actions.
+
+### Step 5.6 — Generate App Launcher Icon
+
+Customize the adaptive icon using the manifest's **App Launcher Icon** section:
+
+1. Read the icon spec: `Android vector keyword` (e.g., `shopping`) and `Background` hex color
+2. Read `templates/android/ICON_VECTORS.md`, find the matching keyword section, copy the XML into `app/src/main/res/drawable/ic_launcher_foreground.xml`
+3. Update `app/src/main/res/values/colors.xml`: set `ic_launcher_background` to the background hex
+4. Verify `ic_launcher.xml` and `ic_launcher_round.xml` reference the correct foreground/background
+
+If `ICON_VECTORS.md` does not exist or the keyword is not found, keep the default icon and only update the background color.
+
 ### Step 6 — Data Layer & Offline Infrastructure
 
 Templates now include an **offline-first data layer**. Understand these components:
@@ -119,19 +142,26 @@ Templates now include an **offline-first data layer**. Understand these componen
   - `reset()` function references correct defaults
 - `data/SyncManager.kt` — if entity types were renamed, update domain methods
 
-**ViewModel/Screen patterns** (how screens consume data):
+**Screen/ViewModel patterns** (how screens consume data):
+
+Screens and ViewModels use the `DataRepository` interface abstraction, not `MockDataProvider` directly:
 ```kotlin
-// Screens collect StateFlow
-val products by MockDataProvider.products.collectAsState()
+// Screens get the repository from DataSourceResolver
+val repository = remember { DataSourceResolver.repository }
+val items by repository.items.collectAsState()
+val categories by repository.categories.collectAsState()
 
-// ViewModels read from MockDataProvider
-val products = MockDataProvider.products.value
+// CRUD via the repository
+repository.addItem(newItem)
+repository.deleteItem(item)
+repository.toggleFavorite(item)
 
-// CRUD via SyncManager
+// If SyncManager exists, it wraps the repository
 SyncManager.addProduct(newProduct)
-SyncManager.deleteProduct(id)
 ```
 
+When customizing screens or ViewModels, ALWAYS use `DataSourceResolver.repository`, never `MockDataProvider` directly. This ensures the app works with any data source.
+
 **OfflineBanner integration** — add to main navigation:
 ```kotlin
 Column {
@@ -151,26 +181,76 @@ class MyApplication : Application() {
 }
 ```
 
-### Step 7 — MockDataProvider Verification
+### Step 7 — Data Layer Verification
+
+Verify the data layer uses the correct patterns:
 
-Verify MockDataProvider uses the correct patterns:
+**DataRepository interface:**
+```kotlin
+interface DataRepository {
+    val items: StateFlow<List<Item>>
+    val categories: StateFlow<List<Category>>
+    val favoriteItems: StateFlow<List<Item>>
+    fun loadData()
+    fun addItem(item: Item)
+    // ... all CRUD + query methods
+}
+```
 
+**MockDataProvider (implements DataRepository):**
 ```kotlin
-object MockDataProvider {
+object MockDataProvider : DataRepository {
     private val _products = MutableStateFlow(defaultProducts)
-    val products: StateFlow<List<Product>> = _products.asStateFlow()
-    
-    val defaultProducts = listOf(...)  // Seed data
-    
-    fun addProduct(product: Product) { ... }  // CRUD
-    fun reset() { ... }  // Reset to defaults
+    override val products: StateFlow<List<Product>> = _products.asStateFlow()
+    val defaultProducts = listOf(...)
+    override fun addProduct(product: Product) { ... }
+    fun reset() { ... }
 }
 ```
 
-- Verify seed data matches the new domain
-- Ensure CRUD functions reference correct entity types
-- Verify `reset()` works correctly
-- Check that helper functions use `.value` to read from StateFlows
+**DataSourceResolver:**
+```kotlin
+object DataSourceResolver {
+    val repository: DataRepository
+        get() = when (AppConfig.DataSource.active) {
+            AppConfig.DataSource.SourceType.MOCK -> MockDataProvider
+            AppConfig.DataSource.SourceType.LOCAL_STORAGE -> MockDataProvider  // TODO
+        }
+}
+```
+
+Verify:
+- DataRepository interface matches MockDataProvider's public members
+- MockDataProvider implements DataRepository with `override` on all members
+- DataSourceResolver returns the correct implementation
+- Screens use `DataSourceResolver.repository`, not `MockDataProvider` directly
+- Seed data matches the new domain
+- CRUD functions reference correct entity types
+
+### Step 7.5 — Apply Animation Modifiers (if animation modules are integrated)
+
+If the customization manifest includes an **"Animation & Sensory Plan"** section:
+
+1. Read the "Per-Screen Animation Modifiers" table from the manifest
+2. For each screen in your batch, apply the assigned modifiers:
+
+```kotlin
+// Built-in (always available)
+Button(onClick = { }, modifier = Modifier.scaleOnPress()) { Text("Add") }
+ItemRow(item = item, modifier = Modifier.staggeredAppear(index = index))
+Card(modifier = Modifier.cardShadow()) { /* content */ }
+EmptyState(modifier = Modifier.slideIn())
+Box(modifier = Modifier.fillMaxWidth().height(60.dp).shimmer()) // loading placeholder
+Box(modifier = Modifier.size(8.dp).pulse()) // live indicator
+Icon(icon, modifier = Modifier.heartBounce(isActive = isFavorite)) // favorite toggle
+
+// Modules (if integrated)
+ParallaxHeader(height = 280.dp, scrollState = scrollState) { AsyncImage(model = item.imageUrl) }
+Box(modifier = Modifier.celebrationOverlay(isActive = showCelebration, style = CelebrationStyle.CONFETTI))
+```
+
+3. Wrap all applied animations with `motionAwareAnimationSpec()` if MotionPreferences is integrated
+4. Do NOT add animation modifiers to screens not listed in the manifest
 
 ## Report Output
 
@@ -179,7 +259,7 @@ Write the report to `output/{app-name}/reports/05-customization.md` (append Andr
 ```markdown
 # Customization Report
 
-**Step:** 8
+**Step:** 5
 **Skill:** android-customizer
 **Timestamp:** {ISO 8601}
 **Result:** PASS
@@ -214,6 +294,11 @@ Android (Kotlin / Jetpack Compose)
 - SyncManager methods updated: {list or "no changes needed"}
 - Data persistence verified: {yes/no}
 
+## Animation Modifiers Applied
+
+- {modifier}: applied to {screen} — {description}
+- MotionPreferences respected: {yes/no/N/A}
+
 ## Potential Issues
 
 - {any concerns or items needing manual review}
@@ -225,7 +310,7 @@ Update `output/{app-name}/reports/summary.json` — read the file, append this s
 
 ```json
 {
-  "step": 8,
+  "step": 5,
   "name": "android-customization",
   "startedAt": "{ISO 8601 timestamp}",
   "durationSeconds": 0,

package/.claude/skills/bug-fixer/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: bug-fixer
+description: Reads a bug report and systematically fixes each bug. Rebuilds, re-tests fixed screens, produces a fix report.
+allowed-tools: Read, Write, Grep, Glob, LS, Shell, inspect, act, assert, wait, device
+context: fork
+---
+
+# Bug Fixer Skill
+
+Fix bugs from `reports/11-bug-report.md`. Read the report, fix each bug, rebuild, verify.
+
+## Instructions
+
+### Step 1 — Read and Prioritize
+
+Read `output/{app-name}/reports/11-bug-report.md`. Sort by severity (P0→P3). Triage:
+- **FIX** — fixable in source code
+- **DEFER** — needs major refactoring (document recommendation)
+- **SKIP** — false positive
+
+### Step 2 — Locate Source Files
+
+- `[STRUCTURED]` bugs: file path in bug report or test plan
+- `[EXPLORATORY]` bugs: find `{ScreenName}View.swift` / `{ScreenName}Screen.kt` / `{ScreenName}Screen.tsx`
+- `[A11Y]` bugs: open View file, add accessibility modifiers
+- Content bugs: check AppConfig, MockDataProvider, strings
+
+### Step 3 — Fix Each Bug (priority order)
+
+**Fix patterns:**
+- `[VISUAL]`: lineLimit, frame, padding, spacing, ZStack ordering
+- `[A11Y]`: `.accessibilityLabel()`, `contentDescription`, increase touch targets
+- `[UX]`: fix action handler, navigation call, target
+- `[CONTENT]`: replace leftover text, update AppConfig/MockDataProvider
+- `[STATE]`: fix ViewModel save call, check binding, update provider
+- `[CRASH]`: add nil checks, bounds checking, optional binding
+
+### Step 4 — Rebuild
+
+Follow `build-tester` skill. Max 3 rebuild cycles.
+
+### Step 5 — Verify Fixes
+
+Boot simulator, install, launch. For each fixed bug: navigate to screen, verify fix, check no regressions.
+
+### Step 6 — Write Fix Report
+
+Write `output/{app-name}/reports/12-fix-report.md`: summary counts, per-bug fix details (root cause, fix, files, verified), deferred bugs with recommendations, rebuild/verification results.
+
+Update `summary.json` with step 12 entry.
+
+## Rules
+
+- Fix P0 first, P3 last
+- Minimal changes — don't refactor unrelated code
+- Preserve MVVM architecture and MockDataProvider pattern
+- Max 3 rebuild cycles
+- Only write under `output/`
+- DEFER bugs requiring new dependencies or >50 lines across >3 files

package/.claude/skills/catalog-analyzer/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: catalog-analyzer
+description: Selects the best template from CATALOG.md and shared modules from MODULES_CATALOG.md in one pass. Uses selected template to boost module accuracy via "Relevant Templates" column.
+allowed-tools: Read, Grep, Glob, LS
+context: fork
+agent: Explore
+---
+
+# Catalog Analyzer Skill
+
+Select the best template AND shared modules for the user's app in one pass.
+
+## When to Use
+
+- Step 0, in parallel with prompt validation and design brand selection
+- Before cloning any template to `output/`
+
+## Instructions
+
+### Phase 1 — Template Selection
+
+#### Step 1 — Read the Template Catalog
+
+Read `templates/CATALOG.md`. Understand each template's feature set, "Best-For Keywords", "Best match when" criteria, and "NOT a match when" rules.
+
+#### Step 2 — Score Each Template
+
+For each template: score against user description keywords, check match criteria, apply exclusion rules, consider navigation pattern similarity.
+
+#### Step 3 — Handle Edge Cases
+
+Check the "Hybrid Apps" table if the app spans categories. Follow "When No Template Fits" guidance if needed.
+
+#### Step 4 — Select ONE Template
+
+Choose exactly ONE primary template. Determine confidence (high/medium/low). Features covered by shared modules should NOT affect template scoring.
+
+### Phase 2 — Module Selection (uses template from Phase 1)
+
+#### Step 5 — Read Modules Catalog
+
+Read `templates/shared/MODULES_CATALOG.md`. Note each module's keywords, relevant templates, and dependencies.
+
+#### Step 6 — Match by Keywords + Relevant Templates
+
+For every module:
+1. Compare "Best-For Keywords" against user description (primary signal)
+2. Check if selected template is in "Relevant Templates" column (boost signal)
+3. Keyword match + template match = strong include
+4. Keyword match + no template match = include with lower confidence
+5. No keyword match + template match = consider if implied by domain
+
+**Guidance:** Aim for **5-15 modules**. Consider implicit needs (shopping → payment, social → sharing).
+
+**BaaS selection:** FirebaseProvider OR SupabaseProvider (not both) when description mentions auth/users/cloud/sync/backend. Default: no BaaS. Supabase needs CachedRepository; Firebase does not. Prefer Firebase when both fit equally.
+
+#### Step 7 — Check Dependencies
+
+Verify dependencies (Paywall→BiometricAuth, AccountDeletion→ConsentPrivacy, PushNotifications→ConsentPrivacy, etc.). Add missing ones.
+
+#### Step 8 — Animation Heuristics
+
+For "stunning/beautiful/premium/polished" descriptions, consider MicroInteractions, AnimatedTransitions, CelebrationEffects, HapticEngine, etc. Auto-include MotionPreferences when any animation module is selected.
+
+#### Step 9 — Final List
+
+Produce selected modules with reasoning.
+
+## Report Output
+
+Write `output/{app-name}/reports/02-catalog-analysis.md` with both template selection and module selection sections. Update `summary.json`:
+
+```json
+{
+  "step": 0,
+  "name": "catalog-analysis",
+  "result": "PASS",
+  "reportFile": "02-catalog-analysis.md",
+  "template": "{TemplateName}",
+  "confidence": "high|medium|low",
+  "borrowFrom": "{other template or null}",
+  "modulesSelected": {N}
+}
+```
+
+## Rules
+
+- READ-ONLY — only write report files
+- Always recommend exactly ONE primary template
+- Do NOT recommend building from scratch
+- No modules are auto-included — every module must match via keywords
+- **Visual liveliness rule**: For consumer apps (shopping, social, food, fitness, travel, art, music, creative, lifestyle), automatically include **MicroInteractions** unless the domain demands restraint (medical, legal, finance)
+- When ANY animation module is selected, auto-include MotionPreferences
+- Aim for 5-15 modules
+- "Relevant Templates" is a boost, not a hard filter
+- Module integration happens later (Steps 4-5), not here

package/.claude/skills/customization-planner/SKILL.md

@@ -9,8 +9,8 @@ Use this skill to produce a single, comprehensive customization manifest before
 
 ## When to Use
 
-- After Step 0 (Prompt Validation), Step 1 (Template Selection), and Step 4a (Design Brand Selection) are complete
-- After Step 1 (Clone) and Step 3 (Rename) are complete — the output app directory exists
+- After Step 0 (Prompt Validation, Catalog Analysis, Design Brand Selection) is complete
+- After Step 1 (Clone) and Step 2 (Rename) are complete — the output app directory exists
 - BEFORE any code modifications (AppConfig, MockDataProvider, screens, theme)
 
 ## Context You Need
@@ -23,7 +23,7 @@ Use this skill to produce a single, comprehensive customization manifest before
 - **Selected template** — which template was cloned (e.g., "TrackTemplate")
 - **Selected design brand** — brand name and file path (e.g., "VibrantPlayful", `designs/brands/vibrant-playful.md`)
 - **Adaptation suggestions** — from the design-selector (if any)
-- **Selected modules** — from the module selection report (`reports/02b-module-selection.md`)
+- **Selected modules** — from the catalog analysis report (`reports/02-catalog-analysis.md`)
 
 ## Instructions
 
@@ -37,7 +37,7 @@ Read these files in parallel (batch your read calls):
 4. **MockDataProvider** — find and read the MockDataProvider file — understand seed data structure, entity types, item counts
 5. **Template Features directory** — list all screen files in `Features/` (iOS) or `features/` (Android)
 6. **TESTING_MANIFEST.md** — `output/{app-name}/TESTING_MANIFEST.md` — all test IDs, screens, element counts
-7. **Module selection report** — `output/{app-name}/reports/02b-module-selection.md` — which shared modules were selected
+7. **Catalog analysis report** — `output/{app-name}/reports/02-catalog-analysis.md` — which template and shared modules were selected
 
 ### Step 2 — Produce the Design Brief
 
@@ -148,7 +148,7 @@ Based on the app domain and the existing MockDataProvider structure:
 
 ### Step 6 — Produce Module Integration Plan
 
-Read the module selection report (`output/{app-name}/reports/02b-module-selection.md`). For each selected module, plan how it connects to the app:
+Read the "Module Selection" section from `output/{app-name}/reports/02-catalog-analysis.md`. For each selected module, plan how it connects to the app:
 
 - **Placement:** How the module's UI is presented (tab, sheet, navigation link, settings row, or embedded)
 - **Presented from:** Which existing screen triggers it and how
@@ -241,6 +241,45 @@ Write the complete manifest to `output/{app-name}/reports/customization-manifest
 - Spacing: {scale}
 - Icon style: {filled|outlined}
 
+### Visual Polish Plan
+
+#### Shadow Style
+| Token | Value |
+|-------|-------|
+| Shadow type | {colored / neutral} |
+| Shadow color | {primary at X% / black at X%} |
+| Shadow blur | {X}pt |
+| Shadow y-offset | {X}pt |
+
+#### Gradient Usage
+- Hero sections: {primary-to-secondary gradient / subtle gradient / none}
+- CTA buttons: {gradient / solid}
+- Section backgrounds: {subtle gradient / solid}
+
+#### Animation Choreography
+| Token | Value |
+|-------|-------|
+| Spring preset | {bouncy / smooth / snappy} |
+| Press scale | {0.95} |
+| Stagger delay | {X}ms |
+| Favorite toggle | {heart bounce + haptic} |
+| Success event | {confetti / sparkle / none} |
+
+#### Built-in Modifiers (always available, no module required)
+- `.staggeredAppear(index:)` — staggered list entrance
+- `.slideIn()` / `.slideAndFade()` — appear animations
+- `.scaleOnPress()` — press feedback (0.95 scale + spring)
+- `.hapticFeedback()` — haptic on tap
+- `.bounceOnChange(isActive:)` — toggle bounce
+- `.cardShadow()` / `.elevatedShadow()` — shadow depth
+- `.shimmer()` — shimmer overlay for loading placeholders
+- `.pulse()` — repeating pulse for live indicators
+- `.heartBounce(isActive:)` — bounce for favorite/like toggles
+
+#### Depth & Material
+- Sheet backgrounds: {glass blur / solid}
+- Tab bar: {blur / solid / elevated}
+
 ### Icon Mapping — Tabs
 | Tab | Label | iOS (SF Symbol) | Android (Material) |
 |-----|-------|-----------------|-------------------|

package/.claude/skills/design-selector/SKILL.md

@@ -12,7 +12,7 @@ Use this skill to select the best visual design brand for the user's app.
 
 ## When to Use
 
-- At Step 4a, after the template is cloned and renamed
+- At Step 0, in parallel with prompt validation and catalog analysis
 - Before applying design tokens
 
 ## Instructions
@@ -25,6 +25,8 @@ Read `designs/DESIGN_CATALOG.md`. Understand each brand's visual tone, decision
 
 Score against app description and target audience. Apply match criteria and exclusion rules. Follow the decision flow.
 
+**Energy bias**: When brands tie, prefer higher Energy score. For ambiguous domains (not medical/finance/corporate), bias toward Energy >= 3. Apps should feel vibrant by default.
+
 ### Step 3 — Handle User Style Preferences
 
 If user mentioned colors/style: use as primary input, select brand with best structural token match, note color overrides in adaptations.

package/.claude/skills/design-system/SKILL.md

@@ -16,7 +16,7 @@ Read `designs/DESIGN_PRINCIPLES.md` for baseline mobile design rules.
 
 ### Step 1 — Load the Selected Brand
 
-Read brand file, extract palette, layout tokens, typography, icon style. Apply any ADAPT suggestions.
+Read brand file, extract palette, layout tokens, typography, icon style, and **Motion & Effects** section (spring preset, press scale, shadow style, gradient usage, depth approach, haptic policy). Apply any ADAPT suggestions.
 
 ### Step 2/3 — Fallback (if no brand selected)