arda/SKILL.md

---
name: arda
description: >
  Authoritative naming registry for the home-v1 homelab — assigns and records Middle-earth
  (Tolkien) names for every infrastructure component: repositories, physical hosts,
  Kubernetes nodes, and network domains. Use whenever a new homelab component needs a name,
  an existing name must be resolved to its role or IP address, a component is being renamed,
  a name collision must be settled, or a reserved name is being claimed — even when the user
  only says "what do we call the NAS", "name this box", "add a worker node", "which host is
  that", or names a component directly such as arda, gondor, osgiliath, minas-tirith,
  ithilien, palantir, erebor, arnor, or rohan. Owns the naming convention for domain
  repositories (<name>-v1), sub-domains (<parent>-<child>-v1), and cluster nodes
  (<repo>-<place>-<NNN>), plus the reserved-name list and outstanding renames.
compatibility: Documentation-only skill. No scripts or external tooling required.
metadata:
  author: home-v1
  version: "1.0"
  spec: agentskills.io/specification
  scope: home-v1 homelab
---

# Arda — Homelab Naming Registry

`arda` is the single source of truth for **what every component of the home-v1 homelab is
called**. Arda is the world itself in Tolkien's legendarium; everything below sits inside it.

Use this registry before inventing any name. Names in the homelab are not decorative — they
are used verbatim as repository names, hostnames, Kubernetes node names, and DNS labels, so
a name chosen casually becomes load-bearing immediately.

## Naming convention

| Kind | Pattern | Example |
|---|---|---|
| Domain repository | `<name>-v<N>` | `gondor-v1`, `palantir-v1` |
| Sub-domain of a realm | `<parent>-<child>-v<N>` | `gondor-ithilien-v1` |
| Code-agent companion | `<repo>-code-agent` | `gondor-v1-code-agent` |
| Copier template | `<repo>-tmpl` | `gondor-v1-tmpl` |
| Cluster node | `<repo>-<place>-<NNN>` | `gondor-v1-osgiliath-000` |

**Node numbering** — `NNN` is a 3-digit slot, allocated in tens by role:

- `000` — control plane
- `010`, `020`, `030`… — workers

The gaps are deliberate: they leave room to insert a node without renumbering the rest.

**Rule** — the `-v<N>` suffix is part of the name, never dropped. `gondor` is the realm in
prose; `gondor-v1` is the thing that exists.

## Registry — in use

| Component | Name | Role | Address |
|---|---|---|---|
| The estate | `arda-v1` | Umbrella topology + ownership boundaries | — |
| Kubernetes cluster | `gondor-v1` | 3-node microk8s platform (GitOps content) | — |
| Control plane node | `gondor-v1-osgiliath-000` | Control plane, Argo CD, ingress; also runs the edge nginx | — |
| Worker node | `gondor-v1-minas-tirith-010` | Worker (strong CPU) | — |
| Worker node | `gondor-v1-minas-tirith-020` | Worker (strong CPU) | — |
| Edge reverse proxy | `gondor-ithilien-v1` | nginx owning the public IP, apex `lego-cloud.eu` | `78.57.213.95` |
| Operator / tooling | `palantir-v1` | Imperative ops repo — bootstraps and repairs what GitOps owns | — |
| Cluster template | `gondor-v1-tmpl` | Copier template that renders `gondor-v1` | — |

**Why these names fit** — keep this reasoning when adding to the registry:

- **Arda** — the world; the container for everything else.
- **Gondor** — the realm that is actually defended and inhabited: the compute platform.
- **Osgiliath** — Gondor's old capital astride the river, the crossing everything passes
  through. It is the control plane *and* the host of the edge proxy.
- **Minas Tirith** — the fortress city, where the strength is. The heavy workers.
- **Ithilien** — the outland province beyond the river, watched by rangers from a hidden
  outpost. The edge proxy facing the internet.
- **Palantír** — the seeing-stone: see the whole realm from one place, and act on it. The
  imperative operator repo.

## Registry — reserved

Names claimed but not yet bound to a running component. **Do not reuse them for anything
else.**

| Name | Intended for | State |
|---|---|---|
| `erebor` | **The NAS** (TrueNAS) | Reserved — rename pending, see below |
| `arnor-v1` | Unassigned | Empty repository, initial commit only |
| `rohan-v1` | Unassigned | Empty repository, initial commit only |

**Erebor** — the Lonely Mountain: the great hoard under the mountain, everything of value
kept in deep vaults. The natural name for the storage tier.

**Arnor** — the northern sister-kingdom to Gondor. Fits a second, peer cluster or a
separate site.

**Rohan** — the horse-lords: fast, mobile, ride to aid Gondor. Fits an ephemeral, burst, or
edge-compute tier.

## Registry — pending renames

These components are **live but carry non-Tolkien names**. The old names are still what the
code and docs say; treat both as referring to the same thing until the rename lands.

| Component | Current name | Target name | Address |
|---|---|---|---|
| NAS (TrueNAS) | `realm-v1` | `erebor-v1` | `192.168.1.218` |
| Router / gateway | `outpost-v1-router` | **undecided** | `192.168.1.1` |

`realm-v1` and `outpost-v1-router` are declared authoritative in
`arda-v1-code-agent/memory-bank/0100-project/` — that memory bank must be updated as part of
any rename, not just the code.

## Gotchas

**`outpost` is ambiguous — do not use it as a name.** `gondor-ithilien-v1` is already
aliased "Outpost" in its own memory bank, while `arda-v1` independently named the router
`outpost-v1-router`. Two different components, one word. Whatever the router ends up being
called, it must not be `outpost`.

**`arda-v1`'s memory bank is stale.** It documents only the router, the NAS, and the three
cluster nodes. It has **no mention** of `gondor-ithilien-v1`, `palantir-v1`, `arnor-v1`, or
`rohan-v1`. Do not treat it as a complete inventory — this registry is the complete one.

**Names are referenced by IP, not by name, in most code today.** The NAS appears as
`192.168.1.218` and the router as `192.168.1.1` throughout `palantir-v1`. Renaming a
component in this registry does not by itself change anything operational.

## Assigning a new name

1. **Identify the role first**, then find the name — never the reverse. The name must
   justify itself in one sentence, the way each entry above does.
2. **Check reserved names** before inventing one. If a reserved name fits, claim it rather
   than adding another.
3. **Check for collisions**, including informal aliases used in memory banks — that is how
   `outpost` went wrong.
4. **Stay inside the realm's logic.** A component belonging to the cluster gets a Gondorian
   place name (`gondor-<place>-v1`). A standalone domain gets its own realm name.
5. **Record it here in the same commit** that introduces the component. A name that lives
   only in a hostname will drift.

Read `references/name-pool.md` when you need candidate names for a role not covered above —
it lists vetted Middle-earth names grouped by the kind of component they suit, with the
reasoning already worked out.