<div align="center">

<img src="assets/vapora.svg" alt="Vapora Logo" width="400">


🌊 Intelligent Development Orchestration Platform  <br>
🎯 Specialized agents orchestrate pipelines for your team  <br>
🤖 Multi-IA router (Claude, OpenAI, Gemini, Ollama) <br>
⚡ Built with Rust from backend to frontend <br>

[![License](https://img.shields.io/badge/license-MIT%2FApache--2.0-blue.svg)](LICENSE)
[![Rust](https://img.shields.io/badge/rust-1.75%2B-orange.svg)](https://www.rust-lang.org)
[![Kubernetes](https://img.shields.io/badge/kubernetes-ready-326CE5.svg)](https://kubernetes.io)
[![Istio](https://img.shields.io/badge/istio-service%20mesh-466BB0.svg)](https://istio.io)
[![Tests](https://img.shields.io/badge/tests-691%20passing-green.svg)](crates/)

[Features](#features) • [Quick Start](#quick-start) • [Architecture](#architecture) • [Docs](docs/) • [Contributing](#contributing)

</div>

  ---

  ```txt
  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
      ╦  ╦╔═╗╔═╗╔═╗╦═╗╔═╗
      ╚╗╔╝╠═╣╠═╝║ ║╠╦╝╠═╣
       ╚╝ ╩ ╩╩  ╚═╝╩╚═╩ ╩
  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
      Vaporate complexity
  Where ideas vaporize into reality
```

 ## 🌟 What is Vapora?

  **VAPORA** is a **23-crate Rust workspace** (691 tests, 100% pass rate) delivering an **intelligent development orchestration platform** where teams and AI agents collaborate seamlessly to solve the 4 critical problems in parallel:

  - ✅ **Context Switching** (Developers unified in one system instead of jumping between tools)
  - ✅ **Knowledge Fragmentation** (Team decisions, code, and docs discoverable with RAG)
  - ✅ **Manual Coordination** (Specialized agents orchestrate pipelines automatically)
  - ✅ **Dev-Ops Friction** (Unified visibility from code changes through deployment)

  Additional capabilities:
  - 🤖 **Specialized agents** (Architect, Developer, Reviewer, Tester, Documenter, Marketer, Presenter, DevOps, Monitor, Security, ProjectManager, DecisionMaker - customizable & extensible)
  - 🧠 **Multi-IA intelligent routing** (Claude, OpenAI, Gemini, Ollama selected per task)
  - ☁️ **Self-hosted on Kubernetes** (no SaaS, complete control, Provisioning-based deployment)

  ### Key Highlights

  - **🎨 Glassmorphism UI**: Vaporwave aesthetics with UnoCSS, Leptos reactive WASM
  - **🤖 Specialized Agent Orchestration**: NATS JetStream coordination, parallel pipeline execution with approval gates
  - **🧠 Multi-IA Router**: Hybrid routing (rules + dynamic + manual override) for optimal LLM per task
  - **🚀 Full-Stack Rust**: Frontend (Leptos), Backend (Axum), Agents, Infrastructure
  - **☁️ K8s Native**: Istio service mesh, Rook Ceph storage, Cedar policy engine RBAC
  - **📚 RAG Integration**: Semantic search over Vapora docs, guides, code, and project materials
  - **🔒 Multi-Tenant**: SurrealDB scope isolation, fine-grained Cedar policies, complete audit trails

  ---

## Features

  ### 📋 Project Management

  - **Kanban Board**: Drag-and-drop tasks across Todo → Doing → Review → Done columns
  - **Real-time Collaboration**: Optimistic updates for instant UI feedback
  - **Smart Organization**: Feature tags, priority levels, task ordering
  - **Responsive Design**: Works seamlessly from mobile to ultra-wide displays

### 🔄 Workflow Orchestrator (v1.2.0)

- **Multi-Stage Pipelines**: Orchestrate complex workflows with approval gates
- **Short-Lived Agent Contexts**: 95% cache token reduction (from $840/month to $110/month)
- **Artifact Passing**: ADR, Code, TestResults, Review, Documentation artifacts between stages
- **Kogral Integration**: Automatic context enrichment from `.kogral/` filesystem (guidelines, patterns, ADRs)
- **CLI Management**: 6 commands (start, list, status, approve, cancel, templates)
- **Event-Driven Coordination**: NATS pub/sub for workflow stage progression
- **4 Workflow Templates**:
  - `feature_development` (5 stages: design → implementation → testing → review → deployment)
  - `bugfix` (4 stages: investigation → fix → testing → deployment)
  - `documentation_update` (3 stages: creation → review → publish)
  - `security_audit` (4 stages: analysis → testing → remediation → verification)

### 🧩 Recursive Language Models (RLM) - Long-Context Reasoning (v1.3.0)

- **Distributed Reasoning**: Process documents >100k tokens without context rot
- **Hybrid Search**: BM25 (keywords) + Semantic (embeddings) + RRF fusion for optimal retrieval
- **Chunking Strategies**: Fixed-size, semantic (sentence-aware), code-aware (AST-based for Rust/Python/JS)
- **Sandbox Execution**: WASM tier (<10ms) + Docker tier (80-150ms) with automatic tier selection
- **Multi-Provider LLM**: OpenAI, Claude, Ollama integration with cost tracking
- **Knowledge Graph**: Temporal execution history with hybrid retrieval — HNSW (semantic) + BM25 (lexical) + RRF fusion via SurrealDB 3 native indexes
- **Production Ready**: 38/38 tests passing, 0 clippy warnings, real SurrealDB persistence
- **Cost Efficient**: Chunk-based processing reduces token usage vs full-document LLM calls

### 🔔 Webhook Notification Channels

- **Three providers**: Slack (Incoming Webhook), Discord (Webhook embed), Telegram (Bot API) — no vendor SDKs, plain HTTP POST
- **Secret resolution at startup**: `${VAR}` / `${VAR:-default}` interpolation built into `ChannelRegistry`; a raw placeholder never reaches the HTTP layer
- **Fire-and-forget**: channel failures never surface as API errors; delivery is logged and continues for remaining targets
- **Backend events**: `on_task_done`, `on_proposal_approved`, `on_proposal_rejected`, `on_agent_inactive`
- **Workflow events**: `on_stage_complete`, `on_stage_failed`, `on_completed`, `on_cancelled` — per-workflow routing config
- **REST API**: `GET /api/v1/channels` (list), `POST /api/v1/channels/:name/test` (connectivity check)

### ♻️ Agent Hot-Reload — Zero Config-Rotation Learning Loss

- **`stable_id` identity**: Each agent carries a `stable_id = role` that is deterministic across restarts. Learning profiles and KG execution records are keyed by `stable_id`, not the ephemeral UUID, so accumulated expertise survives every reload.
- **SIGHUP reload**: `kill -HUP $(pgrep vapora-agents)` drains all executors and re-spawns them from the updated config without restarting the process.
- **`POST /reload` endpoint**: HTTP entry point for CI pipelines and operators. Returns `{"reloaded": true, "agents": N}` on success.
- **Graceful drain**: Dropping the executor `Sender` closes the mpsc channel; in-flight messages are drained before the executor exits — no tasks are lost during reload.
- **Profile persistence**: `learning_profiles` (keyed by `stable_id`) is never touched during drain/respawn. New executor instances inherit accumulated expertise immediately.

### 🧠 Intelligent Learning & Cost Optimization

- **Per-Task-Type Learning**: Agents build expertise profiles from execution history
- **Recency Bias**: Recent performance weighted 3x (last 7 days) for adaptive selection
- **Budget Enforcement**: Hard caps per role (monthly/weekly) with automatic fallback
- **Cost-Efficient Routing**: Quality/cost ratio optimization for provider selection
- **Learning Curves**: Track agent improvement over time with confidence scoring
- **Prometheus Metrics**: Real-time budget utilization, fallback triggers, cost per provider
- **Gradual Production Rollout**: 4-week canary deployment with automated rollback

  ### 🤖 Specialized AI Agents (Customizable & Extensible)

  Select, tune, or extend agents for your pipeline orchestration needs. Default agents include:

  **Parallel Agent Coordination**:
  - 🏗️ **Architect** (Claude Opus): System design & ADRs
  - 💻 **Developer** (Claude Sonnet): Code implementation [scales 5-20]
  - 👀 **CodeReviewer** (Claude Sonnet): Quality assurance & CR
  - 🧪 **Tester** (Claude Sonnet): Tests & benchmarks
  - 📚 **Documenter** (GPT-4): Docs & root files
  - 📢 **Marketer** (Claude Sonnet): Marketing content
  - 🎤 **Presenter** (Claude Sonnet): Presentations & slides
  - ⚙️ **DevOps** (Claude Sonnet): CI/CD & deployment
  - 👁️ **Monitor** (Gemini Flash): Health & alerting [real-time]
  - 🔒 **Security** (Claude Opus): Audit & compliance [can block]
  - 📊 **ProjectManager** (Claude Sonnet): Roadmap & tracking
  - 🎯 **DecisionMaker** (Claude Opus): Conflict resolution

  **Multi-IA Router**: Transparent LLM selection per task context
  - ✅ Automatic selection based on task complexity/latency/cost
  - ✅ Manual override capability with audit logging
  - ✅ Fallback chains (e.g., Claude Opus → GPT-4 → Claude Sonnet)
  - ✅ Cost tracking & budget alerts per agent role
  - ✅ **Learning-based agent selection**: Agents improve from execution history
  - ✅ **Budget enforcement**: Per-role cost limits with automatic fallback
  - ✅ **Cost-efficient routing**: Quality/cost optimization per task type

  ### 🏗️ Infrastructure

  - **Kubernetes Native**: Built for K8s (K3s, RKE2, or vanilla)
  - **Istio Service Mesh**: mTLS, circuit breakers, rate limiting out of the box
  - **Secrets Management**: RustyVault or Cosmian KMS (Rust-native)
  - **Storage**: Rook Ceph for distributed persistent volumes
  - **CI/CD**: Tekton Pipelines with Gitea integration
  - **Registry**: Zot for lightweight OCI artifact storage
  - **Observability**: Prometheus + Grafana + Loki + Tempo + Kiali

  ---

  ## 🛠️ Tech Stack

  ### Backend

<pre>
  Rust                 Async runtime with Tokio
  Axum                 Fast, ergonomic web framework
  SurrealDB            Multi-model database with scopes
  NATS JetStream       Message queue for agent jobs
  Rig                  AI agent framework
  fastembed            Local embeddings for RAG
</pre>

  ### Frontend

<pre>
  Leptos               Reactive Rust WASM framework
  UnoCSS               Instant on-demand atomic CSS
  leptos-use           Hooks and utilities
  thaw                 Component library
</pre>

  ### Infrastructure

<pre>
  Kubernetes           Orchestration (K3s/RKE2)
  Istio                Service mesh + ingress
  Rook Ceph            Distributed storage
  Tekton               Cloud-native CI/CD
  RustyVault           Secrets management
  Zot                  OCI registry
  Gitea                Self-hosted Git
</pre>

  ### Agents & LLM

<pre>
  Rig                  LLM agent framework with tool calling
  fastembed            Local embeddings for semantic search (RAG)
  RLM (vapora-rlm)     Recursive Language Models for long-context reasoning
  Tantivy              BM25 full-text search for hybrid retrieval
  NATS JetStream       Message queue for async agent coordination
  Cedar                Policy engine for fine-grained RBAC
  MCP Gateway          Model Context Protocol plugin system
  Learning Profiles    Per-task-type expertise with recency bias
  Budget Manager       Per-role cost limits with automatic fallback
  Knowledge Graph      Temporal execution history with learning curves
  Claude API           Anthropic Claude (Opus, Sonnet, Haiku)
  OpenAI API           GPT-4, GPT-4o, GPT-3.5-turbo
  Gemini API           Google Gemini (2.0 Pro, Flash, 1.5 Pro)
  Ollama               Local LLMs (Llama 2, Mistral, etc.)
</pre>

  ---

## Quick Start

  ### Prerequisites

  - **Rust 1.75+** ([rustup](https://rustup.rs))
  - **Node.js 20+** (for UnoCSS)
  - **Docker** (for local development)
  - **Kubernetes cluster** (for production)

  ### Local Development

  ```bash
  # Clone the repository
  git clone https://github.com/vapora-platform/vapora
  cd vapora

  # Install dependencies
  cargo build

  # Available Just recipes (50+ commands)
  just help              # Show all available recipes
  just help build        # Show build recipes
  just help test         # Show test recipes
  just help ci           # Show CI recipes

  # Setup SurrealDB (Docker)
  docker run -d --name surrealdb \
    -p 8000:8000 \
    surrealdb/surrealdb:latest \
    start --bind 0.0.0.0:8000 file://data/database.db

  # Run migrations
  cd migrations && surrealdb import --conn http://localhost:8000 *.surql

  # Start backend
  cd crates/vapora-backend
  cargo run

  # Start frontend (new terminal)
  cd crates/vapora-frontend
  trunk serve

  # Install CLI (optional - for workflow management)
  cd crates/vapora-cli
  cargo build --release
  cp target/release/vapora ~/.local/bin/

  # CLI Usage
  vapora workflow start --template feature_development
  vapora workflow list
  vapora workflow status <id>
  vapora workflow approve <id> --approver "Your Name"

  Visit http://localhost:3000 🎉

  Docker Compose (Full Stack)

  docker compose up -d

  Includes: Backend, Frontend, SurrealDB, NATS, MCP Gateway

```

### Production Deployment (Kubernetes)

```bash
# Build and push Docker images
nu scripts/build-docker.nu --registry docker.io --tag v1.2.0 --push

# Update secrets
edit kubernetes/03-secrets.yaml  # Add your API keys

# Deploy to Kubernetes
nu scripts/deploy-k8s.nu

# Or use Provisioning (advanced)
cd provisioning/vapora-wrksp
provisioning workflow run workflows/deploy-full-stack.yaml
```

**See full deployment guide**: [`Deployment Guide`](docs/setup/deployment.md)

  ---

## Architecture

### System Architecture Diagram

<div align="center">
  <img src="assets/vapora_architecture.svg" alt="VAPORA Architecture Diagram" width="100%">
</div>

**Interactive SVG with animated data flows** - Open the [full diagram](assets/vapora_architecture.svg) to see particle animations along connection paths.

Alternative versions:
- [Dark theme](assets/vapora_architecture.svg) (default - slate background)
- [Light theme](assets/vapora_architecture_white.svg) (white background)

### Architecture Layers

The system is organized in 5 architectural layers:

**1. Presentation Layer**
- Leptos WASM Frontend with Kanban board and glassmorphism UI

**2. Services Layer**
- Axum Backend API (40+ REST endpoints)
- Agent Runtime (orchestration, learning profiles)
- MCP Gateway (Model Context Protocol, plugin system)
- A2A Protocol (Agent-to-Agent communication)

**3. Intelligence Layer**
- RLM Engine (hybrid search: BM25 + Semantic + RRF)
- Multi-IA LLM Router (budget enforcement, cost tracking)
- Swarm Coordinator (load balancing, Prometheus metrics)

**4. Data Layer**
- Knowledge Graph (temporal history, learning curves)
- SurrealDB (multi-model database, multi-tenant)
- NATS JetStream (message queue, async coordination)

**5. LLM Providers**
- Anthropic Claude (Opus, Sonnet, Haiku)
- OpenAI (GPT-4, GPT-4o, GPT-3.5)
- Google Gemini (2.0 Pro, Flash, 1.5 Pro)
- Ollama (local LLMs: Llama, Mistral, CodeLlama)

### Data Flow

1. User interacts with Leptos UI (Kanban board)
2. Frontend → Backend API (REST endpoints)
3. Backend → Agent Runtime (task assignment)
4. Agent Runtime → LLM Router (provider selection with budget enforcement)
5. LLM Router → Providers (Claude/OpenAI/Gemini/Ollama)
6. RLM Engine processes long-context tasks (hybrid search + distributed reasoning)
7. All data persisted in SurrealDB with multi-tenant isolation
8. NATS JetStream coordinates async agent workflows
9. Results streamed back to UI with optimistic updates

  ---
  📸 Screenshots

  Kanban Board with Glassmorphism

```
  ┌─────────────────────────────────────────────────────────┐
  │  Vapora         🔍 Search    Projects  Agents  + New    │
  ├─────────────────────────────────────────────────────────┤
  │                                                         │
  │            📌       🔵        🟣        ✅                │
  │       ┌─────────┬─────────┬─────────┬─────────┐         │
  │       │  TODO   │  DOING  │ REVIEW  │    DONE │         │
  │       │   (5)   │   (3)   │   (2)   │  (12)   │         │
  │       ├─────────┼─────────┼─────────┼─────────┤         │
  │       │ ┌─────┐ │ ┌─────┐ │ ┌─────┐ │ ┌─────┐ │         │
  │       │ │Task │ │ │Task │ │ │Task │ │ │Task │ │         │
  │       │ │Card │ │ │Card │ │ │Card │ │ │Card │ │         │
  │       │ └─────┘ │ └─────┘ │ └─────┘ │ └─────┘ │         │
  │       │         │         │         │         │         │
  │       │  Glass  │ Neon    │ Vapor   │ Fluid   │         │
  │       │  Blur   │ Glow    │ Waves   │ Motion  │         │
  │       └─────────┴─────────┴─────────┴─────────┘         │
  └─────────────────────────────────────────────────────────┘
```

  Agent Plugin Marketplace

```
  ┌─────────────────────────────────────────────────────────┐
  │  MCP Plugins                             🔌 Install New │
  ├─────────────────────────────────────────────────────────┤
  │  ┌──────────────────────────────────────────┐           │
  │  │ 🔍 Code Analysis Plugin                  │           │
  │  │ Analyze code with tree-sitter + LLM      │           │
  │  │ • Rust, TypeScript, Python               │           │
  │  │ • Complexity metrics                     │           │
  │  │ [✓ Installed]                            │           │
  │  └──────────────────────────────────────────┘           │
  │                                                         │
  │  ┌──────────────────────────────────────────┐           │
  │  │ 📚 RAG Search Plugin                     │           │
  │  │ Semantic search over Vapora docs & code  │           │
  │  │ • Local embeddings (fastembed)           │           │
  │  │ • Indexes: guides/, FEATURES, .coder/    │           │
  │  │ [✓ Installed]                            │           │
  │  └──────────────────────────────────────────┘           │
  └─────────────────────────────────────────────────────────┘

```

  ---
  📦 Project Structure

```text
vapora/
├── crates/
│   ├── vapora-shared/           # Core models, errors, types
│   ├── vapora-backend/          # Axum REST API (40+ endpoints, 161 tests)
│   ├── vapora-agents/           # Agent orchestration + learning profiles (71 tests)
│   ├── vapora-llm-router/       # Multi-provider routing + budget (53 tests)
│   ├── vapora-swarm/            # Swarm coordination + Prometheus (6 tests)
│   ├── vapora-knowledge-graph/  # Temporal KG + learning curves (20 tests)
│   ├── vapora-workflow-engine/  # Multi-stage workflows + Kogral integration (26 tests)
│   ├── vapora-rlm/              # Recursive Language Models for long-context (38 tests)
│   ├── vapora-a2a/              # Agent-to-Agent protocol server (7 integration tests)
│   ├── vapora-a2a-client/       # A2A client library (5 tests)
│   ├── vapora-cli/              # CLI commands (start, list, approve, cancel, etc.)
│   ├── vapora-frontend/         # Leptos WASM UI (Kanban)
│   ├── vapora-leptos-ui/        # Leptos component library (16 components, 4 tests)
│   ├── vapora-mcp-server/       # MCP protocol gateway (1 test)
│   ├── vapora-tracking/         # Task/project storage layer (1 test)
│   ├── vapora-telemetry/        # OpenTelemetry integration (16 tests)
│   ├── vapora-analytics/        # Event pipeline + usage stats (5 tests)
│   ├── vapora-worktree/         # Git worktree management (4 tests)
│   └── vapora-doc-lifecycle/    # Documentation management (15 tests)
├── assets/
│   ├── web/                     # Landing page (optimized + minified)
│   │   ├── src/index.html      # Source (readable, 26KB)
│   │   ├── index.html          # Production (minified, 18KB)
│   │   ├── minify.sh           # Auto-minification script
│   │   └── README.md           # Web assets guide
│   └── vapora.svg              # Logo
├── kubernetes/                  # K8s manifests (base, overlays, platform)
├── migrations/                  # SurrealDB migrations
├── config/                      # Configuration files (TOML)
│   ├── vapora.toml             # Backend configuration
│   ├── agents.toml             # Agent roles and limits
│   ├── workflows.toml          # Workflow templates
│   └── agent-budgets.toml      # Budget enforcement config
└── docs/                        # Product documentation
    ├── adrs/                   # Architecture Decision Records
    ├── features/               # Feature documentation
    └── setup/                  # Installation and CLI guides

# Total: 23 crates, 691 tests (100% pass rate)
```

  ---
  🔌 MCP Plugin Development

  Create custom agents with the MCP plugin system:

```rust
  use vapora_mcp::{Plugin, Tool, Resource};

  #[derive(Plugin)]
  pub struct MyCustomPlugin;

  impl Plugin for MyCustomPlugin {
      fn name(&self) -> &str {
          "my-custom-plugin"
      }

      fn tools(&self) -> Vec<Tool> {
          vec![
              Tool::new("my_tool")
                  .description("Does something cool")
                  .parameter("input", "string")
          ]
      }
  }

  #[async_trait]
  impl ToolExecutor for MyCustomPlugin {
      async fn execute_tool(
          &self,
          tool: &str,
          params: serde_json::Value
      ) -> Result<serde_json::Value> {
          match tool {
              "my_tool" => {
                  // Your logic here
                  Ok(json!({"result": "success"}))
              }
              _ => Err(anyhow!("Unknown tool"))
          }
      }
  }
  ```

  See docs/mcp-plugins.md for full guide.

  ---
  🚢 Deployment with Provisioning

  Using Provisioning (not Helm) for declarative K8s infrastructure:

```bash
  # Navigate to Provisioning workspace
  cd provisioning/vapora-wrksp

  # Deploy full VAPORA stack (KCL + Taskservs + Workflows)
  provisioning workflow run workflows/deploy-full-stack.yaml

  # This creates:
  # - K8s cluster (K3s/RKE2) with Cilium CNI
  # - Istio service mesh with mTLS
  # - Rook Ceph storage
  # - SurrealDB (3 replicas, 50Gi storage)
  # - Redis (3 replicas, 20Gi storage)
  # - NATS JetStream (3 replicas, 30Gi storage)
  # - Axum backend (3-10 replicas)
  # - Leptos frontend (2 replicas)
  # - Agent runtime (3-50 replicas, HPA enabled)
  # - LLM Router (2-5 replicas)
  # - MCP Gateway (2-5 replicas)

  # Access UI
  open https://vapora.example.com

  # Scale developer agents
  provisioning taskserv scale vapora-agents --agent developer --replicas 15

  # Monitor health
  provisioning health-check --services all

  Environment Variables

  # Backend
  SURREAL_URL=http://surrealdb:8000
  NATS_URL=nats://nats:4222
  MCP_GATEWAY_URL=http://mcp-gateway:8080
  RUSTYVAULT_ADDR=https://rustyvault:8200

  # Frontend
  VITE_API_URL=https://api.vapora.dev

  # Secrets (stored in RustyVault)
  OPENAI_API_KEY=sk-...
  ANTHROPIC_API_KEY=sk-ant-...
```

  ---
  🧪 Testing

```bash
  # Backend tests
  cd vapora-backend
  cargo test

  # Frontend tests
  cd vapora-frontend
  cargo test --target wasm32-unknown-unknown

  # Integration tests
  cargo test --workspace

  # E2E tests (requires running services)
  ./scripts/run-e2e-tests.sh

```

  ---
  📊 Monitoring

  Access Grafana dashboards:

  kubectl port-forward -n observability svc/grafana 3000:80

  Pre-configured dashboards:
  - Vapora Overview: Request rates, latencies, errors
  - Agent Metrics: Job queue depth, execution times, token usage
  - Istio Service Mesh: Traffic flows, mTLS status
  - Ceph Storage: Capacity, IOPS, health

  ---
  📚 Documentation & Specifications

  VAPORA v1.0 is built on comprehensive specifications organized by domain:

  **Core Specifications** (guides/core/):
  - **VAPORA-ARCHITECTURE-V2.md**: 4-layer architecture (Frontend, API, Service, Data, Infrastructure)
  - **AGENT-REGISTRY-COORDINATION.md**: 12 agent roles, NATS message patterns, health checking
  - **MULTI-IA-ROUTER.md**: Hybrid routing system (rules + dynamic + override), cost tracking
  - **MULTI-AGENT-WORKFLOWS.md**: End-to-end workflows with parallel execution & approval gates
  - **ROLES-PERMISSIONS-PROFILES.md**: Cedar policy engine, team profiles, fine-grained RBAC
  - **TASK-AGENT-DOC-MANAGER-V2.md**: Multi-agent task orchestration & decision extraction

  **Integration Specifications** (guides/integration/):
  - **DOC-LIFECYCLE-INTEGRATION.md**: Dual-mode (plugin + standalone) documentation management
  - **PROVISIONING-INTEGRATION.md**: KCL schemas, taskservs, workflows for K8s deployment
  - **RAG-INTEGRATION.md**: Semantic search with hybrid retrieval & embedding strategy

  **Component Specifications** (guides/):
  - **SESSION-LIFECYCLE-MANAGER.md**: .coder/ organization, metadata extraction, decision capture
  - **ROOT-FILES-KEEPER.md**: Keep README, CHANGELOG, ROADMAP always updated
  - **MIGRATION-PLAN.md**: Gradual migration path for existing projects

  **Deployment Guide** (provisioning/vapora-wrksp/):
  - workspace.toml: Master configuration (agents, LLM, monitoring, backup)
  - taskservs/: Service definitions for backend, frontend, agents, LLM router, MCP gateway
  - kcl/: Infrastructure as Code schemas (cluster, services, storage, agents, multi-ia)
  - workflows/: Batch operations (deploy, scale, upgrade, disaster-recovery)
  - README.md: Quick start and operation guide

  **References**:
  - guides/archive/v1-single-agent/: Legacy v1.0 specifications for historical reference

  ---

## Contributing

  We welcome contributions! Please see CONTRIBUTING.md.

  Development Workflow

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing)
  3. Commit your changes (git commit -m 'Add amazing feature')
  4. Push to branch (git push origin feature/amazing)
  5. Open a Pull Request

  Code Style

  - Rust: Follow rustfmt and clippy recommendations
  - Frontend: Use UnoCSS shortcuts, avoid inline styles
  - Commits: Conventional commits (feat:, fix:, docs:, etc.)

  ---
  📄 License

  Dual-licensed under:

  - MIT License (LICENSE-MIT)
  - Apache License 2.0 (LICENSE-APACHE)

  You may choose either license.

  ---
  🙏 Acknowledgments

  Inspired by:
  - https://github.com/transcend-engineering/archon - Original glassmorphism UI concept
  - https://github.com/docker/mcp-gateway - MCP integration pattern
  - https://rook.io - Ceph storage operator
  - https://istio.io - Service mesh architecture

  Built with ❤️ using Rust 🦀

  ---
  🔗 Links

  - Website: https://vapora.dev
  - Documentation: https://docs.vapora.dev
  - GitHub: https://github.com/vapora-platform/vapora
  - Discord: https://discord.gg/vapora
  - Twitter: https://twitter.com/VaporaPlatform

  ---
  #readme

  Made with vaporwave dreams and Rust reality ✨

  ---
  Archivos Adicionales Recomendados

  CONTRIBUTING.md

  # Contributing to Vapora

  Thank you for your interest in contributing to Vapora!

  ## Code of Conduct

  Be respectful, inclusive, and constructive.

  ## Development Setup

  See [README.md](README.md#-quick-start) for setup instructions.

  ## Pull Request Process

  1. Update documentation for any API changes
  2. Add tests for new features
  3. Ensure `cargo clippy` and `cargo fmt` pass
  4. Update CHANGELOG.md

  ## Coding Standards

  - **Rust**: Idiomatic Rust, avoid `unwrap()`, use `?` operator
  - **Error Handling**: Use `anyhow::Result` for services, custom errors for API
  - **Documentation**: All public items must have doc comments
  - **Tests**: Unit tests for services, integration tests for API

  ## Commit Messages

  Follow [Conventional Commits](https://www.conventionalcommits.org/):

  feat: add code analysis plugin
  fix: resolve race condition in task reordering
  docs: update MCP plugin guide
  chore: bump dependencies


  LICENSE-MIT y LICENSE-APACHE

---

⚠️ **Brand Assets Location**: See [`./assets/`](./assets/) for complete brand system including logo variations, color palettes, and interactive preview → [Open Logo Preview](./assets/vapora_logo.html)

---
