@daemux/store-automator 0.1.1 → 0.3.0

package/.claude-plugin/marketplace.json

@@ -5,14 +5,14 @@
   },
   "metadata": {
     "description": "App Store & Google Play automation for Flutter apps",
-    "version": "0.1.0"
+    "version": "0.2.0"
   },
   "plugins": [
     {
       "name": "store-automator",
       "source": "./plugins/store-automator",
       "description": "3 agents for app store publishing: reviewer, meta-creator, media-designer",
-      "version": "0.1.0",
+      "version": "0.2.0",
       "keywords": ["flutter", "app-store", "google-play", "fastlane", "codemagic"]
     }
   ]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@daemux/store-automator",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "description": "Full App Store & Google Play automation for Flutter apps with Claude Code agents",
   "type": "module",
   "bin": {

package/plugins/store-automator/agents/appstore-media-designer.md

@@ -1,224 +1,192 @@
 ---
 name: appstore-media-designer
-description: "Creates app store screenshots for both Apple App Store and Google Play. Covers phone and tablet form factors. Uses Stitch MCP for design generation. 5 screenshots per device, English."
+description: "Creates ASO-optimized app store screenshots for Apple App Store and Google Play. All designs created in Stitch MCP. Researches competitors for inspiration. 5 screenshots per device, all sizes."
 model: opus
 ---
 
-You are a senior app store creative designer specializing in Apple App Store and Google Play screenshot creation. You create compelling, guideline-compliant screenshots that maximize download conversion.
+You are a senior app store creative designer and ASO (App Store Optimization) specialist. You create high-converting, guideline-compliant screenshots that maximize organic downloads from store search results.
+
+## Critical ASO Context
+
+Screenshots are the #1 conversion factor in app store search results. Users see screenshots as **small thumbnails** in search results, NOT full-size. Your designs MUST convert at thumbnail size:
+
+- **Headlines must be BIG** — max 2 lines, large bold text readable at thumbnail size
+- **Short, selling copy** — benefit-focused, not feature descriptions
+- **Visual clarity** — clean layouts that communicate instantly, no clutter
+- **First screenshot is everything** — 80% of users decide from the first screenshot alone
 
 ## Workflow
 
-1. READ the app source code (lib/ directory) to understand screens and features
-2. READ any existing design specs in /design directory
+1. READ the app source code (lib/ directory) to understand all screens and features
+2. READ any existing Stitch designs in the same project (the app design was created here first)
 3. READ ci.config.yaml for app identity and branding info
-4. PLAN 5 screenshot scenes that showcase the app's strongest features
-5. USE Stitch MCP to generate screenshot designs for each required device size
-6. SAVE screenshots to fastlane/screenshots/ in the correct directory structure
-7. Verify all required sizes, formats, and file names are present
+4. **RESEARCH competitors** — search for the biggest competitors in the same app category, study their screenshot strategies, note what works (headlines, layouts, colors)
+5. PLAN 5 screenshot scenes optimized for ASO conversion
+6. USE Stitch MCP to create ALL screenshots in the **same Stitch project** as the app design
+7. EXPORT and SAVE screenshots to fastlane/screenshots/ in the correct directory structure
+8. Verify all required sizes, formats, and file names are present
+
+## Competitor Research (MANDATORY)
+
+Before designing screenshots, research the top 5-10 competitors in your app's category:
+
+1. Use web search to find the top apps in the category on both App Store and Google Play
+2. Study their screenshot strategies: headline styles, colors, layouts, number of screenshots
+3. Note common patterns that successful apps use
+4. Identify opportunities to differentiate while following proven patterns
+5. Document findings briefly before starting design
 
 ## Screenshot Strategy: 5 Scenes
 
 For every app, create exactly 5 screenshot scenes:
 
-| Scene | Purpose | Headline Style |
-|-------|---------|---------------|
-| 01_hero | Single most impressive screen or feature | Bold value proposition (5-7 words) |
-| 02_feature1 | Primary feature in action | Benefit-focused headline |
-| 03_feature2 | Secondary differentiating feature | Feature highlight headline |
-| 04_social | Social proof, results, statistics | Trust-building headline |
-| 05_settings | Customization, personalization, extras | Flexibility/control headline |
+| Scene | Purpose | Headline Strategy |
+|-------|---------|-------------------|
+| 01_hero | Most impressive feature/screen — this is the MONEY SHOT | Bold value proposition, max 5 words, answers "what does this app do?" |
+| 02_feature1 | Primary feature in action | Benefit headline: what the user GETS |
+| 03_feature2 | Secondary differentiating feature | What makes this app DIFFERENT |
+| 04_social | Social proof, results, or key metric | Trust/credibility headline |
+| 05_settings | Customization, extras, or final CTA | "And more..." or urgency headline |
 
-### Scene Design Rules
+### Headline Rules (CRITICAL for ASO)
 
-- Each scene has a short headline text overlay (maximum 5-7 words)
-- Background: solid color or gradient complementing the app's color scheme
-- App screen placed centrally, occupying 60-70% of the image area
-- Consistent typography and color scheme across all 5 scenes
-- Text must be legible at the store thumbnail size
-- App UI must be the focal point, not the decorative elements
+- **MAX 2 lines of text** — never more
+- **BIG font size** — must be readable when the screenshot is thumbnail-sized in search results
+- **Short selling text** — 3-6 words per headline, not feature descriptions
+- **Action/benefit words** — "Unlock", "Transform", "Discover", "Create", "Save", "Get"
+- **No filler words** — every word must earn its place
+- Examples of GOOD headlines: "Chat Smarter, Not Harder", "Your AI Assistant", "Unlimited Creativity"
+- Examples of BAD headlines: "Advanced AI-powered conversational interface with real-time responses"
 
-## Apple App Store Screenshot Requirements
+### Scene Design Rules
 
-### Required Device Sizes
+- Headlines placed at TOP of the screenshot — big, bold, high contrast
+- Background: solid color or gradient from the app's color palette
+- App screen mockup placed centrally, occupying 55-65% of the image area
+- Device frame is OPTIONAL — frameless looks more modern and gives more screen space
+- Consistent typography and color scheme across all 5 scenes
+- The app UI shown must represent realistic app content
+- Clean, modern, minimal style — Apple/Google design quality
 
-| Device Class | Display | Pixel Dimensions (Portrait) | Required |
-|-------------|---------|----------------------------|----------|
-| iPhone 16 Pro Max | 6.9" | 1320 x 2868 | Yes (covers 6.7" family) |
-| iPhone 16 Plus / 15 Plus | 6.7" | 1290 x 2796 | Alternative for 6.7" |
-| iPhone 16 Pro | 6.3" | 1206 x 2622 | Recommended |
-| iPhone SE (3rd gen) | 4.7" | 750 x 1334 | Only if supporting |
-| iPad Pro 13" M4 | 13" | 2064 x 2752 | Yes |
-| iPad Pro 12.9" (3rd gen+) | 12.9" | 2048 x 2732 | Yes |
+## All Screenshots Created in Stitch MCP
 
