@bluefly/openstandardagents 0.1.9 → 0.2.5-RC

package/README.md

@@ -1,559 +1,358 @@
-# OSSA - Open Standard for Scalable Agents
+# OSSA - Open Standard for Scalable AI Agents
 
-[![OpenAPI](https://img.shields.io/badge/OpenAPI-3.1-orange.svg)](src/api/)
-[![TypeScript](https://img.shields.io/badge/TypeScript-5.3-blue.svg)](https://www.typescriptlang.org/)
-[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+**The OpenAPI for AI Agents**
 
-## Executive Summary
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+[![npm version](https://img.shields.io/npm/v/@bluefly/openstandardagents)](https://www.npmjs.com/package/@bluefly/openstandardagents)
+[![GitLab](https://img.shields.io/badge/GitLab-OSSA-orange.svg)](https://github.com/blueflyio/openstandardagents)
+[![GitHub](https://img.shields.io/badge/GitHub-OSSA-black.svg)](https://github.com/blueflyio/openstandardagents)
+[![OSSA Compliant](https://img.shields.io/badge/OSSA-Compliant-00B8D4.svg)](https://github.com/blueflyio/openstandardagents)
 
-The Open Standard for Scalable Agents (OSSA) provides a comprehensive specification framework for building, deploying, and orchestrating autonomous AI agents at enterprise scale. OSSA defines standardized interfaces, communication protocols, and governance models that enable seamless interoperability between heterogeneous agent systems.
+---
 
-## Technical Overview
+## What is OSSA?
 
-OSSA establishes a vendor-neutral, technology-agnostic standard for agent development, addressing critical challenges in multi-agent system architecture:
+**OSSA: Open Standard for Scalable AI Agents** - The definitive open standard for defining and connecting AI agents.
 
-- **Interoperability**: Standardized APIs enabling cross-platform agent communication
-- **Scalability**: Horizontal scaling patterns supporting millions of concurrent agents
-- **Governance**: Built-in compliance, security, and audit capabilities
-- **Observability**: Comprehensive telemetry and monitoring specifications
-- **Determinism**: Reproducible agent behaviors through formal specifications
+Just as OpenAPI standardized REST APIs, OSSA standardizes AI agent interaction, enabling vendor-neutral interoperability across frameworks. OSSA provides a unified schema for AI agents to communicate, ensuring compatibility across frameworks and enhancing trust in autonomous systems.
 
-## Architecture
+**OSSA is NOT a framework** - it's a standard that defines the contract. Implementations provide the functionality.
 
-### Core Components
+**Key Qualities:**
+- **Vendor-Neutral** - Community-driven, not controlled by any single company
+- **Interoperable** - Common language enabling diverse AI agents to work together
+- **Trustworthy** - Built with compliance and security in mind
+- **Open** - Collaborative effort for the "Internet of Agents"
 
-```
-┌─────────────────────────────────────────────────────────────────┐
-│                         OSSA Architecture                       │
-├─────────────────────────────────────────────────────────────────┤
-│                                                                 │
-│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐        │
-│  │   Agent      │  │  Discovery   │  │  Governance  │        │
-│  │  Registry    │◄─┤   Service    │─►│   Engine     │        │
-│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘        │
-│         │                  │                  │                │
-│         ▼                  ▼                  ▼                │
-│  ┌──────────────────────────────────────────────────┐         │
-│  │            Message Bus (Event-Driven)            │         │
-│  └──────────────────────────────────────────────────┘         │
-│         │                  │                  │                │
-│         ▼                  ▼                  ▼                │
-│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐        │
-│  │   Worker     │  │ Orchestrator │  │   Monitor    │        │
-│  │   Agents     │  │   Agents     │  │   Agents     │        │
-│  └──────────────┘  └──────────────┘  └──────────────┘        │
-│                                                                 │
-└─────────────────────────────────────────────────────────────────┘
-```
+| Component | Role | Comparable To |
+|-----------|------|---------------|
+| OSSA Specification | Standard definition | OpenAPI Specification |
+| OSSA CLI | Validation & generation | OpenAPI Generator (minimal) |
+| agent-buildkit | Reference implementation | Kong API Gateway |
+| OSSA Registry | Agent distribution | npm Registry |
 
-### Agent Taxonomy
+---
 
-OSSA defines six primary agent archetypes, each with distinct responsibilities and interface contracts:
+## Core Principles
 
-| Type | Responsibility | Interface Contract |
-|------|---------------|-------------------|
-| **Worker** | Task execution and data processing | Stateless, idempotent operations via REST/gRPC |
-| **Orchestrator** | Workflow coordination and resource allocation | Saga pattern implementation with compensation logic |
-| **Critic** | Quality assurance and validation | Immutable audit trails with cryptographic verification |
-| **Monitor** | System observability and alerting | OpenTelemetry-compliant metrics and traces |
-| **Governor** | Policy enforcement and compliance | OPA-based policy decision points |
-| **Judge** | Consensus and conflict resolution | Byzantine fault-tolerant consensus protocols |
+1. **Specification-Driven** - OSSA defines the standard
+2. **Implementation-Agnostic** - Any runtime can implement it
+3. **Minimal Tooling** - Basic CLI for validation & generation
+4. **No Vendor Lock-in** - Deploy to any infrastructure
 
-## Data Flow Architecture
+---
 
-### Inter-Agent Communication Protocol
+## Quick Start
 
-```
-┌─────────────┐       ┌─────────────┐       ┌─────────────┐
-│   Agent A   │       │   Message   │       │   Agent B   │
-│  (Producer) │       │     Bus     │       │ (Consumer)  │
-└─────┬───────┘       └──────┬──────┘       └──────┬──────┘
-      │                      │                      │
-      │ 1. Publish Event     │                      │
-      ├─────────────────────►│                      │
-      │                      │ 2. Route & Filter    │
-      │                      ├──────────────────────┤
-      │                      │                      │
-      │                      │ 3. Deliver Event     │
-      │                      ├─────────────────────►│
-      │                      │                      │
-      │                      │ 4. Acknowledge       │
-      │                      │◄─────────────────────┤
-      │ 5. Confirm           │                      │
-      │◄─────────────────────┤                      │
-      │                      │                      │
+### Installation
+
+```bash
+npm install -g @bluefly/openstandardagents
 ```
 
-### Request Processing Pipeline
+### Create Agent
 
-```
-┌──────────┐    ┌───────────┐    ┌────────────┐    ┌──────────┐
-│  Client  │───►│   Auth    │───►│ Rate Limit │───►│  Router  │
-└──────────┘    └───────────┘    └────────────┘    └────┬─────┘
-                                                          │
-                 ┌────────────────────────────────────────┘
-                 │
-    ┌────────────▼────────────┐
-    │   Request Validation    │
-    │  • Schema validation    │
-    │  • Business rules       │
-    │  • Security policies    │
-    └────────────┬────────────┘
-                 │
-    ┌────────────▼────────────┐
-    │   Agent Dispatching     │
-    │  • Load balancing       │
-    │  • Circuit breaking     │
-    │  • Retry logic          │
-    └────────────┬────────────┘
-                 │
-    ┌────────────▼────────────┐
-    │   Response Assembly     │
-    │  • Data aggregation     │
-    │  • Format conversion    │
-    │  • Compression          │
-    └────────────┬────────────┘
-                 │
-                 ▼
-            Response
+```bash
+ossa generate worker --name "My Agent" --id my-agent
+# Creates agent.ossa.yaml
 ```
 
-## Specification Components
-
-### OpenAPI 3.1 Specifications
-
-OSSA provides comprehensive API specifications using OpenAPI 3.1, leveraging advanced features:
-
-- **Discriminator Mappings**: Polymorphic agent type inheritance
-- **Webhooks**: Event-driven lifecycle notifications
-- **JSON Schema Draft 2020-12**: Advanced validation with conditional schemas
-- **Content Negotiation**: Multiple serialization formats (JSON, CBOR, MessagePack)
-- **Security Schemes**: OAuth 2.1, mTLS, API keys with rotation
-
-### Agent Manifest Schema
-
-Each agent is defined by a JSON Schema-compliant manifest:
-
-```json
-{
-  "$schema": "https://ossa.dev/schemas/agent-manifest/v1.0.0",
-  "apiVersion": "v1",
-  "kind": "Agent",
-  "metadata": {
-    "name": "data-processor",
-    "version": "1.0.0",
-    "type": "worker"
-  },
-  "spec": {
-    "capabilities": ["data-processing", "batch-operations"],
-    "interfaces": {
-      "rest": { "port": 8080, "path": "/api/v1" },
-      "grpc": { "port": 9090, "service": "DataProcessor" }
-    },
-    "requirements": {
-      "cpu": "2000m",
-      "memory": "4Gi",
-      "storage": "10Gi"
-    },
-    "scaling": {
-      "min": 1,
-      "max": 100,
-      "targetCPU": 70
-    }
-  }
-}
-```
+### Validate
 
-## Implementation Requirements
+```bash
+ossa validate agent.yml
+```
 
-### Minimum Viable Implementation
+### Run Your Agent
 
-Conformant OSSA implementations must provide:
+```bash
+# Set your API key
+export OPENAI_API_KEY=sk-your-key-here
 
-1. **API Compliance**: Full OpenAPI 3.1 specification implementation
-2. **Schema Validation**: JSON Schema Draft 2020-12 support
-3. **Authentication**: OAuth 2.1 with PKCE flow
-4. **Monitoring**: OpenTelemetry-compatible metrics export
-5. **Event Bus**: At least one supported transport (Kafka, RabbitMQ, NATS)
-6. **Service Discovery**: DNS-based or registry-based discovery
-7. **Health Checks**: Kubernetes-compatible liveness/readiness probes
+# Run interactively
+ossa run agent.ossa.yaml
 
-### Performance Benchmarks
+# Or send a single message
+ossa run agent.ossa.yaml -m "Hello, how can you help me?"
 
-Reference implementation performance targets:
+# With verbose output
+ossa run agent.ossa.yaml -v
+```
 
-| Metric | Requirement | Measurement |
-|--------|------------|-------------|
-| Latency (p99) | < 100ms | End-to-end request processing |
-| Throughput | > 10,000 req/s | Per agent instance |
-| Availability | > 99.95% | Monthly uptime |
-| MTTR | < 5 minutes | Automatic recovery time |
-| Scalability | Linear to 1000 nodes | Horizontal scaling efficiency |
+### Deploy
 
-## Governance Model
+Deploy to **YOUR** infrastructure:
+- AWS, GCP, Azure
+- Kubernetes, Docker
+- On-premise
+- Serverless
 
-### Compliance Framework
+OSSA doesn't care - it's just a standard.
 
-OSSA incorporates enterprise governance requirements:
+---
 
-- **Audit Logging**: Immutable audit trails with tamper detection
-- **Policy Enforcement**: OPA-based policy decision points
-- **Data Residency**: Geographic constraint enforcement
-- **Encryption**: At-rest and in-transit encryption with key rotation
-- **Access Control**: RBAC with attribute-based extensions
+## OSSA CLI (Minimal Tooling)
 
-### Security Architecture
+The OSSA CLI provides basic tooling:
 
-```
-┌─────────────────────────────────────────────────────┐
-│                Security Perimeter                   │
-│                                                     │
-│  ┌──────────┐     ┌──────────┐    ┌──────────┐   │
-│  │   WAF    │────►│   mTLS   │───►│   RBAC   │   │
-│  └──────────┘     │  Gateway │    │  Engine  │   │
-│                   └──────────┘    └──────────┘   │
-│                         │                          │
-│  ┌──────────────────────┼──────────────────────┐  │
-│  │                      ▼                      │  │
-│  │  ┌──────────┐  ┌──────────┐  ┌──────────┐ │  │
-│  │  │  Secret  │  │  Policy  │  │  Audit   │ │  │
-│  │  │  Manager │  │  Engine  │  │  Logger  │ │  │
-│  │  └──────────┘  └──────────┘  └──────────┘ │  │
-│  │                                             │  │
-│  │            Internal Network                 │  │
-│  └─────────────────────────────────────────────┘  │
-│                                                     │
-└─────────────────────────────────────────────────────┘
+```bash
+ossa validate <path>    # Validate against OSSA schema
+ossa generate <type>    # Generate agent from template (chat, workflow, compliance, etc.)
+ossa migrate <source>   # Migrate between OSSA versions
+ossa run <path>         # Run agents with OpenAI adapter
 ```
 
-## Deployment Patterns
+**What OSSA CLI does:**
+- Validate agent manifests
+- Generate project scaffolding
+- Provide templates
+- Run agents interactively (OpenAI adapter)
 
-### Kubernetes-Native Deployment
+**What OSSA CLI does NOT do:**
+- Runtime orchestration
+- Deployment
+- Production monitoring
+- Infrastructure management
 
-OSSA agents are designed for Kubernetes-native deployment:
+For production features, see [Agent Buildkit](https://github.com/blueflyio/agent-buildkit).
 
-```yaml
-apiVersion: ossa.dev/v1
-kind: AgentDeployment
-metadata:
-  name: data-processor
-spec:
-  replicas: 3
-  selector:
-    matchLabels:
-      agent.ossa.dev/type: worker
-  template:
-    metadata:
-      labels:
-        agent.ossa.dev/type: worker
-    spec:
-      agentRef:
-        name: data-processor
-        version: 1.0.0
-      resources:
-        limits:
-          cpu: "2"
-          memory: "4Gi"
-      autoscaling:
-        enabled: true
-        minReplicas: 3
-        maxReplicas: 100
-        metrics:
-        - type: CPU
-          target: 70
-```
+### Running Agents
 
-### Multi-Region Architecture
+The `ossa run` command allows you to execute agents using the OpenAI adapter:
 
-```
-┌────────────────────────────────────────────────────┐
-│                  Global Load Balancer              │
-└─────────┬──────────────┬──────────────┬───────────┘
-          │              │              │
-    ┌─────▼─────┐  ┌─────▼─────┐  ┌─────▼─────┐
-    │  Region   │  │  Region   │  │  Region   │
-    │    US     │  │    EU     │  │   APAC    │
-    └─────┬─────┘  └─────┬─────┘  └─────┬─────┘
-          │              │              │
-    ┌─────▼─────┐  ┌─────▼─────┐  ┌─────▼─────┐
-    │   Agent   │  │   Agent   │  │   Agent   │
-    │  Cluster  │◄─┤  Cluster  │─►│  Cluster  │
-    └───────────┘  └───────────┘  └───────────┘
-          ▲              ▲              ▲
-          └──────────────┼──────────────┘
-                         │
-                 ┌───────▼───────┐
-                 │  Global State │
-                 │   Store (CRD) │
-                 └───────────────┘
-```
-
-## Integration Specifications
+```bash
+# Interactive mode (REPL)
+ossa run my-agent.ossa.yaml
 
-### Event-Driven Integration
+# Single message mode
+ossa run my-agent.ossa.yaml -m "What is the weather today?"
 
-OSSA supports multiple event transport mechanisms:
+# Verbose output (show tool calls)
+ossa run my-agent.ossa.yaml -v
 
-```
-Producer → Event Router → Consumer
-           │
-           ├─► Kafka (recommended for high throughput)
-           ├─► RabbitMQ (recommended for complex routing)
-           ├─► NATS (recommended for low latency)
-           └─► Redis Streams (recommended for simplicity)
+# Custom options
+ossa run my-agent.ossa.yaml --max-turns 20 --no-validate
 ```
 
-### Protocol Support Matrix
+**Features:**
+- Interactive REPL mode for conversations
+- Single message mode for quick queries
+- Tool execution with custom handlers
+- Verbose mode for debugging
+- Configurable max turns to prevent loops
 
-| Protocol | Use Case | Performance | Complexity |
-|----------|----------|-------------|------------|
-| REST/HTTP | Synchronous operations | Medium | Low |
-| gRPC | High-performance RPC | High | Medium |
-| GraphQL | Flexible queries | Medium | High |
-| WebSocket | Real-time streaming | High | Medium |
-| AMQP | Message queuing | High | High |
+**Requirements:**
+- OpenAI API key: `export OPENAI_API_KEY=sk-...`
+- Valid OSSA manifest (YAML or JSON)
 
-## Universal Agent Protocol (UAP)
+See [Running Agents Guide](https://openstandardagents.org/docs/getting-started/running-agents) for more details.
 
-UAP provides a unified communication framework for heterogeneous agent ecosystems, enabling seamless interaction between agents regardless of their underlying implementation or platform.
+---
 
-### Core Protocol Stack
+## Specification
 
-UAP consists of four foundational protocols that work together to enable comprehensive agent interoperability:
+OSSA v0.2.5-RC Schema: [`spec/v0.2.5-RC/ossa-0.2.5-RC.schema.json`](spec/v0.2.5-RC/ossa-0.2.5-RC.schema.json)
 
-#### RASP (Resource Allocation & Scheduling Protocol)
-Manages resource distribution and task scheduling across agent clusters:
+### Required Fields
 
-```
-Agent Request → RASP Scheduler → Resource Pool → Task Assignment
-                     │                │              │
-                     ├─► Load Analysis ├─► Priority   ├─► Execution
-                     ├─► Constraint    ├─► Queueing   ├─► Monitoring
-                     └─► Optimization  └─► Balancing  └─► Feedback
+```yaml
+ossaVersion: "0.2.5-RC"
+
+agent:
+  id: my-agent                    # DNS-1123 format
+  name: My Agent                  # Human-readable
+  version: "1.0.0"                # Semantic version
+  role: worker                    # Agent role
+
+  runtime:
+    type: k8s                     # Runtime type
+
+  capabilities:                   # At least one capability
+    - name: process_data
+      description: Process data
+      input_schema: { ... }
+      output_schema: { ... }
 ```
 
-#### ACAP (Agent Capability Advertisement Protocol)
-Enables dynamic service discovery and capability matching:
-
-```json
-{
-  "protocol": "ACAP/1.0",
-  "agentId": "worker-001",
-  "capabilities": [
-    {
-      "service": "data-processing",
-      "version": "2.1.0",
-      "endpoints": ["/api/v2/process"],
-      "sla": { "latency": "< 50ms", "availability": "99.9%" }
-    }
-  ],
-  "resources": {
-    "cpu": "available: 2.5 cores",
-    "memory": "available: 6.2GB"
-  }
-}
-```
+Full schema documentation: [`docs/specification/`](docs/specification/)
+
+---
 
-#### UADP (Universal Agent Discovery Protocol)
-Provides zero-configuration agent discovery with automatic topology mapping:
+## Production-Ready Example: GitLab Kubernetes Agent Ecosystem
 
-```
-Registry Service ←→ Agent Mesh ←→ Discovery Beacon
-      │                 │               │
-      ├─► Health Check   ├─► Heartbeat   ├─► Announcement
-      ├─► Capability     ├─► Routing     ├─► Topology
-      └─► Status Update  └─► Load Info   └─► Metrics
-```
+**NEW**: Complete production ecosystem with **8 specialized agents** for GitLab-integrated Kubernetes deployments.
 
-#### CPC (Cross-Platform Communication)
-Standardizes message formats and transport mechanisms across different agent platforms:
+[**View Full Documentation**](https://github.com/blueflyio/openstandardagents/wiki/OSSA-Agent-Ecosystem-for-GitLab-Kubernetes-Deployments)
 
-| Transport | Use Case | Reliability | Performance |
-|-----------|----------|-------------|-------------|
-| HTTP/3 | Synchronous RPC | High | Medium |
-| WebSocket | Real-time streams | Medium | High |
-| MQTT | IoT integration | Medium | Low |
-| gRPC | High-performance | High | High |
+### Highlights
 
-### UAP CLI Commands
+- **8 OSSA-compliant agents**: Security, Performance, Database, Config, Monitoring, Rollback, Cost, Compliance
+- **Agent mesh** with Istio + STRICT mTLS
+- **Elite DORA metrics**: 12 deployments/day, 45min lead time, 8.5% change failure rate
+- **Massive ROI**: $80-145K/month cost savings (31-57x return)
+- **Full compliance**: SOC2, HIPAA, PCI-DSS, GDPR, FedRAMP
 
-The OSSA CLI provides comprehensive UAP management capabilities:
+### Quick Deploy
 
-#### Discovery Operations
 ```bash
-# Discover agents in the network
-ossa discover --protocol UADP --filter "type=worker"
+# Deploy agent mesh
+kubectl apply -f .gitlab/agents/mesh-config.yaml
+
+# Deploy all 8 agents
+for agent in security-scanner performance-optimizer db-migrator \
+             config-validator monitoring-agent rollback-coordinator \
+             cost-analyzer compliance-auditor; do
+  buildkit agents deploy .gitlab/agents/$agent/manifest.ossa.yaml
+done
+```
 
-# Register agent capabilities
-ossa register --capability "data-processing" --endpoint "/api/v1/process"
+**Location**: [`.gitlab/agents/`](.gitlab/agents/)
 
-# Query available services
-ossa query --service "machine-learning" --version ">= 2.0"
-```
+---
 
-#### Resource Management
-```bash
-# Monitor resource allocation
-ossa resources --protocol RASP --view cluster
+## Examples
 
-# Request resource reservation
-ossa reserve --cpu "4 cores" --memory "8GB" --duration "2h"
+Reference implementations: [`examples/`](examples/)
 
-# Scale agent deployment
-ossa scale --agent-type worker --replicas 10 --zone us-west-2
-```
+- `compliance-agent.yml` - FedRAMP compliance
+- `chat-agent.yml` - Conversation agent
+- `workflow-agent.yml` - Workflow orchestration
+- **GitLab K8s Ecosystem** - Production-ready multi-agent system (see above)
 
-#### Communication Setup
-```bash
-# Configure cross-platform communication
-ossa comm config --protocol CPC --transport grpc --encryption tls1.3
+---
 
-# Test connectivity between agents
-ossa comm test --source agent-001 --target agent-002 --protocol all
+## OSSA Ecosystem
 
-# Monitor message flows
-ossa comm monitor --protocol CPC --filter "error_rate > 1%"
-```
+### Core Products
 
-#### Protocol Validation
-```bash
-# Validate UAP compliance
-ossa validate uap --spec-version 1.0 --agent-manifest ./agent.yaml
+**OSSA** (This Repository) - The specification standard
+- JSON Schema specification
+- CLI for validation & generation
+- Reference implementations
+- Documentation
 
-# Generate UAP documentation
-ossa docs uap --output ./docs/uap-spec.md --format markdown
+**Agent Buildkit** - CLI tool for building and managing OSSA-compliant agents
+- Modern, fast, minimal CLI
+- GitLab integration
+- Kubernetes deployment
+- Production monitoring
 
-# Benchmark protocol performance
-ossa benchmark uap --duration 5m --agents 100 --concurrent-requests 1000
-```
+**Agent Studio** - GUI platform for agent orchestration
+- macOS-aligned design
+- Visual workflow design
+- Agent monitoring and debugging
+- End-to-end agent lifecycle management
 
-### UAP Integration Example
-
-```typescript
-import { UAP, RASP, ACAP, UADP, CPC } from '@ossa/uap-client';
-
-// Initialize UAP stack
-const uap = new UAP({
-  agent: { id: 'worker-001', type: 'data-processor' },
-  protocols: {
-    rasp: { scheduler: 'kubernetes', priority: 'high' },
-    acap: { advertise: true, discovery: 'automatic' },
-    uadp: { beacon: true, mesh: 'cluster-local' },
-    cpc: { transport: ['grpc', 'websocket'] }
-  }
-});
-
-// Register capabilities
-await uap.acap.advertise({
-  service: 'data-processing',
-  version: '2.1.0',
-  endpoints: ['/api/v2/process'],
-  sla: { latency: 50, availability: 99.9 }
-});
-
-// Discover and connect to other agents
-const peers = await uap.uadp.discover({ type: 'orchestrator' });
-const connection = await uap.cpc.connect(peers[0], { protocol: 'grpc' });
-
-// Request resources for task execution
-const allocation = await uap.rasp.request({
-  cpu: '2 cores',
-  memory: '4GB',
-  duration: '1h'
-});
-```
+### Part of the OSSA Ecosystem
 
-## Observability Framework
+All three products work together:
+- **OSSA** defines the standard
+- **Agent Buildkit** provides CLI tooling
+- **Agent Studio** offers visual management
 
-### Metrics Collection
+Together, they form a complete ecosystem for AI agent development, deployment, and management.
 
-OSSA mandates OpenTelemetry-compliant metrics:
+**Others welcome** - OSSA is an open standard, anyone can implement it.
 
-```
-Agent → OpenTelemetry Collector → Backend
-         │                         │
-         ├─► Metrics              ├─► Prometheus
-         ├─► Traces               ├─► Jaeger
-         └─► Logs                 └─► Elasticsearch
-```
+---
+
+## Why OSSA?
+
+### For Enterprises
+
+- **Lightweight** - Just a standard, minimal dependencies
+- **No Vendor Lock-in** - Use any implementation
+- **Deploy Anywhere** - Your infrastructure, your choice
+- **Clear Specification** - Well-defined contract
+
+### For Framework Builders
 
-### Key Performance Indicators
+- **Standard to Build On** - Like OpenAPI for APIs
+- **Reference Implementation** - Agent Buildkit shows the way
+- **Clear Boundaries** - Standard vs. implementation
 
-| Metric | Description | Alert Threshold |
-|--------|-------------|-----------------|
-| `agent_tasks_total` | Total tasks processed | - |
-| `agent_task_duration_seconds` | Task processing time | p99 > 1s |
-| `agent_error_rate` | Error percentage | > 1% |
-| `agent_saturation` | Resource utilization | > 80% |
-| `agent_availability` | Uptime percentage | < 99.9% |
+---
 
-## Reference Implementation
+## Installation & Usage
 
-### Technology Stack
+### As a Standard (Validation Only)
 
-The reference implementation demonstrates OSSA compliance using:
+```bash
+npm install -g @bluefly/openstandardagents
+ossa validate my-agent.yml
+```
 
-- **Runtime**: Node.js 20 LTS with TypeScript 5.3
-- **Framework**: Express 4.18 with OpenAPI middleware
-- **Validation**: Ajv with JSON Schema Draft 2020-12
-- **Authentication**: Passport.js with OAuth 2.1
-- **Message Bus**: Kafka with Schema Registry
-- **Monitoring**: OpenTelemetry with Prometheus
-- **Container**: Docker with multi-stage builds
-- **Orchestration**: Kubernetes 1.28+
+### With Production Features
 
-### Performance Characteristics
+```bash
+npm install -g @bluefly/agent-buildkit
+buildkit ossa validate my-agent.yml  # Uses OSSA + adds features
+buildkit ossa sync-docs               # GitLab integration
+```
 
-Benchmarked on AWS m5.large instances:
+---
 
-- **Startup Time**: < 3 seconds
-- **Memory Footprint**: < 256 MB idle
-- **CPU Usage**: < 5% idle
-- **Network Overhead**: < 2% of payload
-- **Compression Ratio**: 70% with gzip
+## Documentation
 
-## Adoption Guide
+### Official Website & Documentation Portal
 
-### Enterprise Integration
+**Live Website**: https://openstandardagents.org
 
-Organizations implementing OSSA should follow this phased approach:
+The OSSA website features:
+- **Interactive Documentation** - Browse the complete OSSA wiki with an enhanced UI
+- **GitLab Wiki Integration** - Automatically synced from the official GitLab wiki
+- **Interactive Examples** - Explore OSSA manifests with live validation and URL tracking
+- **Schema Validator** - Validate your OSSA manifests in the browser
+- **Migration Guides** - Step-by-step guides from 6 major frameworks
+- **Responsive Design** - Beautiful, accessible UI built with Next.js 15 and Tailwind CSS
 
-1. **Assessment Phase**: Evaluate existing agent infrastructure
-2. **Pilot Phase**: Implement reference agent in non-production
-3. **Migration Phase**: Gradually migrate existing agents
-4. **Scale Phase**: Deploy production workloads
-5. **Optimization Phase**: Fine-tune performance and costs
+The documentation is organized into:
+- **Getting Started** - Quick start guides, installation, and first agent creation
+- **Core Concepts** - OSSA specification, agent types, capabilities, and runtime models
+- **Advanced Topics** - Security, deployment, monitoring, and scaling
+- **For Your Role** - Tailored guides for developers, architects, enterprises, and researchers
+- **Migration Guides** - From LangChain, MCP, OpenAI Swarm, CrewAI, Langflow, and Drupal ECA
+- **Reference** - Complete schema, CLI, and OpenAPI extension reference
 
-### Compliance Verification
+### Additional Resources
 
-OSSA provides automated compliance verification:
+- **Specification**: [spec/v0.2.5-RC/ossa-0.2.5-RC.schema.json](spec/v0.2.5-RC/ossa-0.2.5-RC.schema.json)
+- **Examples**: [examples/](examples/)
+- **API Reference**: [docs/](docs/)
+- **GitHub Issues**: https://github.com/blueflyio/openstandardagents/issues
 
-```bash
-ossa validate --spec /path/to/implementation
-ossa certify --level basic|standard|advanced
-ossa audit --compliance SOC2|ISO27001|GDPR
-```
+---
 
 ## Contributing
 
-Contributions to the OSSA specification follow a formal RFC process:
+OSSA is an open standard. Contributions welcome.
 
-1. **Proposal**: Submit RFC with rationale and specification changes
-2. **Review**: Community review period (minimum 30 days)
-3. **Implementation**: Proof-of-concept in reference implementation
-4. **Testing**: Comprehensive test suite additions
-5. **Approval**: Technical steering committee review
-6. **Merge**: Integration into specification
+**Repository**: https://github.com/blueflyio/openstandardagents/  
+**Homepage**: https://openstandardagents.org  
+**Issues**: https://github.com/blueflyio/openstandardagents/issues
 
-## License
+1. Fork the repository on GitHub
+2. Create feature branch
+3. Submit pull request
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
 
-The OSSA specification is licensed under the MIT License. Implementations may use any license compatible with the specification requirements.
+---
 
-## Repository
+## License
 
-- **Specification**: [gitlab.bluefly.io/llm/openapi-ai-agents-standard](https://gitlab.bluefly.io/llm/openapi-ai-agents-standard)
-- **Reference Implementation**: [gitlab.bluefly.io/llm/agent_buildkit](https://gitlab.bluefly.io/llm/agent_buildkit)
+Apache 2.0 - see [LICENSE](LICENSE) for details.
 
 ---
 
-**OSSA v0.1.9** - Enabling enterprise-grade AI agent interoperability through open standards.
+## Part of the OSSA Ecosystem
+
+OSSA is part of a unified ecosystem for AI agent development:
+
+- **OSSA** - The open standard (this repository)
+- **Agent Buildkit** - CLI for building and managing agents
+- **Agent Studio** - GUI platform for agent orchestration
+
+**OSSA: Open. Interoperable. Trustworthy.**
+
+*The open standard for interoperable AI agents.*