ckb/README.pl.md

# Cascade Knowledge Base

*Read this in: [English](README.md) | **Polski***

**Repozytorium źródłowe (zawsze najbardziej aktualna wersja):**
[git.wierzbowa.cloud/michal/ckb](https://git.wierzbowa.cloud/michal/ckb)

Warstwowa, zarządzana przez agenta wiki, w której lokalna zawartość nadpisuje
tylko-do-odczytu źródła nadrzędne (upstream). Zbudowana na wzorcu LLM Wiki
Karpathy'ego, rozszerzonym o skalowanie, zarządzanie cyklem życia i wsparcie
dla wielu agentów.

Ten dokument to techniczny przegląd funkcji. Zorientowany na zadania
przewodnik — jak stworzyć wiki, dodawać wiedzę, utrzymywać porządek,
synchronizować się z innymi i przykłady dla każdego przypadku użycia —
znajdziesz w [MANUAL.pl.md](MANUAL.pl.md) ([English](MANUAL.md)).

Jeśli ta baza dokumentuje tworzone przez Ciebie oprogramowanie, opcjonalny moduł
`software` dodaje repozytoria w `src/` i pracę sterowaną specyfikacją — zobacz
[OPENSPEC.pl.md](OPENSPEC.pl.md) ([English](OPENSPEC.md)).

Pełny schemat strony oraz historię obu numerów wersji znajdziesz w
[CHANGELOG.pl.md](CHANGELOG.pl.md) ([English](CHANGELOG.md)).

### Kanały wydawnicze

Repozytorium szablonu utrzymuje trzy gałęzie. Nie są wymienne:

| Gałąź | Czym jest | Kto powinien ją śledzić |
|---|---|---|
| `main` | **Stabilna** — wydany szablon | Wszyscy, domyślnie |
| `test` | **Kandydat do wydania** — walidowany przed scaleniem do `main` | Każdy, kto pomaga walidować wydanie albo potrzebuje poprawki, która weszła, ale jeszcze nie została wydana |
| `experimental` | **Rozwojowa** — bieżąca praca, może być zepsuta albo wycofana | Osoby rozwijające sam szablon |

Zarówno `ckb-init`, jak i `ckb-upgrade` domyślnie używają `main`. Żeby użyć
innego kanału, po prostu powiedz którego: *„zainicjuj z gałęzi test"*,
*„sprawdź experimental pod kątem aktualizacji"*, *„przełącz tę KB z powrotem
na kanał stabilny"*. Śledzona gałąź jest zapisana w `ckb.yaml`:

```yaml
template:
  repo: https://git.wierzbowa.cloud/michal/ckb.git
  branch: main
```

KB bez `ckb.yaml` (albo bez bloku `template:`) jest traktowana jako śledząca
`main` — czyli dokładnie to, co i tak robiła każda KB sprzed tej konwencji.

---

## Struktura katalogów

```
├── libs/         # Zewnętrzne źródła tylko do odczytu — kopie git (w .gitignore) LUB
│                 #   konfiguracje konektora (source.yaml) z własnym generowanym indeksem
├── linked/       # Zewnętrzne bazy wiedzy tylko do odczytu, montowane jako dowiązania symboliczne
├── outputs/      # Wygenerowane artefakty, eksporty, skompilowane pliki
├── raw/          # Materiał źródłowy dostarczony przez użytkownika
│   └── inbox/    # Strefa zrzutu: nieprzetworzony materiał
├── tmp/          # Pliki tymczasowe, cache (w .gitignore)
├── wiki/         # Lokalna, ustrukturyzowana wiki w markdown (zarządzana przez agenta)
│   ├── index.md      # Tabela routingu z wyzwalaczami „Use when" + kb_schema_version
│   ├── overview.md   # Mapa wysokiego poziomu
│   ├── log.md        # Główny dziennik zmian (rollup)
│   ├── error-book.md # Błędy kompilacji i wyprowadzone ograniczenia
│   ├── decisions/    # Numerowane, tylko-dopisywane zapisy decyzji + własny index.md i log.md
│   ├── entities/     # Typowane strony encji (osoby, projekty, koncepcje) + własny index.md
│   └── graph/        # Listy krawędzi i dane relacji + własny index.md
└── workload/     # Podsumowania sesji i decyzje
    └── YYYY-MM-DD_summary.md
```

---

## Priorytet kaskady

Podczas wyszukiwania warstwy są sprawdzane w kolejności — pierwsze trafienie
wygrywa:

```
wiki/        (najwyższy)  ← agent zapisuje tutaj, zawsze wygrywa
linked/A/    (średni)     ← zamontowane przez symlink wiki nadrzędne
linked/B/    (niski)      ← zamontowane przez symlink wiki nadrzędne
libs/A/      (najniższy)  ← kopie zewnętrznych baz wiedzy zarządzane przez git, albo własny generowany indeks konektora
```

Agent nigdy nie zapisuje do `linked/` ani do `libs/<name>/` będącego kopią
git. Aby poprawić treść nadrzędną, zapisz właściwą wersję w `wiki/` —
automatycznie zyskuje pierwszeństwo. Jedynym wyjątkiem jest `libs/<name>/`
oparty na konektorze (zobacz „Konektory zewnętrznych źródeł i indeksowanie”
poniżej) — agent zarządza jego generowanym indeksem tak samo, jak `wiki/`.

---

## Funkcje

### Przepływ oparty na skrzynce odbiorczej (Inbox)
Wrzuć dowolny surowy materiał (notatki, artykuły, linki) do `raw/inbox/` bez
porządkowania. Po komendzie „Ingest" (lub „Sync the wiki" / „Update the
wiki"), agent przetwarza skrzynkę odbiorczą — wydobywa wiedzę, zapisuje ją w
`wiki/` i archiwizuje przetworzone elementy do `raw/` — a następnie
przypomina o przejrzeniu wyniku i uruchomieniu „sync changes", aby wypchnąć
zmiany do `origin`, gdy będziesz z nich zadowolony. Zaimplementowane jako
Claude Code Skill — zobacz `.agents/skills/ckb-ingest/SKILL.md` — zamiast
być zaszytym w `CLAUDE.md`/`AGENTS.md`, dzięki czemu pełna procedura ładuje
się do kontekstu tylko wtedy, gdy jest faktycznie wywoływana. Odrębne od
skilla `ckb-sync-changes`, który jest czysto operacją na poziomie gita, bez
syntezy wiki.

Dla długich rozmów, notatek ze spotkań, transkryptów lub eksportów czatu
ingest używa strukturalnej destylacji, zamiast traktować cały plik jako jedną
niezróżnicowaną bryłę: wyszukiwalne pytanie, krótkie podsumowanie,
rozwiązanie lub decyzja, odniesienia do systemów/kodu, zaangażowane osoby
oraz fragmenty o wysokiej wartości, które zasługują na to, by pozostać
znajdowalne samodzielnie.

„Wysoka wartość" to jawny test, a nie ocena uznaniowa — inaczej każdy
fragment wygląda na wart zachowania, a strona staje się drugą kopią
transkryptu. Fragment zasługuje na własną wyszukiwalną sekcję tylko wtedy,
gdy zawiera termin rzadki w całej wiki (sprawdzane przez `rg -c` — wyróżniający
uchwyt wyszukiwania, a nie słowo już obecne na dwudziestu stronach), ma około
200 znaków lub więcej i jest potwierdzony przez coś dalej w materiale, co się
z nim zgadza, działa na jego podstawie lub go koryguje. Niespełnienie choćby
jednego warunku oznacza, że treść nadal trafia na stronę, tylko wewnątrz
podsumowania, a nie jako osobna jednostka. Awansowane fragmenty zabierają ze
sobą nagłówek nadrzędny lub pytanie wątku, żeby dały się jednoznacznie
czytać samodzielnie.

### Leniwie ładowany indeks z wyzwalaczami „Use When"
`wiki/index.md` to tabela routingu. Każdy wpis ma kolumnę **Use when** z
listą słów kluczowych wyzwalających. Agent najpierw czyta indeks (pozostaje
w kontekście), dopasowuje słowa kluczowe do zadania i ładuje tylko pasujące
strony. Zmniejsza to narzut kontekstu z ~12K do ~3.2K tokenów na zadanie.

### Warstwa zapytań oparta na TLDR
Każda strona zawiera jednozdaniowe podsumowanie `tldr` we frontmatterze.
Podczas zapytania agent najpierw czyta TLDR-y. Jeśli TLDR już odpowiada na
pytanie, pełna treść nigdy nie jest ładowana. Łańcuch odwoławczy: TLDR →
treść → surowe źródło.

### Lokalne zakresy projektów
Dla powracających zespołów, klientów, systemów lub inicjatyw wiki może
trzymać zwykłe strony zakresów w formacie Markdown pod `wiki/projects/`.
Strona zakresu wymienia strony wiki, encje, źródła z `raw/archive/`,
konektorowe `libs/`, wyjścia i obszary grafu, które należy przeszukać
najpierw dla danego projektu. Daje to tę samą praktyczną korzyść co
przestrzeń robocza projektu w większym systemie wyszukiwania, pozostając
lokalnym, przejrzystym i edytowalnym w dowolnym edytorze tekstu.

Zakresy zawężają tylko pierwsze przejście. Jeśli wyszukiwanie w zakresie nie
odpowiada na pytanie, agent wraca do pełnej kaskady.

### Lokalne wyszukiwanie hybrydowe
Gdy routing po indeksie/TLDR nie wystarcza, agent może połączyć kilka
lokalnych sygnałów przed odpowiedzią:
- dokładne wyszukiwanie tekstu przez `rg` dla komunikatów błędów, komend,
  flag, nazw plików, nazw hostów, identyfikatorów zgłoszeń i innych
  literalnych tokenów — również w `raw/inbox/`, więc materiał wrzucony
  godzinę temu i jeszcze nie zingestowany nadal może odpowiedzieć na pytanie
  (i sygnalizuje, że ingest jest zaległy)
- dopasowania semantyczne/encyjne z tytułów stron, TLDR-ów, zakresów
  projektów i relacji w grafie
- metadane świeżości i pewności, dzięki którym nieaktualne lub słabe strony
  są traktowane ostrożnie
- rozszerzenie kontekstu wokół dopasowanej sekcji, aby odpowiedzi były
  osadzone w sąsiadujących nagłówkach i akapitach, a nie w samotnym urywku

Każdy sygnał tworzy własną listę rankingową, a listy są następnie łączone,
zamiast rozstrzygania przez wybór ulubionego sygnału: każdy kandydat zbiera
`weight / (k + rank)` zsumowane po listach, na których występuje, więc strona
na trzecim miejscu w trzech listach wygrywa ze stroną pierwszą w jednej.
`k` wynosi 10, celowo mniej niż zwykle cytowane 60 — 60 jest dostrojone do
wyszukiwarek zwracających setki kandydatów i spłaszcza wszystkie wyniki do
niemal identycznych wartości przy kilkunastu, które daje lokalna wiki.
Zapytania o literalne tokeny podnoszą wagę listy dokładnych dopasowań,
ponieważ żadne podobieństwo tytułu nie powinno wyprzedzić trafienia w dokładny
ciąg, który ktoś wklejił.

Połączeni kandydaci są następnie deduplikowani według twierdzenia — strona
wiki, plik z `raw/archive/`, który cytuje, i strona konektora wskazująca na
nią to trzy trafienia dla jednego faktu, nie trzy źródła — i przerankowani w
skali 0–10 według tego, jak dobrze odpowiadają na dosłownie zadane pytanie, a
nie jak dobrze pasują do jego sformułowania. Ten sam agent, świadome drugie
przejście, bez osobnego modelu.

Wynik jest wewnętrznie normalizowany jako pakiet dowodowy: ścieżka źródła,
dopasowane twierdzenie, data/świeżość, pewność/jakość, wskazówki o relacjach
lub zakresie oraz informacja, z których sygnałów każdy kandydat został
połączony. Nie jest wymagany żaden serwer, baza wektorowa ani dedykowany
klient.

### Zastrzeżenia w odpowiedziach
Metadane, które wiki już śledzi, są podawane w samej odpowiedzi, a nie tylko
sprawdzane przy jej budowaniu. Gdy strona stanowiąca podstawę odpowiedzi
przekroczyła `freshness_window_days`, ma niską `confidence`/`quality`, opiera
się na niezingestowanym materiale z `raw/inbox/` lub została sprawdzona
względem zapisanego w pamięci indeksu konektora, a nie żywego źródła —
odpowiedź mówi o tym obok twierdzenia, którego to dotyczy. Konflikty między
dwiema aktywnymi stronami są ujawniane tak samo, nawet jeśli żadna nie ma
jeszcze `superseded_by`. Zamyka to tryb awarii polegający na pewnej
odpowiedzi *z* nieaktualnej strony bez przekazania tej informacji dalej.

### Wyszukiwanie ekspertów i właścicieli
„Kto wie o X" i „kto jest właścicielem X" to bezpośrednie zapytania do grafu,
a nie zgadywanie po pełnym tekście. Ingest zapisuje krawędzie
`has_expertise_in`, gdy ktoś wykazuje się odpowiadaniem na pytania lub
wyjaśnianiem decyzji w danym temacie, oraz krawędzie `owns` dla zadeklarowanej
odpowiedzialności za system, obszar lub decyzję — oba wyłącznie na podstawie
wykazanych dowodów, nigdy wnioskowane z obecności na spotkaniu czy ze
stanowiska. Gdy krawędzi jeszcze nie ma, wyszukiwanie wraca do dowodów
autorstwa i mówi, które z dwóch stanowiło podstawę odpowiedzi, bo domniemany
ekspert to słabsze twierdzenie niż zapisany.

### Zapisy decyzji
`wiki/decisions/` zawiera jedną numerowaną stronę na decyzję
(`NNNN-slug.md`): co zostało zdecydowane, przez kogo (`decided_by`), kiedy
(`decided_on`), dlaczego, jakie alternatywy odpadły i czego decyzja dotyczy
(`affects`). Pole `status`
(`proposed`/`accepted`/`rejected`/`superseded`/`reversed`) mówi, czy decyzja
faktycznie obowiązuje, a opcjonalna data `review_on` oznacza ją do przeglądu.

Strony decyzji są **tylko do dopisywania**. Gdy wybór się zmienia, *nowa*
decyzja zastępuje starą — `supersedes`/`superseded_by` ustawiane są po obu
stronach, status starej zmienia się na `superseded` lub `reversed`, a jej
pierwotny kontekst i uzasadnienie pozostają nietknięte. To właśnie sprawia,
że „dlaczego jest tak, jak jest?" da się odpowiedzieć po latach, i zamienia
„używamy Postgresa" w „używamy Postgresa, a wcześniej MySQL-a, zmienione we
wrześniu z powodu raportowania". `decided_by` i `affects` stają się też
krawędziami grafu, więc „kto zdecydował o X" i „jakie decyzje dotyczą Y" to
bezpośrednie wyszukania. Skill `ckb-decide` zapisuje decyzje i odpowiada na
pytania o nie; `ckb-lint` sprawdza ich strukturę (słownik statusów, wymagane
daty, dwustronne zastępowanie, unikalne numery, zaległe przeglądy).

### Luki w zapytaniach
Jeśli kaskada nie potrafi odpowiedzieć na pytanie, agent zapisuje lub proponuje
krótki wpis w `wiki/query-gaps.md`: o co pytano, gdzie szukał i jakie
najmniejsze źródło lub strona zamknęłaby lukę. Dzięki temu nieudane
wyszukiwania stają się użytecznym sygnałem zapotrzebowania dla następnego
ingestu, zamiast przepadać w historii czatu.

### Schemat frontmatteru strony
Każda strona wiki używa frontmatteru YAML. Pole `type` jest wymagane; reszta
jest opcjonalna:

```yaml
---
type: concept              # WYMAGANE. Otwarty ciąg znaków: person, project, concept, library, decision, playbook, ...
resource: https://...      # Kanoniczny URI do autorytatywnego zewnętrznego źródła, które opisuje ta strona
tldr: Jednozdaniowe podsumowanie zoptymalizowane pod odczyt przez LLM
confidence: 0.0–1.0      # Wynik potwierdzenia przez źródła
quality: 0.0–1.0          # Samoocena (poniżej 0.7 → oflagowane)
supersedes: path/to/old.md
superseded_by: path/to/new.md
last_updated: YYYY-MM-DD
freshness_window_days: 90 # Liczba dni, po których treść uznaje się za nieaktualną
retention: high|medium|low
source_fingerprint: sha256:3f9a2c1e   # skrót źródła, z którego zbudowano tę stronę
source_checked: YYYY-MM-DD            # kiedy ten skrót był ostatnio zweryfikowany
---
```

- **type** — wymagane; niezarejestrowany ciąg znaków, nowe wartości są
  zawsze poprawne, czytelnicy tolerują nierozpoznane
- **resource** — opcjonalny wskaźnik do żywego/autorytatywnego źródła,
  oddzielony od własnego komentarza wiki
- **confidence** — ustawiane przy zapisie, zanika z czasem, wzmacniane przez
  nowe źródła
- **quality** — samoocena przy zapisie, strony poniżej 0.7 oflagowane do
  przeglądu
- **supersedes / superseded_by** — gdy nowa informacja zastępuje starą,
  połącz je
- **freshness_window_days** — strony starsze niż to okno są oflagowane
  podczas lintowania
- **retention** — strony o niskim priorytecie są archiwizowane po 2× oknie
  świeżości
- **source_fingerprint / source_checked** — skrót materiału, z którego
  zsyntetyzowano stronę, oraz data ostatniego potwierdzenia. Okno świeżości to
  przypuszczenie, że źródło *mogło* się zmienić; skrót to fakt, czy *się
  zmieniło* — i lint sprawdza go mechanicznie.

#### Zastrzeżone sekcje treści
Cztery nagłówki `##` mają w całej KB ściśle określone znaczenie:

| Sekcja | Co zawiera |
|---|---|
| `## Sources` | po jednym punkcie na źródło, każdy ze skrótem |
| `## Crux` | dosłowne cytaty z tych źródeł — dowód, nigdy parafraza |
| `## Notes` | pisane przez człowieka i **chronione**: żaden skill ich nie nadpisuje |

`## Crux` pozwala odpowiedzieć na pytanie ze strony zamiast z archiwum:
streszczenie może po cichu odpłynąć od źródła, cytat albo wciąż się z nim
zgadza, albo nie. `## Notes` daje odwrotną gwarancję — na stronach
regenerowanych przez agenta (indeksy konektorów, mapy kodu) to jedyne miejsce,
w którym adnotacja przetrwa kolejną przebudowę.

Sam `wiki/index.md` dodatkowo zawiera `kb_schema_version` (obecnie `"1.5"`),
deklarujący, według której wersji tego schematu wiki została napisana —
zwiększaj wersję pomniejszą dla dodatkowych opcjonalnych pól, główną dla
zmian łamiących kompatybilność.

### Ekstrakcja encji i graf wiedzy
Podczas ingestu agent wydobywa typowane encje (osoby, projekty, biblioteki,
koncepcje, systemy) i zapisuje je jako strony w `wiki/entities/`. Typowane
relacje są zapisywane w `wiki/graph/edges.json` przy użyciu zamkniętego
słownika, w którym każdy czasownik jest zdefiniowany przez pytanie, na jakie
odpowiada (patrz `wiki/graph/index.md`) — strukturalne (`part_of`, `uses`,
`depends_on`, `produces`, `configures`, `validates`, `implements`, `caused`,
`contradicts`, `supersedes`) oraz łączące osoby z tematami
(`has_expertise_in`, `owns`). Zapytania mogą przechodzić po grafie,
aby odkrywać powiązane strony (np. „co zależy od Redis?") albo bezpośrednio
odpowiadać na „kto wie o X".

### Rekurencyjna konwencja indeksu i dziennika
Każdy podkatalog `wiki/`, który grupuje wiele stron (`entities/`, `graph/`,
przyszłe foldery tematyczne), utrzymuje własny `index.md` — zwykłą listę
linków, bez frontmatteru — dzięki czemu nawigacja po podkatalogach pozostaje
leniwa, zamiast wymagać pełnego skanowania. Podkatalog może też utrzymywać
własny `log.md`, gdy ma już wystarczająco dużo niezależnej historii;
`wiki/log.md` pozostaje rollupem na poziomie głównym i nigdy nie powtarza
zmiany już zapisanej w dzienniku podkatalogu.

### Konektory zewnętrznych źródeł i indeksowanie (na żądanie)
Folder `libs/<name>/` obsługuje drugi sposób zasilania, obok istniejącej
kopii git: mały, autorski plik `libs/<name>/source.yaml`, który deklaruje
*żywe* zewnętrzne źródło — folder SharePoint, folder Google Drive, zwykły
URL albo inny konektor — którego nie chcesz w pełni kopiować lokalnie:
```yaml
connector: sharepoint
location: "https://contoso.sharepoint.com/sites/Finance/Shared Documents/Reports"
description: "Wspólny folder raportów zespołu finansowego"
refresh_interval_days: 7   # opcjonalne, domyślnie 30
```
`refresh_interval_days` dostraja częstotliwość per źródło — folder zmieniający
się codziennie zasługuje na krótsze okno niż kwartalne archiwum, które prawie
nie drgnie — i ustawia `freshness_window_days` nadawane generowanym stronom
tego źródła. Zarówno „index external sources", jak i „Lint" raportują źródło
zaległe względem tej wartości i mówią o ile, żeby użytkownik z dostępem tylko
do odczytu wiedział, kogo zapytać, zamiast po cichu polegać na kopii sprzed
trzech tygodni.

Powiedz „index external sources", a agent go przeskanuje, dopasowując
`connector` do dowolnego żywego narzędzia dostępnego w danej sesji
(połączonego narzędzia MCP do Microsoft 365/Google Drive, albo `WebFetch`
dla zwykłego adresu URL), i zbuduje samodzielny, generowany indeks wewnątrz
tego samego `libs/<name>/` — `index.md`/`entities/`/`graph/`/`log.md`,
odzwierciedlający strukturę `wiki/` opisaną w Rekurencyjnej konwencji
indeksu i dziennika powyżej, ale ograniczony wyłącznie do tego jednego
konektora. To celowa decyzja projektowa: ten indeks **nie** jest wmieszany
w główne `wiki/entities/`/`wiki/graph/edges.json` — pozostaje oddzielony na
warstwie kaskady `libs/`, tak samo jak pliki sklonowanej przez git KB. Sam
`source.yaml` pozostaje wyłącznie twój, agent nigdy go nie zapisuje.

Dwa rozszerzenia na tym fundamencie:

- **Współdzielone, wcześniej zbudowane indeksy.** `source.yaml` może
  dodać opcjonalny blok `index:`, który deklaruje, *gdzie już zbudowany
  indeks się znajduje* — repozytorium git albo zasób współdzielony, np.
  ścieżka sieciowa lub inna lokalizacja dostępna przez konektor:
  ```yaml
  index:
    store: git   # git | shared
    location: "https://github.com/org/finance-index-cache.git"
    ref: main    # opcjonalnie — branch, tag albo podpowiedź co do podścieżki w tym miejscu
  ```
  Każde uruchomienie najpierw sprawdza tę lokalizację: jeśli indeks już
  tam jest, zostaje pobrany — większość osób po prostu czyta to, co już
  jest, zamiast budować to samodzielnie. Jeśli go tam jeszcze nie ma, to
  normalny stan przy pierwszym uruchomieniu, a nie błąd: kolejne
  uruchomienie użytkownika z dostępem do zapisu jest tym, które go tam
  tworzy i publikuje — bez osobnego kroku „inicjalizacji".
- **Odczyt vs. zapis, per użytkownik, per źródło.** Czy *ten* użytkownik
  może faktycznie przebudować indeks (a nie tylko czytać pobraną/
  opublikowaną wersję) to odrębne, lokalne, ignorowane przez git
  `libs/<name>/source.local.yaml` — domyślnie tylko do odczytu. Ustawienie
  `access: write` w tym pliku włącza dany komputer/użytkownika jako
  administratora tego źródła, dzięki czemu zespół może wyznaczyć jedną lub
  dwie osoby do utrzymywania źródła, podczas gdy reszta czyta tylko wynik —
  bez zbędnego, wielokrotnego przebudowywania i bez potrzeby, żeby każdy
  użytkownik miał własną autoryzację konektora.

Zaimplementowane jako Claude Code Skill — zobacz
`.agents/skills/ckb-index-external/SKILL.md`.

### Podwójne linkowanie (Wikilinks + Markdown)
Każde odwołanie krzyżowe używa zarówno `[[Wikilinks]]` (kompatybilnych z
Obsidian), jak i standardowych linków `[markdown](path.md)`. Działa w
widoku grafu Obsidian, renderowaniu GitHub i narzędziach CLI. Odwołania do
treści nadrzędnych używają pełnych ścieżek względnych: `linked/<name>/...`
lub `libs/<name>/...`. Odwołania wewnątrz wiki preferują ścieżki bezwzględne
względem katalogu głównego projektu (`/wiki/entities/foo.md`) zamiast
względnych, dzięki czemu linki przetrwają późniejsze przenoszenie plików.

### Samonaprawiający się lint
Okresowo (lub na żądanie) agent sprawdza kondycję wiki:
- **Zgodność (conformance)** — oflagowuje każdą stronę bez poprawnego
  frontmatteru lub pola `type`
- **Świeżość** — oflagowuje strony starsze niż ich `freshness_window_days`
- **Zanik pewności (confidence decay)** — zmniejsza `confidence` dla stron
  niewzmacnianych nowymi źródłami
- **Przegląd retencji** — archiwizuje strony `retention: low` starsze niż
  2× okno świeżości
- **Wykrywanie supersesji** — znajduje sprzeczności, łączy stare→nowe
- **Wykrywanie sierot** — znajduje strony bez linków przychodzących
- **Spójność grafu** — weryfikuje, czy wszystkie krawędzie wskazują na
  istniejące encje
- **Spójność indeksu/dziennika** — weryfikuje, czy każdy podkatalog ma
  index.md i czy żadna zmiana nie jest podwójnie logowana
- **Skróty źródeł** — przelicza skrót każdego cytowanego źródła i oznacza
  strony, których dowód faktycznie się zmienił, a nie tylko się zestarzał
- **Dosłowność sekcji Crux** — oznacza cytat, którego nie ma już w źródle,
  na które się powołuje
- **Częstotliwość konektorów** — oznacza konektorowe źródło, którego
  generowany indeks jest zaległy względem `refresh_interval_days`, wraz z
  informacją o ile
- **Księga błędów (Error Book)** — zapisuje systemowe problemy wraz z
  przyczyną i naprawą

Automatycznie naprawia to, co może (uszkodzone linki, brakujące odnośniki
zwrotne, nieaktualne flagi), i przypomina o przejrzeniu wyniku oraz
uruchomieniu „sync changes", aby wypchnąć zmiany do `origin`, gdy będziesz
z nich zadowolony. Zaimplementowane jako Claude Code Skill — zobacz
`.agents/skills/ckb-lint/SKILL.md` — zamiast być zaszytym w
`CLAUDE.md`/`AGENTS.md`, dzięki czemu pełna lista kontrolna ładuje się do
kontekstu tylko wtedy, gdy jest faktycznie wywoływana.

### Rozwiązywanie konfliktów (Supersesja)
Gdy nowa informacja przeczy istniejącej stronie, agent dodaje linki
`supersedes` / `superseded_by`. Stara strona jest zachowywana, ale
oznaczana jako nieaktualna. Kontrola wersji dla wiedzy, nie tylko dla
plików.

### Ocena jakości
Każda strona przy zapisie otrzymuje wynik jakości (0.0–1.0), oparty na
strukturze, cytowaniu źródeł i spójności z resztą wiki. Strony poniżej 0.7
są oflagowane do przeglądu lub przepisywane podczas kolejnego lintowania.

### Księga błędów (Error Book)
Systematyczne błędy (uszkodzone linki, problemy z formatowaniem,
sprzeczności między stronami) są zapisywane w `wiki/error-book.md` wraz z
przyczyną, zastosowaną naprawą i ograniczeniem wielokrotnego użytku
zapobiegającym powtórce. Naprawa dwuwarstwowa:
- **Warstwa 1** — deterministyczna automatyczna naprawa problemów
  strukturalnych
- **Warstwa 2** — przebieg rozumowania agenta dla problemów
  semantycznych/między stronami

### Haki automatyzacji (Automation Hooks)
- **Nowe źródło** → automatyczny ingest przy kolejnej komendzie „Ingest"
- **Start sesji** → ładowanie indeksu + ostatniego podsumowania workload;
  sprawdzenie niezsynchronizowanych zmian (niezacommitowana praca lub
  przewaga/zaległość względem `origin`) i zasugerowanie
  `ckb-sync-changes`, jeśli takie zostaną znalezione
- **Koniec sesji** → skompresowanie obserwacji do workload/; ponowne
  sprawdzenie niezsynchronizowanych zmian (w tym tych, które powstały
  właśnie w tej sesji) i zasugerowanie `ckb-sync-changes`, jeśli to
  potrzebne
- **Zapytanie** → zapisanie z powrotem wartościowych odpowiedzi jako strony
  wiki
- **Zapis do pamięci** → sprawdzenie sprzeczności, wywołanie supersesji
- **Harmonogram** → okresowy lint, konsolidacja, zanik retencji

### Kontekst napędzany zapotrzebowaniem (Demand-Driven Context, DDC)
Wiki rośnie na podstawie rzeczywistych niepowodzeń agenta, a nie z góry
narzuconej kuracji:
1. Agent nie potrafi odpowiedzieć → identyfikuje brakującą wiedzę
2. Proponuje minimalną encję/stronę wypełniającą lukę
3. Użytkownik zatwierdza lub dostarcza materiał źródłowy
4. Kolejny ingest wprowadza ją

Zbiega do stabilnej bazy wiedzy po ~20–30 cyklach.

### Podsumowania sesji
Po każdej akcji konwersacyjnej agent dopisuje do
`workload/YYYY-MM-DD_summary.md`. Zapewnia to ciągłość między sesjami i
przeglądalną historię ewolucji bazy wiedzy. Agent czyta ostatnie
podsumowanie na starcie sesji, aby kontynuować od miejsca, w którym
skończył.

### Dziennik zmian
Każda modyfikacja wiki jest natychmiast logowana w `wiki/log.md` w
kolejności odwrotnie chronologicznej (najnowsze na górze), z zapisem co się
zmieniło, dlaczego i jakie było źródło.

### Eksport OKF (na żądanie)
Wiki może zostać wyeksportowana jako zgodny z
[Open Knowledge Format](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md)
v0.1 pakiet w `outputs/okf/`, możliwy do skonsumowania przez dowolne ogólne
narzędzie OKF (np. referencyjny wizualizator grafu Google) bez naruszania
bogatszego wewnętrznego schematu
(`confidence`/`quality`/`retention`/`supersedes`/podwójne linkowanie),
którego OKF natywnie nie rozumie. Zaimplementowane jako Claude Code Skill —
zobacz `.agents/skills/ckb-export-okf/SKILL.md` — zamiast być zaszytym w
`CLAUDE.md`/`AGENTS.md`, dzięki czemu zestaw reguł mapowania ładuje się do
kontekstu tylko wtedy, gdy jest faktycznie wywoływany. Cały transform —
przemapowanie frontmatteru, przepisanie linków, regeneracja indeksów i
dzienników oraz sprawdzenie zgodności z OKF na własnym wyjściu — wykonuje
deterministyczny skrypt Python (`scripts/export_okf.py`), więc eksport jest
odtwarzalny zamiast wyprowadzany na nowo strona po stronie; agent uruchamia
skrypt i przekazuje raport. `outputs/okf/` jest w `.gitignore` — to w pełni
regenerowalny artefakt budowania, więc każda maszyna/narzędzie regeneruje go
na żądanie zamiast przenosić go w historii gita.

### Eksport Starlight (na żądanie)
Wiki może też zostać wyeksportowana do formy skonsumowalnej przez Astro +
Starlight w `outputs/starlight/`, tworząc czytelną dla człowieka stronę
dokumentacji — w odróżnieniu od eksportu OKF, który celuje w konsumpcję
maszynową/narzędziową. Deterministyczny skrypt Python
(`scripts/export_starlight.py`) obsługuje przemapowanie frontmatteru,
zwijanie podwójnych linków, rozwiązywanie wikilinków, kopiowanie zasobów i
generowanie paska bocznego; zadaniem agenta jest jedynie zadanie dwóch
pytań konfiguracyjnych (zakres eksportu: pełny uruchamialny szkielet vs.
tylko treść; czy dołączyć strony meta dziennika/księgi błędów) i
przekazanie raportu skryptu. Również na żądanie i tylko jako skill —
zobacz `.agents/skills/ckb-export-starlight/SKILL.md`. Podobnie jak
`outputs/okf/`, `outputs/starlight/` jest w `.gitignore` jako regenerowalny
artefakt budowania.

### Dziennik decyzji (na żądanie)
Powiedz „zapisz decyzję: ..." (albo po prostu „zdecydowaliśmy ..."), żeby
utworzyć numerowany rekord decyzji; zapytaj „co zdecydowaliśmy w sprawie X",
„kto to zdecydował", „które decyzje są wciąż propozycjami" albo „co zastąpiło
decyzję 3", żeby dostać ją z powrotem wraz z autorem, datą i statusem.
Zapisywanie zbiera brakujące pola w jednej turze zamiast wywiadu, ustawia
powiązania zastępowania w obu kierunkach, dodaje krawędzie grafu
`decided_by`/`affects` i zapisuje do `wiki/decisions/log.md`. Zobacz
`.agents/skills/ckb-decide/SKILL.md`.

### Prowadzone wycieczki wprowadzające (na żądanie)
Poproś „oprowadź mnie po X" (lub „od czego zacząć z X", „krótka wycieczka
po X") aby otrzymać krótką, tylko-do-odczytu prowadzoną kolejność czytania:
akapit wprowadzający plus uporządkowaną listę stron wiki do przeczytania,
zbudowaną przez przejście po grafie wiedzy na zewnątrz od najlepiej
pasującej strony (najpierw podstawy, potem sam temat, potem to, co się na
nim opiera). Nigdy nie zapisuje do `wiki/`. Zobacz
`.agents/skills/ckb-onboard-me/SKILL.md`.

### Podsumowanie projektu (na żądanie)
Poproś o „podsumowanie projektu" (lub „jak stoją sprawy", „nadrób
zaległości w projekcie"), aby zregenerować `PROJECT-OVERVIEW.md` w
katalogu głównym repozytorium — jedno- lub dwustronicowy skrót (przegląd,
stan projektu, działania i ich status, ryzyka, założenia) zsyntetyzowany w
całości z bieżącej zawartości `wiki/` i jej grafu wiedzy. Zawsze
nadpisywany w całości przy ponownym uruchomieniu, nigdy nie dopisywany
ręcznie. Zobacz `.agents/skills/ckb-project-summary/SKILL.md`.

### Synchronizacja gita (na żądanie)
Historia gita tego repozytorium może zostać uzgodniona z jego zdalnym
repozytorium `origin` na żądanie: lokalne zmiany są commitowane, zdalne
zmiany są pobierane i scalane, wszelkie konflikty są prezentowane
użytkownikowi plik po pliku do rozwiązania, a następnie wynik jest
automatycznie wypychany (push). Powiedz „sync changes", aby to uruchomić.
Również zaimplementowane jako Claude Code Skill — zobacz
`.claude/skills/ckb-sync-changes/SKILL.md` — i celowo odrębne od przepływu
na poziomie treści „Sync the wiki" / „Ingest", który przetwarza
`raw/inbox/` na ustrukturyzowane strony `wiki/` i nie ma nic wspólnego z
gitem.

### Tryb quizu (na żądanie)
Poproś o odpytanie z wiki („quiz me on X", „sprawdź moją wiedzę"), aby
uzyskać jednorazowy, punktowany sprawdzian wiedzy: agent czyta odpowiednie
strony, generuje pytania otwarte lub jednokrotnego wyboru oparte na
konkretnych faktach z wiki, przeprowadza je jedno po drugim z natychmiastową
informacją zwrotną i bieżącym wynikiem, a na koniec podaje werdykt.
Bezstanowy — nic nie jest zapisywane między uruchomieniami. Zobacz
`.agents/skills/ckb-quiz/SKILL.md`.

### Prowadzony program nauczania (na żądanie)
Poproś o naukę z wiki („teach me the wiki", „naucz mnie o X", „przeprowadź
sesję nauki"), aby otrzymać stanowy kurs zamiast jednorazowego quizu.
Pierwsze wywołanie go planuje: określa zakres materiału (opcjonalnie
uzupełniając cienkie miejsca z internetu, wyraźnie oznaczone jako
nieautorytatywne), pyta, czy ma to być jedna sesja, czy rozłożona w czasie
seria (czas trwania, częstotliwość, opcjonalne przypomnienia kalendarzowe
`.ics`), dzieli treść na porcje wielkości sesji — wolą dodatkową sesję niż
upychanie materiału — i zapisuje zaakceptowany plan oraz tracker postępu w
`outputs/teaching/<topic>/`. Kolejne wywołania porównują plan z postępem,
uczą kolejnej porcji materiału inną techniką za każdym razem (pytania
sokratejskie, analogie, przykłady rozwiązane krok po kroku, „naucz mnie z
powrotem", mnemotechniki, ...), sprawdzają utrwalenie wiedzy i powtarzają
słabe punkty przed przejściem dalej. Nigdy nie zapisuje do `wiki/`. Zobacz
`.agents/skills/ckb-teach-me/SKILL.md`.

---

## Szybki start

1. **Zamontuj nadrzędne bazy wiedzy:**
   ```bash
   ln -s /path/to/other-kb ./linked/my-upstream
   git clone https://github.com/org/external-kb ./libs/external-kb
   ```
   Albo, dla żywego źródła, którego nie chcesz w pełni kopiować lokalnie,
   umieść zamiast tego `libs/<name>/source.yaml` (zobacz „Konektory
   zewnętrznych źródeł i indeksowanie" powyżej) i powiedz „index external
   sources".

2. **Wrzuć surowy materiał** do `raw/inbox/` (notatki, linki, artykuły).

3. **Poleć agentowi „Ingest"** — przetworzy skrzynkę odbiorczą, skonsultuje
   kaskadę, wydobędzie encje i zapisze ustrukturyzowany markdown w `wiki/`.

4. **Zadawaj pytania** — agent używa indeksu do routingu, TLDR-ów do
   szybkich odpowiedzi i grafu do odkrywania relacji.

5. **Okresowo proś o „Lint"** — agent sprawdzi kondycję wszystkiego,
   naprawi co może i zgłosi problemy.

---

## Pliki instrukcji dla agenta

| Plik | Cel |
|------|-----|
| `AGENTS.md` | Pełna instrukcja dla dowolnego agenta kodującego AI |
| `CLAUDE.md` | Dowiązanie symboliczne do `AGENTS.md`, automatycznie wykrywane przez Claude Code |

Skille znajdują się w jednej wspólnej lokalizacji, `.agents/skills/`, dzięki
czemu każde narzędzie agentowe respektujące tę konwencję je odnajduje.
`.claude/skills` to dowiązanie symboliczne do `.agents/skills` — Claude Code
widzi ten sam zestaw skilli bez drugiej kopii do utrzymywania w
synchronizacji.

---

## Wskazówki

- Nadrzędne bazy wiedzy (`linked/` i kopie git w `libs/`) **nigdy nie są
  modyfikowane** przez agentów. Wyjątkiem jest `libs/<name>/` oparty na
  konektorze (ten z `source.yaml`) — agent zarządza jego generowanym
  indeksem, ale tylko dla użytkownika, który lokalnie ustawił sobie
  `access: write` (zobacz następny punkt); kopia każdego innego
  użytkownika pozostaje tylko do odczytu.
- Aby poprawić treść nadrzędną, zapisz poprawną wersję w `wiki/` — ona
  wygrywa.
- Używaj `raw/inbox/` dla wszystkiego, co nieprzetworzone; agent czyści ją
  podczas ingestu.
- Tabela routingu `wiki/index.md` to najważniejszy plik — utrzymuj go na
  bieżąco.
- Confidence, quality i freshness pozwalają ufać właściwej treści i
  oflagowywać resztę do przeglądu.
- Katalog `tmp/` jest w `.gitignore`, podobnie jak większość `libs/` — ale
  nie cały: zawartość kopii git w `libs/<name>/` pozostaje w `.gitignore`
  jak dawniej, natomiast `source.yaml` konektora i jego generowany
  `index.md`/`entities/`/`graph/`/`log.md` są śledzone, ponieważ to
  zsyntetyzowana wiedza warta udostępnienia przez „sync changes", a nie
  jednorazowy artefakt budowania. `libs/<name>/source.local.yaml`
  (osobiste ustawienie odczytu/zapisu) to jedyny wyjątek, który zostaje w
  `.gitignore` razem z nimi — to osobisty stan komputera, nigdy
  przeznaczony do synchronizacji. Sam `outputs/` jest śledzony,
  ale jego regenerowalne podkatalogi budowania, `outputs/okf/` i
  `outputs/starlight/`, są w `.gitignore` — każdy z nich jest w pełni
  odtwarzalny z `wiki/` na żądanie, więc nie ma czego uzgadniać, przenosząc
  go w historii gita. `outputs/teaching/` (osobiste plany nauki i postęp
  sesji ze skilla do nauczania) jest również w `.gitignore`, ponieważ to
  osobisty stan sesji, a nie współdzielona treść bazy wiedzy. Commituj
  inne, ręcznie utrzymywane artefakty w `outputs/` normalnie.

---

## Wersja i licencja

Aktualna wersja szablonu: [VERSION](VERSION). Licencja:
[Apache License 2.0](LICENSE).