image-updater: definicja wdrażana przez ArgoCD zamiast wklepywanej ręcznie

Astroklient zbudował się poprawnie, ale jego obraz nie schodził do klastra. Przyczyna nie leżała ani w CI, ani w rejestrze: CRD ImageUpdater w klastrze miał CZTERY obrazy (data, logic, presentation, render), a plik w gicie sześć. Brakowało astrodemo I astroklienta. `image-updater.yaml` nie był w kustomization.yaml, więc ArgoCD go nie nakładał. Dopisanie usługi do pliku nie robiło zatem nic — listy nikt nie stosował. ODWRACAM DECYZJĘ UDOKUMENTOWANĄ W TYM REPO. README twierdziło, że wyłączenie jest celowe: resource stoi w ns argocd, poza namespace docelowym aplikacji, i jest konfiguracją kontrolera, a nie aplikacji. Rozumowanie nie było głupie, ale nie wytrzymało praktyki — ręczny krok zapomniano dwa razy w ciągu dwóch tygodni, najpierw dla astrodemo, potem dla astroklienta. Najgorsza była CICHOŚĆ rozjazdu. Plik w gicie wyglądał poprawnie, git log pokazywał dopisanie usługi, a objawem był obraz, który „się nie deployuje" — co kieruje podejrzenia na CI albo na rejestr, czyli wszędzie poza właściwe miejsce. Diagnoza wymaga porównania pliku ze stanem klastra, a nikt nie porównuje rzeczy, o której nie wie, że mogą się różnić. Przeszkody technicznej nie było: projekt ArgoCD dopuszcza dowolną przestrzeń nazw (destinations: '*'), a dry-run serwerowy przyjmuje resource bez zastrzeżeń. W README zostaje wyjaśnienie, dlaczego jest w kustomization mimo wcześniejszego uzasadnienia — razem z prośbą, żeby przy ewentualnym wyjmowaniu usunąć też ten akapit. Inaczej następna osoba przeczyta powód, którego już nie ma. Zweryfikowane: kustomize build 38 obiektów (było 37), dry-run serwerowy aktualizuje istniejący CRD. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
build: automatic update of conjurer
2026-08-27 21:18:45 +02:00 · 2026-08-27 18:10:20 +00:00 · 2026-08-27 18:10:18 +00:00 · 2026-08-27 15:42:12 +00:00 · 2026-08-27 15:40:08 +00:00 · 2026-08-27 16:10:12 +02:00
25 changed files with 2188 additions and 17 deletions
@@ -0,0 +1,215 @@
+# astrodemo — wdrożenie wersji demo (PRE-28/29)
+
+Osobna usługa o dwóch funkcjach: **dodanie pliku bazy** i **zapytanie o
+interpretację urodzeniową**. Opis aplikacji: `services/astrodemo/README.md`
+w repo aplikacji.
+
+---
+
+## Jak to jest odizolowane
+
+```
+astrodemo  →  logic-demo  →  data-demo  →  /mnt/Tank1/astrololo-demo
+                                              └── klientA/   ← pula konta
+                                              └── klientB/   ← pula konta
+```
+
+**Oryginalne bazy są dla demo nieosiągalne.** Nie chodzi o uprawnienia: demo ma
+własną warstwę danych, pracującą na osobnym udziale, pustym na starcie.
+
+Dlaczego osobna jest też **warstwa logiczna**: zna ona jeden adres warstwy danych,
+więc astrodemo korzystający z produkcyjnej logiki i tak trafiłby na produkcyjne
+bazy. Izolacja musi sięgnąć obu warstw naraz, inaczej nie ma jej wcale.
+
+**Każde konto ma własną pulę** — swój podkatalog na tym udziale. Konta nie widzą
+swoich plików nawzajem ani w liście, ani w wynikach wyszukiwania. Pula bierze się
+z **loginu zalogowanej osoby**, nigdy z pola formularza.
+
+---
+
+## Krok 1 — udział `astrololo-demo` na TrueNAS
+
+Ta sama procedura co przy `astrololo-state`, więc jeśli tamten działa, ten też
+zadziała. Po SSH na NAS:
+
+```bash
+sudo zfs create Tank1/astrololo-demo    # albo: sudo mkdir -p /mnt/Tank1/astrololo-demo
+```
+
+```bash
+midclt call sharing.nfs.query '[["path","=","/mnt/Tank1/astrololo-demo"]]' \
+  | python3 -m json.tool
+```
+
+**Pusta lista `[]`** — twórz:
+
+```bash
+midclt call sharing.nfs.create '{
+  "path": "/mnt/Tank1/astrololo-demo",
+  "comment": "astrololo — pule kont wersji demo (PRE-29)",
+  "hosts": ["192.168.1.73", "192.168.1.80", "192.168.1.81", "192.168.1.82"],
+  "enabled": true,
+  "ro": false,
+  "mapall_user": "root",
+  "mapall_group": "root"
+}'
+```
+
+**Coś zwróciło** — weź `id` i użyj `sharing.nfs.update <ID>` z tą samą treścią.
+
+```bash
+midclt call service.restart nfs
+sudo exportfs -v | grep astrololo-demo
+```
+
+Musi tam być `rw`. Sprawdź jeszcze zapis z węzła — to jest ten test, którego
+zabrakło przy poprzednim udziale:
+
+```bash
+ssh <węzeł> 'sudo mkdir -p /mnt/t && sudo mount -t nfs 192.168.1.34:/mnt/Tank1/astrololo-demo /mnt/t \
+  && sudo touch /mnt/t/proba && echo ZAPIS-OK || echo ZAPIS-NIE; sudo rm -f /mnt/t/proba; sudo umount /mnt/t'
+```
+
+---
+
+## Krok 2 — konta demo
+
+Każde konto to osobna pula, więc **rozdajesz konta, nie jedno hasło**.
+
+Hasła najlepiej jako hash — wtedy nie leżą nigdzie jawnie (skrypt jest w repo
+aplikacji, `services/presentation/scripts/make_user.py`):
+
+```bash
+python scripts/make_user.py klientA     # wypisze: scrypt$…
+python scripts/make_user.py klientB
+```
+
+```bash
+kubectl -n astrololo create secret generic astrololo-astrodemo \
+  --from-literal=ASTRODEMO_USERS='klientA:scrypt$…,klientB:scrypt$…' \
+  --from-literal=SESSION_SECRET="$(openssl rand -hex 32)"
+```
+
+`SESSION_SECRET` podpisuje ciasteczka sesji (LOG-34). **Pod bez niego celowo nie
+wstanie.** Jest WŁASNY, nie ten z pełnej aplikacji: demo i produkcja nie mają
+powodu uznawać nawzajem swoich sesji.
+
+> **Zdalne unieważnienie w demo działa inaczej niż w pełnej wersji.** Demo nie ma
+> własnego wolumenu, więc nie ma gdzie trzymać licznika sesji. Zamiast tego:
+> usunięcie konta z `ASTRODEMO_USERS` albo zmiana jego hasła **natychmiast ubija jego
+> otwarte sesje** — bo odcisk poświadczenia wpisany w ciasteczko przestaje pasować.
+> Rotacja `SESSION_SECRET` wylogowuje wszystkich naraz.
+
+### Dodanie konta później
+
+```bash
+STARE=$(kubectl -n astrololo get secret astrololo-astrodemo -o jsonpath='{.data.ASTRODEMO_USERS}' | base64 -d)
+
+kubectl -n astrololo create secret generic astrololo-astrodemo \
+  --from-literal=ASTRODEMO_USERS="${STARE},klientC:scrypt\$…" \
+  --dry-run=client -o yaml | kubectl apply -f -
+
+kubectl -n astrololo rollout restart deploy/astrodemo
+```
+
+### Odebranie dostępu
+
+Usuń wpis z `ASTRODEMO_USERS` tą samą drogą. **Pula zostaje na udziale** — pliki
+klienta nie znikają, tylko przestaje być komu je pokazywać.
+
+---
+
+## Krok 3 — tag obrazu
+
+**Zanim wdrożysz.** CI pcha obrazy wyłącznie pod tagiem ośmioznakowym
+(`TAG=${GITHUB_SHA::8}`) i **nigdy nie pcha `latest`**. Manifest z `newTag: latest`
+zatrzyma się na `ImagePullBackOff`, co wygląda na problem z rejestrem albo siecią,
+a jest zwykłym brakiem takiego tagu.
+
+Po zmergowaniu zmian w repozytorium aplikacji i zbudowaniu obrazu:
+
+```bash
+TAG=$(git -C ~/git/astrololo rev-parse --short=8 master)
+echo "$TAG"          # ten sam ciąg musi być widoczny w logu zadania „build"
+```
+
+Wpisz go jako `newTag` przy `astrololo-astrodemo` w `kustomization.yaml`. Kolejne
+wersje podbija już image-updater sam — pod warunkiem, że obraz jest na jego liście
+(`image-updater.yaml`), co ten PR załatwia.
+
+## Krok 4 — wdrożenie
+
+```bash
+kubectl apply -k astrololo
+kubectl -n astrololo rollout status deploy/data-demo deploy/logic-demo deploy/astrodemo
+```
+
+Sprawdzenie na czas jednej sesji, bez wystawiania na świat:
+
+```bash
+kubectl -n astrololo port-forward deploy/astrodemo 8005:8005
+```
+
+Wejście z zewnątrz jest już w `ingress.yaml`: host **astrodemo.czernobog.pl**,
+z przekierowaniem z http na https i tym samym certyfikatem co astrololo
+(`tls.yaml` obejmuje oba hosty).
+
+Osobny host, a nie ścieżka `/demo` pod adresem astrololo — CELOWO. Ścieżka
+dzieliłaby z pełną aplikacją pochodzenie w rozumieniu przeglądarki, czyli
+i ciasteczka: wejście do jednej ruszałoby sesję w drugiej.
+
+Pozostaje wpis DNS: **astrodemo.czernobog.pl musi wskazywać na ten sam adres co
+astrololo.czernobog.pl**. Bez tego Traefik nigdy nie zobaczy żądania.
+**Celowo nie zakładam tego za Ciebie**: to decyzja, pod jakim adresem świat
+zobaczy demo.
+
+---
+
+## Import puli klienta do pełnej aplikacji
+
+Sedno całego układu: klient, który przechodzi na pełną wersję, **nie traci
+dotychczasowych wgrań**. Jego pula to jeden katalog.
+
+**1. Zobacz, co tam jest** (na NAS):
+
+```bash
+LOGIN=klientA
+sudo ls -la /mnt/Tank1/astrololo-demo/$LOGIN/
+```
+
+**2. Sprawdź kolizje nazw** z bazami produkcyjnymi:
+
+```bash
+comm -12 \
+  <(cd /mnt/Tank1/astrololo-demo/$LOGIN && ls *.xlsx 2>/dev/null | sort) \
+  <(cd /mnt/Tank1/astrololo && ls *.xlsx 2>/dev/null | sort)
+```
+
+Pusto = brak kolizji. Cokolwiek się wypisze, przenieś ręcznie pod inną nazwą —
+**nie nadpisuj bazy produkcyjnej**.
+
+**3. Skopiuj** (`-n` = nie nadpisuj niczego, co już jest):
+
+```bash
+sudo cp -n /mnt/Tank1/astrololo-demo/$LOGIN/*.xlsx /mnt/Tank1/astrololo/
+```
+
+> Kopiujemy **tylko pliki `.xlsx`**. Plik `.files-state.json` zostaje — opisuje
+> stan wewnątrz puli demo i w produkcji nie ma sensu; produkcja ma własny.
+
+**4. Włącz je w pełnej aplikacji**: zakładka **Pliki**, nowe bazy pojawią się jako
+„gotowa, odstawiona". Klikasz przełącznik przy tych, które mają wejść do użytku.
+
+To, że nie włączają się same, jest zamierzone: przeniesienie plików jest czynnością
+techniczną, a decyzja, które bazy biorą udział w interpretacji, należy do Ciebie.
+
+---
+
+## Odcięcie całego demo
+
+```bash
+kubectl -n astrololo scale deploy/astrodemo --replicas=0
+```
+
+Pule i dane zostają. Skasowanie sekretu `astrololo-astrodemo` zatrzyma pod (nie wstanie
+bez niego) i to też jest zachowanie zamierzone.
@@ -0,0 +1,136 @@
+# Astroklient — wdrożenie warstwy pośredniej
+
+Pełne funkcje astrologiczne, bez generowania tekstu i bez administracji.
+Trzeci produkt drabiny: **astrodemo** (dwie funkcje) → **astroklient** → **astrololo**.
+
+Host: `astroklient.czernobog.pl` · obraz `astrololo-astroklient` · port 8006.
+
+## Jak to jest odizolowane
+
+Trzy granice, w kolejności od najmocniejszej:
+
+**Obraz.** Plików ekranów, których ten produkt nie ma, NIE MA w obrazie — usuwa
+je `usun.txt` przy budowaniu. Nie ma więc czego wyłączać ani czym odsłaniać:
+uprawnienia liczą się z katalogu funkcji, a katalog składa się ze zgłoszeń
+ekranów obecnych w obrazie. Test w repo aplikacji sprawdza to na złożonym
+drzewie, razem z zaporą słownikową — po nieobecnych funkcjach nie zostaje nawet
+słowo w komentarzu.
+
+**Udział NFS.** Własny `astrololo-klient`, osobny od produkcyjnego i od demo.
+Pule kont izolują klientów od siebie, ale to izolacja PROGRAMOWA — opiera się na
+poprawności mechanizmu pul. Granica na poziomie systemu plików nie zależy od
+tego, czy w kodzie niczego nie przeoczono. Przy sprzątaniu demo nie da się przez
+pomyłkę skasować cudzych danych, bo leżą gdzie indziej.
+
+**Warstwa danych i logiki.** Własna para `data-astroklient` + `logic-astroklient`,
+z silnikiem własnym (permisywnym) — silnik B (AGPL) nie wchodzi do produktu
+oddawanego klientom.
+
+---
+
+## Krok 1 — udział `astrololo-klient` na TrueNAS
+
+```bash
+midclt call sharing.nfs.create '{
+  "path": "/mnt/Tank1/astrololo-klient",
+  "hosts": ["192.168.1.73", "192.168.1.80", "192.168.1.81", "192.168.1.82"],
+  "maproot_user": "root", "maproot_group": "root", "enabled": true
+}'
+midclt call service.restart nfs
+```
+
+**Wszystkie CZTERY węzły.** Klaster ma cztery (`kubectl get nodes -o wide`), a nie
+trzy — pominięcie jednego daje `access denied by server` dopiero wtedy, gdy
+scheduler tam coś postawi, czyli w losowym momencie tygodnie później.
+
+Kontrolę wyłapującą braki i literówki w adresach masz w
+[README.md](README.md) → „Kontrola: czy każdy udział obejmuje każdy węzeł".
+
+Jeśli katalog jeszcze nie istnieje, utwórz dataset przed eksportem.
+
+## Krok 2 — konta klientów
+
+Każde konto to osobna pula, więc **rozdajesz konta, nie jedno hasło**.
+Wszystkie mają ten sam poziom dostępu — konta rozdziela się dla rozdzielenia
+plików, nie uprawnień.
+
+```bash
+# skrypt w repo aplikacji; format hasha wspólny dla wszystkich usług
+python services/presentation/scripts/make_user.py klientA    # wypisze: scrypt$…
+```
+
+```bash
+kubectl -n astrololo create secret generic astrololo-astroklient \
+  --from-literal=ASTROKLIENT_USERS='klientA:scrypt$…,klientB:scrypt$…' \
+  --from-literal=SESSION_SECRET="$(openssl rand -hex 32)"
+```
+
+`SESSION_SECRET` jest **własny**, nie ten z pełnej aplikacji ani z demo: trzy
+produkty nie mają powodu uznawać nawzajem swoich sesji. Ciasteczko też ma własną
+nazwę (`astroklient_sesja`), więc logowanie do jednego nie wyrzuca z drugiego.
+
+**Pod bez `SESSION_SECRET` celowo nie wstanie** — logowanie bez klucza podpisu
+nie miałoby czym się bronić.
+
+### Unieważnienie dostępu
+
+Nie ma wolumenu stanu, więc nie ma licznika pokolenia sesji. Zamiast tego:
+
+- usunięcie konta z `ASTROKLIENT_USERS` albo zmiana jego hasła **natychmiast ubija
+  jego otwarte sesje** — odcisk poświadczenia w ciasteczku przestaje pasować,
+- rotacja `SESSION_SECRET` wylogowuje wszystkich naraz.
+
+**Pula zostaje na udziale.** Odebranie dostępu nie kasuje plików klienta —
+przestaje być tylko komu je pokazywać.
+
+### Dodanie konta później
+
+```bash
+STARE=$(kubectl -n astrololo get secret astrololo-astroklient -o jsonpath='{.data.ASTROKLIENT_USERS}' | base64 -d)
+
+kubectl -n astrololo create secret generic astrololo-astroklient \
+  --from-literal=ASTROKLIENT_USERS="${STARE},klientC:scrypt\$…" \
+  --dry-run=client -o yaml | kubectl apply -f -
+
+kubectl -n astrololo rollout restart deploy/astroklient
+```
+
+## Krok 3 — wdrożenie
+
+Sekret i udział **muszą istnieć wcześniej**. Potem wystarczy merge do `master` —
+ArgoCD zsynchronizuje, a image-updater będzie odtąd podbijał tag sam, bo obraz
+jest dopisany do [`image-updater.yaml`](image-updater.yaml).
+
+## Sprawdzenie po wdrożeniu
+
+```bash
+kubectl -n astrololo get pods -l app=astroklient -o wide
+kubectl -n astrololo logs -l app=astroklient --tail=30
+curl -sk https://astroklient.czernobog.pl/ -o /dev/null -w '%{http_code}\n'   # 303 → bramka logowania odpowiada
+```
+
+Po zalogowaniu w nawigacji ma być **sześć** pozycji: Horoskop, Interpretacje,
+Kalendarz, Synastria, Sygnifikatory, Pliki.
+
+**Bez zalogowania każdy adres oddaje 303** — także nieistniejący. Bramka
+logowania działa przed trasowaniem, więc niezalogowany nie wyczyta z kodów
+odpowiedzi, które ekrany istnieją. Sprawdzanie nieobecnych adresów bez sesji nic
+więc nie mówi: pokaże 303 dla wszystkiego, łącznie z `/nie-ma-takiego-ekranu`.
+
+Sprawdzenie ma sens dopiero Z SESJĄ, i wtedy nieobecne ekrany dają **404, nie
+403** — odmowa z powodem byłaby informacją, że coś tam jest:
+
+```bash
+CIASTKO='astroklient_sesja=<wartość z przeglądarki po zalogowaniu>'
+for A in / /compile /settings /accounts /files; do
+  printf "%-12s %s\n" "$A" \
+    "$(curl -sk -o /dev/null -w '%{http_code}' -H "Cookie: $CIASTKO" https://astroklient.czernobog.pl$A)"
+done
+# oczekiwane:  / → 200,  reszta → 404
+```
+
+## Import puli klienta do pełnej aplikacji
+
+Pula to zwykły katalog na udziale — kopiuje się go tak samo jak w demo,
+patrz [README-astrodemo.md](README-astrodemo.md) → „Import puli klienta".
+Ścieżka źródłowa to `/mnt/Tank1/astrololo-klient/<login>`.
@@ -0,0 +1,133 @@
+# Zarządzanie plikami baz — otwarcie udziału na zapis (DAN-27)
+
+Ekran „Pliki" pozwala wgrywać bazy, archiwizować je i (dla administratora)
+kasować, a stan użycia jest **klikany**, więc musi być trwały. Wymaga to zapisu
+do udziału z bazami — a ten jest dziś wyeksportowany tylko do odczytu.
+
+---
+
+## Co świadomie tracimy
+
+DAN-25 dawał gwarancję, że **baz nie da się zmienić przez NFS**. DAN-27 tę
+gwarancję z definicji znosi — nie da się mieć obu naraz.
+
+**Co zostaje:**
+
+| zabezpieczenie | działa nadal |
+|---|---|
+| eksport zawężony do trzech węzłów k8s | ✅ |
+| token międzywarstwowy | ✅ |
+| szyfrowane łącze prezentacja ↔ logika ↔ dane | ✅ |
+| kasowanie plików wyłącznie z konta administracyjnego (PRE-27) | ✅ |
+| dziennik audytowy (kto, kiedy, co) | ✅ |
+
+Ryzyko, które przybywa: **przejęcie warstwy danych pozwala teraz nie tylko
+odczytać bazy, ale i je zmienić.**
+
+---
+
+## Krok 1 — otwórz udział na zapis
+
+```bash
+midclt call sharing.nfs.query '[["path","=","/mnt/Tank1/astrololo"]]' \
+  | python3 -c "import sys,json;[print(s['id'], '| ro:', s['ro'], '| mapall:', s.get('mapall_user')) for s in json.load(sys.stdin)]"
+```
+
+Weź `id` i podstaw za `<ID>`:
+
+```bash
+midclt call sharing.nfs.update <ID> '{"ro": false, "mapall_user": "root", "mapall_group": "root"}'
+```
+
+> **Dlaczego `mapall_user`, skoro katalog ma `drwxrwxrwx`?** Samo `ro: false`
+> wystarczyłoby do zapisu — zmapowany `nobody` mieści się w prawach „innych".
+> Ale nowe pliki należałyby wtedy do `nobody`, a istniejące bazy do `root`.
+> Mieszana własność zemści się przy pierwszym zaostrzeniu praw. `mapall_user:
+> root` daje spójność i jest tym samym ustawieniem, co na udziale `astrololo-state`.
+
+```bash
+midclt call service.restart nfs
+```
+
+Sprawdź, że zmiana **faktycznie trafiła do jądra** — sama konfiguracja to za mało:
+
+```bash
+sudo exportfs -v | grep -A1 "Tank1/astrololo "
+```
+
+Przy `/mnt/Tank1/astrololo` musi być `rw`, nie `ro`.
+
+---
+
+## Krok 2 — zmerguj oba PR-y
+
+* aplikacja: `feat/zarzadzanie-plikami`
+* deploy: `feat/pliki-zapis` (zdejmuje `readOnly` z montowania w podzie)
+
+Bez tego drugiego pod nadal montuje udział tylko do odczytu, choćby serwer
+pozwalał pisać.
+
+---
+
+## Krok 3 — przeładuj warstwę danych PRZEZ ZERO REPLIK
+
+> ⚠️ **`rollout restart` NIE WYSTARCZY.** Stary i nowy pod na chwilę
+> współistnieją, więc montowanie NFS ani na moment nie zostaje bez użytkownika
+> i nowy pod dziedziczy uprawnienia sprzed zmiany eksportu. To kosztowało
+> najwięcej czasu przy udziale `astrololo-state` — patrz
+> [README-stan-prezentacji.md](README-stan-prezentacji.md).
+
+```bash
+kubectl -n astrololo scale deploy/data --replicas=0
+kubectl -n astrololo wait --for=delete pod -l app=data --timeout=90s
+kubectl -n astrololo scale deploy/data --replicas=1
+kubectl -n astrololo rollout status deploy/data
+```
+
+---
+
+## Krok 4 — sprawdź, w tej kolejności
+
+**Czy warstwa danych może pisać:**
+
+```bash
+kubectl -n astrololo exec deploy/data -- sh -c 'touch /app/data_files/proba && echo ZAPIS-OK && rm /app/data_files/proba'
+```
+
+**Czy powstał plik stanu i czy bazy zostały przyjęte jako aktywne:**
+
+```bash
+kubectl -n astrololo exec deploy/data -- sh -c 'cat /app/data_files/.files-state.json' | head -20
+```
+
+Oczekiwane: każda baza ze `"status": "active"`. Przy pierwszym uruchomieniu bazy
+zastane na udziale są przyjmowane automatycznie — **bez tego wyszukiwanie
+przestałoby cokolwiek znajdować**, bo plik bez wpisu w rejestrze nie bierze
+udziału w wynikach.
+
+**Czy wyszukiwanie NADAL DZIAŁA** — to jest najważniejszy sprawdzian tego
+wdrożenia, bo właśnie tu zmiana mogłaby przejść niezauważona:
+
+```bash
+kubectl -n astrololo logs deploy/data --tail=20
+```
+
+a potem w przeglądarce: zakładka **Sygnifikatory**, dowolne wyszukanie. Musi
+zwracać wyniki jak przedtem. Jeśli nagle nic nie znajduje — zajrzyj do
+`.files-state.json` z komendy wyżej.
+
+**Czy ekran „Pliki" działa:** zakładka **Pliki**, lista baz, przełącznik przy
+każdej. Wgraj testowy plik, zarchiwizuj go, skasuj.
+
+---
+
+## Odkręcenie
+
+```bash
+midclt call sharing.nfs.update <ID> '{"ro": true, "mapall_user": null, "mapall_group": null}'
+midclt call service.restart nfs
+```
+
+plus cofnięcie deploy `feat/pliki-zapis`. Ekran „Pliki" zostanie, ale wgrywanie
+i kasowanie przestaną działać — a stan użycia przestanie się zapisywać, więc bazy
+będą przyjmowane od nowa przy każdym starcie (czyli wszystkie aktywne).
@@ -0,0 +1,284 @@
+# Postgres — lustro baz w SQL (DAN-28)
+
+Runbook krok po kroku. Zakłada, że nie pamiętasz nic z rozmowy, w której to
+powstało.
+
+---
+
+## Co to jest — i czego to NIE jest
+
+Postgres trzyma **lustro** plików Excela, żeby wyszukiwanie było szybsze i mądrzejsze.
+
+> **ŹRÓDŁEM PRAWDY SĄ PLIKI EXCELA NA NFS.** Utrata tej bazy **nie jest utratą
+> danych** — odbudowuje się z plików. Dlatego kopie zapasowe Postgresa są tu
+> **opcjonalne**, a wolumen stoi na `local-path` zamiast na NFS.
+
+Po co w ogóle Postgres, skoro danych jest mało (~54 tys. wierszy)? Nie dla skali —
+przy takim rozmiarze SQLite bywa szybszy. Dla **wyszukiwania w polskim,
+nieznormalizowanym tekście**: `pg_trgm` (dopasowanie mimo literówek) i `unaccent`
+(ogonki) nie mają w SQLite taniego zamiennika.
+
+---
+
+## Część 1 — co zrobiłem za Ciebie (w repo)
+
+Nic z tego nie wymaga Twojej ręki, ale wiedz, co jest gdzie:
+
+| plik | co w nim jest |
+|---|---|
+| `astrololo/postgres.yaml` | PVC (5 Gi, `local-path`), ConfigMap z SQL-em inicjalizującym, Deployment (`Recreate`), Service `ClusterIP` |
+| `astrololo/kustomization.yaml` | `postgres.yaml` dopisany **przed** `data.yaml` |
+| `astrololo/data.yaml` | `SQL_URL` z sekretu; `DATA_PROVIDER` **zostaje `excel`** |
+| repo aplikacji: `services/data/requirements.txt` | sterownik `psycopg[binary]` |
+
+Decyzje, które w tych plikach zapadły — żeby nie trzeba było ich odtwarzać z głowy:
+
+* **`local-path`, nie NFS.** Postgres zakłada semantykę blokad i `fsync`, której NFS
+  nie gwarantuje — to klasyczne źródło uszkodzenia bazy przy nagłym restarcie.
+  Ceną jest przywiązanie do węzła; przy luście odtwarzalnym z Excela to nie boli.
+* **`strategy: Recreate`.** Wolumen jest `ReadWriteOnce`, a dwa procesy Postgresa
+  na jednym katalogu danych to uszkodzona baza. Rolling próbowałby wstać z nowym
+  podem, zanim stary zejdzie.
+* **`PGDATA` w podkatalogu** (`…/data/pgdata`). Katalog główny wolumenu potrafi
+  zawierać wpisy systemu plików, a `initdb` odmawia pracy w niepustym katalogu.
+* **Wersja przypięta (`postgres:17`) i POZA image-updaterem.** Podbicie majora
+  wymaga migracji katalogu danych — nie może się zdarzyć samo, w nocy, przy okazji
+  builda aplikacji.
+* **`DATA_PROVIDER` zostaje na `excel`.** Postgres można wdrożyć i obejrzeć **bez
+  żadnego ryzyka** dla działającego wyszukiwania. Przełączenie na `sql` to osobna,
+  późniejsza decyzja — po wdrożeniu lustra.
+
+---
+
+## Część 2 — co musisz zrobić Ty
+
+### Krok 0. Sprawdź, że klaster ma `local-path`
+
+```bash
+kubectl get storageclass
+```
+
+Oczekiwany wynik: linia z `local-path` i dopiskiem `(default)`. W k3s jest
+domyślnie. **Jeśli jej nie ma — zatrzymaj się tutaj** i daj znać; bez niej PVC
+zawiśnie w `Pending`.
+
+### Krok 1. Utwórz sekret `astrololo-postgres`
+
+Ta sama konwencja co `astrololo-auth`: **sekretu nie ma w repo**, bo to repo
+GitOps i cokolwiek by tu wpadło, zostałoby w historii gita na zawsze.
+
+```bash
+PGPASS="$(openssl rand -base64 24 | tr -d '/+=' | head -c 32)"
+
+kubectl -n astrololo create secret generic astrololo-postgres \
+  --from-literal=POSTGRES_PASSWORD="$PGPASS" \
+  --from-literal=SQL_URL="postgresql+psycopg://astrololo:${PGPASS}@postgres:5432/astrololo"
+
+unset PGPASS
+```
+
+Hasła **nie musisz nigdzie zapisywać ani nigdy oglądać** — używają go tylko usługi
+między sobą. Gdybyś kiedyś go potrzebował:
+
+```bash
+kubectl -n astrololo get secret astrololo-postgres \
+  -o jsonpath='{.data.POSTGRES_PASSWORD}' | base64 -d; echo
+```
+
+> **Dlaczego dwa klucze, skoro hasło jest w obu?** `POSTGRES_PASSWORD` czyta sam
+> Postgres przy inicjalizacji, `SQL_URL` czyta warstwa danych. Rozdzielone, bo to
+> dwa różne formaty i dwóch różnych odbiorców — sklejanie DSN-a w manifeście
+> wymagałoby wstawienia tam hasła.
+
+### Krok 2. Wdróż
+
+Jeśli ArgoCD pilnuje katalogu `astrololo`, wystarczy **zmergować PR** — reszta
+zrobi się sama. Ręcznie:
+
+```bash
+kubectl apply -k astrololo
+```
+
+### Krok 3. Sprawdź, że wstało
+
+```bash
+kubectl -n astrololo rollout status deploy/postgres
+kubectl -n astrololo get pvc postgres-data
+```
+
+Oczekiwane: `deployment "postgres" successfully rolled out` i PVC w stanie `Bound`.
+
+### Krok 4. Sprawdź, że rozszerzenia się założyły
+
+To jest **najważniejszy sprawdzian tego wdrożenia** — bez tych rozszerzeń cały
+sens stawiania Postgresa znika.
+
+```bash
+kubectl -n astrololo exec deploy/postgres -- \
+  psql -U astrololo -d astrololo -c "\dx"
+```
+
+Na liście muszą być **`pg_trgm`** i **`unaccent`**. Sprawdź też, że działają:
+
+```bash
+kubectl -n astrololo exec deploy/postgres -- psql -U astrololo -d astrololo -c \
+  "SELECT unaccent('różdżka')                              AS bez_ogonkow,
+          similarity(unaccent('różdżka'), 'rozdzka')       AS po_zdjeciu_ogonkow,
+          similarity('kowalski', 'kowlaski') > 0.3         AS literowka_lapana;"
+```
+
+Oczekiwane **dokładnie**:
+
+```
+ bez_ogonkow | po_zdjeciu_ogonkow | literowka_lapana
+-------------+--------------------+------------------
+ rozdzka     |                  1 | t
+```
+
+Pierwsza kolumna pokazuje, że `unaccent` zna polskie znaki; druga, że po zdjęciu
+ogonków słowa są **identyczne** (stąd równo `1`); trzecia, że `pg_trgm` łapie
+przestawione litery. Jeśli druga kolumna nie jest równa `1`, rozszerzenia są, ale
+reguły `unaccent` nie obsługują polskich znaków — daj znać, bo to zmienia sposób
+budowania indeksów.
+
+### Krok 5. Sprawdź, że warstwa danych ma połączenie
+
+```bash
+kubectl -n astrololo rollout restart deploy/data
+kubectl -n astrololo rollout status deploy/data
+kubectl -n astrololo logs deploy/data --tail=30 | grep -i -E "sql|postgres|error" || echo "brak wzmianek — OK"
+```
+
+Na tym etapie warstwa danych **nadal czyta Excela** (`DATA_PROVIDER=excel`).
+Postgres tylko stoi i czeka. Aplikacja ma działać dokładnie jak przedtem —
+i to jest oczekiwany wynik tego wdrożenia.
+
+---
+
+## Część 3 — obsługa na co dzień
+
+### Zajrzeć do bazy
+
+```bash
+kubectl -n astrololo exec -it deploy/postgres -- psql -U astrololo -d astrololo
+```
+
+Przydatne w środku: `\dt mirror.*` (tabele lustra), `\dx` (rozszerzenia),
+`\l` (bazy), `\q` (wyjście).
+
+### Podłączyć narzędzie graficzne z laptopa
+
+Baza **celowo nie jest wystawiona poza klaster**. Na czas jednej sesji:
+
+```bash
+kubectl -n astrololo port-forward deploy/postgres 5432:5432
+```
+
+i łączysz się na `localhost:5432`, użytkownik `astrololo`, baza `astrololo`,
+hasło jak w kroku 1. Po zamknięciu terminala tunel znika.
+
+### Dodanie rozszerzenia do ISTNIEJĄCEJ bazy
+
+> ⚠️ **Pułapka.** Skrypty z `/docker-entrypoint-initdb.d/` uruchamiają się
+> **wyłącznie przy pierwszej inicjalizacji**, na pustym katalogu danych. Dopisanie
+> rozszerzenia do ConfigMapy **nie zrobi nic**, jeśli baza już istnieje.
+
+```bash
+kubectl -n astrololo exec deploy/postgres -- \
+  psql -U astrololo -d astrololo -c "CREATE EXTENSION IF NOT EXISTS nazwa;"
+```
+
+### Kopia zapasowa (opcjonalna — patrz nagłówek)
+
+```bash
+kubectl -n astrololo exec deploy/postgres -- \
+  pg_dump -U astrololo -d astrololo -Fc > astrololo-$(date +%F).dump
+```
+
+Odtworzenie:
+
+```bash
+kubectl -n astrololo exec -i deploy/postgres -- \
+  pg_restore -U astrololo -d astrololo --clean --if-exists < astrololo-2026-08-06.dump
+```
+
+### Wyczyścić lustro i wczytać od nowa
+
+```bash
+kubectl -n astrololo exec deploy/postgres -- psql -U astrololo -d astrololo -c \
+  "DROP SCHEMA mirror CASCADE; CREATE SCHEMA mirror;"
+```
+
+Po tym warstwa danych odbuduje lustro z plików Excela (gdy lustro będzie już
+zaimplementowane — dziś ta komenda tylko czyści pusty schemat).
+
+### Podbicie wersji Postgresa
+
+**Nie robi się tego przez zmianę tagu w manifeście.** Major wymaga migracji
+katalogu danych. Ponieważ to lustro:
+
+1. `kubectl -n astrololo scale deploy/data --replicas=0`
+2. skasuj Deployment i **PVC** (`kubectl -n astrololo delete deploy/postgres pvc/postgres-data`)
+3. zmień tag obrazu w `postgres.yaml`, wdróż ponownie
+4. `kubectl -n astrololo scale deploy/data --replicas=1` — lustro odbuduje się z Excela
+
+To jest właśnie ta sytuacja, w której „lustro, nie źródło prawdy" oszczędza dzień
+pracy.
+
+---
+
+## Co zostało sprawdzone przed oddaniem, a co nie
+
+**Sprawdzone:** `kubectl kustomize astrololo` składa komplet 21 zasobów bez błędu;
+YAML wszystkich manifestów parsuje się poprawnie; audyt odwołań do sekretów
+potwierdza, że jedyne brakujące to `astrololo-postgres` (oba klucze); DSN
+`postgresql+psycopg://…` jest poprawnie rozpoznawany przez SQLAlchemy 2.0
+z zainstalowanym `psycopg` 3.
+
+**NIE sprawdzone, bo nie było na czym:** skrypt inicjalizujący nie został
+uruchomiony przeciwko prawdziwemu Postgresowi (na maszynie, na której to
+powstawało, nie ma Dockera). Składnia jest prosta i przejrzana, ale **krok 4 jest
+tu prawdziwym testem** — jeśli coś ma nie zadziałać, to właśnie tam.
+
+---
+
+## Część 4 — typowe problemy
+
+| objaw | przyczyna | co zrobić |
+|---|---|---|
+| PVC wisi w `Pending` | brak `local-path` albo brak miejsca na węźle | `kubectl get storageclass`, `kubectl describe pvc postgres-data` |
+| pod w `CrashLoopBackOff`, w logach `directory not empty` | `PGDATA` wskazuje katalog główny wolumenu | sprawdź, czy `PGDATA` to `…/data/pgdata` (jest w manifeście) |
+| pod nie startuje, `secret not found` | nie wykonany krok 1 | utwórz sekret i `kubectl -n astrololo rollout restart deploy/postgres` |
+| `\dx` nie pokazuje `pg_trgm` | baza założona przed dodaniem ConfigMapy | patrz „Dodanie rozszerzenia do istniejącej bazy" |
+| warstwa danych: `ModuleNotFoundError: psycopg` | obraz zbudowany przed dodaniem sterownika | poczekaj na build z CI albo `kubectl -n astrololo rollout restart deploy/data` po nowym obrazie |
+| `password authentication failed` | `SQL_URL` w sekrecie nie zgadza się z `POSTGRES_PASSWORD` | odtwórz sekret krokiem 1 (oba klucze naraz) i zrestartuj **oba** deploymenty |
+
+Gdy nic nie pasuje — pierwsze dwie komendy do wklejenia:
+
+```bash
+kubectl -n astrololo describe pod -l app=postgres | tail -30
+kubectl -n astrololo logs deploy/postgres --tail=50
+```
+
+---
+
+## Część 5 — pełne odtworzenie ręczne, bez ArgoCD i bez repo
+
+Gdyby trzeba było postawić to od zera na czystym klastrze:
+
+```bash
+kubectl create namespace astrololo
+
+PGPASS="$(openssl rand -base64 24 | tr -d '/+=' | head -c 32)"
+kubectl -n astrololo create secret generic astrololo-postgres \
+  --from-literal=POSTGRES_PASSWORD="$PGPASS" \
+  --from-literal=SQL_URL="postgresql+psycopg://astrololo:${PGPASS}@postgres:5432/astrololo"
+unset PGPASS
+
+kubectl apply -f astrololo/postgres.yaml
+kubectl -n astrololo rollout status deploy/postgres
+kubectl -n astrololo exec deploy/postgres -- psql -U astrololo -d astrololo -c "\dx"
+```
+
+Reszta aplikacji wymaga jeszcze sekretów `astrololo-auth` i `astrololo-link` —
+patrz [README.md](README.md).
@@ -0,0 +1,135 @@
+# Udział na stan prezentacji — `astrololo-state`
+
+Potrzebny do kont zakładanych z ekranu „Konta" (PRE-27). **Bez niego pod
+`presentation` nie wstanie.**
+
+---
+
+## Dlaczego osobny udział, a nie podkatalog
+
+Pierwsza wersja montowała `/mnt/Tank1/astrololo` z `subPath: presentation-state`
+i pod stanął w `CreateContainerConfigError`:
+
+```
+failed to create subPath directory for volumeMount "state" of container "presentation"
+```
+
+Przyczyna była podwójna i za każdym razem ta sama: udział z bazami jest
+wyeksportowany **`ro: true` z `root_squash`** (patrz runbook DAN-25 w repo
+aplikacji). Zatem:
+
+1. kubelet nie mógł utworzyć podkatalogu — bo udział jest tylko do odczytu,
+2. a gdyby nawet mógł, aplikacja i tak nie zapisałaby tam pliku kont.
+
+**Osobny udział rozwiązuje to bez ruszania DAN-25.** Udział z bazami zostaje tylko
+do odczytu; konta dostają własne, małe miejsce. Przy okazji znika `subPath`, czyli
+znika potrzeba, żeby kubelet cokolwiek zakładał — katalog istnieje, bo jest
+korzeniem udziału.
+
+---
+
+## Krok 1 — dataset i udział na TrueNAS
+
+Po SSH na NAS (192.168.1.34). Konwencja jak w DAN-25: **nie edytujemy
+`/etc/exports` ręcznie**, tylko przez `midclt`.
+
+```bash
+# dataset
+sudo zfs create Tank1/astrololo-state
+```
+
+Jeśli `Tank1` nie jest pulą ZFS albo wolisz zwykły katalog:
+
+```bash
+sudo mkdir -p /mnt/Tank1/astrololo-state
+```
+
+### Właściciel i prawa
+
+Kontenery aplikacji działają **jako root**, a eksport ma `root_squash`, więc root
+z klienta NIE jest rootem na udziale. Żeby zapis działał, przypinamy cały ruch
+z tych hostów do jednego, nieuprzywilejowanego użytkownika — to bezpieczniejsze
+niż `no_root_squash`, bo nie oddaje roota.
+
+```bash
+# użytkownik, na którego mapujemy (jeśli nie istnieje — utwórz w UI TrueNAS)
+sudo chown -R apps:apps /mnt/Tank1/astrololo-state
+sudo chmod 770 /mnt/Tank1/astrololo-state
+```
+
+> Podstaw swojego użytkownika w miejsce `apps`. Sprawdzisz istniejących:
+> `midclt call user.query | python3 -c "import sys,json;[print(u['uid'], u['username']) for u in json.load(sys.stdin)]"`
+
+### Eksport NFS
+
+```bash
+midclt call sharing.nfs.create '{
+  "path": "/mnt/Tank1/astrololo-state",
+  "comment": "astrololo — stan prezentacji (konta PRE-27)",
+  "hosts": ["192.168.1.73", "192.168.1.80", "192.168.1.81", "192.168.1.82"],
+  "ro": false,
+  "mapall_user": "apps",
+  "mapall_group": "apps"
+}'
+```
+
+| ustawienie | po co |
+|---|---|
+| `hosts` zawężone | te same trzy węzły k8s co w DAN-25 — nikt inny nie zamontuje |
+| `ro: false` | **musi być zapisywalny**, inaczej konta się nie zapiszą |
+| `mapall_user` | cały ruch pisze jako jeden nieuprzywilejowany użytkownik, niezależnie od UID w kontenerze |
+
+> Podstaw swoje adresy węzłów, jeśli się zmieniły. Aktualne:
+> `kubectl get nodes -o wide`
+
+---
+
+## Krok 2 — sprawdź z węzła, ZANIM wdrożysz
+
+To jest ten test, którego zabrakło za pierwszym razem:
+
+```bash
+ssh 192.168.1.73 'sudo mount -t nfs 192.168.1.34:/mnt/Tank1/astrololo-state /mnt/test \
+  && sudo touch /mnt/test/proba && echo "ZAPIS DZIAŁA" \
+  && sudo rm /mnt/test/proba; sudo umount /mnt/test'
+```
+
+Musi wypisać **`ZAPIS DZIAŁA`**. Jeśli zamiast tego widzisz `Permission denied` —
+wróć do praw katalogu i `mapall_user` w kroku 1.
+
+---
+
+## Krok 3 — wdróż i sprawdź
+
+```bash
+kubectl apply -k astrololo
+kubectl -n astrololo rollout status deploy/presentation
+```
+
+Sprawdź, że aplikacja faktycznie umie tam zapisać — załóż konto testowe
+na ekranie „Konta", a potem:
+
+```bash
+kubectl -n astrololo exec deploy/presentation -- ls -l /app/state/
+```
+
+Oczekiwane: plik `accounts.json`.
+
+---
+
+## Odkręcenie
+
+```bash
+# ID udziału
+midclt call sharing.nfs.query | python3 -c "import sys,json;[print(s['id'], s.get('path')) for s in json.load(sys.stdin)]"
+midclt call sharing.nfs.delete <ID>
+```
+
+---
+
+## Uwaga na przyszłość: DAN-27 uderzy w tę samą ścianę
+
+Zarządzanie plikami baz (wgrywanie, archiwizacja, kasowanie) wymaga zapisu do
+**udziału z bazami** — a ten jest `ro: true`. Ten runbook tego **nie rozwiązuje**
+i celowo nie rusza DAN-25: to osobna decyzja, bo oznacza rezygnację z gwarancji,
+że baz nie da się zmienić przez NFS. Patrz PR `feat/pliki-zapis`.
@@ -12,16 +12,176 @@ Adres aplikacji: **https://astrololo.czernobog.pl** — patrz [TLS](#-tls--wymag

 Lista obrazów podbijanych automatycznie jest **jawna** i żyje w CRD `ImageUpdater`
 (ns `argocd`). Obraz, którego na niej nie ma, **nigdy się nie podbije**, choćby CI
