Upgrade the client app UX: launch hub, first-run setup, Account/Configuration split, hint-only default

[alpha5611331]

Closes #124. Supersedes #121, which GitHub closed when this branch was renamed.

The problem

Everything the app can do was reachable, and almost none of it was findable. / redirected into the control console; the console's capabilities lived in a 32px icon row; one "Settings" page answered two unrelated questions; and nothing anywhere told a new user what they had to set before their first interview. The two most expensive failures in this app — an empty profile and the wrong microphone — both present as silence rather than as errors, in the middle of a real call.

What changed

Twenty-seven commits, each buildable and testable on its own.

1. refactor(suggestions) — hint-only / full-sentence

"Professional mode" named neither of the two things it switched between, so the tooltip, the status badge and the settings row all had to explain the setting rather than label it. The modes now carry their own names: hint-only (a headline plus keyword bullets, read at a glance) and full-sentence (the answer written out as it would be spoken).

Hint-only becomes the default for a new install. Reading a paragraph of prose while an interviewer waits is the thing candidates cannot actually do, and the mode built for that should not be the one nobody finds.

Two things deliberately did not move with the rename:

• The wire values stay normal / professional. They are the backend's contract (app/schemas/suggestion.py), it deploys separately, and renaming the TypeScript members without renaming the strings keeps the client readable without shipping the two together. Both mirrors say so.
• An existing install keeps the mode it was on. The migration reads professionalMode one last time to seed hintOnlyMode, then scrubRetiredKey removes it — so the rename cannot silently change what current users see in the panel. test/config-store.test.mjs pins both halves.

The hotkey keeps Ctrl+Shift/Ctrl+Opt+F7; only its IPC channel, title and description change.

2. refactor(settings) — Account and Configuration, not "Settings"

The split follows a real difference, not a taxonomy:

	Account	Configuration
Answers	Who am I	How does the interview run
Holds	email, full name, profile/CV, job context, password	microphone (+ test), language, suggestion style, transcript panel
Shares	—	every field is a component the wizard and the mock dialog reuse
Writes to	the backend account, as one unit	the local config, per control
Save button	yes — a half-written profile is worse than an unedited one	no — nothing can be half-applied

Configuration gains what the old Session tab never had: a microphone picker with a live level test. Choosing a device from a list said nothing about whether the machine was listening to it.

Each setting is now a component under components/custom/settings/, and the three account fields share use-account-form.ts. Both exist so the wizard renders the same controls rather than a second, drifting copy.

Also lifts the sticky header each routed page had its own copy of into page-header.tsx — including the location.key === 'default' fallback that a reload otherwise turns into a dead back button — and adopts it on Documentation and Buy Credits too.

3. feat(onboarding) — first-run setup

/onboarding asks once for the six things a first interview needs, one per step, in the order it needs them: profile, job context, language, microphone, suggestion style, transcript panel. Every step renders the same component the two settings pages use.

• Only the profile step gates progress. The name and CV are what the control bar checks before it will start anything; letting the wizard past them would only move the failure later.
• Skip is available throughout and records the same completion — nagging someone who has decided is worse than the state it would protect them from.
• The account fields are written on the way out of each account step, and again on Skip. They are the only thing here the user typed, and a window closed on step four should not cost them a pasted CV.
• Gated on onboardingCompleted, local rather than account-level because half of what the wizard sets — the microphone above all — is a property of the machine. An install that predates the wizard is migrated straight past it.

4. feat(home) — the launch hub

/ now names all five things a user comes here to do: start a mock interview, start the live assistant, Account, Configuration, Buy Credits.

Both buttons start a session — neither implements starting one. Live hands off to /main through router state, because /main's control panel owns the whole start sequence — the config and microphone checks, the headphone notice, the macOS permission gate, the save-history guard — and a second copy of that here is how the two would drift apart. Mock opens the same setup dialog the control bar uses, which collects the session's shape and hands the result to /mock-interview. In both cases the click ends in a running session, not on a console with a Start button waiting to be pressed again.

