# NimPak User Guide

Welcome to **NimPak**, the next-generation unified package manager for NexusOS. NimPak provides a single, consistent interface for managing binary packages, applications, and containers, all backed by a powerful Content-Addressable Storage (CAS) system.

## 🚀 Getting Started

### Installation

NimPak is included by default in NexusOS. For other Linux distributions, you can install it via the bootstrap script:

```bash
curl -sSL https://get.nexusos.io/nimpak | sudo bash
```

### Basic Usage

The `nip` command is your main entry point.

```bash
nip help
```

## 📦 Package Formats

NimPak supports three distinct package formats, all stored in the same unified CAS:

### 1. NPK (Nexus Package Kit)
Binary packages for system libraries and tools. Similar to `.deb` or `.rpm` but atomic and deduplicated.

```bash
# Install a package
nip npk install nginx-1.24.0.npk

# List installed packages
nip npk list

# Remove a package
nip npk remove nginx
```

### 2. NIP (Nexus Application Bundle)
Self-contained applications with all dependencies. Similar to `.app` or Flatpak.

```bash
# Install an application
nip app install firefox.nip

# Run an application
nip app run firefox

# List applications
nip app list
```

### 3. NEXTER (Nexus Container)
Lightweight, secure containers for isolated environments.

```bash
# Create a container
nip nexter create dev-env --type=user

# Start a container
nip nexter start dev-env

# Enter container
nip nexter exec dev-env bash
```

## 💾 Unified Storage (CAS)

NimPak uses a **Content-Addressable Storage (CAS)** system located at `~/.local/share/nexus/cas`.

- **Deduplication:** Identical files are stored only once, regardless of how many packages use them.
- **Integrity:** Every file is verified by its cryptographic hash (XXH3/BLAKE3).
- **Atomicity:** Updates are atomic; no broken partial states.

You can inspect the CAS directly:

```bash
nip cas stats
nip cas list
```

### Garbage Collection

To free up space from unused packages or old versions:

```bash
nip gc run
```

## 🔧 Troubleshooting

### Common Issues

**"Package not found"**
- Ensure you have the correct package file or URL.
- Check your network connection.

**"Permission denied"**
- System packages require root privileges (`sudo nip ...`).
- User packages/containers do not.

**"CAS corruption detected"**
- Run `nip cas verify` to check integrity.
- If errors are found, run `nip gc run --force` to clean up invalid objects.

### FAQ

**Q: How is this different from Flatpak?**
A: NimPak unifies system packages, apps, and containers in one storage layer, offering superior deduplication and a single tool for all needs.

**Q: Can I use NimPak on Ubuntu/Fedora?**
A: Yes, NimPak is designed to be distro-agnostic.

**Q: Where are my applications installed?**
A: Applications are linked in `~/.local/share/nexus/nips`, but the actual data resides in the CAS.