docs(readme): rewrite stub into proper entry point

The previous readme was a 17-line stub with a typo (configration), a
single Docker snippet, and a stale "Add mason.nvim" road map item that
shipped years ago. Replace it with an entry point that actually
explains the repo: the dotfm + per-tool setup two-layer design, a
correct quick-start (dotfm apply as the everyday flow, setup.{ps1,sh}
as per-tool bootstrap fallback), a tool catalogue table, and pointers
to docs/STRUCTURE.md for the full design.

Author: ShortArrow

readme.md

@@ -1,8 +1,53 @@
 # dotfiles
 
-configration of @ShortArrow
+[![Deploy Hugo site to Pages](https://github.com/ShortArrow/dotfiles/actions/workflows/hugo.yml/badge.svg)](https://github.com/ShortArrow/dotfiles/actions/workflows/hugo.yml)
 
-## Quick Test on Docker
+Cross-platform dotfiles of [@ShortArrow](https://github.com/ShortArrow). Same end state on Windows / Linux / macOS via a single source of truth (`dotfm.toml`).
+
+## How it works
+
+Two parallel layers produce the same symlink tree — pick whichever is bootstrappable on the host:
+
+1. **[`dotfm`](https://github.com/ShortArrow/dotfm)** — small Rust binary, reads `dotfm.toml` and applies the link rules. Recommended for everyday use.
+2. **`<tool>/setup.ps1` / `<tool>/setup.sh`** — bootstrap launchers used when `dotfm` isn't available yet (fresh boxes, no Rust). They consume the same `dotfm.toml` through `lib/_lib.{ps1,sh}`.
+
+Running both is a no-op the second time. See [`docs/STRUCTURE.md`](docs/STRUCTURE.md) for the full design (decision matrix for `symlink` / `copy` / `post_apply` / `script`, security rules, how to add a tool).
+
+## Quick start
+
+The everyday flow is `dotfm apply`. The `<tool>/setup.{ps1,sh}` launchers exist as **per-tool** fallbacks for hosts where `dotfm` isn't installed yet — each one only touches its own tool.
+
+### With dotfm (recommended)
+
+```bash
+# Install dotfm (https://github.com/ShortArrow/dotfm), then:
+git clone https://github.com/ShortArrow/dotfiles.git ~/dotfiles
+cd ~/dotfiles
+dotfm apply       # apply every tool listed in dotfm.toml
+dotfm status      # verify the symlinks are in place
+```
+
+Windows is the same — clone, `cd`, `dotfm apply` from PowerShell.
+
+### Without dotfm (per-tool bootstrap)
+
+When you can't install Rust yet, run only the tools you need. Each script is idempotent.
+
+```bash
+./bash/setup.sh
+./git/setup.sh
+./tmux/setup.sh
+# ...
+```
+
+```pwsh
+.\pwsh\setup.ps1
+.\git\setup.ps1
+.\glazewm\setup.ps1
+# ...
+```
+
+### Docker quick test
 
 ```bash
 git clone https://github.com/ShortArrow/dotfiles.git
@@ -11,6 +56,25 @@ docker compose up -d --build
 docker compose exec nvim /bin/bash -c nvim
 ```
 
-## Road Map
+## What's inside
+
+| Area | Tools |
+| --- | --- |
+| Shells / prompt | bash, pwsh, clink, starship |
+| Terminals | wezterm, alacritty, windows-terminal |
+| Editors | neovim (`nvim/src/`), vim, vscode, zed |
+| Multiplexers / WM | tmux, zellij, glazewm, hyprland, i3wm |
+| Git stack | git, lazygit, neogit, git-foresta |
+| Tool manager | mise (`mise/src/config.toml`) — node, python, go, java, rust-cli, aqua |
+| File / nav | yazi, fzf, zoxide, lsd, fd, ripgrep |
+| Misc | claude (skills + statusline), runex, ssh, keyd |
+
+Each top-level directory contains the actual config files plus optional `setup.{ps1,sh}` and `doctor.ps1`. The full mapping (which file goes where on which OS) lives in [`dotfm.toml`](dotfm.toml).
+
+## Branch strategy
+
+`main` only. Topic branches are optional; merge back to `main`.
+
+## License
 
-- Add [mason.nvim](https://github.com/williamboman/mason-lspconfig.nvim)
+See [`LICENSE`](LICENSE).