fix: address DeepSeek provider roast findings

.env.example

@@ -1,18 +1,26 @@
-# supercut director — LLM provider (OpenAI-compatible). Copy to .env and fill in.
+# supercut director — LLM provider. Copy to .env and fill in.
 # Only `supercut generate` needs this; `record` and `render` work without a key.
+# generate sends crawled DOM text, optional screenshots, and optional repo notes
+# to the configured provider. Use trusted apps/providers only.
 
-# ── DeepSeek (recommended) ───────────────────────────────────────────────
+# ── Provider selection ──────────────────────────────────────────────────
+# Optional when exactly one provider key is set. Required to disambiguate if
+# multiple provider keys exist.
+# SUPERCUT_PROVIDER=deepseek        # deepseek | openrouter | custom
+
+# ── DeepSeek (text-only; DOM-only analysis, no screenshot QC) ───────────
 # Get a key: https://platform.deepseek.com/api_keys
 DEEPSEEK_API_KEY=
+# SUPERCUT_MODEL=deepseek-v4-pro    # or deepseek-v4-flash
+# SUPERCUT_VISION=false             # DeepSeek text-only; true is rejected
 
-# Model: deepseek-v4-pro (smart, recommended for the director) or
-#        deepseek-v4-flash (cheaper/faster). Both are text-only.
-SUPERCUT_MODEL=deepseek-v4-pro
-
-# ── OR OpenRouter (one key, many models incl. vision) ────────────────────
+# ── OpenRouter (can use vision-capable models) ──────────────────────────
 # OPENROUTER_API_KEY=
 # SUPERCUT_MODEL=anthropic/claude-sonnet-4.6
+# SUPERCUT_VISION=true
 
-# ── Advanced overrides (usually leave blank) ─────────────────────────────
-# SUPERCUT_LLM_BASE_URL=     # custom endpoint
-# SUPERCUT_VISION=           # "true"/"false" to force vision on/off
+# ── Custom OpenAI-compatible endpoint ───────────────────────────────────
+# SUPERCUT_API_KEY=
+# SUPERCUT_LLM_BASE_URL=https://your-compatible-endpoint.example/api/v1
+# SUPERCUT_MODEL=your-model-name      # required for custom endpoints
+# SUPERCUT_VISION=false

.github/workflows/ci.yml

@@ -0,0 +1,36 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  typecheck-and-unit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+        with:
+          node-version: 22
+          cache: npm
+      - run: npm ci
+      - run: npm run typecheck
+      - run: npm test -- --run test/cursor.test.ts test/director.test.ts test/director-validation.test.ts test/schema.test.ts test/config.test.ts test/url-policy.test.ts test/redaction.test.ts test/plan.test.ts
+      - run: npm audit --audit-level=moderate
+
+  browser-e2e:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+        with:
+          node-version: 22
+          cache: npm
+      - run: npm ci
+      - run: npx playwright install --with-deps chromium
+      - run: sudo apt-get update && sudo apt-get install -y ffmpeg
+      - run: npm test -- --run test/record.e2e.test.ts test/generate.e2e.test.ts

README.md

@@ -4,27 +4,130 @@
 
 Institutional-grade, max-60-second launch videos generated from your **real**
 product — not an HTML mockup. A scripted browser performs your app on camera;
-a cinematic renderer adds the Screen Studio look (spring zoom-to-cursor,
-motion blur, padded background, music on the beat grid); an AI director writes
-the script and quality-checks the footage.
+a cinematic renderer adds the Screen Studio look: spring zoom-to-cursor,
+motion blur, padded background, and a polished final export.
 
-**Status: pre-release, under active construction.** The design doc and build
-plan are complete; stages are landing in order. Nothing to install yet.
+**Status: pre-release.** The core record/render/generate pipeline exists, but
+it is still being hardened. Use it on trusted apps and trusted recipes.
 
+```text
+ your app URL ──▶ ① analyze   pick the 2-4 money moments (LLM)
+                  ② script    write the filming recipe (LLM, schema-validated)
+                  ③ record    deterministic browser executor performs it
+                  ④ qc        deterministic + optional vision checks, bounded retakes
+                  ⑤ render    cinematic compositing ──▶ final.mp4 (≤60s target)
 ```