-go budowało — tak przez chwilę wisiał `render` na `:latest`, zanim dopisaliśmy go do
-listy. Dodając nową usługę, dopisz jej wpis w `image-updater.yaml` i nałóż:
+go budowało — tak przez chwilę wisiał `render` na `:latest`.

-```bash
-kubectl apply -f astrololo/image-updater.yaml
+Dodając nową usługę, dopisz jej wpis w `image-updater.yaml`. **Nic więcej nie
+trzeba**: plik jest w `kustomization.yaml`, więc ArgoCD nakłada go razem z resztą.
+
+### Dlaczego jest w kustomization, skoro kiedyś celowo nie był
+
+Wcześniej ten plik był z niej wyłączony z uzasadnieniem, że resource stoi w ns
+`argocd`, poza namespace docelowym aplikacji, i że to konfiguracja kontrolera,
+a nie samej aplikacji — więc nakłada się go ręcznie.
+
+Rozumowanie nie było głupie, ale **nie wytrzymało praktyki**. Ręczny krok
+zapomniano dwa razy w ciągu dwóch tygodni: najpierw dla `astrodemo`, potem dla
+`astroklient`. Obie usługi miały wpis w pliku i obu brakowało w klastrze, więc
+ich obrazy stały w miejscu mimo poprawnie działającego CI.
+
+Najgorsza w tym była **cichość rozjazdu**: plik w gicie wyglądał poprawnie,
+`git log` pokazywał dopisanie usługi, a objawem był obraz, który „się nie
+deployuje" — co kieruje podejrzenia na CI albo na rejestr, czyli wszędzie poza
+właściwe miejsce. Diagnoza wymaga porównania pliku ze stanem klastra, a nikt nie
+porównuje rzeczy, o której nie wie, że mogą się różnić.
+
+Przeszkody technicznej nie było: projekt ArgoCD dopuszcza dowolną przestrzeń
+nazw (`destinations: [{namespace: "*", server: "*"}]`), więc resource w ns
+`argocd` nakłada się bez zastrzeżeń.
+
+Jeśli kiedyś trzeba będzie go stamtąd wyjąć, **wyjmij razem z tym akapitem** —
+inaczej następna osoba przeczyta uzasadnienie, którego już nie ma.
+
+## Pliki baz — udział otwarty na zapis (DAN-27)
+
+Runbook: **[README-pliki.md](README-pliki.md)**. Ekran „Pliki" wymaga zapisu do
+udziału z bazami, więc znosi gwarancję z DAN-25, że baz nie da się zmienić przez
+NFS. Co zostaje z zabezpieczeń i jak to wdrożyć — w runbooku.
+
+## astrodemo — wersja demonstracyjna (PRE-28/29)
+
+Osobna usługa o dwóch funkcjach: dodanie pliku i pytanie o interpretację
+urodzeniową. Runbook: **[README-astrodemo.md](README-astrodemo.md)**.
+
+Ma **własną warstwę danych i logiki** (`astrodemo-stack.yaml`) oraz własny udział
+NFS, a każde konto dostaje w nim odrębną, niewidoczną dla pozostałych pulę plików
+(PRE-29). Nie sięga do produkcyjnych baz.
+
+Konta są osobne (sekret `astrololo-astrodemo`), więc usługę odcina się jedną
+zmianą, bez ruszania kont głównej aplikacji. Wchodzi się przez własny host
+`astrodemo.czernobog.pl` — nie przez ścieżkę pod adresem astrololo, bo wspólne
+pochodzenie oznaczałoby wspólne ciasteczka i wzajemne wylogowywanie.
+
+## ⚠️ Wymóg węzłów: klient NFS
+
+Wszystkie warstwy montują udziały z NAS-a, więc **każdy węzeł, na którym może
+wylądować pod, musi mieć klienta NFS**. Bez niego kubelet nie zamontuje wolumenu:
+
+```
+mount: ... bad option; for several filesystems (e.g. nfs, cifs) you might need
+a /sbin/mount.<type> helper program
 ```

-Ten plik **celowo nie jest w `kustomization.yaml`**: resource stoi w ns `argocd`
-(poza namespace docelowym aplikacji), a to konfiguracja kontrolera, który wdraża tę
-aplikację — nakładamy go ręcznie, w repo trzymamy dla odtwarzalności i historii.
+Ten komunikat **nie oznacza problemu z udziałem ani z uprawnieniami** — serwer
+w ogóle nie został zapytany. Jądro nie znalazło programu pomocniczego
+`/sbin/mount.nfs`.
+
+### Sprawdzenie
+
+```bash
+for N in 192.168.1.73 192.168.1.80 192.168.1.81 192.168.1.82; do
+  printf "%-15s " "$N"
+  ssh hammer@$N 'test -x /sbin/mount.nfs && echo MA-KLIENTA || echo BRAK-KLIENTA'
+done
+```
+
+### Instalacja
+
+```bash
+ssh hammer@<węzeł> 'sudo apt-get update && sudo apt-get install -y nfs-common'
+```
+
+> **Na WSZYSTKICH węzłach, nie tylko na tym, gdzie pod stoi teraz.** Braku na
+> pozostałych nie widać, dopóki scheduler tam czegoś nie przeniesie — a wtedy
+> awaria wygląda na nagłą, choć przyczyna leżała od dawna. Dokładnie tak wyszło
+> za pierwszym razem: pody działały miesiącami na jednym węźle, aż zejście do
+> zera replik przy innej naprawie przeplanowało je gdzie indziej.
+
+### Skąd wiadomo, że to TO
+
+| komunikat | co znaczy |
+|---|---|
+| `bad option ... mount.<type> helper program` | **brak `nfs-common` na węźle** — serwer niepytany |
+| `access denied by server while mounting` | serwer odmawia: eksport nieprzeładowany, węzła nie ma na liście `hosts`, albo udział wyłączony |
+| `Permission denied` przy zapisie | montowanie działa, brakuje praw — patrz `mapall_user` i właściciel katalogu |
+
+## ⚠️ Wymóg węzłów: rozszerzenia procesora (x86-64-v2)
+
+Warstwa danych używa pandas, a przez nią NumPy. Koła NumPy z PyPI są budowane
+z bazą **x86-64-v2**, więc na węźle bez tych rozszerzeń kontener nie wstaje:
+
+```
+RuntimeError: NumPy was built with baseline optimizations:
+(X86_V2) but your machine doesn't support: (X86_V2).
+```
+
+Komunikat mówi o „optymalizacjach", czyli o niczym, po czym dałoby się poznać,
+że chodzi o **węzeł**, a nie o obraz. Pod wpada w pętlę restartów i wygląda to
+na zepsuty build.
+
+### To NIE jest ograniczenie sprzętu
+
+Węzły k3s są maszynami wirtualnymi. Proxmox z domyślnym modelem CPU (`kvm64`,
+„Common KVM processor") **maskuje flagi procesora** — gość nie widzi SSE4.2 ani
+POPCNT, mimo że fizyczny i7-3770 obsługuje nawet x86-64-**v3**. Stąd bierze się
+złudzenie, że „węzły mają różne procesory": mają ten sam sprzęt i różne maski.
+
+### Sprawdzenie: które węzły to udźwigną
+
+```bash
+for N in $(kubectl get nodes -o jsonpath='{.items[*].metadata.name}'); do
+  kubectl run cpucheck-$N --image=busybox --restart=Never --rm -i --quiet \
+    --overrides="{\"spec\":{\"nodeName\":\"$N\",\"tolerations\":[{\"operator\":\"Exists\"}]}}" \
+    --command -- sh -c '
+      F=$(grep -m1 ^flags /proc/cpuinfo); BRAK=""
+      for f in cx16 lahf_lm popcnt pni ssse3 sse4_1 sse4_2; do
+        echo "$F" | grep -qw "$f" || BRAK="$BRAK $f"
+      done
+      echo "$(grep -m1 "model name" /proc/cpuinfo | cut -d: -f2-)"
+      [ -z "$BRAK" ] && echo "  x86-64-v2: TAK" || echo "  x86-64-v2: NIE —$BRAK"
+    ' 2>/dev/null | sed "s/^/$N /"
+done
+```
+
+**Pułapka przy czytaniu flag:** Linux raportuje SSE3 jako **`pni`** (Prescott New
+Instructions), nie `sse3`. Szukanie `sse3` daje fałszywy alarm na maszynie, która
+SSE3 ma — pierwsza wersja tej kontroli wskazała w ten sposób trzy zdrowe węzły
+jako niesprawne.
+
+### Naprawa u źródła (Proxmox)
+
+Na węźle Proxmox, dla każdej maszyny k3s:
+
+```bash
+qm set <VMID> --cpu host
+qm stop <VMID> && qm start <VMID>
+```
+
+**Sam restart z wnętrza gościa nie wystarczy** — zmiana modelu CPU wchodzi
+dopiero przy pełnym wyłączeniu i włączeniu maszyny.
+
+`--cpu host` przekazuje pełny zestaw rozszerzeń i daje przy okazji realnie
+szybszą arytmetykę. Ma jeden koszt: **blokuje migrację na żywo** między hostami
+o różnych procesorach. Jeśli kiedyś zaczniemy migrować maszyny między pve2
+a NUC-iem, właściwym wyborem będzie wspólny mianownik `x86-64-v2-AES` zamiast
+`host`.
+
+### Zabezpieczenie: etykieta zamiast wykluczania po nazwie
+
+`data` i `data-demo` wymagają etykiety `astrololo.czernobog.pl/cpu-x86-64-v2`.
+Nowy węzeł jest domyślnie **nieoznaczony**, więc nie dostanie tych podów, dopóki
+ktoś go nie sprawdzi i nie oznaczy świadomie:
+
+```bash
+kubectl label node <węzeł> astrololo.czernobog.pl/cpu-x86-64-v2=true
+```
+
+Wykluczanie konkretnego węzła po nazwie znaczyłoby, że każdy KOLEJNY źle
+postawiony węzeł znów zbierze się przez awarię. Tak wyszedł agent3: dołożony
+14 dni po pozostałych, bez kroku `--cpu host`, i nikt tego nie zauważył, dopóki
+scheduler nie postawił tam akurat warstwy danych.
+
+**KOLEJNOŚĆ MA ZNACZENIE.** Oznacz węzły ZANIM to wdrożysz — bez etykiet `data`
+nie ma się gdzie uruchomić i pójdzie w Pending.

 ## ⚠️ Sekret `astrololo-auth` — utwórz PRZED wdrożeniem

@@ -41,11 +201,54 @@ read -rs -p "Hasło do aplikacji (APP_PASSWORD): " APP_PASSWORD; echo

 kubectl -n astrololo create secret generic astrololo-auth \
  --from-literal=APP_PASSWORD="$APP_PASSWORD" \
-  --from-literal=INTERNAL_TOKEN="$(openssl rand -hex 32)"
+  --from-literal=INTERNAL_TOKEN="$(openssl rand -hex 32)" \
+  --from-literal=SESSION_SECRET="$(openssl rand -hex 32)"

 unset APP_PASSWORD
 ```

