# 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.
