# 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.