@shaykec/app-agent 1.0.9 → 1.0.10

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

@@ -0,0 +1,222 @@
+---
+name: catalog-analyzer
+description: Selects the best template from CATALOG.md and the best shared modules from MODULES_CATALOG.md in a single pass. Uses the selected template to boost module selection accuracy via the "Relevant Templates" column.
+---
+
+# Catalog Analyzer Skill
+
+Use this skill to select the best template AND the best shared modules for the user's app in one pass.
+
+## When to Use
+
+- At Step 0 of the AppAgent workflow, in parallel with prompt validation and design brand selection
+- When you need to pick both a starting template and shared modules
+- Before cloning any template to `output/`
+
+## Context You Need
+
+- **User description** — what kind of app the user wants to build
+- **Platform** — `ios`, `android`, or `react-native`
+- **Sanitized description** — from the prompt-validator skill (if available)
+
+## Instructions
+
+### Phase 1 — Template Selection
+
+#### Step 1 — Read the Template Catalog
+
+Read `templates/CATALOG.md` thoroughly. Understand each template's:
+- Feature set and architecture
+- "Best-For Keywords" in the decision matrix
+- "Best match when" criteria
+- "NOT a match when" exclusion rules
+
+#### Step 2 — Score Each Template
+
+For each template in the catalog:
+1. Score it against the user's description using the "Best-For Keywords"
+2. Check the "Best match when" criteria — how many match?
+3. Apply the "NOT a match when" rules — does any exclusion trigger?
+4. Consider navigation pattern similarity (tabs, lists, detail screens)
+
+#### Step 3 — Handle Edge Cases
+
+- If the app spans multiple categories, check the "Hybrid Apps" table in the catalog
+- If no template is a strong match, follow the "When No Template Fits" guidance — pick the template with the most similar navigation and screen patterns
+- Consider the platform (iOS vs Android vs React Native) — all templates are available on all three platforms. The same template names exist under `templates/ios/`, `templates/android/`, and `templates/react-native/`
+
+#### Step 4 — Select ONE Template
+
+Choose exactly ONE primary template. Determine confidence:
+- **high** — multiple criteria match, clear winner
+- **medium** — good fit but some aspects don't align perfectly
+- **low** — no great match, picking the closest option
+
+If hybrid is needed, identify what to borrow from a secondary template.
+
+**Important:** Features covered by shared modules (consent, paywall, push notifications, etc.) should NOT affect template scoring — they are handled by module selection in Phase 2.
+
+### Phase 2 — Module Selection
+
+Uses the template selected in Phase 1 for improved accuracy.
+
+#### Step 5 — Read the Modules Catalog
+
+Read `templates/shared/MODULES_CATALOG.md` thoroughly. Understand each module's:
+- "Best-For Keywords" in the decision matrix
+- "Relevant Templates" column
+- Module dependencies
+
+#### Step 6 — Match Modules by Keywords + Relevant Templates
+
+For every module in the catalog:
+1. Compare its "Best-For Keywords" against the user's description (primary signal)
+2. Check if the **selected template** (from Phase 1) is in the "Relevant Templates" column (boost signal)
+3. If keyword matches AND template matches → **strong include**
+4. If keyword matches but template doesn't match → include with lower confidence
+5. If no keyword match but template matches → consider if implied by domain
+
+**Selection guidance:**
+- Aim for **5-15 modules** that genuinely match the app's features
+- Don't over-select — only include modules the app will actually use
+- Don't under-select — if a keyword matches, the module is likely needed
+- Consider implicit needs (e.g., a "shopping app" implies payment, a "social app" implies sharing)
+
+#### Step 7 — BaaS Module Selection
+
+**BaaS module selection (FirebaseProvider, SupabaseProvider, CachedRepository):**
+- Select FirebaseProvider OR SupabaseProvider (not both) when the description mentions: "real data", "users", "auth", "login", "sign up", "accounts", "cloud", "sync", "backend", "database", "multi-device", "server"
+- Default (no BaaS keywords): NO BaaS module. The app uses `localStorage` (Core Data / Room) by default.
+- If SupabaseProvider is selected, also add CachedRepository (Supabase has no built-in offline cache)
+- If FirebaseProvider is selected, do NOT add CachedRepository (Firestore has built-in offline persistence)
+- Prefer Firebase for "Google ecosystem" keywords, Supabase for "PostgreSQL", "open source", "self-hosted" keywords
+- When both would fit equally, prefer Firebase (more mature mobile SDK)
+
+#### Step 8 — Check Dependencies
+
+Verify that included modules have their dependencies met:
+- Paywall depends on BiometricAuth (optional)
+- AccountDeletion depends on ConsentPrivacy
+- PushNotifications depends on ConsentPrivacy
+- PaymentMethods depends on Paywall
+- GamificationKit depends on ChartsLibrary
+- NotificationCenter depends on PushNotifications
+- CloudSync depends on NetworkBanner
+- LiveActivities depends on PushNotifications
+- SupabaseProvider depends on CachedRepository (for offline support)
+- FirebaseProvider depends on ErrorHandling (optional), NetworkBanner (optional)
+- SupabaseProvider depends on ErrorHandling (optional), NetworkBanner (optional)
+
+If a dependency is missing, add it.
+
+#### Step 9 — Animation & Sensory Module Heuristics
+
+When the user description contains words like **"stunning", "beautiful", "premium feel", "polished", "delightful", "smooth", "animated", "modern", "sleek", "creative", "artistic", "colorful", "vibrant", "elegant", "stylish", "cool", "interactive"**, consider these signal-word matches:
+
+| Signal Word | Consider Modules |
+|---|---|
+| stunning, beautiful, premium, polished | MicroInteractions, AnimatedTransitions, CelebrationEffects |
+| haptic, tactile, vibration, feedback | HapticEngine |
+| sound, audio, click sound, chime | AudioFeedback |
+| parallax, scroll effect, header animation | ScrollEffects |
+| confetti, celebration, achievement | CelebrationEffects |
+| onboarding, walkthrough, tutorial | AnimatedOnboarding |
+| transitions, hero, card flip, animated navigation | AnimatedTransitions |
+| micro-animations, bounce, press, stagger | MicroInteractions |
+
+**Auto-include rule:** When ANY of HapticEngine, AudioFeedback, ScrollEffects, CelebrationEffects, MicroInteractions, AnimatedTransitions, or AnimatedOnboarding is selected, **MotionPreferences is automatically added** (it provides the accessibility foundation — reduce motion support).
+
+**Visual liveliness rule:** For apps that should feel vibrant and alive (most consumer apps — shopping, social, food, fitness, travel, art, music, creative, lifestyle), automatically include **MicroInteractions** (press feedback, bounces) unless the domain explicitly demands restraint (medical, legal, finance). This ensures every app gets basic visual polish through press feedback and toggle animations.
+
+#### Step 10 — Final Module List
+
+Produce the final list of selected modules with reasoning for each.
+
+## Report Output
+
+Write the report to `output/{app-name}/reports/02-catalog-analysis.md`:
+
+```markdown
+# Catalog Analysis Report
+
+**Step:** 0
+**Skill:** catalog-analyzer
+**Timestamp:** {ISO 8601}
+**Result:** PASS
+
+## Template Selection
+
+**Selected Template:** {TemplateName}
+**Confidence:** high | medium | low
+
+### Reasoning
+
+{2-3 sentences explaining why this template was chosen}
+
+### Scoring
+
+| Template | Score | Match Criteria | Exclusions |
+|----------|-------|---------------|------------|
+| {name}   | {/10} | {matched}     | {any}      |
+
+### Hybrid Recommendation
+
+**Borrow From:** {other template name} or "none"
+**Hybrid Notes:** {what to borrow and why} or "n/a"
+
+## Module Selection — {N} total
+
+| Module | Matched Keywords | Template Boost | Reason |
+|--------|-----------------|----------------|--------|
+| {name} | {keywords}      | yes/no         | {why included} |
+...
+
+### Excluded Modules
+
+| Module | Reason for Exclusion |
+|--------|---------------------|
+...
+
+### Dependencies Added
+
+| Module | Added Because |
+|--------|--------------|
+| {name} | Required by {other module} |
+...
+```
+
+Update `output/{app-name}/reports/summary.json` — read the file, append this step.
+
+**Timing:** Record the current timestamp when you begin this skill. When writing the step entry, set `"startedAt"` to that timestamp (ISO 8601) and `"durationSeconds"` to the elapsed seconds.
+
+```json
+{
+  "step": 0,
+  "name": "catalog-analysis",
+  "startedAt": "{ISO 8601 timestamp}",
+  "durationSeconds": 0,
+  "result": "PASS",
+  "reportFile": "02-catalog-analysis.md",
+  "template": "{TemplateName}",
+  "confidence": "high|medium|low",
+  "borrowFrom": "{other template or null}",
+  "modulesSelected": {N}
+}
+```
+
+Also update the top-level `"template"` field in summary.json.
+
+## Important Rules
+
+- This skill is READ-ONLY — do NOT create, edit, or delete any app source files during this step
+- The ONLY files you write are the report files in `reports/`
+- Always recommend exactly ONE primary template
+- If confidence is "low", explain what aspects don't fit well
+- Do NOT recommend building from scratch — always pick the closest template
+- Consider the platform when relevant — all templates are available on iOS, Android, and React Native
+- For React Native, templates use TypeScript + React Navigation + custom hooks (MVVM-hook pattern)
+- Features covered by shared modules should NOT affect template scoring — they are handled in Phase 2
+- No modules are auto-included — every module must earn its place via keyword matching (exception: MotionPreferences is auto-included when any animation/sensory module is selected)
+- Aim for 5-15 modules — be selective, not exhaustive
+- Module integration happens later during customization (Steps 4-5) — this skill only produces the selection list
+- The "Relevant Templates" column is a **boost signal**, not a hard filter — a module can be selected without template match if keywords are strong

