kasy-cli 1.15.0 → 1.17.0

package/lib/utils/png-padding.js

@@ -1,7 +1,9 @@
 const fsp = require('node:fs/promises');
 const { PNG } = require('pngjs');
 
-const ANDROID12_SAFE_RATIO = 0.5;
+const ANDROID12_SAFE_RATIO = 0.4;
+const ANDROID_ADAPTIVE_LOGO_RATIO = 0.65;
+const ANDROID_ADAPTIVE_CANVAS = 1024;
 
 async function readPng(filePath) {
   const buffer = await fsp.readFile(filePath);
@@ -117,4 +119,134 @@ async function writeAndroid12Variant(srcPath, dstPath, safeRatio = ANDROID12_SAF
   return { canvasSize, logoW, logoH };
 }
 
-module.exports = { writeAndroid12Variant, ANDROID12_SAFE_RATIO };
+function sampleSolidBackground(png) {
+  const inset = Math.max(2, Math.floor(Math.min(png.width, png.height) * 0.02));
+  const corners = [
+    [inset, inset],
+    [png.width - inset - 1, inset],
+    [inset, png.height - inset - 1],
+    [png.width - inset - 1, png.height - inset - 1],
+  ];
+
+  let r = 0;
+  let g = 0;
+  let b = 0;
+  let opaque = 0;
+  for (const [x, y] of corners) {
+    const idx = (y * png.width + x) * 4;
+    const alpha = png.data[idx + 3];
+    if (alpha < 250) continue;
+    r += png.data[idx];
+    g += png.data[idx + 1];
+    b += png.data[idx + 2];
+    opaque += 1;
+  }
+
+  if (opaque === 0) {
+    return { r: 255, g: 255, b: 255, sampled: false };
+  }
+  return {
+    r: Math.round(r / opaque),
+    g: Math.round(g / opaque),
+    b: Math.round(b / opaque),
+    sampled: true,
+  };
+}
+
+function fillSolidColor(png, color) {
+  for (let i = 0; i < png.data.length; i += 4) {
+    png.data[i] = color.r;
+    png.data[i + 1] = color.g;
+    png.data[i + 2] = color.b;
+    png.data[i + 3] = 255;
+  }
+}
+
+function compositeLogoOnBackground(background, logo) {
+  const offsetX = Math.floor((background.width - logo.width) / 2);
+  const offsetY = Math.floor((background.height - logo.height) / 2);
+
+  for (let y = 0; y < logo.height; y++) {
+    for (let x = 0; x < logo.width; x++) {
+      const srcIdx = (y * logo.width + x) * 4;
+      const alpha = logo.data[srcIdx + 3] / 255;
+      if (alpha === 0) continue;
+
+      const dstIdx = ((y + offsetY) * background.width + (x + offsetX)) * 4;
+      const inv = 1 - alpha;
+      background.data[dstIdx] = Math.round(logo.data[srcIdx] * alpha + background.data[dstIdx] * inv);
+      background.data[dstIdx + 1] = Math.round(logo.data[srcIdx + 1] * alpha + background.data[dstIdx + 1] * inv);
+      background.data[dstIdx + 2] = Math.round(logo.data[srcIdx + 2] * alpha + background.data[dstIdx + 2] * inv);
+      background.data[dstIdx + 3] = 255;
+    }
+  }
+}
+
+/**
+ * Generate the Android adaptive icon background asset. Reads the user-supplied
+ * icon PNG, samples a solid background color from its corners (falling back to
+ * white when the image is transparent), and writes a square canvas with the
+ * logo scaled down and centered. The result is what `flutter_launcher_icons`
+ * passes to `adaptive_icon_background`, fully filling the launcher's circular
+ * mask without the default white halo around square icons.
+ *
+ * @param {string} srcPath source icon PNG path
+ * @param {string} dstPath output path for icon_android.png
+ * @param {object} [options]
+ * @param {number} [options.canvasSize] output square size (default 1024)
+ * @param {number} [options.logoRatio] logo fill ratio inside canvas (default 0.65)
+ * @param {string} [options.backgroundColor] explicit hex like "#01171f" to override sampling
+ */
+async function writeAndroidAdaptiveBackground(srcPath, dstPath, options = {}) {
+  const canvasSize = options.canvasSize || ANDROID_ADAPTIVE_CANVAS;
+  const logoRatio = options.logoRatio || ANDROID_ADAPTIVE_LOGO_RATIO;
+
+  const src = await readPng(srcPath);
+
+  let color;
+  if (options.backgroundColor) {
+    const hex = options.backgroundColor.replace('#', '');
+    color = {
+      r: parseInt(hex.slice(0, 2), 16),
+      g: parseInt(hex.slice(2, 4), 16),
+      b: parseInt(hex.slice(4, 6), 16),
+      sampled: false,
+    };
+  } else {
+    color = sampleSolidBackground(src);
+  }
+
+  const canvas = new PNG({ width: canvasSize, height: canvasSize });
+  fillSolidColor(canvas, color);
+
+  const logoSize = Math.round(canvasSize * logoRatio);
+  const resized = resizeBilinear(src, logoSize, logoSize);
+  compositeLogoOnBackground(canvas, resized);
+
+  await writePng(canvas, dstPath);
+  return { canvasSize, logoSize, color };
+}
+
+/**
+ * Write a fully transparent square PNG. Used to satisfy
+ * `adaptive_icon_foreground` when the entire image already lives in the
+ * background layer.
+ *
+ * @param {string} dstPath
+ * @param {number} [size]
+ */
+async function writeTransparentSquare(dstPath, size = ANDROID_ADAPTIVE_CANVAS) {
+  const png = new PNG({ width: size, height: size });
+  png.data.fill(0);
+  await writePng(png, dstPath);
+  return { size };
+}
+
+module.exports = {
+  writeAndroid12Variant,
+  writeAndroidAdaptiveBackground,
+  writeTransparentSquare,
+  ANDROID12_SAFE_RATIO,
+  ANDROID_ADAPTIVE_LOGO_RATIO,
+  ANDROID_ADAPTIVE_CANVAS,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kasy-cli",
-  "version": "1.15.0",
+  "version": "1.17.0",
   "description": "CLI for scaffolding production-ready Flutter SaaS apps with Firebase, Supabase, or API REST backends.",
   "bin": {
     "kasy": "./bin/kasy.js"

package/templates/firebase/README.en.md

@@ -48,16 +48,26 @@ They live in `.vscode/launch.json` as build environment variables (`--dart-defin
 
 | Variable | Module | How to get |
 |----------|--------|------------|
-| `RC_ANDROID_API_KEY` | RevenueCat | RevenueCat dashboard → Apps → Android → **Google Play** public key (`goog_…`) |
-| `RC_IOS_API_KEY` | RevenueCat | RevenueCat dashboard → Apps → iOS → **Apple App Store** public key (`appl_…`) |
+| `RC_TEST_KEY` | RevenueCat | RevenueCat dashboard → Apps → Test Store → key (`test_…`). **One key for both iOS+Android.** Auto-used on simulator/emulator. |
+| `RC_IOS_PROD_KEY` | RevenueCat | RevenueCat dashboard → Apps → App Store → key (`appl_…`). Auto-used on physical iPhone (Sandbox and Production). |
+| `RC_ANDROID_PROD_KEY` | RevenueCat | RevenueCat dashboard → Apps → Google Play → key (`goog_…`). Auto-used on physical Android. |
 | `RC_WEB_API_KEY` | RevenueCat Web | RevenueCat dashboard → Apps → Web Billing → **production** key (`rcb_…`, not `rcb_sb_`) for release builds |
 
-### RevenueCat: `test_` vs store keys (TestFlight / release)
+### RevenueCat: `kasy run` picks the right key automatically
 
-- Keys starting with **`test_`** are RevenueCat **Test Store**: fine for **`flutter run` debug** on your Mac (fake purchases in RC’s test environment). **Do not** bake them into TestFlight/App Store IPAs — the SDK rejects them or the kit skips RC init.
-- **TestFlight / Apple sandbox** (no real charges): use **store** public keys — **`appl_…`** (iOS) and **`goog_…`** (Android). TestFlight purchases still use **Apple/Google sandbox**, not real billing.
-- The VS Code **Firebase — prod** config **no longer** sets RC keys; put `appl_` / `goog_` in **`Firebase/.env`** or **`.dart_defines`** (see `Makefile`) when building release / TestFlight.
-- **Firebase — dev** still ships sample `test_` keys for local development only.
+The CLI detects whether you're running on **simulator/emulator** or **physical device** and injects the right key:
+
+| Where you run | Key used |
+|---|---|
+| iOS Simulator / Android Emulator | `RC_TEST_KEY` (test_) |
+| Physical iPhone | `RC_IOS_PROD_KEY` (appl_) — falls back to `RC_TEST_KEY` if missing |
+| Physical Android | `RC_ANDROID_PROD_KEY` (goog_) — falls back to `RC_TEST_KEY` if missing |
+
+Force manually: `kasy run --rc=test` or `kasy run --rc=prod`. `--rc=auto` (default) applies the rule above.
+
+- **Why the split?** Simulators can't run real in-app purchases against `appl_`/`goog_` — only RevenueCat Test Store works there. On physical devices, `appl_`/`goog_` covers both Sandbox and Production (the SDK detects the environment).
+- **TestFlight and release:** use the production keys. **NEVER ship `test_` to the store** — the RevenueCat SDK crashes the app on release.
+- **VS Code (F5 without kasy run):** `launch.json` defaults to `RC_TEST_KEY` (or production if test_ is missing). To switch manually, run via `kasy run`.
 | `SENTRY_DSN` | Sentry | Dashboard Sentry → Project → DSN |
 | `MIXPANEL_TOKEN` | Mixpanel | Dashboard Mixpanel → Settings → Token |
 

package/templates/firebase/README.es.md

@@ -48,16 +48,26 @@ Están en `.vscode/launch.json` como variables de entorno de build (`--dart-defi
 
 | Variable | Módulo | Cómo obtener |
 |----------|--------|--------------|
-| `RC_ANDROID_API_KEY` | RevenueCat | Panel RevenueCat → Apps → Android → clave pública **Google Play** (`goog_…`) |
-| `RC_IOS_API_KEY` | RevenueCat | Panel RevenueCat → Apps → iOS → clave pública **Apple App Store** (`appl_…`) |
+| `RC_TEST_KEY` | RevenueCat | Panel RevenueCat → Apps → Test Store → clave (`test_…`). **Una sola clave sirve para iOS+Android.** Usada automáticamente en simulador/emulador. |
+| `RC_IOS_PROD_KEY` | RevenueCat | Panel RevenueCat → Apps → App Store → clave (`appl_…`). Usada automáticamente en iPhone físico (Sandbox y Producción). |
+| `RC_ANDROID_PROD_KEY` | RevenueCat | Panel RevenueCat → Apps → Google Play → clave (`goog_…`). Usada automáticamente en Android físico. |
 | `RC_WEB_API_KEY` | RevenueCat Web | Panel RevenueCat → Apps → Web Billing → clave **producción** (`rcb_…`, no `rcb_sb_`) en builds release |
 
-### RevenueCat: `test_` vs tienda (TestFlight / release)
+### RevenueCat: `kasy run` elige la clave automáticamente
 
-- Clave **`test_`** = **Test Store** de RevenueCat: sirve para **`flutter run` en debug** en tu Mac. **No** la empaques en IPA de TestFlight/App Store.
-- **TestFlight / sandbox de Apple** (sin cobro real): usa claves de **tienda** — **`appl_…`** (iOS) y **`goog_…`** (Android).
-- La config **Firebase — prod** en VS Code **ya no** define RC; pon `appl_` / `goog_` en **`.env`** o **`.dart_defines`** al generar release / TestFlight.
-- **Firebase — dev** sigue con `test_` de ejemplo solo para desarrollo local.
+La CLI detecta si vas a correr en **simulador/emulador** o en **dispositivo físico** e inyecta la clave correcta:
+
+| Dónde corres | Clave usada |
+|---|---|
+| iOS Simulator / Android Emulator | `RC_TEST_KEY` (test_) |
+| iPhone físico | `RC_IOS_PROD_KEY` (appl_) — fallback `RC_TEST_KEY` si falta |
+| Android físico | `RC_ANDROID_PROD_KEY` (goog_) — fallback `RC_TEST_KEY` si falta |
+
+Forzar manualmente: `kasy run --rc=test` o `kasy run --rc=prod`. `--rc=auto` (por defecto) aplica la regla anterior.
+
+- **¿Por qué el split?** Los simuladores no pueden hacer compras reales con claves `appl_`/`goog_` — solo funciona Test Store de RevenueCat. En dispositivo físico, `appl_`/`goog_` cubre Sandbox y Producción (el SDK lo detecta).
+- **TestFlight y release:** usa las claves de producción. **NUNCA subas `test_` a la tienda** — el SDK de RevenueCat crashea el app en release.
+- **VS Code (F5 sin kasy run):** `launch.json` usa `RC_TEST_KEY` por defecto (o producción si test_ falta). Para alternar manualmente, corre `kasy run`.
 | `SENTRY_DSN` | Sentry | Dashboard Sentry → Proyecto → DSN |
 | `MIXPANEL_TOKEN` | Mixpanel | Dashboard Mixpanel → Configuración → Token |
 

package/templates/firebase/README.md

@@ -48,16 +48,26 @@ Ficam no `.vscode/launch.json` como variáveis de ambiente de build (`--dart-def
 
 | Variável | Módulo | Como obter |
 |----------|--------|------------|
-| `RC_ANDROID_API_KEY` | RevenueCat | Dashboard RevenueCat → Apps → Android → chave pública **Google Play** (`goog_…`) |
-| `RC_IOS_API_KEY` | RevenueCat | Dashboard RevenueCat → Apps → iOS → chave pública **Apple App Store** (`appl_…`) |
+| `RC_TEST_KEY` | RevenueCat | Dashboard RevenueCat → Apps → Test Store → chave (`test_…`). **Uma chave só, serve pra iOS+Android.** Usada automaticamente em simulador/emulador. |
+| `RC_IOS_PROD_KEY` | RevenueCat | Dashboard RevenueCat → Apps → App Store → chave (`appl_…`). Usada automaticamente em iPhone físico (Sandbox e Produção). |
+| `RC_ANDROID_PROD_KEY` | RevenueCat | Dashboard RevenueCat → Apps → Google Play → chave (`goog_…`). Usada automaticamente em Android físico. |
 | `RC_WEB_API_KEY` | RevenueCat Web | Dashboard RevenueCat → Apps → Web Billing → chave **produção** (`rcb_…`, não `rcb_sb_`) em builds release |
 
-### RevenueCat: `test_` vs loja (TestFlight / release)
+### RevenueCat: `kasy run` escolhe a chave automaticamente
 
-- Chave que começa com **`test_`** = **Test Store** da RevenueCat: serve para **`flutter run` em debug** no Mac (compras fictícias no ambiente de teste da RC). **Não** use em IPA de TestFlight/App Store — o SDK bloqueia ou o app ignora o RC (comportamento atual do kit).
-- **TestFlight / sandbox da Apple** (compras sem cobrar de verdade): use no IPA as chaves públicas de **loja** — **`appl_…`** (iOS) e **`goog_…`** (Android). No TestFlight as compras ainda são **sandbox** da Apple/Google, não cobrança real.
-- A configuração **Firebase — prod** no VS Code **não** define mais RC; coloque `appl_` / `goog_` no seu **`.env`** na raiz do `Firebase/` ou em **`.dart_defines`** (ver `Makefile`) ao gerar release / TestFlight.
-- **Firebase — dev** no VS Code continua com `test_` de exemplo só para desenvolvimento local.
+A CLI detecta se você vai rodar em **simulador/emulador** ou em **dispositivo físico** e injeta a chave certa:
+
+| Onde você roda | Chave usada |
+|---|---|
+| iOS Simulator / Android Emulator | `RC_TEST_KEY` (test_) |
+| iPhone físico | `RC_IOS_PROD_KEY` (appl_) — fallback `RC_TEST_KEY` se ausente |
+| Android físico | `RC_ANDROID_PROD_KEY` (goog_) — fallback `RC_TEST_KEY` se ausente |
+
+Forçar manualmente: `kasy run --rc=test` ou `kasy run --rc=prod`. `--rc=auto` (default) usa a regra acima.
+
+- **Por que o split?** Simulador iOS e emulador Android não conseguem fazer in-app purchase real com chaves `appl_`/`goog_` — só funciona Test Store da RevenueCat. Já em físico, `appl_`/`goog_` cobre Sandbox e Produção (o SDK detecta sozinho).
+- **TestFlight e release:** use as chaves de produção. **NUNCA suba `test_` para a loja** — o SDK do RevenueCat crasha o app no release.
+- **VS Code (F5 sem kasy run):** o `launch.json` carrega `RC_TEST_KEY` como default (ou produção se test_ ausente). Pra alternar manualmente, rode pelo `kasy run`.
 | `SENTRY_DSN` | Sentry | Dashboard Sentry → Projeto → DSN |
 | `MIXPANEL_TOKEN` | Mixpanel | Dashboard Mixpanel → Configurações → Token |
 

package/templates/firebase/android/app/src/main/kotlin/com/aicrus/firebase/kit/MainActivity.kt

@@ -1,7 +1,9 @@
 package com.aicrus.firebase.kit
 
 import android.content.Context
+import android.content.Intent
 import android.os.Bundle
+import android.util.Log
 import androidx.appcompat.app.AppCompatDelegate
 import com.google.android.gms.ads.identifier.AdvertisingIdClient
 import io.flutter.embedding.android.FlutterActivity
@@ -20,6 +22,19 @@ class MainActivity : FlutterActivity() {
     super.onCreate(savedInstanceState)
   }
 
+  // Logs the incoming intent so we can diagnose warm-starts from the home
+  // widget that land on go_router's 404. With this, the Dart side's onException
+  // logs and these adb logs together show whether the intent itself carries a
+  // bad URI (data Uri / extras) or whether the 404 comes from elsewhere.
+  override fun onNewIntent(intent: Intent) {
+    Log.d(
+      "KasyWidgetTap",
+      "onNewIntent action=${intent.action} data=${intent.data} " +
+        "flags=0x${Integer.toHexString(intent.flags)} extras=${intent.extras}",
+    )
+    super.onNewIntent(intent)
+  }
+
   // Forces the night mode to match the user's saved theme preference (read
   // from `shared_preferences`) so the native splash drawable selection
   // (drawable-night vs drawable) follows the in-app choice, not just the OS.

package/templates/firebase/android/app/src/main/kotlin/com/aicrus/firebase/kit/MyWidget.kt

@@ -1,7 +1,6 @@
 package com.aicrus.firebase.kit
 
 import android.content.Context
-import android.content.Intent
 import androidx.compose.runtime.Composable
 import androidx.compose.ui.graphics.Color
 import androidx.compose.ui.unit.dp
@@ -14,7 +13,7 @@ import androidx.glance.LocalSize
 import androidx.glance.action.clickable
 import androidx.glance.appwidget.GlanceAppWidget
 import androidx.glance.appwidget.SizeMode
-import androidx.glance.appwidget.action.actionStartActivity
+import androidx.glance.appwidget.action.actionRunCallback
 import androidx.glance.appwidget.provideContent
 import androidx.glance.background
 import androidx.glance.currentState
@@ -89,7 +88,7 @@ class MyWidgetWidget : GlanceAppWidget() {
     Box(
       modifier = GlanceModifier
         .fillMaxSize()
-        .clickable(actionStartActivity(launchAppIntent(context))),
+        .clickable(actionRunCallback<OpenAppAction>()),
     ) {
       Image(
         provider = ImageProvider(R.drawable.widget_gradient_inner),
@@ -153,7 +152,7 @@ class MyWidgetWidget : GlanceAppWidget() {
               contentDescription = "Add",
               modifier = GlanceModifier
                 .size(34.dp)
-                .clickable(actionStartActivity(launchAppIntent(context))),
+                .clickable(actionRunCallback<OpenAppAction>()),
             )
           }
         }
@@ -219,19 +218,4 @@ class MyWidgetWidget : GlanceAppWidget() {
     }
     return DefaultStrings(greeting, hello)
   }
-
-  /// Builds the exact Intent the system launcher fires when the user taps
-  /// the app icon. We must NOT add extra flags here — getLaunchIntentForPackage
-  /// already returns `FLAG_ACTIVITY_NEW_TASK | FLAG_ACTIVITY_RESET_IF_NEEDED`,
-  /// which is the same combo the launcher uses. Adding `CLEAR_TOP` destroys
-  /// go_router's navigation stack on warm starts and lands the user on the
-  /// errorBuilder ("404 - Page not found").
-  private fun launchAppIntent(context: Context): Intent {
-    return context.packageManager.getLaunchIntentForPackage(context.packageName)
-      ?: Intent(context, MainActivity::class.java).apply {
-        action = Intent.ACTION_MAIN
-        addCategory(Intent.CATEGORY_LAUNCHER)
-        flags = Intent.FLAG_ACTIVITY_NEW_TASK
-      }
-  }
 }

package/templates/firebase/android/app/src/main/kotlin/com/aicrus/firebase/kit/MyWidgetReceiver.kt

@@ -1,7 +1,44 @@
 package com.aicrus.firebase.kit
 
+import android.appwidget.AppWidgetManager
+import android.content.Context
+import androidx.glance.appwidget.GlanceAppWidgetManager
 import es.antonborri.home_widget.HomeWidgetGlanceWidgetReceiver
+import kotlinx.coroutines.runBlocking
 
 class MyWidgetReceiver : HomeWidgetGlanceWidgetReceiver<MyWidgetWidget>() {
     override val glanceAppWidget = MyWidgetWidget()
+
+    // Override the parent's onUpdate because its updateAppWidgetState
+    // transformation returns the SAME state instance back. Glance compares
+    // references, treats the state as unchanged, and skips the recomposition.
+    // The symptom on the Flutter side: first language switch does not update,
+    // user has to tap twice. We force a fresh recompose by calling update()
+    // directly on each widget id — the composable then reads the latest
+    // SharedPreferences values that Dart already committed synchronously.
+    override fun onUpdate(
+        context: Context,
+        appWidgetManager: AppWidgetManager,
+        appWidgetIds: IntArray,
+    ) {
+        runBlocking {
+            val manager = GlanceAppWidgetManager(context)
+            appWidgetIds.forEach { widgetId ->
+                val glanceId = manager.getGlanceIdBy(widgetId)
+                glanceAppWidget.update(context, glanceId)
+            }
+            // Defensive 2nd update: Glance occasionally coalesces or skips the
+            // first invalidation when the user triggers two updates in quick
+            // succession (e.g. tapping the language tile and immediately
+            // returning to the home screen). A short gap + second update
+            // guarantees the freshly committed SharedPreferences values
+            // actually reach the composition. The symptom without this:
+            // first language tap appears to do nothing, second tap "fixes" it.
+            kotlinx.coroutines.delay(200)
+            appWidgetIds.forEach { widgetId ->
+                val glanceId = manager.getGlanceIdBy(widgetId)
+                glanceAppWidget.update(context, glanceId)
+            }
+        }
+    }
 }

package/templates/firebase/android/app/src/main/kotlin/com/aicrus/firebase/kit/OpenAppAction.kt

@@ -0,0 +1,26 @@
+package com.aicrus.firebase.kit
+
+import android.content.Context
+import android.content.Intent
+import androidx.glance.GlanceId
+import androidx.glance.action.ActionParameters
+import androidx.glance.appwidget.action.ActionCallback
+
+// Custom ActionCallback used by MyWidgetWidget instead of actionStartActivity.
+// actionStartActivity wraps the launch in an internal "glance-action://CALLBACK"
+// intent that ends up reaching MainActivity (because launchMode=singleTop) as
+// the new intent — Flutter sees that URI as a deep link and go_router blows up
+// with "no routes for location: glance-action:/CALLBACK". Running the launch
+// ourselves through onAction bypasses that wrapping entirely.
+class OpenAppAction : ActionCallback {
+    override suspend fun onAction(
+        context: Context,
+        glanceId: GlanceId,
+        parameters: ActionParameters,
+    ) {
+        val intent = Intent(context, MainActivity::class.java).apply {
+            flags = Intent.FLAG_ACTIVITY_SINGLE_TOP or Intent.FLAG_ACTIVITY_NEW_TASK
+        }
+        context.startActivity(intent)
+    }
+}

package/templates/firebase/docs/revenuecat-setup.es.md

@@ -9,12 +9,24 @@ Guía para activar suscripciones y compras en la app después de que la CLI gene
 | Ya listo | Lo que falta |
 |----------|--------------|
 | Instaló `purchases_flutter` | Crear cuenta en RevenueCat |
-| Configuró las claves en `Makefile` y `.vscode/launch.json` | Crear Productos, Entitlements y Offerings en el panel RC |
+| Configuró las claves en `.env` (test/iOS prod/Android prod) | Crear Productos, Entitlements y Offerings en el panel RC |
 | Generó el código del paywall y del repositorio de suscripciones | Registrar la URL del webhook en el panel RC |
 | Firebase: desplegó la Cloud Function del webhook | — |
 | Supabase: desplegó la Edge Function del webhook | — |
 
-> Las claves quedan en `.vscode/launch.json` y `Makefile`. Ambos archivos están en `.gitignore` — las claves nunca van al repositorio.
+> Las claves quedan en `.env` en la raíz (fuente de verdad) y reflejadas en `.vscode/launch.json` + `Makefile`. Todos en `.gitignore` — nunca van al repositorio.
+
+### ¿Qué clave usar?
+
+La CLI pregunta **tres claves opcionales** (al menos una es obligatoria):
+
+| Variable | Prefijo | Uso |
+|---|---|---|
+| `RC_TEST_KEY` | `test_` | Test Store. **Una sola clave**, sirve para iOS+Android. Usada automáticamente en simulador/emulador. |
+| `RC_IOS_PROD_KEY` | `appl_` | App Store (Sandbox + Producción). Usada automáticamente en iPhone físico. |
+| `RC_ANDROID_PROD_KEY` | `goog_` | Google Play (Sandbox + Producción). Usada automáticamente en Android físico. |
+
+`kasy run` elige la clave correcta según el dispositivo. Forzar manualmente: `kasy run --rc=test` o `kasy run --rc=prod`.
 
 ---
 
@@ -155,9 +167,13 @@ Después de completar todo y configurar el idioma del grupo, el estado sale de *
 
 [app.revenuecat.com](https://app.revenuecat.com) → tu proyecto → **Apps** → `+ Add app` → **App Store** → copia la clave `appl_xxx`.
 
-Actualiza en los archivos del proyecto:
-- `.vscode/launch.json` → reemplaza `RC_IOS_API_KEY`
-- `Makefile` → reemplaza la misma variable en el bloque `DEFINES`
+Pégala en el `.env` de la raíz:
+
+```env
+RC_IOS_PROD_KEY=appl_xxxxxxxxxxxxxxx
+```
+
+`kasy run` usa esta clave automáticamente en iPhone físico (el simulador sigue con `RC_TEST_KEY`).
 
 **6. Crear Sandbox Tester — obligatorio para probar en iPhone físico**
 
@@ -253,9 +269,13 @@ d) Google Play Console → **Configuración** → **Usuarios y permisos** → **
 
 [app.revenuecat.com](https://app.revenuecat.com) → tu proyecto → **Apps** → `+ Add app` → **Google Play** → sube el archivo JSON → copia la clave `goog_xxx`.
 
-Actualiza en los archivos del proyecto:
-- `.vscode/launch.json` → reemplaza `RC_ANDROID_API_KEY`
-- `Makefile` → reemplaza la misma variable en el bloque `DEFINES`
+Pégala en el `.env` de la raíz:
+
+```env
+RC_ANDROID_PROD_KEY=goog_xxxxxxxxxxxxxxx
+```
+
+`kasy run` usa esta clave automáticamente en Android físico (el emulador sigue con `RC_TEST_KEY`).
 
 **8. Agregar License Tester — obligatorio para probar en el dispositivo**
 

package/templates/firebase/docs/revenuecat-setup.pt.md

@@ -9,12 +9,24 @@ Guia para ativar assinaturas e compras no app depois que a CLI gerou o projeto.
 | Já pronto | O que ainda falta |
 |-----------|-------------------|
 | Instalou `purchases_flutter` | Criar conta no RevenueCat |
-| Configurou as chaves no `Makefile` e `.vscode/launch.json` | Criar Produtos, Entitlements e Offerings no painel RC |
+| Configurou as chaves no `.env` (test/iOS prod/Android prod) | Criar Produtos, Entitlements e Offerings no painel RC |
 | Gerou o código do paywall e do repositório de assinaturas | Registrar a URL do webhook no painel RC |
 | Firebase: implantou a Cloud Function do webhook | — |
 | Supabase: implantou a Edge Function do webhook | — |
 
-> As chaves ficam em `.vscode/launch.json` e `Makefile`. Esses dois arquivos estão no `.gitignore` — as chaves nunca vão para o repositório.
+> As chaves ficam em `.env` na raiz (fonte da verdade) e refletidas no `.vscode/launch.json` + `Makefile`. Todos no `.gitignore` — nunca vão para o repositório.
+
+### Qual chave usar?
+
+A CLI pergunta **três chaves opcionais** (pelo menos uma é obrigatória):
+
+| Variável | Prefixo | Uso |
+|---|---|---|
+| `RC_TEST_KEY` | `test_` | Test Store. **Uma chave única**, vale iOS+Android. Usada automaticamente em simulador/emulador. |
+| `RC_IOS_PROD_KEY` | `appl_` | App Store (Sandbox + Produção). Usada automaticamente em iPhone físico. |
+| `RC_ANDROID_PROD_KEY` | `goog_` | Google Play (Sandbox + Produção). Usada automaticamente em Android físico. |
+
+O `kasy run` escolhe a chave certa baseado no device. Forçar manual: `kasy run --rc=test` ou `kasy run --rc=prod`.
 
 ---
 
@@ -155,9 +167,13 @@ Após preencher tudo e configurar o idioma do grupo, o status sai de **Missing M
 
 [app.revenuecat.com](https://app.revenuecat.com) → seu projeto → **Apps** → `+ Add app` → **App Store** → copie a chave `appl_xxx`.
 
-Atualize nos arquivos do projeto:
-- `.vscode/launch.json` → substitua `RC_IOS_API_KEY`
-- `Makefile` → substitua a mesma variável no bloco `DEFINES`
+Cole no `.env` da raiz:
+
+```env
+RC_IOS_PROD_KEY=appl_xxxxxxxxxxxxxxx
+```
+
+O `kasy run` usa essa chave automaticamente em iPhone físico (simulador continua com `RC_TEST_KEY`).
 
 **6. Criar Sandbox Tester — obrigatório para testar no iPhone físico**
 
@@ -253,9 +269,13 @@ d) Google Play Console → **Configurações** → **Usuários e permissões**
 
 [app.revenuecat.com](https://app.revenuecat.com) → seu projeto → **Apps** → `+ Add app` → **Google Play** → faça upload do arquivo JSON → copie a chave `goog_xxx`.
 
-Atualize nos arquivos do projeto:
-- `.vscode/launch.json` → substitua `RC_ANDROID_API_KEY`
-- `Makefile` → substitua a mesma variável no bloco `DEFINES`
+Cole no `.env` da raiz:
+
+```env
+RC_ANDROID_PROD_KEY=goog_xxxxxxxxxxxxxxx
+```
+
+O `kasy run` usa essa chave automaticamente em Android físico (emulador continua com `RC_TEST_KEY`).
 
 **8. Adicionar License Tester — obrigatório para testar no dispositivo**