From c0c6e646faf039133d2391cf6b9d27d981fbd40b Mon Sep 17 00:00:00 2001
From: Hur Ali <hurali97@gmail.com>
Date: Thu, 16 Apr 2026 15:01:05 +0500
Subject: [PATCH 1/4] feat: add brownfield navigation skills

---
 .agents/skills/brownfield-navigation/SKILL.md | 46 ++++++++++++
 .../references/javascript-usage.md            | 69 +++++++++++++++++
 .../references/native-integration.md          | 73 ++++++++++++++++++
 .../references/setup-codegen.md               | 74 +++++++++++++++++++
 4 files changed, 262 insertions(+)
 create mode 100644 .agents/skills/brownfield-navigation/SKILL.md
 create mode 100644 .agents/skills/brownfield-navigation/references/javascript-usage.md
 create mode 100644 .agents/skills/brownfield-navigation/references/native-integration.md
 create mode 100644 .agents/skills/brownfield-navigation/references/setup-codegen.md

diff --git a/.agents/skills/brownfield-navigation/SKILL.md b/.agents/skills/brownfield-navigation/SKILL.md
new file mode 100644
index 00000000..bc6e0262
--- /dev/null
+++ b/.agents/skills/brownfield-navigation/SKILL.md
@@ -0,0 +1,46 @@
+---
+name: brownfield-navigation
+description: Allows presenting existing native screens from React Native. Defines the schema in Typescript, run the codegen to generate the bindings, add the function invocation on the JS side. Generate the xcframework/AAR, then add the native bindings like delegate to the native host App.
+license: MIT
+metadata:
+  author: Callstack
+  tags: react-native, expo, brownfield, navigation
+---
+
+# Overview
+
+Brownfield Navigation flows from a TypeScript contract (`brownfield.navigation.ts`) through `npx brownfield navigation:codegen`, which generates JS bindings, native stubs, and delegate protocols. Host apps implement `BrownfieldNavigationDelegate`, register it with `BrownfieldNavigationManager` at startup, then React Native code calls the generated `@callstack/brownfield-navigation` module.
+
+# When to Apply
+
+Reference these skills when:
+- App uses brownfield setup
+- Presenting existing native screen from React Native
+- Configuring schema for brownfield navigation
+- Implementing the brownfield navigation delegate
+
+# Quick Reference
+
+- Generate the files using codegen script:
+```bash
+npx brownfield navigation:codegen
+```
+- Same files are also codegen when:
+```bash
+# iOS
+npx brownfield package:ios
+
+# android
+npx brownfield package:android
+npx brownfield publish:android
+```
+
+## Routing (concern → file)
+
+| Concern | Read |
+|--------|------|
+| JS call sites, `BrownfieldNavigation.*` usage, `undefined is not a function`, params vs generated API | [`javascript-usage.md`](references/javascript-usage.md) |
+| `BrownfieldNavigationDelegate`, `setDelegate` / `shared.setDelegate`, startup crashes, no-op / wrong native route | [`native-integration.md`](references/native-integration.md) |
+| Contract placement, `BrownfieldNavigationSpec` / `Spec`, `navigation:codegen`, generated artifacts, stale or missing outputs | [`setup-codegen.md`](references/setup-codegen.md) |
+
+
diff --git a/.agents/skills/brownfield-navigation/references/javascript-usage.md b/.agents/skills/brownfield-navigation/references/javascript-usage.md
new file mode 100644
index 00000000..73f1f720
--- /dev/null
+++ b/.agents/skills/brownfield-navigation/references/javascript-usage.md
@@ -0,0 +1,69 @@
+# Brownfield Navigation JavaScript Usage
+
+**Product docs:** Authoritative documentation paths are listed in [`SKILL.md`](SKILL.md) in this folder.
+
+## Discoverability triggers
+
+- "how to call BrownfieldNavigation from JS"
+- "`undefined is not a function` on a Brownfield method"
+- "JS method missing after updating `brownfield.navigation.ts`"
+- "Brownfield JS method exists but opens wrong destination"
+
+## Scope
+
+In scope:
+- Calling `BrownfieldNavigation.<method>()` from React Native code.
+- JS call-site patterns for buttons/screens and parameter passing.
+- Runtime troubleshooting for JS-facing failures (`undefined is not a function`, missing methods, API drift signals).
+- Reminding users when contract changes require codegen and native rebuild.
+
+Out of scope:
+- Authoring `brownfield.navigation.ts` and codegen mechanics. For that, read [`setup-codegen.md`](setup-codegen.md) in this folder.
+- Android/iOS delegate implementation and startup registration details. For that, read [`native-integration.md`](native-integration.md) in this folder.
+
+## Procedure
+
+1. Confirm readiness before discussing JS calls
+   - Native delegate registration must already be in place before JS uses the module.
+   - If registration/startup order is uncertain, read [`native-integration.md`](native-integration.md) in this folder.
+
+2. Provide the default JS invocation pattern
+   - Import `BrownfieldNavigation` from `@callstack/brownfield-navigation`.
+   - Call generated methods directly from handlers (for example, button `onPress`).
+   - Keep method names and argument shape aligned with the generated API.
+
+3. Recommend call-site best practices
+   - Pass stable explicit params (`userId`, IDs, flags), not transient UI-derived data.
+   - Keep each JS method call mapped to a clearly named native destination.
+   - Use simple direct calls first; avoid wrapping in unnecessary abstractions while debugging.
+
+4. Apply troubleshooting flow for runtime failures
+   - `undefined is not a function`: method changed in spec but codegen/rebuild not reapplied.
+   - Native crash on call: likely delegate registration/startup ordering issue; hand off implementation details to [`native-integration.md`](native-integration.md) in this folder.
+   - Method exists but wrong route/no-op: generated method present, but native delegate wiring likely incorrect; route delegate fixes to [`native-integration.md`](native-integration.md) in this folder.
+
+5. Enforce regeneration rule when JS/native API drift appears
+   - If method names, params, or return types changed in `brownfield.navigation.ts`, rerun:
+     `npx brownfield navigation:codegen`
+   - Then rebuild native apps before retesting JS calls.
+
+6. Route non-JS root causes quickly
+   - Spec placement/signature/codegen output questions → [`setup-codegen.md`](setup-codegen.md) in this folder.
+   - Delegate implementation/registration/lifecycle questions → [`native-integration.md`](native-integration.md) in this folder.
+
+## Quick reference
+
+- Import: `import BrownfieldNavigation from '@callstack/brownfield-navigation'`
+- Typical calls:
+  - `BrownfieldNavigation.navigateToSettings()`
+  - `BrownfieldNavigation.navigateToReferrals('user-123')`
+- Regenerate on contract change: `npx brownfield navigation:codegen`
+- Retest order:
+  1. Confirm contract shape
+  2. Regenerate
+  3. Rebuild native apps
+  4. Retest JS call sites
+- Error cues this skill should handle first:
+  - `undefined is not a function` on a Brownfield method
+  - JS method missing after updating `brownfield.navigation.ts`
+  - JS call parameters appear out of sync with generated API
diff --git a/.agents/skills/brownfield-navigation/references/native-integration.md b/.agents/skills/brownfield-navigation/references/native-integration.md
new file mode 100644
index 00000000..1d731b30
--- /dev/null
+++ b/.agents/skills/brownfield-navigation/references/native-integration.md
@@ -0,0 +1,73 @@
+# Brownfield Navigation Native Integration
+
+**Product docs:** Authoritative documentation paths are listed in [`SKILL.md`](SKILL.md) in this folder.
+
+## Discoverability triggers
+
+- "implement `BrownfieldNavigationDelegate`"
+- "where to call `BrownfieldNavigationManager.setDelegate(...)`"
+- "where to call `BrownfieldNavigationManager.shared.setDelegate(...)`"
+- "navigation call crashes at app startup or upon invocation"
+
+## Scope
+
+In scope:
+- Implementing generated `BrownfieldNavigationDelegate` methods in Android and iOS host code.
+- Registering the delegate with `BrownfieldNavigationManager` during app startup.
+- Enforcing startup/lifecycle ordering (delegate registered before JS calls).
+- Troubleshooting native wiring issues (crash/no-op/wrong route).
+
+Out of scope:
+- Authoring `brownfield.navigation.ts` and running codegen. For that, read [`setup-codegen.md`](setup-codegen.md) in this folder.
+- JavaScript call-site usage patterns in RN screens. For that, read [`javascript-usage.md`](javascript-usage.md) in this folder.
+
+## Procedure
+
+1. Confirm prerequisite
+   - `BrownfieldNavigation.xcframework` is linked in the iOS host app.
+     - If applicable, note this comes from `npx brownfield package:ios` under `ios/.brownfield`.
+   - `Gson` dependency is added to the Android host app.
+
+2. Implement Android delegate
+   - Implement generated `BrownfieldNavigationDelegate` in the host `Activity` (or class with navigation context).
+   - Wire each generated method to the native destination and map params exactly.
+   - Typical implementation starts Android `Activity` instances with `Intent` extras.
+
+3. Register Android delegate during startup
+   - Call `BrownfieldNavigationManager.setDelegate(...)` in startup flow (for example `onCreate`).
+   - Registration must happen before any React Native screen can call `BrownfieldNavigation.*`.
+
+4. Implement iOS delegate
+   - Create a class conforming to `BrownfieldNavigationDelegate`.
+   - Wire each generated method to the intended native presentation flow (UIKit/SwiftUI).
+   - Ensure screen presentation runs on the main/UI thread.
+
+5. Register iOS delegate during startup
+   - Call `BrownfieldNavigationManager.shared.setDelegate(navigationDelegate: ...)` at app startup (for example in app `init`).
+   - Registration must happen before RN-rendered routes can invoke module methods.
+
+6. Enforce lifecycle requirements
+   - Delegate must be present before JS usage; missing delegate is a startup bug.
+   - Re-register if the host object owning the delegate is recreated.
+   - Keep navigation/presentation work on main thread.
+
+7. Triage runtime integration failures
+   - Method added/changed in TS but missing natively: rerun `npx brownfield navigation:codegen` and rebuild.
+   - Crash on launch or first method call: verify delegate registration order vs RN route rendering.
+   - Method exists but wrong destination/no-op: verify delegate implementation wiring and parameter mapping.
+
+## Quick reference
+
+- Android delegate type: `BrownfieldNavigationDelegate`
+- Android registration: `BrownfieldNavigationManager.setDelegate(...)`
+- iOS delegate type: `BrownfieldNavigationDelegate`
+- iOS registration: `BrownfieldNavigationManager.shared.setDelegate(navigationDelegate: ...)`
+- Integration order:
+  1. Generate/update contract outputs
+  2. Implement delegate methods natively
+  3. Register delegate at startup
+  4. Render RN routes that call `BrownfieldNavigation.*`
+- Error cues this skill should address:
+  - Crashes when JS calls navigation methods early
+  - Missing delegate registration at startup
+  - Wrong native screen opened from a JS call
diff --git a/.agents/skills/brownfield-navigation/references/setup-codegen.md b/.agents/skills/brownfield-navigation/references/setup-codegen.md
new file mode 100644
index 00000000..bbe147c6
--- /dev/null
+++ b/.agents/skills/brownfield-navigation/references/setup-codegen.md
@@ -0,0 +1,74 @@
+# Brownfield Navigation Setup and Codegen
+
+**Product docs:** Authoritative documentation paths are listed in [`SKILL.md`](SKILL.md) in this folder.
+
+## Discoverability triggers
+
+- "where to put `brownfield.navigation.ts`"
+- "run brownfield navigation codegen"
+- "generated files missing after codegen"
+- "spec changes not reflected in generated APIs"
+
+## Scope
+
+In scope:
+- Authoring and updating `brownfield.navigation.ts` in the React Native app root.
+- Enforcing supported signature rules (`BrownfieldNavigationSpec`/`Spec`, typed params, optional params, `void`-first guidance).
+- Running `npx brownfield navigation:codegen`.
+- Explaining generated artifacts and when regeneration + native rebuild are required.
+- First-pass setup/codegen triage (missing files, stale API after spec changes).
+
+Out of scope:
+- Android/iOS delegate implementation and registration details. For that, read [`native-integration.md`](native-integration.md) in this folder.
+- JavaScript screen usage patterns and runtime call ergonomics. For that, read [`javascript-usage.md`](javascript-usage.md) in this folder.
+
+## Procedure
+
+1. Confirm prerequisites
+   - `@callstack/brownfield-navigation` is installed. Otherwise, install the latest version
+   - Babel deps used by codegen are available (`@babel/core`, `@react-native/babel-preset`).
+
+2. Verify contract file placement and shape
+   - File name is exactly `brownfield.navigation.ts`.
+   - File is in the React Native app root.
+   - Interface is `BrownfieldNavigationSpec` (or `Spec`).
+
+3. Validate method signatures before codegen
+   - Method names are valid TypeScript identifiers.
+   - Typed params and optional params are allowed.
+   - Prefer synchronous `void` navigation methods.
+   - Warn that Promise-based methods are not currently supported by generated native implementations on iOS/Android; they may compile but reject with `not_implemented`.
+
+4. Run codegen from app root
+   - Command: `npx brownfield navigation:codegen`
+
+5. Confirm expected generated outputs
+   - `src/NativeBrownfieldNavigation.ts`
+   - `src/index.ts`
+   - `ios/BrownfieldNavigationDelegate.swift`
+   - `ios/NativeBrownfieldNavigation.mm`
+   - Android delegate/module files in `android/src/main/java/com/callstack/nativebrownfieldnavigation/`
+
+6. Enforce rerun/rebuild rule
+   - Any add/remove/rename/update of methods in `brownfield.navigation.ts` requires:
+     1) rerunning codegen, then
+     2) recompiling native apps.
+
+7. Handoff when issue is outside setup/codegen
+   - Delegate lifecycle/startup order: [`native-integration.md`](native-integration.md) in this folder.
+   - JS invocation/runtime call-site guidance: [`javascript-usage.md`](javascript-usage.md) in this folder.
+
+## Quick reference
+
+- Primary command: `npx brownfield navigation:codegen`
+- Contract file: `brownfield.navigation.ts` at React Native app root
+- Parser-supported interface names: `BrownfieldNavigationSpec` or `Spec`
+- Safe default return type: `void`
+- Important order:
+  1. Define/update TS contract
+  2. Run codegen
+  3. Rebuild native apps
+- Error cues this skill should address:
+  - Generated files missing or stale after spec edits
+  - JS/native surfaces not reflecting renamed/added methods
+  - Promise-based navigation method behaving as `not_implemented`

