diff --git a/CLAUDE.md b/CLAUDE.md index 2d9a20c..80bd579 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -18,7 +18,7 @@ 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**: `` — 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`. +- **Hardware identifiers**: `` — 2-digit, unique per kind (`srv`, `sw`, `pp`, `pdu`, `ups`, `shf`). Grouping (`cluster:`) lives in frontmatter, not the name. Full scheme: `docs/guides/hardware-naming-scheme.md`. ## Repository Structure diff --git a/docs/guides/editing-hardware-docs.md b/docs/guides/editing-hardware-docs.md index afecb9f..0fcb0bd 100644 --- a/docs/guides/editing-hardware-docs.md +++ b/docs/guides/editing-hardware-docs.md @@ -19,8 +19,9 @@ graph — is **generated** from that frontmatter. ## Quick start: add a device -1. Pick a hostname following the scheme `` — a 2-digit number, - unique per kind (`srv`, `sw`, `pp`, `pdu`, `ups`, `shf`, …). Example: `srv06`. +1. Pick a hostname following the [naming scheme](hardware-naming-scheme.md): + `` — a 2-digit number, unique per kind (`srv`, `sw`, `pp`, + `pdu`, `ups`, `shf`, …). Example: `srv06`. 2. Create `docs/hardware/.md`. **The filename stem must equal the `hostname` field** — `srv06.md` must contain `hostname: srv06`. 3. Fill in the frontmatter (see the reference below). Write any free-text under @@ -175,7 +176,8 @@ check fails and nothing is published. !!! success "Do" - **Do** run `make docs-index` and commit the regenerated files with your change. - **Do** keep the filename equal to the `hostname`. - - **Do** use the `` naming scheme, 2 digits, unique per kind. + - **Do** use the [`` naming scheme](hardware-naming-scheme.md), + 2 digits, unique per kind. - **Do** mark unknown values as provisional placeholders and ask before inventing rack/power/network numbers. - **Do** preview locally with `make docs-serve` before pushing. diff --git a/notes/dev/specs/2026-06-24-hardware-naming-scheme.md b/docs/guides/hardware-naming-scheme.md similarity index 100% rename from notes/dev/specs/2026-06-24-hardware-naming-scheme.md rename to docs/guides/hardware-naming-scheme.md diff --git a/mkdocs.yml b/mkdocs.yml index f5caef5..42298bf 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -60,6 +60,7 @@ nav: - Hardware: - hardware/index.md - Editing the hardware docs: guides/editing-hardware-docs.md + - Naming scheme: guides/hardware-naming-scheme.md - Services: - services/index.md - Infrastructure: diff --git a/notes/dev/plans/2026-06-24-hardware-naming-migration.md b/notes/dev/plans/2026-06-24-hardware-naming-migration.md index 7ec0915..f2480dd 100644 --- a/notes/dev/plans/2026-06-24-hardware-naming-migration.md +++ b/notes/dev/plans/2026-06-24-hardware-naming-migration.md @@ -8,7 +8,7 @@ **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`. +**Spec:** `docs/guides/hardware-naming-scheme.md`. ## Global Constraints @@ -149,7 +149,7 @@ to: In `CLAUDE.md`, immediately after the existing `- **Filenames**: …` bullet, add this new bullet: ```markdown -- **Hardware identifiers**: `` — 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`. +- **Hardware identifiers**: `` — 2-digit, unique per kind (`srv`, `sw`, `pp`, `pdu`, `ups`, `shf`). Grouping (`cluster:`) lives in frontmatter, not the name. Full scheme: `docs/guides/hardware-naming-scheme.md`. ``` - [ ] **Step 3: Fix the stale hardware hint in `README.md`** @@ -193,7 +193,7 @@ git commit -m "docs: record hardware naming scheme, refresh stale mf0x hints" ## Self-Review -**Spec coverage (`2026-06-24-hardware-naming-scheme.md`):** +**Spec coverage (`docs/guides/hardware-naming-scheme.md`):** - Format ``, `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. ✔