feat: add brownie skills

skills/brownie/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: brownie
+description: Provides guidance for shared state in React Native brownfield apps with @callstack/brownie. Define stores in TypeScript, run brownfield codegen, use the generated APIs in React Native and native hosts, and package native artifacts for integration.
+license: MIT
+metadata:
+  author: Callstack
+  tags: react-native, expo, brownfield, state-management, brownie
+---
+
+# Overview
+
+Brownie provides cross-platform shared state for React Native brownfield apps. The workflow starts from `*.brownie.ts` store definitions, runs `brownfield codegen` (or packaging commands that include codegen), then uses typed APIs on TypeScript, Android, and iOS sides.
+
+# When to Apply
+
+Reference this skill when:
+- Setting up `@callstack/brownie` in an existing brownfield app
+- Defining or changing store schemas in `*.brownie.ts`
+- Using `useStore`, `subscribe`, `getSnapshot`, or `setState` on the JS side
+- Registering and consuming stores in Android or iOS hosts
+- Packaging and embedding iOS frameworks that include Brownie
+
+# Quick Reference
+
+- Install Brownie:
+```bash
+npm install @callstack/brownie
+```
+- Generate native types:
+```bash
+npx brownfield codegen
+```
+- Packaging commands also include Brownie codegen:
+```bash
+# iOS
+npx brownfield package:ios --scheme YourScheme --configuration Release
+
+# Android
+npx brownfield package:android --module-name :YourModuleName --variant release
+npx brownfield publish:android --module-name :YourModuleName
+```
+
+## Routing (concern -> file)
+
+Concern | Read
+--------|------
+Initial install, prerequisites, setup sequence, first integration pass | [`getting-started.md`](references/getting-started.md)
+`*.brownie.ts` schema rules, `BrownieStores` augmentation, type mapping, when to rerun codegen | [`store-definition-and-codegen.md`](references/store-definition-and-codegen.md)
+`useStore` selectors, update patterns, low-level APIs (`subscribe`, `getSnapshot`, `setState`) | [`typescript-usage.md`](references/typescript-usage.md)
+Android registration lifecycle, serializer options, package settings, build and publish flow | [`android-usage.md`](references/android-usage.md)
+Swift store registration and UI usage, plus XCFramework packaging and embedding | [`swift-and-xcframework.md`](references/swift-and-xcframework.md)

skills/brownie/references/android-usage.md

@@ -0,0 +1,83 @@
+# Brownie Android Usage
+
+## Discoverability triggers
+
+- "registerStoreIfNeeded brownie"
+- "Brownie Android setup package.json kotlin path"
+- "Brownie custom serializer kotlin"
+- "brownfield package android brownie publish"
+
+## Scope
+
+In scope:
+- Android-side store registration lifecycle.
+- Brownie Android package configuration and Gson dependency requirements.
+- Easy path and advanced serializer options in Kotlin.
+- Packaging and publish flow for AAR distribution.
+
+Out of scope:
+- Initial installation and first setup checklist. For that, read [`getting-started.md`](getting-started.md) in this folder.
+- Store schema authoring and codegen file design. For that, read [`store-definition-and-codegen.md`](store-definition-and-codegen.md) in this folder.
+- React Native hook-level patterns. For that, read [`typescript-usage.md`](typescript-usage.md) in this folder.
+- iOS Swift and XCFramework guidance. For that, read [`swift-and-xcframework.md`](swift-and-xcframework.md) in this folder.
+
+## Procedure
+
+1. Confirm Android configuration
+   - `package.json` includes a `brownie` block with:
+     - `kotlin` output directory
+     - `kotlinPackageName`
+
+2. Ensure serializer dependency strategy
+   - Brownie Android default serializer path requires Gson at runtime.
+   - Hard requirement: do not complete integration unless `com.google.code.gson:gson` is present in the brownfield module or native app dependency graph.
+
+3. Generate/build/publish artifacts
+   - Build AAR with:
+     - `npx brownfield package:android --module-name :YourModuleName --variant release`
+   - Publish to local Maven with:
+     - `npx brownfield publish:android --module-name :YourModuleName`
+   - `package:android` also runs Brownie codegen before packaging.
+
+4. Register store at startup
+   - Use `registerStoreIfNeeded` once during startup to avoid duplicate registration.
+   - Keep registration before native UI or JS flow assumes store availability.
+   - `registerStoreIfNeeded` returns `null` if the store key is already registered.
+
+5. Access and update typed store
+   - Retrieve with `StoreManager.shared.store<T>(STORE_NAME)`.
+   - Read from `store.state`, update via `store.set { ... }`, observe via `store.subscribe(...)`.
+
+6. Use advanced serializers only when required
+   - Use `brownieStoreDefinition(..., serializer = ...)` or `encode`/`decode` lambdas.
+   - Keep decode/encode logic deterministic and version aware for backward compatibility.
+
+## Compact Kotlin example
+
+```kotlin
+import com.callstack.brownie.StoreManager
+import com.callstack.brownie.registerStoreIfNeeded
+import com.callstack.brownie.store
+import com.rnapp.brownfieldlib.AppStore
+
+registerStoreIfNeeded(storeName = AppStore.STORE_NAME) {
+  AppStore(counter = 0.0)
+}
+
+val store = StoreManager.shared.store<AppStore>(AppStore.STORE_NAME)
+store?.set { state -> state.copy(counter = state.counter + 1) }
+```
+
+## Quick reference
+
+- Startup registration: `registerStoreIfNeeded(storeName) { initialState }`
+- Store lookup: `StoreManager.shared.store<T>(STORE_NAME)`
+- Required runtime dependency: `com.google.code.gson:gson`
+- Packaging:
+  - `npx brownfield package:android --module-name :YourModuleName --variant release`
+  - `npx brownfield publish:android --module-name :YourModuleName`
+- Error cues this guide handles:
+  - Store not found due to missing registration
+  - `ClassNotFoundException: com.google.gson.Gson` due to missing Gson dependency
+  - Decode/encode issues in custom serializer path
+  - Generated classes not found due to wrong `kotlinPackageName` or output path