+`SESSION_SECRET` podpisuje ciasteczka sesji (LOG-34). **Pod bez niego celowo nie
+wstanie**: usługa z kontami, ale bez klucza, nie odróżniłaby ważnej sesji od
+podrobionej. Nikt go nigdy nie musi oglądać.
+
+### ⚠️ Masz już sekret sprzed LOG-34? Dołóż klucz, nie twórz od nowa
+
+Komenda wyżej zakłada sekret **od zera**. Jeśli `astrololo-auth` już istnieje,
+merge manifestu sam klucza nie dołoży — pod zgłosi wtedy:
+
+```
+Error: couldn't find key SESSION_SECRET in Secret astrololo/astrololo-auth
+```
+
+Dokładamy klucz, nie ruszając pozostałych:
+
+```bash
+kubectl -n astrololo patch secret astrololo-auth --type=merge \
+  -p "{\"stringData\":{\"SESSION_SECRET\":\"$(openssl rand -hex 32)\"}}"
+
+kubectl -n astrololo rollout restart deploy/presentation
+```
+
+Sprawdzenie, że komplet kluczy jest na miejscu (bez pokazywania wartości):
+
+```bash
+kubectl -n astrololo get secret astrololo-auth -o jsonpath='{.data}' \
+  | tr ',' '\n' | grep -o '"[A-Z_]*"'
+```
+
+Oczekiwane: `APP_PASSWORD`, `INTERNAL_TOKEN`, `SESSION_SECRET`.
+
+> `--type=merge` ze `stringData` **dokłada albo nadpisuje** i nie wymaga, żeby
+> klucz wcześniej istniał — w odróżnieniu od JSON Patch z `op: replace`, który
+> na brakującej ścieżce po prostu odmawia. Ta sama komenda służy więc i do
+> dołożenia, i do rotacji.
+
+### Rotacja klucza sesji
+
+**Wylogowuje WSZYSTKICH.** To nie usterka, tylko awaryjny wyłącznik: gdy
+podejrzewasz, że ktoś przechwycił cudzą sesję, podmiana klucza unieważnia je
+wszystkie naraz. Komenda ta sama, co dołożenie wyżej.
+
 `INTERNAL_TOKEN` jest losowany i **nikt go nigdy nie musi oglądać** — służy tylko
 usługom do rozmowy między sobą. `APP_PASSWORD` wpisujesz w przeglądarce
 (użytkownik: `astrololo`, zmienny przez `APP_USER` w `presentation.yaml`).
