diff --git a/README.md b/README.md
index 49399d0..b2b4e72 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,6 @@
 # dotfiles
 
-NixOS flake-based system and user configuration. Managed with [Jujutsu (jj)](https://github.com/martinvonz/jj).
+The repository contains system and user configuration as a Nix flake. Jujutsu (jj) provides version control.
 
 ## Hosts
 
@@ -12,59 +12,54 @@ NixOS flake-based system and user configuration. Managed with [Jujutsu (jj)](htt
 | reg | Server | x86_64 | Tailscale, SSH, PDS |
 | wakuna | Server | aarch64 | ARM — built as SD image |
 
-## Stack
+## Components
 
-- **System**: NixOS unstable, Lix, flake-parts, easy-hosts
-- **User**: home-manager, Catppuccin (macchiato)
-- **Desktop**: Niri / Noctalia Shell, Ghostty, Helium browser
-- **Dev**: Nushell, Starship, Atuin, Zellij, Helix (custom fork), Jujutsu, Docker, direnv
-- **AI**: OpenCode — custom agents, skills, MCP (GitHub, Outline, Linear, Sentry)
-- **Secrets**: sops-nix (age)
-- **Cache**: Attic → nix-cache.karitham.dev/dotfiles
+- System: NixOS unstable, Lix, flake-parts, easy-hosts
+- User: home-manager, Catppuccin (macchiato)
+- Desktop: Niri/Noctalia Shell, Ghostty, Helium browser
+- Dev: Nushell, Starship, Atuin, Zellij, Helix (custom fork), Jujutsu, Docker, direnv
+- AI: OpenCode with custom agents, skills, MCP (GitHub, Outline, Linear, Sentry)
+- Secrets: sops-nix (age)
+- Cache: Attic at nix-cache.karitham.dev/dotfiles
 
-## Quick Start
+## Commands
 
 ```bash
 nh os switch                    # rebuild & switch (uses ~/dotfiles)
 nixos-rebuild switch --flake .#kiwi  # explicit host
 nix build .#wakuna-image        # SD image for wakuna
-nix fmt                         # format all files (nixfmt, nufmt, biome)
+nix fmt                         # format (nixfmt, nufmt, biome)
 ```
 
-## Structure
+`nh os switch` rebuilds and switches for the current host and assumes the repository at `~/dotfiles`. `nixos-rebuild switch` targets an explicit host. `nix build` produces the `wakuna` image. `nix fmt` formats the repository.
+
+## Repository structure
 
 ```
 flake.nix              # Flake entry point
-flake-parts.nix        # Flake-parts hub: systems, packages, module exports
+flake-parts.nix        # Systems, packages, module exports
 modules/
-├── core.nix           # my.username option, user groups
-├── nix.nix            # Lix config, Attic cache push
+├── core.nix           # my.username, user groups
+├── nix.nix            # Lix, Attic cache push
 ├── locale.nix         # Europe/Paris, en_US + fr_FR
-├── home/              # home-manager + Catppuccin
+├── home/              # home-manager, Catppuccin
 ├── desktop/           # Niri/Noctalia, Ghostty, audio, apps
 ├── dev/               # Nushell, Helix, jj, Docker, OpenCode
 ├── server/            # Tailscale, SSH
 ├── wsl/               # NixOS-WSL
 ├── tags/              # work, secureboot
-└── opencode/          # AI assistant: agents, skills, plugins, commands
+└── opencode/          # Agents, skills, plugins, commands
 systems/
-├── default.nix        # easy-hosts host definitions
+├── default.nix        # easy-hosts definitions
 ├── kiwi/ belaf/ ozen/ reg/ wakuna/
-pkgs/                  # Custom package derivations
+pkgs/                  # Custom derivations
 secrets/               # sops-nix encrypted (age)
 ```
 
-## Module System
-
-`flake.nix` imports `flake-parts.nix`, which defines the supported systems, custom packages, and exports NixOS/home-manager modules.
-
-Hosts are defined declaratively in `systems/default.nix` via [easy-hosts](https://github.com/tgirlcloud/easy-hosts). Each host has a **class** (`desktop`, `server`, `wsl`) that pulls in the corresponding module group, and optional **tags** (`work`, `secureboot`) that layer in additional config.
-
-`desktop.enable = true` cascades to: wm, terminal, audio, apps, and sub-features.
-`dev.enable = true` cascades to: shell, editor, vcs, tools, opencode, Docker.
+## Module system
 
-Most features provide both a NixOS module (`nixos.nix`) and a home-manager module (`home.nix`).
+`flake.nix` imports `flake-parts.nix`. `flake-parts.nix` declares supported systems, custom packages, and module exports. `systems/default.nix` declares hosts through [easy-hosts](https://github.com/tgirlcloud/easy-hosts). Each host has a class (`desktop`, `server`, `wsl`) that includes the corresponding module group. Tags (`work`, `secureboot`) add further configuration. `desktop.enable` includes window manager, terminal, audio, applications, and sub-features. `dev.enable` includes shell, editor, version control, tools, OpenCode, and Docker. Each feature provides `nixos.nix` for the system and `home.nix` for the user.
 
-## Secrets
+## Secret management
 
-sops-nix with age encryption. Files in `secrets/` are decrypted at build time. Keys and creation rules are in `.sops.yaml`.
+sops-nix with age encryption manages secrets. Files in `secrets/` decrypt at build time. `.sops.yaml` defines keys and creation rules.