From c1e866666367480f0af3543257c9d705bd201e26 Mon Sep 17 00:00:00 2001 From: Oleg Lukasonok Date: Tue, 18 Aug 2026 11:58:15 +0300 Subject: [PATCH] arda skill: initial import MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Naming registry for the home-v1 homelab — Middle-earth names for every infrastructure component. Records the naming convention, the names in use, reserved names (erebor for the NAS), and the outstanding renames. Co-Authored-By: Claude Opus 5 (1M context) --- README.md | 22 +++++++ SKILL.md | 140 ++++++++++++++++++++++++++++++++++++++++ references/name-pool.md | 79 +++++++++++++++++++++++ 3 files changed, 241 insertions(+) create mode 100644 README.md create mode 100644 SKILL.md create mode 100644 references/name-pool.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..b783df4 --- /dev/null +++ b/README.md @@ -0,0 +1,22 @@ +# arda + +Naming registry for the **home-v1 homelab** — the authoritative record of what every +infrastructure component is called, using Middle-earth names. + +Arda is the world itself in Tolkien's legendarium; every component of the estate sits +inside it. + +The skill covers: + +- the **naming convention** for domain repositories, sub-domains, and cluster nodes +- the **registry** of names currently in use, with each name's role and address +- **reserved** names not yet bound to a component (`erebor` for the NAS, plus `arnor-v1` + and `rohan-v1`) +- **pending renames** — components still carrying non-Tolkien names +- the rules for **assigning a new name**, and a vetted candidate pool in + [`references/name-pool.md`](references/name-pool.md) + +This skill lives only in the [home-v1-skills-code-agent](https://gitea.lego-cloud.eu/home-v1-skills-code-agent) +organisation on Gitea, so it has a single remote. + +See [SKILL.md](SKILL.md). diff --git a/SKILL.md b/SKILL.md new file mode 100644 index 0000000..7c8ed92 --- /dev/null +++ b/SKILL.md @@ -0,0 +1,140 @@ +--- +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 (-v1), sub-domains (--v1), and cluster nodes + (--), 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 | `-v` | `gondor-v1`, `palantir-v1` | +| Sub-domain of a realm | `--v` | `gondor-ithilien-v1` | +| Code-agent companion | `-code-agent` | `gondor-v1-code-agent` | +| Copier template | `-tmpl` | `gondor-v1-tmpl` | +| Cluster node | `--` | `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` 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--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. diff --git a/references/name-pool.md b/references/name-pool.md new file mode 100644 index 0000000..9bc1835 --- /dev/null +++ b/references/name-pool.md @@ -0,0 +1,79 @@ +# Candidate name pool + +Vetted Middle-earth names for homelab components, grouped by the kind of thing they suit. +Load this only when naming something the main registry does not already cover. + +A name earns its place by **matching the component's role**, not by sounding good. Each +entry below carries the reasoning; if you cannot state the reasoning for a new name in one +sentence, it is the wrong name. + +Nothing here is claimed. Claiming happens in `SKILL.md` → "Registry — reserved". + +## Storage and persistence + +| Name | Why it fits | +|---|---| +| `erebor` | **Claimed for the NAS.** The Lonely Mountain — the hoard in deep vaults. | +| `khazad-dum` | The vast delved halls; deeper and larger than Erebor. Suits archive or cold storage beneath the primary NAS. | +| `moria` | Same place, later and abandoned. Reads as decommissioned — good for an archive tier, bad for anything you want to trust. | +| `mathom-house` | The hobbit museum for things kept but not used. Backups, snapshots, retention. | + +## Network edge and gateways + +| Name | Why it fits | +|---|---| +| `argonath` | The Gates of Kings — the pillars marking the border, which everything entering the realm passes between. The strongest fit for a router/gateway. | +| `rammas-echor` | The outer wall encircling Gondor's fields. A perimeter firewall. Long to type. | +| `carrock` | The single stepping-stone crossing the river. A NAT or jump host. | +| `bruinen` | The ford that repels attackers at the border. A WAF or DDoS boundary. | +| ~~`outpost`~~ | **Do not use** — already ambiguous between the router and `gondor-ithilien-v1`. | + +## Compute realms and clusters + +| Name | Why it fits | +|---|---| +| `arnor` | **Reserved.** Gondor's northern sister-kingdom — a peer cluster or second site. | +| `rohan` | **Reserved.** The horse-lords — fast, mobile, ride to aid Gondor. Burst or ephemeral compute. | +| `lorien` | Timeless and preserved, outside the world's decay. A long-lived staging or golden-image environment. | +| `shire` | Small, comfortable, unbothered. A development or sandbox environment. | +| `isengard` | Industrial, mechanised, mass-producing. A build farm or CI fleet — with the obvious caveat that it goes rogue. | + +## Cluster nodes (places within a realm) + +Gondorian place names, for nodes under `gondor-v1`: + +| Name | Why it fits | +|---|---| +| `osgiliath` | **In use** — the river crossing; control plane. | +| `minas-tirith` | **In use** — the fortress city; heavy workers. | +| `cair-andros` | The fortified island guarding the northern approach. Another worker or a quorum/witness node. | +| `pelargir` | The great port where supplies arrive. An ingress-heavy or storage-gateway node. | +| `dol-amroth` | The coastal princedom that sends its own knights. A semi-independent or specialised node pool. | +| `henneth-annun` | The hidden refuge behind the waterfall, in Ithilien. Fits something concealed under the edge — a bastion or VPN endpoint. | + +## Observation, control, and tooling + +| Name | Why it fits | +|---|---| +| `palantir` | **In use** — the seeing-stone; see the realm and act on it. Operator tooling. | +| `amon-hen` | The Hill of Sight — see far, but only see. Monitoring, metrics, dashboards; explicitly read-only, which is the useful distinction from `palantir`. | +| `beacon` | The chain of warning-fires from Gondor to Rohan. Alerting and paging. | +| `orthanc` | The tower from which Saruman watched and schemed. A control plane you do not fully trust — or simply a strong name for a scheduler. | + +## Identity and secrets + +| Name | Why it fits | +|---|---| +| `doors-of-durin` | Opens only to the one who speaks the word. Authentication, SSO, Keycloak. | +| `mellon` | The password to those doors. A secrets store or vault. | +| `mithril` | Rare, precious, protective. Certificate or key material. | + +## Names to avoid + +| Name | Why not | +|---|---| +| `mordor`, `barad-dur`, `sauron` | Adversary names. Funny once; confusing in an incident when someone asks whether Mordor is supposed to be down. | +| `gollum`, `smeagol` | Split identity, unreliable. Bad omen for anything stateful. | +| `one-ring`, `precious` | Single point of failure, corrupts its holder. Never name infrastructure this. | +| `outpost` | Ambiguous in this estate — see above. | +| `arda` | Reserved for the estate as a whole. Never a component. |