package/.cursor/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), `features/` (Android), or `src/screens/` (React Native)
 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
 
@@ -165,7 +165,7 @@ DATA REPOSITORY:
 
 ### 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:
 
 ```
 MODULE INTEGRATION PLAN:
@@ -271,6 +271,39 @@ 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 |
+| Floating element shadow | {deeper: blur Xpt, y Xpt} |
+
+#### 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} |
+| Spring response | {X}s |
+| Spring damping | {X} |
+| Stagger delay | {X}ms per item |
+| Press scale | {0.95} |
+| Button feedback | {scale + haptic (light)} |
+| Favorite toggle | {heart bounce + haptic} |
+| Success event | {confetti / sparkle / none} |
+
+#### Depth & Material
+- Sheet backgrounds: {glass blur / solid / gradient}
+- Navigation bar: {transparent+blur / solid / gradient}
+- Tab bar: {blur / solid / elevated}
+
 ### Icon Mapping — Tabs
 | Tab | Label | iOS (SF Symbol) | Android (Material) |
 |-----|-------|-----------------|-------------------|
@@ -364,11 +397,25 @@ Write the complete manifest to `output/{app-name}/reports/customization-manifest
 {List selected animation/sensory modules and their purpose in this app}
 
 ### Per-Screen Animation Modifiers
