chore: organize documentation structure for monorepo

- Create /docs structure (microdao, daarion, agents)
- Organize 61 cursor technical docs
- Add README files for each category
- Copy key documents to public categories
- Add GitHub setup instructions and scripts

docs/microdao/README.md

@@ -0,0 +1,25 @@
+# MicroDAO — Документація
+
+Ця папка містить документацію про систему MicroDAO: архітектуру, RBAC, токеноміку, технічні специфікації.
+
+## Структура
+
+### Архітектура та дизайн
+- `architecture.md` — загальна архітектура системи
+- `rbac.md` — система ролей та доступів (RBAC)
+- `tokenomics.md` — токеноміка MicroDAO
+
+### Технічна документація
+- `api.md` — API специфікація
+- `database-schema.md` — схема бази даних
+- `security.md` — безпека та аудит
+
+### Для розробників
+Детальна технічна документація для розробки знаходиться в `/docs/cursor/` — це специфікації для Cursor AI та розробників.
+
+## Посилання
+
+- [Технічна документація для розробки](../cursor/README.md)
+- [DAARION.city інтеграція](../daarion/README.md)
+- [Агентська система](../agents/README.md)
+

docs/microdao/access-keys-capabilities.md

@@ -0,0 +1,677 @@
+# 24 — Access Keys & Capabilities System (MicroDAO)
+
+Універсальна система ключів доступу та capability-механіка
+
+Цей документ описує універсальну систему ключів доступу (access keys) та capability-механіку для платформи **microdao / DAARION.city**:
+
+- як видаються й перевіряються ключі;
+- як описуються та застосовуються capabilities;
+- як працюють **Wallet Agent** і **Embassy Module**;
+- як система вбудовується в існуючі RBAC/Entitlements/Mode (public|confidential) та Governance.
+
+Ціль: єдиний шар авторизації для веб-клієнта, приватних агентів, API, інтеграцій та зовнішніх платформ.
+
+---
+
+## 1. Purpose & Scope
+
+Цей документ описує універсальну систему ключів доступу (access keys) та capability-механіку для платформи **microdao / DAARION.city**:
+
+- як видаються й перевіряються ключі;
+- як описуються та застосовуються capabilities;
+- як працюють **Wallet Agent** і **Embassy Module**;
+- як система вбудовується в існуючі RBAC/Entitlements/Mode (public|confidential) та Governance.
+
+Ціль: єдиний шар авторизації для веб-клієнта, приватних агентів, API, інтеграцій та зовнішніх платформ.
+
+---
+
+## 2. Основні поняття
+
+### 2.1 Access Key
+
+Access Key — це матеріалізований «токен доступу» до певної області системи:
+
+- має унікальний `key_id`;
+- прив'язаний до **суб'єкта** (user / team / agent / external platform);
+- має **набір capabilities**;
+- має строк дії та статус (active / revoked / expired).
+
+Приклади:
+
+- ключ API для інтеграції з GreenFood;
+- ключ приватного агента до Co-Memory та Projects;
+- ключ Embassy для міжплатформенної взаємодії.
+
+### 2.2 Capability
+
+Capability — атомарне право **на дію над ресурсом**.
+
+Формат (концептуально):
+
+```text
+<domain>.<resource>.<action>[:<scope>]
+```
+
+Приклади:
+
+- `chat.message.send`
+- `chat.channel.manage`
+- `comemory.item.read:team`
+- `projects.task.write`
+- `wallet.balance.view`
+- `wallet.stake.ringk`
+- `governance.proposal.create`
+- `energy.asset.read`
+- `platform.greenfood.inventory.update`
+
+### 2.3 Capability Bundle (role / plan / template)
+
+Capability-набір:
+
+- набір capabilities, який прив'язується до:
+  - ролі (`Owner`, `Guardian`, `Member`, `Visitor`);
+  - тарифного плану (Freemium / Casual / Premium / Platformium);
+  - конкретного access key (API-ключ, агент, інтеграція).
+
+---
+
+## 3. Модель доступу (оновлена формула allow)
+
+Базова формула авторизації:
+
+```text
+allow =
+  RBAC(role, action, resource)
+  ∧ Entitlement(plan, RINGK_staked)
+  ∧ Capability(key, action, resource)
+  ∧ ACL(resource)
+  ∧ Mode(public|confidential)
+```
+
+Тобто:
+
+1. Роль дозволяє дію (Owner/Guardian/Member/Visitor).
+2. План + стейк RINGK дають достатні ліміти/право (ентайтли).
+3. Ключ (user/agent/API) має відповідну capability.
+4. ACL ресурсу не забороняє (список дозволених/заборонених).
+5. Режим каналу/команди (public/confidential) не блокує дію.
+
+---
+
+## 4. Типи ключів
+
+### 4.1 User Session Key
+
+- Прив'язаний до користувача (`user_id`) і сесії (JWT / cookie).
+- Використовується веб-клієнтом.
+- Capabilities виводяться з ролі, ентайтлів і контексту (team, mode).
+
+### 4.2 Agent Access Key
+
+- Прив'язаний до приватного агента (`ag_…`).
+- Використовується при викликах **Agent Mesh / Tooling API**.
+- Має обмежений набір capabilities:
+  - `chat.message.read:scoped`
+  - `comemory.item.read:scoped`
+  - `followups.create`
+  - `projects.task.read/write` (за необхідності)
+- Має обмеження за:
+  - токенами/хв;
+  - кількістю викликів;
+  - бюджетом 1T / KWT.
+
+### 4.3 API Key / Integration Key
+
+- Прив'язаний до інтеграції (`integrations`).
+- Наприклад: Notion, Slack, GreenFood, Energy Union, Water Union.
+- Capabilities для зовнішнього сервісу:
+  - `webhook.events.receive:team`
+  - `projects.task.sync`
+  - `rwa.energy.update`
+  - `platform.greenfood.sync`
+
+### 4.4 Embassy Key
+
+- Ключ для **Embassy Module** — шлюз між DAARION.city та зовнішньою платформою/мережею.
+- Додаткові властивості:
+  - mapping зовнішніх ідентичностей (external_id ↔ DID/user_id);
+  - whitelist дозволених типів актів (`intent.created`, `offer.published`, `gift.ack`, `rwa.claim` тощо);
+  - окремий журнал дій для аудиту.
+
+### 4.5 Wallet Capability Key
+
+- Спеціальний ключ для **Wallet Agent**:
+  - `wallet.balance.view`
+  - `wallet.tx.initiate`
+  - `wallet.tx.sign`
+  - `wallet.stake.ringk`
+  - `wallet.claim.rwa`
+- Може бути:
+  - нон-кастодіальний (підпис у клієнта, key лише для маршрутизації);
+  - кастодіальний (wallet service з 4-eyes контролем).
+
+---
+
+## 5. Wallet Agent: специфікація
+
+### 5.1 Призначення
+
+Wallet Agent — це агент, який:
+
+- показує баланси токенів (RINGK, 1T, KWT, DAAR, DAARION тощо);
+- ініціює й перевіряє дії стейкінгу/unstake RINGK;
+- показує історію payouts (1T/KWT);
+- працює з RWA-сертифікатами (Energy, GREENFOOD тощо) через Embassy.
+
+### 5.2 Основні флоу
+
+1. **View balances**
+
+- Виклик: `/wallet/balances`.
+- Перевірка:
+  - RBAC: будь-який Member+ / Owner/Guardian.
+  - Capability: `wallet.balance.view`.
+  - Mode: не залежить від public/confidential.
+
+2. **Stake RINGK**
+
+- Виклик: `/staking/ringk` (`amount`).
+- Перевірка:
+  - RBAC: Member+.
+  - Capability: `wallet.stake.ringk`.
+  - Entitlements: перевірка мінімального стейку, lock-параметрів.
+  - Governance: параметри стейку (lock_until, min_amount) беруться з onchain/DAO-конфігів.
+
+3. **Claim payouts (1T/KWT/RWA)**
+
+- Флоу:
+  - Wallet Agent читає `payouts`/`rwa_claims` з backend;
+  - ініціює підпис транзакції користувачем;
+  - виконує через onchain gateway/Embassy.
+- Capabilities:
+  - `wallet.payout.view`
+  - `wallet.payout.claim`
+  - `rwa.claim`
+
+### 5.3 Дані (мінімум)
+
+- `wallets` (user_id ↔ address)
+- `staking_ringk`
+- `payouts`
+- `rwa_certificates` / `rwa_claims` (через Embassy)
+
+---
+
+## 6. Embassy Module: специфікація
+
+### 6.1 Призначення
+
+Embassy Module — шар інтеграції між:
+
+- DAARION.city (місто агентів, microdao);
+- зовнішніми платформами (GreenFood, Energy Union, інші RWA-ініціативи);
+- публічними мережами (L2, marketplace, вузли взаємообміну).
+
+Він відповідає за:
+
+- мапінг ідентичностей;
+- валідацію актів взаємодії;
+- трансформацію подій і capability-рівнів.
+
+### 6.2 Ідентичності
+
+- `resident_id` ↔ `user_id`/DID.
+- `district_id` ↔ team/microDAO.
+- `agent_id` ↔ citizen-agent.
+- `rwa_id` ↔ сертифікат дару/актив RWA.
+
+Embassy Key має capability-набори:
+
+- `embassy.intent.read/write`
+- `embassy.rwa.claim`
+- `embassy.energy.update`
+- `embassy.audit.view`
+
+### 6.3 Події (канонічні акти)
+
+- `intent.created`
+- `offer.published`
+- `gift.ack`
+- `memory.update`
+- `rwa.claim`
+- `energy.update`
+
+Embassy:
+
+- приймає подію через webhook / шину (NATS);
+- перевіряє capability Embassy Key;
+- трансформує в внутрішні події (`reward.*`, `oracle.*`, `payout.*`).
+
+---
+
+## 7. Runtime capability-check
+
+### 7.1 Компоненти
+
+- **PDP** (Policy Decision Point) — сервіс, який:
+  - приймає контекст запиту: `user_id / agent_id`, `team_id`, `resource`, `action`, `mode`, `key_id`;
+  - повертає `allow/deny` + причину.
+- **PEP** (Policy Enforcement Point):
+  - live у API-gateway і сервісах (Messaging, Projects, Wallet, Governance).
+
+### 7.2 Кеш і формат токена
+
+- Для кожного access key формується компактний «capability token»:
+  - `sub` (user/agent/integration);
+  - `team_scope`;
+  - `caps` (список capability кодів або bitmap);
+  - `exp`.
+- Токен зберігається в Redis / in-memory кеші для швидкої перевірки.
+
+### 7.3 Приклади перевірок
+
+1. Агент хоче прочитати Co-Memory:
+
+```text
+action = comemory.item.read
+resource = chat: c_123
+mode = confidential
+subject = ag_456
+key_id = ak_789
+
+→ RBAC: owner of agent = Member в team t_1
+→ Entitlements: план дозволяє приватні агенти
+→ Capability(ak_789): містить comemory.item.read:scoped
+→ ACL: чат дозволяє агентів
+→ Mode: confidential → E2EE, агент отримує лише векторні ознаки/summary
+
+→ allow
+```
+
+2. Зовнішній RWA-хаб оновлює енергетичний актив:
+
+```text
+action = energy.update
+subject = embassy_key ek_001
+→ Capability(ek_001): енергетичні оновлення дозволені для конкретного district_id
+→ Governance: політика для цього district_id активна
+
+→ allow
+```
+
+---
+
+## 8. Інтеграція з Governance Agent
+
+Governance Agent:
+
+- має capability `governance.policy.manage` (тільки Owner/Guardian через DAO-процес);
+- може:
+  - створювати/оновлювати **capability bundles**;
+  - прив'язувати bundles до ролей/планів/ключів;
+  - змінювати пороги доступу (напр. min RINGK stake для Premium/Platformium).
+
+Флоу:
+
+1. Створюється пропозиція (onchain / в DAO Service):
+   - змінити набір capabilities для `Platformium` плану;
+   - додати capability `platform.greenfood.inventory.update`.
+2. Пропозиція голосується токеном DAARION.
+3. Після прийняття Governance Agent:
+   - оновлює конфіг у Capability Registry;
+   - виконує міграцію активних access keys;
+   - логуються події `governance.policy.updated`.
+
+---
+
+## 9. Дані та моделі (мінімальна схема)
+
+Таблиці (спрощений вигляд):
+
+```sql
+create table access_keys (
+  id text primary key,        -- ak_...
+  subject_kind text not null, -- user|agent|integration|embassy
+  subject_id text not null,
+  team_id text null,
+  name text not null,
+  status text not null check (status in ('active','revoked','expired')),
+  created_at timestamptz not null default now(),
+  expires_at timestamptz null
+);
+
+create table capabilities (
+  id text primary key,        -- cap_...
+  code text not null,         -- chat.message.send, wallet.stake.ringk
+  description text not null
+);
+
+create table access_key_caps (
+  key_id text references access_keys(id) on delete cascade,
+  cap_id text references capabilities(id) on delete cascade,
+  primary key (key_id, cap_id)
+);
+
+create table bundles (
+  id text primary key,        -- bundle_...
+  name text not null,         -- e.g. "role.Member", "plan.Premium", "agent.default"
+  created_at timestamptz not null default now()
+);
+
+create table bundle_caps (
+  bundle_id text references bundles(id) on delete cascade,
+  cap_id text references capabilities(id) on delete cascade,
+  primary key (bundle_id, cap_id)
+);
+```
+
+Access key може наслідувати capabilities з одного чи кількох bundles.
+
+---
+
+## 10. Безпека
+
+- Мінімізований набір capabilities за замовчуванням (principle of least privilege).
+- Для confidential-контенту:
+  - агенти не отримують plaintext без явної згоди;
+  - Embassy не передає контент, тільки агреговані/векторні дані.
+- Всі access keys:
+  - зберігаються у зашифрованому вигляді (KMS);
+  - мають короткий час життя, періодичну ротацію;
+  - мають аудит використання (audit_log).
+
+---
+
+## 11. Інтеграція з RBAC & Entitlements
+
+Посилання на документ: `microdao — RBAC і Entitlements (MVP).docx`
+
+1. Розширена формула доступу (оновлює пункт 2 у RBAC-документі):
+
+```text
+allow =
+  RBAC(role, action, resource)
+  ∧ Entitlement(plan, RINGK_staked)
+  ∧ Capability(key, action, resource)
+  ∧ ACL(resource)
+  ∧ Mode(public|confidential)
+```
+
+2. Мапінг ролей з RBAC → capability bundles:
+
+- з таблиць `team_members.role` (`Owner`, `Guardian`, `Member`) та viewer-type (`reader`, `commenter`, `contributor`) формуються стартові bundles:
+  - `bundle.role.Owner`
+  - `bundle.role.Guardian`
+  - `bundle.role.Member`
+  - `bundle.role.Visitor` (для гостя в public-каналах).
+- кожен bundle включає capabilities, що відповідають матрицям з розділу «4) Ресурси → дії (матриці)» RBAC-документу
+  (Community, Channels, Messages, Follow-ups, Projects, Tasks, Docs, Meetings).
+
+3. Мапінг Entitlements (плани + стейк RINGK):
+
+- таблиці з Data Model:
+  - `wallets`
+  - `staking_ringk`
+- плани з RBAC-документу (`Freemium`, `Casual`, `Premium`, `Platformium`) задаються як:
+  - `bundle.plan.Freemium`
+  - `bundle.plan.Casual`
+  - `bundle.plan.Premium`
+  - `bundle.plan.Platformium`
+- формула з RBAC → в capability-рівень:
+
+```text
+effective_quota = min(plan_quota × multiplier(RINGK_staked), hard_limit)
+```
+
+- ліміти прив'язуються до capabilities на кшталт:
+  - `chat.message.send`
+  - `agent.run.invoke`
+  - `router.invoke`
+  - `wallet.payout.claim`
+
+---
+
+## 12. Інтеграція з Security Architecture & Threat Model
+
+Посилання: `microdao — Security Architecture & Threat Model (MVP).docx`
+
+1. Зберігання ключів:
+
+- метадані ключа — в таблиці `access_keys` (див. розділ 13 нижче);
+- сам секрет (`secret`) зберігається зашифрованим (KMS/HSM), згідно з розділами про secrets у Security Architecture;
+- one-time reveal: після створення ключ не показується повторно.
+
+2. Транспорт і токени:
+
+- веб-клієнт:
+  - використовує сесію (`users` + сесійні токени на рівні Auth);
+  - capability-набір інкапсульовано в «capability token» (JWT/opaque), який несе:
+    - `sub` (u_/ag_/integr),
+    - `team_id`,
+    - стиснений список `caps`.
+- API/Webhooks/Embassy:
+  - ключ передається в `Authorization: Bearer <access_key_secret>` або в окремому заголовку;
+  - підпис вебхуків (Embassy) — HMAC, як у Security Architecture.
+
+3. Confidential-режим:
+
+- `teams.mode` ∈ (`public`, `confidential`);
+- для `mode='confidential'`:
+  - агенти з Agent Access Key не бачать `chat_message.body` у plaintext,
+  - доступ дається до:
+    - агрегованих структур (`comemory_items`),
+    - embeddings/summary, сформованих локально або в E2EE-шарі;
+- це наслідує E2EE-модель з Security-документу (сервер бачить мінімум метаданих).
+
+4. Threat model для access keys:
+
+- нові активи:
+  - `access_keys`, `bundles`, capability-кеш;
+- загрози:
+  - компрометація ключа, зловживання Embassy-ключем, масовий abuse agent-ключів;
+- мітiгації:
+  - короткий `expires_at`, обов'язкова ротація;
+  - strict capabilities (least privilege);
+  - обов'язковий аудит через події `audit.event` і нові `access_key.*` (див. нижче).
+
+---
+
+## 13. Інтеграція з Data Model & Event Catalog
+
+Посилання: `microdao — Data Model & Event Catalog.docx`
+
+1. Нові таблиці (додати в розділ DB-схеми, поруч із Wallet / Governance):
+
+```sql
+create table access_keys (
+  id text primary key,        -- ak_...
+  subject_kind text not null, -- 'user' | 'agent' | 'integration' | 'embassy'
+  subject_id text not null,   -- u_/ag_/...
+  team_id text null,          -- t_..., якщо scoped до команди
+  name text not null,
+  status text not null check (status in ('active','revoked','expired')),
+  created_at timestamptz not null default now(),
+  expires_at timestamptz null,
+  last_used_at timestamptz null
+);
+
+create table capabilities (
+  id text primary key,        -- cap_...
+  code text not null unique,  -- chat.message.send, wallet.stake.ringk, ...
+  description text not null
+);
+
+create table access_key_caps (
+  key_id text references access_keys(id) on delete cascade,
+  cap_id text references capabilities(id) on delete cascade,
+  primary key (key_id, cap_id)
+);
+
+create table bundles (
+  id text primary key,        -- bundle_...
+  name text not null unique,  -- role.Member / plan.Premium / agent.default
+  created_at timestamptz not null default now()
+);
+
+create table bundle_caps (
+  bundle_id text references bundles(id) on delete cascade,
+  cap_id text references capabilities(id) on delete cascade,
+  primary key (bundle_id, cap_id)
+);
+```
+
+- конвенції ID узгоджуються з розділом «2) Конвенції»:
+  - `ak_…` для access keys;
+  - `cap_…` для capabilities;
+  - `bundle_…` для bundle-ів.
+
+2. Прив'язка до існуючих таблиць:
+
+- `access_keys.subject_id` → `users.id` / `agents.id` / `integrations.id` / Embassy-ідентифікатори (згідно з Data Model);
+- `access_keys.team_id` → `teams.id` (team як microDAO/платформа).
+
+3. Нові події для Event Catalog (розширення enum `topic`):
+
+Додати в список `topic.enum`:
+
+```jsonc
+"access_key.created",
+"access_key.revoked",
+"access_key.used"
+```
+
+та окремі `allOf`-entry з `$defs`:
+
+```jsonc
+// envelope.topic = "access_key.created"
+"access_key_created": {
+  "type": "object",
+  "properties": {
+    "key_id": { "type": "string" },
+    "subject_kind": { "type": "string" },
+    "subject_id": { "type": "string" },
+    "team_id": { "type": ["string","null"] }
+  },
+  "required": ["key_id","subject_kind","subject_id"]
+}
+```
+
+аналогічні схеми для `access_key.revoked` і `access_key.used`
+(з полями `revoked_by`, `action`, `resource_kind`).
+
+4. Зв'язок з уже наявними подіями:
+
+- `staking_ringk` + `payouts` вже мають події:
+  - `"staking.locked"`
+  - `"payout.generated"`
+  - `"rwa.inventory.updated"`
+- Wallet Agent та Embassy в sequence-діаграмах нижче використовують саме ці topic-и; capability-check визначає, хто має право ініціювати або читати ці події.
+
+---
+
+## 14. Sequence-діаграми (ключові флоу)
+
+### 14.1 Wallet Agent: login → access key → capability-check → stake RINGK
+
+```mermaid
+sequenceDiagram
+    participant U as User (browser)
+    participant Auth as Auth Service
+    participant API as API Gateway
+    participant PDP as Policy Service
+    participant W as Wallet Service
+    participant BUS as NATS JetStream
+
+    U->>Auth: 1) POST /login (email+code)
+    Auth-->>U: 2) Session (JWT/cookie з user_id + capability token)
+
+    U->>API: 3) POST /wallet/stake {amount}
+    API->>PDP: 4) authorize(user_id, action=wallet.stake.ringk)
+    PDP-->>API: 5) allow / deny
+
+    API->>W: 6) create_stake_request(user_id, amount)
+    W->>BUS: 7) publish topic="staking.locked" (payload.staking_id)
+    API-->>U: 8) 200 OK (stake pending)
+
+    W->>BUS: 9) (після ончейн-обробки) publish topic="payout.generated"
+    BUS-->>U: 10) notification → Wallet Agent (claim available)
+```
+
+### 14.2 Embassy Module: external RWA → Embassy → capability-check → internal events
+
+```mermaid
+sequenceDiagram
+    participant Ext as External RWA Hub
+    participant GW as Embassy Gateway (HTTP/Webhook)
+    participant PDP as Policy Service
+    participant BUS as NATS JetStream
+
+    Ext->>GW: 1) POST /embassy/rwa {inventory_update} + access_key
+    GW->>PDP: 2) authorize(embassy_key, action=rwa.inventory.update)
+    PDP-->>GW: 3) allow / deny
+
+    GW->>BUS: 4) publish topic="rwa.inventory.updated" (payload.rwa_id, delta)
+    BUS-->>BUS: 5) downstream services (Wallet/Gift Fabric) слухають подію
+```
+
+### 14.3 Energy Union: meter → Energy Union → Embassy → payouts
+
+```mermaid
+sequenceDiagram
+    participant M as Metering Agent
+    participant EU as Energy Union Backend
+    participant Emb as Embassy Module
+    participant PDP as Policy Service
+    participant BUS as NATS JetStream
+    participant W as Wallet Service
+
+    M->>EU: 1) send meter data (kWh)
+    EU->>EU: 2) aggregate & validate
+
+    EU->>Emb: 3) POST /embassy/oracle {site, period, kWh} + access_key
+    Emb->>PDP: 4) authorize(embassy_key, action=oracle.reading.publish)
+    PDP-->>Emb: 5) allow
+
+    Emb->>BUS: 6) publish topic="oracle.reading.published"
+    BUS->>W: 7) consume oracle → compute payouts
+    W->>BUS: 8) publish topic="payout.generated" (symbol="KWT"/"1T")
+    BUS-->>Users: 9) Wallet Agent показує доступні виплати
+```
+
+---
+
+## 15. Завдання для Cursor
+
+```text
+You are a senior backend engineer. Implement the Access Keys & Capabilities System using:
+- 24_access_keys_capabilities_system.md
+- 18_governance_access_agent.md
+- 23_domains_wallet_dao_deepdive.md
+- 05_coding_standards.md
+
+Tasks:
+1) Create database schema: access_keys, capabilities, access_key_caps, bundles, bundle_caps.
+2) Implement PDP (Policy Decision Point) service.
+3) Integrate PEP (Policy Enforcement Point) into API Gateway.
+4) Implement Wallet Agent endpoints with capability checks.
+5) Create Embassy Module stub with capability validation.
+6) Add capability-check middleware for all API endpoints.
+
+Output:
+- list of modified files
+- diff
+- summary
+```
+
+---
+
+## 16. Результат
+
+Після впровадження цієї системи:
+
+- єдиний шар авторизації для всіх типів доступу (users, agents, integrations, platforms);
+- чіткий контроль прав через capabilities;
+- інтеграція з Wallet Agent та Embassy Module;
+- підготовка до масштабування та додавання нових платформ.
+

