The first five minutes, as the product and not as a developer's first run

The first launch was a code box with a link under it, then an empty
Live screen with 'No cameras' in amber in a far corner, then a form
asking for an IP address, and for the first few minutes of all of it
the engine silently downloading 275 MB with nothing on screen but a
stopped-looking status. Walked in a browser with the new mock; nobody
who was not an installer would have got through it.

Now: a welcome that asks the one question a shop owner can answer -
managed from a head office, or on this PC only - with each path in a
sentence; a Getting Started checklist on Live that reads its three steps
from the engine and ticks them itself (recognition ready, camera added
and connected, camera proven by a walk-past), with the one button for
the next step, and that disappears the moment somebody is recognised;
and the model download reported as a percentage in the tray, the
sidebar and the checklist, parsed by the supervisor from the engine's
own progress lines.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KGcjxF1cNLcuwc3DAPcnfj

agent/pkg/engine/supervisor.go

@@ -21,6 +21,8 @@ import (
 	"net/http"
 	"os"
 	"os/exec"
+	"regexp"
+	"strconv"
 	"strings"
 	"sync"
 	"time"
@@ -77,6 +79,7 @@ type Supervisor struct {
 	restarts int
 	cancel   context.CancelFunc
 	done     chan struct{}
+	progress Progress
 }
 
 func New(opts Options) *Supervisor {
@@ -110,6 +113,37 @@ func (s *Supervisor) Start() {
 	go s.supervise(ctx, done)
 }
 
+// Progress is what the engine is busy with before it answers - on first run,
+// downloading ~275 MB of models. Empty once the engine is up.
+type Progress struct {
+	What    string `json:"what"`
+	Percent int    `json:"percent"`
+}
+
+var progressRe = regexp.MustCompile(`download: (.+?) (\d{1,3})%`)
+
+func (s *Supervisor) noteProgress(line string) {
+	m := progressRe.FindStringSubmatch(line)
+	if m == nil {
+		return
+	}
+	pct, _ := strconv.Atoi(m[2])
+	s.mu.Lock()
+	if pct >= 100 {
+		s.progress = Progress{}
+	} else {
+		s.progress = Progress{What: m[1], Percent: pct}
+	}
+	s.mu.Unlock()
+}
+
+// Progress reports the current first-run download, if any.
+func (s *Supervisor) Progress() Progress {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	return s.progress
+}
+
 // Stop asks the engine to exit and waits for it.
 func (s *Supervisor) Stop() {
 	s.mu.Lock()
@@ -233,6 +267,7 @@ func (s *Supervisor) runOnce(ctx context.Context) error {
 		for sc.Scan() {
 			line := sc.Text()
 			fmt.Fprintln(s.opts.LogWriter, line)
+			s.noteProgress(line)
 			tailMu.Lock()
 			tail = append(tail, line)
 			if len(tail) > 12 {
@@ -244,6 +279,9 @@ func (s *Supervisor) runOnce(ctx context.Context) error {
 
 	s.setState(Running, nil)
 	waitErr := cmd.Wait()
+	s.mu.Lock()
+	s.progress = Progress{}
+	s.mu.Unlock()
 	<-pumped
 
 	// A context cancel terminates the child through exec's own handling; the

behavision/model_assets.py

@@ -35,6 +35,31 @@ _COPY_MAP = {
 }
 
 
+def _fetch(url: str, dest: Path, label: str) -> None:
+    """Download with progress on stdout the supervisor can read.
+
+    On first run this is minutes of nothing: the API is not up yet, so the
+    app cannot ask the engine what it is doing, and a shop PC that shows a
+    stopped engine for five minutes after install looks broken. The
+    supervisor watches for `download: <label> <n>%` and puts the number in
+    the tray and the window. Logged every 5 points, not every chunk, so the
+    log file does not fill with a progress bar.
+    """
+    last = -5
+
+    def hook(blocks: int, block_size: int, total: int) -> None:
+        nonlocal last
+        if total <= 0:
+            return
+        pct = min(100, blocks * block_size * 100 // total)
+        if pct >= last + 5:
+            last = pct
+            log.info("download: %s %d%%", label, pct)
+
+    urllib.request.urlretrieve(url, dest, hook)
+    log.info("download: %s 100%%", label)
+
+
 def setup_models(models_dir: Path) -> "list[str]":
     """Ensure all model files exist in models_dir. Returns missing ones."""
     models_dir = Path(models_dir)
@@ -44,7 +69,7 @@ def setup_models(models_dir: Path) -> "list[str]":
     if not yunet.exists():
         log.info("downloading YuNet face detector (~230 KB)...")
         tmp = yunet.with_suffix(".part")
-        urllib.request.urlretrieve(YUNET_URL, tmp)
+        _fetch(YUNET_URL, tmp, "face detector")
         tmp.rename(yunet)
         log.info("YuNet saved to %s", yunet)
 
@@ -88,7 +113,7 @@ def setup_models(models_dir: Path) -> "list[str]":
             import zipfile
 
             tmp = models_dir / "buffalo_l.zip.part"
-            urllib.request.urlretrieve(BUFFALO_L_URL, tmp)
+            _fetch(BUFFALO_L_URL, tmp, "recognition models")
             with zipfile.ZipFile(tmp) as zf:
                 for name, target in wanted.items():
                     member = next((n for n in zf.namelist()

desktop/app.go

@@ -561,6 +561,8 @@ type EngineStatus struct {
 	Reachable bool            `json:"reachable"`
 	Model     string          `json:"recognition_model,omitempty"`
 	Cameras   map[string]bool `json:"cameras,omitempty"`
+	// Progress is the first-run model download, when one is happening.
+	Progress *agentengine.Progress `json:"progress,omitempty"`
 }
 
 func (a *App) EngineStatus() EngineStatus {
@@ -571,6 +573,9 @@ func (a *App) EngineStatus() EngineStatus {
 	st, err := a.sup.State()
 	out.State = string(st)
 	out.Restarts = a.sup.Restarts()
+	if p := a.sup.Progress(); p.What != "" {
+		out.Progress = &p
+	}
 	if err != nil {
 		out.Error = err.Error()
 	}

desktop/frontend/dist/index.html

@@ -4,8 +4,8 @@
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>Behavision</title>
-    <script type="module" crossorigin src="./assets/index-uOKaPIDr.js"></script>
-    <link rel="stylesheet" crossorigin href="./assets/index-CGAmTH1J.css">
+    <script type="module" crossorigin src="./assets/index-Be_Iv2Nz.js"></script>
+    <link rel="stylesheet" crossorigin href="./assets/index-lhDNZRcC.css">
   </head>
   <body>
     <div id="root"></div>

desktop/frontend/src/App.jsx

@@ -133,7 +133,7 @@ export default function App() {
         </div>
       </aside>
       <main className="main">
-        <Current session={session} />
+        <Current session={session} onNavigate={setView} />
         {/* Loya's door, top right of every screen. A buddy you have to find in
             a sidebar is not around; one in the corner is. */}
         {!helping && (
@@ -172,6 +172,7 @@ function EngineBox() {
   // what this panel showed while recognition was visibly running.
   if (!running && s.reachable) { tone = 'warn'; text = 'Running outside the app' }
   else if (s.state === 'failed' || s.state === 'backoff') { tone = 'bad'; text = 'Not running' }
+  else if (running && !s.reachable && s.progress) { tone = 'warn'; text = `Downloading ${s.progress.what}… ${s.progress.percent}%` }
   else if (running && !s.reachable) { tone = 'warn'; text = 'Starting…' }
   else if (running && cams.length === 0) { tone = 'warn'; text = 'No cameras' }
   else if (running && up === 0) { tone = 'bad'; text = 'No camera connected' }

desktop/frontend/src/styles.css

@@ -610,3 +610,27 @@ tr.click { cursor: pointer; } tr.click:hover td { background: var(--s2); }
 .foundlist .mono { font-family: var(--font-mono); font-size: 12.5px; min-width: 120px; }
 .foundlist .what { flex: 1; color: var(--ink-2); }
 .foundlist li.rescan button { width: auto; border: 0; background: none; padding: 4px 0; color: var(--ink-3); }
+
+/* Welcome: two paths, each a card. */
+.login .box.wide { max-width: 640px; }
+.choices { display: grid; grid-template-columns: 1fr 1fr; gap: var(--sp-3); margin-top: var(--sp-2); }
+@media (max-width: 720px) { .choices { grid-template-columns: 1fr; } }
+.choice { display: flex; flex-direction: column; align-items: flex-start; gap: 8px; text-align: left; padding: var(--sp-4);
+  border-radius: var(--r-lg); border: 1px solid var(--line); background: var(--s2); color: var(--ink); cursor: pointer; }
+.choice:hover { border-color: var(--accent); background: var(--accent-3); }
+.choice b { font-size: 14px; }
+.choice span { font-size: 12.5px; color: var(--ink-2); line-height: 1.5; }
+.choice em { font-family: var(--font-mono); font-style: normal; font-size: 11.5px; }
+.choice svg { color: var(--accent); }
+.login .foot em { font-style: normal; color: var(--ink-2); }
+.linkbtn { display: inline-flex; align-items: center; gap: 6px; }
+
+/* Getting started */
+.starter { margin-bottom: var(--sp-4); }
+.starter .panelhead { padding: var(--sp-3) var(--sp-4); }
+.starter .steps { margin: 0; padding: var(--sp-3) var(--sp-4) 0; }
+.starter .steps.compact li { padding: var(--sp-3) var(--sp-4) var(--sp-3) 52px; }
+.starter .steps li .btn { margin-top: var(--sp-2); }
+.starter .note { padding: var(--sp-3) var(--sp-4); font-size: 12px; }
+.btn.ghost { background: none; border-color: transparent; color: var(--ink-3); }
+.btn.ghost:hover { color: var(--ink); }

desktop/frontend/src/views/Live.jsx

@@ -16,7 +16,7 @@ import * as Icon from '../ui/icons.jsx'
 // No camera picture here - the person at the counter is not watching CCTV,
 // and a live video tile costs CPU the recognition pipeline needs. The picture
 // lives on the Cameras screen, where it is a setup tool.
-export default function Live() {
+export default function Live({ onNavigate }) {
   const { data, error } = usePolled(() => api.live(), 3000)
   const { data: pipe } = usePolled(() => api.pipelineStatus(), 5000)
 
@@ -47,6 +47,8 @@ export default function Live() {
 
       <PipelineStrip pipe={pipe} cameras={cameras} up={up} />
 
+      <GettingStarted cameras={cameras} arrivals={arrivals} onNavigate={onNavigate} />
+
       <div className="panel arrivals-panel">
         <div className="panelhead">
           <h3>Who just walked in</h3>
@@ -82,6 +84,65 @@ export default function Live() {
   )
 }
 
+// The first five minutes, as a checklist that ticks itself.
+//
+// Before this the Live screen after install was "Nobody yet" over a row of
+// dashes, with an amber "No cameras" in the far corner. Nothing said what to
+// do next. This says the three things, in order, and each step reads its own
+// state from the engine: recognition ready, a camera added, the camera
+// proven by a walk-past. It disappears on its own once someone has actually
+// been recognised, because at that point the product has explained itself.
+function GettingStarted({ cameras, arrivals, onNavigate }) {
+  const { data: eng } = usePolled(() => api.engineStatus(), 4000)
+  const [hidden, setHidden] = useState(() => { try { return localStorage.getItem('bv.gettingStarted') === 'done' } catch { return false } })
+  const hasCamera = cameras.length > 0
+  const anyUp = cameras.some(c => c.connected)
+  const { data: checks } = usePolled(async () => {
+    const out = {}
+    for (const c of cameras) { try { out[c.camera_id] = await api.placementResult(c.camera_id) } catch { /* not yet */ } }
+    return out
+  }, 10000, [cameras.map(c => c.camera_id).join('|')])
+  const proven = Object.values(checks ?? {}).some(r => r && !r.running && r.verdict === 'good')
+  const recognised = arrivals.length > 0
+
+  if (hidden || recognised) return null
+  const engineReady = Boolean(eng?.reachable && eng?.recognition_model)
+  const progress = eng?.progress
+
+  const steps = [
+    { done: engineReady, now: !engineReady,
+      title: engineReady ? `Recognition ready (${eng.recognition_model})` : progress ? `Downloading ${progress.what}… ${progress.percent}%` : 'Starting recognition…',
+      text: engineReady ? null : 'First start downloads about 275 MB of recognition models. A few minutes on a normal connection; nothing to do meanwhile.' },
+    { done: hasCamera && anyUp, now: engineReady && !(hasCamera && anyUp),
+      title: hasCamera ? (anyUp ? 'Camera connected' : 'Camera added — not connecting yet') : 'Add your camera',
+      text: hasCamera ? (anyUp ? null : 'Check its password and stream path under Cameras → Edit.') : 'Behavision can find it on the network; you type only its password.',
+      action: hasCamera ? null : { label: 'Add camera', go: 'cameras' } },
+    { done: proven, now: hasCamera && anyUp && !proven,
+      title: proven ? 'Camera proven — it can recognise faces' : 'Walk past the camera',
+      text: proven ? null : 'Run Check placement and walk past like a customer for 25 seconds. Only a “good” verdict means it will recognise people.',
+      action: hasCamera && anyUp && !proven ? { label: 'Check placement', go: 'cameras' } : null },
+  ]
+
+  return (
+    <section className="panel starter">
+      <div className="panelhead">
+        <h3>Getting started</h3>
+        <button className="btn sm ghost" onClick={() => { try { localStorage.setItem('bv.gettingStarted', 'done') } catch {} ; setHidden(true) }}>Hide</button>
+      </div>
+      <ol className="steps compact">
+        {steps.map((st, i) => (
+          <li key={i} className={st.done ? 'done' : st.now ? 'now' : ''}>
+            <b>{st.title}</b>
+            {st.text && <span>{st.text}</span>}
+            {st.action && <button className="btn sm primary" onClick={() => onNavigate?.(st.action.go)}>{st.action.label}</button>}
+          </li>
+        ))}
+      </ol>
+      <p className="note">The moment a customer is recognised, this list goes away.</p>
+    </section>
+  )
+}
+
 // One customer, big enough to match against the person in front of you.
 function Arrival({ e, fresh }) {
   const isNew = e.type === 'person.new'

desktop/frontend/src/views/Setup.jsx

@@ -15,7 +15,6 @@ export default function Setup({ onDone, onCancel }) {
   const [code, setCode] = useState('')
   const [busy, setBusy] = useState(null)
   const [error, setError] = useState(null)
-  const [alone, setAlone] = useState(false)
 
   async function submit(e) {
     e.preventDefault()
@@ -40,13 +39,66 @@ export default function Setup({ onDone, onCancel }) {
     }
   }
 
+  // First launch: a choice, not a code box. Two thirds of the people who
+  // open this have no idea what an installation code is; the other third has
+  // one in their hand. Both must see their own path in the first second.
+  const [path, setPath] = useState(onCancel ? 'code' : null)
+
+  if (path === null) {
+    return (
+      <div className="login">
+        <div className="box wide">
+          <span className="mark"><img src={logo} alt="" /></span>
+          <h1>Welcome to Behavision</h1>
+          <p className="lead">
+            This PC will watch your shop’s cameras and recognise returning customers.
+            First, one question: is this shop managed from a head office?
+          </p>
+          <div className="choices">
+            <button type="button" className="choice" onClick={() => setPath('code')}>
+              <Icon.Cloud size={22} />
+              <b>Yes — I have an installation code</b>
+              <span>Head office gave you a code like <em>ABCDEF-123456-…</em>. This PC joins that shop and gets its cameras from there.</span>
+            </button>
+            <button type="button" className="choice" onClick={() => setPath('alone')}>
+              <Icon.Shield size={22} />
+              <b>No — set up on this PC only</b>
+              <span>Cameras, customers and recognition stay on this PC. Nothing is sent anywhere. You can link to a head office later.</span>
+            </button>
+          </div>
+        </div>
+      </div>
+    )
+  }
+
+  if (path === 'alone') {
+    return (
+      <div className="login">
+        <div className="box">
+          <span className="mark"><img src={logo} alt="" /></span>
+          <h1>On this PC only</h1>
+          <p className="lead">
+            Behavision will run entirely here. Next you’ll add your camera — it can find it on the network for you — and walk past it once so it can prove it works.
+          </p>
+          {error && <div className="err"><Icon.Warning size={15} />{error}</div>}
+          <button type="button" className="btn primary" disabled={!!busy} onClick={standalone}>
+            {busy === 'alone' ? 'Setting up…' : 'Continue'}
+          </button>
+          <div className="alt">
+            <button type="button" className="linkbtn" onClick={() => setPath(null)}><Icon.Back size={14} /> Back</button>
+          </div>
+        </div>
+      </div>
+    )
+  }
+
   return (
     <div className="login">
       <div className="box">
         <span className="mark"><img src={logo} alt="" /></span>
-        <h1>{onCancel ? 'Link to head office' : 'Set up this PC'}</h1>
+        <h1>{onCancel ? 'Link to head office' : 'Join your shop'}</h1>
         <p className="lead">
-          Type the installation code for this shop. You only do this once.
+          Type the installation code head office gave you. It works once, and this PC becomes that shop.
         </p>
         <form onSubmit={submit}>
           {error && <div className="err"><Icon.Warning size={15} />{error}</div>}
@@ -67,38 +119,12 @@ export default function Setup({ onDone, onCancel }) {
           </button>
         </form>
         <p className="foot">
-          The code works once. Ask whoever manages your shops for it — they can
-          create one from the Behavision platform, under the shop.
+          Don’t have one? Whoever runs head office creates it under the shop: <em>Shops → the shop → Set up a shop PC</em>.
         </p>
-
-        {/* The second way out of this screen, and the reason it exists.
-            Recognition, the cameras and this shop's own gallery all run on
-            this PC and need no server, so a shop with one till and no head
-            office was being blocked from adding a camera until somebody
-            issued it a code — the software refusing to do the thing it is
-            for. Linking later is still one click away, and it keeps the
-            visits already recorded here. */}
         <div className="alt">
           {onCancel
-            ? <button type="button" className="linkbtn" onClick={onCancel}>
-                Not now — go back
-              </button>
-            : !alone
-            ? <button type="button" className="linkbtn" onClick={() => setAlone(true)}>
-                No head office — set this PC up on its own
-              </button>
-            : <>
-                <p className="note">
-                  This PC will watch its cameras and recognise returning
-                  customers on its own. Nothing is sent anywhere. You can link
-                  it to head office later without losing anything recorded
-                  here.
-                </p>
-                <button type="button" className="btn" disabled={!!busy}
-                        onClick={standalone}>
-                  {busy === 'alone' ? 'Setting up…' : 'Use this PC on its own'}
-                </button>
-              </>}
+            ? <button type="button" className="linkbtn" onClick={onCancel}>Not now — go back</button>
+            : <button type="button" className="linkbtn" onClick={() => setPath(null)}><Icon.Back size={14} /> Back</button>}
         </div>
       </div>
     </div>

desktop/tray.go

@@ -173,6 +173,8 @@ func describe(s EngineStatus) (state, label string) {
 		return "error", "Not running — " + firstLine(s.Error)
 	case s.State == "backoff":
 		return "error", fmt.Sprintf("Restarting (%d attempts)", s.Restarts)
+	case !s.Reachable && s.Progress != nil:
+		return "warn", fmt.Sprintf("Downloading %s… %d%%", s.Progress.What, s.Progress.Percent)
 	case !s.Reachable:
 		return "warn", "Starting…"
 	case len(s.Cameras) == 0: