adr

# Conflicts:
#	docs/adr/260614-1703-n-tool-surface-mvp-рішення.md
#	docs/adr/260615-2027-кастомний-вибір-bun-workspace-замість-нативного-файл-менедже.md
#	docs/adr/260615-2043-кастомний-вибір-bun-workspace-замість-нативного-файлового-ме.md
#	docs/adr/260615-2051-кастомний-вибір-bun-воркспейсу-замість-нативного-файлового-м.md

Author: vitaliytv

app/src/material-symbols-outlined.css

@@ -0,0 +1,28 @@
+@font-face {
+  font-family: 'Material Symbols Outlined';
+  font-style: normal;
+  font-weight: 100 700;
+  font-display: block;
+  src:
+    url('../../node_modules/@quasar/extras/exports/material-symbols-outlined/web-font/kJEhBvYX7BgnkSrUwT8OhrdQw4oELdPIeeII9v6oFsLjBuVY.woff2')
+      format('woff2'),
+    url('../../node_modules/@quasar/extras/exports/material-symbols-outlined/web-font/kJF1BvYX7BgnkSrUwT8OhrdQw4oELdPIeeII9v6oDMzByHX9rA6RzaxHMPdY43zj-jCxv3fzvRNU22ZXGJpEpjC_1v-p_4MrImHCIJIZrDCvHeel.woff')
+      format('woff');
+}
+
+.material-symbols-outlined {
+  font-family: 'Material Symbols Outlined';
+  font-weight: normal;
+  font-style: normal;
+  line-height: 1;
+  letter-spacing: normal;
+  text-transform: none;
+  display: inline-block;
+  white-space: nowrap;
+  word-wrap: normal;
+  direction: ltr;
+  -webkit-font-smoothing: antialiased;
+  text-rendering: optimizeLegibility;
+  -moz-osx-font-smoothing: grayscale;
+  font-feature-settings: 'liga';
+}

docs/adr/260614-1757-iconset-quasar-обʼєкт-не-рядок.md

