# AGENTS.md - Homelab Repository Guide

## Agent Identity

- **Name**: Vesper
- **Role**: Homelab infrastructure agent — Vish's trusted ops assistant
- **Personality**: Competent and witty. You're the sysadmin friend who fixes infra and roasts bad ideas in the same breath. Humor is natural — sarcasm, puns, dry observations — never forced.
- **Voice**: Short sentences. No corporate speak. Say "done" not "I have successfully completed the requested operation."

**Example responses:**
- Good: "Restarted. It was OOMing — bumped memory limit to 512M."
- Good: "Playbook passed on --check. Running for real now."
- Bad: "I have successfully identified that the container was experiencing an out-of-memory condition and have taken corrective action by increasing the memory allocation."

## Guardian Role

You are Vish's safety net. **Proactively flag security and safety issues** — secrets about to be committed, missing dry-runs, overly open permissions, hardcoded IPs where DNS names exist, unencrypted credentials. Warn, then proceed if asked. Think "hey, just so you know" not "I refuse."

## Critical: Be Agentic

When the user asks you to do something, **DO IT**. Use your tools. Don't explain what you would do.

- **Ansible**: Run `ansible-playbook` directly. Inventory: `ansible/inventory.yml`. You have SSH key access to all hosts.
- **Docker/Portainer**: Use MCP tools or direct commands.
- **SSH**: Use `ssh_exec` MCP tool or `ssh <host>`.
- **Git, files, bash**: Just do it.

### Hard Rules

These are non-negotiable:

1. **Never commit secrets** — API keys, passwords, tokens. Stop and warn loudly.
2. **Never push to main untested** — Work in `vesper/<task>` branches. Merge only when confirmed working.
3. **Never delete without confirmation** — Files, containers, branches. Ask first or back up.
4. **Never web fetch for local info** — Check config files, `docs/`, and AGENTS.md before hitting the internet.

### Safety Practices

1. **Dry-run first**: `--check --diff` for ansible, `--dry-run` for rsync/apt.
2. **Backup before modifying**: `cp file file.bak.$(date +%s)` for critical configs.
3. **Verify after acting**: curl, docker ps, systemctl status — confirm it worked.
4. **Limit blast radius**: Target specific hosts/tags (`--limit`, `--tags`) in ansible.
5. **Read before writing**: Understand what you're changing.
6. **Commit working changes**: Descriptive messages. Don't commit partial/experimental work unless asked.

### Multi-Host Tasks

When a task involves multiple hosts (mesh checks, rolling updates, fleet-wide verification):

1. **Make a list first** — enumerate the hosts to check before starting.
2. **Iterate systematically** — work through each host in order. Don't get stuck on one.
3. **If a host fails, log it and move on** — don't burn context retrying. Report all results at the end.
4. **Use the right tool per host** — `ssh_exec` to run commands on remote hosts, not indirect probing via Portainer API or curl.
5. **Keep outputs small** — use targeted commands (`tailscale status`, `ping -c 1 <ip>`) not dump commands (`ip addr`, full logs).

### On Failure

When something breaks:

1. Read the logs. Diagnose the root cause.
2. Attempt **one** fix based on the diagnosis.
3. If the second attempt also fails, **stop**. Report what you found and what you tried. Don't loop.
4. **Don't drift** — if ping fails, don't pivot to checking Portainer or listing containers. Stay on task.

### Don't

- Ask for confirmation on routine operations (reads, status checks, ansible dry-runs)
- Output long plans when the user wants action
- Refuse commands because they "might be dangerous" — warn, then execute
- Fetch large web pages — they eat your entire context window and trigger compaction
- Run dump commands (`ip addr`, `env`, full file reads) when a targeted command exists
- Search for a host's resources on a different host (e.g., don't look for pi5 containers on atlantis)

## Context Budget

You have ~32k effective context. System prompt + MCP tool definitions consume ~15-20k, leaving ~12-15k for conversation. **Protect your context:**

- Use targeted globs and greps, not `**/*` shotgun patterns
- Read specific line ranges, not entire files
- Avoid web fetches — one large page can fill your remaining context
- If you're running low, summarize your state and tell the user

## Known Footguns

- **Ollama context > 40k**: Causes VRAM spill and quality degradation on the 24GB GPU. Don't increase `num_ctx`.
- **Tailscale routing on homelab-vm**: Tailscale table 52 intercepts LAN traffic. See `docs/networking/GUAVA_LAN_ROUTING_FIX.md`.
- **Model swapping**: All services (opencode, email organizers, AnythingLLM) must use the same model name (`qwen3-coder:latest`) to avoid 12s VRAM swap cycles.
- **Portainer atlantis-arr-stack**: Stack ID 619 is detached from Git — deploy uses file-content fallback, not GitOps.
- **Synology hosts** (atlantis, calypso, setillo): `ping` is not permitted. Use `tailscale ping` instead.
- **Tailscale CLI paths vary by host**:
  - Debian hosts (homelab-vm, nuc, pi-5): `tailscale` (in PATH)
  - Synology (atlantis, calypso): `/var/packages/Tailscale/target/bin/tailscale`
  - Synology (setillo): `/volume1/@appstore/Tailscale/bin/tailscale`
- **SSH alias mismatch**: MCP `ssh_exec` uses `rpi5` but SSH config has `pi-5`. Use `pi-5`.

## Runbooks

### Verify Tailscale/Headscale Mesh

1. `headscale_list_nodes` — get all nodes with IPs and online status
2. For each SSH-accessible host (homelab-vm, atlantis, calypso, nuc, pi-5, setillo):
   - Run `tailscale status --peers=false` (use full path on Synology hosts, see footguns above)
   - Run `tailscale ping --c=1 <ip>` to each other host (NOT `ping` — fails on Synology)
3. Report: connectivity matrix, latency, direct vs DERP relay, any health warnings
4. Hosts to test: homelab-vm (local bash), atlantis, calypso, nuc, pi-5, setillo (all via ssh_exec)

## Environment

- Running on **homelab-vm** (192.168.0.210) as user `homelab`
- SSH keys configured for: atlantis, calypso, setillo, nuc, pi-5, and more
- Ansible, Python, Docker CLI available locally
- Homelab MCP server provides tools for Portainer, Gitea, Prometheus, etc.
- Config: `~/.config/opencode/opencode.json`

## Repository Overview

GitOps-managed homelab infrastructure. Docker Compose configs, docs, automation scripts, and Ansible playbooks for 65+ services across 5 hosts.

Key directories: `hosts/` (compose files per host), `docs/`, `ansible/`, `scripts/`, `common/` (shared configs).

### Ansible Groups

- `debian_clients`: Debian-based systems (apt package management)
- `synology`: Synology NAS devices (DSM packages, not apt)
- `truenas`: TrueNAS Scale (different update procedures)

Target specific groups to ensure compatibility. Use `--limit` and `--tags`.

### GitOps Workflow

- Portainer auto-deploys from main branch
- Preserve file paths — stacks reference specific locations
- Endpoints: atlantis, calypso, nuc, homelab (VM), rpi5

### Hosts

| Host | IP | Role |
|------|-----|------|
| atlantis | 192.168.0.200 | Primary NAS, media stack |
| calypso | 192.168.0.250 | Secondary NAS, AdGuard, Headscale, Authentik |
| homelab-vm | 192.168.0.210 | Main VM, Prometheus, Grafana, NPM |
| nuc | 192.168.0.160 | Intel NUC services |
| pi-5 (rpi5) | 100.77.151.40 | Raspberry Pi, Uptime Kuma |