- your app URL ──▶ ① analyze   pick the 3-4 money moments (LLM)
-                  ② script    write the filming recipe, beat-aligned (LLM, schema-validated)
-                  ③ record    a deterministic browser executor performs it (pure code)
-                  ④ qc        vision checks the footage, refilms what's bad (bounded loop)
-                  ⑤ render    cinematic compositing + music ──▶ launch.mp4 (≤60s, 1080p60)
+
+## Install for local development
+
+```bash
+npm install
+npm run typecheck
+npm run test:fast
+```
+
+For browser/video tests you also need Chromium + ffmpeg:
+
+```bash
+npx playwright install chromium
+npm run test:e2e
+```
+
+## CLI
+
+```bash
+npm run build
+node dist/cli/index.js doctor
+node dist/cli/index.js record --recipe examples/demo.recipe.json --out out/take --seed 1
+node dist/cli/index.js render --take out/take --out out/final.mp4
+node dist/cli/index.js generate --url https://your-app.example --out out/generate --yes
+```
+
+### Private/local apps
+
+`generate` blocks localhost, RFC1918, link-local, and cloud metadata addresses
+by default. If you intentionally want to film a local development app, opt in:
+
+```bash
+node dist/cli/index.js generate --url http://127.0.0.1:3000 --allow-private-network --yes
+```
+
+Do not use recipes or URLs you do not trust. They drive real browser navigation.
+
+## LLM provider setup
+
+Copy `.env.example` to `.env` or pass `--env-file <file>`.
+
+```bash
+cp .env.example .env
+```
+
+DeepSeek is text-only in this project, so Supercut disables screenshots and
+vision QC for DeepSeek by default:
+
+```env
+SUPERCUT_PROVIDER=deepseek
+DEEPSEEK_API_KEY=...
+SUPERCUT_MODEL=deepseek-v4-pro
+```
+
+OpenRouter/custom OpenAI-compatible providers can use vision-capable models:
+
+```env
+SUPERCUT_PROVIDER=openrouter
+OPENROUTER_API_KEY=...
+SUPERCUT_MODEL=anthropic/claude-sonnet-4.6
+SUPERCUT_VISION=true
+```
+
+For `SUPERCUT_PROVIDER=custom`, set both `SUPERCUT_LLM_BASE_URL` and
+`SUPERCUT_MODEL`; Supercut will not guess an OpenRouter model for your endpoint.
+
+If multiple provider keys are present, set `SUPERCUT_PROVIDER` explicitly.
+Ambiguous provider configuration fails loudly rather than guessing.
+
+## Privacy warning
+
+`supercut generate` may send crawled DOM text, element labels/selectors,
+optional screenshots, and optional repo notes (`--repo`) to the configured LLM
+provider. It can also persist sensitive frames, recipes, and director reports in
+`out/`. Review those artifacts before sharing them.
+
+Use `record` + `render` for a no-LLM workflow.
+
+## Event-log contract
+
+The public boundary is:
+
+```text
+recipe.json ──▶ record ──▶ take directory
+                         ├─ events.json
+                         ├─ frames-index.json
+                         └─ frames/*.png
+
+take directory ──▶ render ──▶ final.mp4
+```
+
+Schemas reject unsupported URL schemes, malformed known events, non-monotonic
+timelines, oversized event logs, and impossible camera/zoom boxes.
+
+## Project principles
+
+- Real product footage beats mockups.
+- The event log is a public contract.
+- Non-AI recorder/render paths must remain useful without an API key.
+- Defaults should fail loudly on unsafe or ambiguous config.
+
+## Contributing
+
+```bash
+npm run typecheck
+npm run test:fast
+npm run test:e2e
+npm audit --audit-level=moderate
 ```
 
-- Real footage only — no fake UI renders, ever
-- The event-log JSON between recorder and renderer is a public contract; any
-  recorder can feed it
-- Stages ③ and ⑤ run standalone with zero API key (`supercut record`,
-  `supercut render`)
-- MIT, CC0-only bundled music, macOS + Linux
+Keep PRs focused and add tests for behavior changes.
 
 ## License