@@ -0,0 +1,142 @@
+# Warstwa danych i logiki WYŁĄCZNIE dla wersji demo (PRE-29).
+#
+# DLACZEGO OSOBNY KOMPLET, A NIE WSPÓŁDZIELONY. Warstwa logiczna zna JEDEN adres
+# warstwy danych, więc astrodemo korzystający z produkcyjnej logiki i tak trafiłby
+# na produkcyjne bazy. Izolacja demo musi więc sięgnąć obu warstw naraz, inaczej
+# nie ma jej wcale.
+#
+# Udział `astrololo-astrodemo` jest PUSTY na starcie i nigdy nie zawiera oryginalnych
+# baz. Każde konto demo dostaje w nim własny podkatalog (pulę) — patrz PRE-29.
+---
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: data-demo
+  namespace: astrololo
+spec:
+  replicas: 1
+  selector:
+    matchLabels: { app: data-demo }
+  template:
+    metadata:
+      labels: { app: data-demo }
+    spec:
+      # Ta usługa liczy na pandas, a przez nią na NumPy. Koła NumPy z PyPI są
+      # budowane z bazą x86-64-v2, więc na węźle bez tych rozszerzeń kontener
+      # NIE WSTAJE: `import numpy` kończy się RuntimeError, pod wpada w pętlę
+      # restartów, a komunikat mówi o „baseline optimizations" — czyli o niczym,
+      # po czym dałoby się poznać, że chodzi o węzeł.
+      #
+      # Wymagana ETYKIETA, a nie wykluczony konkretny węzeł. Nowy węzeł jest
+      # domyślnie NIEOZNACZONY, więc nie dostanie tu poda, dopóki ktoś go nie
+      # sprawdzi (skrypt w README) i nie oznaczy świadomie. Pending z czytelnym
+      # powodem jest lepszy niż pętla restartów z komunikatem o optymalizacjach —
+      # a wykluczanie węzłów po nazwie znaczyłoby, że każdy KOLEJNY źle
+      # postawiony węzeł znów zbiera się przez awarię.
+      affinity:
+        nodeAffinity:
+          requiredDuringSchedulingIgnoredDuringExecution:
+            nodeSelectorTerms:
+              - matchExpressions:
+                  - key: astrololo.czernobog.pl/cpu-x86-64-v2
+                    operator: In
+                    values: ["true"]
+      containers:
+        - name: data
+          # TEN SAM obraz co produkcja — różni się wyłącznie udziałem, na którym
+          # pracuje. Osobny obraz oznaczałby drugi kod do utrzymania i pewność,
+          # że kiedyś się rozjadą.
+          image: gitea.czernobog.pl/gitea/astrololo-data:latest
+          ports: [{ containerPort: 8002 }]
+          env:
+            - name: DATA_PROVIDER
+              value: "excel"
+            - name: EXCEL_DIR
+              value: "/app/data_files"
+            - name: CACHE_DIR
+              value: "/app/.cache"
+            - name: INTERNAL_TOKEN
+              valueFrom:
+                secretKeyRef: { name: astrololo-auth, key: INTERNAL_TOKEN }
+            - name: LINK_KEY_LOGIC_DATA
+              valueFrom:
+                secretKeyRef: { name: astrololo-link, key: LINK_KEY_LOGIC_DATA }
+            - name: LINK_ENCRYPTION_REQUIRED
+              value: "true"
+          volumeMounts:
+            - name: cache
+              mountPath: /app/.cache
+            - name: demo
+              mountPath: /app/data_files
+          resources:
+            requests: { cpu: "100m", memory: "256Mi" }
+            limits:   { cpu: "500m", memory: "512Mi" }
+      volumes:
+        - name: cache
+          emptyDir: {}
+        - name: demo
+          nfs:
+            server: 192.168.1.34
+            # OSOBNY udział, pusty na starcie. NIE /mnt/Tank1/astrololo —
+            # to jest cała istota izolacji demo.
+            path: /mnt/Tank1/astrololo-demo
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: data-demo
+  namespace: astrololo
+spec:
+  type: ClusterIP
+  selector: { app: data-demo }
+  ports: [{ port: 8002, targetPort: 8002 }]
+---
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: logic-demo
+  namespace: astrololo
+spec:
+  replicas: 1
+  selector:
+    matchLabels: { app: logic-demo }
+  template:
+    metadata:
+      labels: { app: logic-demo }
+    spec:
+      containers:
+        - name: logic
+          image: gitea.czernobog.pl/gitea/astrololo-logic:latest
+          ports: [{ containerPort: 8001 }]
+          env:
+            # JEDYNA różnica wobec produkcyjnej logiki — i zarazem cała izolacja.
+            - name: DATA_URL
+              value: "http://data-demo:8002"
+            - name: EPHEMERIS_ENGINE
+              value: "own"
+            - name: INTERNAL_TOKEN
+              valueFrom:
+                secretKeyRef: { name: astrololo-auth, key: INTERNAL_TOKEN }
+            - name: LINK_KEY_PRESENTATION_LOGIC
+              valueFrom:
+                secretKeyRef: { name: astrololo-link, key: LINK_KEY_PRESENTATION_LOGIC }
+            - name: LINK_KEY_LOGIC_DATA
+              valueFrom:
+                secretKeyRef: { name: astrololo-link, key: LINK_KEY_LOGIC_DATA }
+            - name: LINK_ENCRYPTION_REQUIRED
+              value: "true"
+            # Bez kluczy do modeli językowych. Astroklient nie umie o nie prosić,
+            # więc ich tu nie ma — czego nie ma w podzie, tego nie wyniesie.
+          resources:
+            requests: { cpu: "100m", memory: "128Mi" }
+            limits:   { cpu: "500m", memory: "512Mi" }
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: logic-demo
+  namespace: astrololo
+spec:
+  type: ClusterIP
+  selector: { app: logic-demo }
+  ports: [{ port: 8001, targetPort: 8001 }]
@@ -0,0 +1,86 @@
+# astrodemo — wersja demonstracyjna (PRE-28).
+#
+# Osobna usługa o DWÓCH funkcjach: dodanie pliku bazy i zapytanie o interpretację
+# urodzeniową. Pozostałe funkcje nie są tu ukryte — nie ma ich w obrazie.
+#
+# IZOLACJA (PRE-29): astrodemo ma WŁASNĄ warstwę logiczną i WŁASNĄ warstwę
+# danych (astrodemo-stack.yaml), pracujące na osobnym, pustym na starcie
+# udziale. Oryginalne bazy interpretacyjne są dla demo NIEOSIĄGALNE.
+#
+# Wewnątrz demo każde konto ma własną pulę plików — swój podkatalog na tym
+# udziale — niewidoczną dla pozostałych kont. Dzięki temu demo można rozdawać
+# szeroko, a pliki jednego klienta da się później przenieść do pełnej aplikacji
+# jako jeden katalog (patrz README-astrodemo.md).
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: astrodemo
+  namespace: astrololo
+spec:
+  replicas: 1
+  selector:
+    matchLabels: { app: astrodemo }
+  template:
+    metadata:
+      labels: { app: astrodemo }
+    spec:
+      containers:
+        - name: astrodemo
+          image: gitea.czernobog.pl/gitea/astrololo-astrodemo:latest
+          ports: [{ containerPort: 8005 }]
+          env:
+            # WŁASNA warstwa logiczna, wskazująca na WŁASNĄ warstwę danych.
+            # Wpisanie tu produkcyjnego `logic` cofnęłoby całą izolację demo
+            # jednym słowem — dlatego stoi to tuż obok siebie w jednym pliku.
+            - name: LOGIC_URL
+              value: "http://logic-demo:8001"
+            # Konto demo — WŁASNE, nie astrololo-auth. Sekret tworzony POZA repo
+            # (jak pozostałe), patrz README-astrodemo.md.
+            # KONTA DEMO — lista `login:sekret` po przecinku. Każde konto ma
+            # WŁASNĄ, niewidoczną dla pozostałych pulę baz (PRE-29), więc jedno
+            # wspólne konto oznaczałoby klientów oglądających swoje wgrania
+            # nawzajem. Sekrety najlepiej jako hash scrypt.
+            - name: ASTRODEMO_USERS
+              valueFrom:
+                secretKeyRef: { name: astrololo-astrodemo, key: ASTRODEMO_USERS }
+            # Token międzywarstwowy i klucz łącza — TE SAME co prezentacja:
+            # demo nie jest furtką omijającą ochronę warstwy logicznej.
+            - name: INTERNAL_TOKEN
+              valueFrom:
+                secretKeyRef: { name: astrololo-auth, key: INTERNAL_TOKEN }
+            - name: LINK_KEY_PRESENTATION_LOGIC
+              valueFrom:
+                secretKeyRef: { name: astrololo-link, key: LINK_KEY_PRESENTATION_LOGIC }
+            - name: LINK_ENCRYPTION_REQUIRED
+              value: "true"
+            # Klucz podpisu ciasteczek sesji (LOG-34). WYMAGANY — pod bez niego
+            # celowo nie wstaje. WŁASNY, nie ten z pełnej aplikacji: demo i produkcja
+            # nie mają powodu uznawać nawzajem swoich sesji, a wspólny klucz
+            # znaczyłby, że sesja z demo bywa ważna tam, gdzie nie powinna.
+            - name: SESSION_SECRET
+              valueFrom:
+                secretKeyRef: { name: astrololo-astrodemo, key: SESSION_SECRET }
+            # Za Ingressem bezpośrednim rozmówcą jest pod Traefika. Bez tego limit
+            # liczyłby WSZYSTKICH do jednego wiadra i pierwsza osoba, która go
+            # wyklika, odcięłaby pozostałe.
+            - name: TRUST_PROXY
+              value: "true"
+            # Niższy niż w pełnej aplikacji: demo bywa udostępniane szerzej,
+            # a każde zapytanie sięga do treści baz.
+            - name: RATE_LIMIT_PER_MIN
+              value: "60"
+          resources:
+            requests: { cpu: "50m", memory: "96Mi" }
+            limits:   { cpu: "300m", memory: "256Mi" }
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: astrodemo
+  namespace: astrololo
+spec:
+  # ClusterIP — wejście z zewnątrz wyłącznie przez Ingress po https, tak samo
+  # jak prezentacja. Druga, nieszyfrowana droga byłaby obejściem PRE-16.
+  type: ClusterIP
+  selector: { app: astrodemo }
+  ports: [{ port: 8005, targetPort: 8005 }]
@@ -0,0 +1,134 @@
+# Własna warstwa danych i logiki dla astroklienta (PR 5).
+#
+# OSOBNY UDZIAŁ, nie osobny katalog na wspólnym. Pule kont izolują klientów od
+# siebie w każdym wariancie, ale to jest izolacja PROGRAMOWA — opiera się na
+# poprawności mechanizmu pul. Granica na poziomie systemu plików nie zależy od
+# tego, czy w kodzie niczego nie przeoczono, i dlatego pliki klientów nie leżą
+# ani przy bazach produkcyjnych, ani przy danych demonstracyjnych.
+#
+# Przy sprzątaniu demo nie da się przez pomyłkę skasować cudzych danych, bo są
+# gdzie indziej.
+---
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: data-astroklient
+  namespace: astrololo
+spec:
+  replicas: 1
+  selector:
+    matchLabels: { app: data-astroklient }
+  template:
+    metadata:
+      labels: { app: data-astroklient }
+    spec:
+      # Warstwa danych ciągnie pandas, a przez nią NumPy budowane z bazą
+      # x86-64-v2. Węzeł bez tych rozszerzeń nie uruchomi kontenera, a komunikat
+      # mówi o „baseline optimizations", nie o węźle. Etykieta jest wymagana,
+      # więc nowy, nieoznaczony węzeł daje czytelny Pending zamiast pętli
+      # restartów (patrz README.md, „Wymóg węzłów: rozszerzenia procesora").
+      affinity:
+        nodeAffinity:
+          requiredDuringSchedulingIgnoredDuringExecution:
+            nodeSelectorTerms:
+              - matchExpressions:
+                  - key: astrololo.czernobog.pl/cpu-x86-64-v2
+                    operator: In
+                    values: ["true"]
+      automountServiceAccountToken: false
+      imagePullSecrets: [{ name: gitea-registry }]
+      containers:
+        - name: data
+          image: gitea.czernobog.pl/gitea/astrololo-data:latest
+          ports: [{ containerPort: 8002 }]
+          env:
+            - name: DATA_PROVIDER
+              value: "excel"
+            - name: EXCEL_DIR
+              value: "/app/data_files"
+            - name: CACHE_DIR
+              value: "/app/.cache"
+            - name: INTERNAL_TOKEN
+              valueFrom:
+                secretKeyRef: { name: astrololo-auth, key: INTERNAL_TOKEN }
+            - name: LINK_KEY_LOGIC_DATA
+              valueFrom:
+                secretKeyRef: { name: astrololo-link, key: LINK_KEY_LOGIC_DATA }
+            - name: LINK_ENCRYPTION_REQUIRED
+              value: "true"
+          volumeMounts:
+            - name: cache
+              mountPath: /app/.cache
+            - name: klient
+              mountPath: /app/data_files
+          resources:
+            requests: { cpu: "100m", memory: "256Mi" }
+            limits:   { cpu: "500m", memory: "512Mi" }
+      volumes:
+        - name: cache
+          emptyDir: {}
+        - name: klient
+          nfs:
+            server: 192.168.1.34
+            path: /mnt/Tank1/astrololo-klient
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: data-astroklient
+  namespace: astrololo
+spec:
+  type: ClusterIP
+  selector: { app: data-astroklient }
+  ports: [{ port: 8002, targetPort: 8002 }]
+---
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: logic-astroklient
+  namespace: astrololo
+spec:
+  replicas: 1
+  selector:
+    matchLabels: { app: logic-astroklient }
+  template:
+    metadata:
+      labels: { app: logic-astroklient }
+    spec:
+      automountServiceAccountToken: false
+      imagePullSecrets: [{ name: gitea-registry }]
+      containers:
+        - name: logic
+          image: gitea.czernobog.pl/gitea/astrololo-logic:latest
+          ports: [{ containerPort: 8001 }]
+          env:
+            - name: DATA_URL
+              value: "http://data-astroklient:8002"
+            # Silnik własny, permisywny. Silnik B (Swiss Ephemeris, AGPL) nie
+            # wchodzi do produktu oddawanego klientom.
+            - name: EPHEMERIS_ENGINE
+              value: "own"
+            - name: INTERNAL_TOKEN
+              valueFrom:
+                secretKeyRef: { name: astrololo-auth, key: INTERNAL_TOKEN }
+            - name: LINK_KEY_PRESENTATION_LOGIC
+              valueFrom:
+                secretKeyRef: { name: astrololo-link, key: LINK_KEY_PRESENTATION_LOGIC }
+            - name: LINK_KEY_LOGIC_DATA
+              valueFrom:
+                secretKeyRef: { name: astrololo-link, key: LINK_KEY_LOGIC_DATA }
+            - name: LINK_ENCRYPTION_REQUIRED
+              value: "true"
+          resources:
+            requests: { cpu: "100m", memory: "128Mi" }
+            limits:   { cpu: "500m", memory: "512Mi" }
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: logic-astroklient
+  namespace: astrololo
+spec:
+  type: ClusterIP
+  selector: { app: logic-astroklient }
+  ports: [{ port: 8001, targetPort: 8001 }]
@@ -0,0 +1,64 @@
+# Astroklient — warstwa pośrednia (PR 4/5).
+#
+# Pełne funkcje astrologiczne, bez generowania tekstu i bez administracji.
+# Obraz NIE ZAWIERA plików usuniętych wg usun.txt, więc nie ma tu czego wyłączać
+# ani czym odsłaniać: to jest osobny produkt, a nie pełna aplikacja z zaciągniętą
+# kurtyną.
+#
+# Konta pochodzą wyłącznie z sekretu (ASTROKLIENT_USERS), każde ma własną pulę
+# plików na udziale astrololo-klient. Nie ma pliku kont, więc nie ma wolumenu
+# stanu: sesje żyją w podpisanym ciasteczku.
+---
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: astroklient
+  namespace: astrololo
+spec:
+  replicas: 1
+  selector:
+    matchLabels: { app: astroklient }
+  template:
+    metadata:
+      labels: { app: astroklient }
+    spec:
+      automountServiceAccountToken: false
+      imagePullSecrets: [{ name: gitea-registry }]
+      containers:
+        - name: astroklient
+          image: gitea.czernobog.pl/gitea/astrololo-astroklient:latest
+          ports: [{ containerPort: 8006 }]
+          env:
+            - name: LOGIC_URL
+              value: "http://logic-astroklient:8001"
+            - name: ASTROKLIENT_USERS
+              valueFrom:
+                secretKeyRef: { name: astrololo-astroklient, key: ASTROKLIENT_USERS }
+            - name: SESSION_SECRET
+              valueFrom:
+                secretKeyRef: { name: astrololo-astroklient, key: SESSION_SECRET }
+            - name: INTERNAL_TOKEN
+              valueFrom:
+                secretKeyRef: { name: astrololo-auth, key: INTERNAL_TOKEN }
+            - name: LINK_KEY_PRESENTATION_LOGIC
+              valueFrom:
+                secretKeyRef: { name: astrololo-link, key: LINK_KEY_PRESENTATION_LOGIC }
+            - name: LINK_ENCRYPTION_REQUIRED
+              value: "true"
+            - name: TRUST_PROXY
+              value: "true"
+            - name: RATE_LIMIT_PER_MIN
+              value: "60"
+          resources:
+            requests: { cpu: "50m", memory: "128Mi" }
+            limits:   { cpu: "500m", memory: "384Mi" }
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: astroklient
+  namespace: astrololo
+spec:
+  type: ClusterIP
+  selector: { app: astroklient }
+  ports: [{ port: 8006, targetPort: 8006 }]
@@ -9,6 +9,30 @@ spec:
  template:
    metadata: { labels: { app: data } }
    spec:
