@@ -1,99 +1,54 @@
 # Working rules for this repository
 
 The general rules — sources and evidence, verification, files and state, git,
-delegation, working with Adrian — live in his global `~/.claude/CLAUDE.md`,
-hoisted 2026-09-06 from every repo on his other machine. **They are the
-authority and they are not copied here**, because a copy drifts and those rules
-were bought with real failures.
+delegation, working with Adrian — live in his global `~/.claude/CLAUDE.md`.
+**That file is the authority and is not copied here**, because a copy drifts
+and those rules were bought with real failures.
+
+It does not travel with a repository. A session on a machine without it is
+missing them and should say so rather than proceeding as though what follows is
+complete.
+
+Everything specific to this library is enforced by something executable rather
+than written down as a habit to remember. The rule and the thing that checks it
+are the same object:
+
+| what it enforces | run |
+|---|---|
+| every OSC address is in the contract | `extras/webserial/test/test-namespace.mjs` |
+| a board answers what it announces | `extras/webserial/test/test-announce.mjs` |
+| the page has a panel for every capability | `extras/webserial/test/test-panels.mjs` |
+| generated sketches match the template | `extras/webserial/check.mjs` |
+| the probe itself still detects a broken board | `test/hardware/test_contractprobe.py` |
+| a board obeys the contract on the wire | `test/hardware/contractprobe.py PORT` |
+| what is actually plugged in, by identity not port name | `test/hardware/census.py --probe` |
+| a person must press, turn or watch something | `test/hardware/humanprobe.py` |
+| the `python` a core needs, without breaking Homebrew | `tools/python-shim.sh` |
+| no credential reaches a commit | `tools/pre-commit` (installed by `tools/install-hooks.sh`) |
+
+`make -C extras/webserial all` runs the host suite. Each tool's header says
+which failure bought it.
+
+## The documents
+
+[ADDRESSES.md](./ADDRESSES.md) is the OSC address contract — capability-named,
+and *absence is silence*: what a board lacks is missing from its `/enq`
+greeting and answers nothing.
 
-That file does not travel with this repository, so a session on a machine
-without it is missing them. If you are such a session, say so rather than
-proceeding as though the guidance below is complete. The rules it carries that
-this repository has already violated, in one session, are worth naming: *"not
-found" means "not where I looked"*, *read the primary source before you assert*,
-*nothing that must outlive the turn lives in /tmp*, and *a uniform negative is a
-harness bug until shown otherwise*.
-
-What follows is only what is specific to this library.
-
-## The authorities here
-
-[ADDRESSES.md](./ADDRESSES.md) is the OSC address contract.
 [BRINGUP.md](./BRINGUP.md) is how a board is brought up, and
-[BOARDS.md](./BOARDS.md) records what has actually run on hardware, with the
-Method rules for measurement in
-[test/hardware/README.md](./test/hardware/README.md) — trickle gate passed,
-three repeats, same-day reference board, mechanism named.
+[BOARDS.md](./BOARDS.md) records what has run on hardware, under the Method in
+[test/hardware/README.md](./test/hardware/README.md) — trickle gate, three
+repeats, same-day reference, mechanism named.
 `.claude/skills/board-bringup/` is BRINGUP.md's operating summary and is
-committed, so it does travel.
-
-## The address space is enforced, not just documented
-
-`ADDRESSES.md` is the contract, and three tests fail on any drift from it:
-`test-namespace.mjs` on an address outside the document, `test-announce.mjs`
-when a board announces a capability nothing answers, `test-panels.mjs` when the
-contract gains a capability the page forgot. `make -C extras/webserial all`
-runs them.
-
-**Absence is silence.** A capability a board lacks is missing from its `/enq`
-greeting and answers nothing — no booleans, no sentinel values, and never a
-reply claiming success from hardware that is not there. A board built against a
-generic variant will inherit peripherals it does not have; `boards.json` takes
-`defines` (`OSC_NO_RGB`, `OSC_NO_LED`) so it cannot announce them.
-
-Examples are named `<Board><Chip><Transport>`; the convention and its three
-deliberate exceptions are in `extras/webserial/README.md`.
-
-## Hardware specifics
-
-**The chip is not the board.** Every native-USB ESP32 enumerates as
-`303a:1001`; pin maps, LED polarity and FQBN defaults belong to the carrier.
-Ask which board it is and weight the answer above your own inference.
+committed, so it travels with the repository.
 
