diff --git a/README.md b/README.md
index e69de29..50a9632 100644
--- a/README.md
+++ b/README.md
@@ -0,0 +1,21 @@
+# dotstate-storage
+
+Git-backed storage for [dotstate](https://dotstate.serkan.dev) — manages dotfiles and application configs across machines.
+
+## How it works
+
+Dotstate symlinks files from this repo into their expected locations on disk (e.g. `~/.zshrc`, `~/.config/starship.toml`). Each machine gets its own profile, but shared configs stay in sync via this repo.
+
+## Structure
+
+- `default/` — default profile (active on new machines)
+- `bootstrap.sh` — installs dependencies and clones this repo on a fresh machine
+- `.dotstate-profiles.toml` — profile definitions
+
+## Usage
+
+```bash
+dotstate activate   # apply symlinks for the active profile
+dotstate sync       # commit and push changes
+dotstate doctor     # diagnose issues
+```