fix(kb): README-wskazniki dla services i hosts + wyjatek ken-legacy

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:

    # <nazwa>

    <jedno zdanie opisu>

    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/<svc>/README.md, 5 x hosts/<node>/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) <noreply@anthropic.com>

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)

hosts/piha/README.md

@@ -0,0 +1,5 @@
+# PIHA
+
+Infrastructure + Automation Node.
+
+Dokumentacja: [kb/nodes/piha.md](../../kb/nodes/piha.md)

hosts/saturn/README.md

@@ -0,0 +1,5 @@
+# SATURN
+
+Primary Development & Orchestration Node.
+
+Dokumentacja: [kb/nodes/saturn.md](../../kb/nodes/saturn.md)

hosts/solaria/README.md

@@ -0,0 +1,5 @@
+# SOLARIA
+
+Compute / GPU / Inference Node.
+
+Dokumentacja: [kb/nodes/solaria.md](../../kb/nodes/solaria.md)

hosts/vps/README.md

@@ -0,0 +1,5 @@
+# VPS
+
+Public Edge + Ingress Node.
+
+Dokumentacja: [kb/nodes/vps.md](../../kb/nodes/vps.md)

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,
+Zakres domyślny: kb/ oraz docs/sessions/, z wyłączeniem README-wskaźników
-.claude/skills/ itd.) leży poza bazą wiedzy i nie podlega walidacji.
+(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/<svc>/ i hosts/<node>/ 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))
 
 

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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/<node>/ przez wlasny docker socket.
+
+Dokumentacja: [kb/services/node-agent.md](../../kb/services/node-agent.md)

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)

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)

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)

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)

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)

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)

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)

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)

services/vikunja/README.md

@@ -0,0 +1,5 @@
+# vikunja
+
+Self-hosted task management.
+
+Dokumentacja: [kb/services/vikunja.md](../../kb/services/vikunja.md)

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)