# Nexus NIIX Documentation

Welcome to the Nexus NIIX documentation. Here you'll find everything you need to understand and use our sovereign technology stack.

## Quick Start

### Installation

```bash
# Install NexusOS
git clone https://git.sovereign-society.org/nexus/nexus.git
cd nexus
./bootstrap.sh
```

### Your First Project

```bash
# Create a new sovereign project
nexus new my-app
cd my-app
nexus run
```

## Core Concepts

### Sovereign by Design

Nexus NIIX is built around the principle of **user sovereignty**:
- No external dependencies
- No vendor lock-in
- Full cryptographic verification
- Your keys, your data

### Content-Addressed Storage

Every piece of data in Nexus NIIX has a cryptographic identity:
- **Integrity**: Verify data hasn't been tampered with
- **Deduplication**: Automatically detect identical content
- **Referencing**: Use content hashes as permanent URLs

### Mesh Networking

Decentralized peer-to-peer communication without central points of failure.

## Ecosystem

### NexFS

Native Zig flash filesystem optimized for:
- IoT sensors (nexfs-core: ~40KB)
- Personal devices (nexfs-sovereign: ~120KB)
- Home servers (nexfs-mesh: ~200KB)

### Rumpk

Runtime package manager with:
- Cryptographic signing
- Content-addressed storage
- Dependency resolution
- Secure execution

### Nip

Package format specification:
- Dependency declarations
- Version constraints
- Cryptographic manifests
- Distribution-agnostic

## Architecture

```
┌─────────────────────────────────────────┐
│           Nexus NIIX Stack              │
├─────────────────────────────────────────┤
│  Application Layer (Your Code)          │
├─────────────────────────────────────────┤
│  Rumpk (Package Manager)                │
├─────────────────────────────────────────┤
│  Nip (Package Format)                   │
├─────────────────────────────────────────┤
│  NexFS (Filesystem)                     │
├─────────────────────────────────────────┤
│  Hardware (Flash, Memory, CPU)          │
└─────────────────────────────────────────┘
```

## Configuration

### System Requirements

- **Minimum**: 1GB RAM, 10GB storage
- **Recommended**: 2GB RAM, 50GB storage
- **Supported**: x86_64, ARM64, RISC-V

### Environment Variables

```bash
NEXUS_HOME=~/.nexus
NEXUS_DATA=/data/nexus
NEXUS_LOG_LEVEL=info
```

## API Reference

### Core CLI Commands

| Command | Description |
|---------|-------------|
| `nexus init` | Initialize new project |
| `nexus build` | Build project |
| `nexus run` | Run development server |
| `nexus deploy` | Deploy to production |
| `nexus update` | Update Nexus NIIX |
| `nexus doctor` | System diagnostics |

### Programmatic API

```javascript
import { Nexus } from '@nexus/core';

const nexus = new Nexus({
  home: '~/.nexus',
  data: '/data/nexus'
});

// Create a new project
await nexus.create('my-app');

// Install a package
await nexus.install('rumpk');

// Run a command
await nexus.run('echo "Hello, Sovereign!"');
```

## Support

- **Git Repository**: https://git.sovereign-society.org/nexus
- **Issue Tracker**: https://git.sovereign-society.org/nexus/nexus/-/issues
- **Community**: https://git.sovereign-society.org/nexus/community

## License

Nexus NIIX is licensed under the **LSL-1.0** (Libertaria Source License 1.0).

See [LICENSE](https://git.sovereign-society.org/nexus/nexus/-/raw/main/LICENSE) for details.