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>

AGENTS.md

@@ -0,0 +1,89 @@
+# AGENTS.md — orientation for any agent on a homelab client
+
+You are running on a machine that is part of the **hubris** homelab. The full
+context is in this checkout at `/opt/homelab-context/`. This file is the entry
+point. Read it once at start, then keep working.
+
+## 1. Who you are
+
+Run `hostname` (Linux) or `scutil --get LocalHostName` (macOS), then read:
+
+    /opt/homelab-context/hosts/<your-hostname>.yaml
+
+That file tells you your role, your peers, what's mounted, and what services
+you host. If it does not exist, this client was not enrolled — stop and tell
+the operator to run `homelab client add <hostname>` from an existing client.
+
+## 2. The topology
+
+- `/opt/homelab-context/inventory.yaml` — every host, LXC, VM, and workstation
+  with their mesh addresses, roles, and service mappings. Treat this file as
+  authoritative; anything you read in narrative pages should agree with it.
+- `/opt/homelab-context/infrastructure/mesh.md` — Tailscale → Netbird state.
+  Both meshes are accepted today; Netbird is preferred for new traffic.
+- `/opt/homelab-context/infrastructure/dns.md` — split-horizon DNS via
+  dnsmasq on LXC 124. `*.hubris.network` resolves to 192.168.x.x on the LAN
+  and to mesh addresses off-LAN.
+- `/opt/homelab-context/operations/commands.md` — the operator's cheatsheet
+  for pct, caddy, dnsmasq. Use these verbs when you take actions.
+
+## 3. The MCP server
+
+The homelab exposes a Model Context Protocol server with structured tools.
+Endpoint is in `inventory.yaml` under `services.homelab_mcp.endpoint`.
+
+Available tools:
+
+  Context (pure read):
+    get_host(name), list_services(), find_service(name_or_role),
+    get_topology(), search_docs(query), get_page(path),
+    get_changelog(page, since?), whoami(hostname),
+    list_my_secrets(caller_pubkey?)
+
+  Management (read-only):
+    get_service_status(service), tail_log(service, lines=200),
+    list_lxcs(), get_lxc_state(lxc), ping_service(service)
+
+Mutations are **not** exposed via MCP. Use the `homelab` CLI for those, with
+operator confirmation.
+
+**When to prefer MCP over grepping the clone:** any time you need to resolve a
+name to an address, look up service status, or search the wiki by content.
+Grep is fine for browsing or when MCP is unreachable.
+
+## 4. Wiki conventions
+
+- Pages live under `containers/`, `hosts/`, `vms/`, `infrastructure/`,
+  `investigations/`, `operations/`. Cross-link liberally; orphans are bugs.
+- Every page ends with a `## Changelog` section, entries in reverse-chrono
+  order:
+
+      ### YYYY-MM-DD — short title
+      one or two lines describing what changed and why.
+
+- Investigation files are dated and slugged: `YYYY-MM-DD-slug.md`.
+- Live state takes precedence over docs. If you observe a discrepancy, update
+  the docs *in the same session* (per the same-session update rule).
+
+## 5. Acting on the homelab
+
+- **Read state**: prefer MCP tools, then files, then shell. Examples:
+  `homelab whoami`, `homelab list`, `homelab status`, `homelab logs caddy`.
+- **Cross-host actions** (caddy reload, pct exec, etc.): use the `homelab`
+  CLI — it resolves hostname → mesh address → ssh / pct path for you. Direct
+  SSH still works; the CLI just removes the lookup burden.
+- **Secrets**: never hardcode. Call `homelab secret <name>` to decrypt on
+  demand using the per-client age key at `/etc/age/key.txt`. Secrets ARE
+  available in this system — `list_my_secrets()` (MCP) shows what you can
+  decrypt.
+- **Mutations** (restart, edit configs, etc.): the `homelab` CLI's mutating
+  subcommands ask for confirmation. For ad-hoc work, SSH and edit directly —
+  but commit changes that touch tracked configs (caddy, gitea custom,
+  artifacto, mule-image, etc.; see `infrastructure/auto-deploy.md`).
+- **Wiki updates**: same-session rule applies to any meaningful state change
+  this client makes.
+
+## 6. When in doubt
+
+Run `homelab mcp search_docs <query>` or `homelab mcp get_host <name>`.
+The clone is the fallback; MCP is the index.