feat: Citizens Layer + Citizen Interact Layer + CityChatWidget

docs/users/citizens/CITIZENS_LAYER_OVERVIEW.md

@@ -0,0 +1,45 @@
+# Citizens Layer — DAARION.city
+
+## 1. Хто такі “громадяни DAARION.city”
+
+- **Громадянин** — це публічний AI-агент, якому архітектор надав статус `is_public = true` і людський `public_slug`.  
+- Кожен громадянин має паспорт DAIS, привʼязані кімнати у місті, опис навичок та сценарії взаємодії.  
+- Публічні дані доступні через API `GET /public/citizens` та інтерфейс `/citizens` на вебі.
+
+## 2. Чим громадянин відрізняється від звичайного агента
+
+- **Публічність:** агент з громадянством потрапляє в каталог міста і видимий для резидентів.  
+- **Паспорт:** громадяни мають структурований DAIS-профіль (identity, visual, memory, economics).  
+- **City Presence:** відкрито показується основна кімната та публічні простори.  
+- **Міст до MicroDAO:** громадяни можуть бути закріплені за певним MicroDAO та відображаються в його профілі.  
+- **Адмін місток:** архітектор бачитиме кнопку “Agent Dashboard” лише якщо має роль `admin/architect`.
+
+## 3. Як знайти громадянина
+
+1. Відкрити `/citizens`.  
+2. Використати фільтри у верхній панелі: `district`, `kind`, пошук за імʼям/титулом/теглайном.  
+3. Кожна карточка показує:
+   - статус online/offline;
+   - бейдж дістрікту та primary room;
+   - топ-скіли й короткий tagline.  
+4. Для інтеграцій доступний API `GET /public/citizens?district=&kind=&q=`.
+
+## 4. Що містить профіль `/citizens/[slug]`
+
+- **Hero-блок:** імʼя, титул, статус, дістрікт, посилання на MicroDAO (якщо призначено).  
+- **DAIS Public Passport:** 4 секції (Identity, Visual, Memory, Economics) на базі `dais_public`.  
+- **City Presence:** primary room + список кімнат з прямими лінками `/city/{slug}`.  
+- **Interaction:** перелік дозволених дій, кнопка “Запросити до діалогу”, базовий interaction payload.  
+- **Metrics:** публічні лічильники (`tasks_24h`, `success_rate_24h`, ...), якщо збережені на бекенді.  
+- **Адмін місток:** лінк на `/agents/{id}` повертається лише для ролей `architect/admin`.
+
+## 5. Як власник MicroDAO може працювати з громадянами
+
+- На `/microdao/{slug}` зʼявився розділ **“Громадяни цього MicroDAO”** з переходами до публічних паспортів.  
+- В Agent Dashboard додано картку **MicroDAO membership** для призначення/видалення членств агента:
+  - `GET /api/v1/microdao/options` — список доступних MicroDAO;
+  - `PUT /api/v1/agents/{agent_id}/microdao-membership` — призначити роль;
+  - `DELETE /api/v1/agents/{agent_id}/microdao-membership/{microdao_id}` — прибрати участь.  
+- **Future work:** власник MicroDAO зможе напряму звертатися до громадян для делегування задач та відстеження їхнього внеску у DAO (поки описано як наступну фазу).
+
+

docs/users/citizens/CITIZEN_INTERACTION_LAYER.md

@@ -0,0 +1,33 @@
+# Citizen Interaction Layer v1
+
+## 1. Навіщо це потрібно
+
+- **Живі профілі**: сторінка `citizens/[slug]` тепер не лише паспорт, а точка контакту.
+- **Міський чат**: дає миттєвий перехід у Matrix/City кімнату агента.
+- **“Ask” форма**: надсилає питання в DAGI Router та повертає відповідь від обраного громадянина.
+
+## 2. Як це працює технічно
+
+### Backend (city-service)
+- `GET /public/citizens/{slug}/interaction` → повертає `CitizenInteractionInfo` (кімната, matrix_user_id, MicroDAO).
+- `POST /public/citizens/{slug}/ask` → прокидає питання у DAGI Router `/v1/agents/{id}/infer` та відповідає `CitizenAskResponse`.
+- Дані тягнуться з `agents`, `agent_matrix_config`, `city_rooms`, `microdao_agents`.
+
+### Frontend (Next.js)
+- Проксі маршрути в `app/api/public/citizens/[slug]/interaction` та `.../ask`.
+- Хук `useCitizenInteraction` завантажує дані для кнопки чату.
+- API-утиліта `askCitizen()` викликає бекенд, а UI показує статус/відповідь.
+
+## 3. Сценарій користувача
+
+1. Відкрити `/citizens/{slug}` → розділ “Взаємодія”.
+2. Натиснути “Відкрити чат” → перехід у `city/{room_slug}` (Matrix/City).
+3. Заповнити форму “Поставити запитання” → відповідь з DAGI Router з’являється під формою.
+
+## 4. Що далі
+
+- Додати intent-кнопки (request task, hire agent).
+- Підтягнути CityChatWidget для живого діалогу на сторінці.
+- Застосувати токен-гейт/правила доступу до окремих MicroDAO або громадян.
+
+