Docs: Clarify native code placement in Flutter modules (#12968)

Fixes #12960. Clarifies that the .android folder is ephemeral and that
native code should be placed in Plugins or the Host App.

---------

Co-authored-by: Camille Simon <[email protected]>
Co-authored-by: John Ryan <[email protected]>
Co-authored-by: Brett Morgan <[email protected]>

Author: 4 people

src/content/add-to-app/android/project-setup.md

@@ -122,37 +122,39 @@ follow these steps:
 
 #### Create a Flutter module
 
-Let's assume that you have an existing Android app at
+Assuming that you have an existing Android app at
 `some/path/MyApp`, and that you want your Flutter
-project as a sibling:
+project as a sibling, do the following:
 
 ```console
 cd some/path/
 flutter create -t module --org com.example flutter_module
 ```
 
 This creates a `some/path/flutter_module/` Flutter module project
-with some Dart code to get you started and an `.android/`
+with some Dart code to get you started and a `.android/`
 hidden subfolder. The `.android` folder contains an
 Android project that can both help you run a barebones
-standalone version of your Flutter module via `flutter run`
+standalone version of your Flutter module with `flutter run`
 and it's also a wrapper that helps bootstrap the Flutter
 module an embeddable Android library.
 
-:::note
-Add custom Android code to your own existing
-application's project or a plugin,
-not to the module in `.android/`.
-Changes made in your module's `.android/`
-directory won't appear in your existing Android
-project using the module.
-
-Do not source control the `.android/` directory
-since it's autogenerated. Before building the
-module on a new machine, run `flutter pub get`
-in the `flutter_module` directory first to regenerate
-the `.android/` directory before building the
-Android project using the Flutter module.
+:::warning
+**Do not** edit files in `.android/` to add native functionality.
+This folder is generated for testing purposes and **will be overwritten**
+whenever you run `flutter pub get` or build the module.
+
+* To add native code that you can use across apps/modules,
+  create a [Flutter Plugin](/packages-and-plugins/developing-packages#plugin)
+  and depend on it.
+* To add **app-specific** native code,
+  add it directly to your existing Android host application.
+
+The `.android` directory contains a generated Android project that uses Java
+to bootstrap the Flutter module, so **do not** add it to source control.
+This approach helps you run a barebones standalone version
+of your Flutter module (with `flutter run`) and verify basic functionality.
+Using Java here doesn't prevent you from using Kotlin in your host app or plugins.
 :::
 
 :::note