@@ -0,0 +1,27 @@
+# `iconSet` Quasar — передавати об'єктом, не рядком
+
+**Status:** Accepted
+**Date:** 2026-06-14
+
+## Context and Problem Statement
+
+Після додавання першого `q-select` у `CreateTaskDialog.vue` усі кнопки застосунку переставали реагувати на кліки. Налагодження показало, що `$q.iconSet.arrow.dropdown` викидає `TypeError` при рендері `q-select`: Quasar звертається до цієї властивості як до поля об'єкта, а не рядка — рядок не має такої властивості, Vue ламає цикл реактивності й усі обробники кліків губляться.
+
+## Considered Options
+
+- Передати `iconSet` рядком `'material-symbols-outlined'` — початковий підхід у `main.js`.
+- Передати `iconSet` імпортованим об'єктом з `quasar/icon-set/material-symbols-outlined.js`.
+
+## Decision Outcome
+
+Chosen option: "Передати `iconSet` імпортованим об'єктом", because Quasar звертається до `$q.iconSet.arrow.dropdown` (властивість об'єкта) при рендері компонентів з іконками вибору; рядок не має цієї властивості → `TypeError` → Vue ламає цикл реактивності → втрата всіх обробників кліків.
+
+### Consequences
+
+- Good, because після виправлення у лозі Vite зафіксовано 0 помилок після full reload; кнопки відновили реакцію на кліки.
+- Bad, because transcript не містить підтверджених негативних наслідків.
+- Neutral, because симптом виявляється лише при рендері першого `q-select` у сесії; `q-btn` самостійно баг не тригерить — він може бути прихований у проєктах без `q-select`.
+
+## More Information
+
+Файл: `app/src/main.js`. До виправлення: `iconSet: 'material-symbols-outlined'`. Після: `import materialSymbolsOutlined from 'quasar/icon-set/material-symbols-outlined.js'` + `iconSet: materialSymbolsOutlined`. Баг був прихований відсутністю `q-select` до появи `CreateTaskDialog`.

docs/adr/260614-1803-omlx-локальний-llm-провайдер.md

@@ -0,0 +1,38 @@
+# Локальна офлайн-модель через omlx як LLM-провайдер агента
+
+**Status:** Accepted
+**Date:** 2026-06-14
+
+## Context and Problem Statement
+
+Для in-app agent-loop потрібен LLM-провайдер. Вимоги: приватність, офлайн-доступність, сумісність із наявною інфраструктурою (`tauri-plugin-http`). Обирали між хмарним Claude, локальною офлайн-моделлю та провайдер-агностичним інтерфейсом.
+
+## Considered Options
+
+- Claude (Anthropic) через `tauri-plugin-http` — хмарний, потребує API-ключа і мережі.
+- Локальна офлайн-модель через omlx (OpenAI-сумісний MLX-сервер) + Gemma 4 E4B.
+- Провайдер-агностичний інтерфейс із кількома бекендами — відкладено як передчасне для MVP.
+
+## Decision Outcome
+
+Chosen option: "Локальна офлайн-модель Gemma через omlx", because вимога — офлайн і приватність; omlx говорить OpenAI API, тому `tauri-plugin-http` підходить без змін, а формат tool-маніфесту — стандартний OpenAI function-calling із того самого `src/tool/catalog.js`. MCP залишається ціллю після MVP.
+
+### Consequences
+
+- Good, because end-to-end цикл підтверджено наживо: `gemma-4-e2b-it-4bit` через omlx самостійно обрала тул `create`, `dispatch` виконав через `mt-scanner`, файли `task.md` + `a.md` реально створено.
+- Bad, because `gemma-4-e4b-it-OptiQ-4bit` впала з HTTP 507 (memory ceiling 11.84 GB, зайнято 10.57 GB) — потрібно звільняти RAM або використовувати меншу модель.
+- Bad, because ~4B-модель нестабільна в генерації коректного JSON для `tool_calls` — необхідний constrained decoding як наступний крок.
+
+## More Information
+
+Конфіг: `OMLX_BASE_URL` (дефолт `http://127.0.0.1:8000/v1`), `OMLX_MODEL` (дефолт `gemma-4-e4b-it-OptiQ-4bit`), `OMLX_API_KEY`. Файли: `app/src/tool/llm.js` (`createOpenAiChat`, `runAgent`), `app/src/composables/use-omlx.js` (localStorage), `app/bin/task.mjs` (команда `task agent "<prompt>"`). Модель підтверджено через `/v1/models` на сервері. MCP-обгортка — ціль на потім.
+
+## Update 2026-06-15
+
+Додаткові деталі реалізації (сесія `e8e91f68`): `createOpenAiChat({ baseUrl, model, apiKey, fetchFn })` — `fetchFn` інжектується як залежність: Tauri використовує `@tauri-apps/plugin-http`, CLI — node `fetch`, тести — mock; єдиний код обслуговує всі три контексти. `runAgent({ prompt, dispatch, chat, maxSteps })` — до 3–5 кроків за прогін.
+
+Підтверджено наживо: `gemma-4-e2b-it-4bit` на порту `:8000` завершила повний tool-call цикл → `mt-scanner create` → файли `demo-llm/task.md` + `demo-llm/a.md`. `gemma-4-e4b-it-OptiQ-4bit` впала з HTTP 507 (потребує 17.89 GB, ceiling 11.84 GB).
+
+Рекомендація надійності: тримати малий набір тулів (≤3), по 1 за хід; наступний крок — constrained decoding для гарантованого JSON у `tool_calls`.
+
+Пер-stack реалізація `n-tool-surface` у `n-tauri` (версія `1.5`): один Rust-fn на тул, `#[tauri::command]`, dispatch-invoke через camelCase-ключі, конверт `{ok,output}` / `{ok:false,error}`. Правило `n-tool-surface` авто-активується через `depInAnyPackageJson` для `vue`/`react`/`svelte`/`@tauri-apps/api`/`@capacitor/core`.

docs/adr/260615-0533-tauri-http-localhost-порти.md

@@ -0,0 +1,30 @@
+# Tauri HTTP-плагін — явний wildcard-порт для localhost у capabilities
+
+**Status:** Accepted
+**Date:** 2026-06-15
+
+## Context and Problem Statement
+
+Фронтенд (`AgentDialog.vue`) використовує `@tauri-apps/plugin-http` для запитів до локального LLM-сервера (`http://127.0.0.1:8000/v1/chat/completions`). Tauri відхиляв запит, попри наявний шаблон `{ "url": "http://**" }` у `capabilities/default.json`. Причина: реалізація `urlpattern` у Tauri трактує шаблон без явного порту як дозвіл лише на порт за замовчуванням (80 для `http://`) — нестандартний порт `:8000` ніколи не збігався з цим шаблоном.
+
+## Considered Options
+
+- Залишити `http://**` і розраховувати, що він покриє будь-який порт (не спрацьовує через семантику `urlpattern`).
+- Додати явні шаблони з wildcard-портом `:*` для `127.0.0.1` і `localhost`.
+
+## Decision Outcome
+
+Chosen option: "Явні шаблони `http://127.0.0.1:*/*` і `http://localhost:*/*`", because `http://**` не матчить нестандартний порт в реалізації `urlpattern` Tauri, а явна вказівка `:*` вирішує проблему без надмірного розширення scope.
+
+### Consequences
+
+- Good, because запити до `http://127.0.0.1:8000/v1/chat/completions` тепер проходять Tauri scope-перевірку; після виправлення нова помилка стала `401 API key required` від omlx-сервера — scope-проблему повністю вирішено.
+- Bad, because capabilities компілюються у бінарник під час build — зміна набирає чинності лише після перезапуску `tauri dev` / повного rebuild; hot-reload фронтенду недостатньо.
+
+## More Information
+
+Змінений файл: `app/src-tauri/capabilities/default.json` — блок `http:default` → `allow`, додано `{ "url": "http://127.0.0.1:*/*" }` і `{ "url": "http://localhost:*/*" }`. Існуючий `http://**` збережено для non-loopback HTTP. Компонент, що виконує запит: `app/src/components/AgentDialog.vue` (імпортує `fetch` з `@tauri-apps/plugin-http`). Перевірено: `cargo check`.
+
+## Update 2026-06-15
+
+Попередній фрагмент тієї самої сесії `005a85c1` (за 1 хвилину до основного запису): шаблони `{ "url": "http://127.0.0.1:*" }` і `{ "url": "http://localhost:*" }` застосовані в `capabilities/default.json`; існуючий `http://**` збережено для non-loopback HTTP. Семантика підтверджена: `urlpattern` Tauri трактує шаблон без явного порту як дозвіл лише на default-порт (80 для `http://`).

docs/adr/260615-0547-omlx-налаштування-settings-json.md

@@ -0,0 +1,37 @@
+# `~/.omlx/settings.json` як канонічне джерело конфігурації omlx у Tauri
+
+**Status:** Accepted
+**Date:** 2026-06-15
+
+## Context and Problem Statement
+
+omlx API-ключ зберігався у `localStorage` браузерного webview Tauri і мав вводитися вручну через ⚙-панель `AgentDialog` для кожного застосунку окремо. CLI (`app/bin/task.mjs`) вже читав ключ із `OMLX_API_KEY` env, але Tauri-застосунок цього не робив. GUI `.app`, запущений із Finder/Dock, не бачить `~/.zshrc`, тому env-підхід вимагав `launchctl setenv` або LaunchAgent на кожній машині.
+
+## Considered Options
+
+- Зберігати ключ у `localStorage` — попередній підхід, ручне введення per-app.
+- Читати з env-змінної `OMLX_API_KEY` — проміжне рішення; не працює для GUI з Finder/Dock без додаткового налаштування.
+- Читати з `~/.omlx/settings.json` (файл, що вже існує на кожній машині з omlx) з env як опційним override.
+
+## Decision Outcome
+
+Chosen option: "Читання з `~/.omlx/settings.json` з fallback на env", because файл вже є канонічним джерелом конфігурації omlx-сервера (host, port, api_key), резолвиться через `$HOME` per-machine, не потребує додаткового launchd/plist і уніфікує джерело для UI та CLI.
+
+### Consequences
+
+- Good, because один файл `~/.omlx/settings.json` покриває всі машини з omlx без ручного виставлення env на кожному комп'ютері.
+- Good, because CLI і Tauri UI тепер читають ключ з одного джерела — `auth.api_key` із `~/.omlx/settings.json` (або `OMLX_API_KEY` env як override).
+- Bad, because GUI `.app` із Finder/Dock не бачить `~/.zshrc` — env-override потребує `launchctl setenv` або LaunchAgent; пряме читання файлу усуває цю проблему.
+
+## More Information
+
+Змінені файли:
+- `src-tauri/src/lib.rs` — нова Tauri-команда `omlx_config`: читає `~/.omlx/settings.json` (поля `server.host`, `server.port`, `auth.api_key`) та env-змінні `OMLX_*` як override; зареєстрована в `invoke_handler`.
+- `src/composables/use-omlx.js` — `apiKey` прибрано з `localStorage`; `loadEnv()` викликає `invoke('omlx_config')`.
+- `src/components/AgentDialog.vue` — `onMounted(loadEnv)` підтягує конфіг при відкритті діалогу.
+
+Структура `~/.omlx/settings.json`: `server.host`, `server.port`, `auth.api_key`. Перевірено: `cargo check` і `vitest run` (36 тестів) — зелені.
+
+## Update 2026-06-15
+
+Проміжний крок тієї самої сесії `005a85c1` (до запису settings.json-рішення): API-ключ спочатку переведено з `localStorage` на читання через env-змінну — нова Tauri-команда `omlx_config` у `lib.rs` читала `OMLX_BASE_URL`, `OMLX_MODEL`, `OMLX_API_KEY` зі `std::env` і повертала JSON фронту; `loadEnv()` у `use-omlx.js` викликала `invoke('omlx_config')` і перекривала localStorage-дефолт. Цей підхід усував ручне введення у UI, але не вирішував проблему GUI `.app` запущеного з Finder/Dock (не бачить `~/.zshrc`). Саме це обмеження стало головним аргументом на користь прямого читання з `~/.omlx/settings.json`.

docs/adr/260616-0625-виправлення-рекурсивного-виклику-tauri-скрипта-в-app-package.md

@@ -0,0 +1,32 @@
+---
+session: 6220396b-6750-408d-9018-b5153cdb0963
+captured: 2026-06-16T06:25:46+03:00
+transcript: /Users/vitaliytv/.claude/projects/-Users-vitaliytv-www-nitra-task/6220396b-6750-408d-9018-b5153cdb0963.jsonl
+---
+
+The script has been updated — `tauri` now calls the binary directly instead of recursively calling itself via `--cwd=app`.
+
+Running `bun run start` should work now (the `tauri` binary is hoisted to root `node_modules/.bin/` and is accessible from the workspace).
+---
+
+## ADR Виправлення рекурсивного виклику `tauri` скрипта в `app/package.json`
+
+## Context and Problem Statement
+Запуск `bun run start` завершувався помилкою `ENOENT: Could not change directory to "app"`. Кореневий скрипт `start` у `package.json` делегував виклик в `app/` через `bun --cwd=app run tauri dev`, але скрипт `tauri` у `app/package.json` рекурсивно повторював `bun --cwd=app run tauri`, намагаючись перейти в неіснуючу директорію `app/app/`.
+
+## Considered Options
+* Виправити скрипт `tauri` у `app/package.json`, щоб він викликав бінарний файл `tauri` безпосередньо
+* Інші варіанти в transcript не обговорювалися.
+
+## Decision Outcome
+Chosen option: "Виправити скрипт `tauri` у `app/package.json`, щоб він викликав бінарний файл `tauri` безпосередньо", because бінарний файл `tauri` вже піднятий (hoisted) у кореневий `node_modules/.bin/` через workspaces і доступний з будь-якого workspace без додаткового `--cwd`.
+
+### Consequences
+* Good, because `bun run start` більше не впирається в рекурсивну помилку шляху — `app/package.json` тепер викликає `tauri` напряму.
+* Bad, because transcript не містить підтверджених негативних наслідків.
+
+## More Information
+- Файл змінено: `app/package.json`, скрипт `tauri`: `"bun --cwd=app run tauri"` → `"tauri"`
+- Скрипт `android` у `app/package.json` також містив аналогічну рекурсію (`"bun --cwd=app run tauri android dev"`) — виправлено у тому ж коміті
+- Бінарний файл `tauri` зареєстрований у `node_modules/.bin/tauri` кореневого workspace
+- Залежність `@tauri-apps/cli` підключена через `app/package.json` як devDependency