From e093a8afaeb62c843eb68a736ce2b7be124b439e Mon Sep 17 00:00:00 2001
From: KoalaDev <6156589+Shik3i@users.noreply.github.com>
Date: Mon, 6 Jul 2026 17:31:24 +0200
Subject: [PATCH] docs: refresh onboarding and examples

---
 README.md                                 |  24 +++--
 docs/AI_INIT.md                           |  38 ++++---
 docs/README.md                            |  10 ++
 docs/SYNC_GUIDE.md                        |  12 ++-
 examples/docker-compose.caddy.example.yml |   1 +
 examples/docker-compose.ip.example.yml    |   1 +
 extension/README.md                       | 118 ++++++++++++++++------
 extension/content.js                      |   4 +-
 extension/episode-utils.js                |   2 +-
 scripts/README.md                         |  96 ++++++++++++++----
 scripts/build-extension.cjs               |  49 ++++-----
 server/.env.example                       |   5 +
 server/README.md                          |  27 +++++
 shared/README.md                          |  82 +++++++++++----
 website/README.md                         | 109 ++++++++++++--------
 15 files changed, 407 insertions(+), 171 deletions(-)

diff --git a/README.md b/README.md
index 2bc692f..32ccf4a 100644
--- a/README.md
+++ b/README.md
@@ -29,6 +29,7 @@
 
 - **Global Synchronization**: Synchronize Play, Pause, and Seeking on any website with a `<video>` tag.
 - **Episode Auto-Sync**: Perfectly sync series binges. All peers wait until everyone has loaded the next episode before starting together.
+- **Host Control & Co-Hosts**: Room hosts can lock playback control to trusted controllers while guests keep watching in sync.
 - **Smart Matching**: Automatically highlights tabs containing matching video titles.
 - **Dual Heartbeat Architecture**: Robust session tracking that prevents ghost rooms and stale connections.
 - **Efficient Relay**: Minimal overhead WebSocket message forwarding.
@@ -58,7 +59,7 @@ The easiest and safest way to install KoalaSync is directly through the official
 
 ### 🌐 Localization & Translations
 
-Both the official KoalaSync website and the **v2.0 Browser Extension** feature full dynamic localization:
+Both the official KoalaSync website and the browser extension feature dynamic localization:
 - **Available Languages**: Support is included for 15 languages: English (`en`), German (`de`), French (`fr`), Spanish (`es`), Portuguese (Brazil) (`pt-BR`), Russian (`ru`), Italian (`it`), Polish (`pl`), Turkish (`tr`), Dutch (`nl`), Japanese (`ja`), Korean (`ko`), Chinese (Simplified) (`zh`), Ukrainian (`uk`), and European Portuguese (`pt`).
 - **Real-Time Extension Localization**: Inside the extension Settings panel, users can swap languages instantly. The entire interface, notifications, Empty States, and onboarding guides re-translate dynamically in real-time.
 - **Contributing**: We welcome community translations for both the website and the extension! Please refer directly to the [TRANSLATION.md](docs/TRANSLATION.md) guide for step-by-step instructions on how to audit, refine, or add new languages.
@@ -86,16 +87,20 @@ npm run build:extension
 The compiled artifacts will be available in the `dist/` directory.
 
 #### For Self-Hosting (Docker)
-Deploy your own private relay server using our official image:
+For local development or a simple private relay, use the root Compose file:
 ```bash
-# Pull the latest image
-docker pull ghcr.io/shik3i/koalasync:latest
-
-# Or use our example compose file
-cp examples/docker-compose.caddy.example.yml docker-compose.yml
-docker-compose up -d
+cp server/.env.example server/.env
+# Edit server/.env and set SERVER_SALT to a unique random value:
+# openssl rand -base64 32
+docker compose up -d --build
 ```
-The server will be available at `ws://localhost:3000`. See [Docker network compose](examples/docker-compose.caddy.example.yml) or [Static IP compose](examples/docker-compose.ip.example.yml) for ready-to-use Docker Compose files.
+The local relay will be available at `ws://localhost:3000`.
+
+For production, use the official image and one of the ready-to-edit examples:
+- [Docker network compose](examples/docker-compose.caddy.example.yml): for a Caddy or reverse-proxy network. This file does not publish `localhost:3000`; Caddy routes traffic to the container.
+- [Static IP compose](examples/docker-compose.ip.example.yml): for a pre-existing Docker network with a fixed container IP.
+
+In every real deployment, set a unique `SERVER_SALT`. Without it the relay still starts, but it warns that room-password hashes are using the public fallback salt from the repository.
 
 To connect your extension to a self-hosted server, open the popup → **Room** tab → select **Custom Server** → enter your server's WebSocket URL (e.g., `ws://localhost:3000`).
 
@@ -134,6 +139,7 @@ gh attestation verify dist/koalasync-chrome.zip \
 - **[PROTOCOL.md](docs/PROTOCOL.md)**: WebSocket protocol specification and event reference.
 - **[ROADMAP.md](docs/ROADMAP.md)**: Planned features, backlog, and rejected ideas.
 - **[SECURITY.md](SECURITY.md)**: Disclosure policy and security practices.
+- **[AI_INIT.md](docs/AI_INIT.md)**: Maintainer and agent onboarding notes for safe code changes.
 - **[Caddyfile.example](examples/Caddyfile.example)**: Production Caddy configuration for website and relay.
 
 ---
diff --git a/docs/AI_INIT.md b/docs/AI_INIT.md
index b99280c..8a6674c 100644
--- a/docs/AI_INIT.md
+++ b/docs/AI_INIT.md
@@ -7,7 +7,7 @@ Welcome to the KoalaSync project. This file is the primary entry point for any d
 > - **Font Stack**: Use a modern system font stack (e.g., -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif) to maintain a premium look without external dependencies. Prohibit the use of `@import` or `<link>` for external font services.
 > 
 > [!IMPORTANT]
-> **Caveman Communication Protocol**: To conserve context window and tokens, AI agents MUST communicate with the user in **caveman language** (broken, short German/English hybrid caveman style, e.g., "Ich Antigravity. Ich machen Git pull. Code fertig.") at all times. This rule is highly strict and must NOT be broken under any circumstances unless the user explicitly requests to drop it.
+> **Communication Standard**: Be concise, concrete, and professional. Match the user's language when practical, explain risky changes before making them, and report exactly what was changed and verified. Do not use joke protocols or intentionally broken language in contributor-facing work.
 
 ---
 
@@ -23,26 +23,28 @@ KoalaSync is a specialized tool for **synchronized video playback** across multi
 - `website/`: **Landing Page** & Invitation Bridge (Marketing, Tutorials, and Downloads).
   - **`build.cjs`**: Zero-dependency static site compiler. Translates `template.html` + `locales/*.json` → `www/`. Also minifies CSS/JS automatically.
   - **`www/` is auto-generated**: Never edit files in `www/` directly. Always edit source files (`template.html`, `style.css`, `app.js`, `lang-init.js`, `locales/*.json`) and run `node website/build.cjs` to regenerate. CSS/JS are output as `.min.*` files — a built-in cleanup step removes stale artifacts on each build.
-- `shared/`: **Single Source of Truth** for protocol constants and event names.
+- `shared/`: **Single Source of Truth** for protocol constants, event names, blacklist data, and generated usernames.
 - `scripts/`: Development utilities (e.g., `build-extension.cjs`).
 - `docker-compose.yml`: Root-level orchestration for the relay server.
 
 > [!IMPORTANT]
-> **Single Source of Truth**: `shared/constants.js` and `shared/blacklist.js` are the master files. They must be synchronized to the `extension/shared/` directory using `node scripts/build-extension.cjs`. 
+> **Single Source of Truth**: `shared/constants.js`, `shared/blacklist.js`, and `shared/names.js` are the master shared files. They must be synchronized to the `extension/shared/` directory using `node scripts/build-extension.cjs`.
 > - **Extension Modules** (`background.js`, `popup.js`) import directly from `./shared/constants.js`.
 > - **Content Scripts** (`content.js`) use a **marker-injected synchronous copy** of the constants. The build script automatically replaces the marked blocks — no manual mirroring needed.
 
 ## 3. Mandatory Reading
 Before touching any code, you MUST read the following documents in order:
