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
This commit is contained in:
Apple
2025-11-15 04:08:35 -08:00
parent 5520665600
commit c552199eed
138 changed files with 39624 additions and 40 deletions

View File

@@ -0,0 +1,24 @@
-- 000001_init.sql
-- Up
create extension if not exists "uuid-ossp";
create extension if not exists "pgcrypto";
create extension if not exists "vector";
create table if not exists users (
id text primary key, -- u_...
email text unique not null,
created_at timestamptz not null default now(),
last_login_at timestamptz
);
create table if not exists sessions (
session_id text primary key,
user_id text not null references users(id) on delete cascade,
created_at timestamptz not null default now(),
expires_at timestamptz
);
-- Down
drop table if exists sessions cascade;
drop table if exists users cascade;

View File

@@ -0,0 +1,75 @@
-- 000002_microdao_core.sql
-- Up
create table if not exists teams (
id text primary key, -- t_...
name text not null,
slug text unique not null,
mode text not null check (mode in ('public','confidential')),
created_at timestamptz not null default now()
);
create table if not exists team_members (
team_id text not null references teams(id) on delete cascade,
user_id text not null references users(id) on delete cascade,
role text not null check (role in ('Owner','Guardian','Member')),
viewer_type text not null check (viewer_type in ('reader','commenter','contributor')),
created_at timestamptz not null default now(),
primary key (team_id, user_id)
);
create index if not exists idx_team_members_user_id
on team_members(user_id);
create table if not exists channels (
id text primary key, -- c_...
team_id text not null references teams(id) on delete cascade,
name text not null,
created_at timestamptz not null default now()
);
create index if not exists idx_channels_team_id
on channels(team_id);
create table if not exists messages (
id text primary key, -- m_...
channel_id text not null references channels(id) on delete cascade,
user_id text references users(id) on delete set null,
body text,
metadata jsonb default '{}'::jsonb,
created_at timestamptz not null default now()
);
create index if not exists idx_messages_channel_id_created_at
on messages(channel_id, created_at);
create table if not exists followups (
id text primary key, -- f_...
message_id text not null references messages(id) on delete cascade,
type text, -- agent/tool/summary/...
payload jsonb default '{}'::jsonb,
created_at timestamptz not null default now()
);
create index if not exists idx_followups_message_id
on followups(message_id);
create table if not exists comemory_items (
id text primary key,
team_id text not null references teams(id) on delete cascade,
embeddings vector(1536),
summary text,
source_message text,
created_at timestamptz not null default now()
);
create index if not exists idx_comemory_items_team_id
on comemory_items(team_id);
-- Down
drop table if exists comemory_items cascade;
drop table if exists followups cascade;
drop table if exists messages cascade;
drop table if exists channels cascade;
drop table if exists team_members cascade;
drop table if exists teams cascade;

View File

@@ -0,0 +1,37 @@
-- 000003_projects_tasks.sql
-- Up
create table if not exists projects (
id text primary key, -- p_...
team_id text not null references teams(id) on delete cascade,
name text not null,
description text,
status text not null default 'active' check (status in ('active','archived')),
created_at timestamptz not null default now(),
updated_at timestamptz
);
create index if not exists idx_projects_team_id
on projects(team_id);
create table if not exists tasks (
id text primary key, -- task_...
project_id text not null references projects(id) on delete cascade,
title text not null,
description text,
status text not null default 'todo'
check (status in ('todo','in_progress','done','cancelled')),
assignee text references users(id) on delete set null,
created_at timestamptz not null default now(),
updated_at timestamptz
);
create index if not exists idx_tasks_project_id
on tasks(project_id);
create index if not exists idx_tasks_assignee
on tasks(assignee);
-- Down
drop table if exists tasks cascade;
drop table if exists projects cascade;

View File

