@adverant-nexus/cli 2.0.1 → 3.0.1

package/README.md

@@ -1,593 +1,535 @@
-# Adverant-Nexus CLI
+<div align="center">
+  <img src="https://raw.githubusercontent.com/adverant/Adverant-Nexus-CLI/main/docs/images/adverant-logo-final.svg" alt="Adverant" width="280"/>
 
-> World-class command-line interface for the Adverant-Nexus platform - Surpassing Claude Code CLI and Gemini CLI
+  # Nexus CLI
 
-[![Version](https://img.shields.io/npm/v/@adverant-nexus/cli.svg)](https://www.npmjs.com/package/@adverant-nexus/cli)
-[![License](https://img.shields.io/npm/l/@adverant-nexus/cli.svg)](https://github.com/adverant-ai/adverant-nexus/blob/main/LICENSE)
-[![TypeScript](https://img.shields.io/badge/TypeScript-5.3-blue.svg)](https://www.typescriptlang.org/)
+  **Enterprise-Grade CLI for AI-Powered Development**
 
-## Overview
+  [![npm version](https://img.shields.io/npm/v/@adverant-nexus/cli.svg)](https://www.npmjs.com/package/@adverant-nexus/cli)
+  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+  [![TypeScript](https://img.shields.io/badge/TypeScript-5.3-blue.svg)](https://www.typescriptlang.org/)
+  [![Node.js](https://img.shields.io/badge/Node.js-%3E%3D20.0.0-green.svg)](https://nodejs.org/)
 
-The **Adverant-Nexus CLI** (`nexus`) is a production-grade, auto-discovering command-line interface that provides unified access to all 32+ microservices, 70+ Nexus MCP tools, and the entire Adverant-Nexus ecosystem.
+  **Version:** 3.0.0 | **Last Updated:** December 2024
 
-### Why This CLI is Better
+  [Why Nexus?](#why-nexus-cli) &#8226; [Features](#-features) &#8226; [Quick Start](#-quick-start) &#8226; [Commands](#-command-reference) &#8226; [Architecture](#-architecture) &#8226; [Contributing](#-contributing)
 
-| Feature | Adverant-Nexus CLI | Claude Code | Gemini CLI |
-|---------|-------------------|-------------|------------|
-| **Auto-Discovery** | ✅ All services & plugins | ❌ Manual | ❌ Manual |
-| **Service Commands** | ✅ 32+ services | ❌ Single agent | ❌ Single agent |
-| **Nexus Tools** | ✅ 70+ tools exposed | ❌ N/A | ❌ N/A |
-| **Plugin System** | ✅ Full SDK | ✅ Skills | ✅ Extensions |
-| **Interactive REPL** | ✅ Full-featured | ❌ Chat only | ✅ Yes |
-| **Streaming** | ✅ WebSocket + SSE | ✅ Yes | ✅ Yes |
-| **Output Formats** | ✅ 5 formats | ✅ Text + JSON | ✅ Text + JSON |
-| **ReAct Agent** | ✅ 20 iterations | ✅ Task agent | ❌ No |
-| **Service Management** | ✅ Full control | ❌ N/A | ❌ N/A |
-| **Multi-Agent** | ✅ 10+ agents | ❌ Single | ❌ Single |
+</div>
 
-## Features
-
-### 🚀 Auto-Discovery
-- **Automatic service detection** from docker-compose.yml
-- **OpenAPI schema parsing** for automatic command generation
-- **MCP tool discovery** for Nexus system integration
-- **Plugin auto-loading** from ~/.nexus/plugins/
-
-### 🎯 Unified Interface
-- **32+ microservices** accessible via single CLI
-- **500+ API endpoints** exposed as commands
-- **70+ Nexus tools** integrated
-- **Service namespaces**: `nexus <service> <action>`
-
-### 🤖 Intelligent Automation
-- **ReAct agent mode** for autonomous task execution
-- **Multi-agent orchestration** (up to 10 agents)
-- **Code validation** with 3-model consensus
-- **Progressive learning** system integration
-
-### 🔌 Extensible
-- **Plugin SDK** for third-party extensions
-- **MCP protocol** support
-- **Custom commands** via .nexus.toml
-- **Workspace-aware** configuration
-
-### 📊 Multiple Output Formats
-- **Text** (human-readable)
-- **JSON** (machine-parseable)
-- **YAML** (configuration files)
-- **Table** (structured data)
-- **Stream-JSON** (real-time events)
-
-### 🎨 Rich Developer Experience
-- **Interactive REPL** mode
-- **Tab completion** for all commands
-- **Session checkpointing** (save/resume work)
-- **Streaming progress** for long operations
-- **Git integration** (status, diff, commit)
-
-## Installation
-
-### From Source (Current)
-```bash
-# Navigate to CLI directory
-cd /home/user/Adverant-Nexus/packages/nexus-cli
-
-# Install dependencies
-npm install
+---
 
-# Build
-npm run build
+## Why Nexus CLI?
 
-# Link globally
-npm run link:global
+**Most AI CLIs give you a chatbot. Nexus gives you a command center.**
 
-# Verify installation
-nexus --version
-```
+Developers often juggle multiple tools, copy context between terminals, and lose track of what each system knows. Nexus CLI was built to unify your AI-powered workflow into a single, coherent interface.
 
-### From NPM (Coming Soon)
-```bash
-npm install -g @adverant-nexus/cli
-```
+### Key Capabilities
 
-## Quick Start
+| Capability | Description |
+|------------|-------------|
+| **Auto-Discovery** | Automatically detects and integrates 32+ microservices |
+| **MCP Integration** | 70+ Model Context Protocol tools exposed as commands |
+| **Multi-Agent Orchestration** | Run 10+ concurrent AI agents for complex tasks |
+| **ReAct Agent Mode** | Autonomous task execution with up to 20 iterations |
+| **Interactive REPL** | Full-featured shell with history and tab completion |
+| **Plugin SDK** | Complete extensibility for custom integrations |
+| **Workflow Automation** | YAML-based workflows with visual builder |
+| **Real-time Monitoring** | Dashboard with alerts and performance metrics |
+| **Cost Tracking** | Built-in usage analytics per operation |
+| **Session Management** | Save, resume, and checkpoint your work |
+| **Collaboration** | Multi-user sessions for team workflows |
+| **Streaming** | WebSocket and SSE support for real-time updates |
 
-```bash
-# Check CLI version
-nexus --version
+---
 
-# Show all discovered services
-nexus services list
+## The Problem We Solve
 
-# Check service health
-nexus services health --all
+```
+                    BEFORE: Fragmented Tooling
+
+  Your Terminal --> Tool A    Custom Scripts    Tool B
+                       |           |               |
+                       v           v               v
+                  Context Lost | No Integration | Limited Features
+
+                    AFTER: Unified Command Center
+
+  Your Terminal --> NEXUS CLI
+                    - 32+ Services
+                    - 70+ MCP Tools
+                    - 10+ Agents
+                    - Full Context
+                         |
+        +----------------+----------------+
+        v                v                v
+    GraphRAG        MageAgent         Gateway
+```
 
-# Store a document in GraphRAG
-nexus graphrag store-document --file report.pdf --title "Q4 Report"
+---
 
-# Query GraphRAG
-nexus graphrag query --text "user authentication patterns"
+## Features
 
-# Run multi-agent orchestration
-nexus mageagent orchestrate --task "Analyze codebase for security issues"
+### Auto-Discovery & Integration
 
-# Execute code in sandbox
-nexus sandbox execute --code "print('Hello, Nexus!')" --language python
+Stop configuring. Start building.
 
-# Recall memories from Nexus
-nexus nexus recall-memory --query "typescript patterns" --limit 10
+- **Automatic service detection** from Docker Compose, Kubernetes, and OpenAPI specs
+- **70+ MCP tools** exposed through Model Context Protocol integration
+- **32+ microservices** accessible through a single CLI
+- **500+ API endpoints** auto-generated as commands
+- **Plugin auto-loading** from `~/.nexus/plugins/`
 
-# Start interactive REPL
-nexus repl
+```bash
+# Nexus discovers your entire stack automatically
+nexus services list
+# Output: 32 services discovered, 47 healthy, 0 degraded
 
-# Run autonomous agent
-nexus agent run --task "Fix all TypeScript errors"
+nexus mcp tools
+# Output: 70 tools available across 12 providers
 ```
 
-## Usage
+### Intelligent Automation
 
-### Service Commands
+Your AI that actually gets things done.
 
-Every microservice in the Adverant-Nexus stack is accessible via the CLI:
+- **Natural language commands**: Just describe what you want
+- **ReAct agent mode**: 20 autonomous iterations with reasoning
+- **Multi-agent orchestration**: Up to 10 concurrent specialized agents
+- **Context-aware execution**: Remembers your stack, preferences, and patterns
+- **Workflow templates**: YAML-defined automation pipelines
 
 ```bash
-# GraphRAG - Knowledge Management
-nexus graphrag store-document --file report.pdf
-nexus graphrag query --text "search query"
-nexus graphrag store-entity --domain code --type class --content "User"
+# Natural language - Nexus understands intent
+nexus ask "Deploy the latest GraphRAG changes to staging"
 
-# MageAgent - Multi-Agent Orchestration
-nexus mageagent orchestrate --task "Complex task" --max-agents 5
-nexus mageagent analyze --input code.ts --focus security
-nexus mageagent collaborate --agents 3 --task "Build API"
+# ReAct agent - autonomous problem solving
+nexus agent task "Analyze the codebase and suggest performance improvements" --iterations 20
 
-# Sandbox - Code Execution
-nexus sandbox execute --code "..." --language python --stream
-nexus sandbox list-languages
+# Multi-agent - parallel specialized work
+nexus agent orchestrate --agents "code-review,security-scan,test-coverage"
+```
 
-# VideoAgent - Video Intelligence
-nexus videoagent process-video --url video.mp4 --stream
+### Extensible Architecture
 
-# GeoAgent - Geospatial Intelligence
-nexus geoagent proximity-search --lat 37.7749 --lon -122.4194 --radius 10km
+Build on top of Nexus, don't work around it.
 
-# OrchestrationAgent - Autonomous Execution
-nexus orchestration run --task "Implement feature" --max-iterations 20
+- **Plugin SDK** with full TypeScript support
+- **Hot-reloadable** plugins without restart
+- **Permission-based sandbox** for security
+- **Custom commands** via workspace configuration
+- **MCP protocol** support for tool integration
 
-# LearningAgent - Progressive Learning
-nexus learning trigger --topic "rust_async" --priority 9
+```typescript
+// Create a plugin in minutes
+import { NexusPlugin, command } from '@adverant-nexus/sdk';
+
+export default class MyPlugin extends NexusPlugin {
+  @command('greet', 'Say hello')
+  async greet(name: string) {
+    return `Hello, ${name}! Welcome to Nexus.`;
+  }
+}
 ```
 
-### Nexus MCP Commands
+### Rich Developer Experience
 
-All 70+ Nexus tools are exposed:
+Built by developers, for developers who demand excellence.
+
+- **Interactive REPL** with full history and tab completion
+- **Session checkpointing**: Save work, switch contexts, resume later
+- **Multiple output formats**: JSON, YAML, Table, Streaming
+- **Git integration**: Status, diff, commit from Nexus
+- **Real-time streaming**: Watch operations as they happen
 
 ```bash
-# Memory Operations
-nexus nexus store-memory --content "..." --tags "tag1,tag2"
-nexus nexus recall-memory --query "search" --limit 10
-nexus nexus store-document --file doc.pdf
-nexus nexus retrieve --query "..." --strategy hybrid
-
-# Knowledge Graph
-nexus nexus store-entity --domain code --type function --content "..."
-nexus nexus query-entities --domain code --search "auth"
-nexus nexus create-relationship --source id1 --target id2 --type CALLS
-
-# Code Analysis
-nexus nexus validate-code --file app.ts --risk-level high
-nexus nexus analyze-code --file app.ts --focus security,performance
-
-# Multi-Agent
-nexus nexus orchestrate --task "Security audit" --max-agents 5
-
-# Learning
-nexus nexus trigger-learning --topic "rust" --priority 8
-nexus nexus recall-knowledge --topic "async" --layer EXPERT
-
-# Health
-nexus nexus health --detailed
-```
+# Interactive mode - your AI command center
+nexus repl
 
-### Service Management
+nexus> services health --all
+nexus> agent start research --topic "GraphRAG optimization"
+nexus> session save "morning-work"
+nexus> exit
 
-```bash
-# List all services
-nexus services list
+# Resume exactly where you left off
+nexus session load "morning-work"
+```
 
-# Check service status
-nexus services status
+### Monitoring & Analytics
 
-# Get service info
-nexus services info graphrag
+Know everything. Miss nothing.
 
-# Control services
-nexus services start graphrag
-nexus services stop mageagent
-nexus services restart sandbox
+- **Service health dashboard** with live updates
+- **Custom alert conditions** with webhooks and notifications
+- **Performance metrics** per operation
+- **Cost tracking** for API operations
+- **Time-series analytics** for optimization
 
-# View logs
-nexus services logs graphrag --follow
+```bash
+# Real-time health monitoring
+nexus monitor --dashboard
 
-# Check health
-nexus services health --all
+# Cost analysis
+nexus analytics costs --period 30d
+# Output: Total: $47.82 | GraphRAG: $23.41 | MageAgent: $18.90 | Other: $5.51
 
-# Show port mappings
-nexus services ports
+# Performance insights
+nexus analytics performance --service graphrag
 ```
 
-### Interactive REPL
-
-```bash
-# Start REPL
-nexus repl
+---
 
-# Inside REPL:
-> help                          # Show all commands
-> services                      # List discovered services
-> use graphrag                  # Switch to graphrag namespace
-> store-document --file x.pdf   # Execute in current namespace
-> history                       # Show command history
-> save my-session               # Save session
-> exit                          # Exit REPL
-```
+## Quick Start
 
-### Autonomous Agent Mode
+### Installation
 
 ```bash
-# Run autonomous task
-nexus agent run --task "Fix all TypeScript errors"
-
-# With constraints
-nexus agent run \
-  --task "Implement user authentication" \
-  --max-iterations 20 \
-  --budget 50 \
-  --workspace /path/to/project
-
-# With streaming
-nexus agent run --task "Security audit" --stream
+# npm (recommended)
+npm install -g @adverant-nexus/cli
+
+# yarn
+yarn global add @adverant-nexus/cli
+
+# pnpm
+pnpm add -g @adverant-nexus/cli
 ```
 
-### Session Management
+### First Run
 
 ```bash
-# Save session
-nexus session save my-work
+# 1. Configure your API endpoint
+nexus config set services.apiUrl https://your-nexus-api.com
 
-# List sessions
-nexus session list
+# 2. Authenticate
+nexus auth login
+# Opens browser for OAuth, or use API key:
+nexus auth login --api-key YOUR_API_KEY
 
-# Resume session
-nexus session load my-work
+# 3. Verify connection
+nexus services health
 
-# Export/import
-nexus session export my-work > session.json
-nexus session import < session.json
+# 4. Explore what's available
+nexus --help
+nexus services list
+nexus mcp tools
 ```
 
-### Configuration
+### Your First Commands
 
 ```bash
-# Show current config
-nexus config list
+# Ask a natural language question
+nexus ask "What services are currently running?"
 
-# Get specific value
-nexus config get services.api_url
-
-# Set value
-nexus config set defaults.output_format json
+# Check all service health
+nexus services health --all
 
-# Manage profiles
-nexus config profiles list
-nexus config profiles use production
+# Start an interactive session
+nexus repl
 
-# Initialize workspace
-nexus config init
+# Run an autonomous agent task
+nexus agent task "Analyze authentication patterns in the codebase"
 ```
 
-### Output Formats
+---
 
-```bash
-# JSON output (for scripting)
-nexus services list --output-format json
+## Command Reference
 
-# Streaming JSON (real-time)
-nexus videoagent process-video --url video.mp4 --output-format stream-json
+### Core Commands
 
-# Table output
-nexus services status --output-format table
+| Command | Description |
+|---------|-------------|
+| `nexus auth login` | Authenticate with Nexus API |
+| `nexus auth logout` | Clear stored credentials |
+| `nexus auth whoami` | Show current user info |
+| `nexus config set <key> <value>` | Update configuration |
+| `nexus config get <key>` | Get configuration value |
+
+### Service Commands
 
-# YAML output
-nexus services list --output-format yaml
+| Command | Description |
+|---------|-------------|
+| `nexus services list` | List all discovered services |
+| `nexus services health [--all]` | Check service health |
+| `nexus services info <service>` | Get detailed service info |
+| `nexus services logs <service>` | Stream service logs |
+| `nexus services restart <service>` | Restart a service |
+
+### Agent Commands
+
+| Command | Description |
+|---------|-------------|
+| `nexus agent task <description>` | Run autonomous agent task |
+| `nexus agent orchestrate` | Multi-agent orchestration |
+| `nexus agent status <id>` | Check agent task status |
+| `nexus agent list` | List running agents |
+| `nexus agent stop <id>` | Stop running agent |
+
+### MCP Commands
+
+| Command | Description |
+|---------|-------------|
+| `nexus mcp tools` | List available MCP tools |
+| `nexus mcp run <tool> [args]` | Execute an MCP tool |
+| `nexus mcp servers` | List MCP servers |
+| `nexus mcp status` | MCP connection status |
+
+### Session Commands
+
+| Command | Description |
+|---------|-------------|
+| `nexus session save <name>` | Save current session |
+| `nexus session load <name>` | Load saved session |
+| `nexus session list` | List all saved sessions |
+| `nexus session export` | Export session to file |
+
+### Workflow Commands
+
+| Command | Description |
+|---------|-------------|
+| `nexus workflow run <file>` | Execute workflow from YAML |
+| `nexus workflow create` | Interactive workflow builder |
+| `nexus workflow list` | List saved workflows |
+| `nexus workflow status <id>` | Check workflow status |
+
+### Analytics Commands
+
+| Command | Description |
+|---------|-------------|
+| `nexus analytics costs` | View cost breakdown |
+| `nexus analytics usage` | View usage statistics |
+| `nexus analytics performance` | Performance metrics |
 
-# Quiet mode
-nexus sandbox execute --code "..." --quiet
+---
+
+## Architecture
 
-# Verbose mode
-nexus mageagent orchestrate --task "..." --verbose
 ```
++-----------------------------------------------------------------------------+
+|                              NEXUS CLI                                       |
++-----------------------------------------------------------------------------+
+|                                                                             |
+|   +------------------+  +------------------+  +-------------------------+   |
+|   |    Commands      |  |      REPL        |  |     Plugin System       |   |
+|   |   (60+ cmds)     |  |  (Interactive)   |  |    (SDK + Hooks)        |   |
+|   +--------+---------+  +--------+---------+  +------------+------------+   |
+|            |                     |                         |                |
+|            +---------------------+-------------------------+                |
+|                                  |                                          |
+|                     +------------v------------+                             |
+|                     |     Command Router      |                             |
+|                     |  (Discovery + Routing)  |                             |
+|                     +------------+------------+                             |
+|                                  |                                          |
+|            +---------------------+---------------------+                    |
+|            |                     |                     |                    |
+|     +------v------+       +------v------+       +------v------+            |
+|     | HTTP Client |       |  WebSocket  |       |     MCP     |            |
+|     |  (REST API) |       | (Streaming) |       |   (Tools)   |            |
+|     +------+------+       +------+------+       +------+------+            |
+|            |                     |                     |                    |
++------------+---------------------+---------------------+--------------------+
+             |                     |                     |
+             v                     v                     v
++-----------------------------------------------------------------------------+
+|                        NEXUS PLATFORM SERVICES                               |
++-----------------------------------------------------------------------------+
+|                                                                             |
+|  +-------------+  +-------------+  +-------------+  +-----------------+    |
+|  |  GraphRAG   |  |  MageAgent  |  |   Gateway   |  |   32+ More...   |    |
+|  |   Memory    |  |   Agents    |  |   Routing   |  |    Services     |    |
+|  +-------------+  +-------------+  +-------------+  +-----------------+    |
+|                                                                             |
++-----------------------------------------------------------------------------+
+```
+
+---
 
 ## Configuration
 
-### Global Configuration
+### Environment Variables
 
-Located at: `~/.nexus/config.toml`
+```bash
+# Required
+NEXUS_API_URL=https://your-nexus-api.com
+
+# Authentication (choose one)
+NEXUS_API_KEY=your_api_key_here
+NEXUS_JWT_TOKEN=your_jwt_token_here
+
+# Optional
+NEXUS_OUTPUT_FORMAT=json          # json, yaml, table, text
+NEXUS_STREAMING=true              # Enable real-time streaming
+NEXUS_LOG_LEVEL=info              # debug, info, warn, error
+NEXUS_CACHE_ENABLED=true          # Enable response caching
+NEXUS_CACHE_TTL=300000            # Cache TTL in ms (5 min)
+NEXUS_REQUEST_TIMEOUT=30000       # Request timeout in ms
+NEXUS_MAX_RETRIES=3               # Max retry attempts
+```
+
+### Configuration Files
 
+**Global config**: `~/.nexus/config.toml`
 ```toml
 [services]
-api_url = "http://localhost:9092"
-mcp_url = "http://localhost:9000"
+api_url = "https://your-nexus-api.com"
 timeout = 30000
 
 [auth]
+type = "api-key"
 api_key = "${NEXUS_API_KEY}"
-strategy = "api-key"
 
-[defaults]
-output_format = "json"
+[output]
+format = "json"
+color = true
 streaming = true
-verbose = false
 
 [plugins]
-enabled = ["my-plugin"]
-disabled = []
+directory = "~/.nexus/plugins"
+auto_update = false
 ```
 
-### Workspace Configuration
-
-Located at: `.nexus.toml` (project root)
-
+**Workspace config**: `.nexus.toml`
 ```toml
-[workspace]
+[project]
 name = "my-project"
-type = "typescript"
-
-[agent]
-max_iterations = 20
-auto_approve_safe = true
-
-[nexus]
-auto_store = true
-memory_tags = ["project:my-project"]
-
-[[shortcuts]]
-name = "test"
-command = "sandbox execute --file tests/run.py"
-```
-
-## Plugin Development
+default_service = "graphrag"
 
-### Create a Plugin
-
-```bash
-# Initialize plugin
-nexus plugin init my-plugin --template typescript
-
-# Plugin structure:
-my-plugin/
-├── plugin.json          # Plugin manifest
-├── src/
-│   ├── index.ts        # Main entry point
-│   └── commands/       # Command implementations
-├── package.json
-└── README.md
+[commands]
+# Custom command aliases
+deploy = "workflow run ./deploy.yaml"
+test = "agent task 'Run all tests and report coverage'"
 ```
 
-### Plugin Manifest (plugin.json)
-
-```json
-{
-  "name": "my-plugin",
-  "version": "1.0.0",
-  "description": "My custom plugin",
-  "author": "Your Name",
-  "main": "dist/index.js",
-
-  "commands": [
-    {
-      "name": "analyze",
-      "description": "Analyze data",
-      "args": [
-        {
-          "name": "input",
-          "type": "string",
-          "required": true,
-          "description": "Input file path"
-        }
-      ]
-    }
-  ],
-
-  "permissions": [
-    "file:read",
-    "network:http",
-    "service:graphrag"
-  ]
-}
-```
+---
 
-### Plugin Implementation
+## Plugin Development
 
-```typescript
-import { PluginBuilder } from '@adverant-nexus/cli-sdk';
-
-export default PluginBuilder
-  .create('my-plugin')
-  .version('1.0.0')
-  .description('My plugin')
-
-  .command('analyze', {
-    description: 'Analyze data',
-    args: [{ name: 'input', type: 'string', required: true }],
-    handler: async (args, context) => {
-      // Access Nexus services
-      const result = await context.services.graphrag.query({
-        text: `Analyze file: ${args.input}`
-      });
-
-      return { success: true, data: result };
-    }
-  })
-
-  .build();
-```
+Create powerful extensions with the Nexus SDK.
 
-### Install Plugin
+### Quick Start
 
 ```bash
-# Install locally
-nexus plugin install ./my-plugin
+# Create new plugin
+npx @adverant-nexus/sdk create my-plugin
+cd my-plugin
 
-# Publish to registry
-nexus plugin publish my-plugin
+# Install dependencies
+npm install
 
-# Install from registry
-nexus plugin install my-plugin
+# Build and link
+npm run build
+nexus plugin install ./dist
 ```
 
-## Architecture
-
-The CLI is built with a modular, auto-discovering architecture:
+### Example Plugin
 
-```
-┌─────────────────────────────────────────────────────┐
-│              Adverant-Nexus CLI                     │
-├─────────────────────────────────────────────────────┤
-│  Interactive REPL │ Scripting │ Autonomous Agent    │
-│         ↓              ↓              ↓              │
-│            Command Router (Auto-Discovery)          │
-│         ↓              ↓              ↓              │
-│  Service Commands │ Nexus MCP │ Plugin Commands     │
-│         ↓              ↓              ↓              │
-│         Transport Layer (HTTP | WS | MCP)           │
-│                      ↓                               │
-│           Adverant-Nexus Microservices              │
-└─────────────────────────────────────────────────────┘
+```typescript
+import {
+  NexusPlugin,
+  command,
+  option,
+  PluginContext
+} from '@adverant-nexus/sdk';
+
+export default class AnalyticsPlugin extends NexusPlugin {
+  name = 'analytics';
+  version = '1.0.0';
+  description = 'Custom analytics commands';
+
+  @command('report', 'Generate analytics report')
+  @option('--period <days>', 'Report period in days', '30')
+  @option('--format <type>', 'Output format', 'table')
+  async generateReport(ctx: PluginContext) {
+    const { period, format } = ctx.options;
+
+    // Access Nexus services
+    const analytics = await ctx.services.get('analytics');
+    const data = await analytics.getReport({ days: parseInt(period) });
+
+    // Format and return
+    return ctx.format(data, format);
+  }
+}
 ```
 
-Key components:
-- **Service Discovery**: Auto-discovers services from docker-compose and OpenAPI
-- **Command Router**: Dynamically routes commands to appropriate handlers
-- **Transport Layer**: HTTP, WebSocket, and MCP protocol support
-- **Plugin System**: Third-party extensions with full SDK
-- **Output Formatters**: Multiple output formats for different use cases
+---
 
-See [ARCHITECTURE.md](./ARCHITECTURE.md) for complete details.
+## Contributing
 
-## Development
+We welcome contributions! Nexus CLI is open source and community-driven.
 
-### Build
+### Getting Started
 
 ```bash
+# Fork and clone
+git clone https://github.com/YOUR_USERNAME/Adverant-Nexus-CLI.git
+cd Adverant-Nexus-CLI
+
+# Install dependencies
+npm install
+
+# Build all packages
 npm run build
-```
 
-### Development Mode
+# Run tests
+npm test
 
-```bash
-npm run dev
+# Run in development
+npm run dev:cli
 ```
 
-### Testing
+### Development Guidelines
 
-```bash
-npm test
-npm run test:watch
-npm run test:coverage
-```
+- **TypeScript**: All code must be TypeScript with strict mode
+- **Testing**: Add tests for new features
+- **Commits**: Use [Conventional Commits](https://www.conventionalcommits.org/)
+- **PRs**: Include description, tests, and documentation updates
 
-### Linting
+See [CONTRIBUTING.md](https://github.com/adverant/Adverant-Nexus-CLI/blob/main/CONTRIBUTING.md) for detailed guidelines.
 
-```bash
-npm run lint
-npm run lint:fix
-```
+---
 
-### Type Checking
+## Documentation
 
-```bash
-npm run typecheck
-```
+- [Full Documentation](https://docs.adverant.ai/nexus-cli)
+- [API Reference](https://docs.adverant.ai/nexus-cli/api)
+- [Plugin SDK Guide](https://docs.adverant.ai/nexus-cli/plugins)
+- [Configuration Guide](https://docs.adverant.ai/nexus-cli/config)
 
-## Project Status
-
-### ✅ Completed
-- [x] Comprehensive architecture design (see [ARCHITECTURE.md](./ARCHITECTURE.md))
-- [x] Complete type system (7 type modules)
-- [x] Enhanced package.json with all dependencies
-- [x] Directory structure
-- [x] Documentation (README + ARCHITECTURE)
-
-### 🚧 In Progress
-- [ ] Core CLI framework implementation
-- [ ] Service discovery engine
-- [ ] Transport layers (HTTP, WebSocket, MCP)
-- [ ] Output formatters
-- [ ] Command generation system
-
-### 📋 Upcoming
-- [ ] Service-specific commands (32+ services)
-- [ ] Nexus MCP integration (70+ tools)
-- [ ] Interactive REPL
-- [ ] Plugin system
-- [ ] Agent mode
-- [ ] Session management
-- [ ] Comprehensive tests
-
-## Roadmap
-
-### Phase 1: Core Framework (Week 1)
-- CLI framework setup
-- Configuration management
-- Workspace detection
-- HTTP transport layer
-- Output formatters
-
-### Phase 2: Service Discovery (Week 2)
-- Docker Compose parser
-- OpenAPI schema parser
-- Service discovery engine
-- Auto-command generation
-
-### Phase 3: Service Commands (Week 3)
-- GraphRAG commands
-- MageAgent commands
-- Sandbox commands
-- Service management commands
-
-### Phase 4: Nexus MCP Integration (Week 4)
-- MCP client implementation
-- All 70+ Nexus tools exposed
-- MCP tool discovery
-
-### Phase 5: Advanced Features (Weeks 5-10)
-- Streaming & real-time
-- Interactive REPL
-- Plugin system
-- Agent mode
-- Session management
-- Documentation & testing
+---
 
-## Contributing
+## Security
 
-Contributions are welcome! Please read our contributing guidelines before submitting PRs.
+Security is a top priority. See [SECURITY.md](https://github.com/adverant/Adverant-Nexus-CLI/blob/main/SECURITY.md) for:
+- Reporting vulnerabilities
+- Security best practices
+- Credential management
+
+---
 
 ## License
 
-MIT © Adverant AI
+MIT License - see [LICENSE](https://github.com/adverant/Adverant-Nexus-CLI/blob/main/LICENSE) for details.
 
-## Support
+---
 
-- **Documentation**: [ARCHITECTURE.md](./ARCHITECTURE.md)
-- **Issues**: [GitHub Issues](https://github.com/adverant-ai/adverant-nexus/issues)
-- **Discussions**: [GitHub Discussions](https://github.com/adverant-ai/adverant-nexus/discussions)
+## Acknowledgments
 
-## Related Projects
+Built with these amazing open source projects:
 
-- [@adverant-nexus/sdk](../nexus-sdk) - SDK for building Nexus Nexus plugins
-- [Adverant-Nexus Platform](../../README.md) - Main platform documentation
+- [Commander.js](https://github.com/tj/commander.js/) - CLI framework
+- [Inquirer.js](https://github.com/SBoudrias/Inquirer.js/) - Interactive prompts
+- [Chalk](https://github.com/chalk/chalk) - Terminal styling
+- [Axios](https://github.com/axios/axios) - HTTP client
+- [Zod](https://github.com/colinhacks/zod) - Schema validation
+- [MCP SDK](https://github.com/anthropics/mcp) - Model Context Protocol
 
 ---
 
-**Made with ❤️ by Adverant AI**
+<div align="center">
+
+**Built with love by [Adverant](https://adverant.ai)**
+
+[Website](https://adverant.ai) &#8226; [Documentation](https://docs.adverant.ai) &#8226; [Twitter](https://twitter.com/adverant) &#8226; [Discord](https://discord.gg/adverant)
+
+</div>