nixpkgs/docs/README.md

# m3ta-nixpkgs Documentation

Complete documentation for m3ta's personal Nix flake repository.

## Overview

m3ta-nixpkgs is a collection of custom packages, overlays, NixOS modules, and Home Manager modules organized as a modern Nix flake. This repository follows a flakes-only approach (no channels) and provides reusable components for personal infrastructure.

## Getting Started

- **[Quick Start Guide](./QUICKSTART.md)** - Get up and running in 5 minutes
- **[Architecture](./ARCHITECTURE.md)** - Understanding the repository structure and design
- **[Contributing](./CONTRIBUTING.md)** - How to contribute to this repository

## Documentation Sections

### 📚 Guides

Step-by-step guides for common tasks:

- [Getting Started](./guides/getting-started.md) - Initial setup and basic usage
- [Adding Packages](./guides/adding-packages.md) - How to add new packages
- [Adding Modules](./guides/adding-modules.md) - How to add new NixOS or Home Manager modules
- [Port Management](./guides/port-management.md) - Managing service ports across hosts
- [Using Modules](./guides/using-modules.md) - Using NixOS and Home Manager modules
- [Development Workflow](./guides/development-workflow.md) - Development and testing workflow

### 📦 Packages

- [Packages Index](./packages/) - All packages with descriptions
- [Adding Packages](../guides/adding-packages.md) - How to add new packages
- [Templates](../templates.md) - Boilerplate templates

### ⚙️ Modules

Configuration modules for NixOS and Home Manager:

#### NixOS Modules
- [Overview](./modules/nixos/overview.md) - NixOS modules overview
- [mem0](./modules/nixos/mem0.md) - Mem0 REST API server module
- [ports](./modules/nixos/ports.md) - Port management module

#### Home Manager Modules
- [Overview](./modules/home-manager/overview.md) - Home Manager modules overview
- [CLI Tools](./modules/home-manager/cli/) - CLI-related modules
  - [rofi-project-opener](./modules/home-manager/cli/rofi-project-opener.md) - Rofi-based project launcher
  - [stt-ptt](./modules/home-manager/cli/stt-ptt.md) - Push to Talk Speech to Text
  - [zellij-ps](./modules/home-manager/cli/zellij-ps.md) - Zellij project switcher
- [Coding](./modules/home-manager/coding/) - Development-related modules
  - [editors](./modules/home-manager/coding/editors.md) - Editor configurations

### 📖 Reference

Technical references and APIs:

- [Functions](./reference/functions.md) - Library functions documentation
- [Patterns](./reference/patterns.md) - Code patterns and anti-patterns
- [Templates](../templates.md) - Boilerplate for packages and modules

## Repository Structure

```
m3ta-nixpkgs/
├── docs/                    # This directory
│   ├── README.md
│   ├── QUICKSTART.md
│   ├── ARCHITECTURE.md
│   ├── CONTRIBUTING.md
│   ├── guides/
│   ├── packages/
│   ├── modules/
│   └── reference/
├── pkgs/                    # Custom packages
├── modules/
│   ├── nixos/              # NixOS modules
│   └── home-manager/       # Home Manager modules
├── lib/                    # Library functions
├── shells/                 # Development shells
├── overlays/              # Package overlays
├── templates/             # Templates
└── examples/              # Usage examples
```

## Key Concepts

### Flakes-Only Approach

This repository uses modern Nix flakes exclusively. No channels or `nix-channel` commands are needed. All dependencies are declaratively specified in `flake.nix`.

### Namespace Convention

All modules use the `m3ta.*` namespace:

- `m3ta.ports.*` - Port management
- `m3ta.mem0.*` - Mem0 service configuration
- `m3ta.*.enable` - Enable/disable modules

### Port Management

Centralized port management across hosts using the `m3ta.ports` module:

```nix
m3ta.ports = {
  enable = true;
  definitions = { mem0 = 8000; };
  hostOverrides.laptop = { mem0 = 8080; };
  currentHost = "laptop";
};
```

## Supported Systems

- `x86_64-linux` - Primary
- `aarch64-linux` - ARM Linux
- `x86_64-darwin` - macOS (Intel)
- `aarch64-darwin` - macOS (Apple Silicon)

## Quick Commands

```bash
# Validate flake
nix flake check

# Format code
nix fmt

# Build package
nix build .#<package-name>

# List outputs
nix flake show

# Enter dev shell
nix develop
```

## License

Individual packages may have their own licenses. Check each package's `meta.license` attribute.

## Maintainer

[@m3tam3re](https://m3ta.dev)