@@ -0,0 +1,34 @@
-- 000004_agents.sql
-- Up
create table if not exists agents (
id text primary key, -- ag_...
team_id text not null references teams(id) on delete cascade,
name text not null,
description text,
config jsonb not null default '{}'::jsonb,
created_at timestamptz not null default now(),
updated_at timestamptz
);
create index if not exists idx_agents_team_id
on agents(team_id);
create table if not exists agent_runs (
id text primary key, -- run_...
agent_id text not null references agents(id) on delete cascade,
user_id text references users(id) on delete set null,
input jsonb not null,
output jsonb,
status text not null default 'pending'
check (status in ('pending','running','completed','failed')),
created_at timestamptz not null default now(),
updated_at timestamptz
);
create index if not exists idx_agent_runs_agent_id_created_at
on agent_runs(agent_id, created_at);
-- Down
drop table if exists agent_runs cascade;
drop table if exists agents cascade;

View File

@@ -0,0 +1,40 @@
-- 000005_wallet_staking_payouts.sql
-- Up
create table if not exists wallets (
user_id text primary key references users(id) on delete cascade,
address text unique,
created_at timestamptz not null default now(),
metadata jsonb default '{}'::jsonb
);
create table if not exists staking_ringk (
id text primary key,
user_id text not null references users(id) on delete cascade,
amount numeric(30, 8) not null check (amount > 0),
lock_until timestamptz,
status text not null default 'locked' check (status in ('locked','unlocked')),
created_at timestamptz not null default now()
);
create index if not exists idx_staking_ringk_user_id
on staking_ringk(user_id);
create table if not exists payouts (
id text primary key,
user_id text not null references users(id) on delete cascade,
amount numeric(30, 8) not null check (amount > 0),
symbol text not null, -- KWT, 1T, DAAR…
status text not null default 'pending'
check (status in ('pending','claimed','cancelled')),
created_at timestamptz not null default now(),
claimed_at timestamptz
);
create index if not exists idx_payouts_user_id_status
on payouts(user_id, status);
-- Down
drop table if exists payouts cascade;
drop table if exists staking_ringk cascade;
drop table if exists wallets cascade;

View File

@@ -0,0 +1,18 @@
-- 000006_rwa.sql
-- Up
create table if not exists rwa_inventory (
id text primary key, -- rwa_...
team_id text not null references teams(id) on delete cascade,
type text not null check (type in ('energy','food','water','essence','generic')),
quantity numeric(30, 8) not null check (quantity >= 0),
unit text not null default 'unit',
metadata jsonb default '{}'::jsonb,
updated_at timestamptz not null default now()
);
create index if not exists idx_rwa_inventory_team_type
on rwa_inventory(team_id, type);
-- Down
drop table if exists rwa_inventory cascade;

View File

@@ -0,0 +1,48 @@
-- 000007_embassy.sql
-- Up
create table if not exists embassy_identities (
id text primary key, -- emb_...
external_id text not null,
platform text not null check (
platform in ('energy_union','greenfood','water_union','essence_stream','daarion_core','daarwizz')
),
user_id text references users(id) on delete set null,
team_id text references teams(id) on delete set null,
metadata jsonb default '{}'::jsonb,
created_at timestamptz not null default now()
);
create index if not exists idx_embassy_identities_platform_external
on embassy_identities(platform, external_id);
create table if not exists embassy_webhooks (
id text primary key, -- hook_...
platform text not null check (
platform in ('energy_union','greenfood','water_union','essence_stream','daarion_core','daarwizz')
),
url text not null,
secret text not null,
is_active boolean not null default true,
created_at timestamptz not null default now()
);
create index if not exists idx_embassy_webhooks_platform_active
on embassy_webhooks(platform, is_active);
create table if not exists oracles (
id text primary key,
platform text not null check (
platform in ('energy_union','greenfood','water_union','essence_stream')
),
payload jsonb not null,
created_at timestamptz not null default now()
);
create index if not exists idx_oracles_platform_created_at
on oracles(platform, created_at);
-- Down
drop table if exists oracles cascade;
drop table if exists embassy_webhooks cascade;
drop table if exists embassy_identities cascade;

View File

