First-run setup: the Wi-Fi network is a dropdown, Cloud is Recommended, and the phone setup asks one thing at a time (W-1073)

[wr]

Three changes to the first run, from the walkthrough of a new kit.

Screens, today and after, side by side: https://claude.ai/artifact/T4omY22whjoz3UnwBW1kUB (private to Wells)

What changed

Written for someone who has never heard of BirdNET (a kit opened as a gift): the default path needs no technical word, and the technical choices are a link off it.

• Kit setup portal, Wi-Fi (firmware/src/ff_portal.h): the networks are one dropdown, strongest first, with Other… for a hidden network, instead of a list that could run off the screen plus a separate Network field (the Macintosh mini setup page's pattern). It starts on "Choose a network", not the strongest network nearby, which may be a neighbour's; Save waits for a choice. An open network hides the password. A frame that knows its network (the KEY3 hold) has it chosen.
• Kit setup portal, own server: on Cloud the page asks only for the Wi-Fi. I have my own Featherframe server under Save opens one field, Your Featherframe server ("Leave it blank to find it on your network."), and becomes Use Featherframe Cloud instead. A frame already on its own server opens with the field showing. "After you save, your frame will show a QR code."
• Cloud's "Set up your frame" page (hosted/src/pages.ts), after a look at Sonos's and Oura's setup flows: full screens, as a phone app's setup is drawn, not a card. A column on a computer.
  • Welcome: the marketing page's scene full-bleed, cycling through its four birds: the site's clips of the cardinal, Eastern Bluebird, Tufted Titmouse and Black-capped Chickadee joined into one 24 s loop (public domain and CC BY-SA excerpts; the one playing is credited in the video's corner in the site's own words; six seconds each, each cropped to keep its bird clear of the frame, 4:3, 720 wide, no sound, 740 KB). The page follows the video's clock: each bird's "New detection" a moment after it lands, then the walnut frame, hanging off the video's bottom edge, repaints to its illustration. The frame is the kit being set up, from what it reported of its panel: the 13" colour frame for an EE02, the 10" gray one otherwise. It is cut in two, the walnut over a screen of its own, so only the screen repaints, dark, then light, then the illustration, as e-paper does. Only while the welcome shows; the cardinal, still, with reduced motion or no script. The Worker answers the video by byte range (util.rangeResponse, tested), since Safari plays nothing otherwise; a full cycle checked in WebKit. "Hear a bird outside. See it on your frame." "Your frame will show the latest bird heard near you, as a 19th-century illustration. Setting it up takes about two minutes." Get started, and I already have an account, which goes straight to the email as Sign in ("We'll email you a code to add this frame.").
  • Choose a station near you (1 of 2): "Your frame will show the birds heard by a station near you. Stations are microphones that people set up at home and share on BirdWeather." A ZIP code or town search with the usual location arrow inside it ("Use current location") beside Find; stations near the phone's guessed place, nearest first: each one's distance large on the right ("2 mi / away"), "38 kinds of birds this week" under its name, and the nearest tagged Closest. A search or location that fails is a callout that says what to do ("Location is off. Turn on location for this browser in your phone's settings, or enter your ZIP code or town."), not a muted line. I have my own BirdNET station swaps in Your BirdNET station: "Your frame will show the birds your station hears. Which one do you have?", BirdNET-Pi / BirdNET-Go, and once one is chosen, What happens next: "You'll create your account. The Featherframe webapp will show you how to connect your BirdNET-Pi. It takes a few minutes. Your frame will show the next bird your station hears."
  • Create your account (2 of 2): Email, "We'll send you a link to confirm your account. Your email address will never be shared or sold to anyone.", Set up frame.
  • Type and states: body text and list rows 17 px, field labels 15 px; the chosen row tinted and ringed in the accent. Location off, a place not found and no stations nearby are notices (gray, an "i"), with balanced lines so no word stands alone; only a failed request is a warning (red, a "!"). The video's credit fades between clips and stops short of the frame. The wordmark's face is preloaded and set to wait rather than flash Georgia. The email step opens with its field focused; while any field has the keyboard up, the button follows the form instead of sitting at the bottom of the screen, so the keyboard never covers it.
  • Color: the buttons, the chosen radio and the Closest tag are walnut a shade lighter at the top (a vertical gradient with a faint top edge, picked from seven colorways); links stay walnut. The chosen row is a warm tint with its radio filled, no ring. Location off is a tooltip from the location button over the page, gone at the next tap or keystroke, so nothing below moves; the button shows the page's spinner while it looks.
  • Each screen: a big title, one line, the field, the main button at the bottom of the screen in the same place every time, a back arrow. Still one form and one POST with the same fields; a page shown again for an error opens on that error's screen; Enter never posts a half-filled form. Eleven small webp files (each kit's frame and its screen showing each bird) and the video from site/public, bundled into the Worker and served like its icons.