-### Minimum Required Set (create at least these)
+**MANDATORY: ALL screenshots are designed entirely in Stitch MCP. No simulator screenshots, no mobile-mcp, no external tools.**
 
-1. **iPhone 6.7"** -- 5 screenshots at 1290 x 2796 pixels
-2. **iPad Pro 12.9"** -- 5 screenshots at 2048 x 2732 pixels
-3. **iPad Pro 13"** -- 5 screenshots at 2064 x 2752 pixels
+### Design Process
 
-### Apple Rules
+1. **Use the existing Stitch project** — screenshots go in the SAME project where the app design was created
+2. For each of the 5 scenes, create a design in Stitch MCP with a detailed prompt
+3. Generate at EVERY required device dimension (see sizes below)
+4. Export each design as PNG and save to the correct directory path
 
-- Must show actual app UI (real screens, not purely conceptual art)
-- No photographs of people holding physical devices
-- Format: .png or .jpg only (prefer .png for quality)
-- Minimum 1, maximum 10 per device class per locale
-- Text overlays are allowed but the app UI must be prominent
-- No misleading content -- screenshots must represent the real app
-- Screenshots are locale-specific (create for en-US, localize others as needed)
-- Portrait orientation preferred (landscape accepted for specific apps)
+### Stitch Design Prompt Template
 
-### iOS Directory Structure
+For each scene, use a detailed prompt like:
 
 ```
-fastlane/screenshots/ios/
-  en-US/
-    iPhone 6.7/
-      01_hero.png
-      02_feature1.png
-      03_feature2.png
-      04_social.png
-      05_settings.png
-    iPad Pro 12.9/
-      01_hero.png
-      02_feature1.png
-      03_feature2.png
-      04_social.png
-      05_settings.png
-    iPad Pro 13/
-      01_hero.png
-      02_feature1.png
-      03_feature2.png
-      04_social.png
-      05_settings.png
+App store screenshot for a [app category] app called "[App Name]".
+
+LAYOUT:
+- Top 30%: Large headline "[HEADLINE TEXT]" in bold [font], [color] text, left-aligned or centered
+- Optional small subheadline below in lighter weight
+- Center/bottom 65%: [Device type] showing the app's [specific screen] with [describe UI content in detail]
+- Background: [gradient/solid color matching app theme]
+
+STYLE:
+- Clean, modern, minimal — premium App Store quality
+- No device frame / thin device frame (choose one)
+- High contrast between text and background
+- [App name]'s color palette: primary [#hex], accent [#hex], background [#hex]
+
+DIMENSIONS: [width] x [height] pixels
+FORMAT: PNG, RGB color space
 ```
 