+      # LOG-33: pody nie rozmawiają z API Kubernetesa, więc token konta
+      # serwisowego jest im niepotrzebny — a zamontowany byłby gotowym
+      # punktem wyjścia do klastra dla kogoś, kto przejmie kontener.
+      # Ta usługa liczy na pandas, a przez nią na NumPy. Koła NumPy z PyPI są
+      # budowane z bazą x86-64-v2, więc na węźle bez tych rozszerzeń kontener
+      # NIE WSTAJE: `import numpy` kończy się RuntimeError, pod wpada w pętlę
+      # restartów, a komunikat mówi o „baseline optimizations" — czyli o niczym,
+      # po czym dałoby się poznać, że chodzi o węzeł.
+      #
+      # Wymagana ETYKIETA, a nie wykluczony konkretny węzeł. Nowy węzeł jest
+      # domyślnie NIEOZNACZONY, więc nie dostanie tu poda, dopóki ktoś go nie
+      # sprawdzi (skrypt w README) i nie oznaczy świadomie. Pending z czytelnym
+      # powodem jest lepszy niż pętla restartów z komunikatem o optymalizacjach —
+      # a wykluczanie węzłów po nazwie znaczyłoby, że każdy KOLEJNY źle
+      # postawiony węzeł znów zbiera się przez awarię.
+      affinity:
+        nodeAffinity:
+          requiredDuringSchedulingIgnoredDuringExecution:
+            nodeSelectorTerms:
+              - matchExpressions:
+                  - key: astrololo.czernobog.pl/cpu-x86-64-v2
+                    operator: In
+                    values: ["true"]
+      automountServiceAccountToken: false
      imagePullSecrets: [{ name: gitea-registry }]
      containers:
        - name: data
