navada-edge-cli 3.3.0 → 3.4.1

package/README.md

@@ -1,67 +1,96 @@
-# navada-edge-cli
+# NAVADA Edge CLI
 
-An AI-powered terminal agent for the **NAVADA Edge Network**. Full computer access, distributed infrastructure control, and conversational AI — all from your terminal.
+An AI-powered terminal agent. Install it, type naturally, and control your computer — files, shell, Docker, cloud services, and distributed infrastructure — all through conversation.
 
-```bash
+```
 npm install -g navada-edge-cli
 ```
 
-## Executive Summary
+```
+navada> deploy the API to production and check disk space on all nodes
+  [shell] docker push registry:5000/my-api:latest
+  [lucas_ssh] {"node":"ec2","command":"df -h"}
+
+  NAVADA
+  Deployed my-api to production. EC2: 45% disk used (12G/26G).
+  HP: 32% used. Oracle: 61% used. All nodes healthy.
+```
+
+---
+
+## Table of Contents
+
+- [What is a Terminal?](#what-is-a-terminal)
+- [What is a CLI?](#what-is-a-cli)
+- [NAVADA Edge CLI](#navada-edge-cli-1)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [AI Providers](#ai-providers)
+- [Commands](#commands)
+- [Architecture](#architecture)
+- [Edge Network](#edge-network)
+- [The Vision](#the-vision)
+- [License](#license)
+
+---
+
+## What is a Terminal?
+
+A terminal is a text-based interface to your computer. Before graphical desktops existed, the terminal was the only way to interact with a machine. You type commands, the computer executes them, and prints the result.
+
+Every operating system has one:
+
+| OS | Terminal |
+|---|---|
+| **Windows** | PowerShell, Command Prompt, Windows Terminal |
+| **macOS** | Terminal.app, iTerm2 |
+| **Linux** | GNOME Terminal, Konsole, any shell emulator |
+
+The terminal gives you direct, unfiltered access to your system. When you type `ls` (or `dir` on Windows), the operating system lists files. When you type `node server.js`, it starts a process. There is no button, no menu, no intermediary. You speak to the machine and it responds.
+
+This matters because every server in the world runs on terminals. Cloud infrastructure, Docker containers, CI/CD pipelines, database administration -- all of it happens through text commands. The graphical interface is a layer on top; the terminal is the foundation underneath.
+
+The NAVADA Edge CLI lives in this space. It turns the terminal from a command executor into a conversational AI agent -- one that understands what you want to do and has the tools to do it.
 
-**NAVADA Edge CLI** is a production-grade terminal tool that gives developers and infrastructure teams an AI agent with full system access, connected to a distributed computing network.
+---
 
-### Install
+## What is a CLI?
+
+A CLI (Command-Line Interface) is a program designed to run inside a terminal. Instead of clicking buttons in a window, you type commands and receive text output.
 
 ```bash
-npm install -g navada-edge-cli
-navada
+# A GUI: click File > Open > navigate to folder > click file
+# A CLI: one command
+cat /etc/hosts
 ```
 
-Or run with Docker:
+CLIs differ from GUIs (Graphical User Interfaces) in several important ways:
+
+**Speed.** A CLI command executes immediately. No loading screens, no animations, no waiting for a window to render. You type, it runs.
+
+**Composability.** CLI commands can be chained together. The output of one becomes the input of another. This is called piping, and it is the foundation of Unix philosophy:
 
 ```bash