-**The vendor's peripheral list is a work list.** Every peripheral the
-documentation names ends up either announced as `/enq/<capability>` or written
-into the board's `boards.json` note as present-but-not-wired. Prefer the
-vendor's own pin header to its README: the T-Encoder-Pro's `pin_config.h` named
-a haptic engine, IMU, RTC and PMIC that the README summary did not.
-
-**Ports renumber, and boards drop off hubs.** Re-list immediately before every
-upload; never reuse a port name across two commands.
-
-**FQBN options are per-board.** Read `boards.txt`; never carry another board's
-options across. Give `arduino-cli` a private `--build-path` per sketch or
-parallel builds stomp each other's objects.
-
-**Asking a human to press or turn something needs the ask to arrive first.**
-Tool output does not reach them until the turn ends, so a prompt printed inside
-a sampling loop is read after the window has shut. Start the sampler in the
-background, then ask.
-
-## Credentials
-
-WiFi credentials live in `arduino_secrets.h`: git-ignored twice over, refused by
-`tools/pre-commit`, which also greps added lines for `ssid`/`password`/`pass`/
-`psk` patterns. Never edit the placeholder defaults in a tracked sketch. Sweep
-the staged diff before any push — this remote is public.
+Naming is `<Board><Chip><Transport>`; the convention and its three deliberate
+exceptions are in `extras/webserial/README.md`.
 
 ## Git here
 
 The default branch is **`master`**; there is no `main`. Commit as
 `adrian@adrianfreed.com` — an unset `user.email` makes git invent a hostname
 address — and end messages with the `Co-Authored-By` trailer. Commit and push
-only when asked.
-
-`git add -A` has twice swept up in-flight files that were not mine. Check
-`git status` before staging and leave what you did not write.
-
-## This machine
-
-**The Seeed nRF52 core shells out to `python`**, which modern macOS lacks. Use a
-shim directory on PATH holding a *script* that execs an *absolute*
-`/usr/bin/python3`. A symlink does not work — `/usr/bin/python3` is the Command
-Line Tools stub and dispatches on `argv[0]`. Never write into the Homebrew
-prefix, and never omit the absolute path: `exec python3 "$@"` recurses forever,
-and that exact line overwrote Homebrew's binary here and broke every ESP32 build
-for sixteen hours.
-
-**macOS denies CoreBluetooth to command-line tools** with no prompt at all, so
-BLE testing goes through Chrome and Web Bluetooth. Serial is never blocked.
+only when asked, and check `git status` before staging: `git add -A` has twice
+swept up in-flight files belonging to someone else.
@@ -296,6 +296,27 @@ missing and whose write path turned out to be dropping bytes on the host.
 codec round-trips, and `write_all()` against an fd that guarantees short
 writes, with a negative control proving the old broken pattern fails it.
 
