Update and add documentation

Author: kraenhansen

docs/ANDROID.md

@@ -1,4 +1,6 @@
-# Building Hermes from source
+# Android support
+
+## Building Hermes from source
 
 Because we're using a version of Hermes patched with Node-API support, we need to build React Native from source.
 
@@ -8,6 +10,8 @@ export REACT_NATIVE_OVERRIDE_HERMES_DIR=`npx react-native-node-api-modules vendo
 
 ## Cleaning your React Native build folders
 
+If you've accidentally built your app without Hermes patched, you can clean things up by deleting the `ReactAndroid` build folder.
+
 ```
 rm -rf node_modules/react-native/ReactAndroid/build
 ```

docs/AUTO-LINKING.md

@@ -0,0 +1,27 @@
+# Auto-linking
+
+The `react-native-node-api-modules` package (sometimes referred to as "the host package") has mechanisms to automatically find and link prebuilt binaries with Node-API modules.
+
+When auto-linking, prebuilt binaries are copied (sometimes referred to as vendored) from dependencies of the app into the host package. As they're copied, they get renamed to avoid conflicts in naming as the library files across multiple dependency packages will be sharing a namespace when building the app.
+
+## Naming scheme of libraries when linked into the host
+
+The name of the library when linked / copied into the host is based on two things:
+
+- The package name of the encapsulating package: The directory tree is walked from the original library path to the nearest `package.json` (this is the Node-API module's package root).
+- The relative path of the library to the package root:
+  - Normalized (any "lib" prefix or file extension is stripped from the filename).
+  - Escaped (any non-alphanumeric character is replaced with "-").
+
+## How do I link Node-API module libraries into my app?
+
+Linking will run when you `pod install` and as part of building your app with Gradle as long as your app has a dependency on the `react-native-node-api-modules` package.
+
+You can also manually link by running the following in your app directory:
+
+```bash
+npx react-native-node-api-modules link --android --apple
+```
+
+> [!NOTE]
+> Because vendored frameworks must be present when running `pod install`, you have to run `pod install` if you add or remove a dependency with a Node-API module (or after creation if you're doing active development on it).

docs/PREBUILDS.md

@@ -1,17 +1,38 @@
 # Prebuilds
 
-This document will codify the naming and directory structure of prebuilt binaries, expected by the `react-native-node-api-modules` package and tools.
+This document codifies the naming and directory structure of prebuilt binaries, expected by the auto-linking mechanism.
 
-To align with prior art and established patterns around the distribution of Node-API modules for Node.js (and other engines supporting this), 
+At the time of writing, our auto-linking host package (`react-native-node-api-modules`) support two kinds of prebuilds:
 
-## Apple: XCFrameworks of dynamic libraries in frameworks
+## `*.android.node` (for Android)
+
+A jniLibs-like directory structure of CPU-architecture specific directories containing a single `.so` library file.
+
+The name of all the `.so` library files:
+
+- must be the same across all CPU-architectures
+- can have a "lib" prefix, but doesn't have to
+- must have an `.so` or `.node` file extension
+
+> [!NOTE]
+> The `SONAME` doesn't have to match and is not updated as the .so is copied into the host package.
+> This might cause trouble if you're trying to link with the library from other native code.
+> We're tracking [#14](https://github.com/callstackincubator/react-native-node-api-modules/issues/14) to fix this 🤞
+
+The directory must have a `react-native-node-api-module` file (the content doesn't matter), to signal that the directory is intended for auto-linking by the `react-native-node-api-module` package.
+
+## `*.apple.node` (for Apple)
+
+An XCFramework of dynamic libraries wrapped in `.framework` bundles, renamed from `.xcframework` to `.apple.node` to ease discoverability.
 
 The Apple Developer documentation on ["Creating a multiplatform binary framework bundle"](https://developer.apple.com/documentation/xcode/creating-a-multi-platform-binary-framework-bundle#Avoid-issues-when-using-alternate-build-systems) mentions:
 
 > An XCFramework can include dynamic library files, but only macOS supports these libraries for dynamic linking. Dynamic linking on iOS, watchOS, and tvOS requires the XCFramework to contain .framework bundles.
 
-<!-- TODO: Write this -->
+The directory must have a `react-native-node-api-module` file (the content doesn't matter), to signal that the directory is intended for auto-linking by the `react-native-node-api-module` package.
+
+## Why did we choose this naming scheme?
 
-## Android: Directory of architecture specific directories of shared object library files.
+To align with prior art and established patterns around the distribution of Node-API modules for Node.js, we've chosen to use the ".node" filename extension for prebuilds of Node-API modules, targeting React Native.
 
-<!-- TODO: Write this -->
+To enable distribution of packages with multiple co-existing platform-specific prebuilts, we've chosen to lean into the pattern of platform-specific filename extensions, used by the Metro bundler.