omnixient/docs/getting-started.md

# Getting Started — adopting Omnixient

Omnixient is a Hyprland desktop you build on top of, not a turnkey installer.
There are **two ways to adopt it**:

1. **As a flake input (recommended)** — your own small repo pins Omnixient as
   a dependency. You never edit Omnixient's files, so `nix flake update omni`
   pulls upstream changes with zero merge conflicts. This is the path below.
2. **By forking** — clone Omnixient and edit it directly. More control over
   Omnixient internals, but you maintain a fork. See
   [Forking instead](#forking-instead) at the end.

This guide assumes a working NixOS install (or the official NixOS ISO). New
to NixOS? Read the [NixOS manual](https://nixos.org/manual/nixos/stable/)
and the [NixOS & Flakes Book](https://nixos-and-flakes.thiscute.world/)
first.

---

## What's yours vs. what's Omnixient's

In the dependency model your repo is tiny and owns only **your** stuff:

- `flake.nix` — pins Omnixient + your `settings` (identity, hostname, theme…).
- `hosts/<host>/default.nix` — which packs/options you want.
- `hosts/<host>/hardware-configuration.nix` — your real hardware scan.

Omnixient (the desktop, theming, packs, modules) comes from the pinned input.
You update it like any dependency; it never touches your files.

---

## 1. Scaffold your config

```bash
nix flake init -t git+https://git.atitlan.io/aiolabs/omnixient   # writes flake.nix + hosts/myhost/
cd <your-config>
```

This drops a starter that already wires `omni.lib.mkSystem` +
`omni.nixosModules.omni`. Open `flake.nix` and:

- set `omni.url` to the real repo (pin a tag for reproducibility, e.g.
  `git+https://git.atitlan.io/aiolabs/omnixient?ref=v1.0.0`);
- fill in the `settings` block:

```nix
settings = {
  user = "alice";
  gitName = "Alice Example";
  gitEmail = "alice@example.com";
  hostName = "myhost";
  timeZone = "America/New_York";
  theme = "tokyo-night";        # any module under Omnixient's modules/themes/
  sshKeys = [ ];                # e.g. [ "ssh-ed25519 AAAA… alice@myhost" ]
  stateVersion = "24.11";       # ⚠ the release you FIRST installed — never change
};
```

> **`stateVersion`** is the field that bites people: it is *not* your
> current NixOS version. It pins stateful defaults from your original
> install; changing it on a live system can break data.

## 2. Generate your hardware scan

```bash
sudo nixos-generate-config --show-hardware-config \
  > hosts/myhost/hardware-configuration.nix
```

This captures your disks, filesystems, kernel modules, and CPU microcode.
The template ships a placeholder — replace it before building on real
hardware.

## 3. Choose packs and options

Edit `hosts/myhost/default.nix`. Core (base system + Hyprland desktop +
theming) is always on; everything else is opt-in:

```nix
omni = {
  enable = true;
  desktop.enable = true;
  user = settings.user;
  theme = settings.theme;

  packs.development.enable = true;   # editors, LSPs, compilers, container CLIs
  packs.media.enable = true;         # gimp, inkscape, mpv, obs, …
  # packs.gaming.enable = true;      # Steam, Lutris, Wine
  # packs.bitcoin.enable = true;     # a real bitcoind + lightning node
};
```

The full catalog is in **[docs/packs.md](packs.md)**.

## 4. Track your files, then build

Flakes only see **git-tracked** files, so stage everything first:

```bash
git init && git add .
sudo nixos-rebuild switch --flake .#myhost
```

> **Flakes not enabled yet?** On a stock NixOS install the first command
> fails with `experimental Nix feature 'nix-command' is disabled` — flakes
> are opt-in. Bootstrap the first build with a one-shot flag:
>
> ```bash
> sudo nixos-rebuild switch --flake .#myhost \
>   --extra-experimental-features "nix-command flakes"
> ```
>
> Your `hosts/myhost/default.nix` enables flakes permanently, so later
> rebuilds don't need the flag.

On the next boot you'll have the Omnixient desktop, plus the bundled helpers
(`omni-rebuild`, `omni-update`, `omni-theme`; `omni-help` lists them).

## 5. Set your password

The default is `initialPassword = "omni"`. Change it after first login:

```bash
passwd
```

For a declarative password, use `hashedPasswordFile` with a sops secret
(see [Secrets](#secrets-optional)).

---

## Already on NixOS?

Adopting Omnixient on a machine you already run is the same flow, with three
differences — because you're protecting a working system:

1. **Enable flakes first** (if you're on channels): add
   `nix.settings.experimental-features = [ "nix-command" "flakes" ];` to your
   current `/etc/nixos/configuration.nix` and `sudo nixos-rebuild switch`.
2. **Reuse what you have** — copy your existing
   `hardware-configuration.nix` into `hosts/myhost/`, and carry your
   **existing `stateVersion` across verbatim** (never bump it).
3. **Preview before you switch** — Omnixient is a full opinionated desktop
   (Hyprland + greetd login manager + services), so it *will* change your
   desktop:
   ```bash
   sudo nixos-rebuild build   --flake .#myhost   # build only, catch errors
   sudo nixos-rebuild build-vm --flake .#myhost && ./result/bin/run-*-vm  # try it in a VM
   ```
   When happy, `switch`. If it's not what you want, roll back instantly from
   the boot menu or `sudo nixos-rebuild switch --rollback` — your old
   generation is untouched.

> If you currently run GNOME/KDE/another login manager, expect overlap with
> greetd + Hyprland; preview in the VM first and disable the old desktop in
> the same switch.

---

## Updating

```bash
nix flake update omni            # pull the latest Omnixient
sudo nixos-rebuild switch --flake .#myhost
```

This **can't** conflict with your config — Omnixient is a pinned dependency,
not a checkout. Roll back by reverting `flake.lock`; pin a release with
`omni.url = "git+https://git.atitlan.io/aiolabs/omnixient?ref=v1.0.0"`.

---

## Secrets (optional)

Secrets are **off by default** — a fresh config builds with zero secret
setup. Enable them only if you turn on something that needs one (e.g. an
MCP server) or add your own. Omnixient ships the sops-nix *module*; you supply
the *data*, with **your own** age key:

```bash
# 1. your master key (back this up!)
nix-shell -p age --run 'age-keygen -o ~/.config/sops/age/keys.txt'  # prints age1…

# 2. declare yourself the recipient (copy Omnixient's .sops.yaml.example)
$EDITOR .sops.yaml          # paste your age1… public key

# 3. create + encrypt your secrets (copy secrets/omni.yaml.example)
nix-shell -p sops --run 'sops secrets/omni.yaml'

# 4. TRACK the encrypted file — flakes only see git-tracked files
git add .sops.yaml secrets/omni.yaml
```

Then enable it in `hosts/myhost/default.nix` and rebuild:

```nix
omni.secrets.enable = true;
```

`modules/secrets.nix` reads `/home/<user>/.config/sops/age/keys.txt`, and
only activates when the flag is set *and* `secrets/omni.yaml` exists — so
it never gets in your way until you ask for it.

---

## Building a custom ISO (optional)

From an Omnixient checkout (or `nix build git+https://git.atitlan.io/aiolabs/omnixient#omni-iso`):

```bash
nix build .#omni-iso        # → result/iso/nixos-*.iso
```

A live Omnixient environment for installing onto new hardware.

---

## Forking instead

If you want to modify Omnixient's own modules/themes rather than just consume
them, fork the repo and edit in place:

```bash
git clone https://git.atitlan.io/aiolabs/omnixient.git ~/omni && cd ~/omni
```

Then model a host on **`hosts/example/`** (copy it to `hosts/<yourhost>/`,
drop in your hardware scan, register it in `flake.nix`), and edit
`settings.nix`. The trade-off is the usual fork one: to get upstream
changes you `git pull` / rebase and resolve conflicts in any files you've
edited. The dependency model above avoids that entirely, which is why it's
recommended for most adopters.

---

## Where to go next

- **[docs/packs.md](packs.md)** — the pack catalog, enabling/disabling, and
  reusing packs on a non-Omnixient NixOS.
- **[docs/ARCHITECTURE.md](ARCHITECTURE.md)** — how the flake, `mkSystem`,
  modules, and theming fit together.
- **[docs/system-map.md](system-map.md)** — a file-by-file map of the repo.