stack/docs/scratchpads/gateway-install-ux-20260404.md

Gateway Install UX Fixes — 2026-04-04

Context

User hit two publish-drift bugs on mosaic gateway install (fixed in #386 and #389). On top of those, the install UX itself has three concrete problems:

1. Admin API token is generated by the bootstrap step and saved to ~/.config/mosaic/gateway/meta.json, but never shown to the user. There is no way to retrieve it without reading the file or running mosaic gateway config afterward.
2. When install crashes mid-way (e.g. daemon fails to become healthy), the next run of mosaic gateway install prompts "Reinstall? [y/N]". Saying N aborts, leaving the user with a half-configured install and no clear path forward. There is no resume path.
3. Health-check failure only prints "Check logs: mosaic gateway logs" — forcing the user to run another command to see the actual error.

Goal

Make mosaic gateway install a single end-to-end, resumable command that shows the admin token on creation and surfaces errors inline.

Plan

• install.ts: detect partial state (meta exists, no admin token, daemon not running) and skip already-completed phases instead of aborting.
• install.ts: add a prominent "Admin API Token" banner printed right after bootstrap succeeds. Include copy-now warning.
• install.ts: on health-check timeout, read the tail of LOG_FILE and print the last ~30 non-empty lines before returning.
• Keep mosaic gateway config as-is (view/edit env vars); this is not the setup wizard.
• No new commands. No new flags yet.

Out of scope

• Readline/stdin piping fragility (pre-existing, not related to user complaint).
• Refactor to a phased state machine (overkill for three targeted fixes).

Verification

• Typecheck, lint, format (mandatory gates).
• Manual end-to-end: fresh install → confirm token displayed.
• Manual resume: delete daemon.pid mid-install → re-run → confirm it resumes.
• Manual failure: point ENV_FILE port to a used port → re-run → confirm log tail is printed.