rewrite Nina README around verified workflows (3.4.14)

@@ -1,148 +1,147 @@11 # nina22 3-**the best way to use nixos.**3+Nina is a command-line helper for NixOS. Use it to find packages, apply your configuration, roll back a generation, or check another machine over SSH.44 5-Nina wraps the full NixOS workflow in plain, memorable verbs — packages, rebuilds, generations, flakes, services, remote machines. Written in Zig. Zero dependencies. One binary.6-5+```sh6+nina search ripgrep7+nina apply8+nina back9+nina status --all710 ```8-$ nina search ripgrep9-$ nina apply10-$ nina back11-$ nina status --all12-```1311 14----12+It calls the Nix tools you already use and gives common tasks shorter names. Your configuration stays in Nix files. Nina is written in Zig and builds as a single binary with no third-party Zig dependencies; it needs Nix and the relevant system tools to carry out commands.1513 16-## install14+## Install1715 18-**nix profile** (recommended — instant, per-user, no `sudo`):16+Nina's system commands are for NixOS. Package and development commands use Nix, which needs the `nix-command` and `flakes` experimental features enabled.1917 18+Install in your user profile:19+2020 ```sh2121 nix profile add 'https://kepr.uk/nina/archive/HEAD.tar.gz#nina'2222 ```2323 24-Remove any time with `nina goodbye`.24+Then run:2525 26-**koh** (build from source via koh):26+```sh27+nina setup28+```2729 30+Setup creates Nina's configuration if it is missing and checks the required Nix features. On NixOS, it offers to add the setting to `/etc/nixos/configuration.nix`; you must rebuild for it to take effect. If the install command above fails because these features are disabled, enable them in Nix first.31+32+To build from source, you need Zig 0.16:33+2834 ```sh2935 koh steal kepr.uk/nina3036 cd nina && zig build -Doptimize=ReleaseFast3137 sudo cp zig-out/bin/nina /usr/local/bin/nina3238 ```3339 34-**source archive** (download and build manually):40+You can also download a source archive from [releases](https://kepr.uk/nina/releases):3541 36-Download the source archive from [kepr.uk/nina/releases](https://kepr.uk/nina/releases), then:37-3842 ```sh3943 tar xf nina-*.tar.gz && cd nina-*/4044 zig build -Doptimize=ReleaseFast4145 sudo cp zig-out/bin/nina /usr/local/bin/nina4246 ```4347 44-**linux · nixos 24.05+** — requires `nix-command` and `flakes` experimental features.  45-Run `nina setup` on first use to enable them automatically.48+`nina goodbye` uninstalls Nina. Run `nina update` to check for a newer Nina release. If your system configuration manages Nina, update it through that configuration.4649 47----50+## Apply a configuration4851 49-## the commands you'll actually use52+`nina edit` opens `configuration.nix` in your editor. Check it before applying, or build it without switching:5053 54+```sh55+nina edit56+nina check57+nina apply --dry58+nina apply5159 ```52-nina apply           rebuild and switch to the new configuration53-nina apply --dry     preview what would change without switching54-nina back            roll back to the previous generation55-nina go <n>          jump to any generation by number56-nina history         list all generations57-nina clean           remove old generations and free store space5860 59-nina search <q>      search nixpkgs inline — browse, install, or try60-nina option <q>      search NixOS options inline61-nina install <p>     add a package — profile (instant) or system config62-nina remove <p>      remove a package from profile or system config63-nina try <p>         run a package without installing it64-nina list            show installed packages61+Nina also supports flake-based system configurations. Set the machine's `config` directory to the directory containing your configuration.6562 66-nina home apply      apply home-manager config67-nina home back       roll back one home-manager generation68-nina home history    list home-manager generations69-nina home edit       open home.nix70-nina home check      validate home config without switching71-nina home diff       compare the latest two home generations72-nina home packages   list packages managed by home-manager63+If you need to go back, use `nina back`. To choose a specific generation, find its number with `nina history`, then run `nina go <n>`.7364 74-nina status          machine health at a glance75-nina status --all    health across every configured machine76-nina doctor          diagnose common issues77-nina diff            what changed between generations78-nina log             operation history65+| Command | What it does |66+| --- | --- |67+| `nina history` | Lists system generations |68+| `nina back` | Rolls back one generation |69+| `nina go <n>` | Switches to generation `<n>` |70+| `nina diff` | Compares generations |71+| `nina upgrade` | Updates Nix inputs or channels and rebuilds |72+| `nina clean` | Removes old system generations and collects garbage |7973 80-nina service list    list systemd services and their state81-nina service logs <s> journal logs for a service82-nina service start/stop/restart <s>74+`nina clean` keeps the number of generations set in your config, five by default. Removing generations means you can no longer roll back to them.8375 84-nina flake show      inspect flake outputs85-nina flake update    update lock files86-nina pin <in> <rev>  pin a flake input to a commit87-nina unpin <in>      release a pinned flake input88-nina develop         enter a dev shell89-nina build           build a flake output90-nina run <p>         run a package without installing76+## Find and use packages9177 92-nina edit            open configuration.nix in your editor93-nina edit --dir      open the config directory in your editor94-nina check           validate config without switching95-nina fmt             format nix files96-nina info            nixos version, kernel, uptime97-nina boot            boot entries78+`nina search <q>` searches nixpkgs through `nix search`. In a terminal, results appear in an inline browser. Use the arrow keys to move, Tab for package details, Enter to select a package, and Escape to cancel. When stdin is not a terminal, search prints a plain list.9879 99-nina help            all commands100-nina --version       version info80+```sh81+nina search ripgrep82+nina install ripgrep83+nina try ripgrep84+nina remove ripgrep85+nina list10186 ```10287 103----88+Selecting a package in search or running `nina install` asks how you want to use it:10489 105-## hooks90+- Install it in your user profile without a system rebuild.91+- Add it through your system configuration: Nina opens the editor at the package list and offers to apply your changes.92+- Try it in a temporary shell without installing it.10693 107-Nina runs optional executable hook scripts before and after state-changing commands.108-Create them in `~/.config/nina/hooks/`:94+Search and installation may need network access to fetch Nix inputs or packages. `nina option <q>` searches NixOS options.10995 110-```111-pre-apply     post-apply112-pre-back      post-back113-pre-home      post-home114-pre-upgrade   post-upgrade115-```96+## Home Manager11697 117-Missing hooks are ignored. Hook files must be executable (`chmod +x`) to run.118-If a pre-hook exits non-zero, Nina shows the last five output lines and asks119-whether to continue, defaulting to no. If a post-hook exits non-zero, Nina shows120-a warning after the command's success line.98+Nina supports standalone Home Manager and Home Manager integrated into a NixOS configuration. To create a standalone configuration:12199 122-Example: stop `nina apply` when your config has uncommitted changes.123-124100 ```sh125-#!/usr/bin/env sh126-# ~/.config/nina/hooks/pre-apply127-if git -C ~/nixos-config status --porcelain | grep -q .; then128-    echo "uncommitted changes - commit before applying"129-    exit 1130-fi101+nina home init131102 ```132103 133----104+Add `--switch` to activate it immediately. Nina chooses a Home Manager branch from your NixOS version and leaves an existing configuration in place.134105 135-## multi-machine106+| Command | What it does |107+| --- | --- |108+| `nina home apply` | Applies your home configuration |109+| `nina home back` | Rolls back one home generation |110+| `nina home history` | Lists home generations |111+| `nina home edit` | Opens `home.nix` |112+| `nina home check` | Builds the home configuration without switching |113+| `nina home diff` | Compares the latest two home generations |114+| `nina home packages` | Lists packages in the home generation |136115 137-Any command runs on a remote machine with `--on <name>`. Configure machines in `~/.config/nina/config`:116+When Home Manager is part of your NixOS configuration, `nina home apply` runs a system rebuild. Home commands operate on the local user; they do not support `--on`.138117 118+## Configure Nina119+120+Nina reads `~/.config/nina/config`, or `$XDG_CONFIG_HOME/nina/config` when that environment variable is set.121+139122 ```ini123+editor      = hx124+generations = 5125+confirm     = true126+teach       = false127+color       = true128+140129 [machine]141-name    = kyoshi130+name    = my-machine142131 config  = /etc/nixos143132 local   = true144133 default = true134+```145135 136+Set `editor` to your preferred editor. `generations` controls how many system generations cleanup keeps. With `teach = true`, Nina prints the underlying commands as you work.137+138+Nina disables color when stdout is not a terminal and respects `NO_COLOR`.139+140+## Work on another machine141+142+Add a machine with an SSH host to your config:143+144+```ini146145 [machine]147146 name    = azula148147 host    = azula@@ -150,95 +149,76 @@150149 ssh_key = ~/.ssh/id_ed25519151150 ```152151 153-```152+Put `--on <name>` after the command to select it:153+154+```sh154155 nina apply --on azula155156 nina service logs ollama -f --on azula156157 nina status --all157158 ```158159 159-```160-:: status160+Remote system operations use SSH and the tools on the target machine. `nina status --all` checks every configured machine. Use `nina hello` to list them.161161 162-   kyoshi   gen 348   3m ago    42 GB163-   azula    gen 192   14m ago   18 GB164-```162+## Run hooks165163 166----164+Place executable scripts in `~/.config/nina/hooks/` to run before or after these operations:167165 168-## search that stays at the prompt169-170-`nina search` opens an inline widget — no fullscreen takeover. Browse results, see versions and licenses, then press enter to install the highlighted package (choosing profile, system, or try afterward).171-166+```text167+pre-apply     post-apply168+pre-back      post-back169+pre-home      post-home170+pre-upgrade   post-upgrade172171 ```173-:: search nixpkgs  ripgrep                          12 results174172 175-   > ripgrep        14.1.1   free    fast line-oriented search176-     ripgrep-all    0.9.6    free    search across file formats177-     ugrep          6.0.0    free    grep compatible ripgrep alt173+Missing or non-executable hooks are skipped. If a pre-hook fails, Nina shows its last five output lines and asks whether to continue, defaulting to no. A failed post-hook produces a warning after the operation succeeds. Hooks run locally, including when the operation targets a remote machine.178174 179-   ripgrep  14.1.1  free180-   recursively search directories for a regex pattern181-   attr   pkgs.ripgrep175+For example, save this as `~/.config/nina/hooks/pre-apply` to check for uncommitted changes, then make it executable with `chmod +x`:182176 183-   enter install  tab info  [up/down] nav  esc cancel177+```sh178+#!/usr/bin/env sh179+# ~/.config/nina/hooks/pre-apply180+if git -C ~/nixos-config status --porcelain | grep -q .; then181+    echo "uncommitted changes - commit before applying"182+    exit 1183+fi184184 ```185185 186----186+## More commands187187 188-## install that actually works188+| Command | What it does |189+| --- | --- |190+| `nina status` | Shows machine health |191+| `nina doctor` | Checks for common problems |192+| `nina log` | Shows Nina's operation history |193+| `nina service list` | Lists systemd services |194+| `nina service logs <s>` | Reads a service's journal |195+| `nina service start/stop/restart <s>` | Controls a service |196+| `nina flake show` | Shows flake outputs |197+| `nina flake update` | Updates flake inputs |198+| `nina pin <in> <rev>` | Pins a flake input to a revision |199+| `nina unpin <in>` | Updates a pinned input |200+| `nina develop` | Enters a development shell |201+| `nina build` | Builds a flake output |202+| `nina run <p>` | Runs a package |203+| `nina edit --dir` | Opens the configuration directory |204+| `nina fmt` | Formats the system configuration |205+| `nina info` | Shows system information |206+| `nina boot` | Lists boot entries |189207 190-`nina install` uses `nix search nixpkgs` directly — no external API, no network dependency after your first channel update, no silent failures. Works offline.208+Run `nina help` for the full command list, `nina <group> help` for a group such as `home` or `service`, and `nina man [topic]` for the built-in manual. `nina --version` prints the installed version.191209 192-Two install paths, your choice:210+## Build and test193211 194-- **profile** — instant. package available immediately. no rebuild.195-- **system** — opens your editor at the right line in `configuration.nix`, then offers to apply.212+From the source directory:196213 197----198-199-## config200-201-`~/.config/nina/config` — plain text, no surprises:202-203-```ini204-editor      = hx205-generations = 5206-confirm     = true207-teach       = false208-color       = true209-210-[machine]211-name    = my-machine212-config  = /etc/nixos213-local   = true214-default = true214+```sh215+zig build216+zig build test217+zig fmt --check build.zig src/*.zig215218 ```216219 217-`teach = true` prints the underlying nix command after each operation so you learn while you work.220+System operations need a NixOS host for live testing. The [VM test harness](test/vm/README.md) describes testing against disposable NixOS images.218221 219----222+Made by [Asha Software](https://asha.software).220223 221-## what nina outputs222-223-```224-:: rebuilding kyoshi...225-226-   -> [build output]227-228-:: generation 14  [42.3s]229-```230-231-```232-:: error: 'firefocks' not found in nixpkgs233-   -> try: nina search firefox234-```235-236-Pink `::` marks Nina's voice. Green for success. Red for errors. Yellow for warnings. Color auto-disables when stdout is not a TTY. Respects `NO_COLOR`.237-238----239-240-## built by241-242-[asha software](https://asha.software) — hope in every line of code.243-244-**[nina.asha.software](https://nina.asha.software)** · [source](https://kepr.uk/nina) · [docs](https://nina.asha.software/docs)224+[Website](https://nina.asha.software) · [Source](https://kepr.uk/nina) · [Documentation](https://nina.asha.software/docs)