docs(hardware): clarify provisional cluster note in naming spec

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

CLAUDE.md

@@ -18,12 +18,13 @@ From `notes/todo/2026-04-14-todo.md`:
 - **Decisions**: Lightweight markdown decision logs
 - **License**: FLOSS by default
 - **Filenames**: ASCII lowercase, kebab-case (`like-this.md`), English regardless of content language. Dated docs use an ISO prefix joined with a hyphen: `YYYY-MM-DD-label.md`. Hostnames are the exception — `docs/hardware/*.md` must equal the host's `hostname` (enforced by `scripts/gen_overview.py`).
+- **Hardware identifiers**: `<kind-abbrev><NN>` — 2-digit, unique per kind (`srv`, `sw`, `pp`, `pdu`, `ups`, `shf`). Grouping (`cluster:`) lives in frontmatter, not the name. Full scheme: `notes/dev/specs/2026-06-24-hardware-naming-scheme.md`.
 
 ## Repository Structure
 
 ```
 docs/             # everything here is built and shipped to docs.makerfloss.eu
-  hardware/       # auto-indexed per-host frontmatter (mf00..mf03, makerfloss.eu)
+  hardware/       # auto-indexed per-host frontmatter (srv01..srv05, makerfloss.eu)
   services/       # auto-indexed per-service frontmatter (docs, forgejo, …)
   infrastructure/ # labdesign, VPS/DNS, etc.
   presentations/  # Marp decks (build-slides.sh)

README.md

@@ -10,7 +10,7 @@ Documentation and working notes for **MakerFLOSS**, an Orange Makerspace initiat
 
 ```
 docs/             # built into the public site (docs.makerfloss.eu)
-  hardware/       # auto-indexed per-host frontmatter (mf00..mf03, makerfloss.eu)
+  hardware/       # auto-indexed per-host frontmatter (srv01..srv05, makerfloss.eu)
   services/       # auto-indexed per-service frontmatter (docs, forgejo, …)
   infrastructure/ # labdesign, VPS/DNS, etc.
   presentations/  # Marp decks (also published to slides.makerfloss.eu)

docs/hardware/index.md

