diff --git a/README.md b/README.md
new file mode 100644
index 0000000..b08785a
--- /dev/null
+++ b/README.md
@@ -0,0 +1,98 @@
+# Helder
+
+**A dark, AI-first desktop code workbench for reviewing code written by an AI agent.**
+
+Helder is an Electron app that puts code review, git, and a live Claude Code agent side by side in one dense, IDE-style window. It opens one project per window, is dark-only by design (no light mode, no theme toggle), and is built around a single idea: make it effortless to point an AI agent at exactly the code you're looking at.
+
+> **Status: greenfield.** This repository currently contains the design handoff only — no application code yet. The first task is to scaffold the Electron app and port the prototype. See [Getting started](#getting-started).
+
+---
+
+## What it does
+
+A four-column workbench, left to right, between a thin title bar and status bar:
+
+1. **Source Control** — git working state: commit box, staged list, changes list, per-file `+/−` counts. Stage, unstage, commit, and discard. (Push, pull, fetch, and branch switching are out of scope this version.)
+2. **Explorer** — a VS Code-style file tree with colored file-type icons and inline change badges.
+3. **Editor** — tabs plus syntax-highlighted code, with four diff view modes for changed files: **Original · Updated · Diff · Split** (Split goes full-screen, side by side).
+4. **Right column** — a live **Claude Code agent** terminal stacked over a normal shell terminal.
+
+Every pane boundary is a draggable splitter; positions persist across launches.
+
+### The defining feature: Copy reference / Pass on to Agent
+
+Right-click in the editor to copy a project-relative `path:line` reference (e.g. `src/Http/Controller/UserController.php:42`), or **Pass on to Agent** — which inserts the reference into the agent's input *without submitting*, so you can stack several references before sending. Under the hood this uses bracketed paste into the agent's PTY, exactly how a real terminal paste behaves.
+
+### One search for everything
+
+`⌘F` / `Ctrl+F` opens a single modal that searches **both file contents and file names** at once — content matches on the left (ripgrep), fuzzy file-name matches on the right. There is intentionally no separate "go to file" command.
+
+---
+
+## Tech stack
+
+| Layer | Choice |
+|-------|--------|
+| Shell | Electron (latest stable), main + renderer + preload bridge (`contextIsolation: true`) |
+| Renderer | React 18 + TypeScript + Vite (`electron-vite`) |
+| Highlighting | Prism 1.29 (swappable to Shiki / CodeMirror 6) |
+| Filesystem | `fs` + `chokidar`, via the main process |
+| Git | `git` / `simple-git`, via the main process |
+| Terminals | `node-pty` + `xterm.js` |
+| Search | `ripgrep` (content) + a fuzzy matcher (file names) |
+| Mono font | JetBrains Mono, bundled locally |
+
+**Architecture rule:** the renderer never touches the filesystem, git, or PTYs directly. All of it goes through the main process over IPC / the preload bridge.
+
+---
+
+## Getting started
+
+> No build tooling exists yet. This section will be filled in once the Electron + Vite toolchain is scaffolded.
+
+Planned implementation order:
+
+1. Electron shell + frameless dark window; port design tokens to CSS variables; bundle JetBrains Mono.
+2. Static layout: four resizable columns + title/status bars.
+3. Real file tree + open files into tabs (read-only) with Prism highlighting.
+4. Git panel from `git status` → staging + commit → the four diff modes + Split.
+5. Search (ripgrep + fuzzy).
+6. Terminals via node-pty + xterm.js; run `claude` in the agent pane.
+7. Copy reference + Pass-on-to-Agent.
+
+To preview the design prototype now, open `design_handoff_helder_workbench/design/Helder - AI Code Workbench.html` in a browser — it's a clickable React-via-Babel mock with sample data.
+
+---
+
+## Configuration
+
+Settings are project-scoped, in a `.helder/` folder in the opened project's root:
+
+- **`.helder/config.json`** — your overrides only (sparse).
+- **`.helder/config.default.json`** — the full default set, regenerated on every launch as live documentation of every setting.
+- **`.helder/theme.css`** — a custom theme layered over the built-in dark theme; the code font and size live here.
+
+An effective setting is the value from `config.json` if present, otherwise from `config.default.json`, merged key by key.
+
+---
+
+## Repository layout
+
+```
+DESIGN.md                          Functional/UX spec — every panel, state, and interaction
+CLAUDE.md                          Guidance for Claude Code working in this repo
+design_handoff_helder_workbench/
+  README.md                        Technical handoff — structure, design tokens, integration mechanics
+  design/
+    Helder - AI Code Workbench.html  Clickable prototype (open in a browser)
+    styles.css                       Canonical design tokens (the :root block)
+    src/*.jsx                        Prototype components (reference only — replace mock data)
+```
+
+The two handoff documents are the source of truth: **`DESIGN.md`** for *what the app does*, **`design_handoff_helder_workbench/README.md`** for *how to build it*. The prototype is a visual reference — do not ship it as-is.
+
+---
+
+## License
+
+TBD.