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>

secrets/README.md

@@ -0,0 +1,63 @@
+# secrets/
+
+SOPS-encrypted YAML files. The plaintext lives only in transit and in the
+operator's head — committed files are always ciphertext.
+
+## Conventions
+
+- One file per logical grouping (e.g. `gitea-tokens.yaml`, `webhook-hmacs.yaml`,
+  `api-keys.yaml`).
+- Recipients are declared in `../.sops.yaml` by path-regex, not per-file.
+- The plaintext schema inside each file is free-form YAML; the consumer code
+  decides what it expects (e.g. `gitea-tokens.yaml` contains
+  `{"<host>": "ghp_xxx"}`).
+
+## How to add a secret
+
+```bash
+# 1. Decide which clients should be able to decrypt it; edit ../.sops.yaml to
+#    list their age public keys for the new path_regex.
+# 2. Create the plaintext, encrypt in place:
+sops -e --in-place secrets/my-thing.yaml
+# 3. Commit + push. The 5-min sync propagates to every recipient.
+```
+
+## How to consume a secret
+
+```bash
+# On any client that's a recipient:
+homelab secret my-thing               # prints plaintext
+# Or programmatically:
+sops -d /opt/homelab-context/secrets/my-thing.yaml
+```
+
+The `mcp` tool `list_my_secrets(caller_pubkey)` returns the names of secrets
+the caller can decrypt. The MCP server never reads plaintext — decryption
+stays client-side.
+
+## Granting / revoking access
+
+To grant a new recipient: edit `../.sops.yaml` to add their age pubkey, then
+re-key every affected file:
+
+```bash
+sops updatekeys -y secrets/my-thing.yaml
+```
+
+To revoke: remove the recipient from `../.sops.yaml` and `sops updatekeys` —
+but remember this only protects future ciphertext. Past plaintext the client
+already decrypted is gone from your control. Rotate the underlying credential
+if compromise is suspected.
+
+`homelab client remove <name>` does the recipient removal + `updatekeys` for
+you, and prints the rotation checklist as a follow-up.
+
+## hello.yaml — bootstrap decrypt test
+
+`secrets/hello.yaml` is encrypted to every enrolled client. Used by Phase 3a
+verification to confirm the end-to-end decrypt path works on a freshly-
+bootstrapped machine. Content is intentionally trivial:
+
+```yaml
+greeting: hello from the homelab
+```