# apply — применение YAML-конфига

Применяет конфиг из YAML-файла: вместо длинных команд — один файл со всеми настройками.
Файл можно хранить в любом месте (например `~/.config/katana.yaml`), в репозитории лежит пример [katana.yaml.example](../../katana.yaml.example).

```
./katana.py apply ~/my-katana.yaml        # применить конфиг
./katana.py apply katana.yaml.example     # применить пример из репозитория
```

Зависимость: PyYAML (`pip install pyyaml`, см. [install.md](../install.md)).

## Порядок применения и сохранение

Секции применяются всегда в одном порядке, независимо от их порядка в файле:

1. `remap` — таблица переназначений (04 11), save;
2. `paint` — per-key раскраска, включает режим 0x80, save;
3. `lighting` — финальный режим подсветки (mode/off/default), перекрывает 0x80 от paint, save;
4. `raw` — произвольный payload (для экспериментов);
5. `macros` — ВСЕ слоты одним блобом (04 19), save;
6. `remap` и `lighting` — **повторно** (если секции были в конфиге), со save.

**Модель сохранения** (проверена на железе): каждая область прошивки (bind-таблица, paint-таблица, режим, макросы) сохраняется во флеш **только своим собственным save** (04 f0) — чужой save чужую область ни сохраняет, ни затирает. Поэтому в apply каждая секция несёт свой save.

**Почему remap и lighting повторяются после макросов:** запись макросов (04 19) сбивает bind-таблицу и режим подсветки **в RAM** (во флеше они остаются). Повторная отправка восстанавливает их в RAM и заодно фиксирует save'ом.

**Почему все макросы одним блобом:** каждый вызов `macro set` обнуляет прочие слоты — несколько макросов нужно писать за одну транзакцию (apply так и делает).

Ключ `save` в секциях конфига **не поддерживается** — apply управляет save'ами сам (написанный по ошибке `save: false` отклоняется как неизвестный ключ).

Каждая секция прогоняется через соответствующую команду CLI — валидация значений та же самая.
Перед каждым шагом печатается `apply [...] ...`, после — итоговый список применённого.

Команды `keys`, `scan`, `reset` в конфиге не нужны: это диагностика, а не состояние.

## Секции

### `macros` — содержимое макросов (см. [macro.md](macro.md))

Все слоты пишутся **одним блобом** (пропуски между номерами — пустые слоты).
Ключ — номер слота 0..99, значение — `tokens` (список) или `xml` (файл).

```yaml
macros:
  0:
    tokens: ["+lctrl", "a@50", "-lctrl"]   # Ctrl+A
  1:
    xml: raw-data/katana-v1/test.xml
```

### `remap` — переназначение клавиш (см. [remap.md](remap.md))

```yaml
remap:
  keys:
    caps: macro0       # КЛЮЧ: ДЕЙСТВИЕ — те же, что у remap --key
    menu: meta+e
  # clear: true        # вместо keys: сбросить ВСЕ переназначения
```

### `paint` — раскраска клавиш (см. [paint.md](paint.md))

```yaml
paint:
  all: black           # база (или black: true / keep: true)
  keys:
    esc: "ff0000"      # КЛЮЧ: ЦВЕТ
  wasd: dodgerblue     # shorthand-алиасы CLI: wasd, numpad, alpha, punct, digits, arrows
  rows:
    1: "202020"        # ряды 1..6
  brightness: 15
```

### `lighting` — режим подсветки (см. [color-modes.md](../color-modes.md))

`mode` — имя или номер 1..19, а также `off` и `default` (применяются как команды `off`/`default`).

```yaml
lighting:
  mode: static
  color: red
  brightness: 15       # 1..15
  # speed: 5           # 2..15
  # rainbow: true      # статика: спектр вместо color
  # direction: north-south
```

### `raw` — сырой payload (см. [raw.md](raw.md))

```yaml
raw: "80 00 ... aa 55"   # hex-строка или список строк
```

## Валидация

- Неизвестные секции и неизвестные ключи внутри секций отклоняются с указанием опечатки.
- `macros`: слот должен иметь либо `tokens`, либо `xml` (не оба и не ни одного).
- Значения проверяются тем же парсером, что и CLI-команды (`parse_color`, `parse_mode`, диапазоны).

Офлайн-тесты — `tests/test_apply.py` (пример конфига разбирается и превращается в валидные argv).