@@ -0,0 +1,58 @@
-- 000008_access_keys_capabilities.sql
-- Up
create table if not exists access_keys (
id text primary key, -- ak_...
subject_kind text not null
check (subject_kind in ('user','agent','integration','embassy')),
subject_id text not null, -- u_/ag_/...
team_id text references teams(id) on delete set 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,
last_used_at timestamptz
);
create index if not exists idx_access_keys_subject
on access_keys(subject_kind, subject_id);
create index if not exists idx_access_keys_team
on access_keys(team_id);
create table if not exists capabilities (
id text primary key, -- cap_...
code text not null unique, -- chat.message.send, wallet.stake.ringk, ...
description text not null
);
create table if not exists access_key_caps (
key_id text not null references access_keys(id) on delete cascade,
cap_id text not null references capabilities(id) on delete cascade,
primary key (key_id, cap_id)
);
create index if not exists idx_access_key_caps_cap_id
on access_key_caps(cap_id);
create table if not exists 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 if not exists bundle_caps (
bundle_id text not null references bundles(id) on delete cascade,
cap_id text not null references capabilities(id) on delete cascade,
primary key (bundle_id, cap_id)
);
create index if not exists idx_bundle_caps_cap_id
on bundle_caps(cap_id);
-- Down
drop table if exists bundle_caps cascade;
drop table if exists bundles cascade;
drop table if exists access_key_caps cascade;
drop table if exists capabilities cascade;
drop table if exists access_keys cascade;

View File

@@ -0,0 +1,32 @@
-- 000009_audit_outbox.sql
-- Up
create table if not exists audit_log (
id text primary key,
user_id text references users(id) on delete set null,
team_id text references teams(id) on delete set null,
action text not null,
resource_kind text,
resource_id text,
data jsonb default '{}'::jsonb,
created_at timestamptz not null default now()
);
create index if not exists idx_audit_log_team_created_at
on audit_log(team_id, created_at);
create table if not exists outbox_events (
id text primary key, -- evt_...
topic text not null,
payload jsonb not null,
created_at timestamptz not null default now(),
processed boolean not null default false,
processed_at timestamptz
);
create index if not exists idx_outbox_events_processed
on outbox_events(processed, created_at);
-- Down
drop table if exists outbox_events cascade;
drop table if exists audit_log cascade;

View File

@@ -0,0 +1,89 @@
# Database Migrations (MicroDAO)
SQL-міграції для схеми бази даних microDAO/DAARION.city
---
## Структура
Міграції розташовані в хронологічному порядку:
1. `000001_init.sql` - Users, Sessions, базові extensions
2. `000002_microdao_core.sql` - Teams, Channels, Messages, Follow-ups, Co-Memory
3. `000003_projects_tasks.sql` - Projects, Tasks
4. `000004_agents.sql` - Agents, Agent Runs
5. `000005_wallet_staking_payouts.sql` - Wallets, Staking, Payouts
6. `000006_rwa.sql` - RWA Inventory
7. `000007_embassy.sql` - Embassy Module (identities, webhooks, oracles)
8. `000008_access_keys_capabilities.sql` - Access Keys, Capabilities, Bundles
9. `000009_audit_outbox.sql` - Audit Log, Outbox Events
10. `seeds.sql` - Seed data для bundles, capabilities та bundle mappings (запускати після всіх міграцій)
---
## Використання
### З Supabase CLI
```bash
# Застосувати всі міграції локально
supabase db reset
# Застосувати seed data після міграцій
psql -d microdao -f supabase/migrations/seeds.sql
# Або застосувати конкретну міграцію
supabase migration up 000001_init
```
### З PostgreSQL напряму
```bash
# Застосувати всі міграції по порядку
psql -d microdao -f 000001_init.sql
psql -d microdao -f 000002_microdao_core.sql
# ... і так далі до 000009_audit_outbox.sql
# Після всіх міграцій застосувати seed data
psql -d microdao -f seeds.sql
```
---
## Порядок застосування
**Важливо:** Міграції повинні застосовуватися строго в порядку нумерації, оскільки вони залежать одна від одної.
---
## Seed Data
Файл `seeds.sql` містить:
- Базові capabilities (chat, wallet, agent, projects, RWA, embassy, governance, comemory)
- Прив'язку capabilities до bundle.role.* (Owner, Guardian, Member, Visitor)
- Прив'язку capabilities до bundle.plan.* (Freemium, Casual, Premium, Platformium)
---
## Rollback
Кожна міграція містить секцію `-- Down` для відкочення змін.
**Увага:**
- Outbox events не відкочуються
- RWA-поведінка не rollback'иться ніколи
- На prod rollback дозволено тільки для staging, forward-fix для prod
---
## Посилання
- Повна специфікація: `docs/cursor/27_database_schema_migrations.md`
- Access Keys System: `docs/cursor/24_access_keys_capabilities_system.md`
---
**Версія:** 1.0
**Останнє оновлення:** 2024-11-14

