docs: add intelligence endpoints to OpenAPI spec

Add vendor-treemap, ssid-graph, and fingerprint-clusters paths
with response schemas. Bump spec version to 0.1.4.

src/esp32_web/openapi.yaml

@@ -2,7 +2,7 @@ openapi: 3.0.3
 info:
   title: ESP32-Web API
   description: REST API for ESP32 sensor fleet management
-  version: 0.1.3
+  version: 0.1.4
   contact:
     name: ESP32-Web
 servers:
@@ -24,6 +24,8 @@ tags:
     description: Aggregate statistics
   - name: export
     description: Data export endpoints
+  - name: intelligence
+    description: Device intelligence and visualization data
 
 paths:
   /sensors:
@@ -556,6 +558,83 @@ paths:
               schema:
                 type: string
 
+  /intelligence/vendor-treemap:
+    get:
+      tags: [intelligence]
+      summary: Get vendor treemap hierarchy
+      description: Returns D3-ready hierarchy of devices grouped by type (wifi/ble) and vendor.
+      operationId: getVendorTreemap
+      responses:
+        '200':
+          description: Treemap hierarchy
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/VendorTreemap'
+
+  /intelligence/ssid-graph:
+    get:
+      tags: [intelligence]
+      summary: Get SSID social graph
+      description: >
+        Returns force-graph data with device nodes and links between devices
+        that share probed SSIDs. Requires probe data (promiscuous mode).
+      operationId: getSsidGraph
+      parameters:
+        - name: hours
+          in: query
+          schema:
+            type: integer
+            default: 24
+            minimum: 1
+          description: Time window in hours
+        - name: min_shared
+          in: query
+          schema:
+            type: integer
+            default: 1
+            minimum: 1
+          description: Minimum shared SSIDs to create a link
+        - name: limit
+          in: query
+          schema:
+            type: integer
+            default: 200
+            maximum: 500
+            minimum: 1
+          description: Max number of nodes (top by probe diversity)
+      responses:
+        '200':
+          description: Force-graph data
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/SsidGraph'
+
+  /intelligence/fingerprint-clusters:
+    get:
+      tags: [intelligence]
+      summary: Get device fingerprint clusters
+      description: >
+        Groups active devices by behavior (device type, vendor, activity level).
+        Uses rule-based clustering: low (<5), medium (5-20), high (>20) activity.
+      operationId: getFingerprintClusters
+      parameters:
+        - name: hours
+          in: query
+          schema:
+            type: integer
+            default: 24
+            minimum: 1
+          description: Time window in hours
+      responses:
+        '200':
+          description: Device clusters
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/FingerprintClusters'
+
 components:
   parameters:
     hostname:
@@ -834,3 +913,128 @@ components:
               type: integer
             hours:
               type: integer
+
+    VendorTreemap:
+      type: object
+      properties:
+        name:
+          type: string
+          example: devices
+        children:
+          type: array
+          items:
+            type: object
+            properties:
+              name:
+                type: string
+                example: ble
+              children:
+                type: array
+                items:
+                  type: object
+                  properties:
+                    name:
+                      type: string
+                      example: Apple, Inc.
+                    value:
+                      type: integer
+                      example: 42
+
+    SsidGraph:
+      type: object
+      properties:
+        nodes:
+          type: array
+          items:
+            type: object
+            properties:
+              id:
+                type: string
+                description: Device MAC address
+              device_id:
+                type: integer
+              vendor:
+                type: string
+              type:
+                type: string
+                enum: [wifi, ble]
+              ssid_count:
+                type: integer
+        links:
+          type: array
+          items:
+            type: object
+            properties:
+              source:
+                type: string
+                description: Source device MAC
+              target:
+                type: string
+                description: Target device MAC
+              shared_ssids:
+                type: array
+                items:
+                  type: string
+              weight:
+                type: integer
+        ssids:
+          type: array
+          items:
+            type: object
+            properties:
+              ssid:
+                type: string
+              device_count:
+                type: integer
+
+    FingerprintClusters:
+      type: object
+      properties:
+        clusters:
+          type: array
+          items:
+            type: object
+            properties:
+              id:
+                type: integer
+              label:
+                type: string
+                example: Apple BLE - High Activity
+              device_type:
+                type: string
+                enum: [wifi, ble]
+              vendor:
+                type: string
+              activity:
+                type: string
+                enum: [Low, Medium, High]
+              device_count:
+                type: integer
+              devices:
+                type: array
+                items:
+                  type: object
+                  properties:
+                    mac:
+                      type: string
+                    probe_count:
+                      type: integer
+                    sighting_count:
+                      type: integer
+                    avg_rssi:
+                      type: integer
+                      nullable: true
+              centroid:
+                type: object
+                properties:
+                  probe_rate:
+                    type: number
+                  sighting_rate:
+                    type: number
+                  avg_rssi:
+                    type: integer
+                    nullable: true
+        total_devices:
+          type: integer
+        total_clusters:
+          type: integer