From ac3e567db8f23859b64d19fcd95d4041225c302c Mon Sep 17 00:00:00 2001
From: Ryan Malloy <ryan@supported.systems>
Date: Fri, 6 Feb 2026 20:54:38 -0700
Subject: [PATCH] Improve README: clean header, add RE/discovery section

---
 README.md | 44 ++++++++++++++++++++++++++++++++++----------
 1 file changed, 34 insertions(+), 10 deletions(-)

diff --git a/README.md b/README.md
index 306f077..9639589 100644
--- a/README.md
+++ b/README.md
@@ -1,13 +1,4 @@
-<p align="center">
-  <pre>
-               ╔╗  ╔╗         ╔╗               ╔╗  ╔╗
-               ║║  ║║         ║║      ╔╗       ║║  ║║
- ╔╗╔╗╔══╗╔══╗  ║╚═╗║║ ╔╗ ╔╗╔══╝║╔══╗╔═╝║╔══╗╔══╝║╔═╝║╔══╗
- ║╚╝║║╔═╝║╔╗║  ║╔╗║║║ ║║ ║║║╔══╝║╔╗║║╔╗║║╔╗║║╔╗║║╔╗║║╔╗║
- ║║║║║╚═╗║╚╝╚╗ ║╚╝║║╚╗║╚═╝║║╚══╗║╚╝║║╚╝║║╚╝║║╚╝║║╚╝║║║║║
- ╚╩╩╝╚══╝╚═══╝ ╚══╝╚═╝╚═══╝╚═══╝╚══╝╚══╝╚══╝╚══╝╚══╝╚╝╚╝
-  </pre>
-</p>
+<h1 align="center">mcbluetooth</h1>
 
 <p align="center">
   <strong>Give LLMs control of your Linux Bluetooth stack</strong>
@@ -41,6 +32,9 @@
 - **Audio Intelligence** — PipeWire/PulseAudio integration for seamless audio control
 - **HFP Audio Gateway** — Act as a phone for headset testing and call simulation
 - **OBEX Profiles** — File transfer, phonebook access, and message access
+- **BLE Discovery** — Enumerate GATT services, read characteristics, decode sensor data
+- **Device Fingerprinting** — Identify devices by their advertised services and behaviors
+- **Security Research** — Test pairing modes, analyze HCI traffic, probe unknown devices
 
 ## Example Conversation
 
@@ -65,6 +59,36 @@ I found your Bose headphones "Bombay". Connecting now...
   to set them as the default audio output?
 ```
 
+## Discovery & Reverse Engineering
+
+mcbluetooth shines when exploring unknown Bluetooth devices:
+
+```
+You: Scan for BLE devices and show me what services that fitness tracker advertises
+
+Claude: I found a device "Mi Band 7" at E4:12:5C:AA:BB:CC. Let me enumerate its GATT services...
+
+The device exposes:
+- 0x180D Heart Rate Service (standard)
+- 0x180F Battery Service (standard)
+- 0xFEE0 Xiaomi proprietary service (likely firmware/auth)
+- 0xFEE1 Xiaomi proprietary service (likely sensor data)
+
+The heart rate characteristic (0x2A37) supports notifications.
+Want me to subscribe and capture some readings?
+```
+
+**Common workflows:**
+
+| Use Case | What Claude Can Do |
+|----------|-------------------|
+| **BLE Sensor Reverse Engineering** | Enumerate services, read/write characteristics, decode data formats |
+| **Device Fingerprinting** | Identify manufacturer, capabilities, and protocols from advertisements |
+| **Protocol Analysis** | Capture HCI traffic with btmon, analyze pairing handshakes |
+| **Pairing Mode Testing** | Test all 4 SSP modes (Just Works, Numeric, Passkey, Legacy PIN) |
+| **HFP Headset Testing** | Simulate phone calls, send AT commands, test audio routing |
+| **Service Discovery** | Find hidden services, probe for undocumented characteristics |
+
 ## Installation
 
 ### Using uvx (recommended)