c145. Setup Tour: plan (stage 1, for Mark's review)

What's asked. The tour should say what the Status dot means in each state, and offer to connect when the machine isn't connected ("Connect it now? Yes, connect it now"). It could also be a second way to connect and configure the app (initial-prompt.md). Nothing is built yet. This plan, and the wording below, are for ruling first.

What the app has today (qnative, read 2026-11-13)

• The dot has three colours (crates/app/src/pages/status.rs state_line):
  • green: qcontrol is on;
  • amber: degraded, meaning running but missing part of the picture;
  • grey: off or starting.
  
  Nothing is blue or red. Since 2026-11-13 the dot is 26 px, twice the name's x-height.
• Connecting is a separate fact from the dot. The plane line says "plane: not connected". c131 D22 treats being local as a legitimate way to run, not a fault:
  • local: "This machine runs on its own. The configuration lives here and you can change it."
  • connected: "You're connected to HQ. The configuration is managed there."
• There's no Connect page yet. crates/app/src/messaging.rs says "Connect is not built yet; it comes with c131's Connect page". c131 plans its four states (not connected, signing in, connected, failed), D13 (base URL plus credential), and the deep link qpoint://connect. c137 inventory row 15 adds connect-request for planes that require approval.
• The tour can't hold a button in a callout. qguikit::tour::Marker is a label, and the overlay takes no clicks. The panel has one seat for an action, the step's button: today Action::Simulation, shown only while its goal isn't met (design c144).
• Callouts can't change with state yet. A callout's when knows only the simulation's stopped and played (theatre::callout_shown). There are no sensor.state or plane.state facts (crates/app/src/tour/facts.rs).

Rulings to make (with a recommendation each)

1. Where it lives. Recommend both, in two weights:
   • New to Qpoint stays an explainer for everyone. Its Status callout changes with the state.
   • A separate tour, Set up this machine, has the actions. It lists its goals and skips any that are already met.
   • New to Qpoint's Status step offers "Set it up" only when a goal is unmet.
   
   Reason: a setup step that goes away once done would make the explainer longer and conditional for everyone else.
2. Where the button sits. Recommend the panel's action seat. It is the person's one click, as with "Start the simulation", and it hides once the goal is met. The callout says what the dot means, ending in the question ("Connect it now?"), and the panel's button answers "Yes, connect it now". The other way is a button inside the callout. That would mean making callouts clickable, and the overlay is built never to block the page.
3. Is "not connected" a problem? Recommend: only when the organisation expects a connection. That means config.yaml names a plane, or HQ deployed the app, but the machine isn't connected. Otherwise local is a choice, and the tour offers Connect as an option, not a warning. This needs Tyler's word on what the configuration carries.
4. Off: can the app start qcontrol? It's open whether there's a launchd verb the app may call. Until there is, the off state explains and links to Help; it has no Start button.

Wording per state (draft, brand voice checked)

The callout on status.state:

A second callout, on the plane line (a new region, status.plane):

Today's single line, "The dot turns green when the sensor is working.", stays until these rulings land.

Set up this machine: the tour (draft)

Each step has a goal. A step whose goal is met says so in one line and moves on.

1. Is it running? The goal is sensor.state=on. It covers the states above and, when off, what to do.
2. Connected to HQ. The goal is plane.state=connected, and the step appears only when ruling 3 says a connection is expected. Its button is "Yes, connect it now", which opens Connect. Waits for c131's Connect page.
3. Where its settings live. This is the Config page under This machine, built by c146: /pages/native/config in the lab, Route::Config in the app (qnative c11, on main as 313bd7c). The callout sits on config.source, which says which of the three modes holds config.yaml: Edit here, Managed by your company, or From a published file (c146 Q1). With no file, the page opens on Pick a starter (config.first-step). It has no button: editing, starters and an agent's draft are the page's own, and the person applies them (c146 R4). Updated 2026-11-13: this step pointed at the Sensor page's facts until c146 built Config, which took the page over from c138.
4. How it reaches you. Messages › Settings (messages.kinds), with "Allow notifications" as the button, from the page's own messaging::ask_alert_permission.
5. Your agent. Help's Ask the guide (help.guide), with the "Connect your agent" callout. The button copies the command.

Build, in phases, after the rulings

• Phase 1 (no Connect needed):
  • facts sensor.state and plane.state (from pages::status::SensorRead, on the background read refresh_facts already runs);
  • when conditions on callouts (fact=value, fact!=value);
  • a status.plane region;
  • the state-aware Status callouts in New to Qpoint;
  • one story per state (worlds: app-status-off, -starting, -degraded, -connected already exist).
• Phase 2:
  • the Set up this machine tour, steps 1 and 3–5;
  • a goal on each step that marks it done;
  • Action::Tour ("Set it up", which opens the setup tour at its first unmet step) and Action::AllowNotifications.
• Phase 3 (waits for c131's Connect page):
  • step 2 and Action::Connect, through to signing in, failed and connected;
  • the deep link;
  • the connect-request message where a plane requires approval.

Patterns worth considering

• Setup checklists, not tours. Some products show "3 of 5 done" with each step's own button, not a linear walk. The panel could show the goals as a checklist above the step.
• The guide as a second way in. "Set me up" over MCP starts the tour at the first unmet goal. The guide points at each button and never presses one, as with Simulation today.
• First run. On first launch with nothing set up, open the setup tour (c137 inventory row 23, welcome / first run), not New to Qpoint.

Open for Tyler

• What does config.yaml carry that says a plane is expected?
• Can the app start or restart qcontrol?
• Connect's credential exchange (c131 D13, c134 D8).