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

---

## Struktura katalogów

```
├── libs/         # Zewnętrzne bazy wiedzy tylko do odczytu, kopiowane przez git (w .gitignore)
├── 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
│   ├── 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
```

Agent nigdy nie zapisuje do `linked/` ani `libs/`. Aby poprawić treść
nadrzędną, zapisz właściwą wersję w `wiki/` — automatycznie zyskuje
pierwszeństwo.

---

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

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

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

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

Sam `wiki/index.md` dodatkowo zawiera `kb_schema_version` (np. `"1.1"`),
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 (`uses`, `depends_on`, `caused`, `contradicts`, `supersedes`) są
zapisywane w `wiki/graph/edges.json`. Zapytania mogą przechodzić po grafie,
aby odkrywać powiązane strony (np. „co zależy od Redis?").

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

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

### 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/cbk-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
   ```

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 `libs/`) **nigdy nie są modyfikowane**
  przez agentów.
- 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.
- Katalogi `tmp/` i `libs/` są w `.gitignore`. 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).