kb-wiki/_meta/conventions.md

title	type	status	tags	sources	compiled_by	compiled_at	updated_at
Konwencje kb-wiki	meta	active			claude-sonnet-5	2026-07-21	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

---
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:

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.:

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.