+**`census.py [--probe] [--chip]`** answers "what is actually plugged in",
+which BRINGUP.md Phase 0 requires and which no port name can. It lists every
+serial device with what `arduino-cli` believes, and with `--probe` asks each
+one for its OSC `/enq` greeting — a board running an Oscuino sketch names
+itself, which is the cheapest identification available and needs no reset.
+`--chip` additionally runs `esptool chip-id` for the MAC that distinguishes two
+identical-looking ESP32s, and says so, because that leaves the part in download
+mode. It exists because ports renumber on every flash and boards displace each
+other on a hub: in one session a XIAO's port moved three times, an upload to
+the stale name failed, and two boards left the bus entirely.
+
+**`humanprobe.py PORT ADDR "what to do" [--dir] [--secs=N]`** runs a window for
+the things only a person can cause — a press, a turn, a covered sensor. It
+prints the instruction, flushes it and counts down *before* opening the window,
+which is the whole point: the instruction used to be printed inside the
+sampling loop, and tool output does not reach the bench until the turn ends, so
+it was read after the window shut. Two such windows returned "185 samples,
+nothing moved" and looked exactly like a dead encoder. With `--dir` it reports
+which way the first motion counted, which is what settles whether clockwise
+counts up.
+
 **`contractprobe.py <port> [Name] [/old/addr ...]`** probes the core of the
 address-space contract (ADDRESSES.md) on any board: `/enq` answers with the
 name and its `/enq/...` capability lines, `/state` carries a sequence and
 
