diff --git a/README.md b/README.md
new file mode 100644
index 0000000..31e2cdf
--- /dev/null
+++ b/README.md
@@ -0,0 +1,39 @@
+# local-ai-stack
+
+Local open-source AI coding stack for Linux.
+
+## What this does
+
+This stack:
+
+- detects machine hardware
+- generates a local Continue config
+- keeps Ollama within normal resource limits
+- supports a temporary burst mode for heavier tasks
+- gives a repeatable Planner -> Builder -> Critic workflow
+
+## Requirements
+
+Installed on the machine:
+
+- Ollama
+- VS Code or VSCodium
+- Continue extension
+- Python 3
+- systemd
+
+## Main files
+
+- `bootstrap.sh` - runs setup
+- `scripts/probe.sh` - detects CPU, RAM, GPU
+- `scripts/render-config.py` - writes `~/.continue/config.yaml`
+- `scripts/normal-80.sh` - normal Ollama limits
+- `scripts/burst-95.sh` - temporary higher limits
+- `scripts/status.sh` - shows current stack status
+
+## Fresh install
+
+```bash
+git clone https://gitea.l484.com/avi/local-ai-stack.git ~/local-ai-stack
+cd ~/local-ai-stack
+./bootstrap.sh