diff --git a/README.md b/README.md
index 4a0df35..2ef66a4 100644
--- a/README.md
+++ b/README.md
@@ -1,9 +1,118 @@
-# te, a text editor
+# te
 
-![preview](preview.jpg)
+A from-scratch text editor that aims to stay fast, hackable, and practical for day-to-day coding.
 
-In order to build on windows you need to call build.bat from
-the x64 Native Command Tools prompt that ships with Visual Studio.
+![te preview](preview.jpg)
 
-For Linux you will need clang, SDL3 and libbacktrace libraries to be installed and
-available on your system. Just call build.sh when these are available.
\ No newline at end of file
+## What this project is
+
+`te` is a native desktop editor written as a single C++ executable (SDL3 + OpenGL + custom editor core).
+It is built around a straightforward single-threaded architecture, with coroutines used for asynchronous workflows (searching, UI flows, process jobs) so behavior stays easy to reason about and debug.
+
+The codebase includes its own:
+
+- text buffer + undo/redo engine
+- window/view layout system
+- command system + keybinding parser
+- fuzzy selection UI
+- process execution and output streaming
+- built-in font fallback (baked into the binary)
+
+## Highlights
+
+- VS Code-style keybindings and command palette (`Ctrl+Shift+P`)
+- Multi-cursor editing (keyboard and mouse workflows)
+- Fuzzy-open patterns for commands, files, and open buffers
+- Project-wide search (`Ctrl+Shift+F`) and replace-all workflow
+- Shell integration directly from editor input:
+  - `:Command` to run editor commands
+  - `:Set ...` to configure options and keybindings
+  - `!cmd` / `!!cmd` to execute shell commands
+  - `py:...` to execute Python snippets via discovered Python interpreter
+- Build panel integration (`Ctrl+B`, `Alt+B`, etc.) with configurable build commands
+- Config-driven behavior (font, colors, project commands, keymaps, paths)
+
+## Build
+
+### Linux
+
+Requirements:
+
+- `clang`
+- `cmake`
+- `libbacktrace`
+- SDL3 (the build script can clone and install SDL when missing)
+
+Build commands:
+
+```bash
+./build.sh           # debug build (default)
+./build.sh release   # optimized build
+./build.sh slow      # extra asserts/instrumentation path
+```
+
+Run:
+
+```bash
+./build/te
+./build/te path/to/file.cpp
+```
+
+### Windows
+
+Use the **x64 Native Tools Command Prompt for Visual Studio**.
+
+Requirements:
+
+- Visual Studio C++ toolchain (`cl`, `msbuild`)
+- `cmake`
+
+Build commands:
+
+```bat
+build.bat
+build.bat release
+build.bat slow
+```
+
+Run:
+
+```bat
+build\te.exe
+build\te.exe path\to\file.cpp
+```
+
+## First steps in the editor
+
+- `Ctrl+N`: new buffer
+- `Ctrl+O`: open current file's folder / directory navigation view
+- `Ctrl+P`: fuzzy list of open buffers
+- `Ctrl+Shift+P`: all commands
+- `Ctrl+Q` or `F12`: open thing under caret (path / link / command)
+- `Ctrl+F`, `F3`, `Shift+F3`: in-buffer search flow
+- `Ctrl+Shift+F`: interactive search across open project buffers
+- `Alt+Shift+Up/Down`: add cursors vertically
+- `Ctrl+B`: run Build1 command (configurable)
+
+## Configuration
+
+On startup, `te` loads a config file from SDL's app preference directory (`config.te`).
+You can also pass additional `.te` files as CLI arguments.
+
+Useful examples:
+
+```text
+:Set FontSize 16
+:Set PathToFont '/path/to/font.ttf'
+:Set Build1OnUnix 'sh build.sh release'
+:Set Build1OnWindows 'build.bat release'
+:Set TextColor ff202020
+:Set BackgroundColor fffdf6e3
+```
+
+## Notes on architecture
+
+- Single-threaded main loop (event/update/render)
+- Coroutines for async editor tasks instead of multi-threaded complexity
+- "Plugin" modules are integrated in the source tree and compiled in
+- Focus on predictable behavior and low-latency interaction