docs: dokumentacja MkDocs + odchudzone README/CLAUDE.md + skill docs-sync

[mpasternak]

Co i dlaczego

Dotąd README (702 linie) i CLAUDE.md (~30 KB) duplikowały większość treści, co prowadziło do dryfu. Ten PR rozdziela dokumentację na trzy powierzchnie o jasnym przeznaczeniu i wprowadza narzędzie utrzymujące je w synchronizacji.

Powierzchnia	Odbiorca	Czego jest źródłem prawdy
README.md	Nowy operator na GitHubie	Instalacja + pierwsze uruchomienie + linki do dokumentacji
docs/ (MkDocs → GitHub Pages)	Operator prowadzący BPP	Cała dokumentacja operacyjna i referencyjna
CLAUDE.md	Agenci AI edytujący repo	Konwencje, niezmienniki, kontrakty, wskaźniki do plików

Zmiany

• docs/ — 29 stron w 7 sekcjach (instalacja, konfiguracja, eksploatacja, monitoring, architektura, rozwiązywanie problemów, rozwój). Treść zmigrowana i rozbudowana z README + CLAUDE.md (m.in. architektura konfiguracji/force-sync, healthchecks+autoheal, zadania Ofelii, retencja Loki, kolektory Netdata, slow queries, dashboardy, kontrakt backwards-compat).
• MkDocs Material: mkdocs.yml (polski, dark mode, nawigacja zakładkowa, walidacja kotwic) + docs/requirements.txt.
• GitHub Pages: .github/workflows/docs.yml — mkdocs build --strict + mkdocs gh-deploy na push do main (ze ścieżek docs/**, mkdocs.yml).
• README: 702 → 219 linii — zostają tylko Jak zainstalować i uruchomić + Wspólne kroki konfiguracji + tabela linków.
• CLAUDE.md: ~30 KB → 11 KB — twarde niezmienniki dla agenta (lista force-sync, single-instance denorm-queue, logging: przy nowych serwisach, kontrakt .env), reszta jako wskaźniki do docs/.
• Skill docs-sync (.claude/skills/docs-sync/, commitowany do repo) — mapa „co gdzie należy", checklista zmiana → pliki do dotknięcia, niezmienniki, brama mkdocs build --strict. Użyty do przeprowadzenia tej migracji.
• .gitignore — przepuszcza .claude/skills/ (skill współdzielony), chowa lokalne dane Claude i site/.
• .pre-commit-config — check-yaml wyklucza mkdocs.yml (tagi !!python/name: Material nie są safe-loadowalne; waliduje je mkdocs build --strict).

Po stronie maintainera (wymagane do publikacji)

⚠️ Włącz GitHub Pages w Settings → Pages ze źródłem branch gh-pages (workflow utworzy go przy pierwszym uruchomieniu). site_url zakłada https://iplweb.github.io/bpp-deploy/.

Weryfikacja

• ✅ mkdocs build --strict z walidacją kotwic — 0 błędów/warningów
• ✅ ./tests/test_makefile.sh — 119 passed, 0 failed
• ✅ Brak trailing-whitespace, wszystkie pliki z finalnym newline

🤖 Generated with Claude Code