docs/microdao/architecture.md

@@ -0,0 +1,33 @@
+# MicroDAO - Огляд системи
+
+## Що таке MicroDAO
+
+MicroDAO — це приватна мережа ШІ-агентів для малих спільнот (5-50 учасників). Система дозволяє створювати спільноти (teams) з автоматичним створенням micro-DAO, публічні та приватні канали для спілкування, проєкти з задачами, базу знань (Co-Memory) та приватних ШІ-агентів, які допомагають у роботі команди.
+
+## Ключові модулі
+
+1. **Auth** — авторизація через magic-link (email)
+2. **Teams** — спільноти з автоматичним створенням micro-DAO
+3. **Channels** — публічні та приватні канали для спілкування
+4. **Messages** — повідомлення в каналах з підтримкою markdown
+5. **Co-Memory** — база знань (файли, посилання, wiki)
+6. **Follow-ups** — задачі, створені з повідомлень
+7. **Projects** — проєкти з канбан-дошками (Backlog / In Progress / Done)
+8. **Agents** — приватні ШІ-агенти для кожної спільноти
+9. **Search** — пошук по повідомленнях та документах (Meilisearch)
+
+## Режими спільнот
+
+- **Public** — публічний канал, гості можуть читати та реєструватися як глядачі (viewer-type)
+- **Confidential** — тільки запрошені учасники, E2EE для чатів, без публічного індексування
+
+## Посилання на документацію
+
+- `01_product_brief_mvp.md` — Product Requirements для MVP
+- `02_architecture_basics.md` — Технічна архітектура
+- `03_api_core_snapshot.md` — API контракти для MVP
+- `04_ui_ux_onboarding_chat.md` — UI/UX специфікація
+- `05_coding_standards.md` — Стандарти кодування
+- `06_tasks_onboarding_mvp.md` — Задачі для реалізації
+- `07_testing_checklist_mvp.md` — Чеклист тестування
+

