chore: initialize K1 connector pre-production scaffold

docs/reference/CODEX_K1_MAC_LINK_PREPROD_PROMPT.md

@@ -0,0 +1,220 @@
+# Codex prompt: k1-mac-link
+
+Ты работаешь над проектом `k1-mac-link`.
+
+## Контекст
+
+Есть официальный XGRIDS / LixelKity K1, MacBook, Wi-Fi router. Linux как отдельного стенда нет. Цель - использовать K1 как black-box realtime computer vision sensor без модификации firmware и без вскрытия на первом этапе.
+
+Нужны realtime/cached данные:
+
+- point cloud / preview cloud;
+- pose / trajectory / odometry-like stream, если есть;
+- camera / panoramic preview / RGB stream, если есть;
+- device status;
+- raw packets для reverse engineering.
+
+Не нужно в runtime:
+
+- считать LAS;
+- считать LCC;
+- считать Gaussian splats;
+- менять firmware;
+- делать brute force;
+- слать random BLE writes.
+
+## Главная архитектура
+
+Официальные мануалы K1 показывают такую модель:
+
+- BLE используется для discovery/provisioning;
+- SSID/password - это реквизиты нашей Wi-Fi сети;
+- после подключения к Wi-Fi есть отдельный `data connection status`;
+- K1 умеет автономно стартовать scanning double-click кнопкой;
+- K1 пишет `map.las` как realtime point cloud output, но downsampled;
+- K1 пишет `poses.csv` как trajectory recorded during scanning;
+- K1 содержит 2 panoramic cameras и 360 deg LiDAR;
+- live camera stream наружу не доказан, его надо искать экспериментально.
+
+## Создай проект
+
+Python 3.12, macOS-first, Typer CLI.
+
+Структура:
+
+```text
+k1-mac-link/
+  README.md
+  pyproject.toml
+  docs/
+  src/k1link/
+    cli.py
+    config.py
+    logging.py
+    artifacts.py
+    ble/
+      scanner.py
+      gatt_dump.py
+      listener.py
+      provisioner.py
+    net/
+      discover.py
+      ports.py
+      capture.py
+      mdns.py
+      tshark.py
+    analysis/
+      pcap_summary.py
+      flow_classifier.py
+      payload_extract.py
+      payload_fingerprint.py
+      protocol_diff.py
+      pointcloud_probe.py
+      video_probe.py
+      timeline.py
+    decode/
+      pointcloud.py
+      pose.py
+      video.py
+      status.py
+    cache/
+      writer.py
+      manifest.py
+      raw_stream.py
+    export/
+      ply.py
+      pcd.py
+      npz.py
+      frames.py
+  tests/
+```
+
+## Dependencies
+
+Use:
+
+```text
+bleak
+typer
+rich
+pydantic
+pydantic-settings
+loguru
+pyshark
+scapy
+construct
+numpy
+pandas
+opencv-python
+open3d
+pillow
+zeroconf
+ifaddr
+psutil
+pytest
+pytest-asyncio
+ruff
+mypy
+```
+
+## CLI commands
+
+Implement:
+
+```bash
+k1link doctor
+k1link ble scan --duration 30 --out captures/ble_scan.json
+k1link ble gatt-dump --device <macos_uuid> --out captures/gatt_dump.json
+k1link ble listen --device <macos_uuid> --duration 120 --out captures/ble_notifications.jsonl
+k1link net discover --subnet 192.168.1.0/24 --out captures/net_discover.json
+k1link net ports --ip <K1_IP> --out captures/ports.json
+k1link net capture --iface en0 --host <K1_IP> --out captures/session.pcap
+k1link analyze summarize --pcap captures/session.pcap --out captures/session_summary.json
+k1link analyze extract-flows --pcap captures/session.pcap --out-dir captures/flows
+k1link analyze fingerprint --flows captures/flows --out captures/fingerprint.json
+k1link analyze pointcloud-probe --flows captures/flows --out-dir captures/pointcloud_candidates
+k1link analyze video-probe --flows captures/flows --out-dir captures/video_candidates
+```
+
+## Safety rules
+
+Allowed by default:
+
+- BLE scan;
+- GATT discovery;
+- read characteristics;
+- notifications;
+- network discovery;
+- port scanning of owned device;
+- tcpdump capture;
+- pcap analysis.
+
+Forbidden by default:
+
+- BLE write;
+- random fuzzing;
+- brute force;
+- firmware upload;
+- deleting/modifying K1 files;
+- SSH/ADB login attempts.
+
+Any BLE write must require:
+
+```bash
+--i-understand-this-writes-to-device
+```
+
+Provisioner stays NotImplemented until a known payload profile is manually added.
+
+## Outputs
+
+Every session creates:
+
+```text
+session_manifest.json
+notes.md
+captures/*.pcap
+captures/*.json
+flows/*.bin
+flows/*.jsonl
+analysis/*.json
+decoded/pointcloud/*
+decoded/video/*
+decoded/pose/*
+```
+
+Raw captures are never deleted.
+
+## Implement pointcloud probe
+
+Try:
+
+- float32 little-endian XYZ;
+- offsets 0..128;
+- strides 12, 16, 20, 24, 28, 32, 40, 48;
+- scaled int16/int32 fallback;
+- score finite ratio, coordinate range, variance, temporal continuity;
+- export PLY/NPZ for top candidates.
+
+## Implement video probe
+
+Detect/extract:
+
+- JPEG FF D8 FF ... FF D9;
+- PNG signature;
+- H264/H265 Annex B;
+- MP4 ftyp/moof/mdat;
+- RTSP/RTP;
+- MJPEG;
+- WebSocket binary large frames.
+
+Try ffmpeg/OpenCV extraction where possible.
+
+## README must include
+
+- macOS setup;
+- Wireshark ChmodBPF note;
+- Bluetooth permission note;
+- Bleak macOS UUID caveat;
+- K1 lab network setup;
+- experiment flow: idle capture, button scan capture, app scan capture, camera perturbation, point cloud perturbation.

docs/reference/README.md

@@ -0,0 +1,15 @@
+# Reference inputs
+
+These files are immutable copies of the user-supplied pre-production material.
+They are retained as inputs, not treated as verified specifications.
+
+| File | SHA-256 | Role |
+|---|---|---|
+| `CODEX_K1_MAC_LINK_PREPROD_PROMPT.md` | `f24537119bd76f76d1914ca7f34a6736d8c5d3b6d19ead6d0ae8a0e5966c9770` | Requested project shape and CLI scope |
+| `XGRIDS_Lixel_K1_PreProduction_Bible.md` | `22ea9d0dc6f5a623ba26d6f08108a905170db08112e0531a1d80bddd6101689c` | OSINT dossier, hypotheses, experiments and long-form design |
+
+Important contextual correction: the actual stand has no LixelGO and no mobile
+device. All experiments in the source documents that require an app or a
+reference app session are unavailable. The active plan is therefore defined by
+`docs/01_IMPLEMENTATION_PLAN.md`.
+