📘 docs(native): Reorganizing and normalizing native-related documentation

README.md

@@ -97,10 +97,15 @@ Native iOS work is also present in this repository as a pre-release Swift Packag
 adapter and the [iOS reference app](./implementations/ios-sdk/README.md). Treat this surface as
 alpha implementation work rather than a stable public native SDK.
 
-The following native and framework SDKs are planned but are not published from this repository:
+Native Android support is also present as a pre-release Kotlin Android library under
+[`packages/android`](./packages/android/README.md), published as the Maven AAR
+`com.contentful.java:optimization-android`, backed by the shared
+[`@contentful/optimization-js-bridge`](./packages/universal/optimization-js-bridge/README.md)
+adapter and the [Android reference app](./implementations/android-sdk/README.md). Treat this surface
+as alpha implementation work rather than a stable public native SDK.
+
+The following framework SDKs are planned but are not published from this repository:
 
-- Android Kotlin SDK
-- Android Java SDK
 - Nest.js SDK
 - Angular SDK
 - Svelte SDK
@@ -123,7 +128,9 @@ patterns with intentionally minimal application code.
 - [React Native](./implementations/react-native-sdk/README.md) - mobile application integration for
   Android and iOS targets
 - [iOS Reference App](./implementations/ios-sdk/README.md) - native app and XCUITest surface for
-  current iOS bridge and preview-panel scenarios; this is not a published iOS SDK package
+  current iOS bridge and preview-panel scenarios
+- [Android Reference App](./implementations/android-sdk/README.md) - native Compose and XML Views
+  app shells plus Maestro E2E coverage for Android bridge and preview-panel scenarios
 
 ## Repository layout
 

documentation/concepts/README.md

@@ -8,9 +8,8 @@ children:
   - ./interaction-tracking-in-node-and-stateless-environments.md
   - ./profile-synchronization-between-client-and-server.md
   - ./react-native-sdk-interaction-tracking-mechanics.md
-  - ./native-mobile-sdk-architecture.md
-  - ./ios-sdk-bridge.md
-  - ./android-sdk-bridge.md
+  - ./ios-sdk-runtime-and-interaction-mechanics.md
+  - ./android-sdk-runtime-and-interaction-mechanics.md
 ---
 
 # Concepts
@@ -46,13 +45,11 @@ they are not the first stop for installation or setup commands.
   explains how the React Native SDK observes, gates, and emits tracking events, covering event
   types, the viewport state machine, default visibility and timing, consent gating, scroll context,
   screen tracking paths, and the configuration resolution order
-- [Native mobile SDK architecture](./native-mobile-sdk-architecture.md) - explains how one
-  TypeScript core runs inside JavaScriptCore on iOS and QuickJS on Android, how polyfills are
-  prepended into the UMD bundle at build time, and how identify, screen, and personalizeEntry
-  round-trip across the JS-native bridge.
-- [iOS SDK bridge](./ios-sdk-bridge.md) - explains the JavaScriptCore context lifecycle, native
-  polyfill bindings, async callback registration, the threading model, and the diagnostics channels
-  (exception handler, fetch signposts) used by the iOS SDK.
-- [Android SDK bridge](./android-sdk-bridge.md) - explains the QuickJS engine wrapper, the
-  single-threaded dispatcher that serializes JS evaluation, the `__native.log`-routing mechanism
-  that delivers async callbacks to Kotlin, and the coroutine integration on the public API.
+- [iOS SDK runtime and interaction mechanics](./ios-sdk-runtime-and-interaction-mechanics.md) -
+  explains how the iOS SDK runs shared optimization behavior through a native bridge, how SwiftUI
+  and UIKit integrations share runtime state, and how consent, personalization, tracking, preview
+  overrides, and offline delivery work
+- [Android SDK runtime and interaction mechanics](./android-sdk-runtime-and-interaction-mechanics.md) -
+  explains how the Android SDK runs shared optimization behavior through QuickJS, how Compose and
+  XML Views integrations share runtime state, and how consent, personalization, tracking, preview
+  overrides, and offline delivery work