# AGENTS.md — atxpi (diy/arm)

> Aгент-инструкции для работы с проектом. Загружаются автоматически, когда Hermes работает внутри репозитория.

## Что это

**atxpi** — управляющая плоскость для сервера на базе Raspberry Pi:
**питание** (ATX) + **RS232-консоль** + статус. По сути компактный «бедняцкий IPMI».
Репо — на внутреннем git-хостинге (ветка `main`). Адрес/хост в публичном репо не указываем.

## Принятые решения (утверждено)

| # | Решение |
|---|---|
| 1 | **Имя пакета/системы — `atxpi`** |
| 2 | Интерфейсы: **браузерный web-UI** + **CLI-инструменты** + **MCP-сервер для агентов** |
| 3 | Всё **лёгкое под Raspberry Pi 2B** (armv7, 1 ГБ): без node/сборки, без тяжёлых БД |
| 4 | Питание — на базе существующего модуля **`atxctl`** (I2C-expander HAT: PWRBTN/RESET/статус) |
| 5 | Консоль — `ttyUSB0` (PL2303, RS232-TTL), поверх — **браузерный терминал + CLI + MCP** |
| 6 | **Никаких реальных проверок питания на «живых» серверах** (продакшн). Только стенд/макет. `ATXPI_DRIVER=mock` для разработки |
| 7 | Доступ: локально через **SSH (key-only)**; удалённо — через VPN/Tailscale. Управляющая плоскость не светится в интернет |
| 8 | **Временные файлы — только в `atxpi/tmp/`** (НЕ в `/tmp` корня ФС), чтобы агент не запрашивал разрешений на системные пути |
| 9 | **Распространение: нативно** (система + systemd), **один сервис** `atxpi.service` = FastAPI (REST + WebSocket-консоль + MCP-HTTP + статика). **Без Docker** |
| 10 | Установка — **one-shot `install.sh`** (`curl \| sudo bash`), идемпотентный; обновление — `deploy/update.sh` |
| 11 | **MCP для агентов — HTTP-эндпоинт** на самом устройстве (`/mcp`), Hermes подключается по URL+`Bearer` |
| 12 | Раскладка: `/opt/arm` (чекаут репо), `/opt/arm/atxpi/venv`, `/etc/atxpi/atxpi.env` (0600, генерится, не в git), сервис-юзер `atxpi` |

## Структура репозитория

```
arm/
├── AGENTS.md               # этот файл
├── .gitignore
├── atxctl/                 # питание: I2C HAT (существующий модуль)
├── lcd/                    # статусный OLED 52pi (существующий)
├── ups/                    # защита батареи, INA219 (существующий)
└── atxpi/                  # НОВЫЙ управляющий слой
    ├── core/               # hardware.py (абстракция+драйверы), mock.py, power.py, console.py
    ├── cli/atxpi           # CLI: status/on/off/reset/cycle/console
    ├── webui/              # (далее) FastAPI: REST + WebSocket-консоль + статика
    ├── mcp/                # (далее) MCP-сервер (stdio) для агентов
    ├── deploy/             # (далее) systemd-юниты + setup.sh
    ├── tmp/                # временные файлы (в gitignore)
    └── README.md
```

## Конвенции и инструменты

- **CLI-вызов:** `cd atxpi && ATXPI_DRIVER=mock ./cli/atxpi status`
- **Драйвер:** `ATXPI_DRIVER=real` (дефолт, железо) | `mock` (разработка). Реальный: питание = `atxctl/main.py`, консоль = `pyserial` на `SERIAL_PORT` (`/dev/ttyUSB0`, 115200).
- **Mock-состояние питания** хранится в `atxpi/tmp/atxpi_mock_power.json` (не в `/tmp`).
- **SSH-ключ:** `~/.ssh/id_ed25519` (в Gitea назван `Toros`), пользователь `eka`.
- **Python:** stdlib для core/CLI; полный набор (`pyserial`, `fastapi`, `uvicorn`, `mcp`) — в `atxpi/requirements.txt`, ставится в venv на устройстве, **не на HP Omen**.
- **Коммиты:** conventional (`feat:`, `fix:`, `chore:`), по чекпоинтам.

## Важно (безопасность)

- Живой сервер (продакшн) — **только чтение кода**, никаких команд питания.
- Питание/сброс — деструктивны: логировать действие, требовать аутентификацию.
- Управляющая плоскость биндится на VPN/loopback, `0.0.0.0` запрещён.
- Никаких `rm`/записей в `/tmp` корня ФС и вне рабочего каталога.

## Статус

- ✅ Шаг ①: core + CLI + mock (работает на stdlib, проверено на mock)
- ⬜ Шаг ②: консоль на `pyserial`
- ⬜ Шаг ③: web-UI (FastAPI + REST + WS-консоль)
- ⬜ Шаг ④: MCP-сервер для агентов
- ⬜ Шаг ⑤: systemd + деплой на Pi 2B