Merge pull request '[ORCH-134] Update root documentation' (#331) from feature/235-update-root-docs into develop

Reviewed-on: #331

README.md

@@ -110,6 +110,8 @@ docker compose down
 - Valkey (Redis-compatible cache)
 - Mosaic API (NestJS)
 - Mosaic Web (Next.js)
+- Mosaic Orchestrator (Agent lifecycle management)
+- Mosaic Coordinator (Task assignment & monitoring)
 - Authentik OIDC (optional, use `--profile authentik`)
 - Ollama AI (optional, use `--profile ollama`)
 
@@ -124,13 +126,29 @@ mosaic-stack/
 │   │   ├── src/
 │   │   │   ├── auth/             # BetterAuth + Authentik OIDC
 │   │   │   ├── prisma/           # Database service
+│   │   │   ├── coordinator-integration/ # Coordinator API client
 │   │   │   └── app.module.ts     # Main application module
 │   │   ├── prisma/
 │   │   │   └── schema.prisma     # Database schema
 │   │   └── Dockerfile
-│   └── web/                      # Next.js 16 frontend (planned)
+│   ├── web/                      # Next.js 16 frontend
-│       ├── app/
+│   │   ├── app/
-│       ├── components/
+│   │   ├── components/
+│   │   │   └── widgets/          # HUD widgets (agent status, etc.)
+│   │   └── Dockerfile
+│   ├── orchestrator/             # Agent lifecycle & spawning (NestJS)
+│   │   ├── src/
+│   │   │   ├── spawner/          # Agent spawning service
+│   │   │   ├── queue/            # Valkey-backed task queue
+│   │   │   ├── monitor/          # Health monitoring
+│   │   │   ├── git/              # Git worktree management
+│   │   │   └── killswitch/       # Emergency agent termination
+│   │   └── Dockerfile
+│   └── coordinator/              # Task assignment & monitoring (FastAPI)
+│       ├── src/
+│       │   ├── webhook.py        # Gitea webhook receiver
+│       │   ├── parser.py         # Issue metadata parser
+│       │   └── security.py       # HMAC signature verification
 │       └── Dockerfile
 ├── packages/
 │   ├── shared/                   # Shared types & utilities
@@ -159,23 +177,36 @@ mosaic-stack/
 └── pnpm-workspace.yaml           # Workspace configuration
 ```
 
+## Agent Orchestration Layer (v0.0.6)
+
+Mosaic Stack includes a sophisticated agent orchestration system for autonomous task execution:
+
+- **Orchestrator Service** (NestJS) - Manages agent lifecycle, spawning, and health monitoring
+- **Coordinator Service** (FastAPI) - Receives Gitea webhooks, assigns tasks to agents
+- **Task Queue** - Valkey-backed queue for distributed task management
+- **Git Worktrees** - Isolated workspaces for parallel agent execution
+- **Killswitch** - Emergency stop mechanism for runaway agents
+- **Agent Dashboard** - Real-time monitoring UI with status widgets
+
+See [Agent Orchestration Design](docs/design/agent-orchestration.md) for architecture details.
+
 ## Current Implementation Status
 
-### ✅ Completed (v0.0.1)
+### ✅ Completed (v0.0.1-0.0.6)
 
-- **Issue #1:** Project scaffold and monorepo setup
+- **M1-Foundation:** Project scaffold, PostgreSQL 17 + pgvector, Prisma ORM
-- **Issue #2:** PostgreSQL 17 + pgvector database schema
+- **M2-MultiTenant:** Workspace isolation with RLS, team management
-- **Issue #3:** Prisma ORM integration with tests and seed data
+- **M3-Features:** Knowledge management, tasks, calendar, authentication
-- **Issue #4:** Authentik OIDC authentication with BetterAuth
+- **M4-MoltBot:** Bot integration architecture (in progress)
+- **M6-AgentOrchestration:** Orchestrator service, coordinator, agent dashboard ✅
 
-**Test Coverage:** 26/26 tests passing (100%)
+**Test Coverage:** 2168+ tests passing
 
 ### 🚧 In Progress (v0.0.x)
 
-- **Issue #5:** Multi-tenant workspace isolation (planned)
+- Agent orchestration E2E testing
-- **Issue #6:** Frontend authentication UI ✅ **COMPLETED**
+- Usage budget management
-- **Issue #7:** Activity logging system (planned)
+- Performance optimization
-- **Issue #8:** Docker compose setup ✅ **COMPLETED**
 
 ### 📋 Planned Features (v0.1.0 MVP)