release.sh can build the macOS package too

Cheap for a reason worth stating: the Windows package is already a SOURCE
install - a pure-Python wheel plus a setup tool that builds a venv on the
target machine, because PyInstaller cannot cross-compile. macOS needs
nothing different. Same wheel, same setup tool, a natively built .app in
place of the .exe. No frozen engine, no 200 MB, no second packaging story.

behavision-setup already handled both platforms (Scripts vs bin, the
tasklist check guarded) and cross-compiled for darwin without a change.
The one thing that did not was its advice when Python is missing: it told
everyone to tick 'Add python.exe to PATH' on a Windows installer page.
Software that does not know which machine it is running on is software
somebody stops trusting for the rest of the session.

MAC=1 opts in, so the ordinary Windows release is unchanged.

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

.gitignore

@@ -52,3 +52,18 @@ node_modules/
 # in the tree `go build ./...` fails on a fresh checkout - on a machine that may
 # have no npm at all. They are ~200 KB and regenerating them is one command; a
 # repository that does not compile is the more expensive problem.
+
+# Backups of .env made when editing camera credentials.
+/.env.bak-*
+
+# Generated by the wails CLI on every dev run and build, not source.
+# NOT /desktop/build/ as a whole: appicon.png, darwin/ and windows/ under it
+# are the Wails project scaffolding (icon, Info.plist, manifest) that a
+# reproducible Windows build needs. Only the compiled output is ignored.
+/desktop/frontend/wailsjs/
+/desktop/frontend/package.json.md5
+
+# Left behind by `pip install .` of the engine (setuptools metadata), not source.
+/behavision.egg-info/
+/.prod/
+/.demo/

RUN.md

@@ -251,7 +251,7 @@ the frozen engine once to prove it runs, and compiles the installer.
 3. Launch from the Start menu. **Set this PC up on its own** — no code needed.
 4. Cameras → Add camera → pick the make → Test connection → Save. The feed must
    appear with no restart.
-5. Check `/api/health` reports `recognition_model`. On a 16 GB machine the
+5. Check `/api/health` reports `recognition_model`. On a small machine the
    166 MB r50 can lose the fallback chain to the 13 MB mbf, and embeddings are
    model-tagged, so which one wins decides whether a gallery carries over.
 6. Sign out of the tray (Quit) — recognition must stop with it. Reboot; the app

agent/cmd/behavision-demo-pack/main.go

@@ -0,0 +1,93 @@
+// Command behavision-demo-pack seals a camera list into demo-cameras.enc for a
+// demo release. It runs on the machine that builds the release and is never
+// shipped.
+//
+//	behavision-demo-pack -cameras cameras.json -out demo-cameras.enc
+//
+// Prints the unlock code exactly once. It is not stored anywhere; a code you
+// can look up later is a code anyone with access to the build machine holds.
+// Lose it and seal again.
+package main
+
+import (
+	"encoding/json"
+	"flag"
+	"fmt"
+	"os"
+
+	"github.com/loyaly/behavision-agent/pkg/demo"
+)
+
+func main() {
+	in := flag.String("cameras", "", "JSON array of cameras (id, host, port, path, username, password) - the PC then runs on its own")
+	enrolCode := flag.String("enrol-code", "", "an installation code from head office - the PC then claims that shop and gets its cameras from there")
+	cloud := flag.String("cloud", "https://mcp.loyaly.ai", "head office, with -enrol-code")
+	out := flag.String("out", "demo-cameras.enc", "sealed bundle to write")
+	flag.Parse()
+	if *in == "" && *enrolCode == "" {
+		fmt.Fprintln(os.Stderr, "usage: behavision-demo-pack (-cameras cameras.json | -enrol-code CODE [-cloud URL]) [-out demo-cameras.enc]")
+		os.Exit(2)
+	}
+
+	var payload demo.Payload
+	if *in != "" {
+		raw, err := os.ReadFile(*in)
+		if err != nil {
+			die("read cameras: %v", err)
+		}
+		if err := json.Unmarshal(raw, &payload.Cameras); err != nil {
+			die("cameras.json: %v", err)
+		}
+		if len(payload.Cameras) == 0 {
+			die("no cameras in %s", *in)
+		}
+	}
+	payload.EnrolCode = *enrolCode
+	if *enrolCode != "" {
+		payload.CloudBase = *cloud
+	}
+	cams := payload.Cameras
+	for i, c := range cams {
+		switch {
+		case c.ID == "":
+			die("camera %d has no id", i)
+		case c.Host == "":
+			die("camera %q has no host", c.ID)
+		case c.Path == "":
+			die("camera %q has no path - the stream path is the field nobody can guess", c.ID)
+		}
+	}
+	// Re-marshal so only the fields the engine accepts travel, in a stable
+	// shape, whatever extra keys the input happened to carry.
+	plain, err := json.Marshal(payload)
+	if err != nil {
+		die("marshal: %v", err)
+	}
+
+	code, err := demo.NewCode()
+	if err != nil {
+		die("code: %v", err)
+	}
+	sealed, err := demo.Seal(code, plain)
+	if err != nil {
+		die("seal: %v", err)
+	}
+	if err := os.WriteFile(*out, sealed, 0o644); err != nil {
+		die("write: %v", err)
+	}
+
+	if payload.EnrolCode != "" {
+		fmt.Printf("\n  sealed an installation code for %s into %s (%d bytes)\n\n", payload.CloudBase, *out, len(sealed))
+	} else {
+		fmt.Printf("\n  sealed %d camera(s) into %s (%d bytes)\n\n", len(cams), *out, len(sealed))
+	}
+	fmt.Printf("  unlock code:  %s\n\n", code)
+	fmt.Println("  Shown once. Give it to whoever runs behavision-setup, by voice")
+	fmt.Println("  or message - not in the same place as the zip.")
+	fmt.Println()
+}
+
+func die(format string, args ...any) {
+	fmt.Fprintf(os.Stderr, "  "+format+"\n", args...)
+	os.Exit(1)
+}

agent/cmd/behavision-setup/main.go

@@ -0,0 +1,645 @@
+// Command behavision-setup prepares a shop PC to run the recognition engine.
+//
+// It exists because the engine is Python and the rest of the product is Go.
+// The Go halves cross-compile to Windows from any machine; the engine, frozen
+// with PyInstaller, does not - PyInstaller bundles the interpreter and native
+// wheels of the machine it runs on, so a frozen engine can only be built on
+// Windows. That single fact was the whole reason a release could not be cut.
+//
+// So this installs the engine from source instead of shipping it frozen: find
+// a Python, build a private virtual environment beside the database, install
+// the engine into it, fetch the models, and record how to start it. Everything
+// in the release can then be built anywhere.
+//
+// The trade, stated plainly because whoever runs this is standing in a shop:
+// it needs Python and a working internet connection at install time, and it
+// takes minutes rather than seconds. A frozen build needs neither. What it
+// buys is a release that exists.
+package main
+
+import (
+	"bufio"
+	"context"
+	"errors"
+	"fmt"
+	"io"
+	"net/http"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"runtime"
+	"strconv"
+	"strings"
+	"time"
+
+	"bytes"
+	"encoding/json"
+
+	"github.com/loyaly/behavision-agent/pkg/config"
+	"github.com/loyaly/behavision-agent/pkg/demo"
+	"github.com/loyaly/behavision-agent/pkg/engine"
+	"github.com/loyaly/behavision-agent/pkg/enrol"
+	"github.com/loyaly/behavision-agent/pkg/paths"
+)
+
+// The engine needs 3.10; nothing here works below it and the failure would
+// otherwise arrive as a syntax error deep inside a dependency.
+const minMinor = 10
+
+func main() {
+	if err := run(); err != nil {
+		fmt.Fprintf(os.Stderr, "\n  Setup did not finish: %v\n\n", err)
+		pause()
+		os.Exit(1)
+	}
+	pause()
+}
+
+func run() error {
+	fmt.Println()
+	fmt.Println("  Behavision setup")
+	fmt.Println("  ----------------")
+	fmt.Println()
+
+	state := paths.StateRoot()
+	src, err := engineSource()
+	if err != nil {
+		return err
+	}
+	fmt.Printf("  engine source   %s\n", src)
+	fmt.Printf("  install into    %s\n", state)
+	fmt.Println()
+
+	if err := paths.EnsureState(); err != nil {
+		return fmt.Errorf("could not create %s: %w", state, err)
+	}
+
+	// A demo release ships its cameras sealed. Ask for the code NOW, before
+	// the ten-minute download, so a mistyped one costs seconds; the cameras
+	// are actually added at the end, through the running engine.
+	bundle, err := unlockDemo(src)
+	if err != nil {
+		return err
+	}
+	var demoCams []demo.Camera
+	if bundle != nil {
+		demoCams = bundle.Cameras
+		switch {
+		case bundle.EnrolCode != "":
+			step("Demo", "unlocked - this PC will join a shop at head office")
+		default:
+			step("Demo cameras", fmt.Sprintf("%d unlocked", len(demoCams)))
+		}
+	}
+
+	if running := behavisionRunning(); running != "" {
+		return fmt.Errorf("%s is running. Quit Behavision from the tray icon first, then run setup again.\n\n"+
+			"Setting up underneath a running copy starts a second engine on the same port and, in a demo,\n"+
+			"re-claims the shop while the open app still holds the old credentials.", running)
+	}
+
+	py, ver, err := findPython()
+	if err != nil {
+		return err
+	}
+	step("Python", fmt.Sprintf("%s  (%s)", ver, py))
+
+	venv := filepath.Join(state, "runtime")
+	if err := makeVenv(py, venv); err != nil {
+		return err
+	}
+	vpy := venvPython(venv)
+	step("Virtual environment", venv)
+
+	// The engine reads its settings from <state>/config/default.yaml and will
+	// seed that from beside its own code on first run - which works when its
+	// code is a checkout or a frozen folder and not when it is a package in
+	// site-packages, where there is no config beside it. Seeded here, from the
+	// copy the release ships. Never overwritten: an upgrade must not revert an
+	// operator's thresholds.
+	if err := seedConfig(src, state); err != nil {
+		return err
+	}
+	step("Settings", filepath.Join(state, "config", "default.yaml"))
+
+	// --upgrade so re-running after a new release replaces the engine rather
+	// than leaving the old one in place and reporting success.
+	if err := pipInstall(vpy, src); err != nil {
+		return err
+	}
+	step("Engine and dependencies", "installed")
+
+	if err := runEngine(vpy, "setup-models"); err != nil {
+		return fmt.Errorf("downloading the recognition models: %w", err)
+	}
+	step("Recognition models", "downloaded")
+
+	if err := writeConfig(vpy); err != nil {
+		return err
+	}
+	step("Startup settings", filepath.Join(state, "agent.json"))
+
+	// Proving it starts is the point. An installer that reports success and
+	// leaves a shop with an engine that will not run has done worse than
+	// failing: the failure surfaces later, to someone who did not install it.
+	// Joining a shop: head office supplies the cameras, so any left on this PC
+	// from an earlier install go first. Otherwise the reconciler offers them UP
+	// to head office - without their passwords, which the engine never returns
+	// - and the shop ends up with the same lens listed twice, one copy of which
+	// can never be pushed to another PC. Measured on the first claimed demo.
+	if bundle != nil && bundle.EnrolCode != "" {
+		if err := os.Remove(paths.CamerasFile()); err == nil {
+			step("Earlier cameras", "removed - head office supplies them now")
+		}
+	}
+	if err := smokeTest(vpy, demoCams); err != nil {
+		return fmt.Errorf("the engine installed but would not start: %w", err)
+	}
+	step("Engine starts and answers", "verified")
+	if len(demoCams) > 0 {
+		step("Demo cameras", "added to the engine")
+	}
+	switch {
+	case bundle != nil && bundle.EnrolCode != "":
+		// The demo that IS the product: this PC claims a real shop, exactly
+		// as a customer install does, and its cameras arrive from head office
+		// on the first sync. The app then opens on Login.
+		siteName, err := claimShop(bundle.EnrolCode, bundle.CloudBase)
+		if err != nil {
+			return fmt.Errorf("could not join the shop at head office: %w", err)
+		}
+		step("Head office", "linked to "+siteName)
+	case bundle != nil:
+		// No head office in this demo. Without this the app opens on "type an
+		// installation code" and sits there; with it, it opens on Live.
+		if err := markStandalone(); err != nil {
+			return err
+		}
+		step("Head office", "none - running on this PC only")
+	}
+
+	fmt.Println()
+	fmt.Println("  Done. Start Behavision from the Start menu or the desktop icon.")
+	fmt.Println("  It appears in the system tray; right-click there to stop it.")
+	fmt.Println()
+	return nil
+}
+
+func step(label, detail string) {
+	fmt.Printf("  [ok] %-24s %s\n", label, detail)
+}
+
+// engineSource finds the Python source shipped beside this executable. Beside,
+// not downloaded: the engine and the app must be the same release, and a
+// version skew between them is the class of bug nobody can reproduce.
+func engineSource() (string, error) {
+	candidates := []string{
+		filepath.Join(paths.InstallRoot(), "engine-src"),
+		filepath.Join(paths.InstallRoot(), "..", "engine-src"),
+	}
+	if wd, err := os.Getwd(); err == nil {
+		candidates = append(candidates, filepath.Join(wd, "engine-src"), wd)
+	}
+	for _, c := range candidates {
+		if _, err := os.Stat(filepath.Join(c, "pyproject.toml")); err == nil {
+			abs, _ := filepath.Abs(c)
+			return abs, nil
+		}
+	}
+	return "", errors.New("could not find the engine source (expected an " +
+		"engine-src folder with pyproject.toml beside this program). " +
+		"Unzip the whole release together rather than moving this file out of it")
+}
+
+// findPython returns the first interpreter that is new enough.
+//
+// `py -3` first on Windows: the launcher is what the official installer puts
+// on PATH, and `python` there is often the Microsoft Store stub that prints an
+// advert and exits 9009 instead of running anything.
+// behavisionRunning names a Behavision process if one is up. Windows only -
+// that is the platform setup ships on - and by image name via tasklist, which
+// needs no extra privilege.
+func behavisionRunning() string {
+	if runtime.GOOS != "windows" {
+		return ""
+	}
+	for _, name := range []string{"Behavision.exe", "behavision-agent.exe"} {
+		out, err := exec.Command("tasklist", "/FI", "IMAGENAME eq "+name, "/NH").Output()
+		if err == nil && strings.Contains(strings.ToLower(string(out)), strings.ToLower(name)) {
+			return name
+		}
+	}
+	return ""
+}
+
+func findPython() (string, string, error) {
+	type cand struct {
+		exe  string
+		args []string
+	}
+	var cands []cand
+	if runtime.GOOS == "windows" {
+		cands = append(cands, cand{"py", []string{"-3"}})
+	}
+	cands = append(cands, cand{"python3", nil}, cand{"python", nil})
+
+	var tried []string
+	for _, c := range cands {
+		exe, err := exec.LookPath(c.exe)
+		if err != nil {
+			continue
+		}
+		args := append(append([]string{}, c.args...), "-c",
+			"import sys;print('%d.%d'%sys.version_info[:2])")
+		out, err := exec.Command(exe, args...).Output()
+		if err != nil {
+			continue
+		}
+		ver := strings.TrimSpace(string(out))
+		tried = append(tried, c.exe+" "+ver)
+		if major, minor, ok := parseVer(ver); ok && (major > 3 || (major == 3 && minor >= minMinor)) {
+			full := exe
+			if len(c.args) > 0 {
+				full = exe + " " + strings.Join(c.args, " ")
+			}
+			return full, "Python " + ver, nil
+		}
+	}
+
+	// The advice has to match the machine. Telling a Mac user to tick "Add
+	// python.exe to PATH" on a Windows installer page reads as software that
+	// does not know where it is running, which is exactly the moment somebody
+	// stops trusting the rest of what it says.
+	msg := "no Python 3.10 or newer was found on this computer.\n\n"
+	if runtime.GOOS == "windows" {
+		msg += "    Install it from https://www.python.org/downloads/windows/\n" +
+			"    and tick \"Add python.exe to PATH\" on the first screen,\n" +
+			"    then run this again."
+	} else {
+		msg += "    Install it with `brew install python@3.12`, or from\n" +
+			"    https://www.python.org/downloads/macos/, then run this again."
+	}
+	if len(tried) > 0 {
+		msg += "\n\n    Found, but too old: " + strings.Join(tried, ", ")
+	}
+	return "", "", errors.New(msg)
+}
+
+func parseVer(s string) (int, int, bool) {
+	parts := strings.Split(s, ".")
+	if len(parts) < 2 {
+		return 0, 0, false
+	}
+	major, err1 := strconv.Atoi(parts[0])
+	minor, err2 := strconv.Atoi(parts[1])
+	return major, minor, err1 == nil && err2 == nil
+}
+
+// splitLauncher turns `py -3` back into a command and its arguments.
+func splitLauncher(s string) (string, []string) {
+	f := strings.Fields(s)
+	if len(f) == 0 {
+		return s, nil
+	}
+	return f[0], f[1:]
+}
+
+func venvPython(venv string) string {
+	if runtime.GOOS == "windows" {
+		return filepath.Join(venv, "Scripts", "python.exe")
+	}
+	return filepath.Join(venv, "bin", "python")
+}
+
+// makeVenv builds the engine's own interpreter under the writable state root.
+//
+// A virtual environment rather than the system Python: a shop PC may have
+// Python there for something else, and pinning numpy below 2.0 - which the
+// engine requires - inside a shared interpreter is how you break the other
+// thing months later, silently.
+func makeVenv(py, venv string) error {
+	if _, err := os.Stat(venvPython(venv)); err == nil {
+		return nil // already built; pip below brings it up to date
+	}
+	exe, args := splitLauncher(py)
+	args = append(args, "-m", "venv", venv)
+	return stream(exec.Command(exe, args...), "creating the virtual environment")
+}
+
+func pipInstall(vpy, src string) error {
+	fmt.Println("  Installing the engine and its libraries. This downloads a few")
+	fmt.Println("  hundred megabytes and takes a while on a slow connection.")
+	fmt.Println()
+	if err := stream(exec.Command(vpy, "-m", "pip", "install", "--upgrade",
+		"pip", "setuptools", "wheel"), "updating pip"); err != nil {
+		return err
+	}
+
+	// A wheel if the release ships one - nothing to build on the shop PC, and
+	// pip never has to touch the folder the release was unzipped into.
+	//
+	// That matters more than it sounds: `pip install <folder>` makes setuptools
+	// write behavision.egg-info INTO that folder, and the folder is read-only
+	// whenever the release was unzipped somewhere sensible - Program Files, or
+	// the shared drive INSTALL.txt says is fine. Found by running this in a
+	// container with the source mounted read-only: "could not create
+	// 'behavision.egg-info': Read-only file system". Falling back to source
+	// copies it somewhere writable first, for the same reason.
+	if wheels, _ := filepath.Glob(filepath.Join(src, "behavision-*.whl")); len(wheels) > 0 {
+		return stream(exec.Command(vpy, "-m", "pip", "install", "--upgrade", wheels[0]),
+			"installing the engine")
+	}
+	tmp, err := os.MkdirTemp("", "behavision-src-")
+	if err != nil {
+		return err
+	}
+	defer os.RemoveAll(tmp)
+	if err := copyTree(src, tmp); err != nil {
+		return fmt.Errorf("staging the engine source: %w", err)
+	}
+	return stream(exec.Command(vpy, "-m", "pip", "install", "--upgrade", tmp),
+		"installing the engine")
+}
+
+// seedConfig puts the shipped default.yaml where the engine will look for it,
+// and leaves an existing one alone.
+func seedConfig(src, state string) error {
+	dst := filepath.Join(state, "config", "default.yaml")
+	if _, err := os.Stat(dst); err == nil {
+		return nil
+	}
+	from := filepath.Join(src, "config", "default.yaml")
+	b, err := os.ReadFile(from)
+	if err != nil {
+		return fmt.Errorf("the release is missing config/default.yaml: %w", err)
+	}
+	if err := os.MkdirAll(filepath.Dir(dst), 0o755); err != nil {
+		return err
+	}
+	return os.WriteFile(dst, b, 0o644)
+}
+
+// copyTree copies a source tree, skipping the caches a checkout accumulates.
+func copyTree(from, to string) error {
+	return filepath.WalkDir(from, func(path string, d os.DirEntry, err error) error {
+		if err != nil {
+			return err
+		}
+		rel, _ := filepath.Rel(from, path)
+		if d.IsDir() {
+			if d.Name() == "__pycache__" || strings.HasSuffix(d.Name(), ".egg-info") {
+				return filepath.SkipDir
+			}
+			return os.MkdirAll(filepath.Join(to, rel), 0o755)
+		}
+		b, err := os.ReadFile(path)
+		if err != nil {
+			return err
+		}
+		return os.WriteFile(filepath.Join(to, rel), b, 0o644)
+	})
+}
+
+// runEngine runs the engine exactly as the app will later: same interpreter,
+// same environment. In particular ChildEnv sets BEHAVISION_DATA_DIR, without
+// which a pip-installed engine decides its state lives in site-packages and
+// downloads the models to a place the app never looks.
+func runEngine(vpy string, args ...string) error {
+	full := append([]string{"-m", "behavision"}, args...)
+	cmd := exec.Command(vpy, full...)
+	cmd.Env = engine.ChildEnv("")
+	return stream(cmd, "running the engine")
+}
+
+// writeConfig records how to start the engine, in the same file and through
+// the same type the app reads, so the two cannot disagree about it.
+func writeConfig(vpy string) error {
+	path := paths.AgentConfig()
+	cfg, err := config.Load(path)
+	if err != nil {
+		return fmt.Errorf("reading %s: %w", path, err)
+	}
+	// An absolute path: the app resolves a relative EngineExe against its own
+	// install root under Program Files, and the interpreter is not there.
+	cfg.EngineExe = vpy
+	cfg.EngineArgs = []string{"-m", "behavision", "run"}
+	if cfg.APIBase == "" {
+		cfg.APIBase = "http://127.0.0.1:8010"
+	}
+	return cfg.Save(path)
+}
+
+// smokeTest starts the engine exactly as the app will and waits for its API to
+// answer. Any reply counts, including 401: the engine invents its own
+// credential when none is configured, and a refusal proves it is serving.
+func smokeTest(vpy string, demoCams []demo.Camera) error {
+	ctx, cancel := context.WithTimeout(context.Background(), 120*time.Second)
+	defer cancel()
+
+	cmd := exec.CommandContext(ctx, vpy, "-m", "behavision", "run")
+	cmd.Env = engine.ChildEnv("")
+	var log strings.Builder
+	cmd.Stdout, cmd.Stderr = &log, &log
+	if err := cmd.Start(); err != nil {
+		return err
+	}
+	defer func() {
+		_ = cmd.Process.Kill()
+		_, _ = cmd.Process.Wait()
+	}()
+
+	client := &http.Client{Timeout: 3 * time.Second}
+	deadline := time.Now().Add(75 * time.Second)
+	for time.Now().Before(deadline) {
+		resp, err := client.Get("http://127.0.0.1:8010/api/health")
+		if err == nil {
+			_, _ = io.Copy(io.Discard, resp.Body)
+			resp.Body.Close()
+			if demoCams == nil {
+				return nil
+			}
+			// Through the engine's own Add Camera, not written to its file:
+			// the store is what applies DPAPI to the password on Windows, so
+			// this is how the credential ends up encrypted on disk rather
+			// than sitting in cameras.json for anyone who can read
+			// ProgramData.
+			return addCameras(demoCams)
+		}
+		if cmd.ProcessState != nil && cmd.ProcessState.Exited() {
+			break
+		}
+		time.Sleep(2 * time.Second)
+	}
+	return fmt.Errorf("it did not answer within 75 seconds.\n\n%s",
+		tail(log.String(), 15))
+}
+
+func tail(s string, n int) string {
+	lines := strings.Split(strings.TrimRight(s, "\n"), "\n")
+	if len(lines) > n {
+		lines = lines[len(lines)-n:]
+	}
+	return "    " + strings.Join(lines, "\n    ")
+}
+
+// stream runs a command and shows its output. Shown, not swallowed: pip failing
+// on a missing build tool prints exactly what is wrong, and hiding that leaves
+// the operator with "setup failed" and nothing to act on.
+func stream(cmd *exec.Cmd, what string) error {
+	cmd.Stdout, cmd.Stderr = os.Stdout, os.Stderr
+	if err := cmd.Run(); err != nil {
+		return fmt.Errorf("%s failed: %w", what, err)
+	}
+	return nil
+}
+
+// pause keeps the window open. Double-clicked from Explorer, a console program
+// that finishes closes instantly and the operator sees nothing at all -
+// success and failure look identical.
+func pause() {
+	if runtime.GOOS != "windows" {
+		return
+	}
+	fmt.Print("  Press Enter to close. ")
+	_, _ = bufio.NewReader(os.Stdin).ReadString('\n')
+}
+
+// unlockDemo returns the sealed cameras a demo release ships, or nil when this
+// is not a demo release. Asks for the unlock code on the console; three tries,
+// because a code is read down a phone and typed by hand.
+func unlockDemo(src string) (*demo.Payload, error) {
+	sealed, err := os.ReadFile(filepath.Join(src, "demo-cameras.enc"))
+	if err != nil {
+		return nil, nil // not a demo release
+	}
+	fmt.Println()
+	fmt.Println("  This is a demo release with the cameras already set up.")
+	fmt.Println("  It needs the unlock code you were given.")
+	fmt.Println()
+	in := bufio.NewReader(os.Stdin)
+	for attempt := 1; attempt <= 3; attempt++ {
+		fmt.Print("  Unlock code: ")
+		line, _ := in.ReadString('\n')
+		plain, err := demo.Open(line, sealed)
+		if err == nil {
+			payload, err := demo.Decode(plain)
+			if err != nil {
+				return nil, fmt.Errorf("the bundle unlocked but did not parse: %w", err)
+			}
+			fmt.Println()
+			return &payload, nil
+		}
+		fmt.Printf("  %v\n", err)
+	}
+	return nil, errors.New("no valid unlock code after three tries. Check it " +
+		"with whoever gave you this release and run setup again")
+}
+
+// claimShop redeems the installation code sealed in the bundle: the same call
+// the app's Setup screen and `behavision-agent claim` make, so the PC ends up
+// in exactly the state a customer's would - broker login, API token, the
+// broker's CA on disk - and head office pushes its cameras down on the first
+// sync.
+func claimShop(code, base string) (string, error) {
+	if base == "" {
+		base = "https://mcp.loyaly.ai"
+	}
+	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+	defer cancel()
+	b, err := enrol.Claim(ctx, base, code)
+	if err != nil {
+		return "", err
+	}
+	path := paths.AgentConfig()
+	cfg, err := config.Load(path)
+	if err != nil {
+		return "", err
+	}
+	cfg.ClientID = b.ClientSlug
+	cfg.SiteID = b.SiteSlug
+	cfg.SiteName = b.SiteName
+	cfg.BrokerURL = b.MQTTURL
+	cfg.BrokerUsername = b.MQTTUser
+	cfg.BrokerPassword = b.MQTTPass
+	cfg.AgentToken = b.AgentToken
+	cfg.CloudBase = base
+	cfg.Standalone = false
+	cfg.SessionToken, cfg.SessionRefresh, cfg.SessionEmail = "", "", ""
+	caPath, err := enrol.SaveCA(b.CACert, paths.BrokerCA())
+	if err != nil {
+		return "", err
+	}
+	cfg.BrokerCAFile = caPath
+	if err := cfg.Save(path); err != nil {
+		return "", err
+	}
+	return b.SiteName, nil
+}
+
+// addCameras posts each demo camera to the running engine, with the credential
+// the engine generated for itself on first start.
+func addCameras(cams []demo.Camera) error {
+	user, pass, err := engineCredential()
+	if err != nil {
+		return err
+	}
+	client := &http.Client{Timeout: 30 * time.Second}
+	for _, c := range cams {
+		if c.Port == 0 {
+			c.Port = 554
+		}
+		body, _ := json.Marshal(c)
+		req, _ := http.NewRequest(http.MethodPost, "http://127.0.0.1:8010/api/cameras",
+			bytes.NewReader(body))
+		req.Header.Set("Content-Type", "application/json")
+		if user != "" {
+			req.SetBasicAuth(user, pass)
+		}
+		resp, err := client.Do(req)
+		if err != nil {
+			return fmt.Errorf("adding camera %s: %w", c.ID, err)
+		}
+		msg, _ := io.ReadAll(io.LimitReader(resp.Body, 4096))
+		resp.Body.Close()
+		// 409 is "already there" - a re-run of setup, which is allowed.
+		if resp.StatusCode >= 300 && resp.StatusCode != http.StatusConflict {
+			return fmt.Errorf("adding camera %s: %s: %s", c.ID, resp.Status,
+				strings.TrimSpace(string(msg)))
+		}
+	}
+	return nil
+}
+
+// engineCredential reads the Basic credential the engine wrote on its first
+// start. Empty when the engine is configured without one.
+func engineCredential() (string, string, error) {
+	b, err := os.ReadFile(paths.APICredentials())
+	if err != nil {
+		if os.IsNotExist(err) {
+			return "", "", nil
+		}
+		return "", "", err
+	}
+	var user, pass string
+	for _, line := range strings.Split(string(b), "\n") {
+		if v, ok := strings.CutPrefix(line, "username="); ok {
+			user = strings.TrimSpace(v)
+		}
+		if v, ok := strings.CutPrefix(line, "password="); ok {
+			pass = strings.TrimSpace(v)
+		}
+	}
+	return user, pass, nil
+}
+
+// markStandalone records that this PC runs on its own, through the same
+// config type the app reads.
+func markStandalone() error {
+	path := paths.AgentConfig()
+	cfg, err := config.Load(path)
+	if err != nil {
+		return err
+	}
+	cfg.Standalone = true
+	return cfg.Save(path)
+}

agent/go.mod

@@ -7,4 +7,5 @@ require (
 	github.com/gorilla/websocket v1.5.0 // indirect
 	golang.org/x/net v0.8.0 // indirect
 	golang.org/x/sync v0.1.0 // indirect
+	golang.org/x/sys v0.20.0 // indirect
 )

agent/go.sum

@@ -6,3 +6,5 @@ golang.org/x/net v0.8.0 h1:Zrh2ngAOFYneWTAIAPethzeaQLuHwhuBkuV6ZiRnUaQ=
 golang.org/x/net v0.8.0/go.mod h1:QVkue5JL9kW//ek3r6jTKnTFis1tRmNAW2P1shuFdJc=
 golang.org/x/sync v0.1.0 h1:wsuoTGHzEhffawBOhz5CYhcrV4IdKZbEyZjBMuTp12o=
 golang.org/x/sync v0.1.0/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
+golang.org/x/sys v0.20.0 h1:Od9JTbYCk261bKm4M/mw7AklTlFYIa0bIp9BgSm1S8Y=
+golang.org/x/sys v0.20.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=

agent/main.go

@@ -29,6 +29,7 @@ import (
 	"github.com/loyaly/behavision-agent/pkg/cameras"
 	"github.com/loyaly/behavision-agent/pkg/config"
 	"github.com/loyaly/behavision-agent/pkg/engine"
+	"github.com/loyaly/behavision-agent/pkg/enrol"
 	"github.com/loyaly/behavision-agent/pkg/mqtt"
 	"github.com/loyaly/behavision-agent/pkg/paths"
 	"github.com/loyaly/behavision-agent/pkg/spool"
@@ -38,8 +39,15 @@ var version = "dev"
 
 func main() {
 	flag.Usage = func() {
-		fmt.Fprintf(os.Stderr, "behavision-agent %s\n\nusage: %s <run|status|paths>\n",
+		fmt.Fprintf(os.Stderr, `behavision-agent %s
-			version, filepath.Base(os.Args[0]))
+
+usage: %s <command>
+
+  run              supervise the engine and report to head office (default)
+  claim <code>     link this PC to a shop, using an installation code
+  status           what this PC is and whether it is claimed
+  paths            where this install reads and writes
+`, version, filepath.Base(os.Args[0]))
 	}
 	flag.Parse()
 
@@ -53,6 +61,8 @@ func main() {
 		err = cmdRun()
 	case "status":
 		err = cmdStatus()
+	case "claim":
+		err = cmdClaim(flag.Args()[1:])
 	case "paths":
 		err = cmdPaths()
 	default:
@@ -64,6 +74,73 @@ func main() {
 	}
 }
 
+// cmdClaim is the headless half of onboarding.
+//
+// The desktop app has had a Setup screen for this; a back-office PC with no
+// window had nothing at all, so the only way to claim one was to hand-edit
+// agent.json - which is the state that screen was built to end.
+func cmdClaim(args []string) error {
+	if len(args) == 0 {
+		return fmt.Errorf("usage: behavision-agent claim <installation code>\n" +
+			"Ask whoever manages your shops for one - they can create it from\n" +
+			"the Behavision platform, under the shop.")
+	}
+	// Joined rather than requiring quotes: the code is printed in groups for
+	// reading aloud, and an operator pasting it will paste the spaces too.
+	code := strings.Join(args, "")
+
+	if err := paths.EnsureState(); err != nil {
+		return err
+	}
+	cfg, err := config.Load(paths.AgentConfig())
+	if err != nil {
+		return err
+	}
+	base := cfg.CloudBase
+	if v := os.Getenv("BEHAVISION_CLOUD"); v != "" {
+		base = v
+	}
+	if base == "" {
+		base = "https://mcp.loyaly.ai"
+	}
+
+	b, err := enrol.Claim(context.Background(), base, code)
+	if err != nil {
+		return err
+	}
+
+	// The slugs, not the uuids: the topic prefix is <client>.<site> and the
+	// broker's ACL is written against exactly that username.
+	cfg.ClientID = b.ClientSlug
+	cfg.SiteID = b.SiteSlug
+	cfg.SiteName = b.SiteName
+	cfg.BrokerURL = b.MQTTURL
+	cfg.BrokerUsername = b.MQTTUser
+	cfg.BrokerPassword = b.MQTTPass
+	cfg.AgentToken = b.AgentToken
+	cfg.CloudBase = base
+	cfg.SessionToken, cfg.SessionRefresh, cfg.SessionEmail = "", "", ""
+	caPath, err := enrol.SaveCA(b.CACert, paths.BrokerCA())
+	if err != nil {
+		return err
+	}
+	cfg.BrokerCAFile = caPath
+	// A PC that was running on its own and has now been linked is no longer
+	// standalone.
+	cfg.Standalone = false
+	if err := cfg.Save(paths.AgentConfig()); err != nil {
+		// Reported, never swallowed: a claim that is not on disk works until
+		// the next restart and then silently is not claimed any more, which
+		// looks exactly like a wrong code.
+		return fmt.Errorf("could not save the settings: %w", err)
+	}
+
+	fmt.Printf("linked to %s (%s.%s)\n", b.SiteName, b.ClientSlug, b.SiteSlug)
+	fmt.Printf("settings written to %s\n", paths.AgentConfig())
+	fmt.Println("restart the agent for it to take effect.")
+	return nil
+}
+
 func cmdPaths() error {
 	return json.NewEncoder(os.Stdout).Encode(map[string]string{
 		"version":      version,
@@ -84,6 +161,7 @@ func cmdStatus() error {
 	// which is the default. Reading it here is what stops every call the agent
 	// makes to the engine coming back 401 on a stock install.
 	cfg = cfg.WithEngineCredentials(paths.APICredentials())
+	creds := config.NewCreds(paths.APICredentials(), cfg.APIUser, cfg.APIPassword)
 	q, err := spool.Open(paths.SpoolDir(), cfg.SpoolMax)
 	if err != nil {
 		return err
@@ -92,7 +170,7 @@ func cmdStatus() error {
 		Command:   func(context.Context) *exec.Cmd { return nil },
 		HealthURL: strings.TrimRight(cfg.APIBase, "/") + "/api/health",
 		StatsURL:  strings.TrimRight(cfg.APIBase, "/") + "/api/stats",
-		User:      cfg.APIUser, Password: cfg.APIPassword,
+		User:      cfg.APIUser, Password: cfg.APIPassword, Creds: creds,
 	})
 	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
 	defer cancel()
@@ -127,6 +205,7 @@ func cmdRun() error {
 	// which is the default. Reading it here is what stops every call the agent
 	// makes to the engine coming back 401 on a stock install.
 	cfg = cfg.WithEngineCredentials(paths.APICredentials())
+	creds := config.NewCreds(paths.APICredentials(), cfg.APIUser, cfg.APIPassword)
 	// Opened before the engine starts: detections arriving in the first second
 	// must have somewhere to land.
 	q, err := spool.Open(paths.SpoolDir(), cfg.SpoolMax)
@@ -152,6 +231,14 @@ func cmdRun() error {
 	sup := engine.New(engine.Options{
 		Command: func(ctx context.Context) *exec.Cmd {
 			cmd := exec.CommandContext(ctx, exe, cfg.EngineArgs...)
+			// Run the engine FROM a known directory rather than from whatever
+			// happened to launch us. A double-clicked bundle hands its child
+			// "/", and an engine invoked as `-m behavision` then cannot find
+			// itself - measured on macOS, where it retried forever.
+			cmd.Dir = cfg.EngineDir
+			if cmd.Dir == "" {
+				cmd.Dir = paths.InstallRoot()
+			}
 			// How the engine learns where to send detections. The engine's
 			// config already reads `events.webhook_url: ${BEHAVISION_WEBHOOK_URL}`
 			// and python-dotenv does not override a variable the process
@@ -161,13 +248,13 @@ func cmdRun() error {
 			// nothing - the URL was returned, logged and even exposed on the
 			// desktop's status object, and never actually given to the engine.
 			// A claimed shop PC published heartbeats and zero visits.
-			cmd.Env = append(os.Environ(), "BEHAVISION_WEBHOOK_URL="+hookURL)
+			cmd.Env = engine.ChildEnv(hookURL)
 			return cmd
 		},
 		LogWriter: logFile,
 		HealthURL: strings.TrimRight(cfg.APIBase, "/") + "/api/health",
 		StatsURL:  strings.TrimRight(cfg.APIBase, "/") + "/api/stats",
-		User:      cfg.APIUser, Password: cfg.APIPassword,
+		User:      cfg.APIUser, Password: cfg.APIPassword, Creds: creds,
 	})
 
 	ctx, stop := signal.NotifyContext(context.Background(),
@@ -202,7 +289,11 @@ func cmdRun() error {
 	cloud := cameras.NewCloudClient(cfg.CloudBase, cfg.AgentToken)
 	cloud.Upload = uploader.UploadBytes
 	eng := cameras.NewEngineClient(cfg.APIBase, cfg.APIUser, cfg.APIPassword)
+	eng.Creds = creds
 	go cameras.New(eng, cloud, logger).Run(ctx)
+	// The live relay, which uploads nothing until somebody at head office is
+	// actually watching a camera.
+	go cameras.NewLive(eng, cloud, logger).Run(ctx)
 
 	// Before the engine starts, so the engine can be launched already knowing
 	// where to post its detections.

agent/pkg/bridge/images.go

@@ -106,6 +106,18 @@ func (u *SpacesUploader) UploadBytes(ctx context.Context, body []byte) (string,
 	}
 
 	target, err := u.target(ctx)
+	if errors.Is(err, ErrImagesOff) {
+		// No object storage on this server. Send the bytes to the API itself,
+		// which holds them for a deployment that has no bucket - the same
+		// fallback camera snapshots already take, and chosen by the SENTINEL
+		// rather than by matching the message, because a prose change would
+		// otherwise silently stop every photo in the estate.
+		//
+		// Only after target() has spoken. The unclaimed case returns the same
+		// sentinel from the guard at the top of this function, and a PC with no
+		// credentials has no server to PUT to either.
+		return u.uploadDirect(ctx, body)
+	}
 	if err != nil {
 		return "", err
 	}
@@ -135,6 +147,54 @@ func (u *SpacesUploader) UploadBytes(ctx context.Context, body []byte) (string,
 	return target.Key, nil
 }
 
+// uploadDirect posts the image to our own API, for a deployment with no bucket.
+//
+// Deliberately the second choice. A presigned PUT never passes a photograph
+// through the server at all, which is what makes it the right route wherever
+// object storage exists; this one is what stops "no S3 account" from meaning
+// "no customer photo, ever" on every local install and every self-hosted site.
+//
+// The server decides where it lands and returns the key, exactly as the
+// presigned route does. That symmetry is the point: the caller cannot tell
+// which route ran, so the queued visit, the read path and erasure all stay
+// single implementations.
+func (u *SpacesUploader) uploadDirect(ctx context.Context, body []byte) (string, error) {
+	req, err := http.NewRequestWithContext(ctx, http.MethodPost,
+		strings.TrimRight(u.BaseURL, "/")+"/api/agent/faces", bytes.NewReader(body))
+	if err != nil {
+		return "", err
+	}
+	req.Header.Set("Authorization", "Bearer "+u.Token)
+	req.Header.Set("Content-Type", "image/jpeg")
+	req.ContentLength = int64(len(body))
+
+	resp, err := u.httpClient().Do(req)
+	if err != nil {
+		return "", fmt.Errorf("upload face: %w", err)
+	}
+	defer resp.Body.Close()
+	if resp.StatusCode == http.StatusNotImplemented {
+		// This server stores no images at all. Stop trying rather than retry
+		// every visitor forever.
+		return "", ErrImagesOff
+	}
+	if resp.StatusCode != http.StatusOK && resp.StatusCode != http.StatusCreated {
+		msg, _ := io.ReadAll(io.LimitReader(resp.Body, 4<<10))
+		return "", fmt.Errorf("upload face returned %s: %s",
+			resp.Status, strings.TrimSpace(string(msg)))
+	}
+	var out struct {
+		Key string `json:"key"`
+	}
+	if err := json.NewDecoder(io.LimitReader(resp.Body, 8<<10)).Decode(&out); err != nil {
+		return "", err
+	}
+	if out.Key == "" {
+		return "", errors.New("server stored the face but named no key for it")
+	}
+	return out.Key, nil
+}
+
 func (u *SpacesUploader) target(ctx context.Context) (uploadTarget, error) {
 	var out uploadTarget
 	req, err := http.NewRequestWithContext(ctx, http.MethodPost,

agent/pkg/bridge/images_test.go

@@ -1,6 +1,7 @@
 package bridge
 
 import (
+	"bytes"
 	"context"
 	"encoding/json"
 	"errors"
@@ -200,3 +201,80 @@ func TestNoUploaderMeansNoImageAndNoLeftovers(t *testing.T) {
 		t.Fatal("the local image was left on disk")
 	}
 }
+
+// A deployment with no object storage must still get a photo onto the customer
+// record. Until the fallback existed, `images_disabled` meant every local
+// install and every self-hosted site showed no face for anybody, forever.
+func TestNoBucketFallsBackToTheServer(t *testing.T) {
+	var askedURL, postedFace bool
+	var gotBody []byte
+	var gotAuth, gotType string
+
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		switch r.URL.Path {
+		case "/api/agent/upload-url":
+			askedURL = true
+			// What a server with no bucket answers.
+			w.WriteHeader(http.StatusNotImplemented)
+			_, _ = w.Write([]byte(`{"error":"images_disabled"}`))
+		case "/api/agent/faces":
+			postedFace = true
+			gotAuth = r.Header.Get("Authorization")
+			gotType = r.Header.Get("Content-Type")
+			gotBody, _ = io.ReadAll(r.Body)
+			w.WriteHeader(http.StatusCreated)
+			_, _ = w.Write([]byte(`{"key":"db:11111111-1111-4111-8111-111111111111"}`))
+		default:
+			t.Errorf("unexpected request to %s", r.URL.Path)
+			w.WriteHeader(http.StatusNotFound)
+		}
+	}))
+	defer srv.Close()
+
+	u := &SpacesUploader{BaseURL: srv.URL, Token: "agent-token", Client: srv.Client()}
+	img := []byte{0xFF, 0xD8, 0xFF, 0xE0, 'x', 'y', 'z'}
+	key, err := u.UploadBytes(context.Background(), img)
+	if err != nil {
+		t.Fatalf("upload: %v", err)
+	}
+	if !askedURL {
+		t.Error("the presigned route must be tried first - it is the right one where a bucket exists")
+	}
+	if !postedFace {
+		t.Fatal("no fallback upload was made")
+	}
+	if !strings.HasPrefix(key, "db:") {
+		t.Errorf("want the server's own key, got %q", key)
+	}
+	if !bytes.Equal(gotBody, img) {
+		t.Error("the bytes sent are not the bytes given")
+	}
+	if gotAuth != "Bearer agent-token" || gotType != "image/jpeg" {
+		t.Errorf("auth %q type %q", gotAuth, gotType)
+	}
+}
+
+// A server that stores no images AT ALL must stop the agent trying, rather than
+// have it retry every visitor forever. Distinct from a failure, which is why
+// it is a sentinel and not a message.
+func TestAServerThatStoresNothingSaysSoOnce(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusNotImplemented)
+	}))
+	defer srv.Close()
+
+	u := &SpacesUploader{BaseURL: srv.URL, Token: "agent-token", Client: srv.Client()}
+	_, err := u.UploadBytes(context.Background(), []byte{0xFF, 0xD8, 0xFF, 0xE0})
+	if !errors.Is(err, ErrImagesOff) {
+		t.Fatalf("want ErrImagesOff so the caller stops trying, got %v", err)
+	}
+}
+
+// An unclaimed PC has no server to send anything to. The fallback must not fire
+// there - it would be a request to nowhere on every single visit.
+func TestAnUnclaimedAgentDoesNotTryToUpload(t *testing.T) {
+	u := &SpacesUploader{} // no BaseURL, no token
+	if _, err := u.UploadBytes(context.Background(), []byte{0xFF, 0xD8}); !errors.Is(err, ErrImagesOff) {
+		t.Fatalf("want ErrImagesOff, got %v", err)
+	}
+}

agent/pkg/cameras/cameras.go

@@ -29,7 +29,14 @@ type Engine interface {
 type Cloud interface {
 	Desired(ctx context.Context) ([]Desired, error)
 	Report(ctx context.Context, rep Report) error
+	// UploadSnapshot puts a JPEG in object storage and names it. Used for the
+	// placement check's proof picture, which is transient.
 	UploadSnapshot(ctx context.Context, jpeg []byte) (key string, err error)
+	// PutSnapshot gets a camera's latest frame to head office by whichever
+	// route this deployment has - the bucket, or the server itself when there
+	// is none. An empty key means the server already stored it, so the state
+	// report has nothing to carry.
+	PutSnapshot(ctx context.Context, cameraID string, jpeg []byte) (key string, err error)
 }
 
 // Local is a camera as the engine holds it.
@@ -48,6 +55,9 @@ type Local struct {
 
 // Desired is a camera as head office holds it.
 type Desired struct {
+	// ID is head office's uuid for this camera; CameraID is the name the
+	// engine on this PC knows it by. The live relay translates between them.
+	ID       string         `json:"id"`
 	CameraID string         `json:"camera_id"`
 	Label    string         `json:"label"`
 	Host     string         `json:"host"`
@@ -252,7 +262,9 @@ func (s *Syncer) reportWith(ctx context.Context, adopt []Desired) {
 			// camera is down matters far more than having a picture of it,
 			// and the picture is the part most likely to fail.
 			if jpeg, err := s.Engine.Snapshot(ctx, c.ID); err == nil && len(jpeg) > 0 {
-				if key, err := s.Cloud.UploadSnapshot(ctx, jpeg); err == nil {
+				// An empty key is not a failure: it means this deployment has
+				// no object storage and the server stored the picture itself.
+				if key, err := s.Cloud.PutSnapshot(ctx, c.ID, jpeg); err == nil {
 					st.SnapshotKey = key
 				} else {
 					s.logf("camera %s: snapshot upload failed: %v", c.ID, err)

agent/pkg/cameras/cameras_test.go

@@ -59,6 +59,10 @@ type fakeCloud struct {
 	reports    []Report
 	uploads    int
 	uploadErr  error
+	// direct records the cameras whose picture went to the server itself
+	// rather than to object storage.
+	direct     []string
+	directOnly bool
 }
 
 func (f *fakeCloud) Desired(context.Context) ([]Desired, error) {
@@ -68,6 +72,20 @@ func (f *fakeCloud) Report(_ context.Context, r Report) error {
 	f.reports = append(f.reports, r)
 	return nil
 }
+
+// PutSnapshot mirrors the real client: the bucket when there is one, the
+// server itself when there is not.
+func (f *fakeCloud) PutSnapshot(ctx context.Context, cameraID string, jpeg []byte) (string, error) {
+	if f.directOnly {
+		if f.uploadErr != nil {
+			return "", f.uploadErr
+		}
+		f.direct = append(f.direct, cameraID)
+		return "", nil
+	}
+	return f.UploadSnapshot(ctx, jpeg)
+}
+
 func (f *fakeCloud) UploadSnapshot(context.Context, []byte) (string, error) {
 	if f.uploadErr != nil {
 		return "", f.uploadErr
@@ -239,3 +257,28 @@ func TestAnEngineThatIsNotRunningIsNotAnError(t *testing.T) {
 		t.Fatal("reported state it could not have observed")
 	}
 }
+
+// A deployment with no object storage must still get its picture to head
+// office. Before this, the camera screen said "This system is not storing
+// images" for every camera, forever - on the one screen whose entire job is to
+// show the camera.
+func TestASnapshotStillReachesHeadOfficeWithNoObjectStorage(t *testing.T) {
+	e := newEngine(Local{ID: "entrance", Connected: true})
+	c := &fakeCloud{directOnly: true}
+	syncer(e, c).Once(context.Background())
+
+	if len(c.direct) != 1 || c.direct[0] != "entrance" {
+		t.Fatalf("the picture did not reach the server: %v", c.direct)
+	}
+	if len(c.reports) == 0 || len(c.reports[0].State) != 1 {
+		t.Fatalf("no state was reported: %+v", c.reports)
+	}
+	// Empty, and that is the point: there is no object to name. A key here
+	// would have head office try to presign a bucket it does not have.
+	if key := c.reports[0].State[0].SnapshotKey; key != "" {
+		t.Fatalf("the direct route reported an object key %q", key)
+	}
+	if !c.reports[0].State[0].Connected {
+		t.Error("connected state was lost")
+	}
+}

agent/pkg/cameras/clients.go

@@ -4,12 +4,17 @@ import (
 	"bytes"
 	"context"
 	"encoding/json"
+	"errors"
 	"fmt"
 	"io"
 	"net/http"
 	"net/url"
+	"strconv"
 	"strings"
 	"time"
+
+	"github.com/loyaly/behavision-agent/pkg/bridge"
+	"github.com/loyaly/behavision-agent/pkg/config"
 )
 
 // EngineClient talks to the recognition engine on this PC's loopback.
@@ -17,7 +22,12 @@ type EngineClient struct {
 	Base     string
 	User     string
 	Password string
-	Client   *http.Client
+	// Creds re-reads the engine's generated credential when one is rejected.
+	// Without it a fresh install is 401 for the life of the process: the agent
+	// starts the engine, and the engine writes its credential file seconds
+	// after the agent has already read (and failed to find) it.
+	Creds  *config.Creds
+	Client *http.Client
 }
 
 func NewEngineClient(base, user, password string) *EngineClient {
@@ -46,14 +56,24 @@ func (e *EngineClient) do(ctx context.Context, method, path string, body, out an
 	if body != nil {
 		req.Header.Set("Content-Type", "application/json")
 	}
-	if e.User != "" {
+	user, pass := e.User, e.Password
-		req.SetBasicAuth(e.User, e.Password)
+	if e.Creds != nil {
+		user, pass = e.Creds.Get()
+	}
+	if user != "" {
+		req.SetBasicAuth(user, pass)
 	}
 	resp, err := e.Client.Do(req)
 	if err != nil {
 		return err
 	}
 	defer resp.Body.Close()
+	if resp.StatusCode == http.StatusUnauthorized && e.Creds != nil && e.Creds.Refresh() {
+		// The engine generated its credential after we last looked. Read it
+		// and try once more rather than failing for the life of the process.
+		resp.Body.Close()
+		return e.do(ctx, method, path, body, out)
+	}
 	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
 		// The engine's message, not just a status. "camera stored but failed to
 		// start: connection refused" is something an operator can act on;
@@ -95,8 +115,29 @@ func (e *EngineClient) Remove(ctx context.Context, id string) error {
 // trip. A camera that has not produced a frame yet answers 503, which is a
 // normal state on a just-added camera and not an error worth logging loudly.
 func (e *EngineClient) Snapshot(ctx context.Context, id string) ([]byte, error) {
-	req, err := http.NewRequestWithContext(ctx, http.MethodGet,
+	return e.Frame(ctx, id, 0, 0)
-		e.Base+"/api/cameras/"+url.PathEscape(id)+"/frame.jpg", nil)
+}
+
+// Frame fetches the latest frame, optionally re-encoded smaller.
+//
+// The live relay asks for ~640 px at quality 60 - about a third the bytes of
+// the full frame - because it sends several a second up a shop's uplink, where
+// the snapshot sends one a minute and can afford the detail. The engine does
+// the re-encode: it already has OpenCV open and the frame in memory, and
+// shipping a scaler into the agent to redo that would be the same work twice.
+func (e *EngineClient) Frame(ctx context.Context, id string, width, quality int) ([]byte, error) {
+	q := url.Values{}
+	if width > 0 {
+		q.Set("width", strconv.Itoa(width))
+	}
+	if quality > 0 {
+		q.Set("quality", strconv.Itoa(quality))
+	}
+	target := e.Base + "/api/cameras/" + url.PathEscape(id) + "/frame.jpg"
+	if len(q) > 0 {
+		target += "?" + q.Encode()
+	}
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, target, nil)
 	if err != nil {
 		return nil, err
 	}
@@ -192,6 +233,64 @@ func (c *CloudClient) UploadSnapshot(ctx context.Context, jpeg []byte) (string,
 	return c.Upload(ctx, jpeg)
 }
 
+// PutSnapshot gets a camera's latest frame to head office by whichever route
+// that deployment has.
+//
+// The bucket first: a presigned PUT goes straight to object storage and never
+// passes through the API, which is what makes it the right route at estate
+// scale. When there is no bucket the picture goes to the server itself, which
+// stores one row per camera. Without this second route head office reported
+// "This system is not storing images" for every camera forever, on the screen
+// whose entire job is to show the camera.
+//
+// The returned key is empty for the direct route - there is no object to name -
+// and the server records the picture as it stores it, so the state report has
+// nothing to carry.
+func (c *CloudClient) PutSnapshot(ctx context.Context, cameraID string, jpeg []byte) (string, error) {
+	if c.Upload != nil {
+		key, err := c.Upload(ctx, jpeg)
+		if err == nil {
+			return key, nil
+		}
+		// A bucket that is configured here but disabled at the server is the
+		// ordinary case on a self-hosted install: fall through rather than
+		// giving up, and let the direct route decide.
+		if !isImagesDisabled(err) {
+			return "", err
+		}
+	}
+	return "", c.putSnapshotDirect(ctx, cameraID, jpeg)
+}
+
+func (c *CloudClient) putSnapshotDirect(ctx context.Context, cameraID string, jpeg []byte) error {
+	req, err := http.NewRequestWithContext(ctx, http.MethodPut,
+		c.Base+"/api/agent/cameras/"+url.PathEscape(cameraID)+"/snapshot",
+		bytes.NewReader(jpeg))
+	if err != nil {
+		return err
+	}
+	req.Header.Set("Authorization", "Bearer "+c.Token)
+	req.Header.Set("Content-Type", "image/jpeg")
+	resp, err := c.Client.Do(req)
+	if err != nil {
+		return err
+	}
+	defer resp.Body.Close()
+	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
+		return fmt.Errorf("head office: %s", resp.Status)
+	}
+	return nil
+}
+
+// isImagesDisabled recognises the server saying it has no object storage.
+//
+// A sentinel, not a string match on the message: this decides whether to take a
+// completely different route, and getting it wrong from prose that somebody
+// later rewords would silently stop every camera picture in the estate.
+func isImagesDisabled(err error) bool {
+	return errors.Is(err, bridge.ErrImagesOff)
+}
+
 // ---------------------------------------------------------------- probing
 
 // Test opens the candidate stream once, without saving it.

agent/pkg/cameras/live.go

@@ -0,0 +1,243 @@
+package cameras
+
+import (
+	"bytes"
+	"context"
+	"crypto/sha256"
+	"encoding/binary"
+	"encoding/json"
+	"fmt"
+	"io"
+	"log"
+	"net/http"
+	"time"
+)
+
+// Live relays camera frames to head office, but only while somebody is
+// watching.
+//
+// The engine serves MJPEG on this PC's loopback and this PC sits behind a
+// router with no inbound route, so head office cannot pull it. It can answer
+// our outbound requests, which is the shape of everything else here: we ask
+// "is anyone watching?", and push frames for as long as the answer is yes.
+//
+// It is a few frames a second of re-encoded JPEG, not 25 fps video. True video
+// needs WebRTC and a TURN server; this needs neither, and answers the question
+// somebody at head office is actually asking - what does that camera see right
+// now - at a cost a shop's uplink can carry.
+//
+// **Nothing is uploaded when nobody is looking.** That is the entire cost
+// argument, and it is why the wanted-check comes first and the push stops the
+// moment the server says the last viewer has gone.
+type Live struct {
+	Engine    *EngineClient
+	Cloud     *CloudClient
+	Log       *log.Logger
+	FPS       float64
+	Width     int
+	Quality   int
+	pollDelay time.Duration
+}
+
+// Defaults, measured against the office camera rather than guessed.
+//
+// The engine produces ~12 distinct frames a second, so asking for more than
+// that only re-sends pictures the viewer already has - which is why the poll
+// runs slightly ahead of it and identical frames are dropped rather than sent.
+// 640 px at quality 60 is ~20 KB, so a watcher costs ~200 KB/s at the full
+// rate, and a camera nobody is watching costs nothing at all.
+const (
+	DefaultLiveFPS     = 15.0
+	DefaultLiveWidth   = 640
+	DefaultLiveQuality = 60
+)
+
+func NewLive(eng *EngineClient, cloud *CloudClient, logger *log.Logger) *Live {
+	return &Live{Engine: eng, Cloud: cloud, Log: logger,
+		FPS: DefaultLiveFPS, Width: DefaultLiveWidth, Quality: DefaultLiveQuality}
+}
+
+// Run waits for viewers and serves them until the context ends.
+func (l *Live) Run(ctx context.Context) {
+	if l.Engine == nil || l.Cloud == nil {
+		return
+	}
+	for {
+		if ctx.Err() != nil {
+			return
+		}
+		wanted, err := l.Cloud.LiveWanted(ctx)
+		if err != nil {
+			// Unclaimed, offline, or head office is down. All three mean the
+			// same thing here - nobody can be watching - so back off rather
+			// than hammering, and keep the shop's own recognition untouched.
+			if ctx.Err() != nil {
+				return
+			}
+			l.sleep(ctx, 15*time.Second)
+			continue
+		}
+		if len(wanted) == 0 {
+			// The poll is held open by the server, so an empty answer already
+			// means ~25 s passed. No extra delay.
+			continue
+		}
+		for _, id := range wanted {
+			if ctx.Err() != nil {
+				return
+			}
+			l.serve(ctx, id)
+		}
+	}
+}
+
+// serve pushes frames for one camera until the server says stop.
+func (l *Live) serve(ctx context.Context, cameraID string) {
+	engineID, err := l.Cloud.LiveEngineID(ctx, cameraID)
+	if err != nil {
+		l.logf("live %s: %v", cameraID, err)
+		l.sleep(ctx, 2*time.Second)
+		return
+	}
+	interval := time.Duration(float64(time.Second) / l.fps())
+
+	// A pipe so frames can be written as they are grabbed while one request
+	// carries all of them. A request per frame would spend more on handshakes
+	// and headers than on pictures.
+	pr, pw := io.Pipe()
+	done := make(chan error, 1)
+	go func() { done <- l.Cloud.PushLive(ctx, cameraID, pr) }()
+
+	tick := time.NewTicker(interval)
+	defer tick.Stop()
+	// The engine re-serves its latest frame until the pipeline produces a new
+	// one, so polling faster than it encodes returns the SAME picture again.
+	// Measured: 93 polls in 6 s yielded 72 distinct frames. Sending the
+	// duplicates would cost a fifth of the bandwidth for nothing, so the poll
+	// runs a little ahead of the engine and the repeats are dropped - which is
+	// what lets the rate follow the camera instead of a guess.
+	var lastSum [32]byte
+	for {
+		select {
+		case <-ctx.Done():
+			_ = pw.CloseWithError(context.Canceled)
+			<-done
+			return
+		case err := <-done:
+			// The server closed the request: the last viewer went away, or the
+			// session cap was reached. Either way stop grabbing frames.
+			_ = pw.Close()
+			if err != nil {
+				l.logf("live %s ended: %v", cameraID, err)
+			}
+			return
+		case <-tick.C:
+		}
+		jpeg, err := l.Engine.Frame(ctx, engineID, l.Width, l.Quality)
+		if err != nil || len(jpeg) == 0 {
+			// A camera that is reconnecting has no frame. Keep the request
+			// open - the viewer sees the last frame rather than a dropped
+			// stream, and the next tick may well have one.
+			continue
+		}
+		if sum := sha256.Sum256(jpeg); sum == lastSum {
+			continue
+		} else {
+			lastSum = sum
+		}
+		var hdr [4]byte
+		binary.BigEndian.PutUint32(hdr[:], uint32(len(jpeg)))
+		if _, err := pw.Write(hdr[:]); err != nil {
+			<-done
+			return
+		}
+		if _, err := pw.Write(jpeg); err != nil {
+			<-done
+			return
+		}
+	}
+}
+
+func (l *Live) fps() float64 {
+	if l.FPS <= 0 || l.FPS > 25 {
+		// A ceiling rather than a target: duplicate frames are dropped, so
+		// polling above what the engine encodes costs requests and no
+		// bandwidth - but it is still work, on the PC doing the recognition.
+		return DefaultLiveFPS
+	}
+	return l.FPS
+}
+
+func (l *Live) sleep(ctx context.Context, d time.Duration) {
+	t := time.NewTimer(d)
+	defer t.Stop()
+	select {
+	case <-ctx.Done():
+	case <-t.C:
+	}
+}
+
+func (l *Live) logf(format string, args ...any) {
+	if l.Log != nil {
+		l.Log.Printf(format, args...)
+	}
+}
+
+// ------------------------------------------------------------------ wire --
+
+// LiveWanted asks head office which of this site's cameras are being watched.
+// The server holds the request open, so this returns promptly when somebody
+// presses Live and after ~25 s when nobody has.
+func (c *CloudClient) LiveWanted(ctx context.Context) ([]string, error) {
+	var body struct {
+		Cameras []string `json:"cameras"`
+	}
+	// Longer than the server's own wait, so a held request is not cut off by
+	// our own client timeout and reported as a failure.
+	ctx, cancel := context.WithTimeout(ctx, 60*time.Second)
+	defer cancel()
+	if err := c.do(ctx, http.MethodGet, "/api/agent/live", nil, &body); err != nil {
+		return nil, err
+	}
+	return body.Cameras, nil
+}
+
+// LiveEngineID maps head office's camera uuid to the name the engine knows,
+// which is the only name this PC can ask for a frame with.
+func (c *CloudClient) LiveEngineID(ctx context.Context, cameraID string) (string, error) {
+	desired, err := c.Desired(ctx)
+	if err != nil {
+		return "", err
+	}
+	for _, d := range desired {
+		if d.ID == cameraID {
+			return d.CameraID, nil
+		}
+	}
+	return "", fmt.Errorf("camera %s is not one of this site's", cameraID)
+}
+
+// PushLive streams frames until the server stops reading.
+func (c *CloudClient) PushLive(ctx context.Context, cameraID string, body io.Reader) error {
+	req, err := http.NewRequestWithContext(ctx, http.MethodPost,
+		c.Base+"/api/agent/cameras/"+cameraID+"/live", body)
+	if err != nil {
+		return err
+	}
+	req.Header.Set("Authorization", "Bearer "+c.Token)
+	req.Header.Set("Content-Type", "application/octet-stream")
+	resp, err := c.Client.Do(req)
+	if err != nil {
+		return err
+	}
+	defer resp.Body.Close()
+	blob, _ := io.ReadAll(io.LimitReader(resp.Body, 4<<10))
+	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
+		return fmt.Errorf("head office: %s: %s", resp.Status, bytes.TrimSpace(blob))
+	}
+	var out struct {
+		Frames int `json:"frames"`
+	}
+	_ = json.Unmarshal(blob, &out)
+	return nil
+}

agent/pkg/config/config.go

@@ -37,7 +37,18 @@ type Config struct {
 	BrokerCAFile string `json:"broker_ca_file"`
 
 	// Engine process.
-	EngineExe   string   `json:"engine_exe"`
+	EngineExe string `json:"engine_exe"`
+	// EngineDir is the working directory the engine is launched IN. Empty
+	// means the install root.
+	//
+	// It exists because nothing set it, so the engine inherited whatever
+	// launched the app - and for an app started by double-clicking its
+	// bundle that is "/", not anywhere useful. The symptom on macOS was
+	// `python: No module named behavision` repeating forever: the dev engine
+	// is `-m behavision`, which resolves against the working directory. The
+	// same app started from a terminal in the repo worked, which is exactly
+	// the shape of a bug that survives every test run by a developer.
+	EngineDir   string   `json:"engine_dir,omitempty"`
 	EngineArgs  []string `json:"engine_args"`
 	APIBase     string   `json:"api_base"`
 	APIUser     string   `json:"api_user"`

agent/pkg/config/credentials.go

@@ -4,6 +4,7 @@ import (
 	"bufio"
 	"os"
 	"strings"
+	"sync"
 )
 
 // EngineCredentials reads the Basic credentials the engine generated for
@@ -60,3 +61,60 @@ func (c Config) WithEngineCredentials(path string) Config {
 	c.APIUser, c.APIPassword = EngineCredentials(path)
 	return c
 }
+
+// Creds resolves the engine's Basic credentials, re-reading the file when it
+// has none.
+//
+// Reading once at startup is wrong on a fresh install, and that is the case
+// that matters: the agent starts the engine, the engine generates its
+// credential and writes the file a few seconds later, and an agent that read
+// the file before that holds "" forever. Every call it makes - health, stats,
+// camera sync, the embedding for a visit - then comes back 401 for the life of
+// the process, on a brand new shop PC, with the tray showing a red engine that
+// is running perfectly. Measured on a fresh state directory: three 401s and no
+// camera ever reconciled.
+//
+// A configured credential is never re-read: an operator who set
+// BEHAVISION_API_USER means it.
+type Creds struct {
+	path  string
+	mu    sync.Mutex
+	user  string
+	pass  string
+	fixed bool
+}
+
+// NewCreds takes whatever the config already has. Non-empty means configured,
+// and is used unchanged.
+func NewCreds(path, user, password string) *Creds {
+	c := &Creds{path: path, user: user, pass: password}
+	c.fixed = user != "" || password != ""
+	return c
+}
+
+// Get returns the current pair, reading the file if it has nothing yet.
+func (c *Creds) Get() (string, string) {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	if c.user == "" && !c.fixed {
+		c.user, c.pass = EngineCredentials(c.path)
+	}
+	return c.user, c.pass
+}
+
+// Refresh re-reads the file after a rejection and reports whether the pair
+// changed. Callers retry once when it did - which covers both the fresh-install
+// race and a credential the engine regenerated under a running agent.
+func (c *Creds) Refresh() bool {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	if c.fixed {
+		return false
+	}
+	u, p := EngineCredentials(c.path)
+	if u == c.user && p == c.pass {
+		return false
+	}
+	c.user, c.pass = u, p
+	return u != ""
+}

agent/pkg/config/credentials_firstrun_test.go

@@ -0,0 +1,77 @@
+package config
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+// The sequence on a brand new shop PC, in order:
+//
+//	agent starts  ->  file does not exist yet
+//	agent starts the engine
+//	engine generates its credential and writes the file
+//	agent calls the engine  ->  must now succeed
+//
+// Read once at startup, the agent holds "" for the life of the process and
+// every engine call is 401: health, stats, camera sync, the embedding for a
+// visit. The tray shows a red engine that is running perfectly, and nothing
+// says why. Measured on a fresh state directory before this existed.
+func TestCredentialsArriveAfterTheAgentHasAlreadyLooked(t *testing.T) {
+	dir := t.TempDir()
+	path := filepath.Join(dir, "api_credentials.txt")
+
+	creds := NewCreds(path, "", "") // nothing configured, file not there yet
+	if u, _ := creds.Get(); u != "" {
+		t.Fatalf("expected no credential before the engine has written one, got %q", u)
+	}
+
+	// the engine starts and writes its credential
+	if err := os.WriteFile(path, []byte("username=behavision\npassword=s3cret\n"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+
+	// a 401 makes the agent look again
+	if !creds.Refresh() {
+		t.Fatal("Refresh did not pick up the credential the engine just wrote")
+	}
+	u, p := creds.Get()
+	if u != "behavision" || p != "s3cret" {
+		t.Fatalf("got %q/%q", u, p)
+	}
+}
+
+// An operator who set BEHAVISION_API_USER means it, and a file must never
+// override them.
+func TestAConfiguredCredentialIsNeverReplacedByTheFile(t *testing.T) {
+	dir := t.TempDir()
+	path := filepath.Join(dir, "api_credentials.txt")
+	if err := os.WriteFile(path, []byte("username=generated\npassword=nope\n"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	creds := NewCreds(path, "chosen", "byhand")
+	if u, p := creds.Get(); u != "chosen" || p != "byhand" {
+		t.Fatalf("configured credential was replaced: %q/%q", u, p)
+	}
+	if creds.Refresh() {
+		t.Fatal("Refresh overrode a configured credential")
+	}
+}
+
+// A credential the engine regenerates under a running agent is picked up too -
+// the same mechanism, and the reason paths.APICredentials says the agent reads
+// the file "rather than storing a second copy".
+func TestARegeneratedCredentialIsPickedUp(t *testing.T) {
+	dir := t.TempDir()
+	path := filepath.Join(dir, "api_credentials.txt")
+	os.WriteFile(path, []byte("username=behavision\npassword=old\n"), 0o600)
+	creds := NewCreds(path, "", "")
+	creds.Get()
+	os.WriteFile(path, []byte("username=behavision\npassword=new\n"), 0o600)
+	if !creds.Refresh() {
+		t.Fatal("a regenerated password was not picked up")
+	}
+	if _, p := creds.Get(); p != "new" {
+		t.Fatalf("still holding %q", p)
+	}
+}

agent/pkg/demo/bundle.go

@@ -0,0 +1,140 @@
+// Package demo seals a camera list so a release can carry it without carrying
+// the credentials in any usable form.
+//
+// The need: a demo build that installs with the office cameras already set up,
+// handed to people who should not be able to read the cameras' admin password
+// out of the zip. "Encode it" does not do that - anything the installer can
+// decode, anyone holding the installer can decode. So the bundle is encrypted
+// with a key that is NOT in the package: a short unlock code, generated when
+// the bundle is sealed, spoken or messaged to whoever runs setup, and typed
+// once. Without it the file is noise.
+//
+// The code is random, not chosen, so it is used as key material directly
+// (through SHA-256) rather than stretched with a KDF. A human-chosen
+// passphrase would need argon2 and a dependency; 120 random bits do not.
+package demo
+
+import (
+	"crypto/aes"
+	"crypto/cipher"
+	"crypto/rand"
+	"crypto/sha256"
+	"encoding/base32"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"strings"
+)
+
+// Magic identifies the file and the format version, so a future change can be
+// told apart from corruption instead of failing as "authentication failed".
+const magic = "BVDEMO1\n"
+
+// Payload is what a sealed bundle carries. Two demo shapes exist:
+//
+//   - cameras only: the PC runs on its own with these cameras (the first
+//     demo build);
+//   - an enrolment code: the PC claims a real shop at head office and gets
+//     its cameras from there, exactly as a customer install would, so the
+//     demo exercises the whole product rather than a local copy of it. The
+//     code is single-use, so one bundle is one install.
+//
+// A bundle from the first build is a bare JSON array; Decode accepts both.
+type Payload struct {
+	Cameras   []Camera `json:"cameras,omitempty"`
+	EnrolCode string   `json:"enrol_code,omitempty"`
+	CloudBase string   `json:"cloud_base,omitempty"`
+}
+
+// Decode reads either payload shape.
+func Decode(plain []byte) (Payload, error) {
+	var p Payload
+	if len(plain) > 0 && plain[0] == '[' {
+		return p, json.Unmarshal(plain, &p.Cameras)
+	}
+	return p, json.Unmarshal(plain, &p)
+}
+
+// Camera is one entry as the engine's Add Camera endpoint accepts it.
+type Camera struct {
+	ID       string `json:"id"`
+	Label    string `json:"label,omitempty"`
+	Host     string `json:"host"`
+	Port     int    `json:"port"`
+	Path     string `json:"path"`
+	Username string `json:"username"`
+	Password string `json:"password"`
+	MaxWidth int    `json:"max_width,omitempty"`
+}
+
+// NewCode mints an unlock code: 15 random bytes as 24 base32 characters in
+// four groups, the same shape as an installation code, for the same reason -
+// it gets read down a phone.
+func NewCode() (string, error) {
+	raw := make([]byte, 15)
+	if _, err := rand.Read(raw); err != nil {
+		return "", err
+	}
+	s := base32.StdEncoding.WithPadding(base32.NoPadding).EncodeToString(raw)
+	return fmt.Sprintf("%s-%s-%s-%s", s[0:6], s[6:12], s[12:18], s[18:24]), nil
+}
+
+// NormalizeCode makes the typed and the printed form hash the same: case,
+// spaces and dashes are all noise a person adds or drops.
+func NormalizeCode(code string) string {
+	code = strings.ToUpper(code)
+	code = strings.NewReplacer("-", "", " ", "", "\t", "", "\r", "", "\n", "").Replace(code)
+	return code
+}
+
+func keyFor(code string) []byte {
+	sum := sha256.Sum256([]byte("behavision-demo-bundle:" + NormalizeCode(code)))
+	return sum[:]
+}
+
+// Seal encrypts plaintext under the code. Output is magic || nonce || ciphertext.
+func Seal(code string, plaintext []byte) ([]byte, error) {
+	block, err := aes.NewCipher(keyFor(code))
+	if err != nil {
+		return nil, err
+	}
+	gcm, err := cipher.NewGCM(block)
+	if err != nil {
+		return nil, err
+	}
+	nonce := make([]byte, gcm.NonceSize())
+	if _, err := rand.Read(nonce); err != nil {
+		return nil, err
+	}
+	out := append([]byte(magic), nonce...)
+	return gcm.Seal(out, nonce, plaintext, []byte(magic)), nil
+}
+
+// ErrWrongCode is what a mistyped code looks like. GCM cannot tell a wrong key
+// from a corrupted file, and neither can we, so both read as this.
+var ErrWrongCode = errors.New("that unlock code does not open this bundle")
+
+// Open decrypts a sealed bundle.
+func Open(code string, sealed []byte) ([]byte, error) {
+	if !strings.HasPrefix(string(sealed), magic) {
+		return nil, errors.New("not a Behavision demo bundle")
+	}
+	body := sealed[len(magic):]
+	block, err := aes.NewCipher(keyFor(code))
+	if err != nil {
+		return nil, err
+	}
+	gcm, err := cipher.NewGCM(block)
+	if err != nil {
+		return nil, err
+	}
+	if len(body) < gcm.NonceSize() {
+		return nil, errors.New("bundle is truncated")
+	}
+	nonce, ct := body[:gcm.NonceSize()], body[gcm.NonceSize():]
+	plain, err := gcm.Open(nil, nonce, ct, []byte(magic))
+	if err != nil {
+		return nil, ErrWrongCode
+	}
+	return plain, nil
+}

agent/pkg/demo/bundle_test.go

@@ -0,0 +1,87 @@
+package demo
+
+import (
+	"bytes"
+	"errors"
+	"strings"
+	"testing"
+)
+
+func TestSealedBundleRoundTripsWithTheCodeAsTyped(t *testing.T) {
+	code, err := NewCode()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(NormalizeCode(code)) != 24 {
+		t.Fatalf("code should be 24 base32 chars, got %q", code)
+	}
+	secret := []byte(`[{"id":"cam1","password":"the-camera-admin-password"}]`)
+
+	sealed, err := Seal(code, secret)
+	if err != nil {
+		t.Fatal(err)
+	}
+	// People type codes in lower case, with the dashes dropped, with a space
+	// where a dash was. All of those are the same code.
+	for _, typed := range []string{
+		code,
+		strings.ToLower(code),
+		strings.ReplaceAll(code, "-", ""),
+		strings.ReplaceAll(code, "-", " "),
+		"  " + code + "\n",
+	} {
+		got, err := Open(typed, sealed)
+		if err != nil {
+			t.Fatalf("open with %q: %v", typed, err)
+		}
+		if !bytes.Equal(got, secret) {
+			t.Fatalf("round trip changed the contents")
+		}
+	}
+}
+
+// The whole point of the file: the password is not in it.
+func TestTheSealedFileDoesNotContainTheSecret(t *testing.T) {
+	code, _ := NewCode()
+	sealed, _ := Seal(code, []byte(`{"password":"the-camera-admin-password","host":"192.168.1.121"}`))
+	for _, leak := range []string{"the-camera-admin-password", "192.168.1.121", "password"} {
+		if bytes.Contains(sealed, []byte(leak)) {
+			t.Fatalf("sealed bundle contains %q in the clear", leak)
+		}
+	}
+}
+
+func TestAWrongCodeIsRefusedNotMisread(t *testing.T) {
+	code, _ := NewCode()
+	other, _ := NewCode()
+	sealed, _ := Seal(code, []byte("secret"))
+
+	if _, err := Open(other, sealed); !errors.Is(err, ErrWrongCode) {
+		t.Fatalf("a different code should be ErrWrongCode, got %v", err)
+	}
+	// One flipped byte in the ciphertext is the same answer: GCM refuses
+	// rather than returning garbage that then gets written into cameras.json.
+	tampered := append([]byte{}, sealed...)
+	tampered[len(tampered)-1] ^= 0x01
+	if _, err := Open(code, tampered); !errors.Is(err, ErrWrongCode) {
+		t.Fatalf("a tampered bundle should be refused, got %v", err)
+	}
+}
+
+func TestSomethingThatIsNotABundleSaysSo(t *testing.T) {
+	if _, err := Open("ABCDEF-GHIJKL-MNOPQR-STUVWX", []byte("hello")); err == nil ||
+		errors.Is(err, ErrWrongCode) {
+		t.Fatalf("a non-bundle should be named as such, not blamed on the code: %v", err)
+	}
+}
+
+// Two seals of the same plaintext under the same code must differ: a fixed
+// nonce would let two releases' bundles be compared byte for byte.
+func TestEverySealIsDifferent(t *testing.T) {
+	code, _ := NewCode()
+	a, _ := Seal(code, []byte("same"))
+	b, _ := Seal(code, []byte("same"))
+	if bytes.Equal(a, b) {
+		t.Fatal("nonce is not random")
+	}
+}

agent/pkg/engine/env.go

@@ -0,0 +1,41 @@
+package engine
+
+import (
+	"os"
+
+	"github.com/loyaly/behavision-agent/pkg/paths"
+)
+
+// ChildEnv is the environment the engine is launched with, wherever it is
+// launched from - the desktop app and the headless agent both go through
+// here, so a third caller cannot get it half right.
+//
+// The line that matters is BEHAVISION_DATA_DIR.
+//
+// The engine's paths.py knows two worlds: frozen with PyInstaller, where state
+// lives under ProgramData, and a checkout, where everything sits in the repo
+// root. An engine installed from source into a virtual environment is neither.
+// Left to itself it resolves its state root to site-packages - writes its
+// database and camera list there, and generates its API credential into a
+// folder this process never reads - while this process resolves the same
+// state root to ProgramData. The two halves then disagree about where
+// everything lives, and every call to the engine is 401 on a stock install,
+// with nothing in either log saying why. Seen twice: once on a Mac checkout
+// (the app in ~/Library, the engine in the repo) and once in a clean Linux
+// container running the installer.
+//
+// Telling the engine where THIS process keeps state makes the two agree by
+// construction, however the engine was installed. paths.py honours the
+// override ahead of every other rule it has.
+//
+// hookURL is where the engine posts detections; empty is allowed and means
+// the bridge has not started, which the engine treats as "no webhook".
+func ChildEnv(hookURL string) []string {
+	env := append(os.Environ(),
+		"BEHAVISION_DATA_DIR="+paths.StateRoot(),
+	)
+	if hookURL != "" {
+		env = append(env, "BEHAVISION_WEBHOOK_URL="+hookURL)
+	}
+	return env
+}

agent/pkg/engine/env_test.go

@@ -0,0 +1,44 @@
+package engine
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/loyaly/behavision-agent/pkg/paths"
+)
+
+// The engine must be told where THIS process keeps state, or a pip-installed
+// engine decides on site-packages and the two halves never find each other.
+func TestTheEngineIsToldWhereStateLives(t *testing.T) {
+	t.Setenv("BEHAVISION_DATA_DIR", t.TempDir())
+
+	env := ChildEnv("http://127.0.0.1:5555/events")
+
+	want := "BEHAVISION_DATA_DIR=" + paths.StateRoot()
+	if !contains(env, want) {
+		t.Fatalf("engine env lacks %q - a source-installed engine would put its "+
+			"database and credential somewhere this process never looks", want)
+	}
+	if !contains(env, "BEHAVISION_WEBHOOK_URL=http://127.0.0.1:5555/events") {
+		t.Fatal("webhook url not passed to the engine")
+	}
+}
+
+// Before the bridge has a port there is no webhook. An empty variable would be
+// read by the engine as a webhook at "", which is not the same as none.
+func TestNoWebhookMeansNoVariable(t *testing.T) {
+	for _, v := range ChildEnv("") {
+		if strings.HasPrefix(v, "BEHAVISION_WEBHOOK_URL=") {
+			t.Fatalf("empty hook still exported: %q", v)
+		}
+	}
+}
+
+func contains(env []string, want string) bool {
+	for _, v := range env {
+		if v == want {
+			return true
+		}
+	}
+	return false
+}

agent/pkg/engine/supervisor.go

@@ -21,7 +21,12 @@ import (
 	"net/http"
 	"os"
 	"os/exec"
+	"regexp"
+	"strconv"
+	"strings"
 	"sync"
+
+	"github.com/loyaly/behavision-agent/pkg/config"
 	"time"
 )
 
@@ -56,6 +61,9 @@ type Options struct {
 	// no captured output is undiagnosable, which on a customer site means a
 	// site visit.
 	LogWriter io.Writer
+	// Creds re-reads the engine's generated credential when one is rejected,
+	// which is the ordinary case on a first run.
+	Creds *config.Creds
 	// HealthURL, StatsURL, User, Password address the engine's own API.
 	HealthURL string
 	StatsURL  string
@@ -76,6 +84,7 @@ type Supervisor struct {
 	restarts int
 	cancel   context.CancelFunc
 	done     chan struct{}
+	progress Progress
 }
 
 func New(opts Options) *Supervisor {
@@ -109,6 +118,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()
@@ -194,22 +234,59 @@ func (s *Supervisor) runOnce(ctx context.Context) error {
 		return err
 	}
 	cmd.Stderr = cmd.Stdout
+	// Cancel ends the whole process tree, not just the process exec spawned.
+	// `kill` is filled in after Start, once the tree is confined; until then
+	// it is exec's own behaviour.
+	var kill func() error
+	cmd.Cancel = func() error {
+		if kill == nil {
+			return cmd.Process.Kill()
+		}
+		return kill()
+	}
+	prepare(cmd)
 	if err := cmd.Start(); err != nil {
 		return fmt.Errorf("engine failed to start: %w", err)
 	}
+	k, release, err := confine(cmd)
+	if err != nil {
+		// Not fatal: the engine runs, and stopping it falls back to killing
+		// the one process. Logged because on Windows that fallback is the
+		// bug this exists to fix.
+		fmt.Fprintf(s.opts.LogWriter, "supervisor: could not confine engine process tree: %v\n", err)
+	}
+	kill = k
+	defer release()
 
+	// The last few lines the engine printed travel with the failure, because
+	// "engine exited: exit status 1" sends somebody to a log file on a shop
+	// PC, and the one line that matters - "port 8010 is already in use" - was
+	// right there.
+	var tailMu sync.Mutex
+	var tail []string
 	pumped := make(chan struct{})
 	go func() {
 		defer close(pumped)
 		sc := bufio.NewScanner(stdout)
 		sc.Buffer(make([]byte, 0, 64*1024), 1024*1024)
 		for sc.Scan() {
-			fmt.Fprintln(s.opts.LogWriter, sc.Text())
+			line := sc.Text()
+			fmt.Fprintln(s.opts.LogWriter, line)
+			s.noteProgress(line)
+			tailMu.Lock()
+			tail = append(tail, line)
+			if len(tail) > 12 {
+				tail = tail[1:]
+			}
+			tailMu.Unlock()
 		}
 	}()
 
 	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
@@ -218,6 +295,12 @@ func (s *Supervisor) runOnce(ctx context.Context) error {
 		return nil
 	}
 	if waitErr != nil {
+		tailMu.Lock()
+		reason := explain(tail)
+		tailMu.Unlock()
+		if reason != "" {
+			return fmt.Errorf("%s (%v)", reason, waitErr)
+		}
 		return fmt.Errorf("engine exited: %w", waitErr)
 	}
 	return errors.New("engine exited unexpectedly with status 0")
@@ -331,14 +414,24 @@ func (s *Supervisor) getJSON(ctx context.Context, url string, out any) error {
 	if err != nil {
 		return err
 	}
-	if s.opts.User != "" {
+	user, pass := s.opts.User, s.opts.Password
-		req.SetBasicAuth(s.opts.User, s.opts.Password)
+	if s.opts.Creds != nil {
+		user, pass = s.opts.Creds.Get()
+	}
+	if user != "" {
+		req.SetBasicAuth(user, pass)
 	}
 	resp, err := (&http.Client{Timeout: 5 * time.Second}).Do(req)
 	if err != nil {
 		return err
 	}
 	defer resp.Body.Close()
+	if resp.StatusCode == http.StatusUnauthorized && s.opts.Creds != nil && s.opts.Creds.Refresh() {
+		// See cameras.EngineClient: on a fresh install the engine writes its
+		// credential after the agent has already read for one.
+		resp.Body.Close()
+		return s.getJSON(ctx, url, out)
+	}
 	if resp.StatusCode != http.StatusOK {
 		return fmt.Errorf("%s returned %s", url, resp.Status)
 	}
@@ -353,3 +446,28 @@ func LogFile(path string) (*os.File, error) {
 	}
 	return os.OpenFile(path, os.O_CREATE|os.O_WRONLY|os.O_APPEND, 0o600)
 }
+
+// explain turns the engine's last output into the sentence the tray shows.
+// The cases are the ones seen on real installs; anything else shows the last
+// non-empty line verbatim.
+func explain(tail []string) string {
+	last := ""
+	for _, l := range tail {
+		low := strings.ToLower(l)
+		switch {
+		case strings.Contains(low, "address already in use") || strings.Contains(low, "only one usage of each socket address"):
+			return "port 8010 is already in use - another Behavision or its engine is still running"
+		case strings.Contains(low, "no module named behavision"):
+			return "the engine is not installed in this Python - run behavision-setup again"
+		case strings.Contains(low, "modulenotfounderror") || strings.Contains(low, "importerror"):
+			return "the engine is missing a library - run behavision-setup again"
+		}
+		if strings.TrimSpace(l) != "" {
+			last = strings.TrimSpace(l)
+		}
+	}
+	if len(last) > 120 {
+		last = last[:120] + "…"
+	}
+	return last
+}

agent/pkg/engine/tree_other.go

@@ -0,0 +1,13 @@
+//go:build !windows
+
+package engine
+
+import "os/exec"
+
+// On every other platform the engine is one process and exec's own kill is
+// enough. See tree_windows.go for why Windows is not.
+func prepare(*exec.Cmd) {}
+
+func confine(cmd *exec.Cmd) (kill func() error, release func(), err error) {
+	return cmd.Process.Kill, func() {}, nil
+}

agent/pkg/engine/tree_windows.go

@@ -0,0 +1,111 @@
+//go:build windows
+
+package engine
+
+import (
+	"fmt"
+	"os/exec"
+	"syscall"
+	"unsafe"
+
+	"golang.org/x/sys/windows"
+)
+
+// The engine is not one process on Windows, and stopping it used to leave
+// recognition running.
+//
+// The installer starts it as `<venv>\Scripts\python.exe -m behavision run`.
+// Since Python 3.7.2 that python.exe is a REDIRECTOR: a small launcher that
+// spawns the base interpreter as a child and waits for it. Stop() cancelled the
+// context, exec terminated the launcher, and the interpreter that actually
+// holds the cameras and the SQLite WAL carried on with no parent, no tray icon
+// and nothing left that could stop it. Seen on a Windows install: "Quit
+// Behavision" from the tray, and the engine still running.
+//
+// The fix is the primitive Windows has for exactly this: a job object with
+// KILL_ON_JOB_CLOSE. Every process the engine spawns inherits membership, and
+// the whole tree dies when the job is terminated or when this process's last
+// handle to it goes away - so "quitting the app stops recognition" holds even
+// if the app crashes, which no amount of careful Stop() code can promise.
+//
+// The child is started SUSPENDED and resumed only after it is in the job.
+// Assigning after the fact leaves a window in which the launcher has already
+// spawned the interpreter outside it, and that window is precisely the case
+// this file exists to close.
+
+// prepare is applied to the command before it starts.
+func prepare(cmd *exec.Cmd) {
+	if cmd.SysProcAttr == nil {
+		cmd.SysProcAttr = &syscall.SysProcAttr{}
+	}
+	// CREATE_NO_WINDOW: python.exe is a console program and Behavision.exe is
+	// not, so without this Windows opens a black console window for the
+	// engine on a shop counter - the app looks like it has crashed into a
+	// terminal. Output still arrives on the pipes.
+	cmd.SysProcAttr.CreationFlags |= windows.CREATE_SUSPENDED | windows.CREATE_NO_WINDOW
+}
+
+// confine is applied after Start. It puts the process in a kill-on-close job,
+// then resumes it. It returns a function that ends the whole tree, and one
+// that releases the job handle once the tree has exited.
+//
+// If the job cannot be set up the process is still resumed and the plain
+// terminate remains: a suspended engine that never runs is strictly worse
+// than one that may outlive its parent.
+func confine(cmd *exec.Cmd) (kill func() error, release func(), err error) {
+	pid := uint32(cmd.Process.Pid)
+	defer resumeProcess(pid)
+
+	kill = cmd.Process.Kill
+	release = func() {}
+
+	job, err := windows.CreateJobObject(nil, nil)
+	if err != nil {
+		return kill, release, fmt.Errorf("create job object: %w", err)
+	}
+	info := windows.JOBOBJECT_EXTENDED_LIMIT_INFORMATION{}
+	info.BasicLimitInformation.LimitFlags = windows.JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE
+	if _, err := windows.SetInformationJobObject(job, windows.JobObjectExtendedLimitInformation,
+		uintptr(unsafe.Pointer(&info)), uint32(unsafe.Sizeof(info))); err != nil {
+		windows.CloseHandle(job)
+		return kill, release, fmt.Errorf("configure job object: %w", err)
+	}
+	proc, err := windows.OpenProcess(windows.PROCESS_SET_QUOTA|windows.PROCESS_TERMINATE, false, pid)
+	if err != nil {
+		windows.CloseHandle(job)
+		return kill, release, fmt.Errorf("open engine process: %w", err)
+	}
+	defer windows.CloseHandle(proc)
+	if err := windows.AssignProcessToJobObject(job, proc); err != nil {
+		windows.CloseHandle(job)
+		return kill, release, fmt.Errorf("assign engine to job: %w", err)
+	}
+
+	kill = func() error { return windows.TerminateJobObject(job, 1) }
+	release = func() { windows.CloseHandle(job) }
+	return kill, release, nil
+}
+
+// resumeProcess resumes every thread of a process started CREATE_SUSPENDED.
+// exec does not hand back the main thread handle, so it is found through the
+// toolhelp snapshot; a suspended new process has exactly one.
+func resumeProcess(pid uint32) {
+	snap, err := windows.CreateToolhelp32Snapshot(windows.TH32CS_SNAPTHREAD, 0)
+	if err != nil {
+		return
+	}
+	defer windows.CloseHandle(snap)
+	var te windows.ThreadEntry32
+	te.Size = uint32(unsafe.Sizeof(te))
+	for err = windows.Thread32First(snap, &te); err == nil; err = windows.Thread32Next(snap, &te) {
+		if te.OwnerProcessID != pid {
+			continue
+		}
+		h, err := windows.OpenThread(windows.THREAD_SUSPEND_RESUME, false, te.ThreadID)
+		if err != nil {
+			continue
+		}
+		windows.ResumeThread(h)
+		windows.CloseHandle(h)
+	}
+}

agent/pkg/enrol/enrol.go

@@ -0,0 +1,113 @@
+// Package enrol links a PC to a shop, using the one-shot code an operator is
+// given.
+//
+// It existed only inside the desktop app, which meant a HEADLESS install - a
+// back-office PC with no window, the configuration the agent binary is for -
+// could not be claimed at all. The only route was hand-editing agent.json,
+// which is exactly the state the desktop's Setup screen was built to end.
+//
+// The endpoint behind this is deliberately unauthenticated: the PC doing it has
+// nobody signed in yet, and requiring a login would mean shipping a password to
+// every shop that installs the software.
+package enrol
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"os"
+	"strings"
+	"time"
+)
+
+// Bootstrap is what the server hands back: which shop this PC is, and the
+// credentials it needs to say so.
+type Bootstrap struct {
+	ClientSlug string `json:"client_slug"`
+	SiteSlug   string `json:"site_slug"`
+	SiteName   string `json:"site_name"`
+	MQTTURL    string `json:"mqtt_url"`
+	MQTTUser   string `json:"mqtt_username"`
+	MQTTPass   string `json:"mqtt_password"`
+	CACert     string `json:"ca_cert,omitempty"`
+	AgentToken string `json:"agent_token"`
+}
+
+// Claim redeems an installation code.
+//
+// The code is read aloud down a phone and photographed off screens, so what is
+// typed here can be as untidy as it needs to be: the server strips spaces,
+// dashes and case at its end. Sending it as typed keeps ONE implementation of
+// that normalisation, on the side that also issued the code - two would
+// eventually disagree and hash to something the redeemer never produces.
+func Claim(ctx context.Context, base, code string) (Bootstrap, error) {
+	var out Bootstrap
+	base = strings.TrimRight(base, "/")
+	if base == "" {
+		return out, fmt.Errorf("no server address configured (set cloud_base or BEHAVISION_CLOUD)")
+	}
+	body, err := json.Marshal(map[string]string{"site_token": code})
+	if err != nil {
+		return out, err
+	}
+	ctx, cancel := context.WithTimeout(ctx, 30*time.Second)
+	defer cancel()
+
+	req, err := http.NewRequestWithContext(ctx, http.MethodPost,
+		base+"/api/agent/enrol", bytes.NewReader(body))
+	if err != nil {
+		return out, err
+	}
+	req.Header.Set("Content-Type", "application/json")
+
+	resp, err := http.DefaultClient.Do(req)
+	if err != nil {
+		return out, fmt.Errorf("could not reach %s: %w", base, err)
+	}
+	defer resp.Body.Close()
+	blob, _ := io.ReadAll(io.LimitReader(resp.Body, 64<<10))
+	if resp.StatusCode != http.StatusOK {
+		// The server answers unknown, expired and already-used identically on
+		// purpose - the difference only helps somebody guessing codes, and the
+		// operator's next step is the same in all three cases. Its own words
+		// are passed through rather than reworded here.
+		var e struct {
+			Message string `json:"message"`
+		}
+		_ = json.Unmarshal(blob, &e)
+		if e.Message != "" {
+			return out, fmt.Errorf("%s", e.Message)
+		}
+		return out, fmt.Errorf("head office: %s", resp.Status)
+	}
+	if err := json.Unmarshal(blob, &out); err != nil {
+		return out, err
+	}
+	if out.SiteSlug == "" || out.MQTTURL == "" {
+		return out, fmt.Errorf("head office returned an incomplete setup")
+	}
+	return out, nil
+}
+
+// SaveCA writes the broker's CA beside the agent config and returns its path.
+//
+// The server hands the CA out at enrolment precisely so it never has to be
+// shipped in an installer - and for a while nothing on the receiving end
+// wrote it anywhere. Every claimed PC then dialled tls://mcp.loyaly.ai:8883
+// with the system trust store, the private CA failed verification, and the
+// agent reported "the broker did not accept this PC" (a TLS failure is
+// indistinguishable from a refusal at that layer). No real site could ever
+// publish a visit. An empty CA returns "" so a deployment on a public
+// certificate keeps working unchanged.
+func SaveCA(pem, path string) (string, error) {
+	if strings.TrimSpace(pem) == "" {
+		return "", nil
+	}
+	if err := os.WriteFile(path, []byte(pem), 0o600); err != nil {
+		return "", fmt.Errorf("write broker CA: %w", err)
+	}
+	return path, nil
+}

agent/pkg/mqtt/client.go

@@ -16,6 +16,8 @@ import (
 	"errors"
 	"fmt"
 	"log"
+	"net"
+	"net/url"
 	neturl "net/url"
 	"os"
 	"strings"
@@ -104,7 +106,13 @@ func NewClient(opts ClientOptions) (*Client, error) {
 
 	tok := c.client.Connect()
 	if !tok.WaitTimeout(20 * time.Second) {
-		return c, fmt.Errorf("mqtt: connect to %s timed out", opts.BrokerURL)
+		// SetConnectRetry means paho retries internally and this token never
+		// completes, so a REFUSED connection and an UNREACHABLE broker both
+		// arrive here as a timeout. They need opposite actions - re-link this
+		// PC, or go and look at the network - and reporting both as "timed
+		// out" sent the diagnosis to the wrong place. Measured: mosquitto
+		// logged "not authorised" while the agent logged a timeout.
+		return c, fmt.Errorf("mqtt: %s", describeStall(opts.BrokerURL))
 	}
 	if err := tok.Error(); err != nil {
 		return c, fmt.Errorf("mqtt: connect to %s: %w", opts.BrokerURL, err)
@@ -112,6 +120,47 @@ func NewClient(opts ClientOptions) (*Client, error) {
 	return c, nil
 }
 
+// describeStall says which of the two failures this is, by asking the one
+// question that separates them: can we open a socket to the broker at all?
+//
+// It cannot name the exact reason - the broker does not tell a rejected client
+// why, and a TLS failure looks the same from here - so it says what is known
+// and what to check, rather than guessing. Being reachable but not accepted is
+// overwhelmingly a credential this PC no longer has, which is what happens when
+// a site is re-provisioned.
+func describeStall(brokerURL string) string {
+	host := brokerHostPort(brokerURL)
+	if host == "" {
+		return fmt.Sprintf("connect to %s timed out", brokerURL)
+	}
+	conn, err := net.DialTimeout("tcp", host, 5*time.Second)
+	if err != nil {
+		return fmt.Sprintf("cannot reach the broker at %s: %v - check the "+
+			"network and that the broker is running", host, err)
+	}
+	_ = conn.Close()
+	return fmt.Sprintf("the broker at %s is reachable but did not accept this "+
+		"PC - usually its credentials are no longer valid; re-link it with "+
+		"`behavision-agent claim <code>`", host)
+}
+
+// brokerHostPort extracts host:port for the reachability probe. Parsed with
+// net/url, never by scanning for the first ":" - an IPv6 literal is bracketed
+// and full of them.
+func brokerHostPort(brokerURL string) string {
+	u, err := url.Parse(brokerURL)
+	if err != nil || u.Host == "" {
+		return ""
+	}
+	if u.Port() != "" {
+		return u.Host
+	}
+	if strings.HasPrefix(brokerURL, "tls://") || strings.HasPrefix(brokerURL, "ssl://") {
+		return net.JoinHostPort(u.Hostname(), "8883")
+	}
+	return net.JoinHostPort(u.Hostname(), "1883")
+}
+
 // Publish sends one message at QoS 1 and waits for the broker's PUBACK.
 //
 // QoS 1, not 0 or 2. At QoS 0 the broker never confirms, so the pump would ack

agent/pkg/mqtt/client_test.go

@@ -1,6 +1,7 @@
 package mqtt
 
 import (
+	"net"
 	"strings"
 	"testing"
 )
@@ -102,3 +103,66 @@ func TestPublishOnADeadClientErrorsRatherThanPanics(t *testing.T) {
 func writeFile(path, content string) error {
 	return osWriteFile(path, []byte(content), 0o600)
 }
+
+// "The broker refused this PC" and "the broker is not there" need opposite
+// actions - re-link this PC, or go and look at the network - and paho's
+// connect-retry makes both arrive as a timeout. Measured on a real broker:
+// mosquitto logged "not authorised" while the agent logged a timeout, which
+// sent the diagnosis to the wrong place.
+func TestARefusedBrokerIsNotDescribedAsUnreachable(t *testing.T) {
+	// A listener that accepts TCP and then says nothing is exactly what a
+	// broker rejecting a client looks like from out here.
+	ln, err := net.Listen("tcp", "127.0.0.1:0")
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer ln.Close()
+	go func() {
+		for {
+			c, err := ln.Accept()
+			if err != nil {
+				return
+			}
+			_ = c
+		}
+	}()
+
+	got := describeStall("tcp://" + ln.Addr().String())
+	if !strings.Contains(got, "reachable but did not accept") {
+		t.Fatalf("a reachable broker was described as unreachable: %s", got)
+	}
+	if !strings.Contains(got, "claim") {
+		t.Errorf("the message does not say what to do about it: %s", got)
+	}
+}
+
+func TestAnAbsentBrokerIsDescribedAsUnreachable(t *testing.T) {
+	// Bound and immediately closed, so the port is certainly nobody's.
+	ln, err := net.Listen("tcp", "127.0.0.1:0")
+	if err != nil {
+		t.Fatal(err)
+	}
+	addr := ln.Addr().String()
+	ln.Close()
+
+	got := describeStall("tcp://" + addr)
+	if !strings.Contains(got, "cannot reach the broker") {
+		t.Fatalf("an absent broker was not described as unreachable: %s", got)
+	}
+}
+
+// An IPv6 literal is bracketed and full of colons, so scanning for the first
+// one gives "[". The same bug this package already fixed once for broker URLs.
+func TestTheProbeAddressHandlesIPv6AndDefaultPorts(t *testing.T) {
+	for _, tc := range []struct{ in, want string }{
+		{"tcp://127.0.0.1:51883", "127.0.0.1:51883"},
+		{"tcp://[::1]:1883", "[::1]:1883"},
+		{"tcp://broker.example", "broker.example:1883"},
+		{"tls://broker.example", "broker.example:8883"},
+		{"tls://[2001:db8::1]:8884", "[2001:db8::1]:8884"},
+	} {
+		if got := brokerHostPort(tc.in); got != tc.want {
+			t.Errorf("brokerHostPort(%q) = %q, want %q", tc.in, got, tc.want)
+		}
+	}
+}

agent/pkg/paths/paths.go

@@ -57,8 +57,11 @@ func InstallRoot() string {
 }
 
 func AgentConfig() string { return filepath.Join(StateRoot(), "agent.json") }
-func SpoolDir() string    { return filepath.Join(StateRoot(), "spool") }
+
-func EngineLog() string   { return filepath.Join(StateRoot(), "engine.log") }
+// BrokerCA is the broker's CA certificate, written at enrolment.
+func BrokerCA() string  { return filepath.Join(StateRoot(), "broker-ca.crt") }
+func SpoolDir() string  { return filepath.Join(StateRoot(), "spool") }
+func EngineLog() string { return filepath.Join(StateRoot(), "engine.log") }
 
 // APICredentials is the file the engine writes when it generates its own
 // Basic credentials. The agent reads it rather than storing a second copy,
@@ -67,6 +70,12 @@ func APICredentials() string {
 	return filepath.Join(StateRoot(), "data", "api_credentials.txt")
 }
 
+// CamerasFile is the engine's own camera store. The agent never edits it -
+// cameras go through the engine's API so passwords are sealed - but setup
+// removes it when a PC joins a shop, because head office is the source of
+// truth from then on.
+func CamerasFile() string { return filepath.Join(StateRoot(), "data", "cameras.json") }
+
 // EnsureState creates the writable tree. Called before anything opens a file
 // under it, so a first run on a fresh machine does not fail on a missing dir.
 func EnsureState() error {

behavision/__main__.py

@@ -21,6 +21,17 @@ def cmd_run(args: argparse.Namespace) -> int:
 
     cfg = load_config(args.config)
     setup_logging(cfg.app.log_level, cfg.app.data_dir)
+    if cfg.app.detect_threads > 0:
+        # OpenCV sizes its pool for one big job on an idle machine. This is a
+        # small job repeated forever on a machine also running the recogniser,
+        # the tracker and possibly three other cameras, so the default costs
+        # twice the CPU for no useful latency. Measured: 31 ms CPU/frame at the
+        # default against 15 ms at one thread, for 6 ms more wall time against
+        # a 66 ms budget.
+        import cv2
+        cv2.setNumThreads(cfg.app.detect_threads)
+        log.info("detection threads: %d (OpenCV default was %d)",
+                 cfg.app.detect_threads, cv2.getNumThreads())
     missing = setup_models(cfg.app.models_dir)
     if missing:
         log.error("required models missing: %s", ", ".join(missing))

behavision/api.py

@@ -6,6 +6,7 @@ models finish loading without a single unguarded None dereference.
 from __future__ import annotations
 
 import asyncio
+import time
 import logging
 import secrets
 from pathlib import Path
@@ -111,6 +112,35 @@ def _auth_dependencies(api_cfg: ApiSection) -> list:
     return [Depends(check)]
 
 
+def _reencode(jpeg: bytes, width: int, quality: int) -> "bytes | None":
+    """Decode, scale and re-encode one frame. None on any failure.
+
+    None rather than an exception on purpose: the caller falls back to the
+    original frame, so a re-encode that fails costs bandwidth rather than the
+    picture. A live view that goes blank because a resize failed is a worse
+    outcome than one that is briefly larger than asked for.
+    """
+    try:
+        import cv2
+        import numpy as np
+
+        img = cv2.imdecode(np.frombuffer(jpeg, np.uint8), cv2.IMREAD_COLOR)
+        if img is None:
+            return None
+        if 0 < width < img.shape[1]:
+            # Only ever DOWN. Upscaling a frame to a requested width would send
+            # more bytes than the original for no more detail.
+            scale = width / img.shape[1]
+            img = cv2.resize(img, (width, max(1, int(img.shape[0] * scale))),
+                             interpolation=cv2.INTER_AREA)
+        q = quality if 1 <= quality <= 100 else 75
+        ok, buf = cv2.imencode(".jpg", img, [int(cv2.IMWRITE_JPEG_QUALITY), q])
+        return buf.tobytes() if ok else None
+    except Exception:
+        log.debug("frame re-encode failed", exc_info=True)
+        return None
+
+
 def create_app(engine: Engine) -> FastAPI:
     app = FastAPI(title="Behavision", version="1.0.0",
                   dependencies=_auth_dependencies(engine.cfg.api))
@@ -125,11 +155,25 @@ def create_app(engine: Engine) -> FastAPI:
     def dashboard() -> str:
         return (_STATIC / "dashboard.html").read_text(encoding="utf-8")
 
+    @app.get("/static/favicon.png")
+    def favicon() -> Response:
+        # The one static asset besides the page itself. Served explicitly
+        # rather than mounting the directory: nothing else in there is meant
+        # to be reachable, and a mount would make that a matter of what lands
+        # in the folder.
+        return Response((_STATIC / "favicon.png").read_bytes(), media_type="image/png",
+                        headers={"cache-control": "public, max-age=86400"})
+
     @app.get("/api/health")
     def health() -> dict:
         from .paths import describe
+        # A gallery the running encoder cannot read is the failure most
+        # worth catching from outside: the process is healthy, the cameras
+        # are up, and the shop recognises nobody it already knows.
+        stranded = engine.gallery.health["stranded"]
         return {"status": "ok" if engine.started_at else "starting",
                 "recognition_model": engine.encoder.model_name,
+                "gallery_unreadable_embeddings": stranded,
                 # "where is my database" must be answerable from the API: the
                 # tray, the installer and support all need it, and installed
                 # it is not next to the code.
@@ -293,6 +337,17 @@ def create_app(engine: Engine) -> FastAPI:
             worker.commission.cancel()
         return {"cancelled": camera_id}
 
+    @app.get("/api/cameras/discover")
+    def discover_cameras() -> dict:
+        """Cameras on this PC's network, for the add-camera form to pick from.
+
+        A sync def so FastAPI runs it in the threadpool: it holds a socket
+        open for a couple of seconds and sweeps a /24, and the event loop
+        must keep serving the live picture meanwhile.
+        """
+        from .discover import discover
+        return discover()
+
     @app.post("/api/cameras/test")
     def test_camera(payload: CameraPayload) -> dict:
         """Try a camera WITHOUT saving it - the UI's Test button.
@@ -313,10 +368,23 @@ def create_app(engine: Engine) -> FastAPI:
         return probe_source(source, cam.max_width)
 
     @app.get("/api/cameras/{camera_id}/frame.jpg")
-    def frame(camera_id: str) -> Response:
+    def frame(camera_id: str, width: int = 0, quality: int = 0) -> Response:
+        """The latest frame, optionally re-encoded smaller.
+
+        `width`/`quality` exist for the live relay, which sends several frames
+        a second up a shop's uplink and cannot afford the full-size picture the
+        dashboard uses. The re-encode happens here rather than in the agent
+        because this process already has OpenCV open and the frame decoded;
+        shipping a scaler into the agent would be the same work done twice.
+
+        Done on demand, not on every frame: a camera nobody is watching must
+        not pay for a second encode it will never use.
+        """
         jpeg = worker_or_404(camera_id).latest_jpeg()
         if jpeg is None:
             raise HTTPException(503, "no frame yet")
+        if width > 0 or quality > 0:
+            jpeg = _reencode(jpeg, width, quality) or jpeg
         return Response(jpeg, media_type="image/jpeg")
 
     @app.get("/api/cameras/{camera_id}/stream.mjpeg")
@@ -328,11 +396,23 @@ def create_app(engine: Engine) -> FastAPI:
             # Stop when the camera is deleted or its worker dies - otherwise a
             # removed camera leaves this generator running for the life of the
             # process, holding a reference to a worker nothing else can see.
+            # Driven by the camera, not a timer: a frame goes out when the
+            # capture thread has one newer than the last one sent, so nothing
+            # is sent twice and nothing waits on the recognition pipeline.
+            # Capped at 15 fps - the office cameras' own rate - so a viewer
+            # never costs more encodes than the camera produces pictures.
+            last_ts, min_gap, sent_at = 0.0, 1.0 / 15, 0.0
             while engine.workers.get(camera_id) is worker and worker.is_alive():
-                jpeg = worker.latest_jpeg()
+                now = time.time()
-                if jpeg is not None:
+                if now - sent_at < min_gap:
-                    yield boundary + jpeg + b"\r\n"
+                    await asyncio.sleep(min_gap - (now - sent_at))
-                await asyncio.sleep(0.1)  # ~10 fps to the browser
+                    continue
+                jpeg, ts = worker.latest_jpeg_since(last_ts)
+                if jpeg is None:
+                    await asyncio.sleep(0.02)
+                    continue
+                last_ts, sent_at = ts, time.time()
+                yield boundary + jpeg + b"\r\n"
 
         return StreamingResponse(
             generate(),

behavision/capture.py

@@ -17,13 +17,57 @@ import numpy as np
 
 log = logging.getLogger(__name__)
 
-# Force TCP transport and a 5s socket timeout for RTSP before OpenCV loads
+# Set before OpenCV loads ffmpeg, which reads this once.
-# ffmpeg. UDP is the default and silently drops frames on lossy Wi-Fi.
+#
+# rtsp_transport=tcp: UDP is the default and silently drops frames on lossy
+# Wi-Fi.
+#
+# The timeout here is NOT what bounds a dead camera, and the comment that
+# once said it did was wrong. Measured against OpenCV 4.11 / FFmpeg 7.1 on a
+# socket that accepts the connection and then says nothing:
+#
+#     stimeout;5000000   -> 30.0s      timeout;5000000 -> 30.0s
+#     stimeout;2000000   -> 30.5s      timeout;2000000 -> 30.4s
+#     no timeout option at all         -> 30.3s
+#
+# Identical with the option absent, so it is not being honoured under either
+# name through this path. `stimeout` was renamed `timeout` in FFmpeg 5.0, and
+# neither reaches the RTSP protocol here. What actually bounds it is
+# OpenCV's own interrupt callback (30s for open, 30s for read), which is a
+# compile-time constant we do not control.
+#
+# Both names are still set, because on a build where they DO take effect the
+# shorter bound is what we want and an unrecognised option is ignored. But
+# nothing may depend on it: a wrong address is caught by _tcp_reachable
+# below, in code we own, in under a second.
+#
+# fflags=nobuffer and flags=low_delay: without them ffmpeg's RTSP demuxer
+# holds a comfortable queue of frames before handing over the first, which
+# on a live feed is half a second to two seconds of latency that no amount of
+# work downstream can recover - the frame is already old when we get it. A
+# recorder wants that buffer; a live view does not. max_delay caps the
+# reorder wait for the same reason.
 os.environ.setdefault(
-    "OPENCV_FFMPEG_CAPTURE_OPTIONS", "rtsp_transport;tcp|stimeout;5000000"
+    "OPENCV_FFMPEG_CAPTURE_OPTIONS",
+    "rtsp_transport;tcp|stimeout;5000000|timeout;5000000"
+    "|fflags;nobuffer|flags;low_delay|max_delay;200000",
 )
 
 
+# A stream can stay open and stop delivering. OpenCV breaks a blocked read
+# after 30s and we reconnect, but for those 30s `connected` is True and the
+# camera is dead — and a stream that trickles a frame every 20s never trips
+# that timeout at all, so it never reconnects and never recovers either.
+#
+# 10s is not a preference. The tracker gives up on a face after `max_misses`
+# (25 frames, ~1.7s at 15 fps), so by 10s every track is long gone and 150
+# frames are missing: whatever this is, it is not something recognition can
+# work with. Reported separately from `connected` because the two need
+# opposite actions — one says check the network, the other says the camera
+# is answering but sending nothing.
+STALL_AFTER_S = 10.0
+
+
 def _tcp_reachable(source: "str | int", timeout: float
                    ) -> "tuple[bool, str]":
     """Cheap pre-flight for an rtsp:// URL. Non-URL sources pass through."""
@@ -47,6 +91,23 @@ def _tcp_reachable(source: "str | int", timeout: float
         return False, f"cannot reach {parsed.hostname}:{port} - {exc.strerror or exc}"
 
 
+def _fourcc(cap) -> str:
+    """The stream's codec as a four-character code, or "" if unknown.
+
+    FFmpeg reports H.265 as "hevc" and H.264 as "h264"/"avc1" depending on the
+    container. Returned as-is rather than mapped to a friendly name: the raw
+    value is what somebody searching their camera's manual will match.
+    """
+    try:
+        raw = int(cap.get(cv2.CAP_PROP_FOURCC))
+    except Exception:
+        return ""
+    if raw <= 0:
+        return ""
+    code = "".join(chr((raw >> (8 * i)) & 0xFF) for i in range(4))
+    return code.strip().strip("\x00")
+
+
 def probe_source(source: "str | int", max_width: int = 1280,
                  timeout: float = 12.0, connect_timeout: float = 3.0) -> dict:
     """Open a candidate camera, grab one frame, and let go.
@@ -97,6 +158,17 @@ def probe_source(source: "str | int", max_width: int = 1280,
         return {
             "ok": True, "width": int(width), "height": int(height),
             "downscaled_to": int(preview.shape[1]) if preview is not frame else None,
+            "fps": round(cap.get(cv2.CAP_PROP_FPS) or 0, 1),
+            # The codec decides whether head office can ever show TRUE live
+            # video from this camera. A browser plays H.264 everywhere; H.265
+            # only on some platforms, so a passthrough relay cannot rely on it
+            # and the picture has to be re-encoded frame by frame instead.
+            # Reported here because it is a property of the camera's settings
+            # that an installer can usually change, and because otherwise the
+            # only way to learn it is to read RTSP by hand — which is how this
+            # was found: a camera whose paths end in ".264" was emitting H.265
+            # on both streams.
+            "codec": _fourcc(cap),
             "snapshot": (base64.b64encode(buf.tobytes()).decode("ascii")
                          if ok else None),
         }
@@ -131,6 +203,10 @@ class VideoSource(threading.Thread):
         self.frames_total = 0
         self.reconnects = 0
         self._ever_connected = False
+        # Why the last open failed, in the words an installer can act on.
+        # Without it a camera that never connects reports only `connected:
+        # false`, which cannot distinguish a wrong IP from a wrong password.
+        self.last_error = ""
 
     # -- public ---------------------------------------------------------
     def latest(self) -> "tuple[Optional[np.ndarray], float]":
@@ -161,11 +237,23 @@ class VideoSource(threading.Thread):
     def stop(self) -> None:
         self._stopping.set()
 
+    def stalled(self) -> bool:
+        """Open, but not delivering. See STALL_AFTER_S."""
+        if not self.connected or not self._frame_ts:
+            return False
+        return (time.time() - self._frame_ts) > STALL_AFTER_S
+
     def stats(self) -> dict:
         return {
             "camera_id": self.camera_id,
             "url": self._display_url,
             "connected": self.connected,
+            # Connected AND delivering. `connected` alone stays true through
+            # a stall, so it is the wrong thing for a dashboard to colour a
+            # camera green on.
+            "streaming": self.connected and not self.stalled(),
+            "stalled": self.stalled(),
+            "last_error": self.last_error,
             "frames_total": self.frames_total,
             "reconnects": self.reconnects,
             "last_frame_age_s": round(time.time() - self._frame_ts, 1)
@@ -222,6 +310,19 @@ class VideoSource(threading.Thread):
         log.info("[%s] capture stopped", self.camera_id)
 
     def _open(self) -> Optional[cv2.VideoCapture]:
+        # Pre-flight the socket, exactly as probe_source does. Without it a
+        # camera that is off, moved or mistyped costs 30s per attempt inside
+        # the VideoCapture constructor (measured; it is OpenCV's interrupt
+        # timeout, not ours to shorten) — and the constructor is not
+        # interruptible, so stop() cannot cut it short and a removed camera
+        # leaves a daemon thread holding a socket for half a minute. A
+        # refused or unroutable address answers in well under a second, which
+        # is also what lets the backoff below mean what it says.
+        reachable, why = _tcp_reachable(self._source, 2.0)
+        if not reachable:
+            log.debug("[%s] %s", self.camera_id, why)
+            self.last_error = why
+            return None
         try:
             if isinstance(self._source, int):
                 cap = cv2.VideoCapture(self._source)
@@ -230,8 +331,12 @@ class VideoSource(threading.Thread):
             cap.set(cv2.CAP_PROP_BUFFERSIZE, 1)
             if not cap.isOpened():
                 cap.release()
+                self.last_error = ("reachable, but the stream would not open "
+                                   "- check the path and credentials")
                 return None
+            self.last_error = ""
             return cap
         except cv2.error:
             log.exception("[%s] VideoCapture error", self.camera_id)
+            self.last_error = "VideoCapture error - see the engine log"
             return None

behavision/config.py

@@ -132,6 +132,29 @@ class AppSection(BaseModel):
     # on changes what the system is under GDPR and India's DPDP, so it has to
     # be a decision somebody makes rather than one they inherit.
     store_faces: bool = False
+    # How many threads OpenCV may use for detection. Measured on the office
+    # camera (800x448 sub-stream): the default of 8 costs 31 ms of CPU per
+    # frame for 8.9 ms of wall time, while ONE thread costs 15.3 ms of CPU for
+    # 15.3 ms of wall - half the CPU for 6 ms more latency, against a 66 ms
+    # frame budget at 15 fps. The default is wrong here because OpenCV sizes it
+    # for one big job on an idle machine, and this is a small job repeated
+    # forever on a machine also running the recogniser, the tracker and three
+    # other cameras. 0 leaves OpenCV's own default alone.
+    detect_threads: int = 1
+    # Skip detection on frames where nothing has changed and nothing is being
+    # tracked. A shop is empty most of the day and a frame of an empty room
+    # costs exactly as much to search as a busy one. See CameraWorker.run for
+    # why this cannot lose a face.
+    motion_gate: bool = True
+    # Mean absolute difference, 0-255, over a 160x90 greyscale thumbnail. 1.0
+    # is well below the noise floor of a real camera - measured on this one,
+    # an empty room varies by ~0.3 between frames - so it triggers on movement
+    # rather than on sensor noise, and anything ambiguous detects.
+    motion_threshold: float = 1.0
+    # Detect at least this often regardless of the gate, so a change the
+    # thumbnail cannot see - someone entering at the far edge, a slow lean into
+    # frame - is still found within a second.
+    motion_max_skip: int = 12
 
 
 class ApiSection(BaseModel):

behavision/discover.py

@@ -0,0 +1,206 @@
+"""Find the cameras on the shop's network, so nobody has to type an address.
+
+The add-camera form asked for an IP address, and a shop owner does not know
+their camera's IP address. It is on a sticker under the camera, if at all, or
+inside the camera's own app under a menu called something different for every
+make. That one field is where onboarding stopped for anyone who was not an
+installer.
+
+Two probes, merged:
+
+- **WS-Discovery** (ONVIF's discovery protocol): one multicast to
+  239.255.255.250:3702 and every ONVIF camera on the LAN answers with its
+  address and, usually, its make and model. Cheap, fast, and names the device
+  - but only cameras that speak ONVIF answer, and some cheap ones do not.
+- **A TCP sweep of port 554** across the local /24: anything listening on the
+  RTSP port is very probably a camera or a recorder. Names nothing, misses
+  nothing that streams.
+
+A host found by either is a candidate; one found by both is a camera with a
+name. The result is a list to pick from, not a decision: the person still
+supplies the password, and Test still proves the stream opens.
+
+Stdlib only. This runs inside the engine, which ships as a small wheel, and a
+network-scanning dependency would be a large thing to add for two sockets.
+"""
+from __future__ import annotations
+
+import ipaddress
+import re
+import socket
+import uuid
+from concurrent.futures import ThreadPoolExecutor
+from dataclasses import dataclass, field, asdict
+from typing import Iterable
+
+# ONVIF WS-Discovery probe. The MessageID must be unique per probe; devices
+# ignore a repeat.
+_PROBE = (
+    '<?xml version="1.0" encoding="UTF-8"?>'
+    '<e:Envelope xmlns:e="http://www.w3.org/2003/05/soap-envelope" '
+    'xmlns:w="http://schemas.xmlsoap.org/ws/2004/08/addressing" '
+    'xmlns:d="http://schemas.xmlsoap.org/ws/2005/04/discovery" '
+    'xmlns:dn="http://www.onvif.org/ver10/network/wsdl">'
+    '<e:Header><w:MessageID>uuid:{mid}</w:MessageID>'
+    '<w:To e:mustUnderstand="true">urn:schemas-xmlsoap-org:ws:2005:04:discovery</w:To>'
+    '<w:Action e:mustUnderstand="true">http://schemas.xmlsoap.org/ws/2005/04/discovery/Probe</w:Action>'
+    '</e:Header><e:Body><d:Probe><d:Types>dn:NetworkVideoTransmitter</d:Types></d:Probe></e:Body>'
+    '</e:Envelope>'
+)
+_MCAST = ("239.255.255.250", 3702)
+
+# Makes we can name from an ONVIF scope or hostname, mapped to the ids the
+# camera-make picker uses so the form can preselect the stream path.
+_MAKES = (
+    ("hikvision", "hikvision"), ("hik", "hikvision"), ("dahua", "dahua"),
+    ("cp plus", "cpplus"), ("cpplus", "cpplus"), ("cp-plus", "cpplus"),
+    ("uniview", "uniview"), ("unv", "uniview"), ("tapo", "tplink"),
+    ("tp-link", "tplink"), ("reolink", "reolink"), ("amcrest", "amcrest"),
+    ("axis", "axis"),
+)
+
+
+@dataclass
+class Found:
+    host: str
+    rtsp: bool = False            # port 554 answered
+    onvif: bool = False           # answered WS-Discovery
+    name: str = ""                # from ONVIF scopes, e.g. "Hikvision DS-2CD2043"
+    make: str = ""                # picker id, when it can be guessed
+    onvif_url: str = ""
+    sources: list[str] = field(default_factory=list)
+
+
+def local_networks() -> list[ipaddress.IPv4Network]:
+    """The /24s this machine sits on, best effort and without dependencies.
+
+    Interface masks are not portable in the stdlib, so this assumes /24 - the
+    shape of nearly every shop's router - for each local IPv4 address it can
+    find. A bigger network would need a scan anyway that this should not run
+    unasked.
+    """
+    addrs: set[str] = set()
+    try:
+        # The address the OS would use to reach the internet: the LAN we care about.
+        s = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+        s.settimeout(0.5)
+        s.connect(("8.8.8.8", 80))
+        addrs.add(s.getsockname()[0])
+        s.close()
+    except OSError:
+        pass
+    try:
+        for a in socket.gethostbyname_ex(socket.gethostname())[2]:
+            addrs.add(a)
+    except OSError:
+        pass
+    nets = []
+    for a in addrs:
+        try:
+            ip = ipaddress.IPv4Address(a)
+        except ValueError:
+            continue
+        if ip.is_loopback or ip.is_link_local:
+            continue
+        nets.append(ipaddress.IPv4Network(f"{a}/24", strict=False))
+    return sorted(set(nets), key=str)
+
+
+def ws_discover(timeout: float = 2.5) -> list[Found]:
+    """One ONVIF probe, every answer within `timeout` seconds."""
+    out: dict[str, Found] = {}
+    try:
+        sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM, socket.IPPROTO_UDP)
+        sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+        sock.setsockopt(socket.IPPROTO_IP, socket.IP_MULTICAST_TTL, 2)
+        sock.settimeout(timeout)
+        sock.sendto(_PROBE.format(mid=uuid.uuid4()).encode(), _MCAST)
+    except OSError:
+        return []
+    import time
+    deadline = time.monotonic() + timeout
+    while time.monotonic() < deadline:
+        try:
+            data, (host, _) = sock.recvfrom(65535)
+        except socket.timeout:
+            break
+        except OSError:
+            break
+        f = parse_probe_match(data.decode("utf-8", "replace"), host)
+        if f:
+            out[f.host] = f
+    sock.close()
+    return list(out.values())
+
+
+_XADDR = re.compile(r"<[^>]*XAddrs[^>]*>([^<]+)<")
+_SCOPES = re.compile(r"<[^>]*Scopes[^>]*>([^<]+)<")
+
+
+def parse_probe_match(xml: str, host: str) -> Found | None:
+    """Pull the address and the human-readable scopes out of a ProbeMatch.
+
+    A regex rather than an XML parser on purpose: cameras emit every namespace
+    prefix imaginable and some emit XML that is not quite well-formed, and the
+    two fields wanted are flat text.
+    """
+    xaddrs = _XADDR.search(xml)
+    scopes = _SCOPES.search(xml)
+    if not xaddrs and not scopes:
+        return None
+    url = xaddrs.group(1).split()[0] if xaddrs else ""
+    # Prefer the host from the XAddrs URL: a device with several interfaces
+    # answers from the one it heard us on, which is the one we can reach.
+    m = re.match(r"https?://([^/:]+)", url)
+    ip = m.group(1) if m else host
+    f = Found(host=ip, onvif=True, onvif_url=url, sources=["onvif"])
+    if scopes:
+        words = []
+        for s in scopes.group(1).split():
+            if "/name/" in s or "/hardware/" in s:
+                from urllib.parse import unquote
+                words.append(unquote(s.rsplit("/", 1)[-1]))
+        f.name = " ".join(dict.fromkeys(words))  # dedupe, keep order
+    f.make = guess_make(f.name)
+    return f
+
+
+def guess_make(text: str) -> str:
+    low = text.lower()
+    for needle, make in _MAKES:
+        if needle in low:
+            return make
+    return ""
+
+
+def rtsp_sweep(nets: Iterable[ipaddress.IPv4Network], timeout: float = 0.5,
+               workers: int = 128) -> list[str]:
+    """Every host in `nets` with port 554 open. ~254 hosts in about a second."""
+    def probe(ip: str) -> str | None:
+        s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+        s.settimeout(timeout)
+        try:
+            return ip if s.connect_ex((ip, 554)) == 0 else None
+        except OSError:
+            return None
+        finally:
+            s.close()
+    hosts = [str(h) for n in nets for h in n.hosts()]
+    with ThreadPoolExecutor(max_workers=workers) as ex:
+        return [ip for ip in ex.map(probe, hosts) if ip]
+
+
+def discover(timeout: float = 2.5) -> dict:
+    """Both probes, merged, as the API returns it."""
+    nets = local_networks()
+    found: dict[str, Found] = {f.host: f for f in ws_discover(timeout)}
+    for ip in rtsp_sweep(nets):
+        f = found.setdefault(ip, Found(host=ip))
+        f.rtsp = True
+        f.sources.append("rtsp")
+    cams = sorted(found.values(), key=lambda f: (not (f.rtsp and f.onvif), not f.rtsp,
+                                                 ipaddress.IPv4Address(f.host)))
+    return {
+        "networks": [str(n) for n in nets],
+        "cameras": [asdict(c) for c in cams],
+    }

behavision/engine.py

@@ -18,6 +18,7 @@ import numpy as np
 
 from .attributes import AttributeEstimator, aggregate as aggregate_attrs
 from .cameras import CameraStore
+from . import capture
 from .capture import VideoSource
 from .faces import FaceOutbox
 from .commission import CommissionRun
@@ -162,10 +163,20 @@ class CameraWorker(threading.Thread):
         # every test using a stubbed worker passed.
         self._stopping = threading.Event()
         self._lock = threading.Lock()
-        self._annotated_jpeg: Optional[bytes] = None
+        # What the live view draws over the freshest frame: the boxes from
+        # the most recent processed frame, and when they were computed. NOT a
+        # pre-rendered JPEG - see latest_jpeg for why.
+        self._overlay: "list[tuple[tuple[int, int, int, int], tuple[int, int, int], str]]" = []
+        self._overlay_ts = 0.0
         self._last_frame_ts = 0.0
         self._was_connected = False
+        self._was_stalled = False
         self.frames_processed = 0
+        # Motion gate state: a 160x90 greyscale thumbnail of the last frame we
+        # actually searched, and how many frames we have skipped since.
+        self._motion_prev = None
+        self._motion_skipped = 0
+        self.frames_skipped = 0
         self.faces_seen = 0
         self.pipeline = PipelineStats()
         # One outbox per worker, all writing into the same directory. Files are
@@ -187,13 +198,52 @@ class CameraWorker(threading.Thread):
         self.source.stop()
 
     def latest_jpeg(self) -> Optional[bytes]:
+        jpeg, _ = self.latest_jpeg_since(0.0)
+        return jpeg
+
+    def latest_jpeg_since(self, known_ts: float) -> "tuple[Optional[bytes], float]":
+        """The freshest captured frame with the latest boxes drawn on it, or
+        (None, known_ts) if the camera has produced nothing newer.
+
+        The live picture is deliberately NOT the frame the pipeline last
+        finished with. That version advanced only when detection, tracking and
+        identification had all completed on a frame - a few times a second on a
+        modest shop PC - and every picture it showed was already as old as that
+        processing. It looked like lag because it was lag. Here the picture runs
+        at the camera's rate off the capture thread's latest frame, and the
+        boxes - which genuinely can only update at pipeline rate - are drawn
+        over it from the last processed frame. Boxes may trail a fast walker by
+        one pipeline period; the picture never does.
+
+        Encoded on demand, per request, so a camera nobody is watching pays for
+        no JPEG at all. The old path encoded every processed frame whether or
+        not a viewer existed - CPU spent on precisely the machine short of it.
+        """
+        frame, ts = self.source.latest_since(known_ts)
+        if frame is None:
+            return None, known_ts
         with self._lock:
-            return self._annotated_jpeg
+            overlay, overlay_ts = list(self._overlay), self._overlay_ts
+        # A stalled pipeline must not leave a box floating over an empty spot.
+        # Older than a second and the person has walked out from under it.
+        draw = overlay if (time.time() - overlay_ts) < 1.0 else []
+        if draw:
+            frame = frame.copy()
+            for (x1, y1, x2, y2), color, text in draw:
+                cv2.rectangle(frame, (x1, y1), (x2, y2), color, 2)
+                if text:
+                    cv2.putText(frame, text, (x1, max(20, y1 - 8)),
+                                cv2.FONT_HERSHEY_SIMPLEX, 0.55, color, 2)
+        ok, buf = cv2.imencode(".jpg", frame, [int(cv2.IMWRITE_JPEG_QUALITY), 80])
+        if not ok:
+            return None, known_ts
+        return buf.tobytes(), ts
 
     def stats(self) -> dict:
         return {
             **self.source.stats(),
             "frames_processed": self.frames_processed,
+            "frames_skipped": self.frames_skipped,
             "faces_seen": self.faces_seen,
             "active_tracks": len(self.tracker.tracks),
             "pipeline": self.pipeline.snapshot(self.rcfg.min_enroll_quality),
@@ -202,6 +252,43 @@ class CameraWorker(threading.Thread):
                       "enroll_threshold": self.rcfg.enroll_threshold},
         }
 
+    def _nothing_moved(self, frame) -> bool:
+        """True when this frame is close enough to the last searched one that
+        searching it again would find the same nothing.
+
+        It cannot lose a face, and that property is what makes it acceptable
+        rather than merely cheap. Three guards, in order:
+
+          * the caller only asks while NO track is open, so a person already
+            being followed is never affected by it;
+          * `motion_max_skip` forces a real detection about once a second
+            whatever the thumbnail says, which covers a change too small or too
+            gradual for it - someone easing into frame at the far edge;
+          * the threshold sits well above measured sensor noise and well below
+            a person, and anything ambiguous falls through to detection. When
+            in doubt it looks.
+
+        Cost is 0.1 ms against detection's 15 ms, so an empty shop stops paying
+        for a search of an empty room ~90 times a second.
+        """
+        import cv2 as _cv2
+        small = _cv2.resize(_cv2.cvtColor(frame, _cv2.COLOR_BGR2GRAY), (160, 90),
+                            interpolation=_cv2.INTER_AREA)
+        prev, self._motion_prev = self._motion_prev, small
+        if prev is None:
+            return False
+        if self._motion_skipped >= self.cfg.app.motion_max_skip:
+            self._motion_skipped = 0
+            return False
+        if float(_cv2.absdiff(small, prev).mean()) >= self.cfg.app.motion_threshold:
+            self._motion_skipped = 0
+            # Keep the thumbnail we just searched against, not this one, so a
+            # slow drift cannot creep past the threshold one frame at a time.
+            return False
+        self._motion_prev = prev
+        self._motion_skipped += 1
+        return True
+
     # -- thread ---------------------------------------------------------
     def run(self) -> None:
         tcfg = self.cfg.tracking
@@ -214,6 +301,15 @@ class CameraWorker(threading.Thread):
                     continue
                 self._last_frame_ts = ts
 
+                # An empty room costs exactly as much to search as a busy one,
+                # and a shop is empty most of the day. Only ever while nothing
+                # is being tracked - see _nothing_moved.
+                if (self.cfg.app.motion_gate and not self.tracker.tracks
+                        and self._nothing_moved(frame)):
+                    self.frames_skipped += 1
+                    self._remember_tracks([])
+                    continue
+
                 detections = self.detector.detect(frame)
                 for det in detections:
                     det.quality = face_quality(frame, det.box, det.kps)
@@ -236,7 +332,7 @@ class CameraWorker(threading.Thread):
                 for track in ended:
                     self._finish_track(track, ts)
 
-                self._publish_annotated(frame, active)
+                self._remember_tracks(active)
                 self.frames_processed += 1
             except Exception:
                 log.exception("[%s] frame processing failed", self.cam_cfg.id)
@@ -252,6 +348,20 @@ class CameraWorker(threading.Thread):
                 type="camera.up" if connected else "camera.down",
                 camera_id=self.cam_cfg.id))
 
+        # A stall is not a disconnect and must not be reported as one: the
+        # socket is fine, the camera is answering, and nothing is arriving.
+        # Logged on the transition only — a per-frame warning would bury the
+        # one line that matters under thousands of copies of itself.
+        stalled = self.source.stalled()
+        if stalled != self._was_stalled:
+            self._was_stalled = stalled
+            if stalled:
+                log.warning("[%s] connected but no frame for over %.0fs - the "
+                            "camera is answering and sending nothing",
+                            self.cam_cfg.id, capture.STALL_AFTER_S)
+            else:
+                log.info("[%s] frames resumed", self.cam_cfg.id)
+
     def _finish_track(self, track: Track, ts: float) -> None:
         """Record what became of a track, once, as it ends.
 
@@ -426,12 +536,14 @@ class CameraWorker(threading.Thread):
                                            track.quality, rcfg=self.rcfg):
             track.reinforcements += 1
 
-    def _publish_annotated(self, frame: np.ndarray, tracks: "list[Track]") -> None:
+    def _remember_tracks(self, tracks: "list[Track]") -> None:
-        canvas = frame.copy()
+        """Record what to draw. Cheap: a handful of tuples under the lock,
+        no frame copy and no encode. The encode happens in latest_jpeg_since,
+        only when somebody is looking."""
+        overlay = []
         for t in tracks:
             if t.misses > 0:
                 continue  # only draw tracks matched in this frame
-            x1, y1, x2, y2 = t.box
             if t.state == "resolved":
                 color = _COLORS["known"] if t.label and not str(t.label).startswith(
                     "Visitor") else _COLORS["new"]
@@ -440,15 +552,10 @@ class CameraWorker(threading.Thread):
                 color, text = _COLORS["ambiguous"], "?"
             else:
                 color, text = _COLORS["pending"], ""
-            cv2.rectangle(canvas, (x1, y1), (x2, y2), color, 2)
+            overlay.append((tuple(t.box), color, text))
-            if text:
+        with self._lock:
-                cv2.putText(canvas, text, (x1, max(20, y1 - 8)),
+            self._overlay = overlay
-                            cv2.FONT_HERSHEY_SIMPLEX, 0.55, color, 2)
+            self._overlay_ts = time.time()
-        ok, buf = cv2.imencode(".jpg", canvas,
-                               [int(cv2.IMWRITE_JPEG_QUALITY), 80])
-        if ok:
-            with self._lock:
-                self._annotated_jpeg = buf.tobytes()
 
 
 class Engine:
@@ -590,7 +697,10 @@ class Engine:
                 "age_model": ("genderage" if self.attributes is not None
                               and self.attributes.has_genderage else "caffe/none"),
             },
-            "gallery": self.store.stats(),
+            # Counts, plus whether the running encoder can actually SEARCH
+            # them. A gallery of 21 identities that the loaded model cannot
+            # read is the silent version of an empty one.
+            "gallery": {**self.store.stats(), **self.gallery.health},
             "cameras": [w.stats() for w in self.snapshot_workers()],
         }
 

behavision/gallery/service.py

@@ -53,10 +53,56 @@ class Gallery:
         # vectors from a different model are numerically incompatible.
         ids, vecs = store.all_embeddings(index.dim, model=model_name)
         index.add(ids, vecs)
+        self.health = self._assess(len(ids))
+        if self.health["stranded"]:
+            # Not an INFO line. The encoder fallback chain exists so a
+            # memory-starved box still runs, and when it fires every vector
+            # written by the previous encoder becomes invisible: the shop
+            # keeps its customer list and recognises nobody on it, greeting
+            # every regular as new and enrolling them a second time. Footfall
+            # stays right, which is exactly why nothing looks wrong. The old
+            # message for that state was "gallery ready: 0 embeddings".
+            log.warning(
+                "gallery: %d of %d stored embeddings were written by a "
+                "DIFFERENT encoder (%s) and cannot be searched - %d known "
+                "%s unrecognisable under the running model '%s'. Either "
+                "restore that model or accept that these identities start "
+                "over.",
+                self.health["stranded"], self.health["stored"],
+                ", ".join(sorted(self.health["other_models"])),
+                self.health["identities_stranded"],
+                "person is" if self.health["identities_stranded"] == 1
+                else "people are",
+                model_name)
         log.info("gallery ready: %d embeddings (model '%s') across %d "
                  "identities", len(ids), model_name,
                  store.stats()["identities"])
 
+    def _assess(self, usable: int) -> dict:
+        """What share of the gallery the running encoder can actually reach.
+
+        Reported rather than merely logged, because a log line on a shop PC
+        is read by nobody: this travels to head office the same way
+        `fraction_below_gate` does, beside the number it qualifies.
+        """
+        counts = self.store.model_counts()
+        stored = sum(counts.values())
+        others = {m: n for m, n in counts.items() if m != self.model_name}
+        identities = self.store.stats()["identities"]
+        return {
+            "model": self.model_name,
+            "stored": stored,
+            "usable": usable,
+            "stranded": sum(others.values()),
+            "other_models": sorted(others),
+            "identities": identities,
+            "identities_usable": self.store.identities_with_model(
+                self.model_name),
+            "identities_stranded": max(
+                0, identities - self.store.identities_with_model(
+                    self.model_name)),
+        }
+
     def resolve(self, embedding: np.ndarray, quality: float, camera_id: str,
                 ts: "float | None" = None,
                 attributes: "dict | None" = None,

behavision/gallery/store.py

@@ -281,6 +281,31 @@ class IdentityStore:
             return None
         return np.frombuffer(row["vector"], dtype=np.float32), float(row["quality"])
 
+    def model_counts(self) -> "dict[str, int]":
+        """How many stored embeddings each encoder produced.
+
+        The gallery only ever searches vectors tagged with the *running*
+        encoder, so this is what says whether the rest of the gallery is
+        reachable at all. See `Gallery.health` for why that matters.
+        """
+        with self._lock:
+            rows = self._db.execute(
+                "SELECT model, COUNT(*) AS n FROM embeddings "
+                "GROUP BY model").fetchall()
+        return {str(r["model"]): int(r["n"]) for r in rows}
+
+    def identities_with_model(self, model: str) -> int:
+        """Identities holding at least one embedding from this encoder.
+
+        Not the same as the identity count: an identity whose only vectors
+        came from a previous encoder still exists, and is unrecognisable.
+        """
+        with self._lock:
+            row = self._db.execute(
+                "SELECT COUNT(DISTINCT identity_id) AS n FROM embeddings "
+                "WHERE model=?", (model,)).fetchone()
+        return int(row["n"]) if row else 0
+
     def embedding_owners(self, model: "str | None" = None) -> "dict[int, int]":
         """embedding_id -> identity_id, for turning index hits into identity
         pairs without a round trip to SQLite per hit."""

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()

behavision/static/dashboard.html

@@ -4,6 +4,7 @@
 <meta charset="utf-8">
 <meta name="viewport" content="width=device-width, initial-scale=1">
 <title>Behavision</title>
+<link rel="icon" type="image/png" href="/static/favicon.png">
 <style>
   :root { color-scheme: dark; }
   * { box-sizing: border-box; margin: 0; }
@@ -513,11 +514,24 @@ async function refresh() {
     ]);
     renderFeeds(camList);
     renderCameras(camList);
+    // 'stalled' is its own word on purpose: connected and offline send you
+    // to the network, a camera that is answering and sending nothing does
+    // not. Three states, because two of them need opposite actions.
     const cams = stats.cameras.map(c =>
-      `${c.camera_id}: ${c.connected ? 'live' : 'offline'}`).join(' · ');
+      `${c.camera_id}: ${c.streaming ? 'live' : c.connected ? 'stalled' : 'offline'}`
+    ).join(' · ');
+    // The one failure that otherwise looks like perfect health: the encoder
+    // that loaded cannot read the embeddings already stored, so every known
+    // customer is a stranger. Counts stay right, which is why it needs saying.
+    const stranded = stats.gallery.stranded || 0;
+    const warn = stranded
+      ? ` · ⚠ ${stats.gallery.identities_stranded} people unrecognisable `
+        + `(${stranded} embeddings from ${stats.gallery.other_models.join(', ')}, `
+        + `running ${stats.gallery.model})`
+      : '';
     // textContent, not innerHTML — no escaping needed here.
     document.getElementById('status').textContent =
-      `${cams} · ${stats.gallery.identities} people · ${stats.gallery.sightings} sightings`;
+      `${cams} · ${stats.gallery.identities} people · ${stats.gallery.sightings} sightings${warn}`;
 
     document.getElementById('events').innerHTML = events.map(e => {
       const cls = e.type === 'person.new' ? 'new'

demo/console.html

@@ -0,0 +1,258 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
+<title>Behavision — live demo</title>
+<style>
+  :root{
+    --bg:#0A0E12; --s1:#11171C; --s2:#161D24; --s3:#1D262E;
+    --line:#24303A; --line2:#1B242C;
+    --ink:#E8EEF3; --ink2:#9FB0BD; --ink3:#6B7E8C;
+    --accent:#3DD0C4; --accent-dim:#123039;
+    --ok:#3FBF7F; --warn:#E0A33A; --bad:#E15B4C;
+    --mono:'SF Mono',ui-monospace,Menlo,monospace;
+    --font:'Inter',-apple-system,BlinkMacSystemFont,'Segoe UI',system-ui,sans-serif;
+  }
+  *{box-sizing:border-box;margin:0;padding:0}
+  body{background:var(--bg);color:var(--ink);font-family:var(--font);font-size:14px;line-height:1.5;
+       -webkit-font-smoothing:antialiased;padding:18px;min-height:100vh}
+  .top{display:flex;align-items:center;gap:14px;margin-bottom:16px;flex-wrap:wrap}
+  .brand{display:flex;align-items:center;gap:10px;margin-right:auto}
+  .brand img{width:26px;height:26px;object-fit:contain}
+  .brand b{font-size:16px;letter-spacing:-.01em}
+  .brand span{color:var(--ink3);font-size:12px}
+  .pill{display:inline-flex;align-items:center;gap:7px;padding:5px 11px;border-radius:99px;
+        border:1px solid var(--line);background:var(--s1);font-size:12px;color:var(--ink2)}
+  .dot{width:7px;height:7px;border-radius:99px;background:var(--ink3);flex:none}
+  .dot.ok{background:var(--ok);box-shadow:0 0 0 3px rgba(63,191,127,.16)}
+  .dot.bad{background:var(--bad);box-shadow:0 0 0 3px rgba(225,91,76,.16)}
+  .dot.warn{background:var(--warn);box-shadow:0 0 0 3px rgba(224,163,58,.16)}
+
+  .grid{display:grid;grid-template-columns:minmax(0,1.05fr) minmax(0,1fr);gap:14px;align-items:start}
+  @media(max-width:1100px){.grid{grid-template-columns:minmax(0,1fr)}}
+  .card{background:var(--s1);border:1px solid var(--line);border-radius:12px;overflow:hidden}
+  .card h2{font-size:11px;font-weight:600;letter-spacing:.09em;text-transform:uppercase;color:var(--ink3);
+           padding:12px 16px;border-bottom:1px solid var(--line2);display:flex;align-items:center;gap:10px}
+  .card h2 .grow{margin-left:auto;font-weight:500;letter-spacing:0;text-transform:none;font-size:12px;color:var(--ink3)}
+  .pad{padding:16px}
+
+  .cam{position:relative;aspect-ratio:16/9;background:#05090C}
+  .cam img{width:100%;height:100%;object-fit:cover;display:block}
+  .cam .none{position:absolute;inset:0;display:grid;place-items:center;color:var(--ink3);font-size:13px;text-align:center;padding:20px}
+  .cam .tag{position:absolute;top:10px;left:10px;background:rgba(10,14,18,.78);backdrop-filter:blur(8px);
+            border:1px solid var(--line);border-radius:8px;padding:5px 10px;font-size:11.5px;font-family:var(--mono)}
+
+  /* the chain */
+  .chain{display:flex;flex-direction:column;gap:0}
+  .step{display:grid;grid-template-columns:26px 1fr auto;gap:12px;align-items:start;padding:11px 16px;
+        border-bottom:1px solid var(--line2);opacity:.38;transition:opacity .25s}
+  .step:last-child{border-bottom:0}
+  .step.on{opacity:1}
+  .step .n{width:22px;height:22px;border-radius:99px;display:grid;place-items:center;font-size:11px;font-weight:600;
+           background:var(--s3);color:var(--ink3);border:1px solid var(--line);margin-top:1px}
+  .step.on .n{background:var(--accent);color:#04161B;border-color:transparent}
+  .step b{font-size:13.5px;font-weight:550;display:block}
+  .step small{color:var(--ink2);font-size:12px;display:block;margin-top:1px;font-family:var(--mono)}
+  .step .ms{font-family:var(--mono);font-size:11.5px;color:var(--accent);white-space:nowrap;margin-top:2px}
+
+  .empty{padding:34px 16px;text-align:center;color:var(--ink3);font-size:13px;line-height:1.6}
+  .empty b{display:block;color:var(--ink2);font-size:14px;margin-bottom:5px}
+
+  /* customer */
+  .who{display:flex;gap:13px;align-items:center;padding:16px;border-bottom:1px solid var(--line2)}
+  .av{width:50px;height:50px;border-radius:10px;background:var(--s3);border:1px solid var(--line);
+      display:grid;place-items:center;font-weight:600;font-size:17px;color:var(--ink2);flex:none;overflow:hidden}
+  .av img{width:100%;height:100%;object-fit:cover}
+  .who .n{font-size:16px;font-weight:600;letter-spacing:-.01em}
+  .who .m{color:var(--ink3);font-size:12.5px;margin-top:2px}
+  .badge{display:inline-block;padding:2px 8px;border-radius:99px;font-size:10.5px;font-weight:600;
+         letter-spacing:.04em;text-transform:uppercase}
+  .badge.new{background:var(--accent-dim);color:var(--accent)}
+  .badge.seen{background:rgba(63,191,127,.14);color:var(--ok)}
+  label{display:block;font-size:11.5px;font-weight:550;color:var(--ink2);margin-bottom:5px}
+  input{width:100%;background:var(--s2);border:1px solid var(--line);border-radius:7px;padding:9px 11px;
+        color:var(--ink);font:inherit;font-size:13.5px}
+  input:focus{outline:none;border-color:var(--accent)}
+  .row{display:grid;grid-template-columns:1fr 1fr;gap:10px;margin-bottom:12px}
+  button{background:var(--accent);color:#04161B;border:0;border-radius:7px;padding:9px 16px;
+         font:inherit;font-size:13px;font-weight:600;cursor:pointer}
+  button:disabled{opacity:.45;cursor:default}
+  button.sec{background:var(--s3);color:var(--ink);border:1px solid var(--line)}
+  .saved{color:var(--ok);font-size:12.5px;margin-top:9px;display:flex;align-items:center;gap:6px}
+
+  /* raw json */
+  pre{font-family:var(--mono);font-size:11px;line-height:1.55;color:var(--ink2);
+      background:#080C10;border-top:1px solid var(--line2);padding:13px 16px;margin:0;
+      max-height:230px;overflow:auto;white-space:pre-wrap;word-break:break-word}
+  .req{font-family:var(--mono);font-size:11.5px;color:var(--accent);padding:10px 16px;background:var(--s2)}
+  .req .st{float:right;color:var(--ink3)}
+  .hint{color:var(--ink3);font-size:12px;padding:10px 16px 14px;line-height:1.55}
+  .stack{display:flex;flex-direction:column;gap:14px}
+</style>
+</head>
+<body>
+  <div class="top">
+    <div class="brand">
+      <img src="data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCI+PHBhdGggZD0iTTEyIDIxcy04LTQuNS04LTEwYTQuNSA0LjUgMCAwIDEgOC0yLjggNC41IDQuNSAwIDAgMSA4IDIuOGMwIDUuNS04IDEwLTggMTB6IiBmaWxsPSIjRjJDMTFGIi8+PC9zdmc+" alt="">
+      <div><b>Behavision</b> <span id="site">— live demo</span></div>
+    </div>
+    <span class="pill"><i class="dot" id="d-eng"></i><span id="t-eng">engine…</span></span>
+    <span class="pill"><i class="dot" id="d-cam"></i><span id="t-cam">camera…</span></span>
+    <span class="pill"><i class="dot" id="d-cloud"></i><span id="t-cloud">cloud…</span></span>
+  </div>
+
+  <div class="grid">
+    <div class="stack">
+      <div class="card">
+        <h2>The camera <span class="grow" id="camname"></span></h2>
+        <div class="cam">
+          <img id="feed" alt="" style="display:none">
+          <div class="none" id="feednone">waiting for the camera…</div>
+          <div class="tag" id="camtag" style="display:none"></div>
+        </div>
+      </div>
+
+      <div class="card">
+        <h2>The customer <span class="grow">type a name, then walk past again</span></h2>
+        <div id="cust">
+          <div class="empty"><b>Nobody yet</b>Walk in front of the camera.</div>
+        </div>
+      </div>
+    </div>
+
+    <div class="stack">
+      <div class="card">
+        <h2>What just happened <span class="grow" id="lat"></span></h2>
+        <div id="chain"><div class="empty"><b>Waiting</b>Every step below lights up as it really happens.</div></div>
+      </div>
+
+      <div class="card">
+        <h2>What the mobile app receives</h2>
+        <div class="req" id="m-req">GET /api/visits<span class="st" id="m-st"></span></div>
+        <pre id="m-body">…</pre>
+      </div>
+
+      <div class="card">
+        <h2>What the dashboard receives</h2>
+        <div class="req" id="d-req">GET /api/reports/footfall<span class="st" id="d-st"></span></div>
+        <pre id="d-body">…</pre>
+        <div class="hint">Both of these are the real production API at mcp.loyaly.ai, called from this
+          machine with a staff login — not a mock, and not the local engine.</div>
+      </div>
+    </div>
+  </div>
+
+<script>
+const $ = s => document.querySelector(s);
+let camStarted = null, current = null, savedFor = null;
+
+function setPill(dot, text, tone, label){
+  $(dot).className = 'dot' + (tone ? ' ' + tone : '');
+  $(text).textContent = label;
+}
+
+function initials(name, ref){
+  const m = /^Visitor (\d+)$/.exec((name||'').trim());
+  if (m) return m[1];
+  const w = (name||'').trim().split(/\s+/).filter(Boolean);
+  if (!w.length) return '?';
+  return (w[0][0] + (w[1]?.[0] ?? '')).toUpperCase();
+}
+
+function drawChain(e){
+  if (!e){ $('#chain').innerHTML = '<div class="empty"><b>Waiting</b>Every step below lights up as it really happens.</div>'; $('#lat').textContent=''; return; }
+  const g = e.engine, c = e.cloud;
+  const steps = [
+    [true,  'Camera saw a face', g.quality != null ? `quality ${(+g.quality).toFixed(2)} · camera ${g.camera}` : `camera ${g.camera}`, ''],
+    [true,  e.kind === 'new' ? 'Engine: nobody it knows → enrolled' : 'Engine: matched a returning customer',
+            (g.label || '') + (g.similarity != null && g.similarity >= 0 ? ` · similarity ${(+g.similarity).toFixed(2)}` : '') , ''],
+    [true,  'Agent queued the visit', 'durable on this disk until the broker confirms', ''],
+    [!!c,   'Broker delivered it', 'MQTT over TLS to mcp.loyaly.ai', ''],
+    [!!c,   'Server recorded it', c ? `${c.site} · ${c.is_new ? 'new customer' : 'returning'}` : 'waiting…', ''],
+    [!!c,   'Mobile + dashboard can see it', c ? `visit ${String(c.visit_id).slice(0,8)}` : 'waiting…',
+            e.latency != null ? `+${e.latency}s` : ''],
+  ];
+  $('#chain').innerHTML = steps.map(([on,title,sub,ms],i)=>
+    `<div class="step ${on?'on':''}"><div class="n">${i+1}</div><div><b>${title}</b><small>${sub}</small></div><div class="ms">${ms}</div></div>`
+  ).join('');
+  $('#lat').textContent = e.latency != null ? `camera → cloud in ${e.latency}s` : '';
+}
+
+function drawCustomer(e){
+  const c = e && e.cloud;
+  if (!c){ if(!current) $('#cust').innerHTML = '<div class="empty"><b>Nobody yet</b>Walk in front of the camera.</div>'; return; }
+  const changed = !current || current.visitor_id !== c.visitor_id || current.visit_id !== c.visit_id;
+  if (!changed) return;
+  current = c;
+  const name = c.label || 'Unrecognised';
+  const img = c.image && c.image.available && c.image.url;
+  $('#cust').innerHTML = `
+    <div class="who">
+      <div class="av">${img ? `<img src="${img}">` : initials(name)}</div>
+      <div style="flex:1;min-width:0">
+        <div class="n">${name}</div>
+        <div class="m">${c.ref ? c.ref + ' · ' : ''}${c.is_new ? 'first time here' : 'returning'}${c.similarity>0 ? ' · match ' + (+c.similarity).toFixed(2) : ''}</div>
+      </div>
+      <span class="badge ${c.is_new?'new':'seen'}">${c.is_new?'new':'returning'}</span>
+    </div>
+    <div class="pad">
+      <div class="row">
+        <div><label>Name</label><input id="f-name" placeholder="e.g. Suriya" value=""></div>
+        <div><label>Phone</label><input id="f-phone" placeholder="+91…" value=""></div>
+      </div>
+      <button id="save">Save to the customer record</button>
+      <div id="savedmsg"></div>
+      <div class="hint" style="padding:12px 0 0">This writes to the production API. Walk past again and
+        the name comes back through the cloud instead of “${name}”.</div>
+    </div>`;
+  $('#save').onclick = async () => {
+    const b = $('#save'); b.disabled = true; b.textContent = 'Saving…';
+    const r = await fetch('/api/profile', {method:'POST', headers:{'content-type':'application/json'},
+      body: JSON.stringify({id: c.visitor_id, full_name: $('#f-name').value, phone: $('#f-phone').value})});
+    const d = await r.json();
+    b.disabled = false; b.textContent = 'Save to the customer record';
+    $('#savedmsg').innerHTML = (d.status===200||d.status===204)
+      ? '<div class="saved">✓ Saved — PUT /api/visitors/'+String(c.visitor_id).slice(0,8)+'…/profile → '+d.status+'</div>'
+      : '<div class="saved" style="color:var(--bad)">'+(d.body&&d.body.message||('HTTP '+d.status))+'</div>';
+    savedFor = c.visitor_id;
+  };
+}
+
+async function tick(){
+  let s;
+  try { s = await (await fetch('/api/snapshot')).json(); } catch { return; }
+
+  const eng = s.engine || {};
+  setPill('#d-eng','#t-eng', eng.up ? 'ok' : 'bad', eng.up ? ('engine · ' + (eng.model||'starting')) : 'engine starting…');
+  const cam = (eng.cameras||[])[0];
+  setPill('#d-cam','#t-cam', cam && cam.connected ? 'ok' : 'warn',
+          cam ? (cam.connected ? `camera live · ${cam.frames||0} frames` : 'camera connecting…') : 'no camera yet');
+  setPill('#d-cloud','#t-cloud', s.cloud_ok ? 'ok' : 'bad', s.cloud_ok ? 'cloud connected' : 'cloud unreachable');
+  $('#camname').textContent = cam ? cam.id : '';
+
+  if (cam && cam.connected){
+    if (camStarted !== cam.id){
+      camStarted = cam.id;
+      $('#feed').style.display = 'block'; $('#feednone').style.display = 'none';
+      $('#camtag').style.display = 'block';
+      // A polled still rather than an MJPEG stream: the engine re-serves its
+      // latest frame anyway, and a multipart stream through a proxy is one
+      // more thing to fail in front of an audience.
+      setInterval(() => { $('#feed').src = '/camera.jpg?id=' +
+        encodeURIComponent(camStarted) + '&t=' + Date.now(); }, 350);
+    }
+    $('#camtag').textContent = cam.id + (cam.tracks ? ` · ${cam.tracks} in frame` : '');
+  }
+
+  const e = (s.chain||[])[0];
+  drawChain(e); drawCustomer(e);
+
+  $('#m-st').textContent = s.mobile.status;
+  $('#m-body').textContent = JSON.stringify(s.mobile.body, null, 1).slice(0, 2600);
+  $('#d-st').textContent = s.dashboard.status;
+  $('#d-body').textContent = JSON.stringify(s.dashboard.body, null, 1).slice(0, 1800);
+}
+tick(); setInterval(tick, 1500);
+</script>
+</body>
+</html>

demo/console.py

@@ -0,0 +1,330 @@
+"""A one-screen live demo of the whole Behavision chain, for showing someone.
+
+Run it on the shop PC (here, this Mac) while the engine and agent are running.
+It holds every credential itself and the browser holds none, so the page can be
+put on a projector without putting a token on it.
+
+What it shows, and why each part is there:
+
+- the live camera, so the person walking past sees themselves;
+- the CHAIN, measured rather than described: the engine recognised a face at
+  this instant, the same visit appeared in the cloud API this many seconds
+  later. That number is the product's claim, and it is computed here from two
+  independent sources rather than asserted;
+- the customer, editable - type a name, walk past again, watch the name come
+  back through the cloud instead of "Visitor 5";
+- the raw JSON a phone and a dashboard receive, side by side, because a
+  colleague's real question is "is this actually wired up or is it a mock".
+
+    .venv/bin/python demo/console.py            # http://127.0.0.1:8099
+"""
+from __future__ import annotations
+
+import base64
+import json
+import os
+import threading
+import time
+import urllib.error
+import urllib.request
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+STATE = Path(os.environ.get("BEHAVISION_DATA_DIR", ROOT / ".demo"))
+CLOUD = os.environ.get("BEHAVISION_CLOUD", "https://mcp.loyaly.ai")
+ENGINE = "http://127.0.0.1:8010"
+PORT = int(os.environ.get("DEMO_PORT", "8099"))
+
+# Whoever the demo signs in as. Staff on purpose: it is the weakest role that
+# can do everything the shop floor does, so nothing here is only possible
+# because we used an owner.
+EMAIL = os.environ.get("DEMO_EMAIL", "staff.demo@tenext.in")
+PASSWORD = os.environ.get("DEMO_PASSWORD", "admin@123")
+
+
+def engine_auth() -> str:
+    """The engine invents a Basic credential when none is configured, and
+    writes it here. Read it rather than keeping a second copy."""
+    f = STATE / "data" / "api_credentials.txt"
+    if not f.exists():
+        return ""
+    user = pw = ""
+    for line in f.read_text().splitlines():
+        # `key=value`, and `key: value` too - the engine writes one and people
+        # read the other, and which is which is not worth a support call.
+        if "=" in line or ":" in line:
+            k, v = line.split("=", 1) if "=" in line else line.split(":", 1)
+            if k.strip().lower() == "username":
+                user = v.strip()
+            elif k.strip().lower() == "password":
+                pw = v.strip()
+    if not user:
+        return ""
+    return "Basic " + base64.b64encode(f"{user}:{pw}".encode()).decode()
+
+
+def fetch(url: str, *, headers=None, body=None, method="GET", timeout=20):
+    req = urllib.request.Request(url, method=method,
+                                 data=json.dumps(body).encode() if body is not None else None,
+                                 headers={k: v for k, v in (headers or {}).items() if v})
+    if body is not None:
+        req.add_header("content-type", "application/json")
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as r:
+            raw = r.read()
+            return r.status, (json.loads(raw) if raw and r.headers.get("content-type", "").startswith("application/json") else raw)
+    except urllib.error.HTTPError as e:
+        raw = e.read()
+        try:
+            return e.code, json.loads(raw or b"{}")
+        except Exception:
+            return e.code, raw[:400]
+    except Exception as e:
+        return 0, {"error": str(e)}
+
+
+class Cloud:
+    """The signed-in session, refreshed when it expires."""
+
+    def __init__(self):
+        self.token = ""
+        self.lock = threading.Lock()
+
+    def sign_in(self) -> bool:
+        st, d = fetch(f"{CLOUD}/api/auth/login", method="POST",
+                      body={"email": EMAIL, "password": PASSWORD, "device": "Demo console"})
+        if st == 200 and isinstance(d, dict):
+            self.token = d.get("access_token", "")
+            return True
+        return False
+
+    def call(self, path, method="GET", body=None, retry=True):
+        with self.lock:
+            if not self.token and not self.sign_in():
+                return 0, {"error": "cannot sign in to the platform"}
+            tok = self.token
+        st, d = fetch(f"{CLOUD}{path}", method=method, body=body,
+                      headers={"authorization": f"Bearer {tok}"})
+        if st == 401 and retry:
+            with self.lock:
+                self.sign_in()
+            return self.call(path, method, body, retry=False)
+        return st, d
+
+
+cloud = Cloud()
+
+# The chain, as the watcher builds it. One dict per recognition, newest first.
+events: list[dict] = []
+events_lock = threading.Lock()
+
+
+def watch():
+    """Poll the engine's own event log and the cloud feed, and join them.
+
+    They are joined on the identity and the second, not on a shared id,
+    because the engine numbers identities locally and the server numbers them
+    per tenant - the two are deliberately different (see CLAUDE.md). What
+    matters for the demo is the LATENCY between one seeing a person and the
+    other, and that only needs the same person and the same moment.
+    """
+    seen_local: set[str] = set()
+    while True:
+        try:
+            auth = engine_auth()
+            st, d = fetch(f"{ENGINE}/api/events?limit=25", headers={"authorization": auth})
+            # The engine returns a bare list; a dict with "events" is accepted
+            # too so this survives either shape.
+            evs = d if isinstance(d, list) else (d or {}).get("events", []) if isinstance(d, dict) else []
+            if st == 200:
+                for e in evs:
+                    if e.get("type") not in ("person.new", "person.seen"):
+                        continue
+                    key = f"{e.get('ts')}|{e.get('camera_id')}|{(e.get('data') or {}).get('identity_id')}"
+                    if key in seen_local:
+                        continue
+                    seen_local.add(key)
+                    data = e.get("data") or {}
+                    with events_lock:
+                        events.insert(0, {
+                            "key": key,
+                            "at": time.time(),
+                            "kind": "new" if e["type"] == "person.new" else "seen",
+                            "engine": {
+                                "label": data.get("label"),
+                                "identity_id": data.get("identity_id"),
+                                "similarity": data.get("similarity"),
+                                "quality": data.get("quality"),
+                                "gender": data.get("gender"),
+                                "age": data.get("age"),
+                                "camera": e.get("camera_id"),
+                                "ts": e.get("ts"),
+                            },
+                            "cloud": None,
+                            "latency": None,
+                        })
+                        del events[40:]
+        except Exception:
+            pass
+
+        # the other half: has the cloud got it yet?
+        try:
+            with events_lock:
+                pending = [e for e in events if e["cloud"] is None][:6]
+            if pending:
+                st, d = cloud.call("/api/visits?limit=12")
+                arrivals = (d or {}).get("arrivals", []) if isinstance(d, dict) else []
+                for e in pending:
+                    for a in arrivals:
+                        # same camera, and the cloud's visit is not older than
+                        # the engine's sighting
+                        if a.get("camera_id") != e["engine"]["camera"]:
+                            continue
+                        if a.get("visit_id") in [x["cloud"].get("visit_id") for x in events if x["cloud"]]:
+                            continue
+                        with events_lock:
+                            e["cloud"] = {
+                                "visit_id": a.get("visit_id"),
+                                "visitor_id": a.get("visitor_id"),
+                                "label": a.get("label"),
+                                "ref": a.get("customer_ref") or a.get("ref"),
+                                "is_new": a.get("is_new_visitor"),
+                                "similarity": a.get("similarity"),
+                                "site": a.get("site"),
+                                "occurred_at": a.get("occurred_at"),
+                                "image": a.get("image"),
+                            }
+                            e["latency"] = round(time.time() - e["at"], 1)
+                        break
+        except Exception:
+            pass
+        time.sleep(1.0)
+
+
+def snapshot() -> dict:
+    """Everything the page draws, in one reply."""
+    auth = engine_auth()
+    _, health = fetch(f"{ENGINE}/api/health", headers={"authorization": auth})
+    _, stats = fetch(f"{ENGINE}/api/stats", headers={"authorization": auth})
+    st_v, visits = cloud.call("/api/visits?limit=3")
+    st_f, foot = cloud.call("/api/reports/footfall?from=%s&to=%s"
+                            % (time.strftime("%Y-%m-%d", time.localtime(time.time() - 7 * 86400)),
+                               time.strftime("%Y-%m-%d")))
+    with events_lock:
+        chain = json.loads(json.dumps(events[:8]))
+    cams = (stats or {}).get("cameras", []) if isinstance(stats, dict) else []
+    return {
+        "engine": {
+            "up": isinstance(health, dict) and bool(health.get("status")),
+            "model": (health or {}).get("recognition_model") if isinstance(health, dict) else None,
+            "cameras": [{"id": c.get("camera_id"), "connected": c.get("connected"),
+                         "frames": c.get("frames_processed") or c.get("frames_total"),
+                         "faces": c.get("faces_seen"),
+                         "tracks": c.get("active_tracks")} for c in cams],
+        },
+        "cloud_ok": st_v == 200,
+        "chain": chain,
+        "mobile": {"request": "GET /api/visits?limit=3", "status": st_v, "body": visits},
+        "dashboard": {"request": "GET /api/reports/footfall?from=…&to=…", "status": st_f, "body": foot},
+    }
+
+
+def main():
+    from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+    from urllib.parse import urlparse, parse_qs
+
+    page = (Path(__file__).parent / "console.html").read_bytes()
+
+    class H(BaseHTTPRequestHandler):
+        def log_message(self, *a):  # quiet
+            pass
+
+        def _send(self, code, body, ctype="application/json"):
+            self.send_response(code)
+            self.send_header("content-type", ctype)
+            self.send_header("content-length", str(len(body)))
+            self.end_headers()
+            try:
+                self.wfile.write(body)
+            except (BrokenPipeError, ConnectionResetError):
+                pass
+
+        def do_GET(self):
+            u = urlparse(self.path)
+            if u.path == "/":
+                return self._send(200, page, "text/html; charset=utf-8")
+            if u.path == "/api/snapshot":
+                return self._send(200, json.dumps(snapshot()).encode())
+            if u.path == "/api/customer":
+                vid = parse_qs(u.query).get("id", [""])[0]
+                if not vid:
+                    return self._send(400, b'{"error":"no id"}')
+                st, d = cloud.call(f"/api/visitors/{vid}/history?limit=8")
+                return self._send(200, json.dumps({"status": st, "history": d}).encode())
+            if u.path == "/camera.jpg":
+                # A polled still, not the MJPEG stream. The engine re-serves its
+                # latest frame until the pipeline produces a new one, so polling
+                # shows the same picture - and a multipart stream through a
+                # proxy is one more thing to fail in front of an audience.
+                cam = parse_qs(u.query).get("id", [""])[0]
+                st, body = fetch(f"{ENGINE}/api/cameras/{cam}/frame.jpg",
+                                 headers={"authorization": engine_auth()}, timeout=15)
+                if st != 200 or not isinstance(body, (bytes, bytearray)):
+                    return self._send(502, b'{"error":"no frame"}')
+                self.send_response(200)
+                self.send_header("content-type", "image/jpeg")
+                self.send_header("cache-control", "no-store")
+                self.send_header("content-length", str(len(body)))
+                self.end_headers()
+                try:
+                    self.wfile.write(body)
+                except (BrokenPipeError, ConnectionResetError):
+                    pass
+                return
+            self._send(404, b'{"error":"no"}')
+
+        def do_POST(self):
+            u = urlparse(self.path)
+            n = int(self.headers.get("content-length", 0))
+            body = json.loads(self.rfile.read(n) or b"{}")
+            if u.path == "/api/profile":
+                vid = body.pop("id", "")
+                st, d = cloud.call(f"/api/visitors/{vid}/profile", method="PUT", body=body)
+                return self._send(200, json.dumps({"status": st, "body": d}).encode())
+            self._send(404, b'{"error":"no"}')
+
+        def _proxy_stream(self, url):
+            """The engine's MJPEG, relayed so the browser needs no credential.
+
+            The engine's API is Basic-authenticated with a credential it
+            generated locally; putting that in a page would hand the whole
+            biometric API to anyone who opened it.
+            """
+            try:
+                req = urllib.request.Request(url, headers={"authorization": engine_auth()})
+                up = urllib.request.urlopen(req, timeout=20)
+            except Exception:
+                return self._send(502, b'{"error":"camera not available"}')
+            self.send_response(200)
+            self.send_header("content-type", up.headers.get("content-type", "multipart/x-mixed-replace"))
+            self.end_headers()
+            try:
+                while True:
+                    chunk = up.read(8192)
+                    if not chunk:
+                        break
+                    self.wfile.write(chunk)
+                    self.wfile.flush()
+            except Exception:
+                pass
+            finally:
+                up.close()
+
+    threading.Thread(target=watch, daemon=True).start()
+    print(f"\n  Demo console  →  http://127.0.0.1:{PORT}\n")
+    print(f"  engine {ENGINE} · cloud {CLOUD} · signed in as {EMAIL}\n")
+    ThreadingHTTPServer(("127.0.0.1", PORT), H).serve_forever()
+
+
+if __name__ == "__main__":
+    main()

desktop/app.go

@@ -23,6 +23,7 @@ import (
 	agentcameras "github.com/loyaly/behavision-agent/pkg/cameras"
 	agentcfg "github.com/loyaly/behavision-agent/pkg/config"
 	agentengine "github.com/loyaly/behavision-agent/pkg/engine"
+	"github.com/loyaly/behavision-agent/pkg/enrol"
 	agentmqtt "github.com/loyaly/behavision-agent/pkg/mqtt"
 	agentpaths "github.com/loyaly/behavision-agent/pkg/paths"
 	agentspool "github.com/loyaly/behavision-agent/pkg/spool"
@@ -43,6 +44,9 @@ type App struct {
 	broker     *agentmqtt.Client
 	stopBridge func()
 	hookURL    string
+	// Relays camera feeds to the webview so the engine's credential never has
+	// to travel in an <img> src, which a Chromium webview would strip anyway.
+	proxy *streamProxy
 	// Set once the operator logs in. Until then the UI shows the login sheet
 	// and nothing else is reachable.
 	onSessionChange func(bool)
@@ -62,7 +66,8 @@ func NewApp() *App {
 	return &App{
 		cfg:   cfg,
 		cloud: cloud.New(envOr("BEHAVISION_CLOUD", "https://mcp.loyaly.ai")),
-		local: local.New(base, cfg.APIUser, cfg.APIPassword),
+		local: localWithCreds(base, cfg),
+		proxy: newStreamProxy(),
 	}
 }
 
@@ -70,6 +75,14 @@ func (a *App) startup(ctx context.Context) {
 	a.ctx = ctx
 	_ = agentpaths.EnsureState()
 
+	// Before any screen asks for a camera URL. A failure here is logged and
+	// not fatal: the rest of the app - people, cameras, the engine controls -
+	// works without a picture, and refusing to start over a broken tile would
+	// take a working shop offline.
+	if err := a.proxy.start(a.local.Base, a.local.User, a.local.Password); err != nil {
+		log.Printf("camera relay unavailable, tiles will not load: %v", err)
+	}
+
 	// A saved session means a shop PC that rebooted overnight comes back
 	// working instead of waiting for someone to log in.
 	if a.cfg.SessionToken != "" {
@@ -92,6 +105,14 @@ func (a *App) startup(ctx context.Context) {
 	a.sup = agentengine.New(agentengine.Options{
 		Command: func(c context.Context) *exec.Cmd {
 			cmd := exec.CommandContext(c, exe, a.cfg.EngineArgs...)
+			// Run the engine FROM a known directory rather than from whatever
+			// happened to launch us. A double-clicked bundle hands its child
+			// "/", and an engine invoked as `-m behavision` then cannot find
+			// itself - measured on macOS, where it retried forever.
+			cmd.Dir = a.cfg.EngineDir
+			if cmd.Dir == "" {
+				cmd.Dir = agentpaths.InstallRoot()
+			}
 			// How the engine learns where to post its detections. Its config
 			// already reads `events.webhook_url: ${BEHAVISION_WEBHOOK_URL}`,
 			// and python-dotenv does not override a variable the process
@@ -102,7 +123,7 @@ func (a *App) startup(ctx context.Context) {
 			// be told again. Without it the engine recognised people and the
 			// bridge received nothing: a claimed shop PC published heartbeats
 			// and zero visits.
-			cmd.Env = append(os.Environ(), "BEHAVISION_WEBHOOK_URL="+a.webhookURL())
+			cmd.Env = agentengine.ChildEnv(a.webhookURL())
 			return cmd
 		},
 		LogWriter: logFile,
@@ -112,6 +133,24 @@ func (a *App) startup(ctx context.Context) {
 	})
 
 	a.startPipeline(ctx)
+	go a.watchConfig(ctx)
+
+	// Recognition starts with the app. Until this, the engine only ever
+	// started when somebody pressed Start - which meant a till that rebooted
+	// overnight came back with the window open, the tray icon showing, the
+	// session restored, and recognition off until a shop assistant noticed.
+	// That is the failure the tray colours exist to catch, and it should not
+	// be the default state every morning.
+	//
+	// Guarded on the interpreter actually being there: on a PC where setup has
+	// not run yet, starting the supervisor would loop on a missing executable
+	// with nothing useful to say. The Start button still exists for the one
+	// case where somebody has deliberately stopped it.
+	if _, err := os.Stat(exe); err == nil {
+		a.sup.Start()
+	} else {
+		log.Printf("engine not installed yet (%s); run behavision-setup, then Start", exe)
+	}
 }
 
 // webhookURL is the loopback address the bridge is listening on, or empty
@@ -229,6 +268,9 @@ func (a *App) startLocalCameras(ctx context.Context, logger *log.Logger) {
 	// this app - and the headless agent - both ended up wiring configuration
 	// and forgetting the check runner, so "Test connection" at head office
 	// never completed on any shop PC.
+	// The live relay runs alongside the reconciler and uploads nothing until
+	// somebody at head office is actually watching a camera.
+	go agentcameras.NewLive(camEngine, camCloud, logger).Run(ctx)
 	agentcameras.New(camEngine, camCloud, logger).Run(ctx)
 }
 
@@ -270,8 +312,8 @@ type PipelineStatus struct {
 	// Standalone separates "nothing is being sent because this PC is set up on
 	// its own" from "nothing is being sent and something is wrong". They look
 	// identical from the counters alone, and only one of them is a fault.
-	Standalone bool `json:"standalone"`
+	Standalone bool   `json:"standalone"`
-	BrokerUp   bool `json:"broker_up"`
+	BrokerUp   bool   `json:"broker_up"`
 	Accepted   uint64 `json:"accepted"`
 }
 
@@ -402,6 +444,14 @@ func (a *App) Claim(code string) (SessionInfo, error) {
 	a.cfg.BrokerPassword = b.MQTTPass
 	a.cfg.AgentToken = b.AgentToken
 	a.cfg.CloudBase = a.cloud.Base
+	// A new head office: whoever was signed in was signed in somewhere else.
+	a.cfg.SessionToken, a.cfg.SessionRefresh, a.cfg.SessionEmail = "", "", ""
+	a.cloud.Clear()
+	caPath, err := enrol.SaveCA(b.CACert, agentpaths.BrokerCA())
+	if err != nil {
+		return SessionInfo{}, err
+	}
+	a.cfg.BrokerCAFile = caPath
 	// A PC that was running on its own and has now been linked is no longer
 	// standalone. Leaving the flag set would keep the head-office screens
 	// hidden on the one machine that just earned them.
@@ -426,6 +476,62 @@ func (a *App) Claim(code string) (SessionInfo, error) {
 // the current config. Only Claim needs it today; it exists as its own method
 // because "stop everything that reads the config, then start it" is the part
 // that is easy to get half right.
+// watchConfig reloads agent.json when something else writes it.
+//
+// behavision-setup re-run on a PC with the app open re-claims the shop and
+// rotates its API token; the running app kept the old one and every camera
+// sync was refused from then on - heartbeats still flowed, so head office
+// looked fine while the cameras went stale. A claim from `behavision-agent
+// claim` does the same. Rather than ask people to restart the app, the app
+// watches the file and picks the new credentials up itself.
+func (a *App) watchConfig(ctx context.Context) {
+	path := agentpaths.AgentConfig()
+	last := mtime(path)
+	t := time.NewTicker(10 * time.Second)
+	defer t.Stop()
+	for {
+		select {
+		case <-ctx.Done():
+			return
+		case <-t.C:
+		}
+		now := mtime(path)
+		if now.IsZero() || now.Equal(last) {
+			continue
+		}
+		last = now
+		fresh, err := agentcfg.Load(path)
+		if err != nil {
+			continue
+		}
+		fresh = fresh.WithEngineCredentials(agentpaths.APICredentials())
+		a.mu.Lock()
+		changed := fresh.AgentToken != a.cfg.AgentToken || fresh.SiteID != a.cfg.SiteID ||
+			fresh.BrokerPassword != a.cfg.BrokerPassword || fresh.CloudBase != a.cfg.CloudBase ||
+			fresh.Standalone != a.cfg.Standalone
+		if changed {
+			// Keep this process's live session; a claim clears it in the file
+			// deliberately, and that is honoured too.
+			a.cfg = fresh
+			if fresh.SessionToken == "" {
+				a.cloud.Clear()
+			}
+		}
+		a.mu.Unlock()
+		if changed {
+			a.restartPipeline()
+		}
+	}
+}
+
+func mtime(path string) time.Time {
+	st, err := os.Stat(path)
+	if err != nil {
+		return time.Time{}
+	}
+	return st.ModTime()
+}
+
 func (a *App) restartPipeline() {
 	if a.stopBridge != nil {
 		a.stopBridge()
@@ -463,6 +569,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 {
@@ -473,6 +581,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()
 	}
@@ -511,6 +622,14 @@ func (a *App) Cameras() ([]map[string]any, error) {
 	return a.local.Cameras(ctx)
 }
 
+// DiscoverCameras lists the cameras on this PC's network, so the add-camera
+// form is a pick-list and not a request for an IP address nobody knows.
+func (a *App) DiscoverCameras() (map[string]any, error) {
+	ctx, cancel := context.WithTimeout(a.ctx, 30*time.Second)
+	defer cancel()
+	return a.local.DiscoverCameras(ctx)
+}
+
 func (a *App) TestCamera(cam map[string]any) (map[string]any, error) {
 	ctx, cancel := context.WithTimeout(a.ctx, 60*time.Second)
 	defer cancel()
@@ -546,15 +665,25 @@ func (a *App) PlacementResult(id string) (map[string]any, error) {
 	return a.local.PlacementResult(ctx, id)
 }
 
-// StreamURL is the MJPEG endpoint for a camera, with credentials inline so an
+// StreamURL is the MJPEG endpoint for a camera tile.
-// <img> tag can load it. Loopback only - it never leaves this machine.
+//
+// It points at this app's own loopback relay, not at the engine directly. The
+// previous version put the engine's Basic credentials inline in the URL, with
+// a comment saying they were there "so an <img> tag can load it" - which a
+// browser will not do. Chromium strips credentials from subresource URLs, and
+// WebView2 is Chromium, so every camera tile on a shop PC was a broken image.
+// See stream_proxy.go for the measurement.
+//
+// The relay is also why no password appears in the page any more. If it is not
+// running the fallback is the bare engine URL with no credential: correct for
+// an engine configured without auth, and for one with auth a tile that fails
+// to load rather than a password sitting in the DOM.
 func (a *App) StreamURL(cameraID string) string {
-	base := strings.TrimPrefix(strings.TrimPrefix(a.local.Base, "http://"), "https://")
+	if u := a.proxy.urlFor(cameraID, "stream.mjpeg"); u != "" {
-	if a.local.User == "" {
+		return u
-		return fmt.Sprintf("http://%s/api/cameras/%s/stream.mjpeg", base, cameraID)
 	}
-	return fmt.Sprintf("http://%s:%s@%s/api/cameras/%s/stream.mjpeg",
+	base := strings.TrimPrefix(strings.TrimPrefix(a.local.Base, "http://"), "https://")
-		a.local.User, a.local.Password, base, cameraID)
+	return fmt.Sprintf("http://%s/api/cameras/%s/stream.mjpeg", base, cameraID)
 }
 
 // ------------------------------------------------------------------- live --
@@ -611,6 +740,15 @@ func (a *App) Sites() ([]cloud.SiteHealth, error) {
 }
 
 // VisitorHistory is one customer's timeline, for the customer record screen.
+// Ask is the help panel. It needs head office: the assistant runs there,
+// against this company's own data, as this signed-in user. A PC running on
+// its own has nobody to ask, and the panel says so rather than erroring.
+func (a *App) Ask(history []cloud.AssistantTurn) (cloud.AssistantAnswer, error) {
+	ctx, cancel := context.WithTimeout(a.ctx, 90*time.Second)
+	defer cancel()
+	return a.cloud.Ask(ctx, history)
+}
+
 func (a *App) VisitorHistory(id string, limit int) ([]cloud.Visit, error) {
 	if limit <= 0 {
 		limit = 100
@@ -685,3 +823,12 @@ func envOr(key, def string) string {
 	}
 	return def
 }
+
+// localWithCreds builds the engine client with a credential resolver, so a
+// first run - where the engine writes its credential after the app has looked
+// for it - recovers by itself instead of 401ing for the life of the process.
+func localWithCreds(base string, cfg agentcfg.Config) *local.Client {
+	c := local.New(base, cfg.APIUser, cfg.APIPassword)
+	c.Creds = agentcfg.NewCreds(agentpaths.APICredentials(), cfg.APIUser, cfg.APIPassword)
+	return c
+}

desktop/build/darwin/Info.dev.plist

@@ -0,0 +1,68 @@
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+    <dict>
+        <key>CFBundlePackageType</key>
+        <string>APPL</string>
+        <key>CFBundleName</key>
+        <string>{{.Info.ProductName}}</string>
+        <key>CFBundleExecutable</key>
+        <string>{{.OutputFilename}}</string>
+        <key>CFBundleIdentifier</key>
+        <string>com.wails.{{safeBundleID .Name}}</string>
+        <key>CFBundleVersion</key>
+        <string>{{.Info.ProductVersion}}</string>
+        <key>CFBundleGetInfoString</key>
+        <string>{{.Info.Comments}}</string>
+        <key>CFBundleShortVersionString</key>
+        <string>{{.Info.ProductVersion}}</string>
+        <key>CFBundleIconFile</key>
+        <string>iconfile</string>
+        <key>LSMinimumSystemVersion</key>
+        <string>10.13.0</string>
+        <key>NSHighResolutionCapable</key>
+        <string>true</string>
+        <key>NSHumanReadableCopyright</key>
+        <string>{{.Info.Copyright}}</string>
+        {{if .Info.FileAssociations}}
+        <key>CFBundleDocumentTypes</key>
+        <array>
+          {{range .Info.FileAssociations}}
+          <dict>
+            <key>CFBundleTypeExtensions</key>
+            <array>
+              <string>{{.Ext}}</string>
+            </array>
+            <key>CFBundleTypeName</key>
+            <string>{{.Name}}</string>
+            <key>CFBundleTypeRole</key>
+            <string>{{.Role}}</string>
+            <key>CFBundleTypeIconFile</key>
+            <string>{{.IconName}}</string>
+          </dict>
+          {{end}}
+        </array>
+        {{end}}
+        {{if .Info.Protocols}}
+        <key>CFBundleURLTypes</key>
+        <array>
+          {{range .Info.Protocols}}
+            <dict>
+                <key>CFBundleURLName</key>
+                <string>com.wails.{{.Scheme}}</string>
+                <key>CFBundleURLSchemes</key>
+                <array>
+                    <string>{{.Scheme}}</string>
+                </array>
+                <key>CFBundleTypeRole</key>
+                <string>{{.Role}}</string>
+            </dict>
+          {{end}}
+        </array>
+        {{end}}
+        <key>NSAppTransportSecurity</key>
+        <dict>
+            <key>NSAllowsLocalNetworking</key>
+            <true/>
+        </dict>
+    </dict>
+</plist>

desktop/build/darwin/Info.plist

@@ -0,0 +1,63 @@
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+    <dict>
+        <key>CFBundlePackageType</key>
+        <string>APPL</string>
+        <key>CFBundleName</key>
+        <string>{{.Info.ProductName}}</string>
+        <key>CFBundleExecutable</key>
+        <string>{{.OutputFilename}}</string>
+        <key>CFBundleIdentifier</key>
+        <string>com.wails.{{safeBundleID .Name}}</string>
+        <key>CFBundleVersion</key>
+        <string>{{.Info.ProductVersion}}</string>
+        <key>CFBundleGetInfoString</key>
+        <string>{{.Info.Comments}}</string>
+        <key>CFBundleShortVersionString</key>
+        <string>{{.Info.ProductVersion}}</string>
+        <key>CFBundleIconFile</key>
+        <string>iconfile</string>
+        <key>LSMinimumSystemVersion</key>
+        <string>10.13.0</string>
+        <key>NSHighResolutionCapable</key>
+        <string>true</string>
+        <key>NSHumanReadableCopyright</key>
+        <string>{{.Info.Copyright}}</string>
+        {{if .Info.FileAssociations}}
+        <key>CFBundleDocumentTypes</key>
+        <array>
+          {{range .Info.FileAssociations}}
+          <dict>
+            <key>CFBundleTypeExtensions</key>
+            <array>
+              <string>{{.Ext}}</string>
+            </array>
+            <key>CFBundleTypeName</key>
+            <string>{{.Name}}</string>
+            <key>CFBundleTypeRole</key>
+            <string>{{.Role}}</string>
+            <key>CFBundleTypeIconFile</key>
+            <string>{{.IconName}}</string>
+          </dict>
+          {{end}}
+        </array>
+        {{end}}
+        {{if .Info.Protocols}}
+        <key>CFBundleURLTypes</key>
+        <array>
+          {{range .Info.Protocols}}
+            <dict>
+                <key>CFBundleURLName</key>
+                <string>com.wails.{{.Scheme}}</string>
+                <key>CFBundleURLSchemes</key>
+                <array>
+                    <string>{{.Scheme}}</string>
+                </array>
+                <key>CFBundleTypeRole</key>
+                <string>{{.Role}}</string>
+            </dict>
+          {{end}}
+        </array>
+        {{end}}
+    </dict>
+</plist>

desktop/build/windows/info.json

@@ -0,0 +1,15 @@
+{
+	"fixed": {
+		"file_version": "{{.Info.ProductVersion}}"
+	},
+	"info": {
+		"0000": {
+			"ProductVersion": "{{.Info.ProductVersion}}",
+			"CompanyName": "{{.Info.CompanyName}}",
+			"FileDescription": "{{.Info.ProductName}}",
+			"LegalCopyright": "{{.Info.Copyright}}",
+			"ProductName": "{{.Info.ProductName}}",
+			"Comments": "{{.Info.Comments}}"
+		}
+	}
+}

desktop/build/windows/wails.exe.manifest

@@ -0,0 +1,15 @@
+<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<assembly manifestVersion="1.0" xmlns="urn:schemas-microsoft-com:asm.v1" xmlns:asmv3="urn:schemas-microsoft-com:asm.v3">
+    <assemblyIdentity type="win32" name="com.wails.{{.Name}}" version="{{.Info.ProductVersion}}.0" processorArchitecture="*"/>
+    <dependency>
+        <dependentAssembly>
+            <assemblyIdentity type="win32" name="Microsoft.Windows.Common-Controls" version="6.0.0.0" processorArchitecture="*" publicKeyToken="6595b64144ccf1df" language="*"/>
+        </dependentAssembly>
+    </dependency>
+    <asmv3:application>
+        <asmv3:windowsSettings>
+            <dpiAware xmlns="http://schemas.microsoft.com/SMI/2005/WindowsSettings">true/pm</dpiAware> <!-- fallback for Windows 7 and 8 -->
+            <dpiAwareness xmlns="http://schemas.microsoft.com/SMI/2016/WindowsSettings">permonitorv2,permonitor</dpiAwareness> <!-- falls back to per-monitor if per-monitor v2 is not supported -->
+        </asmv3:windowsSettings>
+    </asmv3:application>
+</assembly>

desktop/darwin_link.go

@@ -0,0 +1,25 @@
+//go:build darwin
+
+// Link the framework Wails' darwin frontend forgets.
+//
+// It references UTType (UniformTypeIdentifiers) without linking it, so a macOS
+// build fails at the LINK step with `Undefined symbols: _OBJC_CLASS_$_UTType`
+// - after compiling everything successfully, which makes it read like a broken
+// toolchain rather than one missing flag. That is why there was no Mac build:
+// not a design limit, a link error nobody had chased.
+//
+// Declared in the source rather than passed as CGO_LDFLAGS on the command
+// line, for the same reason deploy.sh now finds Go itself: a build that needs
+// the operator to know an incantation is a build that does not happen. Plain
+// `go build` and `wails build` both work on a Mac with this file present, and
+// the build tag makes it inert everywhere else.
+//
+// Note for anyone editing: the comment directly above `import "C"` is cgo's C
+// PREAMBLE, not documentation. This paragraph sits above `package main` on
+// purpose - put it there and the prose is compiled as C, which is how the
+// first attempt failed.
+
+package main
+
+// #cgo LDFLAGS: -framework UniformTypeIdentifiers
+import "C"

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-whFsTNQf.js"></script>
+    <script type="module" crossorigin src="./assets/index-Be_Iv2Nz.js"></script>
-    <link rel="stylesheet" crossorigin href="./assets/index-XjqO50wd.css">
+    <link rel="stylesheet" crossorigin href="./assets/index-lhDNZRcC.css">
   </head>
   <body>
     <div id="root"></div>

desktop/frontend/src/App.jsx

@@ -1,11 +1,14 @@
 import { useCallback, useEffect, useState } from 'react'
 import { api, isDesktop, message } from './bridge.js'
 import { usePolled } from './hooks.js'
+import * as Icon from './ui/icons.jsx'
+import logo from './assets/loyaly-mark.png'
 import Login from './views/Login.jsx'
 import Setup from './views/Setup.jsx'
 import Live from './views/Live.jsx'
 import Customers from './views/Customers.jsx'
 import Cameras from './views/Cameras.jsx'
+import Assistant from './views/Assistant.jsx'
 
 // Three screens, and the trim is by AUDIENCE rather than by taste.
 //
@@ -22,9 +25,9 @@ import Cameras from './views/Cameras.jsx'
 // the customer record lives on the server, the cameras and what this PC is
 // seeing do not.
 const VIEWS = [
-  { id: 'live',      label: 'Live',      glyph: '◉', View: Live },
+  { id: 'live',      label: 'Live',      Glyph: Icon.Live,   View: Live },
-  { id: 'customers', label: 'Customers', glyph: '☺', View: Customers, cloud: true },
+  { id: 'customers', label: 'Customers', Glyph: Icon.People, View: Customers, cloud: true },
-  { id: 'cameras',   label: 'Cameras',   glyph: '▢', View: Cameras },
+  { id: 'cameras',   label: 'Cameras',   Glyph: Icon.Camera, View: Cameras },
 ]
 
 export default function App() {
@@ -34,12 +37,23 @@ export default function App() {
   // A standalone PC can join head office later. That is the same Setup screen,
   // reached deliberately rather than because the app will not open otherwise.
   const [linking, setLinking] = useState(false)
+  const [helping, setHelping] = useState(false)
 
   useEffect(() => {
-    (async () => {
+    let alive = true
-      try { setSession(await api.session()) } catch { setSession(null) }
+    const load = async () => {
-      setBooting(false)
+      try {
-    })()
+        const s = await api.session()
+        if (alive) setSession(prev => JSON.stringify(prev) === JSON.stringify(s) ? prev : s)
+      } catch { if (alive) setSession(null) }
+      if (alive) setBooting(false)
+    }
+    load()
+    // Re-read every few seconds: a session the server has ended - or one
+    // that never belonged to this head office - must put Login back on
+    // screen, not leave "session expired" banners on every page.
+    const id = setInterval(load, 8000)
+    return () => { alive = false; clearInterval(id) }
   }, [])
 
   if (!isDesktop()) {
@@ -48,6 +62,7 @@ export default function App() {
     // error nobody will read.
     return (
       <div className="login"><div className="box">
+        <span className="mark"><img src={logo} alt="" /></span>
         <h1>Behavision</h1>
         <p className="lead">
           This is the Behavision window running outside the app, so it has no
@@ -78,41 +93,56 @@ export default function App() {
     <div className="shell">
       <aside className="side">
         <div className="brand">
-          <h1>Behavision</h1>
+          <span className="mark"><img src={logo} alt="" /></span>
-          <p>{session.site_name || session.user?.client_name || 'Store'}</p>
+          <div className="id">
+            <h1>Behavision</h1>
+            <p>{session.site_name || session.user?.client_name || 'This shop'}</p>
+          </div>
         </div>
         <nav className="nav">
-          {views.map(v => (
+          {views.map(({ id, label, Glyph }) => (
-            <button key={v.id} onClick={() => setView(v.id)}
+            <button key={id} onClick={() => setView(id)}
-                    aria-current={v.id === view ? 'page' : undefined}>
+                    aria-current={id === view ? 'page' : undefined}>
-              <span className="glyph">{v.glyph}</span>{v.label}
+              <Glyph size={17} />{label}
             </button>
           ))}
         </nav>
         <EngineBox />
-        <div style={{ padding: '10px 12px 14px', borderTop: '1px solid var(--line-soft)' }}>
+        <div className="who">
           {session.standalone
             ? <>
-                <div className="note" style={{ marginBottom: 8 }}>
+                <div className="id">
-                  Running on its own
+                  <b>On its own</b>
+                  <span>No head office</span>
                 </div>
-                <button className="btn sm" style={{ width: '100%' }}
+                <button className="btn sm icon" title="Link to head office"
                         onClick={() => setLinking(true)}>
-                  Link to head office
+                  <Icon.Link size={15} />
                 </button>
               </>
             : <>
-                <div className="note" style={{ marginBottom: 8 }}>
+                <div className="id">
-                  {session.user?.email}
+                  <b>Signed in</b>
+                  <span>{session.user?.email}</span>
                 </div>
-                <button className="btn sm" style={{ width: '100%' }}
+                <button className="btn sm icon" title="Sign out"
                         onClick={async () => setSession(await api.logout())}>
-                  Sign out
+                  <Icon.Logout size={15} />
                 </button>
               </>}
         </div>
       </aside>
-      <main className="main"><Current session={session} /></main>
+      <main className="main">
+        <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 && (
+          <button className="loya-fab" onClick={() => setHelping(true)} aria-label="Ask Loya" title="Ask Loya">
+            <img src={logo} alt="" /><span>Loya</span>
+          </button>
+        )}
+      </main>
+      {helping && <Assistant session={session} onClose={() => setHelping(false)} />}
     </div>
   )
 }
@@ -136,7 +166,13 @@ function EngineBox() {
   const up = cams.filter(Boolean).length
 
   let tone = 'idle', text = 'Stopped'
-  if (s.state === 'failed' || s.state === 'backoff') { tone = 'bad'; text = 'Not running' }
+  // Reachable but not ours: somebody started the engine outside this app, or a
+  // previous copy is still up. Saying "Stopped" beside live camera feeds is the
+  // two-surfaces-disagreeing bug the tray exists to avoid - and it is exactly
+  // 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' }
@@ -145,16 +181,21 @@ function EngineBox() {
 
   return (
     <div className="enginebox">
-      <div className="row"><i className={`dot ${tone}`} /><strong>{text}</strong></div>
+      <div className="row">
-      {s.recognition_model && (
+        <i className={`dot ${tone === 'ok' ? 'live' : tone}`} />
-        <span className="label">Model: {s.recognition_model}</span>
+        <span className="state">{text}</span>
-      )}
+      </div>
+      {s.recognition_model && <span className="label">{s.recognition_model}</span>}
       {s.error && <span className="label" style={{ color: 'var(--bad)' }}>{s.error}</span>}
       <div className="actions">
-        <button className="btn sm" disabled={busy || running}
+        <button className="btn sm" disabled={busy || running || s.reachable}
-                onClick={() => act(api.startEngine)}>Start</button>
+                onClick={() => act(api.startEngine)}>
+          <Icon.Play size={13} />Start
+        </button>
         <button className="btn sm" disabled={busy || !running}
-                onClick={() => act(api.stopEngine)}>Stop</button>
+                onClick={() => act(api.stopEngine)}>
+          <Icon.Stop size={13} />Stop
+        </button>
       </div>
     </div>
   )

desktop/frontend/src/bridge.js

@@ -32,6 +32,7 @@ export const api = {
 
   cameras:            () => call('Cameras'),
   testCamera:         (cam) => call('TestCamera', cam),
+  discoverCameras:    () => call('DiscoverCameras'),
   saveCamera:         (id, cam) => call('SaveCamera', id, cam),
   deleteCamera:       (id) => call('DeleteCamera', id),
   startPlacement:     (id, seconds) => call('StartPlacementCheck', id, seconds),
@@ -51,6 +52,7 @@ export const api = {
   sales:              (from, to) => call('Sales', from, to),
   customers:          (q, limit) => call('Customers', q, limit),
   saveProfile:        (p) => call('SaveProfile', p),
+  ask:                (history) => call('Ask', history),
   recordPurchase:     (id, amount, items, notes) =>
                         call('RecordPurchase', id, amount, items, notes),
 }

desktop/frontend/src/main.jsx

@@ -3,6 +3,9 @@ import { createRoot } from 'react-dom/client'
 import App from './App.jsx'
 import './styles.css'
 
+// Dev only: ?mock=<scenario> renders the app in a browser with fake bindings.
+if (import.meta.env.DEV) await import('./mock.js')
+
 createRoot(document.getElementById('root')).render(
   <React.StrictMode><App /></React.StrictMode>
 )

desktop/frontend/src/mock.js

@@ -0,0 +1,83 @@
+// A stand-in for the Go bindings, for looking at screens in a browser.
+//
+// The app only exists inside Wails, so until this there was no way to put a
+// screen in front of somebody without a Windows build - which is how the
+// first-run experience went unreviewed. Loaded ONLY by the dev server and only
+// with ?mock=<scenario>; a production bundle never contains it.
+//
+//   ?mock=fresh       first launch after install: unclaimed, engine starting
+//   ?mock=standalone  chose "run on this PC only", no cameras yet
+//   ?mock=claimed     claimed, signed in, one camera, arrivals flowing
+//
+// State is in memory and advances as you click, so the flow can be walked.
+const scenario = new URLSearchParams(location.search).get('mock')
+
+if (scenario) {
+  const st = {
+    claimed: scenario === 'claimed',
+    standalone: scenario === 'standalone',
+    logged_in: scenario === 'claimed',
+    cameras: scenario === 'claimed' ? [{id: 'entrance', label: 'Entrance', host: '192.168.1.122', port: 554, path: '/ch0_1.264', username: 'admin', has_password: true, enabled: true}] : [],
+    engine: scenario === 'fresh' ? 'starting' : 'running',
+    startedAt: Date.now(),
+  }
+  const user = {id: 'u1', email: 'suriya@tenext.in', full_name: 'Suriya', role: 'owner', client_id: 'c1', client_name: 'TeNext Retail'}
+  const session = () => ({logged_in: st.logged_in, user: st.logged_in ? user : {}, site_name: st.claimed ? 'TeNext Chennai' : '', claimed: st.claimed, standalone: st.standalone && !st.claimed})
+  const now = () => new Date().toISOString()
+  const arrivals = () => st.cameras.length === 0 ? [] : [
+    {type: 'person.seen', ts: now(), camera_id: 'entrance', data: {label: 'Visitor 3', identity_id: 3, similarity: 0.61, gender: 'Male', age: 34, emotion: 'neutral'}},
+    {type: 'person.new', ts: new Date(Date.now() - 95e3).toISOString(), camera_id: 'entrance', data: {label: 'Visitor 7', identity_id: 7, gender: 'Female', age: 28}},
+    {type: 'person.seen', ts: new Date(Date.now() - 410e3).toISOString(), camera_id: 'entrance', data: {label: 'Priya', identity_id: 2, similarity: 0.72, gender: 'Female', age: 41}},
+  ]
+  const delay = (v, ms = 120) => new Promise(r => setTimeout(() => r(v), ms))
+  const App = {
+    Session: () => delay(session()),
+    Login: (email) => { st.logged_in = true; user.email = email || user.email; return delay(session()) },
+    Logout: () => { st.logged_in = false; return delay(session()) },
+    Claim: (code) => code.replace(/[^A-Z0-9]/gi, '').length >= 20
+      ? (st.claimed = true, st.standalone = false, delay(session(), 900))
+      : Promise.reject(new Error('That installation code is not valid. Ask for a new one.')),
+    RunStandalone: () => { st.standalone = true; return delay(session()) },
+    EngineStatus: () => {
+      // The engine takes a minute or two on first run (models download).
+      if (st.engine === 'starting' && Date.now() - st.startedAt > 20000) st.engine = 'running'
+      const cams = Object.fromEntries(st.cameras.map(c => [c.id, true]))
+      return delay({state: st.engine === 'starting' ? 'running' : 'running', reachable: st.engine !== 'starting', recognition_model: st.engine === 'starting' ? '' : 'w600k_r50', cameras: cams, restarts: 0})
+    },
+    StartEngine: () => delay({state: 'running', reachable: true}),
+    StopEngine: () => delay({state: 'stopped', reachable: false}),
+    Cameras: () => delay(st.cameras.map(c => ({...c, connected: true, frames: 1200, faces: 9}))),
+    DiscoverCameras: () => delay({networks: ['192.168.1.0/24'], cameras: [
+      {host: '192.168.1.122', rtsp: true, onvif: true, name: 'HIKVISION DS-2CD2043G2', make: 'hikvision'},
+      {host: '192.168.1.121', rtsp: true, onvif: true, name: 'IPC-model IPC', make: ''},
+      {host: '192.168.1.40', rtsp: true, onvif: false, name: '', make: ''},
+    ]}, 2500),
+    TestCamera: (cam) => delay({ok: Boolean(cam.host), width: 800, height: 448, codec: 'hevc', error: cam.host ? '' : 'no host'}, 1500),
+    SaveCamera: (id, cam) => { const c = {id: id || cam.id || 'cam' + (st.cameras.length + 1), ...cam, has_password: Boolean(cam.password)}; delete c.password; st.cameras = [...st.cameras.filter(x => x.id !== c.id), c]; return delay(c) },
+    DeleteCamera: (id) => { st.cameras = st.cameras.filter(c => c.id !== id); return delay(null) },
+    StartPlacementCheck: () => delay({state: 'running'}),
+    PlacementResult: () => delay({state: 'finished', verdict: 'good', headline: 'faces recognised on a walk-past', advice: []}),
+    StreamURL: () => '',
+    Live: () => delay({stats: {cameras: st.cameras.map(c => ({camera_id: c.id, connected: true, pipeline: {best_quality: {n: 40, fraction_below_gate: 0.18}}})), gallery: {identities: st.cameras.length ? 7 : 0, sightings: st.cameras.length ? 44 : 0}}, events: arrivals()}),
+    PipelineStatus: () => delay({webhook_url: 'http://127.0.0.1:53658/events', queued: 0, dropped: 0, claimed: st.claimed, standalone: st.standalone && !st.claimed, broker_up: st.claimed, accepted: st.claimed ? 12 : 0}),
+    LocalIdentities: () => delay([]), LocalSightings: () => delay([]),
+    Footfall: () => delay({total: 0, buckets: []}), Sites: () => delay([]),
+    VisitorHistory: () => delay([]), VisitorPhoto: () => delay({available: false, reason: 'This system is not storing images.'}),
+    ForgetCustomer: () => delay(null), Sales: () => delay([]),
+    Customers: () => delay([{id: 'v1', label: 'Priya', number: 2, first_seen_at: now(), last_seen_at: now(), visits: 6}]),
+    SaveProfile: () => delay(null), RecordPurchase: () => delay(null),
+    Ask: (history) => {
+      const q = history[history.length - 1]?.text ?? ''
+      if (!st.claimed) return Promise.reject(new Error('The assistant is not switched on for this server.'))
+      const text = /camera/i.test(q)
+        ? 'Go to Cameras and press Add camera. The address is on a sticker on the camera itself; pick the make and I fill in the stream path. Test it, save it, then walk past it once so I can tell you whether the placement works.'
+        : /code|install/i.test(q)
+          ? 'Whoever runs head office makes one: open the shop there, press Set up a shop PC, and read the code out. It works once.'
+          : /who|morning|came/i.test(q)
+            ? 'Three people so far: Priya at 13:12 (her sixth visit), a new face at 13:18 I have called Visitor 7, and Visitor 3 just now.'
+            : 'Chennai is online and the door camera is connected, but nobody has proved it yet. Walk past it once with Check placement running and I will tell you if it can actually see faces - until then a quiet screen might just be a badly aimed camera.'
+      return delay({text, used: /camera|code/i.test(q) ? [] : ['site_status', 'cameras']}, 1400)
+    },
+  }
+  window.go = {main: {App}}
+}

desktop/frontend/src/styles.css

@@ -1,252 +1,636 @@
-/* Behavision desktop — an instrument panel, not a website.
+/* Behavision desktop — a shop-floor instrument, not a website.
-   A shop PC runs this all day on a cheap monitor, so: high contrast, dense
+   ===========================================================================
-   but not cramped, and state readable at a glance from across a counter. */
+   Designed for one situation: a PC behind a counter, on a cheap monitor, in a
+   room with daylight, glanced at by somebody who is mid-conversation with a
+   customer. Everything below follows from that.
+
+   - Dark, because the screen sits in peripheral vision all day and a white
+     field at 1000 lux is a lamp pointed at the operator.
+   - State is carried by shape AND colour: a pill, a dot and an edge stripe,
+     never colour alone. This gets read from two metres away, and some
+     operators do not see red and green apart.
+   - One spacing scale and one type scale. The previous version set margins
+     inline, per screen, which is how a UI ends up looking assembled rather
+     than designed.
+   - Motion only where it carries meaning: a live camera, a fresh arrival.
+     Nothing loops for decoration — this process shares a CPU with recognition.
+   =========================================================================== */
 
 :root {
-  --ground:    #0E1317;
+  /* ground → raised, four steps, blue-green biased: the product lives in the
-  --surface:   #161D23;
+     world of lenses and CCTV, and a neutral grey reads as unfinished. */
-  --surface-2: #1D262D;
+  --bg:     #0A0F13;
-  --line:      #27333B;
+  --s1:     #111A20;
-  --line-soft: #1F2A31;
+  --s2:     #17232B;
-  --ink:       #E7EEF3;
+  --s3:     #1E2D37;
-  --ink-2:     #B4C2CC;
+  --line:   #223038;
-  --muted:     #7C8B97;
+  --line-2: #1A252C;
-  --accent:    #45B0C7;
+
-  --accent-dim:#123039;
+  --ink:   #ECF3F7;
-  --ok:        #4FB37B;
+  --ink-2: #A3B6C2;
-  --warn:      #E0A33A;
+  --ink-3: #6C808D;
-  --bad:       #E0655A;
+
-  --radius:    8px;
+  /* Accent is for state and focus only, never decoration, so that when it does
-  --mono: "SFMono-Regular", ui-monospace, Menlo, Consolas, monospace;
+     appear the eye goes to it. */
+  --accent:   #40C4DC;
+  --accent-2: #0F3B47;
+  --accent-3: #0B2A33;
+
+  --ok:     #48C78E;  --ok-2:   #102E22;
+  --warn:   #EAAA3D;  --warn-2: #31260F;
+  --bad:    #EC6A5C;  --bad-2:  #331815;
+
+  --r-sm: 6px; --r: 10px; --r-lg: 14px;
+
+  --sp-1: 4px;  --sp-2: 8px;  --sp-3: 12px; --sp-4: 16px;
+  --sp-5: 20px; --sp-6: 24px; --sp-7: 32px; --sp-8: 40px;
+
+  --shadow:    0 1px 2px rgb(0 0 0 / .4), 0 8px 24px -12px rgb(0 0 0 / .6);
+  --shadow-lg: 0 2px 4px rgb(0 0 0 / .4), 0 24px 48px -16px rgb(0 0 0 / .7);
+
+  /* Segoe UI Variable first: it is on every Windows 11 shop PC, it has real
+     optical sizes, and it is what makes this look like an application rather
+     than a web page in a frame. No webfont — a shop PC has no internet at
+     install time, and a font that fails to arrive is a layout that shifts
+     under the operator. */
+  --font: "Segoe UI Variable Text", "Segoe UI", Inter, -apple-system,
+          BlinkMacSystemFont, system-ui, "Helvetica Neue", Arial, sans-serif;
+  --font-display: "Segoe UI Variable Display", var(--font);
+  --mono: "Cascadia Mono", "SFMono-Regular", ui-monospace, Menlo, Consolas, monospace;
+
+  /* Kept as aliases so any screen not yet rewritten keeps its colours. */
+  --ground: var(--bg); --surface: var(--s1); --surface-2: var(--s2);
+  --line-soft: var(--line-2); --muted: var(--ink-3); --radius: var(--r);
+  --accent-dim: var(--accent-3);
 }
 
 * { box-sizing: border-box; margin: 0; }
 html, body, #root { height: 100%; }
+
 body {
-  background: var(--ground);
+  background: var(--bg);
   color: var(--ink);
-  font: 14px/1.55 system-ui, -apple-system, "Segoe UI", sans-serif;
+  font-family: var(--font);
+  font-size: 14px;
+  line-height: 1.5;
   -webkit-font-smoothing: antialiased;
+  text-rendering: optimizeLegibility;
   overflow: hidden;
   user-select: none;
 }
-button, input, select, textarea { font: inherit; color: inherit; }
-:focus-visible { outline: 2px solid var(--accent); outline-offset: 2px; }
 
-/* ---------------------------------------------------------------- shell -- */
+button, input, select, textarea { font: inherit; color: inherit; }
-.shell { display: grid; grid-template-columns: 216px 1fr; height: 100%; }
+input, textarea { user-select: text; }
+:focus-visible { outline: 2px solid var(--accent); outline-offset: 2px; border-radius: 3px; }
+::selection { background: var(--accent-2); color: var(--ink); }
+
+/* Digits that line up wherever they are compared or refreshed in place. */
+.num, .value, .metric-v, .when, .mono, .code, td { font-variant-numeric: tabular-nums; }
+.mono, .code { font-family: var(--mono); }
+
+/* The default light scrollbar on a dark panel is the most obvious "this is a
+   web page" tell there is. */
+* { scrollbar-width: thin; scrollbar-color: var(--s3) transparent; }
+*::-webkit-scrollbar { width: 10px; height: 10px; }
+*::-webkit-scrollbar-track { background: transparent; }
+*::-webkit-scrollbar-thumb { background: var(--s3); border-radius: 99px; border: 3px solid var(--bg); }
+*::-webkit-scrollbar-thumb:hover { background: #2A3D49; }
+
+/* ================================================================ shell == */
+
+.shell { display: grid; grid-template-columns: 232px 1fr auto; height: 100%; }
+
 .side {
-  background: var(--surface); border-right: 1px solid var(--line);
+  background: var(--s1); border-right: 1px solid var(--line);
   display: flex; flex-direction: column; min-height: 0;
 }
-.side .brand {
+.side .brand { display: flex; align-items: center; gap: var(--sp-3); padding: var(--sp-5) var(--sp-5) var(--sp-4); }
-  padding: 18px 18px 14px; border-bottom: 1px solid var(--line-soft);
+.side .brand .mark { width: 30px; height: 30px; flex: none; display: grid; place-items: center; }
-}
+.side .brand .mark img, .login .mark img { width: 100%; height: 100%; object-fit: contain; display: block; }
-.side .brand h1 { font-size: 15px; font-weight: 650; letter-spacing: -.01em; }
+.side .brand .id { min-width: 0; }
-.side .brand p { font-size: 11.5px; color: var(--muted); margin-top: 3px; }
+.side .brand h1 { font-family: var(--font-display); font-size: 15px; font-weight: 600; letter-spacing: -.012em; line-height: 1.2; }
-.nav { padding: 10px 10px; display: flex; flex-direction: column; gap: 2px; flex: 1; }
+.side .brand p { font-size: 11.5px; color: var(--ink-3); margin-top: 1px; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
+
+.nav { padding: var(--sp-2) var(--sp-3); display: flex; flex-direction: column; gap: 2px; flex: 1; }
 .nav button {
-  display: flex; align-items: center; gap: 10px; width: 100%;
+  position: relative; display: flex; align-items: center; gap: var(--sp-3); width: 100%;
-  background: none; border: 0; border-radius: 6px; padding: 8px 10px;
+  background: none; border: 0; border-radius: var(--r-sm); padding: 9px var(--sp-3);
-  color: var(--ink-2); cursor: pointer; text-align: left; font-size: 13.5px;
+  color: var(--ink-2); cursor: pointer; text-align: left; font-size: 13.5px; font-weight: 450;
+  transition: background .12s ease, color .12s ease;
 }
-.nav button:hover { background: var(--surface-2); color: var(--ink); }
+.nav button svg { flex: none; opacity: .9; }
-.nav button[aria-current="page"] { background: var(--accent-dim); color: var(--accent); font-weight: 550; }
+.nav button:hover { background: var(--s2); color: var(--ink); }
-.nav .glyph { width: 16px; text-align: center; opacity: .85; font-size: 13px; }
+.nav button[aria-current="page"] { background: var(--accent-3); color: var(--accent); font-weight: 550; }
-
+/* A rail, not a background wash: it survives being looked at sideways. */
-.enginebox { padding: 12px; border-top: 1px solid var(--line-soft); }
+.nav button[aria-current="page"]::before {
-.enginebox .row { display: flex; align-items: center; gap: 8px; font-size: 12px; }
+  content: ""; position: absolute; left: -12px; top: 7px; bottom: 7px;
-.enginebox .label { color: var(--muted); font-size: 11px; margin-top: 2px;
+  width: 2.5px; border-radius: 0 2px 2px 0; background: var(--accent);
-                    display: block; line-height: 1.4; }
-.enginebox .actions { display: flex; gap: 6px; margin-top: 10px; }
-
-.main { min-width: 0; min-height: 0; overflow-y: auto; }
-.page { padding: 22px 26px 40px; max-width: 1180px; }
-.page > header { margin-bottom: 18px; }
-.page h2 { font-size: 19px; font-weight: 620; letter-spacing: -.01em; }
-.page header p { color: var(--muted); font-size: 13px; margin-top: 3px; }
-
-/* --------------------------------------------------------------- pieces -- */
-.card {
-  background: var(--surface); border: 1px solid var(--line);
-  border-radius: var(--radius); padding: 16px;
 }
-.card h3 { font-size: 12px; text-transform: uppercase; letter-spacing: .07em;
-           color: var(--muted); font-weight: 600; margin-bottom: 12px; }
-.grid { display: grid; gap: 14px; }
-.cols-4 { grid-template-columns: repeat(auto-fit, minmax(190px, 1fr)); }
-.cols-2 { grid-template-columns: repeat(auto-fit, minmax(320px, 1fr)); }
 
-.stat .value { font-size: 30px; font-weight: 620; letter-spacing: -.02em;
+/* The one control that starts and stops the product, so it gets its own block
-               font-variant-numeric: tabular-nums; line-height: 1.1; }
+   at the foot rather than a row in a list. */
-.stat .unit  { font-size: 15px; color: var(--muted); margin-left: 3px; }
+.enginebox {
-.stat .sub   { color: var(--muted); font-size: 12px; margin-top: 5px; }
+  margin: var(--sp-3); padding: var(--sp-3) var(--sp-4) var(--sp-4);
+  border: 1px solid var(--line); border-radius: var(--r); background: var(--s2);
+}
+.enginebox .row { display: flex; align-items: center; gap: var(--sp-2); }
+.enginebox .state { font-size: 12.5px; font-weight: 600; letter-spacing: -.005em; }
+.enginebox .label { display: block; color: var(--ink-3); font-size: 11px; line-height: 1.45; margin-top: 3px; font-variant-numeric: tabular-nums; }
+.enginebox .actions, .enginebox .controls { display: flex; gap: var(--sp-2); margin-top: var(--sp-3); }
+.enginebox .actions .btn, .enginebox .controls .btn { flex: 1; justify-content: center; padding: 6px 8px; font-size: 12px; }
 
-.dot { width: 8px; height: 8px; border-radius: 50%; flex: none; }
+.side .who {
-.dot.ok { background: var(--ok); }
+  padding: var(--sp-3) var(--sp-5) var(--sp-5); border-top: 1px solid var(--line-2);
-.dot.warn { background: var(--warn); }
+  display: flex; align-items: center; gap: var(--sp-3);
-.dot.bad { background: var(--bad); }
+}
-.dot.idle { background: var(--muted); }
+.side .who .id { min-width: 0; flex: 1; }
+.side .who .id b { display: block; font-size: 12.5px; font-weight: 550; }
+.side .who .id span { display: block; font-size: 11px; color: var(--ink-3); overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
 
-.pill { display: inline-flex; align-items: center; gap: 5px; font-size: 11px;
+.main { min-width: 0; min-height: 0; overflow: auto; position: relative; }
-        padding: 3px 8px; border-radius: 99px; border: 1px solid var(--line);
+
-        color: var(--muted); white-space: nowrap; }
+/* ================================================================= page == */
-.pill.ok   { color: var(--ok);   border-color: #2b5c42; background: #12251b; }
+
-.pill.warn { color: var(--warn); border-color: #5c4a22; background: #241d0f; }
+.page { padding: var(--sp-6) var(--sp-7) var(--sp-8); max-width: 1500px; }
-.pill.bad  { color: var(--bad);  border-color: #5c2e2a; background: #241312; }
+.page > header { margin-bottom: var(--sp-5); }
+.page > header h2, .page h2 { font-family: var(--font-display); font-size: 22px; font-weight: 600; letter-spacing: -.02em; line-height: 1.2; }
+.page > header p, .page header p { color: var(--ink-3); font-size: 13px; margin-top: 3px; }
+
+.pagehead { display: flex; align-items: flex-start; justify-content: space-between; gap: var(--sp-4); margin-bottom: var(--sp-5); flex-wrap: wrap; }
+
+h3 { font-size: 11px; font-weight: 600; letter-spacing: .085em; text-transform: uppercase; color: var(--ink-3); }
+
+/* ================================================================ cards == */
+
+.card { background: var(--s1); border: 1px solid var(--line); border-radius: var(--r); padding: var(--sp-4); }
+.card > h3 { margin-bottom: var(--sp-3); }
+.card.flush { padding: 0; overflow: hidden; }
+
+.panel { background: var(--s1); border: 1px solid var(--line); border-radius: var(--r-lg); overflow: hidden; display: flex; flex-direction: column; min-height: 0; }
+.panel > .panelhead {
+  display: flex; align-items: center; justify-content: space-between; gap: var(--sp-3);
+  padding: var(--sp-3) var(--sp-4); border-bottom: 1px solid var(--line-2);
+  background: linear-gradient(var(--s2), var(--s1)); flex: none;
+}
+.panel > .panelhead h3 { margin: 0; }
+.panel > .panelbody { padding: var(--sp-4); min-height: 0; overflow: auto; }
+.panel > .panelbody.flush { padding: 0; }
+
+.grid { display: grid; gap: var(--sp-4); }
+.cols-2 { grid-template-columns: repeat(2, minmax(0, 1fr)); }
+.cols-3 { grid-template-columns: repeat(3, minmax(0, 1fr)); }
+.cols-4 { grid-template-columns: repeat(4, minmax(0, 1fr)); }
+@media (max-width: 1180px) { .cols-4 { grid-template-columns: repeat(2, minmax(0,1fr)); } }
+@media (max-width: 980px)  { .cols-2, .cols-3 { grid-template-columns: minmax(0,1fr); } }
+
+/* Four equal boxes used to dominate this screen. The numbers matter, but they
+   are not what anybody opens the app to see. */
+.metrics {
+  display: grid; grid-template-columns: repeat(auto-fit, minmax(152px, 1fr));
+  gap: 1px; background: var(--line); border: 1px solid var(--line);
+  border-radius: var(--r); overflow: hidden;
+}
+.metric { background: var(--s1); padding: var(--sp-3) var(--sp-4) var(--sp-4); }
+.metric .metric-k { font-size: 10.5px; font-weight: 600; letter-spacing: .085em; text-transform: uppercase; color: var(--ink-3); }
+.metric .metric-v { font-family: var(--font-display); font-size: 26px; font-weight: 600; letter-spacing: -.025em; line-height: 1.1; margin-top: 5px; }
+.metric .metric-s { font-size: 11.5px; color: var(--ink-3); margin-top: 3px; line-height: 1.4; }
+.metric.ok .metric-v { color: var(--ok); }
+.metric.warn .metric-v { color: var(--warn); }
+.metric.bad .metric-v { color: var(--bad); }
+
+/* legacy .stat, for screens not yet rewritten */
+.stat h3 { margin-bottom: var(--sp-2); }
+.stat .value { font-family: var(--font-display); font-size: 26px; font-weight: 600; letter-spacing: -.025em; line-height: 1.1; }
+.stat .unit { font-size: 15px; color: var(--ink-3); margin-left: 3px; }
+.stat .sub { font-size: 11.5px; color: var(--ink-3); margin-top: 4px; line-height: 1.4; }
+
+/* =============================================================== status == */
+
+.dot { width: 7px; height: 7px; border-radius: 99px; flex: none; background: var(--ink-3); }
+.dot.ok   { background: var(--ok);   box-shadow: 0 0 0 3px color-mix(in srgb, var(--ok) 18%, transparent); }
+.dot.warn { background: var(--warn); box-shadow: 0 0 0 3px color-mix(in srgb, var(--warn) 18%, transparent); }
+.dot.bad  { background: var(--bad);  box-shadow: 0 0 0 3px color-mix(in srgb, var(--bad) 18%, transparent); }
+.dot.idle { background: var(--ink-3); }
+
+/* A live camera is the one thing that should breathe: it is how an operator
+   knows the picture is not frozen. Everything else holds still. */
+.dot.live { background: var(--ok); animation: pulse 2.4s ease-in-out infinite; }
+@keyframes pulse {
+  0%, 100% { box-shadow: 0 0 0 0 color-mix(in srgb, var(--ok) 55%, transparent); }
+  70%      { box-shadow: 0 0 0 6px color-mix(in srgb, var(--ok) 0%, transparent); }
+}
+
+.pill {
+  display: inline-flex; align-items: center; gap: 6px; padding: 3px 9px 3px 7px;
+  border-radius: 99px; font-size: 11px; font-weight: 600; letter-spacing: .02em;
+  background: var(--s3); color: var(--ink-2); border: 1px solid var(--line); white-space: nowrap;
+}
+.pill.ok   { background: var(--ok-2);   color: var(--ok);   border-color: color-mix(in srgb, var(--ok) 28%, transparent); }
+.pill.warn { background: var(--warn-2); color: var(--warn); border-color: color-mix(in srgb, var(--warn) 28%, transparent); }
+.pill.bad  { background: var(--bad-2);  color: var(--bad);  border-color: color-mix(in srgb, var(--bad) 28%, transparent); }
+.pill.accent { background: var(--accent-3); color: var(--accent); border-color: color-mix(in srgb, var(--accent) 30%, transparent); }
+
+.tag {
+  display: inline-flex; align-items: center; padding: 2px 7px; border-radius: var(--r-sm);
+  font-size: 10.5px; font-weight: 600; letter-spacing: .04em; text-transform: uppercase;
+  background: var(--s3); color: var(--ink-2);
+}
+.tag.new  { background: var(--accent-3); color: var(--accent); }
+.tag.seen { background: var(--ok-2); color: var(--ok); }
+.tag.miss { background: var(--warn-2); color: var(--warn); }
+
+/* One line that answers "is this shop working" above everything else. */
+.statusbar {
+  display: flex; align-items: center; gap: var(--sp-5); flex-wrap: wrap;
+  padding: var(--sp-3) var(--sp-4); background: var(--s1);
+  border: 1px solid var(--line); border-radius: var(--r); margin-bottom: var(--sp-4);
+}
+.statusbar .item { display: flex; align-items: center; gap: var(--sp-2); font-size: 12.5px; }
+.statusbar .item b { font-weight: 600; letter-spacing: -.005em; }
+.statusbar .item svg { color: var(--ink-3); }
+.statusbar .sep { width: 1px; align-self: stretch; background: var(--line); }
+.statusbar .grow { flex: 1; }
+
+/* ============================================================= arrivals == */
+
+/* The reason the product exists, so it gets the width and the weight. */
+.arrivals { display: flex; flex-direction: column; gap: var(--sp-2); padding: var(--sp-3); }
+
+.arrival {
+  display: grid; grid-template-columns: 46px 1fr auto; gap: var(--sp-3); align-items: center;
+  padding: var(--sp-3); border-radius: var(--r);
+  background: var(--s2); border: 1px solid var(--line-2);
+  position: relative; overflow: hidden;
+}
+.arrival::before { content: ""; position: absolute; left: 0; top: 0; bottom: 0; width: 2.5px; background: var(--ink-3); }
+.arrival.is-new::before  { background: var(--accent); }
+.arrival.is-seen::before { background: var(--ok); }
+.arrival.is-miss::before { background: var(--warn); }
+
+/* Only the newest row animates, and only once. */
+.arrival.fresh { animation: slidein .28s cubic-bezier(.2,.8,.3,1); }
+@keyframes slidein { from { opacity: 0; transform: translateY(-6px); } to { opacity: 1; transform: none; } }
+
+.arrival .avatar {
+  width: 46px; height: 46px; border-radius: var(--r-sm); display: grid; place-items: center;
+  overflow: hidden; background: var(--s3); border: 1px solid var(--line);
+  font-family: var(--font-display); font-size: 15px; font-weight: 600;
+  color: var(--ink-2); letter-spacing: -.01em; font-variant-numeric: tabular-nums;
+}
+.arrival .avatar img { width: 100%; height: 100%; object-fit: cover; }
+.arrival.is-new .avatar { background: var(--accent-3); color: var(--accent); border-color: color-mix(in srgb, var(--accent) 25%, transparent); }
+
+.arrival .who { min-width: 0; }
+.arrival .who .name { font-size: 14.5px; font-weight: 600; letter-spacing: -.01em; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
+.arrival .who .meta { font-size: 11.5px; color: var(--ink-3); margin-top: 2px; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
+.arrival .right { text-align: right; display: flex; flex-direction: column; align-items: flex-end; gap: 5px; }
+.arrival .right .when { font-size: 11.5px; color: var(--ink-3); }
+
+/* ================================================================ feeds == */
+
+.feeds { display: grid; gap: var(--sp-3); grid-template-columns: repeat(auto-fit, minmax(300px, 1fr)); padding: var(--sp-3); }
+
+.feed { position: relative; border-radius: var(--r); overflow: hidden; background: #05090C; border: 1px solid var(--line); aspect-ratio: 16 / 9; }
+.feed img { width: 100%; height: 100%; object-fit: cover; display: block; }
+.feed .placeholder { width: 100%; height: 100%; display: grid; place-items: center; color: var(--ink-3); }
+/* Caption over the picture, not beneath it: the tile stays a picture. */
+.feed .cap {
+  position: absolute; left: 0; right: 0; bottom: 0;
+  display: flex; align-items: center; justify-content: space-between; gap: var(--sp-2);
+  padding: var(--sp-5) var(--sp-3) var(--sp-3);
+  background: linear-gradient(transparent, rgb(0 0 0 / .8));
+  font-size: 12.5px; font-weight: 600; letter-spacing: -.005em;
+}
+
+/* ================================================================ lists == */
+
+.events, .timeline { list-style: none; padding: 0; display: flex; flex-direction: column; }
+.events li { display: flex; align-items: center; gap: var(--sp-3); padding: 9px var(--sp-4); border-bottom: 1px solid var(--line-2); font-size: 13px; }
+.timeline li { display: flex; align-items: center; gap: var(--sp-3); padding: 9px 0; border-bottom: 1px solid var(--line-2); font-size: 13px; }
+.events li:last-child, .timeline li:last-child { border-bottom: 0; }
+.events .when, .timeline .when { font-size: 11.5px; color: var(--ink-3); width: 46px; flex: none; }
+
+.empty {
+  display: flex; flex-direction: column; align-items: center; justify-content: center;
+  gap: var(--sp-3); padding: var(--sp-8) var(--sp-5); color: var(--ink-3); text-align: center; font-size: 12.5px;
+}
+.empty svg { opacity: .35; }
+.empty b { display: block; color: var(--ink-2); font-size: 13.5px; font-weight: 550; }
+.empty p { max-width: 34ch; line-height: 1.5; }
+
+.tablewrap { overflow: auto; }
+table { border-collapse: collapse; width: 100%; font-size: 13px; }
+th {
+  text-align: left; padding: 9px var(--sp-4); font-size: 10.5px; font-weight: 600;
+  letter-spacing: .085em; text-transform: uppercase; color: var(--ink-3);
+  background: var(--s2); border-bottom: 1px solid var(--line); position: sticky; top: 0; z-index: 1;
+}
+td { padding: 10px var(--sp-4); border-bottom: 1px solid var(--line-2); }
+tbody tr:last-child td { border-bottom: 0; }
+tbody tr[role="button"], tbody tr.clickable { cursor: pointer; }
+tbody tr[role="button"]:hover, tbody tr.clickable:hover { background: var(--s2); }
+
+/* ============================================================= controls == */
 
 .btn {
-  background: var(--surface-2); border: 1px solid var(--line);
+  display: inline-flex; align-items: center; gap: 7px; padding: 8px 14px;
-  border-radius: 6px; padding: 7px 13px; cursor: pointer; font-size: 13px;
+  border-radius: var(--r-sm); background: var(--s3); color: var(--ink);
-  color: var(--ink); white-space: nowrap;
+  border: 1px solid var(--line); cursor: pointer;
+  font-size: 13px; font-weight: 550; letter-spacing: -.005em; white-space: nowrap;
+  transition: background .12s ease, border-color .12s ease, transform .06s ease;
 }
-.btn:hover:not(:disabled) { background: #26323a; }
+.btn:hover:not(:disabled) { background: #253643; border-color: #2E414E; }
-.btn:disabled { opacity: .45; cursor: default; }
+.btn:active:not(:disabled) { transform: translateY(.5px); }
-.btn.primary { background: var(--accent); border-color: var(--accent); color: #06222a;
+.btn:disabled { opacity: .45; cursor: not-allowed; }
-               font-weight: 600; }
+.btn svg { flex: none; }
-.btn.primary:hover:not(:disabled) { background: #5ac0d6; }
+.btn.primary { background: var(--accent); color: #04171C; border-color: transparent; font-weight: 600; }
-.btn.danger { color: var(--bad); border-color: #4a2823; }
+.btn.primary:hover:not(:disabled) { background: #55D0E6; }
-.btn.sm { padding: 4px 9px; font-size: 12px; }
+.btn.danger { background: var(--bad-2); color: var(--bad); border-color: color-mix(in srgb, var(--bad) 32%, transparent); }
+.btn.danger:hover:not(:disabled) { background: #43201C; }
+.btn.ghost { background: transparent; }
+.btn.ghost:hover:not(:disabled) { background: var(--s2); }
+.btn.sm { padding: 5px 10px; font-size: 12px; }
+.btn.icon { padding: 7px; }
 
-.field { display: block; margin-bottom: 12px; }
+.linkbtn { background: none; border: 0; color: var(--accent); cursor: pointer; font-size: 12.5px; padding: 2px 0; text-align: left; }
-.field span { display: block; font-size: 11.5px; color: var(--muted);
+.linkbtn:hover { text-decoration: underline; }
-              margin-bottom: 4px; letter-spacing: .01em; }
+
+.seg { display: inline-flex; background: var(--s2); border: 1px solid var(--line); border-radius: var(--r-sm); padding: 2px; gap: 2px; }
+.seg button { background: none; border: 0; border-radius: 4px; padding: 5px 11px; color: var(--ink-3); cursor: pointer; font-size: 12.5px; font-weight: 500; }
+.seg button[aria-pressed="true"] { background: var(--s3); color: var(--ink); }
+
+/* ================================================================ forms == */
+
+.field { display: block; margin-bottom: var(--sp-4); }
+.field > span { display: block; font-size: 11.5px; font-weight: 550; color: var(--ink-2); margin-bottom: 6px; }
 .field input, .field select, .field textarea {
-  width: 100%; background: var(--ground); border: 1px solid var(--line);
+  width: 100%; padding: 9px 11px; background: var(--s2); color: var(--ink);
-  border-radius: 6px; padding: 8px 10px; font-size: 13.5px;
+  border: 1px solid var(--line); border-radius: var(--r-sm);
-  user-select: text;
+  transition: border-color .12s ease, background .12s ease, box-shadow .12s ease;
 }
+.field input::placeholder { color: var(--ink-3); }
+.field input:hover, .field select:hover, .field textarea:hover { border-color: #2C3D49; }
 .field input:focus, .field select:focus, .field textarea:focus {
-  border-color: var(--accent); outline: none;
+  outline: none; border-color: var(--accent); background: var(--s1); box-shadow: 0 0 0 3px var(--accent-3);
 }
-.field textarea { resize: vertical; min-height: 66px; }
+.field .hint { display: block; font-size: 11.5px; color: var(--ink-3); margin-top: 5px; line-height: 1.45; }
-.fieldrow { display: grid; gap: 0 12px; grid-template-columns: 1fr 1fr; }
 
-table { width: 100%; border-collapse: collapse; font-size: 13px; }
+.fieldrow { display: grid; grid-template-columns: repeat(2, minmax(0,1fr)); gap: var(--sp-3); }
-th { text-align: left; font-size: 10.5px; text-transform: uppercase;
+.fieldrow.three { grid-template-columns: repeat(3, minmax(0,1fr)); }
-     letter-spacing: .08em; color: var(--muted); font-weight: 600;
-     padding: 8px 10px; border-bottom: 1px solid var(--line); }
-td { padding: 9px 10px; border-bottom: 1px solid var(--line-soft); vertical-align: middle; }
-tr:last-child td { border-bottom: 0; }
-tbody tr.click { cursor: pointer; }
-tbody tr.click:hover { background: var(--surface-2); }
-td.num { font-variant-numeric: tabular-nums; text-align: right; }
-.tablewrap { overflow-x: auto; }
 
-.empty { color: var(--muted); font-size: 13px; padding: 26px 4px; text-align: center; }
 .err {
-  border: 1px solid #5c2e2a; background: #241312; color: #f0b3ad;
+  display: flex; align-items: flex-start; gap: var(--sp-2);
-  border-radius: 6px; padding: 10px 12px; font-size: 13px; margin-bottom: 14px;
+  background: var(--bad-2); color: var(--bad);
+  border: 1px solid color-mix(in srgb, var(--bad) 30%, transparent);
+  border-radius: var(--r-sm); padding: 9px 11px; font-size: 12.5px; line-height: 1.45; margin-bottom: var(--sp-4);
 }
-.note { color: var(--muted); font-size: 12.5px; }
+.err svg { flex: none; margin-top: 1px; }
-.mono { font-family: var(--mono); font-size: 12px; }
 
-/* --------------------------------------------------------------- login --- */
+.note { color: var(--ink-3); font-size: 12px; line-height: 1.5; }
-.login { height: 100%; display: grid; place-items: center; padding: 24px; }
+.note.warn { color: var(--warn); }
-.login .box { width: 100%; max-width: 380px; }
+.note.bad { color: var(--bad); }
-.login h1 { font-size: 21px; font-weight: 650; letter-spacing: -.015em; }
+.lead { color: var(--ink-2); font-size: 13.5px; line-height: 1.55; }
-.login .lead { color: var(--muted); font-size: 13px; margin: 6px 0 22px; }
+.sm { font-size: 12px; }
-.login form { background: var(--surface); border: 1px solid var(--line);
+.lbl, .key { color: var(--ink-3); font-size: 11.5px; }
-              border-radius: 10px; padding: 20px; }
+.grow { flex: 1; }
-.login .btn { width: 100%; margin-top: 6px; }
+.row { display: flex; align-items: center; gap: var(--sp-3); }
-.login .foot { color: var(--muted); font-size: 11.5px; margin-top: 14px;
+
-               text-align: center; line-height: 1.5; }
+/* ================================================================= gate == */
-/* The second way out of the setup screen: a shop with no head office. Styled
+
-   quieter than the form above it because linking is still the common case,
+/* Login and Setup: the first thing anybody sees, and previously a grey box on
-   but present, because for a single-till shop it is the only one that works. */
+   a grey field. One soft light behind the card gives the window a centre and
-.login .alt { margin-top: 18px; padding-top: 16px; text-align: center;
+   costs nothing — it is a static gradient, not an animation. */
-              border-top: 1px solid var(--line-soft); }
+.login {
-.login .alt .note { line-height: 1.55; margin-bottom: 12px; text-align: left; }
+  height: 100%; display: grid; place-items: center; padding: var(--sp-6); overflow: auto;
+  background: radial-gradient(900px 480px at 50% -10%, #10303A 0%, transparent 62%), var(--bg);
+}
+.login .box {
+  width: 100%; max-width: 396px; background: var(--s1); border: 1px solid var(--line);
+  border-radius: var(--r-lg); padding: var(--sp-7); box-shadow: var(--shadow-lg);
+}
+.login .mark { width: 44px; height: 44px; margin-bottom: var(--sp-4); display: grid; place-items: center; }
+.login h1 { font-family: var(--font-display); font-size: 21px; font-weight: 600; letter-spacing: -.022em; }
+.login .lead { margin: 6px 0 var(--sp-5); }
+.login .btn { width: 100%; justify-content: center; margin-top: var(--sp-1); }
+.login .foot { font-size: 11.5px; color: var(--ink-3); line-height: 1.55; margin-top: var(--sp-5); padding-top: var(--sp-4); border-top: 1px solid var(--line-2); }
+.login .alt { margin-top: var(--sp-4); display: flex; flex-direction: column; gap: var(--sp-3); }
 .login .alt .btn { margin-top: 0; }
-.linkbtn { background: none; border: 0; padding: 0; cursor: pointer;
+.login .note { margin: 0; }
-           font: inherit; font-size: 12.5px; color: var(--accent);
-           text-decoration: underline; text-underline-offset: 3px; }
-.linkbtn:hover { color: var(--ink); }
 
-/* ---------------------------------------------------------------- live --- */
+/* =============================================================== drawer == */
-.feeds { display: grid; gap: 14px; grid-template-columns: repeat(auto-fit, minmax(300px, 1fr)); }
-.feed { background: #000; border: 1px solid var(--line); border-radius: var(--radius);
-        overflow: hidden; }
-.feed img { width: 100%; display: block; aspect-ratio: 16/9; object-fit: cover; background: #000; }
-.feed .cap { display: flex; justify-content: space-between; align-items: center;
-             padding: 8px 11px; background: var(--surface); font-size: 12.5px; }
 
-.events { list-style: none; max-height: 420px; overflow-y: auto; }
+.drawer { position: fixed; inset: 0; z-index: 40; background: rgb(4 8 11 / .6); display: flex; justify-content: flex-end; animation: fade .16s ease; }
-.events li { display: flex; gap: 9px; align-items: baseline;
+@keyframes fade { from { opacity: 0 } to { opacity: 1 } }
-             padding: 7px 2px; border-bottom: 1px solid var(--line-soft); font-size: 12.5px; }
+.drawer .sheet {
-.events li:last-child { border-bottom: 0; }
+  width: min(540px, 100%); height: 100%; overflow: auto;
-.events .when { color: var(--muted); font-family: var(--mono); font-size: 11px;
+  background: var(--s1); border-left: 1px solid var(--line); box-shadow: var(--shadow-lg);
-                flex: none; }
+  animation: slidein-r .2s cubic-bezier(.2,.8,.3,1);
-.tag { font-size: 10px; padding: 2px 6px; border-radius: 4px; flex: none;
+}
-       background: var(--surface-2); color: var(--muted); }
+@keyframes slidein-r { from { transform: translateX(16px); opacity: .6 } to { transform: none; opacity: 1 } }
-.tag.new  { background: #17364f; color: #86c2ec; }
+.drawer .sheethead {
-.tag.seen { background: #14301f; color: #7fcb9c; }
+  position: sticky; top: 0; z-index: 1; display: flex; align-items: center; justify-content: space-between;
-.tag.miss { background: #3a1c1a; color: #eb9a92; }
+  gap: var(--sp-3); padding: var(--sp-4) var(--sp-5); background: var(--s1); border-bottom: 1px solid var(--line);
+}
+.drawer .sheethead h2 { font-family: var(--font-display); font-size: 17px; font-weight: 600; letter-spacing: -.015em; }
+.drawer .sheetbody { padding: var(--sp-5); }
+.drawer .close { background: none; border: 0; color: var(--ink-3); cursor: pointer; padding: 6px; border-radius: var(--r-sm); display: grid; place-items: center; }
+.drawer .close:hover { background: var(--s2); color: var(--ink); }
 
-/* -------------------------------------------------------------- charts --- */
+.avatar {
-.bars { display: flex; align-items: flex-end; gap: 3px; height: 150px; margin-top: 4px; }
+  width: 44px; height: 44px; border-radius: var(--r-sm); flex: none; display: grid; place-items: center;
-.bars .col { flex: 1; display: flex; flex-direction: column; justify-content: flex-end;
+  overflow: hidden; background: var(--s3); border: 1px solid var(--line);
-             gap: 2px; min-width: 0; }
+  font-weight: 600; color: var(--ink-2); font-variant-numeric: tabular-nums;
-.bars .seg { border-radius: 2px 2px 0 0; }
+}
-.bars .seg.ret { background: var(--accent); }
+.avatar img { width: 100%; height: 100%; object-fit: cover; }
-.bars .seg.new { background: #2f6f81; }
-.axis { display: flex; justify-content: space-between; color: var(--muted);
-        font-size: 10.5px; margin-top: 6px; font-family: var(--mono); }
-.key { display: flex; gap: 14px; font-size: 11.5px; color: var(--muted); margin-top: 10px; }
-.key i { display: inline-block; width: 9px; height: 9px; border-radius: 2px;
-         margin-right: 5px; vertical-align: -1px; }
 
-/* --------------------------------------------------------------- drawer -- */
+@media (prefers-reduced-motion: reduce) {
-.drawer { position: fixed; inset: 0; background: rgba(4,8,10,.6);
+  *, *::before, *::after { animation: none !important; transition: none !important; }
-          display: flex; justify-content: flex-end; z-index: 30; }
+}
-.drawer .panel { width: min(480px, 100%); height: 100%; background: var(--surface);
-                 border-left: 1px solid var(--line); overflow-y: auto; padding: 20px 22px 40px; }
-.drawer h3 { font-size: 16px; font-weight: 620; text-transform: none;
-             letter-spacing: -.01em; color: var(--ink); margin-bottom: 2px; }
-/* Close lives in the sticky header (.who) now. Positioned against the fixed
-   overlay it stayed put while the sheet scrolled underneath it, printing the
-   button on top of whatever happened to be at the top of the viewport. */
 
-/* -- customer record ---------------------------------------------------- */
+/* Cameras and arrivals side by side, the same height, each scrolling its own
-/* Full-bleed sticky header: a customer record is long enough to scroll, and
+   content. Left to itself the arrivals panel shrank to fit two cards and left
-   both the name and the way out have to stay reachable. The negative margins
+   a hole beside a tall camera tile - the layout looked broken precisely when
-   cancel the panel's padding so the background covers the full width. */
+   the shop was quiet, which is most of the time. */
-.who { position: sticky; top: -20px; z-index: 1; display: flex; gap: 14px;
+.live-split {
-       align-items: flex-start; background: var(--surface);
+  display: grid; gap: var(--sp-4);
-       margin: -20px -22px 18px; padding: 20px 22px 14px;
+  grid-template-columns: minmax(0, 1.35fr) minmax(0, 1fr);
-       border-bottom: 1px solid var(--line-soft); }
+  align-items: stretch;
-.who .grow { flex: 1; min-width: 0; }
+  min-height: 420px;
-.who h3 { margin-bottom: 2px; }
+}
-.avatar { width: 64px; height: 64px; border-radius: 10px; flex: none;
+.live-split > .panel { max-height: 62vh; }
-          object-fit: cover; background: var(--ground);
+@media (max-width: 1100px) {
-          border: 1px solid var(--line); }
+  .live-split { grid-template-columns: minmax(0, 1fr); }
-.avatar.none { display: grid; place-items: center; color: var(--muted);
+  .live-split > .panel { max-height: none; }
-               font-size: 20px; font-weight: 600; letter-spacing: .02em; }
+}
 
-.timeline { list-style: none; max-height: 220px; overflow-y: auto; }
+/* Arrivals alone on the Live screen: one column, capped so a long day scrolls
-.timeline li { display: flex; gap: 10px; align-items: baseline; padding: 6px 0;
+   inside the panel rather than pushing the metrics off the bottom. */
-               border-bottom: 1px solid var(--line-soft); font-size: 12.5px; }
+.arrivals-panel { max-height: 64vh; margin-bottom: var(--sp-4); }
-.timeline li:last-child { border-bottom: 0; }
+.arrivals-panel .arrivals { display: grid; grid-template-columns: repeat(auto-fill, minmax(340px, 1fr)); gap: var(--sp-2); }
-.timeline .when { font-family: var(--mono); font-size: 11px; color: var(--muted);
-                  flex: none; min-width: 108px; }
-.timeline .where { flex: 1; min-width: 0; overflow: hidden;
-                   text-overflow: ellipsis; white-space: nowrap; }
 
-/* Visually separated from Save: this is the one control in the sheet that
+/* =============================================================== cameras == */
-   cannot be undone, and it must not read as just another button in a row. */
-.danger-zone { margin-top: 22px; border-color: #4a2823; }
-.danger-zone > h3 { color: var(--bad); }
-.danger-zone .note { margin-bottom: 10px; }
 
-.confirm h4 { font-size: 13.5px; font-weight: 620; margin-bottom: 10px; }
+.pagehead { display: flex; justify-content: space-between; align-items: flex-end; gap: var(--sp-4); }
-.confirm .cols { display: grid; grid-template-columns: 1fr 1fr; gap: 14px;
+.page > header.pagehead { margin-bottom: var(--sp-5); }
-                 margin-bottom: 12px; }
+
-@media (max-width: 560px) { .confirm .cols { grid-template-columns: 1fr; } }
+.camgrid { display: grid; gap: var(--sp-4); grid-template-columns: repeat(auto-fill, minmax(440px, 1fr)); }
-.confirm .lbl { font-size: 11px; text-transform: uppercase; letter-spacing: .07em;
+.camcard { background: var(--s1); border: 1px solid var(--line); border-radius: var(--r-lg); overflow: hidden; display: flex; flex-direction: column; }
-                color: var(--muted); margin-bottom: 5px; }
+.camview { position: relative; aspect-ratio: 16 / 9; background: #05090C; }
-.confirm .lbl.bad { color: var(--bad); }
+.camview img { width: 100%; height: 100%; object-fit: cover; display: block; }
-.confirm ul { list-style: none; font-size: 12.5px; }
+.camview .placeholder { width: 100%; height: 100%; display: grid; place-items: center; color: var(--ink-3); }
-.confirm li { padding: 3px 0 3px 12px; position: relative; color: var(--ink); }
+.camview .pill.over { position: absolute; top: 10px; right: 10px; backdrop-filter: blur(6px); }
-.confirm li::before { content: '·'; position: absolute; left: 2px;
+.cambody { padding: var(--sp-4); display: flex; flex-direction: column; gap: var(--sp-3); }
-                      color: var(--muted); }
+.camtitle { display: flex; justify-content: space-between; align-items: flex-start; gap: var(--sp-3); }
-.confirm .row { display: flex; gap: 8px; }
+.camtitle h3 { font-family: var(--font-display); font-size: 16px; font-weight: 600; letter-spacing: -.012em; text-transform: none; color: var(--ink); margin: 0 0 2px; }
+.camtitle .note { font-size: 12px; }
+.camactions { display: flex; gap: 6px; flex: none; }
+.camproof { display: grid; grid-template-columns: auto 1fr auto; align-items: center; gap: var(--sp-3);
+  padding: var(--sp-3); border-radius: var(--r); background: var(--s2); border: 1px solid var(--line-2); }
+.camproof .note { font-size: 12px; line-height: 1.45; }
+@media (max-width: 640px) { .camproof { grid-template-columns: 1fr; } }
+
+.empty.tall { padding: var(--sp-8) var(--sp-6); }
+.empty.tall .btn { margin-top: var(--sp-3); }
+
+/* The sheet is a form that reads top to bottom: a sentence saying what is
+   needed, three short sections, the result of the test, the actions. */
+.drawer .sheet { width: min(600px, 100%); }
+.sheetbody .lead { color: var(--ink-2); font-size: 13.5px; line-height: 1.55; margin-bottom: var(--sp-5); }
+.formsection { margin-bottom: var(--sp-5); }
+.formsection h4 { font-size: 11px; font-weight: 600; letter-spacing: .09em; text-transform: uppercase; color: var(--ink-3); margin: 0 0 var(--sp-3); padding-bottom: 6px; border-bottom: 1px solid var(--line-2); }
+.field .hint { font-style: normal; }
+.fieldrow { grid-template-columns: minmax(0, 1fr) minmax(0, 1fr); }
+.fieldrow .field.narrow { max-width: 140px; }
+.fieldrow:has(.field.narrow) { grid-template-columns: minmax(0, 1fr) 140px; }
+.field input.mono { font-family: var(--font-mono); font-size: 12.5px; }
+.sheetactions { display: flex; gap: var(--sp-2); justify-content: flex-end; padding-top: var(--sp-4); border-top: 1px solid var(--line-2); margin-top: var(--sp-2); }
+.testresult { display: flex; gap: var(--sp-3); align-items: flex-start; padding: var(--sp-3) var(--sp-4); border-radius: var(--r); margin-bottom: var(--sp-4); border: 1px solid; font-size: 13px; }
+.testresult.ok { background: var(--ok-2); border-color: color-mix(in srgb, var(--ok) 30%, transparent); color: var(--ok); }
+.testresult.bad { background: var(--bad-2); border-color: color-mix(in srgb, var(--bad) 30%, transparent); color: var(--bad); }
+.testresult b { display: block; }
+.testresult span { display: block; color: var(--ink-2); margin-top: 2px; }
+.testresult img { width: 100%; margin-top: var(--sp-3); border-radius: var(--r-sm); border: 1px solid var(--line); display: block; }
+
+/* Placement check: two numbered steps, then a verdict box in the tone of the answer. */
+.steps { list-style: none; counter-reset: step; margin: 0 0 var(--sp-5); padding: 0; display: grid; gap: var(--sp-3); }
+.steps li { counter-increment: step; position: relative; padding: var(--sp-3) var(--sp-4) var(--sp-3) 52px; border-radius: var(--r); border: 1px solid var(--line-2); background: var(--s2); opacity: .55; }
+.steps li.now, .steps li.done { opacity: 1; }
+.steps li::before { content: counter(step); position: absolute; left: 16px; top: 14px; width: 24px; height: 24px; border-radius: 50%;
+  display: grid; place-items: center; font-size: 12px; font-weight: 600; background: var(--s3); color: var(--ink-2); border: 1px solid var(--line); }
+.steps li.now::before { background: var(--accent); color: #041014; border-color: transparent; }
+.steps li.done::before { content: '✓'; background: var(--ok-2); color: var(--ok); }
+.steps b { display: block; font-size: 14px; }
+.steps span { display: block; font-size: 12.5px; color: var(--ink-2); line-height: 1.5; margin-top: 2px; }
+.progress { height: 4px; background: var(--s3); border-radius: 2px; overflow: hidden; margin-top: var(--sp-3); }
+.progress > div { height: 100%; background: var(--accent); transition: width .4s linear; }
+.verdict { padding: var(--sp-4); border-radius: var(--r); border: 1px solid var(--line); background: var(--s2); }
+.verdict.ok { border-color: color-mix(in srgb, var(--ok) 35%, transparent); background: var(--ok-2); }
+.verdict.warn { border-color: color-mix(in srgb, var(--warn) 35%, transparent); background: var(--warn-2); }
+.verdict.bad { border-color: color-mix(in srgb, var(--bad) 35%, transparent); background: var(--bad-2); }
+.verdict-head { display: flex; align-items: center; gap: var(--sp-2); font-size: 15px; }
+.verdict.ok .verdict-head { color: var(--ok); } .verdict.warn .verdict-head { color: var(--warn); } .verdict.bad .verdict-head { color: var(--bad); }
+.verdict ul { margin: var(--sp-3) 0 0 18px; font-size: 13px; color: var(--ink); line-height: 1.5; }
+.verdict ul li { margin-bottom: 5px; }
+.verdict .note { margin-top: var(--sp-3); }
+.spinner { width: 16px; height: 16px; border-radius: 50%; border: 2px solid var(--line); border-top-color: var(--accent); animation: spin .8s linear infinite; display: inline-block; }
+@keyframes spin { to { transform: rotate(360deg) } }
+
+/* ============================================================== assistant == */
+
+.helpbtn { display: flex; align-items: center; gap: 9px; margin: 0 var(--sp-3) var(--sp-3); padding: 9px 10px; border-radius: var(--r);
+  border: 1px solid var(--line); background: var(--s2); color: var(--ink); cursor: pointer; font-size: 12.5px; font-weight: 550; text-align: left; }
+.helpbtn img { width: 18px; height: 18px; object-fit: contain; }
+.helpbtn span { flex: 1; }
+.helpbtn:hover, .helpbtn[aria-pressed="true"] { border-color: color-mix(in srgb, var(--accent) 45%, transparent); background: var(--accent-3); }
+
+.helper { width: 380px; height: 100%; display: flex; flex-direction: column; min-height: 0;
+  background: var(--s1); border-left: 1px solid var(--line); animation: slidein-r .2s cubic-bezier(.2,.8,.3,1); }
+.helperhead { display: flex; align-items: center; gap: var(--sp-3); padding: var(--sp-4); border-bottom: 1px solid var(--line); }
+.helperhead img { width: 26px; height: 26px; object-fit: contain; }
+.helperhead div { flex: 1; min-width: 0; }
+.helperhead b { display: block; font-family: var(--font-display); font-size: 14.5px; }
+.helperhead span { display: block; font-size: 11.5px; color: var(--ink-3); margin-top: 1px; }
+.helperhead .close { background: none; border: 0; color: var(--ink-3); cursor: pointer; padding: 6px; border-radius: var(--r-sm); display: grid; place-items: center; }
+.helperhead .close:hover { background: var(--s2); color: var(--ink); }
+.helperbody { flex: 1; overflow: auto; padding: var(--sp-4); display: flex; flex-direction: column; gap: var(--sp-3); }
+.helperintro p { color: var(--ink-2); font-size: 13px; line-height: 1.55; margin-bottom: var(--sp-3); }
+.chips { display: flex; flex-wrap: wrap; gap: 6px; }
+.chip { border: 1px solid var(--line); background: var(--s2); color: var(--ink); border-radius: 99px; padding: 6px 11px; font-size: 12px; cursor: pointer; text-align: left; }
+.chip:hover { border-color: var(--accent); color: var(--accent); }
+.chip:disabled { opacity: .5; cursor: default; }
+.helpernote { display: flex; gap: var(--sp-3); padding: var(--sp-3); border-radius: var(--r); background: var(--warn-2); border: 1px solid color-mix(in srgb, var(--warn) 30%, transparent); color: var(--warn); font-size: 12.5px; }
+.helpernote b { display: block; } .helpernote span { display: block; color: var(--ink-2); margin-top: 2px; line-height: 1.45; }
+.turn { display: flex; flex-direction: column; gap: 4px; }
+.turn.user { align-items: flex-end; }
+.bubble { max-width: 92%; padding: 10px 13px; border-radius: 14px; font-size: 13.5px; line-height: 1.5; white-space: pre-wrap; }
+.turn.user .bubble { background: var(--accent); color: #041014; border-bottom-right-radius: 4px; }
+.turn.assistant .bubble { background: var(--s2); border: 1px solid var(--line); border-bottom-left-radius: 4px; }
+.turn .used { font-size: 11px; color: var(--ink-3); padding: 0 4px; }
+.bubble.thinking { display: flex; gap: 4px; padding: 12px 14px; }
+.bubble.thinking span { width: 6px; height: 6px; border-radius: 50%; background: var(--ink-3); animation: blink 1.2s infinite ease-in-out; }
+.bubble.thinking span:nth-child(2) { animation-delay: .2s } .bubble.thinking span:nth-child(3) { animation-delay: .4s }
+@keyframes blink { 0%, 80%, 100% { opacity: .25 } 40% { opacity: 1 } }
+.helperask { display: flex; gap: var(--sp-2); padding: var(--sp-3) var(--sp-4); border-top: 1px solid var(--line); }
+.helperask input { flex: 1; min-width: 0; background: var(--s2); border: 1px solid var(--line); border-radius: var(--r); padding: 10px 12px; font-size: 13.5px; color: var(--ink); }
+.helperask input:focus { outline: none; border-color: var(--accent); }
+.helperask .btn { padding: 0 12px; }
+.quickhelp { margin-top: var(--sp-5); border-top: 1px solid var(--line-2); padding-top: var(--sp-4); }
+.quickhelp dt { font-size: 12.5px; font-weight: 600; margin-top: var(--sp-3); }
+.quickhelp dd { font-size: 12.5px; color: var(--ink-2); line-height: 1.5; margin: 3px 0 0; }
+@media (max-width: 1100px) { .helper { position: fixed; right: 0; top: 0; bottom: 0; z-index: 30; box-shadow: var(--shadow-lg); } }
+
+.search { display: flex; align-items: center; gap: 8px; background: var(--s1); border: 1px solid var(--line); border-radius: var(--r); padding: 0 12px; height: 36px; width: min(340px, 100%); color: var(--ink-3); }
+.search input { flex: 1; min-width: 0; background: none; border: 0; outline: none; color: var(--ink); font-size: 13.5px; }
+.search:focus-within { border-color: var(--accent); }
+.sheethead.who { align-items: center; gap: var(--sp-3); }
+.sheethead.who .grow { flex: 1; min-width: 0; }
+.sheethead.who .note { margin-top: 2px; font-size: 12px; }
+.sheethead .close { font-size: 14px; line-height: 1; }
+.formsection .field:last-child { margin-bottom: 0; }
+.formsection.dangerzone { margin-top: var(--sp-6); padding: var(--sp-4); border: 1px solid color-mix(in srgb, var(--bad) 30%, transparent); border-radius: var(--r); background: var(--bad-2); }
+.formsection.dangerzone h4 { color: var(--bad); border-color: color-mix(in srgb, var(--bad) 30%, transparent); }
+tr.click { cursor: pointer; } tr.click:hover td { background: var(--s2); }
+
+/* Loya's door: fixed to the top-right of the content area, on every screen. */
+.loya-fab { position: fixed; top: var(--sp-4); right: var(--sp-5); z-index: 20;
+  display: flex; align-items: center; gap: 8px; padding: 8px 14px 8px 10px; border-radius: 99px;
+  border: 1px solid color-mix(in srgb, var(--accent) 40%, transparent); background: var(--s1); color: var(--ink);
+  box-shadow: var(--shadow-lg); cursor: pointer; font-size: 13px; font-weight: 600; }
+.loya-fab img { width: 20px; height: 20px; object-fit: contain; }
+.loya-fab:hover { background: var(--accent-3); border-color: var(--accent); }
+
+/* Camera finder: the pick-list that replaces "type an IP address". */
+.finder { display: flex; flex-direction: column; gap: var(--sp-3); align-items: flex-start; padding: var(--sp-3) var(--sp-4); border: 1px dashed var(--line); border-radius: var(--r); background: var(--s2); }
+.finder p { font-size: 13px; color: var(--ink-2); line-height: 1.5; margin: 0; }
+.finder.busy { flex-direction: row; align-items: center; color: var(--ink-2); font-size: 13px; border-style: solid; }
+.foundlist { list-style: none; margin: 0; padding: 0; display: flex; flex-direction: column; gap: 6px; }
+.foundlist li button { width: 100%; display: flex; align-items: center; gap: var(--sp-3); padding: 10px 12px; border-radius: var(--r); border: 1px solid var(--line); background: var(--s2); color: var(--ink); cursor: pointer; text-align: left; font-size: 13px; }
+.foundlist li button:hover { border-color: var(--accent); }
+.foundlist li.picked button { border-color: var(--accent); background: var(--accent-3); }
+.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/ui/icons.jsx

@@ -0,0 +1,71 @@
+// One icon set, drawn rather than typed.
+//
+// The navigation used to be text characters — ◉ ☺ ▢ — which render in whatever
+// the system decides, sit on the text baseline instead of optical centre, and
+// cannot take a stroke weight. On a shop PC that is the difference between
+// software somebody trusts with their customers and something that looks
+// improvised.
+//
+// All of these are 24-unit grid, 1.6 stroke, currentColor, no fill. That means
+// one icon works on every surface and in every state without a second copy.
+
+const base = {
+  width: 18, height: 18, viewBox: '0 0 24 24', fill: 'none',
+  stroke: 'currentColor', strokeWidth: 1.6,
+  strokeLinecap: 'round', strokeLinejoin: 'round',
+  'aria-hidden': 'true', focusable: 'false',
+}
+
+function Svg({ size, children, ...rest }) {
+  return <svg {...base} {...rest} width={size ?? base.width} height={size ?? base.height}>{children}</svg>
+}
+
+export const Live = p => (
+  <Svg {...p}><circle cx="12" cy="12" r="3.2" /><path d="M5.6 5.6a9 9 0 0 0 0 12.8M18.4 18.4a9 9 0 0 0 0-12.8" /></Svg>
+)
+export const People = p => (
+  <Svg {...p}><circle cx="9" cy="8.5" r="3.2" /><path d="M2.8 19.5a6.4 6.4 0 0 1 12.4 0" /><path d="M16.5 6.2a3.2 3.2 0 0 1 0 6.1M18 19.5a6 6 0 0 0-1.6-4" /></Svg>
+)
+export const Camera = p => (
+  <Svg {...p}><path d="M3 8.5h3.4L8 6h8l1.6 2.5H21v10.2H3z" /><circle cx="12" cy="13.2" r="3.1" /></Svg>
+)
+export const Search = p => (
+  <Svg {...p}><circle cx="11" cy="11" r="6.4" /><path d="M15.8 15.8 20.5 20.5" /></Svg>
+)
+export const Plus = p => (<Svg {...p}><path d="M12 5.5v13M5.5 12h13" /></Svg>)
+export const Close = p => (<Svg {...p}><path d="M6.5 6.5l11 11M17.5 6.5l-11 11" /></Svg>)
+export const Check = p => (<Svg {...p}><path d="M5 12.8l4.4 4.2L19 7" /></Svg>)
+export const Play = p => (<Svg {...p}><path d="M8 5.6v12.8L18.5 12z" /></Svg>)
+export const Stop = p => (<Svg {...p}><rect x="7" y="7" width="10" height="10" rx="1.6" /></Svg>)
+export const Warning = p => (
+  <Svg {...p}><path d="M12 4.6 21 19.4H3z" /><path d="M12 10v4.1" /><path d="M12 17.1v.01" /></Svg>
+)
+export const Signal = p => (
+  <Svg {...p}><path d="M5 19.4v-4.2M10.3 19.4v-7.6M15.7 19.4v-11M21 19.4V4.6" /></Svg>
+)
+export const Cloud = p => (
+  <Svg {...p}><path d="M7.2 18.4a4.2 4.2 0 0 1-.6-8.35A6.2 6.2 0 0 1 18.4 9a4.2 4.2 0 0 1 .3 9.4z" /></Svg>
+)
+export const CloudOff = p => (
+  <Svg {...p}><path d="M7.2 18.4a4.2 4.2 0 0 1-.6-8.35 6.2 6.2 0 0 1 2-3.2M10.6 5.2A6.2 6.2 0 0 1 18.4 9a4.2 4.2 0 0 1 1.9 7.6" /><path d="M3.6 3.6l16.8 16.8" /></Svg>
+)
+export const Shield = p => (
+  <Svg {...p}><path d="M12 3.8 19.4 6.6v5.2c0 4.2-3 7.4-7.4 8.4-4.4-1-7.4-4.2-7.4-8.4V6.6z" /></Svg>
+)
+export const Link = p => (
+  <Svg {...p}><path d="M10.2 13.8a3.6 3.6 0 0 0 5.2 0l2.8-2.8a3.7 3.7 0 0 0-5.2-5.2l-1.3 1.3" /><path d="M13.8 10.2a3.6 3.6 0 0 0-5.2 0l-2.8 2.8a3.7 3.7 0 0 0 5.2 5.2l1.3-1.3" /></Svg>
+)
+export const Logout = p => (
+  <Svg {...p}><path d="M14.4 7.6V5.4H4.6v13.2h9.8v-2.2" /><path d="M10 12h9.4M16.4 8.8 19.8 12l-3.4 3.2" /></Svg>
+)
+export const Back = p => (<Svg {...p}><path d="M14.6 5.6 8 12l6.6 6.4" /></Svg>)
+export const Chevron = p => (<Svg {...p}><path d="M9.4 5.6 16 12l-6.6 6.4" /></Svg>)
+export const Dot = p => (<Svg {...p}><circle cx="12" cy="12" r="4.5" fill="currentColor" stroke="none" /></Svg>)
+
+// Drawn for the empty states rather than an apologetic sentence in grey.
+export const NoCamera = p => (
+  <Svg {...p} strokeWidth="1.2"><path d="M3 8.5h3.4L8 6h8l1.6 2.5H21v10.2H3z" /><circle cx="12" cy="13.2" r="3.1" /><path d="M3.6 3.6l16.8 16.8" /></Svg>
+)
+export const NoFaces = p => (
+  <Svg {...p} strokeWidth="1.2"><circle cx="12" cy="9" r="3.4" /><path d="M5.4 20a6.8 6.8 0 0 1 13.2 0" /></Svg>
+)

desktop/frontend/src/views/Assistant.jsx

@@ -0,0 +1,123 @@
+import { useEffect, useRef, useState } from 'react'
+import { api, message } from '../bridge.js'
+import * as Icon from '../ui/icons.jsx'
+import logo from '../assets/loyaly-mark.png'
+
+// The help. A conversation with the head-office assistant, which answers from
+// the shop's own data and knows how the product is set up - so "why is nobody
+// being recognised" and "how do I add my camera" are both answered here, by
+// the same thing, without leaving the app.
+//
+// The history lives in this component and is resent whole; nothing is stored
+// anywhere. A PC running on its own has no head office to ask and is told so.
+const SUGGESTED = [
+  'Is my shop working right now?',
+  'How do I add my camera?',
+  'Why has nobody been recognised today?',
+  'Who came in this morning?',
+]
+
+export default function Assistant({ session, onClose }) {
+  const [turns, setTurns] = useState([])
+  const [draft, setDraft] = useState('')
+  const [busy, setBusy] = useState(false)
+  const [error, setError] = useState(null)
+  const scroller = useRef(null)
+  const standalone = session?.standalone
+
+  useEffect(() => { scroller.current?.scrollTo({ top: 1e9, behavior: 'smooth' }) }, [turns, busy])
+
+  async function ask(text) {
+    const q = (text ?? draft).trim()
+    if (!q || busy) return
+    const history = [...turns, { role: 'user', text: q }]
+    setTurns(history); setDraft(''); setBusy(true); setError(null)
+    try {
+      const a = await api.ask(history.map(t => ({ role: t.role, text: t.text })))
+      setTurns([...history, { role: 'assistant', text: a.text, used: a.used ?? [] }])
+    } catch (e) {
+      const m = message(e)
+      // Her only failure that is not hers: the login is gone. Say what to do,
+      // not "session expired" - the shell returns to Login within seconds.
+      setError(/session expired|unauthori[sz]ed/i.test(m)
+        ? 'You’re signed out of head office, so I can’t look anything up. Sign in again and ask me once more.'
+        : m)
+      setTurns(turns) // the question stays in the box, not in the transcript
+      setDraft(q)
+    } finally { setBusy(false) }
+  }
+
+  return (
+    <aside className="helper" role="dialog" aria-label="Loya">
+      <header className="helperhead">
+        <img src={logo} alt="" />
+        <div>
+          <b>Loya</b>
+          <span>Your Behavision buddy — knows your cameras, your customers and your numbers.</span>
+        </div>
+        <button className="close" onClick={onClose} aria-label="Close"><Icon.Close size={16} /></button>
+      </header>
+
+      <div className="helperbody" ref={scroller}>
+        {standalone && (
+          <div className="helpernote">
+            <Icon.CloudOff size={16} />
+            <div>
+              <b>This PC runs on its own</b>
+              <span>Loya lives at head office. Link this PC to a shop to talk to her; the basics are below.</span>
+            </div>
+          </div>
+        )}
+        {turns.length === 0 && (
+          <div className="helperintro">
+            <div className="turn assistant"><div className="bubble">
+              {greeting(session)} Ask me anything about {session?.site_name || 'this shop'} — what’s happening now, or how to set something up.
+            </div></div>
+            <div className="chips">
+              {SUGGESTED.map(s => <button key={s} className="chip" onClick={() => ask(s)} disabled={busy || standalone}>{s}</button>)}
+            </div>
+            {standalone && <QuickHelp />}
+          </div>
+        )}
+        {turns.map((t, i) => (
+          <div key={i} className={`turn ${t.role}`}>
+            <div className="bubble">{t.text}</div>
+            {t.used?.length > 0 && <span className="used">Looked at: {t.used.join(', ')}</span>}
+          </div>
+        ))}
+        {busy && <div className="turn assistant"><div className="bubble thinking"><span /><span /><span /></div></div>}
+        {error && <div className="err"><Icon.Warning size={15} />{error}</div>}
+      </div>
+
+      <form className="helperask" onSubmit={e => { e.preventDefault(); ask() }}>
+        <input value={draft} onChange={e => setDraft(e.target.value)} disabled={busy || standalone}
+               placeholder={standalone ? 'Link this PC to head office to talk to Loya' : 'Ask Loya…'} />
+        <button className="btn primary" disabled={busy || standalone || !draft.trim()} aria-label="Ask"><Icon.Chevron size={16} /></button>
+      </form>
+    </aside>
+  )
+}
+
+function greeting(session) {
+  const h = new Date().getHours()
+  const part = h < 12 ? 'Morning' : h < 17 ? 'Afternoon' : 'Evening'
+  const name = session?.user?.full_name?.split(' ')[0]
+  return name ? `${part}, ${name}.` : `${part}.`
+}
+
+// What a PC with no head office can still be told. Static on purpose: there is
+// nobody to ask, and a chat box that always fails is worse than a short list.
+function QuickHelp() {
+  return (
+    <dl className="quickhelp">
+      <dt>Adding a camera</dt>
+      <dd>Cameras → Add camera. The address is on a label on the camera; pick the make and the stream path fills itself in. Test, then save.</dd>
+      <dt>Proving it works</dt>
+      <dd>Press Check placement and walk past the camera like a customer for 25 seconds. Only “good” means it can recognise faces — otherwise move it to head height, facing the way people approach.</dd>
+      <dt>Nothing showing on Live</dt>
+      <dd>Check the camera is Connected and Proven. A camera aimed from above or the side streams fine and recognises nobody.</dd>
+      <dt>Linking to head office later</dt>
+      <dd>Use the link button at the bottom of the sidebar and type an installation code from head office. Nothing recorded here is lost.</dd>
+    </dl>
+  )
+}

desktop/frontend/src/views/Cameras.jsx

@@ -1,69 +1,60 @@
 import { useEffect, useRef, useState } from 'react'
 import { api, message } from '../bridge.js'
 import { usePolled } from '../hooks.js'
+import * as Icon from '../ui/icons.jsx'
 import { MAKES, makeById } from '../../../../shared/cameraMakes.js'
 
-const BLANK = { id: '', host: '', port: 554, path: '', username: '', password: '',
+// The camera screen is a picture, not a settings table.
-                max_width: 1280 }
+//
+// The first version was a table of id / rtsp url / status with three buttons
+// per row - the view a developer wants. A camera is a thing you look at, so
+// the live picture is the card, the state sits over it, and the one line that
+// matters is under it: whether anyone has PROVED this camera can recognise a
+// face, which is a different claim from "connected" and is the gap a site gets
+// signed off through.
+const BLANK = { id: '', host: '', port: 554, path: '', username: '', password: '', max_width: 1280 }
 
 export default function Cameras() {
   const { data, error, reload } = usePolled(() => api.cameras(), 8000)
   const [editing, setEditing] = useState(null)
   const [check, setCheck] = useState(null)
   const cams = data ?? []
+  const streams = useStreamURLs(cams)
 
-  async function remove(id) {
+  async function remove(cam) {
-    if (!confirm(`Remove camera "${id}"? Recognition from it stops immediately.`)) return
+    if (!confirm(`Remove ${cam.id}? Recognition from it stops immediately.`)) return
-    try { await api.deleteCamera(id); reload() } catch (e) { alert(message(e)) }
+    try { await api.deleteCamera(cam.id); reload() } catch (e) { alert(message(e)) }
   }
 
   return (
     <div className="page">
-      <header style={{ display: 'flex', justifyContent: 'space-between', alignItems: 'flex-end' }}>
+      <header className="pagehead">
         <div>
           <h2>Cameras</h2>
-          <p>Add a camera, check it can see faces properly, then it starts working.</p>
+          <p>Add a camera, then prove it can see faces with a walk-past. Only then is it working.</p>
         </div>
         <button className="btn primary" onClick={() => setEditing({ ...BLANK })}>
-          Add camera
+          <Icon.Plus size={15} />Add camera
         </button>
       </header>
 
-      {error && <div className="err">{error}</div>}
+      {error && <div className="err"><Icon.Warning size={15} />{error}</div>}
 
-      <div className="card">
+      {cams.length === 0
-        {cams.length === 0
+        ? <div className="panel">
-          ? <div className="empty">No cameras yet.</div>
+            <div className="empty tall">
-          : <div className="tablewrap">
+              <Icon.NoCamera size={40} />
-              <table>
+              <b>No cameras yet</b>
-                <thead><tr><th>Name</th><th>Address</th><th>Status</th><th></th></tr></thead>
+              <p>Add the camera by its address. Most cameras print it on a label underneath, or show it in their own app.</p>
-                <tbody>
+              <button className="btn primary" onClick={() => setEditing({ ...BLANK })}><Icon.Plus size={15} />Add your first camera</button>
-                  {cams.map(c => (
+            </div>
-                    <tr key={c.id}>
+          </div>
-                      <td>{c.id}</td>
+        : <div className="camgrid">
-                      <td className="mono">{c.url}</td>
+            {cams.map(c => (
-                      <td>
+              <CameraCard key={c.id} cam={c} stream={streams[c.id]}
-                        {c.connected === undefined
+                          onEdit={() => setEditing(c)} onCheck={() => setCheck(c.id)} onRemove={() => remove(c)} />
-                          ? <span className="pill"><i className="dot idle" />stopped</span>
+            ))}
-                          : c.connected
+          </div>}
-                            ? <span className="pill ok"><i className="dot ok" />live</span>
-                            : <span className="pill bad"><i className="dot bad" />offline</span>}
-                      </td>
-                      <td style={{ textAlign: 'right', whiteSpace: 'nowrap' }}>
-                        <button className="btn sm" onClick={() => setCheck(c.id)}>
-                          Check placement
-                        </button>{' '}
-                        <button className="btn sm" onClick={() => setEditing(c)}>Edit</button>{' '}
-                        <button className="btn sm danger" onClick={() => remove(c.id)}>
-                          Remove
-                        </button>
-                      </td>
-                    </tr>
-                  ))}
-                </tbody>
-              </table>
-            </div>}
-      </div>
 
       {editing && <CameraSheet cam={editing} onClose={() => setEditing(null)}
                                onSaved={() => { setEditing(null); reload() }} />}
@@ -72,10 +63,68 @@ export default function Cameras() {
   )
 }
 
+function CameraCard({ cam, stream, onEdit, onCheck, onRemove }) {
+  const conn = cam.connected === undefined ? { tone: 'idle', label: 'Engine stopped' }
+    : cam.connected ? { tone: 'ok', label: 'Connected' } : { tone: 'bad', label: 'Not connecting' }
+  // The last placement verdict, so "proven" survives closing the sheet. Only
+  // `good` is a pass: marginal means half the visitors are silently discarded.
+  const { data: last } = usePolled(() => api.placementResult(cam.id), 15000, [cam.id])
+  const proof = !last || last.running || !last.verdict || last.verdict === 'starting'
+    ? { tone: 'miss', label: 'Not yet proven', text: 'Walk past it once and Behavision will tell you if the placement works.' }
+    : last.verdict === 'good'
+      ? { tone: 'seen', label: 'Proven', text: last.headline || 'Faces recognised on a walk-past.' }
+      : { tone: 'miss', label: 'Not proven', text: last.headline || 'Move the camera and check again.' }
+  return (
+    <article className="camcard">
+      <div className="camview">
+        {stream
+          ? <img src={stream} alt={cam.id} />
+          : <div className="placeholder"><Icon.NoCamera size={34} /></div>}
+        <span className={`pill ${conn.tone === 'idle' ? '' : conn.tone} over`}><i className={`dot ${conn.tone}`} />{conn.label}</span>
+      </div>
+      <div className="cambody">
+        <div className="camtitle">
+          <div>
+            <h3>{cam.id}</h3>
+            <span className="mono note">{cam.host || cam.url}{cam.path ? ` · ${cam.path}` : ''}</span>
+          </div>
+          <div className="camactions">
+            <button className="btn sm" onClick={onEdit}>Edit</button>
+            <button className="btn sm danger" onClick={onRemove}>Remove</button>
+          </div>
+        </div>
+        <div className="camproof">
+          <span className={`tag ${proof.tone}`}>{proof.label}</span>
+          <span className="note">{proof.text}</span>
+          <button className={`btn sm ${proof.tone === 'seen' ? '' : 'primary'}`} onClick={onCheck}><Icon.Play size={13} />{proof.tone === 'seen' ? 'Check again' : 'Check placement'}</button>
+        </div>
+      </div>
+    </article>
+  )
+}
+
+// Stream URLs are fetched once per camera and left alone: reassigning an
+// MJPEG <img> src restarts the stream, so rebuilding them on every poll makes
+// every feed flicker forever.
+function useStreamURLs(cams) {
+  const [urls, setUrls] = useState({})
+  useEffect(() => {
+    let alive = true
+    const missing = cams.filter(c => !(c.id in urls))
+    if (!missing.length) return
+    ;(async () => {
+      const add = {}
+      for (const c of missing) { try { add[c.id] = await api.streamURL(c.id) } catch { add[c.id] = '' } }
+      if (alive) setUrls(u => ({ ...u, ...add }))
+    })()
+    return () => { alive = false }
+  }, [cams.map(c => c.id).join('|')]) // eslint-disable-line react-hooks/exhaustive-deps
+  return urls
+}
+
 function CameraSheet({ cam, onClose, onSaved }) {
   const isNew = !cam.id
-  const [f, setF] = useState({ ...BLANK, ...cam, password: '',
+  const [f, setF] = useState({ ...BLANK, ...cam, password: '', path: cam.path || (isNew ? MAKES[0].path : '') })
-                               path: cam.path || (isNew ? MAKES[0].path : '') })
   const [make, setMake] = useState(isNew ? MAKES[0].id : 'manual')
   const [test, setTest] = useState(null)
   const [busy, setBusy] = useState(null)
@@ -114,93 +163,137 @@ function CameraSheet({ cam, onClose, onSaved }) {
     catch (e) { setError(message(e)) } finally { setBusy(null) }
   }
 
+  const chosen = makeById(make)
+
+  // The camera is picked from a scan of the shop's network rather than typed.
+  // Nobody knows their camera's address; the sticker is under the camera and
+  // the menu is different in every make's app. The scan names ONVIF cameras
+  // and lists anything with the RTSP port open; picking one fills the
+  // address and, when the make is recognisable, the stream path too.
+  const [scan, setScan] = useState(null)      // null | 'busy' | {cameras, networks} | {error}
+  async function findCameras() {
+    setScan('busy')
+    try { setScan(await api.discoverCameras()) } catch (e) { setScan({ error: message(e) }) }
+  }
+  function pick(c) {
+    const m = c.make ? makeById(c.make) : null
+    setF(prev => ({ ...prev, host: c.host, path: m?.path || prev.path,
+                    id: prev.id || (m ? '' : ''), }))
+    if (m) setMake(m.id)
+    setTest(null)
+  }
+
   return (
     <div className="drawer" onMouseDown={e => e.target === e.currentTarget && onClose()}>
-      <div className="panel">
+      <div className="sheet">
-        <button className="btn sm close" onClick={onClose}>Close</button>
+        <div className="sheethead">
-        <h3>{isNew ? 'Add camera' : cam.id}</h3>
+          <h2>{isNew ? 'Add a camera' : `Edit ${cam.id}`}</h2>
-        <p className="note" style={{ marginBottom: 18 }}>
+          <button className="close" onClick={onClose} aria-label="Close"><Icon.Close size={16} /></button>
-          Test the connection before saving — a wrong address is the most common mistake.
+        </div>
-        </p>
+        <form className="sheetbody" onSubmit={save} autoComplete="off">
-        <form onSubmit={save}>
+          <p className="lead">Three things from the camera: its address, its make, and its password. Test before you save — a wrong address is the most common mistake.</p>
-          {error && <div className="err">{error}</div>}
+          {error && <div className="err"><Icon.Warning size={15} />{error}</div>}
-          <label className="field">
-            <span>Name</span>
-            <input value={f.id} onChange={set('id')} disabled={!isNew}
-                   placeholder="entrance" required autoComplete="off" />
-          </label>
-          {/* The highest-value field on this form. The address and the
-              password are on a label or in the installer's notes; the RTSP
-              path is not written anywhere a shop owner would look, and getting
-              it wrong produces "could not open stream", which reads like a
-              password problem and is not. */}
-          <label className="field"><span>Make of camera</span>
-            <select value={make} onChange={chooseMake}>
-              {MAKES.map(m => <option key={m.id} value={m.id}>{m.label}</option>)}
-            </select>
-          </label>
-          {makeById(make).note && (
-            <p className="note" style={{ marginTop: -8, marginBottom: 12 }}>
-              {makeById(make).note}
-            </p>
-          )}
-          <div className="fieldrow">
-            <label className="field"><span>Camera address</span>
-              <input value={f.host} onChange={set('host')} placeholder="192.168.0.138"
-                     autoComplete="off" />
-            </label>
-            <label className="field"><span>Port</span>
-              <input value={f.port} onChange={set('port')} inputMode="numeric"
-                     autoComplete="off" />
-            </label>
-          </div>
-          <label className="field"><span>Stream path</span>
-            <input value={f.path} onChange={set('path')} placeholder="/ch0_0.264"
-                   autoComplete="off" />
-          </label>
-          <div className="fieldrow">
-            {/* A text input next to a password input is a sign-in form as far
-                as the webview is concerned, so without this the browser offers
-                the operator's own Behavision email as the camera's username -
-                which fails with a message about credentials that points at the
-                camera. "off" alone is frequently ignored; a non-login name and
-                new-password on the secret are what actually work. */}
-            <label className="field"><span>Username</span>
-              <input value={f.username} onChange={set('username')}
-                     name="camera-account" autoComplete="off" />
-            </label>
-            <label className="field"><span>Password</span>
-              <input type="password" value={f.password} onChange={set('password')}
-                     name="camera-secret" autoComplete="new-password"
-                     placeholder={cam.has_password ? '(unchanged)' : ''} />
-            </label>
-          </div>
 
-          <div style={{ display: 'flex', gap: 8, marginTop: 4 }}>
+          {isNew && (
-            <button type="button" className="btn" onClick={runTest} disabled={!!busy}>
+            <section className="formsection">
-              {busy === 'test' ? 'Connecting…' : 'Test connection'}
+              <h4>Find it</h4>
-            </button>
+              {scan === null && (
-            <button className="btn primary" disabled={!!busy || !f.id}>
+                <div className="finder">
-              {busy === 'save' ? 'Saving…' : 'Save'}
+                  <p>Behavision can look for cameras on this shop’s network.</p>
-            </button>
+                  <button type="button" className="btn primary" onClick={findCameras}><Icon.Search size={14} />Find cameras on this network</button>
-          </div>
+                </div>
+              )}
+              {scan === 'busy' && <div className="finder busy"><span className="spinner" />Looking on the network… a few seconds.</div>}
+              {scan?.error && <div className="err"><Icon.Warning size={15} />{scan.error}</div>}
+              {scan?.cameras && (
+                scan.cameras.length === 0
+                  ? <div className="finder">
+                      <p>Nothing answered on {scan.networks?.join(', ') || 'this network'}. The camera may be on a different network, switched off, or not yet connected — check its cable and power, then try again. You can still type its address below.</p>
+                      <button type="button" className="btn" onClick={findCameras}>Try again</button>
+                    </div>
+                  : <ul className="foundlist">
+                      {scan.cameras.map(c => (
+                        <li key={c.host} className={f.host === c.host ? 'picked' : ''}>
+                          <button type="button" onClick={() => pick(c)}>
+                            <span className="mono">{c.host}</span>
+                            <span className="what">{c.name || (c.rtsp ? 'Streams video (RTSP)' : 'Answers ONVIF')}</span>
+                            {c.make && <span className="tag seen">{makeById(c.make).label}</span>}
+                            {f.host === c.host && <Icon.Check size={16} />}
+                          </button>
+                        </li>
+                      ))}
+                      <li className="rescan"><button type="button" className="btn sm" onClick={findCameras}>Scan again</button></li>
+                    </ul>
+              )}
+            </section>
+          )}
+
+          <section className="formsection">
+            <h4>The camera</h4>
+            {isNew && (
+              <label className="field"><span>Name</span>
+                <input value={f.id} onChange={set('id')} placeholder="entrance" required autoFocus />
+                <em className="hint">Short, no spaces. It names this camera everywhere and cannot be changed later.</em>
+              </label>
+            )}
+            <div className="fieldrow">
+              <label className="field"><span>Address</span>
+                <input value={f.host} onChange={set('host')} placeholder="192.168.1.20" inputMode="decimal" />
+                <em className="hint">On a label on the camera, or in its own app under “network”.</em>
+              </label>
+              <label className="field narrow"><span>Port</span>
+                <input value={f.port} onChange={set('port')} inputMode="numeric" />
+              </label>
+            </div>
+          </section>
+
+          <section className="formsection">
+            <h4>The stream</h4>
+            <label className="field"><span>Make of camera</span>
+              <select value={make} onChange={chooseMake}>
+                {MAKES.map(m => <option key={m.id} value={m.id}>{m.label}</option>)}
+              </select>
+              {chosen.note && <em className="hint">{chosen.note}</em>}
+            </label>
+            <label className="field"><span>Stream path</span>
+              <input className="mono" value={f.path} onChange={set('path')} placeholder="/Streaming/Channels/101" />
+              <em className="hint">Filled in from the make. Change it only if the camera’s own app says something else.</em>
+            </label>
+          </section>
+
+          <section className="formsection">
+            <h4>Sign-in to the camera</h4>
+            <div className="fieldrow">
+              <label className="field"><span>Username</span>
+                <input name="rtsp-account" autoComplete="off" value={f.username} onChange={set('username')} placeholder="admin" />
+              </label>
+              <label className="field"><span>Password</span>
+                <input type="password" name="rtsp-secret" autoComplete="new-password" value={f.password}
+                       onChange={set('password')} placeholder={cam.has_password ? '(unchanged)' : ''} />
+              </label>
+            </div>
+          </section>
 
           {test && (
-            <div style={{ marginTop: 14 }}>
+            test.ok
-              {test.ok
+              ? <div className="testresult ok">
-                ? <>
+                  <Icon.Check size={16} />
-                    <p style={{ color: 'var(--ok)', fontSize: 13 }}>
+                  <div>
-                      Connected — {test.width}×{test.height}
+                    <b>Connected — {test.width}×{test.height}{test.codec ? ` · ${String(test.codec).toUpperCase()}` : ''}</b>
-                    </p>
+                    {test.snapshot && <img alt="Camera preview" src={`data:image/jpeg;base64,${test.snapshot}`} />}
-                    {test.snapshot && (
+                  </div>
-                      <img alt="Camera preview" style={{ width: '100%', marginTop: 8,
+                </div>
-                             borderRadius: 6, border: '1px solid var(--line)' }}
+              : <div className="testresult bad"><Icon.Warning size={16} /><div><b>Could not connect</b><span>{test.error}</span></div></div>
-                           src={`data:image/jpeg;base64,${test.snapshot}`} />
-                    )}
-                  </>
-                : <div className="err">{test.error}</div>}
-            </div>
           )}
+
+          <div className="sheetactions">
+            <button type="button" className="btn" onClick={runTest} disabled={!!busy || !f.host}>
+              {busy === 'test' ? 'Connecting…' : 'Test connection'}
+            </button>
+            <button className="btn primary" disabled={!!busy || !f.id || !f.host}>
+              {busy === 'save' ? 'Saving…' : isNew ? 'Add camera' : 'Save changes'}
+            </button>
+          </div>
         </form>
       </div>
     </div>
@@ -208,7 +301,7 @@ function CameraSheet({ cam, onClose, onSaved }) {
 }
 
 // The commissioning wizard. This is what stops a site being signed off with a
-// camera that recognises nobody — the failure that otherwise shows up weeks
+// camera that recognises nobody - the failure that otherwise shows up weeks
 // later as a footfall report that was always zero.
 function PlacementSheet({ id, onClose }) {
   const [state, setState] = useState({ verdict: 'starting', advice: [] })
@@ -233,45 +326,54 @@ function PlacementSheet({ id, onClose }) {
     return () => { alive = false; clearInterval(timer.current) }
   }, [id])
 
-  const tone = { good: 'ok', marginal: 'warn', poor: 'bad', artifact: 'bad',
+  const tone = { good: 'ok', marginal: 'warn', poor: 'bad', artifact: 'bad', no_faces: 'warn',
-                 no_faces: 'warn', inconclusive: 'warn' }[state.verdict]
+                 inconclusive: 'warn', no_completed_passes: 'warn' }[state.verdict]
   const pct = state.seconds ? Math.min(100, (state.elapsed / state.seconds) * 100) : 0
+  const running = state.running || state.verdict === 'starting'
 
   return (
     <div className="drawer" onMouseDown={e => e.target === e.currentTarget && onClose()}>
-      <div className="panel">
+      <div className="sheet">
-        <button className="btn sm close" onClick={onClose}>Close</button>
+        <div className="sheethead">
-        <h3>Placement check — {id}</h3>
+          <h2>Check placement · {id}</h2>
-        <p className="note" style={{ marginBottom: 18 }}>
+          <button className="close" onClick={onClose} aria-label="Close"><Icon.Close size={16} /></button>
-          Walk past the camera the way a customer would, a few times.
+        </div>
-        </p>
+        <div className="sheetbody">
+          {error && <div className="err"><Icon.Warning size={15} />{error}</div>}
 
-        {error && <div className="err">{error}</div>}
+          <ol className="steps">
+            <li className={running ? 'now' : 'done'}>
+              <b>Walk past the camera</b>
+              <span>The way a customer would — in through the door, not looking at the lens. Two or three times, for about 25 seconds.</span>
+              {running && <div className="progress"><div style={{ width: `${pct}%` }} /></div>}
+            </li>
+            <li className={running ? '' : 'now'}>
+              <b>Behavision judges what it saw</b>
+              <span>Not “were the frames sharp”, but “did a person walking past produce a face worth recognising”.</span>
+            </li>
+          </ol>
 
-        <div className="card">
+          <div className={`verdict ${tone ?? ''}`}>
-          <div style={{ fontSize: 15, fontWeight: 600,
+            <div className="verdict-head">
-                        color: tone ? `var(--${tone})` : 'var(--ink)' }}>
+              {running ? <span className="spinner" /> : tone === 'ok' ? <Icon.Check size={18} /> : <Icon.Warning size={18} />}
-            {state.headline || 'Starting…'}
+              <b>{state.headline || 'Watching…'}</b>
-          </div>
+            </div>
-          {state.running && (
+            {state.advice?.length > 0 && (
-            <div style={{ height: 5, background: 'var(--surface-2)', borderRadius: 3,
+              <ul>{state.advice.map((a, i) => <li key={i}>{a}</li>)}</ul>
-                          overflow: 'hidden', margin: '12px 0' }}>
+            )}
-              <div style={{ height: '100%', width: `${pct}%`, background: 'var(--accent)',
+            {state.quality?.n > 0 && (
-                            transition: 'width .4s linear' }} />
+              <p className="note">
+                {state.quality.n} face{state.quality.n === 1 ? '' : 's'} seen · median quality {state.quality.p50} ·
+                {' '}{Math.round((state.quality.fraction_below_gate ?? 0) * 100)}% too poor to use
+              </p>
+            )}
+          </div>
+
+          {!running && (
+            <div className="sheetactions">
+              <button className="btn" onClick={onClose}>Close</button>
+              <button className="btn primary" onClick={() => { setState({ verdict: 'starting', advice: [] }); api.startPlacement(id, 25).then(setState).catch(e => setError(message(e))) }}>Run again</button>
             </div>
-          )}
-          {state.advice?.length > 0 && (
-            <ul style={{ margin: '12px 0 0 18px', fontSize: 13, color: 'var(--ink-2)' }}>
-              {state.advice.map((a, i) => <li key={i} style={{ marginBottom: 5 }}>{a}</li>)}
-            </ul>
-          )}
-          {state.quality?.n > 0 && (
-            <p className="note" style={{ marginTop: 12 }}>
-              {state.quality.n} face{state.quality.n === 1 ? '' : 's'} seen ·
-              median quality {state.quality.p50} ·
-              gate {state.gate} ·
-              {' '}{Math.round((state.quality.fraction_below_gate ?? 0) * 100)}% below it
-            </p>
           )}
         </div>
       </div>

desktop/frontend/src/views/CustomerForm.jsx

@@ -54,28 +54,28 @@ export default function CustomerForm({ customer, session, onClose, onSaved }) {
 
   return (
     <div className="drawer" onMouseDown={e => e.target === e.currentTarget && onClose()}>
-      <div className="panel">
+      <div className="sheet">
-        <div className="who">
+        <div className="sheethead who">
           <CustomerPhoto photo={shown} name={customer.full_name || customer.label}
+                         customerRef={customer.ref}
                          onBroken={() => setPhoto({ available: false,
                            reason: 'The photo could not be loaded.' })} />
           <div className="grow">
-            <h3>{customer.full_name || customer.label}</h3>
+            <h2>{customer.full_name || customer.label}</h2>
             <p className="note">
               {customer.visit_count} visit{customer.visit_count === 1 ? '' : 's'}
               {customer.last_seen_at && ` · last seen ${new Date(customer.last_seen_at).toLocaleDateString()}`}
+              {shown && !shown.available && shown.reason && ` · ${shown.reason}`}
             </p>
-            {shown && !shown.available && shown.reason &&
-              <p className="note">{shown.reason}</p>}
           </div>
-          <button type="button" className="btn sm" onClick={onClose}>Close</button>
+          <button type="button" className="close" onClick={onClose} aria-label="Close">✕</button>
         </div>
 
-        <form onSubmit={save}>
+        <form className="sheetbody" onSubmit={save}>
           {error && <div className="err">{error}</div>}
 
-          <div className="card" style={{ marginBottom: 14 }}>
+          <section className="formsection">
-            <h3>Customer details</h3>
+            <h4>Customer details</h4>
             <label className="field">
               <span>Full name</span>
               <input value={f.full_name} onChange={set('full_name')} autoFocus />
@@ -108,10 +108,10 @@ export default function CustomerForm({ customer, session, onClose, onSaved }) {
               <textarea value={f.notes} onChange={set('notes')}
                         placeholder="Preferences, sizes, anything worth remembering" />
             </label>
-          </div>
+          </section>
 
-          <div className="card" style={{ marginBottom: 14 }}>
+          <section className="formsection">
-            <h3>Purchase (optional)</h3>
+            <h4>Purchase (optional)</h4>
             <div className="fieldrow">
               <label className="field">
                 <span>Amount</span>
@@ -126,10 +126,10 @@ export default function CustomerForm({ customer, session, onClose, onSaved }) {
             </div>
             <p className="note">Leave the amount blank if they did not buy anything —
                a visit without a sale is still worth recording.</p>
-          </div>
+          </section>
 
-          <div className="card" style={{ marginBottom: 16 }}>
+          <section className="formsection">
-            <h3>Consent</h3>
+            <h4>Consent</h4>
             <label style={{ display: 'flex', gap: 10, alignItems: 'flex-start',
                             fontSize: 13, cursor: 'pointer' }}>
               <input type="checkbox" checked={f.consent} style={{ marginTop: 3 }}
@@ -141,23 +141,23 @@ export default function CustomerForm({ customer, session, onClose, onSaved }) {
               Recorded with the date and who collected it. They can withdraw it
               at any time, which erases their face data.
             </p>
-          </div>
+          </section>
 
-          <div className="card" style={{ marginBottom: 14 }}>
+          <section className="formsection">
-            <h3>Visits</h3>
+            <h4>Visits</h4>
             <VisitHistory customer={customer} />
-          </div>
+          </section>
 
-          <div style={{ display: 'flex', gap: 8 }}>
+          <div className="sheetactions">
+            <button type="button" className="btn" onClick={onClose}>Cancel</button>
             <button className="btn primary" disabled={busy}>
               {busy ? 'Saving…' : 'Save'}
             </button>
-            <button type="button" className="btn" onClick={onClose}>Cancel</button>
           </div>
 
           {canErase && (
-            <div className="card danger-zone">
+            <section className="formsection dangerzone">
-              <h3>At the customer's request</h3>
+              <h4>At the customer's request</h4>
               {erasing
                 ? <EraseCustomer customer={customer}
                                  onCancel={() => setErasing(false)}
@@ -173,7 +173,7 @@ export default function CustomerForm({ customer, session, onClose, onSaved }) {
                       Erase this customer…
                     </button>
                   </>}
-            </div>
+            </section>
           )}
         </form>
       </div>

desktop/frontend/src/views/CustomerPhoto.jsx

@@ -30,16 +30,31 @@ export function useCustomerPhoto(id) {
 
 // No photo is the normal case — images are off by default — so this renders
 // initials, not an error.
-export default function CustomerPhoto({ photo, name, onBroken }) {
+export default function CustomerPhoto({ photo, name, customerRef, onBroken }) {
   if (photo?.available) {
     return <img className="avatar" src={photo.url} alt={`Photo of ${name}`}
                 onError={onBroken} />
   }
-  const initials = String(name || '').split(/\s+/).filter(Boolean).slice(0, 2)
-    .map(w => w[0].toUpperCase()).join('') || '?'
   return (
     <div className="avatar none" role="img" aria-label={`No photo of ${name}`}>
-      <span>{initials}</span>
+      <span>{avatarText(name, customerRef)}</span>
     </div>
   )
 }
+
+// Initials of a name a human typed; the NUMBER for a customer the system named
+// itself. Taking the first letter of each word of "Visitor 13" gives "V1" —
+// which is also what "Visitor 10" and "Visitor 15" give, so three different
+// people wear the same badge, and it reads as the V-1 reference for a fourth.
+// Same fix as the web app's arrivals feed; the two must not disagree.
+//
+// customerRef, not `ref`: React reserves that prop name and it would never
+// reach this component.
+function avatarText(name, customerRef) {
+  const auto = /^Visitor (\d+)$/.exec(String(name || '').trim())
+  if (auto) return auto[1]
+  const n = /^V-(\d+)$/.exec(String(customerRef || ''))
+  if (n) return n[1]
+  return String(name || '').split(/\s+/).filter(Boolean).slice(0, 2)
+    .map(w => w[0].toUpperCase()).join('') || '?'
+}

desktop/frontend/src/views/Customers.jsx

@@ -1,6 +1,7 @@
 import { useState } from 'react'
 import { api } from '../bridge.js'
 import { usePolled, fmtDate } from '../hooks.js'
+import * as Icon from '../ui/icons.jsx'
 import CustomerForm from './CustomerForm.jsx'
 
 // The customer database, and the form staff fill in when someone walks in.
@@ -15,34 +16,32 @@ export default function Customers({ session }) {
 
   return (
     <div className="page">
-      <header>
+      <header className="pagehead">
-        <h2>Customers</h2>
+        <div>
-        <p>Everyone this business has recognised. Fill in details once and they
+          <h2>Customers</h2>
-           are known at every store.</p>
+          <p>Everyone this business has recognised. Fill in details once and they are known at every store.</p>
+        </div>
+        <label className="search">
+          <Icon.Search size={15} />
+          <input placeholder="Search by name or phone" value={query} onChange={e => setQuery(e.target.value)} />
+        </label>
       </header>
 
-      {error && <div className="err">{error}</div>}
+      {error && <div className="err"><Icon.Warning size={15} />{error}</div>}
 
-      <div className="grid cols-4" style={{ marginBottom: 16 }}>
+      <div className="metrics" style={{ marginBottom: 'var(--sp-4)' }}>
-        <Stat label="Known people" value={rows.length || '—'} />
+        <Metric k="Known people" v={rows.length || '—'} />
-        <Stat label="With details" value={named || '—'}
+        <Metric k="With details" v={named || '—'} s={rows.length ? `${Math.round(100 * named / rows.length)}% captured` : null} />
-              sub={rows.length ? `${Math.round(100 * named / rows.length)}% captured` : null} />
+        <Metric k="Returning" v={rows.filter(r => r.visit_count > 1).length || '—'} />
-        <Stat label="Returning" value={rows.filter(r => r.visit_count > 1).length || '—'} />
+        <Metric k="With consent" v={rows.filter(r => r.has_consent).length || '—'} />
-        <Stat label="With consent" value={rows.filter(r => r.has_consent).length || '—'} />
       </div>
 
-      <div className="card">
+      <div className="panel">
-        <div style={{ display: 'flex', gap: 10, marginBottom: 12 }}>
-          <input className="field" style={{ flex: 1, margin: 0, background: 'var(--ground)',
-                   border: '1px solid var(--line)', borderRadius: 6, padding: '8px 10px' }}
-                 placeholder="Search by name or phone"
-                 value={query} onChange={e => setQuery(e.target.value)} />
-          <button className="btn" onClick={reload}>Refresh</button>
-        </div>
-
         {rows.length === 0
-          ? <div className="empty">
+          ? <div className="empty tall">
-              No customers yet. They appear here the first time a camera sees them.
+              <Icon.NoFaces size={34} />
+              <b>No customers yet</b>
+              <p>They appear here the first time a camera recognises them. Click one to add a name and phone number.</p>
             </div>
           : <div className="tablewrap">
               <table>
@@ -56,7 +55,14 @@ export default function Customers({ session }) {
                 <tbody>
                   {rows.map(c => (
                     <tr key={c.id} className="click" onClick={() => setSelected(c)}>
-                      <td>{c.full_name || <span className="note">{c.label}</span>}</td>
+                      <td>
+                        {c.full_name || <span className="note">{c.label}</span>}
+                        {/* Only beside a name a human typed: the auto label
+                            already IS the number ("Visitor 13"), so showing
+                            both reads as two identifiers for one person. */}
+                        {c.full_name && c.ref &&
+                          <span className="note"> · {c.ref}</span>}
+                      </td>
                       <td className="mono">{c.phone || '—'}</td>
                       <td className="num">{c.visit_count}</td>
                       <td>{fmtDate(c.first_seen_at)}</td>
@@ -82,11 +88,12 @@ export default function Customers({ session }) {
   )
 }
 
-function Stat({ label, value, sub }) {
+function Metric({ k, v, s }) {
   return (
-    <div className="card stat">
+    <div className="metric">
-      <h3>{label}</h3><div className="value">{value}</div>
+      <div className="metric-k">{k}</div>
-      {sub && <div className="sub">{sub}</div>}
+      <div className="metric-v">{v}</div>
+      {s && <div className="metric-s">{s}</div>}
     </div>
   )
 }

desktop/frontend/src/views/Live.jsx

@@ -1,192 +1,253 @@
-import { useEffect, useState } from 'react'
+import { useEffect, useRef, useState } from 'react'
 import { api } from '../bridge.js'
 import { usePolled, fmtTime } from '../hooks.js'
+import * as Icon from '../ui/icons.jsx'
 
-// What is happening right now. The first screen a shop manager opens, so it
+// The shop floor screen.
-// answers "is it working" before it answers anything else.
+//
-export default function Live() {
+// Rebuilt around what somebody standing at the counter is actually here for:
+// WHO JUST WALKED IN. The previous version led with four large stat boxes and
+// left arrivals as a thin list of "person.seen" rows in the corner — the least
+// actionable content taking the most space, and the product's whole reason for
+// existing rendered as a log.
+//
+// Now: a status strip that answers "is this working" in one line, and arrivals
+// as cards big enough to recognise a customer from while looking up at them.
+// 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({ onNavigate }) {
   const { data, error } = usePolled(() => api.live(), 3000)
   const { data: pipe } = usePolled(() => api.pipelineStatus(), 5000)
-  const cams = useCameraFeeds()
 
   const cameras = data?.stats?.cameras ?? []
   const gallery = data?.stats?.gallery ?? {}
   const events = data?.events ?? []
 
   // fraction_below_gate is the number that decides a site: what share of the
-  // faces this camera saw were too poor to enrol. Surfaced here rather than
+  // faces this camera saw were too poor to enrol. Surfaced rather than buried,
-  // buried, because a high value looks exactly like "a quiet day".
+  // because a high value looks exactly like "a quiet day".
   const worst = cameras.reduce((acc, c) => {
     const f = c?.pipeline?.best_quality?.fraction_below_gate
     return typeof f === 'number' && f > acc ? f : acc
   }, 0)
+  const up = cameras.filter(c => c.connected).length
+
+  const arrivals = events.filter(e => e.type === 'person.new' || e.type === 'person.seen')
+  const freshest = useFreshest(arrivals[0])
 
   return (
     <div className="page">
       <header>
         <h2>Live</h2>
-        <p>Cameras, recent detections, and whether this site is recognising people.</p>
+        <p>Who is in the shop, and whether it is reaching head office.</p>
       </header>
 
-      {error && <div className="err">{error}</div>}
+      {error && <div className="err"><Icon.Warning size={15} />{error}</div>}
 
-      <div className="grid cols-4" style={{ marginBottom: 16 }}>
+      <PipelineStrip pipe={pipe} cameras={cameras} up={up} />
-        <Stat label="People known" value={gallery.identities ?? '—'} />
+
-        <Stat label="Sightings" value={gallery.sightings ?? '—'} />
+      <GettingStarted cameras={cameras} arrivals={arrivals} onNavigate={onNavigate} />
-        <Stat label="Cameras live"
+
-              value={`${cameras.filter(c => c.connected).length}/${cameras.length || 0}`} />
+      <div className="panel arrivals-panel">
-        <Stat label="Below quality gate"
+        <div className="panelhead">
-              value={cameras.length ? `${Math.round(worst * 100)}%` : '—'}
+          <h3>Who just walked in</h3>
-              tone={worst > 0.5 ? 'bad' : worst > 0.2 ? 'warn' : 'ok'}
+          {arrivals.length > 0 && <span className="note">{arrivals.length} today</span>}
-              sub={worst > 0.5 ? 'Most visitors are being missed — check camera placement'
+        </div>
-                               : 'Share of faces too poor to enrol'} />
+        <div className="panelbody flush">
+          {arrivals.length === 0
+            ? <div className="empty">
+                <Icon.NoFaces size={34} />
+                <b>Nobody yet</b>
+                <p>Customers appear here the moment a camera recognises a face.</p>
+              </div>
+            : <div className="arrivals">
+                {arrivals.slice(0, 30).map((e, i) => (
+                  <Arrival key={`${e.ts}-${i}`} e={e} fresh={i === 0 && freshest} />
+                ))}
+              </div>}
+        </div>
       </div>
 
-      <Pipeline pipe={pipe} />
+      <div className="metrics" style={{ marginTop: 'var(--sp-4)' }}>
-
+        <Metric k="People known" v={gallery.identities ?? '—'} />
-      <div className="grid cols-2">
+        <Metric k="Sightings" v={gallery.sightings ?? '—'} />
-        <div>
+        <Metric k="Cameras live" v={cameras.length ? `${up}/${cameras.length}` : '—'}
-          <div className="card">
+                tone={!cameras.length ? null : up === 0 ? 'bad' : up < cameras.length ? 'warn' : 'ok'} />
-            <h3>Cameras</h3>
+        <Metric k="Faces too poor to use"
-            {cameras.length === 0
+                v={cameras.length ? `${Math.round(worst * 100)}%` : '—'}
-              ? <div className="empty">No cameras yet. Add one in Cameras.</div>
+                tone={worst > 0.5 ? 'bad' : worst > 0.2 ? 'warn' : 'ok'}
-              : <div className="feeds">
+                s={worst > 0.5 ? 'Most visitors are being missed — move the camera'
-                  {cameras.map(c => (
+                               : 'Share of faces below the enrolment gate'} />
-                    <div className="feed" key={c.camera_id}>
-                      {cams[c.camera_id]
-                        ? <img src={cams[c.camera_id]} alt={c.camera_id} />
-                        : <div style={{ aspectRatio: '16/9' }} />}
-                      <div className="cap">
-                        <span>{c.camera_id}</span>
-                        <span className={`pill ${c.connected ? 'ok' : 'bad'}`}>
-                          <i className={`dot ${c.connected ? 'ok' : 'bad'}`} />
-                          {c.connected ? 'live' : 'offline'}
-                        </span>
-                      </div>
-                    </div>
-                  ))}
-                </div>}
-          </div>
-        </div>
-
-        <div className="card">
-          <h3>Recent detections</h3>
-          {events.length === 0
-            ? <div className="empty">Nothing detected yet.</div>
-            : <ul className="events">
-                {events.map((e, i) => <EventRow key={i} e={e} />)}
-              </ul>}
-        </div>
       </div>
     </div>
   )
 }
 
-// Whether anything is actually reaching head office. Without this the app can
+// The first five minutes, as a checklist that ticks itself.
-// look perfectly healthy while every detection piles up on disk unsent — which
+//
-// is exactly what it did before the bridge existed.
+// Before this the Live screen after install was "Nobody yet" over a row of
-function Pipeline({ pipe }) {
+// 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'
+  const name = e.data?.label || 'Unrecognised'
+  const bits = [e.data?.gender, e.data?.age ?? e.data?.age_range, e.data?.emotion].filter(Boolean)
+  const sim = typeof e.data?.similarity === 'number' ? e.data.similarity : null
+
+  return (
+    <article className={`arrival ${isNew ? 'is-new' : 'is-seen'} ${fresh ? 'fresh' : ''}`}>
+      <div className="avatar">{avatarText(name)}</div>
+      <div className="who">
+        <div className="name">{name}</div>
+        <div className="meta">
+          {e.camera_id}
+          {bits.length > 0 && <> · {bits.join(', ')}</>}
+          {sim !== null && !isNew && <> · match {sim.toFixed(2)}</>}
+        </div>
+      </div>
+      <div className="right">
+        <span className={`tag ${isNew ? 'new' : 'seen'}`}>{isNew ? 'new' : 'returning'}</span>
+        <span className="when">{fmtTime(e.ts)}</span>
+      </div>
+    </article>
+  )
+}
+
+// "Visitor 13" must show 13, not V1 — initials() would give the same two
+// characters to Visitor 10, 13 and 15, and read as the reference V-1 for a
+// fourth person. Found by looking at the screen, not by a test.
+function avatarText(name) {
+  const auto = /^Visitor (\d+)$/.exec(String(name).trim())
+  if (auto) return auto[1]
+  const words = String(name).trim().split(/\s+/).filter(Boolean)
+  if (!words.length) return '?'
+  return (words[0][0] + (words[1]?.[0] ?? '')).toUpperCase()
+}
+
+// One line, above everything, answering the question every other screen is a
+// detail of: is this shop working, and is anything leaving it.
+function PipelineStrip({ pipe, cameras, up }) {
   if (!pipe) return null
-  // A PC set up on its own is not "not linked yet" — nothing is coming, and
+
-  // saying so with an idle dot beside a count of zero reads as a fault.
+  // A PC set up on its own is not "not linked yet" — nothing is coming, and an
+  // idle dot beside a count of zero reads as a fault.
   if (pipe.standalone) {
     return (
-      <div className="card" style={{ marginBottom: 16, display: 'flex',
+      <div className="statusbar">
-                                     gap: 10, alignItems: 'center' }}>
+        <span className="item"><i className="dot ok" /><b>Running on this PC only</b></span>
-        <i className="dot ok" />
+        <span className="sep" />
-        <strong style={{ fontSize: 13 }}>Running on this PC only</strong>
+        <span className="item note">Recognition and customers stay here.</span>
-        <span className="note">Recognition and customers stay here.</span>
+        <span className="grow" />
+        <span className="item note"><Icon.Signal size={14} />{up} of {cameras.length} cameras</span>
       </div>
     )
   }
+
   const stuck = pipe.claimed && !pipe.broker_up
+  const tone = !pipe.claimed ? 'idle' : pipe.broker_up ? 'ok' : 'bad'
+  const text = !pipe.claimed ? 'Not linked to head office'
+    : pipe.broker_up ? 'Sending to head office' : 'Offline — saving locally'
+
   return (
-    <div className="card" style={{ marginBottom: 16, display: 'flex',
+    <div className="statusbar">
-                                   gap: 22, alignItems: 'center', flexWrap: 'wrap' }}>
+      <span className="item">
-      <span style={{ display: 'flex', alignItems: 'center', gap: 8 }}>
+        {pipe.broker_up ? <Icon.Cloud size={15} /> : <Icon.CloudOff size={15} />}
-        <i className={`dot ${!pipe.claimed ? 'idle' : pipe.broker_up ? 'ok' : 'bad'}`} />
+        <i className={`dot ${tone}`} /><b>{text}</b>
-        <strong style={{ fontSize: 13 }}>
-          {!pipe.claimed ? 'Not linked to head office'
-            : pipe.broker_up ? 'Sending to head office' : 'Offline — saving locally'}
-        </strong>
       </span>
-      <span className="note">{pipe.accepted} recorded today</span>
+      <span className="sep" />
+      <span className="item note">{pipe.accepted} recorded today</span>
       {pipe.queued > 0 && (
-        <span className="note" style={stuck ? { color: 'var(--warn)' } : undefined}>
+        <span className={`item note ${stuck ? 'warn' : ''}`}>{pipe.queued} waiting to send</span>
-          {pipe.queued} waiting to send
-        </span>
       )}
       {pipe.dropped > 0 && (
-        <span className="note" style={{ color: 'var(--bad)' }}>
+        <span className="item note bad"><Icon.Warning size={14} />{pipe.dropped} lost — this PC was offline too long</span>
-          {pipe.dropped} lost — this PC was offline too long
-        </span>
       )}
+      <span className="grow" />
+      <span className="item note"><Icon.Signal size={14} />{up} of {cameras.length} cameras</span>
     </div>
   )
 }
 
-function EventRow({ e }) {
+function Metric({ k, v, s, tone }) {
-  const cls = e.type === 'person.new' ? 'new'
-    : e.type === 'person.seen' ? 'seen'
-    : e.type === 'person.missed' ? 'miss' : ''
-  const age = e.data?.age ?? e.data?.age_range
-  const extra = [e.data?.gender, age, e.data?.emotion].filter(Boolean).join(', ')
   return (
-    <li>
+    <div className={`metric ${tone ?? ''}`}>
-      <span className="when">{fmtTime(e.ts)}</span>
+      <div className="metric-k">{k}</div>
-      <span className={`tag ${cls}`}>{label(e.type)}</span>
+      <div className="metric-v">{v}</div>
-      <span style={{ flex: 1, minWidth: 0 }}>
+      {s && <div className="metric-s">{s}</div>}
-        {e.data?.label || e.camera_id}
-        {extra && <span className="note"> · {extra}</span>}
-      </span>
-    </li>
-  )
-}
-
-// The event names are internal; a shop manager should not have to learn them.
-function label(type) {
-  return {
-    'person.new': 'new',
-    'person.seen': 'returning',
-    'person.missed': 'missed',
-    'camera.up': 'camera up',
-    'camera.down': 'camera down',
-    'identity.merged': 'merged',
-  }[type] ?? type
-}
-
-function Stat({ label, value, sub, tone }) {
-  return (
-    <div className="card stat">
-      <h3>{label}</h3>
-      <div className="value" style={tone ? { color: `var(--${tone})` } : undefined}>
-        {value}
-      </div>
-      {sub && <div className="sub">{sub}</div>}
     </div>
   )
 }
 
-// Stream URLs are fetched once per camera and then left alone: reassigning an
+// True for a few seconds after a genuinely new arrival, so the top card can
-// MJPEG <img> src restarts the stream, so rebuilding them on every poll would
+// announce itself once. Keyed on the timestamp rather than the array, which
-// make every feed flicker permanently.
+// changes identity on every poll.
-function useCameraFeeds() {
+function useFreshest(top) {
-  const [urls, setUrls] = useState({})
+  const [fresh, setFresh] = useState(false)
-  const { data } = usePolled(() => api.cameras(), 10000)
+  const seen = useRef(null)
   useEffect(() => {
-    let cancelled = false
+    if (!top || top.ts === seen.current) return
-    ;(async () => {
+    const first = seen.current === null
-      const next = {}
+    seen.current = top.ts
-      for (const cam of data ?? []) {
+    if (first) return              // do not flash the whole list on mount
-        if (urls[cam.id]) { next[cam.id] = urls[cam.id]; continue }
+    setFresh(true)
-        try { next[cam.id] = await api.streamURL(cam.id) } catch { /* engine down */ }
+    const id = setTimeout(() => setFresh(false), 1200)
-      }
+    return () => clearTimeout(id)
-      const changed = Object.keys(next).length !== Object.keys(urls).length ||
+  }, [top?.ts])
-        Object.keys(next).some(k => next[k] !== urls[k])
+  return fresh
-      if (!cancelled && changed) setUrls(next)
-    })()
-    return () => { cancelled = true }
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [data])
-  return urls
 }

desktop/frontend/src/views/Login.jsx

@@ -1,5 +1,7 @@
 import { useState } from 'react'
 import { api, message } from '../bridge.js'
+import * as Icon from '../ui/icons.jsx'
+import logo from '../assets/loyaly-mark.png'
 
 // The gate. Nothing else in the app is reachable until this succeeds, because
 // the broker credentials and the customer database both live behind it.
@@ -24,10 +26,11 @@ export default function Login({ onDone }) {
   return (
     <div className="login">
       <div className="box">
+        <span className="mark"><img src={logo} alt="" /></span>
         <h1>Behavision</h1>
         <p className="lead">Sign in to connect this PC to your store.</p>
         <form onSubmit={submit}>
-          {error && <div className="err">{error}</div>}
+          {error && <div className="err"><Icon.Warning size={15} />{error}</div>}
           <label className="field">
             <span>Email</span>
             <input type="email" value={email} autoComplete="username" required

desktop/frontend/src/views/Setup.jsx

@@ -1,5 +1,7 @@
 import { useState } from 'react'
 import { api, message } from '../bridge.js'
+import * as Icon from '../ui/icons.jsx'
+import logo from '../assets/loyaly-mark.png'
 
 // Linking this PC to a shop — the first thing that happens on a new install,
 // and until now the one thing the app could not do.
@@ -13,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()
@@ -38,15 +39,69 @@ 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">
-        <h1>{onCancel ? 'Link to head office' : 'Set up this PC'}</h1>
+        <span className="mark"><img src={logo} alt="" /></span>
+        <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">{error}</div>}
+          {error && <div className="err"><Icon.Warning size={15} />{error}</div>}
           <label className="field">
             <span>Installation code</span>
             {/* Uppercase and letter-spaced because the code arrives read aloud
@@ -64,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
+          Don’t have one? Whoever runs head office creates it under the shop: <em>Shops → the shop → Set up a shop PC</em>.
-          create one from the Behavision platform, under the shop.
         </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}>
+            ? <button type="button" className="linkbtn" onClick={onCancel}>Not now — go back</button>
-                Not now — go back
+            : <button type="button" className="linkbtn" onClick={() => setPath(null)}><Icon.Back size={14} /> Back</button>}
-              </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>
-              </>}
         </div>
       </div>
     </div>

desktop/go.mod

@@ -14,16 +14,34 @@ require (
 )
 
 require (
+	github.com/bep/debounce v1.2.1 // indirect
 	github.com/eclipse/paho.mqtt.golang v1.4.3 // indirect
+	github.com/go-ole/go-ole v1.2.6 // indirect
 	github.com/godbus/dbus/v5 v5.1.0 // indirect
+	github.com/google/uuid v1.3.0 // indirect
 	github.com/gorilla/websocket v1.5.0 // indirect
+	github.com/jchv/go-winloader v0.0.0-20210711035445-715c2860da7e // indirect
+	github.com/labstack/echo/v4 v4.10.2 // indirect
+	github.com/labstack/gommon v0.4.0 // indirect
 	github.com/leaanthony/go-ansi-parser v1.6.0 // indirect
+	github.com/leaanthony/gosod v1.0.3 // indirect
 	github.com/leaanthony/slicer v1.6.0 // indirect
 	github.com/leaanthony/u v1.1.0 // indirect
+	github.com/mattn/go-colorable v0.1.13 // indirect
+	github.com/mattn/go-isatty v0.0.19 // indirect
+	github.com/pkg/browser v0.0.0-20210911075715-681adbf594b8 // indirect
 	github.com/pkg/errors v0.9.1 // indirect
 	github.com/rivo/uniseg v0.4.4 // indirect
+	github.com/samber/lo v1.38.1 // indirect
+	github.com/tkrajina/go-reflector v0.5.6 // indirect
+	github.com/valyala/bytebufferpool v1.0.0 // indirect
+	github.com/valyala/fasttemplate v1.2.2 // indirect
 	github.com/wailsapp/go-webview2 v1.0.16 // indirect
+	github.com/wailsapp/mimetype v1.4.1 // indirect
+	golang.org/x/crypto v0.23.0 // indirect
+	golang.org/x/exp v0.0.0-20230522175609-2e198f4a06a1 // indirect
 	golang.org/x/net v0.25.0 // indirect
 	golang.org/x/sync v0.1.0 // indirect
 	golang.org/x/sys v0.20.0 // indirect
+	golang.org/x/text v0.15.0 // indirect
 )

desktop/go.sum

@@ -3,6 +3,7 @@ fyne.io/systray v1.12.2/go.mod h1:RVwqP9nYMo7h5zViCBHri2FgjXF7H2cub7MAq4NSoLs=
 github.com/bep/debounce v1.2.1 h1:v67fRdBA9UQu2NhLFXrSg0Brw7CexQekrBwDMM8bzeY=
 github.com/bep/debounce v1.2.1/go.mod h1:H8yggRPQKLUhUoqrJC1bO2xNya7vanpDl7xR3ISbCJ0=
 github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
 github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/eclipse/paho.mqtt.golang v1.4.3 h1:2kwcUGn8seMUfWndX0hGbvH8r7crgcJguQNCyp70xik=
 github.com/eclipse/paho.mqtt.golang v1.4.3/go.mod h1:CSYvoAlsMkhYOXh/oKyxa8EcBci6dVkLCbo5tTC1RIE=
@@ -20,6 +21,7 @@ github.com/labstack/echo/v4 v4.10.2 h1:n1jAhnq/elIFTHr1EYpiYtyKgx4RW9ccVgkqByZaN
 github.com/labstack/echo/v4 v4.10.2/go.mod h1:OEyqf2//K1DFdE57vw2DRgWY0M7s65IVQO2FzvI4J5k=
 github.com/labstack/gommon v0.4.0 h1:y7cvthEAEbU0yHOf4axH8ZG2NH8knB9iNSoTO8dyIk8=
 github.com/labstack/gommon v0.4.0/go.mod h1:uW6kP17uPlLJsD3ijUYn3/M5bAxtlZhMI6m3MFxTMTM=
+github.com/leaanthony/debme v1.2.1 h1:9Tgwf+kjcrbMQ4WnPcEIUcQuIZYqdWftzZkBr+i/oOc=
 github.com/leaanthony/debme v1.2.1/go.mod h1:3V+sCm5tYAgQymvSOfYQ5Xx2JCr+OXiD9Jkw3otUjiA=
 github.com/leaanthony/go-ansi-parser v1.6.0 h1:T8TuMhFB6TUMIUm0oRrSbgJudTFw9csT3ZK09w0t4Pg=
 github.com/leaanthony/go-ansi-parser v1.6.0/go.mod h1:+vva/2y4alzVmmIEpk9QDhA7vLC5zKDTRwfZGOp3IWU=
@@ -30,6 +32,7 @@ github.com/leaanthony/slicer v1.6.0 h1:1RFP5uiPJvT93TAHi+ipd3NACobkW53yUiBqZheE/
 github.com/leaanthony/slicer v1.6.0/go.mod h1:o/Iz29g7LN0GqH3aMjWAe90381nyZlDNquK+mtH2Fj8=
 github.com/leaanthony/u v1.1.0 h1:2n0d2BwPVXSUq5yhe8lJPHdxevE2qK5G99PMStMZMaI=
 github.com/leaanthony/u v1.1.0/go.mod h1:9+o6hejoRljvZ3BzdYlVL0JYCwtnAsVuN9pVTQcaRfI=
+github.com/matryer/is v1.4.0 h1:sosSmIWwkYITGrxZ25ULNDeKiMNzFSr4V/eqBQP0PeE=
 github.com/matryer/is v1.4.0/go.mod h1:8I/i5uYgLzgsgEloJE1U6xx5HkBQpAZvepWuujKwMRU=
 github.com/mattn/go-colorable v0.1.11/go.mod h1:u5H1YNBxpqRaxsYJYSkiCWKzEfiAb1Gb520KVy5xxl4=
 github.com/mattn/go-colorable v0.1.13 h1:fFA4WZxdEF4tXPZVKMLwD8oUnCTTo08duU7wxecdEvA=
@@ -42,6 +45,7 @@ github.com/pkg/browser v0.0.0-20210911075715-681adbf594b8 h1:KoWmjvw+nsYOo29YJK9
 github.com/pkg/browser v0.0.0-20210911075715-681adbf594b8/go.mod h1:HKlIX3XHQyzLZPlr7++PzdhaXEj94dEiJgZDTsxEqUI=
 github.com/pkg/errors v0.9.1 h1:FEBLx1zS214owpjy7qsBeixbURkuhQAwrK5UwLGTwt4=
 github.com/pkg/errors v0.9.1/go.mod h1:bwawxfHBFNV+L2hUp1rHADufV3IMtnDRdf1r5NINEl0=
+github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
 github.com/rivo/uniseg v0.2.0/go.mod h1:J6wj4VEh+S6ZtnVlnTBMWIodfgj8LQOQFoIToxlJtxc=
 github.com/rivo/uniseg v0.4.4 h1:8TfxU8dW6PdqD27gjM8MVNuicgxIjxpm4K7x4jp8sis=
@@ -50,6 +54,8 @@ github.com/samber/lo v1.38.1 h1:j2XEAqXKb09Am4ebOg31SpvzUTTs6EN3VfgeLUhPdXM=
 github.com/samber/lo v1.38.1/go.mod h1:+m/ZKRl6ClXCE2Lgf3MsQlWfh4bn1bz6CXEOxnEXnEA=
 github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
 github.com/stretchr/testify v1.7.0/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
+github.com/stretchr/testify v1.8.4 h1:CcVxjf3Q8PM0mHUKJCdn+eZZtm5yQwehR5yeSVQQcUk=
+github.com/stretchr/testify v1.8.4/go.mod h1:sz/lmYIOXD/1dqDmKjjqLyZ2RngseejIcXlSw2iwfAo=
 github.com/tkrajina/go-reflector v0.5.6 h1:hKQ0gyocG7vgMD2M3dRlYN6WBBOmdoOzJ6njQSepKdE=
 github.com/tkrajina/go-reflector v0.5.6/go.mod h1:ECbqLgccecY5kPmPmXg1MrHW585yMcDkVl6IvJe64T4=
 github.com/valyala/bytebufferpool v1.0.0 h1:GqA5TC/0021Y/b9FG4Oi9Mr3q7XYx6KllzawFIhcdPw=
@@ -92,3 +98,5 @@ golang.org/x/tools v0.0.0-20180917221912-90fa682c2a6e/go.mod h1:n7NCudcB/nEzxVGm
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
 gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
 gopkg.in/yaml.v3 v3.0.0-20210107192922-496545a6307b/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

desktop/icons.go

@@ -2,28 +2,32 @@ package main
 
 import (
 	"bytes"
+	_ "embed"
 	"encoding/binary"
 	"image"
 	"image/color"
 	"image/png"
 	"runtime"
+	"sync"
 
 	agentpaths "github.com/loyaly/behavision-agent/pkg/paths"
 )
 
-// iconFor renders the tray icon at run time rather than embedding four PNGs.
+// iconFor renders the tray icon at run time: the Loyaly mark with a state
+// dot in the corner. Green, amber, red or grey is the only thing a taskbar
+// conveys at this size, and the mark is what makes it OURS among a row of
+// other icons - a plain coloured circle read as a generic status light.
 //
-// A 16x16 filled circle is all the taskbar shows at this size, and generating
+// The mark is embedded once at 128px and scaled down here, so the four
-// it means the four states cannot drift apart visually or have one file go
+// states cannot drift apart and no file can go missing from a build.
-// missing from a build.
 //
 // The encoding is per-platform and is NOT cosmetic. systray writes these bytes
 // to a temp file and, on Windows, hands the path to LoadImageW with
-// IMAGE_ICON|LR_LOADFROMFILE — which decodes .ico and nothing else. A PNG
+// IMAGE_ICON|LR_LOADFROMFILE - which decodes .ico and nothing else. A PNG
 // there returns 0, systray logs "unable to set icon", and the product ships
 // with no tray icon at all: the one control surface a shop manager has.
 func iconFor(state string) []byte {
-	img := circle(colorFor(state))
+	img := trayImage(colorFor(state))
 	if runtime.GOOS == "windows" {
 		return encodeICO(img)
 	}
@@ -46,30 +50,93 @@ func colorFor(state string) color.RGBA {
 	}
 }
 
-const iconSize = 16
+// 32px rather than 16: Windows shows 16 at 100% scaling and 24 at 150%, and
+// scaling a 32 down looks right at both, where a 16 scaled up looks like 2005.
+const iconSize = 32
 
-func circle(c color.RGBA) *image.RGBA {
+//go:embed tray-logo.png
-	img := image.NewRGBA(image.Rect(0, 0, iconSize, iconSize))
+var trayLogoPNG []byte
-	const r = 6.5
+
-	cx, cy := float64(iconSize)/2-0.5, float64(iconSize)/2-0.5
+var (
+	trayLogoOnce sync.Once
+	trayLogo     *image.RGBA
+)
+
+// logo is the embedded mark, decoded once and box-filtered down to iconSize.
+// A box filter rather than nearest-neighbour: 128->32 is an exact 4x4 average
+// and nearest would drop three pixels in four, which shreds the thin outline.
+func logo() *image.RGBA {
+	trayLogoOnce.Do(func() {
+		src, err := png.Decode(bytes.NewReader(trayLogoPNG))
+		if err != nil {
+			trayLogo = image.NewRGBA(image.Rect(0, 0, iconSize, iconSize))
+			return
+		}
+		b := src.Bounds()
+		f := b.Dx() / iconSize
+		out := image.NewRGBA(image.Rect(0, 0, iconSize, iconSize))
+		for y := 0; y < iconSize; y++ {
+			for x := 0; x < iconSize; x++ {
+				var r, g, bl, a uint64
+				for dy := 0; dy < f; dy++ {
+					for dx := 0; dx < f; dx++ {
+						// Premultiplied so transparent pixels do not drag the
+						// colour of the edge towards black.
+						pr, pg, pb, pa := src.At(b.Min.X+x*f+dx, b.Min.Y+y*f+dy).RGBA()
+						r += uint64(pr)
+						g += uint64(pg)
+						bl += uint64(pb)
+						a += uint64(pa)
+					}
+				}
+				n := uint64(f * f)
+				out.SetRGBA(x, y, color.RGBA{
+					R: uint8(r / n >> 8), G: uint8(g / n >> 8), B: uint8(bl / n >> 8), A: uint8(a / n >> 8),
+				})
+			}
+		}
+		trayLogo = out
+	})
+	return trayLogo
+}
+
+// trayImage is the mark with a state dot over its bottom-right corner, ringed
+// so it reads against both the yellow of the mark and a dark taskbar.
+func trayImage(c color.RGBA) *image.RGBA {
+	base := logo()
+	img := image.NewRGBA(base.Bounds())
+	copy(img.Pix, base.Pix)
+	const r = 6.0
+	cx, cy := float64(iconSize)-r-0.5, float64(iconSize)-r-0.5
+	ring := color.RGBA{R: 0x11, G: 0x14, B: 0x18, A: 0xFF}
 	for y := 0; y < iconSize; y++ {
 		for x := 0; x < iconSize; x++ {
 			dx, dy := float64(x)-cx, float64(y)-cy
 			d := dx*dx + dy*dy
 			switch {
-			case d <= (r-1)*(r-1):
+			case d <= (r-1.5)*(r-1.5):
 				img.SetRGBA(x, y, c)
 			case d <= r*r:
+				img.SetRGBA(x, y, ring)
+			case d <= (r+1)*(r+1):
 				// One-pixel feathered edge; a hard-aliased circle looks broken
 				// next to every other icon in the tray.
-				a := uint8(float64(c.A) * (r*r - d) / (r*r - (r-1)*(r-1)))
+				a := uint8(255 * ((r+1)*(r+1) - d) / ((r+1)*(r+1) - r*r))
-				img.SetRGBA(x, y, color.RGBA{R: c.R, G: c.G, B: c.B, A: a})
+				bg := img.RGBAAt(x, y)
+				img.SetRGBA(x, y, blend(bg, ring, a))
 			}
 		}
 	}
 	return img
 }
 
+func blend(under, over color.RGBA, a uint8) color.RGBA {
+	fa := float64(a) / 255
+	mix := func(u, o uint8) uint8 { return uint8(float64(u)*(1-fa) + float64(o)*fa) }
+	ua := float64(under.A)/255*(1-fa) + fa
+	return color.RGBA{R: mix(under.R, over.R), G: mix(under.G, over.G), B: mix(under.B, over.B), A: uint8(ua * 255)}
+}
+
 // encodeICO writes a single-image .ico holding an uncompressed 32-bit DIB.
 //
 // Vista and later also accept a PNG stored inside the .ico container, which
@@ -94,8 +161,8 @@ func encodeICO(img *image.RGBA) []byte {
 	// ICONDIRENTRY. 256 is encoded as 0 in these byte fields; at 16px it is moot.
 	b.WriteByte(byte(w))
 	b.WriteByte(byte(h))
-	b.WriteByte(0) // palette size: none
+	b.WriteByte(0)                                      // palette size: none
-	b.WriteByte(0) // reserved
+	b.WriteByte(0)                                      // reserved
 	binary.Write(&b, binary.LittleEndian, uint16(1))    // colour planes
 	binary.Write(&b, binary.LittleEndian, uint16(32))   // bits per pixel
 	binary.Write(&b, binary.LittleEndian, uint32(dib))  // bytes in resource

desktop/icons_test.go

@@ -13,7 +13,7 @@ import (
 // nothing — and nothing on a Mac could notice. These tests are the substitute
 // for the Windows box we do not have.
 func TestEncodeICOIsAValidIconFile(t *testing.T) {
-	b := encodeICO(circle(colorFor("ok")))
+	b := encodeICO(trayImage(colorFor("ok")))
 	if len(b) < 22 {
 		t.Fatalf("far too short: %d bytes", len(b))
 	}
@@ -48,12 +48,13 @@ func TestEncodeICOIsAValidIconFile(t *testing.T) {
 
 func TestEncodeICOPixelsAreBGRABottomUp(t *testing.T) {
 	want := colorFor("error") // red: distinguishable from B and G if swapped
-	img := circle(want)
+	img := trayImage(want)
 	b := encodeICO(img)
-	// Centre of the circle, which is solid fill. Bottom-up means image row
+	// Centre of the state dot, which is solid fill. Bottom-up means image row
-	// iconSize/2 lands at DIB row iconSize/2-1 counting from the start.
+	// y lands at DIB row iconSize-1-y counting from the start.
-	row := iconSize - 1 - iconSize/2
+	x, y := iconSize-6-1, iconSize-6-1
-	i := 22 + 40 + (row*iconSize+iconSize/2)*4
+	row := iconSize - 1 - y
+	i := 22 + 40 + (row*iconSize+x)*4
 	got := b[i : i+4]
 	if !bytes.Equal(got, []byte{want.B, want.G, want.R, 0xFF}) {
 		t.Errorf("centre pixel = % x, want % x (BGRA)",

desktop/internal/cloud/client.go

@@ -9,6 +9,7 @@ package cloud
 import (
 	"bytes"
 	"context"
+	"encoding/base64"
 	"encoding/json"
 	"errors"
 	"fmt"
@@ -107,8 +108,16 @@ func (c *Client) do(ctx context.Context, method, path string, body, out any) err
 	}
 	if rerr := c.Refresh(ctx); rerr != nil {
 		// The refresh token is gone too, so this really is a sign-in, not a
-		// transient failure. Report it as such so the UI shows the login sheet
+		// transient failure. Forget the session - in memory AND on disk, through
-		// rather than an error dialog.
+		// the same callback that persists rotations - so the app goes back to
+		// Login instead of showing "session expired" on every screen until
+		// somebody finds Sign out. Seen on a PC that had been claimed against a
+		// demo head office and then re-claimed against the real one: the old
+		// login sat there, dead, for the whole session.
+		c.Clear()
+		if c.onRefresh != nil {
+			c.onRefresh(Session{})
+		}
 		return ErrUnauthorized
 	}
 	return c.send(ctx, method, path, raw, out)
@@ -179,9 +188,16 @@ func (c *Client) send(ctx context.Context, method, path string, raw []byte, out
 	switch {
 	case resp.StatusCode == http.StatusUnauthorized && e.Error == "token_expired":
 		return errTokenExpired
-	case resp.StatusCode == http.StatusUnauthorized:
+	case resp.StatusCode == http.StatusUnauthorized && tok != "":
+		// A 401 on a call we sent a session with: the session is the problem.
 		return ErrUnauthorized
 	case resp.StatusCode >= 400:
+		// Every other 4xx/5xx - including a 401 on a call that carried NO
+		// session, such as redeeming an installation code - is about the
+		// request, and the server wrote its message for exactly this moment.
+		// Mapping those to "session expired" told an installer their session
+		// had lapsed on a screen where they had never signed in, and hid
+		// "That installation code is not valid" behind it.
 		msg := e.Message
 		if msg == "" {
 			msg = fmt.Sprintf("%s %s: %s", method, path, resp.Status)
@@ -393,6 +409,11 @@ type Photo struct {
 	ExpiresIn int    `json:"expires_in"`
 	Available bool   `json:"available"`
 	Reason    string `json:"reason"`
+	// Auth is set by the server when the URL is one of its own endpoints and
+	// needs this session's bearer, rather than a presigned object-store link
+	// that carries its own signature. It never reaches the front end - see
+	// VisitorImage, which resolves it here.
+	Auth bool `json:"auth"`
 }
 
 // VisitorImage fetches a short-lived signed link to this customer's photo.
@@ -413,9 +434,91 @@ func (c *Client) VisitorImage(ctx context.Context, id string) (Photo, error) {
 		return Photo{}, err
 	}
 	out.Available = out.URL != ""
+
+	// A deployment with no object storage serves the photo from the API itself,
+	// which means a RELATIVE url that needs this session's bearer. Neither
+	// works in the window: a webview <img> resolves a relative src against
+	// wails://, not against the cloud, and it cannot send an Authorization
+	// header at all - so handing it straight through renders a broken picture
+	// on exactly the deployments that have just started storing photos.
+	//
+	// Fetched here and passed as a data: URI. The alternative is a local proxy
+	// inside this process holding the session, which is a second authenticated
+	// surface on the shop PC to get wrong. One photo per sheet, ~90 KB, and the
+	// server already records the read where the link was handed out.
+	if out.Available && out.Auth {
+		data, err := c.fetchImage(ctx, out.URL)
+		if err != nil {
+			// The record itself is worth far more than the picture, so this is
+			// an absence with a reason rather than a failure that blanks the
+			// customer - the same rule the whole image path follows.
+			return Photo{Reason: "That photo could not be loaded."}, nil
+		}
+		out.URL = data
+		out.Auth = false
+	}
 	return out, nil
 }
 
+// fetchImage reads an image this server holds itself and returns a data: URI.
+//
+// Deliberately not routed through send(): that decodes JSON into `out`, and
+// these are bytes. It shares the token and the expiry retry, because a sheet
+// opened twelve hours after the last one must not show a broken photo.
+func (c *Client) fetchImage(ctx context.Context, path string) (string, error) {
+	body, err := c.imageBytes(ctx, path)
+	if errors.Is(err, errTokenExpired) {
+		if rerr := c.Refresh(ctx); rerr != nil {
+			return "", rerr
+		}
+		body, err = c.imageBytes(ctx, path)
+	}
+	if err != nil {
+		return "", err
+	}
+	return "data:image/jpeg;base64," + base64.StdEncoding.EncodeToString(body), nil
+}
+
+// maxPhotoBytes bounds what will be pulled into memory and then base64'd into
+// the window. Face crops are ~20 KB and a camera still ~100 KB; anything near
+// this is a different file or a fault, and a shop PC should not spend its
+// memory finding that out.
+const maxPhotoBytes = 4 << 20
+
+func (c *Client) imageBytes(ctx context.Context, path string) ([]byte, error) {
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, c.Base+path, nil)
+	if err != nil {
+		return nil, err
+	}
+	c.mu.RLock()
+	tok := c.token
+	c.mu.RUnlock()
+	if tok != "" {
+		req.Header.Set("Authorization", "Bearer "+tok)
+	}
+	resp, err := c.http.Do(req)
+	if err != nil {
+		return nil, fmt.Errorf("cannot reach %s: %w", c.Base, err)
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode == http.StatusUnauthorized {
+		var e struct {
+			Error string `json:"error"`
+		}
+		body, _ := io.ReadAll(io.LimitReader(resp.Body, 8192))
+		_ = json.Unmarshal(body, &e)
+		if e.Error == "token_expired" {
+			return nil, errTokenExpired
+		}
+		return nil, ErrUnauthorized
+	}
+	if resp.StatusCode >= 400 {
+		return nil, fmt.Errorf("photo: %s", resp.Status)
+	}
+	return io.ReadAll(io.LimitReader(resp.Body, maxPhotoBytes))
+}
+
 // ForgetVisitor erases a customer: face template, photo and profile.
 //
 // Irreversible by design — a soft-deleted face template is a retained
@@ -427,6 +530,27 @@ func (c *Client) ForgetVisitor(ctx context.Context, id string) error {
 		"/api/visitors/"+url.PathEscape(id), nil, nil)
 }
 
+// AssistantTurn is one message in the help conversation. The browser holds
+// the history and resends it; nothing is stored server-side.
+type AssistantTurn struct {
+	Role string `json:"role"`
+	Text string `json:"text"`
+}
+
+// AssistantAnswer is the reply, and the names of what it looked at - shown to
+// the user, because an assistant that silently ran a camera check would be
+// alarming and naming what it consulted makes a wrong answer traceable.
+type AssistantAnswer struct {
+	Text string   `json:"text"`
+	Used []string `json:"used,omitempty"`
+}
+
+// Ask puts a question to the head-office assistant as this signed-in user.
+func (c *Client) Ask(ctx context.Context, history []AssistantTurn) (AssistantAnswer, error) {
+	var out AssistantAnswer
+	return out, c.do(ctx, http.MethodPost, "/api/assistant", map[string]any{"history": history}, &out)
+}
+
 func (c *Client) VisitorHistory(ctx context.Context, id string, limit int) ([]Visit, error) {
 	var out []Visit
 	return out, c.do(ctx, http.MethodGet,
@@ -457,7 +581,10 @@ func (c *Client) Sales(ctx context.Context, from, to string) (SalesReport, error
 }
 
 type Customer struct {
-	ID          string `json:"id"`
+	ID string `json:"id"`
+	// Ref is the customer number - "V-42" - and is what staff say to each
+	// other. It is accepted anywhere this customer's id is.
+	Ref         string `json:"ref"`
 	Label       string `json:"label"`
 	FullName    string `json:"full_name"`
 	Phone       string `json:"phone"`

desktop/internal/cloud/client_test.go

@@ -6,6 +6,7 @@ import (
 	"errors"
 	"net/http"
 	"net/http/httptest"
+	"strings"
 	"testing"
 )
 
@@ -137,3 +138,43 @@ func TestVisitorIDIsPathEscaped(t *testing.T) {
 		t.Errorf("path = %q", got)
 	}
 }
+
+// Redeeming an installation code is the one call a fresh PC makes before it
+// has any session. When the server refuses it - wrong code, wrong head office -
+// it answers 401 with a message written for the installer. That message must
+// reach them: "session expired" on a screen where nobody has signed in sent a
+// real installer looking for a login problem that did not exist.
+func TestARefusedInstallationCodeSaysWhyNotSessionExpired(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.Header.Get("Authorization") != "" {
+			t.Errorf("enrol must not carry a session, got %q", r.Header.Get("Authorization"))
+		}
+		fail(w, http.StatusUnauthorized, "bad_token",
+			"That installation code is not valid. Ask for a new one.")
+	}))
+	t.Cleanup(srv.Close)
+	c := New(srv.URL) // deliberately no session
+
+	_, err := c.Bootstrap(context.Background(), "KWFH5S-EH46LT-EE4X47-OSOH7D")
+	if err == nil {
+		t.Fatal("a refused code must be an error")
+	}
+	if errors.Is(err, ErrUnauthorized) {
+		t.Fatalf("a refused code is not a session problem, got %v", err)
+	}
+	if !strings.Contains(err.Error(), "installation code is not valid") {
+		t.Fatalf("the server's own words should reach the installer, got %v", err)
+	}
+}
+
+// The other side of the same rule: a 401 on a call that DID carry a session is
+// a session problem, and must still read as one.
+func TestARejectedSessionStillReadsAsSessionExpired(t *testing.T) {
+	c := serve(t, func(w http.ResponseWriter, r *http.Request) {
+		fail(w, http.StatusUnauthorized, "unauthorized", "Sign in again.")
+	})
+	err := c.do(context.Background(), http.MethodGet, "/api/auth/me", nil, nil)
+	if !errors.Is(err, ErrUnauthorized) {
+		t.Fatalf("a 401 with a session should be ErrUnauthorized, got %v", err)
+	}
+}

desktop/internal/local/client.go

@@ -10,6 +10,7 @@ import (
 	"context"
 	"encoding/json"
 	"fmt"
+	agentconfig "github.com/loyaly/behavision-agent/pkg/config"
 	"io"
 	"net/http"
 	"strings"
@@ -20,7 +21,11 @@ type Client struct {
 	Base     string
 	User     string
 	Password string
-	http     *http.Client
+	// Creds re-reads the engine's generated credential when one is rejected.
+	// On a first run the app starts the engine, and the engine writes that
+	// file seconds later - after the app has already looked for it.
+	Creds *agentconfig.Creds
+	http  *http.Client
 }
 
 func New(base, user, password string) *Client {
@@ -48,8 +53,12 @@ func (c *Client) do(ctx context.Context, method, path string, body, out any) err
 	if body != nil {
 		req.Header.Set("Content-Type", "application/json")
 	}
-	if c.User != "" {
+	user, pass := c.User, c.Password
-		req.SetBasicAuth(c.User, c.Password)
+	if c.Creds != nil {
+		user, pass = c.Creds.Get()
+	}
+	if user != "" {
+		req.SetBasicAuth(user, pass)
 	}
 	resp, err := c.http.Do(req)
 	if err != nil {
@@ -105,6 +114,12 @@ func (c *Client) DeleteCamera(ctx context.Context, id string) error {
 	return c.do(ctx, http.MethodDelete, "/api/cameras/"+id, nil, nil)
 }
 
+// DiscoverCameras asks the engine to scan the shop's network. A few seconds.
+func (c *Client) DiscoverCameras(ctx context.Context) (map[string]any, error) {
+	var out map[string]any
+	return out, c.do(ctx, http.MethodGet, "/api/cameras/discover", nil, &out)
+}
+
 func (c *Client) TestCamera(ctx context.Context, cam map[string]any) (map[string]any, error) {
 	var out map[string]any
 	return out, c.do(ctx, http.MethodPost, "/api/cameras/test", cam, &out)

desktop/main.go

@@ -12,10 +12,12 @@ import (
 	"context"
 	"embed"
 	"log"
+	runtime2 "runtime"
 
 	"github.com/wailsapp/wails/v2"
 	"github.com/wailsapp/wails/v2/pkg/options"
 	"github.com/wailsapp/wails/v2/pkg/options/assetserver"
+	"github.com/wailsapp/wails/v2/pkg/options/mac"
 	"github.com/wailsapp/wails/v2/pkg/options/windows"
 	"github.com/wailsapp/wails/v2/pkg/runtime"
 )
@@ -27,10 +29,38 @@ func main() {
 	app := NewApp()
 	tray := newTray(app)
 
+	// One process per PC, enforced by the OS rather than by hoping.
+	//
+	// The window hides to the tray on close, so the ordinary next thing a shop
+	// assistant does is double-click the desktop shortcut again to get it
+	// back. Without this lock that started a SECOND complete copy: a second
+	// tray icon, a second engine supervisor on the same SQLite WAL and the
+	// same port - the "start twice" failure the agent package exists to
+	// prevent, on the one binary that never had the guard. Seen on a Windows
+	// install as a row of Behavision icons in the tray. A second launch now
+	// only brings the existing window to the front, which is what the person
+	// wanted in the first place.
+	var ctxRef context.Context
+	single := &options.SingleInstanceLock{
+		UniqueId: "ai.loyaly.behavision.desktop",
+		OnSecondInstanceLaunch: func(options.SecondInstanceData) {
+			if ctxRef != nil {
+				// The same four calls the tray uses, and for the same reasons:
+				// this runs on Wails' own listener goroutine rather than the
+				// window's thread, and the launching process holds the
+				// foreground, so without the flip the window comes back behind
+				// it. Double-clicking the desktop icon while it is already
+				// running is the single most common way anyone reaches this.
+				go openWindow(ctxRef)
+			}
+		},
+	}
+
 	err := wails.Run(&options.App{
-		Title:  "Behavision",
+		SingleInstanceLock: single,
-		Width:  1280,
+		Title:              "Behavision",
-		Height: 820,
+		Width:              1280,
+		Height:             820,
 		// Small enough to still be usable on a cramped shop-counter monitor.
 		MinWidth:    1024,
 		MinHeight:   640,
@@ -38,20 +68,48 @@ func main() {
 		// Closing the window hides it rather than quitting: the engine must
 		// keep recognising after a shop assistant clicks the X, and the tray
 		// is where they get the window back.
-		HideWindowOnClose: true,
+		// Windows hides on close because the tray is how the window comes
+		// back and how recognition is stopped. macOS has no tray here (see
+		// tray_run_darwin.go), so hiding would leave a running engine with no
+		// window, no tray and no way to reach either - force-quit or nothing.
+		// Closing the window therefore quits, which also stops the engine
+		// through OnShutdown. Same rule as the tray's Quit: never leave it
+		// watching with no visible control.
+		HideWindowOnClose: runtime2.GOOS == "windows",
 		OnStartup: func(ctx context.Context) {
+			ctxRef = ctx
 			app.startup(ctx)
 			tray.start(ctx)
 		},
 		OnBeforeClose: func(ctx context.Context) bool {
-			runtime.Hide(ctx)
+			if runtime2.GOOS != "windows" {
-			return true // prevent the close
+				return false // let it close, and OnShutdown stops the engine
+			}
+			// WindowHide, not Hide. They are different calls on Windows -
+			// WindowHide locks the OS thread for the Win32 work and Hide does
+			// not - and the tray's reopen uses WindowShow, so hiding through
+			// the other one leaves the pair mismatched. Same call, opposite
+			// direction.
+			runtime.WindowHide(ctx)
+			return true // prevent the close; the tray is how it comes back
 		},
 		OnShutdown: func(ctx context.Context) {
 			tray.stop()
+			app.proxy.stop()
 			app.StopEngine()
 		},
 		Bind: []any{app},
+		// This block has to EXIST, not merely be empty. Wails computes
+		// `zoomable = !Mac.DisableZoom` inside `if frontendOptions.Mac !=
+		// nil`, and the variable defaults to 0 - so leaving Mac unset does not
+		// mean "defaults", it means the green maximise button is created dead.
+		// There was a Windows block and no Mac one, so the window could not be
+		// zoomed on macOS and nothing anywhere said why.
+		Mac: &mac.Options{
+			WebviewIsTransparent: false,
+			WindowIsTranslucent:  false,
+			DisableZoom:          false,
+		},
 		Windows: &windows.Options{
 			WebviewIsTransparent: false,
 			WindowIsTranslucent:  false,

desktop/stream_proxy.go

@@ -0,0 +1,249 @@
+package main
+
+// streamProxy serves the engine's camera feeds to this app's own webview
+// without putting a credential in the page.
+//
+// What this replaces: StreamURL used to build
+// http://user:pass@127.0.0.1:8010/api/cameras/<id>/stream.mjpeg and hand it
+// to an <img>, with a comment saying the credentials were inline "so an <img>
+// tag can load it". It cannot. Chromium strips credentials from subresource
+// URLs and has since M59, and WebView2 is Chromium - so on the one platform
+// this product ships to, every camera tile on the shop floor renders as a
+// broken image. Measured against the same running engine: the app's Go-side
+// calls returned stats and people while an <img> on the very same URL failed,
+// and curl proved the URL itself answered 200. The engine was never the
+// problem; the browser was throwing the password away before it asked.
+//
+// So the password stays on this side of the process boundary. The webview
+// asks this loopback listener, the listener attaches Basic auth and relays
+// the engine's bytes back unchanged. It is the same reasoning the head-office
+// web app already follows in Shot.jsx, where an <img> equally cannot carry a
+// session and the bytes are fetched and handed over as an object URL.
+
+import (
+	"crypto/rand"
+	"crypto/subtle"
+	"encoding/hex"
+	"fmt"
+	"net"
+	"net/http"
+	"net/url"
+	"regexp"
+	"strings"
+	"sync"
+	"time"
+)
+
+// A camera id reaches this from the engine and from a person typing into the
+// Add Camera form. Validated rather than interpolated: without this a `..`
+// would climb out of the two paths below and turn a camera relay into a proxy
+// for any engine endpoint, with the credential helpfully attached.
+var safeCameraIDChars = regexp.MustCompile(`^[A-Za-z0-9_.-]{1,64}$`)
+
+// safeCameraID is the character check AND the two names that pass it and still
+// mean something to a path resolver.
+//
+// The pattern allows `.` because real camera ids contain them - which means it
+// also allows exactly `.` and `..`, and `/api/cameras/../stream.mjpeg` is not
+// the endpoint anyone intended. The id can never contain a slash (the path is
+// split on them before we get here), so these two strings are the entire
+// remaining traversal surface. Found by the test, not by reading the regex.
+func safeCameraID(id string) bool {
+	if id == "." || id == ".." {
+		return false
+	}
+	return safeCameraIDChars.MatchString(id)
+}
+
+type streamProxy struct {
+	mu     sync.RWMutex
+	ln     net.Listener
+	srv    *http.Server
+	client *http.Client
+	token  string
+	target string // engine origin, e.g. http://127.0.0.1:8010
+	user   string
+	pass   string
+}
+
+func newStreamProxy() *streamProxy { return &streamProxy{} }
+
+// start binds a loopback listener and begins relaying. Calling it again while
+// running is a no-op, so a restarted engine cannot leave two listeners behind.
+func (p *streamProxy) start(base, user, pass string) error {
+	p.mu.Lock()
+	defer p.mu.Unlock()
+	if p.srv != nil {
+		return nil
+	}
+
+	if !strings.HasPrefix(base, "http://") && !strings.HasPrefix(base, "https://") {
+		base = "http://" + base
+	}
+	if _, err := url.Parse(base); err != nil {
+		return fmt.Errorf("engine base %q: %w", base, err)
+	}
+
+	// The engine's own credential exists precisely so that the live face feed
+	// is never served open - CLAUDE.md is explicit that an unauthenticated
+	// listener would expose it. An unauthenticated loopback relay would hand
+	// that same feed to any other process on this PC, which on a shop counter
+	// is not a theoretical set. A per-run token, minted here and given only to
+	// this app's own webview, keeps the relay as private as the engine is.
+	raw := make([]byte, 32)
+	if _, err := rand.Read(raw); err != nil {
+		return fmt.Errorf("proxy token: %w", err)
+	}
+
+	// Port 0: the OS picks a free one. A fixed port would collide with
+	// whatever else a shop PC happens to be running, and the failure would be
+	// "the cameras stopped working" with nothing pointing at the cause.
+	ln, err := net.Listen("tcp", "127.0.0.1:0")
+	if err != nil {
+		return fmt.Errorf("stream proxy listen: %w", err)
+	}
+
+	p.ln = ln
+	p.token = hex.EncodeToString(raw)
+	p.target = strings.TrimRight(base, "/")
+	p.user, p.pass = user, pass
+	// No client timeout: an MJPEG stream is endless by design and any deadline
+	// would cut the picture off mid-shift. The request context ends it when
+	// the webview navigates away or the tile is replaced.
+	p.client = &http.Client{
+		Transport: &http.Transport{
+			DialContext:         (&net.Dialer{Timeout: 5 * time.Second}).DialContext,
+			TLSHandshakeTimeout: 5 * time.Second,
+		},
+	}
+	srv := &http.Server{Handler: http.HandlerFunc(p.handle)}
+	p.srv = srv
+
+	// srv and ln are captured, not read off the struct inside the goroutine:
+	// stop() sets both to nil, so a serve loop that reached for them after a
+	// quick start/stop would dereference nil and take the whole app down. The
+	// test that stops the relay found exactly that.
+	go func() { _ = srv.Serve(ln) }()
+	return nil
+}
+
+func (p *streamProxy) stop() {
+	p.mu.Lock()
+	srv, ln := p.srv, p.ln
+	p.srv, p.ln, p.token = nil, nil, ""
+	p.mu.Unlock()
+	if srv != nil {
+		_ = srv.Close()
+	}
+	if ln != nil {
+		_ = ln.Close()
+	}
+}
+
+// urlFor returns the loopback URL for one camera resource, or "" when the
+// proxy is not running so the caller can fall back.
+func (p *streamProxy) urlFor(cameraID, file string) string {
+	p.mu.RLock()
+	defer p.mu.RUnlock()
+	if p.ln == nil || p.token == "" || !safeCameraID(cameraID) {
+		return ""
+	}
+	return fmt.Sprintf("http://%s/s/%s/%s/%s",
+		p.ln.Addr().String(), p.token, cameraID, file)
+}
+
+func (p *streamProxy) handle(w http.ResponseWriter, r *http.Request) {
+	p.mu.RLock()
+	token, target, user, pass, client := p.token, p.target, p.user, p.pass, p.client
+	p.mu.RUnlock()
+	if token == "" || client == nil {
+		http.NotFound(w, r)
+		return
+	}
+
+	// /s/<token>/<camera>/<file>
+	parts := strings.Split(strings.TrimPrefix(r.URL.Path, "/"), "/")
+	if len(parts) != 4 || parts[0] != "s" {
+		http.NotFound(w, r)
+		return
+	}
+	// Constant time: the token is the only thing standing between another
+	// local process and a live view of customers' faces.
+	if subtle.ConstantTimeCompare([]byte(parts[1]), []byte(token)) != 1 {
+		// 404 rather than 403. There is nothing here to tell an unwelcome
+		// caller they have found the right door with the wrong key.
+		http.NotFound(w, r)
+		return
+	}
+	cameraID := parts[2]
+	if !safeCameraID(cameraID) {
+		http.NotFound(w, r)
+		return
+	}
+
+	// An allow-list, not a prefix match. Everything else the engine serves -
+	// the identity list, the gallery, erasure - stays unreachable through here
+	// even for a caller holding the token.
+	//
+	// frame.jpg is listed although no screen asks for one yet. It is reachable
+	// only through urlFor, which is internal, so it adds no bound API nobody
+	// calls; it is here so that adding a still later is a change to a screen
+	// rather than a change to the one file where a mistake is a credentialed
+	// proxy onto the biometric API.
+	var enginePath string
+	switch parts[3] {
+	case "stream.mjpeg":
+		enginePath = "/api/cameras/" + cameraID + "/stream.mjpeg"
+	case "frame.jpg":
+		enginePath = "/api/cameras/" + cameraID + "/frame.jpg"
+	default:
+		http.NotFound(w, r)
+		return
+	}
+
+	req, err := http.NewRequestWithContext(r.Context(), http.MethodGet, target+enginePath, nil)
+	if err != nil {
+		http.Error(w, "bad upstream request", http.StatusInternalServerError)
+		return
+	}
+	// frame.jpg takes width and quality; the engine re-encodes on demand.
+	req.URL.RawQuery = r.URL.RawQuery
+	if user != "" {
+		req.SetBasicAuth(user, pass)
+	}
+
+	resp, err := client.Do(req)
+	if err != nil {
+		http.Error(w, "engine unreachable", http.StatusBadGateway)
+		return
+	}
+	defer resp.Body.Close()
+
+	for _, h := range []string{"Content-Type", "Cache-Control", "Pragma", "Expires"} {
+		if v := resp.Header.Get(h); v != "" {
+			w.Header().Set(h, v)
+		}
+	}
+	w.WriteHeader(resp.StatusCode)
+
+	// Copied by hand rather than with io.Copy so every chunk is flushed. An
+	// MJPEG stream never ends, so anything buffered waiting for a full buffer
+	// is a tile that stays blank forever - which is the same symptom as the
+	// bug this file exists to fix, and would look like it had not worked.
+	flusher, _ := w.(http.Flusher)
+	buf := make([]byte, 32*1024)
+	for {
+		n, rerr := resp.Body.Read(buf)
+		if n > 0 {
+			if _, werr := w.Write(buf[:n]); werr != nil {
+				return // webview went away
+			}
+			if flusher != nil {
+				flusher.Flush()
+			}
+		}
+		if rerr != nil {
+			return
+		}
+	}
+}

desktop/stream_proxy_test.go

@@ -0,0 +1,296 @@
+package main
+
+import (
+	"fmt"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"strings"
+	"testing"
+	"time"
+)
+
+// fakeEngine stands in for the Python engine: it demands Basic auth exactly as
+// the real one does when a credential is configured, and records what it was
+// asked for.
+type fakeEngine struct {
+	*httptest.Server
+	gotPath string
+	gotUser string
+	gotPass string
+	hadAuth bool
+}
+
+func newFakeEngine(t *testing.T, body string) *fakeEngine {
+	t.Helper()
+	f := &fakeEngine{}
+	f.Server = httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		f.gotPath = r.URL.Path
+		if r.URL.RawQuery != "" {
+			f.gotPath += "?" + r.URL.RawQuery
+		}
+		f.gotUser, f.gotPass, f.hadAuth = r.BasicAuth()
+		if !f.hadAuth {
+			w.Header().Set("WWW-Authenticate", `Basic realm="behavision"`)
+			w.WriteHeader(http.StatusUnauthorized)
+			return
+		}
+		w.Header().Set("Content-Type", "multipart/x-mixed-replace; boundary=frame")
+		_, _ = io.WriteString(w, body)
+	}))
+	t.Cleanup(f.Close)
+	return f
+}
+
+func startProxy(t *testing.T, engine string, user, pass string) *streamProxy {
+	t.Helper()
+	p := newStreamProxy()
+	if err := p.start(engine, user, pass); err != nil {
+		t.Fatalf("start: %v", err)
+	}
+	t.Cleanup(p.stop)
+	return p
+}
+
+func get(t *testing.T, url string) (int, string) {
+	t.Helper()
+	c := &http.Client{Timeout: 5 * time.Second}
+	resp, err := c.Get(url)
+	if err != nil {
+		t.Fatalf("get %s: %v", url, err)
+	}
+	defer resp.Body.Close()
+	b, _ := io.ReadAll(resp.Body)
+	return resp.StatusCode, string(b)
+}
+
+// The whole point: the webview gets a URL it can actually load, and the
+// password stays behind. A credential in the src is both unloadable in a
+// Chromium webview and readable by anything that can see the DOM.
+func TestTheCameraURLCarriesNoPassword(t *testing.T) {
+	engine := newFakeEngine(t, "frames")
+	p := startProxy(t, engine.URL, "behavision", "hunter2-the-real-one")
+
+	u := p.urlFor("cam2", "stream.mjpeg")
+	if u == "" {
+		t.Fatal("no url while the proxy is running")
+	}
+	if strings.Contains(u, "hunter2-the-real-one") || strings.Contains(u, "behavision:") {
+		t.Fatalf("credential leaked into the tile URL: %s", u)
+	}
+	if !strings.HasPrefix(u, "http://127.0.0.1:") {
+		t.Fatalf("relay must be loopback only, got %s", u)
+	}
+}
+
+func TestTheRelayAttachesTheCredentialItself(t *testing.T) {
+	engine := newFakeEngine(t, "frame-bytes")
+	p := startProxy(t, engine.URL, "behavision", "s3cret")
+
+	code, body := get(t, p.urlFor("cam2", "stream.mjpeg"))
+	if code != http.StatusOK {
+		t.Fatalf("want 200 through the relay, got %d", code)
+	}
+	if body != "frame-bytes" {
+		t.Fatalf("body not relayed unchanged: %q", body)
+	}
+	if !engine.hadAuth || engine.gotUser != "behavision" || engine.gotPass != "s3cret" {
+		t.Fatalf("engine did not receive the credential: auth=%v user=%q",
+			engine.hadAuth, engine.gotUser)
+	}
+	if engine.gotPath != "/api/cameras/cam2/stream.mjpeg" {
+		t.Fatalf("wrong upstream path: %s", engine.gotPath)
+	}
+}
+
+// The token is what keeps every other process on a shop PC from opening a live
+// view of customers' faces, now that the relay itself has no password.
+func TestAnotherProcessCannotGuessItsWayIn(t *testing.T) {
+	engine := newFakeEngine(t, "frames")
+	p := startProxy(t, engine.URL, "behavision", "s3cret")
+	addr := p.ln.Addr().String()
+
+	for _, bad := range []string{"", "0", strings.Repeat("a", 64), "wrong-token"} {
+		url := fmt.Sprintf("http://%s/s/%s/cam2/stream.mjpeg", addr, bad)
+		if code, _ := get(t, url); code != http.StatusNotFound {
+			t.Fatalf("token %q got %d, want 404", bad, code)
+		}
+	}
+	if engine.hadAuth {
+		t.Fatal("a rejected request still reached the engine")
+	}
+}
+
+// A camera id is interpolated into the upstream path, so it has to be a camera
+// id and not a way to walk to a different endpoint with the credential
+// attached.
+func TestACameraIdCannotClimbOutOfItsPath(t *testing.T) {
+	engine := newFakeEngine(t, "frames")
+	p := startProxy(t, engine.URL, "behavision", "s3cret")
+	addr := p.ln.Addr().String()
+
+	for _, bad := range []string{"..", "%2e%2e", "cam2/../../api/identities", "cam 2", ""} {
+		url := fmt.Sprintf("http://%s/s/%s/%s/stream.mjpeg", addr, p.token, bad)
+		code, _ := get(t, url)
+		if code != http.StatusNotFound {
+			t.Fatalf("camera id %q got %d, want 404", bad, code)
+		}
+	}
+	if strings.Contains(engine.gotPath, "identities") {
+		t.Fatalf("reached a non-camera endpoint: %s", engine.gotPath)
+	}
+}
+
+// Only the two files a tile needs. The engine also serves the identity list and
+// the erasure endpoint; holding the token must not open those.
+func TestOnlyTheTwoCameraFilesAreReachable(t *testing.T) {
+	engine := newFakeEngine(t, "frames")
+	p := startProxy(t, engine.URL, "behavision", "s3cret")
+	addr := p.ln.Addr().String()
+
+	for _, bad := range []string{"identities", "stats", "commission", "stream.mjpeg.bak"} {
+		url := fmt.Sprintf("http://%s/s/%s/cam2/%s", addr, p.token, bad)
+		if code, _ := get(t, url); code != http.StatusNotFound {
+			t.Fatalf("file %q got %d, want 404", bad, code)
+		}
+	}
+
+	for _, good := range []string{"stream.mjpeg", "frame.jpg"} {
+		url := fmt.Sprintf("http://%s/s/%s/cam2/%s", addr, p.token, good)
+		if code, _ := get(t, url); code != http.StatusOK {
+			t.Fatalf("file %q got %d, want 200", good, code)
+		}
+	}
+}
+
+// frame.jpg takes width and quality - the engine re-encodes on demand, and a
+// relay that dropped the query would silently serve full-size frames.
+func TestTheQueryStringSurvivesTheRelay(t *testing.T) {
+	engine := newFakeEngine(t, "frames")
+	p := startProxy(t, engine.URL, "behavision", "s3cret")
+
+	url := p.urlFor("cam2", "frame.jpg") + "?width=640&quality=70"
+	if code, _ := get(t, url); code != http.StatusOK {
+		t.Fatalf("got %d", code)
+	}
+	if !strings.Contains(engine.gotPath, "width=640") ||
+		!strings.Contains(engine.gotPath, "quality=70") {
+		t.Fatalf("query dropped: %s", engine.gotPath)
+	}
+}
+
+// An engine that is not running must read as a bad gateway, not as a hang. A
+// blank tile that never resolves is the symptom this whole file exists to end.
+func TestAnEngineThatIsDownFailsQuickly(t *testing.T) {
+	// Port 1 on loopback: nothing listens, and the connection is refused
+	// rather than dropped, so this is fast and deterministic.
+	p := startProxy(t, "http://127.0.0.1:1", "behavision", "s3cret")
+
+	done := make(chan int, 1)
+	go func() { code, _ := get(t, p.urlFor("cam2", "stream.mjpeg")); done <- code }()
+	select {
+	case code := <-done:
+		if code != http.StatusBadGateway {
+			t.Fatalf("want 502, got %d", code)
+		}
+	case <-time.After(8 * time.Second):
+		t.Fatal("a dead engine left the request hanging")
+	}
+}
+
+// Stopping must actually free the port, or a restarted engine leaves listeners
+// behind for the life of the process.
+func TestStoppingReleasesEverything(t *testing.T) {
+	engine := newFakeEngine(t, "frames")
+	p := newStreamProxy()
+	if err := p.start(engine.URL, "u", "p"); err != nil {
+		t.Fatalf("start: %v", err)
+	}
+	url := p.urlFor("cam2", "stream.mjpeg")
+	if code, _ := get(t, url); code != http.StatusOK {
+		t.Fatalf("want 200 before stop, got %d", code)
+	}
+
+	p.stop()
+
+	if got := p.urlFor("cam2", "stream.mjpeg"); got != "" {
+		t.Fatalf("still handing out URLs after stop: %s", got)
+	}
+	c := &http.Client{Timeout: 3 * time.Second}
+	if resp, err := c.Get(url); err == nil {
+		resp.Body.Close()
+		t.Fatal("listener still accepting after stop")
+	}
+}
+
+// start twice must not leave two listeners, which is what a restarted engine
+// would otherwise cause.
+func TestStartingTwiceIsANoOp(t *testing.T) {
+	engine := newFakeEngine(t, "frames")
+	p := startProxy(t, engine.URL, "u", "p")
+
+	first := p.urlFor("cam2", "stream.mjpeg")
+	if err := p.start(engine.URL, "u", "p"); err != nil {
+		t.Fatalf("second start: %v", err)
+	}
+	if second := p.urlFor("cam2", "stream.mjpeg"); second != first {
+		t.Fatalf("second start moved the relay: %s -> %s", first, second)
+	}
+}
+
+// Against the real engine, which the unit tests above deliberately do not
+// touch. Skipped unless TEST_ENGINE_URL is set, the same rule the server's
+// live store tests follow: the suite must stay runnable with no services.
+//
+//	TEST_ENGINE_URL=http://127.0.0.1:8010 \
+//	TEST_ENGINE_USER=... TEST_ENGINE_PASS=... go test ./desktop/ -run Live
+//
+// It exists because everything above proves the relay against a fake that
+// agrees with me. Only a real engine proves the thing that was actually
+// broken: that a multipart MJPEG stream arrives through the relay in pieces,
+// rather than being buffered into a tile that never paints.
+func TestLiveRelayCarriesRealMJPEGFrames(t *testing.T) {
+	base := os.Getenv("TEST_ENGINE_URL")
+	if base == "" {
+		t.Skip("set TEST_ENGINE_URL to run the live relay test")
+	}
+	cam := os.Getenv("TEST_ENGINE_CAMERA")
+	if cam == "" {
+		cam = "cam2"
+	}
+	p := startProxy(t, base, os.Getenv("TEST_ENGINE_USER"), os.Getenv("TEST_ENGINE_PASS"))
+
+	url := p.urlFor(cam, "stream.mjpeg")
+	req, _ := http.NewRequest(http.MethodGet, url, nil)
+	resp, err := (&http.Client{}).Do(req)
+	if err != nil {
+		t.Fatalf("relay: %v", err)
+	}
+	defer resp.Body.Close()
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("relay returned %d - the credential did not reach the engine", resp.StatusCode)
+	}
+	if ct := resp.Header.Get("Content-Type"); !strings.Contains(ct, "multipart") {
+		t.Fatalf("not a stream: Content-Type %q", ct)
+	}
+
+	// Read until two JPEG start markers have gone past. One proves it opened;
+	// two prove it is still delivering, which is the difference between a
+	// working tile and a single frozen frame.
+	deadline := time.Now().Add(15 * time.Second)
+	var seen, total int
+	buf := make([]byte, 16*1024)
+	for seen < 2 && time.Now().Before(deadline) {
+		n, rerr := resp.Body.Read(buf)
+		total += n
+		seen += strings.Count(string(buf[:n]), "\xff\xd8\xff")
+		if rerr != nil {
+			break
+		}
+	}
+	if seen < 2 {
+		t.Fatalf("only %d JPEG frames in %d bytes - the relay is not streaming", seen, total)
+	}
+	t.Logf("relayed %d frames in %d bytes with no credential in the URL", seen, total)
+}

desktop/tray.go

@@ -3,6 +3,7 @@ package main
 import (
 	"context"
 	"fmt"
+	"os"
 	"sync"
 	"time"
 
@@ -10,6 +11,25 @@ import (
 	"github.com/wailsapp/wails/v2/pkg/runtime"
 )
 
+// BEHAVISION_NO_TRAY runs the window with no tray icon.
+//
+// It exists so the UI can be looked at on a Mac. fyne.io/systray's nativeLoop
+// must own the main thread on macOS - a Cocoa requirement, not a library
+// choice - and Wails already holds it, so starting both kills the process with
+// a SIGTRAP inside cgo before a single screen is drawn. On Windows, which is
+// what ships, a tray on its own goroutine is fine. That asymmetry is why this
+// went unnoticed for so long: the shop-floor UI had never once been run on the
+// platform it is developed on, so every screen in it was unreviewed.
+//
+// Deliberately an environment variable and NOT a GOOS check. A build that
+// quietly drops the tray on some platform is how a shop PC ends up with no
+// control surface at all - the one thing a shop manager has - and it would
+// fail exactly where nobody is watching. Nothing is skipped unless a person
+// asked for it, by name, on this run.
+const noTrayEnv = "BEHAVISION_NO_TRAY"
+
+func trayDisabled() bool { return os.Getenv(noTrayEnv) != "" }
+
 // tray is the always-present control surface. Wails v2 has no systray of its
 // own, so this drives fyne.io/systray alongside the window.
 //
@@ -32,9 +52,10 @@ type tray struct {
 func newTray(a *App) *tray { return &tray{app: a, quit: make(chan struct{})} }
 
 func (t *tray) start(ctx context.Context) {
-	t.once.Do(func() {
+	if trayDisabled() {
-		go systray.Run(func() { t.onReady(ctx) }, func() {})
+		return
-	})
+	}
+	t.once.Do(func() { startSystray(func() { t.onReady(ctx) }) })
 }
 
 func (t *tray) stop() {
@@ -43,6 +64,13 @@ func (t *tray) stop() {
 	default:
 		close(t.quit)
 	}
+	// systray.Quit() on a systray that was never started is not a no-op in
+	// v1.12.2, so the guard has to be on both ends or quitting the window
+	// takes the process down with it - a crash on exit, which is the failure
+	// most likely to be shrugged off as "it closed, fine".
+	if trayDisabled() {
+		return
+	}
 	systray.Quit()
 }
 
@@ -69,11 +97,15 @@ func (t *tray) onReady(ctx context.Context) {
 		case <-t.quit:
 			return
 		case <-t.mOpen.ClickedCh:
-			runtime.Show(ctx)
+			// In a goroutine, like Start and Stop: this sleeps, and a menu
+			// loop that sleeps is a tray that ignores the next click.
+			go openWindow(ctx)
 		case <-t.mStart.ClickedCh:
-			t.app.StartEngine()
+			// Never on the menu loop itself: a stop waits for the process to
+			// exit, and a menu that is deaf for the duration looks broken.
+			go func() { t.app.StartEngine(); t.refresh() }()
 		case <-t.mStop.ClickedCh:
-			t.app.StopEngine()
+			go func() { t.app.StopEngine(); t.refresh() }()
 		case <-t.mLogs.ClickedCh:
 			runtime.BrowserOpenURL(ctx, "file://"+logsDir())
 		case <-t.mQuit.ClickedCh:
@@ -99,23 +131,29 @@ func (t *tray) poll(ctx context.Context) {
 		case <-ctx.Done():
 			return
 		case <-tick.C:
-			s := t.app.EngineStatus()
+			t.refresh()
-			state, label := describe(s)
+		}
-			systray.SetIcon(iconFor(state))
+	}
-			systray.SetTooltip("Behavision — " + label)
+}
-			if t.mStatus != nil {
+
-				t.mStatus.SetTitle(label)
+// refresh redraws the icon and the menu from EngineStatus - the same source
-			}
+// the window reads, so the two cannot disagree.
-			running := s.State == "running"
+func (t *tray) refresh() {
-			if t.mStart != nil && t.mStop != nil {
+	s := t.app.EngineStatus()
-				if running {
+	state, label := describe(s)
-					t.mStart.Disable()
+	systray.SetIcon(iconFor(state))
-					t.mStop.Enable()
+	systray.SetTooltip("Behavision — " + label)
-				} else {
+	if t.mStatus != nil {
-					t.mStart.Enable()
+		t.mStatus.SetTitle(label)
-					t.mStop.Disable()
+	}
-				}
+	running := s.State == "running" || s.State == "starting" || s.State == "backoff"
-			}
+	if t.mStart != nil && t.mStop != nil {
+		if running {
+			t.mStart.Disable()
+			t.mStop.Enable()
+		} else {
+			t.mStart.Enable()
+			t.mStop.Disable()
 		}
 	}
 }
@@ -130,9 +168,13 @@ func describe(s EngineStatus) (state, label string) {
 	case s.State == "stopped":
 		return "stopped", "Stopped"
 	case s.State == "failed":
-		return "error", "Failed — " + firstLine(s.Error)
+		// The supervisor's error is already a sentence (port in use, missing
+		// library); show it whole, because it is the thing to act on.
+		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:
@@ -172,3 +214,36 @@ func firstLine(s string) string {
 	}
 	return s
 }
+
+// openWindow brings the dashboard back, and it takes four calls rather than
+// the one that was here.
+//
+// `runtime.Show` was wrong three times over, and the first is the one that
+// made it fail rather than merely misbehave:
+//
+//  1. WRONG THREAD. Wails implements Show() as a bare `mainWindow.Show()`,
+//     while WindowShow() wraps the same work in runtime.LockOSThread. Win32
+//     window operations have to run on the thread owning the window's message
+//     pump; this is called from the SYSTRAY's goroutine, which is never that
+//     thread. An unlocked call from an arbitrary goroutine is why clicking
+//     "Open dashboard" did nothing reliable.
+//
+//  2. Showing is not un-minimising. A hidden window and a minimised one are
+//     different states and Show only fixes the first, so a window the user
+//     minimised stayed minimised.
+//
+//  3. Windows will not let a process that is not already in the foreground
+//     take it - the shell refuses, and the window comes back BEHIND whatever
+//     is being looked at. Clicking a tray icon is by definition a moment when
+//     this application is not in the foreground, so that is not an edge case
+//     here, it is every time.
+//
+// The always-on-top flip is the ordinary way to ask for the foreground anyway.
+// It is brief and it is why this cannot run on the menu loop.
+func openWindow(ctx context.Context) {
+	runtime.WindowUnminimise(ctx)
+	runtime.WindowShow(ctx)
+	runtime.WindowSetAlwaysOnTop(ctx, true)
+	time.Sleep(200 * time.Millisecond)
+	runtime.WindowSetAlwaysOnTop(ctx, false)
+}

desktop/tray_run_darwin.go

@@ -0,0 +1,28 @@
+//go:build darwin
+
+package main
+
+// There is no tray on macOS, and that is a decision rather than an omission.
+//
+// macOS has exactly ONE main run loop and AppKit insists that windows and
+// status items are created on it. Wails already owns that loop. Two attempts,
+// both crashing within a second of launch:
+//
+//	systray.Run              -> SIGTRAP inside cgo: nativeLoop() takes the
+//	                            main loop for itself, and Wails has it
+//	systray.RunWithExternalLoop -> "NSWindow should only be instantiated on
+//	                            the main thread!" - it registers in the
+//	                            existing NSApplication but still builds
+//	                            AppKit objects, and Wails' OnStartup is not
+//	                            the main thread
+//
+// Making it work needs the status item created through a main-queue dispatch
+// inside Wails' own lifecycle, which is real work for a build whose entire
+// purpose is demoing on a developer's Mac. Windows is the platform this ships
+// to and its tray is the shop manager's only control surface; here the window
+// is right there in the Dock.
+//
+// The consequence is handled rather than left: with no tray there would be no
+// way back from a hidden window and no way to quit, so on macOS closing the
+// window stops the engine and exits. See main.go.
+func startSystray(onReady func()) {}

desktop/tray_run_windows.go

@@ -0,0 +1,10 @@
+//go:build windows
+
+package main
+
+import "fyne.io/systray"
+
+// systray.Run owns a message loop, and on Windows it is free to have its own:
+// the tray lives in its own thread with its own pump, beside the one Wails
+// runs for the window. A goroutine is all it needs.
+func startSystray(onReady func()) { go systray.Run(onReady, func() {}) }

docs/Behavision-Architecture.html

@@ -0,0 +1,577 @@
+<title>Behavision Architecture</title>
+<link rel="preconnect" href="https://fonts.googleapis.com">
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Archivo:wght@500;600;700&family=Source+Serif+4:opsz,wght@8..60,400;8..60,600&family=IBM+Plex+Mono:wght@400;500&display=swap">
+
+<style>
+  :root{
+    --paper:#f1f4f6;--surface:#fff;--surface-2:#e7ecef;--ink:#131b22;--ink-soft:#46545f;--ink-faint:#6d7d88;--rule:#d3dbe0;
+    --acc:#12707e;--acc-ink:#0b4d57;--acc-bg:#dcedf0;--good:#2f7d55;--warn:#9a6413;--bad:#a8403c;--good-bg:#e2efe8;--warn-bg:#f5ecdc;
+    --sans:"Archivo","Helvetica Neue",Arial,sans-serif;--serif:"Source Serif 4",Georgia,serif;--mono:"IBM Plex Mono",ui-monospace,Menlo,monospace;
+  }
+  @media (prefers-color-scheme:dark){:root:not([data-theme="light"]){--paper:#0e141b;--surface:#161f28;--surface-2:#1d2833;--ink:#e6edf2;--ink-soft:#a7b6c1;--ink-faint:#7b8b97;--rule:#2a3742;--acc:#4fc3d6;--acc-ink:#9adfeb;--acc-bg:#13303a;--good:#6cc394;--warn:#d5a55c;--bad:#e0817c;--good-bg:#172c22;--warn-bg:#2e2617}}
+  :root[data-theme="dark"]{--paper:#0e141b;--surface:#161f28;--surface-2:#1d2833;--ink:#e6edf2;--ink-soft:#a7b6c1;--ink-faint:#7b8b97;--rule:#2a3742;--acc:#4fc3d6;--acc-ink:#9adfeb;--acc-bg:#13303a;--good:#6cc394;--warn:#d5a55c;--bad:#e0817c;--good-bg:#172c22;--warn-bg:#2e2617}
+
+  *{box-sizing:border-box}
+  body{margin:0;background:var(--paper);color:var(--ink);font-family:var(--serif);font-size:1rem;line-height:1.55;-webkit-font-smoothing:antialiased}
+  h1,h2,h3,.eyebrow,.nav,.legend,.facts,.tag,.metric{font-family:var(--sans)}
+  h1{font-size:clamp(2.2rem,5vw,3.2rem);line-height:1.02;font-weight:700;letter-spacing:-.025em;margin:0;text-wrap:balance}
+  h2{font-size:1.5rem;line-height:1.15;font-weight:600;letter-spacing:-.01em;margin:0;text-wrap:balance}
+  p{margin:0} code{font-family:var(--mono);font-size:.88em;background:var(--surface-2);padding:.06em .35em;border-radius:2px}
+  a{color:var(--acc)} a:focus-visible{outline:2px solid var(--acc);outline-offset:3px}
+  .wrap{max-width:74rem;margin:0 auto;padding-inline:20px}
+  .eyebrow{font-size:.8rem;text-transform:uppercase;letter-spacing:.14em;font-weight:600;color:var(--acc)}
+
+  header.mast{background:var(--surface);border-bottom:1px solid var(--rule)}
+  header.mast .wrap{padding-block:clamp(2.5rem,6vw,4rem) clamp(1.5rem,4vw,2.5rem);display:flex;flex-direction:column;gap:1.1rem}
+  .brand{display:flex;align-items:center;gap:.7rem;font-family:var(--sans);font-weight:600;letter-spacing:.16em;text-transform:uppercase;font-size:.8rem;color:var(--ink-faint)}
+  .lens{width:1rem;height:1rem;border-radius:50%;border:2px solid var(--acc)}
+  .sub{font-size:1.15rem;color:var(--ink-soft);max-width:38rem;line-height:1.45}
+  .nav{display:flex;flex-wrap:wrap;gap:.35rem .9rem;font-size:.8rem;margin-top:.5rem}
+  .nav a{text-decoration:none;color:var(--ink-faint)} .nav a:hover{color:var(--ink)} .nav .n{font-family:var(--mono);color:var(--acc);margin-right:.35rem}
+
+  /* legend */
+  .legend{display:flex;flex-wrap:wrap;gap:.6rem 1.6rem;font-size:.8rem;color:var(--ink-soft);align-items:center}
+  .legend span{display:inline-flex;align-items:center;gap:.45rem}
+  .legend svg{width:34px;height:20px;display:block}
+
+  /* plates */
+  .plate{padding-block:clamp(2.2rem,5vw,3.5rem);border-bottom:1px solid var(--rule)}
+  .plate:last-of-type{border-bottom:0}
+  .head{display:grid;grid-template-columns:3.2rem 1fr;gap:1rem;align-items:baseline;margin-bottom:1.2rem}
+  .head .n{font-family:var(--mono);font-size:.95rem;color:var(--acc)}
+  .head p{color:var(--ink-soft);margin-top:.35rem;max-width:42rem}
+  .fig{background:var(--surface);border:1px solid var(--rule);padding:clamp(.8rem,2.2vw,1.4rem);overflow-x:auto}
+  .fig svg{display:block;max-width:100%;height:auto;min-width:40rem}
+  .facts{display:grid;grid-template-columns:repeat(auto-fit,minmax(14rem,1fr));gap:.9rem 2rem;margin-top:1.1rem;font-size:.86rem;line-height:1.45}
+  .facts div{display:grid;grid-template-columns:.7rem 1fr;gap:.6rem}
+  .facts div::before{content:"";width:.5rem;height:.5rem;border-radius:1px;background:var(--acc);margin-top:.45rem}
+  .facts b{font-weight:600}
+
+  /* svg semantics */
+  .s{stroke:currentColor;stroke-width:1.5;fill:none}
+  .sa{stroke:var(--acc);stroke-width:1.75;fill:none}
+  .sd{stroke:currentColor;stroke-width:1.25;fill:none;stroke-dasharray:4 4;opacity:.75}
+  .fa{fill:var(--acc)} .fab{fill:var(--acc-bg)} .fs{fill:var(--surface-2)} .fg{fill:var(--good)} .fw{fill:var(--warn)} .fb{fill:var(--bad)} .fgb{fill:var(--good-bg)} .fwb{fill:var(--warn-bg)}
+  .t{font-family:var(--sans);font-size:12.5px;font-weight:600;fill:currentColor}
+  .ta{font-family:var(--sans);font-size:12.5px;font-weight:600;fill:var(--acc)}
+  .m{font-family:var(--mono);font-size:10.5px;fill:currentColor;opacity:.68}
+  .ma{font-family:var(--mono);font-size:10.5px;fill:var(--acc)}
+  .l{font-family:var(--sans);font-size:10.5px;fill:currentColor;opacity:.78}
+  .la{font-family:var(--sans);font-size:10.5px;fill:var(--acc)}
+  .z{font-family:var(--sans);font-size:11.5px;font-weight:600;letter-spacing:1.5px;fill:currentColor;opacity:.5}
+  .cap{font-family:var(--serif);font-size:12.5px;fill:currentColor;opacity:.8}
+
+  .metrics{display:grid;grid-template-columns:repeat(auto-fit,minmax(11rem,1fr));gap:1px;background:var(--rule);border:1px solid var(--rule)}
+  .metric{background:var(--surface);padding:1rem 1.05rem 1.1rem;display:flex;flex-direction:column;gap:.2rem}
+  .metric .v{font-size:1.9rem;font-weight:700;line-height:1;letter-spacing:-.02em;font-variant-numeric:tabular-nums}
+  .metric .k{font-size:.8rem;color:var(--ink-faint);line-height:1.35}
+
+  footer{background:var(--surface);border-top:1px solid var(--rule);color:var(--ink-faint);font-size:.8rem}
+  footer .wrap{padding-block:1.6rem 2.6rem}
+  @media (max-width:40rem){.head{grid-template-columns:1fr;gap:.2rem}}
+  @media (prefers-reduced-motion:reduce){*{animation:none!important;transition:none!important}}
+</style>
+
+<!-- shared glyphs -->
+<svg width="0" height="0" style="position:absolute" aria-hidden="true">
+  <defs>
+    <marker id="a" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse"><path d="M0,0 L10,5 L0,10 z" fill="currentColor"/></marker>
+    <marker id="aa" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse"><path d="M0,0 L10,5 L0,10 z" class="fa"/></marker>
+    <symbol id="g-cam" viewBox="0 0 24 24"><path d="M3 8h4l2-3h6l2 3h4v11H3z" class="s"/><circle cx="12" cy="13" r="3.2" class="s"/></symbol>
+    <symbol id="g-db" viewBox="0 0 24 24"><ellipse cx="12" cy="6" rx="8" ry="3" class="s"/><path d="M4 6v12c0 1.7 3.6 3 8 3s8-1.3 8-3V6" class="s"/><path d="M4 12c0 1.7 3.6 3 8 3s8-1.3 8-3" class="s"/></symbol>
+    <symbol id="g-pc" viewBox="0 0 24 24"><rect x="3" y="4" width="18" height="12" rx="1" class="s"/><path d="M8 20h8M12 16v4" class="s"/></symbol>
+    <symbol id="g-phone" viewBox="0 0 24 24"><rect x="7" y="2" width="10" height="20" rx="2" class="s"/><path d="M11 18h2" class="s"/></symbol>
+    <symbol id="g-lock" viewBox="0 0 24 24"><rect x="5" y="10" width="14" height="10" rx="1" class="s"/><path d="M8 10V7a4 4 0 0 1 8 0v3" class="s"/></symbol>
+    <symbol id="g-file" viewBox="0 0 24 24"><path d="M6 2h8l5 5v15H6z" class="s"/><path d="M14 2v5h5" class="s"/></symbol>
+    <symbol id="g-cloud" viewBox="0 0 24 24"><path d="M7 18a4 4 0 0 1-.6-7.95A6 6 0 0 1 18 9a4 4 0 0 1 0 9z" class="s"/></symbol>
+    <symbol id="g-person" viewBox="0 0 24 24"><circle cx="12" cy="8" r="3.5" class="s"/><path d="M5 20a7 7 0 0 1 14 0" class="s"/></symbol>
+    <symbol id="g-gear" viewBox="0 0 24 24"><circle cx="12" cy="12" r="3" class="s"/><path d="M12 3v2M12 19v2M3 12h2M19 12h2M5.6 5.6l1.4 1.4M17 17l1.4 1.4M5.6 18.4L7 17M17 7l1.4-1.4" class="s"/></symbol>
+  </defs>
+</svg>
+
+<header class="mast">
+  <div class="wrap">
+    <div class="brand"><span class="lens" aria-hidden="true"></span> Behavision · Technical Overview</div>
+    <h1>Behavision Architecture</h1>
+    <p class="sub">Face recognition for retail. An engine that sees, an agent that delivers, a platform that understands — in nine diagrams.</p>
+    <nav class="nav" aria-label="Plates">
+      <a href="#p1"><span class="n">01</span>System</a><a href="#p2"><span class="n">02</span>Shop PC</a><a href="#p3"><span class="n">03</span>Recognition</a><a href="#p4"><span class="n">04</span>Delivery</a><a href="#p5"><span class="n">05</span>Local &amp; master data</a><a href="#p6"><span class="n">06</span>Clients &amp; API</a><a href="#p7"><span class="n">07</span>Onboarding</a><a href="#p8"><span class="n">08</span>Secrets</a><a href="#p9"><span class="n">09</span>Stack &amp; numbers</a>
+    </nav>
+    <div class="legend" aria-label="Diagram legend">
+      <span><svg viewBox="0 0 34 20"><rect x="2" y="3" width="30" height="14" class="s"/></svg>process</span>
+      <span><svg viewBox="0 0 34 20"><ellipse cx="17" cy="5" rx="11" ry="3" class="s"/><path d="M6 5v10c0 1.7 4.9 3 11 3s11-1.3 11-3V5" class="s"/></svg>store</span>
+      <span><svg viewBox="0 0 34 20"><rect x="2" y="3" width="30" height="14" class="sa"/></svg>the path in focus</span>
+      <span><svg viewBox="0 0 34 20"><line x1="2" y1="10" x2="30" y2="10" class="s" marker-end="url(#a)"/></svg>data</span>
+      <span><svg viewBox="0 0 34 20"><line x1="2" y1="10" x2="30" y2="10" class="sd" marker-end="url(#a)"/></svg>control / pull</span>
+      <span><svg viewBox="0 0 34 20"><line x1="17" y1="1" x2="17" y2="19" stroke="currentColor" stroke-width="1.5" stroke-dasharray="4 3" opacity=".5"/></svg>trust boundary</span>
+    </div>
+  </div>
+</header>
+
+<main class="wrap">
+
+<!-- ============================================================ 01 -->
+<section class="plate" id="p1">
+  <div class="head"><span class="n">01</span><div><h2>The whole system</h2><p>Video stays inside the shop. Only visit records cross the boundary — and every connection across it is made from the inside, outward.</p></div></div>
+  <div class="fig">
+    <svg viewBox="0 0 1100 520" role="img" aria-label="Cameras stream RTSP to a shop PC running the engine, the agent and the shop app. The agent publishes visits over TLS MQTT to Mosquitto in the cloud; an ingest consumer writes them to PostgreSQL; the API serves the head-office console, the mobile app and platform administration. The shop PC pulls camera settings and check jobs from the API. A dashed boundary marks the shop network, with no inbound route.">
+      <text x="24" y="28" class="z">SHOP NETWORK</text><text x="520" y="28" class="z">LOYALY CLOUD</text><text x="880" y="28" class="z">PEOPLE</text>
+      <line x1="486" y1="42" x2="486" y2="490" stroke="currentColor" stroke-width="1.5" stroke-dasharray="5 4" opacity=".45"/>
+      <use href="#g-lock" x="474" y="492" width="24" height="24"/>
+      <text x="486" y="510" text-anchor="middle" class="l" dy="8">outbound only</text>
+
+      <!-- cameras -->
+      <use href="#g-cam" x="30" y="188" width="40" height="40"/>
+      <use href="#g-cam" x="30" y="236" width="40" height="40"/>
+      <text x="50" y="292" text-anchor="middle" class="m">RTSP</text>
+
+      <!-- shop pc -->
+      <rect x="120" y="70" width="330" height="400" rx="3" class="s"/>
+      <use href="#g-pc" x="134" y="82" width="22" height="22"/><text x="164" y="99" class="t">Shop PC</text>
+      <rect x="150" y="122" width="270" height="78" rx="2" class="sa"/>
+      <use href="#g-gear" x="162" y="134" width="20" height="20"/>
+      <text x="190" y="148" class="ta">Recognition engine</text>
+      <text x="190" y="166" class="m">Python · ONNX Runtime · FAISS</text>
+      <text x="190" y="182" class="m">detect → track → identify</text>
+      <use href="#g-db" x="384" y="160" width="26" height="26"/><text x="397" y="200" text-anchor="middle" class="m">SQLite</text>
+
+      <rect x="150" y="226" width="270" height="96" rx="2" class="s"/>
+      <text x="164" y="248" class="t">Agent</text><text x="164" y="266" class="m">Go · supervisor · camera sync</text>
+      <rect x="164" y="278" width="242" height="32" rx="2" class="fab"/>
+      <use href="#g-file" x="172" y="284" width="20" height="20"/>
+      <text x="200" y="299" class="ma">durable spool — one file per event</text>
+
+      <rect x="150" y="348" width="270" height="56" rx="2" class="s"/>
+      <text x="164" y="370" class="t">Shop app</text><text x="164" y="388" class="m">Wails · window + system tray</text>
+      <text x="285" y="440" text-anchor="middle" class="cap">runs with no internet;</text>
+      <text x="285" y="456" text-anchor="middle" class="cap">the spool drains when it returns</text>
+
+      <line x1="76" y1="212" x2="148" y2="160" class="s" marker-end="url(#a)"/><text x="126" y="214" class="l">video</text>
+      <line x1="285" y1="202" x2="285" y2="224" class="sa" marker-end="url(#aa)"/><text x="294" y="217" class="la">detections</text>
+      <line x1="285" y1="324" x2="285" y2="346" class="s" marker-end="url(#a)"/>
+
+      <!-- broker -->
+      <rect x="530" y="108" width="170" height="60" rx="2" class="s"/>
+      <use href="#g-cloud" x="542" y="118" width="22" height="22"/><text x="572" y="133" class="t">Mosquitto</text><text x="572" y="151" class="m">MQTT · TLS · per-tenant ACL</text>
+
+      <!-- server -->
+      <rect x="530" y="210" width="290" height="120" rx="2" class="s"/>
+      <text x="544" y="232" class="t">Behavision server</text><text x="544" y="249" class="m">Go · one binary</text>
+      <rect x="546" y="262" width="120" height="50" rx="2" class="s"/><text x="606" y="284" text-anchor="middle" class="t">ingest</text><text x="606" y="300" text-anchor="middle" class="m">dedupe · reinforce</text>
+      <rect x="684" y="262" width="120" height="50" rx="2" class="s"/><text x="744" y="284" text-anchor="middle" class="t">API + web</text><text x="744" y="300" text-anchor="middle" class="m">48 routes · SSE</text>
+
+      <!-- postgres -->
+      <use href="#g-db" x="656" y="388" width="40" height="40"/>
+      <text x="676" y="450" text-anchor="middle" class="ta">PostgreSQL</text>
+      <text x="676" y="466" text-anchor="middle" class="m">master database</text>
+
+      <!-- arrows cloud -->
+      <path d="M422 294 L505 294 L505 138 L528 138" class="sa" marker-end="url(#aa)"/>
+      <text x="462" y="284" text-anchor="middle" class="la">visits · QoS 1</text>
+      <line x1="615" y1="170" x2="606" y2="260" class="s" marker-end="url(#a)"/>
+      <line x1="606" y1="314" x2="668" y2="386" class="s" marker-end="url(#a)"/>
+      <line x1="744" y1="314" x2="690" y2="386" class="s" marker-start="url(#a)" marker-end="url(#a)"/>
+      <path d="M528 300 L470 300 L470 246 L424 246" class="sd" marker-end="url(#a)"/>
+      <text x="470" y="322" text-anchor="middle" class="l">pull: cameras, checks</text>
+
+      <!-- people -->
+      <rect x="880" y="96" width="196" height="56" rx="2" class="s"/><use href="#g-pc" x="892" y="106" width="22" height="22"/><text x="922" y="121" class="t">Head-office console</text><text x="922" y="138" class="m">owner · manager</text>
+      <rect x="880" y="182" width="196" height="56" rx="2" class="s"/><use href="#g-phone" x="892" y="192" width="22" height="22"/><text x="922" y="207" class="t">Mobile app</text><text x="922" y="224" class="m">sales staff</text>
+      <rect x="880" y="268" width="196" height="56" rx="2" class="s"/><use href="#g-person" x="892" y="278" width="22" height="22"/><text x="922" y="293" class="t">Platform admin</text><text x="922" y="310" class="m">creates merchants</text>
+      <path d="M878 124 L846 124 L846 288 L822 288" class="s" marker-end="url(#a)"/>
+      <path d="M878 210 L846 210" class="s"/>
+      <path d="M878 296 L846 296" class="s"/>
+      <text x="846" y="360" text-anchor="middle" class="l">https · session</text>
+    </svg>
+  </div>
+  <div class="facts">
+    <div><b>Three tiers</b>, one direction of trust: the shop initiates every connection it has.</div>
+    <div><b>One server binary</b> carries ingest, the API and the head-office web app.</div>
+    <div><b>One API</b> for the console, the mobile app and the shop app alike.</div>
+    <div><b>Offline is a delay, not a loss</b>: visits queue on disk until the broker confirms them.</div>
+  </div>
+</section>
+
+<!-- ============================================================ 02 -->
+<section class="plate" id="p2">
+  <div class="head"><span class="n">02</span><div><h2>Inside the shop PC</h2><p>Three processes on one machine, each in the language its job is best done in, sharing one state root.</p></div></div>
+  <div class="fig">
+    <svg viewBox="0 0 1100 400" role="img" aria-label="On the shop PC: the engine (Python) captures RTSP, runs detection and recognition, and keeps a SQLite gallery with a FAISS index. The agent (Go) supervises the engine, receives detections on a loopback webhook, spools them, and syncs cameras with head office. The shop app (Wails) hosts the window and tray and embeds the agent as a library. All three read and write one state root under ProgramData.">
+      <!-- engine -->
+      <rect x="30" y="50" width="340" height="230" rx="3" class="sa"/>
+      <text x="46" y="76" class="ta">Recognition engine</text><text x="46" y="93" class="m">Python 3.10+ · private venv</text>
+      <rect x="46" y="112" width="140" height="42" rx="2" class="s"/><text x="116" y="130" text-anchor="middle" class="t">capture thread</text><text x="116" y="146" text-anchor="middle" class="m">per camera · latest frame</text>
+      <rect x="214" y="112" width="140" height="42" rx="2" class="s"/><text x="284" y="130" text-anchor="middle" class="t">worker thread</text><text x="284" y="146" text-anchor="middle" class="m">per camera · one track = one person</text>
+      <line x1="188" y1="133" x2="212" y2="133" class="s" marker-end="url(#a)"/>
+      <rect x="46" y="176" width="308" height="42" rx="2" class="s"/><text x="200" y="194" text-anchor="middle" class="t">models · ONNX Runtime</text><text x="200" y="210" text-anchor="middle" class="m">YuNet · ArcFace r50 · genderage · CoreML / DirectML</text>
+      <use href="#g-db" x="60" y="232" width="30" height="30"/><text x="104" y="246" class="t">SQLite gallery</text><text x="104" y="262" class="m">identities · embeddings · sightings</text>
+      <rect x="250" y="232" width="104" height="34" rx="2" class="fab"/><text x="302" y="253" text-anchor="middle" class="ma">FAISS index</text>
+      <line x1="196" y1="249" x2="248" y2="249" class="sd" marker-end="url(#a)"/><text x="222" y="243" text-anchor="middle" class="l">rebuilt at boot</text>
+      <text x="200" y="300" text-anchor="middle" class="m">FastAPI on 127.0.0.1:8010 · Basic auth, credential generated on first start</text>
+
+      <!-- agent -->
+      <rect x="430" y="50" width="300" height="230" rx="3" class="s"/>
+      <text x="446" y="76" class="t">Agent — Go library</text><text x="446" y="93" class="m">agent/pkg · shared by app and headless agent</text>
+      <rect x="446" y="112" width="130" height="40" rx="2" class="s"/><text x="511" y="130" text-anchor="middle" class="t">supervisor</text><text x="511" y="146" text-anchor="middle" class="m">start · restart · backoff</text>
+      <rect x="586" y="112" width="130" height="40" rx="2" class="s"/><text x="651" y="130" text-anchor="middle" class="t">bridge</text><text x="651" y="146" text-anchor="middle" class="m">loopback webhook</text>
+      <rect x="446" y="166" width="130" height="40" rx="2" class="fab"/><text x="511" y="184" text-anchor="middle" class="ma">spool</text><text x="511" y="200" text-anchor="middle" class="m">bounded · acked per event</text>
+      <rect x="586" y="166" width="130" height="40" rx="2" class="s"/><text x="651" y="184" text-anchor="middle" class="t">pump</text><text x="651" y="200" text-anchor="middle" class="m">MQTT QoS 1 · TLS</text>
+      <rect x="446" y="220" width="270" height="40" rx="2" class="s"/><text x="581" y="238" text-anchor="middle" class="t">camera reconciler</text><text x="581" y="254" text-anchor="middle" class="m">pulls desired state · runs placement checks</text>
+
+      <!-- app -->
+      <rect x="790" y="50" width="280" height="230" rx="3" class="s"/>
+      <text x="806" y="76" class="t">Shop app — Wails</text><text x="806" y="93" class="m">Go + React in the system webview · 12 MB</text>
+      <rect x="806" y="112" width="248" height="40" rx="2" class="s"/><text x="930" y="130" text-anchor="middle" class="t">window</text><text x="930" y="146" text-anchor="middle" class="m">Live · Customers · Cameras</text>
+      <rect x="806" y="166" width="248" height="40" rx="2" class="s"/><text x="930" y="184" text-anchor="middle" class="t">system tray</text><text x="930" y="200" text-anchor="middle" class="m">green / amber / red · start · stop · quit</text>
+      <rect x="806" y="220" width="248" height="40" rx="2" class="s"/><text x="930" y="238" text-anchor="middle" class="t">camera relay</text><text x="930" y="254" text-anchor="middle" class="m">loopback · no credential in the page</text>
+
+      <!-- links -->
+      <path d="M372 133 L428 133" class="s" marker-end="url(#a)"/><text x="400" y="126" text-anchor="middle" class="l">events</text>
+      <path d="M428 186 L372 186" class="sd" marker-end="url(#a)"/><text x="400" y="204" text-anchor="middle" class="l">health · stats</text>
+      <path d="M732 165 L788 165" class="s" marker-start="url(#a)" marker-end="url(#a)"/><text x="760" y="158" text-anchor="middle" class="l">embeds</text>
+
+      <!-- state root -->
+      <rect x="30" y="316" width="1040" height="60" rx="3" class="fs"/>
+      <text x="50" y="340" class="t">One state root — ProgramData\Behavision</text>
+      <text x="50" y="360" class="m">data\behavision.db · data\cameras.json (DPAPI) · data\api_credentials.txt · models\ · runtime\ (the engine's Python) · agent.json · spool\</text>
+      <path d="M200 282 L200 314" class="sd"/><path d="M580 282 L580 314" class="sd"/><path d="M930 282 L930 314" class="sd"/>
+      <text x="1050" y="360" text-anchor="end" class="ma">BEHAVISION_DATA_DIR</text>
+    </svg>
+  </div>
+  <div class="facts">
+    <div><b>Python</b> where the recognition ecosystem is — ONNX, OpenCV, FAISS are first-class.</div>
+    <div><b>Go</b> for lifecycle and delivery — static binaries, cross-compiled to Windows from anywhere.</div>
+    <div><b>Wails</b> for the UI — window, tray and supervisor in one process; a service cannot draw a tray icon.</div>
+    <div><b>Exact search</b>: 100,000 identities in 21.9 ms. Identity is decided once per track, so this is queries per minute, not per frame.</div>
+  </div>
+</section>
+
+<!-- ============================================================ 03 -->
+<section class="plate" id="p3">
+  <div class="head"><span class="n">03</span><div><h2>Recognition: one decision per visit</h2><p>Frames become tracks; tracks accumulate evidence; a track is identified once. A "not sure" outcome is what stops one person becoming three, and a stranger becoming a regular.</p></div></div>
+  <div class="fig">
+    <svg viewBox="0 0 1100 430" role="img" aria-label="Flow: frames from a camera are detected by YuNet, associated into tracks by IoU, scored for quality, aligned and embedded with ArcFace, averaged over at least three views, then compared to the gallery. Similarity at or above 0.42 is a known person; between 0.32 and 0.42 the system waits for a better view; below 0.32 the person is new and enrolled. Known matches at good quality reinforce the gallery.">
+      <g class="t" text-anchor="middle">
+        <rect x="20" y="60" width="120" height="66" rx="2" class="s"/><text x="80" y="88">Frames</text>
+        <rect x="176" y="60" width="130" height="66" rx="2" class="s"/><text x="241" y="88">Detect</text>
+        <rect x="342" y="60" width="130" height="66" rx="2" class="s"/><text x="407" y="88">Track</text>
+        <rect x="508" y="60" width="130" height="66" rx="2" class="s"/><text x="573" y="88">Quality gate</text>
+        <rect x="674" y="60" width="130" height="66" rx="2" class="s"/><text x="739" y="88">Align + embed</text>
+        <rect x="840" y="60" width="130" height="66" rx="2" class="sa"/><text x="905" y="88" class="ta">Average ≥ 3</text>
+      </g>
+      <g class="m" text-anchor="middle">
+        <text x="80" y="108">15 fps · latest frame</text>
+        <text x="241" y="108">YuNet · 5 landmarks</text><text x="241" y="121">score ≥ 0.82</text>
+        <text x="407" y="108">greedy IoU 0.3</text><text x="407" y="121">one track per person</text>
+        <text x="573" y="108">sharp · size · light · frontal</text><text x="573" y="121">per-camera threshold</text>
+        <text x="739" y="108">Umeyama → 112×112</text><text x="739" y="121">ArcFace r50 · 512-d</text>
+        <text x="905" y="108">normalised mean</text><text x="905" y="121">≥ 4 hits</text>
+      </g>
+      <g class="s" marker-end="url(#a)"><line x1="142" y1="93" x2="174" y2="93"/><line x1="308" y1="93" x2="340" y2="93"/><line x1="474" y1="93" x2="506" y2="93"/><line x1="640" y1="93" x2="672" y2="93"/><line x1="806" y1="93" x2="838" y2="93"/></g>
+
+      <!-- decision -->
+      <path d="M905 128 L905 176" class="sa" marker-end="url(#aa)"/>
+      <path d="M905 180 L985 236 L905 292 L825 236 Z" class="sa"/>
+      <text x="905" y="231" text-anchor="middle" class="ta">cosine vs</text><text x="905" y="246" text-anchor="middle" class="ta">gallery</text>
+
+      <!-- outcomes -->
+      <path d="M825 236 L720 236" class="s" marker-end="url(#a)"/>
+      <rect x="590" y="206" width="128" height="60" rx="2" class="fgb"/><text x="654" y="230" text-anchor="middle" class="t">known</text><text x="654" y="248" text-anchor="middle" class="m">≥ 0.42 · person.seen</text>
+      <path d="M905 292 L905 330" class="s" marker-end="url(#a)"/>
+      <rect x="841" y="334" width="128" height="60" rx="2" class="fwb"/><text x="905" y="358" text-anchor="middle" class="t">not sure</text><text x="905" y="376" text-anchor="middle" class="m">0.32 – 0.42 · retry ≤ 8×</text>
+      <path d="M985 236 L1090 236" class="s" marker-end="url(#a)" style="display:none"/>
+      <path d="M985 236 L1020 236 L1020 260" class="s" marker-end="url(#a)"/>
+      <rect x="956" y="264" width="128" height="60" rx="2" class="fab"/><text x="1020" y="288" text-anchor="middle" class="t">new</text><text x="1020" y="306" text-anchor="middle" class="m">&lt; 0.32 · enrol</text>
+
+      <!-- gallery + reinforcement -->
+      <use href="#g-db" x="380" y="216" width="40" height="40"/>
+      <text x="400" y="278" text-anchor="middle" class="t">Gallery</text><text x="400" y="294" text-anchor="middle" class="m">SQLite + FAISS · ≤ 5 views per person</text>
+      <path d="M588 236 L426 236" class="sd" marker-end="url(#a)"/><text x="507" y="228" text-anchor="middle" class="l">reinforce: good quality, not a near-duplicate</text>
+      <path d="M956 300 L940 300 L940 410 L400 410 L400 262" class="sd" marker-end="url(#a)"/><text x="670" y="403" text-anchor="middle" class="l">enrol as "Visitor N"</text>
+      <path d="M400 214 L400 140 L905 140" class="sd" stroke-dasharray="2 3"/><text x="650" y="134" text-anchor="middle" class="l">index searched once per track</text>
+
+      <!-- retry loop -->
+      <path d="M841 364 L780 364 L780 93" class="sd" marker-end="url(#a)"/><text x="720" y="380" text-anchor="middle" class="l">wait 0.5 s for a better frame</text>
+    </svg>
+  </div>
+  <div class="facts">
+    <div><b>Never per frame.</b> Single-frame decisions turned one walk-past into three or four "people"; averaging fixed it.</div>
+    <div><b>Model-tagged embeddings.</b> Only same-model vectors share an index; swapping encoders can never mix spaces.</div>
+    <div><b>Quality is per camera, match is shared.</b> Every camera writes into one gallery.</div>
+    <div><b>Measured:</b> 103 tracks → 7 people, 44 correct re-recognitions, in five minutes on the office camera.</div>
+  </div>
+</section>
+
+<!-- ============================================================ 04 -->
+<section class="plate" id="p4">
+  <div class="head"><span class="n">04</span><div><h2>Delivery: durable before published</h2><p>Nothing is removed from the shop's disk until the broker has confirmed it, and the server drops what it has already seen. That pair is what makes an outage a delay and not a hole.</p></div></div>
+  <div class="fig">
+    <svg viewBox="0 0 1100 380" role="img" aria-label="Swimlanes for shop PC, broker and cloud. A visit event flows from engine to bridge, is appended to the spool and derived an event id, the pump is woken, publishes at QoS 1 over TLS to Mosquitto, the broker acknowledges, only then is the spool file deleted. The ingest consumer deduplicates on the event id, writes to PostgreSQL, and rings a doorbell that wakes live SSE streams to head office. When offline the pump retries with backoff and the spool grows on disk.">
+      <text x="24" y="26" class="z">SHOP PC</text><text x="560" y="26" class="z">BROKER</text><text x="790" y="26" class="z">CLOUD</text>
+      <line x1="536" y1="36" x2="536" y2="350" stroke="currentColor" stroke-width="1.5" stroke-dasharray="5 4" opacity=".45"/>
+      <line x1="760" y1="36" x2="760" y2="350" stroke="currentColor" stroke-width="1" opacity=".25"/>
+
+      <g class="t" text-anchor="middle">
+        <rect x="24" y="70" width="110" height="56" rx="2" class="s"/><text x="79" y="94">engine</text>
+        <rect x="164" y="70" width="110" height="56" rx="2" class="s"/><text x="219" y="94">bridge</text>
+        <rect x="304" y="70" width="110" height="56" rx="2" class="sa"/><text x="359" y="94" class="ta">spool</text>
+        <rect x="24" y="200" width="110" height="56" rx="2" class="s"/><text x="79" y="224">waker</text>
+        <rect x="304" y="200" width="110" height="56" rx="2" class="s"/><text x="359" y="224">pump</text>
+        <rect x="580" y="130" width="130" height="66" rx="2" class="s"/><text x="645" y="158">Mosquitto</text>
+        <rect x="790" y="130" width="120" height="66" rx="2" class="s"/><text x="850" y="158">ingest</text>
+        <rect x="790" y="250" width="120" height="56" rx="2" class="s"/><text x="850" y="274">API · SSE</text>
+      </g>
+      <g class="m" text-anchor="middle">
+        <text x="79" y="113">webhook POST</text>
+        <text x="219" y="113">event_id = site·cam·id·sec</text>
+        <text x="359" y="113">append → fsync</text>
+        <text x="79" y="243">rung AFTER append</text>
+        <text x="359" y="243">QoS 1 · in order</text>
+        <text x="645" y="178">TLS 8883 · ACL by tenant</text>
+        <text x="850" y="178">INSERT … ON CONFLICT</text>
+        <text x="850" y="293">arrivals feed</text>
+      </g>
+      <use href="#g-db" x="1000" y="140" width="40" height="40"/><text x="1020" y="200" text-anchor="middle" class="t">PostgreSQL</text>
+      <use href="#g-pc" x="1000" y="262" width="36" height="36"/><text x="1020" y="316" text-anchor="middle" class="m">head office</text>
+
+      <g class="s" marker-end="url(#a)">
+        <line x1="136" y1="98" x2="162" y2="98"/><line x1="276" y1="98" x2="302" y2="98"/>
+        <path d="M219 128 L219 228 L136 228" /><path d="M136 228 L302 228" style="display:none"/>
+        <line x1="136" y1="228" x2="302" y2="228" />
+        <path d="M416 228 L470 228 L470 163 L578 163" class="sa" marker-end="url(#aa)"/>
+        <line x1="712" y1="163" x2="788" y2="163"/>
+        <line x1="912" y1="163" x2="998" y2="163"/>
+        <line x1="850" y1="198" x2="850" y2="248"/>
+        <line x1="912" y1="278" x2="998" y2="278"/>
+      </g>
+      <text x="228" y="245" text-anchor="middle" class="l">wake</text>
+      <text x="470" y="152" text-anchor="middle" class="la">publish</text>
+      <text x="750" y="156" text-anchor="middle" class="l">deliver</text>
+      <text x="955" y="156" text-anchor="middle" class="l">write</text>
+      <text x="862" y="228" class="l">doorbell</text>
+      <text x="955" y="271" text-anchor="middle" class="l">push</text>
+
+      <!-- ack path -->
+      <path d="M645 198 L645 320 L359 320 L359 258" class="sa" stroke-dasharray="5 4" marker-end="url(#aa)"/>
+      <text x="500" y="338" text-anchor="middle" class="la">PUBACK → delete the spool file. Never before.</text>
+
+      <!-- offline loop -->
+      <path d="M304 240 L280 240 L280 300 L304 300" class="sd" style="display:none"/>
+      <rect x="160" y="284" width="126" height="44" rx="2" class="fs"/>
+      <text x="223" y="302" text-anchor="middle" class="l">offline?</text><text x="223" y="318" text-anchor="middle" class="m">backoff 1 → 30 s · spool grows</text>
+      <path d="M302 244 L286 300" class="sd" marker-end="url(#a)"/>
+      <path d="M286 306 L350 260" class="sd" style="display:none"/>
+    </svg>
+  </div>
+  <div class="facts">
+    <div><b>QoS 1, clean session.</b> QoS 0 could delete an event the wire dropped; QoS 2 buys nothing the derived id doesn't already give.</div>
+    <div><b>Ordered.</b> A failed publish stops the batch — a customer's visits are a timeline.</div>
+    <div><b>Bounded and honest.</b> The spool has a cap and reports what it dropped; a corrupt entry is quarantined, never retried forever.</div>
+    <div><b>Measured:</b> 120 simultaneous visits published, 120 delivered; end to end in ~3 s.</div>
+  </div>
+</section>
+
+<!-- ============================================================ 05 -->
+<section class="plate" id="p5">
+  <div class="head"><span class="n">05</span><div><h2>Local gallery, master database</h2><p>Two stores with two jobs. The shop PC's gallery recognises people in that shop, offline if need be. The platform's database knows the business: customers across shops, history, reports, tenancy.</p></div></div>
+  <div class="fig">
+    <svg viewBox="0 0 1100 360" role="img" aria-label="Left: the shop PC's SQLite gallery with identities, model-tagged embeddings and sightings, plus a camera list. Right: PostgreSQL with clients, sites, users, visitors, visits, embeddings, cameras and sessions, every row carrying a client id. Between them: templates travel up with each visit; camera configuration and check jobs travel down; nothing else crosses.">
+      <text x="24" y="26" class="z">SHOP PC</text><text x="640" y="26" class="z">PLATFORM</text>
+      <line x1="540" y1="36" x2="540" y2="330" stroke="currentColor" stroke-width="1.5" stroke-dasharray="5 4" opacity=".45"/>
+
+      <use href="#g-db" x="60" y="60" width="56" height="56"/>
+      <text x="140" y="80" class="ta">SQLite gallery</text>
+      <text x="140" y="98" class="m">the only persistent state on the PC · WAL</text>
+      <g class="m"><text x="140" y="124">identities        Visitor N, label</text><text x="140" y="140">embeddings        512-d · tagged by model</text><text x="140" y="156">sightings         identity × camera × time</text></g>
+      <text x="140" y="184" class="t">FAISS index — rebuilt from SQLite at boot</text>
+      <text x="140" y="200" class="m">exact inner product · numpy fallback identical</text>
+
+      <use href="#g-file" x="60" y="230" width="44" height="44"/>
+      <text x="140" y="250" class="t">cameras.json</text><text x="140" y="266" class="m">passwords DPAPI-encrypted · machine-bound</text>
+      <text x="140" y="296" class="t">agent.json</text><text x="140" y="312" class="m">broker login · agent token · sealed at rest</text>
+
+      <use href="#g-db" x="590" y="60" width="56" height="56"/>
+      <text x="670" y="80" class="ta">PostgreSQL</text>
+      <text x="670" y="98" class="m">every table carries client_id · self-migrating schema · 13 migrations</text>
+      <g class="m">
+        <text x="670" y="124">clients           slug = MQTT topic prefix</text>
+        <text x="670" y="140">sites · agents    slug · tz · heartbeat · fraction_below_gate</text>
+        <text x="670" y="156">app_users         owner · manager · staff · bcrypt</text>
+        <text x="670" y="172">visitors          number → V-42 · per tenant</text>
+        <text x="670" y="188">visits            seq (feed cursor) · source_event_id (dedupe)</text>
+        <text x="670" y="204">visitor_embeddings  ≤ 5 · reinforced server-side</text>
+        <text x="670" y="220">site_cameras      password sealed AES-GCM, aad = site</text>
+        <text x="670" y="236">sessions          SHA-256 of tokens · revocable</text>
+        <text x="670" y="252">visit_faces · camera_snapshots · audit_log</text>
+      </g>
+      <text x="670" y="290" class="t">Object storage (optional)</text><text x="670" y="306" class="m">presigned PUT from the shop PC · presigned GET for staff · private ACL in the signature</text>
+
+      <!-- flows across -->
+      <path d="M420 120 L660 120" style="display:none"/>
+      <path d="M380 210 L528 210 L528 190 L556 190" class="sa" marker-end="url(#aa)" style="display:none"/>
+      <path d="M400 216 L520 216" class="sa" marker-end="url(#aa)"/><text x="460" y="208" text-anchor="middle" class="la">visit + template ↑</text>
+      <path d="M520 244 L400 244" class="sd" marker-end="url(#a)"/><text x="460" y="262" text-anchor="middle" class="l">cameras · checks ↓</text>
+      <path d="M400 290 L520 290" class="sd" marker-end="url(#a)" opacity=".5"/><text x="460" y="308" text-anchor="middle" class="l">heartbeat · health ↑</text>
+    </svg>
+  </div>
+  <div class="facts">
+    <div><b>Video, frames and raw images never cross.</b> A template and a timestamp do.</div>
+    <div><b>Tenancy is a column and a rule</b>, and the two agree: the tenant comes from the session, never from the request.</div>
+    <div><b>References are immutable</b> — slugs, camera ids, customer numbers — because other systems store them. Display names are free to change.</div>
+    <div><b>Feed by <code>seq</code></b>, never by the camera's clock: lossless under bursts and backlogs; cursors are opaque.</div>
+  </div>
+</section>
+
+<!-- ============================================================ 06 -->
+<section class="plate" id="p6">
+  <div class="head"><span class="n">06</span><div><h2>Clients and the API</h2><p>Three kinds of people and one kind of machine, all through one API. Sessions are opaque tokens in a table, so "log that device out, now" actually works.</p></div></div>
+  <div class="fig">
+    <svg viewBox="0 0 1100 400" role="img" aria-label="Head-office console, mobile app and shop app sign in with email and password and receive an opaque session; the tenant and role come from that session. They call the API's visits, visitors, sites, cameras, reports, team and assistant routes. The shop PC's agent uses its own token, issued at enrolment, against the agent routes only. Live camera video reaches head office through the agent's outbound relay.">
+      <g class="t">
+        <rect x="24" y="50" width="200" height="60" rx="2" class="s"/><use href="#g-pc" x="36" y="62" width="22" height="22"/><text x="66" y="77">Head-office console</text><text x="66" y="95" class="m">React · embedded in server</text>
+        <rect x="24" y="130" width="200" height="60" rx="2" class="s"/><use href="#g-phone" x="36" y="142" width="22" height="22"/><text x="66" y="157">Mobile app</text><text x="66" y="175" class="m">arrivals · customers · sales</text>
+        <rect x="24" y="210" width="200" height="60" rx="2" class="s"/><use href="#g-pc" x="36" y="222" width="22" height="22"/><text x="66" y="237">Shop app</text><text x="66" y="255" class="m">engine on loopback · cloud for the rest</text>
+        <rect x="24" y="300" width="200" height="60" rx="2" class="sa"/><use href="#g-gear" x="36" y="312" width="22" height="22"/><text x="66" y="327" class="ta">Shop PC agent</text><text x="66" y="345" class="m">token issued once at enrolment</text>
+      </g>
+
+      <rect x="300" y="50" width="220" height="220" rx="2" class="sa"/>
+      <text x="316" y="76" class="ta">Session</text>
+      <g class="m"><text x="316" y="100">256-bit opaque token</text><text x="316" y="116">stored as SHA-256 only</text><text x="316" y="132">refresh rotates in place</text><text x="316" y="148">revocable per device, instantly</text></g>
+      <rect x="316" y="166" width="188" height="88" rx="2" class="fs"/>
+      <text x="330" y="186" class="t">tenant ← session.client_id</text>
+      <text x="330" y="206" class="m">staff     arrivals · customers · sales</text>
+      <text x="330" y="222" class="m">manager   + cameras · team · erasure</text>
+      <text x="330" y="238" class="m">owner     + mint owners</text>
+
+      <rect x="600" y="50" width="476" height="310" rx="2" class="s"/>
+      <text x="616" y="76" class="t">/api</text>
+      <g class="m">
+        <text x="616" y="104">/auth/login · refresh · sessions · register</text>
+        <text x="616" y="124">/visits · /visits/stream ·································· SSE, cursor</text>
+        <text x="616" y="144">/visitors · /history · /profile · /image · /purchases</text>
+        <text x="616" y="164">/sites · /sites/{s}/check · /enrolment-code</text>
+        <text x="616" y="184">/cameras · /check · /snapshot.jpg · /live ······· SSE relay</text>
+        <text x="616" y="204">/reports/footfall · /reports/conversion</text>
+        <text x="616" y="224">/team · /team/members · /team/{id}/password · /invitations</text>
+        <text x="616" y="244">/assistant ··································· tools, never SQL</text>
+        <text x="616" y="264">/admin/clients ····························· platform admin only</text>
+      </g>
+      <rect x="616" y="284" width="444" height="56" rx="2" class="fab"/>
+      <text x="630" y="306" class="ma">/agent/*  — enrol · cameras · checks · faces · upload-url · live</text>
+      <text x="630" y="326" class="m">agent token only · a user session is refused</text>
+
+      <g class="s" marker-end="url(#a)"><line x1="226" y1="80" x2="298" y2="80"/><line x1="226" y1="160" x2="298" y2="160"/><line x1="226" y1="240" x2="298" y2="240"/><line x1="522" y1="160" x2="598" y2="160"/></g>
+      <path d="M226 330 L560 330 L560 312 L614 312" class="sa" marker-end="url(#aa)"/>
+      <text x="262" y="72" class="l">email + password</text>
+      <text x="1090" y="385" text-anchor="end" class="cap">Ids accept names: /api/visitors/V-42 · ?site=chennai · /api/cameras/cam1 — a uuid still works everywhere.</text>
+    </svg>
+  </div>
+  <div class="facts">
+    <div><b>Login is boring on purpose.</b> Unknown address and wrong password are byte-identical and cost the same time.</div>
+    <div><b>Another tenant's data is 404</b>, never 403 — nothing to enumerate.</div>
+    <div><b>Live video</b> at head office: the agent pushes ~13 fps only while someone watches. 259 KB/s measured.</div>
+    <div><b>The assistant</b> answers from the same report tools, as the signed-in user; it has no tenant parameter to misuse.</div>
+  </div>
+</section>
+
+<!-- ============================================================ 07 -->
+<section class="plate" id="p7">
+  <div class="head"><span class="n">07</span><div><h2>Onboarding: each tier creates the next</h2><p>No credential ships inside an installer, and nobody creates their own account from nothing.</p></div></div>
+  <div class="fig">
+    <svg viewBox="0 0 1100 300" role="img" aria-label="Sequence: the platform admin creates a merchant and its owner, receiving a one-time password. The owner creates sales staff, receiving a one-time password, or issues an invitation code. Staff sign in on the mobile app. The owner mints a single-use installation code; the shop PC redeems it and receives its broker login and API token. Head office then pushes the shop's cameras to the PC.">
+      <g class="t" text-anchor="middle">
+        <use href="#g-person" x="60" y="40" width="40" height="40"/><text x="80" y="100">Platform admin</text>
+        <use href="#g-person" x="300" y="40" width="40" height="40"/><text x="320" y="100">Merchant owner</text>
+        <use href="#g-phone" x="540" y="40" width="40" height="40"/><text x="560" y="100">Sales staff</text>
+        <use href="#g-pc" x="780" y="40" width="40" height="40"/><text x="800" y="100">Shop PC</text>
+        <use href="#g-cam" x="1000" y="40" width="40" height="40"/><text x="1020" y="100">Cameras</text>
+      </g>
+      <g class="s" marker-end="url(#a)">
+        <line x1="120" y1="140" x2="278" y2="140"/>
+        <line x1="360" y1="140" x2="518" y2="140"/>
+        <line x1="360" y1="200" x2="758" y2="200"/>
+        <line x1="840" y1="200" x2="998" y2="200"/>
+      </g>
+      <path d="M840 240 L1000 240" class="sd" marker-end="url(#a)"/>
+      <g class="m" text-anchor="middle">
+        <text x="199" y="130">POST /api/admin/clients</text><text x="199" y="158">company + owner, one transaction</text><text x="199" y="172" class="ma" opacity="1">owner password, shown once</text>
+        <text x="439" y="130">POST /api/team/members</text><text x="439" y="158">or /team/invitations → a code they redeem</text><text x="439" y="172" class="ma" opacity="1">staff password, shown once</text>
+        <text x="559" y="190">POST /api/sites/{shop}/enrolment-code</text><text x="559" y="218">single use · 7 days · redeemed by the PC:</text><text x="559" y="232" class="ma" opacity="1">broker login + agent token + CA to pin</text>
+        <text x="919" y="190">head office pushes cameras</text><text x="919" y="230">the PC pulls · adopts local ones up</text><text x="919" y="258">passwords travel only to that site's agent</text>
+      </g>
+      <text x="24" y="288" class="cap">Single use is enforced by the UPDATE itself, so two PCs racing on one code cannot both win. A wrong, spent or expired code all read the same.</text>
+    </svg>
+  </div>
+  <div class="facts">
+    <div><b>Direct or by invitation.</b> A manager can hand over a generated password, or let the salesperson choose their own via a code.</div>
+    <div><b>Reset signs the lost phone out</b> in the same transaction as the new password.</div>
+    <div><b>Standalone</b> is a first-class answer on the setup screen: a single-till shop with no head office runs the full product locally.</div>
+    <div><b>Demo build:</b> cameras ship sealed (AES-256-GCM); the unlock code travels separately from the zip.</div>
+  </div>
+</section>
+
+<!-- ============================================================ 08 -->
+<section class="plate" id="p8">
+  <div class="head"><span class="n">08</span><div><h2>Where every secret lives</h2><p>Biometric data is treated as biometric data. Each credential has one home and one protection, and none of them is ever returned by an API.</p></div></div>
+  <div class="fig">
+    <svg viewBox="0 0 1100 330" role="img" aria-label="Map of secrets: on the shop PC, camera passwords under DPAPI, the engine API credential in a 0600 file, agent token and broker password sealed in agent.json; in the database, site broker passwords and camera passwords under AES-256-GCM with the site as additional data, user passwords under bcrypt cost 12, session tokens as SHA-256; in transit, TLS for MQTT and HTTPS for the API; face templates never leave the shop as images, photos are opt-in, erasure deletes templates and objects, every image read is audited.">
+      <text x="24" y="26" class="z">SHOP PC</text><text x="400" y="26" class="z">IN TRANSIT</text><text x="640" y="26" class="z">DATABASE</text><text x="900" y="26" class="z">POLICY</text>
+      <line x1="376" y1="36" x2="376" y2="300" stroke="currentColor" stroke-width="1" opacity=".25"/>
+      <line x1="616" y1="36" x2="616" y2="300" stroke="currentColor" stroke-width="1" opacity=".25"/>
+      <line x1="876" y1="36" x2="876" y2="300" stroke="currentColor" stroke-width="1" opacity=".25"/>
+      <g class="t"><use href="#g-lock" x="24" y="52" width="20" height="20"/><text x="52" y="67">camera passwords</text><text x="52" y="84" class="m">DPAPI · machine-bound · has_password only</text>
+        <use href="#g-lock" x="24" y="110" width="20" height="20"/><text x="52" y="125">engine API credential</text><text x="52" y="142" class="m">generated on first start · 0600 · read by the agent</text>
+        <use href="#g-lock" x="24" y="168" width="20" height="20"/><text x="52" y="183">agent token · broker password</text><text x="52" y="200" class="m">sealed in agent.json · earned by enrolment, never shipped</text>
+        <use href="#g-lock" x="24" y="226" width="20" height="20"/><text x="52" y="241">face templates</text><text x="52" y="258" class="m">SQLite · treated as personal data · erasure deletes outright</text>
+      </g>
+      <g class="t"><text x="400" y="67">MQTT</text><text x="400" y="84" class="m">TLS 8883 · pinned issuer · plaintext to any non-loopback host is refused</text>
+        <text x="400" y="125">API</text><text x="400" y="142" class="m">HTTPS behind Traefik · bearer sessions</text>
+        <text x="400" y="183">images</text><text x="400" y="200" class="m">presigned URLs, minutes-long · private ACL inside the signature</text>
+        <text x="400" y="241">shop PC ↔ engine</text><text x="400" y="258" class="m">loopback only · relay token per run, no password in the page</text>
+      </g>
+      <g class="t"><text x="640" y="67">broker + camera passwords</text><text x="640" y="84" class="m">AES-256-GCM · aad = owning site · row copies don't decrypt</text>
+        <text x="640" y="125">user passwords</text><text x="640" y="142" class="m">bcrypt cost 12 · 10 failures / 15 min per account</text>
+        <text x="640" y="183">session tokens</text><text x="640" y="200" class="m">SHA-256 only · a dump holds no usable session</text>
+        <text x="640" y="241">audit_log</text><text x="640" y="258" class="m">every face-image hand-out, every code minted, every merchant created</text>
+      </g>
+      <g class="t"><text x="900" y="67">video never leaves</text><text x="900" y="84" class="m">recognition runs in the shop</text>
+        <text x="900" y="125">photos are opt-in</text><text x="900" y="142" class="m">store_faces defaults to off</text>
+        <text x="900" y="183">tenancy is structural</text><text x="900" y="200" class="m">session decides · 404, never 403</text>
+        <text x="900" y="241">erasure erases</text><text x="900" y="258" class="m">object first · 502 changes nothing</text>
+      </g>
+    </svg>
+  </div>
+</section>
+
+<!-- ============================================================ 09 -->
+<section class="plate" id="p9">
+  <div class="head"><span class="n">09</span><div><h2>The stack, and the numbers behind it</h2><p>Each layer, the choice, and the one reason that decided it.</p></div></div>
+  <div class="fig">
+    <svg viewBox="0 0 1100 330" role="img" aria-label="Layer stack: clients (React console, mobile, Wails app); API and web (Go, one binary, opaque sessions); transport (Mosquitto MQTT, QoS 1, TLS); master data (PostgreSQL, self-migrating); shop agent (Go library: spool, pump, supervisor); recognition (Python: YuNet, ArcFace r50 on ONNX Runtime, FAISS, SQLite); cameras (any RTSP). Each with its deciding reason.">
+      <g class="t">
+        <rect x="24" y="30" width="1052" height="38" rx="2" class="s"/><text x="40" y="54">Clients</text><text x="200" y="54" class="m">React console (embedded) · mobile app · Wails shop app</text><text x="1060" y="54" text-anchor="end" class="l">one API; UI can never lag its server</text>
+        <rect x="24" y="74" width="1052" height="38" rx="2" class="s"/><text x="40" y="98">API + web</text><text x="200" y="98" class="m">Go · one binary · opaque sessions in a table</text><text x="1060" y="98" text-anchor="end" class="l">instant per-device revocation; JWTs cannot</text>
+        <rect x="24" y="118" width="1052" height="38" rx="2" class="s"/><text x="40" y="142">Transport</text><text x="200" y="142" class="m">Mosquitto · MQTT QoS 1 · TLS · per-tenant ACL</text><text x="1060" y="142" text-anchor="end" class="l">built for many outbound clients; ~10 MB</text>
+        <rect x="24" y="162" width="1052" height="38" rx="2" class="s"/><text x="40" y="186">Master data</text><text x="200" y="186" class="m">PostgreSQL · self-applying migrations · advisory lock · checksums</text><text x="1060" y="186" text-anchor="end" class="l">transactions across tenant + owner; keyset feeds</text>
+        <rect x="24" y="206" width="1052" height="38" rx="2" class="s"/><text x="40" y="230">Shop agent</text><text x="200" y="230" class="m">Go library · spool · pump · supervisor · reconciler</text><text x="1060" y="230" text-anchor="end" class="l">static binary, cross-compiled; one tested implementation</text>
+        <rect x="24" y="250" width="1052" height="38" rx="2" class="sa"/><text x="40" y="274" class="ta">Recognition</text><text x="200" y="274" class="m">Python · YuNet · ArcFace r50 (ONNX Runtime) · FAISS IndexFlatIP · SQLite WAL</text><text x="1060" y="274" text-anchor="end" class="la">97.25 IJB-C · exact search · no second process</text>
+        <rect x="24" y="294" width="1052" height="30" rx="2" class="fs"/><text x="40" y="314">Cameras</text><text x="200" y="314" class="m">any RTSP camera · make picker fills the stream path · placement proved by a 25-second walk-past</text>
+      </g>
+    </svg>
+  </div>
+  <div class="metrics" style="margin-top:1.1rem">
+    <div class="metric"><span class="v">103 → 7</span><span class="k">tracks to people, 5 min, office camera — 44 re-recognitions</span></div>
+    <div class="metric"><span class="v">120 / 120</span><span class="k">simultaneous visits delivered, real broker and database</span></div>
+    <div class="metric"><span class="v">21.9 ms</span><span class="k">exact search over 100,000 identities</span></div>
+    <div class="metric"><span class="v">~3 s</span><span class="k">camera to head-office feed</span></div>
+    <div class="metric"><span class="v">14 fps</span><span class="k">live picture on the shop PC vs a 15 fps camera</span></div>
+    <div class="metric"><span class="v">10 / 10</span><span class="k">install steps on a clean machine, both cameras connected</span></div>
+  </div>
+</section>
+
+</main>
+
+<footer>
+  <div class="wrap">Behavision — Loyaly · Technical overview, 11 September 2026 · release 0.4.1 · engine 1.1.0 · schema at migration 13. All figures measured on the running system.</div>
+</footer>

installer/INSTALL.txt

@@ -0,0 +1,120 @@
+Behavision — installing on a shop PC
+====================================
+
+This is a source install. It needs Python and a working internet connection
+once, at setup. After that the shop PC runs on its own.
+
+
+WHAT YOU NEED FIRST
+-------------------
+
+Python 3.10 or newer.
+
+  https://www.python.org/downloads/windows/
+
+  On the very first screen of the Python installer, tick
+  "Add python.exe to PATH". If you miss it, setup cannot find Python and
+  you will have to run the Python installer again.
+
+
+SETTING UP
+----------
+
+1. Unzip this whole folder somewhere permanent — for example
+   C:\Behavision. Keep the files together; behavision-setup.exe looks for
+   the engine-src folder next to itself.
+
+2. Double-click  behavision-setup.exe
+
+   It will:
+     - find your Python and check it is new enough
+     - build a private Python environment under
+       C:\ProgramData\Behavision\runtime
+     - install the recognition engine and its libraries (from the wheel
+       in engine-src; the folder you unzipped is never written to)
+     - download the recognition models (a few hundred megabytes)
+     - start the engine once to prove it works
+
+   This takes several minutes. Leave the window open until it says Done.
+   If anything fails it prints why, and running it again is safe.
+
+   DEMO RELEASE ONLY: if the release came with the cameras already set up,
+   setup first asks for an unlock code. Type the code you were given. The
+   camera details are sealed inside the release and cannot be read without
+   it; with it, both cameras are added and the PC is set to run on its own,
+   with no head office. Skip the installation-code screen - it will not
+   appear.
+
+3. Double-click  Behavision.exe
+
+   The window opens and an icon appears in the system tray, next to the
+   clock. Right-click the tray icon to open the window again, or to stop
+   recognition.
+
+
+CONNECTING IT TO HEAD OFFICE
+----------------------------
+
+The first screen asks for an installation code. Ask whoever manages your
+shops — they create one from the Behavision platform, under the shop.
+
+No head office? Choose "set this PC up on its own" on the same screen.
+Recognition, the cameras and the customer list all work locally; nothing is
+sent anywhere.
+
+
+ADDING A CAMERA
+---------------
+
+Cameras → Add. You need the camera's address on the shop network, its
+username and password. Choose your camera's make from the list and the
+stream path is filled in for you — that is the field nobody can look up.
+
+Press "Test" before saving. Then press "Check placement" and walk past the
+camera a few times. It will tell you whether the camera can actually
+recognise faces from where it is mounted, which is not the same question as
+whether it is connected.
+
+Camera placement matters more than camera quality. Aim for roughly head
+height, facing the direction people walk in. A camera high in a corner
+looking down, or pointing at a bright window or glass door, will connect
+perfectly and recognise almost nobody.
+
+
+WHERE THINGS LIVE
+-----------------
+
+  C:\ProgramData\Behavision\        database, logs, camera list, models
+  C:\ProgramData\Behavision\runtime the engine's own Python
+
+Everything the software writes is under ProgramData. The folder you unzipped
+is never written to, so you can keep it on a shared drive.
+
+
+STOPPING IT
+-----------
+
+Right-click the tray icon and choose Quit. That stops recognition as well —
+leaving it running with no visible control would be worse than stopping it.
+
+Closing the window does NOT stop recognition. The window hides and the tray
+icon stays, because a shop assistant clicking X should not switch the shop's
+footfall counting off for the rest of the day.
+
+
+IF SOMETHING IS WRONG
+---------------------
+
+  "No Python 3.10 or newer was found"
+      Python is missing, too old, or was installed without the
+      "Add python.exe to PATH" tick. Reinstall Python with that ticked.
+
+  Setup fails while installing libraries
+      Almost always no internet, or a proxy in the way. The error printed
+      just above the failure says which.
+
+  The window opens but says the engine is not running
+      Run behavision-setup.exe again; it will report what is missing.
+
+  Logs
+      C:\ProgramData\Behavision\engine.log

installer/behavision.iss

@@ -31,6 +31,8 @@
 #define MyAppExeName "Behavision.exe"
 
 [Setup]
+; The Loyaly mark, on the installer and in Add/Remove Programs.
+SetupIconFile=..\brand\loyaly.ico
 AppId={{7C4B9E2A-3F51-4C86-9D0A-B1E7A2F65D11}
 AppName={#MyAppName}
 AppVersion={#MyAppVersion}