From f41ec5d0c5b24ef62cb1fe0f87d8105c55ed970e Mon Sep 17 00:00:00 2001 From: Oskar Kapala Date: Fri, 29 May 2026 14:17:23 +0200 Subject: [PATCH] docs: compress CLAUDE.md + fix zigbee2mqtt coordinator docs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - CLAUDE.md: collapsed 5-section deployment block to single annotated block, removed inline emit_event signatures (kept path + type list), flattened runtime path tree to bullets, condensed node table note to reference capabilities.yaml, added CHELSTY docker-compose v1 constraint; 156 → 113 lines (~750 → ~480 tokens) - fix: zigbee2mqtt/README.md updated to TCP coordinator (SLZB-06U at 192.168.1.105:6638, ezsp); removed stale /dev/ttyACM0 USB reference and corrected owner node from piha to chelsty-infra Co-Authored-By: Claude Sonnet 4.6 --- CLAUDE.md | 87 +++++++++------------------------- services/zigbee2mqtt/README.md | 6 ++- 2 files changed, 26 insertions(+), 67 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index a459b5c..fe9d251 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -17,43 +17,22 @@ GitOps-lite orchestration for a distributed homelab. The repo is the source of t | **CHELSTY-INFRA** | LTE edge hypervisor (site: chelsty); Zigbee2MQTT, Mosquitto, stability-agent — offline-first | | **CHELSTY-HA** | LTE Home Assistant VM (site: chelsty); connects to CHELSTY-INFRA MQTT broker — offline-first | -All nodes communicate over Tailscale. CHELSTY-INFRA and CHELSTY-HA have an intermittent LTE uplink; their services (`zigbee2mqtt`, `mosquitto`, `homeassistant`, `stability-agent`) must never depend on SATURN, VPS, or Forgejo at runtime. +All nodes communicate over Tailscale. CHELSTY-INFRA and CHELSTY-HA have an intermittent LTE uplink; their services must never depend on SATURN, VPS, or Forgejo at runtime. Full node capabilities: `hosts//capabilities.yaml`. ## Deployment -### Run a fresh deployment on the current node ```bash -scripts/deploy/deploy.sh +scripts/deploy/deploy.sh # fresh deploy on current node +scripts/deploy/deploy.sh --resume # resume after interruption +scripts/deploy/deploy.sh --stage verify # specific stage only +scripts/deploy/deploy.sh --service mosquitto # specific service only +./scripts/deploy/deploy-control-plane.sh --ssh # SATURN/SOLARIA → VPS +./scripts/deploy/deploy-node.sh chelsty-infra # CHELSTY nodes (individually) +./scripts/bootstrap/prepare-node.sh # general node bootstrap +./scripts/bootstrap/chelsty-runtime.sh # CHELSTY-specific bootstrap ``` -### Resume after interruption -```bash -scripts/deploy/deploy.sh --resume -``` - -### Run a specific stage only -```bash -scripts/deploy/deploy.sh --stage verify -scripts/deploy/deploy.sh --stage diagnose -``` - -### Deploy a specific service -```bash -scripts/deploy/deploy.sh --service mosquitto -``` - -### Deploy from SATURN/SOLARIA to VPS (control plane) -```bash -./scripts/deploy/deploy-control-plane.sh --ssh -``` - -### Bootstrap a new node -```bash -./scripts/bootstrap/chelsty-runtime.sh # CHELSTY-specific -./scripts/bootstrap/prepare-node.sh # General node prep -``` - -The staged deploy pipeline runs: **prepare → validate → deploy → verify → diagnose (on failure) → complete**. Stage state is persisted in `/opt/homelab/state/deploy/` allowing safe resumption. +Pipeline stages: **prepare → validate → deploy → verify → diagnose (on failure) → complete**. Stage state persisted in `/opt/homelab/state/deploy/`. ## Service Structure @@ -94,22 +73,9 @@ Agents must never execute destructive actions (restarts, deploys, config changes ## Event System -Events are append-only JSON lines at: -``` -/opt/homelab/events/YYYY-MM-DD//events.jsonl -``` +Events are append-only JSON lines at `/opt/homelab/events/YYYY-MM-DD//events.jsonl`. -Emit from shell: -```bash -source scripts/lib/events.sh -emit_event "deployment_started" "info" "my-script.sh" "mosquitto" "cid-123" '{}' -``` - -Emit from Python: -```python -from scripts.lib.events import emit_event -emit_event("service_unhealthy", "error", "monitor.py", "ollama", "cid-123", {"error": "OOM"}) -``` +Emit via `scripts/lib/events.sh` (shell) or `scripts/lib/events.py` (Python). Normalized event types: `deployment_started/completed/failed`, `service_unhealthy/recovered`, `node_offline/online`, `healthcheck_failed`, `remediation_started/completed`. @@ -124,29 +90,20 @@ When exploring the system, use these files in order: ## CHELSTY-Specific Rules - Zigbee coordinator is **SLZB-06U** over TCP (`192.168.1.105:6638`, `ezsp` adapter). Never use `/dev/ttyUSB0`. -- Deploy CHELSTY nodes individually: - ```bash - ./scripts/deploy/deploy-node.sh chelsty-infra - ./scripts/deploy/deploy-node.sh chelsty-ha - ``` -- Bootstrap CHELSTY runtime: - ```bash - ./scripts/bootstrap/chelsty-runtime.sh - ``` +- CHELSTY nodes run **docker-compose v1** (1.29.2) — use `docker-compose` (hyphenated), not `docker compose`. - Critical backup sets: HA config+data, Zigbee2MQTT config+db+network key, Mosquitto config+persistence, SLZB-06U coordinator state. ## Runtime Path Conventions -``` -/opt/homelab/ -├── data// # Persistent volumes -├── config// # Secrets and host-local overrides (not in Git) -├── logs// # Service logs -├── state/ # Deployment stage markers, agent heartbeats -├── events/ # Append-only event store -├── world/ # Observer output (synthesized state) -└── actions/ # pending / approved / running / completed / failed -``` +`/opt/homelab/` layout on each node: + +- `data//` — persistent volumes +- `config//` — secrets and host-local overrides (not in Git) +- `logs//` — service logs +- `state/` — deployment stage markers, agent heartbeats +- `events/` — append-only event store +- `world/` — Observer output (synthesized state) +- `actions/` — pending / approved / running / completed / failed ## Naming Conventions diff --git a/services/zigbee2mqtt/README.md b/services/zigbee2mqtt/README.md index 2dc017d..2f6826a 100644 --- a/services/zigbee2mqtt/README.md +++ b/services/zigbee2mqtt/README.md @@ -3,8 +3,10 @@ Zigbee to MQTT bridge, get rid of your proprietary Zigbee bridges. ## Usage -Deployed on the `piha` node. -Requires a Zigbee adapter (e.g., Sonoff ZBDongle-E) mapped to `/dev/ttyACM0`. +Deployed on the `chelsty-infra` node (CHELSTY site). + +Coordinator: **SLZB-06U** over TCP at `192.168.1.105:6638` (`ezsp` adapter). +Do not use USB paths (`/dev/ttyUSB0`, `/dev/ttyACM0`) — the coordinator is network-attached. Frontend is available on port 8080.