-1. [ARCHITECTURE.md](ARCHITECTURE.md) – Detailed communication flows, Dual Heartbeat, and two-phase sync protocol.
-2. [extension/README.md](../extension/README.md) – Extension components, tab structure, and loading process.
-3. [SYNC_GUIDE.md](SYNC_GUIDE.md) – Protocol constants and synchronization requirements.
+1. [../README.md](../README.md) – User, developer, and self-hosting overview.
+2. [README.md](README.md) – Documentation map by role.
+3. [ARCHITECTURE.md](ARCHITECTURE.md) – Detailed communication flows, Dual Heartbeat, and two-phase sync protocol.
+4. [../extension/README.md](../extension/README.md) – Extension components, tab structure, and loading process.
+5. [SYNC_GUIDE.md](SYNC_GUIDE.md) – Protocol constants and synchronization requirements.
 
 ## 4. The "Vanilla JS Mirror" Pattern
 To avoid boot-time race conditions in Manifest V3 without a bundler, the following architectural trade-off is enforced:
 - **Synchronous Execution**: `content.js` MUST execute synchronously to catch early media events. 
-- **Automated Injection**: The build script (`node scripts/build-extension.cjs`) automatically injects `EVENTS` and `HEARTBEAT_INTERVAL` into `content.js` using marker-based replacement (see `../scripts/README.md` for marker details).
-- **Maintenance**: After modifying `shared/constants.js`, simply run the build script. No manual mirroring is required.
+- **Automated Injection**: The build script (`node scripts/build-extension.cjs`) automatically injects `EVENTS`, `HEARTBEAT_INTERVAL`, and episode utility functions into `content.js` using marker-based replacement (see `../scripts/README.md` for marker details).
+- **Maintenance**: After modifying any root `shared/` file, run the build script. No manual mirroring is required.
 
 ## 5. File Responsibility Map
 
@@ -52,13 +54,16 @@ To avoid boot-time race conditions in Manifest V3 without a bundler, the followi
 | `content.js` | Video element detection, media control, event origin detection (loop prevention) |
 | `popup.js` | UI rendering, user input handling, peer display, invitation link generation |
 | `bridge.js` | Landing page ↔ extension communication for invitation join flow |
+| `episode-utils.js` | Shared episode parsing, imported by background and injected into content |
+| `title-privacy.js` | Tab/media title privacy normalization and sanitization |
+| `page-api-seek-overrides.js` | Page-level seek bridge for site-specific player APIs |
 | `server/index.js` | Room management, message relay, rate limiting, authentication, peer lifecycle |
 
 ## 6. Design Guidelines
 The popup UI follows a strict design system. Do not modify these variables or the layout structure without explicit approval.
 - **Font**: System font stack. **MANDATORY**: No external CDNs or Google Fonts to ensure 100% privacy.
 - **Popup Width**: Fixed at `320px`.
-- **Tab Structure**: Must maintain the **Room**, **Sync**, **Settings**, and **Dev** tabs.
+- **Tab Structure**: Must maintain the visible **Room**, **Sync**, **Settings**, and **Status** tabs. The hidden **Dev** tab is available only for developer diagnostics.
 - **CSS Variables**:
   | Variable | Value | Purpose |
   | :--- | :--- | :--- |
@@ -72,6 +77,7 @@ The popup UI follows a strict design system. Do not modify these variables or th
 The following features are critical and must not be removed or fundamentally altered:
 - **Two-Phase Force Sync**: The `Prepare` → `ACK` → `Execute` flow ensures all peers are buffered before playback resumes.
 - **Episode Auto-Sync**: Ensures series binges stay perfectly synced. A lobby initiates during title transitions, freezing peers until everyone is ready.
+- **Host Control Mode**: In `host-only` rooms, only the host and promoted controllers may initiate room-moving playback events. Both client-side UX and server-side gates must remain intact.
 - **Dual Heartbeat**: 
     - **Background Heartbeat (1m)**: Ensures session persistence even without a video element.
     - **Content Heartbeat (15s)**: Transmits current video metadata (time, title).
@@ -80,8 +86,9 @@ The following features are critical and must not be removed or fundamentally alt
 - **Platform Specifics**: Specialized click-logic for YouTube (`.ytp-play-button`) and Twitch.
 - **pollSeekReady()**: Polling mechanism that checks `video.readyState` before acknowledging sync.
 - **SW Keep-alive**: Use of `chrome.alarms` to prevent the Manifest V3 Service Worker from suspending.
-- **Diagnostics**: The "Dev" tab provides real-time access to the underlying `<video>` state for troubleshooting.
+- **Diagnostics**: The visible **Status** tab provides real-time access to connection state, ping, logs, history, and underlying `<video>` state for troubleshooting.
 - **Persistence**: `peerId` and `username` must be stored to remain stable across sessions.
+- **Title Privacy**: Do not accidentally reintroduce tab/media title sharing when users disabled or reduced it.
 - **Room ID Format**: Room IDs are restricted to `[a-zA-Z0-9-]` only (alphanumeric + hyphens). This is enforced server-side.
 
 ## 8. Technical Constraints
@@ -89,7 +96,8 @@ The following features are critical and must not be removed or fundamentally alt
 - **Manual Protocol**: `background.js` implements a subset of the Socket.IO wire protocol natively.
 - **Server Transport**: Restricted to `websocket` only. Polling is disabled.
 - **Docker Context**: The Docker build must run from the **Repo Root**.
-- **Manifest Settings**: `run_at` must remain `document_idle`, and `all_frames` must remain `false`.
+- **Content Script Scope**: `bridge.js` is the only static content script in the manifest and runs on `https://sync.koalastuff.net/*` at `document_start`. Video control scripts are injected only into the selected tab via `chrome.scripting`; do not add broad persistent video content-script matches.
+- **Self-Hosting Salt**: Production/self-hosted relay examples must include a unique `SERVER_SALT` so room-password hashes are not derived with the public fallback salt.
 - **Strict Backward & Forward Compatibility (Store Delay Rule)**: Browser extensions are distributed through stores (e.g., Chrome Web Store, Firefox Add-ons) which can take up to 2 weeks to approve updates. Therefore, the server MUST NOT reject older extension clients unless a critical protocol version bump is explicitly authorized, and new extension versions MUST remain fully operational when connected to older servers (e.g., by silently falling back if a new feature is not supported). This is a core architectural requirement.
 
 ## 9. Security & Deployment
@@ -117,7 +125,7 @@ Before starting any task, committing, or pushing, you **MUST** run `git pull --r
 > **AI AGENTS MUST FOLLOW THIS EXACT SEQUENCE WHEN RELEASING A NEW VERSION OR TAGGING.**
 > 
 > **🚫 NO MANUAL VERSION BUMPING**: You MUST **NEVER** manually modify the version strings in `package.json`, `extension/manifest.base.json`, or `website/version.json`. The GitHub Actions CI pipeline automatically extracts the version from the git tag (e.g. `v2.0.5` -> `2.0.5`), injects it into all target files, and commits the updates back to `main` with `[skip ci]`. Manual bumps will cause merge conflicts and build failures.
-> - **Website Versioning**: **NEVER** manually modify the version fallback strings in `website/index.html`. The website dynamically fetches the latest version and release date from `website/version.json` at runtime using `website/app.js`. Manual bumps in the HTML file are completely redundant and should be avoided.
+> - **Website Versioning**: **NEVER** manually modify generated version strings in `website/www/`. The website build injects version data from `website/version.json` into generated output.
 1. **MANDATORY SYNTAX & LINT CHECKS**: Before staging, committing, or pushing any changes, you **MUST** run both checks on every modified JavaScript file:
    - **Syntax Validation**: Run `node -c` on every single modified JavaScript file (e.g., `node -c extension/background.js` and `node -c extension/content.js`). **NEVER** commit or push code that fails this check.
    - **ESLint Validation**: Run `npm run lint` (or `npx eslint .`). The output must show **zero errors and zero warnings**. ESLint is configured to catch undefined variables, unused vars, unreachable code, and other semantic issues. **NEVER** commit or push code that fails this check.
@@ -143,16 +151,16 @@ Before starting any task, committing, or pushing, you **MUST** run `git pull --r
 ### Making Website Changes
 1. Edit source files in `website/` (`template.html`, `style.css`, `app.js`, `lang-init.js`, or `locales/*.json`).
 2. Run the compiler: `node website/build.cjs`. This generates the multilingual pages in `www/` and minifies CSS/JS.
