# Felhom — Documentation

Felhom is a managed home-server service for Hungarian households, built on a **three-component model**
over Proxmox:

- **Hub** — operator backend on k3s (`hub.felhom.eu`). Repo: `felhom.eu/hub/`.
- **Host agent** — one per Proxmox host; operator-tier; owns all Proxmox interaction. Repo: `felhom-agent/`.
- **In-guest controller** — one per customer LXC; Docker-only; manages the customer's apps. Repo: `felhom-controller/`.

This directory is the central, code-verified documentation home for all three components plus the
platform and the security-audit record.

## Sections

### Controller (in-guest) — `controller/`
The Docker-only app-domain controller. Full per-area docs grounded in current source (v0.59.0).
→ [`controller/README.md`](controller/README.md): module map, deploy & stack lifecycle, backup
architecture, storage/monitoring/metrics, auth/hub/sync/integrations.

### Host agent & platform — `architecture/`, `proxmox-platform.md`
The operator-tier agent and the Proxmox platform.
- [`architecture/01-topology-and-trust.md`](architecture/01-topology-and-trust.md) — topology & trust model
- [`architecture/03-host-agent.md`](architecture/03-host-agent.md) — the host agent (Go; v0.29.1)
- [`architecture/04-control-plane-authorization.md`](architecture/04-control-plane-authorization.md) — signing, escrow, authz
- [`architecture/02-controller-module-map.md`](architecture/02-controller-module-map.md) — **historical** v0.33 planning map; the live map is [`controller/module-map.md`](controller/module-map.md)
- [`proxmox-platform.md`](proxmox-platform.md) — Proxmox platform reference

### Hub (operator backend) — `architecture/05`
- [`architecture/05-hub-architecture.md`](architecture/05-hub-architecture.md) — hub architecture (v0.11.0)

### Security audits & remediation — `audits/`
- [`audits/deep-sweep-2026-06-13.md`](audits/deep-sweep-2026-06-13.md) — cross-repo deep audit (controller + agent) with remediation status
- [`audits/bughunt-reconcile-2026-06-13.md`](audits/bughunt-reconcile-2026-06-13.md) — reconciliation of the v0.30.3 BUGHUNT against current code + merged fix list

### Spike & test findings — `tests/`
Per-slice spike/validation findings (phases 0–5, slices 7–10). See [`tests/`](tests/).

## Conventions

- **Code-verified, not memory-derived.** Architectural claims here are checked against the actual
  current source; if a claim can't be verified it is omitted and flagged, not guessed.
- Per-repo operational working files (`CLAUDE.md`, `CONTEXT.md`, `CHANGELOG.md`, `BUGHUNT.md`,
  `REPORT.md`, `TASK.md`) live in their own repos — they are operational, not published docs.
- Authoritative versions at last refresh: controller **v0.59.0**, agent **v0.29.1**, hub **v0.11.0**.