@@ -40,12 +64,31 @@ spec:
            # zdążyłby wypuścić zapytanie jawnym tekstem, zanim dostanie odmowę.
            - name: LINK_ENCRYPTION_REQUIRED
              value: "true"
+            # Lustro baz w SQL (DAN-28). DSN w SEKRECIE, bo niesie hasło —
+            # w manifeście zostałoby w historii gita na zawsze.
+            #
+            # Sam adres nie przełącza jeszcze warstwy na SQL: o tym decyduje
+            # DATA_PROVIDER, które celowo zostaje na `excel`, dopóki lustro nie
+            # jest zaimplementowane i sprawdzone. Dzięki temu Postgres można
+            # wdrożyć i obejrzeć BEZ ryzyka dla działającego wyszukiwania.
+            - name: SQL_URL
+              valueFrom:
+                secretKeyRef: { name: astrololo-postgres, key: SQL_URL }
          volumeMounts:
            - name: cache
              mountPath: /app/.cache
+            # ZAPISYWALNY od DAN-27. Wcześniej read-only, bo warstwa danych tylko
+            # czytała bazy — teraz ekran „Pliki" pozwala je wgrywać, archiwizować
+            # i (dla administratora) kasować, a stan użycia jest KLIKANY, więc musi
+            # przetrwać restart poda.
+            #
+            # ŚWIADOMY KOSZT: znika jedna warstwa obrony w głąb. Przejęcie warstwy
+            # danych pozwala teraz nie tylko odczytać bazy, ale i je zmienić.
+            # Zostaje reszta: token międzywarstwowy, szyfrowane łącze, ograniczenie
+            # eksportu NFS do konkretnych hostów (DAN-25) i to, że kasować może
+            # wyłącznie konto administracyjne (PRE-27).
            - name: excel
              mountPath: /app/data_files
-              readOnly: true
          resources:
            requests: { cpu: "100m", memory: "256Mi" }
            limits:   { cpu: "500m", memory: "512Mi" }
@@ -34,6 +34,15 @@ spec:
          imageName: gitea.czernobog.pl/gitea/astrololo-presentation
        - alias: render
          imageName: gitea.czernobog.pl/gitea/astrololo-render
+        # Wersja demo (PRE-28). Obraz, którego nie ma na tej liście, NIGDY się nie
+        # podbije, choćby CI go budowało — tak przez chwilę wisiał render na :latest.
+        - alias: astrodemo
+          imageName: gitea.czernobog.pl/gitea/astrololo-astrodemo
+        # BEZ TEGO WPISU nowa usługa NIE DEPLOYUJE SIĘ SAMA: obraz powstaje
+        # w rejestrze, ale kustomization zostaje na starym tagu i wygląda to na
+        # zepsute CI. Tak zawisł kiedyś render.
+        - alias: astroklient
+          imageName: gitea.czernobog.pl/gitea/astrololo-astroklient
  commonUpdateSettings:
    updateStrategy: newest-build
  writeBackConfig:
@@ -73,3 +73,85 @@ spec:
            pathType: Prefix
            backend:
              service: { name: presentation, port: { number: 8000 } }
+---
+# ── astrodemo ──────────────────────────────────────────────────────────────
+# Osobny host, nie ścieżka pod astrololo.czernobog.pl. Ścieżka („/demo") dzieliłaby
+# z pełną aplikacją pochodzenie w rozumieniu przeglądarki, czyli i ciasteczka:
+# wejście do jednej ruszałoby sesję w drugiej. Osobny host trzyma je rozdzielnie.
+apiVersion: networking.k8s.io/v1
+kind: Ingress
+metadata:
+  name: astrodemo
+  namespace: astrololo
+  annotations:
+    traefik.ingress.kubernetes.io/router.entrypoints: websecure
+    traefik.ingress.kubernetes.io/router.middlewares: astrololo-security-headers@kubernetescrd
+spec:
+  tls:
+    - hosts: [astrodemo.czernobog.pl]
+      secretName: astrololo-tls           # ten sam certyfikat obejmuje oba hosty (tls.yaml)
+  rules:
+    - host: astrodemo.czernobog.pl
+      http:
+        paths:
+          - path: /
+            pathType: Prefix
+            backend:
+              service: { name: astrodemo, port: { number: 8005 } }
+---
+apiVersion: networking.k8s.io/v1
+kind: Ingress
+metadata:
+  name: astrodemo-redirect
+  namespace: astrololo
+  annotations:
+    traefik.ingress.kubernetes.io/router.entrypoints: web
+    traefik.ingress.kubernetes.io/router.middlewares: astrololo-redirect-https@kubernetescrd
+spec:
+  rules:
+    - host: astrodemo.czernobog.pl
+      http:
+        paths:
+          - path: /
+            pathType: Prefix
+            backend:
+              service: { name: astrodemo, port: { number: 8005 } }
+---
+apiVersion: networking.k8s.io/v1
+kind: Ingress
+metadata:
+  name: astroklient
+  namespace: astrololo
+  annotations:
+    traefik.ingress.kubernetes.io/router.entrypoints: websecure
+    traefik.ingress.kubernetes.io/router.middlewares: astrololo-security-headers@kubernetescrd
+spec:
+  tls:
+    - hosts: [astroklient.czernobog.pl]
+      secretName: astrololo-tls           # ten sam certyfikat obejmuje wszystkie hosty (tls.yaml)
+  rules:
+    - host: astroklient.czernobog.pl
+      http:
+        paths:
+          - path: /
+            pathType: Prefix
+            backend:
+              service: { name: astroklient, port: { number: 8006 } }
+---
+apiVersion: networking.k8s.io/v1
+kind: Ingress
+metadata:
+  name: astroklient-redirect
+  namespace: astrololo
+  annotations:
+    traefik.ingress.kubernetes.io/router.entrypoints: web
+    traefik.ingress.kubernetes.io/router.middlewares: astrololo-redirect-https@kubernetescrd
+spec:
+  rules:
+    - host: astroklient.czernobog.pl
+      http:
+        paths:
+          - path: /
+            pathType: Prefix
+            backend:
+              service: { name: astroklient, port: { number: 8006 } }
@@ -2,18 +2,32 @@ apiVersion: kustomize.config.k8s.io/v1beta1
 kind: Kustomization
 resources:
  - namespace.yaml
+  - postgres.yaml # lustro baz Excela w SQL (DAN-28) — sekret astrololo-postgres POZA repo
  - data.yaml
  - logic.yaml
+  - astrodemo-stack.yaml # OSOBNA warstwa danych i logiki dla demo (PRE-29)
+  - astrodemo.yaml # wersja demo (PRE-28) — sekret astrololo-astrodemo POZA repo
+  - astroklient-stack.yaml # OSOBNA warstwa danych i logiki dla astroklienta (PR 5)
+  - astroklient.yaml # warstwa pośrednia — sekret astrololo-astroklient POZA repo
  - presentation.yaml
  - render.yaml # składanie raportu PDF (PRE-24), osobny obraz z TeX Live
  - tls.yaml # certyfikat z własnego CA (wymaga cert-managera)
  - ingress.yaml # wejście po https + przekierowanie z http
+  # Definicja obserwatora obrazów — WDRAŻANA, a nie wklepywana ręcznie.
+  # Póki jej tu nie było, plik w gicie i stan klastra rozjeżdżały się w ciszy:
+  # dopisanie usługi do listy nie robiło nic, bo listy nikt nie stosował.
+  # Mieszka w przestrzeni argocd — projekt to dopuszcza (destinations: '*').
+  - image-updater.yaml
 images:
  - name: gitea.czernobog.pl/gitea/astrololo-data
-    newTag: 8ebce816
+    newTag: fd79513c
  - name: gitea.czernobog.pl/gitea/astrololo-logic
-    newTag: 8ebce816
+    newTag: 10970c57
  - name: gitea.czernobog.pl/gitea/astrololo-render
-    newTag: latest
+    newTag: cf24c4d4
  - name: gitea.czernobog.pl/gitea/astrololo-presentation
