Guidance: a get-started checklist and next-step hints

[fylorn]

First run. The Overview's "never used" empty state becomes a three-step checklist:

1. Add an upstream.
2. Connect a client.
3. Send a first request.

Each step is ticked from the current facts, not from which buttons were pressed:

• How many upstreams there are.
• Which clients are connected: adopted, set up by hand with a key, or already probing the gateway.

So an upstream added elsewhere counts too. Only the current step offers its button ("New upstream…", "Go to Clients"), and the third step shows that it is waiting for a request. When the first real request arrives (local answers to probes do not count, matching the Overview's existing rule), the checklist gives way to the usage figures.

During use. One-line hints appear at the moment they apply. Each carries the button for the next step and "Don't show again", and disappears on its own when its condition stops holding:

Where	When	Next step
Overview	the first request went through (only for people who saw the checklist, so upgraders are never told about a "first" request)	View request
Upstreams	upstreams exist, no client is connected, no requests yet	Go to Clients
Clients	no upstream yet	New upstream…
Clients	clients are connected (named) but no request has arrived	Go to Traffic
Traffic	there are requests	(what opening one shows)
Security	protections in Observe (with the count)	(set to Enforce once the log shows no false positives)

Settings. Dismissed hints are kept on this computer (localStorage, key tw-guide), not in config.yaml. Settings › General gains Guidance › Show again, which is disabled when nothing has been dismissed.

Implementation. Everything lives in src/guide/ and builds on the existing Banner. Hints get one lightbulb icon used for nothing else. The copy follows the terminology table ("接管"). The copy test bans 「知道了」 as conversational, so the dismiss action is 「不再显示」.

Tests: src/guide/hints.test.ts covers showing, dismissing across a restart, resetting, the setup-seen flag, unreadable storage and storage that cannot be written; the full suite and tsc pass. Checked in the preview harness in light and dark mode, zh and en, at 1100×720:

• fresh install;
• upstreams and clients configured but no traffic;
• a live first request, with "View request" opening it;
• Traffic, Security and Settings;
• dismissing and resetting.

🤖 Generated with Claude Code