Skip to content

docs(runbook): give docs/ a front door for a successor (#124) - #287

Merged
Gerrrt merged 2 commits into
mainfrom
gerrrt/successor-handover-docs-68de73
Sep 4, 2026
Merged

Gerrrt merged 2 commits into
mainfrom
gerrrt/successor-handover-docs-68de73

Conversation

@Gerrrt

@Gerrrt Gerrrt commented Sep 4, 2026

Copy link
Copy Markdown
Owner

Closes #124.

docs/ had no entry point for a successor. The runbooks are written for someone competent who does not know this estate — the right reader — but nothing addressed that person: no page saying what this estate is, what to check on day one, or which runbook to open in what order.

The page

docs/runbooks/successor-handover.md orders what already exists rather than restating it. Every claim links to the document that owns it, and that document is the authority when the two disagree.

  • This repository is the operator-facing one. ADR-0011 tiers the household's documentation — printed card, the wiki on oracle, a private mirror of that wiki — and none of those three is this. Stated as a correction of a real conflation rather than as a slogan: the third tier is Lemmiwinks' GitHub mirror, not HomeLab.
  • What the estate is, in a paragraph, plus four facts that reorder everything else — morpheus is routing, DHCP and the only advertised resolver; neo carries every VLAN; nothing in the house depends on the observability stack; Hicks is where you administer from and is not the only path into management.
  • Day one, in seven steps, each cheap, each telling you whether the next is meaningful.
  • What fails soonest if nobody touches anything.
  • Where the secrets are — and what is not among them.
  • What can be switched off, and what cannot, plus three things not to change without reading first.
  • A reading order for the runbooks and ADRs.

The two sections that carry more than an ordering

What fails soonest is the part that existed nowhere. The three entries at the top are all failures of notification — an alert channel pointed at a destination the successor does not own, a heartbeat watcher on someone else's free-tier account, an unproven key backup — and every one is silent from inside the estate; there is no dashboard on which they look wrong. The certificate, the UPS pack and the unbatteried monitoring path follow, each with the alert that actually watches it.

Where the secrets are states what the SOPS file does not hold, which is the half a handover actually turns on: no device admin password is in this repository in any form, the CA key is host-local and gitignored, and the alert destinations live in an account. #106 is quoted as the open issue it is — a successor who cannot decrypt has nothing.

Two premises in the issue that had gone stale

The issue lists "nothing schedules any backup, digest check or key verification (#77)" and the UPS battery (#93) among what fails soonest. Both are closed, and the page says so explicitly rather than silently omitting them — a successor reading the older issues will find both described as outstanding and should not go looking for finished work. The issue also says "nine ADRs"; there are 22.

README

A nav entry, a short pointer under the intro, and the runbook list in the layout tree. Its ADR and runbook counts are corrected while I am there: they read fourteen and twelve against 22 and 19, and adding a runbook made the second one wronger.

Verification

$ python3 scripts/check_docs.py
docs OK — 53 Prometheus + 16 Loki rules, 7 dashboards, 140 panels, 7 assertions

$ ./scripts/lint.sh
  PASS yamllint
  PASS markdownlint-cli2
  PASS shellcheck
  PASS actionlint
  PASS editorconfig-checker
  PASS ci.yml, the Makefile and validate.sh all delegate here
lint passed

Every relative link and in-page anchor in the new file was resolved against the tree. The new page joins docs/runbooks/*.md, which check_docs.py globs into PROSE, so it is now covered by the counted-claim and image-pin assertions like every other present-tense document — it deliberately carries no rule, dashboard or panel counts of its own.

Full make validate was not run here: promtool is not on this host and the stack does not run in a worktree, so the container-backed checks would skip rather than pass. CI is the authority on those.

🤖 Generated with Claude Code

Gerrrt and others added 2 commits September 4, 2026 21:59
The runbooks are written for someone competent who does not know this
estate, and they are good at it. Nothing addressed that person directly:
no page saying what this estate is, what to check on day one, or which
runbook to open in what order. That is the difference between "the
documentation is good" and "someone else could pick this up".

It matters because of where the alternative points. ADR-0011 tiers the
household's documentation — a printed card, the wiki on oracle, and a
private mirror of that wiki — and none of those three is this. The wiki
was built to let the family operate the estate and that audience cannot
run pfSense and VLANs from a wiki page, so the realistic reader for deep
operational docs is a technical trustee or a paid MSP arriving cold.
This repository is where they land, and it had no entry point.

docs/runbooks/successor-handover.md orders what already exists rather
than restating it: what the estate is in a paragraph, day one in seven
steps, what fails soonest if nobody touches anything, where the secrets
are and what is not among them, what can be switched off and what
cannot, and a reading order. Every claim links to the document that owns
it, and that document is the authority when the two disagree.

Two sections carry more than an ordering.

"What fails soonest" is the one that existed nowhere. The three entries
at the top of it are all failures of notification — an alert channel
pointed at a destination the successor does not own, a heartbeat watcher
on someone else's free-tier account, an unproven key backup — and every
one is silent from inside the estate. The certificate, the UPS pack and
the unbatteried monitoring path follow, each with the alert that
actually watches it. #77 and #93 are named as closed, because a
successor reading the older issues will find both described as
outstanding and should not go looking for finished work.

"Where the secrets are" states what the SOPS file does not hold, which
is the half a handover actually turns on: no device admin password is in
this repository in any form, the CA key is host-local and gitignored,
and the alert destinations live in an account. #106 — one key, one
holder, one copy — is quoted as the open issue it is, since a successor
who cannot decrypt has nothing.

README gets the pointer and a nav entry, and its ADR and runbook counts
are corrected — they read fourteen and twelve against 22 and 19, and
adding a runbook made the second one wronger.

Closes #124

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@Gerrrt
Gerrrt merged commit 49f13d0 into main Sep 4, 2026
3 checks passed
@Gerrrt
Gerrrt deleted the gerrrt/successor-handover-docs-68de73 branch September 4, 2026 22:15
Gerrrt added a commit that referenced this pull request Oct 10, 2026
…WM and RDP baked in (#1108) (#1114)

* docs(dotfiles): record the first complete Windows run on dot-windows (#1108)

dotfiles-doctor at the console read 28 ok, 1 warn (git identity), 0 fail,
after one upstream bug was worked around: dotfiles-Windows#286, the
PSReadLine 2.3.6 pin loaded beside pwsh 7.6's in-box 2.4.5. §4 now has
that workaround (psmux included), the one-off #287 cache race, GlazeWM's
UAC prompt, the SSH-vs-console doctor gap, the WSL result and the slow
noVNC. The as-run table and changelog record the run.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(dotfiles): bake GlazeWM, the run's one UAC prompt, into dot-windows (#1108)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(dotfiles): the #286 workaround names tester's module path, not SYSTEM's (#1108)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(dotfiles): Remote Desktop on dot-windows from the Hicks workstations (#1108)

noVNC is slow to every guest on Saruman. §3's bake now turns on RDP with
NLA, disables Windows' any-address Remote Desktop rules, and admits 3389
from 10.0.50.80/.90/.102 only, with tester in Remote Desktop Users. §4
runs the layer over RDP. ADR-0090's NOTE records the exception to
ADR-0077's key-only SSH and why it is acceptable on this one guest.
Applied to 198 and verified from the Mac; the as-run table and
changelog record it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

docs/ has no entry point for a successor operator

1 participant