-docker run -it navada-edge-cli:3.0.2
+docker ps | grep navada | wc -l
 ```
 
-**The problem:** Managing distributed infrastructure across multiple cloud providers, on-prem servers, and services requires jumping between terminals, dashboards, and APIs. AI assistants answer questions but can't execute.
+That single line lists running containers, filters for NAVADA services, and counts them. Three tools, one pipeline, instant result.
 
-**The solution:** One CLI that talks naturally, executes commands locally and remotely, and unifies access to your entire infrastructure through a conversational AI agent with tool use, streaming, and smart model routing.
+**Automation.** Anything you type in a CLI can be put in a script. A script is just a file full of commands. This is how infrastructure-as-code works: instead of manually clicking through cloud dashboards, you write scripts that configure servers, deploy applications, and manage databases automatically.
 
-**Key differentiators:**
-- **Free tier included** — Grok AI with 30 RPM, no API key needed, just install and go
-- **Multi-provider AI** — Anthropic (Claude Sonnet 4), OpenAI (GPT-4o/mini), Grok, Qwen Coder — all with streaming
-- **Smart routing** — auto-picks the best model: code queries to Qwen, complex to Claude, general to Grok
-- **Conversational AI agent** — type naturally, the agent uses tools to execute (not just answer)
-- **Full computer access** — shell, files, processes, Python execution on your local machine
-- **Distributed network** — 4 physical nodes connected via Tailscale VPN, managed from one terminal
-- **Two sub-agents** — Lucas CTO (infrastructure) and Claude CoS (communications + automation)
-- **Cloud-native** — Cloudflare (R2, Flux AI, Stream, DNS), Azure (n8n), private Docker registry
-- **58 slash commands** — direct access when you need precision
-- **3 learning modes** — `/learn python`, `/learn csharp`, `/learn node` — interactive tutor mode
-- **Split-panel TUI** — session info, token usage, rate limits, provider status
-- **4 themes** — dark, crow (achromatic), matrix, light
-- **Docker-first** — runs as a container with `restart: always`, ships with Dockerfile
-- **Cross-platform** — Windows, macOS, Linux
-- **Zero config to start** — install and start talking, free tier works immediately
+**Reproducibility.** A CLI command is text. It can be documented, version-controlled, shared, and re-run identically. A series of GUI clicks cannot.
 
-**Who it's for:** DevOps engineers, infrastructure teams, AI developers, and anyone who manages distributed systems and wants an AI copilot in their terminal.
+Developers, system administrators, and infrastructure engineers prefer CLIs because they are faster, scriptable, and precise. The NAVADA Edge CLI takes this further by adding an AI agent layer -- instead of memorising hundreds of commands, you describe what you want in plain English and the agent executes the right tools.
 
-**Pricing:** The CLI is free and open source (MIT). Free tier (Grok) works out of the box. Add your own API key for full agent mode (Anthropic, OpenAI, or HuggingFace).
+---
 
-```
-╭─────────────────────────────────────────────────────────╮
-│   ███╗   ██╗ █████╗ ██╗   ██╗ █████╗ ██████╗  █████╗    │
-│   ██╔██╗ ██║███████║██║   ██║███████║██║  ██║███████║   │
-│   ██║ ╚████║██║  ██║ ╚████╔╝ ██║  ██║██████╔╝██║  ██║   │
-│            E D G E   N E T W O R K   v3.0.2             │
-╰─────────────────────────────────────────────────────────╯
-```
+## NAVADA Edge CLI
 
-## What is this?
+NAVADA Edge CLI is an AI-powered operating system layer that runs in your terminal. It is the first interface to the NAVADA Edge Network -- a distributed computing platform built for AI workloads, infrastructure management, and developer tooling.
 
-NAVADA Edge CLI is a **conversational AI agent** that runs in your terminal. It has full access to your local machine (files, shell, processes) and connects to the NAVADA Edge Network — a distributed infrastructure spanning 4 physical nodes, Cloudflare, Azure, and AI services.
+### What it does
 
-**Just type naturally.** No commands needed.
+The CLI wraps your terminal in a conversational AI agent. It has tools for file operations, shell execution, Docker management, remote SSH, database queries, cloud services, image generation, and more. You can use slash commands for precision or type naturally and let the agent figure out what to do.
 
 ```
 navada> what images are in the docker registry?
@@ -73,235 +102,499 @@ navada> what images are in the docker registry?
 ```
 
 ```
-navada> check disk space on EC2
-  [lucas_ssh] {"node":"ec2","command":"df -h"}
+navada> create a Python script that fetches weather data and save it to weather.py
+  [write_file] {"path":"weather.py","content":"import requests\n..."}
 
   NAVADA