-3. Verify the output: `node --check website/www/app.js && node --check website/www/lang-init.js`.
+3. Verify the output: `node --check website/www/app.min.js && node --check website/www/lang-init.min.js`.
 4. Test locally: `npx serve website/www` or `python3 -m http.server 8080 -d website/www`.
 5. Commit both source changes and the updated `www/` output.
 
 ### Testing Locally
 1. Run the build script: `node scripts/build-extension.cjs`.
 2. Load `dist/chrome/` as an "Unpacked Extension" in Chrome (or `dist/firefox/` in Firefox).
-3. Start the server from the root: `docker-compose up --build`.
+3. Start the server from the root: `docker compose up --build`.
 4. Use **different browser profiles** or vendors to test multi-peer logic.
-5. Use the **Dev tab** to verify real-time video element metadata.
+5. Use the **Status tab** to verify real-time connection state, logs, and video element metadata.
 
 ### Locking Old Versions
 1. Update `MIN_VERSION` in the server's `.env` file to the minimum acceptable version.
diff --git a/docs/README.md b/docs/README.md
index 47d10ab..4532f9c 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -2,11 +2,20 @@
 
 This directory contains deep-dives into the KoalaSync protocol, architecture, roadmap, and operational guidelines.
 
+## Start Here by Role
+
+- **Users and reviewers**: Start with [HOW_IT_WORKS.md](HOW_IT_WORKS.md), then [PRIVACY.md](PRIVACY.md) and [TESTED_SERVICES.md](TESTED_SERVICES.md).
+- **Self-hosters**: Start with the root [README.md](../README.md), then [devops.md](devops.md), [PROTOCOL.md](PROTOCOL.md), and the examples in `../examples/`.
+- **Contributors**: Start with [../CONTRIBUTING.md](../CONTRIBUTING.md), then [ARCHITECTURE.md](ARCHITECTURE.md), [SYNC_GUIDE.md](SYNC_GUIDE.md), and the README for the subdirectory you are editing.
+- **AI agents**: Start with [AI_INIT.md](AI_INIT.md), then read the relevant subdirectory README before changing files.
+- **Security reviewers**: Start with [SECURITY.md](../SECURITY.md), [KNOWN_LIMITATIONS.md](KNOWN_LIMITATIONS.md), [PRIVACY.md](PRIVACY.md), and [PROTOCOL.md](PROTOCOL.md).
+
 ## 🏗️ Core Architecture & Design
 
 - **[ARCHITECTURE.md](ARCHITECTURE.md)**: Overview of the communication flows, Dual Heartbeat architecture, and synchronization logic.
 - **[HOW_IT_WORKS.md](HOW_IT_WORKS.md)**: Step-by-step walkthrough of every user flow, from room creation to synchronized playback. Ideal for store reviewers and manual testers.
 - **[host-control-mode.md](host-control-mode.md)**: Design, requirements, and edge cases of the Host Control feature.
+- **[AI_INIT.md](AI_INIT.md)**: Maintainer and AI-agent onboarding: non-negotiables, workflow order, and safety checks.
 
 ## 📡 Protocol & Synchronization
 
@@ -17,6 +26,7 @@ This directory contains deep-dives into the KoalaSync protocol, architecture, ro
 
 - **[TESTED_SERVICES.md](TESTED_SERVICES.md)**: Status of compatibility with major streaming services and contribution guidelines for testing new platforms.
 - **[KNOWN_LIMITATIONS.md](KNOWN_LIMITATIONS.md)**: Threat model and accepted design limitations (NOFIX entries) for security audits.
+- **[PRIVACY.md](PRIVACY.md)**: Privacy model and data-handling policy for users, reviewers, and contributors.
 - **[ROADMAP.md](ROADMAP.md)**: Planned features, backlog items, and rejected proposals.
 - **[TRANSLATION.md](TRANSLATION.md)**: Guide for native speakers to contribute and audit dynamic extension/website translations.
 
diff --git a/docs/SYNC_GUIDE.md b/docs/SYNC_GUIDE.md
index 73dcc01..df0f69b 100644
--- a/docs/SYNC_GUIDE.md
+++ b/docs/SYNC_GUIDE.md
@@ -10,8 +10,9 @@ You MUST run the build script in any of the following scenarios:
 1. **After a fresh `git clone` or `git pull`** (as the synced files are ignored by git).
 2. **After modifying** `shared/constants.js`.
 3. **After modifying** `shared/blacklist.js`.
-4. **Before committing** changes to the repository if any protocol-related files were touched.
-5. **Before deploying** the server or releasing the extension.
+4. **After modifying** `shared/names.js`.
+5. **Before committing** changes to the repository if any shared protocol or extension-mirrored files were touched.
+6. **Before deploying** the server or releasing the extension.
 
 ## How to sync
 
@@ -24,10 +25,11 @@ npm run build:extension
 
 ## What does it do?
 The build script performs the following actions:
-1. Synchronizes protocol constants by copying `shared/constants.js`, `shared/blacklist.js`, and `shared/README.md` into `extension/shared/`.
+1. Synchronizes shared files by copying `shared/constants.js`, `shared/blacklist.js`, `shared/names.js`, and `shared/README.md` into `extension/shared/`.
 2. Injects `EVENTS`, `HEARTBEAT_INTERVAL`, and `episode-utils.js` functions (`extractEpisodeId`, `sameEpisode`) into `content.js` via marker-based replacement.
-3. Compiles browser-specific manifest files.
-4. Packages the final ready-to-publish extension artifacts for Chrome and Firefox into the `dist/` directory.
+3. Injects browser-specific uninstall URL constants into `background.js` and a build timestamp into `popup.html`.
+4. Compiles browser-specific manifest files.
+5. Packages the final ready-to-publish extension artifacts for Chrome and Firefox into the `dist/` directory.
 
 ## Protocol Versioning
 The system enforces a strict `protocolVersion` check during the `JOIN_ROOM` handshake. 
diff --git a/examples/docker-compose.caddy.example.yml b/examples/docker-compose.caddy.example.yml
index 89b4eac..064f161 100644
--- a/examples/docker-compose.caddy.example.yml
+++ b/examples/docker-compose.caddy.example.yml
@@ -9,6 +9,7 @@ services:
       - MIN_VERSION=1.0.0                                                                  # Minimum client version allowed to connect
       - MAX_ROOMS=100                                                                      # Maximum number of rooms that can exist
       - MAX_PEERS_PER_ROOM=25                                                              # Maximum number of peers allowed per room
+      - SERVER_SALT=CHANGE_ME_GENERATE_WITH_OPENSSL_RAND_BASE64_32                         # Required: unique random salt for room-password hashes
       - ADMIN_METRICS_TOKEN=                                                               # Optional: 32+ char random token for aggregate-only /health metrics
     pids_limit: 2048                                                                       # Limits the container to 2048 process IDs for safety
     networks:                                                                              # Attaches the service to the networks listed below
diff --git a/examples/docker-compose.ip.example.yml b/examples/docker-compose.ip.example.yml
index 0e787aa..00f2e14 100644
--- a/examples/docker-compose.ip.example.yml
+++ b/examples/docker-compose.ip.example.yml
@@ -11,6 +11,7 @@ services:
       - MIN_VERSION=1.0.0                                                                  # Minimum client version allowed to connect
       - MAX_ROOMS=100                                                                      # Maximum number of rooms that can exist
       - MAX_PEERS_PER_ROOM=25                                                              # Maximum number of peers allowed per room