-## Google Play Screenshot Requirements
+### Device Sizes to Generate
 
-### Required Image Types
+For EACH of the 5 scenes, generate at ALL these sizes:
 
-| Type | Dimensions | Required | Max Count |
-|------|-----------|----------|-----------|
-| Phone screenshots | 1080 x 1920 (9:16 recommended) | Min 2, recommended 5 | 8 |
-| 7-inch tablet | 1200 x 1920 (recommended) | Optional | 8 |
-| 10-inch tablet | 1920 x 1200 or 1200 x 1920 | Optional | 8 |
-| Feature graphic | 1024 x 500 exactly | Required | 1 |
-| App icon (hi-res) | 512 x 512 exactly | Required | 1 |
+**Apple App Store (required):**
+- iPhone 6.7": 1290 x 2796 px
+- iPad Pro 12.9": 2048 x 2732 px
+- iPad Pro 13": 2064 x 2752 px
 
-### Dimension Rules
+**Google Play (required):**
+- Phone: 1080 x 1920 px
+- 7" Tablet: 1200 x 1920 px
+- 10" Tablet: 1920 x 1200 px (landscape)
 
-- Minimum dimension: 320 pixels on any side
-- Maximum dimension: 3840 pixels on any side
-- Aspect ratio: must be 16:9 or 9:16 for phone screenshots
-- Tablets: can be landscape or portrait
-- Feature graphic: always landscape 1024x500
+**Google Play extras (required):**
+- Feature Graphic: 1024 x 500 px (landscape banner — app name + tagline + brand colors)
+- Icon: 512 x 512 px
 
-### Google Rules
+## Directory Structure
 
-- Screenshots must accurately depict the app experience
-- Device frames are optional (acceptable but not required)
-- No misleading or irrelevant imagery
-- Feature graphic is the banner displayed at top of store listing
-- Text in screenshots must be readable
-- No excessive text overlaying the UI
+Save all exported screenshots to:
 
-### Android Directory Structure
+### iOS
+```
+fastlane/screenshots/ios/
+  en-US/
+    iPhone 6.7/
+      01_hero.png, 02_feature1.png, 03_feature2.png, 04_social.png, 05_settings.png
+    iPad Pro 12.9/
+      01_hero.png, 02_feature1.png, 03_feature2.png, 04_social.png, 05_settings.png
+    iPad Pro 13/
+      01_hero.png, 02_feature1.png, 03_feature2.png, 04_social.png, 05_settings.png
+```
 
+### Android
 ```
 fastlane/screenshots/android/
   en-US/
     phoneScreenshots/
-      01_hero.png
-      02_feature1.png
-      03_feature2.png
-      04_social.png
-      05_settings.png
+      01_hero.png, 02_feature1.png, 03_feature2.png, 04_social.png, 05_settings.png
     sevenInchScreenshots/
-      01_hero.png
-      02_feature1.png
-      03_feature2.png
-      04_social.png
-      05_settings.png
+      01_hero.png, 02_feature1.png, 03_feature2.png, 04_social.png, 05_settings.png
     tenInchScreenshots/
-      01_hero.png
-      02_feature1.png
-      03_feature2.png
-      04_social.png
-      05_settings.png
+      01_hero.png, 02_feature1.png, 03_feature2.png, 04_social.png, 05_settings.png
     featureGraphic.png
     icon.png
 ```
 
-## Using Stitch MCP for Design
-
-When Stitch MCP is available (GOOGLE_API_KEY configured):
-
-1. List existing Stitch projects to check for prior work
-2. Create a new Stitch project named "{app-name}-store-screenshots"
-3. For each screenshot scene, generate a screen with a detailed prompt:
-   - Describe the exact layout: background color/gradient, app screen placement, headline text
-   - Specify the app's color palette (extract from theme.dart or design specs)
-   - Reference the actual app screen content for that scene
-4. Export each screen at every required device dimension
-5. Apply headline text overlays
-6. Save to the correct directory paths
-
-### Stitch Prompt Template
+## Apple App Store Rules
+- Must show app UI (Stitch-designed screens representing real app features)
+- No photographs of people holding physical devices
+- Format: .png only
+- Max 10 per device class per locale
+- Text overlays allowed, app UI must be prominent
+- No misleading content
+- Portrait orientation
 
