fix(mosaic): resumable gateway install + prominent admin token (#393)

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

@@ -0,0 +1,47 @@
+# 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.