archy/.planning/todos/pending/2026-08-02-onboarding-step-name-your-node.md

created, title, area, severity, files

created	title	area	severity	files
2026-08-02T15:30:00.000Z	Add a "name your node" step to onboarding (sets the real hostname)	ui	major	neode-ui/src/views/OnboardingName.vue (to create — match the existing onboarding step design) neode-ui/src/router/index.ts (:26-76 — the onboarding child routes, in flow order) neode-ui/src/composables/useOnboarding.ts (step persistence / resume) neode-ui/src/views/settings/AccountInfoSection.vue (the existing post-onboarding rename UI — reuse its validation) core/archipelago/src/api/rpc/system/handlers.rs (:462 hostnamectl, :58 + :765 regenerate_tls_cert — backend already exists, no change expected)

Problem

Dorian (2026-08-02): wants a step in the onboarding flow to name your node — in the same design language as the existing steps — which changes the actual hostname.

Today naming only exists after onboarding, in settings/AccountInfoSection.vue. A fresh node keeps its install-time default until the user goes looking for the setting.

What already exists (no backend work expected)

server.set-name (dispatcher.rs:459 → handle_server_set_name) already:

• runs sudo hostnamectl set-hostname <name> (system/handlers.rs:462)
• regenerates the self-signed TLS cert with a SAN covering <name>, <name>.local, localhost, 127.0.0.1 (:58 → regenerate_tls_cert, :765)
• reloads nginx

Current onboarding order (router/index.ts:26-76): Intro → Options → Path → SeedGenerate → SeedVerify / SeedRestore → Did → Identity → Backup → Verify → Done.

The hazard that decides the design

Renaming mid-flow can disconnect the user before their seed is backed up.

The browser is connected to the node over its current hostname and current TLS cert. set-name changes both: the mDNS .local name moves, and the cert is reissued. A user onboarding at https://archipelago.local who renames to mynode can lose the session in the middle of onboarding — potentially between seed generation and seed verification, which is the worst possible moment to drop someone.

That makes step placement a design decision, not an implementation detail. Roughly:

1. Last, just before Done — everything security-critical (seed shown, verified, backed up) is already complete, so a dropped connection costs nothing but a reload. Safest.
2. First, before anything else — the rename happens while there is nothing to lose, but the user is asked to name a node before they have any context for what it is, and they may still be mid-redirect when the cert changes.
3. Defer the apply — collect the name early for good UX, call set-name only at the end. Best of both, at the cost of holding state across steps.

Option 3 or 1 is almost certainly right. This needs deciding explicitly rather than by whichever screen the code lands on.

Also needs deciding / checking

• Validation + slugification. Hostnames are RFC-1123: lowercase alphanumerics and hyphens, ≤63 chars, no leading/trailing hyphen. A user will type Dorian's Node. Decide whether to slugify silently, show the slug live ("will be reachable at dorians-node.local"), or reject. Reuse whatever AccountInfoSection.vue already does rather than inventing a second rule.
• Does the rename propagate everywhere it should? The Reticulum daemon takes a --display-name, and mesh/FIPS surfaces show node names. Confirm whether set-name updates those or whether the node keeps its old name on the mesh until restart.
• Reconnection UX. If the cert/hostname change does drop the session, the step should say so in advance and tell the user where to come back to — not fail silently into a dead tab.
• Skippable? A node with no name is fine; forcing a decision at first run is friction. Decide whether the step has a "keep the default" path.

Solution

Own scope — a quick task or a small plan, not a freehand edit, because of the disconnect hazard above. Sequence it after the in-flight regenerate_tls_cert atomicity fix lands (that fix makes the rename path write the key to a staging file and validate before swapping, instead of truncating the live key in place if openssl fails partway — renaming is exactly the path it protects).