-  EC2 disk usage: 45% used (12G/26G). /dev/xvda1 mounted at /.
+  Written: /Users/you/weather.py
 ```
 
+### How it works under the hood
+
+The CLI is a Node.js application that maintains a conversation loop with an AI provider. When you type a message, it goes through this pipeline:
+
+1. **Input parsing** -- slash commands are routed directly to handlers; natural language goes to the AI agent
+2. **Provider routing** -- the agent selects the appropriate AI provider based on your configuration (NAVADA free tier, Anthropic, OpenAI, Google, NVIDIA, or HuggingFace)
+3. **Tool execution** -- the AI can call tools (shell, file I/O, network, Docker, MCP) and receive results, then continue reasoning
+4. **Streaming** -- responses stream token-by-token to your terminal in real time
+5. **Context management** -- conversation history (last 40 turns) is maintained so the agent remembers what you discussed
+
+The agent uses a tool-use loop: the AI decides which tool to call, the CLI executes it locally, sends the result back, and the AI continues until the task is complete. This means the agent can chain multiple operations in a single response.
+
+---
+
+## Installation
+
+Requires **Node.js 18+**.
+
+### Global install (recommended)
+
+```bash
+npm install -g navada-edge-cli
+navada
 ```
-navada> create a file called hello.txt with "Hello from NAVADA"
-  [write_file] {"path":"hello.txt","content":"Hello from NAVADA"}
 
-  NAVADA
-  ✓ Written: /Users/you/hello.txt
+This adds the `navada` command to your PATH. Run it from anywhere.
+
+### Local / project install
+
+```bash
+npm install navada-edge-cli
+npx navada
 ```
 
-## Network Architecture
+Useful when you want a specific version pinned to a project, or when you do not have permission to install globally.
+
+### Verify installation
+
+```bash
+navada --version
+```
 
-![NAVADA Edge Network](https://cdn.jsdelivr.net/npm/navada-edge-sdk@1.2.0/network.svg)
+---
 
 ## Quick Start
 
 ```bash
-# Install
+# 1. Install
 npm install -g navada-edge-cli
 
-# Start the CLI
+# 2. Launch
 navada
 
-# Login with your API key (Anthropic recommended for full agent mode)
-/login sk-ant-your-key-here
+# 3. Start talking (free tier, no key needed)
+navada> hello, what can you do?
 
