diff --git a/.node-version b/.node-version
index 7273c0f..6f4247a 100644
--- a/.node-version
+++ b/.node-version
@@ -1 +1 @@
-25
+26
diff --git a/README.md b/README.md
index e9ba9e7..6ccf3cb 100644
--- a/README.md
+++ b/README.md
@@ -28,3 +28,62 @@ MacOS tiling WMs, mainly [Aerospace](https://github.com/nikitabobko/AeroSpace) (
 - complicated window dragging features and uis
     - Aerospace supports control + drag to combine windows while moving with the mouse, and normal window dragging.
 
+## Installation
+
+Aerospike isn't on the GNOME extension store yet, so install it from source.
+This builds the extension locally and drops it into your user's extension dir.
+Requires [just](https://github.com/casey/just) as the command runner.
+
+Arch Linux:
+
+```bash
+sudo pacman -S git just
+```
+
+Clone and install:
+
+```bash
+git clone https://github.com/lucasoskorep/aerospike-gnome
+cd aerospike-gnome
+just install
+```
+
+After installing from source, enable it (toggle in the Extensions app, or):
+
+```bash
+gnome-extensions enable aerospike@lucaso.io
+```
+
+Re-login or restart the shell (`Alt+F2` → `r` on X11) to pick it up.
+
+## Development
+
+Building and debugging locally needs a few extra tools:
+
+- `just` — the command runner
+- `fnm` — fast node version manager (the build runs on Node via pnpm)
+- `glib2` — provides `glib-compile-schemas` for compiling the settings schema
+
+Arch Linux:
+
+```bash
+sudo pacman -S just fnm glib2
+```
+
+Set up the Node runtime with fnm (the pinned version lives in `.node-version`):
+
+```bash
+fnm install
+fnm use
+```
+
+Then:
+
+```bash
+just install      # install deps + build + drop into the extension dir
+just lint         # lint
+just test         # run the test suite
+just test-watch   # run tests in watch mode
+just live-debug   # tail gnome-shell logs while you poke at it
+```
+