Phase 1: cross-client homelab context + MCP scaffolding

Add the foundation for distributing homelab context to every client
(LXCs, VMs, workstations including republic-laptop, mac-mini, ludo-mini)
with a single source of truth, structured query layer (MCP), and per-client
age-key issuance for secrets:

- inventory.yaml — canonical topology (hosts, services, mesh addresses)
- hosts/*.yaml — per-host identity files generated from inventory by
  mcp/build_host_files.py; do not edit by hand
- AGENTS.md — orientation doc symlinked to /root/AGENTS.md on every client
- bootstrap.sh — one-shot enroll (Linux + macOS), clones repo, fetches age
  key from issuance, installs sync timer/launchd job, drops the homelab CLI
- bin/homelab — single-binary Python CLI: whoami, list, ssh, pct, logs,
  restart, open, status, secret, sync, mcp, client add/remove, nuke
- mcp/server.py — FastMCP server: context tools + read-only management
  tools (no mutations exposed); shell-outs use mcp-reader restricted ssh key
- mcp/deploy/ — claudio-monitor-style gitea webhook deploy scaffold for the
  MCP service on LXC 105 (ports 9810 mcp, 9811 webhook)
- secrets-issuance/ — per-client age key auto-provisioning over the mesh;
  source-IP gated against inventory, with denylist for revoked clients
  (ports 9820 issue, 9821 webhook)
- secrets/, .sops.yaml — SOPS recipient scaffolding; the operator fills in
  age public keys after Phase 3a generates them
- scripts/sync/ — systemd timer (Linux) + launchd plist (macOS) pulling
  /opt/homelab-context every 5 min

Mesh: both Netbird (preferred, 100.122.0.0/16) and Tailscale accepted
during the in-flight migration; no client is gated on completing the move.

Plan reference: /root/.claude/plans/lets-make-a-plan-fluttering-trinket.md

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

mcp/build_host_files.py

@@ -0,0 +1,158 @@
+#!/usr/bin/env python3
+"""
+Generate hosts/<name>.yaml from inventory.yaml.
+
+Run from the repo root:
+    python3 mcp/build_host_files.py            # writes files, exits non-zero on diff
+    python3 mcp/build_host_files.py --check    # exits non-zero if any output differs
+
+Designed to be wired into a pre-commit hook or Gitea Action so generated
+hosts/*.yaml never drift from inventory.yaml.
+"""
+
+from __future__ import annotations
+
+import argparse
+import difflib
+import os
+import sys
+from pathlib import Path
+
+try:
+    import yaml
+except ImportError:  # pragma: no cover
+    print("PyYAML is required: pip install pyyaml", file=sys.stderr)
+    sys.exit(2)
+
+
+REPO = Path(__file__).resolve().parent.parent
+INVENTORY = REPO / "inventory.yaml"
+HOSTS_DIR = REPO / "hosts"
+
+GENERATED_BANNER = (
+    "# Generated by mcp/build_host_files.py from inventory.yaml.\n"
+    "# Do NOT edit by hand — your changes will be overwritten.\n"
+    "# Source of truth: ../inventory.yaml\n"
+)
+
+
+def narrative_page(name: str, kind: str, pve_id: int | None) -> str | None:
+    """Best-guess path to the human-authored narrative page for this host."""
+    if kind == "proxmox-host":
+        candidate = REPO / "hosts" / f"{name}.md"
+    elif kind == "lxc":
+        candidate = REPO / "containers" / f"{pve_id}-{name}.md"
+    elif kind == "vm":
+        candidate = REPO / "vms" / f"{pve_id}-{name}.md"
+    else:
+        return None
+    if candidate.exists():
+        return str(candidate.relative_to(REPO))
+    return None
+
+
+def build_one(name: str, entry: dict, inventory: dict) -> dict:
+    """Project the entry for a single host into a per-host yaml record."""
+    services = inventory.get("services", {})
+    mesh = inventory.get("mesh", {})
+    pve_id = entry.get("pve_id")
+
+    # Services this host runs: scan inventory.services for matching backend.
+    runs_services = sorted(
+        svc for svc, sentry in services.items()
+        if isinstance(sentry, dict) and sentry.get("backend") == name
+    )
+
+    record = {
+        "name": name,
+        "kind": entry.get("kind"),
+        "os": entry.get("os"),
+        "role": entry.get("role"),
+        "host": entry.get("host"),
+        "pve_id": pve_id,
+        "lan_ip": entry.get("lan_ip"),
+        "mesh": entry.get("mesh", {}),
+        "mesh_globals": {
+            "primary": mesh.get("primary"),
+            "accepted": mesh.get("accepted"),
+        },
+        "peers": entry.get("peers", []),
+        "mounts": entry.get("mounts", []),
+        "public_host": entry.get("public_host"),
+        "public_hosts": entry.get("public_hosts", []),
+        "ssh": entry.get("ssh", {}),
+        "runs": entry.get("runs", []) + runs_services,
+        "services_hosted": [
+            {"name": svc, **services[svc]} for svc in runs_services
+        ],
+        "notes": entry.get("notes", []),
+        "age_pubkey": entry.get("age_pubkey", ""),
+        "see_also": [
+            page for page in [narrative_page(name, entry.get("kind", ""), pve_id)]
+            if page
+        ],
+        "mcp_endpoint": services.get("homelab_mcp", {}).get("endpoint"),
+        "secrets_issuance_endpoint": (
+            services.get("secrets_issuance", {}).get("endpoint")
+        ),
+    }
+    # Strip None and empty containers so the file stays readable.
+    return {k: v for k, v in record.items() if v not in (None, {}, [], "")}
+
+
+def serialize(record: dict) -> str:
+    return GENERATED_BANNER + yaml.safe_dump(
+        record, sort_keys=False, default_flow_style=False, width=100
+    )
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--check", action="store_true",
+                        help="exit 1 if any output would change (don't write)")
+    args = parser.parse_args()
+
+    inventory = yaml.safe_load(INVENTORY.read_text())
+    hosts = inventory.get("hosts", {})
+
+    HOSTS_DIR.mkdir(exist_ok=True)
+    desired: dict[Path, str] = {}
+    for name, entry in hosts.items():
+        desired[HOSTS_DIR / f"{name}.yaml"] = serialize(build_one(name, entry, inventory))
+
+    diff_count = 0
+    for path, content in desired.items():
+        existing = path.read_text() if path.exists() else ""
+        if existing != content:
+            diff_count += 1
+            if args.check:
+                diff = difflib.unified_diff(
+                    existing.splitlines(keepends=True),
+                    content.splitlines(keepends=True),
+                    fromfile=str(path),
+                    tofile=str(path) + " (generated)",
+                )
+                sys.stdout.writelines(diff)
+            else:
+                path.write_text(content)
+                print(f"wrote {path.relative_to(REPO)}")
+
+    # Clean up orphans (file exists but host removed from inventory).
+    for existing_path in HOSTS_DIR.glob("*.yaml"):
+        if existing_path not in desired:
+            diff_count += 1
+            if args.check:
+                print(f"orphan: {existing_path.relative_to(REPO)} (would delete)")
+            else:
+                existing_path.unlink()
+                print(f"deleted orphan {existing_path.relative_to(REPO)}")
+
+    if args.check and diff_count > 0:
+        print(f"\n{diff_count} file(s) would change. Run without --check to write.",
+              file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())