From dedd053e12f5e250c45da691559538bac78b9541 Mon Sep 17 00:00:00 2001
From: Hur Ali <hurali97@gmail.com>
Date: Thu, 16 Apr 2026 15:50:20 +0500
Subject: [PATCH 2/4] feat: update brownfield navigation skills

---
 .agents/skills/brownfield-navigation/SKILL.md |  2 +-
 .../references/javascript-usage.md            | 30 ++++++-
 .../references/native-integration.md          | 82 ++++++++++++++++++-
 .../references/setup-codegen.md               | 48 +++++++----
 4 files changed, 141 insertions(+), 21 deletions(-)

diff --git a/.agents/skills/brownfield-navigation/SKILL.md b/.agents/skills/brownfield-navigation/SKILL.md
index bc6e0262..20c92cbc 100644
--- a/.agents/skills/brownfield-navigation/SKILL.md
+++ b/.agents/skills/brownfield-navigation/SKILL.md
@@ -25,7 +25,7 @@ Reference these skills when:
 ```bash
 npx brownfield navigation:codegen
 ```
-- Same files are also codegen when:
+- Brownfield packaging commands also run the same navigation codegen as part of packaging workflows:
 ```bash
 # iOS
 npx brownfield package:ios
diff --git a/.agents/skills/brownfield-navigation/references/javascript-usage.md b/.agents/skills/brownfield-navigation/references/javascript-usage.md
index 73f1f720..99d06b70 100644
--- a/.agents/skills/brownfield-navigation/references/javascript-usage.md
+++ b/.agents/skills/brownfield-navigation/references/javascript-usage.md
@@ -1,7 +1,5 @@
 # Brownfield Navigation JavaScript Usage
 
-**Product docs:** Authoritative documentation paths are listed in [`SKILL.md`](SKILL.md) in this folder.
-
 ## Discoverability triggers
 
 - "how to call BrownfieldNavigation from JS"
@@ -51,6 +49,34 @@ Out of scope:
    - Spec placement/signature/codegen output questions → [`setup-codegen.md`](setup-codegen.md) in this folder.
    - Delegate implementation/registration/lifecycle questions → [`native-integration.md`](native-integration.md) in this folder.
 
+## Minimal TSX example
+
+Assume the generated contract includes a method like `openNativeProfile(userId: string): void`. The exact method names and params come from the generated `@callstack/brownfield-navigation` module after running codegen.
+
+```tsx
+import React from 'react';
+import {Button, SafeAreaView} from 'react-native';
+import BrownfieldNavigation from '@callstack/brownfield-navigation';
+
+export function ProfileLauncherScreen(): React.JSX.Element {
+  return (
+    <SafeAreaView>
+      <Button
+        title="Open native profile"
+        onPress={() => {
+          BrownfieldNavigation.openNativeProfile('user-123');
+        }}
+      />
+    </SafeAreaView>
+  );
+}
+```
+
+Portable takeaways:
+- Import the generated module from `@callstack/brownfield-navigation`.
+- Call the generated method directly from a user action such as `onPress`.
+- If this method is missing or throws `undefined is not a function`, treat it as a codegen/rebuild drift signal first.
+
 ## Quick reference
 
 - Import: `import BrownfieldNavigation from '@callstack/brownfield-navigation'`
diff --git a/.agents/skills/brownfield-navigation/references/native-integration.md b/.agents/skills/brownfield-navigation/references/native-integration.md
index 1d731b30..05cb648b 100644
--- a/.agents/skills/brownfield-navigation/references/native-integration.md
+++ b/.agents/skills/brownfield-navigation/references/native-integration.md
@@ -1,7 +1,5 @@
 # Brownfield Navigation Native Integration
 
-**Product docs:** Authoritative documentation paths are listed in [`SKILL.md`](SKILL.md) in this folder.
-
 ## Discoverability triggers
 
 - "implement `BrownfieldNavigationDelegate`"
@@ -25,7 +23,7 @@ Out of scope:
 
 1. Confirm prerequisite
    - `BrownfieldNavigation.xcframework` is linked in the iOS host app.
-     - If applicable, note this comes from `npx brownfield package:ios` under `ios/.brownfield`.
+     - If applicable, use the artifact produced by `npx brownfield package:ios` in the current project. The exact output path can vary by package manager and workspace layout.
    - `Gson` dependency is added to the Android host app.
 
 2. Implement Android delegate
@@ -56,6 +54,84 @@ Out of scope:
    - Crash on launch or first method call: verify delegate registration order vs RN route rendering.
    - Method exists but wrong destination/no-op: verify delegate implementation wiring and parameter mapping.
 
+## Minimal native examples
+
+Assume the generated contract includes a method like `openNativeProfile(userId: string): void`. The generated delegate method name and parameter types come from the current project's `brownfield.navigation.ts`.
+
+### Kotlin example
+
+Use this pattern when the host screen or activity owns Android navigation context:
+
+```kotlin
+import android.content.Intent
+import android.os.Bundle
+import androidx.appcompat.app.AppCompatActivity
+import com.callstack.brownfieldnavigation.BrownfieldNavigationDelegate
+import com.callstack.brownfieldnavigation.BrownfieldNavigationManager
+
+class MainActivity : AppCompatActivity(), BrownfieldNavigationDelegate {
+  override fun onCreate(savedInstanceState: Bundle?) {
+    super.onCreate(savedInstanceState)
+    BrownfieldNavigationManager.setDelegate(this)
+  }
+
+  override fun openNativeProfile(userId: String) {
+    val intent = Intent(this, ProfileActivity::class.java).apply {
+      putExtra("userId", userId)
+    }
+    startActivity(intent)
+  }
+}
+```
+
+Portable takeaways:
+- Implement the generated `BrownfieldNavigationDelegate`.
+- Register the delegate before any React Native code can call `BrownfieldNavigation.*`.
+- Map each generated method to an explicit native destination and pass params through unchanged.
+
+### Swift example
+
+Use this pattern when an app-level object can own navigation setup and present UIKit or SwiftUI flows:
+
+```swift
+import BrownfieldNavigation
+import UIKit
+
+final class AppNavigationDelegate: BrownfieldNavigationDelegate {
+  func openNativeProfile(userId: String) {
+    DispatchQueue.main.async {
+      guard let rootViewController = UIApplication.shared.connectedScenes
+        .compactMap({ $0 as? UIWindowScene })
+        .flatMap(\.windows)
+        .first(where: \.isKeyWindow)?
+        .rootViewController else {
+        return
+      }
+
+      let viewController = ProfileViewController(userId: userId)
+      rootViewController.present(viewController, animated: true)
+    }
+  }
+}
+
+final class AppDelegate: UIResponder, UIApplicationDelegate {
+  private let navigationDelegate = AppNavigationDelegate()
+
+  func application(
+    _ application: UIApplication,
+    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? = nil
+  ) -> Bool {
+    BrownfieldNavigationManager.shared.setDelegate(navigationDelegate: navigationDelegate)
+    return true
+  }
+}
+```
+
+Portable takeaways:
+- Keep a strong reference to the delegate for as long as React Native might call it.
+- Register the delegate during startup, before RN screens that use Brownfield navigation are shown.
+- Perform presentation on the main thread and keep the implementation focused on routing plus param mapping.
+
 ## Quick reference
 
 - Android delegate type: `BrownfieldNavigationDelegate`
diff --git a/.agents/skills/brownfield-navigation/references/setup-codegen.md b/.agents/skills/brownfield-navigation/references/setup-codegen.md
index bbe147c6..70d6d1c6 100644
--- a/.agents/skills/brownfield-navigation/references/setup-codegen.md
+++ b/.agents/skills/brownfield-navigation/references/setup-codegen.md
@@ -1,7 +1,5 @@
 # Brownfield Navigation Setup and Codegen
 
-**Product docs:** Authoritative documentation paths are listed in [`SKILL.md`](SKILL.md) in this folder.
-
 ## Discoverability triggers
 
 - "where to put `brownfield.navigation.ts`"
@@ -39,20 +37,36 @@ Out of scope:
    - Prefer synchronous `void` navigation methods.
    - Warn that Promise-based methods are not currently supported by generated native implementations on iOS/Android; they may compile but reject with `not_implemented`.
 
-4. Run codegen from app root
-   - Command: `npx brownfield navigation:codegen`
-
-5. Confirm expected generated outputs
-   - `src/NativeBrownfieldNavigation.ts`
-   - `src/index.ts`
-   - `ios/BrownfieldNavigationDelegate.swift`
-   - `ios/NativeBrownfieldNavigation.mm`
-   - Android delegate/module files in `android/src/main/java/com/callstack/nativebrownfieldnavigation/`
+4. Choose the right codegen invocation
+   - Default form: `npx brownfield navigation:codegen`
+   - Explicit path form: `npx brownfield navigation:codegen <specPath>`
+   - Use the default form when your current working directory is the React Native app root and the contract file is the default `./brownfield.navigation.ts`.
+   - Use the explicit-path form when you are running from another directory, when the app lives inside a workspace/monorepo, or when you want to remove ambiguity about which spec file should be parsed.
+   - Relative `specPath` values are resolved from the directory where you run the command; absolute paths also work.
+
+5. Understand the artifact root before verifying outputs
+   - Codegen writes into the installed `@callstack/brownfield-navigation` package root, not into the app directory that contains `brownfield.navigation.ts`.
+   - The exact absolute location depends on the consumer's package manager and workspace layout. It may live under a local `node_modules` tree, a hoisted workspace dependency, or another package-store-managed install location.
+   - Treat the package root as the stable anchor, then verify these generated relative paths beneath it:
+     - `src/NativeBrownfieldNavigation.ts`
+     - `src/index.ts`
+     - `lib/commonjs/index.js`
+     - `lib/module/index.js`
+     - `lib/typescript/commonjs/src/index.d.ts`
+     - `lib/typescript/module/src/index.d.ts`
+     - `ios/BrownfieldNavigationDelegate.swift`
+     - `ios/BrownfieldNavigationModels.swift` when complex model types are generated
+     - `ios/NativeBrownfieldNavigation.mm`
+     - Android files under `android/src/main/java/<generated-package>/`, including `BrownfieldNavigationDelegate.kt`, `NativeBrownfieldNavigationModule.kt`, and `BrownfieldNavigationModels.kt` when complex model types are generated
 
 6. Enforce rerun/rebuild rule
-   - Any add/remove/rename/update of methods in `brownfield.navigation.ts` requires:
-     1) rerunning codegen, then
-     2) recompiling native apps.
+   - Any change that affects the contract surface in `brownfield.navigation.ts` requires rerunning codegen, then rebuilding native apps.
+   - This includes adding, removing, renaming, or retyping methods; changing params or optionality; and introducing/removing model types used by params.
+   - If JavaScript can no longer see a generated method, or native code still behaves like the old contract, assume regeneration or rebuild was skipped.
+   - Safe order:
+     1) update the contract
+     2) rerun codegen
+     3) rebuild iOS and/or Android before retesting
 
 7. Handoff when issue is outside setup/codegen
    - Delegate lifecycle/startup order: [`native-integration.md`](native-integration.md) in this folder.
@@ -60,8 +74,12 @@ Out of scope:
 
 ## Quick reference
 
-- Primary command: `npx brownfield navigation:codegen`
+- Primary commands:
+  - `npx brownfield navigation:codegen`
+  - `npx brownfield navigation:codegen <specPath>`
 - Contract file: `brownfield.navigation.ts` at React Native app root
+- Default command behavior: reads `./brownfield.navigation.ts` from the current working directory
+- Output location: generated files are written under the resolved `@callstack/brownfield-navigation` package root
 - Parser-supported interface names: `BrownfieldNavigationSpec` or `Spec`
 - Safe default return type: `void`
 - Important order:

From 872d1b9b00728b1bb32e139a48d8632ec1be86b5 Mon Sep 17 00:00:00 2001
From: Hur Ali <hurali97@gmail.com>
Date: Thu, 16 Apr 2026 16:16:23 +0500
Subject: [PATCH 3/4] fix: review comments

---
 .agents/skills/brownfield-navigation/SKILL.md        | 12 ++++++------
 .../references/native-integration.md                 |  6 +++---
 .../references/setup-codegen.md                      |  2 +-
 3 files changed, 10 insertions(+), 10 deletions(-)

diff --git a/.agents/skills/brownfield-navigation/SKILL.md b/.agents/skills/brownfield-navigation/SKILL.md
index 20c92cbc..28407bc0 100644
--- a/.agents/skills/brownfield-navigation/SKILL.md
+++ b/.agents/skills/brownfield-navigation/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: brownfield-navigation
-description: Allows presenting existing native screens from React Native. Defines the schema in Typescript, run the codegen to generate the bindings, add the function invocation on the JS side. Generate the xcframework/AAR, then add the native bindings like delegate to the native host App.
+description: Allows presenting existing native screens from React Native. Define the schema in TypeScript, run codegen to generate the bindings, invoke the function on the JS side, generate the XCFramework/AAR, and integrate native bindings such as the delegate into the host app.
 license: MIT
 metadata:
   author: Callstack
@@ -37,10 +37,10 @@ npx brownfield publish:android
 
 ## Routing (concern → file)
 
-| Concern | Read |
-|--------|------|
-| JS call sites, `BrownfieldNavigation.*` usage, `undefined is not a function`, params vs generated API | [`javascript-usage.md`](references/javascript-usage.md) |
-| `BrownfieldNavigationDelegate`, `setDelegate` / `shared.setDelegate`, startup crashes, no-op / wrong native route | [`native-integration.md`](references/native-integration.md) |
-| Contract placement, `BrownfieldNavigationSpec` / `Spec`, `navigation:codegen`, generated artifacts, stale or missing outputs | [`setup-codegen.md`](references/setup-codegen.md) |
+Concern | Read
+--------|------
+JS call sites, `BrownfieldNavigation.*` usage, `undefined is not a function`, params vs generated API | [`javascript-usage.md`](references/javascript-usage.md)
+`BrownfieldNavigationDelegate`, `setDelegate` / `shared.setDelegate`, startup crashes, no-op / wrong native route | [`native-integration.md`](references/native-integration.md)
+Contract placement, `BrownfieldNavigationSpec` / `Spec`, `navigation:codegen`, generated artifacts, stale or missing outputs | [`setup-codegen.md`](references/setup-codegen.md)
 
 
diff --git a/.agents/skills/brownfield-navigation/references/native-integration.md b/.agents/skills/brownfield-navigation/references/native-integration.md
index 05cb648b..c1e0f76d 100644
--- a/.agents/skills/brownfield-navigation/references/native-integration.md
+++ b/.agents/skills/brownfield-navigation/references/native-integration.md
@@ -21,7 +21,7 @@ Out of scope:
 
 ## Procedure
 
-1. Confirm prerequisite
+1. Confirm prerequisites
    - `BrownfieldNavigation.xcframework` is linked in the iOS host app.
      - If applicable, use the artifact produced by `npx brownfield package:ios` in the current project. The exact output path can vary by package manager and workspace layout.
    - `Gson` dependency is added to the Android host app.
@@ -66,8 +66,8 @@ Use this pattern when the host screen or activity owns Android navigation contex
 import android.content.Intent
 import android.os.Bundle
 import androidx.appcompat.app.AppCompatActivity
-import com.callstack.brownfieldnavigation.BrownfieldNavigationDelegate
-import com.callstack.brownfieldnavigation.BrownfieldNavigationManager
+import com.callstack.nativebrownfieldnavigation.BrownfieldNavigationDelegate
+import com.callstack.nativebrownfieldnavigation.BrownfieldNavigationManager
 
 class MainActivity : AppCompatActivity(), BrownfieldNavigationDelegate {
   override fun onCreate(savedInstanceState: Bundle?) {
diff --git a/.agents/skills/brownfield-navigation/references/setup-codegen.md b/.agents/skills/brownfield-navigation/references/setup-codegen.md
index 70d6d1c6..7510b997 100644
--- a/.agents/skills/brownfield-navigation/references/setup-codegen.md
+++ b/.agents/skills/brownfield-navigation/references/setup-codegen.md
@@ -24,7 +24,7 @@ Out of scope:
 
 1. Confirm prerequisites
    - `@callstack/brownfield-navigation` is installed. Otherwise, install the latest version
-   - Babel deps used by codegen are available (`@babel/core`, `@react-native/babel-preset`).
+   - Babel deps used by codegen are available (`@babel/core`, `@react-native/babel-preset`). Otherwise, install the compatible version OR ask the user.
 
 2. Verify contract file placement and shape
    - File name is exactly `brownfield.navigation.ts`.

From 4474dfc9e8ad41ce8c416b16424dab145f0ea2a4 Mon Sep 17 00:00:00 2001
From: Hur Ali <hurali97@gmail.com>
Date: Thu, 16 Apr 2026 16:17:54 +0500
Subject: [PATCH 4/4] refactor: rearrange skills

---
 {.agents/skills => skills}/brownfield-navigation/SKILL.md         | 0
 .../brownfield-navigation/references/javascript-usage.md          | 0
 .../brownfield-navigation/references/native-integration.md        | 0
 .../brownfield-navigation/references/setup-codegen.md             | 0
 4 files changed, 0 insertions(+), 0 deletions(-)
 rename {.agents/skills => skills}/brownfield-navigation/SKILL.md (100%)
 rename {.agents/skills => skills}/brownfield-navigation/references/javascript-usage.md (100%)
 rename {.agents/skills => skills}/brownfield-navigation/references/native-integration.md (100%)
 rename {.agents/skills => skills}/brownfield-navigation/references/setup-codegen.md (100%)

diff --git a/.agents/skills/brownfield-navigation/SKILL.md b/skills/brownfield-navigation/SKILL.md
similarity index 100%
rename from .agents/skills/brownfield-navigation/SKILL.md
rename to skills/brownfield-navigation/SKILL.md
diff --git a/.agents/skills/brownfield-navigation/references/javascript-usage.md b/skills/brownfield-navigation/references/javascript-usage.md
similarity index 100%
rename from .agents/skills/brownfield-navigation/references/javascript-usage.md
rename to skills/brownfield-navigation/references/javascript-usage.md
diff --git a/.agents/skills/brownfield-navigation/references/native-integration.md b/skills/brownfield-navigation/references/native-integration.md
similarity index 100%
rename from .agents/skills/brownfield-navigation/references/native-integration.md
rename to skills/brownfield-navigation/references/native-integration.md
diff --git a/.agents/skills/brownfield-navigation/references/setup-codegen.md b/skills/brownfield-navigation/references/setup-codegen.md
similarity index 100%
rename from .agents/skills/brownfield-navigation/references/setup-codegen.md
rename to skills/brownfield-navigation/references/setup-codegen.md