kb-wiki/_meta/conventions.md

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

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