feat(*): init

docs/agents/kickoff.md

@@ -0,0 +1,116 @@
+$impeccable делаем Firefly UI: новый интерфейс к моему Firefly III. Это отдельный SvelteKit-клиент поверх его API, узнаваемый Firefly по раскладке, но красивый, быстрый и целиком управляемый с клавиатуры. К утру он должен работать на https://firefly.hhhhh.dev, на тех же адресах, что и сам Firefly. Пользователь один, я: power user, люблю vim-навигацию.
+
+Сначала 15 минут со мной, потом я сплю, дальше ты сам до утра.
+
+## Старт, пока я рядом
+
+1. Прочитай код Firefly (ниже, что и где), без скринов и без запуска. Составь для себя карту: страницы, что на каждой, какие эндпоинты API за ней стоят, чего в API нет.
+2. `impeccable init` с интервью, жёстко, минут на 15. Спрашивай про вкус, плотность, что меня бесит в Firefly и что я в нём люблю. Ответы в PRODUCT.md и `docs/agents/decisions.md`.
+3. Один раунд вопросов по «Что нужно от меня» (ниже), до 4 штук, у каждого дефолт. Не отвечу за 10 минут: бери дефолты и пиши их в decisions.md с пометкой «допущение».
+4. Дальше всё без меня.
+
+## Что это за продукт
+
+Мне нравится сама система Firefly III и его раскладка, к ней я привык. Пользоваться им невозможно: таблицы рендерятся криво, отчёты и способ их получения ужасны, поиск странный, редактор транзакций глючит, с клавиатуры не работает почти ничего. В v6.7 автор выкинул старый интерфейс (v1 на Twig и v2 на Alpine) и оставил только новый v3 (Blade, Alpine, AdminLTE 4). Сам он пишет, что v3 сырой (`changelog.md`, v6.7.1, Known issues).
+
+Нужно надмножество обычного Firefly. Всё, что он умеет, плюс то, чего ему не хватает. Это не «привет, Claude, сделай финансовое приложение». Человек, привыкший к Firefly, открывает его и сразу узнаёт: то же меню, те же страницы, те же блоки на тех же местах. Только сделано хорошо.
+
+Как работать над каждой страницей:
+1. Посмотри, как страница выглядела в v1 и как выглядит в v3: скрин со стенда, шаблон и контроллер.
+2. Пойми, что автор, вероятно, хотел этим сказать. Одна строка на страницу в `docs/agents/pages.md`.
+3. Сделай нашу версию. Раскладка и места элементов как в Firefly, чтобы рука находила. Таблицы, формы, навигация и клавиатура сделаны заново и хорошо.
+4. Где можно выпендриться, выпендрись: дашборд, страницы счетов, бюджетов, категорий, отчёты, всё со статистикой и графиками. Выпендрёж не должен ломать узнаваемость.
+5. Скрин нашей версии рядом со скрином v1 в `docs/agents/demos/<страница>/`.
+
+## Что читать
+
+- **Исходники Firefly III**: `~/projects/contributions/firefly-iii`. Если на машине его нет: `git clone https://github.com/firefly-iii/firefly-iii ~/projects/contributions/firefly-iii`. Это чужой репо, ничего в нём не меняй и рабочую копию не переключай. Старые версии читай через `git show <тег>:<путь>` или отдельный `git worktree` во временном каталоге.
+  - `v6.6.6`: последний релиз со старыми интерфейсами. v1 лежит в `resources/views/*.twig` (кроме `v2/`), v2 в `resources/views/v2` и `resources/assets/v2`. Отсюда раскладка, меню, состав страниц, формы.
+  - Последний тег (сейчас `v6.7.9`): v3 в `resources/views`, `resources/assets/v3`. Отсюда текущие возможности и новые экраны.
+  - `routes/web.php`: адреса страниц. Наши экраны живут по тем же путям.
+  - `routes/api.php`, `app/Api/V1`: что умеет API. Типы генерируй из OpenAPI-спеки (`https://github.com/firefly-iii/api-docs`, yaml), руками их не пиши.
+  - `changelog.md` и issues на GitHub с меткой про layout: что у людей болит в v3.
+- **Firefly Pico** (`https://github.com/cioraneanu/firefly-pico`): сторонний фронт на Nuxt поверх того же API. Бери только грабли API, которые они уже нашли. Вид оттуда не брать.
+- **claddcn-svelte** (`https://git.kotikot.com/lib/claddcn-svelte`): тема cladd для shadcn-svelte, уже поставлена в этот репо (`src/routes/claddcn.css`, `#lib/components/ui`). README там: утилиты `cladd-*`, акценты, Surface.
+- **Деплой**: `~/projects/infra/komodo` (если нет: `git clone git@git.kotikot.com:infra/komodo.git`).
+  - `fleet/personal/personal-main/fireflyiii/`: стек Firefly (`stack.toml`, `site.caddy`). Firefly на `:latest` с `auto_update`, так и остаётся.
+  - `scripts/new-app-stack.py` и `docs/architecture.md`, раздел «Деплой приложений»: как завести стек приложения из шаблона.
+  - `fleet/personal/personal-main/lodge/`: живой образец такого стека.
+
+Исследуй параллельными субагентами, быстро.
+
+## Устройство
+
+- SPA на SvelteKit (`adapter-static`), раздаётся `serve.ts` на Bun, как задал шаблон. Своего бэкенда нет, всё через `/api/v1` Firefly.
+- **Авторизация через Firefly.** Вход, MFA и выход остаются его страницами. После входа Firefly ставит куку `laravel_token` (`CreateFreshApiToken` в `bootstrap/app.php`), и API принимает её с CSRF-заголовком. Так ходит и сам v3: `resources/assets/v3/js/boot/axios.js`. Для этого клиент обязан жить на том же домене. На 401 полная перезагрузка на `/login`, после входа возврат туда, где был.
+- **Риск, проверить первым:** кука выдаётся только на web-ответах Laravel, а наши страницы отдаёт не Laravel. Узнай, сколько она живёт и как её продлевать, пока вкладка открыта. Решение и проверку запиши в decisions.md.
+- **Пути.** Каждый экран живёт по тому же адресу, что в Firefly (`/accounts/asset`, `/transactions/show/12`, `/budgets`). Закладки и ссылки продолжают работать. Всё, чего у нас нет, отдаёт сам Firefly: `/api`, `/oauth`, `/login`, `/profile`, `/two-factor`, cron-URL, автоматизации, POST-запросы его форм. Переход из клиента на такую страницу делается полной загрузкой. Нужен переключатель «открыть эту страницу в старом интерфейсе» (клавиша плюс пункт палитры), который работает на любом адресе. Маршрутизация живёт в `site.caddy` стека `fireflyiii`. Отказ от нового интерфейса это откат одного файла, опиши его в report.md.
+- Firefly обновляется сам, поэтому клиент не должен молча ломаться. Типы из спеки и `make smoke`: прогон основных запросов против локального `fireflyiii/core:latest`. Версию API клиент читает из `/api/v1/about`. Если она уехала вперёд, показывает это одной строкой в подвале.
+- В dev Vite проксирует на локальный Firefly всё, что не наше, чтобы вход и куки работали как на проде (`vite.config.ts`, `.env`).
+- SvelteKit здесь третий: алиас `#lib` (subpath imports в `package.json`), а не `$lib`. `components.json` уже переведён.
+
+## Стенд для отсмотра
+
+Поднимай на этой машине в докере. Имя compose-проекта `ffui-*`, порты случайные высокие, трогать только своё.
+- `fireflyiii/core:version-6.6.6` с `FIREFLY_III_LAYOUT=v1` (для сравнения можно и `v2`).
+- `fireflyiii/core:latest`: на нём v3 и на нём же разрабатывается клиент.
+- База у каждого своя: sqlite или mariadb, как быстрее заведётся.
+- Одни и те же демо-данные в обоих через `scripts/seed` по API. Это отдельный скрипт, моков во фронте нет. Данные правдоподобные: 6–12 месяцев истории; счета (основные, сберегательные, кредитка, кредит), расходные и доходные; сплиты, переводы, две-три валюты, бюджеты с лимитами, категории, теги, подписки (bills), копилки, группы объектов, повторяющиеся транзакции и пара правил. Снос данных тем же скриптом.
+- Эталонные скрины v1 и v3 каждой страницы: `docs/agents/reference/<страница>/{v1,v3}.png`.
+
+## Что должно быть к утру, по приоритету
+
+Объём не режь, делай всё по списку. Порядок нужен только на случай, если время кончится: тогда режь снизу. Первый пункт доведи до конца.
+
+1. **Каркас на проде.** Узнаваемая раскладка Firefly v1 (боковое меню того же состава и порядка, шапка, хлебные крошки, выбор периода как у Firefly). Вход через Firefly. Палитра команд (`⌘K` / `Ctrl+K`) по страницам, счетам, бюджетам, категориям, тегам и действиям. Vim-навигация: `j/k` по строкам, `gg/G`, `/` поиск, `g`-переходы (`g d` дашборд, `g t` транзакции и так далее), `?` шпаргалка. Переключатель в старый интерфейс. Маршрутизация путей, как описано выше.
+   Приёмка: на https://firefly.hhhhh.dev после входа открывается новый дашборд. `/rules` открывает старую страницу Firefly. `/api/v1/about` с токеном отвечает. Выход и повторный вход возвращают на страницу, где был. Клавишей открывается та же страница в старом интерфейсе.
+2. **Транзакции.** Списки по типам и по счёту. Нормальные таблицы: плотные, выравнивание сумм, валюты, сплиты раскрываются на месте. Множественный выбор с клавиатуры и массовые действия (категория, бюджет, теги, удаление). Поиск на языке запросов Firefly с автодополнением операторов и значений, запрос живёт в URL. Редактор транзакции страницей, без модалки: создание, правка, сплиты, клон, удаление, ссылки между транзакциями, вложения. Автодополнение счетов, категорий, бюджетов, тегов. Сохранение `⌘Enter`. Быстрый ввод с любой страницы.
+   Приёмка: на стенде ввести с клавиатуры, без мыши, расход со сплитом на две категории, найти его поиском, поменять категорию массовым действием, удалить.
+3. **Счета и дашборд.** Счета по типам (список, просмотр с графиком баланса и транзакциями за период, создание и правка). Дашборд с тем же составом блоков, что в Firefly, нарисованный заново.
+4. **Бюджеты** (лимиты по периодам, доступный бюджет, траты против лимита), **категории**, **теги**, **подписки (bills)**, **копилки**, **группы объектов**.
+5. **Отчёты.** Генератор как в Firefly (тип, счета, период), но сразу живая страница: параметры в URL, меняются на месте, графики красивые, данные из insight- и chart-эндпоинтов. Главное место для выпендрёжа.
+6. **Остальное с API:** валюты и курсы, вложения, типы ссылок, настройки (preferences), экспорт, финансовые группы (administrations).
+7. **Автоматизации** (правила, группы правил, повторяющиеся транзакции, вебхуки): списки и просмотр можно, создание и правка уходят полной загрузкой в старый интерфейс Firefly.
+
+Чего не делаем: редактирование автоматизаций (только старый UI); то, чего нет в API (профиль, пароль, MFA, OAuth-клиенты, админка пользователей): это ссылки в старый UI. Если сверку счёта (reconcile) или смену типа транзакции нельзя честно сделать через API, они тоже остаются в старом UI, а в decisions.md записано почему.
+
+## Данные
+
+Разработка и проверка идут только на стенде с демо-данными. Прод это мои настоящие финансы. На проде только чтение и один смоук записи: транзакция с тегом `ffui-smoke` создаётся и удаляется, после смоука на проде не остаётся ничего твоего.
+
+## Дизайн
+
+impeccable, режим Operate, claddcn-svelte (уже стоит). PRODUCT.md по итогам интервью.
+- Вкус: узнаваемый Firefly. Палитра «примерно как у Firefly, только не уродская»: возьми его синий и цвета сумм (доход, расход, перевод) из v1 и v3, приведи в порядок через акценты claddcn. Не розовый msos. Светлая и тёмная тема, по умолчанию как в системе.
+- Плотность как у инструмента для power user: таблицы плотные, числа моноширинные и выровнены, ничего не прячется за наведением.
+- Без попапов. Редактирование страницей или на месте. Подтверждение удаления повторным нажатием на месте, а не диалогом.
+- Силы вкладывать в: таблицы транзакций и редактор; дашборд и отчёты (графики); палитру и клавиатуру. Остальное спокойное.
+- Не надо: таблетки, пульсация, скелетоны, тосты, длинные тире, висячие предлоги, некликабельные кнопки, подписи под блоками, жаргон. Карточки одной высоты. Фильтры, период и вкладки в URL. ПКМ вместо трёх точек. Ответ там, где нажал.
+- Тексты интерфейса как в Firefly (язык решим в интервью). Числа и даты по локали из настроек Firefly пользователя.
+
+## Как работаем
+
+- Карта страниц и контракт API в `docs/agents/pages.md` и `docs/agents/api-contract.md`, потом экраны параллельно субагентами.
+- Ядро по приоритетам доводи до приёмки. Дальше пространство твоё: всё, что сделает продукт лучше, делай без вопроса, смелые ставки приветствуются. Условие одно: каждая такая вещь описана в tour.md в блоке «сверх кикоффа» со строкой «зачем».
+- Чего в кикоффе нет, не придумывай. Нашёл дыру, назови дыру. Если репо устроен иначе, чем тут написано, следуй репо.
+- Чужие процессы и контейнеры на машине не трогай. Только свои PID, своё дерево. Никаких `pkill -f`, `prune`, `git reset` в общих копиях. Субагентам то же.
+- Проверка глазами (`eyes`): headless chromium, 1440×900, 1920×1080 и 390×844. Каждый экран, рядом с эталоном v1. Посмотри сам, исправь одним заходом, сними ещё раз. Скрины в `docs/agents/demos`.
+- `make fmt` и `make check` после каждого куска.
+- Коммиты через `/commit` в `dev`. Деплой: сервер `personal-main`, домен `firefly.hhhhh.dev`. Новый стек приложения через `scripts/new-app-stack.py` в `infra/komodo`, маршрутизация в `fleet/personal/personal-main/fireflyiii/site.caddy`, выкатка через `kom`. После деплоя доказать, что доехало: `kom` и живой адрес.
+- Главный сценарий (пункты 1 и 2) пройди на проде целиком в рамках смоука выше, потом проверь, что твоих данных не осталось.
+- Не заканчивай ход, пока работают фоновые агенты или идёт деплой.
+
+## Что нужно от меня (спроси в раунде вопросов)
+
+1. Права на деплой: можно ли пушить в `infra/komodo` (`main`) новый стек и правку `site.caddy` у `fireflyiii` и выкатывать через `kom` без меня. Дефолт: да, только эти два каталога. Проверь `kom`-ключом этой машины, что он вообще разрешает. Если отказ, обходить нельзя: всё готовишь, а выкатку оставляешь мне с точной командой в report.md.
+2. Смоук на проде: одна транзакция с тегом `ffui-smoke`, создать и удалить. Дефолт: да.
+3. Язык интерфейса. Дефолт: английский, как подписи Firefly v1; форматы по локали пользователя.
+4. Что открывается на корне домена: новый интерфейс (старый по переключателю) или старый (новый на `/app`). Дефолт: новый на тех же путях.
+
+## Утром
+
+Два файла в `docs/agents` и короткий отчёт в чат простым языком:
+- `report.md`: адрес; что работает и чем проверено; что не проверено вживую; что не сделано и почему; где угадывал (особенно про API); как откатить маршрутизацию одним шагом; что бы ещё закрыл. Всё, что обещал в раунде вопросов, тут есть.
+- `tour.md`: по экрану одна строка «что это, как попасть (адрес, клавиша, ПКМ), зачем». Отдельно полная раскладка клавиш. Отдельно блок «сверх кикоффа» в том же формате. Все скрытые аффордансы перечислены: меню по ПКМ, клавиши, тумблеры, переключатель в старый UI.
+
+Когда я вернусь, первым ходом проведи меня по tour.md, потом правки.