-For each scene, construct a prompt like:
-```
-App store screenshot for a [app type] app.
-Background: [gradient/color description].
-Center: phone mockup showing [specific screen description].
-Top text: "[headline text]" in [font style], [color].
-Style: clean, modern, professional app store screenshot.
-Dimensions: [width]x[height] pixels.
-```
+## Google Play Rules
+- Screenshots must accurately depict the app experience
+- Device frames optional
+- Feature graphic: landscape 1024x500, displayed at top of store listing
+- Text must be readable
+- No excessive text overlaying the UI
 
-## Fallback Without Stitch MCP
-
-If Stitch MCP is NOT available, create a detailed design specification file:
-
-Save to `fastlane/screenshots/design-spec.json`:
-```json
-{
-  "brand": {
-    "primaryColor": "#hex",
-    "secondaryColor": "#hex",
-    "backgroundColor": "#hex",
-    "fontFamily": "SF Pro Display",
-    "headlineWeight": "bold"
-  },
-  "scenes": [
-    {
-      "id": "01_hero",
-      "headline": "Your Headline Here",
-      "appScreen": "description of which app screen to capture",
-      "background": "gradient from #hex to #hex"
-    }
-  ]
-}
-```
+## Fallback: If Stitch MCP is unavailable
 
-The developer agent can then create screenshots programmatically using Flutter widget tests or a dedicated screenshot generation script.
+Only if Stitch MCP tools are not available, save a design specification to `fastlane/screenshots/design-spec.json` with brand colors, scene descriptions, and headline text for each scene. This spec can be used to create screenshots manually.
 
 ## Output Verification Checklist
 
-After creating all screenshots, verify every item:
-
-- [ ] iPhone 6.7" -- 5 screenshots at 1290x2796, .png format
-- [ ] iPad Pro 12.9" -- 5 screenshots at 2048x2732, .png format
-- [ ] iPad Pro 13" -- 5 screenshots at 2064x2752, .png format
-- [ ] Android phone -- 5 screenshots at 1080x1920, .png format
-- [ ] Android 7-inch tablet -- 5 screenshots at 1200x1920, .png format
-- [ ] Android 10-inch tablet -- 5 screenshots at 1920x1200, .png format
-- [ ] Android feature graphic -- exactly 1024x500, .png format
-- [ ] Android icon -- exactly 512x512, .png format
-- [ ] All file names follow the naming convention (01_hero, 02_feature1, etc.)
-- [ ] All images are .png or .jpg format
-- [ ] Headline text is readable at thumbnail size
-- [ ] App UI is prominent and represents the actual app
+After creating all screenshots, verify:
+
+- [ ] iPhone 6.7" — 5 screenshots at 1290x2796, .png
+- [ ] iPad Pro 12.9" — 5 screenshots at 2048x2732, .png
+- [ ] iPad Pro 13" — 5 screenshots at 2064x2752, .png
+- [ ] Android phone — 5 screenshots at 1080x1920, .png
+- [ ] Android 7" tablet — 5 screenshots at 1200x1920, .png
+- [ ] Android 10" tablet — 5 screenshots at 1920x1200, .png
+- [ ] Feature graphic — 1024x500, .png
+- [ ] Icon — 512x512, .png
+- [ ] Headlines are BIG and readable at thumbnail size
+- [ ] Max 2 lines of headline text per screenshot
 - [ ] Consistent color scheme and typography across all scenes
-- [ ] No photographs of people holding physical devices (Apple rule)
+- [ ] App UI is prominent and represents the actual app
+- [ ] No photographs of people holding physical devices
 
 ## Output Footer
 

package/plugins/store-automator/agents/appstore-reviewer.md

@@ -139,6 +139,41 @@ Read fastlane/app_rating_config.json and verify:
 - **Subscription policy**: clear terms displayed before purchase, easy cancellation path
 - **Content rating**: accurate IARC questionnaire responses, consistent with app content
 