That handoff is deferred, not fired on arrival: checkCanStart reads the account config and the enumerated microphones, neither of which has resolved in the first frames after a route change, so starting immediately would greet the user with "could not load your saved configuration" for a config that was about to arrive.

5. feat(session) — stopping offers to save, then goes home

Stop only stopped. The transcript stayed in main-process memory with nothing on screen saying it was still there and nothing saying it was about to go, and the first question about saving it arrived at the start of the next session — a question about an interview the candidate had finished with an hour earlier, asked at the moment they are trying to begin a new one.

Stop now ends the session, asks whether to keep it, drops the buffers and returns home. stop is the first reason in save-history-dialog.tsx that is not a guard: the other four are asked before the destructive act and can be answered with "not now", which leaves the interview alone. This one is asked after, so it drops its Cancel and refuses Esc — an Esc that read as backing out would silently be the discard.

Deliberately not what the stop hotkey does. That one is the stealth-mode escape: it fires while the app is hidden mid-screen-share, where a modal dialog and a navigation to a dashboard are the opposite of what was asked for. It still stops, and the next Start still asks about what it left behind.

The control bar's Stop and the command palette's both route through one hook, so the two cannot drift.

6. feat(mock-interview) — the language is set where it is read

The dialog whose entire job is configuring a session showed the language as a read-only row and told the user to change it on another screen — the one setting there that could not be set where it was being read. It is now the same LanguageField the configuration page and the wizard use, editing the same stored setting, because there is only one: a mock session reads the language the live assistant does.

showVoice is new on that field and only the mock passes it. The live assistant never speaks, so whether a language has a Deepgram voice is a fact about mock interviews alone — it marks the voiceless languages in the list itself, where it is needed while choosing.

7. refactor(control-bar) — /main only stops

Starting is a home-screen decision now, so the control bar's split Start button was a third way to do the same thing — with its own dropdown, and its own stored memory of which mode you last used, to answer a question the home screen asks outright. /main carries Stop and nothing else. Idle is a transient state on that route rather than its resting one (a start cancelled at the headphone notice or the permission gate, or the route opened directly), and the primary slot holds a way back home for it, because an idle console with an empty primary position is a dead end.

Three things follow from the removal rather than being separate changes:

• The mock setup dialog moves to the home screen, its only caller now. "Practise again" on the report and the palette's mock start hand off there instead of to /main, and the mock route's other two exits follow them home.
• lastSessionMode is removed and scrubbed from disk. It existed solely to decide what the split button did by default; leaving a key the app still writes and never reads is how config rots.
• /main's router-state handoff narrows to the live start, the only thing that still arrives that way.

8. feat(home) — Sign out

Reachable only from the titlebar menu and the command palette before — a strange place for the one action that ends everything else the screen offers. Refused while a session is running, with the reason on the control.

9. refactor(onboarding) + fix(onboarding) — the flag moves to the account, and the wizard becomes answerable

