# Phase 1: Matrix QA & Polish — Context

**Gathered:** 2026-04-02
**Status:** Ready for planning

<domain>
## Phase Boundary

Переработать и довести Matrix адаптер до уровня "приемлемо работает" как Telegram:
- Переход с DM-first на Space+rooms архитектуру
- Убрать реакции как механизм подтверждения — заменить текстовыми командами
- Реализовать все команды управления (`!new`, `!chats`, `!rename`, `!archive`, `!skills`, `!soul`, `!safety`, `!settings`)
- Подтвердить работу ручным тестированием (бот уже запускался)

Новые возможности (коннекторы, E2EE, Space discovery) — вне scope.

</domain>

<decisions>
## Implementation Decisions

### Архитектура: Space + rooms

- **D-01:** Space+rooms — единственная поддерживаемая модель. DM-first убрать.
- **D-02:** При первом invite бот создаёт Space `Lambda — {display_name}`, внутри — первую комнату `Чат 1`. Приглашает пользователя.
- **D-03:** `!new [name]` создаёт новую комнату внутри Space пользователя, приглашает его туда.
- **D-04:** `!archive` выводит комнату из Space (не удаляет).
- **D-05:** Маппинг `room_id → space_id` + `room_id → chat_id` хранится в SQLite через `adapter/matrix/store.py`.

### Подтверждение действий

- **D-06:** Реакции (`👍`/`❌`) — убрать полностью. `OutgoingUI` с кнопками рендерится как текст + `!yes` / `!no`.
- **D-07:** Когда агент запрашивает подтверждение, бот пишет текстовое сообщение с описанием и подсказкой: `Ответьте !yes для подтверждения или !no для отмены.`
- **D-08:** `!yes` / `!no` работают в текущей комнате. Состояние ожидания подтверждения хранится per (user_id, room_id).

### Команды

- **D-09:** Все команды работают из любой комнаты Space — нет выделенной комнаты «Настройки».
- **D-10:** Команды: `!new [name]`, `!chats`, `!rename <name>`, `!archive`, `!skills`, `!soul`, `!safety`, `!settings`, `!yes`, `!no`.
- **D-11:** `!start` — не нужен, онбординг через invite flow.

### Настройки (Вариант D)

- **D-12:** `!settings` — read-only дашборд: одно сообщение со статусом всего (скиллы, soul, safety, активные чаты). Ничего не меняет.
- **D-13:** Изменения через субкоманды:
  - `!skills` — показать список; `!skill on/off <name>` — переключить
  - `!soul` — показать профиль; `!soul name/style/priority/reset <value>` — изменить
  - `!safety` — показать статус; `!safety on/off <action>` — переключить
- **D-14:** Каждая команда без аргументов (`!skills`, `!soul`, `!safety`) выводит текущее состояние + подсказку как менять.

### Claude's Discretion

- Формат текста в Matrix (plain text vs markdown) — на усмотрение, Matrix клиенты рендерят markdown
- Структура invite-сообщения в новом Space — на усмотрение, главное: приветствие + список команд
- Обработка ошибок matrix-nio (room_create fail, join fail) — логировать + ответить пользователю

</decisions>

<canonical_refs>
## Canonical References

**Downstream agents MUST read these before planning or implementing.**

### Архитектурные документы
- `docs/matrix-prototype.md` — описание Space+rooms структуры, FSM состояний, команд (ВНИМАНИЕ: секция "Реакции как действия" устарела — заменена D-06..D-08)
- `bot-examples/matrix_bot_rooms.py` — reference реализация Space+rooms на matrix-nio (другая архитектура поверх, но паттерны работы с Space/rooms актуальны)

### Текущая реализация (требует переработки)
- `adapter/matrix/bot.py` — точка входа, `send_outgoing` (реакции убрать), `MatrixBot`, `MatrixRuntime`
- `adapter/matrix/handlers/auth.py` — `handle_invite` (сейчас создаёт DM без Space — переписать)
- `adapter/matrix/handlers/chat.py` — `make_handle_new_chat` (сейчас не добавляет комнату в Space — переписать)
- `adapter/matrix/store.py` — хранилище метаданных комнат (расширить для space_id)
- `adapter/matrix/room_router.py` — маршрутизация room_id → chat_id

### Протокол
- `core/protocol.py` — `IncomingCommand`, `OutgoingUI`, `OutgoingMessage` — типы не менять
- `adapter/matrix/converter.py` — маппинг nio events → IncomingEvent

</canonical_refs>

<code_context>
## Existing Code Insights

### Reusable Assets
- `adapter/matrix/store.py`: `get_room_meta` / `set_room_meta` — переиспользовать, добавить поля `space_id`
- `adapter/matrix/room_router.py`: `resolve_chat_id` — переиспользовать, возможно расширить
- `core/handlers/`: все обработчики команд уже зарегистрированы через `register_all`
- `adapter/matrix/handlers/settings.py`, `confirm.py` — проверить, возможно переиспользовать/обновить

### Known Bugs (из анализа кода)
- `auth.py:27`: `"chat_id": "C1"` захардкожен — у каждого нового пользователя будет коллизия
- `bot.py:167`: `_button_action_to_reaction` — убрать целиком
- `handlers/chat.py:50`: `room_create` не добавляет комнату в Space (`space_id` не указан)

### Integration Points
- `AsyncClient.room_create(space=True)` — создание Space через matrix-nio
- `AsyncClient.room_put_state(room_id, "m.space.child", ...)` — добавление комнаты в Space
- Оба метода есть в `bot-examples/matrix_bot_rooms.py`

</code_context>

<specifics>
## Specific Ideas

- Подтверждение: бот пишет `Ответьте !yes для подтверждения или !no для отмены.` — явно, без двусмысленности
- `!settings` — один дашборд-блок, не несколько сообщений

</specifics>

<deferred>
## Deferred Ideas

- Комната «Настройки» как отдельная закреплённая комната — решили не делать в Phase 1
- E2EE / python-olm — инфраструктурный трек, вне scope
- Space discovery (бот находит существующий Space при повторном invite) — Phase 2+
- Attachment handling (m.file, m.image, m.audio) — Phase 2+

</deferred>

---

*Phase: 01-matrix-qa-polish*
*Context gathered: 2026-04-02*