The previous layout put AddressProbeStep at the top with the agent card
below as "Or install the agent on the host." Both sections read as
alternatives to the probe, which made the probe the primary action even
though the probe is inherently a Platform-API-oriented move (figure out
which API to connect to). A user committed to the agent path has no use
for it. The "Recommended" chip on the agent card did not fix this — the
structural lead won.
Move the agent card to the top of the Add landing with no divider above
it (it's the primary, not an alternative). Fold the probe + platform
grid into a single "Or connect a platform API directly" section below,
so the ordering matches the story: agent first, API as fallback for
hosts the agent can't cover.
Architecture pin in settingsArchitecture.test.ts updated to guard the
new ordering: agent card copy indexOf < API section indexOf < probe
indexOf. Explicitly asserts the old "Or install the agent on the host"
divider is gone.
Flip the two sections so the agent card sits above the platform grid
and reads "Recommended" with a blue border. The platform grid is now
explicitly framed as "Or connect a platform API directly — for VMware,
TrueNAS, PMG, or a remote Proxmox you can't install the agent on."
The ordering matches what the agent actually delivers: on a Proxmox
host it mints the API token and auto-registers both PVE and PBS with
zero credentials paste (RunAll in internal/hostagent/proxmox_setup.go).
The platform grid is the right path when the target is an appliance
you can't install on or a remote machine. Visual weight now matches
friction.
Architecture pin extended to assert the section ordering so a future
edit doesn't silently swap them back.
On a PVE or PBS host, the agent mints its own API token and registers
the node via RunAll (internal/hostagent/proxmox_setup.go + agent.go
:1295–1340). That is the fastest path to a working Proxmox connection
— no address paste, no credentials. Previous copy framed the agent
purely as "host metrics you add on top," which hid the shortcut and
steered Proxmox users into pasting credentials they did not need.
Reframe the two sections:
- "Or connect a remote platform API" — five tiles for when Pulse lives
elsewhere from the target (PMG / VMware / TrueNAS have no host-side
agent path, and remote Proxmox reaches the tile from a different box).
- "Or install the agent on the host" — leads with "On a Proxmox host,
this is the fastest path," then keeps the host-metrics pitch for
bare-metal Linux / Unraid / FreeBSD / Docker / Kubernetes.
Architecture pins extended to guard the Proxmox auto-register copy.
The flat catalog put Install Pulse Agent beside Proxmox / VMware /
TrueNAS as a peer. A user arriving to connect Proxmox picks Proxmox
instantly and never learns the agent also adds CPU temperature, disk
SMART, systemd services, and Docker/Kubernetes auto-detect on the host
itself.
Split the landing into two sections:
- "Or pick a platform to connect" — five peer tiles for PVE / PBS /
PMG / VMware / TrueNAS. These are management-API integrations and
belong together.
- "Or install a host-level agent" — a distinct full-width card with a
"Runs on a host" chip. Copy names the telemetry the agent adds and
says explicitly that it layers *in addition to* a platform connection
above, not instead of one.
The agent is a different kind of integration from the platform APIs.
Framing it as a peer hid its value; framing it as an adjunct teaches
it.
The intermediate two-card picker screen ("Add connection" vs "Install
agent") restated the same decision twice and framed the agent path as a
walled-off alternative. Replace it with a single catalog landing that
matches how Datadog, Grafana, and GCP Marketplace present "add an
integration" — an address probe at the top, and a tile grid below
listing Proxmox VE / PBS / PMG / VMware / TrueNAS / Install Pulse Agent
as peer entries. Picking a tile or a probed candidate drops straight
into that product's credential slot; "Back to catalog" returns to the
landing.
Retires the ConnectionsExplainer component, the picker-mode state in
InfrastructureWorkspace, and the "Enter credentials manually" toggle
in AddressProbeStep. Tests updated for the shortened path (one click
from ledger header to any credential slot).
The two teaching cards lived permanently above the ledger, so every
repeat visit paid visual cost for content the user only needs when
adding something new. The new shape:
Ledger — just the table plus one "Add infrastructure" action.
Picker — clicking Add brings up the two cards on their own
screen ("Add connection" / "Install agent") with full
teaching context.
Sub-flow — the chosen mode runs as before: probe for Platform API,
install section for the agent. Each sub-flow exposes a
"Change method" button so the user can step back into
the picker without leaving add mode.
Legacy ?add=pick deep links still route into the new picker rather than
jumping directly into the probe.
The teaching cards and the ledger-header action buttons were duplicating
the same mode split: cards explained Platform API vs Unified Agent, then
the header restated it as "Add connection" / "Install agent." The cards
are now the entry surface — each carries its own CTA button inside the
card body — and the ledger header goes back to just titling the table.
Removes the dismiss (X) affordance; the cards are now functional, not a
tutorial banner, so they stay permanently visible. In read-only mode the
CTAs are hidden so the cards remain informational.
The two-card explainer teaches Platform API vs Unified Agent as peer
options, but the ledger-header buttons had Add connection rendered as
primary/blue and Install agent as secondary/bordered — implying Add
connection was the default choice. Neither is a default: the right one
depends on the user's system. Both buttons now use the secondary tone so
they read as peers, and the user's choice is driven by the explainer
above rather than by button prominence.
The Add screen's subtext offramp was the only path to the agent install
page, and that was the wrong design: the explainer teaches Platform API
and Pulse Unified Agent as peer modes, but clicking Add connection
funneled users into a probe-first flow where the agent path was a
footnote. Users wanting CPU/disk temps, SMART, or bare-metal Linux
couldn't find the page without hunting.
Changes:
- Ledger header now has two peer actions: Add connection (Platform API
probe) and Install agent (direct to agent install slot).
- Drop the always-visible "Install the Unified Agent on a host" subtext
from the Add screen; the header button makes it redundant.
- Enhance the probe no-match box to name bare-metal Linux / Unraid /
FreeBSD and offer the agent as a first-class alternative so a user who
probed the wrong thing isn't stranded on a Platform-API-only picker.
- Rewrite the infrastructure description to match: "Add connection for
Platform API setup; Install agent for host-level metrics or bare-metal
Linux / Unraid / FreeBSD."
Tests updated to match (architecture pins, workspace flow, editor
behavior). 41 affected vitest cases pass. Playwright-verified against
the live dev server: both header buttons route correctly, subtext is
gone, no-match box surfaces the agent alternative.
Agent rows already got an honest confirm-expansion ("Removing forgets
this agent from the ledger; history is retained…") plus uninstall
commands as a courtesy. Platform API rows (PVE / PBS / PMG / VMware /
TrueNAS) had nothing beyond "Click again to confirm," which left two
honest questions unanswered:
- Does this delete my history? (No — history is retained in v1.)
- Does this log me out of the platform itself? (No — credentials on
the platform side are untouched.)
Add a parallel expansion for non-agent rows that answers both directly.
Matches the plan's "user-facing copy in Remove dialog must be explicit"
note and keeps honesty symmetric between Agent and Platform API rows.