-# Start talking
-hello, what can you do?
+# 4. Try some commands
+navada> /status
+navada> /help
+navada> list files in my home directory
+navada> create a file called test.txt with "Hello from NAVADA"
+```
+
+The free tier uses GPT-4o-mini via the NAVADA Edge server. No API key required -- install and go.
+
+To unlock full agent mode with tool use, add your own API key:
+
+```bash
+navada> /login sk-ant-your-anthropic-key
+```
+
+To connect to the NAVADA Edge Network for distributed infrastructure access:
+
+```bash
+navada> /onboard
+navada> /edge login nv_edge_your_key_here
 ```
 
-The CLI accepts **any** API key:
+---
 
-| Key Type | Prefix | What You Get |
-|----------|--------|-------------|
-| **Anthropic** | `sk-ant-...` | Full agent with tool use — recommended |
-| **OpenAI** | `sk-...` | GPT-4o chat |
-| **HuggingFace** | `hf_...` | Qwen Coder (FREE) |
-| **NAVADA Edge** | `nv_edge_...` | MCP server access + all network tools |
+## AI Providers
 
-## Features
+The CLI supports 6 AI providers. Each is activated by logging in with the corresponding API key.
 
-### AI Agent with Tool Use
+| Provider | Key Prefix | Model | Cost | Tool Use |
+|---|---|---|---|---|
+| **NAVADA Free Tier** | (none needed) | GPT-4o-mini | Free (30 RPM) | No |
+| **Anthropic** | `sk-ant-...` | Claude Sonnet 4 | Paid | Yes (full agent) |
+| **OpenAI** | `sk-...` | GPT-4o | Paid | Yes |
+| **Google Gemini** | `AIza...` | Gemini 2.0 Flash | Free | No |
+| **NVIDIA** | `nvapi-...` | Llama, DeepSeek, Mistral + 5 more | Free | No |
+| **HuggingFace** | `hf_...` | Qwen Coder 32B | Free | No |
 
-The CLI is powered by Claude Sonnet 4 with 13 tools. It doesn't just answer questions — it **executes tasks**:
+### Login with each provider
 
-| Tool | What it does |
-|------|-------------|
-| `shell` | Run any command on your local machine |
-| `read_file` | Read files from your filesystem |
-| `write_file` | Create or modify files |
-| `list_files` | Browse directories |
-| `system_info` | CPU, RAM, disk, hostname, OS |
-| `network_status` | Ping all NAVADA Edge nodes |
-| `lucas_exec` | Run bash on EC2 via Lucas CTO |
-| `lucas_ssh` | SSH to any node via Lucas |
-| `lucas_docker` | Docker exec in remote containers |
-| `mcp_call` | Call any of 18 MCP server tools |
-| `docker_registry` | Query the private Docker registry |
-| `send_email` | Send email via SMTP or MCP |
-| `generate_image` | Generate images (Flux FREE / DALL-E) |
+```bash
+# NAVADA free tier (default, no login needed)
+navada
+
+# Anthropic — full agent with tool use (recommended)
+navada> /login sk-ant-api03-xxxxx
+
+# OpenAI — GPT-4o with tool use
+navada> /login sk-xxxxx
+
+# Google Gemini — free, fast
+navada> /login AIzaSyxxxxx
+
+# NVIDIA — 8 free models (Llama, DeepSeek, Mistral, etc.)
+navada> /login nvapi-xxxxx
+navada> /nvidia models
+
+# HuggingFace — Qwen Coder 32B, free
+navada> /login hf_xxxxx
+```
+
+### NVIDIA models
 
-### Two AI Agents
+NVIDIA provides 8 models for free via [build.nvidia.com](https://build.nvidia.com):
 
-| Agent | Role | Access |
-|-------|------|--------|
-| **Lucas CTO** | Infrastructure agent on EC2 | bash, SSH, Docker, deploy, file operations |
-| **Claude CoS** | Chief of Staff | Email, image gen, SMS, research, automation |
+| Model | ID |
+|---|---|
+| Meta Llama 3.3 70B | `llama-3.3-70b` |
+| Meta Llama 3.1 8B | `llama-3.1-8b` |
+| DeepSeek R1 | `deepseek-r1` |
+| Mistral Large 2 | `mistral-large` |
+| Code Llama 70B | `codellama-70b` |
+| Google Gemma 2 27B | `gemma-2-27b` |
+| Microsoft Phi 3 Medium 128K | `phi-3-medium` |
+| NVIDIA Nemotron 70B | `nemotron-70b` |
 
+```bash
+navada> /model deepseek-r1
+navada> /nvidia chat explain Docker networking
 ```
-navada> /agents
-  ● Lucas CTO      ONLINE (MCP http://100.x.x.x:8820)
-    Tools: bash, ssh, docker_exec, deploy, read_file, write_file
 
-  ● Claude CoS     ONLINE (Dashboard http://100.x.x.x:7900)
-    Controls: Telegram, email, SMS, image gen, R2, cost tracking
+### Model selection
 
-  ● MCP Server     ONLINE (http://100.x.x.x:8811)
-    Version: 1.0.0
+```bash
+navada> /model               # show all available models
+navada> /model auto          # smart routing (picks best per query)
+navada> /model claude        # always use Claude Sonnet 4
+navada> /model gpt-4o        # always use GPT-4o
+navada> /model deepseek-r1   # always use DeepSeek R1
 ```
 
-### 45+ Slash Commands
+---
+
+## Commands
+
+75 commands organised by category. Use `/help` inside the CLI for the full list.
+
+### AI
+
+| Command | Description |
+|---|---|
+| `/chat <msg>` | Chat with NAVADA Edge AI agent |
+| `/qwen <prompt>` | Qwen Coder 32B (free via HuggingFace) |
+| `/yolo detect <img>` | Object detection on an image |
+| `/yolo model` | Show YOLO model info |
+| `/image <prompt>` | Generate image (Flux, free) |
+| `/image --dalle <prompt>` | Generate image (DALL-E 3) |
+| `/model [name]` | Show or set default AI model |
+| `/research <query>` | RAG search via MCP server |
+| `/retry` | Resend the last message to the AI |
+| `/tokens` | Show session token usage and cost |
+| `/clear` | Clear conversation history and reset session |
+| `/save [name]` | Save current conversation to disk |
+| `/load <name>` | Load a saved conversation |
+| `/conversations` | List all saved conversations |
+
+### NVIDIA
+
+| Command | Description |
+|---|---|
+| `/nvidia login <key>` | Set NVIDIA API key |
+| `/nvidia models` | List all available NVIDIA models |
+| `/nvidia model <name>` | Set default NVIDIA model |
+| `/nvidia chat <msg>` | Chat with selected NVIDIA model |
+| `/nvidia status` | Test NVIDIA API connection |
 
-Use `/commands` for direct control, or just type naturally for the AI agent.
+### NETWORK
 
-**Network**
 | Command | Description |
-|---------|-------------|
-| `/status` | Ping all nodes + cloud services |
+|---|---|
+| `/status` | Ping all nodes and cloud services |
 | `/nodes` | Show node configuration |
-| `/doctor` | Validate all connections |
-| `/ping` | Quick all-nodes ping |
-| `/metrics` | CPU/RAM/disk for all nodes |
-| `/health` | Deep health check |
 | `/dashboard` | Command Dashboard status |
+| `/doctor` | Validate all service connections |
+| `/metrics` | CPU, RAM, disk for all nodes |
+| `/health` | Deep health check |
+| `/ping` | Quick all-nodes ping |
+| `/opencode` | OpenCode status on all nodes |
+
+### AGENTS
 
-**Agents**
 | Command | Description |
-|---------|-------------|
+|---|---|
 | `/agents` | Show Lucas CTO + Claude CoS status |
-| `/claude <msg>` | Send message to Claude CoS |
-| `/lucas exec <cmd>` | Run bash on EC2 via Lucas |
-| `/lucas ssh <node> <cmd>` | SSH to node via Lucas |
-| `/lucas docker <ctr> <cmd>` | Docker exec via Lucas |
-| `/lucas deploy <name> <node>` | Deploy container |
+| `/claude <msg>` | Send message to Claude CoS agent |
+| `/lucas exec <cmd>` | Run bash on EC2 via Lucas CTO |
+| `/lucas ssh <node> <cmd>` | SSH to any node via Lucas |
+| `/lucas docker <ctr> <cmd>` | Docker exec on remote container |
+| `/lucas deploy <name> <node>` | Deploy container to a node |
+| `/lucas status` | Lucas network status |
+| `/lucas files <dir>` | List files on remote node |
+| `/lucas read <file>` | Read file on remote node |
+
+### DOCKER
 
-**Docker**
 | Command | Description |
-|---------|-------------|
-| `/registry` | List images in private registry |
+|---|---|
+| `/registry` | List images in private Docker registry |
 | `/registry tags <image>` | List tags for an image |
-| `/deploy <name> <node>` | Deploy container to node |
+| `/deploy <name> <node>` | Deploy container to a node |
 | `/logs <container>` | View container logs |
 
-**AI**
+### MCP
+
 | Command | Description |
-|---------|-------------|
-| `/chat <msg>` | Chat with NAVADA Edge AI |
-| `/qwen <prompt>` | Qwen Coder 32B (FREE) |
-| `/yolo detect <img>` | Object detection |
-| `/image <prompt>` | Generate image (Flux FREE) |
-| `/image --dalle <prompt>` | Generate with DALL-E 3 |
-| `/model` | Show/set AI model |
-| `/research <query>` | RAG search via MCP |
-
-**Cloudflare**
+|---|---|
+| `/mcp tools` | List all MCP server tools |
+| `/mcp call <tool> [json]` | Call an MCP tool directly |
+
+### CLOUDFLARE
+
 | Command | Description |
-|---------|-------------|
-| `/r2 ls [prefix]` | List R2 objects |
-| `/r2 upload <key> <file>` | Upload to R2 |
-| `/dns` | List DNS records |
+|---|---|
+| `/r2 ls [prefix]` | List R2 storage objects |
+| `/r2 buckets` | List R2 buckets |
+| `/r2 upload <key> <file>` | Upload file to R2 |
+| `/r2 delete <key>` | Delete R2 object |
+| `/r2 url <key>` | Get public URL for R2 object |
+| `/dns` | List Cloudflare DNS records |
 | `/dns create <type> <name> <val>` | Create DNS record |
 | `/tunnel` | List Cloudflare tunnels |
-| `/stream` | List Stream videos |
-| `/flux <prompt>` | Generate image (FREE) |
-| `/trace <url>` | Trace through WAF |
+| `/stream` | List Cloudflare Stream videos |
+| `/flux <prompt>` | Generate image (free Cloudflare AI) |
+| `/trace <url>` | Trace request through Cloudflare WAF |
+
+### DATABASE
+
+| Command | Description |
+|---|---|
+| `/db <sql>` | Query PostgreSQL |
+
+### EDGE
+
+| Command | Description |
+|---|---|
+| `/edge login <key>` | Connect with NAVADA Edge API key |
+| `/edge status` | Check Edge Network connection |
+| `/edge logout` | Disconnect from Edge Network |
+| `/edge tier` | Show current tier and limits |
+| `/onboard` | Open Edge Portal to create account |
+
+### TASKS
+
+| Command | Description |
+|---|---|
+| `/tasks` | List tasks |
+| `/tasks create <title>` | Create a task |
+| `/tasks done <id>` | Mark task complete |
+| `/tasks delete <id>` | Delete a task |
+
+### KEYS
+
+| Command | Description |
+|---|---|
+| `/keys` | List API keys |
+| `/keys create [name]` | Create an API key |
+| `/keys delete <key>` | Delete an API key |
+
+### AZURE
+
+| Command | Description |
+|---|---|
+| `/n8n` | Azure n8n health check |
+| `/n8n restart` | Restart Azure n8n |
+
+### LEARNING
+
+| Command | Description |
+|---|---|
+| `/learn python` | Enter Python learning mode |
+| `/learn csharp` | Enter C# learning mode |
+| `/learn node` | Enter Node.js learning mode |
+| `/learn off` | Exit learning mode |
+
+### SANDBOX
 
-**Database**
 | Command | Description |
-|---------|-------------|
-| `/db <sql>` | Query Postgres |
+|---|---|
+| `/sandbox run <lang>` | Run code with syntax highlighting |
+| `/sandbox exec <file>` | Execute a file in the sandbox |
+| `/sandbox highlight <file>` | Syntax-highlight a file |
+| `/sandbox demo` | Run a demo to test colors |
+
+### SYSTEM
 
-**System**
 | Command | Description |
-|---------|-------------|
+|---|---|
+| `/help` | Show all commands |
 | `/config` | Show all configuration |
-| `/login <key>` | Set API key (auto-detects type) |
+| `/login <key>` | Set API key (auto-detects provider) |
+| `/init <key> <value>` | Set a config value |
 | `/setup` | Guided onboarding wizard |
-| `/theme [name]` | Switch theme (dark/crow/matrix/light) |
-| `/history` | Command history |
-| `/alias <name> <cmd>` | Create shortcut |
+| `/theme [name]` | Switch theme (dark, crow, matrix, light) |
+| `/history [search]` | Command history |
+| `/alias <name> <cmd>` | Create command shortcut |
 | `/watch <cmd> <sec>` | Repeat command on interval |
-| `/export <file>` | Save output to file |
-| `/pipe` | Copy output to clipboard |
-| `/email <to> <subj> <body>` | Send email (SMTP/MCP) |
-| `/email setup` | Configure SMTP (Hotmail/Gmail/Zoho) |
-| `/serve [port]` | Start mobile HTTP UI |
-| `/version` | Version + tier info |
-| `/upgrade` | Check for updates |
-| `/clear` | Clear screen |
+| `/export <file>` | Save last output to file |
+| `/pipe` | Copy last output to clipboard |
+| `/email <to> <subj> <body>` | Send email (SMTP or MCP) |
+| `/email setup` | Configure SMTP provider |
+| `/activity` | Recent activity log |
+| `/version` | Version and tier info |
+| `/upgrade` | Check for CLI updates |
 | `/exit` | Exit CLI |
 
-### 4 Themes
+---
 
-```
-navada> /theme crow      # achromatic, minimal
-navada> /theme matrix    # green terminal
-navada> /theme dark      # default
-navada> /theme light     # blue + white
-```
+## Architecture
+
+![NAVADA Edge Network Architecture](architecture.svg)
 
-### Mobile Access
+### Agent routing
+
+When you type a message, the CLI determines how to handle it:
 
 ```