View File

@@ -0,0 +1,147 @@
-- seeds.sql
-- базові bundles та capabilities для microDAO / DAARION.city
-- Запускати після всіх міграцій
-- 1) Bundles
insert into bundles (id, name)
values
('bundle_role_owner', 'role.Owner'),
('bundle_role_guardian', 'role.Guardian'),
('bundle_role_member', 'role.Member'),
('bundle_role_visitor', 'role.Visitor'),
('bundle_plan_freemium', 'plan.Freemium'),
('bundle_plan_casual', 'plan.Casual'),
('bundle_plan_premium', 'plan.Premium'),
('bundle_plan_platformium', 'plan.Platformium')
on conflict (id) do nothing;
-- 2) Capabilities
insert into capabilities (id, code, description) values
-- chat / channels
('cap_chat_read', 'chat.message.read', 'Читання повідомлень у каналах'),
('cap_chat_send', 'chat.message.send', 'Надсилання повідомлень у каналах'),
('cap_chat_edit', 'chat.message.edit', 'Редагування власних повідомлень'),
('cap_chat_delete', 'chat.message.delete', 'Видалення повідомлень'),
('cap_channel_create', 'channel.create', 'Створення каналів у команді'),
('cap_channel_manage', 'channel.manage', 'Керування каналами в команді'),
-- co-memory / docs
('cap_comem_read', 'comemory.item.read', 'Читання елементів Co-Memory'),
('cap_comem_write', 'comemory.item.write', 'Створення/оновлення елементів Co-Memory'),
-- projects / tasks
('cap_project_create', 'project.create', 'Створення проєктів'),
('cap_project_manage', 'project.manage', 'Керування проєктами команди'),
('cap_task_create', 'task.create', 'Створення задач у проєктах'),
('cap_task_manage', 'task.manage', 'Керування задачами'),
-- agents / router
('cap_agent_run', 'agent.run.invoke', 'Запуск агентів (Agent Runs)'),
('cap_agent_config', 'agent.config.manage', 'Керування конфігурацією агентів'),
('cap_router_invoke', 'router.invoke', 'Виклики роутера DAARWIZZ/Swarm-OS'),
-- wallet / staking / payouts
('cap_wallet_view', 'wallet.balance.view', 'Перегляд балансів гаманця'),
('cap_wallet_stake', 'wallet.stake.ringk', 'Стейкінг токенів RINGK'),
('cap_wallet_payout_v', 'wallet.payout.view', 'Перегляд доступних виплат'),
('cap_wallet_payout_c', 'wallet.payout.claim', 'Забір (claim) виплат'),
-- RWA / Embassy
('cap_rwa_update', 'rwa.inventory.update', 'Оновлення інвентарю RWA'),
('cap_emb_rwa_claim', 'embassy.rwa.claim', 'Обробка заявок на RWA через Embassy'),
('cap_emb_energy_upd', 'embassy.energy.update', 'Оновлення енергетичних даних через Embassy'),
('cap_emb_intent_read', 'embassy.intent.read', 'Читання intent-подій через Embassy'),
-- Governance
('cap_gov_proposal', 'governance.proposal.create', 'Створення governance-пропозицій'),
('cap_gov_vote', 'governance.vote.cast', 'Голосування за пропозиції'),
('cap_gov_policy', 'governance.policy.manage', 'Керування політиками/бандлами доступу')
on conflict (id) do nothing;
-- 3) Прив'язка capabilities до role-bundles
-- Owner: максимум прав
insert into bundle_caps (bundle_id, cap_id)
select 'bundle_role_owner', id
from capabilities
on conflict (bundle_id, cap_id) do nothing;
-- Guardian: все, крім, наприклад, повної політики, якщо хочеш — тут залишимо теж усе
insert into bundle_caps (bundle_id, cap_id)
select 'bundle_role_guardian', id
from capabilities
on conflict (bundle_id, cap_id) do nothing;
-- Member: обмежений, без критичних governance/policy й agent-config
insert into bundle_caps (bundle_id, cap_id)
values
('bundle_role_member', 'cap_chat_read'),
('bundle_role_member', 'cap_chat_send'),
('bundle_role_member', 'cap_chat_edit'),
('bundle_role_member', 'cap_comem_read'),
('bundle_role_member', 'cap_comem_write'),
('bundle_role_member', 'cap_project_create'),
('bundle_role_member', 'cap_project_manage'),
('bundle_role_member', 'cap_task_create'),
('bundle_role_member', 'cap_task_manage'),
('bundle_role_member', 'cap_agent_run'),
('bundle_role_member', 'cap_router_invoke'),
('bundle_role_member', 'cap_wallet_view'),
('bundle_role_member', 'cap_wallet_stake'),
('bundle_role_member', 'cap_wallet_payout_v'),
('bundle_role_member', 'cap_wallet_payout_c')
on conflict (bundle_id, cap_id) do nothing;
-- Visitor: тільки читання
insert into bundle_caps (bundle_id, cap_id)
values
('bundle_role_visitor', 'cap_chat_read'),
('bundle_role_visitor', 'cap_comem_read')
on conflict (bundle_id, cap_id) do nothing;
-- 4) Прив'язка capabilities до plan-bundles (Entitlements)
-- Freemium: базовий чат + читання + один агент
insert into bundle_caps (bundle_id, cap_id)
values
('bundle_plan_freemium', 'cap_chat_read'),
('bundle_plan_freemium', 'cap_chat_send'),
('bundle_plan_freemium', 'cap_comem_read'),
('bundle_plan_freemium', 'cap_agent_run')
on conflict (bundle_id, cap_id) do nothing;
-- Casual: + wallet, router, tasks
insert into bundle_caps (bundle_id, cap_id)
values
('bundle_plan_casual', 'cap_chat_read'),
('bundle_plan_casual', 'cap_chat_send'),
('bundle_plan_casual', 'cap_comem_read'),
('bundle_plan_casual', 'cap_comem_write'),
('bundle_plan_casual', 'cap_agent_run'),
('bundle_plan_casual', 'cap_router_invoke'),
('bundle_plan_casual', 'cap_wallet_view'),
('bundle_plan_casual', 'cap_wallet_stake'),
('bundle_plan_casual', 'cap_wallet_payout_v'),
('bundle_plan_casual', 'cap_wallet_payout_c'),
('bundle_plan_casual', 'cap_task_create'),
('bundle_plan_casual', 'cap_task_manage')
on conflict (bundle_id, cap_id) do nothing;
-- Premium: + RWA/Embassy, governance (без policy.manage)
insert into bundle_caps (bundle_id, cap_id)
values
('bundle_plan_premium', 'cap_rwa_update'),
('bundle_plan_premium', 'cap_emb_rwa_claim'),
('bundle_plan_premium', 'cap_emb_energy_upd'),
('bundle_plan_premium', 'cap_emb_intent_read'),
('bundle_plan_premium', 'cap_gov_proposal'),
('bundle_plan_premium', 'cap_gov_vote')
on conflict (bundle_id, cap_id) do nothing;
-- Platformium: повний набір включно з governance.policy.manage
insert into bundle_caps (bundle_id, cap_id)
select 'bundle_plan_platformium', id
from capabilities
on conflict (bundle_id, cap_id) do nothing;