The completion flag started as a local config key, which cannot answer the question it was asked: a user who set up on their laptop was walked through it again on their desktop, and a second account on a shared machine never saw it at all. It lives on the account now (backend#62, merged), and the local key is scrubbed rather than merely ignored.

Then a UX pass on the wizard itself, which had six things wrong with it:

• A disabled Continue said nothing. It now names what is missing, and the "account unreachable" case gets a Retry rather than an instruction to restart the app.
• Typing while the account loaded lost what was typed. The fetch runs to thirty seconds and the fields render immediately. Fields are disabled until it lands, and a late response no longer overwrites edited fields.
• Enter did nothing. The step is a form; Enter advances from any single-line field.
• Nothing said where you were. The screen names itself, the progress line names the step, completed steps read differently from the current one, and the heading takes focus on every change.
• The titlebar offered three ways out that all looked broken. Hidden during the compulsory run; left alone for a voluntary one.
• Skipping looked final. Configuration offers Run setup, so the button says "Skip for now" and finishing confirms itself.

And the wizard ran twice, every time. Its write to the account resolves over one IPC message and the app state carrying the result arrives over another, with nothing ordering the two — so home re-rendered on the old value the instant the wizard navigated to it and sent the user straight back in. A session-local dismissal now says "done now" while the account flag says "done"; the gate reads both.

10. fix(onboarding) — interface size joins Configuration and setup

Zoom was a control-bar button and a hotkey, which is no use to the person who needs it: this window is small on purpose so it does not cover the call, and a candidate squinting at a suggestion mid-question is not going to go hunting for a zoom control. zoom:set-factor is new — an invoke rather than a send, unlike the three beside it, so the field's readout cannot drift from the window when a value is clamped.

11. feat(mock-interview) — the question is written out as it is spoken

A whole paragraph appearing at once, followed a second or two later by a voice starting to read it, does not read as someone asking a question. The reveal is timed against the first audio chunk actually sounding rather than against the Speaking state — that state begins before the first sentence has been synthesised, so timing against it would have put the words up during the silence and made the gap worse.

Presentation only: the backend returns the question whole. It paces at roughly twice speech so the last word lands before the sentence ends, gives up waiting for audio after 2.5s so a failed synthesis cannot leave an empty row, shows everything at once under prefers-reduced-motion, and keeps the full text in the DOM for assistive technology throughout.

12. A review pass over everything since v1.7.1

The last pass reviewed this branch against the release rather than against itself, and found five
defects — four of them cross-account, on a machine two people share.

• Sign-out left the interview in memory. It cleared the token and the account config and
  nothing else, so the transcript, the suggestions and the whole mock session survived it — and
  the close guard reads hasHistory / hasMockContent straight off that state. A second user
  signing in and closing the app was offered "Save this interview before closing?" and would
  have exported the first user's questions and spoken answers to a file.
• Sign-out was only guarded against a live session. A mock session deliberately leaves
  runningState on Idle, so the check waved it through and the candidate could sign out from
  under an interviewer that was mid-question.
• Sign-out did not ask. It destroys an interview that is not on disk unless it was exported —
  the definition the save-history guard already applies to Clear, Start, Stop and closing the app.
• The setup dismissal was cleared from the index route, which only sees the sign-outs that
  happen while it is mounted. Sign out from Configuration and the next account to sign in was
  never offered setup at all — the exact hole the reset existed to close, open on every route but
  one.
• Home and Account reported who was remembered, not who was signed in. ConfigStore.email
  is a credential the login form writes only under "remember me", so a user who declined it — on
  a shared machine, where declining is the reasonable choice — was shown "Not signed in" on the
  home screen of an app they were signed into. The account's own email is carried in app state
  now, and cleared with the rest on sign-out.

Two more from the same pass, both introduced by this branch:

• Leaving a mock interview mid-session ended it silently, and this branch added five new
  one-click ways to leave (titlebar Home and the two settings pages, the same in the palette, and
  the palette's two Start actions). Guarded with useBlocker rather than a check on each, because
  that list grows.
• The home screen's live start could fire before /main's config had loaded, opening the ASR
  socket with an empty session token. A hand-pressed Start was always well clear of that.

test/account.test.mjs gains ten assertions covering the pull-then-clear cycle for all three
account fields, and the absent-flag rule.

13–27. Docs and earlier review fixes

ux-conventions.md now points at the two settings pages with the rule for choosing between them, and gains one convention the work argues for: a setting the app cannot work without is not finished when it appears on a settings page — it goes in the wizard too, rendering the same component. CLAUDE.md, SPEC.md, the in-app Documentation page and the README follow.

The remaining commits are fixes found reviewing the flow end to end — see "What review caught" below.

Judgment calls

• The wire enum was not renamed. Renaming 'professional' to 'hint_only' would have required the backend to deploy in lockstep with the client for a cosmetic gain. The TypeScript members are HintOnly / FullSentence; the strings are the contract.
• Existing users keep full-sentence mode. The new default applies to new installs only. A rename that quietly changed what long-time users see in the panel mid-interview would be a worse bug than the one it fixed.
• onboardingCompleted is local, not account-scoped. The cost is a second account signing in on a machine where the first has already been through the wizard: it does not run again, and that user reaches Start with an empty profile. They are not stranded — the control bar names the missing field and sends them to Account — and scoping the flag to an account trades this for a worse failure: re-running the wizard for the same person on every new machine. Documented where the flag is declared.
• Configuration keeps a keyboard-shortcuts entry, beyond the four settings the brief names. The cheat-sheet was previously the Settings page's Shortcuts tab; dropping it entirely would have removed a surface rather than moved it.
• The mock setup dialog stays. Home's mock button opens it rather than starting with remembered defaults: seniority, length and difficulty are the whole shape of the session, and a mock that silently reuses last week's settings is worse than one extra press.
• /main keeps no Start at all, not even a disabled one. The idle slot holds a Home button instead: a disabled Start would imply the screen could start something, and an empty slot would strand anyone who cancelled out of the headphone notice.
• The onboarding flag is on the account, and there is no backfill. Existing accounts read as false and are offered the wizard once, prefilled and skippable. A backfill would spare them that screen and cost a migration plus a startup query on every boot — and this release changes the default suggestion mode and adds a microphone test, which makes showing them once the better half of that trade.
• Stopping clears the session. The save prompt is therefore the genuine last chance, and the console is empty when you return — rather than holding a finished interview that only the next Start would ask about.
• "Full name", not "username". It is the string the prompts address the candidate by, and it is what the rest of the app already calls it. The sign-in identity (email) is shown above it, so the page carries both.

What review caught

Five holes, each fixed in its own commit rather than folded back:

1. Signing in redirected to /main — the one route the first-run gate does not cover. The users the wizard exists for were the users who would never have seen it. Sign-in now lands on home.
2. Finishing the wizard navigated home whether or not the completion flag was written. Home gates on that flag, so a failed write bounced the user straight back into the wizard with no explanation — a loop, not a degraded state.
3. Skip discarded a CV that had just been pasted in, and the deferred live start could fire twice under StrictMode (the effect runs twice on mount with no render in between, so the recomputed condition was not what stopped the second run — the ref is).
4. The palette's second Start was swallowed. The arrival intent was consumed once per mount, which was right while every request arrived with a route change and wrong the moment one could arrive without one — firing Start from the palette while already on /main is the same mount. Guarded per history entry now.
5. Home offered "Start mock interview" during a live session, and routed the user to a screen whose only content was the main process refusing it. The card now names the reason and leaves the tab order; the live card becomes the way back to the interview it would otherwise offer to start again.
6. An older backend would have locked the app. A deployment without onboarding_completed omits it, and the client read that as false — sending every user of that deployment into a wizard whose only two exits write through an endpoint it does not have either. Absent counts as done now: guessing wrong that way costs a screen nobody saw, the other way locks the app.
7. A slow account pull could revert a just-finished setup, putting the wizard back in front of someone who had completed it. The write bumps the generation now, the same way saving a profile does.
8. A voluntary Run setup was dressed as a first run — "Skip for now" as the only way out of a page the user chose to open, with the titlebar's navigation taken away.

test/mock-session-scroll.test.mjs caught the mock route's redirect target when it moved, which is what that assertion is there for.

Test plan

• pnpm lint clean across the project
• tsc -b (renderer) and tsc -p tsconfig.electron.json (main) both clean
• pnpm test:main — all checks pass, including new config-store assertions for the rename migration, the key scrub, and the onboarding migration
• pnpm run build succeeds end to end
• Manual walkthrough in the packaged app: fresh install → sign up → sign in → wizard (all six steps, Back, Skip, mic test with a real device) → home → both launch buttons → Account save and Change Password → Configuration (mic test, language switch, style switch, transcript toggle) → Buy Credits → Ctrl+Shift+F7 and the control-bar toggle mid-session → Stop (save prompt in both formats, and discard) landing back on home with an empty console → the stop hotkey in stealth mode, confirming it does not prompt or navigate → a mock interview, confirming the question is written out in step with the voice and that a text-only language reveals immediately → Run setup from Configuration, confirming it reads as a page rather than a first run → an upgrade over an existing install, confirming the previous suggestion style survives and the wizard does not appear

[gitar-bot]

Gitar is working

_Gitar