From 00a5d62c892799ed9864124f36a1108bed2d0193 Mon Sep 17 00:00:00 2001 From: oskar Date: Tue, 4 Aug 2026 16:25:26 +0200 Subject: [PATCH] fix(kb): README-wskazniki dla services i hosts + wyjatek ken-legacy MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Naprawa kontraktu CLAUDE.md §Service Structure (opcja b). Migracja do KB zabrala README z katalogow serwisow i hostow, przez co 0/26 katalogow services/ spelnialo wymagany layout. Wskazniki przywracaja nawigacje, nie duplikujac tresci. 31 wskaznikow, jednolity format, dokladnie 5 linii: # Dokumentacja: [kb/...](../../kb/...) Opis nie jest pisany od zera — wyciagany z kb-doca: pierwsze pelne zdanie pierwszego akapitu (sklejane z zawinietych linii, ciete tylko tam, gdzie backticki i nawiasy sa zbilansowane), a dla node'ow czlon tytulu H1 po myslniku. Dla ha-mcp opis z H1, bo pierwszy akapit zaczyna sie od markera statusu. Wiodace markery "**Status: ...**" sa zdejmowane. 26 x services//README.md, 5 x hosts//README.md. WYJATEK services/home-assistant/config/ken-legacy/README.md: pelne ostrzezenie "historical archive, do not deploy" przywrocone doslownie z historii (odzyskane z drzewa sprzed migracji) + link do kb-doca. Ostrzezenie musi stac tam, gdzie chroni — w katalogu archiwum, nie tylko w KB. Odwolanie do services/home-assistant/DESIGN.md przepiete na kb/decisions/ha-configs-as-code.md + kb/incidents/2026-07-22-ha-dwie-instancje.md. check_okf.py: POINTER_GLOBS + is_pointer() wykluczaja wskazniki ze scope'u lintu. Wskazniki celowo NIE maja frontmattera OKF — to nawigacja, nie dokumenty KB. Wykluczenie zapisane wprost, zeby poszerzenie SCOPE nie zaczelo ich nagle walidowac. Bez wskaznikow: hosts/chelsty-ha/ i hosts/lustro/ — nie maja dokumentow w kb/nodes/ (luka odnotowana juz w reconie etapu 1). Utworzenie ich wymagaloby napisania nowej dokumentacji, czyli wyjscia poza konwersje. Lint: 190/190 ZGODNE. Weryfikacja 822 plikow: 0 martwych linkow. Co-Authored-By: Claude Opus 5 (1M context) --- hosts/chelsty-infra/README.md | 5 ++++ hosts/piha/README.md | 5 ++++ hosts/saturn/README.md | 5 ++++ hosts/solaria/README.md | 5 ++++ hosts/vps/README.md | 5 ++++ scripts/kb/check_okf.py | 28 ++++++++++++++++--- services/agent-system/README.md | 5 ++++ services/brain-watchdog/README.md | 5 ++++ services/control-plane/README.md | 5 ++++ services/fleet-prometheus/README.md | 5 ++++ services/forgejo/README.md | 5 ++++ services/gokapi/README.md | 5 ++++ services/ha-diag-agent/README.md | 5 ++++ services/ha-mcp/README.md | 5 ++++ services/home-assistant/README.md | 5 ++++ .../config/ken-legacy/README.md | 25 +++++++++++++++++ services/kb-postgres/README.md | 5 ++++ services/kb-query/README.md | 5 ++++ services/llm-gateway/README.md | 5 ++++ services/mosquitto/README.md | 5 ++++ services/narty27/README.md | 5 ++++ services/nextcloud/README.md | 5 ++++ services/node-agent/README.md | 5 ++++ services/node_exporter/README.md | 5 ++++ services/npm/README.md | 5 ++++ services/ollama-piha/README.md | 5 ++++ services/ollama/README.md | 5 ++++ services/paperless-worker/README.md | 5 ++++ services/paperless/README.md | 5 ++++ services/planner-agent/README.md | 5 ++++ services/stability-agent/README.md | 5 ++++ services/vikunja/README.md | 5 ++++ services/zigbee2mqtt/README.md | 5 ++++ 33 files changed, 204 insertions(+), 4 deletions(-) create mode 100644 hosts/chelsty-infra/README.md create mode 100644 hosts/piha/README.md create mode 100644 hosts/saturn/README.md create mode 100644 hosts/solaria/README.md create mode 100644 hosts/vps/README.md create mode 100644 services/agent-system/README.md create mode 100644 services/brain-watchdog/README.md create mode 100644 services/control-plane/README.md create mode 100644 services/fleet-prometheus/README.md create mode 100644 services/forgejo/README.md create mode 100644 services/gokapi/README.md create mode 100644 services/ha-diag-agent/README.md create mode 100644 services/ha-mcp/README.md create mode 100644 services/home-assistant/README.md create mode 100644 services/home-assistant/config/ken-legacy/README.md create mode 100644 services/kb-postgres/README.md create mode 100644 services/kb-query/README.md create mode 100644 services/llm-gateway/README.md create mode 100644 services/mosquitto/README.md create mode 100644 services/narty27/README.md create mode 100644 services/nextcloud/README.md create mode 100644 services/node-agent/README.md create mode 100644 services/node_exporter/README.md create mode 100644 services/npm/README.md create mode 100644 services/ollama-piha/README.md create mode 100644 services/ollama/README.md create mode 100644 services/paperless-worker/README.md create mode 100644 services/paperless/README.md create mode 100644 services/planner-agent/README.md create mode 100644 services/stability-agent/README.md create mode 100644 services/vikunja/README.md create mode 100644 services/zigbee2mqtt/README.md diff --git a/hosts/chelsty-infra/README.md b/hosts/chelsty-infra/README.md new file mode 100644 index 0000000..881f61d --- /dev/null +++ b/hosts/chelsty-infra/README.md @@ -0,0 +1,5 @@ +# CHELSTY-INFRA + +Runtime environment and deployment flow for CHELSTY, an offline-capable home automation edge node split across two VMs. + +Dokumentacja: [kb/nodes/chelsty-infra.md](../../kb/nodes/chelsty-infra.md) diff --git a/hosts/piha/README.md b/hosts/piha/README.md new file mode 100644 index 0000000..cb4f7f3 --- /dev/null +++ b/hosts/piha/README.md @@ -0,0 +1,5 @@ +# PIHA + +Infrastructure + Automation Node. + +Dokumentacja: [kb/nodes/piha.md](../../kb/nodes/piha.md) diff --git a/hosts/saturn/README.md b/hosts/saturn/README.md new file mode 100644 index 0000000..52b0ec8 --- /dev/null +++ b/hosts/saturn/README.md @@ -0,0 +1,5 @@ +# SATURN + +Primary Development & Orchestration Node. + +Dokumentacja: [kb/nodes/saturn.md](../../kb/nodes/saturn.md) diff --git a/hosts/solaria/README.md b/hosts/solaria/README.md new file mode 100644 index 0000000..5617136 --- /dev/null +++ b/hosts/solaria/README.md @@ -0,0 +1,5 @@ +# SOLARIA + +Compute / GPU / Inference Node. + +Dokumentacja: [kb/nodes/solaria.md](../../kb/nodes/solaria.md) diff --git a/hosts/vps/README.md b/hosts/vps/README.md new file mode 100644 index 0000000..dd12c1e --- /dev/null +++ b/hosts/vps/README.md @@ -0,0 +1,5 @@ +# VPS + +Public Edge + Ingress Node. + +Dokumentacja: [kb/nodes/vps.md](../../kb/nodes/vps.md) diff --git a/scripts/kb/check_okf.py b/scripts/kb/check_okf.py index c0c6d6c..f19dbdd 100755 --- a/scripts/kb/check_okf.py +++ b/scripts/kb/check_okf.py @@ -19,8 +19,10 @@ reguły tego repo: pozostałe wpisy to wolny tekst. 11. `stub` — o ile obecne — musi być boolem. -Zakres domyślny: kb/ oraz docs/sessions/. Reszta repo (CLAUDE.md, README.md, -.claude/skills/ itd.) leży poza bazą wiedzy i nie podlega walidacji. +Zakres domyślny: kb/ oraz docs/sessions/, z wyłączeniem README-wskaźników +(POINTER_GLOBS) — te są nawigacją do kb-doca, nie dokumentami KB, i celowo nie +mają frontmattera OKF. Reszta repo (CLAUDE.md, README.md, .claude/skills/ itd.) +leży poza bazą wiedzy i nie podlega walidacji. Tylko biblioteka standardowa: minimalny parser YAML wystarczający dla frontmatterów w tym repo (klucze skalarne, listy inline, listy blokowe). @@ -31,7 +33,7 @@ from __future__ import annotations import re import sys -from pathlib import Path +from pathlib import Path, PurePosixPath PINNED_OKF = "0.1" @@ -52,9 +54,23 @@ STATUSES = {"active", "deprecated", "planned"} SCOPE = ("kb", "docs/sessions") +# README-wskazniki w services// i hosts// to NAWIGACJA, nie dokumenty +# KB: nazwa + jedno zdanie + link do kb-doca, bez frontmattera OKF. Zrodlem prawdy +# jest kb-doc, do ktorego wskaznik odsyla. Wykluczenie jest tu zapisane wprost, +# zeby ewentualne poszerzenie SCOPE nie zaczelo ich nagle walidowac. +POINTER_GLOBS = ( + "services/*/README.md", + "services/home-assistant/config/ken-legacy/README.md", + "hosts/*/README.md", +) + DATE_RE = re.compile(r"^\d{4}-\d{2}-\d{2}$") +def is_pointer(rel: str) -> bool: + return any(PurePosixPath(rel).match(pat) for pat in POINTER_GLOBS) + + def split_frontmatter(text: str) -> tuple[str | None, str]: """Zwraca (blok frontmattera lub None, reszta dokumentu).""" if not text.startswith("---\n"): @@ -120,7 +136,11 @@ def scope_files(root: Path) -> list[Path]: for rel in SCOPE: base = root / rel if base.is_dir(): - files.extend(p for p in base.rglob("*.md") if ".git" not in p.parts) + files.extend( + p for p in base.rglob("*.md") + if ".git" not in p.parts + and not is_pointer(p.relative_to(root).as_posix()) + ) return sorted(set(files)) diff --git a/services/agent-system/README.md b/services/agent-system/README.md new file mode 100644 index 0000000..f09485f --- /dev/null +++ b/services/agent-system/README.md @@ -0,0 +1,5 @@ +# agent-system + +Central runtime materializer and Operator Control Plane UI. + +Dokumentacja: [kb/subsystems/agent-system.md](../../kb/subsystems/agent-system.md) diff --git a/services/brain-watchdog/README.md b/services/brain-watchdog/README.md new file mode 100644 index 0000000..0af1fb9 --- /dev/null +++ b/services/brain-watchdog/README.md @@ -0,0 +1,5 @@ +# brain-watchdog + +Zewnetrzny watchdog control-plane na VPS: odpytuje /summary po Tailscale i alertuje przez Telegram Bot API, bez zaleznosci od samego control-plane. + +Dokumentacja: [kb/services/brain-watchdog.md](../../kb/services/brain-watchdog.md) diff --git a/services/control-plane/README.md b/services/control-plane/README.md new file mode 100644 index 0000000..0969846 --- /dev/null +++ b/services/control-plane/README.md @@ -0,0 +1,5 @@ +# control-plane + +Observer + Supervisor + Executor + Operator UI na VPS — synteza world state z eventow i dyspozycja akcji. + +Dokumentacja: [kb/services/control-plane.md](../../kb/services/control-plane.md) diff --git a/services/fleet-prometheus/README.md b/services/fleet-prometheus/README.md new file mode 100644 index 0000000..124fd02 --- /dev/null +++ b/services/fleet-prometheus/README.md @@ -0,0 +1,5 @@ +# fleet-prometheus + +Prometheus instance that is the **source of truth for fleet liveness**. + +Dokumentacja: [kb/services/fleet-prometheus.md](../../kb/services/fleet-prometheus.md) diff --git a/services/forgejo/README.md b/services/forgejo/README.md new file mode 100644 index 0000000..ca71d63 --- /dev/null +++ b/services/forgejo/README.md @@ -0,0 +1,5 @@ +# forgejo + +Forgejo is a self-hosted lightweight software forge. + +Dokumentacja: [kb/services/forgejo.md](../../kb/services/forgejo.md) diff --git a/services/gokapi/README.md b/services/gokapi/README.md new file mode 100644 index 0000000..6b69b3e --- /dev/null +++ b/services/gokapi/README.md @@ -0,0 +1,5 @@ +# gokapi + +Lekki self-hosted "Firefox Send" alternative — link do jednego pliku, na zewnątrz, z limitem pobrań/czasu. **Osobny serwis od Nextclouda, celowo.**. + +Dokumentacja: [kb/services/gokapi.md](../../kb/services/gokapi.md) diff --git a/services/ha-diag-agent/README.md b/services/ha-diag-agent/README.md new file mode 100644 index 0000000..362b034 --- /dev/null +++ b/services/ha-diag-agent/README.md @@ -0,0 +1,5 @@ +# ha-diag-agent + +Per-host Home Assistant diagnostic agent. + +Dokumentacja: [kb/services/ha-diag-agent.md](../../kb/services/ha-diag-agent.md) diff --git a/services/ha-mcp/README.md b/services/ha-mcp/README.md new file mode 100644 index 0000000..328ccfd --- /dev/null +++ b/services/ha-mcp/README.md @@ -0,0 +1,5 @@ +# ha-mcp + +Read-only MCP server for Home Assistant. + +Dokumentacja: [kb/services/ha-mcp.md](../../kb/services/ha-mcp.md) diff --git a/services/home-assistant/README.md b/services/home-assistant/README.md new file mode 100644 index 0000000..2ca1051 --- /dev/null +++ b/services/home-assistant/README.md @@ -0,0 +1,5 @@ +# home-assistant + +Read-only import tooling, plus a deploy (repo -> instance) write path for the `api` adapter's automations/scripts/ scenes scope only (`scripts/ha/deploy.sh`) — see "Deploy" below. + +Dokumentacja: [kb/services/home-assistant.md](../../kb/services/home-assistant.md) diff --git a/services/home-assistant/config/ken-legacy/README.md b/services/home-assistant/config/ken-legacy/README.md new file mode 100644 index 0000000..b1c1162 --- /dev/null +++ b/services/home-assistant/config/ken-legacy/README.md @@ -0,0 +1,25 @@ +# ken-legacy — historical archive, do not deploy + +This directory holds the `/config` import of the **pre-migration** Home +Assistant instance: the `homeassistant5` container on piha, wound down +2026-07. It is kept for historical reference only — e.g. recovering the +logic of an old automation — not as a live or deployable instance. + +See `kb/decisions/ha-configs-as-code.md` and the incident +`kb/incidents/2026-07-22-ha-dwie-instancje.md` (2026-07-22) for +why this instance exists separately from the canonical `ken` (now the +Home Assistant OS instance on the RPi4 at 192.168.31.7): this container +kept running after the real migration and was firing automations in +parallel with the real home instance until the cutover was caught and +fixed. + +**Rules for humans and agents:** +- Never run `import.sh ken-legacy` expecting a deploy target — it isn't + one. `services/home-assistant/instances.yaml` marks it `status: + archived` for this reason. +- Never write back to `homeassistant5` from this directory. +- Treat everything here as read-only history. + +Archival import performed: 2026-07-22. + +Dokumentacja: [kb/services/home-assistant-ken-legacy.md](../../../../kb/services/home-assistant-ken-legacy.md) diff --git a/services/kb-postgres/README.md b/services/kb-postgres/README.md new file mode 100644 index 0000000..0db88cf --- /dev/null +++ b/services/kb-postgres/README.md @@ -0,0 +1,5 @@ +# kb-postgres + +Postgres 16 + pgvector — KB spine on **PIHA** (Raspberry Pi 5, always-on). + +Dokumentacja: [kb/services/kb-postgres.md](../../kb/services/kb-postgres.md) diff --git a/services/kb-query/README.md b/services/kb-query/README.md new file mode 100644 index 0000000..2f89b39 --- /dev/null +++ b/services/kb-query/README.md @@ -0,0 +1,5 @@ +# kb-query + +FastAPI search API in front of the module-5 KB retrieval engine (`packages/kb-retrieval/`). + +Dokumentacja: [kb/services/kb-query.md](../../kb/services/kb-query.md) diff --git a/services/llm-gateway/README.md b/services/llm-gateway/README.md new file mode 100644 index 0000000..56e15e0 --- /dev/null +++ b/services/llm-gateway/README.md @@ -0,0 +1,5 @@ +# llm-gateway + +Small FastAPI router in front of Ollama on **SOLARIA**. + +Dokumentacja: [kb/services/llm-gateway.md](../../kb/services/llm-gateway.md) diff --git a/services/mosquitto/README.md b/services/mosquitto/README.md new file mode 100644 index 0000000..48aad92 --- /dev/null +++ b/services/mosquitto/README.md @@ -0,0 +1,5 @@ +# mosquitto + +Eclipse Mosquitto is an open source (EPL/EDL licensed) message broker that implements the MQTT protocol versions 5.0, 3.1.1 and 3.1. + +Dokumentacja: [kb/services/mosquitto.md](../../kb/services/mosquitto.md) diff --git a/services/narty27/README.md b/services/narty27/README.md new file mode 100644 index 0000000..c47c1d0 --- /dev/null +++ b/services/narty27/README.md @@ -0,0 +1,5 @@ +# narty27 + +Static hosting for a single self-contained `viz.html` (narty 2027 / Saalbach KB export) on PIHA. + +Dokumentacja: [kb/services/narty27.md](../../kb/services/narty27.md) diff --git a/services/nextcloud/README.md b/services/nextcloud/README.md new file mode 100644 index 0000000..e75d04f --- /dev/null +++ b/services/nextcloud/README.md @@ -0,0 +1,5 @@ +# nextcloud + +Drugi adapter dokumentów filaru KB #2 (moduł 4, `kb/phases/kb-m4-nextcloud.md`): zamiennik Google Drive — dowolne pliki + sync telefon/desktop, źródło dla ingestu KB (moduł 5) przez WebDAV. + +Dokumentacja: [kb/services/nextcloud.md](../../kb/services/nextcloud.md) diff --git a/services/node-agent/README.md b/services/node-agent/README.md new file mode 100644 index 0000000..5761f08 --- /dev/null +++ b/services/node-agent/README.md @@ -0,0 +1,5 @@ +# node-agent + +Demon monitorujacy zdrowie node'a, uruchamiany na kazdym zarzadzanym wezle; wykonuje `container_restart` z actions/dispatch// przez wlasny docker socket. + +Dokumentacja: [kb/services/node-agent.md](../../kb/services/node-agent.md) diff --git a/services/node_exporter/README.md b/services/node_exporter/README.md new file mode 100644 index 0000000..a53e40a --- /dev/null +++ b/services/node_exporter/README.md @@ -0,0 +1,5 @@ +# node_exporter + +Prometheus Node Exporter — wystawia metryki hosta (CPU, pamiec, dysk, siec) do scrapowania; deploy per-host (vps i piha). + +Dokumentacja: [kb/services/node-exporter.md](../../kb/services/node-exporter.md) diff --git a/services/npm/README.md b/services/npm/README.md new file mode 100644 index 0000000..9fb31b5 --- /dev/null +++ b/services/npm/README.md @@ -0,0 +1,5 @@ +# npm + +Expose your services easily and securely with Nginx Proxy Manager. + +Dokumentacja: [kb/services/npm.md](../../kb/services/npm.md) diff --git a/services/ollama-piha/README.md b/services/ollama-piha/README.md new file mode 100644 index 0000000..8c991e3 --- /dev/null +++ b/services/ollama-piha/README.md @@ -0,0 +1,5 @@ +# ollama-piha + +Local CPU Ollama on **PIHA**, serving exactly one purpose: the **fallback embed backend** for `kb-query` while SOLARIA (the GPU node, ~16 h/day powered off) sleeps. + +Dokumentacja: [kb/services/ollama-piha.md](../../kb/services/ollama-piha.md) diff --git a/services/ollama/README.md b/services/ollama/README.md new file mode 100644 index 0000000..fd28517 --- /dev/null +++ b/services/ollama/README.md @@ -0,0 +1,5 @@ +# ollama + +Get up and running with large language models locally. + +Dokumentacja: [kb/services/ollama.md](../../kb/services/ollama.md) diff --git a/services/paperless-worker/README.md b/services/paperless-worker/README.md new file mode 100644 index 0000000..9430947 --- /dev/null +++ b/services/paperless-worker/README.md @@ -0,0 +1,5 @@ +# paperless-worker + +Ciężki OCR filaru KB #2 (moduł 3, `kb/phases/kb-m3-ocr-worker.md`). + +Dokumentacja: [kb/services/paperless-worker.md](../../kb/services/paperless-worker.md) diff --git a/services/paperless/README.md b/services/paperless/README.md new file mode 100644 index 0000000..87e8fb3 --- /dev/null +++ b/services/paperless/README.md @@ -0,0 +1,5 @@ +# paperless + +Serwis dokumentów filaru KB #2 (moduł 2, `kb/phases/kb-m2-paperless.md`): UI + API + Postgres + Redis. + +Dokumentacja: [kb/services/paperless.md](../../kb/services/paperless.md) diff --git a/services/planner-agent/README.md b/services/planner-agent/README.md new file mode 100644 index 0000000..10545be --- /dev/null +++ b/services/planner-agent/README.md @@ -0,0 +1,5 @@ +# planner-agent + +Asynchroniczny agent diagnozujący zdarzenia zdrowotne w homelabowej infrastrukturze. + +Dokumentacja: [kb/services/planner-agent.md](../../kb/services/planner-agent.md) diff --git a/services/stability-agent/README.md b/services/stability-agent/README.md new file mode 100644 index 0000000..00802b6 --- /dev/null +++ b/services/stability-agent/README.md @@ -0,0 +1,5 @@ +# stability-agent + +A lightweight filesystem-first watchdog and observer agent for homelab nodes. + +Dokumentacja: [kb/services/stability-agent.md](../../kb/services/stability-agent.md) diff --git a/services/vikunja/README.md b/services/vikunja/README.md new file mode 100644 index 0000000..37c8835 --- /dev/null +++ b/services/vikunja/README.md @@ -0,0 +1,5 @@ +# vikunja + +Self-hosted task management. + +Dokumentacja: [kb/services/vikunja.md](../../kb/services/vikunja.md) diff --git a/services/zigbee2mqtt/README.md b/services/zigbee2mqtt/README.md new file mode 100644 index 0000000..07858f2 --- /dev/null +++ b/services/zigbee2mqtt/README.md @@ -0,0 +1,5 @@ +# zigbee2mqtt + +Zigbee to MQTT bridge, get rid of your proprietary Zigbee bridges. + +Dokumentacja: [kb/services/zigbee2mqtt.md](../../kb/services/zigbee2mqtt.md)