@@ -20,11 +20,11 @@ _Auto-generated from `docs/hardware/*.md` — do not edit by hand. Run `make doc
 | Hostname | Location | CPU | RAM | Storage | NIC | Status |
 |---|---|---|---|---|---|---|
 | [makerfloss.eu](makerfloss.eu.md) | Hetzner HEL1 (cloud) | AMD EPYC (shared vCPU) · 2c | 4 GB | 40 GB NVME | 1 GbE | in-use |
-| [mf00](mf00.md) | The pile | ? | ? | ? | ? | staging |
+| [srv01](srv01.md) | The pile | ? | ? | ? | ? | staging |
-| [mf01](mf01.md) | The pile | Intel Core i5-8500 @ 3.00GHz · 6c | 8 GB | 40 GB NVME | 1 GbE | staging |
+| [srv02](srv02.md) | The pile | Intel Core i5-8500 @ 3.00GHz · 6c | 8 GB | 40 GB NVME | 1 GbE | staging |
-| [mf02](mf02.md) | The pile | Intel Core i5-8500 @ 3.00GHz · 6c | 16 GB | 40 GB NVME | 1 GbE | staging |
+| [srv03](srv03.md) | The pile | Intel Core i5-8500 @ 3.00GHz · 6c | 16 GB | 40 GB NVME | 1 GbE | staging |
-| [mf03](mf03.md) | The pile | Intel Core i5-3570K @ 3.40GHz · 4c | 8 GB | 500 GB HDD | 1 GbE | staging |
+| [srv04](srv04.md) | The pile | Intel Core i5-3570K @ 3.40GHz · 4c | 8 GB | 500 GB HDD | 1 GbE | staging |
-| [mf04](mf04.md) | The pile | Intel Core i5-3570K @ 3.40GHz · 4c | 8 GB | 500 GB HDD | 1 GbE | staging |
+| [srv05](srv05.md) | The pile | Intel Core i5-3570K @ 3.40GHz · 4c | 8 GB | 500 GB HDD | 1 GbE | staging |
 
 ## Switches
 

docs/hardware/srv01.md

@@ -1,7 +1,8 @@
 ---
-hostname: mf00
+hostname: srv01
 kind: server
 status: staging
+cluster: tappaas
 location: The pile
 cpu: "?"
 cpu_cores: "?"

docs/hardware/srv02.md

@@ -1,5 +1,5 @@
 ---
-hostname: mf01
+hostname: srv02
 kind: server
 status: staging
 location: The pile

docs/hardware/srv03.md

@@ -1,5 +1,5 @@
 ---
-hostname: mf02
+hostname: srv03
 kind: server
 status: staging
 location: The pile

docs/hardware/srv04.md

@@ -1,5 +1,5 @@
 ---
-hostname: mf03
+hostname: srv04
 kind: server
 status: staging
 location: The pile

docs/hardware/srv05.md

@@ -1,5 +1,5 @@
 ---
-hostname: mf04
+hostname: srv05
 kind: server
 status: staging
 location: The pile

docs/infrastructure/racks/rack01-elevation.svg

@@ -148,15 +148,15 @@
 <text x="54" y="974" text-anchor="end" fill="#999">47</text>
 <text x="54" y="994" text-anchor="end" fill="#999">48</text>
 <rect x="59" y="41" width="238" height="18" rx="3" fill="#4c78a8" stroke="#333"/>
-<text x="178" y="54" text-anchor="middle" fill="#ffffff">mf00 (U1)</text>
+<text x="178" y="54" text-anchor="middle" fill="#ffffff">srv01 (U1)</text>
 <rect x="59" y="61" width="238" height="18" rx="3" fill="#4c78a8" stroke="#333"/>
-<text x="178" y="74" text-anchor="middle" fill="#ffffff">mf01 (U2)</text>
+<text x="178" y="74" text-anchor="middle" fill="#ffffff">srv02 (U2)</text>
 <rect x="59" y="81" width="238" height="18" rx="3" fill="#4c78a8" stroke="#333"/>
-<text x="178" y="94" text-anchor="middle" fill="#ffffff">mf02 (U3)</text>
+<text x="178" y="94" text-anchor="middle" fill="#ffffff">srv03 (U3)</text>
 <rect x="59" y="121" width="238" height="38" rx="3" fill="#4c78a8" stroke="#333"/>
-<text x="178" y="144" text-anchor="middle" fill="#ffffff">mf03 (U5–U6)</text>
+<text x="178" y="144" text-anchor="middle" fill="#ffffff">srv04 (U5–U6)</text>
 <rect x="349" y="121" width="238" height="38" rx="3" fill="#4c78a8" stroke="#333"/>
-<text x="468" y="144" text-anchor="middle" fill="#ffffff">mf04 (U5–U6)</text>
+<text x="468" y="144" text-anchor="middle" fill="#ffffff">srv05 (U5–U6)</text>
 <rect x="59" y="221" width="238" height="18" rx="3" fill="#59a14f" stroke="#333"/>
 <text x="178" y="234" text-anchor="middle" fill="#ffffff">sw01 (U10)</text>
 <rect x="59" y="501" width="238" height="18" rx="3" fill="#9c755f" stroke="#333"/>

docs/infrastructure/racks/rack01.md

@@ -12,47 +12,47 @@ _Auto-generated from `docs/hardware/*.md` (items with `rack: rack01`) — do not
 flowchart LR
     pdu01["pdu01<br/>8 outlets"]
     pdu02["pdu02<br/>8 outlets"]
-    mf00["mf00"]
+    srv01["srv01"]
-    mf01["mf01"]
+    srv02["srv02"]
-    mf02["mf02"]
+    srv03["srv03"]
-    mf03["mf03"]
+    srv04["srv04"]
-    mf04["mf04"]
+    srv05["srv05"]
-    pdu01 -->|outlet 1| mf00
+    pdu01 -->|outlet 1| srv01
-    pdu01 -->|outlet 2| mf01
+    pdu01 -->|outlet 2| srv02
-    pdu01 -->|outlet 3| mf02
+    pdu01 -->|outlet 3| srv03
-    pdu01 -->|outlet 4| mf03
+    pdu01 -->|outlet 4| srv04
-    pdu01 -->|outlet 5| mf04
+    pdu01 -->|outlet 5| srv05
-    pdu02 -->|outlet 1| mf00
+    pdu02 -->|outlet 1| srv01
 ```
 
 ## Network
 
 ```mermaid
 flowchart LR
-    mf00["mf00"]
-    mf01["mf01"]
-    mf02["mf02"]
-    mf03["mf03"]
-    mf04["mf04"]
     pp01["pp01<br/>patch-panel"]
+    srv01["srv01"]
+    srv02["srv02"]
+    srv03["srv03"]
+    srv04["srv04"]
+    srv05["srv05"]
     sw01["sw01<br/>switch"]
-    mf00 -->|eth0 → p1 · 1G| sw01
-    mf01 -->|eth0 → p1 · 1G| pp01
-    mf02 -->|eth0 → p2 · 1G| pp01
-    mf03 -->|eth0 → p3 · 1G| pp01
-    mf04 -->|eth0 → p4 · 1G| pp01
     pp01 -->|uplink → p24 · 1G| sw01
+    srv01 -->|eth0 → p1 · 1G| sw01
+    srv02 -->|eth0 → p1 · 1G| pp01
+    srv03 -->|eth0 → p2 · 1G| pp01
+    srv04 -->|eth0 → p3 · 1G| pp01
+    srv05 -->|eth0 → p4 · 1G| pp01
 ```
 
 ## Occupancy
 
 | U | Device | Kind | Face | Status |
 |---|---|---|---|---|
-| U1 | [mf00](../../hardware/mf00.md) | server | front | staging |
+| U1 | [srv01](../../hardware/srv01.md) | server | front | staging |
-| U2 | [mf01](../../hardware/mf01.md) | server | front | staging |
+| U2 | [srv02](../../hardware/srv02.md) | server | front | staging |
-| U3 | [mf02](../../hardware/mf02.md) | server | front | staging |
+| U3 | [srv03](../../hardware/srv03.md) | server | front | staging |
-| U5–U6 | [mf03](../../hardware/mf03.md) | server | front | staging |
+| U5–U6 | [srv04](../../hardware/srv04.md) | server | front | staging |
-| U5–U6 | [mf04](../../hardware/mf04.md) | server | rear | staging |
+| U5–U6 | [srv05](../../hardware/srv05.md) | server | rear | staging |
 | U10 | [sw01](../../hardware/sw01.md) | switch | front | in-use |
 | U24 | [pp01](../../hardware/pp01.md) | patch-panel | front | in-use |
 | 0U | [pdu01](../../hardware/pdu01.md) | pdu | left | in-use |

notes/dev/plans/2026-06-24-hardware-naming-migration.md

@@ -0,0 +1,207 @@
+# Hardware Naming Migration Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Apply the approved hardware naming scheme by renaming the placeholder compute nodes `mf00`–`mf04` to `srv01`–`srv05`, recording cluster membership in frontmatter, and syncing the prose references — leaving all generated artifacts and the drift guard green.
+
+**Architecture:** Pure data + docs migration; **no generator logic changes**. The compute files are renamed (`git mv`), their `hostname:` field updated to match (the repo enforces filename-stem == `hostname`), `cluster: tappaas` added to the one known node, then `make docs-index` regenerates the hardware index and rack artifacts. Because `mf00`–`mf04` are referenced only by themselves (their `power:`/`links:` point outward to `pdu*`/`sw*`/`pp*`, with no reverse references), the rename cascades cleanly through regeneration.
+
+**Tech Stack:** Markdown frontmatter, Python generators (`gen_overview.py`, `gen_rack.py`) run via `make`, MkDocs Material, pytest.
+
+**Spec:** `notes/dev/specs/2026-06-24-hardware-naming-scheme.md`.
+
+## Global Constraints
+
+- **No code changes** to `scripts/*.py`, `tests/*`, `Makefile`, CI, `mkdocs.yml`, or `scripts/overview_config.yml`. The `cluster:` field is free-form frontmatter the generators ignore by design; it needs no enum or validation in this migration (the spec defers generator/grouping work).
+- Identifier format per the scheme: `<kind-abbrev><NN>`, 2-digit zero-padded, unique within a kind, starting at `01`. Compute = `srv`.
+- A renamed file's `hostname:` field MUST equal its new filename stem, or `gen_overview.py` fails (`filename stem != hostname`).
+- Preserve each file's body and all other frontmatter unchanged — only `hostname:` changes (plus the one added `cluster:` line).
+- `cluster:` values are provisional except the one known mapping: `srv01` (was `mf00`, "TaPPaaS node 1") → `cluster: tappaas`. Do **not** invent cluster values for `srv02`–`srv05`; leave the field off them until real assignments are given.
+- `makerfloss.eu` (cloud FQDN) is untouched — it keeps its real hostname and gets no `cluster:`.
+- Test-fixture hostnames in `tests/test_gen_rack.py` (synthetic `mf00`/`mf01` strings) and the historical phase specs/plans under `notes/dev/` are **out of scope** — they are illustrative/historical, not references to the renamed files.
+- After each task: `make test` passes (49 tests, unaffected — fixtures are synthetic), `mkdocs build --strict` passes, and `make docs-check` exits 0.
+
+## Name mapping (this migration)
+
+| Old file | New file | `hostname:` | `cluster:` |
+|----------|----------|-------------|------------|
+| `mf00.md` | `srv01.md` | `srv01` | `tappaas` |
+| `mf01.md` | `srv02.md` | `srv02` | (omit) |
+| `mf02.md` | `srv03.md` | `srv03` | (omit) |
+| `mf03.md` | `srv04.md` | `srv04` | (omit) |
+| `mf04.md` | `srv05.md` | `srv05` | (omit) |
+
+---
+
+### Task 1: Rename `mf00`–`mf04` → `srv01`–`srv05`, add cluster, regenerate
+
+**Files:**
+- Rename: `docs/hardware/mf00.md`→`srv01.md`, `mf01.md`→`srv02.md`, `mf02.md`→`srv03.md`, `mf03.md`→`srv04.md`, `mf04.md`→`srv05.md`
+- Modify (each renamed file): `hostname:` line; add `cluster: tappaas` to `srv01.md`
+- Regenerate: `docs/hardware/index.md`, `docs/infrastructure/racks/rack01.md`, `docs/infrastructure/racks/rack01-elevation.svg`
+
+**Interfaces:**
+- Consumes: `make docs-index` (runs `gen_overview.py` + `gen_rack.py`), `make test`, `make docs-check`, `mkdocs build --strict`.
+
+- [ ] **Step 1: Rename the five files with `git mv` (preserves history + body)**
+
+```bash
+cd /home/sjat/Projects/MakerFLOSS
+git mv docs/hardware/mf00.md docs/hardware/srv01.md
+git mv docs/hardware/mf01.md docs/hardware/srv02.md
+git mv docs/hardware/mf02.md docs/hardware/srv03.md
+git mv docs/hardware/mf03.md docs/hardware/srv04.md
+git mv docs/hardware/mf04.md docs/hardware/srv05.md
+```
+
+- [ ] **Step 2: Update the `hostname:` field in each renamed file**
+
+In each file, change the `hostname:` line (line 2) to match its new stem. Make exactly these five edits:
+
+- `docs/hardware/srv01.md`: `hostname: mf00` → `hostname: srv01`
+- `docs/hardware/srv02.md`: `hostname: mf01` → `hostname: srv02`
+- `docs/hardware/srv03.md`: `hostname: mf02` → `hostname: srv03`
+- `docs/hardware/srv04.md`: `hostname: mf03` → `hostname: srv04`
+- `docs/hardware/srv05.md`: `hostname: mf04` → `hostname: srv05`
+
+Do not change any other line in these files.
+
+- [ ] **Step 3: Add `cluster: tappaas` to `srv01.md` only**
+
+In `docs/hardware/srv01.md`, insert a `cluster: tappaas` line immediately after the `status: staging` line, so the top of the frontmatter reads:
+
+```yaml
+---
+hostname: srv01
+kind: server
+status: staging
+cluster: tappaas
+location: The pile
+```
+
+Leave `srv02.md`–`srv05.md` without a `cluster:` field.
+
+- [ ] **Step 4: Regenerate all indices and rack artifacts**
+
+Run: `make docs-index`
+Expected: `gen_overview.py` rewrites `docs/hardware/index.md` (now listing `srv01`–`srv05` under Servers, no `mf0x`); `gen_rack.py` prints `Wrote rack01.md + rack01-elevation.svg (9 item(s))`. No `gen_overview` schema error (each stem now matches its `hostname`).
+
+- [ ] **Step 5: Confirm no `mf0x` remains anywhere under `docs/`**
+
+Run: `grep -rn -E "mf0[0-4]" docs/ ; echo "exit=$?"`
+Expected: no matches, `exit=1` (grep found nothing).
+
+Run: `ls docs/hardware/srv0*.md | wc -l`
+Expected: `5`.
+
+Run: `grep -n "cluster: tappaas" docs/hardware/srv01.md`
+Expected: one match.
+
+- [ ] **Step 6: Run the full test suite**
+
+Run: `make test`
+Expected: PASS (49 tests — the suite uses synthetic fixtures and is unaffected by the rename).
+
+- [ ] **Step 7: Build the site strictly**
+
+Run: `mkdocs build --strict` (if `mkdocs` is not on PATH, use `python3 -m mkdocs build --strict`)
+Expected: build succeeds with no warnings-as-errors. The rack page and hardware index now show `srv01`–`srv05`.
+
+- [ ] **Step 8: Confirm the drift guard is satisfied**
+
+Run: `make docs-check`
+Expected: exit 0 — committed artifacts match a fresh regeneration.
+
+- [ ] **Step 9: Commit**
+
+```bash
+git add docs/hardware/ docs/infrastructure/racks/
+git commit -m "refactor(hardware): rename mf00-mf04 to srv01-srv05, add cluster field"
+```
+
+---
+
+### Task 2: Sync prose references and record the scheme in CLAUDE.md
+
+**Files:**
+- Modify: `CLAUDE.md` (stale hardware hint + new naming-scheme note)
+- Modify: `README.md` (stale hardware hint)
+
+**Interfaces:**
+- Consumes: `grep`, `make test`, `make docs-check` (sanity).
+
+- [ ] **Step 1: Fix the stale hardware hint in `CLAUDE.md`**
+
+In `CLAUDE.md`, change the repository-structure comment line:
+
+```
+  hardware/       # auto-indexed per-host frontmatter (mf00..mf03, makerfloss.eu)
+```
+
+to:
+
+```
+  hardware/       # auto-indexed per-host frontmatter (srv01..srv05, makerfloss.eu)
+```
+
+- [ ] **Step 2: Add a naming-scheme note to the `CLAUDE.md` working norms**
+
+In `CLAUDE.md`, immediately after the existing `- **Filenames**: …` bullet, add this new bullet:
+
+```markdown
+- **Hardware identifiers**: `<kind-abbrev><NN>` — 2-digit, unique per kind (`srv`, `sw`, `pp`, `pdu`, `ups`, `shf`). Grouping (`cluster:`) lives in frontmatter, not the name. Full scheme: `notes/dev/specs/2026-06-24-hardware-naming-scheme.md`.
+```
+
+- [ ] **Step 3: Fix the stale hardware hint in `README.md`**
+
+In `README.md`, change the repository-layout comment line:
+
+```
+  hardware/       # auto-indexed per-host frontmatter (mf00..mf03, makerfloss.eu)
+```
+
+to:
+
+```
+  hardware/       # auto-indexed per-host frontmatter (srv01..srv05, makerfloss.eu)
+```
+
+- [ ] **Step 4: Confirm no stale `mf0x` hint remains in the two files**
+
+Run: `grep -n -E "mf0[0-4]" CLAUDE.md README.md ; echo "exit=$?"`
+Expected: no matches, `exit=1`.
+
+Run: `grep -c "Hardware identifiers" CLAUDE.md`
+Expected: `1`.
+
+- [ ] **Step 5: Sanity-check tests and drift still pass**
+
+Run: `make test`
+Expected: PASS (49 tests).
+
+Run: `make docs-check`
+Expected: exit 0 (CLAUDE.md/README.md are not generated artifacts, so this only confirms nothing regressed).
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add CLAUDE.md README.md
+git commit -m "docs: record hardware naming scheme, refresh stale mf0x hints"
+```
+
+---
+
+## Self-Review
+
+**Spec coverage (`2026-06-24-hardware-naming-scheme.md`):**
+- Format `<kind-abbrev><NN>`, `srv` for compute — Task 1 (rename to `srv01`–`srv05`). ✔
+- Stable identifier + `cluster:` in frontmatter — Task 1 (rename + add `cluster: tappaas` to the one known node). ✔
+- `srv01` = `tappaas`; others provisional/omitted — Task 1 Step 3 + Global Constraints. ✔
+- `makerfloss.eu` FQDN exception untouched — Global Constraints (not in the rename set). ✔
+- No generator/grouping/validation work (deferred by spec) — Global Constraints (no `*.py`/config changes). ✔
+- Scheme discoverable to contributors — Task 2 (CLAUDE.md note + spec pointer). ✔
+- Stale prose hints corrected — Task 2 (CLAUDE.md + README.md). ✔
+
+**Placeholder scan:** No "TBD"/"handle edge cases"/"similar to Task N". Cluster values for `srv02`–`srv05` are intentionally omitted (real-data dependency, explicitly bounded), not a placeholder.
+
+**Type consistency:** No code interfaces in this migration. The name mapping table (Task 1) and the `hostname:` edits (Step 2) are internally consistent: `mf00→srv01`, `mf01→srv02`, `mf02→srv03`, `mf03→srv04`, `mf04→srv05`, with `cluster: tappaas` on `srv01` only. Verification greps reference the same `srv0x` names produced by the edits.

notes/dev/specs/2026-06-24-hardware-naming-scheme.md

@@ -0,0 +1,117 @@
+# Hardware Naming Scheme Design
+
+**Date:** 2026-06-24
+**Status:** Approved
+
+## Goal
+
+Settle a single, clear hardware naming scheme for the MakerFLOSS rack that the
+team can grow within, before more devices are documented. The scheme assigns
+every physical device a stable identifier and pushes everything that changes
+over time (which cluster a node serves, its role) into frontmatter, so the
+identifier never has to be renamed when hardware is repurposed.
+
+## Context
+
+- Hardware is documented one-file-per-device under `docs/hardware/*.md`, with the
+  file name equal to the device identifier (enforced by `scripts/gen_overview.py`).
+- Current names are inconsistent: compute uses an org/brand prefix
+  (`mf00`–`mf04`), infrastructure uses kind prefixes (`pdu01/02`, `sw01`, `pp01`).
+- The inventory to be documented is a mix of rack and home-office gear, grouped
+  into clusters (TaPPaaS production + four test clusters) plus crosscutting
+  power/network gear. Stationary PCs will sit on rack shelves.
+- Hardware moves between test clusters over time, so cluster membership is a
+  changeable attribute, not an intrinsic property of a device.
+
+## Decisions
+
+### 1. Identifier nature (mixed)
+
+- **Compute nodes (stationary PCs) and managed switches:** the identifier *is*
+  the device's real OS/DNS hostname. It must be DNS-safe (lowercase letters,
+  digits, hyphens) and stable — renaming costs OS/DNS/Ansible churn.
+- **Passive gear (UPS, PDU/power strip, patch panel, unmanaged switch):** the
+  identifier is a documentation/physical-label id only; the device has no OS.
+
+### 2. Format
+
+`<kind-abbrev><NN>` — a kind abbreviation followed by a **2-digit zero-padded
+sequence**, **globally unique within a kind**, starting at `01`. The number is
+just "next free"; it encodes nothing — not cluster, rack, role, or port count.
+A 10-port and a 24-port switch are still `sw01` and `sw02`.
+
+### 3. Kind abbreviation table
+
+The prefix equals the `kind` field, so the name is self-describing.
+
+| Device | `kind` | abbrev | example |
+|--------|--------|--------|---------|
+| Stationary PC / server | `server` | `srv` | `srv01` |
+| Switch (managed or dumb) | `switch` | `sw` | `sw01` |
+| Patch / network panel | `patch-panel` | `pp` | `pp01` |
+| PDU / power strip | `pdu` | `pdu` | `pdu01` |
+| UPS | `ups` | `ups` | `ups01` |
+| Shelf | `shelf` | `shf` | `shf01` |
+
+Existing enum kinds not yet in the rack reuse their natural short form when
+first used (`ap` → `ap`, `kvm` → `kvm`, `sbc` → `sbc`, `laptop` → `lt`,
+`desktop` → `dt`, `blank` → `blank`); register the chosen abbrev in this table
+at that time.
+
+Distinguishing attributes (port/outlet count, managed vs dumb, speed) live in
+frontmatter (`ports:`, `outlets:`, …), never in the name.
+
+### 4. Grouping in frontmatter, not the name
+
+- `cluster:` — one of `tappaas`, `test-1`, `test-2`, `test-3`, `test-4`, or
+  `shared` (crosscutting gear that spans clusters: power strips, shared patch
+  panels). Editing this field is the entire cost of moving a node between
+  clusters.
+- `role:` — optional, free-form (e.g. `control`, `worker`); added only where it
+  earns its keep.
+
+A future generator step may group/table hardware by `cluster`, exactly as the
+hardware index groups by `kind` today. That is **not** part of this scheme — the
+scheme only fixes the field and its allowed values.
+
+### 5. Exceptions
+
+Cloud / externally-named hosts keep their real FQDN as the identifier (e.g.
+`makerfloss.eu`) instead of `srvNN`. They are not racked and DNS owns the name.
+Such hosts carry no `rack:` field and need no `cluster:`.
+
+### 6. Growth rules
+
+- **New device class:** add the `kind` to the `hardware` enum in
+  `scripts/overview_config.yml` and register a short abbrev in the table above.
+- **New grouping:** add a `cluster:` value.
+- **More than 99 of one kind:** widen that kind's sequence to 3 digits.
+- **More racks:** already supported via the `rack:` field (Phase 1).
+- **Multiple sites:** deferred until real (YAGNI); a site prefix or field can be
+  added without disturbing existing names.
+
+## Migration of current names
+
+| Current | New | Notes |
+|---------|-----|-------|
+| `mf00` | `srv01` | "TaPPaaS node 1" → `cluster: tappaas` |
+| `mf01` | `srv02` | cluster omitted until a real assignment is given |
+| `mf02` | `srv03` | |
+| `mf03` | `srv04` | |
+| `mf04` | `srv05` | |
+| `pdu01`, `pdu02` | unchanged | already conform |
+| `sw01`, `pp01` | unchanged | already conform |
+| `makerfloss.eu` | unchanged | cloud FQDN exception |
+
+The `mf0x` machines are staging placeholders, so renaming is cheap now. The
+rename touches their files, the `power:`/`links:` references to them in
+`pdu*`/`sw*`/`pp*` and sibling host files, and the regenerated artifacts under
+`docs/hardware/index.md` and `docs/infrastructure/racks/`. The cluster
+assignments for `srv02`–`srv05` are provisional until real values are given;
+`srv01` = `tappaas` is the one known mapping.
+
+## Out of scope
+
+- Choosing the *best distribution* of hardware across clusters.
+- Building a generator view that groups by `cluster` (possible future work).
+- Real cluster assignments beyond `srv01` = TaPPaaS.