-navada> /serve 7800
-  MOBILE SERVER
-  Local        http://localhost:7800
-  Network      http://100.x.x.x:7800
-  [QR code displayed]
+User Input
+  |
+  +-- Starts with "/" --> Slash command handler (direct execution)
+  |
+  +-- Natural language --> AI Agent pipeline:
+        |
+        1. Build message array (system prompt + conversation history + user message)
+        2. Select provider:
+        |    - Anthropic key set? --> Claude Sonnet 4 (with tool definitions)
+        |    - OpenAI key set?    --> GPT-4o (with tool definitions)
+        |    - Gemini key set?    --> Gemini 2.0 Flash
+        |    - NVIDIA key set?    --> Selected NVIDIA model
+        |    - HF token set?      --> Qwen Coder 32B
+        |    - No key?            --> NAVADA free tier (GPT-4o-mini via Edge server)
+        |
+        3. Stream response token-by-token to terminal
+        4. If AI requests tool use --> execute tool --> return result --> continue
+        5. Update conversation history (40-turn sliding window)
 ```
 
-Opens a web UI on your phone — same commands, same network access.
+### Tool execution loop
 
-### Email
+The agent (Anthropic and OpenAI providers) supports tool use. The AI model decides which tools to call based on the user's request. Available tools:
 
-```bash
-# Configure SMTP (Hotmail, Gmail, Zoho)
-navada> /email setup
+| Tool | Scope | Function |
+|---|---|---|
+| `shell` | Local | Run any shell command on your machine |
+| `read_file` | Local | Read files from your filesystem |
+| `write_file` | Local | Create or modify files |
+| `list_files` | Local | Browse directories |
+| `system_info` | Local | CPU, RAM, disk, hostname, OS |
+| `python_exec` | Local | Execute Python code |
+| `python_pip` | Local | Install Python packages |
+| `python_script` | Local | Run a Python script file |
+| `sandbox_run` | Local | Run code with syntax highlighting |
+| `network_status` | Network | Ping all NAVADA Edge nodes |
+| `lucas_exec` | Remote | Run bash on EC2 via Lucas CTO |
+| `lucas_ssh` | Remote | SSH to any network node |
+| `lucas_docker` | Remote | Docker exec in remote containers |
+| `mcp_call` | Remote | Call any of 18 MCP server tools |
+| `docker_registry` | Remote | Query the private Docker registry |
+| `send_email` | Remote | Send email via SMTP or MCP |
+| `generate_image` | Remote | Generate images (Flux or DALL-E) |
+| `founder_info` | Local | Information about the NAVADA founder |
 