-    newTag: 8ebce816
+    newTag: 338ec24e
+  - name: gitea.czernobog.pl/gitea/astrololo-astrodemo
+    newTag: fd79513c
+  - name: gitea.czernobog.pl/gitea/astrololo-astroklient
+    newTag: 10970c57
@@ -9,6 +9,10 @@ spec:
  template:
    metadata: { labels: { app: logic } }
    spec:
+      # LOG-33: pody nie rozmawiają z API Kubernetesa, więc token konta
+      # serwisowego jest im niepotrzebny — a zamontowany byłby gotowym
+      # punktem wyjścia do klastra dla kogoś, kto przejmie kontener.
+      automountServiceAccountToken: false
      imagePullSecrets: [{ name: gitea-registry }]
      containers:
        - name: logic
@@ -0,0 +1,150 @@
+# Postgres — lustro baz Excela w SQL (DAN-28).
+#
+# DLACZEGO POSTGRES, A NIE SQLITE. Nie ze względu na skalę: dzisiejszy zbiór to
+# ~54 tys. wierszy, przy których SQLite bywa szybszy. Powodem jest WYSZUKIWANIE
+# w nieznormalizowanym, polskim tekście — `pg_trgm` (dopasowanie rozmyte, literówki)
+# i `unaccent` (ogonki) nie mają w SQLite taniego zamiennika, a to jest główna
+# funkcja programu, nie dodatek. Drugi powód: `pg_advisory_lock` sprawia, że model
+# sesji z atomowym commitem przestaje zakładać „jedna replika na zawsze".
+#
+# TO LUSTRO, NIE ŹRÓDŁO PRAWDY. Źródłem są pliki Excela na NFS. Utrata tej bazy
+# NIE JEST utratą danych — odbudowuje się z plików. Dlatego kopie zapasowe są tu
+# OPCJONALNE, a wolumen może stać na local-path.
+---
+apiVersion: v1
+kind: PersistentVolumeClaim
+metadata:
+  name: postgres-data
+  namespace: astrololo
+spec:
+  accessModes: [ReadWriteOnce]
+  # local-path (domyślny provisioner k3s), NIE NFS. Postgres zakłada semantykę
+  # blokad i fsync, której NFS nie gwarantuje — to klasyczne źródło uszkodzenia
+  # bazy przy nagłym restarcie. Ceną jest przywiązanie do węzła; przy luście
+  # odtwarzalnym z Excela to akceptowalne.
+  storageClassName: local-path
+  resources:
+    requests:
+      storage: 5Gi
+---
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: postgres-init
+  namespace: astrololo
+data:
+  # UWAGA: skrypty z /docker-entrypoint-initdb.d/ uruchamiają się WYŁĄCZNIE przy
+  # pierwszej inicjalizacji, na pustym katalogu danych. Dopisanie tu rozszerzenia
+  # PO utworzeniu bazy nic nie zrobi — trzeba je wtedy założyć ręcznie (patrz
+  # README-postgres.md, sekcja „Dodanie rozszerzenia do istniejącej bazy").
+  01-extensions.sql: |
+    -- Dopasowanie rozmyte: similarity(), operator %, indeksy GIN po trigramach.
+    -- To jest powód, dla którego stoi tu Postgres, a nie SQLite.
+    CREATE EXTENSION IF NOT EXISTS pg_trgm;
+    -- Zdejmowanie ogonków: „różdżka" ma się znaleźć na „rozdzka".
+    CREATE EXTENSION IF NOT EXISTS unaccent;
+
+    -- Schemat na lustro. Osobny, żeby purge i odbudowa nie musiały ruszać
+    -- niczego w `public` i żeby `DROP SCHEMA mirror CASCADE` był bezpiecznym
+    -- „wyczyść wszystko i wczytaj od nowa".
+    CREATE SCHEMA IF NOT EXISTS mirror;
+
+    -- Rejestr luster: co, z jakiego pliku, o jakim skrócie i kiedy wczytane.
+    -- Zgodność pliku z tabelą poznajemy po sha256 — nazwa pliku nie wystarcza,
+    -- bo treść potrafi się zmienić bez zmiany nazwy.
+    CREATE TABLE IF NOT EXISTS mirror.registry (
+      table_name   text PRIMARY KEY,
+      source_path  text NOT NULL UNIQUE,
+      sha256       text NOT NULL,
+      row_count    integer NOT NULL DEFAULT 0,
+      loaded_at    timestamptz NOT NULL DEFAULT now(),
+      active       boolean NOT NULL DEFAULT false
+    );
+    CREATE INDEX IF NOT EXISTS registry_active_idx ON mirror.registry (active);
+---
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: postgres
+  namespace: astrololo
+spec:
+  replicas: 1
+  # Recreate, NIE RollingUpdate: wolumen jest ReadWriteOnce, a dwa procesy
+  # Postgresa na jednym katalogu danych to uszkodzona baza. Rolling próbowałby
+  # wstać z nowym podem, zanim stary zejdzie.
+  strategy:
+    type: Recreate
+  selector:
+    matchLabels: { app: postgres }
+  template:
+    metadata:
+      labels: { app: postgres }
+    spec:
+      containers:
+        - name: postgres
+          # Wersja PRZYPIĘTA i celowo poza image-updaterem: podbicie majora
+          # Postgresa wymaga migracji katalogu danych, więc nie może się zdarzyć
+          # samo, w nocy, przy okazji builda aplikacji.
+          image: postgres:17
+          ports: [{ containerPort: 5432, name: postgres }]
+          env:
+            - name: POSTGRES_DB
+              value: astrololo
+            - name: POSTGRES_USER
+              value: astrololo
+            - name: POSTGRES_PASSWORD
+              valueFrom:
+                secretKeyRef: { name: astrololo-postgres, key: POSTGRES_PASSWORD }
+            # PGDATA w PODKATALOGU montowanego wolumenu. Katalog główny wolumenu
+            # potrafi zawierać wpisy systemu plików (np. lost+found), a initdb
+            # odmawia inicjalizacji w niepustym katalogu.
+            - name: PGDATA
+              value: /var/lib/postgresql/data/pgdata
+            # C.UTF-8 zamiast pl_PL.UTF-8: dopasowanie tekstu robimy przez
+            # unaccent i pg_trgm, nie przez collation, a locale pl_PL wymagałoby
+            # obrazu z wygenerowanymi lokalizacjami. Gdyby kiedyś potrzebne było
+            # polskie SORTOWANIE, dokłada się collation ICU na konkretnej kolumnie.
+            - name: POSTGRES_INITDB_ARGS
+              value: "--encoding=UTF8 --locale=C.UTF-8"
+          volumeMounts:
+            - name: data
+              mountPath: /var/lib/postgresql/data
+            - name: init
+              mountPath: /docker-entrypoint-initdb.d
+              readOnly: true
+          # pg_isready, nie zwykły TCP: gniazdo słucha, zanim baza przyjmuje
+          # zapytania, więc sonda po porcie przepuściłaby ruch za wcześnie.
+          readinessProbe:
+            exec:
+              command: ["pg_isready", "-U", "astrololo", "-d", "astrololo", "-q"]
+            initialDelaySeconds: 5
+            periodSeconds: 5
+          livenessProbe:
+            exec:
+              command: ["pg_isready", "-U", "astrololo", "-d", "astrololo", "-q"]
+            initialDelaySeconds: 30
+            periodSeconds: 20
+            failureThreshold: 6
+          resources:
+            requests: { cpu: "100m", memory: "256Mi" }
+            limits:   { cpu: "1000m", memory: "1Gi" }
+      volumes:
+        - name: data
+          persistentVolumeClaim:
+            claimName: postgres-data
+        - name: init
+          configMap:
+            name: postgres-init
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: postgres
+  namespace: astrololo
+spec:
+  # ClusterIP i tylko ClusterIP. Baza nie ma żadnego powodu być widoczna poza
+  # klastrem; dostęp z zewnątrz robi się przez `kubectl port-forward` na czas
+  # jednej sesji (patrz README-postgres.md).
+  type: ClusterIP
+  selector: { app: postgres }
+  ports: [{ port: 5432, targetPort: 5432 }]
@@ -9,6 +9,10 @@ spec:
  template:
    metadata: { labels: { app: presentation } }
    spec:
+      # LOG-33: pody nie rozmawiają z API Kubernetesa, więc token konta
+      # serwisowego jest im niepotrzebny — a zamontowany byłby gotowym
+      # punktem wyjścia do klastra dla kogoś, kto przejmie kontener.
+      automountServiceAccountToken: false
      imagePullSecrets: [{ name: gitea-registry }]
      containers:
        - name: presentation
@@ -28,6 +32,13 @@ spec:
                secretKeyRef: { name: astrololo-auth, key: INTERNAL_TOKEN }
            - name: APP_USER
              value: "astrololo"
+            # Klucz podpisu ciasteczek sesji (LOG-34). WYMAGANY — pod bez niego
+            # celowo nie wstaje: usługa z kontami, ale bez klucza, nie umiałaby
+            # odróżnić ważnej sesji od podrobionej. Rotacja tego klucza WYLOGOWUJE
+            # WSZYSTKICH, i tak ma być — to jest awaryjny wyłącznik.
+            - name: SESSION_SECRET
+              valueFrom:
+                secretKeyRef: { name: astrololo-auth, key: SESSION_SECRET }
            - name: RATE_LIMIT_PER_MIN
              value: "120"                       # 0 = bez limitu
            # Aplikacja stoi za Ingressem, więc bezpośrednim rozmówcą jest zawsze
@@ -56,9 +67,36 @@ spec:
                secretKeyRef: { name: astrololo-link, key: LINK_KEY_PRESENTATION_RENDER }
            - name: LINK_ENCRYPTION_REQUIRED
              value: "true"
+            # Konta zakładane z ekranu „Konta" (PRE-26). Konto administracyjne
+            # zostaje w APP_USER/APP_PASSWORD powyżej — celowo, bo dzięki temu
+            # NIE DA SIĘ go skasować ani ograniczyć z aplikacji.
+            - name: ACCOUNTS_FILE
+              value: "/app/state/accounts.json"
+          volumeMounts:
+            # OSOBNY UDZIAŁ, nie podkatalog udziału z bazami. Pierwsza wersja
+            # montowała /mnt/Tank1/astrololo z subPath — i nie wstała:
+            # „failed to create subPath directory”. Powód był podwójny i oba razy
+            # ten sam brak: udział z bazami jest wyeksportowany `ro: true`
+            # z `root_squash` (DAN-25), więc (1) kubelet nie mógł utworzyć
+            # podkatalogu, a (2) gdyby nawet mógł, aplikacja i tak nie zapisałaby
+            # tam pliku kont.
+            #
+            # Osobny udział rozwiązuje to bez naruszania DAN-25: udział z bazami
+            # ZOSTAJE tylko do odczytu, a konta mają własne, małe miejsce.
+            # Przy okazji znika subPath, czyli znika potrzeba, żeby kubelet
+            # cokolwiek zakładał — katalog istnieje, bo jest korzeniem udziału.
+            - name: state
+              mountPath: /app/state
          resources:
            requests: { cpu: "100m", memory: "128Mi" }
            limits:   { cpu: "300m", memory: "256Mi" }
+      volumes:
+        - name: state
+          nfs:
+            server: 192.168.1.34
+            # Udział WYŁĄCZNIE na stan prezentacji (konta z PRE-27). Wymaga
+            # utworzenia na TrueNAS — patrz README-stan-prezentacji.md.
+            path: /mnt/Tank1/astrololo-state
 ---
 apiVersion: v1
 kind: Service
@@ -19,6 +19,10 @@ spec:
  template:
    metadata: { labels: { app: render } }
    spec:
+      # LOG-33: pody nie rozmawiają z API Kubernetesa, więc token konta
+      # serwisowego jest im niepotrzebny — a zamontowany byłby gotowym
+      # punktem wyjścia do klastra dla kogoś, kto przejmie kontener.
+      automountServiceAccountToken: false
      imagePullSecrets: [{ name: gitea-registry }]
      containers:
        - name: render
@@ -59,6 +59,10 @@ spec:
  commonName: astrololo.czernobog.pl
  dnsNames:
    - astrololo.czernobog.pl
+    # Jeden certyfikat na oba hosty. Osobny wymagałby osobnego sekretu i osobnego
+    # odnawiania, a to ten sam klaster i ten sam wystawca.
+    - astrodemo.czernobog.pl
+    - astroklient.czernobog.pl
  duration: 2160h                         # 90 dni
  renewBefore: 720h                       # 30 dni zapasu
  privateKey: { algorithm: ECDSA, size: 256, rotationPolicy: Always }
