diff --git a/README.md b/README.md
new file mode 100644
index 0000000..ad6874f
--- /dev/null
+++ b/README.md
@@ -0,0 +1,132 @@
+# dotfiles
+
+Bare-git managed dotfiles for zsh/vim/tmux on Linux and macOS.
+
+## How it works
+
+This repo uses a **bare git repository** at `~/.dotgit` with the work tree set to `$HOME`. This avoids symlinks and lets dotfiles live at their native paths.
+
+The alias that drives everything:
+
+```bash
+alias .g='git --git-dir=$HOME/.dotgit/ --work-tree=$HOME'
+```
+
+`.g status`, `.g add`, `.g diff`, `.g commit`, `.g push` — same as git, just scoped to the dotfiles repo. Untracked files are hidden by default (`showUntrackedFiles = no` in config).
+
+## Bootstrap on a new machine
+
+```bash
+git clone --bare https://gitea.abra.me/svxf/dotfiles.git $HOME/.dotgit
+alias .g='git --git-dir=$HOME/.dotgit/ --work-tree=$HOME'
+.g checkout
+.g config status.showUntrackedFiles no
+```
+
+If checkout conflicts with existing files, back them up first:
+
+```bash
+.g checkout 2>&1 | grep "^\t" | xargs -I{} mv {} {}.bak
+.g checkout
+```
+
+On next shell start, zinit will bootstrap itself and install all plugins automatically.
+
+## Tracked files
+
+| File | What it does |
+|---|---|
+| `.zshrc` | Shell config — plugins, aliases, functions, keybindings, PATH |
+| `.vimrc` | Vim config — space-leader, persistent undo, arrow keys disabled |
+| `.tmux.conf` | tmux config — mouse, green accent, fzf window switcher, auto-rename |
+| `.starship.toml` | Prompt — two-line, git status, docker indicators, command duration |
+| `.gitignore_global` | Global ignores — `*~`, `.DS_Store`, `__pycache__`, `.idea`, `.ipynb_checkpoints` |
+
+## Key features
+
+### Zinit plugin stack (`.zshrc`)
+
+- **zsh-autosuggestions** — inline fish-style suggestions
+- **zsh-syntax-highlighting** — live command coloring
+- **zsh-completions** — extra completion definitions
+- **zsh-history-substring-search** — up/down searches from prefix
+- **starship** — installed via zinit from GitHub releases
+
+### Async dotfiles pull
+
+On shell start, a background job pulls `--ff-only` from origin once per day (marker at `~/.cache/.dotfiles-pull`). Silent, non-blocking.
+
+### Starship prompt (`.starship.toml`)
+
+Two-line layout:
+- **Line 1**: docker container indicator → docker-compose status → git branch/status → (fill) → directory
+- **Line 2**: `➤` character (green=ok, red=error)
+- **Right**: command duration (>5s) → user@host → time
+
+Custom modules detect `/.dockerenv` for container awareness and parse `docker compose ps` for service status.
+
+### fzf integration (`.zshrc`)
+
+Sources fzf keybindings and completion when available. Default opts: `--height 40% --reverse`.
+
+### Project switcher — `pj` (`.zshrc`)
+
+Fuzzy-finds directories under `/projects` or `~/projects` using fzf. `pj foo` pre-fills the query.
+
+### Yazi wrapper — `y` (`.zshrc`)
+
+Wraps the yazi file manager so the shell `cd`s to wherever you navigated on exit.
+
+### Docker compose aliases (`.zshrc`)
+
+| Alias | Expands to |
+|---|---|
+| `,dcdu` | `docker compose --profile dev up service_dev --force-recreate --detach` |
+| `,dcdd` | `docker compose --profile dev down --remove-orphans` |
+| `,dcdl` | `docker compose --profile dev logs -f service_dev` |
+| `dcu` | `docker compose up --force-recreate --detach` |
+| `dcd` | `docker compose down --remove-orphans` |
+| `dcl` | `docker compose logs -f` |
+
+### Tmux aliases (`.zshrc`)
+
+| Alias | What it does |
+|---|---|
+| `tmuxr` | Attach-or-create session named "auto" |
+| `tmuxn` | Same + opens a new window |
+| `tmuxa NAME` | Attach-or-create a named session |
+
+### Tmux keybindings (`.tmux.conf`)
+
+- **Shift+Left/Right** — switch windows (no wrap)
+- **PgUp/PgDn** — swap window position left/right
+- **prefix+f** — fzf fuzzy window switcher
+- **prefix+R** — rename window
+- Splits retain current path. 1-indexed windows, auto-rename shows `command@directory`.
+
+### Vim (`.vimrc`)
+
+Space as leader. `jk` exits insert mode. Persistent undo in `~/.vim/undo/`. Arrow keys disabled (hjkl only). Mouse enabled. Smart case search. 8-line scroll margin.
+
+### Utility functions (`.zshrc`)
+
+| Function | Purpose |
+|---|---|
+| `clip` | Pipe stdin to system clipboard via OSC 52 (works over SSH/tmux) |
+| `mkcd DIR` | mkdir + cd in one step |
+| `cdtmp [label]` | Create and cd into a timestamped temp dir under `~/tmp/` |
+
+### Other aliases (`.zshrc`)
+
+- `c` → `claude`
+- `,cd` → `claude --dangerously-skip-permissions` (with sandbox flag)
+- `zshreload` → `exec zsh`
+- `LATEST` — global alias expanding to `*(om[1])` (most recently modified file)
+
+### Shell options (`.zshrc`)
+
+Extended history (100k lines, shared, deduped). Case-insensitive globbing. Auto-pushd on cd. No flow control (Ctrl-S disabled). Emacs keybindings with Ctrl+X,E / Alt+E for `$EDITOR`.
+
+### Machine-local overrides
+
+`~/.zshrc-extra` is sourced at the end if it exists — for per-machine config that doesn't belong in version control.