skills/brownie/references/getting-started.md

@@ -0,0 +1,80 @@
+# Brownie Getting Started
+
+## Discoverability triggers
+
+- "install @callstack/brownie"
+- "set up Brownie in brownfield app"
+- "first Brownie store setup"
+- "how to start Brownie on iOS or Android"
+
+## Scope
+
+In scope:
+- Prerequisites and initial installation.
+- First store definition and app entry import.
+- Platform handoff sequence for iOS and Android setup.
+- First-pass verification that state sync works.
+
+Out of scope:
+- Deep schema modeling details and codegen internals. For that, read [`store-definition-and-codegen.md`](store-definition-and-codegen.md) in this folder.
+- Advanced JS runtime patterns and low-level TypeScript APIs. For that, read [`typescript-usage.md`](typescript-usage.md) in this folder.
+- Platform-specific deep dives. For Android details, read [`android-usage.md`](android-usage.md). For iOS details, read [`swift-and-xcframework.md`](swift-and-xcframework.md) in this folder.
+
+## Procedure
+
+1. Confirm prerequisites
+   - React Native brownfield setup is already complete.
+   - `@callstack/react-native-brownfield` is installed.
+   - Native host app(s) exist for iOS and/or Android.
+
+2. Install Brownie in the React Native app
+   - Run `npm install @callstack/brownie`.
+
+3. Define the first store
+   - Create a file ending in `.brownie.ts`.
+   - Declare an interface extending `BrownieStore`.
+   - Add module augmentation for `BrownieStores`.
+
+4. Ensure augmentation is loaded
+   - Import the `.brownie.ts` file from the app entry (`App.tsx` or `index.js`).
+
+5. Add first TypeScript usage
+   - Use `useStore('StoreName', selector)` in a component.
+   - Perform one update via object or callback updater.
+
+6. Platform handoff
+   - iOS path:
+     1. Run `npx brownfield package:ios --scheme YourScheme --configuration Release`.
+     2. Confirm package output contains your module XCFramework plus `Brownie.xcframework`, `ReactBrownfield.xcframework`, and Hermes (`hermesvm.xcframework` or `hermes.xcframework`).
+     3. Embed generated frameworks as `Embed & Sign`.
+     4. Register the store in app startup.
+   - Android path:
+     1. Configure `brownie` settings in `package.json` (`kotlin`, `kotlinPackageName`).
+     2. Ensure Gson dependency exists in brownfield module or app.
+     3. Run `npx brownfield package:android --module-name :YourModuleName --variant release`.
+     4. Run `npx brownfield publish:android --module-name :YourModuleName`.
+     5. Register store during startup with `registerStoreIfNeeded`.
+   - Note: both `package:ios` and `package:android` run Brownie codegen as part of packaging.
+
+7. Verify sync
+   - Update state from React Native and confirm native UI observes updates.
+   - Update from native and confirm React Native reflects changes.
+   - If one side is stale after schema edits, rerun packaging/codegen and rebuild host apps.
+   - Android runtime gate:
+     - If launch fails with `ClassNotFoundException: com.google.gson.Gson`, add `implementation("com.google.code.gson:gson:<version>")` to brownfield module or host app and rebuild.
+
+## Quick reference
+
+- Install: `npm install @callstack/brownie`
+- Store file pattern: `*.brownie.ts`
+- Codegen/build entry points:
+  - `npx brownfield codegen`
+  - `npx brownfield package:ios --scheme YourScheme --configuration Release`
+  - `npx brownfield package:android --module-name :YourModuleName --variant release`
+  - `npx brownfield publish:android --module-name :YourModuleName`
+- iOS packaging outputs (CLI docs):
+  - `ios/.brownfield/package/build/`
+- Error cues this guide handles first:
+  - Store file exists but typed APIs are missing
+  - Native setup done but store not registered at startup
+  - First state update does not appear on one side

