docs: README for Phase 1 MVP

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

README.md

@@ -1,7 +1,49 @@
-# Tauri + React + Typescript
+# Browserlay
 
-This template should help get you started developing with Tauri, React and Typescript in Vite.
+A Windows desktop app that creates a translucent, always-on-top browser overlay. Type a URL, drop the opacity, toggle click-through — keep a stream, dashboard, or doc page floating over your work.
 
-## Recommended IDE Setup
+## Features (Phase 1 / MVP)
 
-- [VS Code](https://code.visualstudio.com/) + [Tauri](https://marketplace.visualstudio.com/items?itemName=tauri-apps.tauri-vscode) + [rust-analyzer](https://marketplace.visualstudio.com/items?itemName=rust-lang.rust-analyzer)
+- Frameless, transparent overlay window pinned over other apps.
+- Real-time opacity slider (10%–100%) backed by Win32 `SetLayeredWindowAttributes` — true OS-level translucency.
+- Always-on-top toggle.
+- Click-through toggle — mouse events pass through to the app underneath.
+- **`Ctrl+Alt+Space`** global hotkey to toggle click-through from anywhere (the escape hatch when you can't click the overlay).
+- Last URL, opacity, and toggle states persist between sessions.
+- Window position and size remembered between sessions.
+
+## Dev setup
+
+Prereqs: Node 18+, Rust toolchain (`rustup`), Tauri 2 prereqs for Windows ([WebView2 ships with Windows 11](https://tauri.app/start/prerequisites/)).
+
+```bash
+cd browserlay
+npm install
+npm run tauri dev
+```
+
+Frontend tests:
+
+```bash
+npm test
+```
+
+## Build
+
+```bash
+npm run tauri build
+```
+
+Outputs an MSI/NSIS installer under `src-tauri/target/release/bundle/`.
+
+## Architecture
+
+Two-window Tauri 2 app. Control window hosts a React + Tailwind v4 + Zustand UI; overlay is a frameless transparent webview spawned at runtime pointing directly at the user-supplied URL. Per-window capability files lock the overlay down — pages it loads can't call any Tauri APIs.
+
+The click-through escape hatch (`Ctrl+Alt+Space`) runs in Rust via `tauri-plugin-global-shortcut` so it works regardless of focus. Window opacity drops down to Win32 directly because Tauri 2.11.x doesn't expose `set_opacity` (open issue [tauri-apps/tauri#3279](https://github.com/tauri-apps/tauri/issues/3279)).
+
+See [`docs/plans/2026-05-08-browserlay-mvp-design.md`](docs/plans/2026-05-08-browserlay-mvp-design.md) for the full design.
+
+## Roadmap (Phase 2)
+
+Presets · configurable hotkeys · system tray icon · edge-snap · multi-monitor placement · in-overlay toolbar.