kasy-cli 1.32.0 → 1.35.0

package/templates/firebase/AGENTS.md

@@ -0,0 +1,170 @@
+# AGENTS.md — working in this codebase
+
+This project was generated with the **Kasy** kit. This file orients any AI coding
+assistant (Claude Code, Cursor, GitHub Copilot, …). Read it before generating
+code. Claude Code users: `CLAUDE.md` points here.
+
+## What this is
+
+A production-ready Flutter app (web, iOS, Android) built on the **Kasy design
+system** and a **feature-first** architecture. It was generated with **one**
+backend — Firebase, Supabase, or a REST API. Only the **data layer** differs
+between backends; the UI, state, i18n and design system are identical. So almost
+everything below is backend-agnostic.
+
+## Golden rules (every time)
+
+1. **Use the design system, never raw values.** No hardcoded `fontSize`,
+   `Color(0x…)`, `Colors.*`, or literal padding / radius / icon sizes. Use
+   `context.textTheme.*` / `KasyTextTheme.*`, `context.colors.*`,
+   `KasySpacing.*`, `KasyRadius.*`, `KasyIconSize.*`. Full reference:
+   **`DESIGN_SYSTEM.md`**.
+2. **Use kit components, not raw Material.** `KasyButton` (not
+   ElevatedButton / TextButton), `showKasyConfirmDialog` (not AlertDialog),
+   `showKasyToast` (not SnackBar), plus `KasyCard`, `KasyTextField`,
+   `KasyScreen`, etc.
+3. **The Home screen is the visual reference** — clean, minimal, lots of
+   surface, one accent colour used sparingly. New screens should mirror it.
+4. **English everywhere** in code, comments and identifiers. **No hardcoded
+   user-facing strings** — use slang i18n (`context.t.…`).
+5. **Package imports only**: `import 'package:kasy_kit/…';`, never relative.
+6. **Zero analyzer issues.** Run `flutter analyze` and fix everything before
+   considering a change done.
+
+## Design system, components & responsiveness
+
+This kit is an **organized, opinionated** design system — not a blank canvas.
+Before building anything, browse the live **Design System** screen
+(`lib/features/home/design_system_page.dart`) and the **Components** gallery:
+colours, typography, spacing and dozens of ready widgets (`KasyButton`,
+`KasyCard`, `KasyTextField`, `KasyScreen`, `showKasyToast`,
+`showKasyConfirmDialog`, …). Reuse one before writing a new widget. Full token
+reference: **`DESIGN_SYSTEM.md`**.
+
+**Responsiveness is deliberate, not improvised.** There are exactly three
+breakpoints and the type sizes are pinned per breakpoint, so the UI never
+oscillates or guesses:
+
+| Breakpoint | Width      | Notes                                            |
+| ---------- | ---------- | ------------------------------------------------ |
+| Mobile     | `< 768`    | native iOS/Android + phone-width web             |
+| Tablet     | `768–1024` |                                                  |
+| Desktop    | `>= 1024`  | authored baseline                                |
+
+- **Typography** (`KasyTypeScale`): each role has an **explicit size per
+  breakpoint** — headings are largest on desktop and step down on smaller
+  screens; body/labels stay constant. It is applied globally by
+  `ResponsiveTextTheme` — **screens just use `context.textTheme.*` /
+  `context.kasyTextTheme.*` and the right size comes out**. Don't hardcode
+  `fontSize`; don't invent your own breakpoints.
+- **Native mobile** is straightforward: it's the Mobile breakpoint and never
+  scales the viewport.
+- **Web render scale** (`WebViewportScale`) is a *separate* concern: Flutter web
+  renders ~10% large, so **desktop only** scales the whole UI to `0.95`. Tablet
+  and mobile web render at natural size, like native. This is NOT the typography
+  scale — don't conflate the two.
+
+To re-tune sizes, edit `KasyTypeScale` in `lib/core/theme/type_scale.dart` —
+nothing else. The live ramp (tabs per breakpoint) is under **Design System →
+Typography**.
+
+## Architecture (feature-first, three layers)
+
+```
+lib/
+├── components/   # Kasy design-system widgets (KasyButton, KasyCard, …)
+├── core/         # cross-cutting: theme/, data/, states/, security/, widgets/, i18n
+└── features/
+    └── <feature>/
+        ├── api/           # data source (Firebase / Supabase / REST) → returns entities
+        ├── repositories/  # entities → domain models (business logic)
+        ├── providers/     # Riverpod notifiers → immutable page state
+        └── ui/            # pages, components (use provider + domain), widgets (dumb)
+```
+
+- **Data flow:** `api → repository → provider (notifier) → ui`. Only repositories
+  use api classes. The api returns entities; repositories return domain models.
+- **State:** a Riverpod notifier exposes an immutable (freezed) state; the view
+  `ref.watch`es it and triggers actions. Use `.when` / `.map` for
+  data / loading / error.
+- **Backend note:** the `api` layer is the only backend-specific code. A new
+  data-backed feature follows the same `api → repo → provider` chain the
+  existing features use.
+
+## Building a screen or component — checklist
+
+1. Read `DESIGN_SYSTEM.md` (tokens, typography roles, components).
+2. Reuse a kit component before building one. Wrap new pages in `KasyScreen`
+   (or mirror an existing page's scaffold).
+3. Use semantic typography roles (`pageTitle`, `sectionTitle`, `rowTitle`, …)
+   and tokens for **every** size, colour and spacing.
+4. Strings via `context.t.*` (add keys to the i18n JSON, never inline text).
+5. `flutter analyze` clean. Optional: `dart run tool/design_check.dart` flags
+   any raw values that slipped into `lib/features`.
+
+## Platform notes (native-only features)
+
+Some features only work on a real iOS / Android build and are gated with
+`kIsWeb`. They never run on web; where the user explicitly triggers them, a
+"native app only" toast is shown instead of failing silently.
+
+- **In-app review / store rating** — sends the user to the App Store / Play
+  Store. It is never shown on web. **iOS requires the numeric App Store ID**:
+  run `kasy configure` and fill `App Store ID (numeric)`. Android works
+  automatically from the package name. Until the ID is set, iOS store review
+  throws at runtime.
+- **Push / FCM token, notification permission** — native APIs; on web the admin
+  actions surface the "native app only" toast.
+- **App update prompts** — two distinct flows, both native-only and driven by
+  Firebase Remote Config (works on every backend): **"update available"** (shown
+  *before*, when the installed version is below `app_latest_version` / blocking
+  below `app_min_version`, sends the user to the store) and **"what's new"**
+  (shown *after* updating). See `lib/core/app_update/` and the README.
+
+## Optional design guard-rail
+
+`dart run tool/design_check.dart` scans `lib/features` for raw values
+(hardcoded fonts / colours / Material widgets). It is **opt-in and
+non-blocking** — relax it, wire it into CI, or delete it freely. Per-line
+escape hatch: `// design-check: ignore`.
+
+## Updating the kit (merging new versions with your changes)
+
+The project is a scaffold: the kit code was copied into it. Improvements ship via
+the CLI, which **overwrites** files (it does not auto-merge). The safety net is git.
+
+Recommended flow when the user wants newer kit code:
+
+1. **Commit first** so the working tree is clean (the CLI also warns about this).
+2. Run the relevant command:
+   - `kasy update` — shows what's new for the features in use
+   - `kasy update core` / `kasy update components` — refreshes core files / UI components
+   - `kasy update <feature>` — e.g. `revenuecat`, `ai_chat`, `auth` (re-applies that feature)
+3. The command overwrites the files and prints which ones changed.
+4. **Merge:** if the user had customized any overwritten file, reconcile their version
+   (in the previous git commit) with the new kit version. As the in-project agent,
+   this is your job: read `git diff` (or `git show HEAD:<file>` for the user's prior
+   version) and produce a result that keeps BOTH the user's customizations and the new
+   kit improvements. Prefer additive merges; never silently drop the user's logic.
+   When unsure which side wins for a hunk, ask the user.
+
+This is why committing before `kasy update` matters: it makes the user's prior version
+recoverable so the merge is a normal 3-way reconcile, not a guess.
+
+## Debugging when something doesn't work
+
+Diagnose with real signals, not guesses:
+
+- **App logs first.** Key steps (auth, service init) are logged via `Logger` — read
+  the `kasy run` terminal / browser console.
+- **Then the backend logs.** Supabase: Dashboard → Logs (Auth / Edge Functions /
+  Postgres). Firebase: Console → Functions logs / Authentication.
+- **Auth / token errors:** decode the JWT (base64url-decode the middle segment) and
+  inspect `sub` / `aud` / `iss`. A `missing sub claim` usually means the wrong
+  session/token was sent (e.g. the publishable `anon` key), not a bad provider token.
+- **`kasy doctor`** checks common setup gaps (Google SHA-1, authorized domains,
+  provider config).
+- **Web vs native differ:** web runs in `authRequired` mode (no anonymous user);
+  native is anonymous-first. Account-linking only applies when a real session exists.
+
+Add a temporary `print(...)` to inspect a runtime value, then remove it.

package/templates/firebase/CLAUDE.md

@@ -0,0 +1,16 @@
+# CLAUDE.md
+
+This project shares one AI-guidance file across tools. **Read `AGENTS.md`** in
+this directory first — it defines the architecture, the Kasy design system, and
+the conventions to follow before generating any code.
+
+Quick reminders:
+
+- Use design-system tokens, never raw values — see `DESIGN_SYSTEM.md`
+  (`context.textTheme.*`, `context.colors.*`, `KasySpacing.*`, `KasyRadius.*`,
+  `KasyIconSize.*`).
+- Use Kasy components (`KasyButton`, `KasyCard`, `showKasyToast`,
+  `showKasyConfirmDialog`, …), not raw Material.
+- The Home screen is the visual reference: clean, minimal, one accent colour.
+- English in code; user strings via `context.t.*` (slang i18n).
+- Run `flutter analyze` and keep it clean.

package/templates/firebase/DESIGN_SYSTEM.md

@@ -0,0 +1,269 @@
+# Kasy Design System
+
+**Version 1.0.0** · last updated 2026-06-11
+
+The single source of truth for how the app looks. Everything here lives in code
+under `lib/core/theme/` and `lib/components/`, so changing a token in one place
+updates the whole app (web, Android, iOS) at once. This document just writes the
+rules down so anyone, including projects generated by the Kasy CLI, inherits the
+same standard without guessing.
+
+Design principle: **clean, modern, minimal**. Lots of surface, one accent colour
+used sparingly, no loud weights. The Home screen (sidebar + header + elevated
+`KasyCard`) is the reference for "what good looks like"; new screens should
+mirror it.
+
+---
+
+## The golden rule
+
+Use **tokens and roles**, never bespoke values.
+
+| Instead of…                         | Use…                                         |
+| ----------------------------------- | -------------------------------------------- |
+| `fontSize: 16, fontWeight: w600`    | `context.textTheme.*` / `KasyTextTheme.*`    |
+| `Icon(size: 20)`                    | `Icon(size: KasyIconSize.lg)`                |
+| `EdgeInsets.all(16)`                | `EdgeInsets.all(KasySpacing.md)`             |
+| `BorderRadius.circular(16)`         | `BorderRadius.circular(KasyRadius.lg)`       |
+| `Color(0xFF…)` / `Colors.*`         | `context.colors.*`                           |
+| `ElevatedButton`, `TextButton`      | `KasyButton`                                 |
+| `AlertDialog`, `SnackBar`           | `showKasyConfirmDialog`, `showKasyToast`     |
+
+A bespoke number is only acceptable when a component is being *calibrated* (the
+sidebar, the date-picker grid, badges) and there is no token that fits. When in
+doubt, add or reuse a role rather than hardcoding.
+
+---
+
+## Typography — `KasyTextTheme` (`lib/core/theme/texts.dart`)
+
+### HeroUI scale (the raw roles, Inter)
+
+| Role            | Size / weight / line-height |
+| --------------- | --------------------------- |
+| `heading1`      | 36 / w800 / 40              |
+| `heading2`      | 24 / w700 / 32              |
+| `heading3`      | 20 / w600 / 28              |
+| `heading4`      | 16 / w600 / 24              |
+| `bodyBase`      | 16 / w400                   |
+| `bodyBaseMedium`| 16 / w500                   |
+| `bodySm`        | 14 / w400                   |
+| `bodySmMedium`  | 14 / w500                   |
+| `bodyXs`        | 12 / w400                   |
+| `bodyXsMedium`  | 12 / w500                   |
+
+### Semantic app roles (prefer these on screens)
+
+| Role           | Maps to                        | Use for                                   |
+| -------------- | ------------------------------ | ----------------------------------------- |
+| `pageTitle`    | `heading2` (24/w700)           | Screen / page titles, onboarding titles   |
+| `sectionTitle` | `heading4` (16/w600)           | Detail / section headings                 |
+| `sectionLabel` | 12 / w600 / letter-spacing 0.5 | Uppercase group eyebrows (lists, settings)|
+| `rowTitle`     | `bodySmMedium` (14/w500)       | List / settings row titles                |
+| `rowValue`     | `bodySm` (14/w400)             | List / settings row values                |
+| `cardTitle`    | `bodySmMedium` (14/w500)       | Card titles                               |
+| `cardSubtitle` | `bodyXs` (12/w400)             | Card secondary text                       |
+| `caption`      | `bodyXs` (12/w400)             | Captions, helper text                     |
+
+Access the semantic roles via `context.kasyTextTheme.*` (colourless — apply
+colour with `.copyWith`). Access Material slots via `context.textTheme.*`
+(colour already applied). The raw scale roles are also exposed as
+`KasyTextTheme.*` statics, but those are **fixed** (the desktop baseline, for
+specs/docs) — use the `context.*` accessors in live UI so text scales.
+
+Material → role mapping: `headlineMedium = heading2`, `headlineSmall =
+titleLarge = heading3`, `titleMedium = heading4`.
+
+The chrome/app-bar title is **w700** (not w900). Black weights read as heavy and
+fight the rest of the UI.
+
+### Responsive type — `KasyTypeScale` (`lib/core/theme/type_scale.dart`)
+
+Not a blind multiplier: **every role declares an explicit size per breakpoint**
+(the way Figma variables / modes do). The professional pattern — **headings are
+largest on desktop and step down on smaller viewports** (a 36px title would feel
+huge and wrap badly on a phone), while **body and labels stay constant** for
+stable reading everywhere. Desktop is the authored reference.
+
+| Role (example) | Mobile `< 768` | Tablet `768–1024` | Desktop `>= 1024` |
+| -------------- | -------------- | ----------------- | ----------------- |
+| `heading1`     | 28             | 32                | 36                |
+| `heading2`     | 22             | 23                | 24                |
+| `heading3`     | 18             | 19                | 20                |
+| `bodyBase`     | 16             | 16                | 16                |
+| `bodySm`       | 14             | 14                | 14                |
+
+`ResponsiveTextTheme` (innermost wrapper in `main.dart`) reads the viewport
+width, picks the breakpoint and republishes a `Theme` whose Material `textTheme`
+and `KasyTextTheme` extension use that breakpoint's sizes. Every
+`context.textTheme.*` and `context.kasyTextTheme.*` inherits it — **no screen
+does anything**; desktop is a pass-through (the authored baseline). Component
+themes (buttons, inputs) keep their calibrated sizes on purpose. To re-tune the
+whole app, edit the numbers in `KasyTypeScale` — nothing else. The live ramp is
+visible under **Design System → Typography** (tabs per breakpoint).
+
+**Web render scale (`WebViewportScale`, `lib/core/web_viewport_scale.dart`).** A
+separate concern from type sizes: Flutter web renders ~10% larger than an
+equivalent HTML app, so on **desktop only** (`>= 1024`) the whole UI is scaled to
+`0.95` — a true viewport scale, so layout, scrolling and hit-testing stay
+correct. Tablet and mobile web render at natural size, exactly like the native
+build, which never scales.
+
+---
+
+## Icon sizes — `KasyIconSize` (`lib/core/theme/icon_sizes.dart`)
+
+| Token       | px | Token alias  | = |
+| ----------- | -- | ------------ | -- |
+| `xxs`       | 12 | `rowLeading` | `lg` (20) |
+| `xs`        | 14 | `rowTrailing`| `sm` (16) |
+| `sm`        | 16 | `chrome`     | `lg` (20) |
+| `md`        | 18 | `inline`     | `md` (18) |
+| `lg`        | 20 | | |
+| `xl`        | 24 | | |
+| `xxl`       | 28 | | |
+| `display`   | 36 | | |
+| `hero`      | 72 | | |
+
+Never pass a numeric `size:` to `Icon`; use a token so re-scaling is one edit.
+
+---
+
+## Spacing — `KasySpacing` (`lib/core/theme/spacing.dart`)
+
+`xs 4 · sm 8 · smd 12 · md 16 · lg 24 · xl 32 · xxl 48 · xxxl 64`
+
+`pageHorizontalGutter = md (16)` · `pageVerticalGutter = sm (8)` ·
+`belowChromeContentGap = 20`.
+
+## Radius — `KasyRadius` (`lib/core/theme/radius.dart`)
+
+Semantic: `xs 4 · sm 8 · md 12 · lg 16 · xl 24 · full 999`.
+`KasyCard` defaults to `lg` (16).
+
+---
+
+## Colours — `KasyColors`, via `context.colors.*`
+
+Always pull colours from `context.colors.*` so light/dark resolve automatically.
+Key tokens: `primary`, `onPrimary`, `surface`, `onSurface`, `onBackground`,
+`muted`, `fieldLabel`, `outline`, `error` / `onError`, `success`, `warning`,
+`surfacePrimarySoft`, `surfaceNeutralSoft`, `surfaceErrorSoft`.
+
+Brand: avocado green `#D2F51E` (accent), deep green `#011820` (dark ground).
+Disabled state: blend the colour toward the surface (opaque), never raw opacity.
+
+---
+
+## Components
+
+### `KasyButton`
+Sizes (height): `small 40` · `medium 45` (default) · `large 54`. Radius
+`KasyRadius.md`. Variants: primary, secondary, tertiary, destructive,
+destructiveSoft, inverse, link, soft, neutral, outline, ghost.
+
+### `KasyTextField`
+Canonical single-line height: **`singleLineHeight = 45`** (drives the field's
+vertical padding so the box itself is exactly that tall on every platform — web
+density is normalised to `standard`). Matches the medium button.
+
+Variants:
+- **primary** — surface fill + hairline border + soft shadow (floats; good on a
+  bare background).
+- **secondary** — elevated fill (contrasts on a card) + border, no shadow.
+- **flat** — primary's surface fill + a soft border, **no shadow**. For fields
+  sitting on a same-coloured card. Border comes from
+  `KasyShadows.inputFieldFlatBorder` (derived from `onSurface`, so it reads in
+  both light and dark; subtle by design).
+- **embedded** — transparent, no border, no shadow.
+
+Auth screens (sign in / sign up / recover) use **flat** on every breakpoint.
+A custom `contentPadding` opts a field out of the 45 lock (e.g. the compact
+header search). Use `forceFocusBorder` to show the "active" focused border from
+state without taking real focus (composite triggers like the date picker).
+
+### `KasyTextArea`
+Multi-line sibling of `KasyTextField`; same variants (primary / secondary / flat
+/ embedded). Height grows with content (not locked to 45).
+
+### `KasyDatePicker`
+Reuses `KasyTextField` as a read-only trigger, so it inherits the field look and
+the 45 height. The "open" border is painted from state (`forceFocusBorder`), so
+a mouse click never doubles the keyboard focus ring and the border never drops
+while the calendar is open.
+
+### `KasyCard`
+Elevated surface panel, radius `KasyRadius.lg` (16). The base for screen content.
+
+### `KasyScreen`
+Opt-in screen scaffold. A new page wrapped in it gets the internal-screen
+contract for free: page background, a centred content column capped at
+`maxContentWidth` (~600), the page gutter, scroll handling and an optional
+`KasyCard`. It is a thin convenience over `Scaffold` (same `appBar` /
+`floatingActionButton` / `bottomNavigationBar` slots), so it never blocks a
+screen that needs bespoke chrome.
+
+```dart
+KasyScreen(
+  appBar: KasyAppBar.root(title: 'Settings'),
+  card: true,
+  child: Column(children: [...]),
+)
+```
+
+---
+
+## Internal-screen contract
+
+New internal screens follow the sidebar / Home ruler:
+- Body text 14, icons 20 (`KasyIconSize.lg`), titles ~16-17 (`sectionTitle`).
+- `KasyCard` radius 16, content width contained (~600), no oversized boxes.
+- Use `KasyButton`, `showKasyConfirmDialog`, `showKasyToast` — not raw Material.
+- Haptics only on native (`if (!kIsWeb)`); "hide chrome on scroll" only on the
+  phone breakpoint (`width < 768`).
+
+---
+
+## Keeping it consistent — the guard-rail (optional)
+
+`tool/design_check.dart` is a plain Dart script that flags a **feature screen**
+reaching around the design system (raw `fontSize`, raw `Color`, raw Material
+widgets, literal icon sizes). The design system's own code (`lib/components`,
+`lib/core`, `lib/main.dart`) is out of scope — that is where the primitives are
+built.
+
+```bash
+dart run tool/design_check.dart
+```
+
+It is **opt-in and non-blocking by default**: nothing runs it automatically (not
+wired into `flutter analyze`, builds or git hooks). Run it locally or add it to
+CI to turn the convention into a gate. It has no extra dependency — read it, tune
+the allowlists at the top, or delete it. For a deliberate one-off, put
+`// design-check: ignore` on the line.
+
+This is intentionally not a cage: a project built with the kit can relax or drop
+it freely, and rebranding is still a token change (colours / type) in one place.
+
+---
+
+## Changelog
+
+### 1.1.0 — 2026-06-11
+- `KasyScreen` scaffold added (opt-in internal-screen contract).
+- Design guard-rail added (`tool/design_check.dart`), opt-in / non-blocking.
+- Feature layer brought to a green baseline against the guard-rail (deliberate
+  exceptions marked with `// design-check: ignore`).
+
+
+### 1.0.0 — 2026-06-11
+- Icon sizes centralised into `KasyIconSize`; product migrated off numeric sizes.
+- Semantic typography roles added (`pageTitle`, `sectionTitle`, `sectionLabel`,
+  `rowTitle`, …).
+- `KasyTextField`: `flat` variant + `forceFocusBorder`; single-line height
+  locked to **45** via derived padding (platform-independent); flat border role
+  `inputFieldFlatBorder` (visible in both themes, subtle).
+- `KasyButton` medium height aligned to **45**.
+- `KasyTextArea` gained the variant set.
+- App-bar title weight `w900 → w700`; onboarding titles `28/26 → 24` (page-title
+  scale); notifications group eyebrow → `sectionLabel`.

