Marauder's Map — wiring packet

# WIRING PACKET — A-12 Marauder's Map
**Horizon Works · Q-Branch Item A-12 · 2026-10-31 · Theme: "Parchment Circuit"**
**Status: WIRING PACKET ONLY. Nothing is wired, installed, or tracking. The prototype in this folder runs on invented data — it tracks nothing and no one. The real map is off until the owner turns it on.**

> Order matters: each step below builds only on the step before it. Every step is labeled **EXISTS TODAY** / **NEEDS HARDWARE** / **NEEDS A SITTING**. A step labeled NEEDS A SITTING does not happen in a build pass — it happens with the owner present, deciding.

## The chain in one line

Per-room BLE scanners listen → a resolver assigns each consented token to its strongest-signal room → Home Assistant holds that room state locally → this map page (a local page) reads local state only and draws dots. No step sends data off the LAN.

---

## Step 1 — Per-room BLE scanning
**Label: NEEDS HARDWARE (partially inventoried) + NEEDS A SITTING (placement)**

- **What exists today:** the house's RF Detector bench — the Detector app line and its sealed-session discipline — proves the house can passively hear BLE advertisements and log them honestly. Spare handsets in the fleet have served as Detector handsets. That bench is the pattern and the test instrument; it is not, by itself, a fixed per-room scanner network.
- **What is needed:** one fixed, powered scanner per room that matters — ESP32-class boards running an open BLE-scanner firmware (ESPHome / ESPresense-class, license-checked per item before adoption), or a spare handset per room pinned to that room's scanner job. The Q-Branch record does **not** inventory a stock of ESP32 boards in the house — so the honest label is NEEDS HARDWARE until the owner inventories or rules a $0 / priced purchase per scanner. Do not assume boards exist.
- **Placement (sitting work):** one scanner per room, mains-powered (not battery — a dead scanner must read as *absent*, not as *empty room*), mounted away from metal and water, labeled with its room name on the hardware itself. Rooms without a scanner are printed on the map as UNCOVERED — never silently guessed.
- **What a scanner emits:** timestamp · scanner room · observed token identifier (the consented token's rotating BLE identifier, resolved locally — see Step 2) · RSSI. Nothing else. No payloads, no connections — passive receive only, the RF Detector fence carried whole.

## Step 2 — Presence resolver (strongest-signal room assignment)
**Label: EXISTS TODAY as a design + prototype logic; NEEDS A SITTING to tune on the real house**

- **Rule:** at any moment, a token belongs to the room whose scanner hears it **strongest** (highest RSSI), with two honesty guards: (a) a short hold — a token does not flip rooms on a single loud sample; it needs the new room to win for a sustained window (tens of seconds), and (b) a dead-band — if two rooms hear it nearly equally, the resolver prints **between rooms / uncertain** rather than picking a winner it does not believe.
- **Error honesty — printed, not footnoted:** this is **room-level presence, not exact position**. BLE signal passes through walls, reflects off appliances, and varies with a phone in a pocket vs. on a table. Expect: occasional room flips at boundaries, lag of seconds-to-a-minute on a move, and misses when a token's radio sleeps. The map must never draw a precise point inside a room as if it were measured — the prototype's room-center dot is a *room label*, and the real page keeps that convention.
- **The prototype proves the shape, not the sensing:** `index.html`'s replay engine assigns tokens to rooms from its synthetic dataset with the same `roomAt(token, time)` contract the resolver will expose. Swapping the dataset for resolver output is the wiring — the page's drawing, log, and scrubber do not change shape.
- **Tuning is sitting work:** RSSI thresholds and hold windows are set by walking the real house with a consented token while the owner watches the resolver — a calibration sitting, on the owner's feet, not a desk guess.

## Step 3 — Home Assistant presence layer
**Label: NEEDS A SITTING (the A-11 JARVIS / DAWN line owns the HA install decision)**

- Home Assistant (HA), running locally on the house hub (the Pavilion line, Setup B posture: LAN-bound), is the presence layer: each scanner reports to HA (MQTT / ESPHome native, LAN only), the resolver runs as HA-side logic (or a small local helper HA reads), and HA holds one entity per consented token: `room` · `since` · `confidence (clear / uncertain / stale)`.
- HA is also where presence history would live — which is why retention is an owner decision in §6 below, made **before** this step is switched on, not after data accumulates by default.
- This packet does not install HA. A-11 is the HA commission; A-12 rides it. If HA is not yet standing, Steps 1–2 can be bench-tested with the RF Detector tooling and a laptop — and the map stays a prototype until HA (or an owner-ruled local substitute) holds the state.

## Step 4 — The map page, fed by local data only
**Label: EXISTS TODAY (this prototype) — the feed is the wiring**

- The page in this folder is the finished *shape*: floor plan, dots with trails, event log, time display — all drawing from an in-page dataset.
- The wired page differs in exactly one way: instead of the synthetic dataset, it reads the Step 3 entities from the local HA instance (LAN address only) or from a local state file the resolver writes on the hub. No cloud relay, no external tile/map service, no analytics, no font or script fetched from anywhere — the $0, zero-external-assets discipline of this prototype is the production discipline.
- The floor plan in the wired version is drawn by/for the owner from the real house — **that drawing is an owner sitting artifact, never inferred, never in this prototype.** The prototype's plan is labeled SAMPLE PLAN for exactly this reason.
- If the local feed stops, the page prints **STALE — last update [time]** over the plan. A frozen map that looks live is the failure this rule exists to prevent.

## 5. Consent + off-switch design
**Label: NEEDS A SITTING (per person) — design EXISTS TODAY in this packet**

- **Per-person opt-in tokens:** nobody is tracked by default and nobody is tracked by household membership. Each person who chooses in carries/wears a token *they* control: their phone with the house presence app / BLE identity enabled by them, or a small BLE fob handed to them with its purpose stated. Enrolling a token is a recorded, per-person act — token, person (household-internal label only), date, and the plain words of what it does. A guest gets no token. A person who never opts in simply never appears — absence from the map is the default state of a human being.
- **Opt-out is instant and unilateral:** turning the token's Bluetooth off, leaving the fob in its off cradle, or asking for removal ends presence at the next resolver cycle. No persuasion step, no admin approval.
- **A physical off state for the whole map:** a switched outlet / labeled plug that powers the scanner hub (or the resolver host) — **unplug = off**, demonstrable, not a settings page. Plus the page-level switch prototyped here (`Map: ON / OFF`) which hides all presence and prints the OFF state. Both layers exist because a software toggle alone asks the watched to trust the watcher; a plug does not.
- **Children's posture:** no token is enrolled for a child by this packet. Any future proposal involving a child's presence is a separate owner decision under Rin's program fences — this packet neither builds it nor assumes it.

## 6. Privacy posture
**Label: Design EXISTS TODAY; the retention number is an OWNER DECISION, printed open**

- **Data never leaves the LAN.** Scanners → hub → HA → map page: every hop is a LAN hop. No cloud account, no vendor presence service, no remote viewing by default. Off-LAN access, if ever wanted, is a separate security-reviewed decision (Defender / Protector read), never a silent add-on.
- **What is kept:** room-assignment events (token label · room · time) — the minimum the map and its log need. Raw RSSI streams are working data for the resolver, not a record; the design discards them once the room call is made, apart from a short tuning window during a calibration sitting.
- **Retention, measured in days — DECISION FOR THE OWNER:** the packet proposes **7 days** of room-event history as the starting figure (long enough to answer "when did the keys last show in the den?", short enough that the map is not a diary), with **24 hours** and **30 days** printed as the neighboring choices. The owner picks the number at the wiring sitting; until he does, the wired build keeps **no history at all** (live state only, log dies with the day). Whatever number is picked is printed on the map page's face beside the log.
- **Who sees it:** the map page lives on the LAN, behind the house's own door (the Setup B LAN-only posture). It is a household surface for the consenting household — not a feed, not an export, not a product input. The family's data is never a product input (Horizon fence).

## What this packet does NOT authorize

No scanner purchase, no HA install, no token enrollment, no floor-plan drawing of the real house, and no switch-on. Each is a named sitting/decision above. This packet's job is to make those sittings short: the chain, the labels, and the fences are already decided on paper.