feat: align agent/microdao model - add is_orchestrator, is_platform, hierarchy

docs/internal/architecture/DAARION_AGENT_MICRODAO_MODEL_v1.md

@@ -0,0 +1,139 @@
+# DAARION Agent & MicroDAO Model v1
+
+## Overview
+
+This document describes the unified data model for Agents and MicroDAOs in the DAARION ecosystem.
+
+## Core Hierarchy
+
+```
+Node → Agent → MicroDAO
+         ↓
+    Platform (District)
+```
+
+- **Node**: Physical/virtual infrastructure where agents run (NODE1, NODE2)
+- **Agent**: AI entity with identity, capabilities, and affiliations
+- **MicroDAO**: Organization/community of agents with shared goals
+- **Platform/District**: Top-level MicroDAO that acts as a category/district
+
+## Agent Model
+
+### Key Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | text | Unique identifier |
+| `slug` | text | URL-friendly identifier |
+| `display_name` | text | Human-readable name |
+| `kind` | text | Type: orchestrator, security, marketing, etc. |
+| `node_id` | text | Home node where agent runs |
+| `is_public` | boolean | Visible in public Citizens catalog |
+| `visibility_scope` | text | Access level: global, microdao, private |
+| `is_orchestrator` | boolean | Can create/manage microDAOs |
+| `primary_microdao_id` | text | Primary organization affiliation |
+
+### Visibility Scope Values
+
+- **global**: Visible to everyone in the city
+- **microdao**: Visible only to MicroDAO members
+- **private**: Visible only to owner/admin
+
+### Agent Types by Kind
+
+- `orchestrator`: MicroDAO leaders, can manage organizations
+- `security`: Security and audit agents
+- `marketing`: Marketing and communication agents
+- `developer`: Development and technical agents
+- `research`: Research and analysis agents
+- `finance`: Financial management agents
+- `system`: Infrastructure and monitoring agents
+
+## MicroDAO Model
+
+### Key Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | text | Unique identifier |
+| `slug` | text | URL-friendly identifier |
+| `name` | text | Display name |
+| `is_public` | boolean | Visible in public services |
+| `is_platform` | boolean | Is a platform/district (top-level) |
+| `orchestrator_agent_id` | text | Main orchestrator agent |
+| `parent_microdao_id` | text | Parent for hierarchy |
+| `district` | text | District/category name |
+
+### MicroDAO Types
+
+- **Platform** (`is_platform = true`): Top-level organizational unit (district)
+- **Regular** (`is_platform = false`): Standard MicroDAO under a platform
+
+### Hierarchy
+
+```
+Platform (District)
+├── MicroDAO 1
+│   ├── Agent A (orchestrator)
+│   ├── Agent B (member)
+│   └── Agent C (member)
+└── MicroDAO 2
+    ├── Agent D (orchestrator)
+    └── Agent E (member)
+```
+
+## UI Mapping
+
+### Agent Console (`/agents`)
+- Technical view of all agents
+- Shows: node_id, visibility_scope, is_orchestrator
+- Filters: kind, node_id, microdao_id, is_public
+
+### Citizens (`/citizens`)
+- Public view of agents (`is_public = true`)
+- Shows: display_name, title, tagline, skills
+- Filters: district, kind, search
+
+### MicroDAO Dashboard (`/microdao`)
+- Organization management
+- Shows: member_count, orchestrator, channels
+- Filters: district, is_platform, is_public
+
+## API Endpoints
+
+### Agents
+```
+GET /city/agents
+    ?kind=orchestrator
+    &node_id=node-1-hetzner-gex44
+    &microdao_id=dao_daarion
+    &is_public=true
+    &visibility_scope=global
+    &include_system=false
+```
+
+### MicroDAOs
+```
+GET /city/microdao
+    ?district=Core
+    &is_public=true
+    &is_platform=false
+    &q=search
+
+GET /city/microdao/{slug}
+```
+
+## Important Notes
+
+1. **Citizen ≠ separate entity**: Citizens are just public agents (`is_public = true`)
+2. **Every agent needs MicroDAO**: Active agents must belong to at least one MicroDAO
+3. **Orchestrators**: Agents with `is_orchestrator = true` can manage MicroDAOs
+4. **Soft delete**: Use `is_archived`, `is_test`, `deleted_at` instead of hard delete
+
+## Related Files
+
+- Models: `services/city-service/models_city.py`
+- Repository: `services/city-service/repo_city.py`
+- Routes: `services/city-service/routes_city.py`
+- Migrations: `migrations/026_align_agent_microdao_model.sql`
+