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