# 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) **Co zawiera ta baza wiedzy:** zobacz [ABOUT.pl.md](ABOUT.pl.md) (lub [ABOUT.md](ABOUT.md)) - jej cel, odbiorców, zakres, właścicieli i poziom poufności, opisane przez osobę, która ją prowadzi. Reszta tego README opisuje narzędzia Cascade KB, takie same w każdej bazie. Warstwowa wiki zarządzana przez agenta, w której lokalna zawartość nadpisuje źródła nadrzędne (upstream) dostępne tylko do odczytu. 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. Przewodnik zorientowany na zadania (jak stworzyć wiki, dodawać wiedzę, utrzymywać porządek, synchronizować się z innymi, z przykładami dla każdego przypadku użycia) znajdziesz w [docs/MANUAL.pl.md](docs/MANUAL.pl.md) ([English](docs/MANUAL.md)). Zaczynasz? Przeczytaj jednostronicowy [docs/QUICKSTART.pl.md](docs/QUICKSTART.pl.md) ([English](docs/QUICKSTART.md)). Jeśli ta baza dokumentuje tworzone przez Ciebie oprogramowanie, opcjonalny moduł `software` dodaje repozytoria w `src/` i pracę sterowaną specyfikacją — zobacz [docs/OPENSPEC.pl.md](docs/OPENSPEC.pl.md) ([English](docs/OPENSPEC.md)). Aby korzystać z bazy w aplikacji webowej Claude lub innym kliencie MCP, opcjonalny moduł `mcp` udostępnia ją przez MCP: wyszukiwanie i odczyt, zgłoszenia do `raw/inbox/` i cofanie źle skierowanego zgłoszenia, także przy kilku bazach podłączonych naraz — zobacz [docs/MCP.pl.md](docs/MCP.pl.md) ([English](docs/MCP.md)). Aby zapisywać strony WWW, PDF-y i transkrypcje filmów w `raw/inbox/`, opcjonalny moduł `capture` zapisuje każdą jako datowany zrzut oznaczony jako niezaufany. Aby wysłać dokument do innej bazy, opcjonalny moduł `share` korzysta ze wspólnego repozytorium git z jedną skrzynką na bazę; odbiorca bierze dokument do `raw/inbox/` i przetwarza go zwykłym ingestem. Aby wszystko, co baza wysyła na zewnątrz, brzmiało głosem zespołu, opcjonalny moduł `voice` przepisuje zachowane odpowiedzi, dokumenty i raporty według profilu głosu trzymanego jako strona wiki, nie ruszając faktów, cytatów ani źródeł. Aby oddać dokument jako plik Worda lub PDF, opcjonalny moduł `convert` uruchamia pandoca ze stylem firmowym trzymanym w `templates/styles/`, zbudowanym z kilku ustawień albo z firmowego szablonu Worda. Każdy moduł ma własne README w obu językach w `.agents/modules//`. Pełny schemat strony oraz historię obu numerów wersji znajdziesz w [docs/CHANGELOG.pl.md](docs/CHANGELOG.pl.md) ([English](docs/CHANGELOG.md)). Własne decyzje projektowe szablonu, czyli dlaczego wygląda tak, a nie inaczej, opisuje [docs/decisions/](docs/decisions/README.md). ### Kanały wydawnicze Repozytorium szablonu utrzymuje cztery gałęzie wydań oraz `dev`, na którą trafia praca. 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` | **Podglądowa** — zmiany scalone z `dev` wcześnie, mogą być zepsute albo wycofane | Osoby rozwijające sam szablon | | `1.x` | **Utrzymaniowa** — linia 1.x po wydaniu 2.0: tylko poprawki; ostatnia z obsługą PowerShella | KB, które potrzebują PowerShella albo nie mogą jeszcze przejść na 2.0 | | `dev` | **Integracyjna** — tu najpierw trafia każda zmiana; `VERSION` nigdy się tu nie zmienia | Nikt: to nie jest kanał (upgrade z niej nie znajdzie nic nowszego) | Wersja zmienia się tylko przy scaleniu `dev` do innej gałęzi, nigdy na samej `dev`. Zmiany idą `dev` → `experimental` → `test` → `main`, `dev` → `test` → `main` albo `dev` → `main`; wersja zachowuje swój numer po drodze. Znaczenie pozycji numeru się nie zmienia: główna dla zmian łamiących, poboczna dla funkcji, poprawkowa dla poprawek. Zobacz [D-0022](docs/decisions/0022-dev-branch-and-merge-versioning.md). Zarówno `ckb-init`, jak i `ckb-upgrade` domyślnie używają `main`. Żeby użyć innego kanału, 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`; każda KB sprzed tej konwencji i tak go śledziła. --- ## Struktura katalogów ``` ├── ABOUT.md # Co zawiera ta KB: cel, odbiorcy, zakres, właściciele - piszesz go ty ├── ABOUT.pl.md # To samo po polsku - wypełnij plik w języku swojej bazy ├── ckb.yaml # Manifest repozytorium: śledzona gałąź szablonu, zainstalowane moduły, ustawienia rozmów, rutyny ├── docs/ # Podręcznik, changelog, przewodnik OpenSpec i decisions/ — własne ADR-y szablonu ├── tests/ # Tylko w repo szablonu: baza-fixture + test dymny (tests/smoke.sh); nie kopiowany do KB ├── 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 │ └── documents/ # Dokumenty przygotowane z templates/ ├── raw/ # Materiał źródłowy dostarczony przez użytkownika │ └── inbox/ # Strefa zrzutu: nieprzetworzony materiał ├── templates/ # Twoje szablony dokumentów: nagłówki plus komentarz z instrukcją pod każdą sekcją ├── 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 # Czego dotyczy ta KB — treść, nie schemat │ ├── log.md # Główny dziennik zmian (rollup) │ ├── error-book.md # Błędy kompilacji i wyprowadzone ograniczenia │ ├── query-gaps.md # Pytania bez odpowiedzi, cele przyszłego ingestu │ ├── projects/ # Opcjonalne lokalne zakresy zapytań │ ├── 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//` będącego kopią git. Aby poprawić treść nadrzędną, zapisz właściwą wersję w `wiki/`, a ona automatycznie zyska pierwszeństwo. Jedynym wyjątkiem jest `libs//` oparty na konektorze (zobacz „Konektory zewnętrznych źródeł i indeksowanie” poniżej): agent zarządza jego generowanym indeksem tak samo jak `wiki/`. --- ## Funkcje Każda funkcja poniżej to skill w `.agents/skills/`. Skill ładuje się do kontekstu dopiero po wywołaniu; `AGENTS.md` zawiera routing i reguły nienegocjowalne, nic więcej. ### 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 „Update the wiki") agent przetwarza skrzynkę odbiorczą: wydobywa wiedzę, zapisuje ją w `wiki/` i archiwizuje przetworzone elementy do `raw/`. Potem przypomina o przejrzeniu wyniku i uruchomieniu „sync changes", żeby wypchnąć zmiany do `origin`, kiedy wynik będzie Ci odpowiadał. Skill: `.agents/skills/ckb-ingest/SKILL.md`. Zanim cokolwiek zapisze, skrypt (`dedup_inbox.py`) zgłasza pliki ze skrzynki, które już zingestowano: identyczne co do bajtu lub co do tekstu kopie plików z archiwum, pliki, których skrót strona już cytuje, linki do adresów URL, które strona już cytuje, oraz duplikaty w samej skrzynce. Potem agent **się melduje**: dla każdego źródła mówi, jak je rozumie, które strony zmieni i z czym jest sprzeczne. Nic nie zostaje zapisane, dopóki nie odpowiesz. „Ingest in batch” pomija meldunek. Tekst owinięty w `…` nigdy nie jest ingestowany. 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 warto móc znaleźć osobno. „Wysoka wartość" to jawny test, a nie ocena uznaniowa, bo 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`: ma to być wyróżniający uchwyt wyszukiwania, a nie słowo obecne już 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. Jeśli fragment nie spełnia choćby jednego warunku, treść nadal trafia na stronę, tylko do podsumowania, a nie jako osobna jednostka. Wydzielone 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. Indeks pozostaje mały; strony, na które wskazuje, nie muszą. ### 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, agent w ogóle nie ładuje pełnej treści. Ł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 to samo, co przestrzeń robocza projektu w większym systemie wyszukiwania, ale zakres pozostaje lokalny, przejrzysty i edytowalny 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 - wyszukiwanie BM25 po sekcjach przez SQLite FTS5 (biblioteka standardowa), każda sekcja indeksowana z tytułem strony, ścieżką nagłówków i `tldr` jako kontekstem, więc kandydat wskazuje trafione sekcje i swój koszt w tokenach Zebranie i połączenie tych sygnałów jest mechaniczne, więc wykonuje je skrypt `.agents/skills/ckb-retrieve/scripts/retrieve_candidates.py`, tak samo jak detekcję w lincie; agent czyta jego ranking i wykonuje osąd (deduplikacja według twierdzenia, przerankowanie względem dosłownego pytania, weryfikacja źródła). Każdy sygnał tworzy własną listę rankingową, a listy są następnie łączone, a nie rozstrzygane wyborem 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. Wartość 60 jest dostrojona 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 potrzeba serwera, bazy wektorowej ani osobnego klienta. ### 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`. Chodzi o to, żeby agent nie odpowiadał pewnie *z* nieaktualnej strony, nie przekazując tej informacji dalej. ### Konsolidacja i podsumowania tematów (na żądanie) „Consolidate” zapisuje raport samych propozycji w `outputs/reports/`: grupy tematów (i czy każda strona w `wiki/topics/` istnieje i jest aktualna), kandydatów do scalenia, brakujące linki, strony nieaktualne i stare wpisy dziennika. Nic w wiki się nie zmienia, dopóki nie zaakceptujesz danej pozycji. Zaakceptowane strony tematów podsumowują, co KB zawiera o jednym temacie, i wymieniają strony członkowskie ze skrótami, więc lint oznacza temat, gdy któryś członek się zmieni. Skill: `.agents/skills/ckb-consolidate/SKILL.md`. ### Profile i lekcje Każda osoba może mieć profil w `workload/profiles/` (rola, jak z nią pracować), wypisywany w podsumowaniu startu jej własnej sesji i niczyjej innej. „Remember this” albo „lesson: …” zapisuje lekcję: osobistą w profilu, dla całej KB w `wiki/lessons.md`, gdzie czeka na przegląd drugiej osoby. Pierwszeństwo: `AGENTS.md`, potem `## Rules` projektu, potem profil. Każda lekcja zapisuje kontekst, w którym powstała (agent/model, wersja szablonu), więc po zmianie modelu lub szablonu agent ją sprawdza, zamiast uznawać za pewnik. Lekcje z baz w `linked/` pojawiają się w podsumowaniu jako zewnętrzne, poniżej lokalnych, a nowa KB może zacząć od lekcji przeniesionych z bazy, która ją utworzyła. Skill: `.agents/skills/ckb-profile/SKILL.md`. ### Zachowane odpowiedzi Odpowiedź, która wymagała prawdziwej pracy, można na prośbę zachować w `outputs/answers/` ze skrótami w `## Sources` i sekcją `## Gaps`. Lint oznacza zachowaną odpowiedź, której źródła się zmieniły, a to samo pytanie zadane ponownie aktualizuje ją zamiast tworzyć duplikat. Wprowadzenie odpowiedzi do wiki odbywa się zwykłym ingestem, nigdy bezpośrednim zapisem. Fragmenty prywatne (``) nigdy nie są cytowane. ### 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 postanowiono, 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. Opcjonalne `expected_outcome`, zapisane w chwili podjęcia decyzji, mówi, co ma ona zmienić; przy przeglądzie agent zapisuje, co faktycznie się stało (`outcome: met/partly/missed/unclear`) w dopisywanej sekcji `## Outcome`, a sekcja `## Tried` zachowuje to, co zbudowano lub przetestowano i porzucono. 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. Dzięki temu na pytanie „dlaczego jest tak, jak jest?" da się odpowiedzieć po latach, a „używamy Postgresa" zamienia się 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ę. Nieudane wyszukiwania stają się wtedy 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 review: draft|reviewed|needs_update # z reviewed_by / reviewed_on (1.6) tags: retries, billing # tylko tagi z wiki/tags.md (1.6) --- ``` - **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 oznaczane do przeglądu - **supersedes / superseded_by** — gdy nowa informacja zastępuje starą, połącz je - **freshness_window_days** — strony starsze niż to okno są oznaczane 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*, a lint sprawdza go mechanicznie. - **review / reviewed_by / reviewed_on** *(1.6)* — czy stronę sprawdził człowiek: ingest zapisuje `draft`, polecenie „mark X as reviewed” ustawia `reviewed`, a późniejsza zmiana tego, co strona twierdzi, ustawia `needs_update` - **tags** *(1.6)* — płaska lista sprawdzana względem własnego słownika KB w `wiki/tags.md`; wyszukiwanie może po niej filtrować #### Zastrzeżone sekcje treści Trzy 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 | | `## Rules` | tylko na stronach zakresu projektu: zasady zespołu dla tego projektu, chronione jak `## Notes` | Gdy dwa źródła się nie zgadzają, a nikt nie zdecydował, które ma rację, ingest wpisuje na stronę znacznik `> CONTRADICTION: …` zamiast wybierać zwycięzcę; lint wypisuje go, dopóki człowiek go nie rozstrzygnie. `## 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.8"`), 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, tylko dostaje jednolinijkowy wpis `POINTER`. `wiki/decisions/log.md` to jedyny dziennik podkatalogu w bazowym szkielecie, a Reguła B w `AGENTS.md` wymienia go jako wyjątek. ### Konektory zewnętrznych źródeł i indeksowanie (na żądanie) Folder `libs//` obsługuje drugi sposób zasilania, obok istniejącej kopii git: mały plik `libs//source.yaml` pisany przez użytkownika, 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` ustala częstotliwość osobno dla każdego źródła (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 zaległej o trzy tygodnie. 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//` — `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. 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. Do tego dochodzą dwa rozszerzenia: - 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 czyta to, co już jest, zamiast budować indeks samodzielnie. Jeśli go tam jeszcze nie ma, to normalny stan przy pierwszym uruchomieniu, a nie błąd: najbliższe uruchomienie przez użytkownika z dostępem do zapisu tworzy go tam i publikuje, bez osobnego kroku „inicjalizacji". - Odczyt vs. zapis, per użytkownik, per źródło. Czy *ten* użytkownik może przebudować indeks (a nie tylko czytać pobraną/ opublikowaną wersję) to odrębne, lokalne, ignorowane przez git `libs//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. Skill: `.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//...` lub `libs//...`. 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)** — oznacza każdą stronę bez poprawnego frontmatteru lub pola `type` - **Świeżość** — oznacza 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 - **Sekrety i fragmenty prywatne** — oznacza postaci danych uwierzytelniających w commitowanym tekście i fragmenty ``, które trafiły do `wiki/`, zamaskowane, nigdy nie naprawiane automatycznie; nieszkodliwe dopasowania trafiają do `.secrets-allow` opartego na skrócie linii - **Zachowane odpowiedzi** — oznacza odpowiedzi w `outputs/answers/`, których źródła się zmieniły - **Budżet kontekstu** — szacuje warstwę ładowaną zawsze (`AGENTS.md` plus opisy skilli) i oznacza przekroczenie `budget.always_loaded_tokens` w `ckb.yaml` - **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. Skill: `.agents/skills/ckb-lint/SKILL.md`. ### Rozwiązywanie konfliktów (Supersesja) Gdy nowa informacja przeczy istniejącej stronie, agent dodaje linki `supersedes` / `superseded_by`. Stara strona zostaje, oznaczona jako nieaktualna. Kontrola wersji obejmuje więc wiedzę, a nie tylko pliki. ### 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ą oznaczane 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`, jeden wpis na powracający problem. Wpis nazywa podejrzewaną przyczynę i zachowuje każdą wypróbowaną naprawę: co zmieniono, czemu miało to zapobiec (zapisane, zanim znany był wynik), co faktycznie pokazały kolejne przebiegi lintu oraz model i wersję szablonu, przy których to działało. Naprawy, które nie zadziałały, zostają w zapisie, więc ta sama naprawa nie jest próbowana ponownie na ślepo. Naprawa dwuwarstwowa: - **Warstwa 1** — deterministyczna automatyczna naprawa problemów strukturalnych - **Warstwa 2** — przebieg rozumowania agenta dla problemów semantycznych/między stronami ### Konwencje sesji To reguły, których agent przestrzega na podstawie `AGENTS.md`, a nie haki wpięte w narzędzie: nic w `.claude/` nie uruchamia się samo. Jeśli chcesz, by któraś była wymuszana mechanicznie, musisz dodać ją jako hook Claude Code albo zaplanowanego agenta. - **Start sesji** → wybór tytułu rozmowy na podstawie pierwszej wiadomości i podanie go w jednej linijce (chyba że `conversations.announce_title: false`); jedno wywołanie `session_start.py` zapisuje tytuł i wypisuje `git status`, jednolinijkowy wynik `lint_report.py --quick`, zaległe rutyny i ostatni blok najnowszego podsumowania workload; sugestia `ckb-sync-changes` lub `ckb-lint` tylko wtedy, gdy któreś coś zgłosi; zaległe rutyny wykonywane po pierwszej prośbie; przy włączonym autozapisie rozmów sprawdza też, czy ta maszyna ma hook `Stop` w ignorowanym przez gita `.claude/settings.local.json`, i pyta przed jego zainstalowaniem. Podsumowanie wymienia też otwarte wątki: nieodhaczone pozycje `- [ ]` pod `### Open threads` w notatkach workload - **Hook startu sesji (opcjonalny, Claude Code)** → przy `session.start_hook: true` hook `SessionStart` na tej maszynie wstrzykuje to samo podsumowanie przed pierwszą wiadomością i ponownie po każdym kompaktowaniu; agent pyta przed jego zainstalowaniem - **Koniec sesji** → dopisanie do `workload/`; powtórzenie sprawdzenia niezsynchronizowanych zmian; po sesji z realną pracą jednorazowe pytanie, czy zapisać rozmowę (`ckb-add-conversation`) — zapis tylko po „tak" albo bez pytania, gdy w `ckb.yaml` ustawiono `conversations.autosave: true` - **Każda tura dotykająca KB** → notatka w `workload/` (Reguła D) - **Błędne lub źle skierowane źródło** → `ckb-retract` usuwa je i dokładnie to, co wniosło (strony, twierdzenia, krawędzie), po pokazaniu planu; prośby z `raw/retractions/` (np. od serwera MCP) są zgłaszane przy ingestii - **Pytanie bez odpowiedzi** → wpis w `wiki/query-gaps.md`, jedyny zapis, który należy do `ckb-retrieve`; odpowiedzi nigdy nie są automatycznie zapisywane jako strony - **Lint na żądanie lub przez rutynę** → „Lint" uruchamia pełną kontrolę; „lint every week" robi z tego rutynę w `ckb.yaml`, która odpala się na pierwszym starcie sesji po upływie okresu (`ckb-routine`) ### Kontekst napędzany zapotrzebowaniem (Demand-Driven Context, DDC) Wiki rośnie dzięki rzeczywistym niepowodzeniom agenta, a nie dzięki doborowi treści z góry: 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 ją uwzględnia ### Podsumowania sesji Po każdej akcji konwersacyjnej agent dopisuje do `workload/YYYY-MM-DD__summary.md` — jeden plik na osobę na dzień, nazwany i opisany tożsamością gita, pod którą działa sesja. Daje to ciągłość między sesjami, przeglądalną historię ewolucji bazy wiedzy, a we współdzielonym repozytorium zapis, kto co zrobił, bez konfliktów scalania w `workload/`. Ta sama tożsamość trafia do linii `**Author:**` każdego wpisu w `wiki/log.md`. Agent czyta ostatnie podsumowanie na starcie sesji, niezależnie od autora, aby kontynuować od miejsca, w którym skończono. ### Dziennik zmian Każda modyfikacja wiki jest natychmiast logowana w dokładnie jednym dzienniku, w kolejności odwrotnie chronologicznej: `wiki/decisions/log.md` dla wszystkiego pod `wiki/decisions/`, `wiki/log.md` dla reszty, z jednolinijkowym `POINTER` w dzienniku głównym, gdy zmianę wchłania dziennik decyzji. Lint zgłasza zmianę zapisaną w obu. ### Eksport OKF (na żądanie) Wiki można wyeksportować do `outputs/okf/` jako pakiet zgodny z [Open Knowledge Format](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md) v0.1, który odczyta 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. Całe przekształcenie (przemapowanie frontmatteru, przepisanie linków, regenerację 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, a nie 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. Skill: `.agents/skills/ckb-export-okf/SKILL.md`. ### Eksport Starlight (na żądanie) Wiki można też wyeksportować do formatu dla Astro + Starlight w `outputs/starlight/`, co daje czytelną dla człowieka stronę dokumentacji, w odróżnieniu od eksportu OKF, przeznaczonego dla maszyn i narzędzi. 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; agent zadaje tylko dwa pytania konfiguracyjne (zakres eksportu: pełny uruchamialny szkielet vs. tylko treść; czy dołączyć strony meta dziennika/księgi błędów) i przekazuje raport skryptu. Skill: `.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ą kolejność czytania w trybie tylko do odczytu: 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", „wprowadź mnie w bieżący stan projektu"), 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`. ### Dokumenty z szablonów (na żądanie) Dokumenty, które piszesz regularnie, trzymaj jako szablony w `templates/`: plik Markdown, w którym nagłówki nadają kształt, a komentarze HTML mówią agentowi, co ma trafić do każdej sekcji - zapytaj użytkownika, przeczytaj tę stronę wiki, zmieść się w trzech zdaniach. „Prepare a new document using template status-report" czyta szablon, zadaje wszystkie pytania naraz, resztę bierze z wiki i zapisuje wynik w `outputs/documents/`, z frontmatterem wskazującym szablon i użyte strony. Luki stają się liniami `TODO:`, nie domysłami. W zestawie jest jeden przykład, `templates/status-report.md`; format opisuje `templates/README.md`. Zobacz `.agents/skills/ckb-document/SKILL.md`. ### Synchronizacja gita (na żądanie) Na żądanie agent uzgadnia historię gita tego repozytorium z jego zdalnym repozytorium `origin`: commituje lokalne zmiany, pobiera i scala zdalne, pokazuje Ci konflikty plik po pliku do rozwiązania, a na koniec automatycznie wypycha wynik (push). Przed stagingiem sprawdza, czy to, co ma zostać zacommitowane, nie zawiera sekretów, i zatrzymuje się, jeśli coś znajdzie. Powiedz „sync changes", aby to uruchomić. Nie ma to nic wspólnego z „Ingest", który zamienia `raw/inbox/` na strony `wiki/` i nie dotyka gita. Samo „sync" zawsze oznacza gita. Skill: `.agents/skills/ckb-sync-changes/SKILL.md`. ### Zapisane rozmowy (na żądanie) Powiedz „save this conversation", a transkrypt sesji zostanie skopiowany do `raw/saved-conversations//` - oryginalny plik JSONL, który przechowuje Claude Code, plus czytelna wersja `.md` - i wpisany do `index.md` w tym folderze. Zapisane rozmowy pozostają poza wyszukiwaniem: na pytania agent nadal odpowiada wyłącznie z wiki. Możesz natomiast pytać o same rozmowy („czy rozmawialiśmy o X", „co ci mówiłem/mówiłam o Y") i dostać zacytowaną dokładną wymianę zdań. Aby przenieść rozmowę do wiki, skopiuj jej `.md` do `raw/inbox/` i powiedz „Ingest". Powiedz „save conversations automatically", aby przełączyć `conversations.autosave` w `ckb.yaml` - od tej pory każda sesja jest zapisywana na końcu bez pytania. Każda sesja zaczyna się od tytułu, który agent nadaje jej na podstawie pierwszej wiadomości i podaje w pierwszej odpowiedzi; nazywa on zapisany transkrypt, a „stop telling me the title" wycisza tę linijkę. Skill: `.agents/skills/ckb-add-conversation/SKILL.md`. ### 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 (woli dodać sesję, niż upychać materiał) i zapisuje zaakceptowany plan oraz tracker postępu w `outputs/teaching//`. 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`. ### Wyjaśnienia metodą Feynmana (na żądanie) Powiedz „Feynman me on X” (albo „wyjaśnij mi porządnie X”, „czego nie rozumiem?”), a agent wyjaśni jedną stronę wiki słowami, które zna dwunastolatek, pod każdym fragmentem podając link do sekcji, z której pochodzi, a potem nazwie każde miejsce, w którym wyjaśnienie się rozrzedziło, i przypisze je do jednej z trzech grup: luka na stronie, luka w jej źródłach albo luka u wyjaśniającego. Agent nigdy nie łata luki własną wiedzą. Następnie prosi cię, żebyś sam wyjaśnił jeden fragment, i schodzi poziom głębiej. Gdy nie podasz pojęcia, proponuje strony robocze (`draft`), oparte na jednym źródle albo nieaktualne. Sesja trafia do `outputs/teaching/feynman/`; luka w źródłach trafia do `wiki/query-gaps.md` tylko po twojej zgodzie. Zobacz `.agents/skills/ckb-feynman/SKILL.md`. --- ## Szybki start 0. **Opcjonalnie: zainstaluj Pythona 3.8+.** Osiem skilli uruchamia skrypt w Pythonie (tylko biblioteka standardowa); bez niego kontrola na starcie sesji przechodzi na zapasowy skrypt bash (na Windows: Git Bash), lint i wyszukiwanie działają w wolniejszym trybie ręcznym, a eksporty są niedostępne. Kroki dla poszczególnych systemów: [docs/MANUAL.pl.md → Wymagania wstępne](docs/MANUAL.pl.md#wymagania-wstępne). 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//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//` 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 oznaczać resztę do przeglądu. - `tmp/` jest w `.gitignore`. Podobnie większość `libs/`, z jednym podziałem: kopia git w `libs//` pozostaje ignorowana, natomiast konektorowy `libs//` ma śledzone `source.yaml` oraz generowane `index.md`/`entities/`/`graph/`/`log.md`. Ten indeks to zsyntetyzowana wiedza warta udostępnienia przez „sync changes", a nie artefakt budowania. `libs//source.local.yaml` to wyjątek w wyjątku: osobisty stan maszyny, nigdy nie synchronizowany. - `outputs/` jest śledzony, ale `outputs/okf/` i `outputs/starlight/` nie. Każdy z nich da się odtworzyć z `wiki/` na żądanie, więc nie ma czego uzgadniać w historii gita. Ręcznie utrzymywane artefakty w `outputs/` commituj normalnie. - `outputs/teaching/` też jest ignorowany. Plany nauki, postęp sesji i sesje Feynmana są osobiste, nie są współdzieloną treścią KB. --- ## Wersja i licencja Aktualna wersja szablonu: [VERSION](VERSION). Licencja: [Apache License 2.0](LICENSE).