docs/microdao/rbac.md

@@ -0,0 +1,409 @@
+# 48 — Teams Access Control & Confidential Mode (MicroDAO)
+
+*Командні доступи, ролі, членство, ACL, confidential mode, індексація, інструменти, агенти, governance-політики. Канонічна специфікація microDAO команд.*
+
+---
+
+## 1. Purpose & Scope
+
+Цей документ визначає:
+
+- структуру команд (microDAO),
+- ролі та дозволи,
+- ACL для ресурсів,
+- поведінку Confidential Mode,
+- вплив на агентів, інструменти, чат, LLM Proxy, Router, Wallet, Embassy, Projects/Tasks,
+- правила Governance.
+
+Це центральний рівень контролю безпеки й приватності у DAARION.city.
+
+---
+
+## 2. Team (microDAO) Model
+
+Команда = організаційний домен, який має:
+
+- учасників (members),
+- ролі,
+- командні налаштування,
+- власну економіку (1T / KWT / RINGK стейк),
+- власний набір агентів,
+- власні канали,
+- власні ACL.
+
+---
+
+## 3. Team Roles
+
+| Role         | Capabilities                                            | Опис                 |
+| ------------ | ------------------------------------------------------- | -------------------- |
+| **Owner**    | повний контроль, зміна налаштувань, звільнення Guardian | creator of team      |
+| **Guardian** | майже все, крім знищення команди                        | security + oversight |
+| **Admin**    | керування каналами/агентами/ресурсами                   | operational          |
+| **Member**   | доступ до основних інструментів                         | worker               |
+| **Guest**    | читання + обмежені інструменти                          | limited              |
+| **Agent**    | системний агент команди                                 | restricted           |
+
+Команда може мати:
+
+- 1 owner
+- 0–N guardians
+- 0–N admins
+- 0–N members
+- 0–N guests
+- 0–N private agents
+
+---
+
+## 4. Role Capability Mapping
+
+### Owner
+
+- повний доступ
+- оновлювати план
+- додавати/видаляти членів
+- змінювати confidential mode
+- випускати токени команди (якщо дозволено governance)
+
+### Guardian
+
+- контролює security sensitive
+- додавання агентів
+- доступ до private channels
+- керування ACL
+- активація E2EE
+
+### Admin
+
+- створення каналів
+- створення проектів
+- керування задачами
+- запуск agent flows
+
+### Member
+
+- участь у каналах
+- запуск агентів (якщо дозволено)
+- створення задач у публічних проєктах
+
+### Guest
+
+- читання
+- обмежені інструменти
+- немає доступу до agent visibility
+
+### Agent
+
+- діє через PDP
+- може діяти лише у дозволених каналах/проєктах
+- не має власних ролей
+
+---
+
+## 5. Team-Level ACL
+
+У команді існує ACL для кожного типу ресурсу:
+
+```text
+RESOURCE → [allowed_roles]
+```
+
+Приклад:
+
+### Projects
+
+```text
+create: [owner, guardian, admin]
+read: [owner, guardian, admin, member]
+update: [owner, guardian, admin]
+delete: [owner, guardian]
+```
+
+### Channels
+
+```text
+create: [owner, guardian, admin]
+read/write: залежить від channel.acl
+```
+
+### Agents
+
+```text
+create: [owner, guardian]
+update: [owner, guardian]
+run: [owner, guardian, member] (опційно)
+```
+
+### Wallet
+
+```text
+view: [owner, guardian]
+tx: [owner]
+claim: [owner, guardian]
+```
+
+### Embassy Data
+
+```text
+read: [owner, guardian]
+write: none (тільки embassy service)
+```
+
+---
+
+## 6. Team States
+
+Команда може перебувати в станах:
+
+- **active** — нормальна робота
+- **locked** — тимчасове блокування (борги, порушення)
+- **confidential** — підвищена приватність
+- **suspended** — потребує KYC / security audit
+- **archived** — команда закрита
+
+---
+
+## 7. Confidential Mode
+
+Confidential Mode — це **режим максимального захисту** для команд.
+
+### Увімкнення:
+
+лише Owner або Guardian
+
+### Поведінка:
+
+#### 7.1 LLM Proxy
+
+- не бачить plaintext повідомлень
+- використовує summary-only режим
+- vision вимкнено
+- embedding робиться з redacted тексту
+
+#### 7.2 Agents
+
+- не отримують plaintext
+- не можуть використовувати tools категорії C/D
+- не можуть використовувати platform tools
+- autonomy знижується на 1 рівень
+- не можуть запускати subagents
+
+#### 7.3 Messaging
+
+- повідомлення не зберігаються у plaintext
+- DM канал між Owner та Guardian → E2EE only
+- file attachments encrypt-only
+- retention: 0–30 днів
+
+#### 7.4 Projects/Tasks
+
+- task description → summary-only
+- файли завжди E2EE
+- agent-run logs → redacted
+
+#### 7.5 Wallet/RWA
+
+- доступ обмежений Owner/Guardian
+- payouts проходять без content-level history
+- RWA дані теж redacted
+
+---
+
+## 8. Team Privacy Layers
+
+Рівні приватності:
+
+| Level        | Description                       |
+| ------------ | --------------------------------- |
+| open         | звичайний режим                   |
+| restricted   | менш видимі канали                |
+| private      | DM-like behavior                  |
+| confidential | максимальний захист, summary-only |
+
+---
+
+## 9. Team Settings Schema
+
+```json
+{
+  "team_id": "t_444",
+  "name": "GreenFood Hub",
+  "plan": "Premium",
+  "confidential": true,
+  "settings": {
+    "agents_enabled": true,
+    "allow_subagents": false,
+    "allow_router_flows": true,
+    "file_storage_limit_mb": 5000,
+    "agent_default_autonomy": "low"
+  },
+  "acl_overrides": {
+    "wallet.view": ["owner","guardian"],
+    "wallet.tx": ["owner"],
+    "projects.create": ["owner","guardian","admin"]
+  }
+}
+```
+
+---
+
+## 10. PDP Integration
+
+PDP оцінює дію:
+
+- роль користувача
+- ACL ресурсу
+- командний стан
+- confidential mode
+- usage
+- план команди
+- stake RINGK
+
+Висновок:
+
+```text
+allow | deny | require-confirmation
+```
+
+---
+
+## 11. Governance Controls
+
+Governance може:
+
+- змінювати allowed roles
+- визначати максимальну автономію агентів
+- вмикати/вимикати confidential mode для певного плану
+- вводити policy templates для ACL
+- встановлювати KYC-вимоги
+- заморожувати команди, що порушили правила
+
+---
+
+## 12. Membership Lifecycle
+
+### Create Team:
+
+- Owner створює
+- Дається початковий ACL
+
+### Invite Member:
+
+- Owner/Admin може запросити → role=member
+
+### Promote:
+
+- Member → Admin → Guardian
+
+### Demote:
+
+- лише Owner може демотити Guardian
+
+### Remove:
+
+- Owner або Guardian (якщо не Owner)
+
+---
+
+## 13. Agent Integration Rules
+
+Агенти:
+
+- самі не мають ролей
+- використовують access keys
+- діють тільки через PDP
+- бачать тільки те, що канал/проект дозволяє
+- у confidential mode → summary-only
+- не можуть змінювати ACL
+- не можуть виконувати wallet.tx
+
+---
+
+## 14. Examples
+
+### Example 1 — Створення приватного каналу
+
+```text
+roles: [owner, guardian]
+confidential: false
+```
+
+### Example 2 — Канал для автономного агента
+
+```text
+roles: [owner, guardian, member]
+agents_allowed: [ag_777]
+confidential: false
+```
+
+### Example 3 — Канал у confidential mode
+
+```text
+type: confidential
+agents_allowed: []
+raw disabled
+summary-only
+```
+
+---
+
+## 15. Integration with Other Docs
+
+Цей документ доповнює:
+
+- `47_messaging_channels_and_privacy_layers.md`
+- `32_policy_service_PDP_design.md`
+- `36_agent_runtime_isolation_and_sandboxing.md`
+- `45_llm_proxy_and_multimodel_routing.md`
+- `46_router_orchestrator_design.md`
+- `40_rwa_energy_food_water_flow_specs.md`
+
+---
+
+## 16. Завдання для Cursor
+
+```text
+You are a senior backend engineer. Implement Teams Access Control & Confidential Mode using:
+- 48_teams_access_control_and_confidential_mode.md
+- 32_policy_service_PDP_design.md
+- 47_messaging_channels_and_privacy_layers.md
+
+Tasks:
+1) Define Team Roles (Owner, Guardian, Admin, Member, Guest, Agent) with capabilities.
+2) Implement Role Capability Mapping (per role permissions).
+3) Create Team-Level ACL (Projects, Channels, Agents, Wallet, Embassy Data).
+4) Implement Team States (active, locked, confidential, suspended, archived).
+5) Add Confidential Mode (LLM Proxy behavior, Agents restrictions, Messaging rules, Projects/Tasks rules, Wallet/RWA rules).
+6) Implement Team Privacy Layers (open, restricted, private, confidential).
+7) Create Team Settings Schema (JSON config with settings and ACL overrides).
+8) Integrate with PDP (role, ACL, team state, confidential mode, usage, plan, stake evaluation).
+9) Add Governance Controls (allowed roles, agent autonomy, confidential mode activation, ACL templates, KYC requirements, team freezing).
+10) Implement Membership Lifecycle (Create Team, Invite Member, Promote, Demote, Remove).
+11) Add Agent Integration Rules (no roles, access keys, PDP-only, channel/project permissions, confidential mode restrictions, no ACL changes, no wallet.tx).
+
+Output:
+- list of modified files
+- diff
+- summary
+```
+
+---
+
+## 17. Summary
+
+Система команд (microDAO):
+
+- має строгі ролі та ACL
+- повністю інтегрована з PDP
+- визначає дозволи для projects/tasks/wallet/agents
+- підтримує confidential mode (summary-only, no plaintext, no vision)
+- гарантує приватність даних
+- дозволяє побудову складних робочих просторів
+- є фундаментом безпеки та організації в DAARION OS
+
+---
+
+**Версія:** 1.0  
+**Останнє оновлення:** 2024-11-14
+
+