+      - SERVER_SALT=CHANGE_ME_GENERATE_WITH_OPENSSL_RAND_BASE64_32                         # Required: unique random salt for room-password hashes
       - ADMIN_METRICS_TOKEN=                                                               # Optional: 32+ char random token for aggregate-only /health metrics
     pids_limit: 2048                                                                       # Limits the container to 2048 process IDs for safety
     networks:                                                                              # Attaches the service to the networks listed below
diff --git a/extension/README.md b/extension/README.md
index 8e9c68b..1e0412d 100644
--- a/extension/README.md
+++ b/extension/README.md
@@ -1,52 +1,106 @@
 # KoalaSync Browser Extension
 
-A Manifest V3 Browser Extension (Chrome & Firefox) for synchronized video playback across any website.
+This directory contains the Manifest V3 browser extension for Chrome and Firefox. It owns the popup UI, background service worker, content-script video control, invitation bridge, audio processing, and all browser-local settings.
+
+## Where You Are
+
+- `manifest.base.json` is the source manifest. The build script creates browser-specific `manifest.json` files in `dist/chrome/` and `dist/firefox/`.
+- `background.js` is the long-lived coordinator: WebSocket client, room state, host-control authority, heartbeat, reconnects, tab selection, and content-script injection.
+- `content.js` runs in the selected video tab. It detects video state, applies remote play/pause/seek, handles episode transitions, and applies local audio processing.
+- `popup.html` and `popup.js` implement the visible extension UI.
+- `extension/shared/` is generated by `npm run build:extension` from the root `shared/` directory. Do not edit it directly.
 
 ## Key Features
-- **Manifest V3**: Optimized Service Worker architecture with session persistence.
-- **Pure Vanilla JS**: No external dependencies or heavy libraries.
-- **Smart Peer IDs**: Hexadecimal IDs combined with customizable Usernames for easy identification.
-- **On-Demand Connection**: The service worker only maintains a WebSocket connection while you're in a room. No persistent background connections — privacy-first architecture. Based on `connectIntent` flag that gates all reconnect attempts.
-- **Live Diagnostics**: Built-in "Dev" tab for real-time video state debugging (ReadyState, CurrentTime, etc.).
-- **Dynamic i18n (Multi-Language)**: Fully localized in 13 languages (`en`, `de`, `fr`, `es`, `it`, `pl`, `tr`, `nl`, `ja`, `ko`, `pt-BR`, `pt`, `ru`) with auto-detected fallback and dynamic on-the-fly language selectors.
+
+- **Manifest V3**: Service-worker architecture with session persistence and explicit keep-alive handling.
+- **Pure Vanilla JS**: No extension runtime dependencies and no bundler inside `extension/`.
+- **On-Demand Connection**: The service worker connects only while the user intends to be in a room.
+- **Host Control & Co-Hosts**: Hosts can switch a room into `host-only` mode and grant controller rights to trusted peers.
+- **Episode Auto-Sync**: Title/episode changes can open a lobby so peers resume together once everyone is ready.
+- **Smart Matching & Title Privacy**: Matching video tabs are highlighted, while tab/media title sharing can be reduced or disabled.
+- **Audio Processing**: Optional local compressor settings live in the dedicated audio options page.
+- **Status Diagnostics**: The Status tab exposes connection state, ping, video debug data, action history, and copyable logs.
+- **Dynamic i18n**: 15 languages are supported: `en`, `de`, `fr`, `es`, `it`, `nl`, `pl`, `pt`, `pt-BR`, `tr`, `ru`, `ja`, `ko`, `zh`, and `uk`.
 
 ## Tab Overview
-1. **Room**: Manage connections, view active peers, and share invitation links.
-2. **Sync**: Control video playback (Play/Pause/Force Sync) and view recent activity.
-3. **Settings**: Customize your Username, toggle domain-based Noise Filtering, and switch the App Language.
-4. **Dev**: Monitor connection status and view real-time video element metadata for debugging.
+
+1. **Room**: Select official/custom server, create or join rooms, view peers, share invite links, and manage Host Control when supported by the relay.
+2. **Sync**: Select the video tab, send play/pause/seek/force-sync actions, and view episode lobby state.
+3. **Settings**: Configure username, title sharing, noise filtering, auto episode sync, notifications, language, and audio options.
+4. **Status**: Inspect connection state, latency, video debug info, history, and logs for bug reports.
+5. **Dev**: Hidden developer-only controls shown for the `KoalaDev` username.
 
 ## Privacy & Permissions
-KoalaSync requires `<all_urls>` permission to detect and interact with video elements (`<video>`) on websites.
-- **No Browsing History**: We do not track or store your browsing history.
-- **State Management**: Sensitive data (Room Passwords) is stored locally using `chrome.storage`.
-- **Zero Telemetry**: No analytics or external tracking scripts.
-- **Zero Runtime Dependencies**: The extension is built with pure Vanilla JS and contains no external libraries or tracking scripts, ensuring performance and privacy.
+
+KoalaSync requires `<all_urls>` host permission so it can detect and control `<video>` elements on arbitrary sites.
+
+- No browsing history is collected or uploaded.
+- Room credentials and user settings are stored locally with `chrome.storage`.
+- No analytics, external scripts, external fonts, or tracking libraries are used by the extension.
+- Audio processing is local to the selected tab.
+- Title privacy controls decide whether tab/media titles are shared with room peers.
 
 ## Installation
-1. **Prepare Extension**: From the repository root, run:
-   ```bash
-   npm run build:extension
-   ```
-2. Open Chrome and go to `chrome://extensions/`.
-3. Enable **Developer mode** (top right).
-4. Click **Load unpacked** and select the `dist/chrome` folder.
+
+From the repository root:
+```bash
+npm install
+npm run build:extension
+```
+
+Then load the generated bundle:
+
+- Chrome/Chromium: open `chrome://extensions/`, enable Developer Mode, and load `dist/chrome`.
+- Firefox: open `about:debugging`, choose **This Firefox**, and load `dist/firefox/manifest.json`.
 
 ## Development
-If you modify `shared/constants.js`, you must synchronize the changes by running the build script from the root:
+
+Run the build whenever shared protocol files or extension packaging inputs change:
 ```bash
 npm run build:extension
 ```
-This ensures that the `extension/shared` folder is updated with the latest protocol constants.
+
+The build copies `shared/constants.js`, `shared/blacklist.js`, `shared/names.js`, and `shared/README.md` into `extension/shared/`, injects synchronous constants into `content.js`, generates browser manifests, and creates zip artifacts in `dist/`.
+
+Useful focused checks from the repository root:
+```bash
+node -c extension/background.js
+node -c extension/content.js
+node -c extension/popup.js
+node scripts/test-episode-utils.mjs
+node scripts/test-title-privacy.mjs
+node scripts/test-audio-settings.mjs
+node scripts/test-locales.cjs
+```
+
+For the full suite, run:
+```bash
+npm run verify
+```
+
+## Do Not Break
+
+- Keep `content.js` synchronous and IIFE-based; it cannot import ES modules directly.
+- Keep the injection markers used by `scripts/build-extension.cjs`.
+- Keep protocol names in `shared/constants.js` as the source of truth.
+- Keep extension runtime dependencies at zero unless the project explicitly decides to introduce a bundler.
+- Keep all extension assets self-hosted.
 
 ## Module Structure
 
 | File | Purpose |
 |---|---|
