docs: update documentation (first part)

Author: grabbou

docs/docs/docs/_meta.json

@@ -4,6 +4,11 @@
     "name": "introduction.mdx",
     "label": "Introduction"
   },
+  {
+    "type": "file",
+    "name": "quick-start.mdx",
+    "label": "Quick Start"
+  },
   {
     "type": "dir",
     "name": "core",

docs/docs/docs/backends/_meta.json

@@ -1,12 +1,17 @@
 [
+  {
+    "type": "file",
+    "name": "introduction.mdx",
+    "label": "Introduction"
+  },
   {
     "type": "file",
     "name": "backend-platform.mdx",
-    "label": "Platform Backend"
+    "label": "Platform"
   },
   {
     "type": "file",
-    "name": "backend-wrapper-tracy.mdx",
-    "label": "Tracy Wrapper Backend"
+    "name": "backend-tracy.mdx",
+    "label": "Tracy"
   }
 ]

docs/docs/docs/backends/backend-platform.mdx

@@ -1,5 +1,73 @@
-import Readme from '../../../../packages/backend-platform/README.md';
+# @ottrelite/backend-platform
 
-# Platform Backend
+This plugin is the platform-specific backend implementation for RN Ottrelite Core. On Android, it utilizes [ATrace](https://developer.android.com/ndk/reference/group/tracing) (Android tracing API), on iOS it utilizes the [OSSignposter API](https://developer.apple.com/documentation/os/ossignposter).
 
-<Readme />
+## When to use this backend?
+
+This backend is designed for **system-level analysis using familiar tools** that are already part of your development environment. It leverages the native profiling APIs built into Android and iOS platforms, allowing you to use the debugging tools you're already comfortable with.
+
+Use Platform Backend when you want:
+- **Familiar tooling** - Work with Android Studio Profiler and Xcode Instruments that you already know
+- **System-level insights** - Analyze app performance alongside system metrics and other processes
+- **No additional setup** - Uses built-in platform APIs without requiring external profiling tools
+
+:::important
+This backend is not designed for production use cases and should not be installed in production builds. See the [backends introduction](/docs/backends/introduction#production-builds) for guidance on excluding backends from production builds.
+:::
+
+## Supported features
+
+| Feature                                       | Android Support | iOS Support |
+| --------------------------------------------- | --------------- | ----------- |
+| synchronous traces (`{begin,end}Event`)       | API level ≥ 23 (Android M) | iOS 15+ |
+| asynchronous traces (`{begin,end}AsyncEvent`) | API level ≥ 29 (Android Q) | iOS 15+ |
+| counter events (`counterEvent`)               | API level ≥ 29 (Android Q) | iOS 15+ |
+
+:::note
+The support levels above mean that the application must be **compiled** with at least the given `minSdkVersion`. This is because those APIs are not available on older Android versions and therefore it is not possible to compile the native code against older SDKs.
+:::
+
+## Installation
+
+To use this package, you need to install it in your React Native project:
+
+```bash
+npm install @ottrelite/backend-platform
+```
+
+And register the backend with Ottrelite Core in your entrypoint file (e.g. `index.js`):
+
+```typescript
+import { OttreliteBackendPlatform } from '@ottrelite/backend-platform';
+import { Ottrelite } from '@ottrelite/core';
+
+Ottrelite.install([OttreliteBackendPlatform]);
+```
+
+## Recording the trace
+
+### Android
+
+You can record and view traces in two ways:
+- using Android Studio's Profiler's 'Capture System Activities' option, as per the [documentation](https://developer.android.com/studio/profile); this method works both on physical devices & the Android emulator
+- using the `perfetto` CLI tool, which is distributed as part of the Android OS onboard most modern devices. More details can be found in the [documentation](https://perfetto.dev/docs/getting-started/system-tracing); the resulting file can be viewed in [Perfetto UI](https://ui.perfetto.dev/); this method works only on a physical device
+
+:::important
+Make sure that the app you are profiling is `profileable` by placing an [appropriate element](https://developer.android.com/guide/topics/manifest/profileable-element) within your `AndroidManifest.xml`'s `<application>` element: `<profileable android:shell="true" />`
+:::
+
+#### Perfetto CLI
+
+If using the Perfetto CLI via the `record_android_trace` script, make sure to adjust the `--app` argument to match your app's package. We discovered that on some devices it is needed to set it, otherwise some userspace events may be missing.
+
+Some devices allow to pass an additional tracing category, `app`, which can also be considered in such cases. An example invocation might look like the following: 
+
+```bash
+./record_android_trace --app=com.callstack.ottrelite.demo -o trace_file.perfetto-trace -t 40s -b 64mb sched freq idle am wm gfx view binder_driver hal dalvik camera input res memory rs app
+```
+
+### iOS
+
+You can view the traces in Xcode Instruments, as per the [documentation](https://developer.apple.com/documentation/os/recording-performance-data#Review-Signposts-in-Instruments).
+
+The traces will be signpost-ed using the `OSSignposter` API, using the default `OS_LOG_DEFAULT` logger.

docs/docs/docs/backends/backend-tracy.mdx

@@ -0,0 +1,82 @@
+# @ottrelite/backend-wrapper-tracy
+
+This plugin is a wrapper around the [open-source Tracy profiler](https://github.com/wolfpld/tracy) client, which brings tracing using Tracy to Ottrelite.
+
+## When to use this backend?
+
+The Tracy backend is designed for **real-time development profiling** and provides immediate visual feedback as your React Native app runs. Unlike the Platform backend which requires recording sessions and post-analysis, Tracy gives you live insights into your app's performance.
+
+Use Tracy when you want:
+- **Real-time feedback** - See performance data as it happens, perfect for iterative optimization
+- **Frame-by-frame analysis** - Detailed timing information for each frame of your app
+- **Cross-platform consistency** - Same profiling experience across iOS and Android
+- **Memory tracking** - Visual representation of memory usage patterns
+- **Interactive exploration** - Zoom, filter, and analyze traces dynamically
+
+:::important
+This backend is not designed for production use cases and should not be installed in production builds. See the [backends introduction](/docs/backends/introduction#production-builds) for guidance on excluding backends from production builds.
+:::
+
+## Supported features
+
+| Feature                                       | Support level                                                              |
+| --------------------------------------------- | -------------------------------------------------------------------------- |
+| synchronous traces (`{begin,end}Event`)       | Supported                                                                  |
+| asynchronous traces (`{begin,end}AsyncEvent`) | Unsupported (see [tracy#149](https://github.com/wolfpld/tracy/issues/149)) |
+| counter events (`counterEvent`)               | Supported                                                                  |
+
+## Installation
+
+To use this package, you need to install it in your React Native project:
+
+```bash
+npm install @ottrelite/backend-wrapper-tracy
+```
+
+And register the backend with Ottrelite Core in your entrypoint file (e.g. `index.js`):
+
+```typescript
+import { OttreliteBackendTracy } from '@ottrelite/backend-wrapper-tracy';
+import { Ottrelite } from '@ottrelite/core';
+
+Ottrelite.install([OttreliteBackendTracy]);
+```
+
+:::important
+Remember to give attribution to the Tracy Profiler in your application, as in the [last section](#additional-information).
+:::
+
+## Recording the trace
+
+To record the trace, you must use the Tracy Profiler tool. For Windows, there are releases containg `.7z` archives with prebuilt binaries, for other platforms you must follow the [documentation](https://github.com/wolfpld/tracy/releases/latest/download/tracy.pdf) to build it yourself. 
+
+In short, the instructions to build the Tracy Profiler tool locally are as follows:
+
+```bash
+git clone -b v0.12.2 https://github.com/wolfpld/tracy
+cd tracy
+cmake -B profiler/build -S profiler -DCMAKE_BUILD_TYPE=Release
+cmake --build profiler/build --config Release --parallel
+cd profiler/build
+# on Windows, you can now run tracy-profiler.exe from this directory.
+# on macOS & Linux, you can run ./tracy-profiler from this directory.
+./tracy-profiler
+```
+
+In case of Android, simply forward the port used by Tracy (default is `8086`) to your device/emulator, e.g. using `adb` for Android:
+
+```bash
+adb forward tcp:8086 tcp:8086
+```
+
+## Limitations
+
+The `tracy::Profiler::PlotData` function that handles counter events assumes that the counter's name is persisted (it does not copy the string data, just a pointer to it). This is valid for C++ usage where the data is hardcoded in the code (static), yet here (e.g. from JS) it is dynamic. Therefore, this backend keeps the strings passed to the `counterEvent` function in an `std::unordered_set` to ensure that the strings are not deallocated whenever Tracy would try to access them. This means that the counter names will be kept in memory for the lifetime of the backend instance, so be careful with the number of unique counter names you use - using an enormous number of unique counter names (or of enormous lengths) may lead to increased memory usage.
+
+Since Tracy does not support async events, OTEL APIs data will not be visible here. This is because the closest equivalent of OTEL's `Span`s are async events, which are not supported by this backend.
+
+## Additional information
+
+This package utilizes the Tracy Profiler client API under the hood. Please remember to give proper attribution to the Tracy Profiler in your application, as per the [Tracy Profiler license](https://github.com/wolfpld/tracy/blob/master/LICENSE).
+
+Many thanks to the author & contributors of the [Tracy Profiler](https://github.com/wolfpld/tracy).

docs/docs/docs/backends/backend-wrapper-tracy.mdx

@@ -0,0 +1,74 @@
+# Visualization Backends
+
+Visualization backends are the "display layer" of Ottrelite that transform your trace data into actionable insights. They take raw performance data from your React Native app and present it in different tools and formats to help you quickly identify bottlenecks and optimization opportunities.
+
+## What are Backends?
+
+Backends in Ottrelite are plugins that handle how and where your tracing data is visualized. Each backend connects to different profiling tools and provides unique perspectives on your app's performance. You can use multiple backends simultaneously to get comprehensive insights from different angles.
+
+Think of backends as different "viewers" for the same performance data - some excel at real-time analysis, others integrate with tools you're already familiar with, and some provide specialized visualizations for specific use cases.
+
+## Available Backends
+
+| Backend | Package | Best For | What It Does |
+|---------|---------|----------|--------------|
+| **Platform** | `@ottrelite/backend-platform` | System-level analysis with familiar tools | Integrates with Android Studio Profiler, Xcode Instruments, and Perfetto using native platform APIs |
+| **Tracy** | `@ottrelite/backend-wrapper-tracy` | Real-time development profiling | Frame-by-frame analysis with live trace visualization, memory tracking, and cross-platform support |
+
+### Platform Backend
+
+The Platform backend leverages native tracing APIs that you're likely already familiar with:
+- **Android**: Uses ATrace API, viewable in Android Studio Profiler or Perfetto
+- **iOS**: Uses OSSignposter API, viewable in Xcode Instruments
+
+This backend is ideal when you want to use the profiling tools built into your development environment.
+
+### Tracy Backend  
+
+The Tracy backend wraps the open-source Tracy profiler, providing real-time profiling capabilities:
+- Live trace visualization as your app runs
+- Frame-by-frame performance analysis
+- Memory tracking and visualization
+- Cross-platform consistency
+
+This backend is perfect for iterative development where you want immediate feedback on performance changes.
+
+## Production Builds
+
+Backends are designed for development use only and should not be included in production builds. 
+
+To exclude backends from production builds:
+
+1. **Conditional installation** - Install backends only when a development feature flag is set:
+
+```typescript
+import { Ottrelite } from '@ottrelite/core';
+
+if (__DEV__ || isProfilingEnabled) {
+  const { OttreliteBackendPlatform } = require('@ottrelite/backend-platform');
+  Ottrelite.install([OttreliteBackendPlatform]);
+}
+```
+
+2. **Build-time exclusion** - Use `react-native.config.js` to exclude backend packages from specific build types:
+
+```javascript
+module.exports = {
+  dependencies: {
+    '@ottrelite/backend-platform': {
+      platforms: {
+        android: {
+          buildTypes: ['debug'], // Only include in debug builds
+        },
+        ios: {
+          configurations: ['Debug'], // Only include in debug builds
+        },
+      },
+    },
+  },
+};
+```
+
+:::important
+If you've created a separate optimized configuration for performance profiling (as recommended in the [installation guide](/docs/core/introduction#configuring)), make sure to include that configuration in your build-time exclusion list as well to prevent it from being shipped to production.
+:::

docs/docs/docs/backends/introduction.mdx

@@ -4,11 +4,6 @@
     "name": "quick-start.mdx",
     "label": "Quick Start"
   },
-  {
-    "type": "file",
-    "name": "react-api.mdx",
-    "label": "React API"
-  },
   {
     "type": "file",
     "name": "react-native-internals.mdx",