package/templates/firebase/docs/auth-setup.en.md

@@ -73,9 +73,9 @@ Requires an [Apple Developer](https://developer.apple.com) account (paid).
 >
 > **Android**: the Apple button is hidden by design (it needs the paid Services ID web flow and adds little on Android for a SaaS). Leave it hidden.
 >
-> **Web (Firebase)**: works after Steps 1-4 above (`withAppleWebSignin` already ships `true`). The Services ID Return URL (`firebaseapp.com/__/auth/handler`) covers the popup flow.
+> **Web (Firebase)**: after Steps 1-3, run `kasy apple-web` — it writes the Services ID + Team ID + Key ID + `.p8` into the Firebase Apple provider and turns on `withAppleWebSignin` (which ships `false`). The Services ID Return URL (`firebaseapp.com/__/auth/handler`) covers the popup flow. Firebase re-signs the secret itself (never expires).
 >
-> **Web (Supabase)**: the CLI ships `withAppleWebSignin = false` (native iOS works; web needs more). To enable it: in Supabase → Authentication → Providers → Apple, add the **client secret** (a JWT signed with your `.p8` key + Services ID), then set `withAppleWebSignin = true` in `lib/core/config/features.dart`.
+> **Web (Supabase)**: Apple on the web for Supabase is **not wired in the app yet** (roadmap) — the button stays hidden on web. On Supabase, Apple works on **native iOS only** (already set up by `kasy new`). See `ROADMAP.md`.
 
 ---
 
@@ -83,6 +83,8 @@ Requires an [Apple Developer](https://developer.apple.com) account (paid).
 
 Requires a [Meta for Developers](https://developers.facebook.com) account.
 
+> **Shortcut:** the `kasy facebook` command automates writing the credentials (Info.plist, strings.xml, and the Firebase/Supabase provider) and opens the Meta dashboard. The steps below are what you do on Meta (manual, no API).
+
 ### Step 1 — Create an app on Meta
 
 1. Open [Meta for Developers → My Apps](https://developers.facebook.com/apps)

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

@@ -73,9 +73,9 @@ Requiere cuenta de [Apple Developer](https://developer.apple.com) (de pago).
 >
 > **Android**: el botón Apple queda oculto por defecto (necesita el flujo del Services ID de pago y aporta poco en Android para un SaaS). Déjalo oculto.
 >
-> **Web (Firebase)**: funciona tras los Pasos 1 a 4 anteriores (`withAppleWebSignin` ya viene `true`). La Return URL del Services ID (`firebaseapp.com/__/auth/handler`) cubre el flujo de popup.
+> **Web (Firebase)**: tras los Pasos 1 a 3, ejecuta `kasy apple-web` — escribe el Services ID + Team ID + Key ID + `.p8` en el proveedor Apple de Firebase y activa `withAppleWebSignin` (que viene `false`). La Return URL del Services ID (`firebaseapp.com/__/auth/handler`) cubre el flujo de popup. Firebase vuelve a firmar el secret solo (no expira).
 >
-> **Web (Supabase)**: la CLI genera `withAppleWebSignin = false` (iOS nativo funciona; la web necesita más). Para habilitar: en Supabase → Authentication → Providers → Apple, agrega el **client secret** (un JWT firmado con la clave `.p8` + Services ID) y luego define `withAppleWebSignin = true` en `lib/core/config/features.dart`.
+> **Web (Supabase)**: Apple en la web para Supabase **aún no viene activado en la app** (roadmap) — el botón queda oculto en la web. En Supabase, Apple funciona solo en **iOS nativo** (ya configurado por `kasy new`). Consulta `ROADMAP.md`.
 
 ---
 
@@ -83,6 +83,8 @@ Requiere cuenta de [Apple Developer](https://developer.apple.com) (de pago).
 
 Requiere cuenta en [Meta for Developers](https://developers.facebook.com).
 
+> **Atajo:** el comando `kasy facebook` automatiza escribir las credenciales (Info.plist, strings.xml y el proveedor en Firebase/Supabase) y abre el panel de Meta. Los pasos de abajo son lo que haces en Meta (manual, sin API).
+
 ### Paso 1 — Crear una app en Meta
 
 1. Abre [Meta for Developers → My Apps](https://developers.facebook.com/apps)

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

@@ -73,9 +73,9 @@ Requer conta [Apple Developer](https://developer.apple.com) (paga).
 >
 > **Android**: o botão Apple fica escondido por padrão (exige o fluxo do Services ID pago e agrega pouco no Android para um SaaS). Deixe escondido.
 >
-> **Web (Firebase)**: funciona depois dos Passos 1 a 4 acima (`withAppleWebSignin` já vem `true`). A Return URL do Services ID (`firebaseapp.com/__/auth/handler`) cobre o fluxo de popup.
+> **Web (Firebase)**: depois dos Passos 1 a 3, rode `kasy apple-web` — ele grava o Services ID + Team ID + Key ID + `.p8` no provedor Apple do Firebase e liga `withAppleWebSignin` (que nasce `false`). A Return URL do Services ID (`firebaseapp.com/__/auth/handler`) cobre o fluxo de popup. O Firebase re-assina o secret sozinho (não expira).
 >
-> **Web (Supabase)**: a CLI gera `withAppleWebSignin = false` (iOS nativo funciona; web precisa de mais). Para habilitar: em Supabase → Authentication → Providers → Apple, adicione o **client secret** (um JWT assinado com a chave `.p8` + Services ID) e depois defina `withAppleWebSignin = true` em `lib/core/config/features.dart`.
+> **Web (Supabase)**: Apple na web no Supabase **não vem ligado no app ainda** (roadmap) — o botão fica escondido na web. No Supabase, o Apple funciona só no **iOS nativo** (já configurado pelo `kasy new`). Veja `ROADMAP.md`.
 
 ---
 
@@ -83,6 +83,8 @@ Requer conta [Apple Developer](https://developer.apple.com) (paga).
 
 Requer conta no [Meta for Developers](https://developers.facebook.com).
 
+> **Atalho:** o comando `kasy facebook` automatiza a parte de gravar as credenciais (Info.plist, strings.xml e o provedor no Firebase/Supabase) e abre o painel da Meta. Os passos abaixo são o que você faz na Meta (manual, sem API).
+
 ### Passo 1 — Criar app no Meta
 
 1. Abra [Meta for Developers → My Apps](https://developers.facebook.com/apps)

package/templates/firebase/firebase.json

@@ -1 +1,56 @@
-{"firestore":{"rules":"firestore.rules","indexes":"firestore.indexes.json"},"storage":{"rules":"storage.rules"},"functions":[{"source":"functions","codebase":"default","ignore":["node_modules",".git","firebase-debug.log","firebase-debug.*.log"],"predeploy":["npm --prefix \"$RESOURCE_DIR\" run build"]}],"flutter":{"platforms":{"android":{"default":{"projectId":"fir-kit-8e56b","appId":"1:613770689965:android:f800aacb0091708b0f7524","fileOutput":"android/app/google-services.json"}},"ios":{"default":{"projectId":"fir-kit-8e56b","appId":"1:613770689965:ios:7cc1f4579cf759fd0f7524","uploadDebugSymbols":false,"fileOutput":"ios/Runner/GoogleService-Info.plist"}},"dart":{"lib/firebase_options.dart":{"projectId":"fir-kit-8e56b","configurations":{"android":"1:613770689965:android:f800aacb0091708b0f7524","ios":"1:613770689965:ios:7cc1f4579cf759fd0f7524","web":"1:613770689965:web:e9347bac3b3eae5d0f7524"}}}}}}
+{
+  "hosting": {
+    "public": "build/web",
+    "ignore": ["firebase.json", "**/.*", "**/node_modules/**"],
+    "rewrites": [
+      { "source": "**", "destination": "/index.html" }
+    ],
+    "headers": [
+      {
+        "source": "**/@(index.html|flutter_bootstrap.js|flutter_service_worker.js|main.dart.js|main.dart.wasm|main.dart.mjs|manifest.json|version.json)",
+        "headers": [
+          { "key": "Cache-Control", "value": "no-cache, no-store, must-revalidate" }
+        ]
+      }
+    ]
+  },
+  "firestore": { "rules": "firestore.rules", "indexes": "firestore.indexes.json" },
+  "storage": { "rules": "storage.rules" },
+  "functions": [
+    {
+      "source": "functions",
+      "codebase": "default",
+      "ignore": ["node_modules", ".git", "firebase-debug.log", "firebase-debug.*.log"],
+      "predeploy": ["npm --prefix \"$RESOURCE_DIR\" run build"]
+    }
+  ],
+  "flutter": {
+    "platforms": {
+      "android": {
+        "default": {
+          "projectId": "fir-kit-8e56b",
+          "appId": "1:613770689965:android:f800aacb0091708b0f7524",
+          "fileOutput": "android/app/google-services.json"
+        }
+      },
+      "ios": {
+        "default": {
+          "projectId": "fir-kit-8e56b",
+          "appId": "1:613770689965:ios:7cc1f4579cf759fd0f7524",
+          "uploadDebugSymbols": false,
+          "fileOutput": "ios/Runner/GoogleService-Info.plist"
+        }
+      },
+      "dart": {
+        "lib/firebase_options.dart": {
+          "projectId": "fir-kit-8e56b",
+          "configurations": {
+            "android": "1:613770689965:android:f800aacb0091708b0f7524",
+            "ios": "1:613770689965:ios:7cc1f4579cf759fd0f7524",
+            "web": "1:613770689965:web:e9347bac3b3eae5d0f7524"
+          }
+        }
+      }
+    }
+  }
+}

package/templates/firebase/functions/src/authentication/triggers.ts

@@ -5,7 +5,7 @@ import {notificationsApi} from "../notifications/notifications_api";
 import {NotificationPayload, SystemNotificationParams} from "../notifications/models/notification";
 import {NotificationTypes} from "../core/data/entities/notification_entity";
 import {Timestamp} from "firebase-admin/firestore";
-import {usersRepository, userDevicesRepository} from "../core/data/repositories/repositories";
+import {usersRepository} from "../core/data/repositories/repositories";
 import * as functions from "firebase-functions/v1";
 import {onDocumentCreated} from "firebase-functions/v2/firestore";
 import {UserDeviceEntityData} from "../core/data/entities/user_device_entity";
@@ -52,9 +52,13 @@ export const onUserRegistration = functions
   });
 
 /**
- * Triggered when the user registers their first device.
- * Sends a localized welcome notification (saved to DB only, no push).
- * Fires on device creation so the device locale is available.
+ * Triggered when a device is registered.
+ * Sends a localized welcome notification ONCE per account (saved to DB only, no
+ * push). Fires on device creation so the device locale is available.
+ *
+ * The "once per account" guard is [UserRepository.claimWelcome], not a device
+ * count: a device re-registered after a logout/login cycle looks like a fresh
+ * first device, so counting devices re-sent the welcome on every re-login.
  */
 export const onFirstDeviceRegistered = onDocumentCreated(
   "users/{userId}/devices/{deviceId}",
@@ -62,8 +66,8 @@ export const onFirstDeviceRegistered = onDocumentCreated(
     const logger = new Logger("onFirstDeviceRegistered");
     const userId = event.params.userId;
     try {
-      const allDevices = await userDevicesRepository.getDevices([userId]);
-      if (allDevices.length > 1) return;
+      const shouldWelcome = await usersRepository.claimWelcome(userId);
+      if (!shouldWelcome) return;
 
       const deviceData = event.data?.data() as UserDeviceEntityData | undefined;
       // Flutter serializes as "extraData" (camelCase); Firestore schema uses "extra_data".

package/templates/firebase/functions/src/core/data/entities/subscription_entity.ts

@@ -13,6 +13,7 @@ export interface SubscriptionEntityData {
     creation_date: Timestamp;
     last_activity: Timestamp;
     expiration_date?: Timestamp;
+    trial_end?: Timestamp;
     status: SubscriptionStatus;
     store: Stores,
     product_id: string;
@@ -30,6 +31,7 @@ export class SubscriptionEntity {
     creation_date,
     last_activity,
     expiration_date,
+    trial_end,
     status,
     store,
     product_id,
@@ -41,6 +43,7 @@ export class SubscriptionEntity {
     this.creation_date = creation_date;
     this.last_activity = last_activity;
     this.expiration_date = expiration_date;
+    this.trial_end = trial_end;
     this.status = status;
     this.store = store;
     this.product_id = product_id;
@@ -66,6 +69,7 @@ export class SubscriptionEntity {
       creation_date: subscription.creationDate,
       last_activity: subscription.lastUpdate,
       expiration_date: subscription.expirationDate,
+      trial_end: subscription.trialEnd,
       status: subscription.status,
       store: subscription.store,
       product_id: subscription.productId,
@@ -78,6 +82,7 @@ export class SubscriptionEntity {
       creationDate: this.creation_date,
       lastUpdate: this.last_activity,
       expirationDate: this.expiration_date,
+      trialEnd: this.trial_end,
       status: this.status,
       store: this.store,
       productId: this.product_id,