-# Send directly
-navada> /email user@example.com "Subject" "Body text"
+The execution loop works like this:
 
-# Or ask the agent naturally
-navada> email lee the network status report
-```
+1. User sends message
+2. AI analyses the message and decides to call a tool (e.g., `shell` with `docker ps`)
+3. CLI executes the tool locally and captures the output
+4. Output is sent back to the AI as a tool result
+5. AI reads the result and either calls another tool or writes a final response
+6. If the AI calls another tool, go back to step 3 (up to 10 iterations)
+
+### Rate limiting
 
-### Persistent History
+The free tier enforces a sliding-window rate limit of 30 requests per minute. The CLI tracks this in-memory per session. When the limit is reached, the CLI suggests upgrading to a provider with your own API key.
 
-Commands survive restarts. Search with `/history docker` to find previous Docker commands.
+### Conversation context
 
-### Docker
+The CLI maintains a sliding window of the last 40 conversation turns (20 exchanges). This allows the agent to reference earlier parts of the conversation without exceeding token limits. Conversations can be saved to disk with `/save` and restored with `/load`.
+
+### Streaming
+
+All providers support streaming. Responses appear token-by-token as the AI generates them, rather than waiting for the full response. This is implemented using Server-Sent Events (SSE) for each provider's API.
+
+---
+
+## Edge Network
+
+The NAVADA Edge Network is a distributed computing platform that the CLI connects to. It consists of physical servers, cloud VMs, and services connected via Tailscale VPN.
+
+### What it provides
+
+- **AI chat** -- free-tier GPT-4o-mini via the Edge server (no API key required)
+- **MCP server** -- 18 tools accessible via JSON-RPC (file operations, network, email, image gen, cloud)
+- **Lucas CTO** -- autonomous infrastructure agent running on EC2 (bash, SSH, Docker, deploy)
+- **Docker registry** -- private container registry for deploying to any node
+- **Command Dashboard** -- real-time status, metrics, and activity logs
+
+### Connecting to the Edge Network
 
 ```bash
