docs: honest privacy wording, prerequisites, Next.js badge, troubleshooting page

CONTRIBUTING.md

@@ -19,8 +19,8 @@ concrete tasks go to [issues](https://github.com/reframe-oss/reframe/issues).
 
 ## Set up
 
-You need [Git](https://git-scm.com), [Bun](https://bun.sh) 1.x and a recent
-Chrome, Firefox or Safari. This project uses **Bun and `bun.lock` only**: don't
+You need [Git](https://git-scm.com), [Bun](https://bun.sh) 1.x, Node.js 20.9 or
+newer, and a recent Chrome, Firefox or Safari. This project uses **Bun and `bun.lock` only**: don't
 use npm or yarn, and never commit `package-lock.json` or `yarn.lock`.
 
 ```bash

README.md

@@ -4,11 +4,12 @@
 
 # Reframe
 
-**Resize, trim and convert videos in your browser. Nothing is uploaded.**
+**Resize, trim and convert videos in your browser. Your video never leaves your device.**
 
 [![Stars](https://img.shields.io/github/stars/reframe-oss/reframe?style=flat-square&logo=github)](https://github.com/reframe-oss/reframe/stargazers)
 [![Issues](https://img.shields.io/github/issues/reframe-oss/reframe?style=flat-square)](https://github.com/reframe-oss/reframe/issues)
 [![License](https://img.shields.io/github/license/reframe-oss/reframe?style=flat-square)](LICENSE)
+[![Next.js](https://img.shields.io/badge/Next.js-16-black?style=flat-square&logo=next.js)](https://nextjs.org)
 [![CI](https://github.com/reframe-oss/reframe/actions/workflows/main.yml/badge.svg?branch=main)](https://github.com/reframe-oss/reframe/actions/workflows/main.yml?query=branch%3Amain)
 [![Netlify Status](https://api.netlify.com/api/v1/badges/fc902da9-9876-4298-9aea-f930075f8d95/deploy-status)](https://app.netlify.com/sites/reframe-os/deploys)
 [![Known Vulnerabilities](https://snyk.io/test/github/reframe-oss/reframe/badge.svg)](https://snyk.io/test/github/reframe-oss/reframe)
@@ -42,13 +43,15 @@ single-threaded build. The details are in [docs/ARCHITECTURE.md](docs/ARCHITECTU
 
 ## Quick start
 
+You need [Bun](https://bun.sh) 1.x and Node.js 20.9 or newer.
+
 ```bash
 git clone https://github.com/reframe-oss/reframe.git && cd reframe
 bun install
 bun run dev
 ```
 
-Then open http://localhost:3000. Deploying your own copy: [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md).
+Then open http://localhost:3000. Deploying your own copy: [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md). Something not working? See [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md).
 
 ## Privacy
 
@@ -72,8 +75,10 @@ to set up, claim an issue with `/assign`, and open a pull request.
   </picture>
 </a>
 
-Reframe is an official GSSoC'26 project. Start with the
-[`gssoc'26` issues](https://github.com/reframe-oss/reframe/issues?q=is%3Aopen+label%3A%22gssoc%2726%22).
+Reframe is an official GSSoC'26 project. Pick one of the
+[`gssoc'26` issues](https://github.com/reframe-oss/reframe/issues?q=is%3Aopen+label%3A%22gssoc%2726%22)
+and claim it by commenting `/assign` ([how claiming works](CONTRIBUTING.md#claim-an-issue)).
+Maintainers add the labels.
 
 ## Supported by
 

docs/TROUBLESHOOTING.md

@@ -0,0 +1,78 @@
+# Troubleshooting and FAQ
+
+## Setting up
+
+### `bun install` fails
+
+- Use [Bun](https://bun.sh) 1.x and Node.js 20.9 or newer (`bun --version`,
+  `node --version`). Don't use npm or yarn: the project uses `bun.lock` only.
+- Run `bun install --frozen-lockfile`. It installs exactly what `bun.lock`
+  lists, the same as CI.
+- If it still fails, **don't delete `bun.lock`** (that pulls in different
+  versions and hides the real problem). Open an issue with the full error
+  output, your OS and the Bun and Node versions.
+
+### "lockfile had changes, but lockfile is frozen"
+
+`package.json` and `bun.lock` disagree. If you changed dependencies, run
+`bun install` (without `--frozen-lockfile`) and commit the updated `bun.lock`
+with your change. If you didn't, your branch is behind `main`: merge `main`.
+
+### Environment variables aren't picked up
+
+- Copy `.env.example` to `.env.local`. All keys are optional; without the
+  Datadog ones, telemetry is simply off.
+- Restart `bun run dev`: environment variables are read only at startup.
+
+## Running
+
+### Exports are slow, and the browser console says the engine is single-threaded
+
+The fast multi-threaded engine needs the page to be cross-origin isolated
+(COOP/COEP headers). `bun run dev` doesn't send them. To test the
+multi-threaded engine, build and serve the static export with the headers:
+
+```bash
+bun run build
+node scripts/serve-isolated.mjs   # http://127.0.0.1:4173
+```
+
+See [DEPLOYMENT.md](DEPLOYMENT.md) for hosting.
+
+### An export stops making progress
+
+Reframe stops it after a while and, on the multi-threaded engine, retries on
+the single-threaded one automatically. If that also stalls you'll see a
+message with **Retry export**. Large files need a lot of memory: close other
+tabs, or trim the clip or lower the output resolution first.
+
+### Changes to `src/lib/ffmpeg*.ts` don't show up
+
+The FFmpeg worker stays loaded across Fast Refresh. Reload the page fully.
+
+## FAQ
+
+### How do I start the project?
+
+```bash
+bun install --frozen-lockfile
+bun run dev
+```
+
+### How do I run the tests?
+
+`bun run test` for unit tests, and `bunx playwright test` for the end-to-end
+export tests (see [CONTRIBUTING.md](../CONTRIBUTING.md#set-up) for the
+one-time setup).
+
+### How do I report a bug?
+
+Open an [issue](https://github.com/reframe-oss/reframe/issues/new) with the
+steps to reproduce, what you expected, what happened, your browser and OS,
+and the console error if there is one. Please don't attach private videos.
+
+### Does Reframe upload my video?
+
+No. Videos are processed on your device. Reframe sends anonymous performance
+and error data, which you can turn off under **Settings** (the privacy page).
+See [DATADOG.md](DATADOG.md) for exactly what is sent.

docs/USAGE.md

@@ -1,6 +1,6 @@
 # Using Reframe
 
-Reframe edits a video in your browser. Nothing is uploaded: the file is
+Reframe edits a video in your browser. Your video is never uploaded: it is
 processed on your device by FFmpeg running as WebAssembly.
 
 ## Basic flow

src/components/DatadogInit.tsx

@@ -36,9 +36,9 @@ export default function DatadogInit() {
             // The commit SHA (next.config.ts): errors and vitals group by release.
             version: process.env.NEXT_PUBLIC_RELEASE || "dev",
             sessionSampleRate: 100,
-            // Reframe advertises itself as 100% private client-side video editing —
-            // session replay would visually record the editor UI, which cuts
-            // against that claim. Metrics/errors only.
+            // Off: session replay would visually record the editor (and the
+            // video in the preview), which videos never leaving the device rules
+            // out. Metrics and errors only.
             sessionReplaySampleRate: 0,
             // Replay is off; if it were ever enabled, text and inputs stay masked.
             defaultPrivacyLevel: "mask",