docs: kompletne prepsat README pro zacatecniky

- Strukturovany obsah (tabulky, seznamy)
- Ceske popisy, vysvetleni co je co
- Začínáme sekce (krok za krokem)
- Detailni navody pro kazdy soubor/sluzba
- Souvisejici repo + licence
- Konzistentni format napric 6 repo

README.md

@@ -1,31 +1,142 @@
 # mates-infra
 
-Hlavní index pro home infrastructure as code projekty.
+Profil a rozcestník pro **home infrastructure as code** projekty.
-Toto repo slouží jako rozcestník – detailní dokumentace je v Jotty knowledge base.
+Toto je **úvodní stránka** celého GitHub/Gitea profilu.
 
-## Repozitáře
+> **Jsi tu nový?** Čti od [Začínáme](#zaciname) – vše krok za krokem.
 
-| Repo | Účel | URL |
+---
+
+## 🏠 Co je mates-infra?
+
+Sada **6 repozitářů** pro správu domácí infrastruktury:
+- Docker služby (Portainer, Vaultwarden, Gitea, Nextcloud, …)
+- Ansible pro nový server
+- Bash skripty pro správu Dockeru
+- macOS workstation setup
+- Metadata NAS projektů
+
+Vše **verzované**, **replikovatelné** a **připravené pro obnovu** na jiném stroji.
+
+---
+
+## 📦 Repozitáře
+
+| Repo | Co tu je | Kdy použít |
 |---|---|---|
-| `mates-docker-services` | Docker Compose pro 14 služeb (portainer, npm, vaultwarden, gitea, jotty, nextcloud, další) | http://<server-ip>:3000/mates/mates-docker-services |
+| **`mates-docker-services`** | 14× `docker-compose.yml` (portainer, npm, vaultwarden, gitea, jotty, nextcloud, …) | Když chceš **nasadit novou službu** |
-| `mates-ansible` | Ansible playbooky (bootstrap, deploy, update, security) | http://<server-ip>:3000/mates/mates-ansible |
+| **`mates-ansible`** | 4× Ansible playbook + 5 rolí | Když chceš **připravit nový server** |
-| `mates-install-scripts` | Bash skripty pro správu Dockeru (záloha, update, cleanup, mount NAS) | http://<server-ip>:3000/mates/mates-install-scripts |
+| **`mates-install-scripts`** | 7× bash skript + aliasy `dk-*` | Když chceš **spravovat Docker** (update/backup/cleanup) |
-| `mates-macos-setup` | macOS workstation (Brewfile, Fish, Hermes) | http://<server-ip>:3000/mates/mates-macos-setup |
+| **`mates-macos-setup`** | Brewfile + osx-defaults + Fish + Hermes | Když chceš **nastavit macOS** |
-| `mates-home-nas-tools` | Metadata k projektům na NAS (bez binárek) | http://<server-ip>:3000/mates/mates-home-nas-tools |
+| **`mates-home-nas-tools`** | Metadata k NAS projektům (bez binárek) | Když hledáš **archiv na NAS** |
 
-## Rychlý start (nový server)
+---
+
+## 🚀 Začínáme
+
+### Krok 1: Naklonuj hlavní repo
 
 ```bash
-# Klonuj potřebná repo
+git clone http://<server-ip>:3000/mates/mates-infra.git
-git clone http://<server-ip>:3000/mates/mates-install-scripts.git
+cd mates-infra
-git clone http://<server-ip>:3000/mates/mates-docker-services.git
-
-# Nasaď služby
-cd mates-docker-services/<sluzba>
-cp .env.example .env
-docker compose up -d
 ```
 
-## Licence
+Toto repo slouží jako **rozcestník** – otevři ho v prohlížeči nebo v editoru a podívej se na ostatní repozitáře.
+
+### Krok 2: Najdi co potřebuješ
+
+| Chci... | Jdi do... |
+|---|---|
+| Připravit nový server | `mates-ansible` |
+| Nasadit Docker službu | `mates-docker-services` |
+| Spravovat Docker (zálohy, update) | `mates-install-scripts` |
+| Nastavit nový Mac | `mates-macos-setup` |
+| Najít archiv na NAS | `mates-home-nas-tools` |
+
+### Krok 3: Klonuj potřebné repo
+
+```bash
+git clone http://<server-ip>:3000/mates/mates-<repo>.git
+cd mates-<repo>
+cat README.md    # vse je v README
+```
+
+---
+
+## 🏗 Jak to celé funguje
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ mates-infra (toto repo)                                     │
+│ Hlavni index, rozcestnik, profil                            │
+└─────────────────────────────────────────────────────────────┘
+            │
+            ├── mates-docker-services     # Implementace (Docker)
+            ├── mates-ansible              # Implementace (Ansible)
+            ├── mates-install-scripts      # Implementace (bash)
+            ├── mates-macos-setup          # Implementace (macOS)
+            └── mates-home-nas-tools       # Metadata k NAS
+```
+
+**Dokumentace** (architektura, návody, rozhodnutí) je v **Jotty knowledge base** – ne v gitu.
+
+---
+
+## 🎯 Typické scénáře
+
+### "Chci připravit nový server od nuly"
+1. Připrav `inventory.yml` a SSH klíč
+2. Spusť `ansible-playbook -i inventory.yml playbooks/priprav-novy-server.yml`
+3. Nasaď služby: `ansible-playbook -i inventory.yml playbooks/nasad-sluzby.yml`
+
+→ Detail v `mates-ansible/README.md`
+
+### "Chci přidat novou Docker službu"
+1. Přidej složku `moje-sluzba/` do `mates-docker-services/`
+2. Vytvoř `docker-compose.yml`, `.env.example`, `README.md`
+3. Commitni a pushni
+
+→ Detail v `mates-docker-services/README.md`
+
+### "Chci zálohovat Docker na NAS"
+1. Nastav `DOCKERY` env proměnnou
+2. Spusť `dk-backup --auto` (cron-friendly)
+3. Zálohy jsou v `/Volumes/Backups/Prace/server-backups/`
+
+→ Detail v `mates-install-scripts/README.md`
+
+### "Chci nastavit nový Mac"
+1. Nainstaluj Homebrew
+2. Spusť `brew bundle --file=Brewfile`
+3. Spusť `osx-defaults.sh`, `configure-fish.sh`, `install-hermes.sh`
+
+→ Detail v `mates-macos-setup/README.md`
+
+---
+
+## 🔐 Bezpečnost
+
+- ✅ **Žádné PII v git** – IP adresy, emaily, klíče nahrazeny placeholdery
+- ✅ **API tokeny v macOS keychainu**, ne v URL ani v env
+- ✅ **SSH klíče** pro přístup k serverům (hesla zakázána)
+- ✅ **Historie git je čistá** – bez PII v minulých commitech
+
+---
+
+## 📚 Dokumentace
+
+| Co hledáš | Kde je |
+|---|---|
+| Architektura | Jotty knowledge base |
+| Postupy | `README.md` každého repo |
+| Reference | `LICENSE`, `.gitignore`, `.env.example` |
+
+---
+
+## 📜 Licence
 
 MIT – viz [LICENSE](LICENSE)
+
+---
+
+**Home lab · 2026 · Poslední update:** 2026-08-01