From 28df42cbee54877669b15a0d13ff8df3fd8a7e6c Mon Sep 17 00:00:00 2001 From: oskar Date: Tue, 4 Aug 2026 15:02:06 +0200 Subject: [PATCH] feat(kb): stuby dla katalogow z kodem bez README (8 plikow) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Rozstrzygniecie 5: katalogi z kodem, ktore nie mialy README, dostaja stub (frontmatter + stub: true + opis jednozdaniowy). NIE pisana pelna dokumentacja. kb/services/: control-plane, node-agent, brain-watchdog, node-exporter, job-gmail-bulk-import, pkg-kb-mail, pkg-kb-retrieval. Kazdy stub podaje zrodlo opisu (service.yaml / docstring / CLAUDE.md / pyproject.toml). Dla gmail-bulk-import i kb-retrieval zrodla brak — stub mowi o tym wprost zamiast zmyslac opis. Dodatkowo kb/subsystems/repo-operating-contract.md — wskaznik na CLAUDE.md (rozstrzygniecie 4). CLAUDE.md zostaje w korzeniu jako zywa konfiguracja narzedzia; kb-doc niesie pole contradicts: brak katalogow services/joplin, services/outline, services/ai-cluster deklarowanych w sekcji "Repo-managed services on VPS". Kontekst PR2 feat/vps-service-migration, swiadomie nienaprawiane. Co-Authored-By: Claude Opus 5 (1M context) --- kb/services/brain-watchdog.md | 17 ++++++++++++ kb/services/control-plane.md | 17 ++++++++++++ kb/services/job-gmail-bulk-import.md | 17 ++++++++++++ kb/services/node-agent.md | 17 ++++++++++++ kb/services/node-exporter.md | 17 ++++++++++++ kb/services/pkg-kb-mail.md | 17 ++++++++++++ kb/services/pkg-kb-retrieval.md | 17 ++++++++++++ kb/subsystems/repo-operating-contract.md | 34 ++++++++++++++++++++++++ 8 files changed, 153 insertions(+) create mode 100644 kb/services/brain-watchdog.md create mode 100644 kb/services/control-plane.md create mode 100644 kb/services/job-gmail-bulk-import.md create mode 100644 kb/services/node-agent.md create mode 100644 kb/services/node-exporter.md create mode 100644 kb/services/pkg-kb-mail.md create mode 100644 kb/services/pkg-kb-retrieval.md create mode 100644 kb/subsystems/repo-operating-contract.md diff --git a/kb/services/brain-watchdog.md b/kb/services/brain-watchdog.md new file mode 100644 index 0000000..ec477f4 --- /dev/null +++ b/kb/services/brain-watchdog.md @@ -0,0 +1,17 @@ +--- +okf: "0.1" +type: service +visibility: private +status: active +updated: 2026-08-03 +stub: true +links: [] +--- + +# brain-watchdog + +Zewnetrzny watchdog control-plane na VPS: odpytuje /summary po Tailscale i alertuje przez Telegram Bot API, bez zaleznosci od samego control-plane. + +> **Stub.** Katalog z kodem nie ma README — ten dokument powstal automatycznie w migracji do KB OKF (etap 2). Opis jednozdaniowy wyciagniety z: services/brain-watchdog/service.yaml, pole `description`. Pelna dokumentacja do napisania. + +**Kod:** `services/brain-watchdog/ (service.yaml, src/, healthcheck.sh)` diff --git a/kb/services/control-plane.md b/kb/services/control-plane.md new file mode 100644 index 0000000..c0c479c --- /dev/null +++ b/kb/services/control-plane.md @@ -0,0 +1,17 @@ +--- +okf: "0.1" +type: service +visibility: private +status: active +updated: 2026-08-03 +stub: true +links: [] +--- + +# control-plane + +Observer + Supervisor + Executor + Operator UI na VPS — synteza world state z eventow i dyspozycja akcji. + +> **Stub.** Katalog z kodem nie ma README — ten dokument powstal automatycznie w migracji do KB OKF (etap 2). Opis jednozdaniowy wyciagniety z: CLAUDE.md, sekcja `Agent System Architecture` (pkt 2-5). Pelna dokumentacja do napisania. + +**Kod:** `services/control-plane/ (src/, docker-compose.yml, pyproject.toml)` diff --git a/kb/services/job-gmail-bulk-import.md b/kb/services/job-gmail-bulk-import.md new file mode 100644 index 0000000..95a0be3 --- /dev/null +++ b/kb/services/job-gmail-bulk-import.md @@ -0,0 +1,17 @@ +--- +okf: "0.1" +type: service +visibility: private +status: active +updated: 2026-08-03 +stub: true +links: [] +--- + +# gmail-bulk-import + +Job masowego importu Gmaila do koperty KB (filar mailowy). + +> **Stub.** Katalog z kodem nie ma README — ten dokument powstal automatycznie w migracji do KB OKF (etap 2). Opis jednozdaniowy wyciagniety z: nazwa pakietu w jobs/gmail-bulk-import/pyproject.toml — brak service.yaml i brak docstringu. Pelna dokumentacja do napisania. + +**Kod:** `jobs/gmail-bulk-import/ (src/gmail_bulk_import/, pyproject.toml, tests/)` diff --git a/kb/services/node-agent.md b/kb/services/node-agent.md new file mode 100644 index 0000000..1288f8e --- /dev/null +++ b/kb/services/node-agent.md @@ -0,0 +1,17 @@ +--- +okf: "0.1" +type: service +visibility: private +status: active +updated: 2026-08-03 +stub: true +links: [] +--- + +# node-agent + +Demon monitorujacy zdrowie node'a, uruchamiany na kazdym zarzadzanym wezle; wykonuje `container_restart` z actions/dispatch// przez wlasny docker socket. + +> **Stub.** Katalog z kodem nie ma README — ten dokument powstal automatycznie w migracji do KB OKF (etap 2). Opis jednozdaniowy wyciagniety z: docstring services/node-agent/src/node_agent.py + CLAUDE.md, tabela typow akcji. Pelna dokumentacja do napisania. + +**Kod:** `services/node-agent/ (src/node_agent.py, docker-compose.yml)` diff --git a/kb/services/node-exporter.md b/kb/services/node-exporter.md new file mode 100644 index 0000000..eaaa643 --- /dev/null +++ b/kb/services/node-exporter.md @@ -0,0 +1,17 @@ +--- +okf: "0.1" +type: service +visibility: private +status: active +updated: 2026-08-03 +stub: true +links: [] +--- + +# node_exporter + +Prometheus Node Exporter — wystawia metryki hosta (CPU, pamiec, dysk, siec) do scrapowania; deploy per-host (vps i piha). + +> **Stub.** Katalog z kodem nie ma README — ten dokument powstal automatycznie w migracji do KB OKF (etap 2). Opis jednozdaniowy wyciagniety z: services/node_exporter/service.yaml, pole `description`. Pelna dokumentacja do napisania. + +**Kod:** `services/node_exporter/ (service.yaml, docker-compose.yml)` diff --git a/kb/services/pkg-kb-mail.md b/kb/services/pkg-kb-mail.md new file mode 100644 index 0000000..2a7e454 --- /dev/null +++ b/kb/services/pkg-kb-mail.md @@ -0,0 +1,17 @@ +--- +okf: "0.1" +type: service +visibility: private +status: active +updated: 2026-08-03 +stub: true +links: [] +--- + +# kb-mail + +Biblioteka wspoldzielona: model koperty KB, helpery asyncpg do bazy, append-only archiwum .eml. + +> **Stub.** Katalog z kodem nie ma README — ten dokument powstal automatycznie w migracji do KB OKF (etap 2). Opis jednozdaniowy wyciagniety z: CLAUDE.md, sekcja `Shared Python Libraries (packages/)`. Pelna dokumentacja do napisania. + +**Kod:** `packages/kb-mail/ (src/, pyproject.toml, tests/)` diff --git a/kb/services/pkg-kb-retrieval.md b/kb/services/pkg-kb-retrieval.md new file mode 100644 index 0000000..15e815a --- /dev/null +++ b/kb/services/pkg-kb-retrieval.md @@ -0,0 +1,17 @@ +--- +okf: "0.1" +type: service +visibility: private +status: active +updated: 2026-08-03 +stub: true +links: [] +--- + +# kb-retrieval + +Biblioteka wspoldzielona warstwy retrievalu: embedowanie chunkow (Ollama) i wyszukiwanie. + +> **Stub.** Katalog z kodem nie ma README — ten dokument powstal automatycznie w migracji do KB OKF (etap 2). Opis jednozdaniowy wyciagniety z: eksporty packages/kb-retrieval/src/kb_retrieval/__init__.py — brak service.yaml i brak description w pyproject.toml. Pelna dokumentacja do napisania. + +**Kod:** `packages/kb-retrieval/ (src/kb_retrieval/{embed,retrieval}.py, pyproject.toml)` diff --git a/kb/subsystems/repo-operating-contract.md b/kb/subsystems/repo-operating-contract.md new file mode 100644 index 0000000..695c522 --- /dev/null +++ b/kb/subsystems/repo-operating-contract.md @@ -0,0 +1,34 @@ +--- +okf: "0.1" +type: subsystem +visibility: private +status: active +updated: 2026-08-03 +stub: true +links: [] +contradicts: + - CLAUDE.md "Repo-managed services on VPS" wymienia services/joplin/ — katalog nie istnieje + - CLAUDE.md "Repo-managed services on VPS" wymienia services/outline/ — katalog nie istnieje + - CLAUDE.md "Repo-managed services on VPS" wymienia services/ai-cluster/ — katalog nie istnieje +--- + +# Kontrakt operacyjny repo (CLAUDE.md) + +Zrodlo prawdy o rolach node’ow, ukladzie serwisow, architekturze agentowej, +konwencjach runtime i regulach VPS-a lezy w `CLAUDE.md` w korzeniu repo. + +> **Stub / wskaznik.** `CLAUDE.md` jest zywa konfiguracja narzedzia (czyta ja +> Claude Code przy kazdej sesji) i **zostaje w korzeniu repo** — nie jest +> kopiowana do KB, zeby nie powstala druga, rozjezdzajaca sie wersja. +> Ten dokument istnieje po to, zeby kontrakt byl adresowalny z poziomu KB +> i zeby powiesic na nim pole `contradicts`. + +**Zrodlo:** `../../CLAUDE.md` + +## Znana sprzecznosc: sekcja „Repo-managed services on VPS” + +`CLAUDE.md` deklaruje trzy stacki jako GitOps-managed pod `services//`: +`joplin`, `outline`, `ai-cluster`. **Zadny z tych katalogow nie istnieje w repo.** + +Znany kontekst PR2 `feat/vps-service-migration` — **nie naprawiane w etapie 2** +(migracja do KB jest mechaniczna, bez redakcji tresci).