.claude/skills/node-onboarding/SKILL.md

@@ -93,7 +93,7 @@ services:
 
 preflight fills `arch`, `ram_mb`, `docker_present`, `mm_runtime` — do NOT guess these.
 
-Full schema: `kb/runbooks/node-onboarding-tool.md`.
+Full schema: `scripts/onboard/README.md`.
 
 ---
 

CLAUDE.md

@@ -40,7 +40,7 @@ Pipeline stages: **prepare → validate → deploy → verify → diagnose (on f
 ## Node Onboarding
 
 New nodes are onboarded via `scripts/onboard/` — an idempotent bash tool driven by
-`hosts/<node>/node.yaml` manifests (no Ansible). See `kb/runbooks/node-onboarding-tool.md` for
+`hosts/<node>/node.yaml` manifests (no Ansible). See `scripts/onboard/README.md` for
 the full schema, step status table, and gotchas.
 
 Key fields in `node.yaml`: `ssh_user`, `first_contact` (LAN IP — not `.local`),
@@ -93,7 +93,7 @@ Agent → /opt/homelab/actions/pending/<id>.json
       → Executor dispatches to the target node → completed / failed
 ```
 
-The executor never connects to a node (deliberate — see kb/phases/backlog.md
+The executor never connects to a node (deliberate — see docs/backlog.md
 "Remediacja floty bez SSH"). It writes a dispatch file that the node collects:
 
 | Action type | Inbox | Executed on the node by |

README.md

@@ -31,29 +31,29 @@ Action approval flow: `pending/` → operator approves → `approved/` → execu
 
 ## Repository Structure
 
-- `docs/`: [Infrastructure Standards](kb/subsystems/standards.md) and [Deployment Conventions](kb/subsystems/deployment.md).
-- `kb/phases/subsystem-a-naprawa.md`: [Current Maintenance Plan (Control Plane)](kb/phases/subsystem-a-naprawa.md).
+- `docs/`: [Infrastructure Standards](docs/standards.md) and [Deployment Conventions](docs/deployment.md).
+- `docs/architecture/PLAN-subsystem-a-2026-07-28.md`: [Current Maintenance Plan (Control Plane)](docs/architecture/PLAN-subsystem-a-2026-07-28.md).
 - `hosts/`: Host-specific configurations and service assignments.
 - `services/`: Reusable Docker Compose service definitions.
 - `scripts/`: Deployment and management scripts.
 
 ## Getting Started
 
-1.  **Standardization**: Follow the [Infrastructure Standards](kb/subsystems/standards.md).
-2.  **Deployment**: See [Deployment Conventions](kb/subsystems/deployment.md) for how to roll out changes.
+1.  **Standardization**: Follow the [Infrastructure Standards](docs/standards.md).
+2.  **Deployment**: See [Deployment Conventions](docs/deployment.md) for how to roll out changes.
 3.  **SATURN**: Remember that SATURN is the only node where commits should be made.
 
 ## Documentation Index
 
-- [Current Maintenance Plan (Control Plane)](kb/phases/subsystem-a-naprawa.md)
-- [Infrastructure Standards](kb/subsystems/standards.md)
-- [Agent Operating Procedures](kb/subsystems/agent-operating-procedures.md) (For AI/Non-Human Agents)
-- [Deployment Conventions](kb/subsystems/deployment.md)
-- [Hardware](kb/nodes/legacy-hardware.md)
-- [Networking](kb/subsystems/networking.md)
-- [Services](kb/subsystems/legacy-services-list.md)
-- [Node Capabilities](kb/subsystems/capability-model.md)
-- [Action Model](kb/subsystems/action-approval-model.md)
+- [Current Maintenance Plan (Control Plane)](docs/architecture/PLAN-subsystem-a-2026-07-28.md)
+- [Infrastructure Standards](docs/standards.md)
+- [Agent Operating Procedures](docs/agents.md) (For AI/Non-Human Agents)
+- [Deployment Conventions](docs/deployment.md)
+- [Hardware](docs/hardware.md)
+- [Networking](docs/networking.md)
+- [Services](docs/services.md)
+- [Node Capabilities](docs/capabilities.md)
+- [Action Model](services/agent-system/action-model.md)
 
 ---
 *Note: This repository documents the state of the homelab. Runtime state lives outside the repository in `/opt/homelab`.*

docs/access.md

@@ -1,13 +1,3 @@
----
-okf: "0.1"
-type: subsystem
-visibility: private
-status: deprecated
-updated: 2026-04-15
-links: []
-superseded_by: "kb/subsystems/fleet-inventory.md + hosts/<node>/capabilities.yaml (stub z 2026-04-15, sprzed floty)"
----
-
 # Access
 
 ## Description

docs/agents.md

@@ -1,12 +1,3 @@
----
-okf: "0.1"
-type: subsystem
-visibility: public
-status: active
-updated: 2026-05-20
-links: []
----
-
 # Agent Operating Procedures
 
 This document defines the operating procedures, constraints, and interaction protocols for non-human agents (AI agents, autonomous scripts) within the Homelab Codex ecosystem.
@@ -15,9 +6,9 @@ This document defines the operating procedures, constraints, and interaction pro
 
 1.  **Read-Only by Default**: Agents should assume read-only access to the `/opt/homelab` runtime unless explicitly executing an approved action.
 2.  **Git as Authority**: The repository on **SATURN** is the source of truth. Agents must not modify the runtime state on nodes directly without corresponding (or pending) Git state, unless it's an emergency mitigation.
-3.  **Human-in-the-Loop (HIL)**: All destructive or structural changes (restarts, deployments, config changes) must follow the [Action Approval Model](action-approval-model.md).
+3.  **Human-in-the-Loop (HIL)**: All destructive or structural changes (restarts, deployments, config changes) must follow the [Action Approval Model](../services/agent-system/action-model.md).
 4.  **Idempotency**: All scripts and actions proposed or executed by agents MUST be idempotent.
-5.  **Context-Awareness**: Agents MUST read the `README.md` and `kb/subsystems/agent-operating-procedures.md` at the start of every session to align with current infrastructure standards.
+5.  **Context-Awareness**: Agents MUST read the `README.md` and `docs/agents.md` at the start of every session to align with current infrastructure standards.
 
 ## 2. Agent Roles
 

docs/architecture/ARCHITEKTURA.md

@@ -1,17 +1,8 @@
----
-okf: "0.1"
-type: decision
-visibility: private
-status: active
-updated: 2026-07-29
-links: []
----
-
 # Architektura — decyzje obowiązujące
 
 Stan decyzji na 2026-07-28. Podstawa dowodowa:
-[RECON-multiagent-2026-07-27.md](../subsystems/recon-multiagent.md); plan wykonawczy:
-[PLAN-subsystem-a-2026-07-28.md](../phases/subsystem-a-naprawa.md). Zmiana którejkolwiek
+[RECON-multiagent-2026-07-27.md](RECON-multiagent-2026-07-27.md); plan wykonawczy:
+[PLAN-subsystem-a-2026-07-28.md](PLAN-subsystem-a-2026-07-28.md). Zmiana którejkolwiek
 decyzji wymaga aktualizacji tego pliku z nową datą.
 
 ## Dwa subsystemy (2026-07-28)
@@ -42,7 +33,7 @@ Stack ai-cluster na vps (openclaw, codex-worker, planner-worker, service-ops-wor
 redis, mosquitto) jest **wygaszany, nie migrowany**. Bus `codex/*` martwy od
 2026-06-09 (zero nowych połączeń). Branch `task/ai-cluster-solaria` zostaje
 **niezmergowany** — pełni rolę dokumentacji. Kontenery na vps zostaną zatrzymane w
-osobnej, nadzorowanej sesji. Szczegóły: [ai-cluster-LEGACY.md](ai-cluster-legacy.md).
+osobnej, nadzorowanej sesji. Szczegóły: [ai-cluster-LEGACY.md](ai-cluster-LEGACY.md).
 
 ## Approvale zostają HITL (2026-07-28)
 

docs/architecture/PLAN-subsystem-a-2026-07-28.md

@@ -1,15 +1,6 @@
----
-okf: "0.1"
-type: phase
-visibility: private
-status: active
-updated: 2026-07-28
-links: []
----
-
 # Plan naprawy subsystemu A (control-plane) — 2026-07-28
 
-Kontekst: kb/subsystems/recon-multiagent.md. Decyzje bazowe:
+Kontekst: docs/architecture/RECON-multiagent-2026-07-27.md. Decyzje bazowe:
 - Flota dzieli się na dwa subsystemy. A = utrzymaniowy (control-plane, node-agenty,
   self-healing) — ten plan. B = zleceniowy (dyspozytor + Telegram + KB + HA +
   homelab-ops) — prowadzony w osobnym projekcie, poza tym planem.

docs/architecture/RECON-czujniki-2026-07-30.md

@@ -1,16 +1,6 @@
----
-okf: "0.1"
-type: audit
-visibility: private
-status: active
-updated: 2026-07-30
-as_of: 2026-07-30
-links: []
----
-
 # Recon — node-agent vs stability-agent (2026-07-30)
 
-Read-only recon. Ground truth: `kb/subsystems/recon-multiagent.md`
+Read-only recon. Ground truth: `docs/architecture/RECON-multiagent-2026-07-27.md`
 (A1, A2, B7, D15). Source read at master @ `473bf8e`; this branch is cut from
 master @ `0650eb8`. The two intervening merges (`0650eb8` ha-mcp, `cb8a19d`
 kb-query tests) touch none of the audited paths — `services/node-agent/`,
@@ -66,7 +56,7 @@ control plane, stability-agent feeds the agent-system UI, and stability-agent's
 half of the event store is a write-only archive nothing has ever read.
 
 A prior recon reached the same conclusion about the event path on 2026-07-06
-(`kb/audits/prometheus-cutover-2026-07-06.md:88-91`); it has not been acted on.
+(`docs/infra/prometheus-cutover-recon-2026-07-06.md:88-91`); it has not been acted on.
 
 ---
 
@@ -307,7 +297,7 @@ prefix that `container_service_name()` was written to strip.
 - Remove entries from `hosts/solaria/services.yaml` and `hosts/vps/services.yaml`.
 - `docker compose down` on vps, piha, solaria (chelsty-infra when reachable).
 - Purge or archive `/opt/homelab/events/2026-*/` on all four nodes (~5 MB on piha, mostly May).
-- Update CLAUDE.md (agent-system architecture §1, event-path claim at line 100), `kb/services/chelsty-stability-agent.md`, recon A1/A2/B7.
+- Update CLAUDE.md (agent-system architecture §1, event-path claim at line 100), `docs/chelsty-stability-agent.md`, recon A1/A2/B7.
 - **Not covered by the cleanup:** the Redis publisher must be rehomed first or the UI loss is permanent.
 
 ### (b) Merge stability-agent's unique checks into node-agent

docs/architecture/RECON-multiagent-2026-07-27.md

@@ -1,12 +1,3 @@
----
-okf: "0.1"
-type: subsystem
-visibility: private
-status: active
-updated: 2026-07-30
-links: []
----
-
 # Architecture Recon — multi-agent systems (2026-07-27)
 
 Read-only recon of the two multi-agent systems (control-plane, ai-cluster) across vps,
@@ -615,7 +606,7 @@ No runtime state was touched.
 
 **Legacy**
 
-- `kb/decisions/ai-cluster-legacy.md`: ai-cluster is retired in place,
+- `docs/architecture/ai-cluster-LEGACY.md`: ai-cluster is retired in place,
   not migrated (bus idle since 2026-06-09, C9); branch `task/ai-cluster-solaria`
   stays unmerged as documentation; surviving patterns listed; runtime
   retirement runbook (stop stack on vps, observe `free -m`, remove containers)

docs/architecture/ai-cluster-LEGACY.md

@@ -1,12 +1,3 @@
----
-okf: "0.1"
-type: decision
-visibility: public
-status: active
-updated: 2026-07-30
-links: []
----
-
 # ai-cluster — LEGACY, wygaszany (decyzja 2026-07-28)
 
 ## Decyzja
@@ -14,7 +5,7 @@ links: []
 Stack **ai-cluster** działający na vps (`ai-cluster-openclaw-1`, `codex-worker`,
 `planner-worker`, `service-ops-worker`, `redis`, `mosquitto`) jest **wygaszany,
 nie migrowany**. Podstawa (recon
-[RECON-multiagent-2026-07-27.md](../subsystems/recon-multiagent.md), C9):
+[RECON-multiagent-2026-07-27.md](RECON-multiagent-2026-07-27.md), C9):
 bus `codex/*` jest martwy od **2026-06-09** — zero nowych połączeń przez ~7 tygodni,
 workery trzymają tylko puste długożyjące połączenia.
 

docs/capabilities.md

@@ -1,12 +1,3 @@
----
-okf: "0.1"
-type: subsystem
-visibility: public
-status: active
-updated: 2026-05-20
-links: []
----
-
 # Node Capability Model
 
 This document defines the capability model for the homelab infrastructure. The goal is to provide a declarative way to describe what each node can do, its constraints, and its suitability for various workloads.

docs/chelsty-runtime.md

@@ -1,13 +1,3 @@
----
-okf: "0.1"
-type: node
-visibility: private
-status: active
-updated: 2026-05-27
-links:
-  - ../runbooks/chelsty-deploy-recovery.md
----
-
 # CHELSTY Runtime
 
 This document describes the runtime environment and deployment flow for CHELSTY, an offline-capable home automation edge node split across two VMs.
@@ -110,6 +100,48 @@ services:
 
 Remove `monitor: false` once node-agent is bootstrapped on this VM.
 
+## Deployment Flow
+
+### Initial Bootstrap
+```bash
+./scripts/bootstrap/chelsty-runtime.sh
+```
+
+### Deploy services
+```bash
+./scripts/deploy/deploy-node.sh chelsty-infra
+./scripts/deploy/deploy-node.sh chelsty-ha
+```
+
+### Manual (SSH) — chelsty-infra uses docker-compose v1
+```bash
+ssh oskar@100.122.201.22
+cd ~/homelab-codex-ws/services/<service>
+docker-compose -f docker-compose.yml \
+  -f ../../hosts/chelsty-infra/runtime/<service>/docker-compose.override.yml \
+  up -d --build --force-recreate
+```
+
+> **Note:** `docker compose` (v2) is **not** available on chelsty-infra — always use `docker-compose` (hyphenated, v1 1.29.2).
+
+## Recovery Procedures
+
+### Mosquitto stopped
+```bash
+ssh oskar@100.122.201.22 "docker start mosquitto"
+# Ensure restart policy is correct:
+docker update --restart unless-stopped mosquitto
+```
+
+### Zigbee2MQTT won't start
+1. Check logs: `docker logs zigbee2mqtt --tail 50`
+2. Verify SLZB-06U reachable from host: `nc -zv 192.168.1.105 6638`
+3. Verify config is not empty: `cat /opt/homelab/data/zigbee2mqtt/data/configuration.yaml`
+4. If config missing, recreate from the minimal template above
+
+### SLZB-06U unreachable
+`192.168.1.105:6638` EHOSTUNREACH means the coordinator is offline or the LAN is down. Zigbee2MQTT will keep retrying — no restart needed once the coordinator returns.
+
 ## Critical Backup Sets
 
 | Data | Path |

docs/chelsty-stability-agent.md

@@ -1,12 +1,3 @@
----
-okf: "0.1"
-type: service
-visibility: private
-status: active
-updated: 2026-05-20
-links: []
----
-
 ### CHELSTY Stability Agent
 
 The stability-agent on CHELSTY provides local observability and health monitoring for the node's services and infrastructure.

docs/core-stack.md

@@ -1,13 +1,3 @@
----
-okf: "0.1"
-type: subsystem
-visibility: private
-status: deprecated
-updated: 2026-04-15
-links: []
-superseded_by: "kb/subsystems/fleet-inventory.md + hosts/<node>/capabilities.yaml (stub z 2026-04-15, sprzed floty)"
----
-
 # Core Stack
 
 ## Description

docs/deployment.md

@@ -1,13 +1,3 @@
----
-okf: "0.1"
-type: subsystem
-visibility: private
-status: active
-updated: 2026-06-25
-links:
-  - ../incidents/deploy-sh-vps-niszczy-control-plane.md
----
-
 # Deployment Conventions
 
 This document describes the GitOps-lite deployment process for the homelab.
@@ -20,6 +10,21 @@ This document describes the GitOps-lite deployment process for the homelab.
 4.  **Tailscale Mesh**: All hosts are connected via Tailscale, allowing secure communication without public port exposure.
 5.  **Host Autonomy**: Services that must operate during WAN or Git outages keep their runtime dependencies on the execution node or local LAN.
 
+## ⚠️ ZNANY BUG — `deploy.sh vps` niszczy control-plane (2026-06-25)
+
+`deploy.sh vps` uruchamia `deploy-node.sh` w pętli po wszystkich serwisach VPS, w tym
+`control-plane`. Pętla używa innego `COMPOSE_PROJECT_NAME` niż `deploy-local.sh`
+(który uruchamiany jest z `cwd=services/control-plane`). Niezgodność project-name powoduje
+`Recreate` → `No such container` → `set -e` przerywa pętlę → **observer, supervisor,
+executor i operator-ui znikają z VPS.**
+
+**Dopóki bug nie zostanie naprawiony (backlog — Krytyczny):**
+- Do deployu control-plane używać: `ssh -t vps 'cd ~/homelab-codex-ws && cd services/control-plane && bash deploy-local.sh'`
+- Inne serwisy VPS deployować punktowo: `deploy-node.sh` z `--service <name>` lub przez SSH + `docker compose up -d`
+- **NIE uruchamiać `deploy.sh vps` bez pełnej świadomości ryzyka.**
+
+---
+
 ## Staged Deployment Framework
 
 The homelab uses a modularized staged deployment framework located at `scripts/deploy/deploy.sh`. This script is designed to be resumable, stage-aware, and observable, with core logic split into maintainable libraries in `scripts/lib/`.

docs/event-system.md

@@ -1,12 +1,3 @@
----
-okf: "0.1"
-type: subsystem
-visibility: public
-status: active
-updated: 2026-05-12
-links: []
----
-
 # Homelab Event System
 
 The homelab multi-agent platform uses a filesystem-first event architecture for observability, auditability, and agent reasoning.

docs/hardware.md

@@ -1,13 +1,3 @@
----
-okf: "0.1"
-type: node
-visibility: private
-status: deprecated
-updated: 2026-04-15
-links: []
-superseded_by: "hosts/<node>/capabilities.yaml + kb/subsystems/fleet-inventory.md"
----
-
 # Hardware
 
 ## Description

docs/hetzner-vps.md

@@ -1,13 +1,3 @@
----
-okf: "0.1"
-type: node
-visibility: private
-status: deprecated
-updated: 2026-04-15
-links: []
-superseded_by: "kb/nodes/vps.md + kb/subsystems/fleet-inventory.md (stub z 2026-04-15, sprzed floty)"
----
-
 # Hetzner VPS
 
 ## Description

docs/incidents/2026-07-30-ollama-solaria-vanish.md

@@ -1,12 +1,3 @@
----
-okf: "0.1"
-type: incident
-visibility: private
-status: active
-updated: 2026-07-30
-links: []
----
-
 # Incydent: zniknięcie kontenera `ollama` na SOLARII — 2026-07-30
 
 **Status:** root-cause ustalony, potwierdzony logiem i kodem. Fix NIE zaimplementowany (świadomie — patrz §7).

docs/infra/inventory-2026-06-30.md

@@ -1,12 +1,3 @@
----
-okf: "0.1"
-type: subsystem
-visibility: private
-status: active
-updated: 2026-07-03
-links: []
----
-
 # Inwentaryzacja floty homelab-codex — 2026-06-30
 
 Zebrano: 2026-06-30 17:09 CEST  

docs/infra/inventory-verify-2026-07-02.md

@@ -1,17 +1,8 @@
----
-okf: "0.1"
-type: subsystem
-visibility: private
-status: active
-updated: 2026-07-02
-links: []
----
-
 # Weryfikacja inwentaryzacji floty 2026-06-30 — stan na 2026-07-02
 
 Zebrano: 2026-07-02 ~15:20 CEST (read-only recon, zero zmian na nodach).
 Metoda: ssh + `docker ps -a / inspect / logs`, `free/df/nproc/lscpu/lsblk`, `git branch/log` (odczyt),
-`curl` do fleet-prometheus API. Porównanie z `kb/subsystems/fleet-inventory.md` (23 rozjazdy)
+`curl` do fleet-prometheus API. Porównanie z `docs/infra/inventory-2026-06-30.md` (23 rozjazdy)
 oraz z repo na `master` (HEAD `22adfb1`).
 
 Dostępność nodów podczas weryfikacji:

docs/infra/lustro-shipping-recon-2026-07-16.md

@@ -1,13 +1,3 @@
----
-okf: "0.1"
-type: audit
-visibility: private
-status: active
-updated: 2026-07-16
-as_of: 2026-07-16
-links: []
----
-
 # Recon: lustro `event=dead prom=up` — 1507 mismatchy w shadow-liveness.log (2026-07-16)
 
 READ-ONLY recon. Zero zmian w kodzie/serwisach. Wszystkie czasy **UTC**

docs/infra/monitoring-coverage-2026-07-14.md

@@ -1,13 +1,3 @@
----
-okf: "0.1"
-type: audit
-visibility: private
-status: active
-updated: 2026-07-14
-as_of: 2026-07-14
-links: []
----
-
 # Monitoring coverage — co biega vs co jest monitorowane (recon 2026-07-14)
 
 **Pytanie:** czy wszystkie serwisy floty są monitorowane?
@@ -131,7 +121,7 @@ compose-service kontenera.
 | owntracks-prometheus-exporter-prometheus-owntracks-exporter-1 | linusgroh/prometheus-owntracks-exporter | Up 2w | 0.0.0.0:8780→80 |
 | own-tracks-frontend-owntracks-frontend-1 | owntracks/frontend | Up 2w | 0.0.0.0:8084→80 |
 
-Zmiany vs audyt 2026-06-30 (`kb/subsystems/fleet-inventory.md`): **przybyły** paperless,
+Zmiany vs audyt 2026-06-30 (`docs/infra/inventory-2026-06-30.md`): **przybyły** paperless,
 paperless-db, paperless-broker (Deploy 1, 2026-07-10); **zniknęły** diskover i elasticsearch
 (w audycie 06-30 były w 33 shadow; dziś nie biegają). 06-30: 40 kontenerów → dziś: 42.
 

docs/infra/okit-cloudflare-migracja.md

@@ -1,12 +1,3 @@
----
-okf: "0.1"
-type: phase
-visibility: private
-status: active
-updated: 2026-07-07
-links: []
----
-
 # Migracja okit.pl: 42.pl (FreeDNS) -> Cloudflare — plan faz
 
 Cel: okit.pl na Cloudflare (jak kapala.org) -> wildcard *.okit.pl DNS-01 ->

docs/infra/ollama-solaria-cutover-2026-07-15.md

@@ -1,12 +1,3 @@
----
-okf: "0.1"
-type: runbook
-visibility: private
-status: active
-updated: 2026-07-16
-links: []
----
-
 # Ollama SOLARIA: manual → declarative cutover runbook
 
 Date: 2026-07-15
@@ -97,7 +88,7 @@ bind-mount the existing model directory.**
    docker exec ollama ollama ps
    ```
 3. Embeddings endpoint + vector dimension (deferred check from
-   `kb/phases/kb-m5-faza2.md` §6 step 2):
+   `docs/kb/modules/05-faza2-plan.md` §6 step 2):
    ```bash
    curl -s http://localhost:11434/api/embeddings -d '{"model":"bge-m3","prompt":"test"}' \
      | python3 -c "import json,sys; v=json.load(sys.stdin)['embedding']; print(len(v))"
@@ -145,7 +136,7 @@ SOLARIA:
 - Given the missing driver, the cutover proceeded **in CPU-only mode**: the
   `deploy.resources` GPU reservation was commented out in
   `services/ollama/docker-compose.yml` (commit `f57a01a`), and the driver fix
-  was filed as a backlog item (see `kb/phases/backlog.md`) blocking the module 5
+  was filed as a backlog item (see `docs/backlog.md`) blocking the module 5
   mail-embedding phase.
 - **2026-07-16: driver fixed.** Installed `nvidia-driver-595-open` from the
   distro repository — not the old `ppa:graphics-drivers/ppa` (jammy), which

docs/infra/piha-slim-audit-2026-07-02.md

@@ -1,16 +1,6 @@
----
-okf: "0.1"
-type: audit
-visibility: private
-status: active
-updated: 2026-07-02
-as_of: 2026-07-02
-links: []
----
-
 # Audyt odchudzania PIHA — 2026-07-02
 
-> Faza 1 (READ-ONLY) modulu 0 filaru dokumentow (`kb/phases/kb-m0-piha-slim.md`).
+> Faza 1 (READ-ONLY) modulu 0 filaru dokumentow (`docs/kb/modules/00-piha-slim.md`).
 > Zadna akcja nie zostala wykonana — wylacznie `docker stats/inspect/logs`, `ss`, `curl` (odczyt).
 > Stan w momencie audytu: **RAM 7.9Gi total, 5.0Gi used, 2.9Gi available; swap 4Gi total, 2.0Gi uzyty.**
 > 41 kontenerow Up (inwentaryzacja 2026-06-30 liczyla 40; wszystkie nadal biega).

docs/infra/prometheus-cutover-recon-2026-07-06.md

@@ -1,13 +1,3 @@
----
-okf: "0.1"
-type: audit
-visibility: private
-status: active
-updated: 2026-07-06
-as_of: 2026-07-06
-links: []
----
-
 # Prometheus liveness cutover — recon starego toru (2026-07-06)
 
 Read-only recon przed cutoverem liveności floty na Prometheus `up{}`. Mapa obecnego
@@ -300,7 +290,7 @@ renderuje `health`/`status`/`last_seen`), `/unhealthy` (`:302-334`), `/summary`,
   chelsty/chelsty-infra (exporter DOWN po LTE, 2026-06-26).
 - Reguła `NodeDown` (`rules/liveness.yml:21-28`): `up{node=~"vps|piha"} == 0`,
   `for: 5m`, severity critical. solaria/lustro świadomie wykluczone (`:12-16` —
-  planned power-off; docelowo anomaly detection, `kb/phases/backlog.md:390-406`).
+  planned power-off; docelowo anomaly detection, `docs/backlog.md:390-406`).
   Bez Alertmanagera by design (`:3-7`) — delivery = brain-watchdog poll `/api/v1/alerts`.
 - node_exporter w repo tylko dla VPS (`services/node_exporter/`, network_mode: host,
   `hosts/vps/services.yaml:36-43`). Exportery na piha/solaria/lustro **nie mają
@@ -348,7 +338,7 @@ chelsty-infra, chelsty-ha, lustro.
 | lustro | TAK (`:50-52`) | NIE | TAK (bez stability-agenta) | jw. |
 | **chelsty-infra** | **NIE** (`:57-60`, exporter DOWN po LTE) | NIE | **TAK** (remote TTL 900/3600, `liveness.py:43-50`) | **tylko stary tor — cutover totalny zostawiłby go bez liveności** |
 | chelsty-ha | NIE | NIE | NIE (`hosts/chelsty-ha/services.yaml:6-12`, `monitor: false`) | już dziś bez liveności (pośrednio przez MQTT chelsty-infra) — cutover nic nie zmienia |
-| saturn | NIE (`:55`, laptop) | NIE | NIE (brak `hosts/saturn/services.yaml`, `kb/phases/backlog.md:423`) | już dziś bez liveności — cutover nic nie zmienia |
+| saturn | NIE (`:55`, laptop) | NIE | NIE (brak `hosts/saturn/services.yaml`, `docs/backlog.md:423`) | już dziś bez liveności — cutover nic nie zmienia |
 
 **Chelsty offline ~34 dni — jak traktuje go stara rura:** eventy buforują się lokalnie
 (rsync fail = non-fatal, `node_agent.py:560-566`), `last_seen` na VPS zamrożone sprzed
@@ -361,7 +351,7 @@ totalnym chelsty-infra nie miałby żadnej liveności i żadnego przejścia offl
 Dodatkowo docs sygnalizują konflikt IP w komentarzach `prometheus.yml:57` vs
 `hosts/chelsty-infra/host.yaml:12` — do wyjaśnienia przy ewentualnym dodawaniu scrape.
 *(rzeczywisty bieżący stan chelsty — do weryfikacji na żywo; ostatni zapis:
-UNREACHABLE, `kb/subsystems/fleet-inventory-verify.md:17,151`)*
+UNREACHABLE, `docs/infra/inventory-verify-2026-07-02.md:17,151`)*
 
 **Wniosek twardy:** cutover NIE może być globalny. Docelowa architektura to
 **hybryda per-node**: `up{}` dla scrape'owanych (vps, piha, solaria, lustro),
@@ -460,7 +450,7 @@ z `last_seen` — rzadszy heartbeat przy niezmienionych TTL-ach = fałszywe degr
 - chelsty-infra: zbadać exporter-over-LTE (`prometheus.yml:57-60` + konflikt IP
   z `hosts/chelsty-infra/host.yaml:12`); do tego czasu zostaje na torze eventowym.
 - NodeDown dla solaria/lustro: świadomie odroczone do anomaly detection
-  (`kb/phases/backlog.md:390-406`) — nie wciągać do cutoveru.
+  (`docs/backlog.md:390-406`) — nie wciągać do cutoveru.
 - Watchdog na sam Prometheus (D.2 pkt 5) — mały task przy etapie 3.
 - saturn / chelsty-ha: świadomie poza monitoringiem — status quo.
 
@@ -468,7 +458,7 @@ z `last_seen` — rzadszy heartbeat przy niezmienionych TTL-ach = fałszywe degr
 
 **Seria.** Minimalnie trzy taski implementacyjne + weryfikacje między nimi:
 (1) etap 1 shadow-read; (2) etap 3 flaga per-node (po tygodniu etapu 2);
-(3) watchdog-na-Prometheusa + aktualizacja `kb/subsystems/observer.md`.
+(3) watchdog-na-Prometheusa + aktualizacja `docs/observer-runtime.md`.
 Etap 0 to czynność operatorska (runtime, nie repo). Etap 5 to niezależny backlog.
 
 ---

docs/infra/prometheus-shadow-etap2-analiza-2026-07-15.md

@@ -1,12 +1,3 @@
----
-okf: "0.1"
-type: phase
-visibility: private
-status: active
-updated: 2026-07-15
-links: []
----
-
 # Prometheus cutover — Etap 2: analiza zgodności shadow-run (2026-07-15)
 
 Analiza READ-ONLY logów `SHADOW_LIVENESS_MISMATCH` observera (parallel-run od
@@ -164,7 +155,7 @@ Skutek uboczny do zaakceptowania świadomie: syntetyczne `node_stale`/
 wyłączeniu **wcześniej, ale nie liczniej** — te eventy już dziś powstają co noc
 (21:32/21:39 dla lustro, każdorazowo dla solaria). Cutover nie zwiększa wolumenu
 alertów. Docelowe wyciszenie planowych okien off to wątek anomaly-detection
-z backlogu (`kb/phases/backlog.md:390-406`) — **niezależny od cutoveru i nieblokujący**;
+z backlogu (`docs/backlog.md:390-406`) — **niezależny od cutoveru i nieblokujący**;
 `NodeDown` dla solaria/lustro słusznie pozostaje wyłączony.
 
 ### Rekomendowany mapping (potwierdzenie rekomendacji z recon F/Etap 2)

docs/infra/vps-audit-2026-07-27.md

@@ -1,13 +1,3 @@
----
-okf: "0.1"
-type: audit
-visibility: private
-status: active
-updated: 2026-07-27
-as_of: 2026-07-27
-links: []
----
-
 # Audyt niezarządzanych stacków na VPS — 2026-07-27
 
 Recon read-only przed konsolidacją do GitOps. Zebrane przez `ssh vps` (user `oskar`,

docs/joplin-server.md

@@ -1,13 +1,3 @@
----
-okf: "0.1"
-type: service
-visibility: private
-status: deprecated
-updated: 2026-04-15
-links: []
-superseded_by: "brak katalogu services/joplin/ w repo — patrz contradicts w kb/subsystems/repo-operating-contract.md"
----
-
 # Joplin Server
 
 ## Description

docs/kb/eval/retrieval-pilot-2026-07-16.md

@@ -1,12 +1,3 @@
----
-okf: "0.1"
-type: phase
-visibility: private
-status: active
-updated: 2026-07-16
-links: []
----
-
 # Eval-set: pilot retrieval (faza 2, krok 7) — 2026-07-16
 
 Stan bazy: document_chunk = 2683 chunki (bge-m3, dim 1024), 160 dokumentów z 186 kopert paperless.

docs/kb/kb-00-overview.md

@@ -1,13 +1,3 @@
----
-okf: "0.1"
-type: subsystem
-visibility: private
-status: active
-updated: 2026-06-26
-links:
-  - ../decisions/kb-log-decyzji.md
----
-
 # Baza wiedzy — przegląd i log decyzji (homelab-codex · KB)
 
 > Master-dokument inicjatywy. Stoi ponad dokumentami per-projekt (`kb-01-email-design.md`, …).
@@ -92,6 +82,21 @@ Dwa dolne tiery są per-filar i neutralne. Dwa górne są wspólne dla wszystkic
 
 ---
 
+## Decyzje — zamknięte vs otwarte
+
+**Zamknięte:**
+- Spine: Postgres + pgvector (nie Qdrant).
+- Embed: **bge-m3** (multilingual, długi kontekst — pod polski lepszy niż multilingual-e5).
+- Załączniki: indeksowane w **II turze** (MVP najpierw czysty tekst).
+- Warstwa 3 startuje jako **cienki graf encji**; federacja przy zapytaniu dochodzi później (docelowo hybryda).
+- Dokumenty: Nextcloud + Paperless-ngx.
+
+**Otwarte:**
+- **Transakcje:** agregator vs CSV, pokrycie mBanku, Revolut, koszt (filar #4).
+- **Maile §design:** sizing archiwum / node (ile waży Gmail), unifikacja adaptera (jeden IMAP dla obu vs JMAP+IMAP osobno).
+
+---
+
 ## Tor równoległy (nie tutaj)
 
 Hardening homelabu / stabilizacja control-plane — osobny wątek.

docs/kb/kb-01-email-design.md

@@ -1,12 +1,3 @@
----
-okf: "0.1"
-type: subsystem
-visibility: private
-status: active
-updated: 2026-06-24
-links: []
----
-
 # Filar maili — projekt (homelab-codex · KB · projekt #1)
 
 > Pierwszy filar. Wzorzec referencyjny dla pozostałych (archiwum, embeddingi na SOLARIA, szkielet agenta, deploy).

docs/kb/kb-02-documents-design.md

@@ -1,18 +1,9 @@
----
-okf: "0.1"
-type: subsystem
-visibility: private
-status: active
-updated: 2026-07-01
-links: []
----
-
 # KB filar #2 — Dokumenty (Nextcloud + Paperless) — design
 
 > Dokument-master filaru dokumentow. Stoi pod `kb-00-overview.md`.
 > Cel: kazda sesja / Claude Code startuje z pelnym kontekstem decyzji.
 > Status: ARCHITEKTURA ZAMKNIETA (2026-07-01), implementacja modulowa czeka.
-> Moduly implementacyjne: `kb/phases/kb-m*.md` — puszczane CC jeden po drugim.
+> Moduly implementacyjne: `docs/kb/modules/0X-*.md` — puszczane CC jeden po drugim.
 
 ---
 

docs/kb/modules/00-piha-slim.md

@@ -1,12 +1,3 @@
----
-okf: "0.1"
-type: phase
-visibility: private
-status: active
-updated: 2026-07-02
-links: []
----
-
 # Modul 0 — Odchudzic PIHA (prerekwizyt filaru dokumentow)
 
 > Prerekwizyt modulow 2/4 (Paperless/Nextcloud na PIHA). Bez tego PIHA nie ma
@@ -15,7 +6,7 @@ links: []
 ## STATUS: prerekwizyt RAM SPELNIONY (2026-07-02)
 
 Faza 1 (audyt read-only) + faza 2 (egzekucja po review Oskara) wykonane —
-szczegoly: `kb/audits/piha-slim-2026-07-02.md` (sekcja "Korekta po review
+szczegoly: `docs/infra/piha-slim-audit-2026-07-02.md` (sekcja "Korekta po review
 + egzekucja").
 
 - **Kryterium >= 1.5Gi available: SPELNIONE.** Przed egzekucja: 2.8Gi available
@@ -37,7 +28,7 @@ Zwolnic RAM na PIHA (dzis: 3.1Gi available, swap 2G uzyty) tak, by lekki Paperle
 serwis wszedl z zapasem, nie na styku swap.
 
 ## Wymogi
-- Audyt 33 shadow-kontenerow (lista w `kb/subsystems/fleet-inventory.md`).
+- Audyt 33 shadow-kontenerow (lista w `docs/infra/inventory-2026-06-30.md`).
 - Zidentyfikowac kandydatow do usuniecia/przeniesienia/wylaczenia:
   - **elasticsearch 1Gi** — kto tego uzywa? (wikijs? diskover?) — jesli martwy, ubic
   - **diskover** — jednorazowy indekser? czy chodzi ciagle bez potrzeby?

docs/kb/modules/01-sso-forgejo-oidc.md

@@ -1,12 +1,3 @@
----
-okf: "0.1"
-type: decision
-visibility: private
-status: active
-updated: 2026-07-01
-links: []
----
-
 # Modul 1 — SSO Forgejo-OIDC (decyzja + wzorzec wpiecia)
 
 > Fundament tozsamosci dla filaru dokumentow (i szerzej homelaba). Zapisuje decyzje

docs/kb/modules/02-paperless-service.md

@@ -1,12 +1,3 @@
----
-okf: "0.1"
-type: phase
-visibility: private
-status: active
-updated: 2026-07-01
-links: []
----
-
 # Modul 2 — Paperless-ngx serwis (na PIHA)
 
 > Serwis dokumentow: UI+API+Postgres+Redis. Always-on na PIHA. OCR-worker OSOBNO

docs/kb/modules/03-paperless-ocr-worker.md

@@ -1,12 +1,3 @@
----
-okf: "0.1"
-type: phase
-visibility: private
-status: active
-updated: 2026-07-01
-links: []
----
-
 # Modul 3 — Paperless OCR-worker (SOLARIA + fallback PIHA)
 
 > Ciezki OCR odseparowany od serwisu. Worker na SOLARIA (moc), fallback PIHA (wolno).

docs/kb/modules/04-nextcloud.md

@@ -1,12 +1,3 @@
----
-okf: "0.1"
-type: phase
-visibility: private
-status: active
-updated: 2026-07-02
-links: []
----
-
 # Modul 4 — Nextcloud (drive/WebDAV + OIDC)
 
 > Drugi adapter dokumentow: zamiennik Google Drive, dowolne pliki + sync. Zrodlo

docs/kb/modules/05-documents-ingest.md

@@ -1,12 +1,3 @@
----
-okf: "0.1"
-type: phase
-visibility: private
-status: active
-updated: 2026-07-02
-links: []
----
-
 # Modul 5 — Ingest dokumentow -> koperta KB
 
 > Adapter obu zrodel (Paperless API + Nextcloud WebDAV) -> koperta KB. Domyka filar #2

docs/kb/modules/05-fallback-dedup-raport.md

@@ -1,12 +1,3 @@
----
-okf: "0.1"
-type: phase
-visibility: private
-status: active
-updated: 2026-07-30
-links: []
----
-
 # Raport dedup: fallback embed SOLARIA→PIHA — e7625cd (master) vs 3d4ee38 (task/kb-f4-fallback)
 
 **Data**: 2026-07-30 · **Worktree**: `task/kb-fallback-dedup` · **Status**: salvage **wykonany**
@@ -71,10 +62,10 @@ zegarem, master trzyma to samo wewnątrz `EmbedRouter` (też injektowalny zegar)
 | `services/kb-query/{README,env.example,service.yaml,docker-compose.yml}` | ~±58 | duplikat | **porzuć** | inny (porzucony) schemat env `OLLAMA_PIHA_URL`; master bogatszy (testy A/B/C, rename `OLLAMA_URL`→`EMBED_PRIMARY_URL`) |
 | `packages/kb-retrieval/src/kb_retrieval/embed.py` (`timeout_s` w `embed_chunk`) | +16 | duplikat funkcji | **porzuć** | master osiąga twardy timeout przez `asyncio.wait_for` bez zmiany współdzielonego pakietu — mniejsza powierzchnia zmian, ten sam efekt |
 | `jobs/documents-ingest/eval/retrieval_eval.py` (`--transport {direct,http}` + `--base-url`) | +109 | **unikalna wartość** | **cherry-pick** | plan §2 decyzja 6 / §9 (bramka HTTP-equivalence) — **na masterze w ogóle nie istnieje**; e7625cd nie tknął tego pliku, patch aplikuje się czysto; kod woła tylko `GET /search` i czyta `envelope_id`/`dist`/`source` — w pełni zgodny z odpowiedzią mastera |
-| `kb/phases/kb-m5-documents-ingest-fazy.md` | +6 | **unikalna wartość** | **cherry-pick** | dokumentacja powyższego, idzie w parze |
+| `jobs/documents-ingest/README.md` | +6 | **unikalna wartość** | **cherry-pick** | dokumentacja powyższego, idzie w parze |
 | `docs/sessions/2026-07-27-kb-f4-fallback.md` | +189 | **unikalna wartość** | **adaptuj** | jedyny zapis: (1) znalezisko osieroconego natywnego `ollama.service` na PIHA + jego wyłączenie 2026-07-27 i backlog odinstalowania, (2) kalibracja live ollama-piha (GO: peak ~983 MiB, ~4.2–5.3 s/embed), (3) metodologia i wyniki bramki §9 (HTTP-equivalence 0 rozbieżności; sol-down Δ~3e-4), (4) rsync-deploy → dirty working tree na PIHA. Wciągnąć z dopiskiem redakcyjnym, że zmergowana implementacja to **inny kod** (e7625cd) i wyniki bramki wymagają powtórki |
 | `services/ollama-piha/*` (5 plików) | +155 | duplikat | **porzuć** | wersja mastera lepsza: named volume `ollama_piha_models` (uzasadnienie uid-pattern PIHA), healthcheck sprawdza obecność `bge-m3`, bind tylko 127.0.0.1+LAN |
-| `hosts/piha/runtime/ollama-piha/docker-compose.override.yml` | +13 | duplikat + **1 unikalny fakt** | **adaptuj (mikro)** | ten sam `mem_limit: 2560m`; ale komentarz brancha zawiera potwierdzony pomiar (peak ~983 MiB), a master wciąż mówi „Confirm/trim after live calibration" — dopisać wynik kalibracji do komentarza override'u i/lub sekcji „Calibration" w `kb/services/ollama-piha.md` |
+| `hosts/piha/runtime/ollama-piha/docker-compose.override.yml` | +13 | duplikat + **1 unikalny fakt** | **adaptuj (mikro)** | ten sam `mem_limit: 2560m`; ale komentarz brancha zawiera potwierdzony pomiar (peak ~983 MiB), a master wciąż mówi „Confirm/trim after live calibration" — dopisać wynik kalibracji do komentarza override'u i/lub sekcji „Calibration" w `services/ollama-piha/README.md` |
 | `hosts/piha/services.yaml` | ±26 | duplikat | **porzuć** | master ma własny wpis `ollama-piha` + soft-dependency kb-query; drobna różnica (`offline_required: true` na branchu vs `false` na masterze) — master źródłem prawdy |
 
 ---
@@ -107,7 +98,7 @@ skonfigurowanego → `EmbedBackendError`, `fallback_status` (up/unconfigured), s
 ## 4. Rekomendacja zbiorcza (lista do zatwierdzenia)
 
 1. **S1 — cherry-pick**: `retrieval_eval.py --transport http --base-url` + akapit w
-   `kb/phases/kb-m5-documents-ingest-fazy.md` (plan §2 D6/§9; aplikuje się czysto, zero zależności
+   `jobs/documents-ingest/README.md` (plan §2 D6/§9; aplikuje się czysto, zero zależności
    od porzuconego kodu brancha).
 2. **S2 — adaptuj**: `docs/sessions/2026-07-27-kb-f4-fallback.md` → `docs/sessions/`
    z dopiskiem redakcyjnym na górze (implementacja z tej sesji porzucona na rzecz
@@ -116,7 +107,7 @@ skonfigurowanego → `EmbedBackendError`, `fallback_status` (up/unconfigured), s
 3. **S3 — adaptuj**: luki testowe T1 + T2 (T3 opcjonalnie) do `test_embed_router.py`.
 4. **S4 — adaptuj (mikro)**: wynik kalibracji 2026-07-27 (peak ~983 MiB, ~4.2–5.3 s,
    werdykt GO) do komentarza `hosts/piha/runtime/ollama-piha/docker-compose.override.yml`
-   i sekcji Calibration w `kb/services/ollama-piha.md` — pomiar dotyczył kontenera
+   i sekcji Calibration w `services/ollama-piha/README.md` — pomiar dotyczył kontenera
    ollama-piha (ta sama konfiguracja: obraz, `OLLAMA_KEEP_ALIVE=0`, `mem_limit 2560m`),
    więc **przenosi się** na wersję mastera; różni się tylko storage (bind vs named
    volume), co nie wpływa na RAM/latencję.
@@ -130,7 +121,7 @@ skonfigurowanego → `EmbedBackendError`, `fallback_status` (up/unconfigured), s
   (3d4ee38) i worktree `~/homelab-codex-ws-kb-f4-fallback` po zakończeniu salvage.
 - **(b) Powtórka testu sol-down na żywym masterze**: kalibracja i bramka z 2026-07-27
   dotyczyły **innego kodu** (`fallback.py`, env `OLLAMA_PIHA_URL`) — na wdrożonym
-  e7625cd trzeba przejść testy A/B/C z `kb/services/kb-query.md` oraz bramkę
+  e7625cd trzeba przejść testy A/B/C z `services/kb-query/README.md` oraz bramkę
   `retrieval_eval.py --transport http` (po S1): HTTP-equivalence przy SOLARIA-up
   (identyczne `dist`) i sol-down (Δ≤epsilon, kolejność top-k identyczna; baseline
   z 27.07: Δ~3e-4). Symulacja wg README: `EMBED_PRIMARY_URL=http://192.0.2.1:11434`

docs/kb/modules/05-faza-mailowa-plan.md

@@ -1,12 +1,3 @@
----
-okf: "0.1"
-type: phase
-visibility: private
-status: active
-updated: 2026-07-23
-links: []
----
-
 # Moduł 5, faza mailowa — treść maili w retrievalu (RECON + PLAN)
 
 > Status (2026-07-23): Kroki 0-4 WYKONANE na żywo (chunker wydzielony, hybrid

docs/kb/modules/05-faza2-plan.md

@@ -1,12 +1,3 @@
----
-okf: "0.1"
-type: phase
-visibility: private
-status: active
-updated: 2026-07-13
-links: []
----
-
 # Modul 5, faza 2 — koperta dokumentow + embeddingi + cross-source (RECON + PLAN)
 
 > Status: RECON ZAKONCZONY (2026-07-13), architektura DO ZATWIERDZENIA. Zaden kod nie
@@ -545,7 +536,7 @@ zeby dalo sie uruchomic partiami i zweryfikowac progres bez czekania na cale 225
   rzedu dziesiatek-set chunkow/s. Caly pilot (2–3k chunkow) → **rzedu minut**, nie wymaga
   specjalnego batchowania/partii.
 - **Skala docelowa (70k zalacznikow z maili)**: modul 5 faza-1 to swiadomie **probka, nie
-  bulk** (`kb/phases/kb-m5-documents-ingest-fazy.md` — decyzja architektoniczna). Realny wolumen
+  bulk** (`jobs/documents-ingest/README.md` — decyzja architektoniczna). Realny wolumen
   ktory trafi do embeddingu zalezy od (a) throughput OCR-workera na SOLARII (modul 3) —
   **to jest waskie gardlo skalowania, nie embedding** — oraz (b) filtra selektywnosci
   (decyzja #6). Sam embedding bge-m3 nie bedzie bottleneckiem nawet przy tysiacach

docs/kb/modules/05-faza3-plan.md

@@ -1,12 +1,3 @@
----
-okf: "0.1"
-type: phase
-visibility: private
-status: active
-updated: 2026-07-17
-links: []
----
-
 # Moduł 5, faza 3 — warstwa kompilacji (RECON + PLAN)
 
 > Status: RECON ZAKOŃCZONY (2026-07-16), plan DO ZATWIERDZENIA. Zero kodu, zero migracji,
@@ -448,7 +439,7 @@ Próbka 25 dokumentów (stratyfikowana: polisy, faktury, umowy, urzędowe, FLL/s
 - **kompletność faktów kluczowych** (kwoty, daty, strony, numery),
 - **jakość tagów** (trafność + zgodność ze słownikiem).
 
-Wynik do `kb/phases/kb-m5-faza3-pilot-streszczen.md`: tabela per dokument + wnioski.
+Wynik do `docs/kb/modules/05-faza3-pilot-streszczen.md`: tabela per dokument + wnioski.
 **Kryterium „lokalny wystarcza na skalę mailową"**: mediana wierności = 2 (zero tolerancji
 dla przekręconych kwot — to trafia do wiki) i kompletność ≥ 80% punktów API. Jeśli lokalny
 nie daje rady → decyzja o skali mailowej rozważa API z polityką eskalacji fazy 5 (koszt
@@ -505,7 +496,7 @@ aktywnych chunków, N większe niż liczba kopert, no-summaries short-circuit)
 pakietu przechodzi.
 
 **Eval-set utrwalony**: `jobs/documents-ingest/eval/queries.yaml` (7 zapytań z pilota
-07-16, 1:1 z `kb/phases/kb-m5-eval-retrieval-pilot.md`, ten plik pozostał nietknięty —
+07-16, 1:1 z `docs/kb/eval/retrieval-pilot-2026-07-16.md`, ten plik pozostał nietknięty —
 `queries.yaml` to jego wersjonowana kopia robocza). Skrypt bramki (read-only, integracyjny,
 **nie wchodzi do pytest**): `jobs/documents-ingest/eval/retrieval_eval.py`.
 
@@ -700,7 +691,7 @@ streszczeń). Kandydaci na pierwsze strony (encje z pilota): PZU/WARTA (polisy),
 ## 9. Poza zakresem fazy 3
 
 Granice planu — wszystko poniżej jest świadomie odłożone, z istniejącym miejscem w
-roadmapie (`kb/subsystems/kb-overview.md` „Stan etapów/Backlog", sesja
+roadmapie (`docs/kb/kb-00-overview.md` „Stan etapów/Backlog", sesja
 `docs/sessions/2026-07-16.md`, backlog operatora):
 
 | Temat | Gdzie zakotwiczone | Kiedy |

docs/kb/modules/05-faza4-plan.md

@@ -1,12 +1,3 @@
----
-okf: "0.1"
-type: phase
-visibility: private
-status: active
-updated: 2026-07-22
-links: []
----
-
 # Moduł 5, faza 4 — kb-query + UI (RECON + PLAN)
 
 > Status: RECON ZAKOŃCZONY (2026-07-22), plan DO ZATWIERDZENIA. Zero kodu, zero
@@ -68,7 +59,7 @@ links: []
 
 ### 1.3 PIHA — budżet RAM (istotne dla decyzji D2 / lokalnego fallbacku)
 
-- Audyt `kb/audits/piha-slim-2026-07-02.md`: po "bezpiecznym usuń"
+- Audyt `docs/infra/piha-slim-audit-2026-07-02.md`: po "bezpiecznym usuń"
   (elasticsearch+diskover+stary llm-gateway) available rosło z **2.9Gi do ~3.8Gi**
   (na 8 GB total, +4 GB swap). To jest **jedyna zweryfikowana liczba w repo i ma
   3 tygodnie** — od tego dnia na PIHA doszły (GitOps, z `mem_limit`): paperless+db+broker
@@ -97,7 +88,7 @@ domeny `*.kapala.org`:
   (cert #51 *.okit.pl, cert osobny dla *.kapala.org — sesje ją tylko konfigurują
   ręcznie/SQL-em, nigdy nie deployują z repo). kb-query dogania się do tego samego
   wzorca: nowy vhost w `npm@PIHA`, TLS z **już istniejącego** wildcard `*.kapala.org`
-  (pokrywa `paper.`/`cloud.`/`vikunja.kapala.org` — `kb/decisions/kb-dokumenty-otwarte.md`
+  (pokrywa `paper.`/`cloud.`/`vikunja.kapala.org` — `docs/kb/modules/DECYZJE-do-podjecia.md`
   #6) — **żaden nowy certyfikat nie jest potrzebny**.
 - **DNS — dwie warstwy, obie trzeba dotknąć** (lekcja `okit-cloudflare-migracja.md`
   §"WAZNE: split-horizon DNS"): (a) Cloudflare rekord A → Tailscale IP PIHA
@@ -261,7 +252,7 @@ przed backfillem" z fazy 3 §3.1 (zmierz, obejrzyj, dopiero wtedy zaufaj progowi
 ### Decyzja 3 — Linki do źródeł: paperless vs gmail
 
 **Paperless**: URL do dokumentu — **do zweryfikowania na żywym Paperless przed
-implementacją** (repo nie ma zapisanego przykładu, `kb/phases/kb-m2-paperless.md`
+implementacją** (repo nie ma zapisanego przykładu, `docs/kb/modules/02-paperless-service.md`
 dokumentuje tylko subdomenę, nie ścieżkę). Kandydat wg konwencji paperless-ngx UI:
 `https://paper.kapala.org/documents/<id>/details` (Angular routing) — `envelope_id`
 `paperless:<id>` już niesie surowy `<id>` do wstawienia. Krok implementacji: jeden
@@ -471,7 +462,7 @@ Jedna strona (Jinja2 template + vanilla JS + CSS, serwowane z tego samego FastAP
 - Pole zapytania + submit (Enter albo przycisk).
 - Wyniki grupowane po `envelope_id` (dokument), w obrębie dokumentu chunki
   posortowane po `dist`.
-- Kolorowanie progów (progi z fazy 3, `kb/phases/kb-m5-faza3.md` §1.2,
+- Kolorowanie progów (progi z fazy 3, `docs/kb/modules/05-faza3-plan.md` §1.2,
   zweryfikowane bramką): `dist < 0.45` zielony, `0.45–0.55` żółty, `> 0.55` —
   **nie renderować wyniku**, tylko komunikat "brak odpowiedzi w KB" (żółta/czerwona
   strefa nadal renderuje wynik z ostrzeżeniem wizualnym; czerwona = brak sensownego

docs/kb/modules/DECYZJE-do-podjecia.md

@@ -1,12 +1,3 @@
----
-okf: "0.1"
-type: decision
-visibility: private
-status: planned
-updated: 2026-07-09
-links: []
----
-
 # Decyzje do podjęcia — filar dokumentów (moduły 2/3/4)
 
 > Zbiorcza lista decyzji z przygotowania configów (2026-07-06, branch
@@ -63,7 +54,7 @@ zdecydować, czy podbić concurrency, czy zostawić zapas na ollama/AI.
   rsync/borg → SOLARIA (2 TB, ta sama LAN). Retencja: 7 dziennych +
   4 tygodniowe + 6 miesięcznych. Offsite (np. restic → chmura) zostaje jako
   future-note, poza zakresem tego etapu. Cron/skrypt deployowy powstaje przy
-  deployu modułu 2, nie teraz. Szczegóły: `kb/services/paperless.md`.
+  deployu modułu 2, nie teraz. Szczegóły: `services/paperless/README.md`.
 
 - **4. Redis brokera: `requirepass`.** Broker (6380) dostaje hasło —
   `PAPERLESS_REDIS_PASSWORD` w `.env` po obu stronach (paperless@PIHA,
@@ -76,7 +67,7 @@ zdecydować, czy podbić concurrency, czy zostawić zapas na ollama/AI.
   + SOLARIA po NFS) świadomie zaakceptowane — indeks jest odtwarzalny
   (`document_index reindex`), oryginałom nic nie grozi. Bez zmian w
   configu; fallback-worker na PIHA zostaje. Szczegóły:
-  `kb/services/paperless-worker.md`.
+  `services/paperless-worker/README.md`.
 
 - **6. Domeny: `kapala.org` (mesh, prywatne).** `paper.kapala.org`
   (Paperless), `cloud.kapala.org` (Nextcloud) — potwierdzone, `*.okit.pl`
@@ -99,7 +90,7 @@ zdecydować, czy podbić concurrency, czy zostawić zapas na ollama/AI.
   maintainerów paperless-ngx (nieoficjalnie wspierany): ten sam obraz,
   `command: celery --app paperless worker`, wspólny Redis+Postgres+storage,
   identyczne ścieżki kontenerowe i numeryczny UID po obu stronach. Pełny
-  wynik badania + ryzyka: `kb/services/paperless-worker.md`.
+  wynik badania + ryzyka: `services/paperless-worker/README.md`.
 - Storage dokumentów na PIHA; NFS export → SOLARIA po LAN
   (192.168.31.5 → 192.168.31.70), nie Tailscale.
 - AOF w Redis brokera (kolejka przeżywa restart — zero utraty zadań).

docs/lifecycle.md

@@ -1,13 +1,3 @@
----
-okf: "0.1"
-type: subsystem
-visibility: private
-status: active
-updated: 2026-05-11
-links:
-  - ../runbooks/service-operational-recovery.md
----
-
 # Service Lifecycle and Recovery
 
 This document defines the lifecycle of a service in the homelab and the procedures for operational recovery.
@@ -35,6 +25,25 @@ This document defines the lifecycle of a service in the homelab and the procedur
     - `docker compose down`.
     - Archive `/opt/homelab/data/<service>` if necessary.
 
+## Operational Recovery
+
+### 1. Container Failure
+If a service is unhealthy:
+- Check `docker compose logs`.
+- Restart: `docker compose restart`.
+- Recreate: `docker compose up -d --force-recreate`.
+
+### 2. Node Failure
+If a host node fails:
+- Services with `owner_node` matching the failed node must be recovered on a backup node or the node must be restored.
+- Persistence data must be restored from backups to `/opt/homelab/data/<service>`.
+
+### 3. Dependency Recovery
+If a dependency fails:
+- Services depending on it might report unhealthy status.
+- Recover the dependency first.
+- Re-verify dependent services.
+
 ## Persistent Data Conventions
 
 - **Data**: `/opt/homelab/data/<service>` - Primary persistent state.

docs/networking.md

@@ -1,13 +1,3 @@
----
-okf: "0.1"
-type: subsystem
-visibility: private
-status: deprecated
-updated: 2026-04-15
-links: []
-superseded_by: "kb/subsystems/fleet-inventory.md + hosts/<node>/capabilities.yaml (stub z 2026-04-15, sprzed floty)"
----
-
 # Networking
 
 ## Description

docs/node-onboarding.md

@@ -1,12 +1,3 @@
----
-okf: "0.1"
-type: runbook
-visibility: public
-status: active
-updated: 2026-05-12
-links: []
----
-
 # Node Onboarding Workflow
 
 This document describes the process of onboarding a new Linux machine into the homelab platform.

docs/observer-runtime.md

@@ -1,12 +1,3 @@
----
-okf: "0.1"
-type: subsystem
-visibility: public
-status: active
-updated: 2026-06-17
-links: []
----
-
 # Observer Runtime
 
 The Observer Runtime is a lightweight agent responsible for synthesizing the operational world state of the homelab from raw events, logs, and state files.

docs/questions.md

@@ -0,0 +1,65 @@
+# Unknowns and Clarification Questions
+
+## Description
+
+This page lists information that is missing or unclear from the current homelab documentation.
+
+## Current configuration
+
+The currently documented configuration is limited to:
+
+- Raspberry Pi 5 as the main server.
+- Docker, Portainer, and Nginx Proxy Manager as the core stack.
+- NAT with forwarded ports:
+  - `80-81` to `4480-4481`
+  - `443` to `4443`
+- Public access through Nginx Proxy Manager with Let's Encrypt HTTPS.
+- Private access through Tailscale.
+- Hetzner VPS handoff:
+  - Hostname: `ubuntu-4gb-hel1-1`
+  - Tailscale IP: `100.95.58.48`
+  - Public IPv4: `135.181.153.108`
+  - Public IPv6: `2a01:4f9:c014:98f0::1`
+  - Running container: `npm`
+  - Joplin files created but not running.
+
+## Known facts
+
+- The homelab is documented only from the known facts above.
+- Anything not listed as known remains unconfirmed.
+
+## Unknown / needs clarification
+
+1. What operating system and version is running on the Raspberry Pi 5?
+2. What is the Raspberry Pi 5 RAM size?
+3. What storage devices are used, and where is persistent service data stored?
+4. What is the Raspberry Pi 5 LAN IP address?
+5. Is the Raspberry Pi 5 using DHCP or a static IP address?
+6. What router or firewall performs NAT and port forwarding?
+7. Is the WAN IP static, dynamic, or behind CGNAT?
+8. Does external port `80` map to internal port `4480`, and does external port `81` map to internal port `4481`?
+9. Are the forwarded ports TCP only, UDP only, or both?
+10. Are any other ports forwarded?
+11. What domain names or subdomains point to the homelab?
+12. What are the Nginx Proxy Manager proxy hosts?
+13. Which services are public, and which are private-only?
+14. Is HTTP-to-HTTPS redirection enabled in Nginx Proxy Manager?
+15. Are Nginx Proxy Manager access lists used?
+16. How are Docker, Portainer, and Nginx Proxy Manager deployed?
+17. Are Docker Compose files, Portainer stacks, or other manifests available?
+18. What containers are currently running?
+19. What Docker networks and volumes exist?
+20. What is the Tailscale device name for the Raspberry Pi 5?
+21. Does the Raspberry Pi 5 advertise Tailscale subnet routes?
+22. Is the Raspberry Pi 5 configured as a Tailscale exit node?
+23. Is Tailscale SSH enabled?
+24. What backup system exists, if any?
+25. What monitoring or alerting exists, if any?
+26. Is the Hetzner VPS part of the homelab documentation scope, a separate system, or both?
+27. What is the operating system version on `ubuntu-4gb-hel1-1`?
+28. Is public Nginx Proxy Manager admin access on port `81` intentionally reachable on `135.181.153.108`?
+29. Has DNS record `joplin.okit.pl -> 135.181.153.108` been created?
+30. Has optional AAAA record `joplin.okit.pl -> 2a01:4f9:c014:98f0::1` been created?
+31. Has `POSTGRES_PASSWORD=CHANGE_ME_STRONG_PASSWORD` been changed before first Joplin production start?
+32. Has the Nginx Proxy Manager proxy host for `joplin.okit.pl` been created?
+33. Are ports `80` and `443` publicly reachable on the Hetzner VPS for Let's Encrypt HTTP validation?

docs/service-model.md

@@ -1,12 +1,3 @@
----
-okf: "0.1"
-type: subsystem
-visibility: public
-status: active
-updated: 2026-05-11
-links: []
----
-
 # Service Model and Healthchecks
 
 This document defines the normalized service model for the homelab.

docs/services.md

@@ -1,13 +1,3 @@
----
-okf: "0.1"
-type: subsystem
-visibility: private
-status: deprecated
-updated: 2026-04-15
-links: []
-superseded_by: "kb/subsystems/fleet-inventory.md + hosts/<node>/capabilities.yaml (stub z 2026-04-15, sprzed floty)"
----
-
 # Services
 
 ## Description

docs/sessions/2026-05-27-planner-agent.md

@@ -1,12 +1,3 @@
----
-okf: "0.1"
-type: session-log
-visibility: private
-status: active
-updated: 2026-05-27
-links: []
----
-
 # SESSION: Budowa planner-agent — LLM-based diagnostics
 
 **DATA:** 2026-05-27  

docs/sessions/2026-05-27.md

@@ -1,12 +1,3 @@
----
-okf: "0.1"
-type: session-log
-visibility: private
-status: active
-updated: 2026-05-27
-links: []
----
-
 # SESSION: Stabilizacja systemu wieloagentowego homelabu
 
 **DATE:** 2026-05-27  

docs/sessions/2026-06-08-lustro-onboarding.md

@@ -1,12 +1,3 @@
----
-okf: "0.1"
-type: session-log
-visibility: private
-status: active
-updated: 2026-06-09
-links: []
----
-
 # Sesja 2026-06-08 — onboarding LUSTRO (RPi4 / Magic Mirror / KEN)
 
 ## Cel
@@ -90,7 +81,7 @@ przez Tailscale działa bezhasłowo. Verify czysty (arch=aarch64).
 
 ## Learnings
 
-(odzwierciedlone też w `kb/runbooks/node-onboarding-tool.md`)
+(odzwierciedlone też w `scripts/onboard/README.md`)
 
 - mDNS `.local` zawodny do automatyzacji → `first_contact` przez IP lub tailscale, nie `.local`
 - istniejący node z userem uid=1000: użyj go zamiast tworzyć `oskar` (kolizja uid)

docs/sessions/2026-06-09-flota-recovery-lustro-register.md

@@ -1,12 +1,3 @@
----
-okf: "0.1"
-type: session-log
-visibility: private
-status: active
-updated: 2026-06-09
-links: []
----
-
 # Sesja 2026-06-09 — flota recovery + LUSTRO register
 
 ## Cel
@@ -130,4 +121,4 @@ Docelowo: osobny worktree per task.
 
 ## Tech-debt złapany w sesji
 
-→ wpisany do `kb/phases/backlog.md`
+→ wpisany do `docs/backlog.md`

docs/sessions/2026-06-11-lustro-ssh-shipping.md

@@ -1,12 +1,3 @@
----
-okf: "0.1"
-type: session-log
-visibility: private
-status: active
-updated: 2026-06-11
-links: []
----
-
 # Sesja 2026-06-10/11 — lustro SSH shipping fix + ha-diag-agent piha
 
 ## Cel
@@ -79,13 +70,13 @@ solaria / piha / chelsty to wciąż **stare root kontenery** node-agenta
 (piha Created 2026-05-27, uid 0). Ich mount `/root/.ssh` działa tylko dlatego,
 że kontenery są sprzed `user: "1000:1000"`. Pierwszy `--force-recreate` / reboot
 hosta / update obrazu przełączy je na uid 1000 i shipping padnie jak na lustrze.
-**NIE RECREATE bez fixu.** Szczegóły i fix: `kb/phases/backlog.md`.
+**NIE RECREATE bez fixu.** Szczegóły i fix: `docs/backlog.md`.
 
 ---
 
 ## Tech-debt złapany w sesji
 
-→ wpisany do `kb/phases/backlog.md` (flota-bomba, ha-diag-agent blocked,
+→ wpisany do `docs/backlog.md` (flota-bomba, ha-diag-agent blocked,
 poison-quarantine review, `--omit-dir-times`, stale komentarz node_agent.py,
 shipping success na `logger.debug`, event-bloat lustro na VPS).
 
@@ -96,8 +87,8 @@ fa59625 docs(ha-diag-agent): replace curl verify commands with docker exec
 d7e0d31 fix(ha-diag-agent): remove host port mapping for 8087
 
 ### Files changed
- kb/runbooks/ha-diag-agent-deploy.md          | 4 ++--
- kb/services/ha-diag-agent.md          | 4 ++--
+ services/ha-diag-agent/DEPLOY.md          | 4 ++--
+ services/ha-diag-agent/README.md          | 4 ++--
  services/ha-diag-agent/docker-compose.yml | 3 ---
  services/ha-diag-agent/service.yaml       | 3 ---
  4 files changed, 4 insertions(+), 10 deletions(-))

docs/sessions/2026-06-17-kb-foundations.md

@@ -1,12 +1,3 @@
----
-okf: "0.1"
-type: session-log
-visibility: private
-status: active
-updated: 2026-06-17
-links: []
----
-
 # Sesja 2026-06-17 — KB foundations (etap 1 maili)
 
 ## Cel
@@ -120,14 +111,14 @@ services/kb-postgres/service.yaml
 services/kb-postgres/env.example
 services/kb-postgres/healthcheck.sh
 services/kb-postgres/init/001_envelope.sql
-kb/services/kb-postgres.md
+services/kb-postgres/README.md
 hosts/solaria/runtime/kb-postgres/docker-compose.override.yml
 hosts/solaria/services.yaml
 inventory/topology.yaml
 packages/kb-mail/pyproject.toml
 packages/kb-mail/src/kb_mail/{__init__,envelope,db,archive}.py
 packages/kb-mail/tests/{conftest,test_envelope,test_archive,test_db,test_migration}.py
-kb/subsystems/kb-overview.md   (etap 1 done, konwencja packages/)
+docs/kb/kb-00-overview.md   (etap 1 done, konwencja packages/)
 CLAUDE.md                   (sekcja Shared Python Libraries)
 docs/sessions/2026-06-17-kb-foundations.md
 ```

docs/sessions/2026-06-17-vikunja-observer-panel.md

@@ -1,12 +1,3 @@
----
-okf: "0.1"
-type: session-log
-visibility: private
-status: active
-updated: 2026-06-17
-links: []
----
-
 # Sesja 2026-06-17 — Vikunja OIDC+GitOps · Observer heartbeat-TTL · panel-source
 
 ## Zrobione i wdrożone

docs/sessions/2026-06-22-kb-postgres-piha.md

@@ -1,12 +1,3 @@
----
-okf: "0.1"
-type: session-log
-visibility: private
-status: active
-updated: 2026-06-22
-links: []
----
-
 # Sesja 2026-06-22 — KB spine relokowany na PIHA + przygotowanie hosta
 
 ## Cel

docs/sessions/2026-06-22.md

@@ -1,12 +1,3 @@
----
-okf: "0.1"
-type: session-log
-visibility: private
-status: active
-updated: 2026-06-22
-links: []
----
-
 # Sesja 2026-06-22 — decyzja: Prometheus jako źródło prawdy dla liveness floty
 
 ## Cel

docs/sessions/2026-06-24-kb-gmail-importer.md

@@ -1,12 +1,3 @@
----
-okf: "0.1"
-type: session-log
-visibility: private
-status: active
-updated: 2026-06-24
-links: []
----
-
 # Sesja 2026-06-24 — KB etap 2: importer Gmail (kod gotowy)
 
 ## Cel
@@ -171,7 +162,7 @@ jobs/gmail-bulk-import/pyproject.toml
 jobs/gmail-bulk-import/tests/test_importer.py
 hosts/piha/capabilities.yaml
 .gitignore
-kb/subsystems/kb-overview.md          (etap 2 gotowy, konwencja jobs/)
-kb/subsystems/kb-mail-pillar.md      (§8 krok 2 = kod gotowy)
+docs/kb/kb-00-overview.md          (etap 2 gotowy, konwencja jobs/)
+docs/kb/kb-01-email-design.md      (§8 krok 2 = kod gotowy)
 docs/sessions/2026-06-24-kb-gmail-importer.md
 ```

docs/sessions/2026-06-24.md

@@ -1,12 +1,3 @@
----
-okf: "0.1"
-type: session-log
-visibility: private
-status: active
-updated: 2026-06-24
-links: []
----
-
 # Sesja 2026-06-24 — fleet-prometheus etap 1: scaffold + deploy-node hostname fix
 
 ## Cel
@@ -108,7 +99,7 @@ docker compose \
 
 ---
 
-## Nowe tech-debty (dodane do `kb/phases/backlog.md`)
+## Nowe tech-debty (dodane do `docs/backlog.md`)
 
 1. **Rozjazd stanu Docker Compose na VPS** — serwisy `node-agent`, `control-plane` i inne
    stworzone innym `project-name` niż `deploy-node.sh` oczekuje; Recreate pada na stale

docs/sessions/2026-06-25-kb-gmail-import-uruchomiony.md

@@ -1,12 +1,3 @@
----
-okf: "0.1"
-type: session-log
-visibility: private
-status: active
-updated: 2026-06-26
-links: []
----
-
 # Sesja 2026-06-25 — KB etap 2: bulk import Gmail uruchomiony
 
 ## Cel

docs/sessions/2026-06-25.md

@@ -1,12 +1,3 @@
----
-okf: "0.1"
-type: session-log
-visibility: private
-status: active
-updated: 2026-06-25
-links: []
----
-
 # Sesja 2026-06-25 — fleet-prometheus etap 1: uruchomienie na VPS + incydent mózgu
 
 ## Cel

docs/sessions/2026-06-26.md

@@ -1,12 +1,3 @@
----
-okf: "0.1"
-type: session-log
-visibility: private
-status: active
-updated: 2026-06-26
-links: []
----
-
 # Sesja 2026-06-26 — fleet-prometheus etap 2: targety floty + zamknięcie buga deploy.sh vps
 
 ## Cel

docs/sessions/2026-06-30-fleet-inventory.md

@@ -1,12 +1,3 @@
----
-okf: "0.1"
-type: session-log
-visibility: private
-status: active
-updated: 2026-06-30
-links: []
----
-
 # Sesja 2026-06-30 — Inwentaryzacja floty + gaszenie dysku SATURN
 
 ## Cel
@@ -19,7 +10,7 @@ architekturą dokumentów KB. Start od weryfikacji stanu faktycznego wszystkich
 - CC (Sonnet 4.6) w worktree `fleet-inventory` zebrał stan faktyczny (docker ps +
   free/df/nproc) z 4 dostępnych nodów: PIHA, VPS, SOLARIA, SATURN. LUSTRO+CHELSTY
   offline (timeout :22) -> oznaczone UNREACHABLE.
-- Wynik: `kb/subsystems/fleet-inventory.md` — 23 zpriorytetyzowane rozjazdy.
+- Wynik: `docs/infra/inventory-2026-06-30.md` — 23 zpriorytetyzowane rozjazdy.
 - Kluczowe ustalenia:
   - **forgejo** biega na PIHA (always-on), ale `service.yaml owner_node=saturn` — rozjazd
   - **mosquitto** biega na VPS, `service.yaml owner=piha`, na PIHA go nie ma

docs/sessions/2026-06-30-kapala-cloudflare-wildcard-mesh.md

@@ -1,12 +1,3 @@
----
-okf: "0.1"
-type: session-log
-visibility: private
-status: active
-updated: 2026-06-30
-links: []
----
-
 # 2026-06-30 — Migracja kapala.org → Cloudflare + wildcard DNS-01, HA i Immich na mesh
 
 ## Cel

docs/sessions/2026-06-30-prometheus-liveness.md

@@ -1,12 +1,3 @@
----
-okf: "0.1"
-type: session-log
-visibility: private
-status: active
-updated: 2026-06-30
-links: []
----
-
 # Sesja 2026-06-30 — fleet-prometheus liveness: reguły NodeDown + wpięcie watchdog→Prometheus
 
 ## Cel

docs/sessions/2026-07-02-modul0-cert-migracja.md

@@ -1,16 +1,7 @@
----
-okf: "0.1"
-type: session-log
-visibility: private
-status: active
-updated: 2026-07-02
-links: []
----
-
 # Sesja 2026-07-02 — Modul 0 (odchudzenie PIHA) + migracja Forgejo/Vikunja na kapala.org
 
 ## Modul 0 kb-02 — WYKONANY (faza 1 audyt + faza 2 egzekucja)
-- Audyt CC (read-only): kb/audits/piha-slim-2026-07-02.md
+- Audyt CC (read-only): docs/infra/piha-slim-audit-2026-07-02.md
 - Review Oskara skorygowal audyt: llm-gateway = WLASNY kod (FastAPI-router LLM,
   /opt/llm-gateway, proxy do Ollama@SOLARIA) — NIE martwy; immich MUSI byc 24/7
   na PIHA (SOLARIA sesyjna) — rekomendacja przeniesienia wykreslona.

docs/sessions/2026-07-02.md

@@ -1,12 +1,3 @@
----
-okf: "0.1"
-type: session-log
-visibility: private
-status: active
-updated: 2026-07-02
-links: []
----
-
 # Sesja 2026-07-02 — recon-weryfikacja inwentaryzacji + rozbrojenie trzech min
 
 ## Cel
@@ -21,7 +12,7 @@ Sesja tylko-recon + minimalne fixy; bez deployów nowych feature'ów.
 
 ### Recon-weryfikacja inwentaryzacji floty (commit `57a6dff`, read-only)
 
-Wynik: `kb/subsystems/fleet-inventory-verify.md`.
+Wynik: `docs/infra/inventory-verify-2026-07-02.md`.
 
 **Bilans 23 rozjazdów z audytu 2026-06-30**:
 - **20 wciąż aktualnych** — nic się samo nie naprawiło.
@@ -100,7 +91,7 @@ Po jednej linii per plik; `owner_node` nie występował nigdzie indziej w repo.
   nie rezolwuje z SOLARII; brak formalnego override mem_limit fleet-prometheus
   w `hosts/vps/runtime/` (siedzi w bazowym compose — kosmetyka).
 
-Wpisy dodane do `kb/phases/backlog.md` w tej sesji.
+Wpisy dodane do `docs/backlog.md` w tej sesji.
 
 ---
 

docs/sessions/2026-07-06.md

@@ -1,12 +1,3 @@
----
-okf: "0.1"
-type: session-log
-visibility: private
-status: active
-updated: 2026-07-06
-links: []
----
-
 # Sesja 2026-07-06 — cutover liveności na Prometheus: recon starego toru + Etap 0 udowodniony w boju
 
 ## Cel
@@ -22,7 +13,7 @@ Prometheus → brain-watchdog → Telegram, którego brakowało od 2026-06-30.
 
 ### Recon cutoveru — wmergowany (commit `d94bb38`)
 
-Wynik: `kb/audits/prometheus-cutover-2026-07-06.md` (517 linii, read-only,
+Wynik: `docs/infra/prometheus-cutover-recon-2026-07-06.md` (517 linii, read-only,
 zero zmian w kodzie). Kluczowe ustalenia:
 
 - **Cutover to podmiana klasyfikacji liveności w JEDNYM miejscu** —

docs/sessions/2026-07-07-immich-pimain-cleanup.md

@@ -1,12 +1,3 @@
----
-okf: "0.1"
-type: session-log
-visibility: private
-status: active
-updated: 2026-07-07
-links: []
----
-
 # Session log 2026-07-07 — Immich upload fix / pimain cleanup (kontynuacja 2026-07-03)
 
 ## Kontekst

docs/sessions/2026-07-07-okit-wildcard.md

@@ -1,12 +1,3 @@
----
-okf: "0.1"
-type: session-log
-visibility: private
-status: active
-updated: 2026-07-07
-links: []
----
-
 # Sesja 2026-07-07 — okit.pl Faza 1 (wildcard cert) + przepiecie 9 hostow
 
 ## Kontekst

docs/sessions/2026-07-09-kb-configi-gokapi.md

@@ -1,12 +1,3 @@
----
-okf: "0.1"
-type: session-log
-visibility: private
-status: active
-updated: 2026-07-09
-links: []
----
-
 # Sesja 2026-07-09 — KB configi (9 decyzji) + wzorzec dzielenia plikow (Nextcloud twierdza + Gokapi)
 
 ## Kontekst

docs/sessions/2026-07-10-paperless-deploy.md

@@ -1,12 +1,3 @@
----
-okf: "0.1"
-type: session-log
-visibility: private
-status: active
-updated: 2026-07-10
-links: []
----
-
 # Sesja 2026-07-10 — Deploy 1 Paperless (DZIALA) + swap PIHA + npm-API tool w akcji
 
 ## Glowne osiagniecie: Paperless serwis LIVE

docs/sessions/2026-07-12-deploy2-ocr-worker.md

@@ -1,12 +1,3 @@
----
-okf: "0.1"
-type: session-log
-visibility: private
-status: active
-updated: 2026-07-12
-links: []
----
-
 # Sesja 2026-07-12 — Deploy 2: split-host OCR-worker (DZIALA) + decyzja kierunku KB
 
 ## Deploy 2 — OCR-worker na SOLARIA przez NFS: DZIALA end-to-end
@@ -46,7 +37,7 @@ maila = ta sama encja, DOWOD zasady kb-00 #7), (3) interfejs pytan (RAG) — pie
 realnej uzytecznosci. Dopiero POTEM dopelniac importy (reszta Takeout, zdjecia, transakcje).
 
 ## TODO nastepne
-- MODUL 5 (koperta + ingest + embeddingi + cross-source) — kb/phases/kb-m5-documents-ingest.md
+- MODUL 5 (koperta + ingest + embeddingi + cross-source) — docs/kb/modules/05-documents-ingest.md
 - Import probki zalacznikow z maili (kilkaset, nie 70k) — do zbudowania RAG
 - Interfejs pytan / RAG — warstwa uzytkowa
 - Deploy 3 (Nextcloud), Deploy 4 (Gokapi) — configi gotowe, czekaja

docs/sessions/2026-07-15.md

@@ -1,12 +1,3 @@
----
-okf: "0.1"
-type: session-log
-visibility: private
-status: active
-updated: 2026-07-15
-links: []
----
-
 # Sesja 2026-07-15 — Prometheus cutover Etap 2 (analiza GO) + domknięcie rodziny bugów event-pipeline/checkpoint
 
 ## Kontekst
@@ -27,12 +18,12 @@ parsowany z nazwy `evt-<node>-<ts>-...` (fallback mtime, **nigdy 0** dla
 istniejącego pliku — 0 = leksykalne "starszy niż checkpoint" = dokładnie ten
 poison), migracja starych path-checkpointów przy starcie. Zdeployowany na VPS
 (observer `StartedAt` 07-14). Zweryfikowany dziś jako kompletny i zdeployowany.
-Szczegóły: `kb/phases/backlog.md` (sekcja "Bug: checkpoint observera po ścieżce
+Szczegóły: `docs/backlog.md` (sekcja "Bug: checkpoint observera po ścieżce
 leksykalnej").
 
 ### 2. docs(infra) analiza Etapu 2 shadow-run (Fable, `8fec62d`)
 
-`kb/phases/prometheus-cutover-etap2.md` — 165 mismatchy
+`docs/infra/prometheus-shadow-etap2-analiza-2026-07-15.md` — 165 mismatchy
 `SHADOW_LIVENESS_MISMATCH` solaria/lustro w dobie 2026-07-14 WYJAŚNIONE: dwa
 nocne wyłączenia węzłów (lustro 21:30 UTC — regularny power-off, solaria
 21:34 UTC). Wzorzec `event=fresh prom=down` to **nie** "żywy węzeł niewidziany

docs/sessions/2026-07-16.md

@@ -1,12 +1,3 @@
----
-okf: "0.1"
-type: session-log
-visibility: private
-status: active
-updated: 2026-07-16
-links: []
----
-
 
 ---
 
@@ -31,7 +22,7 @@ links: []
 
 ### 1. RECON lustro shipping (Fable, commit `542bba4`)
 
-`kb/audits/lustro-shipping-2026-07-16.md` — 1507 mismatchy `lustro event=dead prom=up` w trwałym logu WYJAŚNIONE: (a) wczorajszy kontrolowany test (node-agent stał 3h20m, nie 15 min jak zakładano) + (b) poranny boot-race 56s. **Werdykt: shipping lustro działa, ZERO recurring problemu.** Prometheus 0 pomyłek w 48h — wzmacnia rekomendację GO dla Etapu 3 cutoveru.
+`docs/infra/lustro-shipping-recon-2026-07-16.md` — 1507 mismatchy `lustro event=dead prom=up` w trwałym logu WYJAŚNIONE: (a) wczorajszy kontrolowany test (node-agent stał 3h20m, nie 15 min jak zakładano) + (b) poranny boot-race 56s. **Werdykt: shipping lustro działa, ZERO recurring problemu.** Prometheus 0 pomyłek w 48h — wzmacnia rekomendację GO dla Etapu 3 cutoveru.
 
 Znaleziska poboczne: lustro biega na obrazie sprzed 5 tyg (deploy-node bez `--build` — patrz fix #2 niżej); fake-hwclock boot-race (RPi bez RTC — pierwszy event po boocie ma stary stempel, dropnięty przez timestamp checkpoint).
 

docs/sessions/2026-07-18.md

@@ -1,12 +1,3 @@
----
-okf: "0.1"
-type: session-log
-visibility: private
-status: active
-updated: 2026-07-20
-links: []
----
-
 # Sesja 2026-07-17/18 — KB faza 3: kroki 2-5 DOMKNIĘTE
 
 ## Krok 2 — migracja 004 + pilot streszczeń A/B (17.07)

docs/sessions/2026-07-21.md

@@ -1,12 +1,3 @@
----
-okf: "0.1"
-type: session-log
-visibility: private
-status: active
-updated: 2026-07-22
-links: []
----
-
 # Sesja 2026-07-17…21 — wątek KB: faza 3 kroki 3-5 DONE (+ incydenty)
 
 **Krok 3 — kaskada summary→chunk:** bramka **PASS at N=10, k=5** (N-sweep {1..20}: N=5 to zmierzona podłoga, N=10 niesie 2× margines); kaskada nie degraduje niczego, na 186 dok nie poprawia (test architektury pod skalę mailową, zgodnie z przewidywaniem planu); koszt +1 SQL, zero dodatkowych embedów. cascade_query = domyślna ścieżka kb-query; flat_query zostaje jako baseline. Eval przepisany do wersjonowanego eval/queries.yaml + retrieval_eval.py.

docs/sessions/2026-07-22-ha-dwa-mozgi-cutover.md

@@ -1,12 +1,3 @@
----
-okf: "0.1"
-type: session-log
-visibility: private
-status: active
-updated: 2026-07-22
-links: []
----
-
 # 2026-07-22 — HA: incydent dwóch mózgów, cutover ken, archiwum legacy
 
 ## Odkrycie

docs/sessions/2026-07-22.md

@@ -1,12 +1,3 @@
----
-okf: "0.1"
-type: session-log
-visibility: private
-status: active
-updated: 2026-07-22
-links: []
----
-
 # Sesja 2026-07-22 — KB faza 4: recon + kroki 1-2 (kb-query LIVE na PIHA)
 
 **Recon+plan fazy 4** (05-faza4-plan.md, 603 linie): D1 wydzielenie packages/kb-retrieval (documents-ingest ciągnie anthropic+CLI — nie do obrazu serwisu); D2 fallback embed z pełną maszyną stanów, ale gate'owany kalibracją RAM na żywym PIHA (audyt nieaktualny, ~3.8Gi zajęte — plan daje kryteria i alternatywę: jawna degradacja 503 zamiast łamania inwariantu modelu); OIDC wbudowane w apkę (authlib, wzorzec repo — nigdy forward-auth); gmail: envelope_id już JEST Message-ID.

docs/sessions/2026-07-23-control-plane-remediation-e2e.md

@@ -1,12 +1,3 @@
----
-okf: "0.1"
-type: session-log
-visibility: private
-status: active
-updated: 2026-07-23
-links: []
----
-
 # 2026-07-22/23 — Control-plane: dziura w operator_ui + pierwszy pełny cykl remediacji bez SSH
 
 Zamknięcie wielosesyjnego wątku "czemu mózg nie leczy floty". Dwa dni pracy,
@@ -70,7 +61,7 @@ approval → executor → node-agent → docker restart → completed.
    test E2E padł: agent rzucał `[Errno 13] Permission denied:
    /opt/homelab/actions/dispatch` co cykl. Root cause to ZNANY, POWRACAJĄCY
    (już 4. raz — patrz sekcja "Tech-debt: globalny porządek uid/gid/uprawnień
-   we flocie" w `kb/phases/backlog.md`) motyw
+   we flocie" w `docs/backlog.md`) motyw
    uid/gid na PIHA: oskar ma uid 1004, kontener agenta biega jako uid 1000
    (= user `pi` na hoście). `/opt/homelab/actions` było `oskar:oskar
    drwxr-xr-x` (utworzone w maju), podczas gdy DZIAŁAJĄCY wzorzec to
@@ -111,7 +102,7 @@ approval → executor → node-agent → docker restart → completed.
 Pierwszy w historii systemu pełny cykl remediacji end-to-end potwierdzony w
 produkcji (PIHA), bez SSH z control-plane do węzłów. Publiczna dziura
 autoryzacji na `operator_ui.py:18180` zamknięta (bind ograniczony do
-Tailscale). Otwarte follow-upy — patrz `kb/phases/backlog.md` (retry-w-nieskończoność
+Tailscale). Otwarte follow-upy — patrz `docs/backlog.md` (retry-w-nieskończoność
 zepsutego JSON, uprawnienia `actions/` na innych węzłach, brak twardego checka
 `.env`/`TAILSCALE_BIND_IP` w `deploy-local.sh`, brak autoryzacji w
 `operator_ui.py`, zapchana approval queue przez `alert_only`, brak

docs/sessions/2026-07-23-ha-faza1-otwarta.md

@@ -1,12 +1,3 @@
----
-okf: "0.1"
-type: session-log
-visibility: private
-status: active
-updated: 2026-07-23
-links: []
----
-
 # 2026-07-22/23 — HA: adapter api, import ken, deploy.sh, otwarcie fazy 1
 
 ## Wykonane

docs/sessions/2026-07-23-ha-klima-audyt-fixpack.md

@@ -1,12 +1,3 @@
----
-okf: "0.1"
-type: session-log
-visibility: private
-status: active
-updated: 2026-07-23
-links: []
----
-
 # 2026-07-23 (cd.) — HA: klima E2E, audyt Fable, fix-pack 1
 
 ## Klima salonowa — pierwsza automatyzacja LLM przez repo (E2E)

docs/sessions/2026-07-23-kb-f4-ingress.md

@@ -1,15 +1,6 @@
----
-okf: "0.1"
-type: session-log
-visibility: private
-status: active
-updated: 2026-07-23
-links: []
----
-
 # Sesja 2026-07-23 — KB faza 4: ingress kb.kapala.org (krok 5/§8)
 
-**Zakres**: wyłącznie ingress (`kb/phases/kb-m5-faza4.md` §8, krok 5) —
+**Zakres**: wyłącznie ingress (`docs/kb/modules/05-faza4-plan.md` §8, krok 5) —
 frontend i `/search` już LIVE na PIHA (port 8230) od sesji 2026-07-22. Zero
 zmian w kodzie kb-query w tej sesji.
 
@@ -70,8 +61,8 @@ w tej samej sesji, osobnym przebiegiem po zgłoszeniu przez operatora:
 Potwierdzone w repo (zgodnie z `05-faza4-plan.md` §1.4): **brak wzorca
 forward-auth/reverse-proxy-level auth** — NPM community edition go nie ma
 (sprawdzone: brak `oauth2-proxy`/`authelia`/`forward_auth` w kodzie repo poza
-wzmiankami "przyszła opcja" w `kb/subsystems/kb-documents-pillar.md` i
-`kb/nodes/vps.md`). Wszystkie 3 precedensy (paperless/nextcloud/vikunja)
+wzmiankami "przyszła opcja" w `docs/kb/kb-02-documents-design.md` i
+`hosts/vps/README.md`). Wszystkie 3 precedensy (paperless/nextcloud/vikunja)
 robią OIDC **wewnątrz aplikacji**. kb-query nie ma dziś żadnego logowania.
 
 Zgodnie z instrukcją zadania: **nie budowano** nowego komponentu auth.
@@ -122,7 +113,7 @@ username collision, `docs/sessions/2026-07-10-paperless-deploy.md`).
 
 ## Pliki repo zmienione
 
-- `kb/services/kb-query.md` — sekcja "Ingress" (co żyje, co nie, dlaczego
+- `services/kb-query/README.md` — sekcja "Ingress" (co żyje, co nie, dlaczego
   auth odłożone) zastępuje starą notatkę "not wired up yet".
 - `docs/sessions/2026-07-23-kb-f4-ingress.md` — ten dokument.
 

docs/sessions/2026-07-27-ha-porzadki-sonda.md

@@ -1,12 +1,3 @@
----
-okf: "0.1"
-type: session-log
-visibility: private
-status: active
-updated: 2026-07-27
-links: []
----
-
 # 2026-07-27 — HA: legacy zamkniete, kasacje, pimirror, sonda Zigbee
 
 ## Wykonane

docs/sessions/2026-07-27-kb-f4-fallback.md

@@ -1,15 +1,6 @@
----
-okf: "0.1"
-type: session-log
-visibility: private
-status: active
-updated: 2026-07-30
-links: []
----
-
 # Sesja 2026-07-27 — KB faza 4: fallback embed SOLARIA→PIHA (krok 3, ostatni element rdzenia)
 
-> **Dopisek redakcyjny (2026-07-30, dedup — `kb/phases/kb-m5-faza4-fallback-dedup.md`):**
+> **Dopisek redakcyjny (2026-07-30, dedup — `docs/kb/modules/05-fallback-dedup-raport.md`):**
 > implementacja kodu z tej sesji (`app/fallback.py`, branch `task/kb-f4-fallback`, 3d4ee38)
 > została **porzucona** — do mastera weszła równoległa, szersza implementacja tego samego
 > kroku planu (e7625cd, `app/embed_router.py`, 2026-07-29) i to ona biega na PIHA. Ten log
@@ -23,7 +14,7 @@ links: []
 > Z delty brancha uratowano ponadto: `retrieval_eval.py --transport http` (plan §2 D6/§9)
 > i luki testowe T1/T2 przeniesione do `test_embed_router.py`.
 
-**Zakres**: `kb/phases/kb-m5-faza4.md` §2 decyzja 2 / §5 — aktywny fallback
+**Zakres**: `docs/kb/modules/05-faza4-plan.md` §2 decyzja 2 / §5 — aktywny fallback
 embedu, ostatni brakujący element rdzenia fazy 4 (frontend i ingress LIVE od
 2026-07-22/23, `docs/sessions/2026-07-23-kb-f4-ingress.md`). Zero zmian w schemacie
 DB, zero zmian w `kb_retrieval`'s retrieval logice — wyłącznie warstwa embed + health.

docs/sessions/2026-07-28.md

@@ -1,12 +1,3 @@
----
-okf: "0.1"
-type: session-log
-visibility: private
-status: active
-updated: 2026-07-28
-links: []
----
-
 # Session log 2026-07-28
 
 ## Session 21:59
@@ -19,8 +10,8 @@ e8aa3e3 docs(architecture): recon multiagent 2026-07-27
 
 ### Files changed
 ```
- kb/phases/subsystem-a-naprawa.md |  60 +++
- kb/subsystems/recon-multiagent.md | 551 +++++++++++++++++++++++
+ docs/architecture/PLAN-subsystem-a-2026-07-28.md |  60 +++
+ docs/architecture/RECON-multiagent-2026-07-27.md | 551 +++++++++++++++++++++++
  2 files changed, 611 insertions(+)
 ```
 

docs/sessions/2026-07-30-ha-mcp-faza2a.md

@@ -1,12 +1,3 @@
----
-okf: "0.1"
-type: session-log
-visibility: private
-status: active
-updated: 2026-07-30
-links: []
----
-
 # 2026-07-30 — HA: legacy zamknięte, MCP read-only (faza 2a)
 
 ## Legacy — finał

docs/sessions/2026-07-31-kb-f4-final-narty27.md

@@ -1,12 +1,3 @@
----
-okf: "0.1"
-type: session-log
-visibility: private
-status: active
-updated: 2026-08-04
-links: []
----
-
 # Session log 2026-07-31 — KB Faza 4: zamknięcie + pilot narty27
 
 ## Zakres
@@ -22,7 +13,7 @@ pilota fazy 5 (narty27), wykonanego równolegle.
   - session log 27.07
   - testy luk T1–T3
   - komentarz kalibracji progów dist.
-- Pełny rozbiór obu implementacji: `kb/phases/kb-m5-faza4-fallback-dedup.md`.
+- Pełny rozbiór obu implementacji: `docs/kb/modules/05-fallback-dedup-raport.md`.
 
 ### Deploy na PIHA (z mastera)
 - `ollama-piha`: named volume `ollama_piha_models`, model bge-m3, `KEEP_ALIVE=0`.
@@ -76,7 +67,7 @@ infry**. Infra: `services/narty27`.
    stubie nie przechodzi wyłącznie z tego powodu.
 2. **`hosts/solaria/runtime/ollama/docker-compose.override.yml` — brak w repo**
    (rozjazd repo↔runtime na SOLARII).
-3. **R1–R3 node-agent** (incydent `kb/incidents/2026-07-30-ollama-solaria-vanish.md`)
+3. **R1–R3 node-agent** (incydent `docs/incidents/2026-07-30-ollama-solaria-vanish.md`)
    — **niezrobione**: R1 `_prune_stopped_containers` nie może kasować kontenerów
    zarządzanych, R2 rate-limit dla `ai_node`/`standard`, R3 logowanie usuniętych
    zasobów. Przyczyna nadal aktywna → blokuje/warunkuje fazę mailową

docs/stability-agent-rollout.md

@@ -1,15 +1,16 @@
----
-okf: "0.1"
-type: runbook
-visibility: private
-status: active
-updated: 2026-05-17
-links:
-  - ../subsystems/stability-agent-architektura.md
----
-
 # Stability Agent Multi-Node Rollout
 
+## Architecture Summary
+The `stability-agent` is a lightweight Python service that monitors node health (disk, Docker containers, Tailscale, MQTT) and publishes state to a central Redis instance running on **PIHA**.
+
+- **Source**: `services/stability-agent`
+- **State Path**: `/opt/homelab/state`
+- **Events Path**: `/opt/homelab/events`
+- **Redis Target**: `100.108.208.3:6379` (PIHA)
+
+## Why UI only showed CHELSTY
+Previously, the `stability-agent` had `NODE_NAME` defaulted to `chelsty` and was only deployed there. The Agent System UI materializer on PIHA filters nodes based on the Redis keys `homelab:nodes:<NODE_NAME>`. Without other agents publishing their specific `NODE_NAME`, the UI remained limited to the single active node.
+
 ## Deployment
 
 Use the helper script to deploy or generate commands. The script uses explicit Tailscale IPs for remote targets (piha, chelsty, vps) and runs locally for solaria.

docs/standards.md

@@ -1,12 +1,3 @@
----
-okf: "0.1"
-type: subsystem
-visibility: public
-status: active
-updated: 2026-05-20
-links: []
----
-
 # Infrastructure Standards
 
 This document defines the standards and conventions for the homelab GitOps-lite environment.

docs/topology.md

@@ -1,12 +1,3 @@
----
-okf: "0.1"
-type: subsystem
-visibility: private
-status: active
-updated: 2026-05-11
-links: []
----
-
 # Homelab Topology
 
 ## Nodes

docs/vps-control-plane.md

@@ -1,15 +1,3 @@
----
-okf: "0.1"
-type: subsystem
-visibility: private
-status: deprecated
-updated: 2026-05-27
-links:
-  - ../services/control-plane.md
-  - ../runbooks/control-plane-deploy-recovery.md
-superseded_by: "przepisany tor redeploy, commity da151fc/79bfe8c 2026-08-03"
----
-
 # VPS Control Plane
 
 The VPS Control Plane is the orchestration brain of the homelab platform. It runs on the Hetzner VPS (Tailscale IP: `100.95.58.48`) and provides observability, automated reconciliation, and a web-based operator interface.
@@ -60,6 +48,32 @@ The supervisor supports a `NODE_ALIAS_MAP` environment variable (JSON string) to
 NODE_ALIAS_MAP='{"node-2": "chelsty-infra", "node-1": "piha"}'
 ```
 
+## Deployment
+
+### From SATURN (primary control node)
+```bash
+# Full deploy via SSH
+./scripts/deploy/deploy-control-plane.sh --ssh
+
+# Or manually:
+ssh oskar@100.95.58.48 "cd ~/homelab-codex-ws && git pull origin master && cd services/control-plane && docker compose up -d --build --force-recreate"
+```
+
+### Direct on VPS
+```bash
+cd ~/homelab-codex-ws/services/control-plane
+docker compose up -d --build --force-recreate
+```
+
+`deploy-local.sh` also creates the required `/opt/homelab/` directory structure and sets ownership to UID 1000 (requires `sudo`). If directories already exist, skip to the `docker compose` step directly.
+
+### Verification
+```bash
+# On VPS
+docker ps --filter "name=control-plane"
+curl -s http://localhost:18180/summary | python3 -m json.tool
+```
+
 ## Action Approval Workflow
 
 ```
@@ -73,6 +87,28 @@ Supervisor writes → /opt/homelab/actions/pending/<id>.json
 Possible action states: `pending → approved → running → completed / failed / rejected`  
 Auto-cancel path: `pending → cancelled/`
 
+## Recovery
+
+### World state is stale or corrupt
+```bash
+# On VPS — delete checkpoint to force full replay
+rm /opt/homelab/state/observer_checkpoint.json
+docker restart control-plane-observer
+```
+
+### Flood of pending actions after bootstrap
+Check if node-agent is running and emitting `service_healthy` events on each node. Without `service_healthy`, the supervisor sees all services as missing and queues redeployments every cycle.
+
+```bash
+# Check node-agent on each node
+ssh oskar@<node> "docker ps --filter name=node-agent && docker logs node-agent --tail 20"
+```
+
+### Rebuild from scratch
+```bash
+ssh oskar@100.95.58.48 "cd ~/homelab-codex-ws/services/control-plane && docker compose up -d --build --force-recreate"
+```
+
 ## Integration
 
 ### piha agent-system webui (port 18180 on piha)

hardware/esp/ir-ac-ha-integration/README.md

@@ -1,12 +1,3 @@
----
-okf: "0.1"
-type: service
-visibility: private
-status: active
-updated: 2026-07-17
-links: []
----
-
 # Gree IR Blaster
 
 ESPHome firmware for a Wemos D1 Mini (ESP8266) driving a Gree air conditioner

hosts/chelsty-infra/README.md

@@ -1,5 +0,0 @@
-# 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)