Surface

Surface — drive the office wall display

Chris has a permanent, interactive office display (KVM-attached, on pve2 HDMI-2) driven by the surface command (on PATH; private repo at ~/repos/office-presence). surface <X> means: put the right live view of X on that display. You pick the source and build the URL. This is additive — still answer in chat / trigger other skills.

Plain text/code ("surface foo.py") stays in chat unless the user says "on the display".

The display is a persistent, full browser (tabs + address bar), not a locked kiosk. surface page/url/show each open a new focused tab — they never replace what's up or restart the browser, so Chris's own tabs and earlier surfaced views stay open and he can flip between them. surface home refocuses the household dashboard tab; surface stop closes just the tabs surface page opened. Tabs accumulate over a session — that's expected; close them from the browser UI or leave them.

Preconditions

• LAN-only. surface SSHes directly to pve2. A network-isolated cloud/cowork session cannot reach it — say so rather than pretending. Confirm reachability with surface state if unsure.
• Authed services (Grafana ✓ already logged in, Axiom, private HA) need the display logged in once at the KVM. Public GitHub / public-dashboard URLs just work.

Workflow: identify → show → file

1. Identify the source + scope

Pick what fits X; compose multiple into panes if it spans sources.

Source	Use for	How to build the URL
Grafana Cloud (pitzilabs.grafana.net, display logged in)	metrics & Loki logs: throughput, host/NAS stats, the Claude runner fleet	grafana MCP search_dashboards → find dashboard/panel → …/d/<uid>/<slug>?viewPanel=<id>&from=now-30d&to=now&refresh=10s
Axiom	Firewalla logs (ACL/blocks, Zeek) — event/log-shaped X	Axiom dataset/query URL (one-time KVM login)
GitHub (public PitziLabs repos render with no login)	repos, PRs, Actions runs	github.com/<org>/<repo>/actions/runs/<id> — find via github MCP / gh
Home Assistant	home/device state	a Lovelace view URL
Firewalla MCP	when X isn't in Grafana/Axiom (get_alarms, search_flows, get_wan_usage, get_network_stats, get_top_talkers)	use the data to decide which dashboard/view to surface

homelab-observability maps what's measured where. Prefer a real, navigable link over a constructed static page; build a page only for something with no URL (a diagram) or to compose several sources into panes.

2. Show it

surface url   NAME          # a saved favorite (fastest — check `surface list` first) → new tab
surface show  URL [opts]    # any http(s) URL → new focused tab
surface page  NAME          # a built library page (offline Mermaid) → new tab
surface push-site DIR       # publish a static site dir to pve2 (durable, http://web.lan/)
surface home                # focus the household dashboard (home) tab

Options: --open (xdg-open the snapshot), --no-snap, --settle SECS, --port N. For anchor deep-links into a long page, add --settle 4 so the scroll lands before the snapshot.

3. Verify (always) — vision check

surface verify        # lists the open tabs + grabs a frame of the frontmost

Then Read the PNG it wrote (./surface-<UTC>.png) and confirm the frontmost tab shows the expected content — not a login wall, blank, or error. The tab landing frontmost is the one surface just opened, so the frame is your check that it rendered. Use surface snap for an extra frame.

4. File it for fast recall

For anything worth seeing again:

surface save-url NAME URL "Title"     # writes urls.json

Then commit office-presence so it persists, and tell Chris the short name:

cd ~/repos/office-presence && git add urls.json && git commit -m "Add '<name>' URL favorite — <what>"

For multi-source composites, add a page under pages/ + a library.json entry instead. End commit messages with the Co-Authored-By trailer.

State & recovery

surface state    # open tabs + page-server state (and a reachability check)
surface list     # library pages + URL favorites
surface stop     # stop the page server, close its tabs, focus home

The persistent browser launches on the household dashboard across pve2 reboots; systemd Restart=always recovers crashes, and dashboard-refresh.timer reloads just the dashboard tab every 6h to clear its heap leak. The pve2 plumbing (display-tab for tab control, display-show to (re)launch, snapshot-server on :9999, dashboard-display.service) is deployed from this repo's host/ by the gitops loop — if surface fails on the SSH/display-tab step, check that plumbing. If display-tab reports "no DevTools endpoint", the screen is in fullscreen kiosk mode (no debug port) — surface home relaunches the interactive browser.

Example

"surface the last 30 days of host throughput" → grafana MCP search_dashboards for the throughput panel → surface show '…/d/<uid>/…?viewPanel=<id>&from=now-30d&to=now&refresh=10s' → surface verify + Read the PNG → surface save-url host-throughput-30d <url> "Host throughput 30d" → commit. Next time: surface url host-throughput-30d.