# NOVA Documentation

An AI-native workspace that bridges the gap between high-level planning and autonomous execution. From idea to production — all inside a single terminal.

Currently running: openai/gpt-oss-120b · Switch with:model

## 1. Getting Started

NOVA is an AI-native workspace designed to bridge the gap between high-level planning and autonomous execution. It combines a conversational AI engine with real file system access, live code execution, and built-in Git integration — all from the **Spark Terminal**.

🧠  
**Plan**  
Describe your goal in plain English. NOVA generates a detailed architecture and implementation plan.

⚙️  
**Build**  
Verify the plan, then run build it. NOVA autonomously writes and implements the code.

🩹  
**Heal**  
If something breaks, the Healer intercepts errors and patches the code automatically.

✨  
**Clean**  
The Code Janitor refactors for readability, performance, and removes technical debt.

## Installation & Setup

### Install NOVA

The quickest way to get NOVA is via pip:

```bash
pip install nova-bridgeye
```

### Initial Setup

1. **Authentication**  
   Sign in via GitHub OAuth. NOVA requires repository access to perform Git operations, Healer runs, and Janitor cleanups.
2. **Launch the Spark Terminal**  
   After authentication, open the Spark Terminal — this is NOVA's core interaction environment. Type :help at any time to view all available commands.
3. **Project Initialization**  
   For new projects, run the :wizard command to launch the Project Creation Wizard. It scaffolds your project structure and configures NOVA's context automatically.

## Build — The Execution Engine

**Build** is the evolution of chat. It turns abstract prompts into production-ready code through a structured three-phase process.

1. **Planning** — Describe your goal  
   Start by telling NOVA what you want to build in plain English.  
   ```bash
   "Plan me a simple crypto price tracker using free APIs."
   ```
2. **Verification** — Review the plan  
   NOVA generates a detailed implementation plan covering architecture, data flow, and file structure. Review the plan and confirm before proceeding.
3. **Implementation** — Run it  
   Once verified, NOVA autonomously writes and implements all files. The Spark Terminal will show a summary of files created/modified upon completion.  
   ```bash
   build it
   ```

## Auto-Healing — The Healer

Healer runs automatically detect and fix broken logic or runtime errors. Run your command as usual — NOVA handles the rest.

| Command     | Description                                   |
|-------------|-----------------------------------------------|
| run <cmd>  | Execute any command with Auto-Healing enabled |
| run app.py | Example: run a Python script                  |
| run server.js | Example: run a Node.js server              |

**How it works:** If execution fails, NOVA intercepts the stack trace, analyzes the error in context, and initializes the Healer to patch the code iteratively until the command runs successfully.

💡  
Healer supports **Python, Node.js, Go**, and any language that outputs a stack trace to stdout/stderr. Use `run <cmd>`.

## Code Janitor — Refactoring

The Janitor tidies and refactors your code to maintain high health scores. It optimizes for readability, performance, and elimination of technical debt.

1. **Load the file into context**  
   ```bash
   :load <file_name>
   ```
2. **Execute the cleanup**  
   ```bash
   clean
   ```
3. **Review the refactored output**  
   NOVA refactors the code for readability, optimizes performance, and removes technical debt. Review the diff before saving.

## Terminal Command Reference

### Core Modes

| Command      | Action                                                             |
|--------------|--------------------------------------------------------------------|
| run <cmd>   | Run a command with Auto-Healing enabled (e.g., run python app.py) |
| clean        | Run the Code Janitor to refactor and clean the loaded file        |
| build it     | Execute the verified Build plan and autonomously generate code     |

### File & Navigation

| Command       | Action                                                  |
|---------------|---------------------------------------------------------|
| ls / :map    | Show the project file tree                              |
| cd <path>    | Change directory                                       |
| pwd          | Print current working directory                          |
| :load <file> | Load a file into AI context — required before clean or targeted debugging |
| :unload      | Remove files from the current context                   |
| :paste       | Input multiline text or paste external logs            |

### System Operations

| Command        | Action                                                   |
|----------------|--------------------------------------------------------|
| :gitoptions    | Open the Git Operations Center                          |
| :model         | Change the active AI model                             |
| :wizard        | Run the Project Creation Wizard                       |
| reset          | Wipe current session memory for a fresh start         |
| exit           | Shutdown the NOVA session                              |

## Git Operations Center

Access Git workflows directly from the terminal via: `gitoptions`.

### First-Time Setup

On first run of:gitoptions, if no Git repository is detected in your project directory, NOVA will prompt you to **initialize a Git repository** before any other options are available.

```bash
spark terminal >:gitoptions
```
→ No git repo detected. Initialising…
✔ Git repository initialized successfully.

——— AUTOMATION SETTINGS ———
  
» ○ Toggle Auto-Commit  
   ░🔴 OFF░

○ Toggle Auto-Push    
   ░🔴 OFF░

——— ACTIONS ———
  
○ 📝 Manual Commit (Stage & Commit all)

○ 🚀 Push to Origin

○ ⬇️ Pull from Origin

○ 📊 Git Status

——— EXIT ———
  
○ ← Back to Terminal

### Options Explained

| Option               | Description                                                          |
|----------------------|----------------------------------------------------------------------|
| Toggle Auto-Commit   | Automatically commits after each Build or Healer run                  |
| Toggle Auto-Push     | Automatically pushes to origin after every commit                      |
| Manual Commit        | Stages all changes and commits with an AI-generated commit message    |
| Push to Origin       | Pushes the current branch to the remote repository                    |
| Pull from Origin     | Pulls the latest changes from the remote repository                   |
| Git Status           | Displays a summary of staged, unstaged, and untracked files          |

⚠️  
Navigate the Git menu using **arrow keys** and press **Enter** to select an option.

## AI Models

NOVA supports multiple underlying AI models. Switch at any time using `:model` in the Spark Terminal without losing your session context.

The current default model is **openai/gpt-oss-120b**, optimized for large-scale autonomous code generation tasks.

## Subscription & Credit System

Access to NOVA's autonomous features is managed via your subscription tier. Credits are consumed based on the complexity and output of each operation.

| Feature             | Credit Usage                                             |
|---------------------|---------------------------------------------------------|
| Build Actions       | Consumed based on output tokens generated                |
| Healer Runs         | Charged per execution window / iteration                 |
| Janitor Runs        | Charged per execution window                              |
| Navigation & Context| Free (ls, cd, :load, :unload, etc.)                      |

If the Launch Gatekeeper is active, new registrations may be limited based on system load. View your live occupancy and credit limits on your **Dashboard**.

## Frequently Asked Questions

- Do I need to load a file before every command?  
- How do I know when "Build it" has finished?  
- Can I use Healer for any programming language?  
- What if the Healer gets stuck in a loop?  
- How do I initialize Git for the first time?  
- What should Auto-Commit and Auto-Push be set to?  
- How do I install NOVA?  
- How do I contact support?