-# Run in Docker
-docker run -it --env-file .env navada-edge-cli
+# 1. Create an account at the Edge Portal
+navada> /onboard
+
+# 2. Generate an API key in the portal dashboard
+# 3. Connect your CLI
+navada> /edge login nv_edge_your_key_here
 
-# With mobile access
-docker run -it -p 7800:7800 --env-file .env navada-edge-cli --serve
+# 4. Verify connection
+navada> /edge status
+navada> /doctor
 ```
 
+### API key tiers
+
+| Tier | Requests/day | Tokens/day | Edge tasks | Max runtime |
+|---|---|---|---|---|
+| **Free** | 100 | 50K | 10 | 5 minutes |
+| **Pro** | Coming soon | -- | -- | -- |
+| **Enterprise** | Coming soon | -- | -- | -- |
+
+### Portal
+
+The NAVADA Edge Portal is a web application where users create accounts, generate API keys, and monitor their usage. Visit [portal.navada-edge-server.uk](https://portal.navada-edge-server.uk) or run `/onboard` from the CLI.
+
+---
+
+## The Vision
+
+This is the early stage of an AI-powered operating system.
+
+Today, the CLI is a terminal agent -- you install it, type naturally, and it executes tasks on your machine using AI. But the terminal is just the first interface layer. The architecture is designed for what comes next.
+
+### Where this is going
+
+**Local LLM execution.** The CLI currently routes to cloud AI providers. The next step is running models locally on NVIDIA GPUs via Docker containers. Instead of paying per token to a cloud API, your home server runs Llama, Mistral, or DeepSeek locally. The CLI routes to whichever is fastest -- local GPU or cloud API -- transparently.
+
+**Edge compute offloading.** Today, `/lucas exec` sends a command to one remote node. In the future, you will be able to offload long-running tasks (ML training, batch processing, video encoding) to any node in the Edge Network. The CLI submits a task, the network schedules it on an available node, and you get notified when it completes.
+
+**Sub-agents.** Lucas CTO is the first sub-agent -- an autonomous infrastructure manager. More are planned: a security agent for vulnerability scanning, a data agent for ETL pipelines, a monitoring agent for alerting. Each runs in its own container and communicates via MCP.
+
+**agent.md customisation.** Every user will be able to define their own `agent.md` file -- a plain-text configuration that shapes the AI's personality, tools, and behaviour. Your agent becomes uniquely yours: different system prompts, different tool sets, different priorities. This is the NAVADA moat -- an AI operating system that adapts to each user, not a one-size-fits-all chatbot.
+
+**Multi-device.** The CLI already supports mobile access via `/serve`. The vision is a unified agent layer across terminal, web, and mobile -- same context, same tools, same conversation -- wherever you are.
+
+### The operating system analogy
+
+An OS manages hardware resources and provides an interface for users to interact with them. NAVADA Edge does the same thing for AI and distributed compute:
+
+- **Hardware layer** -- physical servers, GPUs, VMs connected via Tailscale
+- **Service layer** -- Docker containers, MCP servers, databases, cloud APIs
+- **Agent layer** -- AI that understands your intent and orchestrates the services
+- **Interface layer** -- CLI today, web portal, mobile, and API tomorrow
+
+The CLI is the shell. The agent is the kernel. The Edge Network is the hardware. Everything else is a service.
+
+---
+
 ## Configuration
 
-All config lives in `~/.navada/config.json`. Set values with:
+All configuration is stored in `~/.navada/config.json`.
 
 ```bash
