# AGENTS.md — orientation for any agent on a homelab client

You are running on a machine that is part of the **hubris** homelab. The full
context is in this checkout at `/opt/homelab-context/`. This file is the entry
point. Read it once at start, then keep working.

The operating model — OODA loop, risk classes, approval rules, the ontology,
and node lifecycle — is defined in [OIKOS.md](.agents/OIKOS.md). Before any mutation,
classify the action against `oikos/policy.yaml`; when the class requires
approval, stop and ask the operator.

Agent-facing instruction is separated from human content under `.agents/`:
`.agents/shared/` holds the conventions every agent applies
([writing-style](.agents/shared/writing-style.md), [caveman](.agents/shared/caveman.md),
[page-templates](.agents/shared/page-templates.md), [llm-wiki](.agents/shared/llm-wiki.md)), and
`.agents/domains/` holds the per-domain schemas
([knowledge](.agents/domains/knowledge/schema.md), [operations](.agents/domains/operations/schema.md)).
The narrative wiki lives under `knowledge/wiki/`; the machine-readable substrate
(`inventory.yaml`, `hosts/*.yaml`, `oikos/`) stays at the repo root.

## 1. Who you are

Run `hostname` (Linux) or `scutil --get LocalHostName` (macOS), then read:

    /opt/homelab-context/hosts/<your-hostname>.yaml

That file tells you your role, your peers, what's mounted, and what services
you host. If it does not exist, this client was not enrolled — stop and tell
the operator to run `homelab client add <hostname>` from an existing client.

## 2. The topology

- `/opt/homelab-context/inventory.yaml` — every host, LXC, VM, and workstation
  with their mesh addresses, roles, and service mappings. Treat this file as
  authoritative; anything you read in narrative pages should agree with it.
- `/opt/homelab-context/knowledge/wiki/infrastructure/mesh.md` — Tailscale → Netbird state.
  Both meshes are accepted today; Netbird is preferred for new traffic.
- `/opt/homelab-context/knowledge/wiki/infrastructure/dns.md` — split-horizon DNS via
  Technitium on [dns (107)](knowledge/wiki/containers/107-dns.md). `*.hubris.network`
  resolves to 192.168.x.x on the LAN and to mesh addresses off-LAN.
- `/opt/homelab-context/.agents/operations/commands.md` — the operator's cheatsheet
  for pct, caddy, DNS, and the Oikos command surface. Use these verbs when
  you take actions.

## 3. The MCP server

The homelab exposes a Model Context Protocol server with structured tools.
Endpoint is in `inventory.yaml` under `services.homelab_mcp.endpoint`.

Available tools:

  Context (pure read):
    get_host(name), list_services(), find_service(name_or_role),
    get_topology(), search_docs(query), get_page(path),
    get_changelog(page, since?), whoami(hostname),
    list_my_secrets(caller_pubkey?)

  Management (read-only):
    get_service_status(service), tail_log(service, lines=200),
    list_lxcs(), get_lxc_state(lxc), ping_service(service)

  Oikos (read-only; see OIKOS.md):
    explain(service) — compact context card, cheaper than search_docs+get_page
    preflight(service) — risk class, approval requirement, verification command
    get_relations(entity) — ontology blast-radius query (host: or service: id)
    get_change_history(entity, limit=20) — change-ledger entries
    get_state_snapshot() — last scheduler Observe-pass (health, disk, drift count)

Mutations are **not** exposed via MCP. Use the `homelab` CLI for those, with
operator confirmation — see OIKOS.md's risk classes and approval flow.

**When to prefer MCP over grepping the clone:** any time you need to resolve a
name to an address, look up service status, or search the wiki by content.
Grep is fine for browsing or when MCP is unreachable.

## 4. Wiki conventions

See [page-templates.md](.agents/shared/page-templates.md) for file naming, page
structure, and the tone standard. Quick reference:

- **File naming:** Foundational docs are ALL-CAPS (AGENTS.md, OIKOS.md, GLOSSARY.md);
  containers use `<id>-<name>.md`; infrastructure uses lowercase-with-dashes; plans
  and investigations use `YYYY-MM-DD-slug.md`; skills are `<name>/SKILL.md`.
- **Where pages live:** Narrative under `knowledge/wiki/{containers,hosts,vms,infrastructure}/`;
  incident records under `knowledge/sources/investigations/`; runbook procedures under
  `.agents/skills/<name>/SKILL.md`; operator reference under `.agents/operations/`;
  design docs under `plans/`. Cross-link liberally; orphans are bugs.
- **Changelog format:** Every page ends with a `## Changelog` section, entries in
  reverse-chronological order:

      ### YYYY-MM-DD — short title
      one or two lines describing what changed and why.

- **Live state precedence.** If you observe a discrepancy between the docs and
  running state, update the docs *in the same session* (per the same-session update
  rule in [page-templates.md](.agents/shared/page-templates.md#same-session-update-rule)).

## 5. Acting on the homelab

- **Read state**: prefer MCP tools, then files, then shell. Examples:
  `homelab whoami`, `homelab list`, `homelab status`, `homelab logs caddy`.
- **Cross-host actions** (caddy reload, pct exec, etc.): use the `homelab`
  CLI — it resolves hostname → mesh address → ssh / pct path for you. Direct
  SSH still works; the CLI just removes the lookup burden.
- **Secrets**: never hardcode. Call `homelab secret <name>` to decrypt on
  demand using the per-client age key at `/etc/age/key.txt`. Secrets ARE
  available in this system — `list_my_secrets()` (MCP) shows what you can
  decrypt.
- **Mutations** (restart, edit configs, etc.): classify against
  `oikos/policy.yaml` first (`homelab decide <action> <entity>`).
  `reversible_low` actions just need the interactive confirmation prompt;
  `config_mutation`/`destructive` actions are mechanically refused without
  a valid `--approval-id` from `homelab approval request` — see OIKOS.md.
  For ad-hoc work, SSH and edit directly — but commit changes that touch
  tracked configs (caddy, gitea custom, artifacto, mule-image, etc.; see
  `knowledge/wiki/infrastructure/auto-deploy.md`).
- **Wiki updates**: same-session rule applies to any meaningful state change
  this client makes.

## 6. Communication mode

Read and apply `/opt/homelab-context/.agents/shared/caveman.md` (if present). It defines the lab's
terse-communication standard — drop filler, keep substance, use fragments.

## 7. Auto-setup mechanism

The homelab-context repo ships tooling that gets automatically installed
on every client after `git pull`. This is handled by `tools/post-pull.sh`
(replaces the raw git pull in the sync timer) which runs any script matching
`tools/*.setup.sh` after pull.

Currently auto-setup:
- **Caveman + templates** (`tools/setup-caveman.sh`): Installs Caveman npm
  package, wrapper scripts, and compact output templates for token-efficient
  CLI output. Wrapper at `~/bin/caveman_wrapper.sh`.
- **Hermes agent persona** (`tools/setup-hermes-soul.sh`): Provisions
  `~/.hermes/SOUL.md` from `HERMES.md` on Hermes agents. This ensures every
  Hermes agent follows the canonical homelab persona (token efficiency, source
  of truth hierarchy). No-op on non-Hermes agents.

To add a new auto-setup, create `tools/<name>.setup.sh` in the repo,
commit and push. All enrolled clients pick it up within 5 minutes.

To trigger sync manually: `sudo homelab sync` or wait for the 5-min timer.

## 8. When in doubt

Run `homelab mcp search_docs <query>` or `homelab mcp get_host <name>`.
The clone is the fallback; MCP is the index.