huge rewrite

resources/faq.md

@@ -0,0 +1,54 @@
+# Frequently Asked Questions (FAQ)
+
+<p class="page-description">Answers to common questions regarding the Vyla ecosystem, self-hosting, platform compatibility, and legal policies.</p>
+
+## General Questions
+
+### What is Vyla?
+Vyla is a community-built, decentralized media platform and developer ecosystem. It provides client applications (Desktop, Android, Android TV), a multi-provider scraping resolver SDK (`@vyla-entertainment/sdk`), and a self-hostable HTTP/SSE streaming gateway (Stream API).
+
+### Does Vyla host or stream any media?
+**No.** Vyla does not host, upload, cache, or distribute copyrighted video files or media streams. The software functions purely as a client-side indexing and scraping engine that queries publicly accessible third-party providers on demand.
+
+### Is Vyla free and open source?
+Yes. All components of the Vyla ecosystem are open source, licensed under standard permissive open-source licenses, and free to inspect, fork, and self-host.
+
+---
+
+## Technical & Developer Questions
+
+### Why do I need a TMDB API Key?
+The Movie Database (TMDB) provides authoritative metadata, cover artwork, cast details, and standardized numeric identifiers for movies and TV episodes. Several provider scrapers require converting TMDB IDs to IMDb IDs or episode names. You can obtain a free API key at [themoviedb.org](https://www.themoviedb.org/).
+
+### Why do some sources work on my home PC but fail on a datacenter VPS?
+Many public upstream video hosts employ Cloudflare or proprietary anti-bot protections that block known datacenter IP subnets (e.g. AWS, DigitalOcean, Hetzner, OVH) while allowing residential IP connections. When self-hosting Stream API on a VPS, some scrapers may encounter IP-based challenges that do not appear on residential connections.
+
+### What is the difference between Vyla SDK and Stream API?
+- **Vyla SDK (`@vyla-entertainment/sdk`)**: A Node.js library you install directly in a backend application using `npm install`. It runs scrapers directly in your process.
+- **Stream API**: A standalone, self-hostable HTTP/SSE microservice that wraps the SDK, providing a web API for mobile apps, smart TVs, and browser frontends that cannot execute Node.js modules natively.
+
+### What is the 120-byte segment de-masking routine?
+Certain streaming providers mask video chunks by prepending a 120-byte fake image header (such as a PNG or JPEG file signature) to disguise traffic. Stream API inspects video chunks and automatically slices off the fake header, restoring valid MPEG-TS video for standard video players.
+
+---
+
+## Application & Platform Questions
+
+### Which desktop operating systems are supported by Vyla Home?
+Vyla Home officially supports 64-bit Windows (Windows 10/11), macOS (Universal binary supporting Apple Silicon and Intel), and Linux (via source compilation and Flatpak packages).
+
+### Can I run Vyla TV on Amazon Fire TV devices?
+Yes. Vyla TV is built for Android TV (API 26+) and is fully compatible with Amazon Fire TV devices (Fire TV Stick 4K, Fire TV Cube, etc.). You can sideload the APK using tools like Downloader.
+
+### What should I do if Vyla Home fails with a WebView2 error on Windows?
+Ensure the Microsoft Edge WebView2 Evergreen Runtime is installed. If running a portable version, verify that `WebView2Loader.dll` is present in the `bin/` directory adjacent to the application executable.
+
+---
+
+## Policies & Community
+
+### How do rights holders request removal of a source?
+Rights holders can submit source removal requests directly to our team. We promptly review and disable scrapers for requested domains. See our [DMCA Policy](/misc/project/dmca) for contact instructions.
+
+### How can I contribute to Vyla?
+We welcome code contributions, documentation improvements, and bug reports on [GitLab](https://gitlab.com/vyla-entertainment). Check out the [Contributing Guide](/sdk/vyla-sdk/contributing) to learn how to author and submit new provider scrapers.

resources/glossary.md

@@ -0,0 +1,86 @@
+# Ecosystem Glossary
+
+<p class="page-description">Authoritative definitions for technical terms, protocols, and architectural concepts across the Vyla ecosystem.</p>
+
+## A
+
+### AES-128 Encryption
+A symmetric key cipher frequently used in HLS streaming. The playlist references an encryption key endpoint (`#EXT-X-KEY:METHOD=AES-128,URI="..."`). Stream API proxies and rewrites these key URIs to ensure playback permissions and headers match the viewer's session.
+
+---
+
+## C
+
+### Cluster Primary & Worker
+Node.js architecture utilized by Stream API. The **Primary** master process allocates CPU affinity, coordinates IPC messaging, and supervises workers. **Workers** handle inbound HTTP client requests, parse streams, and query upstream hosts concurrently.
+
+---
+
+## E
+
+### ExoPlayer (Media3)
+Google's high-performance, customizable media player library for Android. Used by Vyla TV to render adaptive 4K/HDR HLS streams with hardware acceleration.
+
+---
+
+## F
+
+### Fallback Priority Queue
+A client-side architecture where candidate video streams emitted by Stream API are queued in memory. If the currently playing stream crashes or drops offline, the player immediately mounts the next candidate in the queue without interrupting the viewer.
+
+---
+
+## H
+
+### HLS (HTTP Live Streaming)
+An adaptive bitrate streaming communications protocol developed by Apple. Video is divided into a sequence of small HTTP-based file chunks (.ts or .m4s) indexed by a master `.m3u8` playlist.
+
+### HLS.js
+A JavaScript library that implements an HLS client using HTML5 video and Media Source Extensions (MSE). Used by custom web players to play Vyla HLS streams in browsers lacking native HLS support.
+
+---
+
+## J
+
+### Jitter Staggering
+A randomized delay (0 to 800ms) injected before scraper network requests fire. Prevents dozens of concurrent scrapers from triggering upstream Cloudflare or DDoS rate limits at the same millisecond.
+
+---
+
+## M
+
+### M3U8 Playlist
+A UTF-8 encoded text file representing an HLS playlist. Stream API intercepts and rewrites master and media M3U8 playlists so that chunk and encryption key URLs route through the proxy with valid CORS headers.
+
+---
+
+## P
+
+### Progressive Streaming
+A delivery pattern where metadata and media candidates are emitted to client players in real time over Server-Sent Events (SSE) as each scraper finishes, rather than waiting for all scrapers to complete.
+
+### Provider / Scraper
+A self-contained JavaScript module in `@vyla-entertainment/sdk` (`src/sources/`) that queries an upstream video host, extracts stream URLs, and formats headers.
+
+---
+
+## S
+
+### Server-Sent Events (SSE)
+A standardized HTML5 server-to-client streaming technology over a persistent HTTP connection (`Content-Type: text/event-stream`). Used by Stream API `/movie` and `/tv` routes to emit `meta`, `source`, and `done` events.
+
+### Sidecar Process
+An architectural pattern used in Vyla Home where a secondary runtime process (Node.js) is bundled adjacent to the primary native application shell (Tauri Rust binary) to manage local services.
+
+---
+
+## T
+
+### Tauri v2
+A framework for building tiny, ultra-fast native applications for all major desktop and mobile platforms using web frontends and Rust backends. Vyla Home and Vyla Go are built on Tauri v2.
+
+### TMDB (The Movie Database)
+A community-built movie and television database. Vyla standardizes all movie and TV series queries on numeric TMDB IDs.
+
+### TS Segment De-Masking (120-Byte Stripping)
+A de-obfuscation routine implemented in Stream API. Certain CDNs disguise video chunks by prepending a 120-byte fake image header (PNG, JPEG, TikTok CDN). Stream API removes these 120 bytes, restoring valid MPEG-TS video for media players.

resources/troubleshooting.md

@@ -0,0 +1,95 @@
+# Troubleshooting & Diagnostics
+
+<p class="page-description">Step-by-step diagnostic workflows and resolutions for common issues across Vyla Home, Vyla Go, Vyla TV, Stream API, and the SDK.</p>
+
+## Desktop: Vyla Home
+
+### 1. Windows: "WebView2 runtime initialization error"
+- **Cause**: The Microsoft Edge WebView2 runtime is missing or corrupted on the host machine.
+- **Resolution**:
+  1. Download and run the Evergreen Bootstrapper installer from [Microsoft's WebView2 page](https://developer.microsoft.com/en-us/microsoft-edge/webview2/).
+  2. If using portable builds, verify that `WebView2Loader.dll` exists in `bin\WebView2Loader.dll`.
+
+### 2. Windows: "OS Error 32: File in use by another process"
+- **Cause**: A previous Tauri, Node.js, or Cargo process is still running in the background and holding a file lock.
+- **Resolution**: Terminate any dangling processes in PowerShell:
+  
+```powershell
+  Stop-Process -Name "vyla-home", "node", "cargo" -Force -ErrorAction SilentlyContinue
+```
+
+### 3. Linux: Build Fails with Missing WebKit or AppIndicator
+- **Cause**: Linux requires native GTK3 and WebKit development headers.
+- **Resolution**: Install required system packages:
+  - **Fedora**: `sudo dnf install webkit2gtk4.1-devel libappindicator-gtk3-devel librsvg2-devel`
+  - **Ubuntu/Debian**: `sudo apt install libwebkit2gtk-4.1-dev libayatana-appindicator3-dev librsvg2-dev`
+
+### 4. Inspecting Node Sidecar Logs
+If Vyla Home launches but media fails to resolve:
+- **Windows**: Open `%APPDATA%\vyla-home\vyla-home-files\logs\node-debug.log`
+- **macOS**: Open `~/Library/Application Support/vyla-home/vyla-home-files/logs/node-debug.log`
+
+---
+
+## Mobile: Vyla Go
+
+### 1. Emulator DNS Timeouts when Connecting to GitLab
+- **Cause**: Android emulators occasionally fail to resolve remote domains when private DNS is active.
+- **Resolution**: Disable private DNS mode via ADB:
+  
+```powershell
+  & "$env:LOCALAPPDATA\Android\Sdk\platform-tools\adb.exe" shell settings put global private_dns_mode off
+```
+
+### 2. Dumping Crash Logs from Device
+To capture a full logcat dump of crash traces:
+```powershell
+& "$env:LOCALAPPDATA\Android\Sdk\platform-tools\adb.exe" logcat -d | Select-String "VylaGo|AndroidRuntime|FATAL"
+```
+
+### 3. Resetting Cached App Data
+```powershell
+& "$env:LOCALAPPDATA\Android\Sdk\platform-tools\adb.exe" shell am force-stop com.vyla.go
+& "$env:LOCALAPPDATA\Android\Sdk\platform-tools\adb.exe" shell pm clear com.vyla.go
+```
+
+---
+
+## Living Room: Vyla TV
+
+### 1. Build Fails during `assembleDebug`
+- **Cause**: Incompatible Java Development Kit (JDK) or missing Android TV SDK platform.
+- **Resolution**:
+  1. Ensure JDK 17 or JDK 21 is active: `java -version`.
+  2. Ensure Android TV API level 26 or higher is installed via Android Studio SDK Manager.
+
+### 2. Video Stalls or Fails to Play on Fire TV
+- **Cause**: Hardware codec mismatch or network buffer underrun.
+- **Resolution**:
+  1. Inside the player, press the Down button on your D-pad to open the stream switcher.
+  2. Select an alternative provider (e.g. switch from an adaptive HLS stream to a direct 1080p stream).
+
+---
+
+## Backend: Stream API
+
+### 1. SSE Events Delayed or Arriving All at Once
+- **Cause**: The reverse proxy (Nginx, Cloudflare, Caddy) is buffering chunked responses.
+- **Resolution**:
+  1. In Nginx, ensure `proxy_buffering off;` and `proxy_cache off;` are configured in your `location` block.
+  2. In Cloudflare, ensure response buffering is disabled for your streaming subdomain.
+
+### 2. `EADDRINUSE: address already in use :::7860`
+- **Cause**: A previous Stream API instance is already bound to port 7860.
+- **Resolution**:
+  
+```bash
+  # Find PID on Linux
+  lsof -i :7860
+  # Kill hung process
+  kill -9 <PID>
+```
+
+### 3. TMDB API Warnings in Console
+- **Warning**: `Warning: TMDB_API_KEY not set, imdb-required sources will be unavailable`
+- **Resolution**: Add `TMDB_API_KEY=your_key` to your `.env` file and restart the service.