infrapuzzle/AGENTS.md

AGENTS.md

Note

Infrapuzzle is the monorepo for my personal infrastructure, encompassing Kubernetes cluster provisioning, workload deployment, DNS management, and IoT monitoring.

Repository Structure & Documentation

This repository is divided into distinct domains, each with its own AGENTS.md or specialized documentation.

1. Bootstrap (bootstrap/)

• Purpose: Provisioning the single-node Kubernetes cluster (Haumdaucher).
• Tool: Kubespray (Ansible).
• Key File: init.sh (Source of Truth for versioning).
• Read: bootstrap/AGENTS.md

2. Kubernetes Workloads (k8s/)

• Purpose: Deploying applications and services to the cluster.
• Method: GitOps-style directory structure (Namespace = Folder).
• Constraints: Enforces ingress-nginx, cert-manager (Let's Encrypt), and git-crypt for secrets.
• Read: k8s/AGENTS.md

3. Terraform (terraform/)

• Purpose: Infrastructure as Code for external resources, primarily DNS.
• Provider: OVH (ovh/ovh).
• Scope:
  • DNS Zones: haumdaucher.de, moritzgraf.de, ameliegraf.de, and others.
  • Mail Config: Google Workspace MX/SPF/DKIM records.
  • Cluster IP: Points domains to the Haumdaucher node IP (136.243.23.215).
• Usage:

  cd terraform
  terraform init
  terraform apply
  

4. Monitoring (monitoring/)

• Purpose: IoT and physical device monitoring, separate from K8s metrics.
• Tool: ESPHome.
• Devices: Temperature sensors, plant monitors (Xiaomi/BLE), ESP32 bridges.
• Usage:

  cd monitoring
  # Flash or update a device
  esphome run config/<device>.secret.yml
  

• Network: Devices typically operate on static IPs in the 192.168.x.x range.

5. Knowledge Wiki & OpenClaw Tasks (knowledge-wiki/)

• Purpose: Shared personal knowledge wiki and task dispatch between OpenClaw (mobile/Telegram concierge) and Antigravity (local pair programming agent).
• Location: Git submodule knowledge-wiki/ at root of infrapuzzle (Git repo: https://git.moritzgraf.de/moritz/knowledge-wiki.git, branch main).
• Queue File: knowledge-wiki/tasks/antigravity.md.
• Workflow for Antigravity:
  • When the user asks to check tasks or pick up work from OpenClaw:
    1. Pull latest: git submodule update --remote knowledge-wiki (or git -C knowledge-wiki pull --rebase origin main)
    2. Read knowledge-wiki/tasks/antigravity.md to see pending items.
    3. Implement the chosen task in the appropriate repository files.
    4. Move the task to ## ✅ Completed Tasks with completion details and commit info.
    5. Push back: git -C knowledge-wiki commit -am "chore(tasks): complete <task>" && git -C knowledge-wiki push origin main.
  • When Antigravity needs knowledge about family, home, servers, or setup:

6. Architecture Decision Records (docs/adr/)

• Purpose: Formal record of architectural decisions, technical trade-offs, and design standards across the monorepo.
• Format: MADR (Markdown Architectural Decision Records).
• Consulting ADRs: AI agents MUST consult docs/adr/ before designing or altering system architecture, agent topologies, or tool integration patterns.
• Key Records:
  • ADR 0001: Hybrid MCP Tool Search and Subagent Delegation for AI Agents

Global Constraints

• Secrets: git-crypt is used extensively. Ensure you have the unlock key before editing *.secret files.
• Identity:
  • Cluster: haumdaucher
  • Primary Domain: haumdaucher.de
  • User Identity: moritzgraf.de