+
+**Built-in modifiers (always available, no module required):**
+- `.staggeredAppear(index:)` — staggered fade+slide for list items
+- `.slideIn()` — slide-from-bottom on appear
+- `.slideAndFade()` — slide-from-side + fade on appear
+- `.scaleOnPress()` — scale-down press feedback (0.95 + spring)
+- `.hapticFeedback()` / `.hapticFeedback(.medium)` — haptic on tap
+- `.bounceOnChange(isActive:)` — scale bounce on state toggle
+- `.cardShadow()` — subtle shadow for cards/elevated surfaces
+- `.elevatedShadow()` — deeper shadow for FABs/floating elements
+- `.shimmer()` — shimmer loading overlay for skeleton/placeholder views
+- `.pulse()` — repeating scale pulse for live indicators, notification badges
+- `.heartBounce(isActive:)` — bounce-on-activate for favorite/like buttons
+
 | Screen File | Modifiers to Apply | Notes |
 |---|---|---|
-| HomeView.swift | `.staggeredAppearance()`, `.hapticFeedback(.selection)` | List items stagger in on appear |
-| DetailView.swift | `.slideAndFade()`, `.parallaxHeader()` | Hero image parallax, content slides in |
-| CreateView.swift | `.scaleOnPress()`, `.hapticFeedback(.success)` on save | Button feedback |
+| HomeView.swift | `.staggeredAppear(index:)`, `.cardShadow()` | List items stagger in, cards have shadows |
+| DetailView.swift | `.slideAndFade()`, `.cardShadow()` | Content slides in with shadows |
+| CreateView.swift | `.scaleOnPress()`, `.hapticFeedback(.medium)` on save | Button feedback |
 | {screen} | {modifiers} | {notes} |
 ...
 

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

@@ -9,7 +9,7 @@ Use this skill to select the best visual design brand for the user's app.
 
 ## When to Use
 
-- At Step 4a of the AppAgent workflow, after the template is cloned and renamed
+- At Step 0 of the AppAgent workflow, in parallel with prompt validation and catalog analysis
 - When you need to pick a visual identity from the design brand catalog
 - Before applying design tokens to the app
 
@@ -18,7 +18,7 @@ Use this skill to select the best visual design brand for the user's app.
 - **App name** — display name (e.g., "PawSpa")
 - **App description** — what the app does and who it's for
 - **Platform** — `ios` or `android`
