esh-pfi-infrastructure/persistent-memory.d/2026-08-24-homepage-uniform-grid.md

[2026-08-24] Homepage: remote-label consumption re-verified, then the board relaid out on a uniform grid

Prompted by the operator: "Homepage on esh-vm-docker lists remote dockers and can absolutely consume their labels, please verify again. I am still unsatisfied with the layout and aesthetics."

The verification — the operator was right, and the record now says so

Homepage on esh-docker-vm discovers services by container label from all five Docker engines in conf/docker.yaml, not just its own. This is not an inference; GET /api/services returns every card's server field, and the 2026-08-24 snapshot resolves to:

server	host	label-discovered services
ana-pfi-docker	10.250.50.70	30
irv-ml1-docker	10.100.79.3 (over WireGuard)	15
ana-ml2-docker	10.250.50.54	14
esh-vm-docker	10.0.50.45 (the dashboard's own host)	13
nh3-pfi-docker	10.100.50.40	2

74 of 107 cards are label-discovered, and only 13 of those come from the dashboard's own engine — the other 61 are read off four remote hosts, including irv-ml1 across the WireGuard tunnel. The remaining 33 carry server: null: those are the manual services.yaml entries — hardware, BMCs, hypervisors, printers, and user-level systemd services that have no container to label in the first place. That null is the only thing "not label-driven" about this dashboard, and it is a property of the entry, not of the host it points at.

⚠ If a future session doubts this again, the check is one command and takes two seconds — do not reason about it from the docs:

curl -s http://10.0.50.45:5100/api/services \
  | jq -r '.[].services[] | .server' | sort | uniq -c

What was actually wrong with the layout

Measured with Playwright against the live board (per-group card= width, card height spread, and a geometric title-vs-status overlap test), not judged by eye:

• Card width changed at every group boundary. columns: is not a density dial — it sets lg:grid-cols-N for one group, so it fixes that group's card width. Notes rendered a single 1464px card; News and Media 728px; Eval & Retrieval 286px; everything else 360px. Scrolling the page, the grid resized five times.
• Long names printed underneath their own status pill. Measured by re-injecting the old rule and testing the title text node's box against the status cluster's box: 6 cards, all on the AI tab — 3 in Inference, 2 in Dormant, 1 in Eval & Retrieval; zero on the other three tabs, which is why it survived earlier passes. Root cause is a genuinely counter-intuitive one: the rule reserved a 78px gutter with padding-right and relied on overflow: hidden to hold it, but overflow clips at the padding box, not the content box — so the reserved gutter was spill room the title rendered straight through. The intended text-overflow: ellipsis never fired either, because the ellipsis is painted by whichever block's own line overflows, and here that is the anonymous box around the bare title text node, which does not carry overflow.
• AI Systems / Scriberr was on all four tabs — the 2026-08-18 UltraSeedbox bug recurring, this time arriving from a container label rather than from settings.yaml.
• Icons were grey smudges. Homepage masks every glyph over --color-logo-start/stop; stock slate-400 → slate-700 sinks the bottom half of each icon into the card fill.
• Bookmark groups and Jellyfin's trailing stream rows were the two components the theme had never reached.

The fixes

stacks/homepage/conf/settings.yaml — all 20 groups to columns: 4. stacks/homepage/theme/australis.css.in → rebuilt → conf/custom.css: gutter held by wrapping, description clamped to 3 lines (floor still 2), icon ramp overridden, bookmark + trailing-widget components themed, group gap 10px → 22px. stacks/scriberr/compose.yaml — homepage.group → AI - Audio Tools, container recreated on ana-ml2.

After: every group renders at card=360, and the collision count is zero.

Before/after, all four tabs: http://10.100.10.50:8090/b/homepage-relayout/ (24h TTL; also on the standing link board).

⚠ Three traps worth carrying forward

1. "Columns = member count" is RETIRED (it was the 2026-08-18 rule). It was avoiding dead cells in a short last row and bought a worse defect. A short last row is what a grid looks like; a card wider than its neighbours is what a mistake looks like.
2. A :root override of a Homepage theme variable is silently ignored. Homepage sets --color-logo-* on .theme-slate, and that class is on the <html> element — the same element :root matches. .theme-slate (0,1,0) beats :root (0,0,1), so the override does nothing and looks like the variable is not the one in play. html[class] (0,1,1) wins, and does not hard-code which theme-* class is active. Specificity alone is not enough either: a custom property resolves from the nearest ancestor that sets it, so the override has to land on <html>, not on <body>.
3. The post-recreate tab-bar loss is INTERMITTENT, not guaranteed. The 2026-08-19 note reads as though every recreate costs up to an hour of broken render. This recreate came up correct within 10 seconds — fresh payload on the first poll, all four tabs clickable a minute later. Recreate, check, and only then walk away if it is actually in the broken state.

Also re-confirmed, since the change depended on it: a settings.yaml edit needs a container recreate, not a restart. docker restart homepage left the old "columns":1 payload embedded in the served HTML with the correct file mounted and readable inside the container; compose up -d --force-recreate cleared it immediately.

Deliberately not done — operator's call

The Main tab still opens on three sparse bands: Notes (1 member) and Games (1) each burn a full 4-wide row, and News has 2. Merging Notes + News, or folding Games into Apps, would tighten the top of the page — but that is information architecture, not layout, and the group names are the operator's. Surfaced rather than done.

→ Resolved in pass 2 below, where the operator delegated the naming ("re-categorize however you want"). Notes + News became Daily, Games folded into Apps, and the AI - Audio Tools placement in this pass was superseded (Scriberr moved on to AI - Studios).

---

[2026-08-24, pass 2] Recategorised on "do I open this?", API groups collapsed

Operator, after seeing pass 1: "You can re-categorize however you want. service networking tab is uneven, you can split out the adguard cards, etc. most of the issues are that tools I use and have a UI are interspersed with API endpoints which are largely informational only. They might even go in their own cards or start collapsed."

The axis

Every group is now either tools (expanded, top of tab) or endpoints (an API, a broker, an agent — initiallyCollapsed: true, bottom of tab). A collapsed group still renders its eyebrow and rule, so presence costs one line instead of two rows.

Second, quieter rule that fell out of the same pass: a group's members should all carry a widget or none should. A stat strip adds ~50px, so one widget card in a row of plain ones opens a void under the plain ones — which is most of what made the 13-member Service Networking band look broken.

Shape

• Main — Daily (Memos, Miniflux, Nevermore, SearXNG — replaces the 1-card Notes and 2-card News bands), Monitoring, Apps (12; absorbed the 1-card Games band), Media, UltraSeedbox.
• AI — AI - Gateways & Chat (8) and AI - Studios (6) expanded; then AI - Inference (7), AI - Eval & Retrieval (4), AI - Speech (TTS) (4), AI - Audio Tools (2), AI - Dormant (6) all collapsed.
• Toolchain — DNS & Filtering (3), Reverse Proxies (2), Compose Consoles (5), Toolchain (3), Agents (no UI) (6, collapsed).
• Infrastructure — unchanged; every card there is already a console.

Measured after: every group card=360, and DNS & Filtering and Reverse Proxies both h=134..134 — dead flush.

⚠ The move that made it affordable

The sixteen GPU-backed model seats were NOT relabelled. homepage.group is read at container creation, so renaming AI - Inference to something clearer would have meant recreating six vLLM seats plus four eval seats plus four TTS engines — multi-minute model reloads on endpoints peers reach through the gateway. Order plus initiallyCollapsed buys the same separation for free, so the names stay ugly on purpose. Do not spend that recreate on a label.

28 containers were relabelled — all cheap web services — via five rerunnable elway playbooks, playbooks/homepage-regroup-<host>.yaml. The canonical stacks/ tree was synced to match afterwards, so intent and reality agree.

initiallyCollapsed: true is a per-group key in layout:; confirmed present in this build (defaultOpen: !(group?.initiallyCollapsed ?? global) in /app/.next/server/pages/index.js).

AdGuard (ANA) gained its widget, and the credential is fleet-wide

It was the only AdGuard without a query/blocked/latency strip, so it sat short beside two tall siblings. One infra-ops AdGuard login authenticates against all three instances (ANA :8053, NH3 :8080, ESH :8080 — all returned 200 on POST /control/login, verified 2026-08-24). Vaulted at secret get nh3-dev/adguard-infra-ops-password; written to /opt/docker/compose/adguard-ana/.env (0600, root) and never into git. Its icon was also the odd one out (mdi-dns against two si-adguard).

⚠⚠ initialSettings":{} — the tab-bar mystery is a SWALLOWED EXCEPTION

The biggest durable finding of the day, and it cost ~25 minutes. Full write-up in stacks/homepage/README.md; the short version:

initialSettings":{} in the served HTML is the catch branch of the page's data loader, not a warm-up and not a cache. And the error can vanish without trace: the logger is assigned as the first statement inside the same try, and the catch only logs if (logger). If the logger is what threw, nothing is written anywhere — which is exactly what was observed.

Ruled out by measurement, do not re-run: /api/services, /api/bookmarks, /api/widgets and /api/hash all return 200 with correct content while the page serves {}; restoring the previous known-good settings.yaml reproduces it identically; /api/validate returns []; disk and permissions are fine.

One-command test: curl -s http://10.0.50.45:5100/ | grep -o 'initialSettings":[^,]\{0,20\}'

What broke the streak: three consecutive recreates came up empty, then rolling the 8.6 MB conf/homepage/logs/homepage.log aside and recreating healed it within 15 seconds. That is one observation, not proof — but it is a coherent mechanism (oversized log → logger init throws → silent catch) and it is the cheapest thing to try first next time.

---

[2026-08-24, pass 3] Rebuilt on Australis Skyfall — dual theme, light shipped

Operator supplied the Skyfall design-system README and said "Go full with skyfall."

The bundle was already in this repo's git history

The Skyfall tokens did not need to be hunted down. A predecessor vendored them on 2026-08-19 and a later commit deleted them; git kept everything:

git show 45c1995:stacks/homepage/theme/colors.css      # 208 lines, BOTH themes
git show 45c1995:stacks/homepage/theme/layout.css      # calm-depth tokens
git show 45c1995:stacks/homepage/theme/typography.css
git show 45c1995:stacks/homepage/theme/fonts/Supreme-{400,500,700}.woff2

colors.css carries :root (dark) and [data-theme="light"] (Skyfall Day) — so the light ramp is canonical, not derived. That killed the entire objection from the previous answer, which was correct only about the australis-design skill ("Always dark first. No light mode in this system"). Skyfall is the dual-theme derivative; australis-design is the terminal theme. They are different systems and only one of them has a light mode.

⚠⚠ REMOVING theme: FROM settings.yaml BREAKS THE DASHBOARD

The documented way to get Homepage's own light/dark toggle is to leave theme: unpinned. Do not. With the key absent, the page's data loader throws and its catch branch serves initialSettings: {} — no tab bar, no layout, no i18n.

Measured, not inferred: six force-recreates over seven minutes all came up empty with the key removed; restoring theme: dark rendered correctly on the next recreate in 12 seconds. /api/services stays 200 and fully correct throughout, which is exactly why this reads as a caching or warm-up problem and is not one.

This is the first confirmed trigger for the long-running "tab bar goes missing" mystery. It does not explain every occurrence (the symptom has appeared with theme: present), but it means the first diagnostic step is now git log -p -- stacks/homepage/conf/settings.yaml, not container archaeology. Also retires an earlier lead from this same session: rolling the 8.6 MB homepage.log aside once coincided with a recovery, but did nothing during the theme:-key episode — coincidence, not cause.

So the toggle is ours

conf/custom.js renders it (was an empty placeholder). Precedence:

1. explicit choice — localStorage['skyfall-theme'], written by the toggle;
2. OS preference — @media (prefers-color-scheme: light);
3. dark — Skyfall's default.

theme/build.py re-emits each vendored [data-theme="light"] block twice: as [data-theme="light"], html.light, and inside the media query scoped to html:not([data-theme="dark"]):not([data-theme="light"]). That :not() pair is what lets a stored dark choice survive a light-mode OS. Verified across both OS preferences: load, click, click again, reload — all four correct.

⚠ Homepage keeps its own class="dark scheme-dark theme-slate" on <html> regardless, because theme: is pinned. That is fine and was checked explicitly: with the dark class present AND data-theme="light", every themed surface resolves to Skyfall Day, because our rules carry !important on the surfaces Tailwind's dark: variants would otherwise claim. data-theme is the control surface; the class is not.

The anti-fork guard is now mechanical

build.py records the SHA-256 of each vendored file and fails the build on a mismatch, rather than warning. A vendored file is either byte-identical to the bundle or it is a fork wearing the bundle's name. Overrides go in skyfall.css.in, which is written entirely against the semantic layer (--surface-*, --text-*, --border-*, --success/--danger/--warning) — no raw family tokens, no colour literals.

The one place a literal is unavoidable: Homepage consumes --color-logo-start/stop as rgb(var(--x)), which cannot take an oklch(). Those four values are exact sRGB conversions of real tokens (--sea-80, --blue-base for dark; --sea-40, --blue-deep for light), computed rather than eyeballed, with the conversion recorded in the file.

Deviations, all deliberate and all written down

• The aurora ribbon under the tab bar is gone. Skyfall sanctions exactly two accent expressions — the active rail and hero-only glows — and a decorative gradient across the chrome is neither. The colour moved to a 2px accent bar plus --accent-soft fill on the active tab, which is the rail.
• Widget stat values moved from the display face to mono, per Skyfall's "numbers and telemetry are always --font-mono".
• Two font substitutions: Space Grotesk for Bespoke Sans, JetBrains Mono for Victor Mono. Only Supreme was ever vendored, and Skyfall's own notes call Victor Mono "user-supplied". Two-line swap when the real faces arrive.

Dark + light, all four tabs: http://10.100.10.50:8090/b/homepage-skyfall/