@@ -0,0 +1,106 @@
+# Production ("deploy") Conjurer bot
+
+A second Conjurer bot that runs **alongside** the test `bot` in the `conjurer`
+namespace, sharing the same librarian / musician / radio and the shared
+`CONJURER_API_KEY`. It differs from the test bot only in:
+
+- its Discord token: the **`deploy-conjurer-netrc`** secret (already created),
+- distinct names/labels (`deploy-bot`) and NodePort **32443**,
+- **`/data` on NFS (RWX)** instead of a block PVC — so you can seed/upload files
+  while it runs and back it up concurrently.
+
+Files: `deploy-bot.yaml` (Deployment + Service), `deploy-bot-backup.yaml`
+(daily backup CronJob). Both are wired into `kustomization.yaml`.
+
+## Update channel — only on `[deploy]`
+
+Unlike the test bot (which tracks every build), the production bot updates **only
+when you promote a version**. It runs a **separate image**,
+`conjurer-bot-deploy`, which the conjurer CI tags **only when the commit message
+contains `[deploy]`** (it re-tags the already-built `conjurer-bot:<sha>` — same
+bytes). The image-updater's `deploy-bot` alias then bumps this bot's tag.
+
+So: normal commits update the test bot + librarian; a commit with `[deploy]` in
+its message is the one that also rolls the production bot.
+
+**Already bootstrapped:** the channel was seeded by the first `[deploy]` commit
+(the merge of conjurer#20), which promoted `conjurer-bot-deploy:fbd1ec9f` — the
+tag pinned in `kustomization.yaml`. From here the image-updater keeps it current
+on each future `[deploy]` commit. Note the librarian is shared and still tracks
+latest, so mind large bot⇄librarian version skews.
+
+If you ever need to seed a tag by hand:
+```bash
+docker pull gitea.czernobog.pl/gitea/conjurer-bot:<sha>
+docker tag  gitea.czernobog.pl/gitea/conjurer-bot:<sha> \
+            gitea.czernobog.pl/gitea/conjurer-bot-deploy:<sha>
+docker push gitea.czernobog.pl/gitea/conjurer-bot-deploy:<sha>
+```
+
+## One-time setup
+
+1. **Secret** — already exists as `deploy-conjurer-netrc` (a netrc carrying the
+   deploy Discord token, key `.netrc`). Nothing to do; the Deployment mounts it
+   at `/secrets/.netrc`.
+
+2. **NFS export** — create the data + backup dirs on the NFS server
+   (`192.168.1.34`, adjust to your real export):
+   ```
+   /mnt/Tank1/conjurer_swap/deploy-bot/data
+   /mnt/Tank1/conjurer_swap/deploy-bot/backups
+   ```
+
+## Seeding / uploading config & state into /data
+
+Because `/data` is a plain NFS export, you upload files by copying them onto the
+share — **no `kubectl cp`, no scaling the bot down**. From the PVE box that holds
+`/srv/data` (mount the same export there, or rsync over it):
+
+```bash
+# on a host that can see the NFS export:
+rsync -a /srv/data/ 192.168.1.34:/mnt/Tank1/conjurer_swap/deploy-bot/data/
+```
+
+The bot roots everything under `CONJURER_DATA_DIR=/data`, so these land where it
+expects them:
+
+```
+accident_log.json  Conjurer_graphics/  music/  pamiec.json
+pamiec_muzyki.json  settings.json  system_gpt_settings.json  transcripts/
+```
+
+Upload as much or as little as you like — the bot seeds any missing JSON on
+first run. Live-editing `pamiec.json` while the bot writes to it can race; prefer
+seeding before first start or during a brief `kubectl -n conjurer scale
+deploy/deploy-bot --replicas=0` window.
+
+## Backups (production only)
+
+`deploy-bot-backup` runs daily (04:17) and writes to the `backups` export:
+
+- `current/` — a full rsync mirror of `/data` (incl. music/graphics), always
+  the latest state,
+- `snapshots/deploy-state-<date>.tgz` — dated archives of the critical small
+  state (both memories, settings, accident log, transcripts), kept
+  `RETENTION_DAYS` (30) days.
+
+The test bot is deliberately **not** backed up (amnesia there is fine).
+
+Restore example:
+```bash
+tar xzf snapshots/deploy-state-2026-08-03-0417.tgz -C /mnt/.../deploy-bot/data/
+```
+
+## Routing librarian / musician callbacks
+
+**Librarian — handled automatically.** Each bot advertises its own
+`CONJURER_SELF_CALLBACK` (test `…:32442`, this bot `…:32443`) on every query and
+ping, and the librarian answers each result/pong back to the bot that asked. One
+librarian serves both bots — no `CONJURER_MAIN_BOT` repointing needed. (The
+librarian keeps `CONJURER_MAIN_BOT: http://bot:5000` only as a fallback for a bot
+that doesn't send a callback.)
+
+**Musician — still single-target.** The musician pushes "now playing" events to
+its one `CONJURER_MAIN_BOT` (currently the test bot, `192.168.1.73:32442`). Only
+one bot gets radio events; repoint the musician's `CONJURER_MAIN_BOT` to
+`192.168.1.73:32443` if the production bot should show them instead.
@@ -28,6 +28,22 @@ spec:
            - { name: CONJURER_FILE_SERVICE,     value: "http://192.168.1.89:5000" }

            - { name: CONJURER_RADIO_HARBOR,      value: "http://192.168.1.79:54321" }
+            # Where the librarian sends THIS bot's results/pongs back to (its own
+            # NodePort). Lets one librarian serve both bots - see deploy-bot.yaml.
+            - { name: CONJURER_SELF_CALLBACK,     value: "http://192.168.1.73:32442" }
+            # Self-hosted models (Ollama). No API key - the endpoint IS the
+            # configuration, and the backend stays unselectable while unset.
+            # Pick a model at runtime with: $gadaj_teraz ollama <model>
+            # ($modele_ai lists what the server actually has pulled).
+            - { name: CONJURER_OLLAMA_URL,        value: "http://192.168.1.72:11434" }
+            # The server currently has exactly one model pulled (verified via
+            # /v1/models): gemma4:e2b. Without this the built-in default
+            # (llama3.1:8b) would be requested and every reply would fail.
+            - { name: CONJURER_OLLAMA_MODEL,      value: "gemma4:e2b" }
+            # Self-hosted generation is far slower than a hosted API, especially
+            # the first request after the model is evicted from VRAM. Applies to
+            # every backend, so keep it only as high as you actually need.
+            - { name: CONJURER_AI_TIMEOUT_SECONDS, value: "240" }
          volumeMounts:
            - { name: data,  mountPath: /data }
            - { name: netrc, mountPath: /secrets, readOnly: true }
@@ -17,3 +17,6 @@ spec:
      images:
        - { alias: "librarian",  imageName: "gitea.czernobog.pl/gitea/conjurer-librarian" }
        - { alias: "bot",        imageName: "gitea.czernobog.pl/gitea/conjurer-bot" }
+        # Production bot tracks its own image, which only gets new tags on
+        # [deploy] commits (conjurer CI) - so it updates only on promoted builds.
+        - { alias: "deploy-bot", imageName: "gitea.czernobog.pl/gitea/conjurer-bot-deploy" }
@@ -0,0 +1,65 @@
+# Daily backup of the PRODUCTION ("deploy") bot's /data.
+#
+# Only production is backed up - the test bot's amnesia is fine, this bot's is
+# not (pamiec.json / pamiec_muzyki.json are the conversation & music memory).
+# Both volumes are NFS (RWX), so this runs while the bot is live - no RWO clash.
+#
+# Two-part backup:
+#   * a full, space-efficient MIRROR (rsync --delete) of everything, incl. music
+#     and graphics - always the current state,
+#   * dated SNAPSHOTS of just the small critical state (the memories, settings,
+#     accident log, transcripts) so you can roll back to a point in time.
+# Snapshots older than RETENTION_DAYS are pruned.
+apiVersion: batch/v1
+kind: CronJob
+metadata:
+  name: deploy-bot-backup
+  namespace: conjurer
+spec:
+  schedule: "17 4 * * *"          # every day at 04:17
+  concurrencyPolicy: Forbid
+  successfulJobsHistoryLimit: 3
+  failedJobsHistoryLimit: 3
+  jobTemplate:
+    spec:
+      backoffLimit: 2
+      template:
+        spec:
+          restartPolicy: Never
+          containers:
+            - name: backup
+              image: alpine:3.20
+              command: ["/bin/sh", "-c"]
+              args:
+                - |
+                  set -eu
+                  apk add --no-cache rsync >/dev/null
+                  STAMP="$(date +%F-%H%M)"
+                  mkdir -p /backup/current /backup/snapshots
+                  echo "[$STAMP] mirroring /data -> /backup/current"
+                  rsync -a --delete /data/ /backup/current/
+                  echo "[$STAMP] snapshotting critical state"
+                  tar czf "/backup/snapshots/deploy-state-$STAMP.tgz" -C /data \
+                      accident_log.json pamiec.json pamiec_muzyki.json \
+                      settings.json system_gpt_settings.json transcripts \
+                      2>/dev/null || echo "  (some files absent - skipped)"
+                  echo "[$STAMP] pruning snapshots older than ${RETENTION_DAYS}d"
+                  find /backup/snapshots -name 'deploy-state-*.tgz' -type f \
+                      -mtime +"${RETENTION_DAYS}" -delete
+                  echo "[$STAMP] backup done"
+              env:
+                - { name: RETENTION_DAYS, value: "30" }
+              volumeMounts:
+                - { name: data,   mountPath: /data,   readOnly: true }
+                - { name: backup, mountPath: /backup }
+          volumes:
+            # Same export the bot mounts (read-only here).
+            - name: data
+              nfs:
+                server: 192.168.1.34
+                path: /mnt/Tank1/conjurer_swap/deploy-bot/data
+            # Backup target - ADJUST to your export.
+            - name: backup
+              nfs:
+                server: 192.168.1.34
+                path: /mnt/Tank1/conjurer_swap/deploy-bot/backups
@@ -0,0 +1,93 @@
+# Production ("deploy") Conjurer bot.
+#
+# Same infrastructure as the test `bot` (shares librarian / musician / radio and
+# the CONJURER_API_KEY), with three deliberate differences:
+#   1. its Discord token comes from the `deploy-conjurer-netrc` secret,
+#   2. distinct names/labels so it coexists with the test bot in this namespace,
+#   3. /data is an NFS volume (RWX) instead of a block PVC - so config/state can
+#      be uploaded while the bot runs (just copy onto the share) and backed up
+#      concurrently (see deploy-bot-backup.yaml). The test bot keeps its RWO PVC.
+#
+# ┌─ IMPORTANT: librarian & musician call ONE bot back ─────────────────────────┐
+# │ The librarian (CONJURER_MAIN_BOT) and musician push search results and      │
+# │ "now playing" events to a SINGLE bot address - currently the test bot's     │
+# │ NodePort 192.168.1.73:32442. Only one bot can receive them. To make the     │
+# │ PRODUCTION bot the one that gets librarian results / radio events, repoint   │
+# │ those services' CONJURER_MAIN_BOT to this bot's NodePort (…:32443 below).    │
+# └─────────────────────────────────────────────────────────────────────────────┘
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: deploy-bot
+  namespace: conjurer
+spec:
+  replicas: 1                     # NIGDY więcej — jedna sesja gateway na token
+  strategy: { type: Recreate }    # NIE RollingUpdate — dwa pody = wojna o sesję Discord
+  selector: { matchLabels: { app: deploy-bot } }
+  template:
+    metadata: { labels: { app: deploy-bot } }
+    spec:
+      imagePullSecrets: [{ name: gitea-registry }]
+      containers:
+        - name: bot
+          # SEPARATE image from the test bot: conjurer-bot-deploy only gets a new
+          # tag when a commit message contains [deploy] (see the conjurer CI), so
+          # this bot updates only on versions you explicitly promote. Tag is
+          # managed by the image-updater (kustomization images:).
+          image: gitea.czernobog.pl/gitea/conjurer-bot-deploy:c8aae106
+          ports: [{ containerPort: 5000 }]
+          env:
+            - { name: CONJURER_DATA_DIR,      value: "/data" }
+            - { name: CONJURER_DISCORD_HOST,  value: "0.0.0.0" }
+            - { name: CONJURER_DISCORD_PORT,  value: "5000" }
+            - { name: CONJURER_API_KEY,  value: "d97008b3-7a5a-11f1-acd1-000b0e0f00ed" }
+            - { name: CONJURER_NETRC_FILE, value: "/secrets/.netrc" }
+            - { name: CONJURER_LIBRARIAN_SERVICE, value: "http://librarian:5001" }
+            - { name: CONJURER_MUSICIAN_SERVICE,  value: "http://192.168.1.89:5000" }
+            - { name: CONJURER_RADIO_SERVICE,     value: "http://192.168.1.79:5005" }
+            - { name: CONJURER_FILE_SERVICE,      value: "http://192.168.1.89:5000" }
+            - { name: CONJURER_RADIO_HARBOR,      value: "http://192.168.1.79:54321" }
+            # This bot's own callback (its NodePort). The librarian records it per
+            # query and answers results/pongs HERE - so it serves this bot AND the
+            # test bot from one instance, no CONJURER_MAIN_BOT repointing needed.
+            - { name: CONJURER_SELF_CALLBACK,     value: "http://192.168.1.73:32443" }
+            # Self-hosted models (Ollama). No API key - the endpoint IS the
+            # configuration, and the backend stays unselectable while unset.
+            # Pick a model at runtime with: $gadaj_teraz ollama <model>
+            # ($modele_ai lists what the server actually has pulled).
+            - { name: CONJURER_OLLAMA_URL,        value: "http://192.168.1.72:11434" }
+            # The server currently has exactly one model pulled (verified via
+            # /v1/models): gemma4:e2b. Without this the built-in default
+            # (llama3.1:8b) would be requested and every reply would fail.
+            - { name: CONJURER_OLLAMA_MODEL,      value: "gemma4:e2b" }
+            # Self-hosted generation is far slower than a hosted API, especially
+            # the first request after the model is evicted from VRAM. Applies to
+            # every backend, so keep it only as high as you actually need.
+            - { name: CONJURER_AI_TIMEOUT_SECONDS, value: "240" }
+          volumeMounts:
+            - { name: data,  mountPath: /data }
+            - { name: netrc, mountPath: /secrets, readOnly: true }
+          resources:
+            requests: { cpu: "200m", memory: "256Mi" }
+            limits:   { cpu: "2",    memory: "1Gi" }
+      volumes:
+        # /data on NFS (RWX): lets you seed/upload files while the bot runs (copy
+        # straight onto the export from the PVE box that holds /srv/data) and lets
+        # the backup CronJob read it concurrently. ADJUST server/path to your
+        # actual export - mirrors the librarian's 192.168.1.34 Tank1 layout.
+        - name: data
+          nfs:
+            server: 192.168.1.34
+            path: /mnt/Tank1/conjurer_swap/deploy-bot/data
+        - name: netrc
+          secret: { secretName: deploy-conjurer-netrc }
+---
+apiVersion: v1
+kind: Service
+metadata: { name: deploy-bot, namespace: conjurer }
+spec:
+  type: NodePort                  # so librarian/musician COULD reach it if repointed
+  selector: { app: deploy-bot }
+  # Distinct pinned nodePort (test bot owns 32442). Point librarian/musician
+  # CONJURER_MAIN_BOT at 192.168.1.73:32443 to route their callbacks here.
+  ports: [{ port: 5000, targetPort: 5000, nodePort: 32443 }]
@@ -4,8 +4,16 @@ resources:
  - namespace.yaml
  - librarian.yaml
  - bot.yaml
+  - deploy-bot.yaml
+  - deploy-bot-backup.yaml
 images:
  - name: gitea.czernobog.pl/gitea/conjurer-librarian
-    newTag: 40605b95
+    newTag: c91ec03b
  - name: gitea.czernobog.pl/gitea/conjurer-bot
-    newTag: 8e18071b
+    newTag: c91ec03b
+  # Production bot channel - only bumped when a [deploy]-tagged build appears.
+  # Bootstrapped to fbd1ec9f: that's the image the first [deploy] build (merge
+  # of conjurer#20) promoted to conjurer-bot-deploy. From here the image-updater
+  # keeps it current across future [deploy] commits.
+  - name: gitea.czernobog.pl/gitea/conjurer-bot-deploy
+    newTag: fbd1ec9f