--- title: Konwencje kb-wiki type: meta status: active tags: [] sources: [] compiled_by: claude-sonnet-5 compiled_at: 2026-07-21 updated_at: 2026-08-27 --- # 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: 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: `[^#]`. 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. ## Sekcja „Brak danych w KB" (rozszerzenie, faza 5 etap 1 rekoncyliacja, 2026-08-27) „Zakaz dopowiadania" wyżej mówi, że pojedynczy fakt bez pokrycia w źródłach pisze się wprost jako „brak danych w KB" w miejscu użycia. To rozszerzenie formalizuje to jako **osobną sekcję na końcu strony**, odróżnioną od „Niepewne / sprzeczne": - **„Niepewne / sprzeczne"** — dowody **istnieją**, ale się nie zgadzają (dwa chunki, dwie wartości, dwa przypisy). - **„Brak danych w KB"** — zapytano retrievalem o coś istotnego dla tej encji, i **żaden** pobrany chunk/streszczenie tego nie potwierdza. Nie jest to błąd kompilacji — jest to jawne przyznanie granicy tego, co korpus dziś wie, zamiast milczącego pominięcia pytania. Format — krótka lista na końcu strony, po „Niepewne / sprzeczne" (jeśli obie występują): ```markdown ## Brak danych w KB - Nazwisko trenera drużyny (OCR nieczytelny w `paperless:175`). - Wynik końcowy/klasyfikacja drużyny w całym turnieju (KB ma tylko wyniki cząstkowe). ``` Praktyczna wartość: kolejna kompilacja/aktualizacja tej strony (albo lint) wie od razu, czego szukać przy następnym retrievalu, zamiast rekonstruować to z pamięci sesji albo przeczytać stronę i domyślać się, co zostało pominięte a co nigdy nie było sprawdzone. Pierwszy przykład użycia (przed formalizacją tej reguły): `sprawy/fll-2025-26.md`, sekcja „Brak danych w KB", kompilacja 2026-07-21. ## 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:/'`), 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.