skills/brownie/references/store-definition-and-codegen.md

@@ -0,0 +1,92 @@
+# Brownie Store Definition and Codegen
+
+## Discoverability triggers
+
+- "where to put .brownie.ts files"
+- "BrownieStores module augmentation"
+- "brownfield codegen for brownie"
+- "generated Swift or Kotlin types are stale"
+
+## Scope
+
+In scope:
+- Authoring `*.brownie.ts` stores and augmentation rules.
+- Supported schema patterns and type mapping expectations.
+- Running `brownfield codegen` and knowing when to rerun.
+- Verifying generated artifacts and resolving common drift issues.
+
+Out of scope:
+- Initial installation and first integration sequence. For that, read [`getting-started.md`](getting-started.md) in this folder.
+- React component usage ergonomics (`useStore`, selectors, updates). For that, read [`typescript-usage.md`](typescript-usage.md) in this folder.
+- Platform registration and runtime integration details. For Android, read [`android-usage.md`](android-usage.md). For iOS, read [`swift-and-xcframework.md`](swift-and-xcframework.md) in this folder.
+
+## Procedure
+
+1. Validate store file shape
+   - File name ends with `.brownie.ts`.
+   - Store interface extends `BrownieStore`.
+   - `declare module '@callstack/brownie'` augments `BrownieStores`.
+   - Store key in `BrownieStores` matches intended public store name.
+
+2. Confirm schema expectations before generation
+   - Scalars (`number`, `string`, `boolean`) are supported.
+   - Nested object types are supported and generate native structs/classes.
+  - Union string literals generate native enum types across platforms; for example, `theme: 'light' | 'dark'` emits Kotlin and Swift enum types (such as `Theme`), with generated enum/type names following codegen naming and casing conventions rather than remaining raw string fields.
+
+3. Ensure augmentation is loaded by TypeScript
+   - Import each `.brownie.ts` file from app entry point.
+
+4. Run codegen
+   - Primary command: `npx brownfield codegen`.
+   - Optional platform scope (if needed by CLI config): `npx brownfield codegen -p swift`.
+   - Discovery rule: the CLI recursively scans the project for `*.brownie.ts` files (excluding `node_modules`).
+
+5. Verify generated outputs
+   - Swift output root: `node_modules/@callstack/brownie/ios/Generated/`.
+   - Confirm store type files exist and include store name bindings/protocol conformance.
+   - Android generation is driven by brownfield Android packaging flow; confirm generated Kotlin output path aligns with package configuration.
+
+6. Apply rerun and rebuild rule
+   - Any schema surface change requires rerunning codegen.
+   - If app behavior still reflects old schema, rebuild native artifacts after codegen.
+
+7. Triage common failures
+   - Missing generated files: confirm file extension and augmentation block.
+   - Types not updated: verify app entry imports and rerun codegen from project root.
+   - Runtime mismatch after schema edits: rerun codegen and rebuild platform artifacts.
+
+## Compact schema example
+
+```ts
+import type {BrownieStore} from '@callstack/brownie';
+
+interface AppStore extends BrownieStore {
+  counter: number;
+  user: {name: string};
+}
+
+declare module '@callstack/brownie' {
+  interface BrownieStores {
+    AppStore: AppStore;
+  }
+}
+```
+
+## Quick reference
+
+- File contract:
+  - `*.brownie.ts`
+  - `interface X extends BrownieStore`
+  - `declare module '@callstack/brownie' { interface BrownieStores { ... } }`
+- Type mapping (most common):
+  - `number` -> `Double` (Swift)
+  - `string` -> `String`
+  - `boolean` -> `Bool`
+  - nested object -> generated native type
+- Commands:
+  - `npx brownfield codegen`
+  - `npx brownfield codegen -p swift`
+- Regeneration triggers:
+  - Added/removed store
+  - Renamed key or changed field types
+  - Nested model changes