-| `background.js` | Service worker: message routing, tab listeners, startup |
-| `content.js` | Video detection, audio processing, episode transition (IIFE) |
-| `popup.js` | Popup UI: join/create, tabs, status, settings |
-| `bridge.js` | Landing page bridge (injected into sync.koalastuff.net) |
-| `episode-utils.js` | Shared `extractEpisodeId()` / `sameEpisode()` — used by background.js, injected into content.js at build time |
-| `i18n.js` | Translation loader |
-| `shared/` | Constants, blacklist, name generator |
+| `background.js` | Service worker: WebSocket protocol, room state, host control, tab/content routing, reconnects |
+| `content.js` | Video detection/control, audio processing, episode transition, host-only guest behavior |
+| `popup.js` | Popup UI: room join/create, tabs, settings, peer list, status, diagnostics |
+| `popup.html` | Popup markup, tabs, onboarding, status/debug surfaces |
+| `bridge.js` | Invitation bridge injected into `sync.koalastuff.net` |
+| `episode-utils.js` | Shared episode-title parser imported by background and injected into content at build time |
+| `title-privacy.js` | Tab/media title privacy modes and sanitization helpers |
+| `audio-options.html` / `audio-options.js` / `audio-options.css` | Dedicated local audio-processing settings page |
+| `page-api-seek-overrides.js` | Page-level seek bridge for site-specific player APIs |
+| `modules/tab-manager.js` | Tab lifecycle helper used by the background service worker |
+| `i18n.js` | Dynamic locale loader and DOM translation helper |
+| `locales/` | Runtime popup translations |
+| `_locales/` | Browser-store manifest translations |
+| `shared/` | Generated mirror of root shared constants, blacklist, names, and README |
diff --git a/extension/content.js b/extension/content.js
index b9e7eab..6a12f7e 100644
--- a/extension/content.js
+++ b/extension/content.js
@@ -15,7 +15,7 @@
     window.koalaSyncInjected = true;

 

     // --- SHARED_EVENTS_INJECT_START ---

-    // This block is automatically updated by /scripts/build-extension.js

