ckb/MANUAL.pl.md

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

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

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ą całkowicie 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` zamiast tego. Tak czy inaczej
  otrzymujesz tę samą zamrożoną, tylko-do-odczytu kopię; jedyna różnica to
  brak możliwości późniejszego `git pull`, żeby ją odświeżyć — żeby
  zaktualizować, po prostu 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.

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 nawet tam `source.yaml` pozostaje twój do edycji, nigdy agenta.)

---

## 2. Dodawanie wiedzy

To główny sposób, w jaki rośnie wiki. Są dwie drogi:

### 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 „Sync the wiki” / „Update the wiki” — to samo)

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 będziesz zadowolony.

Jeśli `raw/inbox/` jest puste, agent skanuje bezpośrednio `raw/` (nadal
pomijając `raw/archive/`, które zawiera już przetworzoną historię).

Zaimplementowane przez skill `ckb-ingest` —
`.agents/skills/ckb-ingest/SKILL.md`.

### B. Po prostu powiedz agentowi coś w rozmowie

Nie zawsze potrzebujesz pliku. Jeśli powiesz agentowi fakt wart zachowania
— „właściwie to termin przesunął się na wrzesień” — i ma on trwałą
wartość, 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 — zidentyfikuje 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ć.

---

## 3. Utrzymanie porządku

Powiedz, kiedy chcesz (nie ma sztywnego harmonogramu — zrób to po dużym
ingest lub po prostu okresowo):

> „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
- powtarzające się problemy systemowe trafiają do `wiki/error-book.md`

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. Zaimplementowane przez skill `ckb-lint` —
`.agents/skills/ckb-lint/SKILL.md`.

---

## 4. Synchronizacja — z samym sobą i z innymi ludźmi

Są tu dwa zupełnie 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 tym repozytorium źródłowym —
[git.wierzbowa.cloud/michal/ckb](https://git.wierzbowa.cloud/michal/ckb) —
jest kanoniczna, zawsze aktualna kopia. Jeśli nie masz pewności, czy twoja
lokalna kopia jest aktualna, to właśnie tam warto to sprawdzić.

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; będziesz mieć dokładnie te same pliki i możesz od razu
skierować swojego agenta na rozpakowany folder. Jedyne, czego zabraknie,
to skonfigurowany `origin`, więc „sync changes” i „upgrade the wiki” nie
będą miały z czym porównywać ani dokąd wypychać zmian — uruchom `git init`
w rozpakowanym folderze i dodaj powyższy adres jako `origin` (`git remote
add origin https://git.wierzbowa.cloud/michal/ckb`), gdy będziesz gotowy
na te funkcje.

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.
Zaimplementowane przez skill `ckb-sync-changes` —
`.agents/skills/ckb-sync-changes/SKILL.md`.

Agent przypomina o tym również sam, automatycznie: 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 samodzielnie, bez twojej prośby.

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

Sprawdzane są dwie zupełnie 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 po prostu
„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ę — co może być prawdziwym ulepszeniem
szablonu, albo celową customizacją, którą zrobiłeś, np. w `AGENTS.md`).
Zostaniesz zapytany, 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 chciałbyś, żebym
> zaktualizował też 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, co faktycznie napisałeś**; 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, nic pod `wiki/` nie zostanie dotknięte w ogóle — 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. Zaimplementowane przez skill
`ckb-upgrade` — `.agents/skills/ckb-upgrade/SKILL.md`.

---

## 6. Przykłady użycia

### Zadawanie pytań

Po prostu zapytaj, zwykłym językiem:

> „Co wiemy o ryzyku migracji w Q3?”

Agent najpierw czyta `wiki/index.md`, żeby znaleźć odpowiednie strony,
sprawdza ich jednolinijkowy `tldr` przed załadowaniem pełnej strony,
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.

### Nauka z wiki

**Szybki test tego, co wiesz** — powiedz:

> „Quiz me on the onboarding process.”

Zostaniesz zapytany o liczbę pytań i format (otwarte / jednokrotnego
wyboru), a następnie przejdziesz przez nie jedno po drugim, z natychmiastową
informacją zwrotną i bieżącym wynikiem. Nic nie jest zapisywane potem — to
jednorazowy sprawdzian. `.agents/skills/cbk-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
chciałbyś plik kalendarza `.ics` z przypomnieniami. Następnie dzieli
materiał na porcje wielkości sesji (wolą jedną dodatkową krótką sesję niż
upychanie materiału) i pokazuje ci plan, zanim cokolwiek zapisze. Później
powiedzenie „next lesson” (lub podobnie) podejmuje naukę tam, gdzie
skończyłeś, 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 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 po prostu powiedz agentowi w
rozmowie, jeśli to wystarczająco krótkie, żeby podać wprost.

### 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>/`. Nic pod `wiki/` nie
jest dotykane.

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"
> ```
> *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 całkowicie
> 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
> będziesz zadowolony.

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). Zaimplementowane
przez skill `ckb-index-external` —
`.agents/skills/ckb-index-external/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 — nigdy nie jesteś zablokowany przed jej bezpośrednią
edycją. „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 tym, co
zmieniłeś.

| 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 wrzuciłeś 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 i lokalizację. Agent go czyta, ale nigdy nie zapisuje — tak jak wszystko inne nadrzędne. |
| `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 przez „Index external sources”. 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). Ograniczone wyłącznie do tego konektora; nigdy nie wmieszane w `wiki/`. |
| `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 dotknąłeś 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. |
| `workload/YYYY-MM-DD_summary.md` | Agent (dopisywane co sesję) | Bieżący dziennik tego, co działo się każdego dnia. Możesz go swobodnie czytać, edytować lub skracać — to dziennik dla ciągłości, a nie plik krytyczny dla działania systemu. |
| `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*`, `MANUAL*` | 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 — customizacja tutaj (np. własna nazwa projektu czy posiadacz licencji) jest oczekiwana, nie jest błędem. |

---

## 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` |
| „Ingest” / „Sync the wiki” / „Update the wiki” | Przetwarza `raw/inbox/` na ustrukturyzowane strony `wiki/` | `ckb-ingest` |
| „Lint” | Sprawdza kondycję wiki, automatycznie naprawia to, co bezpiecznie może | `ckb-lint` |
| „Sync changes” / „Sync with git” | Commituje, pobiera, rozwiązuje konflikty, wypycha do `origin` | `ckb-sync-changes` |
| „Quiz me on X” | Jednorazowy, punktowany sprawdzian wiedzy | `cbk-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` |
| „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 | — (podstawowy przepływ zapytań) |