vybekiit 0.4.0 → 0.6.0

package/dist/global-skills/expo-web-to-native/references/false-friends.md

@@ -0,0 +1,119 @@
+# False Friends: web idioms → native
+
+Disclosed reference for [`expo-web-to-native`](../SKILL.md). A *false friend* is a web idiom that looks portable but isn't - it compiles in your head, then breaks (or silently no-ops) on native. Each row is `web idiom → native equivalent → the gotcha`. Reach for this in steps 3–5 of a migration, and whenever you're learning native after the web.
+
+This is the single source of truth for the mapping; the SKILL.md steps name a few high-traffic swaps but defer the full list here.
+
+## Elements & text
+
+| Web | Native | Gotcha |
+|---|---|---|
+| `<div>`, `<section>`, `<span>` | `<View>` | `View` is the only generic container; no semantic element variants. |
+| `<p>`, `<h1>`, raw text in JSX | `<Text>` | **All** text must sit inside `<Text>`. Bare strings in a `View` throw. |
+| `<img src>` | `<Image>` / `expo-image` | `expo-image` adds caching, blurhash, transitions. Remote images need an explicit `width`/`height` or a flex parent. |
+| `<button>`, `<a>` | `<Pressable>` (or `TouchableOpacity`) | No default styling, no hover. Wrap label text in `<Text>`. |
+| `<input>` | `<TextInput>` | Controlled via `value` + `onChangeText` (not `onChange`/`e.target.value`). |
+| `<ul>/<li>` rendered with `.map()` | `<FlatList>` / `<FlashList>` | `.map()` over a long list mounts every row at once → jank. Use a virtualized list with `data` + `renderItem`. |
+
+## Events & interaction
+
+| Web | Native | Gotcha |
+|---|---|---|
+| `onClick` | `onPress` | Also `onLongPress`, `onPressIn/Out`. There is no click. |
+| `onChange={e => e.target.value}` | `onChangeText={text => ...}` | The handler receives the string directly, not an event. |
+| `onSubmit` (form) | `onPress` / `onSubmitEditing` | No `<form>` element and no submit event; wire the button/keyboard return key. |
+| `:hover`, `:focus` | press/focus state | No hover on touch. Track state and style from it, or use `Pressable`'s state callback. |
+| `e.preventDefault()` | — | No default actions to prevent; remove it. |
+
+## Styling & layout
+
+| Web | Native | Gotcha |
+|---|---|---|
+| `className` / CSS files | `StyleSheet.create` or NativeWind | Plain RN has no className. For Tailwind muscle memory use NativeWind (`expo-tailwind-setup`). |
+| CSS cascade & inheritance | none | Styles don't inherit (except a few `Text` props like `color`/`fontSize` to nested `Text`). Style each node. |
+| `display: flex` opt-in, default `row` | flex always on, default **`column`** | Biggest layout surprise: flex is the only layout model and the main axis is vertical by default. |
+| `px`, `rem`, `%` | unitless numbers (dp) | `padding: 16` = density-independent pixels. `%` works in some props; no `rem`/`em`/`vh`. |
+| `@media` queries | `useWindowDimensions()` / `Platform` | No media queries. Branch on dimensions or platform at runtime. |
+| `position: fixed` | `position: absolute` + safe area | No `fixed`. Pin with `absolute` and respect insets (`react-native-safe-area-context`). |
+| `z-index` | `zIndex` (+ `elevation` on Android) | Works mostly, but Android shadow/stacking also needs `elevation`. |
+| CSS transitions / `@keyframes` | `Animated` / Reanimated | No CSS animation. Reanimated is the standard; gestures via `react-native-gesture-handler`. |
+| `gap`, flexbox | `gap`, flexbox | These largely transfer — flexbox is the one big win for web devs. |
+
+## Navigation & URLs
+
+| Web | Native | Gotcha |
+|---|---|---|
+| React Router / Next.js routes | Expo Router (file-based) | File-based like Next App Router; `react-router` concepts map but the API differs. |
+| `<a href>` / `<Link>` | `expo-router` `<Link href>` | Works in DOM components too. |
+| `useNavigate()` / `router.push` | `useRouter()` from `expo-router` | `router.push/replace/back`. |
+| `useParams` / `useSearchParams` | `useLocalSearchParams()` | Note: doesn't work *inside* a DOM component - read in the native parent, pass as props (see `expo-dom`). |
+| `window.location` | `usePathname()` / router | No `location` object. |
+| Deep links / `myapp://` | URL scheme + universal links | Configure `scheme` in app config; native gives you real deep linking and (with AASA) app links - see `expo-app-clip` for the AASA file. |
+
+## React architecture & data (Next.js / SSR apps)
+
+| Web | Native | Gotcha |
+|---|---|---|
+| Async Server Component (`async function Page()`) | client component + data fetch | No RSC on native (Expo's is experimental and different). Split into a client component that fetches via the API + a presentational child *before* porting. |
+| Server actions (`'use server'`) | API route + `fetch` | No server actions. Expose an endpoint and call it. |
+| `cookies()` / `headers()` (server) | token in `expo-secure-store` | Server-only. Auth moves to a bearer token sent as a header. |
+| ORM / DB client in a page (Drizzle, Prisma) | server only - call over HTTP | The device never talks to the DB. Keep the backend deployed, or move routes to EAS Hosting (`eas-hosting`); the app fetches. |
+| `next/navigation` (`notFound`, `redirect`) | `expo-router` | `redirect()` → `router.replace`; `notFound()` → a native `+not-found` route. |
+| `_layout` as a DOM component | always native | Layout routes can't be DOM components — they *are* the native shell. Rewrite web-only layout logic (theme scripts, providers) with native APIs. |
+
+## Storage, state & sessions
+
+| Web | Native | Gotcha |
+|---|---|---|
+| `localStorage` / `sessionStorage` | `expo-sqlite` (`globalThis.localStorage`) | `import 'expo-sqlite/localStorage/install';` polyfills the global `localStorage`, so existing code works as-is (or `expo-sqlite/kv-store`). **No `sessionStorage` equivalent** — native has no session concept. |
+| Cookies / `document.cookie` | `expo-secure-store` + headers | No cookie jar by default. Store tokens in SecureStore; send as auth headers. |
+| Auth via session cookie | token in SecureStore | Redesign auth around bearer tokens, not browser sessions. |
+| In-memory React state | same | `useState`/`useReducer`/`useContext` transfer unchanged. |
+
+## Browser & platform APIs
+
+| Web | Native | Gotcha |
+|---|---|---|
+| `window`, `document` | none | Don't exist. Guard web-only libs, or keep them in a DOM component (`expo-dom`). |
+| `window.matchMedia('(prefers-color-scheme: dark)')` | `useColorScheme()` | Hook from `react-native`, reactive to the system theme. Web theme bootstrap scripts in the layout don't run. |
+| `window.innerWidth/Height` | `useWindowDimensions()` | Reactive hook; updates on rotation. |
+| `navigator.*`, Web APIs | Expo SDK modules | e.g. camera → `expo-camera`, geolocation → `expo-location`, clipboard → `expo-clipboard`. |
+| `alert()` / `confirm()` / `prompt()` | `alert()` works; `Alert.alert(...)` for the rest | RN provides a global `alert()`; `confirm()` / `prompt()` don't exist — use `Alert.alert` with a button array. |
+| `process.env.X` | `process.env.EXPO_PUBLIC_X` | Only `EXPO_PUBLIC_`-prefixed vars are inlined into the client bundle. |
+| `console.log` | `console.log` | Works — shows in the dev tools/terminal. |
+| `dangerouslySetInnerHTML` | — | No DOM to inject into. Render data, or use a DOM component / WebView. |
+| inline SVG | `react-native-svg` | No native `<svg>`; the library mirrors the element API. |
+
+## Networking
+
+| Web | Native | Gotcha |
+|---|---|---|
+| `fetch('/api/x')` (relative) | absolute URL | Native has no origin — relative paths fail. Use a configured base URL (`EXPO_PUBLIC_API_URL`). |
+| CORS | n/a | No browser CORS, but you still need a reachable absolute host. |
+| `fetch`, React Query, SWR | same | The libraries themselves work on native - see `expo-data-fetching`. |
+| Next.js API routes | Expo Router API routes | Move server endpoints to Expo API routes on EAS Hosting - see `eas-hosting`. |
+| Streaming responses (SSE, AI SDK `useChat`) | `expo/fetch` with `textStreaming` | RN's built-in `fetch` can't read a streaming response body. Use `expo/fetch` (streams, and works with the Vercel AI SDK) or an XHR-based polyfill. |
+
+## Third-party services & SDKs
+
+Browser SDKs don't run on native — each needs a native equivalent. The canonical, version-matched integrations live in the `expo-examples` skill (the `expo/examples` repo); reach for those instead of wiring from scratch.
+
+| Web service | Native | Gotcha |
+|---|---|---|
+| **Stripe.js — digital goods / subscriptions** | store **In-App Purchase** via **RevenueCat** (`react-native-purchases`) | **Policy, not just an SDK swap.** Apple & Google *require* IAP for in-app digital goods and take ~15–30%; shipping Stripe for them gets the app rejected. Decide at assess time — it can change the business model. |
+| **Stripe.js — physical goods / services** | `@stripe/stripe-react-native` (PaymentSheet, Apple/Google Pay) | Stripe's RN SDK is allowed for physical goods; see `expo-examples` `with-stripe`. |
+| Google Maps JS | `react-native-maps` | A native map view, not an embedded iframe. |
+| Web Push | `expo-notifications` (APNs / FCM) | Different delivery + permission model. |
+| OAuth redirect flow | `expo-auth-session` (deep-link OAuth), or a native auth SDK (Clerk, Supabase…) | No browser redirect — an app deep link completes the flow. |
+| GA / Segment.js analytics | native SDK (`posthog-react-native`, Segment RN) | The web JS snippet won't load; swap for the native SDK. |
+| `<input type=file>` / `getUserMedia` | `expo-image-picker` / `expo-camera` / `expo-document-picker` | Native pickers + runtime permissions. |
+
+## Scrolling, keyboard & safe area
+
+| Web | Native | Gotcha |
+|---|---|---|
+| Body scrolls by default | `<ScrollView>` / `<FlatList>` | Nothing scrolls unless you make it. Wrap overflowing content explicitly. |
+| `overflow: scroll` | `<ScrollView>` | Don't nest a `ScrollView` inside a `FlatList` of the same axis. |
+| Keyboard overlaps inputs | `KeyboardAvoidingView` | The keyboard covers inputs by default; wrap forms to push content up. |
+| Notch / status bar | `react-native-safe-area-context` | Content flows under the notch/home indicator unless you apply safe-area insets. |
+| `:focus` ring, tab order | manual | No automatic focus management; wire `ref`/`focus()` and `returnKeyType`. |

package/dist/global-skills/expo-web-to-native/references/native-patterns.md

@@ -0,0 +1,39 @@
+# Native patterns: redesigning web UX for native
+
+Disclosed reference for [`expo-web-to-native`](../SKILL.md), step 4. `false-friends.md` translates *idioms* (`div` → `View`); this translates *UX patterns* - a web interaction into its native equivalent. Step 4 isn't a port, it's this redesign.
+
+**Reach for `@expo/ui` first.** It renders real SwiftUI (iOS) and Jetpack Compose (Android), so its components look and feel *exactly* like the OS — the difference between "native-ish RN" and "indistinguishable from an app Apple/Google shipped." See the `expo-ui` skill. Drop to styled RN primitives only for what `@expo/ui` doesn't cover: custom layouts (chat bubbles, bespoke cards) and **large data lists** (`@expo/ui` `List` is a JS-thread node per item — use `FlashList`/`FlatList` for feeds). `@expo/ui` runs in **Expo Go** (SDK 56+) — no dev build needed; reach for a dev build (the `expo-dev-client` skill) only for *custom* native modules.
+
+| Web pattern | Native redesign — reach for first | Why |
+|---|---|---|
+| Top tab bar / nav links | **NativeTabs** - bottom, liquid glass on iOS 26 (`expo-router`) | Thumb-reachable, OS-native bar |
+| Page header / breadcrumb | **large-title** Stack header + header **search field** (`expo-router`) | The native screen frame |
+| In-page tabs / toggle group | **SegmentedControl** — `@expo/ui` (`community/segmented-control`) | Native segmented switch |
+| Modal / dialog | **BottomSheet** — `@expo/ui` | Sheets *are* the native modal |
+| `<select>` / dropdown | **Picker**, or long-press **MenuView** — `@expo/ui` (`community/menu`) | Native wheel / menu, no popover |
+| Accordion / "show more" | **Collapsible** — `@expo/ui` | Native disclosure |
+| Settings / short list | **List** + **FieldGroup** rows (Switch / Picker / TextInput) — `@expo/ui` | The Settings-app look |
+| Data feed / table / long list | **FlashList** / `FlatList`, virtualized + momentum | Tables don't exist on mobile; `@expo/ui` `List` isn't for big data |
+| Checkbox / toggle | **Switch** (on/off) or **Checkbox** (multi-select) — `@expo/ui` | Native control, not a styled box |
+| Date / time input | **DateTimePicker** — `@expo/ui` (`community/datetime-picker`) | Native wheel / calendar |
+| Range slider | **Slider** — `@expo/ui` | |
+| Onboarding / carousel / swipe pages | **PagerView** — `@expo/ui` (`community/pager-view`) | Native paging, not a scroll strip |
+| Refresh button / auto-poll | pull-to-refresh (`RefreshControl`) | The native refresh gesture |
+| Hover menu / tooltip | long-press **MenuView** context menu — `@expo/ui` (`community/menu`) | No hover on touch |
+| Toast / snackbar | native banner + **haptic** (`expo-haptics`) | |
+| Buttons | `@expo/ui` **Button**; `Pressable` for custom | Native press + haptics |
+| Multi-column layout | single column + tabs / stack | One thing at a time on a phone |
+
+**The test:** if a screenshot of the native screen could pass for the web version, you reskinned it. Redesign until it could pass for a screen the OS shipped.
+
+## Feel — beyond the components
+
+The table gets the right *components*; "native" also lives in *motion and touch* - and a web port arrives with almost none, so you must add it. The tooling is in `expo-router` (navigation/transitions) and `expo-native-ui` (motion/effects); reach for it, don't hand-roll:
+
+- **Transitions for free** - use Expo Router's native-stack so push/pop, modals, and sheets animate with real platform physics; shared-element zoom via `expo-router` `zoom-transitions.md`.
+- **Motion** - Reanimated (`withSpring`/`withTiming`; `entering`/`exiting` for list items) + `react-native-gesture-handler` for swipes/drags → `expo-native-ui` `animations.md`.
+- **Touch** — `expo-haptics` on commits, selection changes, and pull-to-refresh — choreography, not just a toast buzz.
+- **Native rhythm** — large-title collapse on scroll, momentum / inverted scroll, a keyboard that pushes content (`KeyboardAvoidingView`).
+- **Respect reduced motion** — gate non-essential animation on Reanimated's `useReducedMotion()`.
+
+**Feel can't be screenshotted.** A janky transition or wrong easing passes a still-image parity check and still betrays the app — for screens with motion, verify with a short recording (iOS `xcrun simctl io booted recordVideo feel.mov`; Android `adb shell screenrecord`; or a device-agent flow), not just a screenshot.

package/dist/global-skills/expo-web-to-native/references/run-as-goal.md

@@ -0,0 +1,48 @@
+# Run the migration as a goal loop
+
+Disclosed reference for [`expo-web-to-native`](../SKILL.md) - the recommended way to drive the whole migration. The migration is a repeat-until-done loop (assess → nativize each screen → verify → check off), which is exactly the shape of a **goal loop**: a single objective re-injected every turn until the worklist is empty. This file carries a ready-shaped, migration-specific objective - and, crucially, the objective **re-reads this skill every iteration**, so the loop keeps following the playbook (and self-bootstraps the assess step if no worklist exists yet).
+
+Use it in one of two modes depending on the agent you're running.
+
+## Mode A — the agent can run a goal loop
+
+Harnesses with a goal/loop command (Claude Code `/goal`, Codex CLI, or any harness of the same shape) can drive this themselves. Fill the template below and hand it to that command — the loop re-runs it until `migration-progress.md` has no unchecked nativize-now items.
+
+## Mode B — the agent can't loop itself
+
+Write the filled-in objective to `migration-goal.md` in the project, then give the user the one-line instruction to launch it (e.g. *"run your agent's goal loop with the objective in `migration-goal.md`"*). The objective is plain text and portable, so the user runs it in whatever harness they have.
+
+## The objective (template)
+
+Fill the two `<…>` slots, then run or hand off verbatim. It is written to survive re-injection — it restates its own worklist, direction, and stop condition every turn.
+
+```
+Goal: migrate <APP NAME> from web to a native Expo app by following the expo-web-to-native skill, one screen per iteration, until done.
+
+Each iteration, FIRST re-read the playbook - plugins/expo/skills/expo-web-to-native/SKILL.md (and its references) - then:
+1. If migration-progress.md doesn't exist yet, do the skill's step 1 (Assess) to
+   create the worklist, then stop. Otherwise open it and take the top unchecked
+   item under "nativize-now"; if none are left unresolved (every nativize-now is
+   done or blocked), STOP and summarize what shipped + what's blocked and why.
+2. Redesign that screen native per the skill's step 4 — reach for @expo/ui FIRST
+   (real SwiftUI/Compose), then expo-router (NativeTabs, large titles);
+   RN primitives only for custom layouts. NEVER a webview port.
+   Use references/native-patterns.md (UX patterns) and references/false-friends.md
+   (idioms). Match the web screen's content and behavior.
+3. Verify per references/verify-on-device.md: compare the running web original
+   (browser agent) against the native screen (simulator / argent) — content and
+   behavior parity, NOT pixels (it should look more native). If it's off for reasons
+   IN the code, fix it this iteration. If it's blocked by something OUTSIDE the code
+   (missing backend/auth/data, or a secret you can't supply), don't loop — mark it
+   blocked in step 4 and move on.
+4. Check the item off in migration-progress.md, appending one line:
+   "<screen> — done", or "<screen> — blocked: <reason> — needs <what would unlock>".
+   Either way the item is resolved; never revisit a blocked one.
+
+Rules: one screen per pass; the app builds green each iteration; @expo/ui before RN primitives; never touch "nativize-later" items.
+Base API URL for native (no relative paths): <EXPO_PUBLIC_API_URL>
+```
+
+## Why a pre-shaped objective
+
+The objective is filled in for this migration — worklist, redesign rules, and self-verification path already wired to the skill's references — so you can launch the loop without authoring one from scratch. Tailor the `<…>` slots and direction when a specific migration needs more than the template covers.

package/dist/global-skills/expo-web-to-native/references/verify-on-device.md

@@ -0,0 +1,45 @@
+# Verify a migrated screen against the running web app
+
+Disclosed reference for [`expo-web-to-native`](../SKILL.md), steps 3–4. Verification means **running both apps and comparing the same screen** - the native port beside the web original. A clean compile or a green `expo export` proves nothing - a screen can build and still render blank or mis-render. This parity check is the gate the strangle loop runs each iteration.
+
+Two agents drive it, and this skill is **opinionated**: it requires both and installs them rather than falling back to manual screenshots.
+
+- **Web side — `agent-browser`** (vercel-labs, a Rust browser CLI): `open <url>`, `snapshot --json` (accessibility tree with refs), `screenshot <path>`, `read` (rendered DOM/text).
+- **Native side — `argent`** (`@swmansion/argent`): drives the simulator — `describe` (a11y tree), `debugger-component-tree` (RN tree), `gesture-tap`/`keyboard`, `flow` to record a check and replay it each pass. Invoke as `argent run <tool> --udid <udid>` (get the udid from `argent run list-devices`).
+
+## Setup — install if missing (don't skip, don't fall back to manual)
+
+Check both are on PATH; if either is absent, ask the user, then install before proceeding:
+
+```bash
+which agent-browser || (npm i -g agent-browser && agent-browser install)   # web agent (+ its Chrome)
+which argent        || npm i -g @swmansion/argent                          # device agent
+```
+
+## The workflow
+
+**A. Capture the web original** with agent-browser — the source of truth for parity. Run the web app (its `pnpm dev` server, or the **deployed URL** if local setup needs DB/auth env), then:
+
+```bash
+agent-browser open "<web-url>/<route>?<params>"
+agent-browser snapshot --json      # structure to diff
+agent-browser screenshot web.png   # visual reference
+```
+
+**Tip:** capture web baselines for every screen once, up front, then diff against them instead of re-opening the web app each iteration.
+
+**B. Capture the native screen** (iOS shown via `simctl`; Android note below):
+1. Run the app: `npx expo start --ios` (Expo Go). On **SDK 56+ both `@expo/ui` and DOM components run in Expo Go** — no dev build, no `react-native-webview` to install; reach for a dev build (the `expo-dev-client` skill) only for *custom* native modules. Stale-bundle trap: a CI-mode Metro + cached Expo Go can show an old build — terminate Expo Go and add `--clear` if a change doesn't appear.
+2. Boot a sim: `xcrun simctl boot <udid>` (`xcrun simctl list devices available`); `open -a Simulator`.
+3. Open the route: deep-link `xcrun simctl openurl booted "exp://<lan-ip>:8081/--/<route>?<params>"`, or argent `launch-app` + `gesture-tap`.
+4. Capture: `xcrun simctl io booted screenshot native.png`, or `argent run describe --udid <udid>` for structure.
+
+> **Android:** `simctl` / `expo run:ios` are iOS-only. Use an Android emulator + `adb` — `adb exec-out screencap -p > native.png`, `adb shell am start -a android.intent.action.VIEW -d "<deep-link>"`, `adb shell screenrecord` for motion — or `npx expo run:android` for a dev build.
+
+**C. Compare** the two for the same route — layout, content, behavior. Diff the structures (agent-browser `snapshot` against argent `describe` / `debugger-component-tree`), not just pixels. Pass only on parity: same data, and params passed into a DOM webview must produce the same result.
+
+**Feel needs motion, not a still.** For a nativized screen with transitions, gestures, or haptics, a screenshot can't catch a janky push or wrong easing — capture a short recording (iOS `xcrun simctl io booted recordVideo feel.mov`; Android `adb shell screenrecord`; or an argent flow) and confirm it moves like a native app (see `native-patterns.md` → Feel).
+
+## What "pass" looks like
+- **DOM-shelled screen (step 3):** the web UI renders inside the native header/shell; params from the native route drive it the same as on web.
+- **Nativized screen (step 4):** native primitives only, no webview; matches the web original screen.

package/dist/global-skills/firebase-ai-logic-basics/SKILL.md

@@ -0,0 +1,165 @@
+---
+name: firebase-ai-logic-basics
+description: Official skill for integrating Firebase AI Logic (Gemini API) into web applications. Covers setup, multimodal inference, structured output, and security.
+version: 1.0.1
+---
+
+# Firebase AI Logic Basics
+
+## Overview
+
+Firebase AI Logic is a product of Firebase that allows developers to add gen AI
+to their mobile and web apps using client-side SDKs. You can call Gemini models
+directly from your app without managing a dedicated backend. Firebase AI Logic,
+which was previously known as "Vertex AI for Firebase", represents the evolution
+of Google's AI integration platform for mobile and web developers.
+
+It supports the two Gemini API providers:
+
+- **Gemini Developer API**: It has a free tier ideal for prototyping, and
+  pay-as-you-go for production
+- **Vertex AI Gemini API**: Ideal for scale with enterprise-grade production
+  readiness, requires Blaze plan
+
+Use the Gemini Developer API as a default, and only Vertex AI Gemini API if the
+application requires it.
+
+## Setup & Initialization
+
+### Prerequisites
+
+- Before starting, ensure you have **Node.js 16+** and npm installed. Install
+  them if they aren’t already available.
+- Identify the platform the user is interested in building on prior to starting:
+  Android, iOS, Flutter or Web.
+- If their platform is unsupported, Direct the user to Firebase Docs to learn
+  how to set up AI Logic for their application (share this link with the user
+  https://firebase.google.com/docs/ai-logic/get-started)
+
+### Installation
+
+The library is part of the standard Firebase Web SDK.
+
+`npm install -g firebase@latest`
+
+If you're in a firebase directory (with a firebase.json) the currently selected
+project will be marked with "current" using this command:
+
+`npx -y firebase-tools@latest projects:list`
+
+Ensure there's at least one app associated with the current project
+
+`npx -y firebase-tools@latest apps:list`
+
+Initialize AI logic SDK with the init command
+
+`npx -y firebase-tools@latest init ailogic`
+
+This will automatically enable the Gemini Developer API in the Firebase console.
+
+More info in
+[Firebase AI Logic Getting Started](https://firebase.google.com/docs/ai-logic/get-started.md.txt)
+
+## Core Capabilities
+
+> [!WARNING] **CRITICAL: Use current model names:** Always check the
+> [Firebase AI Logic Models documentation](https://firebase.google.com/docs/ai-logic/models.md.txt)
+> for the currently supported model names. Do NOT use `gemini-2.0-pro` or
+> `gemini-2.0-flash` or other older models that are shutdown.
+
+### Text-Only Generation
+
+### Multimodal (Text + Images/Audio/Video/PDF input)
+
+Firebase AI Logic allows Gemini models to analyze image files directly from your
+app. This enables features like creating captions, answering questions about
+images, detecting objects, and categorizing images. Beyond images, Gemini can
+analyze other media types like audio, video, and PDFs by passing them as inline
+data with their MIME type. For files larger than 20 megabytes (which can cause
+HTTP 413 errors as inline data), store them in Cloud Storage for Firebase and
+pass their URLs to the Gemini Developer API.
+
+### Chat Session (Multi-turn)
+
+Maintain history automatically using `startChat`.
+
+### Streaming Responses
+
+To improve the user experience by showing partial results as they arrive (like a
+typing effect), use `generateContentStream` instead of `generateContent` for
+faster display of results.
+
+### Generate Images with Nano Banana
+
+> [!WARNING] **Use current Image model names:** Always check the
+> [Firebase AI Logic Models documentation](https://firebase.google.com/docs/ai-logic/models.md.txt)
+> for the currently supported image generation (Nano Banana) model names.
+
+- Requires an upgraded Blaze pay-as-you-go billing plan.
+
+### Search Grounding with the built in googleSearch tool
+
+## Supported Platforms and Frameworks
+
+Supported Platforms and Frameworks include Kotlin and Java for Android, Swift
+for iOS, JavaScript for web apps, Dart for Flutter, and C Sharp for Unity.
+
+## Advanced Features
+
+### Structured Output (JSON)
+
+Enforce a specific JSON schema for the response.
+
+### On-Device AI (Hybrid)
+
+Hybrid on-device inference for web apps, where the Firebase Javascript SDK
+automatically checks for Gemini Nano's availability (after installation) and
+switches between on-device or cloud-hosted prompt execution. This requires
+specific steps to enable model usage in the Chrome browser, more info in the
+[hybrid-on-device-inference documentation](https://firebase.google.com/docs/ai-logic/hybrid-on-device-inference.md.txt).
+
+## Security & Production
+
+### App Check
+
+> [!WARNING] **Critical Safety Requirement:** In order to use AI Logic safely,
+> you MUST set up App Check on your app. This prevents unauthorized clients from
+> using your API quota and accessing your backend resources.
+
+See
+[App Check with reCAPTCHA Enterprise](https://firebase.google.com/docs/app-check/web/recaptcha-enterprise-provider.md.txt)
+for setup instructions.
+
+### Remote Config
+
+Consider that you do not need to hardcode model names (e.g., a specific model
+version string). Use Firebase Remote Config to update model versions dynamically
+without deploying new client code. See
+[Changing model names remotely](https://firebase.google.com/docs/ai-logic/change-model-name-remotely.md.txt)
+
+> [!WARNING] **CRITICAL: Backend Provisioning Required** For all platforms
+> (Flutter, Android, iOS, Web), you MUST run `npx firebase-tools init ailogic`
+> to provision the service. `flutterfire configure` ONLY handles client
+> configuration and does NOT enable the AI service, leading to
+> `PERMISSION_DENIED` errors.
+
+## Initialization Code References
+
+| Language, Framework, Platform | Gemini API provider                  | Context URL                                     |
+| :---------------------------- | :----------------------------------- | :---------------------------------------------- |
+| Web Modular API               | Gemini Developer API (Developer API) | firebase://docs/ai-logic/get-started            |
+| iOS (Swift)                   | Gemini Developer API                 | [ios_setup.md](references/ios_setup.md)         |
+| Flutter (Dart)                | Gemini Developer API                 | [flutter_setup.md](references/flutter_setup.md) |
+
+> [!WARNING] **CRITICAL: Use current model names:** Always check the
+> [Firebase AI Logic Models documentation](https://firebase.google.com/docs/ai-logic/models.md.txt)
+> for the currently supported model names. Do NOT use `gemini-2.0-pro` or
+> `gemini-2.0-flash` or other older models that are shutdown.
+
+## References
+
+[Web SDK code examples and usage patterns](references/usage_patterns_web.md)
+[iOS SDK code examples and usage patterns](references/ios_setup.md)
+[Flutter SDK code examples and usage patterns](references/flutter_setup.md)
+
+[Android (Kotlin) SDK usage patterns](references/usage_patterns_android.md)

package/dist/global-skills/firebase-ai-logic-basics/references/flutter_setup.md

@@ -0,0 +1,95 @@
+# Flutter Setup for Firebase AI Logic
+
+This guide covers how to integrate Firebase AI Logic (Gemini API) into your
+Flutter applications.
+
+> [!IMPORTANT] **Foundational Workflows & CLI-First Approach:**
+>
+> 1. **Review Foundation:** Before implementing platform-specific code, ALWAYS
+>    review the foundational `firebase-basics` skill to ensure familiarity with
+>    core workflows.
+> 1. **Backend Provisioning via CLI:** Use the Firebase CLI for backend setup.
+>    Running `npx firebase-tools init ailogic` is MANDATORY to provision the
+>    service. `flutterfire configure` does NOT enable the AI service and will
+>    result in `PERMISSION_DENIED` if skipped.
+> 1. **Client Configuration:** Use `flutterfire configure` strictly for
+>    generating `firebase_options.dart`. Avoid manual Console configuration.
+
+> [!NOTE] `firebase_vertexai` has been replaced by `firebase_ai`. Always use
+> `firebase_ai` for new projects.
+
+## Installation
+
+Add the necessary Firebase dependencies to your `pubspec.yaml`:
+
+```yaml
+dependencies:
+  flutter:
+    sdk: flutter
+  firebase_core: ^4.0.0
+  firebase_auth: ^6.0.0
+  firebase_ai: ^3.0.0
+```
+
+Run `flutter pub get` to install the packages.
+
+## Initialization
+
+Initialize Firebase and sign in (anonymously or via authenticated user) before
+using AI Logic.
+
+```dart
+import 'package:firebase_core/firebase_core.dart';
+import 'package:firebase_auth/firebase_auth.dart';
+import 'package:firebase_ai/firebase_ai.dart';
+
+void main() async {
+  WidgetsFlutterBinding.ensureInitialized();
+  await Firebase.initializeApp();
+  await FirebaseAuth.instance.signInAnonymously();
+  runApp(const MyApp());
+}
+```
+
+## Usage
+
+Use `FirebaseAI.googleAI` for the **Gemini Developer API**.
+
+> [!IMPORTANT] **Model Selection:** Refer to
+> [Firebase AI Logic Models](https://firebase.google.com/docs/ai-logic/models.md.txt)
+> to find the latest supported model. Do not use old models like
+> `gemini-2.0-pro` or `gemini-2.0-flash`.
+
+> [!IMPORTANT] **Choose the Right API Provider:** Always use
+> `FirebaseAI.googleAI` (Gemini Developer API) as the default for prototyping
+> and standard use. Avoid using the Vertex AI Gemini API unless your application
+> specifically requires enterprise-grade scalability and is configured for the
+> Blaze plan.
+
+### Text Generation
+
+```dart
+import 'package:firebase_ai/firebase_ai.dart';
+import 'package:firebase_auth/firebase_auth.dart';
+
+Future<String> generateText(String prompt) async {
+  final googleAI = FirebaseAI.googleAI(auth: FirebaseAuth.instance);
+  
+  // [AGENT] Replace '<latest_supported_model>' with the latest model from https://firebase.google.com/docs/ai-logic/models.md.txt
+  final model = googleAI.generativeModel(model: '<latest_supported_model>');
+
+  final response = await model.generateContent([Content.text(prompt)]);
+  return response.text ?? 'No response';
+}
+```
+
+### Chat Session
+
+```dart
+final chat = model.startChat(history: [
+  Content.text('Hello, I am a user.'),
+  Content.model([TextPart('Hello! How can I help you today?')]),
+]);
+
+final response = await chat.sendMessage(Content.text('What is CBT?'));
+```