# 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.