@@ -0,0 +1,176 @@
+#!/usr/bin/env python3
+"""What is actually plugged in, by identity rather than by port name.
+
+    python3 test/hardware/census.py [--probe]
+
+BRINGUP.md Phase 0 says identify the chip AND the board it sits on, and never
+identify by port name. This is that rule as a command. For every USB serial
+device it reports the port, what `arduino-cli` thinks it is, and — for ESP32
+parts — the chip and MAC that `esptool chip-id` reads out of the silicon.
+
+Why it exists rather than a remembered procedure:
+
+  * Ports renumber on every flash and boards displace each other on a hub. In
+    one session a XIAO's port name moved three times, an upload aimed at the
+    stale name failed outright, and two boards vanished from the bus entirely.
+    Anything that resolves a board by NAME is wrong by the next command.
+  * The chip is not the board. Every native-USB ESP32 enumerates as
+    303a:1001, so a VID/PID or an `arduino-cli` guess separates an Adafruit
+    board from an Espressif one and nothing finer. The MAC is what tells two
+    identical-looking ESP32s apart, and it is what BOARDS.md rows carry.
+
+`--probe` additionally asks each port for an OSC `/enq` greeting, in both
+framings, so a board already running an Oscuino sketch names itself. That is
+the cheapest identification of all and needs no reset.
+
+NOTE: `esptool chip-id` leaves the part in download mode. This runs it only
+when asked with --probe=chip, because doing it to a freshly flashed board
+stops the sketch you were about to test.
+"""
+
+import glob
+import importlib.util
+import os
+import re
+import select
+import subprocess
+import sys
+import termios
+import time
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+ESPTOOL = os.path.expanduser(
+    "~/Library/Arduino15/packages/esp32/tools/esptool_py/5.3.1/esptool")
+
+
+def ports():
+    """Serial devices, minus the Mac's own Bluetooth and modem ttys."""
+    return [p for p in sorted(glob.glob("/dev/cu.*"))
+            if not re.search(r"BLTH|Bluetooth|URT[0-9]|Joy-", p)]
+
+
+def cli_view():
+    """What arduino-cli believes, keyed by port."""
+    out = {}
+    try:
+        r = subprocess.run(["arduino-cli", "board", "list"],
+                           capture_output=True, text=True, timeout=60)
+    except Exception:
+        return out
+    for line in r.stdout.splitlines():
+        if not line.startswith("/dev/"):
+            continue
+        cols = line.split()
+        out[cols[0]] = " ".join(cols[4:7])[:38] if len(cols) > 5 else ""
+    return out
+
+
+def usb_view():
+    """VID/PID and serial per USB product name, from system_profiler."""
+    try:
+        r = subprocess.run(["system_profiler", "SPUSBDataType"],
+                           capture_output=True, text=True, timeout=120)
+    except Exception:
+        return []
+    rows, name = [], None
+    for line in r.stdout.splitlines():
+        m = re.match(r"^\s{2,}([A-Za-z0-9][^:]*):\s*$", line)
+        if m:
+            name = m.group(1).strip()
+        for key in ("Product ID", "Vendor ID", "Serial Number"):
+            if key + ":" in line and name:
+                rows.append((name, key, line.split(":", 1)[1].strip()))
+    merged = {}
+    for n, k, v in rows:
+        merged.setdefault(n, {})[k] = v
+    return [(n, d) for n, d in merged.items()
+            if "Vendor ID" in d and re.search(r"0x(239a|2341|303a|2e8a|1a86|2886|16c0|1b4f)",
+                                              d.get("Vendor ID", ""), re.I)]
+
+
+def greet(path, timeout=1.2):
+    """Ask for an OSC /enq greeting, trying both framings. Returns a name."""
+    spec = importlib.util.spec_from_file_location(
+        "oscprobe", os.path.join(HERE, "oscprobe.py"))
+    op = importlib.util.module_from_spec(spec)
+    saved, sys.argv = sys.argv, ["oscprobe", path]
+    try:
+        spec.loader.exec_module(op)
+    except SystemExit:
+        pass
+    finally:
+        sys.argv = saved
+    try:
+        fd = os.open(path, os.O_RDWR | os.O_NOCTTY | os.O_NONBLOCK)
+    except OSError:
+        return None
+    try:
+        a = termios.tcgetattr(fd)
+        a[0] = a[1] = a[3] = 0
+        a[2] = termios.CS8 | termios.CREAD | termios.CLOCAL
+        a[4] = a[5] = termios.B115200
+        a[6][termios.VMIN] = a[6][termios.VTIME] = 0
+        termios.tcsetattr(fd, termios.TCSANOW, a)
+        for payload in (op.bundle([op.msg("/enq", ())]), op.msg("/enq", ())):
+            os.write(fd, op.slip_encode(payload))
+            buf, end = b"", time.time() + timeout / 2
+            while time.time() < end:
+                r, _, _ = select.select([fd], [], [], 0.1)
+                if r:
+                    try:
+                        buf += os.read(fd, 4096)
+                    except OSError:
+                        break
+            for f in op.slip_frames(buf):
+                try:
+                    d = op.decode(f)
+                except Exception:
+                    continue
+                for addr, args in (d[1] if d[0] == "bundle" else [d]):
+                    if addr == "/enq" and args:
+                        return args[0]
+    finally:
+        os.close(fd)
+    return None
+
+
+def main():
+    probe = "--probe" in sys.argv
+    chip = "--probe=chip" in sys.argv or "--chip" in sys.argv
+    cli = cli_view()
+
+    print(f"{'port':32s} {'arduino-cli says':40s} identity")
+    for p in ports():
+        ident = ""
+        if probe or chip:
+            name = greet(p)
+            if name:
+                ident = f"/enq -> {name}"
+        if chip and not ident and os.path.exists(ESPTOOL):
+            try:
+                r = subprocess.run([ESPTOOL, "--port", p, "chip-id"],
+                                   capture_output=True, text=True, timeout=90)
+                c = re.search(r"Detecting chip type\.\.\.\s*(\S+)", r.stdout)
+                m = re.search(r"^MAC:\s*(\S+)", r.stdout, re.M)
+                if c:
+                    ident = c.group(1) + (f"  MAC {m.group(1)}" if m else "")
+                    ident += "   (left in download mode -- `esptool run` to restart)"
+            except Exception:
+                pass
+        print(f"{p:32s} {cli.get(p, ''):40s} {ident}")
+
+    usb = usb_view()
+    if usb:
+        print("\nUSB, by vendor id (a bridge chip's id belongs to the bridge, "
+              "not the board):")
+        for name, d in usb:
+            print(f"  {name[:34]:34s} {d.get('Vendor ID','')[:6]}:"
+                  f"{d.get('Product ID','')[:6]}  {d.get('Serial Number','')}")
+
+    if not (probe or chip):
+        print("\n(--probe asks each port for its /enq greeting; --chip also runs "
+              "esptool chip-id,\n which leaves the part in download mode)")
+
+
+if __name__ == "__main__":
+    main()