+    // This block is automatically updated by /scripts/build-extension.cjs
     const EVENTS = {

         PLAY: "play",

         PAUSE: "pause",

@@ -717,7 +717,7 @@
     // Handles: S01E01, S1E1, S01 - E01, Season 1 Episode 1, "Folge 5", "Episode 5", "Ep. 5", "#5"

     // Returns null if no episode pattern found.

     // --- SHARED_EPISODE_UTILS_INJECT_START ---

-    // This block is automatically replaced by /scripts/build-extension.js

+    // This block is automatically replaced by /scripts/build-extension.cjs
     function extractEpisodeId(title) {

         if (!title || typeof title !== 'string') return null;

         const se = title.match(/S(?:eason\s*)?(\d+)[^a-zA-Z0-9]*E(?:pisode\s*)?(\d+)/i);

diff --git a/extension/episode-utils.js b/extension/episode-utils.js
index ab68b07..625ef8a 100644
--- a/extension/episode-utils.js
+++ b/extension/episode-utils.js
@@ -1,6 +1,6 @@
 /**
  * KoalaSync Episode Title Utilities
- * Single source of truth — synced to content.js by build-extension.js.
+ * Single source of truth — synced to content.js by build-extension.cjs.
  * Keep in sync with the injection block in content.js!
  */
 
diff --git a/scripts/README.md b/scripts/README.md
index 53ada3f..eee47bc 100644
--- a/scripts/README.md
+++ b/scripts/README.md
@@ -1,33 +1,93 @@
 # Development Scripts
 
-This directory contains utility scripts for the KoalaSync development workflow.
+This directory contains build, synchronization, and verification scripts for the KoalaSync workspace. Run all commands from the repository root unless a script says otherwise.
+
+## Main Commands
+
+```bash
+npm run build:extension
+npm run verify
+npm run lint
+npm run test:unit
+```
+
+- `npm run build:extension` runs `scripts/build-extension.cjs`.
+- `npm run verify` runs the full release-safety suite in `scripts/verify-release.mjs`.
+- `npm run lint` runs ESLint across the repository.
+- `npm run test:unit` runs Vitest tests.
 
 ## build-extension.cjs
 
-The primary build tool for KoalaSync. This Node.js script automates two critical tasks:
+The primary extension build tool performs these steps:
 
-1.  **Protocol Synchronization**: Copies the "Single Source of Truth" constants (`shared/constants.js`) and the domain blacklist (`shared/blacklist.js`) from the root `/shared` directory into the `extension/shared/` directory.
-2.  **Content Script Injection**: Injects protocol constants directly into `content.js` using marker-based replacement. This is necessary because `content.js` executes synchronously and cannot use ES module imports.
-3.  **Artifact Generation**: Compiles the extension into browser-specific bundles for Chrome and Firefox, located in the `dist/` directory.
-
-### Usage
-
-From the **repository root**, run:
+1. Recreates `dist/`.
+2. Copies `shared/constants.js`, `shared/blacklist.js`, `shared/names.js`, and `shared/README.md` into `extension/shared/`.
+3. Injects synchronous shared values into `content.js`.
+4. Injects browser-specific uninstall URL constants into `background.js`.
+5. Injects the build timestamp into `popup.html`.
+6. Generates browser-specific manifests for Chrome and Firefox.
+7. Creates `dist/koalasync-chrome.zip` and `dist/koalasync-firefox.zip`.
 
+Usage:
 ```bash
 node scripts/build-extension.cjs
+# or
+npm run build:extension
 ```
 
-### Why this script exists
-KoalaSync uses **Vanilla JS** in the extension to maintain zero runtime dependencies and maximum privacy. Since we don't use a bundler (like Webpack or Vite) inside the extension, this script serves as our lightweight "pre-build" step to ensure that the protocol constants remain synchronized between the extension and the relay server.
+## Injection Markers
 
-### Content Injection Markers
+The build script uses marker comments/placeholders. Missing markers are a hard build failure so release artifacts cannot silently contain stale protocol data.
 
-The build script uses marker comments in `content.js` to locate and replace constant blocks:
+| Target | Marker / Placeholder | Injected Value | Source |
+|:---|:---|:---|:---|
+| `content.js` | `SHARED_EVENTS_INJECT_START` / `END` | Full `EVENTS` object | `shared/constants.js` |
+| `content.js` | `SHARED_HEARTBEAT_INJECT_START` / `END` | `HEARTBEAT_INTERVAL` | `shared/constants.js` |
+| `content.js` | `SHARED_EPISODE_UTILS_INJECT_START` / `END` | `extractEpisodeId()` and `sameEpisode()` | `extension/episode-utils.js` |
+| `background.js` | `UNINSTALL_URL_INJECT_START` / `END` | Uninstall URL and browser type | `scripts/build-extension.cjs` |
+| `popup.html` | `__BUILD_TIMESTAMP__` | UTC build timestamp | Build time |
 
-| Marker Pair | Injected Value | Source |
-|:---|:---|:---|
-| `SHARED_EVENTS_INJECT_START` / `END` | The full `EVENTS` object | `shared/constants.js` |
-| `SHARED_HEARTBEAT_INJECT_START` / `END` | `HEARTBEAT_INTERVAL` value | `shared/constants.js` |
+Do not remove or rename these markers without updating the build script and tests.
 
-> **⚠️ Do NOT remove or modify these marker comments in `content.js`.** They are required for the build script to function. If the markers are missing, the build will fail with a clear error message.
+## Verification Suite
+
+`scripts/verify-release.mjs` is the best single command before release, PR review, or handoff:
+
+```bash
+npm run verify
+```
+
+It currently runs:
+
+- Vitest unit tests.
+- Server ops, route, WebSocket, and rate-limiter checks.
+- Episode parser, title privacy, audio settings, popup cooldown, names, and content-video-finder checks.
+- JavaScript syntax checks for server and extension entry points.
+- Extension and website locale coverage checks.
+- ESLint.
+- Production `npm audit` checks for root and server dependencies.
+- Extension build and website build.
+
+## Focused Scripts
+
+| Script | Purpose |
+|:---|:---|
+| `test-server-ops.mjs` | Health payload and admin metrics helpers |
+| `test-server-routes.mjs` | HTTP health routes, caching, and admin metrics access |
+| `test-server-ws.mjs` | Socket.IO relay integration, including host-control behavior |
+| `test-rate-limiter.mjs` | Rate-limiter map and cooldown behavior |
+| `test-episode-utils.mjs` | Episode-title extraction and comparison |
+| `test-title-privacy.mjs` | Tab/media title privacy sanitization |
+| `test-audio-settings.mjs` | Audio settings defaults and normalization |
+| `test-popup-refresh-cooldown.mjs` | Popup refresh throttling behavior |
+| `test-names.mjs` | Generated username format and coverage |
+| `test-content-video-finder.cjs` | Content-script video selection helpers |
+| `test-locales.cjs` | Extension runtime and browser-store locale coverage |
+| `test-website-locales.mjs` | Website locale coverage |
+
+## Do Not Break
+
+- Keep scripts runnable from the repository root.
+- Keep build output under `dist/` and generated website output under `website/www/`.
+- Keep shared protocol sync automated; do not add manual copy steps.
+- Treat warnings in verification scripts as release blockers unless the script explicitly documents them as informational.
diff --git a/scripts/build-extension.cjs b/scripts/build-extension.cjs
index ec3568d..b5d9ac6 100644
--- a/scripts/build-extension.cjs
+++ b/scripts/build-extension.cjs
@@ -36,6 +36,13 @@ console.log('✓ constants.js, blacklist.js, names.js, and README.md synced to e
 // Read the base manifest
 const baseManifest = JSON.parse(fs.readFileSync(baseManifestPath, 'utf8'));
 
+function replaceRequiredBlock(content, pattern, replacement, description) {
+  if (!pattern.test(content)) {
+    throw new Error(`CRITICAL: ${description} markers not found. Aborting build to prevent stale artifacts.`);
+  }
+  return content.replace(pattern, replacement);
+}
+
 // Helper to copy files, ignoring manifest.json and manifest.base.json
 // Also injects shared constants into content.js
 function copyExtensionFiles(targetDir, browserName) {
@@ -79,11 +86,7 @@ function copyExtensionFiles(targetDir, browserName) {
         const ePattern = new RegExp(`${eStart}[\\s\\S]+?${eEnd}`);
         const eRep = `${eStart}\n    // This block is automatically updated by /scripts/build-extension.cjs\n    const EVENTS = ${eventsObject};\n    ${eEnd}`;
         
-        if (ePattern.test(content)) {
-          content = content.replace(ePattern, eRep);
-        } else {
-          console.warn('⚠️ WARNING: Event markers not found in content.js');
-        }
+        content = replaceRequiredBlock(content, ePattern, eRep, 'Event injection');
 
         // 2. Inject Heartbeat
         const hStart = '// --- SHARED_HEARTBEAT_INJECT_START ---';
@@ -91,30 +94,23 @@ function copyExtensionFiles(targetDir, browserName) {
         const hPattern = new RegExp(`${hStart}[\\s\\S]+?${hEnd}`);
         const hRep = `${hStart}\n    const HEARTBEAT_INTERVAL_VAL = ${heartbeatVal};\n    ${hEnd}`;
         
-        if (hPattern.test(content)) {
-          content = content.replace(hPattern, hRep);
-        } else {
-          console.warn('⚠️ WARNING: Heartbeat markers not found in content.js');
-        }
+        content = replaceRequiredBlock(content, hPattern, hRep, 'Heartbeat injection');
 
         // 3. Inject Episode Utils
         const euStart = '// --- SHARED_EPISODE_UTILS_INJECT_START ---';
         const euEnd = '// --- SHARED_EPISODE_UTILS_INJECT_END ---';
         const euPattern = new RegExp(euStart.replace(/[.*+?^${}()|[\]\\]/g, '\\$&') + '[\\s\\S]+?' + euEnd.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'));
         const euPath = path.join(rootDir, 'extension', 'episode-utils.js');
-        if (fs.existsSync(euPath)) {
-          const euContent = fs.readFileSync(euPath, 'utf8');
-          const stripped = euContent
-            .replace(/^\/\*\*[\s\S]*?\*\/\s*/m, '')
-            .replace(/export function /g, 'function ')
-            .trim();
-          const euRep = `${euStart}\n    // This block is automatically updated by /scripts/build-extension.cjs\n${stripped.split('\n').map(l => '    ' + l).join('\n')}\n    ${euEnd}`;
-          if (euPattern.test(content)) {
-            content = content.replace(euPattern, euRep);
-          } else {
-            console.warn('⚠ WARNING: Episode utils markers not found in content.js');
-          }
+        if (!fs.existsSync(euPath)) {
+          throw new Error(`CRITICAL: Episode utils source missing: ${euPath}. Aborting build.`);
         }
+        const euContent = fs.readFileSync(euPath, 'utf8');
+        const stripped = euContent
+          .replace(/^\/\*\*[\s\S]*?\*\/\s*/m, '')
+          .replace(/export function /g, 'function ')
+          .trim();
+        const euRep = `${euStart}\n    // This block is automatically updated by /scripts/build-extension.cjs\n${stripped.split('\n').map(l => '    ' + l).join('\n')}\n    ${euEnd}`;
+        content = replaceRequiredBlock(content, euPattern, euRep, 'Episode utils injection');
 
         fs.writeFileSync(destPath, content);
         console.log('✓ Injected shared constants into content.js');
@@ -132,17 +128,16 @@ function copyExtensionFiles(targetDir, browserName) {
         uRep += `        const BROWSER_TYPE = "${browserName}";\n`;
         uRep += `        ${uEnd}`;
         
-        if (uPattern.test(content)) {
-          content = content.replace(uPattern, uRep);
-        } else {
-          console.warn('⚠️ WARNING: Uninstall URL markers not found in background.js');
-        }
+        content = replaceRequiredBlock(content, uPattern, uRep, 'Uninstall URL injection');
 
         fs.writeFileSync(destPath, content);
         console.log(`✓ Injected uninstall URL constants for ${browserName} into background.js`);
       } else if (item === 'popup.html') {
         let content = fs.readFileSync(srcPath, 'utf8');
         const timestamp = new Date().toISOString().replace('T', ' ').substring(0, 19) + ' UTC';
+        if (!content.includes('__BUILD_TIMESTAMP__')) {
+          throw new Error('CRITICAL: Build timestamp placeholder not found in popup.html. Aborting build.');
+        }
         content = content.replace(/__BUILD_TIMESTAMP__/g, timestamp);
         fs.writeFileSync(destPath, content);
         console.log(`✓ Injected build timestamp into popup.html: ${timestamp}`);
diff --git a/server/.env.example b/server/.env.example
index 8f38ee5..1edd76e 100644
--- a/server/.env.example
+++ b/server/.env.example
@@ -2,6 +2,11 @@ PORT="3000"
 MIN_VERSION="1.0.0"
 MAX_ROOMS="1000"
 MAX_PEERS_PER_ROOM="25"
+
+# Required for production/self-hosting: unique random salt used for room-password hashes.
+# Generate one with: openssl rand -base64 32
+SERVER_SALT=""
+
 # Optional: enables aggregate-only admin metrics on /health with Authorization: Bearer <token>
 # Use a long random token, 32+ characters recommended.
 ADMIN_METRICS_TOKEN=""
diff --git a/server/README.md b/server/README.md
index a6b6d19..320db91 100644
--- a/server/README.md
+++ b/server/README.md
@@ -16,6 +16,11 @@ PORT="3000"
 MAX_ROOMS="1000"
 MAX_PEERS_PER_ROOM="25"
 MIN_VERSION="1.0.0"
+
+# Required for production/self-hosting: unique random salt used for room-password hashes.
+# Generate one with: openssl rand -base64 32
+SERVER_SALT=""
+
 # Optional: enables aggregate-only admin metrics on /health with Authorization: Bearer <token>
 # Use a long random token, 32+ characters recommended.
 ADMIN_METRICS_TOKEN=""
@@ -24,6 +29,19 @@ ADMIN_METRICS_TOKEN=""
 DEBUG_LOGGING="0"
 ```
 
+### Room Password Salt
+`SERVER_SALT` is used to HMAC room passwords before they are stored in RAM. The relay has a built-in fallback so development keeps working, but that fallback is public in the repository and the server logs a startup warning when it is used.
+
+For every real self-hosted deployment, set a unique random value:
+```bash
+openssl rand -base64 32
+```
+
+Then add it to `server/.env` or your Compose environment:
+```bash
+SERVER_SALT=replace-with-a-long-random-salt
+```
+
 ### Health & Metrics
 `GET /` and `GET /health` are IP-rate-limited to 10 requests per minute per client IP. These health-style responses are cached server-side for 60 seconds and refreshed lazily on request. By default `/health` returns only basic service status, uptime, room count, connection count, and a timestamp.
 
@@ -63,11 +81,20 @@ npm install
 npm start
 ```
 
+### Verification
+The server is covered by the root verification suite. From the repository root, run:
+```bash
+npm run verify
+```
+
+For focused server checks, see `scripts/test-server-ops.mjs`, `scripts/test-server-routes.mjs`, `scripts/test-server-ws.mjs`, and `scripts/test-rate-limiter.mjs`.
+
 ## Security
 - **Rate Limiting**: IP-based connection limits and socket-based event limits.
 - **Health Endpoint Throttle**: `GET /` and `GET /health` are limited to 10 requests per minute per IP, with 60-second lazy server-side response caching and stricter throttling for wrong admin bearer attempts.
 - **Room Discovery Throttle**: Room-list refreshes are rate-limited server-side to one request every 10 seconds per socket.
 - **Token Handshake**: Requires a valid token defined in the root `shared/constants.js`.
+- **Password Hash Salt**: Set `SERVER_SALT` in every deployment so room-password hashes are not derived with the public fallback salt.
 - **Single Source of Truth**: The server imports constants directly from the root `shared/` directory.
 - **In-Memory**: Rooms are automatically pruned after 2 hours of inactivity.
 - **Reverse Proxy Boundary**: The server trusts one reverse proxy hop for client IP detection. Keep the Node port private/firewalled so clients can only reach it through Caddy or another trusted proxy.
diff --git a/shared/README.md b/shared/README.md
index 0d82083..d90bd79 100644
--- a/shared/README.md
+++ b/shared/README.md
@@ -1,33 +1,73 @@
 # KoalaSync Shared Constants
 
-This directory contains constants and protocol definitions used by both the extension and the server.
+This directory is the source of truth for protocol constants and shared browser/server data.
+
+## Where You Are
+
+- `constants.js`: protocol version, app version, official URLs/token, event names, control modes, capabilities, and timing constants.
+- `blacklist.js`: domains hidden by the popup's clutter filter.
+- `names.js`: generated username parts and helper used by the extension.
+- `extension/shared/`: generated mirror created by `npm run build:extension`; do not edit that mirror directly.
 
 ## Syncing with the Extension
-> [!IMPORTANT]
-> Every time this directory is modified, you must run `node scripts/build-extension.cjs` to keep the extension's copy up to date.
 
-Because Browser Extensions (Manifest V3) cannot load files outside their root directory, all files in this directory must be copied to `extension/shared/` whenever they are modified. The build script handles this automatically.
+> [!IMPORTANT]
+> After modifying any file in this directory, run `npm run build:extension` from the repository root.
+
+Browser extensions cannot import files outside their own root directory, so the build script copies shared files into `extension/shared/` and injects selected constants into `content.js`.
 
 ## Security & Versioning Constants
-- `OFFICIAL_SERVER_TOKEN`: A 32-byte hex token required to connect to the official relay server.
-- `APP_VERSION`: The current version of the extension. Automatically injected from the git tag during CI release builds.
-- `OFFICIAL_SERVER_URL`: The default endpoint for the official KoalaSync relay.
+
+- `PROTOCOL_VERSION`: exact protocol version required during `join_room`.
+- `APP_VERSION`: extension/app version, injected from release tags by CI.
+- `OFFICIAL_SERVER_URL`: default public relay endpoint.
+- `OFFICIAL_LANDING_PAGE_URL`: public website and invitation bridge origin.
+- `OFFICIAL_SERVER_TOKEN`: public client token used to reject non-KoalaSync Socket.IO clients. It is not a secret; see `docs/KNOWN_LIMITATIONS.md`.
+- `SUPPORT_URL` and `GITHUB_URL`: public project links used by the extension UI.
+
+## Control Modes & Capabilities
+
+- `CONTROL_MODES.EVERYONE`: default room mode; any peer may control playback.
+- `CONTROL_MODES.HOST_ONLY`: only the host and promoted controllers may move playback.
+- `CAPABILITIES.HOST_CONTROL`: relay supports host-only room authority.
+- `CAPABILITIES.CO_HOST`: relay supports promoted controller peers.
+
+Clients should enable capability-gated UI only when the relay advertises the matching flag in `room_data.capabilities`.
 
 ## Protocol Events
-For the complete and current event list, see the `EVENTS` object in [`constants.js`](constants.js). Key events include:
+
+For the complete event list, read the `EVENTS` object in [`constants.js`](constants.js). Current event groups:
 
 | Event | Direction | Purpose |
-|:------|:----------|:--------|
-| `JOIN_ROOM` | Client → Server | Request to join a room with credentials |
-| `LEAVE_ROOM` | Client → Server | Leave the current room |
-| `ROOM_DATA` | Server → Client | Current room state (peers list) |
+|:---|:---|:---|
+| `JOIN_ROOM` | Client -> Server | Join or create a room with credentials and protocol version |
+| `LEAVE_ROOM` | Client -> Server | Leave the current room |
+| `ROOM_DATA` | Server -> Client | Initial room snapshot, peers, host state, capabilities |
+| `ERROR` | Server -> Client | Connection, auth, capacity, or protocol error |
+| `SET_CONTROL_MODE` | Client -> Server | Host switches between `everyone` and `host-only` |
+| `CONTROL_MODE` | Server -> Client | Host/control-mode/controller snapshot changed |
+| `SET_PEER_ROLE` | Client -> Server | Host promotes or demotes a co-host/controller |
 | `PLAY` / `PAUSE` / `SEEK` | Bidirectional relay | Media control commands |
-| `PEER_STATUS` | Bidirectional relay | Heartbeat or join/leave notification |
-| `FORCE_SYNC_PREPARE` | Bidirectional relay | Phase 1: Pause & seek to target time |
-| `FORCE_SYNC_ACK` | Bidirectional relay | Phase 1 confirmation: peer is buffered |
-| `FORCE_SYNC_EXECUTE` | Bidirectional relay | Phase 2: Resume playback simultaneously |
-| `EVENT_ACK` | Server → Client | Delivery confirmation for UI feedback |
-| `EPISODE_LOBBY` | Bidirectional relay | Episode transition: waiting for all peers |
-| `EPISODE_READY` | Bidirectional relay | Episode confirmation: peer has loaded |
-| `GET_ROOMS` / `ROOM_LIST` | Client ↔ Server | Room discovery |
-| `ERROR` | Server → Client | Error message |
+| `PEER_STATUS` | Bidirectional relay | Heartbeat and current media state |
+| `FORCE_SYNC_PREPARE` | Bidirectional relay | Phase 1: pause and seek peers to a target time |
+| `FORCE_SYNC_ACK` | Bidirectional relay | Phase 1 confirmation that a peer is ready |
+| `FORCE_SYNC_EXECUTE` | Bidirectional relay | Phase 2: resume playback together |
+| `EVENT_ACK` | Server -> Client | Delivery confirmation for UI feedback |
+| `EPISODE_LOBBY` | Bidirectional relay | Episode transition lobby started |
+| `EPISODE_READY` | Bidirectional relay | Peer has loaded the episode and is ready |
+| `EPISODE_LOBBY_CANCEL` | Bidirectional relay | Active episode lobby cancelled |
+| `GET_ROOMS` / `ROOM_LIST` | Client <-> Server | Room discovery with server-side cooldown |
+| `PING` / `PONG` | Client <-> Server/Peer | Server RTT and peer latency checks |
+
+## Timing Constants
+
+- `HEARTBEAT_INTERVAL`: content heartbeat interval in milliseconds.
+- `FORCE_SYNC_TIMEOUT`: max wait for force-sync ACKs.
+- `EPISODE_LOBBY_TIMEOUT`: max wait for episode-lobby readiness.
+
+## Do Not Break
+
+- Do not rename events without updating `docs/PROTOCOL.md`, `server/index.js`, `extension/background.js`, and the build-injected `content.js` path.
+- Do not edit `extension/shared/` directly.
+- Keep new server-gated features behind `CAPABILITIES` so old clients and old relays degrade cleanly.
+- Run `npm run build:extension` and `npm run verify` after protocol changes.
diff --git a/website/README.md b/website/README.md
index aa1b4a0..292e896 100644
--- a/website/README.md
+++ b/website/README.md
@@ -1,74 +1,101 @@
 # KoalaSync Website & Invitation Bridge
 
-This directory contains the KoalaSync website. It serves a dual purpose: it is both the **marketing landing page** and the **technical bridge** for joining synchronized rooms.
+This directory contains the static KoalaSync website. It is both the public marketing/onboarding site and the browser-side invitation bridge for joining sync rooms.
+
+## Where You Are
+
+- `template.html`, `style.css`, `app.js`, `lang-init.js`, and `locales/*.json` are source files.
+- `build.cjs` compiles the static site into `website/www/`.
+- `website/www/` is generated output. Do not edit files there directly.
+- `join.html` handles room-invite links and communicates with the extension through `bridge.js`.
+- `llms.txt` gives crawlers and AI tools a compact project overview.
+- `alternatives/` contains comparison pages for users evaluating KoalaSync against other watch-party approaches.
 
 ## Core Roles
 
 ### 1. Marketing & Onboarding
-Provides a premium, multi-language (EN/DE/FR/ES/PT-BR/RU/IT/PL/TR/NL/JA/KO/PT) overview of features, setup instructions, and direct links to the extension stores.
 
-### 2. The Invitation Bridge (`join.html`)
-The website handles incoming invitation links. When a user clicks a link like `sync.koalastuff.net/join.html#join:roomID:pass`, the website:
-- **Detects the Extension**: Verifies if KoalaSync is installed via the `bridge.js` content script.
-- **Privacy-First Handshake**: The room credentials (ID/Password) are stored in the **URL Hash (#)**. This ensures the sensitive credentials **never reach the web server** and are processed entirely within the user's browser.
-- **Auto-Join**: If the extension is detected, it automatically triggers the join flow without requiring user input.
+The site explains KoalaSync, links to browser stores, documents self-hosting, and provides localized user-facing copy in 15 languages:
+
+`en`, `de`, `fr`, `es`, `it`, `nl`, `pl`, `pt`, `pt-BR`, `tr`, `ru`, `ja`, `ko`, `zh`, and `uk`.
+
+### 2. Invitation Bridge (`join.html`)
+
+When a user opens an invitation such as `https://sync.koalastuff.net/join.html#join:roomID:pass`, the page:
+
+- detects whether the KoalaSync extension is installed via the extension's `bridge.js` content script,
+- keeps room credentials inside the URL hash so they are not sent to the web server,
+- asks the extension to join the target room automatically when possible.
 
 ## Architecture
 
-The website is 100% **Static HTML, CSS, and JS**. 
-- **Static i18n Compiler**: The site uses a lightweight, zero-dependency Node.js compiler (`build.cjs`) to parse dictionary files inside `/locales/` against a single source-of-truth template (`template.html`), outputting the fully deployable static folder to `/www/`.
-- **Build-time Minification**: `build.cjs` automatically minifies CSS and JS during compilation using a built-in state-machine tokenizer (no npm dependencies). Source files are written unminified (`style.css`, `app.js`, `lang-init.js`) — always edit source files, never the generated `.min.*` files in `www/`.
-- **Zero Backend**: No Node.js, PHP, or databases are required to host the compiled website.
-- **Zero Tracking**: All assets (fonts, icons) are self-hosted to prevent third-party tracking.
-- **Responsive**: Fully optimized for mobile with a native-feel hamburger menu.
+The website is 100% static HTML, CSS, and JavaScript.
+
+- **Static i18n compiler**: `build.cjs` combines `template.html` with dictionaries in `locales/`.
+- **Build-time minification**: Source CSS/JS stays readable; generated output uses `.min.css` and `.min.js`.
+- **Zero backend**: The compiled site can be hosted by any static file server.
+- **Zero external assets**: Fonts, icons, scripts, and images must remain self-hosted.
+- **Generated SEO/runtime files**: `version.json`, sitemap, robots, clean URLs, localized pages, and minified assets are copied or generated into `www/`.
+
+## Local Development & Compilation
+
+From the repository root:
+```bash
+node website/build.cjs
+npx serve -l 5000 website/www
+```
+
+Then open:
+
+- `http://localhost:5000/` for the default page.
+- `http://localhost:5000/de/` for a localized page.
+- `http://localhost:5000/join.html#join:test-room:test-pass` to test the invitation bridge path.
+
+Focused verification:
+```bash
+node scripts/test-website-locales.mjs
+node --check website/www/app.min.js
+node --check website/www/lang-init.min.js
+```
+
+Full verification:
+```bash
+npm run verify
+```
 
 ## Hosting with Caddy
 
-Caddy is the recommended web server. It provides automatic HTTPS and high-performance static file serving.
-
-### Recommended Caddyfile
-
-For a more comprehensive configuration that includes the Relay Server reverse proxy, see the root [Caddyfile.example](../examples/Caddyfile.example).
+Caddy is the recommended production server because it handles HTTPS and static file serving cleanly. For a complete website plus relay reverse-proxy setup, use the root [Caddyfile.example](../examples/Caddyfile.example).
 
+Minimal static-site block:
 ```caddy
 sync.koalastuff.net {
     root * /var/www/koalasync/website/www
+    try_files {path} {path}.html {path}/
     file_server
     encode zstd gzip
 
-    # Static Caching for high-performance PageSpeed (1 year with validation)
     @static {
         file
-        path *.ico *.css *.js *.png *.svg *.webp
+        path *.ico *.css *.js *.png *.svg *.webp *.avif
     }
     header @static Cache-Control "public, max-age=31536000, must-revalidate"
 
-    # Security Headers & Content Security Policy (CSP)
     header {
-        # Strict Content Security Policy (restricts scripts and connections to self, forbids frames)
-        Content-Security-Policy "default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; connect-src 'self'; img-src 'self' data:; object-src 'none'; frame-ancestors 'none';"
-        # Prevent FLoC tracking
-        Permissions-Policy interest-cohort=()
-        # Security best practices
+        Content-Security-Policy "default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; connect-src 'self'; img-src 'self' data:; object-src 'none'; frame-ancestors 'none'; base-uri 'none'; form-action 'none';"
+        Permissions-Policy "camera=(), microphone=(), geolocation=(), payment=(), usb=()"
         Strict-Transport-Security "max-age=31536000; includeSubDomains; preload"
         X-Content-Type-Options nosniff
-        X-Frame-Options DENY
-        Referrer-Policy no-referrer-when-downgrade
+        X-Frame-Options SAMEORIGIN
+        Referrer-Policy strict-origin-when-cross-origin
     }
 }
 ```
 
-## Local Development & Compilation
+## Do Not Break
 
-1. Run the compilation script from the repository root to generate the `/website/www` folder:
-   ```bash
-   node website/build.cjs
-   ```
-2. Serve the compiled `/www` directory using any local development server:
-   ```bash
-   npx serve website/www
-   ```
-3. To test the invitation flow locally, navigate to `http://localhost:5000/join.html#join:test-room:test-pass`.
-
-> [!IMPORTANT]
-> **Never edit files inside `website/www/` directly.** This directory is fully auto-generated by `build.cjs`. Always edit source files (`template.html`, `style.css`, `app.js`, `lang-init.js`, locale files in `locales/`) and re-run `node website/build.cjs` to apply changes. CSS and JS are output as `style.min.css`, `app.min.js`, and `lang-init.min.js` — the `.min.*` naming makes it visually obvious these are build artifacts. Editing minified files in `www/` will result in lost changes on the next build.
+- Do not edit `website/www/` manually; rebuild it from sources.
+- Do not add external CDNs, fonts, analytics, or third-party scripts.
+- Keep invite credentials in the URL hash, not query parameters.
+- Keep locale files synchronized with `website/build.cjs` and `scripts/test-website-locales.mjs`.
+- Commit source changes and regenerated `www/` output together when website output changes.