ckb/docs/MANUAL.pl.md
Michał Kopeć bf2cc8e8aa Template 1.23.0: agent-knowledge release 2, schema 1.6
Schema 1.6, all fields optional (D-0014):
- F7 review: `review: draft|reviewed|needs_update`, `reviewed_by`,
  `reviewed_on`; lint check 17 and a review queue; ckb-lint marks reviews
- F4 `> CONTRADICTION:` marker, lint check 18; validity dates deferred
- F21 `tags` against the new `wiki/tags.md`, lint check 19,
  retrieve_candidates.py --tag, DRAFT/NEEDS_UPDATE flags
- F9 profiles in workload/profiles/, protected `## Rules` on project
  scope pages, precedence AGENTS.md > Rules > profile
- F8 explicit lessons (profile or wiki/lessons.md); new ckb-profile skill

Carry-over: `.secrets-allow` `<glob> match:<hash>` entries (also in the
bash/PowerShell fallbacks); open threads no longer print twice.
ckb-upgrade migrates 1.5 -> 1.6; init/reset know tags.md; Starlight
shows review and tags. Smoke test covers a 1.6 KB. Docs in EN and PL.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-02 20:06:02 +01:00

1173 lines
69 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Podręcznik użytkownika
*Read this in: [English](MANUAL.md) | **Polski***
To jest podręcznik dla *człowieka* korzystającego z Cascade Knowledge Base
(tego repozytorium) — nie dla agenta. Zasady działania samego agenta
znajdziesz w [AGENTS.md](../AGENTS.md) / [CLAUDE.md](../CLAUDE.md). Techniczny,
funkcja-po-funkcji przegląd znajdziesz w [README.md](../README.md) (lub
[README.pl.md](../README.pl.md)). Pełny schemat strony wraz z historią obu
numerów wersji znajdziesz w [CHANGELOG.pl.md](CHANGELOG.pl.md). Ten dokument
jest zorientowany na zadania:
„chcę zrobić X — co mam powiedzieć i co się wtedy stanie?”
Wszędzie poniżej „powiedz” oznacza napisanie tego do dowolnego agenta AI,
z którego korzystasz w tym repozytorium (Claude Code lub inny agent, który
czyta `AGENTS.md`). Nie musisz używać dokładnych sformułowań — pokazane
frazy wyzwalające to przykłady, nie magiczne słowa; agent dopasowuje się do
intencji.
---
## Spis treści
1. [Tworzenie lub inicjalizacja wiki](#1-tworzenie-lub-inicjalizacja-wiki)
2. [Dodawanie wiedzy](#2-dodawanie-wiedzy)
3. [Utrzymanie porządku](#3-utrzymanie-porządku)
4. [Synchronizacja — z samym sobą i z innymi ludźmi](#4-synchronizacja--z-samym-sobą-i-z-innymi-ludźmi)
5. [Aktualizacja szablonu](#5-aktualizacja-szablonu)
6. [Przykłady użycia](#6-przykłady-użycia)
7. [Co jest generowane przez agenta, a co możesz edytować](#7-co-jest-generowane-przez-agenta-a-co-możesz-edytować)
8. [Szybki przegląd](#8-szybki-przegląd)
---
## 1. Tworzenie lub inicjalizacja wiki
### Wymagania wstępne
Agent robi prawie wszystko, czytając i pisząc Markdown. Pięć skilli
dodatkowo uruchamia mały skrypt w **Pythonie 3.8+** (tylko biblioteka
standardowa, nic do `pip install`): lint (w tym kontrola uruchamiana na
początku każdej sesji), ranking przy wyszukiwaniu, wykrywanie duplikatów w
skrzynce oraz dwa eksporty.
Python jest *zalecany*, nie bezwzględnie wymagany:
| Bez Pythona | Co się dzieje |
|---|---|
| Kontrola na starcie sesji | Zamiast niej działa zapasowy skrypt bash/PowerShell. Wykrywa strony uszkodzone, przeterminowane, zmienione źródła i najczęstsze postaci sekretów; zaznacza, że cytaty Crux i budżet kontekstu nie zostały sprawdzone. |
| Sprawdzanie duplikatów przy „Ingest” | Agent ręcznie porównuje skróty `sha256sum` plików ze skrzynki i archiwum, a porównanie adresów URL pomija. |
| „Lint” | Agent przechodzi ręczną listę kontrolną z `grep` — wolniej, w ograniczonym zakresie, i mówi, co pominął. |
| Pytania | Agent szereguje kandydatów ręcznie z indeksów i `grep` zamiast skryptu fuzji. |
| Eksport OKF / Starlight | Niedostępny do czasu zainstalowania Pythona. |
Agent raz na sesję mówi, że nie znalazł interpretera, i dalej pracuje
ścieżkami zapasowymi. Jak zainstalować Pythona:
- **Windows** — `winget install Python.Python.3.12` w terminalu, albo
aplikacja „Python 3.12” z Microsoft Store, albo instalator z
[python.org](https://www.python.org/downloads/windows/) (zaznacz *Add python.exe
to PATH*). Potem `python --version` lub `py -3 --version` powinno
wypisać `Python 3.x`. Jeśli `python` otwiera Store, wyłącz *Aliasy
wykonywania aplikacji* dla `python.exe` w Ustawieniach Windows albo używaj
`py -3`.
- **macOS** — `brew install python` przez [Homebrew](https://brew.sh) albo
`xcode-select --install` dla `python3` dostarczanego przez Apple.
- **Linux** — `sudo apt install python3` (Debian/Ubuntu),
`sudo dnf install python3` (Fedora), `sudo pacman -S python` (Arch).
Większość dystrybucji już go ma.
Dowolne z `python3`, `python` lub `py -3` wystarczy; agent próbuje ich w tej
kolejności.
### Jeśli czytasz to wewnątrz istniejącej Cascade KB
Nie musisz nic robić — struktura już istnieje (`wiki/`, `raw/`, `outputs/`
itd.). Przejdź do [§2](#2-dodawanie-wiedzy).
### Zakładanie zupełnie nowej wiki gdzie indziej
Powiedz:
> „Set up a new wiki like this one in `~/projects/my-notes`.”
To sklonuje wyłącznie *schemat* — strukturę katalogów, plik zachowań
`AGENTS.md`/`CLAUDE.md` oraz pusty szkielet `wiki/` — do docelowego folderu.
Nigdy nie kopiuje rzeczywistej zawartości tego projektu (żadnych encji,
danych grafu, notatek). Otrzymujesz świeżą, pustą KB, gotową na pierwszy
zrzut do `raw/inbox/`. Zobacz `.agents/skills/ckb-init/SKILL.md`.
Szablon może pochodzić z dwóch miejsc: z plików tego repozytorium albo ze
świeżego, płytkiego klona kanonicznego repozytorium szablonu (lub dowolnego
forka/mirrora, którego URL podasz), pobranego do folderu roboczego.
Powiedz „pull the latest template and set up a KB in \<folder\>” — albo
uruchom skilla spoza jakiejkolwiek KB — a agent najpierw sklonuje
repozytorium, a dopiero potem zbuduje szkielet. Klon jest wyłącznie
roboczy: nowa KB dostaje własną historię gita (agent pyta przed
`git init`), a nie historię szablonu.
Jeśli docelowy folder wygląda już jak baza wiedzy (ma `wiki/` lub
`AGENTS.md`), agent zatrzyma się i zapyta, zanim czegokolwiek dotknie — nie
nadpisze po cichu istniejącej bazy wiedzy.
### Budowanie na bazie cudzej wiki
Cascade KB może opierać się na jednej lub wielu *nadrzędnych* bazach
wiedzy, które pozostają tylko do odczytu. Są trzy sposoby ich
podpięcia:
- **Dowiązanie symboliczne** (inna KB na twojej maszynie, lub taka, którą
utrzymujesz gdzie indziej i chcesz mieć „na żywo”):
```bash
ln -s /path/to/other-kb ./linked/other-team
```
- **Kopia git** (zewnętrzna KB, której chcesz mieć zamrożoną, wersjonowaną
kopię):
```bash
git clone https://github.com/org/external-kb ./libs/external-kb
```
Nie chcesz używać gita? Większość hostingów git oferuje też opcję
„Download ZIP” na stronie repozytorium — pobierz i rozpakuj zawartość
bezpośrednio do `./libs/external-kb`. Tak czy inaczej otrzymujesz tę
samą zamrożoną, tylko-do-odczytu kopię. Różnica polega tylko na tym, że
nie odświeżysz jej później przez `git pull`; żeby ją zaktualizować,
pobierz ZIP ponownie i rozpakuj go na starą zawartość.
- **Konektor** (żywe zewnętrzne źródło, którego *nie* chcesz mieć w pełnej
lokalnej kopii — folder SharePoint, folder Google Drive albo inne
podłączone źródło): sam utwórz `libs/<name>/source.yaml`:
```yaml
connector: sharepoint
location: "https://contoso.sharepoint.com/sites/Finance/Shared Documents/Reports"
description: "Wspólny folder raportów zespołu finansowego"
```
a potem powiedz „index external sources". Agent czyta konfigurację,
łączy się z tym, co jest dostępne w danej sesji (podłączonym narzędziem
Microsoft 365/Google Drive albo zwykłym pobraniem URL), i buduje krótki
indeks tego, co znajdzie — po jednym wpisie na dokument — wewnątrz tego
samego folderu `libs/<name>/`. Zobacz [§6](#6-przykłady-użycia) po
omówiony przykład i to, jak wygląda wynik.
Zanim oprzesz się na źródle typu konektor:
- Nie musisz sam budować indeksu. `source.yaml` może dodać blok
`index:` wskazujący na już zbudowany indeks — repozytorium git albo
zasób współdzielony — dzięki czemu pobierasz to, co ktoś inny już
zaindeksował, zamiast samodzielnie skanować żywe źródło. Każde
uruchomienie najpierw sprawdza tę lokalizację: jeśli indeks już tam
jest, dostajesz go. Jeśli go tam jeszcze nie ma (normalny stan, zanim
ktokolwiek z dostępem do zapisu to uruchomił), to nie błąd: najbliższe
uruchomienie osoby z dostępem do zapisu po raz pierwszy go tam utworzy
i opublikuje.
- Budowanie i odświeżanie są opcjonalne, per osoba, per źródło.
Domyślnie każdy ma do źródła typu konektor dostęp tylko do odczytu —
niczyj agent nie przeskanuje żywego konektora w imieniu osoby, która
wyraźnie o to nie poprosiła. Powiedz „make me the admin for
`<source>`", żeby się na to zapisać (tworzy to lokalny, osobisty plik
`libs/<name>/source.local.yaml` — nigdy niecommitowany, nigdy
niewidoczny dla współpracowników). Jedna lub dwie osoby utrzymują
źródło dla całego zespołu; nikt inny go ponownie nie skanuje.
- Możesz ustawić, jak często ma być odświeżane. Dodaj opcjonalne
`refresh_interval_days: 7` do `source.yaml` (domyślnie 30). Folder
zmieniający się codziennie potrzebuje krótszego okna niż kwartalne
archiwum, którego nikt nie tyka. Wtedy zarówno „index external
sources", jak i „Lint" powiedzą ci, kiedy źródło jest zaległe i o ile.
Ma to największe znaczenie, jeśli masz do niego dostęp tylko do
odczytu: gdy wiesz, *które* źródło się przedawniło, możesz zapytać
osobę, która je utrzymuje.
Niezależnie od sposobu, po podpięciu wystarczy normalnie zadawać pytania.
Agent sprawdza najpierw twoją lokalną `wiki/`, potem przechodzi przez
`linked/`, potem `libs/`, i korzysta z tego, co ma odpowiedź. Nigdy nie
edytujesz plików wewnątrz `linked/` ani kopii git w `libs/<name>/`
bezpośrednio; jeśli coś tam jest błędne lub nieaktualne, poprawiasz to,
zapisując poprawioną wersję we własnej lokalnej `wiki/`, która zawsze
wygrywa. (`libs/<name>/` oparty na konektorze to jedyne miejsce, gdzie
agent *sam* zapisuje w twoim imieniu — zobacz [§6](#6-przykłady-użycia) —
ale tylko swój generowany indeks, i tylko część budowania/odświeżania,
jeśli jesteś administratorem tego źródła; `source.yaml` zawsze pozostaje
twój do edycji, nigdy agenta.)
---
## 2. Dodawanie wiedzy
To główny sposób, w jaki rośnie wiki. Jest pięć dróg:
### A. Wrzuć materiał, potem powiedz „Ingest”
Umieść cokolwiek nieprzetworzonego w `raw/inbox/` — wklejone notatki, plik
`.txt` z transkrypcją, `links.txt` z adresami URL, PDF, chaotyczny plik
roboczy. Nie musisz go najpierw porządkować. Następnie powiedz:
> „Ingest.” (lub „Update the wiki” — to samo; nigdy fraza zawierająca „sync”, to jest git)
Przykład:
> *Wrzucasz `meeting-2026-07-10.txt` (surowe notatki z rozmowy z klientem)
> do `raw/inbox/`, potem mówisz „Ingest.”*
>
> Agent czyta plik, wydobywa wymienione osoby, decyzje i otwarte pytania,
> tworzy lub aktualizuje strony encji w `wiki/entities/`, zapisuje relacje
> w `wiki/graph/edges.json`, dodaje nowe strony do `wiki/index.md`, loguje
> zmianę w `wiki/log.md` i przenosi oryginalny plik do
> `raw/archive/2026-07-10/`. Na koniec przypomina o przejrzeniu wyniku i
> powiedzeniu „sync changes”, gdy wynik będzie ci odpowiadał.
Przy długim transkrypcie agent nie poprzestaje na jednej stronie
podsumowania. Wyciąga wyszukiwalne pytanie, podsumowanie, rozwiązanie oraz
zaangażowane systemy i osoby — a pojedyncze fragmenty awansuje do własnych
znajdowalnych sekcji, jeśli inaczej przepadłyby wewnątrz podsumowania. Ta
ostatnia część ma celowy próg: fragment musi zawierać konkretny
termin (flagę, komunikat błędu, klauzulę, numer wersji), mieć co najmniej
kilka zdań i być potwierdzony przez coś dalej w materiale. W przeciwnym razie
zostaje wtopiony w podsumowanie. Bez tego progu każdy akapit wygląda na wart
zacytowania, a strona wiki znów staje się transkryptem — co przekreśla sens
jego zingestowania.
Jeśli `raw/inbox/` jest puste, agent skanuje bezpośrednio `raw/` (nadal
pomijając `raw/archive/`, które zawiera już przetworzoną historię).
Zanim cokolwiek zostanie zapisane, dzieją się trzy rzeczy:
- **Duplikaty zostają wyłapane.** Skrypt porównuje każdy plik ze skrzynki z
`raw/archive/` i ze źródłami, które strony wiki już cytują. Plik już
zingestowany (co do bajtu albo ten sam tekst zapisany ponownie z innymi
końcami linii), link do strony, którą wiki już cytuje, albo dwie kopie tego
samego pliku w skrzynce zostają zgłoszone jako „już zingestowane <data> →
<strony>”. Agent pyta, zanim którykolwiek pominie.
- **Agent się melduje.** Dla każdego źródła mówi w trzech–czterech
linijkach, jak je rozumie, które strony utworzy lub zmieni i z czym jest
sprzeczne. Potem czeka. Popraw go w tym momencie: to dużo taniej niż
poprawianie stron później. Powiedz „ingest in batch” (albo „no check-in”),
żeby to pominąć, np. dla dużej paczki, której ufasz. Ingest uruchomiony
przez rutynę z `confirm: false` też to pomija.
- **Fragmenty prywatne zostają poza wiki.** Wszystko, co w źródle owiniesz w
`<private>` … `</private>`, nigdy nie trafia do wiki: nie jest zapisywane,
cytowane ani streszczane.
Strony tworzone przez agenta zaczynają jako `review: draft`, czyli nikt ich
jeszcze nie sprawdził. Gdy nowy materiał nie zgadza się ze stroną i nie
wiadomo, co jest prawdą, agent nie wybiera zwycięzcy. Wpisuje na stronę
znacznik i mówi ci o tym:
```markdown
> CONTRADICTION: three retries (`raw/archive/2026-09-01/kickoff-notes.md`) vs five retries (`raw/archive/2026-11-02/runbook.md`) — found 2026-11-02
```
Znacznik zostaje, dopóki go nie rozstrzygniesz (zob. „Przegląd, sprzeczności
i tagi” w [Utrzymaniu porządku](#3-utrzymanie-porządku)).
Skill: `.agents/skills/ckb-ingest/SKILL.md`.
### B. Po prostu powiedz agentowi coś w rozmowie
Nie zawsze potrzebujesz pliku. Jeśli powiesz agentowi fakt o trwałej
wartości, np. „właściwie to termin przesunął się na wrzesień”, agent może
zapisać go bezpośrednio do `wiki/` jako nową stronę lub
aktualizację istniejącej, tak samo jak z zaingestowanego pliku.
### C. Pozwól agentowi powiedzieć, czego brakuje (Demand-Driven Context)
Jeśli zapytasz o coś, na co wiki nie potrafi odpowiedzieć, agent nie
zawiedzie po cichu. Wskaże lukę i zaproponuje minimalną stronę,
która ją wypełni.
Przykład:
> **Ty:** „Jaka jest nasza polityka w sprawie X?”
> **Agent:** „Wiki jeszcze tego nie pokrywa. Chcesz, żebym dodał zalążek
> strony, czy możesz wkleić/opisać tę politykę, a ja ją spiszę?”
Zatwierdzasz, wklejasz źródło albo wrzucasz je do `raw/inbox/` — kolejny
ingest to wchłonie. Dzięki temu wiki pozostaje napędzana zapotrzebowaniem:
rośnie wokół tego, o co faktycznie pytasz, a nie wokół wszystkiego, co
teoretycznie dałoby się spisać.
Trwałe braki można też śledzić w `wiki/query-gaps.md`. Dobry wpis o luce jest
maleńki: pytanie, gdzie agent szukał i jakie najmniejsze źródło lub strona
sprawiłaby, że odpowiedź będzie dostępna następnym razem.
### D. Zapisz decyzję
Gdy zapada jakaś decyzja — wybór technologii, zmiana procesu, polityka —
powiedz:
> „Zapisz decyzję: przenosimy billing na Postgresa. Alice i Bob zdecydowali
> dzisiaj, bo zapytania raportowe zabijały MySQL-a."
Agent zapisze numerowany rekord pod `wiki/decisions/` z decyzją, autorami,
datą, uzasadnieniem, alternatywami i tym, czego dotyczy. Jeśli zastępuje
wcześniejszą decyzję, połączy obie w obu kierunkach i oznaczy starą jako
zastąpioną — nie ruszając jej uzasadnienia. O to, czego nie podasz, dopyta w
jednej turze; jeśli jesteś w środku pracy, powiedz to, a zapisze, co ma, i
wskaże, które pola zostawił otwarte.
Potem pytaj, jak chcesz:
> „Co zdecydowaliśmy w sprawie bazy danych billingu?"
> „Dlaczego używamy Postgresa?"
> „Kto to zdecydował i kiedy?"
> „Które decyzje są wciąż tylko propozycjami?"
> „Co zastąpiło decyzję 3?"
Odpowiedź zawsze przychodzi z informacją kto i kiedy, i wprost mówi, gdy
decyzja jest propozycją, a nie decyzją obowiązującą, albo została już
zastąpiona — żeby nie opierać się na czymś, co nie obowiązuje. Skill: `ckb-decide`.
Dwie zasady:
- Decyzje są tylko do dopisywania. „Właściwie zmieniliśmy zdanie" tworzy
*nową* decyzję zastępującą starą; nigdy nie edytuje uzasadnienia starej.
Historia jest tu sednem. Zwykłe błędy zapisu („tam miała być Anna,
nie Alice") agent poprawia w miejscu.
- Propozycja to nie decyzja. Jeśli sprawa nie została rozstrzygnięta,
zapisywana jest jako `proposed` bez daty decyzji i pojawia się, gdy pytasz,
co jest jeszcze otwarte.
### E. Utwórz lokalny zakres projektu
Gdy jakiś temat, klient, system lub inicjatywa wraca często, poproś:
> „Utwórz zakres projektu dla integracji płatności."
Agent utworzy lub zaktualizuje zwykłą stronę Markdown pod `wiki/projects/`,
wymieniającą strony, encje, pliki z `raw/archive/`, indeksy konektorów i
obszary grafu, które należy przeszukać najpierw dla tego zakresu. Nadal masz
jedną lokalną wiki; to tylko daje powracającym pytaniom lepszy punkt startowy.
Strona zakresu może też zawierać zasady zespołu dla tego projektu, w sekcji
`## Rules`, którą piszesz sam: „środowiska nazywamy `prod`/`stage`, nigdy
`production`”, „decyzje tutaj wymagają zgody klienta”. Agent stosuje je
zawsze, gdy pracuje w tym zakresie, a żaden skill ich nie przepisuje. Nadrzędny
jest tylko `AGENTS.md`.
---
## 3. Utrzymanie porządku
Powiedz, kiedy chcesz — po dużym ingest lub po prostu okresowo (albo niech
robi to za ciebie [rutyna](#rutyny-rób-to-za-mnie-co-n-dni)):
> „Lint.”
To uruchamia przegląd kondycji całej wiki:
- strony bez wymaganego frontmatteru (`type`) są oflagowywane
- strony nietykane od dłuższego czasu są oflagowywane jako nieaktualne
- wyniki pewności (confidence) zanikają, jeśli nic ostatnio ich nie
wzmocniło
- stare, niskopriorytetowe strony są archiwizowane do `wiki/archived/`
(nigdy usuwane)
- sprzeczne strony są łączone stare→nowe (supersesja)
- osierocone strony (nic do nich nie linkuje) dostają odnośniki zwrotne
albo są archiwizowane
- uszkodzone krawędzie grafu są naprawiane lub usuwane
- brakujące/podwójne wpisy w indeksie i dzienniku są poprawiane
- konektorowe źródła, których indeks jest zaległy do odświeżenia, zostają
oflagowane wraz z informacją o ile — przydatne nawet jeśli masz do tego
źródła dostęp tylko do odczytu, bo mówi ci, kogo dopytać
- strony, których źródło faktycznie się zmieniło, zostają oflagowane —
patrz niżej
- cytaty, których nie ma już w źródle, na które się powołują, zostają
oflagowane
- powtarzające się problemy systemowe trafiają do `wiki/error-book.md`
- przypadkowo zacommitowane dane uwierzytelniające (klucze, tokeny, klucze
prywatne, hasło w adresie URL) gdziekolwiek w `wiki/`, `outputs/`,
`workload/` lub `raw/`, a także fragment `<private>`, który trafił na
stronę wiki, zostają oflagowane — nigdy nie są naprawiane automatycznie,
patrz niżej
- zachowane odpowiedzi w `outputs/answers/`, których źródła się zmieniły,
zostają oflagowane
- warstwa ładowana zawsze (`AGENTS.md` plus opis każdego skilla) zostaje
oflagowana, gdy przekroczy budżet z `ckb.yaml`
Dwie kontrole źródeł (zmienione skróty i cytaty, które przestały się
zgadzać) to różnica między „ta strona jest stara"
a „ta strona jest błędna".
Każda strona zapisuje skrót materiału, z którego powstała. Nieaktualność
liczona datą to przypuszczenie: strona napisana rok temu może być wciąż
całkowicie poprawna. Skrót nie jest przypuszczeniem — agent przelicza go i
albo źródło jest co do bajtu tym, przeciwko czemu stronę napisano, albo ktoś
je zmienił. Gdy źródło się zmienia, strona na nim zbudowana trafia na szczyt
listy, przed wszystko, co się jedynie zestarzało.
Strony cytują też swoje źródła wprost, w sekcji `## Crux` — kilka dosłownych
linijek niosących właściwe twierdzenie, pod streszczeniem agenta. Wynikają z
tego dwie rzeczy. Gdy zadajesz pytanie, agent często może odpowiedzieć z
cytatu zamiast ponownie czytać całe źródło i pokazać ci słowa, a nie swoją
parafrazę. A gdy cytat przestaje zgadzać się ze źródłem, to strona twierdzi —
w cudzysłowie — coś, czego jej dowód już nie mówi. To najmocniejsze
znalezisko lintu i agent nigdy nie „naprawi" go, po cichu dopasowując cytat
do źródła.
Połowa wykrywająca działa jako skrypt Python tylko-do-odczytu
(`scripts/lint_report.py`; bez Pythona zob.
[Wymagania wstępne](#wymagania-wstępne), co nadal działa), więc ta sama
wiki zawsze daje tę samą listę znalezisk. Agent czyta ten raport, a potem
wykonuje części wymagające osądu (supersesja, niejednoznaczne sieroty,
wpisy do księgi błędów oraz decyzja, co naprawić, a co oddać tobie).
Naprawia samodzielnie to, co może zrobić bezpiecznie, a resztę zgłasza do
twojej decyzji. Podobnie jak Ingest, na koniec przypomina o przejrzeniu i
synchronizacji. Skill: `.agents/skills/ckb-lint/SKILL.md`.
**Sekrety.** Klucz znaleziony w repozytorium jest pokazywany tylko w
pierwszych czterech znakach, nigdy w całości. Naprawa należy do ciebie: usuń
go i **wymień** (rotate) — zacommitowany sekret zostaje w historii gita nawet
po usunięciu linii. Nieszkodliwe dopasowanie, np. przykładowy klucz w
dokumentacji, można dodać do listy dozwolonych: znalezisko podaje linię
`<ścieżka> <skrót>` do wpisania w `.secrets-allow` w katalogu głównym repo.
Skrót obejmuje tę jedną linię, więc jej edycja przywraca znalezisko. Ta sama
kontrola działa przed każdym commitem w „sync changes”.
### Przegląd, sprzeczności i tagi
**Przegląd.** Strona może mówić, czy sprawdził ją człowiek: `review: draft`
(napisał ją agent, nikt nie sprawdził), `reviewed` (z `reviewed_by` i
`reviewed_on`) albo `needs_update` (była przejrzana, potem się zmieniła lub
pojawiła się sprzeczność). Zapytaj „what needs review?”, żeby zobaczyć
kolejkę, najpierw `needs_update`. Powiedz „mark X as reviewed”, gdy
przeczytasz stronę; agent zapisze twoje nazwisko i dzisiejszą datę i nigdy nie
oznaczy strony, której nie wskazałeś. Jeśli przejrzana strona później się
zmieni, lint to zauważy. Odpowiedzi oparte na stronach `draft` mówią o tym.
**Sprzeczności.** Lint wypisuje każdy otwarty znacznik `> CONTRADICTION:`.
Rozstrzygasz go, mówiąc, która strona ma rację. Agent wtedy zastępuje błędną
stronę (supersesja), zapisuje decyzję („record a decision: we retry five
times”) albo poprawia twierdzenie, i usuwa znacznik.
**Tagi.** Strona może mieć `tags: retries, billing`, ale tylko z tagami
wymienionymi w `wiki/tags.md`. Zanim użyjesz nowego tagu, dodaj tam wiersz;
lint flaguje każdy tag spoza listy. Pytania można wtedy zawęzić do tagu.
**Budżet kontekstu.** Każda sesja zaczyna się od wczytania `AGENTS.md` i
jednolinijkowego opisu każdego skilla. To kosztuje tokeny, zanim cokolwiek
powiesz. Lint szacuje ten koszt (znaki ÷ 4) i flaguje go, gdy przekroczy
`budget: always_loaded_tokens` w `ckb.yaml` (domyślnie 9000). Powiedz „show
the context budget”, żeby zobaczyć rozbicie.
### Start sesji: podsumowanie, otwarte wątki i hook
Na początku każdej sesji agent uruchamia jeden skrypt i dostaje krótkie
podsumowanie: kim jesteś (tożsamość z gita), stan gita, jednolinijkową
kontrolę kondycji, zaległe rutyny i ostatnią notatkę z `workload/`. Reaguje
tylko na linie, które tego wymagają.
**Otwarte wątki.** Gdy sesja kończy się czymś niedokończonym, agent zapisuje
to w notatce z danego dnia pod nagłówkiem `### Open threads` jako
`- [ ] pozycja`. Podsumowanie liczy otwarte wątki we wszystkich notatkach i
wymienia kilka najstarszych, zaznaczając te starsze niż 30 dni. Żeby zamknąć
wątek, odhacz go tam, gdzie został otwarty (`- [x]`), albo napisz
`- [x] dropped: <powód>`. Nic nie jest usuwane, więc notatki pozostają
zapisem. To jest widok „co jest teraz w toku”: nie ma osobnego pliku
statusu, który trzeba by aktualizować.
**Hook startu sesji (tylko Claude Code).** Domyślnie agent sam uruchamia
podsumowanie jako pierwszą czynność. Z hookiem robi to Claude Code, zanim
napiszesz pierwszą wiadomość, i ponownie po kompaktowaniu rozmowy, więc w
długiej sesji podsumowanie nie wypada z kontekstu. Żeby go włączyć, powiedz
„turn on the session-start hook”. Agent ustawia `session: start_hook: true`
w `ckb.yaml` i, po zapytaniu, instaluje hook w `.claude/settings.local.json`.
Ten plik jest per maszyna i nigdy nie jest commitowany, bo hook w gicie
uruchamiałby kod przy każdym klonie. Współpracownicy na innych maszynach
widzą w podsumowaniu linię `start hook:` i są pytani raz. Inni agenci
ignorują to ustawienie i dalej uruchamiają podsumowanie sami.
### Rutyny: rób to za mnie co N dni
Wszystko, co można powiedzieć agentowi, można zamienić w rutynę:
> „Lint co tydzień.”
> „Indeksuj zewnętrzne źródła co 30 dni, ale najpierw mnie zapytaj.”
Agent zapisuje ją w `ckb.yaml` w bloku `routines:` (nazwa, fraza do
wykonania, okres, czy pytać najpierw i data ostatniego uruchomienia).
Rutyna liczy czas od ostatniego uruchomienia, nie według kalendarza: na
starcie każdej sesji agent sprawdza, którym rutynom minął okres, najpierw
odpowiada na to, o co prosisz, a potem w tej samej turze wykonuje zaległe,
raportując każdą jedną linijką. Rutyna oznaczona „najpierw zapytaj” jest
zamiast tego proponowana na końcu odpowiedzi i uruchamia się tylko po
twojej zgodzie. Rutyna, która się nie powiodła albo została odrzucona, nie
jest oznaczana jako wykonana, więc wraca w następnej sesji. Ręczne
wykonanie też się liczy — gdy sam powiesz „Lint”, licznik tygodniowego
lintu startuje od nowa.
Ponieważ data ostatniego uruchomienia jest commitowana z repozytorium,
rutyna odpala się raz na okres dla wszystkich pracujących w tej KB, a nie
raz na maszynę. Dwóch akcji nie da się zrobić rutyną: resetu wiki i
synchronizacji z gitem. „List routines”, „which routines are due”, „run the
routines now” i „remove the weekly lint” robią to, co mówią. To nie jest
chmurowy harmonogram Claude Code: nic się nie dzieje, gdy nikt nie ma KB
otwartej.
Skill: `.agents/skills/ckb-routine/SKILL.md`.
### Zaczynanie od zera: reset do czystego szablonu
Czasem chcesz zachować *kształt* bazy wiedzy bez jej zawartości — zwykle
dlatego, że to repozytorium pełni też rolę szablonu przekazywanego innym, a
zdążyło zebrać decyzje, podsumowania sesji i strony encji, które nie powinny
z nim wędrować.
> „Zresetuj wiki.” / „Zrób z tego czysty szablon.”
To jedyne polecenie w tym repozytorium, które **celowo usuwa wiedzę**, więc
jest zbudowane tak, żeby trudno było je uruchomić przez przypadek:
1. **Najpierw szuka punktu przywracania.** Jeśli drzewo robocze jest
„brudne”, zatrzymuje się i proponuje commit — po resecie wszystko, co
zacommitowane, jest o jedno `git checkout` stąd, a wszystko
niezacommitowane po prostu znika. Może też otagować commit
(`pre-reset-<data>`), żeby nie trzeba było pamiętać hasha.
2. **Pyta, jak daleko sięgnąć.** Sześć poziomów wybieranych osobno: wiedza w
wiki, historia `workload/`, materiał źródłowy w `raw/`, `outputs/`,
źródła zewnętrzne i zainstalowane moduły. Domyślnie włączony jest tylko
pierwszy. `libs/`, `linked/` i moduły domyślnie na *nie* — `linked/`
zawiera dowiązania do cudzych baz wiedzy, więc usuwa dowiązanie, ale
nigdy nie podąża za nim.
3. **Liczy, zanim zapyta.** Dostajesz inwentarz — ile stron, ile rekordów
decyzji (wymienionych z numerem i tytułem), ile krawędzi grafu, plus
wszystko oznaczone `retention: high` — i jedną linijkę o tym, co
przetrwa.
4. **Wymaga wpisania frazy**, nie „tak”. A jeśli w odpowiedzi zmienisz
zakres, przeliczy wszystko i zapyta ponownie, bo zgoda dotyczyła
konkretnej liczby, a liczba się zmieniła.
5. **Weryfikuje po wszystkim**, uruchamiając lint, zanim powie, że się
udało.
Odtwarza dokładnie to, co utworzyłby `ckb-init`: te same katalogi, te same
pliki szkieletu, ten sam `kb_schema_version`. Opróżnienie treści nie cofa
wersji schematu.
Czego nie rusza nigdy, z potwierdzeniem czy bez: warstwy szablonu
(`AGENTS.md`, `.agents/`, `LICENSE`, `VERSION`, dokumentacja) oraz `src/`,
gdzie leżą niezależne repozytoria kodu, do których usuwania to polecenie nie
ma żadnego tytułu.
Jedna celowa osobliwość: w odróżnieniu od każdego innego skilla ten **nie**
zapisuje notatki sesji w `workload/` — byłby to pierwszy wpis w katalogu,
który właśnie opróżnił. Informuje o tym w raporcie.
Skill: `.agents/skills/ckb-reset/SKILL.md`.
---
## 4. Synchronizacja — z samym sobą i z innymi ludźmi
Są tu dwa różne rodzaje „synchronizacji”. Nie myl ich:
| | Ingest / Lint | Sync changes |
|---|---|---|
| **Warstwa** | Treść (co wiki wie) | Git (czyj dysk ma jakie pliki) |
| **Czego dotyczy** | `wiki/`, `raw/` | Historia commitów repo i zdalne repozytorium `origin` |
| **Powiedz** | „Ingest” / „Lint” | „Sync changes” |
### Uzgadnianie z `origin` (synchronizacja na poziomie gita)
Powiedz:
> „Sync changes.”
To commituje wszelkie lokalne zmiany (np. z ostatniego Ingest lub Lint),
pobiera wszystko nowe z `origin`, scala oba, a jeśli pojawi się konflikt —
przeprowadza cię przez niego plik po pliku, pytając, czy zachować twoją
wersję, wersję zdalną, czy podać scaloną treść dla każdego konfliktowego
fragmentu. Gdy wszystko jest rozwiązane, wypycha zmiany (push).
Jeśli to repozytorium nigdy nie było połączone ze zdalnym, agent najpierw
poprosi cię o wklejenie adresu URL:
> **Agent:** „To repozytorium nie ma skonfigurowanego zdalnego `origin`.
> Wklej adres URL zdalnego repozytorium, a dodam je jako `origin`.”
>
> **Ty:** `https://git.wierzbowa.cloud/michal/ckb`
Dla *tej* Cascade KB kanoniczną, zawsze aktualną kopią jest repozytorium
źródłowe
[git.wierzbowa.cloud/michal/ckb](https://git.wierzbowa.cloud/michal/ckb).
Jeśli nie masz pewności, czy twoja lokalna kopia jest aktualna, porównaj ją
właśnie z nim.
Nie musisz go też klonować przez `git clone`, żeby mieć działającą kopię.
Jeśli wolisz w ogóle nie używać gita, pobierz go jako ZIP z tej strony i
rozpakuj lokalnie: dostajesz dokładnie te same pliki i możesz od razu
skierować swojego agenta na rozpakowany folder. Zabraknie tylko
skonfigurowanego `origin`, więc „sync changes” i „upgrade the wiki” nie
będą miały z czym porównywać ani dokąd wypychać zmian. Gdy zechcesz z nich
korzystać, uruchom `git init` w rozpakowanym folderze i dodaj powyższy
adres jako `origin` (`git remote
add origin https://git.wierzbowa.cloud/michal/ckb`).
Od tej pory „sync changes” uzgadnia stan właśnie z tym zdalnym
repozytorium. Tak dzieli się jedną wiki między wieloma osobami: każdy
robi ingest/edycje lokalnie, a „sync changes” to sposób, w jaki zmiany
każdej osoby docierają do reszty — i jak zmiany innych docierają do ciebie.
Przed commitem sprawdza, czy to, co ma zostać zacommitowane, nie zawiera
sekretów (zob. [Utrzymanie porządku](#3-utrzymanie-porządku)). Jeśli coś
znajdzie, zatrzymuje się i pyta, a commituje mimo to tylko na wyraźne
polecenie. Skill: `.agents/skills/ckb-sync-changes/SKILL.md`.
Agent przypomina o tym też sam: na początku i na końcu sesji pracy wykonuje
szybkie, tylko-do-odczytu sprawdzenie, czy jest coś niezacommitowanego lub
niewypchniętego, i informuje, czy warto uruchomić „sync changes”. Nigdy nie
wypycha zmian bez twojej prośby. Na końcu sesji, w której wykonano realną
pracę, pyta też raz, czy zapisać rozmowę (zob. „Zapisywanie rozmowy” w Przykładach użycia) — i
zapisuje tylko wtedy, gdy się zgodzisz.
### Budowanie współdzielonej kaskady (synchronizacja na poziomie KB)
Jeśli zamiast *jednej współdzielonej wiki* chcesz mieć *własną wiki, która
buduje na cudzej* — np. wiki twojego zespołu nadbudowana na
ogólnofirmowej KB — to w ogóle nie jest synchronizacja gita; to podpięcie
`linked/`/`libs/` opisane w
[§1](#budowanie-na-bazie-cudzej-wiki). Każda osoba/zespół utrzymuje własną
lokalną `wiki/` (która zawsze wygrywa), a nadrzędne bazy wiedzy aktualizują
się według własnego harmonogramu, niezależnie.
---
## 5. Aktualizacja szablonu
To inny rodzaj „bycia na bieżąco” niż wszystko w
[§4](#4-synchronizacja--z-samym-sobą-i-z-innymi-ludźmi): tamta sekcja
dotyczy *zdalnego repozytorium twojej własnej KB* — dzielenia się twoją
zawartością ze współpracownikami. Ta sekcja dotyczy nadganiania *narzędzi*
twojej KB względem ulepszeń wprowadzonych w samym kanonicznym szablonie
Cascade KB, niezależnie skąd twoja KB pierwotnie pochodzi (`ckb-init`,
klon, fork, albo KB, która istnieje wystarczająco długo, by poprzedzać
niektóre z tych konwencji).
Powiedz:
> „Upgrade the wiki.” / „Check for a newer template version.”
### Z jakiego kanału pobierasz
Repozytorium szablonu utrzymuje trzy gałęzie i domyślnie dostajesz tę
stabilną:
| Gałąź | Czym jest | Kto powinien na niej być |
|---|---|---|
| `main` | **Stabilna** — wydany szablon | Ty, o ile nie masz powodu, żeby być gdzie indziej |
| `test` | **Kandydat do wydania** — walidowany, zanim trafi do `main` | Pomagasz walidować wydanie albo potrzebujesz poprawki, która weszła, ale nie została wydana |
| `experimental` | **Rozwojowa** — bieżąca praca, może być zepsuta albo wycofana | Rozwijasz sam szablon |
Żeby użyć innej, powiedz której:
> „Upgrade from the test branch.” / „Check experimental for updates.” /
> „Switch this KB back to the stable channel.”
To, co wybierzesz, zostaje — jest zapisane w `ckb.yaml`, więc kolejny upgrade
zostanie na tym samym kanale, zamiast po cichu ściągnąć cię z powrotem na
`main`. Tak samo przy tworzeniu: *„zainicjuj z gałęzi experimental”*.
Na jedno warto uważać. Jeśli śledzisz `test` albo `experimental`, twoja KB
może mieć wersję, której `main` jeszcze nie wydało. Sprawdzenie względem
`main` nie znajdzie wtedy nic nowszego — agent powie ci, że **wyprzedzasz**, a
nie że jesteś aktualny, bo to dwie różne sytuacje. Powrót stamtąd na `main` to
*downgrade*: może usunąć skille i cofnąć schemat poniżej tego, pod co napisano
twoje strony. Agent poprosi o wyraźne potwierdzenie, a gdy treść
przestałaby być zgodna z własnym zadeklarowanym schematem, odmówi wprost.
### Co jest sprawdzane
Sprawdzane są dwie odrębne rzeczy, i każda, obie albo żadna może
coś wykazać:
- **Warstwa szablonu/narzędzi** — `AGENTS.md`/`CLAUDE.md`, każdy skill pod
`.agents/skills/`, `LICENSE`, `VERSION` oraz dokumenty
`README`/`MANUAL`. Porównywana z plikiem `VERSION` samego kanonicznego
repozytorium.
- **Własna wersja schematu twojej treści wiki** — pole `kb_schema_version`
w `wiki/index.md`, porównywane z tym, czego obecnie oczekuje szablon. KB
może być w pełni aktualna pod względem narzędzi, ale nadal nosić treść
`wiki/` zbudowaną lata temu pod starszym (albo w ogóle brakującym)
`kb_schema_version` — albo odwrotnie.
**Jeśli nic nie jest opóźnione na żadnym froncie**, dostaniesz
„już aktualne — szablon vX, schemat wiki vY” i nic się nie zmieni.
**Jeśli warstwa szablonu jest opóźniona**, zobaczysz podział na to, co
nowe (nic lokalnego do stracenia) i to, co *zmienione* (plik szablonu,
którego lokalna kopia różni się — to może być ulepszenie szablonu albo
twoja celowa zmiana, np. w `AGENTS.md`). Agent zapyta, plik po pliku albo
wszystko naraz, czy wziąć wersję
szablonu, zachować swoją, czy najpierw zobaczyć pełną różnicę — nic nie
zostanie po cichu nadpisane.
**Jeśli schemat twojej treści wiki jest opóźniony** (w tym częsty przypadek
starszej KB bez żadnego `kb_schema_version` — „niewersjonowanej” wiki),
dostaniesz odrębne, wyraźne pytanie:
> **Agent:** „Twoja treść `wiki/` została zbudowana bez
> `kb_schema_version` (lub ze starszą wersją). Czy mam też zaktualizować
> wszystkie foldery i dane związane z wiki do nowego standardu?”
Jeśli powiesz tak, agent:
- dodaje wszelkie brakujące elementy szkieletu (np. `wiki/graph/index.md`,
który nigdy nie istniał, jeśli twoja KB poprzedza funkcję grafu),
- uzupełnia brakujący frontmatter na istniejących stronach — `tldr`,
`confidence`, `quality`, `retention` i tak dalej — **bez przepisywania
czegokolwiek z twojego tekstu**; dodawana jest tylko struktura i
metadane, nigdy treść merytoryczna strony,
- potwierdza z tobą, zanim przypisze `type` do jakiejkolwiek strony, gdzie
nie jest to oczywiste,
- loguje każdą dotkniętą stronę w `wiki/log.md` jako wpis migracyjny, żeby
było jasne, że zmiana była strukturalna, a nie nową wiedzą,
- i podnosi `kb_schema_version`, gdy skończy.
Jeśli powiesz nie, agent nie dotknie niczego pod `wiki/` — nawet
`kb_schema_version` — więc następnym razem, gdy to uruchomisz, nadal
zostanie to poprawnie oflagowane jako opóźnione, zamiast po cichu uznane
za załatwione. Te dwie decyzje (warstwa szablonu, treść wiki) są
niezależne: możesz zaakceptować jedną i odrzucić drugą.
Podobnie jak Ingest i Lint, na koniec pojawia się przypomnienie o
przejrzeniu wyniku i uruchomieniu „sync changes” względem *twojego
własnego* `origin` — repozytorium szablonu, z którym właśnie porównano,
jest zwykle osobnym zdalnym repozytorium dla każdej KB innej niż własna
kopia robocza projektu szablonu. Skill: `.agents/skills/ckb-upgrade/SKILL.md`.
---
## 6. Przykłady użycia
### Zadawanie pytań
Zapytaj zwykłym językiem:
> „Co wiemy o ryzyku migracji w Q3?”
Agent najpierw czyta `wiki/index.md`, żeby znaleźć odpowiednie strony. Jeśli
istnieje pasujący zakres projektu pod `wiki/projects/`, przeszukuje najpierw
ten zakres. Potem uruchamia `retrieve_candidates.py`, który zbiera sygnały dokładnych
dopasowań, `tldr`, zakresu projektu, grafu i zaufania w jeden połączony
ranking, rozszerza kontekst wokół dopasowanych sekcji, przechodzi po grafie
wiedzy w poszukiwaniu powiązanych faktów i sięga do `linked/`/`libs/`, jeśli
lokalna wiki nic nie ma.
Dostajesz odpowiedź opartą na tym, co faktycznie zostało spisane, a nie na
domysłach.
Dwa szczegóły mają znaczenie dla użytkownika:
- Przeszukuje też `raw/inbox/`. Materiał wrzucony dziś rano i jeszcze
niezingestowany nadal może odpowiedzieć na twoje pytanie. Agent powie ci,
kiedy odpowiedź pochodzi z niezingestowanego materiału, co jednocześnie
sygnalizuje, że „Ingest" jest zaległy.
- Odpowiedzi noszą własne zastrzeżenia. Jeśli strona stojąca za odpowiedzią
przekroczyła okno świeżości, ma niską pewność albo została przeczytana z
zapisanego indeksu konektora zamiast z żywego źródła, odpowiedź mówi o tym
obok danego twierdzenia. Jeśli dwie strony są ze sobą sprzeczne, a żadna nie
została jeszcze oznaczona jako zastąpiona, też o tym usłyszysz. Nie
trzeba samodzielnie czytać frontmatteru, żeby wiedzieć, na ile ufać
otrzymanej odpowiedzi.
Gdy odpowiedź wymagała prawdziwej pracy (złożenia kilku stron, ponownego
przeczytania źródła), agent raz proponuje jej zachowanie. Jeśli się zgodzisz,
trafia do `outputs/answers/<data>_<pytanie>.md` razem ze źródłami, na których
się opiera (ze skrótami, więc lint powie ci, gdy się zmienią), i sekcją
`## Gaps` z tym, na co KB nie umiała odpowiedzieć. Gdy później zadasz to samo
pytanie, agent zaproponuje aktualizację zachowanej odpowiedzi zamiast
pisania drugiej. Jeśli odpowiedź zawiera coś, co powinna wiedzieć sama wiki,
agent proponuje wprowadzenie jej z powrotem. Oznacza to zwykły ingest, z tym
samym meldunkiem, więc zachowana odpowiedź nigdy sama nie zmienia wiki.
Fragmenty prywatne (`<private>`) nigdy nie są cytowane w odpowiedzi.
Gdy nadal nie ma odpowiedzi, agent powinien powiedzieć, czego brakuje, i albo
dodać/zaproponować krótki wpis w `wiki/query-gaps.md`, albo zasugerować
najmniejsze źródło do wrzucenia do `raw/inbox/`.
### Pytanie, kto się na czymś zna
> „Kto zna się na ścieżce przywracania checkpointów?" / „Kto jest właścicielem
> usługi billingowej?"
Na te pytania odpowiada bezpośrednio graf wiedzy, a nie wyszukiwanie nazwisk po
słowach kluczowych. Ingest zapisuje krawędź eksperctwa lub własności, gdy
materiał źródłowy faktycznie pokazuje, że ktoś odpowiada na pytania w danym
temacie albo ma zadeklarowaną odpowiedzialność za niego — a nie na podstawie
obecności na spotkaniu czy nazwy stanowiska. Jeśli nikt nie ma jeszcze
zapisanej krawędzi, agent wraca do tego, kogo zarchiwizowane źródła pokazują
jako odpowiadającego na tego rodzaju pytania, i mówi ci, że wnioskuje, a nie
raportuje.
### Nauka z wiki
**Szybki test tego, co wiesz** — powiedz:
> „Quiz me on the onboarding process.”
Agent zapyta o liczbę pytań i format (otwarte / jednokrotnego wyboru), a
następnie przeprowadzi cię przez nie jedno po drugim, z natychmiastową
informacją zwrotną i bieżącym wynikiem. Potem nic nie zostaje zapisane — to
jednorazowy sprawdzian. `.agents/skills/ckb-quiz/SKILL.md`.
**Prawdziwy kurs, rozłożony w czasie** — powiedz:
> „Teach me the wiki.” / „Teach me about the supplier onboarding process.”
Pierwsze wywołanie planuje program nauczania: pyta, czy chcesz jedną
sesję czy serię, jak długa ma być każda sesja i jak często, oraz czy
potrzebny jest plik kalendarza `.ics` z przypomnieniami. Następnie dzieli
materiał na porcje wielkości sesji (raczej jedna krótka sesja więcej niż
upychanie materiału) i pokazuje ci plan, zanim cokolwiek zapisze. Później
powiedzenie „next lesson” (lub podobnie) wznawia naukę od miejsca, w którym
się zatrzymała, ucząc za każdym razem inną techniką — pytania sokratejskie,
analogie, przykłady rozwiązane krok po kroku, „naucz mnie z powrotem”,
mnemotechniki — i krótko sprawdzając, co zostało w pamięci, zanim przejdzie
dalej, powtarzając to, co niepewne. Plany i postępy żyją w
`outputs/teaching/<topic>/`. `.agents/skills/ckb-teach-me/SKILL.md`.
**Prowadzona kolejność czytania bez pełnego kursu** — powiedz:
> „Onboard me on the payments integration.” / „Where do I start with X?”
Dostajesz krótki przegląd plus uporządkowaną listę do przeczytania —
najpierw podstawy, potem sam temat, potem to, co się na nim opiera —
zbudowaną przez przejście po grafie wiedzy na zewnątrz. Tylko do odczytu;
nic nie jest zapisywane. `.agents/skills/ckb-onboard-me/SKILL.md`.
### Generowanie dokumentów / dzielenie się wiedzą poza wiki
**Szybki skrót najwyższego poziomu** — powiedz:
> „Give me a project summary.” / „Where do things stand?”
Regeneruje `PROJECT-OVERVIEW.md` w katalogu głównym repozytorium: jedno-
lub dwustronicowy przegląd, bieżący stan, otwarte działania ze statusem,
ryzyka i założenia — w całości zsyntetyzowane z aktualnej wiki. Jest za
każdym razem nadpisywany w całości, więc zawsze odzwierciedla to, co wiki
mówi *teraz*. `.agents/skills/ckb-project-summary/SKILL.md`.
**Eksport maszynowy dla innych narzędzi** — powiedz:
> „Export the wiki as OKF.”
Tworzy pakiet [Open Knowledge Format](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md)
w `outputs/okf/`, możliwy do skonsumowania przez ogólne narzędzia OKF (np.
wizualizator grafu), bez potrzeby rozumienia bogatszego, własnego schematu
tej wiki. `.agents/skills/ckb-export-okf/SKILL.md`.
**Czytelna dla człowieka strona dokumentacji** — powiedz:
> „Export the wiki to Starlight.” / „Build a docs site from the wiki.”
Tworzy gotową do uruchomienia stronę Astro + Starlight w
`outputs/starlight/` — prawdziwe strony, prawdziwą nawigację, coś, co
możesz hostować i dać komuś, kto nigdy nie widział wiki.
`.agents/skills/ckb-export-starlight/SKILL.md`.
**Dokument, który piszesz regularnie, z szablonu** — powiedz:
> „Prepare a new document using template status-report.” / „New status
> report from the template, for Atlas, last two weeks.”
Szablony leżą w `templates/`, każdy w jednym pliku Markdown. Nagłówki
nadają dokumentowi kształt, a komentarz HTML pod każdym nagłówkiem mówi
agentowi, co ma tam trafić: „zapytaj użytkownika”, „weź to ze strony
projektu w wiki”, „trzy zdania, bez punktów”. Agent czyta szablon, zadaje
ci wszystkie pytania naraz, resztę bierze z wiki i zapisuje gotowy dokument
w `outputs/documents/`. Czego nie znalazł, zostawia w pliku jako linię
`TODO:`, nigdy nie zmyśla. W zestawie jest jeden przykład,
`templates/status-report.md`, a `templates/README.md` opisuje format na
jednej stronie. Powiedz „make a template for a handover note”, a agent
przygotuje szkic szablonu do twojej edycji.
`.agents/skills/ckb-document/SKILL.md`.
**Dokument Word, prezentacja lub PDF z zawartości wiki** — nie ma
dedykowanego skilla do tego, ale to normalna prośba:
> „Turn the wiki page on our pricing model into a one-page Word doc I can
> send to legal.”
Agent czyta odpowiednie strony wiki i używa swoich ogólnych umiejętności
tworzenia dokumentów (`docx`, `pptx`, `pdf`), aby wytworzyć plik — wiki
pozostaje źródłem prawdy, dokument jest jednorazowym, pochodnym
artefaktem.
### Dodawanie informacji
W pełni opisane w [§2](#2-dodawanie-wiedzy) — w skrócie: wrzuć materiał do
`raw/inbox/` i powiedz „Ingest”, albo powiedz agentowi w
rozmowie, jeśli to wystarczająco krótkie, żeby podać wprost.
### Twój profil i lekcje
Powiedz „set up my profile”, a agent zada do trzech pytań: o twoją rolę, o to,
jak ma z tobą pracować, i o to, czego zawsze lub nigdy nie robić. Odpowiedzi
trafiają do `workload/profiles/<twoje-imię>.md`. Od tej pory każda sesja, którą
zaczynasz, wypisuje twój profil w podsumowaniu agenta. Profile innych osób nie
są dla ciebie wczytywane. Plik jest commitowany, więc trzymaj w nim tylko
preferencje robocze, którymi podzieliłbyś się z zespołem.
Twoje preferencje nigdy nie są ważniejsze od zasad KB. Najpierw `AGENTS.md`,
potem `## Rules` projektu, a resztę uzupełnia twój profil.
Gdy agent się pomyli, możesz utrwalić poprawkę: „remember this: always cite
the runbook for retry numbers” albo „lesson: …”. Agent pyta, czy lekcja jest
twoja, czy dla wszystkich:
- **Twoja** trafia do twojego profilu.
- **Dla wszystkich** trafia do `wiki/lessons.md` i czeka na przegląd drugiej
osoby. Najbliższa sesja każdej innej osoby wymieni ją jako nową.
Nic nie staje się lekcją, jeśli o to nie poprosisz. Lekcja, która ma zawsze
obowiązywać wszystkich, należy do `AGENTS.md`; agent to zasugeruje, zamiast go
edytować. Skill: `.agents/skills/ckb-profile/SKILL.md`.
### Zapisywanie rozmowy
Każda nowa sesja dostaje tytuł, który agent sam wybiera na podstawie
twojej pierwszej wiadomości (albo ten, który w niej podasz: „title: …”).
Nikt cię nie pyta; pierwsza odpowiedź zaczyna się od jednej
linijki z tytułem i przypomnieniem, że „rename this conversation to X” go
zmienia. Tytuł nadaje nazwę zapisanemu transkryptowi i blokowi sesji w
`workload/`. Jeśli ta linijka ci przeszkadza, powiedz „stop telling me the
title” — agent przestawi `announce_title: false` w bloku `conversations:`
w `ckb.yaml`; tytuł nadal jest ustawiany, tylko nie jest ogłaszany.
Powiedz „save this conversation”, a agent skopiuje transkrypt sesji do
`raw/saved-conversations/<RRRR-MM-DD>/` — oryginalny plik JSONL, który
przechowuje Claude Code, bajt w bajt, plus czytelną wersję `.md` tej samej
wymiany zdań (twoje wiadomości i odpowiedzi agenta dosłownie, wywołania
narzędzi jako jednolinijkowe notatki, wyniki narzędzi skrócone, prywatne
rozumowanie agenta pominięte). `raw/saved-conversations/index.md` wymienia
wszystko, co zapisano. Wcześniejsze sesje tego samego projektu też można
zapisać: poproś, a agent wyświetli listę do wyboru.
Zapisane rozmowy są celowo **poza** wiki. Na pytania agent nadal odpowiada
wyłącznie z `wiki/`, `linked/` i `libs/` — transkrypt sam z siebie nigdy
nie staje się dowodem. Możesz natomiast pytać o same rozmowy: „czy
rozmawialiśmy o przełączeniu rozliczeń”, „co mówiliśmy o nazewnictwie w
zeszłym tygodniu”, „jaka była moja prośba w sprawie eksportu”. Agent przeszukuje
zapisane pliki `.md` i cytuje dokładną wymianę zdań wraz z datą.
Jeśli wolisz, żeby agent nie pytał, powiedz „save conversations automatically”:
agent przestawi `autosave: true` w bloku `conversations:` w `ckb.yaml` i od
tej pory każda sesja jest zapisywana na końcu bez pytania. „Turn off
autosave” przestawia z powrotem. Przełącznik jest commitowany z
repozytorium, więc dotyczy wszystkich pracujących w tej KB. Ponieważ jest to
reguła, którą agent wykonuje na końcu sesji, sesja przerwana w połowie tury
zostałaby pominięta — dlatego funkcja ma też połowę per maszyna: hook
`Stop` Claude Code w `.claude/settings.local.json` (ignorowanym przez gita),
który ponownie zapisuje transkrypt po każdej turze. Agent nigdy nie
instaluje go samodzielnie. Przy włączonym autozapisie kontrola na starcie
sesji zauważa maszynę, na której hooka brakuje (albo taką, na której
autozapis wyłączono, a hook wciąż jest), i pyta raz, czy zmienić
konfigurację tej maszyny; zmianę wprowadza tylko po twojej zgodzie. Każda
maszyna otwierająca repozytorium zostaje zapytana raz.
Jeśli rozmowa zawiera wiedzę, która należy do wiki, skopiuj jej `.md` do
`raw/inbox/` i powiedz „Ingest” — kopię robisz ty, więc nic nie trafia do
wiki bez twojego wyboru. Pamiętaj, że transkrypt jest dosłowny: zawiera
wszystko, co agent wypisał w trakcie sesji (zawartość plików, wyniki
poleceń), i staje się śledzonym plikiem w repozytorium.
Skill: `.agents/skills/ckb-add-conversation/SKILL.md`.
### Indeksowanie zewnętrznego źródła
Powiedz:
> „Index external sources.” (lub „index libs”, „refresh the external
> index”)
To przeszukuje każdy `libs/<name>/`, który ma `source.yaml` (zobacz
[§1](#budowanie-na-bazie-cudzej-wiki)), i buduje krótki indeks tego, co
znajdzie — po jednym wpisie na dokument, plus stronę przeglądową — w
całości wewnątrz tego samego folderu `libs/<name>/`. Niczego pod `wiki/`
nie dotyka.
Przykład:
> *Tworzysz `libs/finance-reports/source.yaml`:*
> ```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
> ```
> *potem mówisz „Index external sources.”*
>
> Agent łączy się, korzystając z tego, co jest dostępne w danej sesji (w
> tym przypadku podłączonego narzędzia Microsoft 365), listuje dokumenty w
> tym folderze, czyta wystarczająco dużo z każdego, aby napisać krótkie
> podsumowanie, i tworzy `libs/finance-reports/index.md` (przegląd źródła)
> plus jedną stronę na dokument w `libs/finance-reports/entities/`,
> połączone krzyżowo przez `libs/finance-reports/graph/edges.json`. Loguje
> wszystko w `libs/finance-reports/log.md`, dzienniku odrębnym od
> `wiki/log.md`, ponieważ ten indeks jest ograniczony do jednego
> konektora, a nie wmieszany w twoją główną wiki. Na koniec przypomina o
> przejrzeniu wyniku i powiedzeniu „sync changes”, gdy wynik będzie ci
> odpowiadał.
Jeśli konektor wymaga autoryzacji (np. połączenie z SharePoint lub Google
Drive, które nie jest jeszcze skonfigurowane), agent mówi, który to i gdzie
go autoryzować, a potem kontynuuje z innymi skonfigurowanymi źródłami,
zamiast zatrzymywać cały przebieg. Uruchom „index external sources”
ponownie w każdej chwili, gdy źródło się zmieni — odświeża istniejące
wpisy w miejscu, zamiast je duplikować, i nigdy nie usuwa strony dla
dokumentu, który zniknął ze źródła (zamiast tego oflagowuje ją, żeby
kolejny przebieg „Lint” zarchiwizował ją naturalnie).
Skill: `.agents/skills/ckb-index-external/SKILL.md`.
**Kto może go budować i gdzie jest współdzielony.** Domyślnie nikt nie ma
dostępu do zapisu w źródle typu konektor, dopóki tego nie zadeklaruje — to
chroni zespół dziesięciu osób przed redundantnym skanowaniem tego samego
folderu SharePoint. Powiedz:
> „Make me the admin for finance-reports.”
To zapisuje osobisty `libs/finance-reports/source.local.yaml` z
`access: write` — nigdy niecommitowany, nigdy niewidoczny dla
współpracowników. Każdy bez tego pliku jest tylko-do-odczytu dla tego
źródła: jeśli powie „index external sources”, agent w jego imieniu w
ogóle nie dotknie żywego konektora. Zgłosi, co już
zaindeksowano (albo powie wprost, że nic jeszcze nie zaindeksowano i kogo
o to zapytać).
Jeśli zespół finansowy chce, żeby wszyscy czytali *ten sam* indeks, a nie
każdy utrzymywał własną lokalną kopię w swojej własnej KB, administrator
dodaje blok `index:` do współdzielonego `source.yaml`:
```yaml
index:
store: git
location: "https://github.com/finance-team/index-cache.git"
# ref: main — opcjonalnie: przypina branch, tag albo podścieżkę w tym miejscu
```
Za pierwszym razem, gdy ktokolwiek uruchomi „index external sources” po
dodaniu tego bloku, `https://github.com/finance-team/index-cache.git` jest
puste. To oczekiwane, nie błąd. Każde uruchomienie sprawdza je najpierw:
użytkownicy tylko-do-odczytu zobaczą „nic jeszcze nie opublikowano, zapytaj
administratora”, a uruchomienie administratora je tworzy, bo uruchomienie
z dostępem do zapisu zawsze przebudowuje indeks z żywego konektora i
wypycha wynik do tej lokalizacji, niezależnie od tego, czy coś tam
wcześniej było. Od tego momentu, kiedy *ktokolwiek* powie „index external
sources”, agent najpierw pobiera to, co już zostało opublikowane.
Użytkownicy tylko-do-odczytu na tym kończą; administrator dodatkowo
przebudowuje indeks z żywego konektora i wypycha odświeżoną wersję do tej
samej lokalizacji, żeby kolejne pobranie innej osoby ją uwzględniło. Pomiń
blok `index:` (najprostsza konfiguracja, właściwy domyślny wybór dla
jednego małego zespołu), a indeks leży bezpośrednio wewnątrz
`libs/finance-reports/` we własnym repozytorium tej KB, współdzielony w
normalny sposób przez „sync changes”, dokładnie jak w prostym przykładzie
powyżej.
### Dodawanie opcjonalnego modułu
Niektóre możliwości mają sens tylko w części baz wiedzy, dlatego są
dostarczane jako **moduły** w `.agents/modules/`: obecne w każdej kopii,
nieaktywne, dopóki ich nie zainstalujesz. Powiedz:
- **„What modules are available”**: lista modułów z informacją, czy są
zainstalowane.
- **„Install the \<name\> module”**: sprawdza, czego moduł potrzebuje, mówi
ci o tym przed jakimkolwiek zapisem, a potem dodaje jego skille, foldery i
ustawienia. Instalacja jest zapisana w `ckb.yaml`.
- **„Uninstall the \<name\> module”**: usuwa jego skille i ustawienia. Twoja
treść zostaje: strony wiki, które utworzył, klony w `src/`, specyfikacje.
| Moduł | Do czego służy | Przewodnik |
|---|---|---|
| `software` | Baza dokumentuje tworzone oprogramowanie: repozytoria jako ignorowane klony w `src/`, kod mapowany na encje wiki, specyfikacje z OpenSpec | [OPENSPEC.pl.md](OPENSPEC.pl.md) · [README modułu](../.agents/modules/software/README.pl.md) |
| `mcp` | Korzystanie z bazy w aplikacjach Claude (web/desktop/mobile), Claude Code lub innym agencie przez serwer MCP: wyszukiwanie, odczyt, dodawanie materiału, cofanie źle skierowanego zgłoszenia. Można podłączyć kilka baz naraz | [MCP.pl.md](MCP.pl.md) · [README modułu](../.agents/modules/mcp/README.pl.md) |
Skill: `.agents/skills/ckb-module/SKILL.md`.
---
## 7. Co jest generowane przez agenta, a co możesz edytować
Krótka wersja: **lokalna `wiki/` zawsze wygrywa** w kaskadzie, co oznacza,
że to *twoja* wiki — nic nie blokuje ci jej bezpośredniej edycji. „Zarządzane przez agenta” poniżej oznacza, że agent traktuje się
jako odpowiedzialnego za utrzymanie tej treści *strukturalnie* poprawną
(frontmatter, indeks, dziennik, graf) — a nie że nie wolno ci jej dotykać.
Jeśli ręcznie edytujesz stronę wiki, dobrą praktyką jest uruchomienie
potem „Lint”, żeby indeks/dziennik/graf pozostały spójne z wprowadzonymi
zmianami.
Jest jeden wyjątek działający w drugą stronę. Na każdej stronie, którą agent
*regeneruje* — indeks konektora, mapa kodu — wszystko, co napiszesz, zwykle
ginie przy następnej przebudowie. Dlatego każda taka strona kończy się sekcją
`## Notes`, której żaden skill nigdy nie tknie:
```markdown
## Notes
<!-- Twoje. Żaden skill tego nie nadpisuje. -->
```
Pisz tam, co chcesz — że ten dokument jest nieaktualny, że osoba w nim
wymieniona już nie pracuje, kogo naprawdę zapytać. Treść jest przenoszona
przez przebudowy co do bajtu. Wszystko, co napiszesz *powyżej* tego nagłówka
na stronie generowanej, zostanie nadpisane.
| Lokalizacja | Kto zwykle to zapisuje | Uwagi |
|---|---|---|
| `raw/inbox/`, luźne pliki w `raw/` | **Tylko ty** | Agent tylko czyta, archiwizuje i przenosi rzeczy tutaj — nigdy nie tworzy treści w `raw/` sam. |
| `raw/archive/<data>/` | Agent | Automatycznie zarchiwizowana kopia tego, co trafiło do `raw/inbox/`, uporządkowana według daty ingestu. Nie umieszczaj tu plików ręcznie — pozwól, żeby zrobił to Ingest, tak by data i powiązanie z wpisem w dzienniku były poprawne. |
| `linked/<name>/` | **Ty** (tworzysz dowiązanie symboliczne) | Wskazuje na rzeczywiste pliki innej KB, które żyją i są edytowane *w tamtym repozytorium* — nigdy tutaj. Agent nigdy nie może zapisywać wewnątrz `linked/`. |
| `libs/<name>/` (kopia git, bez `source.yaml`) | **Ty** (robisz `git clone`) | Zamrożona kopia zewnętrznej KB. Aktualizujesz ją, ponownie pobierając to repozytorium samodzielnie, a nie ręcznie edytując pliki tutaj. Agent nigdy nie może zapisywać wewnątrz niej. |
| `libs/<name>/source.yaml` (konektor) | **Tylko ty** | Deklaruje konektor, lokalizację, opcjonalnie jak często ma być odświeżany (`refresh_interval_days:`) i opcjonalnie gdzie znajduje się współdzielony/wcześniej zbudowany indeks (`index:`). Agent go czyta, ale nigdy nie zapisuje — tak jak wszystko inne nadrzędne. |
| `libs/<name>/source.local.yaml` (konektor) | **Ty** (albo agent, tylko gdy wyraźnie poprosisz o zostanie/przestanie bycia administratorem tego źródła) | Osobiste, per-komputer ustawienie `access: write`/`read` — nigdy niecommitowane, nigdy niewidoczne dla innych. Brak = tylko do odczytu, domyślnie. |
| `libs/<name>/{index.md,entities/,graph/,log.md}` (konektor) | Generowane przez agenta, **możesz swobodnie edytować** | Własny indeks agenta dla tego jednego źródła konektora, budowany/odświeżany przez „Index external sources” — ale tylko jeśli masz lokalnie `access: write`; użytkownicy tylko-do-odczytu dostają pobraną kopię. Strukturalnie ta sama zasada jak przy wierszu `wiki/` poniżej — śmiało popraw wpis ręcznie, a potem uruchom „Lint” (teraz sprawdza też indeksy oparte na konektorach, respektując ten sam podział odczyt/zapis). Ograniczone wyłącznie do tego konektora; nigdy nie wmieszane w `wiki/`. **Przebudowę przetrwa tylko `## Notes`** — trzymaj tam wszystko, co chcesz zachować. |
| `wiki/decisions/` | Generowane przez agenta, **edytuj ostrożnie** | Mechanicznie tak samo jak reszta `wiki/`, ale te strony są z założenia tylko do dopisywania: popraw swobodnie literówkę czy źle przypisane nazwisko, ale nie przepisuj kontekstu ani uzasadnienia decyzji pod późniejszy pogląd — zapisz zamiast tego decyzję zastępującą, żeby historia przetrwała. |
| `wiki/` (strony, `index.md`, `overview.md`, `log.md`, `error-book.md`, `entities/`, `graph/`) | Generowane przez agenta, **możesz swobodnie edytować** | To jedyne miejsce, w którym zarówno agent zapisuje, jak i spodziewa się, że ty też możesz. Śmiało popraw stronę ręcznie — zachowaj tylko pola frontmatteru (lub zaktualizuj `last_updated`) i uruchom potem Lint, jeśli zmiana dotyczy czegoś, do czego odwołuje się indeks/graf/dziennik. |
| `outputs/okf/`, `outputs/starlight/` | Agent, **w pełni regenerowane** | Nie edytuj ręcznie — to zignorowane przez git artefakty budowania, cicho nadpisywane przy każdym kolejnym eksporcie. Jeśli coś jest nie tak, popraw stronę wiki, z której to pochodzi, i wyeksportuj ponownie. |
| `outputs/teaching/<topic>/` | Agent, stan półtrwały | `plan.md`/`progress.md`, które skill do nauczania czyta i zapisuje między sesjami. Możesz je oglądać kiedy chcesz; ręczna edycja jest możliwa, ale może pomieszać śledzenie „co dalej” — bezpieczniej powiedzieć agentowi, co chcesz zmienić, i pozwolić mu zaktualizować pliki. |
| `PROJECT-OVERVIEW.md` (katalog główny) | Agent, **w pełni regenerowany** | Nadpisywany w całości za każdym razem, gdy poprosisz o podsumowanie projektu. Nie edytuj go ręcznie — edytuj strony wiki, z których jest syntetyzowany, a potem zregeneruj. |
| `ABOUT.md` | **Ty** | Do czego służy ta KB: cel, odbiorcy, zakres, właściciele, poufność, język stron. README do niego linkuje. Agent go czyta, przy ingeście sprawdza nowy materiał względem zakresu i nigdy go nie edytuje bez twojej prośby; aktualizacje i reset go nie ruszają. `wiki/overview.md` to podsumowanie agenta tego, co KB faktycznie zawiera. |
| `templates/` | **Ty** | Szablony dokumentów: nagłówki plus komentarz pod każdą sekcją mówiący, co ma tam trafić i skąd. Agent je czyta, a nowy zapisuje tylko na twoją prośbę. Nic nie regeneruje ani nie resetuje tego katalogu. Zacznij od `templates/status-report.md`. |
| `outputs/documents/` | Agent (jeden plik na prośbę), **możesz edytować** | Dokumenty przygotowane z szablonu. Śledzone w gicie i nigdy nie nadpisywane przez kolejne uruchomienie (powtórzona nazwa dostaje `-2`, `-3`). Edytuj je swobodnie; frontmatter zapisuje, z jakiego szablonu i z jakich stron wiki powstały. |
| `workload/YYYY-MM-DD_<autor>_summary.md` | Agent (dopisywane co sesję) | Bieżący dziennik tego, co działo się każdego dnia, jeden plik na osobę, więc współdzielone repozytorium zapisuje, kto co zrobił, i nigdy nie konfliktuje w tym miejscu. Autor to tożsamość gita sesji. Możesz go swobodnie czytać, edytować lub skracać — to dziennik dla ciągłości, a nie plik krytyczny dla działania systemu. |
| `workload/ingest-reports/` | Agent (jeden plik na ingest) | Co zmienił każdy ingest: przyjęte pliki z `raw/` i miejsce ich archiwizacji, zapisane decyzje, utworzone lub zaktualizowane encje i inne strony, krawędzie grafu oraz to, co nowy materiał potwierdził, rozszerzył lub z czym był sprzeczny. Zapisywany raz i nigdy nie przepisywany — przeczytaj go, aby przejrzeć ingest bez odtwarzania go z logu i diffa. |
| `AGENTS.md` / `CLAUDE.md` | **Ty** (rzadko) | To prompt systemowy, który definiuje zachowanie agenta w tym repozytorium. Edytuj go, jeśli chcesz zmienić globalną zasadę — np. schemat frontmatteru, format logowania czy kontrakt katalogów. Zmiany obowiązują od kolejnej sesji. |
| `.agents/skills/*/SKILL.md` | **Ty** (zaawansowane/opcjonalne) | Każdy plik definiuje jedną możliwość na żądanie. Możesz tworzyć nowe albo edytować istniejące, wzorując się na tych, które już tu są — to nie jest wymagane do normalnego użytku, ale nic ci w tym nie przeszkadza. |
| `LICENSE`, `VERSION`, `README*`, `docs/`, `ckb.yaml` | Agent, **możesz edytować** | Część tej samej warstwy szablonu co `AGENTS.md` — utrzymywane w synchronizacji przez `ckb-upgrade`, gdy zaakceptujesz aktualizację szablonu. `ckb-upgrade` zawsze zapyta, zanim dotknie linii praw autorskich w `LICENSE` albo któregokolwiek z tych plików, jeśli twoja lokalna kopia różni się od szablonu — dostosowanie tutaj (np. własna nazwa projektu czy posiadacz licencji) jest oczekiwana, nie jest błędem. |
---
### Gdzie leżą własne decyzje szablonu
`docs/decisions/` przechowuje zapisy projektowe szablonu (D-0001, D-0002…) w
tym samym formacie co `wiki/decisions/`, ale jako część warstwy szablonu:
skille i dokumentacja się na nie powołują, więc muszą przetrwać `ckb-reset` i
podróżować z `ckb-upgrade`. Decyzje twojej KB nadal trafiają do
`wiki/decisions/` przez „record a decision” — nigdy tutaj.
### Sprawdzanie wydania szablonu
`tests/smoke.sh` uruchamia deterministyczne skrypty (`lint_report.py`,
`retrieve_candidates.py`, `save_conversation.py`) na fixture'ach w
`tests/fixtures/` i porównuje wynik z `tests/expected/`. Uruchom go przed
scaleniem czegokolwiek do `test` lub `main`; z `--update` po zamierzonej
zmianie wyjścia skryptów. Folder `tests/` istnieje tylko w repo szablonu:
`ckb-init` go nie kopiuje, a `ckb-upgrade` go nie dostarcza, więc baza
wiedzy nigdy go nie zawiera.
## 8. Szybki przegląd
| Powiedz... | Co się dzieje | Skill |
|---|---|---|
| „Set up a new wiki like this one in \<folder\>” | Zakłada świeżą, pustą KB z tym schematem | `ckb-init` |
| „Pull the ckb repo into \<folder\> and set up the wiki” | Klonuje repozytorium szablonu do katalogu roboczego, a potem zakłada z niego pustą KB | `ckb-init` |
| „Ingest” / „Update the wiki” | Przetwarza `raw/inbox/` na ustrukturyzowane strony `wiki/` | `ckb-ingest` |
| „Zapisz decyzję: ...” / „zdecydowaliśmy ...” | Zapisuje numerowany rekord decyzji pod `wiki/decisions/` | `ckb-decide` |
| „Co zdecydowaliśmy w sprawie X” / „kto zdecydował X” / „co jest otwarte” | Odpowiada z zapisów decyzji, z autorem, datą i statusem | `ckb-decide` |
| „Lint” | Sprawdza kondycję wiki, automatycznie naprawia to, co bezpiecznie może | `ckb-lint` |
| „Zresetuj wiki” / „Zrób z tego czysty szablon” | **Destrukcyjne.** Usuwa zgromadzoną wiedzę i odtwarza pusty szkielet, po inwentarzu i potwierdzeniu wpisaną frazą | `ckb-reset` |
| „Sync changes” / „Sync with git” | Commituje, pobiera, rozwiązuje konflikty, wypycha do `origin` | `ckb-sync-changes` |
| „Save this conversation” | Kopiuje transkrypt sesji (JSONL + czytelne `.md`) do `raw/saved-conversations/<data>/`; poza wyszukiwaniem | `ckb-add-conversation` |
| „Did we discuss X” / „What did I tell you about X” | Przeszukuje zapisane rozmowy i cytuje wymianę zdań | `ckb-add-conversation` |
| „Save conversations automatically” / „Turn off autosave” | Przestawia `conversations.autosave` w `ckb.yaml`; po włączeniu każda sesja jest zapisywana na końcu bez pytania | `ckb-add-conversation` |
| „Rename this conversation to X” / „Stop telling me the title” | Ustawia tytuł sesji (używany przez zapisany transkrypt i notatkę workload) / przestawia `conversations.announce_title` | `ckb-add-conversation` |
| „Retract X” / „Undo the ingest of X” / „This went to the wrong KB” | Pokazuje, co zbudowało źródło (strony, twierdzenia, krawędzie), a po twojej zgodzie usuwa dokładnie to; obsługuje prośby z `raw/retractions/` | `ckb-retract` |
| „Set up my profile” / „Remember this: …” / „Lesson: …” | Zapisuje twój profil albo lekcję osobistą lub dla całej KB | `ckb-profile` |
| „What needs review?” / „Mark X as reviewed” | Wypisuje strony draft i needs_update / zapisuje twój przegląd wskazanych stron | `ckb-lint` |
| „Keep this answer” | Zapisuje ostatnią odpowiedź w `outputs/answers/` razem ze źródłami i lukami | `ckb-retrieve` |
| „Ingest in batch” / „Ingest, no check-in” | Ingestuje bez zatrzymywania się, by najpierw pokazać, jak rozumie każde źródło | `ckb-ingest` |
| „Turn on the session-start hook” / „Show the context budget” | Ustawia `session.start_hook` w `ckb.yaml` i instaluje hook na tej maszynie / pokazuje szacunek tokenów warstwy ładowanej zawsze | `ckb-lint` |
| „Lint every week” / „Index external sources every 30 days, ask me first” | Dodaje rutynę do `ckb.yaml`; zaległe rutyny wykonują się na starcie sesji, po twojej prośbie | `ckb-routine` |
| „List routines” / „Which routines are due” / „Remove the weekly lint” | Pokazuje, sprawdza lub usuwa rutyny | `ckb-routine` |
| „What modules are available” / „Install the mcp module” | Pokazuje lub instaluje opcjonalny moduł; nic w nim nie działa przed instalacją | `ckb-module` |
| „Deploy the MCP server” / „Connect the KB to Claude web” | Prowadzi przez udostępnienie bazy przez serwer MCP i dodanie jej jako konektora (moduł mcp) | `ckb-mcp` |
| „Quiz me on X” | Jednorazowy, punktowany sprawdzian wiedzy | `ckb-quiz` |
| „Teach me the wiki” / „Teach me about X” | Planuje i prowadzi rozłożony w czasie kurs ze śledzeniem postępu | `ckb-teach-me` |
| „Onboard me on X” / „Where do I start with X” | Krótka, prowadzona kolejność czytania po grafie | `ckb-onboard-me` |
| „Give me a project summary” | Regeneruje `PROJECT-OVERVIEW.md` | `ckb-project-summary` |
| „Prepare a new document using template X” / „List templates” / „Make a template for X” | Wypełnia szablon z `templates/` twoimi odpowiedziami i treścią wiki, zapisuje go w `outputs/documents/`; wypisuje lub przygotowuje szablony | `ckb-document` |
| „Export the wiki as OKF” | Eksport maszynowy w `outputs/okf/` | `ckb-export-okf` |
| „Export the wiki to Starlight” | Czytelna dla człowieka strona dokumentacji w `outputs/starlight/` | `ckb-export-starlight` |
| „Upgrade the wiki” / „Check for a newer template version” | Sprawdza wersje szablonu i schematu wiki względem kanonicznego repozytorium, aktualizuje to, co zaakceptujesz | `ckb-upgrade` |
| „Index external sources” / „Index libs” | Buduje/odświeża samodzielny indeks dla każdego `libs/<name>/` opartego na konektorze | `ckb-index-external` |
| Po prostu zadaj pytanie | Odpowiedź z wiki, przy użyciu kaskady indeks/TLDR/graf, z zastrzeżeniami gdy źródło jest nieaktualne lub sprzeczne | `ckb-retrieve` |
| „Kto wie o X" / „Kto jest właścicielem X" | Odpowiedź z krawędzi eksperctwa/własności w grafie | `ckb-retrieve` |