youtube · AIdrifter · Jul 23, 2026
diff --git a/cobalt/site/docs/development/index.md b/cobalt/site/docs/development/index.md
@@ -0,0 +1,107 @@
+Project: /youtube/cobalt/_project.yaml
+Book: /youtube/cobalt/_book.yaml
+
+# Development & Build Platforms Overview
+
+Welcome to Cobalt Development! Cobalt supports multiple operating systems, hardware architectures, and build host environments.
+
+This guide provides an overview of the supported platforms, their target hardware, intended use cases, and recommended development workflows.
+
+---
+
+## Supported Build Platforms & Setup Guides
+
+| Platform / Tooling | Type | Target Architecture & Hardware | Primary Purpose & Intended Use | Setup Guide |
+| :--- | :--- | :--- | :--- | :--- |
+| **Linux** | Target OS | **x86_64 Desktop** (Ubuntu / X11 / Wayland) | **Developer Workstation Environment**. Provides the fastest compile-and-debug iteration cycle for core logic, Web APIs, and Starboard verification (`nplb`), without requiring embedded TV hardware. | [setup-linux.md](setup-linux.md) |
+| **Android TV (ATV)** | Target OS | **ARM / ARM64 / x86** (Smart TVs, Streaming Sticks) | **Android TV Production Target**. Compiles native engine (`libchrobalt.so`) and packages into standard Android application package (`Cobalt.apk`, `dev.cobalt.coat`). | [setup-android.md](setup-android.md) |
+| **RDK** | Target OS | **ARM / ARM64** (Pay-TV Set-Top Boxes, STB reference hardware) | **Pay-TV & STB Platform Target**. Integrates Starboard for RDK (`evergreen-arm-hardfp-rdk`) for operator-managed set-top box deployments. | [setup-rdk.md](setup-rdk.md) |
+| **Docker** | Host Tooling | **Linux x86_64 Host** (Containerized Builder) | **Build Environment Consistency**. Containerized build host tool that standardizes dependencies and tools across developer workstations to avoid host OS version conflicts. | [setup-docker.md](setup-docker.md) |
+
+---
+
+## Recommended Development Workflow
+
+To maximize development efficiency, we recommend following a 3-stage development workflow:
+
+1. **Stage 1: Core Logic & Web Feature Development**
+   - **Platform**: `Linux` (`linux-x64x11`)
+   - **Why**: Fastest build times, direct gdb/lldb integration, and immediate execution on your workstation. Run `nplb` to verify Starboard API compliance.
+
+2. **Stage 2: Standardized Host Build Environment**
+   - **Tooling**: `Docker`
+   - **Why**: Use containerized build definitions to build for cross-compiled targets (like RDK or Android) without polluting or conflicting with your local host environment.
+
+3. **Stage 3: Target Device & Media Integration Validation**
+   - **Platform**: `Android TV` or `RDK`
+   - **Why**: Final testing of hardware video/audio decoding, platform lifecycle (suspend/resume), remote control input handling, and system-level performance.
+
+---
+
+## Core Compilation & Debug Verification: Evergreen vs. Native APK
+
+When developing, debugging, or verifying custom Cobalt modifications on device hardware, developers and SoC partners must distinguish between Cobalt's two fundamentally different runtime architectures. Build targets, compression steps, and library replacement procedures differ substantially across platforms:
+
+| Feature / Step | Evergreen Architecture (RDK / Linux) | Native APK Architecture (Android TV) |
+| :--- | :--- | :--- |
+| **Target Architecture** | **Evergreen Dynamic Slot** (`use_evergreen = true`) | **Standard Android Application** (`use_evergreen = false`) |
+| **Primary Build Target** | **`cobalt`** and **`lz4_compress`** | **`cobalt_apk`** |
+| **Compiled Artifacts** | `app/cobalt/lib/libcobalt.so` and `libcobalt.lz4` | `apks/Cobalt.apk` (`dev.cobalt.coat`, bundling `libchrobalt.so`) |
+| **Debug & Verification** | **Direct Slot Replacement**. Unpack the CRX or access Slot 0 on device, and overwrite `libcobalt.so` (or `.lz4`) via SSH/SCP or `deploy_rdk.py --only-lib`. | **Full APK Reinstallation**. Do not modify filesystem shared libraries directly; reinstall the updated package via `adb install -r -d Cobalt.apk`. |
+| **Host Compression** | Required when testing production compressed library loading (`lz4_compress`). | **Not used / Inapplicable**. Native packaging directly handles shared library compression in APK. |
+
+> [!IMPORTANT]
+> **Live Replacement Safety Rules for Evergreen Platforms:**
+> When replacing shared libraries (`libcobalt.so` or `libcobalt.lz4`) directly on live RDK or Linux target hardware:
+> 1. **Stop Active Processes First**: Kill running `loader_app` or WPEFramework `YouTube` sessions before copying new files. Overwriting active mapped libraries without stopping the process causes immediate `Text file busy` failures or fatal kernel segmentation faults.
+> 2. **Deploy Both Formats**: When testing unstripped builds, deploy both uncompressed (`.so`) and compressed (`.lz4`) library files simultaneously to avoid loader magic signature parsing exceptions.
+> 3. **Keep Resources Synchronized**: If your modifications change interface definitions or resources, always push updated `content/` resources (`cobalt_shell.pak`) alongside the library binary.
+
+---
+
+## Evergreen Path Configuration & Vendor Deployment Setup
+
+When deploying prebuilt or custom-built Evergreen packages (unzipped CRX packages) onto target Linux/ARM hardware, configure the following path parameters and environment variables.
+
+### 1. Evergreen Path Parameter Mapping Reference
+
+| Parameter / Variable | Category | Expected Target Path | Description |
+| :--- | :--- | :--- | :--- |
+| **`--evergreen_library`** | `elf_loader_sandbox` Switch | `<target_root>/app/cobalt/lib/libcobalt.so` (or `libcobalt.lz4`) | Points to the Cobalt Core shared library binary. |
+| **`--evergreen_content`** | `elf_loader_sandbox` Switch | `<target_root>/app/cobalt/content` | Points to the web engine resource directory containing `cobalt_shell.pak`, `fonts/`, and `ssl/`. |
+| **`--content`** | `loader_app` Switch | `<target_root>` | Overrides the base root directory for `kSbSystemPathContentDirectory`. `loader_app` will append `/app/cobalt/` to locate Slot 0. |
+| **`kSbSystemPathContentDirectory`** | Starboard System Path API | `<target_root>` | Returned by `SbSystemGetPath()`. Used by `loader_app` to construct paths for `manifest.json`, `lib/`, and `content/`. |
+
+#### Target Directory Structure (Cobalt 27.lts Slot 0 Layout):
+```text
+/usr/share/content/data/                   <-- Base Target Root (<target_root>)
+├── loader_app                             <-- Partner-built Loader executable
+├── elf_loader_sandbox                     <-- Sandbox test executable
+└── app/
+    └── cobalt/                            <-- Factory Slot 0 Directory
+        ├── manifest.json                  <-- Evergreen manifest file
+        ├── lib/
+        │   └── libcobalt.so               <-- Core shared library
+        └── content/
+            ├── cobalt_shell.pak           <-- UI and web resources
+            ├── fonts/                     <-- System fonts and fonts.xml
+            └── ssl/                       <-- Root CA certificates
+```
+
+### 2. Platform Setup Guides for Custom Core Compilation & Prebuilt CRX Unpacking
+
+Detailed step-by-step instructions for compiling custom Cobalt Core binaries, unzipping prebuilt `.crx` packages, and installing packages on target hardware are maintained in each platform's dedicated setup guide:
+
+* **Linux Workstation & Desktop**:
+  Refer to **[setup-linux.md](setup-linux.md#running-in-evergreen-mode)** for compiling custom `cobalt` binaries, compressing libraries with `lz4_compress`, and unpacking prebuilt `.crx` packages into Slot 0 (`app/cobalt/`).
+* **RDK / Pay-TV Set-Top Boxes**:
+  Refer to **[setup-rdk.md](setup-rdk.md#build-cobalt-binary-for-the-rdk-platform)** for compiling `loader_app_rdk_plugin`, deploying prebuilt `.crx` packages to RDK hardware, and staging Slot 0 (`app/cobalt/`) directories.
+* **Android TV (Chrobalt ATV)**:
+  Refer to **[setup-android.md](setup-android.md#5-compiling--packaging)** for building native `Cobalt.apk` (`use_evergreen = false`) and deploying over ADB. *(Note: Prebuilt `.crx` unpacking does not apply to Android TV).*
+
+---
+
+## Additional References
+
+- [Supported Features](reference/supported-features.md)
+- [Troubleshooting Guide](reference/troubleshooting.md)
diff --git a/cobalt/site/docs/development/setup-android.md b/cobalt/site/docs/development/setup-android.md
@@ -144,9 +144,9 @@ build_type = "qa"       # Options: "debug", "devel", "qa", "gold"
 
 Chrobalt ATV packages its implementation into `Cobalt.apk` defined in `//cobalt/android/BUILD.gn`.
 
-### Building the Application APK
+### Compiling Native Cobalt Core & Application APK
 
-Build the target using `autoninja` (which automatically optimizes core utilization):
+For Android TV builds, the Cobalt Core engine is compiled directly into a native shared library (`libchrobalt.so`) embedded inside `Cobalt.apk`:
 
 ```bash
 autoninja -C out/android-arm_qa cobalt_apk
@@ -158,6 +158,13 @@ Upon successful compilation, the output APK will be available at:
 out/android-arm_qa/apks/Cobalt.apk
 ```
 
+> [!IMPORTANT]
+> **Prebuilt CRX & Evergreen Unpacking Applicability Note:**
+> Unlike Linux and RDK platforms (which use `use_evergreen = true`), Android TV operates as a **Native Monolithic APK** (`use_evergreen = false`).
+> * **CRX Packages**: Prebuilt `.crx` package downloading, unpacking, and Slot 0 file replacement do **NOT** apply to Android TV.
+> * **Library Compression**: `lz4_compress` is neither supported nor needed, as the Android package manager handles APK native library extraction natively.
+> * **Updating Core Logic**: To deploy core logic updates or custom C++ modifications to Android TV hardware, recompile `cobalt_apk` and reinstall the entire package via `adb install -r -d Cobalt.apk`.
+
 ---
 
 ## 6. Device Deployment & Execution

diff --git a/cobalt/site/docs/development/setup-linux.md b/cobalt/site/docs/development/setup-linux.md
@@ -143,24 +143,68 @@ To use this feature, build and run one of these configurations and monitor the t
 
 Because Evergreen support is required for certification, you can also run Cobalt in Evergreen mode on Linux.
 
+### Option A: Compiling Custom Cobalt Core & Loader from Source
+
 1. Initialize an Evergreen build directory for `evergreen-x64`:
 
    ```bash
    cobalt/build/gn.py -p evergreen-x64 -c qa --no-rbe
    ```
 
-2. Compile the `cobalt_loader` target, which packages the compressed Evergreen library:
+2. Compile the Cobalt Core shared library and host compression tool:
+
+   ```bash
+   autoninja -C out/evergreen-x64_qa cobalt lz4_compress loader_app
+   ```
+
+3. (Optional) Compress the shared library for testing LZ4 compressed binary loading:
 
    ```bash
-   autoninja -C out/evergreen-x64_qa cobalt_loader
+   out/evergreen-x64_qa/clang_x64/lz4_compress \
+     out/evergreen-x64_qa/app/cobalt/lib/libcobalt.so \
+     out/evergreen-x64_qa/app/cobalt/lib/libcobalt.lz4
    ```
 
-3. Launch Cobalt in Evergreen mode by running the generated helper script:
+4. Launch Cobalt in Evergreen mode by running the generated helper script:
 
    ```bash
    out/evergreen-x64_qa/cobalt_loader.py [--url=<url>]
    ```
 
+### Option B: Deploying Official Google Prebuilt CRX Packages
+
+In production integration, partners can test with official Google prebuilt `.crx` packages instead of compiling Cobalt Core from source.
+
+1. **Download the Official Prebuilt CRX File**:
+
+   ```bash
+   export LOCAL_CRX_DIR=/tmp/cobalt_dl
+   rm -rf $LOCAL_CRX_DIR && mkdir -p $LOCAL_CRX_DIR
+
+   COBALT_CRX_URL="https://github.com/youtube/cobalt/releases/download/<version>/cobalt_evergreen_<version>_x64_<config>.crx"
+   wget $COBALT_CRX_URL -O $LOCAL_CRX_DIR/cobalt_prebuilt.crx
+   ```
+
+2. **Unpack the CRX Package**:
+
+   ```bash
+   unzip $LOCAL_CRX_DIR/cobalt_prebuilt.crx -d $LOCAL_CRX_DIR/cobalt_prebuilt
+   ```
+
+3. **Stage Unpacked Files into Slot 0 (`app/cobalt/`) Layout**:
+
+   > [!IMPORTANT]
+   > In Cobalt 27.lts, all Slot 0 factory binaries must be located strictly under `<target_root>/app/cobalt/`.
+
+   ```bash
+   export EVERGREEN_DIR=out/evergreen-x64_qa
+   mkdir -p $EVERGREEN_DIR/app/cobalt/lib $EVERGREEN_DIR/app/cobalt/content
+
+   cp -f $LOCAL_CRX_DIR/cobalt_prebuilt/manifest.json $EVERGREEN_DIR/app/cobalt/
+   cp -rf $LOCAL_CRX_DIR/cobalt_prebuilt/lib/* $EVERGREEN_DIR/app/cobalt/lib/
+   cp -rf $LOCAL_CRX_DIR/cobalt_prebuilt/content/* $EVERGREEN_DIR/app/cobalt/content/
+   ```
+
 ## Running Tests
 
 The No Platform Left Behind (NPLB) test suite verifies Starboard implementation and is mandatory for certification.

diff --git a/cobalt/site/docs/development/setup-rdk.md b/cobalt/site/docs/development/setup-rdk.md
@@ -102,36 +102,84 @@ python3 build/linux/sysroot_scripts/install-sysroot.py --arch=arm
 
 ### Build Cobalt binary for the RDK platform
 
-Generate the build files and compile Cobalt:
+Generate the build files and compile Cobalt for RDK hardware:
 
-1.  **Ensure environment variables are set**:
+#### Option A: Compiling Cobalt Core & RDK Loader from Source
 
-    ```
+1. **Ensure environment variables are set**:
+
+    ```bash
     export PATH="$HOME/depot_tools:$PATH"
     export RDK_HOME=$HOME/rdk/toolchain
     ```
 
-2.  **Generate build files**:
+2. **Generate build files**:
 
-    ```
+    ```bash
     cobalt/build/gn.py -p evergreen-arm-hardfp-rdk -c qa --no-rbe
     ```
 
-3.  **Compile targets**:
+3. **Compile Cobalt Core library, LZ4 compression tool, and RDK plugin targets**:
 
-    ```
-    autoninja -C out/evergreen-arm-hardfp-rdk_qa/ cobalt_loader nplb_loader loader_app_rdk_plugin
+    ```bash
+    autoninja -C out/evergreen-arm-hardfp-rdk_qa/ cobalt lz4_compress loader_app_rdk_plugin nplb_loader
     ```
 
 > [!NOTE]
-> The compile target name contains `_plugin` (`loader_app_rdk_plugin`) because this target compiles both the standalone executable (`loader_app`) and the WPE plugin library (`libloader_app.so`). Both build successfully.
+> `cobalt lz4_compress` directly builds the uncompressed shared library (`app/cobalt/lib/libcobalt.so`) and host compression tool. The compile target name contains `_plugin` (`loader_app_rdk_plugin`) because it compiles both the standalone executable (`loader_app`) and the WPE plugin library (`libloader_app.so`).
+
+#### Option B: Deploying Official Google Prebuilt CRX Packages for RDK
+
+In production and certification, SoC partners and OEMs do not compile Cobalt Core (`libcobalt.so`) from source. Instead, partners build `loader_app_rdk_plugin` and deploy official Google-built prebuilt `.crx` packages onto the device.
+
+1. **Download Official Prebuilt CRX Package**:
+
+   ```bash
+   export LOCAL_CRX_DIR=/tmp/cobalt_dl
+   rm -rf $LOCAL_CRX_DIR && mkdir -p $LOCAL_CRX_DIR
+
+   COBALT_CRX_URL="https://github.com/youtube/cobalt/releases/download/<version>/cobalt_evergreen_<version>_arm-hardfp_<config>.crx"
+   wget $COBALT_CRX_URL -O $LOCAL_CRX_DIR/cobalt_prebuilt.crx
+   ```
+
+2. **Unpack the CRX Package**:
 
+   ```bash
+   unzip $LOCAL_CRX_DIR/cobalt_prebuilt.crx -d $LOCAL_CRX_DIR/cobalt_prebuilt
+   ```
+
+3. **Stage Unpacked Files into 27.lts Slot 0 (`app/cobalt/`) Layout**:
+
+   > [!IMPORTANT]
+   > **Cobalt 27.lts Slot 0 Path Change vs. 25.lts:**
+   > Unlike Cobalt 25.lts (which placed CRX contents directly in `$EVERGREEN_DIR/` or `$EVERGREEN_DIR/install/lib/`), Cobalt 27.lts strictly requires all Slot 0 factory artifacts to be located under `<target_root>/app/cobalt/`.
+
+   *Staging in local build output directory (`$EVERGREEN_DIR`):*
+
+   ```bash
+   export EVERGREEN_DIR=out/evergreen-arm-hardfp-rdk_qa
+   mkdir -p $EVERGREEN_DIR/app/cobalt/lib $EVERGREEN_DIR/app/cobalt/content
+
+   cp -f $LOCAL_CRX_DIR/cobalt_prebuilt/manifest.json $EVERGREEN_DIR/app/cobalt/
+   cp -rf $LOCAL_CRX_DIR/cobalt_prebuilt/lib/* $EVERGREEN_DIR/app/cobalt/lib/
+   cp -rf $LOCAL_CRX_DIR/cobalt_prebuilt/content/* $EVERGREEN_DIR/app/cobalt/content/
+   ```
+
+   *Direct deployment to RDK device target root (e.g. `/usr/share/content/data/`):*
+
+   ```bash
+   ssh root@{RDK IP address} "mkdir -p /usr/share/content/data/app/cobalt/lib /usr/share/content/data/app/cobalt/content"
+
+   scp $LOCAL_CRX_DIR/cobalt_prebuilt/manifest.json root@{RDK IP address}:/usr/share/content/data/app/cobalt/
+   scp -r $LOCAL_CRX_DIR/cobalt_prebuilt/lib/* root@{RDK IP address}:/usr/share/content/data/app/cobalt/lib/
+   scp -r $LOCAL_CRX_DIR/cobalt_prebuilt/content/* root@{RDK IP address}:/usr/share/content/data/app/cobalt/content/
+   ```
 
 ### Generate Archive
 
-Bundle the build artifacts into a tarball for deployment.
+Bundle the build artifacts into a tarball for deployment:
 
-```
+```bash
 tar -czvf archive.tar.gz -C out/evergreen-arm-hardfp-rdk_qa/ \
   -T out/evergreen-arm-hardfp-rdk_qa/cobalt_loader.runtime_deps libloader_app.so \
   -T out/evergreen-arm-hardfp-rdk_qa/nplb_loader.runtime_deps gen/build_info.json