• Future tense for what comes next on the kit's page and in the welcome email ("Its first picture will appear within a minute").
• docs/STYLE.md: future tense for what comes next; sign-ups read like everyone else's; first run is written for someone who has never heard of BirdNET, with technical choices as a link and never "No" as a default answer; the first-run pages may say "birds".

Verified

• Cloud: vitest 319 passed (new: the steps, the error's step, the colour kit's frame, telling the kits apart, what comes next for an own detector); tsc --noEmit clean.
• Setup page in WebKit at phone width (360, 390, 440), light and dark: both kits' welcome and a repaint frame by frame (only the screen changes), the credit's fade and its distance from the frame, stations found, location refused, a failed request, BirdNET-Go chosen, the email step focused and blurred; the script face loads with display: block; no script errors.
• Portal: rendered with firmware/tools/portal_preview.py and driven in headless Chrome at phone width: choosing a network fills the form, an open network hides the password, Other… shows Network name, the placeholder blocks Save, a known frame's network is chosen, Save goes through to Connected, no script errors, light and dark.
• Setup page: driven through every path in headless Chrome: Continue waits for a station, Back, BirdNET-Go skips the station, Enter, and the final POST carries source, station, email, tz and km as before.

Not covered

• On a kit: the portal is not flashed yet (CI builds the firmware). It ships with the next firmware release.
• On Cloud: not deployed. It goes out with the next wrangler deploy; that deploy is also the first bundle with .webp and .mp4 files (new rules globs beside the PNGs, about 800 KB in all; a dry run needs Docker, which isn't running here).

Wiki, when this ships

The setup page and Change Wi-Fi steps describe the old list and the one-page setup. This goes to the wiki with the release and the deploy, not before (check_copy.py --wiki clean):

diff --git a/Flash-the-frame.md b/Flash-the-frame.md
index d0f20a7..ab9f8fc 100644
--- a/Flash-the-frame.md
+++ b/Flash-the-frame.md
@@ -29,7 +29,7 @@ Firmware from the installer starts on Featherframe Cloud, and then shows a six-l
 1. Hold **KEY3** for 3 seconds. The frame opens **Featherframe-Setup**.
 2. On your phone, join **Featherframe-Setup**.
 3. Tap **Connect to Wi-Fi**. Leave **Network** and **Password** blank to keep the frame's Wi-Fi.
-4. Under **Server**, choose **Self-hosted**.
+4. Tap **I have my own Featherframe server**.
 5. Enter your server's address with `http://` and the port, for example `http://birdnet.local:8181`. Or leave it blank, and the frame finds the server on your network.
 6. Tap **Save**.
 
diff --git a/Set-up-your-frame.md b/Set-up-your-frame.md
index 802c943..6076ba0 100644
--- a/Set-up-your-frame.md
+++ b/Set-up-your-frame.md
@@ -15,10 +15,9 @@ Connect the frame to power. The screen shows three setup steps, and the light br
 ## 2. Connect it to Wi-Fi
 
 1. On your phone, open the Wi-Fi settings and join **Featherframe-Setup**. The **Connect to Wi-Fi** page opens.
-2. Tap your Wi-Fi network. If it isn't in the list, tap **Refresh**, or type its name under **Network**.
-3. Enter its password under **Password**.
-4. Under **Server**, keep **Featherframe Cloud**.
-5. Tap **Save**.
+2. Choose your Wi-Fi network under **Network**. If it isn't there, tap **Refresh**. For a hidden network, choose **Other…** and type its name.
+3. Enter its password under **Password**. An open network has none.
+4. Tap **Save**.
 
 On Android, if your phone asks whether to stay connected to a network without internet, choose to stay connected.
 
@@ -41,11 +40,14 @@ The code works for a day, and the frame says when it expires. If it expires, the
 
 ## 4. Fill in the setup page
 
-1. Enter your email address. You'll use it to sign in to your Featherframe webapp.
-2. Under **Detection source**, choose where the frame's species come from:
-   - **A BirdWeather station near me:** no equipment needed. Choose a station near where the frame will hang. To look somewhere else, type a ZIP code or town and tap **Find**, or tap **Use my location**. If no station is near you, type a larger town nearby and choose the closest one.
-   - **My BirdNET-Pi** or **My BirdNET-Go:** your own detector. You'll connect it after setup. See [Detection sources](Detection-sources).
-3. Tap **Set up frame**.
+1. Tap **Get started**.
+2. Choose a station near where the frame will hang, then tap **Continue**. Stations are microphones that people set up at home and share on BirdWeather, and the frame will show the birds the one you choose hears. To look somewhere else, type a ZIP code or town and tap **Find**, or tap the arrow in the search box to use your current location. If no station is near you, type a larger town nearby and choose the closest one.
+3. Under **Create your account**, enter your email. You'll use it to sign in to your Featherframe webapp.
+4. Tap **Set up frame**.
+
+If you have your own BirdNET-Pi or BirdNET-Go, tap **I have my own BirdNET station** in step 2 and choose it instead. You'll connect it after setup. See [Detection sources](Detection-sources).
+
+If you already have a Featherframe Cloud account, tap **I already have an account** instead of **Get started**, and enter your email. We'll email you a code that adds the frame.
 
 Your phone is now signed in to your Featherframe webapp, at [cloud.featherframe.app](https://cloud.featherframe.app).
 
diff --git a/Style-guide.md b/Style-guide.md
index 5844191..4acaf97 100644
--- a/Style-guide.md
+++ b/Style-guide.md
@@ -44,6 +44,13 @@ in the repository, which wins if they disagree.
 - **Typography.** Sentence case for headings, labels and buttons. En dash
   for number ranges (1–5). Curly quotes are optional; be consistent within
   a page.
+- **Future tense for what comes next.** "After you save, your frame will
+  show a code", not "your frame shows a code". What is always true stays in
+  the present: "the frame shows the latest detection". A "when" clause stays
+  present too: "When the frame shows a code, scan it."
+- **Sign-up and sign-in read like everyone else's.** "Create your account",
+  "Email", "We'll send you a link to confirm it." Not "You'll sign in with
+  it to manage your frame."
 - **Times, as people write them.** A 12-hour clock with AM and PM: 7:00 PM,
   6:30 AM. A span of time takes an arrow: 10:00 PM → 6:00 AM, Sunset →
   Sunrise. A recent moment is relative: just now, 4 min ago, 2 hours ago,
@@ -86,8 +93,10 @@ of Asia*, *The Birds of Great Britain*.
 
 **"Bird."** In the webapp, never use "bird" for a detection, a species or an
 update: "a new detection reaches the frame", not "a new bird shows up".
-Names and titles that contain the word are fine. The wiki, README and
-marketing page may say "bird" where a person would.
+Names and titles that contain the word are fine. The wiki, README,
+marketing page and the first-run setup pages (the kit's Wi-Fi page, Cloud's
+"Set up your frame") may say "bird" where a person would: "Your frame will
+show the birds heard by a station near you."
 
 **"Plate."** A plate is a numbered sheet of a printed book. The webapp never
 says it (an owner sees illustrations). Docs may, once the page has said what
@@ -117,6 +126,12 @@ a plate is, and the corner mark cites one ("Plate CLIX").
 - **Errors say what to do**, not what broke inside.
 - **No architecture.** A section never opens with an intro about how the
   system works.
+- **First run is written for someone who has never heard of BirdNET** (a kit
+  opened as a gift). The default path needs no technical word and can be
+  taken with confidence. A technical choice (a detector of your own, a
+  server of your own) is a link off the default, for those who know to look
+  for it: "I have my own BirdNET station". Never make "No" the default
+  answer.
 
 ## The frame's own screens
 
diff --git a/Troubleshooting.md b/Troubleshooting.md
index e51370f..318576e 100644
--- a/Troubleshooting.md
+++ b/Troubleshooting.md
@@ -107,7 +107,7 @@ In your Featherframe webapp, go to **Detection source**, and paste the URL of th
 2. On your phone, join **Featherframe-Setup**.
 3. Tap **Connect to Wi-Fi**.
 4. Tap **Show networks**.
-5. Tap the new network.
+5. Choose the new network under **Network**.
 6. Enter its password under **Password**.
 7. Tap **Save**.

Refs W-1073

[linear-code]

W-1073