-navada> /login sk-ant-your-key      # API key
-navada> /init asus 100.x.x.x        # Node IP
-navada> /init mcp http://x.x.x:8811 # MCP server
-navada> /theme crow                  # Theme
-navada> /alias s status              # Alias
+navada> /login sk-ant-your-key       # API key (auto-detects provider)
+navada> /init asus 100.x.x.x         # Set node IP
+navada> /init mcp http://x:8811      # MCP server endpoint
+navada> /theme crow                   # Theme (dark, crow, matrix, light)
+navada> /alias s status               # Create shortcut
 ```
 
-Or use environment variables:
+Environment variables are also supported:
 
-```env
+```
 ANTHROPIC_API_KEY=sk-ant-...
 NAVADA_ASUS=100.x.x.x
 NAVADA_MCP=http://100.x.x.x:8811
@@ -310,19 +603,34 @@ NAVADA_REGISTRY=http://100.x.x.x:5000
 NAVADA_LUCAS=http://100.x.x.x:8820
 ```
 
+---
+
 ## NAVADA Edge Ecosystem
 
 | Package | Install | Purpose |
-|---------|---------|---------|
-| **navada-edge-sdk** | `npm i navada-edge-sdk` | SDK — use in your Node.js apps |
-| **navada-edge-cli** | `npm i -g navada-edge-cli` | CLI — AI agent in your terminal |
+|---|---|---|
+| **navada-edge-sdk** | `npm i navada-edge-sdk` | SDK for Node.js applications |
+| **navada-edge-cli** | `npm i -g navada-edge-cli` | AI agent in your terminal |
+| **Edge Portal** | [portal.navada-edge-server.uk](https://portal.navada-edge-server.uk) | Account management and API keys |
 | **MCP Server** | `POST /mcp` | JSON-RPC tool server (18 tools) |
-| **Docker** | `docker pull navada-edge-cli` | Run CLI in a container |
+
+---
 
 ## Telemetry
 
 The CLI reports anonymous usage events (install, session start, command counts) to the NAVADA Edge Dashboard for monitoring. No personal data or API keys are transmitted. Telemetry requires a configured dashboard endpoint.
 
+---
+
+## Built by
+
+**Leslie (Lee) Akpareva** -- Principal AI Consultant, MBA, MA. 17+ years in enterprise IT, insurance, and AI infrastructure.
+
+- GitHub: [github.com/leeakpareva](https://github.com/leeakpareva)
+- Website: [navada-lab.space](https://www.navada-lab.space)
+
+---
+
 ## License
 
-MIT - Leslie Akpareva / NAVADA
+MIT -- Leslie Akpareva / NAVADA