Add README

What Loki is, how the BLE chaff works (decoy identities, randomized MACs,
swarm cycling, timing jitter), modes (stealth/medium/storm), hardware,
build/flash, and scope/ethics.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

README.md

@@ -0,0 +1,52 @@
+# Loki — BLE Chaff
+
+**A BLE countermeasure that floods the air with realistic decoy Bluetooth devices, so passive scanners can't pick your real device out of the noise.**
+
+Loki broadcasts a rotating crowd of fake-but-plausible BLE advertisements — randomized MACs, cycling identities, and natural timing variation. To a passive surveillance scanner it looks like a shifting crowd of ordinary phones and wearables walking by. Your actual device's signature gets buried in decoys.
+
+> Part of the **Gwaith Dantir** counter-surveillance toolkit. Where [Dantir](https://git.djeditech.com/djedi/dantir) *detects* surveillance gear, Loki *defends* against the passive device-fingerprinting side of it.
+
+## Why
+
+Passive BLE scanners fingerprint and track people by the Bluetooth their devices constantly emit — retail analytics (RetailNext, ShopperTrak), and increasingly law-enforcement/ALPR add-ons that correlate device signatures to vehicles and identities. You can't easily stop your phone from advertising. So Loki inverts the problem: instead of going silent, it makes the dataset worthless by drowning your real signature in plausible decoys. **Poison the data, not the device.**
+
+## How it works
+
+- **Decoy identities** — 24 realistic device profiles with verified Bluetooth-SIG company IDs and real protocol shapes (Apple Continuity *Nearby Info* + *Proximity Pairing*, Samsung continuity payloads), so each decoy reads as a genuine nearby device.
+- **Randomized MACs** — every identity rotates its address; per-broadcast auth bytes are randomized for realism.
+- **Identity cycling + swarm** — fast-cycles through shuffled profiles, multiple per scan window, so the "crowd" is always changing.
+- **Timing jitter** — smoothed (Perlin-style) random dwell/gap so the cadence looks organic, not machine-generated.
+
+## Modes
+
+Cycle with the **BOOT button** (long-press); the LED blinks the mode number. Setting persists across reboots.
+
+| Mode | Profiles | Feel |
+|------|----------|------|
+| **STEALTH** | 6, slow | looks like a few normal phones nearby |
+| **MEDIUM** | 24, moderate | general-purpose chaff |
+| **STORM** | 24, fastest | maximum tracker confusion |
+
+## Hardware
+
+- **ESP32-C3 Super Mini** (onboard blue LED on GPIO8 active-low, BOOT button GPIO9)
+- USB-C power (any battery/power bank for portable use)
+
+## Build & flash
+
+```bash
+# PlatformIO
+pio run -t upload
+```
+Framework: Arduino + NimBLE 1.4.x (ESP-IDF 4.4.x for C3 BLE).
+
+## Scope & ethics
+
+Loki is a **defensive, personal-privacy** tool. It emits its own decoy advertisements — it does **not** jam, deauth, flood, or interfere with other devices' communications, and it transmits nothing about you. It adds plausible noise to the public BLE namespace, the same namespace anyone is free to advertise on. Use it on yourself, in your own space, to resist passive tracking. Check your local radio regulations.
+
+## License
+
+See [LICENSE](LICENSE).
+
+---
+*"Loki" = the trickster. The chaff that makes the watchers chase ghosts.*