Поддержка MacOS (проверено в Tahoe)

docs/SCRIPTS.md

@@ -1,18 +1,20 @@
 # Скрипты репозитория
 
 Состав репозитория и назначение каждого скрипта.
-Использование `katana.py` как библиотеки (свои скрипты и анимации) — в [EXTENDING.md](EXTENDING.md).
+Использование `katana.py` как библиотеки (свои скрипты и анимации) — в [extending.md](extending.md).
 
 ## Структура репозитория
 
 ```
 .
-├── katana.py                Основная CLI-утилита управления подсветкой
-├── keymap.py                Карта «LED-индекс → физическая клавиша» (104 клавиши)
-├── katana.yaml.example      Пример YAML-конфига для команды apply
-├── analyze_pcap.py          Парсер USBPcap-захватов → лог control-трансферов
-├── probe.py                 Исследовательский зонд: чтение feature-репортов
 ├── 70-ganss-katana.rules    udev-правило: доступ к устройству без root
+├── katana.yaml.example      Пример YAML-конфига для команды apply
+├── katana.py                Основная CLI-утилита управления подсветкой
+├── misc/
+│   ├── keymap.py            Карта «LED-индекс → физическая клавиша» (104 клавиши)
+│   ├── analyze_pcap.py      Парсер USBPcap-захватов → лог control-трансферов
+│   ├── probe.py             Исследовательский зонд: чтение feature-репортов
+│   └── iokit_probe.py       Диагностика открытия HID на macOS (код IOReturn)
 ├── tests/                   Офлайн-тесты (без железа)
 ├── docs/                    Документация (см. README.md)
 └── raw-data/
@@ -29,7 +31,7 @@
 ```
 
 Печатает подтверждённую карту, список слепых слотов (39 шт — резерв прошивки, ни к какому LED не подключены), непроидентифицированные индексы и таблицу алиасов клавиш (`KEY_SYMBOL_ALIASES`).
-Методика картирования и открытые вопросы — в [PROTOCOL.md](PROTOCOL.md) (раздел «Карта клавиш»).
+Методика картирования и открытые вопросы — в [protocol.md](protocol.md) (раздел «Карта клавиш»).
 
 ## analyze_pcap.py
 
@@ -41,19 +43,34 @@
 ```
 
 Без второго аргумента пишет `/tmp/tx_log.txt`.
-Формат строк и методика снятия захватов — в [RAW-DATA.md](RAW-DATA.md).
+Формат строк и методика снятия захватов — в [raw-data.md](raw-data.md).
 
-## probe.py
+## misc/probe.py
 
 Исследовательский зонд времён начала реверса: перебирает report id и читает feature-репорты (только GET, состояние клавиатуры не меняет).
 Полезен как минимальный пример hidraw-транспорта:
 
 ```
-./probe.py [hidrawN]
+./misc/probe.py [hidrawN]
 ```
 
 Без аргумента находит все hidraw-узлы клавиатуры сам.
 
+## misc/iokit_probe.py
+
+Диагностика macOS-only: открывает HID-сервис клавиатуры через IOKit напрямую
+(ctypes, сторонних библиотек не нужно) и печатает точный код `IOReturn` от
+`IOHIDDeviceOpen`. Полезен, когда katana.py сообщает только «open failed»:
+
+```
+.venv/bin/python misc/iokit_probe.py
+```
+
+Интерпретация результата: `0x00000000` — права есть (проблема в софте),
+`0xE00002C1` — нет разрешения «Input Monitoring»,
+`0xE00002C5` (`kIOReturnExclusiveAccess`) — устройство захвачено монопольно
+(типичный случай — Karabiner-Elements).
+
 ## tests/
 
 Офлайн-тесты (железо не нужно):
@@ -63,6 +80,7 @@ python3 tests/test_macro.py      # макросы, remap-действия, св
 python3 tests/test_apply.py      # apply: YAML-конфиг → argv команд
 python3 tests/test_parsers.py    # парсеры, payload, ACK, keymap
 python3 tests/test_cli.py        # команды CLI на подменном устройстве
+python3 tests/test_transport.py  # выбор транспорта Linux/macOS, IOKit-обмен
 ```
 
 `test_macro.py` — блоб, собранный из вендорских XML, сверяется побайтово с дампом macros-create, плюс разбор токенов, round-trip XML, hotkey/remap-действия и сверка с дампами keybind-editor/keybind-hotkeys/keybind-multimedia.