diff --git a/README.md b/README.md
new file mode 100644
index 0000000..4616568
--- /dev/null
+++ b/README.md
@@ -0,0 +1,96 @@
+# improvise
+
+*Terminal pivot-table modeling in the spirit of Lotus Improv — multidimensional cells, formulas over dimensions instead of cell addresses, and vim-style keybindings for reassigning axes on the fly.*
+
+![demo](docs/demo.gif)
+
+## Why this exists
+
+Lotus Improv (NeXT, 1991) separated data from its presentation: cells were
+addressed by named dimensions, not grid coordinates, and rearranging a view
+didn't break formulas. That idea never made it into mainstream tools. Excel
+pivot tables borrowed the visual rearrangement but kept cell-address formulas.
+Terminal data tools like sc-im and VisiData do different things well — sc-im is
+a traditional spreadsheet, VisiData is a data explorer — but neither offers the
+dimension-keyed data model that made Improv interesting. improvise is a small
+attempt to bring that model to a modern terminal, with a formula language that
+references category and item names, views that can be rearranged with a single
+keystroke, and a plain-text file format you can diff in git.
+
+## Quick start
+
+```sh
+nix develop
+cargo build --release
+./target/release/improvise examples/demo.improv
+```
+
+Or import your own CSV:
+
+```sh
+./target/release/improvise import path/to/data.csv
+```
+
+## Key bindings to try first
+
+| Key | Action |
+|-----|--------|
+| `T` | Enter tile mode — reassign category axes |
+| `[` / `]` | Cycle through page-axis items |
+| `>` | Drill into an aggregated cell |
+| `<` | Return from drill-down |
+| `F` | Open the formula panel |
+| `t` | Transpose rows and columns |
+| `?` / `F1` | Full key reference |
+| `:w` | Save |
+| `:q` | Quit |
+
+## Installation
+
+### From source with Nix (preferred)
+
+```sh
+nix develop
+cargo build --release
+# optionally install to your PATH:
+cargo install --path .
+```
+
+### From crates.io
+
+```sh
+cargo install improvise
+```
+
+### Prebuilt binaries
+
+See the [GitHub releases page](https://github.com/fiddlerwoaroof/improvise/releases)
+for prebuilt binaries (Linux x86_64, macOS Intel and Apple Silicon).
+
+## What's interesting about the codebase
+
+The data model stores every cell at the intersection of named categories and
+items — `(Region=East, Measure=Revenue)` — rather than at a grid address like
+`B3`. A view is a configuration that assigns each category to a row, column,
+page, or hidden axis, and the grid layout is computed as a pure function from
+`(Model, View)` to `GridLayout`. Transposing a pivot is just swapping the row
+and column assignments; records mode is just assigning the virtual `_Index` and
+`_Dim` categories to particular axes. The formula language references dimension
+names (`Profit = Revenue - Cost`), so formulas survive any rearrangement
+without rewriting. All user actions go through a command/effect pipeline:
+commands are pure functions that read an immutable context and return a list of
+effects, which are the only things that mutate state. The same command registry
+serves both the interactive TUI and the headless `cmd`/`script` CLI
+subcommands. Models persist to a markdown-like `.improv` format that is
+human-readable, git-diffable, and optionally gzip-compressed.
+
+## Expectations
+
+improvise is a personal project I built for my own use. I'm sharing it because
+other people might find it useful, but I can't promise active maintenance or
+feature development. Issues and PRs are welcome but may not get a fast
+response. If you want to build on it, fork away.
+
+## License
+
+MIT