struktura: katalogi, konwencje, README

Szkielet kb-wiki wg docs/kb/modules/05-faza3-plan.md §8.2 (homelab-codex-ws,
read-only stąd): typy stron jako katalogi (podmioty/osoby/sprawy/umowy/tematy),
_meta/conventions.md (frontmatter z blokiem sources, format przypisów
[^envelope_id#chunk_id], zasady flagowania sprzeczności i wersji dokumentów,
zasady lintu), README z ostrzeżeniem że treść jest LLM-kompilowana.

.gitignore

@@ -0,0 +1 @@
+.DS_Store

README.md

@@ -0,0 +1,59 @@
+# kb-wiki
+
+Warstwa pamięci domowej bazy wiedzy (moduł 5, faza 3 — `homelab-codex-ws`,
+`docs/kb/modules/05-faza3-plan.md` §8). Wzorzec: Karpathy llm-wiki
+(gist `karpathy/442a6bf555914893e9891c11519de94f`).
+
+## Czym to jest
+
+Dwuwarstwowa architektura KB:
+
+- **Warstwa dowodowa** (`kb-postgres@PIHA`, poza tym repo): RAG/pgvector na
+  chunkach dokumentów — skala docelowa 225k+ kopert, zawsze lokalna, zawsze
+  źródło prawdy.
+- **Warstwa pamięci** (to repo): strony-encje w Markdownie (firma, umowa,
+  sprawa, temat), kompilowane **z wyników retrievalu**, nie z surowców —
+  destylat, nie kopia.
+
+## ⚠️ Treść jest kompilowana przez LLM
+
+Każda strona w tym repo została napisana przez model językowy (Claude) na
+podstawie wyników zapytań do kaskady retrievalu (streszczenia + chunki z
+`kb-postgres`), **nie przez człowieka czytającego oryginalne dokumenty**.
+Fakty liczbowe i identyfikujące mają przypisy `[^envelope_id#chunk_id]`
+wskazujące źródłowy chunk — **weryfikuj przypis przy każdej decyzji, która
+się na tej stronie opiera** (finansowej, prawnej, ubezpieczeniowej). Sprzeczne
+źródła są flagowane jawnie w tekście, nie ukrywane, ale kompilacja może mimo
+to pominąć niuans, którego model nie uznał za istotny.
+
+## Jak działa kompilacja
+
+1. Zapytanie po polsku trafia do kaskady retrievalu (`documents_ingest.retrieval`,
+   pakiet z `homelab-codex-ws/jobs/documents-ingest`): embed (bge-m3, Ollama)
+   → top-N `document_summary` (model `claude-haiku-4-5`) → top-k
+   `document_chunk` w obrębie tych kopert, zawsze `WHERE excluded_reason IS NULL`.
+2. Sesja CC/API dostaje zwrócone chunki + streszczenia, pisze/aktualizuje
+   stronę Markdown: fakty wyłącznie ze źródeł, przypis inline przy każdym
+   fakcie liczbowym/identyfikującym, blok `sources` we frontmatterze agregujący
+   wszystkie użyte koperty.
+3. Commit do `master` z opisem `compile: <strona> ← <envelope_ids>` — historia
+   commitów tego repo **jest** audytowalną historią kompilacji (inwariant 6
+   szkicu operatora), stąd commitowanie bezpośrednio na `master`, bez task
+   branchy (inny reżim niż `homelab-codex-ws`, patrz uzasadnienie niżej).
+
+Format stron, konwencje linkowania i zasady lintu: `_meta/conventions.md`.
+
+## Dlaczego osobne repo, nie katalog w homelab-codex-ws
+
+Decyzja D7 planu fazy 3: inna klasa wrażliwości (ten wiki jest destylatem danych
+osobistych — zdrowie, finanse, umowy — `homelab-codex-ws` to kod infry) i inny
+cykl commitów (kompilator commituje często i maszynowo; w repo infry zaśmiecałoby
+to historię i gryzłoby się z dyscypliną worktree tamtego repo). Git history tutaj
+= darmowy audit trail kompilacji, czystszy gdy w historii są wyłącznie strony wiki.
+
+## Status
+
+Proof-of-concept fazy 3: struktura + `_meta/conventions.md` + 3–5 stron-encji
+skompilowanych ręcznie sesją CC z wyników retrievalu. Pełna kompilacja korpusu
+(225k+ kopert, przyrostowo) i integracja stron wiki z retrievalem jako
+trzeci poziom kaskady — poza zakresem tej fazy, patrz plan §8.2 i §9.

_meta/conventions.md

@@ -0,0 +1,150 @@
+---
+title: Konwencje kb-wiki
+type: meta
+status: active
+tags: []
+sources: []
+compiled_by: claude-sonnet-5
+compiled_at: 2026-07-21
+updated_at: 2026-07-21
+---
+
+# Konwencje kb-wiki
+
+Ten dokument definiuje format stron tej wiki. Rozwinięcie decyzji architektonicznych
+z `homelab-codex-ws`, `docs/kb/modules/05-faza3-plan.md` §8 (szkic operatora, NIE
+zmieniamy stamtąd decyzji — tylko doprecyzowujemy wykonanie). To repo jest read-write
+tylko dla kompilatora (CC/API); baza źródłowa (`kb-postgres@PIHA`) jest zawsze
+read-only z tej strony.
+
+## Struktura katalogów
+
+Typy stron = katalogi; płasko wewnątrz każdego, graf robią linki `[[...]]`, nie
+hierarchia plików.
+
+| Katalog | Zawartość |
+|---|---|
+| `podmioty/` | Firmy i instytucje: ubezpieczyciele, banki, urzędy — encje trwałe, nie procesy |
+| `osoby/` | Tożsamości/aliasy osób fizycznych |
+| `sprawy/` | Procesy w czasie: sezony, remonty, procesy decyzyjne, porównania ofert |
+| `umowy/` | Konkretne, zawarte kontrakty/polisy — jeden dokument prawny lub jego wersje |
+| `tematy/` | Przekrojowe kategorie łączące wiele podmiotów/spraw (np. „ubezpieczenia auto”) |
+| `_meta/` | Ten plik, raporty lintu |
+
+Wybór katalogu dla nowej strony: jeśli encja to firma/instytucja → `podmioty/`;
+jeśli to coś co się dzieje/działo w czasie (sezon, spór, zakup) → `sprawy/`; jeśli to
+konkretna umowa prawna → `umowy/`; jeśli łączy wiele podmiotów pod wspólnym parasolem
+tematycznym → `tematy/`.
+
+## Frontmatter
+
+```yaml
+---
+title: <nazwa strony, czytelna>
+type: podmiot            # podmiot | osoba | sprawa | umowa | temat | meta
+status: active            # active | archived
+tags: [ubezpieczenie]     # słownik wspólny z jobs/documents-ingest/tags-vocab.yaml
+                          # (homelab-codex-ws) — nie wymyślamy nowego słownika dla wiki
+sources:
+  - envelope_id: paperless:119
+    chunks: [4211, 4213]           # document_chunk.id (klucz PK), NIE chunk_index
+  - envelope_id: "CABtrY-...@mail.gmail.com"
+    chunks: []                     # koperta bez chunków (np. sam manifest)
+compiled_by: claude-sonnet-5       # model/sesja, która skompilowała/ostatnio zmieniła stronę
+compiled_at: 2026-07-20            # data pierwszej kompilacji
+updated_at: 2026-07-20             # data ostatniej zmiany
+---
+```
+
+`sources` agreguje **wszystkie** koperty, z których cokolwiek na stronie pochodzi —
+niezależnie od tego, ile razy dana koperta jest cytowana w treści. To jest poziom
+audytu „skąd strona czerpie w ogóle”; poziom „ten konkretny fakt” robią przypisy
+inline (niżej).
+
+## Przypisy inline i cytowanie faktów
+
+Każdy fakt liczbowy lub identyfikujący (kwota, data, numer polisy/umowy, adres,
+próg punktowy) dostaje przypis w miejscu użycia:
+
+```markdown
+składka 1 234 zł/rok [^paperless:119#4212]
+```
+
+Format: `[^<envelope_id>#<document_chunk.id>]`. Jeden fakt może mieć więcej niż
+jeden przypis, jeśli potwierdzają go niezależnie różne chunki/koperty — wtedy oba
+się wypisuje: `[^paperless:14#965][^paperless:22#2081]`.
+
+Fakty opisowe/narracyjne (np. „PZU oferuje kilka wariantów ubezpieczenia") niosące
+niską specyficzność mogą dzielić jeden przypis na koniec akapitu zamiast przypisu
+po każdym zdaniu — przypis jest obowiązkowy per sekcja, nie per zdanie, ale musi
+dawać się prześledzić do konkretnego chunka.
+
+**Zakaz dopowiadania**: jeśli fakt nie występuje w żadnym pobranym chunku/streszczeniu,
+strona pisze wprost „brak danych w KB" zamiast go zgadywać z wiedzy ogólnej modelu.
+
+## Sprzeczności między źródłami
+
+Gdy dwa dokumenty (typowo: dwie wersje tego samego OWU z różnymi datami
+obowiązywania, albo dwie oferty konkurencyjne) podają różne wartości dla tego
+samego faktu, strona **nie wybiera cicho jednej wersji**. Sprzeczność jest
+flagowana jawnie w tekście, z obiema wartościami i obu przypisami, np.:
+
+```markdown
+Udział własny w AC: 300 zł wg OWU obowiązującego od 21.03.2026 [^paperless:14#871],
+ale 500 zł wg wcześniejszej wersji OWU [^paperless:17#XXXX] — **rozbieżność między
+wersjami, nie literówka**; przy sporze o odszkodowanie decyduje wersja obowiązująca
+w dniu zdarzenia.
+```
+
+## Wersjonowanie dokumentów źródłowych
+
+Ubezpieczenia i regulaminy w korpusie mają wielokrotne wersje z różnymi datami
+„obowiązuje od". Strona encji **nie kompiluje jednej płaskiej prawdy** — jeśli
+źródła mają rozbieżne daty obowiązywania, strona wymienia wersje osobno (np.
+podsekcja per data) zamiast nadpisywać starszą nowszą bez adnotacji. To był
+konkretny finding z pilota dedupa (`docs/kb/eval/retrieval-pilot-2026-07-16.md`,
+`docs/kb/modules/05-faza3-plan.md` §3.2) — dokumenty bywają też **duplikatami
+binarnymi** (`excluded_reason='duplicate'` w bazie), co jest czymś innym niż
+kolejna wersja: duplikat pomijamy w kompilacji (baza już to wyklucza z retrievalu),
+wersję z inną datą obowiązywania — nie.
+
+## Linkowanie między stronami
+
+`[[nazwa-pliku-bez-rozszerzenia]]` — link do innej strony wiki po nazwie pliku
+(bez katalogu, nazwy plików są unikalne w całym repo). Linkujemy tam, gdzie treść
+się faktycznie styka (wspólny podmiot, wspólna sprawa, przywoływany dokument) —
+nie tworzymy linków na wyrost do stron, które jeszcze nie istnieją, chyba że
+świadomie oznaczamy brakujące pojęcie (patrz niżej), bo taki link psuje inwariant
+lintu „brak stron-sierot i wiszących linków" dopóki strona docelowa nie powstanie.
+
+## Brakujące pojęcia (przyszłe strony)
+
+Jeśli podczas kompilacji natrafiamy na encję wartą osobnej strony, ale poza
+zakresem bieżącej kompilacji (np. inny ubezpieczyciel wspomniany punktowo, inna
+sprawa), **nie tworzymy linku `[[...]]`** do niej (byłby wiszący). Zamiast tego
+kandydatka trafia do listy „brakujące pojęcia" w najbliższym raporcie lintu
+(`_meta/lint-reports/`), żeby nie zgubić się w wątku.
+
+## Zasady lintu
+
+Okresowy lint (ręczny w tej fazie, `_meta/lint-reports/YYYY-MM-DD.md`) sprawdza:
+
+1. **Strony-sieroty** — strona bez żadnego linku przychodzącego z innej strony
+   (poza `INDEX.md`, który z definicji linkuje do wszystkiego).
+2. **Wiszące linki** — `[[cel]]` bez odpowiadającego pliku `cel.md` w repo.
+3. **Brakujące pojęcia** — encje wspomniane w treści (nie w linku) a nieopisane
+   osobną stroną; kandydaci na przyszłe strony, nie błąd.
+4. **Spot-check** — dla losowej próbki przypisów `[^envelope_id#chunk_id]`
+   weryfikacja, że treść chunka w bazie faktycznie potwierdza przywołany fakt.
+5. **Sprzeczności międzystronicowe** — ten sam fakt o tej samej encji opisany
+   różnie na dwóch stronach (nie mylić z rozbieżnością międzywersyjną w obrębie
+   jednej strony, która jest już jawnie flagowana w treści per wyżej).
+
+## Integracja z retrievalem (poza zakresem tej fazy)
+
+Docelowo strony wiki wchodzą do `kb-postgres` jako koperty `source='wiki'`
+(`id='wiki:<katalog>/<plik>'`), embedowane tym samym pipeline'em co chunki
+dokumentów — kaskada retrievalu rozszerza się wtedy o trzeci poziom: wiki →
+streszczenie → chunk. Nie jest to realizowane w tej fazie (proof-of-concept
+ręcznej kompilacji 3–5 stron) — patrz `docs/kb/modules/05-faza3-plan.md` §8.2
+w `homelab-codex-ws` po szczegóły.