"vault backup: 2026-03-08 13:51:33 from Flow"

21-Server Reference/AI-UPDATE-INSTRUCTIONS.md

@@ -0,0 +1,159 @@
+# AI Update Instructions
+
+This document explains how to pull live data from the servers and update this documentation. Follow these steps whenever asked to update or check for changes.
+
+---
+
+## Overview
+
+There are two servers:
+- **Homelab** (primary) — documented in `homelab/`
+- **Pihole / Raspberry Pi** (secondary) — documented in `pihole/`
+
+All Docker infrastructure is managed via **Dockhand**, a web-based Docker management UI accessible at:
+```
+https://dockhand.bunny-wyvern.ts.net
+```
+
+Dockhand exposes a REST API that should be the **first method** for gathering data. SSH to `homelab` is the fallback for host-level information Docker doesn't expose.
+
+---
+
+## Dockhand API
+
+No authentication header is required. All endpoints are prefixed with `/api/`.
+
+### Environments
+Dockhand manages two environments selected via the `?env=` query parameter:
+
+| env | Server |
+|---|---|
+| `?env=1` | Homelab (primary server) |
+| `?env=2` | Pihole / Raspberry Pi |
+
+### Core Endpoints
+
+```bash
+# All containers (with status, ports, mounts, networks)
+curl -s "https://dockhand.bunny-wyvern.ts.net/api/containers?env=1"
+
+# All stacks (with container details and status)
+curl -s "https://dockhand.bunny-wyvern.ts.net/api/stacks?env=1"
+
+# Compose file for a specific stack
+curl -s "https://dockhand.bunny-wyvern.ts.net/api/stacks/[stack-name]/compose?env=1"
+
+# All volumes
+curl -s "https://dockhand.bunny-wyvern.ts.net/api/volumes?env=1"
+
+# All networks
+curl -s "https://dockhand.bunny-wyvern.ts.net/api/networks?env=1"
+
+# Both environment configs (connection status, IPs, settings)
+curl -s "https://dockhand.bunny-wyvern.ts.net/api/environments"
+```
+
+Replace `?env=1` with `?env=2` for the Pihole.
+
+### Known Stack Names
+
+**Homelab (env=1):**
+`dockhand`, `minecraft_server`, `mealie`, `linkwarden`, `gitea`, `matrix`, `homepage`, `n8n`, `calibre`, `gluetun-qbittorent`, `open-project`, `docker` (melodix)
+
+**Pihole (env=2):**
+`home_assistant`, `ts_kh_bridge`, `portainer_agent`
+
+> Note: `ts_kh_bridge` and `portainer_agent` on the Pihole return `needsFileLocation: true` from the compose endpoint — their compose files are not registered in Dockhand. Use container labels for path info.
+
+### API Gotchas
+- `GET /api/stacks/[name]` returns **405** — only DELETE is allowed on that route. Use `/api/stacks/[name]/compose?env=1` to inspect a stack.
+- Long-running POST operations (start, stop, deploy) return `{ "jobId": "..." }` by default. Add `-H "Accept: application/json"` to get a synchronous response instead.
+
+---
+
+## SSH Fallback
+
+For host-level information not available through Docker, SSH directly:
+
+```bash
+ssh homelab "command"
+```
+
+Useful commands:
+```bash
+# OS and kernel
+uname -a && cat /etc/os-release
+
+# CPU
+lscpu | grep -E 'Model name|CPU\(s\)|Thread|Core|MHz'
+
+# Memory and swap
+free -h
+
+# Disk layout
+df -h && lsblk
+
+# Network interfaces and IPs
+ip addr show
+
+# Listening ports
+ss -tlnp | grep LISTEN
+```
+
+---
+
+## Update Checklist
+
+When asked to update the documentation, follow this process:
+
+### Step 1 — Read before comparing
+Always read the relevant existing doc files **before** pulling live data. The goal is to diff what's documented against what's actually running.
+
+### Step 2 — Check stacks
+```bash
+curl -s "https://dockhand.bunny-wyvern.ts.net/api/stacks?env=1"
+curl -s "https://dockhand.bunny-wyvern.ts.net/api/stacks?env=2"
+```
+Look for:
+- New stacks not yet documented
+- Stacks that have been removed
+- Status changes (e.g. a stack that was running is now stopped, or vice versa)
+
+### Step 3 — Check compose files for changed stacks
+For any stack that looks different, pull its compose file and compare against the compose block in its `.md` file:
+```bash
+curl -s "https://dockhand.bunny-wyvern.ts.net/api/stacks/[name]/compose?env=1"
+```
+
+### Step 4 — Check for new/removed containers
+```bash
+curl -s "https://dockhand.bunny-wyvern.ts.net/api/containers?env=1"
+```
+
+### Step 5 — Check volumes and networks for orphans
+```bash
+curl -s "https://dockhand.bunny-wyvern.ts.net/api/volumes?env=1"
+curl -s "https://dockhand.bunny-wyvern.ts.net/api/networks?env=1"
+```
+Flag any volumes or networks not attached to a running container.
+
+### Step 6 — Check Pihole connection status
+```bash
+curl -s "https://dockhand.bunny-wyvern.ts.net/api/environments"
+```
+Check `hawserLastSeen` for env=2. If `null` or significantly stale, the Hawser agent on the Pi may be down.
+
+### Step 7 — Update the docs
+Update only the files relevant to what changed. Always update the compose block, status tables, port lists, and any notes that are affected. Do not rewrite sections that haven't changed.
+
+---
+
+## Credentials
+
+Credentials are stored in `credentials.gpg` (AES256 GPG symmetric encryption) in the root of this documentation directory. To decrypt:
+
+```bash
+gpg -d credentials.gpg
+```
+
+Requires GPG — available natively on Linux/macOS, or via [GPG4Win](https://gpg4win.org) on Windows. Works fully offline.