navada-edge-cli 4.0.0 → 4.2.0

package/README.md

@@ -1,135 +1,53 @@
 # NAVADA Edge CLI
 
-An AI-powered terminal agent. Install it, type naturally, and control your computer — files, shell, Docker, cloud services, and distributed infrastructure — all through conversation.
+An AI agent that lives in your terminal. It learns who you are, remembers your conversations, and has full access to your machine — files, shell, Python, code execution, and more. Type naturally and it does the work.
 
 ```
 npm install -g navada-edge-cli
 ```
 
 ```
-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> create a Python script that analyses my CSV data and generate a chart
+  [write_file] {"path":"analyse.py","content":"import pandas as pd..."}
+  [python_exec] {"code":"..."}
 
   NAVADA
-  Deployed my-api to production. EC2: 45% disk used (12G/26G).
-  HP: 32% used. Oracle: 61% used. All nodes healthy.
+  Done. Created analyse.py and ran it — chart saved to output.png.
+  Your CSV has 1,247 rows across 8 columns. Revenue peaked in March.
 ```
 
 ---
 
 ## 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)
+- [What is This?](#what-is-this)
 - [Installation](#installation)
 - [Quick Start](#quick-start)
+- [How It Works](#how-it-works)
+- [Memory System](#memory-system)
+- [Tools](#tools)
+- [Skills](#skills)
 - [AI Providers](#ai-providers)
+- [Automation Pipeline](#automation-pipeline)
+- [Configuration](#configuration)
 - [Commands](#commands)
-- [Architecture](#architecture)
-- [Edge Network](#edge-network)
 - [The Vision](#the-vision)
+- [Built By](#built-by)
 - [License](#license)
 
 ---
 
-## What is a Terminal?
+## What is This?
 
-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.
+A terminal is the text interface to your computer. Every server, every cloud platform, every CI/CD pipeline runs on terminals. The NAVADA Edge CLI turns your terminal into a conversational AI agent — one that understands what you want and has the tools to do it.
 
-Every operating system has one:
+**What makes it different:**
 
-| 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.
-
----
-
-## 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
-# A GUI: click File > Open > navigate to folder > click file
-# A CLI: one command
-cat /etc/hosts
-```
-
-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 ps | grep navada | wc -l
-```
-
-That single line lists running containers, filters for NAVADA services, and counts them. Three tools, one pipeline, instant result.
-
-**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.
-
-**Reproducibility.** A CLI command is text. It can be documented, version-controlled, shared, and re-run identically. A series of GUI clicks cannot.
-
-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.
-
----
-
-## NAVADA Edge CLI
-
-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.
-
-### Two parts, one CLI
-
-The NAVADA Edge CLI has two distinct modes of operation:
-
-**Part 1: Standalone CLI** -- install from npm, runs on your machine, no account needed. Full AI agent with file operations, shell access, Python execution, code sandbox, and 6 AI providers. The free tier works out of the box. When it runs out, add your own API key. This is a complete, independent developer tool.
-
-**Part 2: Cloud Compute** -- opt-in. Sign up at the Edge Portal, generate an API key, and run tasks 24/7 on AWS or Azure. Your laptop can be closed while jobs run in the cloud. Monitoring, output streaming, and task management built into the same CLI.
-
-Part 1 works without Part 2. Part 2 extends Part 1.
-
-### What it does
-
-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?
-  [docker_registry] {}
-
-  NAVADA
-  The private registry contains: my-api, navada-command-dashboard,
-  navada-edge-mcp, navada-opencode-serve, navada-opencode-server.
-```
-
-```
-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
-  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.
+- **3-tier memory** — the agent remembers you across sessions. Your preferences, your projects, your patterns. It gets better the more you use it.
+- **Full tool access** — shell commands, file operations, Python execution, screenshots, web search. The agent doesn't just talk — it acts.
+- **Bring your own model** — use NVIDIA (free), Anthropic, OpenAI, Google Gemini, or HuggingFace. All providers get the same tools.
+- **Automation pipeline** — describe what you want automated and the NAVADA team sets it up on 24/7 cloud infrastructure.
+- **soul.md + guardrails** — configure who the agent thinks you are and what boundaries it respects. Your agent, your rules.
 
 ---
 
@@ -137,28 +55,18 @@ The agent uses a tool-use loop: the AI decides which tool to call, the CLI execu
 
 Requires **Node.js 18+**.
 
-### Global install (recommended)
-
 ```bash
 npm install -g navada-edge-cli
 navada
 ```
 
-This adds the `navada` command to your PATH. Run it from anywhere.
+That's it. The free tier uses NVIDIA AI models — no API key required. Install and start talking.
 
-### Local / project install
-
-```bash
-npm install navada-edge-cli
-npx navada
-```
-
-Useful when you want a specific version pinned to a project, or when you do not have permission to install globally.
-
-### Verify installation
+### Verify
 
 ```bash
 navada --version
+# navada-edge-cli v4.0.0
 ```
 
 ---
@@ -166,488 +74,384 @@ navada --version
 ## Quick Start
 
 ```bash
-# 1. Install
+# Install and launch
 npm install -g navada-edge-cli
-
-# 2. Launch
 navada
 
-# 3. Start talking (free tier, no key needed)
-navada> hello, what can you do?
+# The agent is ready. Just type:
+navada> what files are in my current directory?
+navada> create a Node.js server that returns "hello world" on port 3000
+navada> explain what this Python script does
+navada> take a screenshot of my screen
 
-# 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"
+# Run the setup wizard for full personalisation
+navada> /setup
 ```
 
-The free tier uses Grok via the NAVADA Edge server. No API key required -- install and go. File operations (create, read, edit, delete folders and files) work on the free tier without any AI provider.
-
-To unlock full agent mode with tool use, add your own API key:
+### First-time setup
 
 ```bash
-navada> /login sk-ant-your-anthropic-key
+navada> /setup
 ```
 
-To connect to the NAVADA Edge Network for distributed infrastructure access:
+This walks you through:
+1. **API key** — free tier works without one, or add your own for unlimited
+2. **soul.md** — tell the agent who you are, what you do, what stack you use
+3. **guardrail.md** — set safety boundaries (what the agent can and can't do)
+4. **Theme** — dark, crow, matrix, or light
 
-```bash
-navada> /onboard
-navada> /edge login nv_edge_your_key_here
-```
+After setup, the agent knows you. It loads your soul.md on every interaction and respects your guardrails.
 
 ---
 
-## AI Providers
+## How It Works
 
-The CLI supports 6 AI providers. Each is activated by logging in with the corresponding API key.
+When you type a message, here's what happens:
 
-| Provider | Key Prefix | Model | Cost | Tool Use |
-|---|---|---|---|---|
-| **NAVADA Free Tier** | (none needed) | Grok (via Edge server) | Free (30 RPM) | File ops only |
-| **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 |
+```
+You type: "create a React component for a login form"
+     |
+     v
+  Input Parser
+  +-- Starts with /  -->  Slash command (direct execution)
+  +-- Natural language  -->  AI Agent pipeline
+         |
+         v
+  Memory Injection
+  +-- Tier 1: Working memory (current conversation + summary)
+  +-- Tier 2: Recent episodes (what you discussed yesterday)
+  +-- Tier 3: Knowledge (you prefer TypeScript, use Next.js)
+         |
+         v
+  Provider Selection (NVIDIA free, Anthropic, OpenAI, Gemini, etc.)
+         |
+         v
+  Tool Execution Loop
+  +-- AI decides: write_file --> create LoginForm.tsx
+  +-- AI decides: shell --> npm install @shadcn/ui
+  +-- AI reads results, continues reasoning
+  +-- Repeat until task is complete (up to 10 iterations)
+         |
+         v
+  Response streams token-by-token to your terminal
+         |
+         v
+  Auto-extract: saves preferences and facts to memory
+```
 
-### Login with each provider
+The agent uses a **tool-use loop**: the AI decides which tool to call, the CLI executes it on your machine, sends the result back, and the AI continues. This means it can chain multiple operations — read a file, modify it, run tests, fix errors — all in one response.
 
-```bash
-# NAVADA free tier (default, no login needed)
-navada
+---
 
-# Anthropic — full agent with tool use (recommended)
-navada> /login sk-ant-api03-xxxxx
+## Memory System
 
-# OpenAI — GPT-4o with tool use
-navada> /login sk-xxxxx
+The agent has a 3-tier memory that works invisibly. You never manage it — it just gets smarter.
 
-# Google Gemini — free, fast
-navada> /login AIzaSyxxxxx
+### Tier 1: Working Memory (in-session)
 
-# NVIDIA — 8 free models (Llama, DeepSeek, Mistral, etc.)
-navada> /login nvapi-xxxxx
-navada> /nvidia models
+- Last 20 full messages kept in buffer
+- Older messages compressed into rolling summary
+- Auto-summarises every 15 turns to prevent context overflow
+- Dies when you close the terminal (but auto-saved as episode)
 
-# HuggingFace — Qwen Coder 32B, free
-navada> /login hf_xxxxx
-```
+### Tier 2: Episodic Memory (cross-session)
 
-### NVIDIA models
+- Every meaningful session is auto-saved as an episode
+- Episodes have timestamps, tags, and summaries
+- "What did we work on yesterday?" — the agent actually knows
+- Stored in `~/.navada/memory/episodes/`
 
-NVIDIA provides 8 models for free via [build.nvidia.com](https://build.nvidia.com):
+### Tier 3: Semantic Knowledge (permanent)
 
-| 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` |
+- Facts, preferences, skills, people — auto-extracted from conversations
+- TF-IDF search (pure JavaScript, zero dependencies)
+- "I prefer TypeScript" — saved permanently, used in every future session
+- Stored in `~/.navada/memory/knowledge.json`
 
-```bash
-navada> /model deepseek-r1
-navada> /nvidia chat explain Docker networking
-```
+### How it feels
 
-### Model selection
+**Session 1:**
+```
+navada> I'm a frontend developer, I use React and TypeScript
+NAVADA: Got it. I'll keep that in mind.
+```
 
-```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
+**Session 2 (next day):**
+```
+navada> help me build a component
+NAVADA: Since you use React with TypeScript, here's a typed functional component...
 ```
 
----
+The agent loaded your preference from Tier 3 knowledge. You never asked it to remember — it just did.
 
-## Commands
+---
 
-72 commands (91 with aliases) organised by category. Use `/help` inside the CLI for the full list.
+## Tools
 
-### AI
+The agent has 16 tools across 7 categories. Every tool works with every AI provider.
 
-| Command | Description |
+### Bash
+| Tool | What it does |
 |---|---|
-| `/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 |
+| `shell` | Execute any shell command (bash, PowerShell, cmd) |
+| `python_exec` | Run Python code inline |
+| `python_pip` | Install Python packages |
+| `python_script` | Run .py script files |
+| `sandbox_run` | Sandboxed code execution (JavaScript, Python, TypeScript) |
+
+### System
+| Tool | What it does |
 |---|---|
-| `/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 |
+| `read_file` | Read any file on your machine |
+| `write_file` | Create or edit files |
+| `list_files` | Browse directories |
+| `system_info` | CPU, RAM, disk, OS, hostname |
 
-### NETWORK
-
-| Command | Description |
+### Data
+| Tool | What it does |
 |---|---|
-| `/status` | Ping all nodes and cloud services |
-| `/nodes` | Show node configuration |
-| `/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
+| `web_search` | Search the web for information |
 
-| Command | Description |
+### Communication
+| Tool | What it does |
 |---|---|
-| `/agents` | Show Lucas CTO + Claude CoS status |
-| `/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
+| `automation_request` | Submit automation requests (emails, campaigns, builds) |
 
-| Command | Description |
+### Memory
+| Tool | What it does |
 |---|---|
-| `/registry` | List images in private Docker registry |
-| `/registry tags <image>` | List tags for an image |
-| `/deploy <name> <node>` | Deploy container to a node |
-| `/logs <container>` | View container logs |
+| `save_memory` | Explicitly save something to long-term knowledge |
+| `recall_memory` | Search across all memory tiers |
 
-### MCP
-
-| Command | Description |
+### Perception
+| Tool | What it does |
 |---|---|
-| `/mcp tools` | List all MCP server tools |
-| `/mcp call <tool> [json]` | Call an MCP tool directly |
-
-### CLOUDFLARE
+| `screenshot` | Capture your screen |
+| `describe_image` | AI-powered image analysis |
 
-| Command | Description |
+### Info
+| Tool | What it does |
 |---|---|
-| `/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 Cloudflare Stream videos |
-| `/flux <prompt>` | Generate image (free Cloudflare AI) |
-| `/trace <url>` | Trace request through Cloudflare WAF |
-
-### DATABASE
+| `founder_info` | About the NAVADA founder |
 
-| Command | Description |
-|---|---|
-| `/db <sql>` | Query PostgreSQL |
+---
 
-### FILES
+## Skills
 
-| Command | Description |
-|---|---|
-| `/read <path>` | Read a file (with line numbers) |
-| `/write <path> <content>` | Write content to a file |
-| `/edit <path> <search> -> <replace>` | Find and replace in a file |
-| `/delete <path>` | Delete a file or empty directory |
-| `/ls [path]` | List files and directories |
-| `/mkdir <path>` | Create a directory |
-| `/touch <path>` | Create an empty file |
+The agent can perform complex, multi-step tasks. These are not commands — just describe what you need.
 
-File operations also work via natural language on any tier (no API key needed):
+**Code Generation** — write, debug, refactor code in any language. Full project scaffolds with configs.
 
-```
-navada> create a folder on my desktop called MyProject
-  Created folder: C:\Users\you\Desktop\MyProject
-```
+**Data Analysis** — process CSV, JSON, Excel with Python/pandas. Generate charts and visualisations.
 
-### EDGE (Part 2 -- Cloud Compute)
+**Automation** — submit requests for 24/7 automation: marketing emails, scheduled reports, data pipelines.
 
-| 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 |
-| `/edge setup` | Create agent.md and sub-agents directory |
-| `/onboard` | Open Edge Portal to create account |
-| `/offload <command>` | Run a task 24/7 on the cloud |
-| `/sessions` | View your cloud task sessions |
-| `/attach <session-id>` | Stream output from a running task |
-| `/kill <session-id>` | Stop a running cloud task |
-
-### TASKS
+**DevOps** — Docker builds, git workflows, package management, CI/CD pipelines.
 
-| Command | Description |
-|---|---|
-| `/tasks` | List tasks |
-| `/tasks create <title>` | Create a task |
-| `/tasks done <id>` | Mark task complete |
-| `/tasks delete <id>` | Delete a task |
+**Research** — web search, technical docs, competitive analysis, summarisation.
 
-### KEYS
+**Content** — blog posts, emails, documentation, diagrams (Mermaid, SVG, HTML).
 
-| Command | Description |
-|---|---|
-| `/keys` | List API keys |
-| `/keys create [name]` | Create an API key |
-| `/keys delete <key>` | Delete an API key |
+**Learning** — interactive tutorials: `/learn python`, `/learn node`, `/learn csharp`. Code review and architecture design.
 
-### AZURE
+---
 
-| Command | Description |
-|---|---|
-| `/n8n` | Azure n8n health check |
-| `/n8n restart` | Restart Azure n8n |
+## AI Providers
 
-### LEARNING
+Bring your own model. All providers get full tool access.
 
-| 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 |
+| Provider | Key Prefix | Models | Cost | How to activate |
+|---|---|---|---|---|
+| **NVIDIA (default)** | `nvapi-...` | Llama 3.3, DeepSeek R1, Mistral + 5 more | Free (rate limited) | Default — no key needed |
+| **Anthropic** | `sk-ant-...` | Claude Sonnet 4 | Paid | `/login sk-ant-xxx` |
+| **OpenAI** | `sk-...` | GPT-4o, GPT-4o-mini | Paid | `/login sk-xxx` |
+| **Google Gemini** | `AIza...` | Gemini 2.0 Flash | Free | `/login AIzaxxx` |
+| **HuggingFace** | `hf_...` | Qwen Coder 32B | Free | `/login hf_xxx` |
 
-### SANDBOX
+### Unlimited access
 
-| Command | Description |
-|---|---|
-| `/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 |
+The free NVIDIA tier has rate limits. For unlimited access:
 
-### SYSTEM
+```bash
+navada> /register       # Create account with name + email
+navada> /setup          # Complete soul.md + guardrails
+```
 
-| Command | Description |
-|---|---|
-| `/help` | Show all commands |
-| `/config` | Show all configuration |
-| `/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 [search]` | Command history |
-| `/alias <name> <cmd>` | Create command shortcut |
-| `/watch <cmd> <sec>` | Repeat command on interval |
-| `/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 |
-| `/audit` | Security and compliance audit (30 checks) |
-| `/exit` | Exit CLI |
+This unlocks full access including automation requests and priority support.
 
 ---
 
-## Architecture
+## Automation Pipeline
 
-![NAVADA Edge Network Architecture](architecture.svg)
+Describe what you want automated. The NAVADA team reviews your request and sets it up on 24/7 cloud infrastructure.
 
-### Agent routing
+```bash
+navada> /automate Send a weekly marketing email to my leads every Monday
+```
 
-When you type a message, the CLI determines how to handle it:
+### How it works
 
-```
-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)
-```
+1. **You submit** — via `/automate` or by asking the agent naturally
+2. **Request queued** — goes to the NAVADA Edge operations team
+3. **Team reviews** — Lee (founder) personally reviews and configures your automation
+4. **You get notified** — email confirmation when it's live
+5. **Track metrics** — view status and results on your dashboard
 
-### Tool execution loop
+### What can be automated
 
-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:
+- Marketing email campaigns and newsletters
+- Scheduled reports and data exports
+- Application builds and deployments
+- Data scraping and processing pipelines
+- Custom recurring tasks
 
-| 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 |
-| `edit_file` | Local | Find and replace text in a file |
-| `delete_file` | Local | Delete a file or empty directory |
-| `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 |
-| `founder_info` | Local | Accurate answers about the NAVADA founder (CV-grounded) |
-| `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) |
-
-The execution loop works like this:
-
-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
-
-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.
-
-### Conversation context
-
-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.
+```bash
+navada> /automate --type marketing Build me a weekly newsletter template
+navada> /automate --type data --schedule daily Scrape competitor prices from 3 sites
+navada> /requests     # View all your submitted requests
+```
 
 ---
 
-## 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.
+## Configuration
 
-### What it provides
+All config lives in `~/.navada/`:
 
-- **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
+```
+~/.navada/
++-- config.json          # API keys, theme, model preferences
++-- soul.md              # Your identity (who you are, your goals)
++-- guardrail.md         # Safety boundaries (what the agent can do)
++-- agent.md             # Custom agent personality (optional)
++-- README.md            # Your workspace quickstart
++-- agents/              # Custom sub-agent personas
++-- memory/
+|   +-- knowledge.json   # Tier 3: permanent knowledge base
+|   +-- episodes/        # Tier 2: session summaries
++-- conversations/       # Saved full conversations
++-- requests/            # Local automation request queue
+```
 
-### Connecting to the Edge Network
+### Key commands
 
 ```bash
-# 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
-
-# 4. Verify connection
-navada> /edge status
-navada> /doctor
+navada> /setup           # Full setup wizard
+navada> /soul            # View your soul.md
+navada> /soul edit       # Edit in your default editor
+navada> /guardrails      # View boundaries
+navada> /guardrails edit # Edit boundaries
+navada> /tools           # Show all agent tools
+navada> /skills          # Show what the agent can do
+navada> /config          # Show all settings
+navada> /login <key>     # Set API key (auto-detects provider)
+navada> /theme crow      # Switch theme
 ```
 
-### API key tiers
-
-| Tier | Cloud Compute | Pricing |
-|---|---|---|
-| **Free** | 3 sessions, 1 concurrent, 5 min max | Free |
-| **Starter** | 10 sessions, 3 concurrent, 15 min max | TBC |
-| **Pro** | 50 sessions, 5 concurrent, 1 hour max | TBC |
-| **Enterprise** | 500 sessions, 10 concurrent, 4 hour max | TBC |
+---
 
-### Portal
+## Commands
 
-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.
+68 commands organised by category. Use `/help` inside the CLI for the full list.
 
----
+### Core
 
-## The Vision
+| Command | Description |
+|---|---|
+| `/help` | Show all commands |
+| `/setup` | Full onboarding wizard |
+| `/tools` | Show agent tools by category |
+| `/skills` | Show what the agent can do |
+| `/login <key>` | Set API key |
+| `/register` | Create NAVADA Edge account |
+| `/config` | Show configuration |
 
-This is the early stage of an AI-powered operating system.
+### AI & Chat
 
-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.
+| Command | Description |
+|---|---|
+| `/chat <msg>` | Chat with the agent |
+| `/model [name]` | Show or set AI model |
+| `/nvidia models` | List free NVIDIA models |
+| `/clear` | Reset conversation |
+| `/save [name]` | Save conversation |
+| `/load <name>` | Load saved conversation |
+| `/retry` | Resend last message |
+| `/tokens` | Session token usage |
 
-### What is built today
+### Automation
 
-**Part 1: Standalone CLI.** Install from npm and go. Full local tools (file CRUD, shell, Python, sandbox), 6 AI providers, conversation history, agent.md customisation, sub-agents, learning modes, code sandbox. Works completely independently with no account or sign-up required. Free tier included, or bring your own API key.
+| Command | Description |
+|---|---|
+| `/automate <desc>` | Submit automation request |
+| `/requests` | View your requests |
 
-**Part 2: Cloud Compute.** Sign up at the Edge Portal, generate an API key, and offload tasks to AWS (EC2) for 24/7 execution. Tasks run when your laptop is closed. Monitor sessions, stream output, kill tasks -- all from the CLI. Authenticated via `nv_edge_` API keys with tier-based limits.
+### Edge Network
 
-**agent.md customisation.** Every user can define their own `agent.md` file at `~/.navada/agent.md` -- a plain-text configuration that shapes the AI's personality, tools, and behaviour. Your agent becomes uniquely yours. Sub-agents live in `~/.navada/agents/` and can be switched mid-session with `/agent use <name>`.
+| Command | Description |
+|---|---|
+| `/edge login <key>` | Connect to NAVADA Edge |
+| `/edge status` | Check connection |
+| `/edge tier` | Show tier and limits |
+| `/edge usage` | View usage stats |
+| `/onboard` | Open portal in browser |
 
-**Knowledge skills.** The CLI uses Python-based knowledge skills for grounded, accurate responses. Instead of the AI hallucinating, factual data is baked into Python scripts that the agent calls as tools. No RAG infrastructure needed -- just a Python file and a prompt.
+### Identity
 
-### Where this is going
+| Command | Description |
+|---|---|
+| `/soul` | View soul.md |
+| `/soul edit` | Edit soul.md |
+| `/guardrails` | View guardrail.md |
+| `/guardrails edit` | Edit guardrail.md |
+| `/agent list` | List sub-agents |
+| `/agent use <name>` | Activate sub-agent |
 
-**Azure compute node.** A second cloud region for redundancy and lower latency. The CLI will route tasks to the nearest available node.
+### Learning
 
-**Local LLM execution.** 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.
+| Command | Description |
+|---|---|
+| `/learn python` | Python interactive tutor |
+| `/learn node` | Node.js interactive tutor |
+| `/learn csharp` | C# interactive tutor |
+| `/learn off` | Exit learning mode |
 
-**More 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.
+### System
 
-**Multi-device.** The CLI 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.
+| Command | Description |
+|---|---|
+| `/theme [name]` | Switch theme |
+| `/history` | Command history |
+| `/alias <name> <cmd>` | Create shortcut |
+| `/export <file>` | Save output to file |
+| `/version` | Version info |
+| `/upgrade` | Check for updates |
 
-### 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:
+## The Vision
 
-- **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
+This is the early stage of an AI-powered operating system layer.
 
-The CLI is the shell. The agent is the kernel. The Edge Network is the hardware. Everything else is a service.
+Today, the CLI is a terminal agent — install it, talk naturally, and it works on your machine. But the terminal is just the first interface.
 
----
+**Where this is going:**
 
-## Configuration
+- **Memory that compounds** — the longer you use it, the better it understands you. Your agent becomes uniquely yours.
+- **Automation marketplace** — submit what you need, get it running on cloud infrastructure. Email campaigns, data pipelines, scheduled reports — all managed for you.
+- **Local LLM execution** — run models on your own GPU instead of cloud APIs. Same interface, zero cost.
+- **Sub-agents** — specialised personas for security, data engineering, marketing, DevOps. Switch between them with `/agent use`.
+- **Multi-device** — same agent, same memory, across terminal, web, and mobile.
 
-All configuration is stored in `~/.navada/config.json`.
+### The operating system analogy
 
-```bash
-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
-```
+An OS manages hardware and provides an interface. NAVADA Edge does the same for AI:
 
-Environment variables are also supported:
+- **Hardware layer** — your machine + cloud infrastructure
+- **Memory layer** — 3-tier system that persists across sessions
+- **Agent layer** — AI that understands intent and orchestrates tools
+- **Interface layer** — CLI today, web and mobile tomorrow
 
-```
-ANTHROPIC_API_KEY=sk-ant-...
-NAVADA_ASUS=100.x.x.x
-NAVADA_MCP=http://100.x.x.x:8811
-NAVADA_DASHBOARD=http://100.x.x.x:7900
-NAVADA_REGISTRY=http://100.x.x.x:5000
-NAVADA_LUCAS=http://100.x.x.x:8820
-```
+The CLI is the shell. The agent is the kernel. Memory is the filesystem. Everything else is a service.
 
 ---
 
@@ -655,45 +459,15 @@ NAVADA_LUCAS=http://100.x.x.x:8820
 
 | Package | Install | Purpose |
 |---|---|---|
-| **navada-edge-sdk** | `npm i navada-edge-sdk` | SDK for Node.js applications -- build on top of the Edge Network |
 | **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, API keys, usage dashboard |
-| **Edge Compute** | via CLI `/offload` | 24/7 task execution on AWS/Azure |
-| **MCP Server** | `POST /mcp` | JSON-RPC tool server (18 tools) |
-
-### SDK usage
-
-The CLI ships with the NAVADA Edge SDK as a dependency. You can also install it independently to build your own applications:
-
-```bash
-npm install navada-edge-sdk
-```
-
-```javascript
-const navada = require('navada-edge-sdk');
-
-// Configure
-navada.init({ mcpApiKey: 'nv_edge_your_key' });
-
-// Use
-const status = await navada.network.ping();
-const result = await navada.mcp.call('server_status');
-const image = await navada.cloudflare.flux.generate('a sunset over mountains');
-```
-
-The SDK provides programmatic access to the same services the CLI uses: network nodes, MCP tools, Cloudflare (R2, Flux, Stream, DNS), AI providers, Docker registry, and PostgreSQL.
-
----
-
-## 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.
+| **navada-edge-sdk** | `npm i navada-edge-sdk` | SDK for Node.js applications |
+| **Edge Portal** | [portal.navada-edge-server.uk](https://portal.navada-edge-server.uk) | Account management and API keys |
 
 ---
 
-## Built by
+## Built By
 
-**Leslie (Lee) Akpareva** -- Principal AI Consultant, MBA, MA. 17+ years in enterprise IT, insurance, and AI infrastructure.
+**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)
@@ -702,4 +476,4 @@ The CLI reports anonymous usage events (install, session start, command counts)
 
 ## License
 
-MIT -- Leslie Akpareva / NAVADA
+MIT — Leslie Akpareva / NAVADA