diff --git a/README.md b/README.md
index ec8c552..df16a97 100644
--- a/README.md
+++ b/README.md
@@ -1,43 +1,218 @@
 # mates-macos-setup
 
-macOS workstation setup a Hermes CLI instalace.
-Šablony a konfigurace pro `brew`, `osx-defaults`, `fish` shell a `Hermes` AI agenta.
+Nastavení macOS workstation + Hermes AI asistent.
+Kompletní automatizace: Homebrew, macOS defaults, Fish shell, Hermes CLI.
 
-## Struktura
+> **Jsi začátečník?** Čti od [Začínáme](#zaciname) – vše krok za krokem.
 
-```
-Brewfile                          # Všechny nainstalované CLI/GUI aplikace
-osx-defaults.sh                   # macOS Finder/Dock/klávesnice defaults
-configure-fish.sh                 # Fish shell aliasy
-install-hermes.sh                 # Hermes CLI instalace
-configure-hermes.sh               # Hermes konfigurace (API klíč v keychainu)
-hermes-config.example.yml         # Ukázková konfigurace
-```
+---
 
-## Quickstart (nový Mac)
+## 📦 Co tu je
+
+| Soubor | Co dělá |
+|---|---|
+| `Brewfile` | Seznam všech aplikací (Homebrew) |
+| `osx-defaults.sh` | Nastaví Finder, Dock, klávesnici, Safari |
+| `configure-fish.sh` | Nastaví Fish shell s aliasy |
+| `install-hermes.sh` | Nainstaluje Hermes AI agenta |
+| `configure-hermes.sh` | Nastaví Hermes (API klíč z keychainu) |
+| `hermes-config.example.yml` | Ukázková konfigurace Hermes |
+
+---
+
+## 🚀 Začínáme (nový Mac)
+
+### Krok 1: Nainstaluj Homebrew
 
 ```bash
-# 1. Homebrew
 /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
-
-# 2. Všechny aplikace
-brew bundle --file=Brewfile
-
-# 3. macOS defaults
-bash osx-defaults.sh
-
-# 4. Fish shell
-bash configure-fish.sh
-
-# 5. Hermes
-bash install-hermes.sh
-bash configure-hermes.sh
 ```
 
-## Detailní návod
+### Krok 2: Naklonuj repo
 
-Viz [README.md](README.md) – co každý skript dělá, bezpečnost, aktualizace.
+```bash
+git clone http://<server-ip>:3000/mates/mates-macos-setup.git
+cd mates-macos-setup
+```
 
-## Licence
+### Krok 3: Nainstaluj všechny aplikace
+
+```bash
+brew bundle --file=Brewfile
+```
+
+Tím se nainstaluje **všechny aplikace** z Brewfile:
+- **CLI:** fish, eza, fd, bat, fzf, btop, jq, yq, ffmpeg, deno, python, exiftool, ...
+- **GUI:** Chrome, Firefox, Discord, WhatsApp, Bitwarden, Notion, Obsidian, VSCode, OBS, VLC, Spotify, ...
+
+### Krok 4: macOS defaults
+
+```bash
+bash osx-defaults.sh
+```
+
+Tím se nastaví:
+- **Finder:** zobrazit skryté soubory, přípony, cestovní panel, icnv (ikony)
+- **Dock:** magnification, skrýt nedávné aplikace, tilesize=33
+- **Trackpad:** pravý klik, momentum scroll
+- **Terminal:** profil Clear Dark
+
+### Krok 5: Fish shell
+
+```bash
+bash configure-fish.sh
+```
+
+Tím se nastaví `~/.config/fish/config.fish` s aliasy:
+
+| Alias | Co dělá |
+|---|---|
+| `update` | Spustí `~/Skripty/update-macos.sh` |
+| `dk-update`, `dk-backup`, `dk-cleanup`, ... | Docker skripty |
+| `dk-list` | Seznam záloh |
+| `dk-nas-mount`, `dk-nas-status` | NAS mount |
+
+### Krok 6: Hermes (volitelné)
+
+```bash
+bash install-hermes.sh    # nainstaluje Hermes
+bash configure-hermes.sh  # nastaví API klíč z keychainu
+```
+
+**Co dělá configure-hermes.sh:**
+- Hledá API klíč v macOS keychainu (`security find-generic-password -s "hermes:api"`)
+- Vytvoří `~/.config/hermes/config.yml`
+- Nastaví `HERMES_API_KEY` v shellu
+
+---
+
+## 📚 Detail ke každému souboru
+
+### `Brewfile`
+
+Seznam všech CLI a GUI aplikací. Spustí se přes `brew bundle --file=Brewfile`.
+
+**Obsahuje:**
+
+```ruby
+# CLI (formulas)
+brew "fish"       # Defaultní shell
+brew "eza"        # ls náhrada
+brew "fd"         # find náhrada
+brew "bat"        # cat náhrada
+brew "btop"       # System monitor
+brew "jq"         # JSON parser
+brew "ffmpeg"     # Video/audio konverze
+brew "deno"       # JavaScript runtime
+# ... další
+
+# GUI (casks)
+cask "google-chrome"
+cask "bitwarden"
+cask "obsidian"
+cask "visual-studio-code"
+# ... další
+```
+
+### `osx-defaults.sh`
+
+Nastaví **tyto** hodnoty (1:1 kopie tvého aktuálního setupu):
+
+- **Finder:** AppleShowAllFiles, ShowPathbar, ShowStatusBar, icnv, Date Modified, PfHm
+- **Dock:** magnification, show-recents=0, tilesize=33
+- **Trackpad:** TrackpadRightClick, TrackpadMomentumScroll, TrackpadThreeFingerDrag=0
+- **Terminal:** Clear Dark profil
+- **TextEdit:** NSDocumentSuppressTempVersionStoreWarning
+
+### `configure-fish.sh`
+
+Vytvoří `~/.config/fish/config.fish`:
+
+```fish
+# Aliasy pro docker skripty
+alias dk-update="..."
+alias dk-backup="..."
+alias dk-cleanup="..."
+
+# Zakázání welcome message
+set -g fish_greeting ""
+
+# Hermes – zajisti ~/.local/bin v PATH
+fish_add_path "$HOME/.local/bin"
+```
+
+### `install-hermes.sh`
+
+- Nainstaluje Hermes přes `pip install --user hermes-agent`
+- Přidá do PATH v `~/.zshrc` a Fish config
+- Vytvoří aliasy `h`, `hchat`, `hgit`, `hd` v Fish
+
+### `configure-hermes.sh`
+
+- Hledá API klíč v macOS keychainu (služba: `hermes:api`)
+- Vytvoří `~/.config/hermes/config.yml` s:
+  - `provider: anthropic`
+  - `model: claude-sonnet-4.5`
+  - `sandbox` (allow/deny seznam příkazů)
+  - `integrations.gitea`, `integrations.docker`, `integrations.git`
+- Nastaví `HERMES_API_KEY` v `~/.zshrc` a Fish config
+
+### `hermes-config.example.yml`
+
+Ukázková konfigurace. Slouží jako šablona – **reálná konfigurace je v `~/.config/hermes/config.yml`** (generovaná `configure-hermes.sh`).
+
+---
+
+## 🔐 Bezpečnost
+
+- ✅ **FileVault** – povolit v System Settings → Privacy & Security
+- ✅ **Firewall** – povolit v System Settings → Network → Firewall
+- ✅ **API klíč Hermes** – uložen v **macOS keychainu**, nikdy v config.yml
+- ✅ **Hesla NAS** – uložena v keychainu, ne v skriptech
+- ✅ **SSH klíče** – passphrase v keychainu
+
+---
+
+## 🏗 Struktura
+
+```
+mates-macos-setup/
+├── README.md                       # Tento soubor
+├── LICENSE                         # MIT
+├── Brewfile                        # Seznam aplikací
+├── osx-defaults.sh                # macOS nastavení
+├── configure-fish.sh              # Fish aliasy
+├── install-hermes.sh              # Hermes instalace
+├── configure-hermes.sh            # Hermes konfigurace
+└── hermes-config.example.yml      # Ukázková konfigurace
+```
+
+---
+
+## 🔄 Aktualizace
+
+```bash
+# Homebrew
+brew update && brew upgrade && brew cleanup
+
+# macOS
+System Settings → Software Update
+```
+
+---
+
+## 📚 Související
+
+- **Jotty:** knowledge base
+- **mates-install-scripts:** bash skripty pro Docker
+- **mates-ansible:** Ansible pro nový server
+
+---
+
+## 📜 Licence
 
 MIT – viz [LICENSE](LICENSE)
+
+---
+
+**Poslední update:** 2026-08-01