feat(installer): first-run UX — interim slice of the v2 spec (copy, naming, location fix, clearer errors)

[LukasWodka]

Summary

Interim slice of the installer first-run UX v2 spec (tracebloc/backend#992): every improvement that is safe against the released CLI (v0.5.1) ships here; the full 4-section restructure is gated on tracebloc/cli#137 + tracebloc/cli#138 reaching a release.

Originally opened as a line-by-line UX pass off a real failed prod install (a typed city — berlin — died with only "see the log"); extended with the spec's copy decisions.

What's in

Bootstrap / banner

• Verification reframed as plain-language reassurance (no cosign/manifest jargon, no alarming "not found"); lowercase brand; redundant "Running… environment setup" line dropped.
• Vendor value-prop lines removed from the banner (bash + PowerShell); the trust claim lives in the verified connected summary — now phrased "Models other collaborators submit…" (naming rule: collaborators, never vendors).
• The inaccurate "nothing modified outside ~/.tracebloc and Docker" promise dropped.

Step 1 (GPU) — Apple-Silicon messaging de-duplicated; ⚠ on the real limitation (no GPU training on macOS), not on the chip.

Step 3 (provision)

• Name this machine → Name this client (noun rule: machine = hardware, client = tracebloc entity).
• Location: auto-detected from the system timezone (OS zone.tab, no network) and offered as the Enter-default. Fixes a live prod bug: the shipped prompt says "optional", but v0.5.1's client create hard-requires --location when it can't prompt — so skipping doomed the create with the error buried in the log. Now: Enter accepts the detected zone; no detection → re-ask (3 tries) instead of minting a doomed request; unattended runs fall back to the detected zone silently. (Prompt disappears entirely once cli#137 ships.)
• Client-create failures surface the real reason inline (e.g. "berlin" isn't a recognized carbon zone) instead of "see the log".

Summary — next steps rewritten around the goal chain: ingest data → create your use case (https://ai.tracebloc.io/my-use-cases) → invite other collaborators; training explicitly gated on the user's approval; dashboard + tracebloc --help demoted to footnotes.

Step 4 / Windows — stale dataset push/rm → data ingest/delete; internal ticket refs (RFC-0001 R8) removed from user-facing errors.

Testing

bats: 67/68 across provision, bootstrap, install-cli, summary, common (the 1 failure is the pre-existing environmental validate_config case — fails identically on untouched develop). Auto-detect verified on macOS (Europe/Berlin → DE). Syntax-checked; summary trust-claim assertions still pass.

Follow-ups (filed)

• tracebloc/backend#992 — umbrella: 4-section restructure, zero mid-flow prompts, honest progress (full spec + copy)
• client create: auto-generate the client name (<firstname>-NN) and make --location optional cli#137 — auto-name <firstname>-NN, --location optional
• Installer-facing contract: login progress display, auth status --check, backend connect confirmation cli#138 — login progress display, auth status --check, backend connect confirmation
• tracebloc/backend#993 — "location not set" state instead of the silent DE carbon default

🤖 Generated with Claude Code

[LukasWodka]

👋 Heads-up — Code review queue is at 34 / 30

Above the WIP limit. The team convention is to review existing PRs before opening new work.

Open PRs currently in Code review (oldest first):

• averaging-service#143 — chore(release): promote develop → staging (week of 2026-07-06) · author: @aptracebloc · no reviewer assigned
• averaging-service#156 — feat(strategies): FedMedian Byzantine-robust aggregation (ci: add kanban closure-routing caller workflow #75) · author: @shujaatTracebloc · reviewer: @divyasinghds
• averaging-service#157 — feat(strategies): FedTrimmedAvg Byzantine-robust aggregation (ci: add kanban closure-routing caller workflow #75) · author: @shujaatTracebloc · reviewer: @divyasinghds
• averaging-service#158 — feat(strategies): Krum / MultiKrum Byzantine-robust selection (ci: add kanban closure-routing caller workflow #75) · author: @shujaatTracebloc · reviewer: @divyasinghds
• averaging-service#159 — feat(strategies): FedProx aggregation strategy (docs(migration-tools): tenant migration runbook for eks-1.0.x → client-1.x #74) · author: @shujaatTracebloc · reviewer: @divyasinghds
• averaging-service#160 — feat(strategies): FedOpt family — FedAdam / FedYogi / FedAdagrad (docs(migration-tools): tenant migration runbook for eks-1.0.x → client-1.x #74) · author: @shujaatTracebloc · reviewer: @divyasinghds
• backend#927 — feat(validators): schema check for tabular/text/token classification (#924 G2) · author: @divyasinghds · no reviewer assigned
• backend#931 — feat(validators): generic all-category checks + validation matrix (#924 Phase 0/G12) · author: @divyasinghds · reviewer: @saqlainsyed007
• backend#934 — feat(validators): column-level tabular/text schema diagnostics (#924 G3/G4) · author: @divyasinghds · no reviewer assigned
• backend#935 — feat(validators): time-series & survival temporal checks (#924 G8/G9) · author: @divyasinghds · reviewer: @saqlainsyed007

Pull from review before opening new work. (This is a nudge from the kanban WIP check, not a block.)

[saadqbal]

Nice, careful PR 👍 The location auto-detect (no network, OS zone.tab) and the inline create-failure reason are exactly right, and the manifest is clean.

Pushed two small robustness fixes on top (f6e2607) rather than leaving them inline:

• trim name/location before the silent auto-detect fallback — a whitespace-only location answer was slipping through non-empty and re-dooming the create;
• capture create output under HOST_DATA_DIR instead of a predictable /tmp path when mktemp is unavailable (symlink-clobber target under sudo).

Both are edge cases; nothing blocking. Good to merge once green.