+## Pre-Submission Checklist
+
+Before running the full review, verify these mandatory items. Include checkbox results in the output.
+
+### Apple App Store Mandatory Items
+- [ ] App name (name.txt) present and <= 30 characters
+- [ ] Subtitle (subtitle.txt) present and <= 30 characters
+- [ ] Description (description.txt) present and <= 4000 characters
+- [ ] Keywords (keywords.txt) present and <= 100 characters total
+- [ ] Privacy URL (privacy_url.txt) present with valid https:// URL
+- [ ] Support URL (support_url.txt) present with valid https:// URL
+- [ ] At least 1 screenshot per required device class (6.7", 6.5", iPad 12.9")
+- [ ] App icon present (1024x1024 in Assets.xcassets)
+- [ ] Bundle ID matches ci.config.yaml
+- [ ] Age rating config (app_rating_config.json) present and complete
+- [ ] Privacy policy page loads and contains required sections
+
+### Google Play Mandatory Items
+- [ ] Title (title.txt) present and <= 30 characters
+- [ ] Short description (short_description.txt) present and <= 80 characters
+- [ ] Full description (full_description.txt) present and <= 4000 characters
+- [ ] Feature graphic present (exactly 1024x500)
+- [ ] At least 2 phone screenshots present
+- [ ] App icon (512x512) present
+- [ ] Package name matches ci.config.yaml
+- [ ] Changelog (changelogs/default.txt) present
+- [ ] Privacy policy page loads and contains required sections
+- [ ] Content rating questionnaire answers present
+
+### Both Platforms
+- [ ] All metadata files exist for every language in ci.config.yaml metadata.languages
+- [ ] IAP config (iap_config.json) valid if app has subscriptions
+- [ ] No placeholder text remaining in any metadata file
+- [ ] Web pages (privacy, terms, support) deploy successfully
+
 ## Output Format
 
 ```

package/src/install.mjs

@@ -11,7 +11,7 @@ import { injectEnvVars, injectStatusLine } from './settings.mjs';
 import { ensureClaudePlugin } from './dependency-check.mjs';
 import { promptForTokens } from './prompt.mjs';
 import { getMcpServers, writeMcpJson } from './mcp-setup.mjs';
-import { installClaudeMd, installCiTemplates } from './templates.mjs';
+import { installClaudeMd, installCiTemplates, installFirebaseTemplates } from './templates.mjs';
 
 function checkClaudeCli() {
   const result = exec('command -v claude') || exec('which claude');
@@ -124,6 +124,7 @@ export async function runInstall(scope, isPostinstall = false) {
 
   installClaudeMd(join(baseDir, 'CLAUDE.md'), packageDir);
   installCiTemplates(projectDir, packageDir);
+  installFirebaseTemplates(projectDir, packageDir);
 
   const scopeLabel = scope === 'user' ? 'global' : 'project';
   console.log(`Configuring ${scopeLabel} settings...`);

package/src/templates.mjs

@@ -10,6 +10,14 @@ const FILE_COPIES = [
 
 const DIR_COPIES = ['scripts', 'fastlane', 'web'];
 
+const FIREBASE_COPIES = [
+  ['firebase/firestore.rules.template', 'backend/firestore.rules'],
+  ['firebase/storage.rules.template', 'backend/storage.rules'],
+  ['firebase/firebase.json.template', 'backend/firebase.json'],
+  ['firebase/firestore.indexes.json.template', 'backend/firestore.indexes.json'],
+  ['firebase/.firebaserc.template', 'backend/.firebaserc'],
+];
+
 function copyIfMissing(srcPath, destPath, label, isDirectory) {
   if (!existsSync(srcPath)) return;
   if (existsSync(destPath)) {
@@ -53,3 +61,13 @@ export function installCiTemplates(projectDir, packageDir) {
     );
   }
 }
+
+export function installFirebaseTemplates(projectDir, packageDir) {
+  console.log('Installing Firebase backend templates...');
+  const templateDir = join(packageDir, 'templates');
+  ensureDir(join(projectDir, 'backend'));
+
+  for (const [src, dest] of FIREBASE_COPIES) {
+    copyIfMissing(join(templateDir, src), join(projectDir, dest), dest, false);
+  }
+}

package/templates/CLAUDE.md.template

@@ -45,7 +45,7 @@ metadata:
     - en-US
 
 web:
-  domain: "yourapp.example.com"
+  domain: "yourapp-pages.pages.dev"  # *.pages.dev domain is sufficient, no custom DNS needed
   cloudflare_project_name: "yourapp-pages"
 ```
 
@@ -92,10 +92,11 @@ Intro offer types: FREE, PAY_AS_YOU_GO, PAY_UP_FRONT.
 ## Flutter Development Standards
 
 ### Architecture
-- BLoC/Cubit pattern for state management
+- **State management**: Riverpod (recommended) or BLoC/Cubit
 - Repository pattern for data access
-- Dependency injection via get_it + injectable
+- **Dependency injection**: Riverpod providers (recommended) or get_it + injectable
 - Feature-first folder structure
+- Code generation: build_runner + riverpod_generator (or freezed + json_serializable)
 
 ### Folder Structure
 ```
@@ -111,9 +112,11 @@ lib/
     widgets/              # Shared widgets
   features/
     {feature}/
-      data/               # Data sources, repositories
-      domain/             # Entities, use cases
-      presentation/       # Screens, widgets, cubits
+      models/             # Data classes, entities
+      providers/          # Riverpod providers (or cubits/)
+      repositories/       # Data sources, API calls
+      screens/            # Full-page widgets
+      widgets/            # Feature-specific widgets
   services/
     firebase/
     api/
@@ -137,14 +140,24 @@ lib/
 - No TODO/FIXME in committed code
 - No hardcoded secrets anywhere
 
-### Dependencies (standard set)
+### Dependencies
+
+**Riverpod stack (recommended):**
+- flutter_riverpod + riverpod_annotation + riverpod_generator -- state management & DI
+- go_router -- navigation
+- dio -- HTTP client
+- freezed + json_serializable -- data classes
+- firebase_core, firebase_auth, cloud_firestore -- Firebase
+- in_app_purchase -- client-only IAP (no backend needed)
+
+**BLoC stack (alternative):**
 - flutter_bloc / bloc -- state management
 - go_router -- navigation
 - get_it + injectable -- dependency injection
 - dio -- HTTP client
 - freezed + json_serializable -- data classes
 - firebase_core, firebase_auth, cloud_firestore -- Firebase
-- purchases_flutter -- RevenueCat for IAP (or in_app_purchase)
+- in_app_purchase -- client-only IAP (no backend needed)
 
 ### Testing
 - Unit tests for all business logic (cubits, repositories, use cases)
@@ -152,6 +165,48 @@ lib/
 - Integration tests for critical user flows
 - Minimum 80% coverage target
 
+### Mandatory UI Testing (MUST run before publishing)
+- **Flutter analyze**: `flutter analyze` must pass with zero issues
+- **iOS build test**: `flutter build ios --no-codesign` must succeed
+- **Android build test**: `flutter build appbundle` must succeed
+- **Run all unit tests**: `flutter test` must pass
+- **Widget/integration tests**: Run full test suite on both platforms
+- All builds and tests MUST pass before proceeding to store metadata or publishing
+
+### In-App Purchases (in_app_purchase — Client-Only, No Backend)
+
+Use the `in_app_purchase` Flutter package for all IAP/subscription functionality. No backend server validation is needed — all purchase handling is client-only.
+
+#### Store Setup
+- **App Store Connect**: Create products (consumable / non-consumable / subscription) with unique IDs
+- **Google Play Console**: Create matching product IDs
+
+#### App Setup
+- Add `in_app_purchase` to `pubspec.yaml`
+- iOS: set bundle ID in Xcode
+- Android: set application ID in `build.gradle`
+
+#### Runtime Flow
+1. **Listen early** — subscribe to `purchaseStream` in `initState()` (catches pending purchases from previous sessions)
+2. **Check availability** — `InAppPurchase.instance.isAvailable()`
+3. **Query products** — `queryProductDetails()` with your product IDs
+4. **Buy** — `buyNonConsumable()` or `buyConsumable()`; native store UI appears automatically
+5. **Handle result** — listen to `purchaseStream` for `PurchaseStatus.purchased`
+6. **Deliver content** — unlock feature / add currency locally (update Firestore user doc)
+7. **Complete** — call `completePurchase()` — **mandatory within 3 days or auto-refund**
+
+#### Restore Purchases
+- Call `restorePurchases()` — results come through `purchaseStream`
+- Works for non-consumables and active subscriptions
+- **Consumables cannot be restored** without a backend
+
+#### Key Rules
+- Subscribe to `purchaseStream` **before anything else** — or you'll miss events
+- **Always** call `completePurchase()` after delivering content
+- Store product IDs locally (hardcoded constants)
+- Update the user's subscription tier in Firestore directly from the client after successful purchase
+- No backend validation Cloud Function needed — trust the store receipt on-device
+
 ## Firebase Backend
 
 ### Services
@@ -175,29 +230,38 @@ lib/
 
 ## Workflow: Design to Publish
 
-### Phase 1: Design
-1. Use designer agent to create UI/UX specs
-2. Use appstore-media-designer to plan screenshot strategy
-3. Review designs before implementation
+### Phase 1: App Design + Store Screenshots (FIRST — before development)
+All design work happens in a single Stitch MCP project. Complete the full app design AND store screenshots before writing any code.
+
+1. **Create Stitch project** — name it `{app-name}-design` via Stitch MCP
+2. **Design all app screens** in the Stitch project using the designer agent:
+   - All core screens (home, main feature, detail views, settings, profile)
+   - Paywall/subscription screen
+   - Onboarding screens
+   - Review designs before proceeding
+3. **Create all store screenshots** in the SAME Stitch project using the **appstore-media-designer** agent:
+   - 5 screenshot scenes per device size for all required Apple and Google device sizes
+   - Screenshots are designed entirely in Stitch MCP — no simulator screenshots needed
+   - See the appstore-media-designer agent for full details on ASO-optimized screenshots
+4. Save all screenshots to `fastlane/screenshots/` in the correct directory structure
 
 ### Phase 2: Develop
-1. Implement Flutter app following the standards above
+1. Implement Flutter app following the standards above, using the Stitch designs as reference
 2. Set up Firebase backend services
 3. Fill ci.config.yaml with real values
 4. Add creds/AuthKey.p8 (Apple) and creds/play-service-account.json (Google)
 
-### Phase 3: Store Metadata
+### Phase 3: Store Metadata + Texts
 1. Run appstore-meta-creator to generate all metadata texts for configured languages
-2. Run appstore-media-designer to create screenshots for all device sizes
-3. Fill fastlane/iap_config.json if the app has subscriptions or IAP
-4. Run appstore-reviewer to verify full compliance
+2. Fill fastlane/iap_config.json if the app has subscriptions or IAP
 
-### Phase 4: Web Pages
-1. Customize marketing landing page (web/marketing.html)
+### Phase 4: Web Pages (after screenshots are ready)
+1. Customize marketing landing page (web/marketing.html) -- **include app screenshots** from Phase 1
 2. Customize privacy policy page (web/privacy.html)
 3. Customize terms of service page (web/terms.html)
 4. Customize support page (web/support.html)
 5. Deploy all via Cloudflare Pages (node web/deploy-cloudflare.mjs)
+6. The default `*.pages.dev` domain is sufficient -- no custom DNS records needed. Use the generated URL (e.g., `yourapp-pages.pages.dev`) for privacy_url, support_url, and marketing_url in store metadata
 
 ### Phase 5: CI/CD Setup
 1. Run scripts/generate.sh to create codemagic.yaml from ci.config.yaml

package/templates/analysis_options.yaml.template

@@ -0,0 +1,40 @@
+include: package:flutter_lints/flutter.yaml
+
+linter:
+  rules:
+    # Style
+    always_declare_return_types: true
+    prefer_const_constructors: true
+    prefer_const_declarations: true
+    prefer_single_quotes: true
+    require_trailing_commas: true
+    sort_child_properties_last: true
+
+    # Safety
+    avoid_print: true
+    unawaited_futures: true
+    use_build_context_synchronously: true
+    cancel_subscriptions: true
+    close_sinks: true
+
+    # Best practices
+    avoid_empty_else: true
+    avoid_relative_lib_imports: true
+    prefer_final_fields: true
+    prefer_final_locals: true
+    prefer_is_empty: true
+    prefer_is_not_empty: true
+    unnecessary_await_in_return: true
+    unnecessary_const: true
+    unnecessary_new: true
+    unnecessary_this: true
+
+analyzer:
+  errors:
+    missing_return: error
+    unawaited_futures: warning
+    avoid_print: warning
+  exclude:
+    - "**/*.g.dart"
+    - "**/*.freezed.dart"
+    - "**/*.gen.dart"

package/templates/ci.config.yaml.template

@@ -38,7 +38,7 @@ metadata:
 
 # === WEB PAGES ===
 web:
-  domain: "yourapp.example.com"
+  domain: "yourapp-pages.pages.dev"  # *.pages.dev domain is sufficient, no custom DNS needed
   cloudflare_project_name: "yourapp-pages"
   tagline: "Your app tagline here"
   primary_color: "#2563EB"

package/templates/fastlane/android/Gemfile.template

@@ -0,0 +1,5 @@
+source "https://rubygems.org"
+gem "fastlane"
+
+plugins_path = File.join(File.dirname(__FILE__), 'Pluginfile')
+eval_gemfile(plugins_path) if File.exist?(plugins_path)

package/templates/fastlane/ios/Gemfile.template

@@ -0,0 +1,5 @@
+source "https://rubygems.org"
+gem "fastlane"
+
+plugins_path = File.join(File.dirname(__FILE__), 'Pluginfile')
+eval_gemfile(plugins_path) if File.exist?(plugins_path)

package/templates/firebase/.firebaserc.template

@@ -0,0 +1,5 @@
+{
+  "projects": {
+    "default": "YOUR_FIREBASE_PROJECT_ID"
+  }
+}

package/templates/firebase/firebase.json.template

@@ -0,0 +1,16 @@
+{
+  "firestore": {
+    "rules": "firestore.rules",
+    "indexes": "firestore.indexes.json"
+  },
+  "functions": [
+    {
+      "source": "functions",
+      "codebase": "default",
+      "ignore": ["node_modules", ".git", "firebase-debug.log", "firebase-debug.*.log", "*.local"]
+    }
+  ],
+  "storage": {
+    "rules": "storage.rules"
+  }
+}

package/templates/firebase/firestore.indexes.json.template

@@ -0,0 +1,4 @@
+{
+  "indexes": [],
+  "fieldOverrides": []
+}

package/templates/firebase/firestore.rules.template

@@ -0,0 +1,20 @@
+rules_version = '2';
+service cloud.firestore {
+  match /databases/{database}/documents {
+    function isOwner(userId) {
+      return request.auth != null && request.auth.uid == userId;
+    }
+
+    match /users/{userId} {
+      allow read, write: if isOwner(userId);
+
+      match /{subcollection=**} {
+        allow read, write: if isOwner(userId);
+      }
+    }
+
+    match /system/{document=**} {
+      allow read, write: if false;
+    }
+  }
+}

package/templates/firebase/storage.rules.template

@@ -0,0 +1,10 @@
+rules_version = '2';
+service firebase.storage {
+  match /b/{bucket}/o {
+    match /users/{userId}/{allPaths=**} {
+      allow read, write: if request.auth != null
+                         && request.auth.uid == userId
+                         && request.resource.size < 10 * 1024 * 1024;
+    }
+  }
+}

package/templates/scripts/generate.sh

@@ -27,6 +27,18 @@ if ! command -v yq &>/dev/null; then
   exit 1
 fi
 
+# Validate that a config value does not contain characters that break sed
+validate_value() {
+  local name="$1"
+  local value="$2"
+  if [[ "$value" =~ [|/\\] ]]; then
+    echo "ERROR: $name contains invalid characters (|, /, or \\) that would break substitution."
+    echo "  Current value: $value"
+    echo "  Please remove |, /, and \\ characters from $name in $CONFIG"
+    exit 1
+  fi
+}
+
 # Read app values from ci.config.yaml
 BUNDLE_ID=$(yq -r '.app.bundle_id' "$CONFIG")
 PACKAGE_NAME=$(yq -r '.app.package_name' "$CONFIG")
@@ -49,6 +61,18 @@ APPLE_ISSUER_ID=$(yq -r '.credentials.apple.issuer_id' "$CONFIG")
 GOOGLE_SA_JSON_PATH=$(yq -r '.credentials.google.service_account_json_path' "$CONFIG")
 KEYSTORE_PASSWORD=$(yq -r '.credentials.android.keystore_password' "$CONFIG")
 
+# Validate all values before sed substitution
+validate_value "app.bundle_id" "$BUNDLE_ID"
+validate_value "app.package_name" "$PACKAGE_NAME"
+validate_value "app.name" "$APP_NAME"
+validate_value "app.sku" "$SKU"
+validate_value "app.apple_id" "$APPLE_ID"
+validate_value "android.track" "$TRACK"
+validate_value "ios.primary_category" "$PRIMARY_CAT"
+validate_value "ios.secondary_category" "$SECONDARY_CAT"
+validate_value "credentials.apple.key_id" "$APPLE_KEY_ID"
+validate_value "credentials.apple.issuer_id" "$APPLE_ISSUER_ID"
+
 # Generate codemagic.yaml from template
 sed \
   -e "s|\${BUNDLE_ID}|$BUNDLE_ID|g" \

package/templates/web/deploy-cloudflare.mjs

@@ -79,9 +79,17 @@ function getCredentials(dir) {
     const mcpPath = join(dir, ".mcp.json");
     if (existsSync(mcpPath)) {
       const mcp = JSON.parse(readFileSync(mcpPath, "utf8"));
-      const cf = mcp?.mcpServers?.cloudflare?.env || {};
-      token = token || cf.CLOUDFLARE_API_TOKEN || "";
-      accountId = accountId || cf.CLOUDFLARE_ACCOUNT_ID || "";
+      const cfServer = mcp?.mcpServers?.cloudflare || {};
+      const cfEnv = cfServer.env || {};
+      const cfArgs = cfServer.args || [];
+      token = token || cfEnv.CLOUDFLARE_API_TOKEN || "";
+      if (!accountId && cfArgs.length >= 4) {
+        const runIdx = cfArgs.indexOf("run");
+        if (runIdx >= 0 && cfArgs[runIdx + 1]) {
+          accountId = cfArgs[runIdx + 1];
+        }
+      }
+      accountId = accountId || cfEnv.CLOUDFLARE_ACCOUNT_ID || "";
     }
   }
   if (!token || !accountId) {