-- **App template** — which template was selected (e.g., "BookTemplate")
+- **App template** (optional) — which template was selected, if available (may not be when running in parallel)
 - **User style preferences** — any explicit color, style, or visual direction the user mentioned (may be empty)
 
 ## Instructions
@@ -40,6 +40,7 @@ For each brand in the catalog:
 3. Apply "NOT a match when" exclusion rules
 4. Follow the "Brand Selection Guide" decision flow
 5. Consider the "Hybrid Brands" table if the app spans categories
+6. **Energy bias**: When multiple brands score equally, prefer the one with higher Energy score (from the catalog's decision matrix). For ambiguous domains (not explicitly medical, finance, or corporate), bias toward brands with Energy >= 3. Apps should feel vibrant and alive by default — only choose low-energy brands when the domain clearly demands restraint.
 
 ### Step 3 — Handle User Style Preferences
 
@@ -59,7 +60,7 @@ Write the report to `output/{app-name}/reports/03-design-brand.md`:
 ```markdown
 # Design Brand Report
 
-**Step:** 4
+**Step:** 0
 **Skill:** design-selector
 **Timestamp:** {ISO 8601}
 **Result:** PASS
@@ -99,7 +100,7 @@ Update `output/{app-name}/reports/summary.json` — read the file, append this s
 
 ```json
 {
-  "step": 4,
+  "step": 0,
   "name": "design-brand",
   "startedAt": "{ISO 8601 timestamp}",
   "durationSeconds": 0,
@@ -121,4 +122,4 @@ Also update the top-level `"designBrand"` field in summary.json.
 - Do NOT recommend building a custom brand from scratch — always start with a catalog brand
 - If the user mentioned specific colors, put them in adaptations — never ignore user style preferences
 - The brand file path must use the exact filename from the catalog (kebab-case .md)
-- Consider the app template when relevant — a FinanceTemplate naturally pairs with CorporateProfessional, but can be overridden
+- If the app template is available, consider it as a weak hint — a FinanceTemplate naturally pairs with CorporateProfessional, but the user description keywords are the primary signal

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

@@ -9,9 +9,9 @@ Use this skill to produce a complete design brief for a newly cloned app. The pr
 
 ## When to Use
 
-- After the `design-selector` subagent has picked a brand (Step 4a complete)
-- Before AppConfig customization (Step 6) — the design brief feeds into CUSTOMIZE:THEME
-- Before the platform customizer runs (Step 8) — it applies the tokens to code
+- After the `design-selector` subagent has picked a brand (Step 0 complete)
+- Before AppConfig customization (Step 4) — the design brief feeds into CUSTOMIZE:THEME
+- Before the platform customizer runs (Step 5) — it applies the tokens to code
 
 ## What You Produce
 
@@ -39,8 +39,9 @@ If the `design-selector` provided a brand:
 3. Extract layout tokens (corner radius, spacing scale, card elevation, border width)
 4. Extract typography settings (font family, heading weight, body weight, body size)
 5. Extract icon style preferences (filled vs outlined, line weight)
-6. Note any brand-specific do's, don'ts, and overrides
-7. Note any ADAPT suggestions from the design-selector
+6. Extract **Motion & Effects** tokens (default spring, press scale, stagger delay, shadow style, gradient usage, depth approach, haptic policy)
+7. Note any brand-specific do's, don'ts, and overrides
+8. Note any ADAPT suggestions from the design-selector
 
 **If the design-selector suggested adaptations** (in the ADAPT field):
 - Apply color overrides (e.g., "shift primary to teal for pet domain")
@@ -256,7 +257,7 @@ ACCESSIBILITY:
 
 After producing the design brief, the tokens are applied to specific files in subsequent steps. All templates follow a standardized theme structure:
 
-### iOS (applied by ios-customizer in Step 8)
+### iOS (applied by ios-customizer in Step 5)
 
 | Token Category | File | Structure |
 |---------------|------|-----------|
@@ -268,7 +269,7 @@ After producing the design brief, the tokens are applied to specific files in su
 | Domain-specific colors | `Core/Theme/Colors.swift` | Semantic color tokens (e.g., `Color.incomeColor`, `Color.starFilled`) |
 | Gradient definitions | `Core/Theme/Colors.swift` | `LinearGradient` extensions |
 
-### Android (applied by android-customizer in Step 8)
+### Android (applied by android-customizer in Step 5)
 
 | Token Category | File | Structure |
 |---------------|------|-----------|

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