ckb/README.pl.md

Cascade Knowledge Base

Read this in: English | Polski

Repozytorium źródłowe (zawsze najbardziej aktualna wersja): 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 (English).

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

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

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:

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:

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

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:

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

   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. Licencja: Apache License 2.0.