diff --git a/.warp.md b/.warp.md index 778dbae..c9682bb 100644 --- a/.warp.md +++ b/.warp.md @@ -2,10 +2,10 @@ This file provides guidance to WARP (warp.dev) when working with code in this repository. -This is a minimal entrypoint for agents. - -For the full, up-to-date commands, architecture, and workflows, see: -- cheatsheets/project-guide.md - -Note: Keep cheatsheets/project-guide.md current. Make updates to this index by editing that guide. +Agent entrypoint +- Start with WARP.md (primary project rules and workflows for agents). +- For extended quick refs and workflows, see cheatsheets/project-guide.md. +Maintenance note +- Keep both WARP.md and cheatsheets/project-guide.md current. +- Prefer updating WARP.md for canonical rules; use the project guide for quick commands. diff --git a/WARP.md b/WARP.md new file mode 100644 index 0000000..3968a80 --- /dev/null +++ b/WARP.md @@ -0,0 +1,77 @@ +# WARP.md + +This file provides guidance to WARP (warp.dev) when working with code in this repository. + +Project: ZaneyOS — NixOS flake for desktop systems with per-host overrides, GPU/VM profiles, and an integrated Home Manager layer. + +Important repo expectations +- This repo is expected at: ~/zaneyos (programs.nh.flake points here). If you keep it elsewhere, update modules/core/nh.nix accordingly. +- Target OS: NixOS 23.11+; UEFI + GPT expected; systemd-boot is supported out of the box (see README for details). + +Common commands +- Rebuild and switch (preferred via nh/zcli) + - fr # zsh alias → nh os switch --hostname + - fu # zsh alias → nh os switch --hostname --update + - zcli rebuild [--dry|--ask|--cores N|--verbose|--no-nom] + - zcli update [--dry|--ask|--cores N|--verbose|--no-nom] +- Rebuild for next boot (safer for bigger changes) + - zcli rebuild-boot [same options] + - sudo nixos-rebuild boot --flake .# +- Direct NixOS (without nh/zcli) + - sudo nixos-rebuild switch --flake .# +- Validate the flake + - nix flake check +- Format Nix files (nixfmt-rfc-style is included) + - find . -name "*.nix" -print0 | xargs -0 nixfmt +- Host management (zcli) + - zcli update-host [hostname] [profile] # auto-detect if args omitted + - zcli add-host [profile] # copies hosts/default, can gen hardware.nix + - zcli del-host +- Diagnostics and maintenance + - zcli diag # writes ~/diag.txt + - zcli cleanup # prunes generations (interactive) + - zcli trim # runs fstrim with confirmation +- 2.3 → 2.4 upgrade (existing installs) + - ./upgrade-2.3-to-2.4.sh # automated analysis, backup, and upgrade + - ./upgrade-2.3-to-2.4.sh --revert + +Notes on profiles and hosts +- Profiles represent hardware targets: amd, intel, nvidia, nvidia-laptop (hybrid), vm. +- Use the profile in flake targets like .#vm or .#nvidia, or via nh’s --hostname. +- Host-specific settings live under hosts//; variables.nix holds UX and feature toggles. + +High-level architecture (big picture) +- flake.nix + - Inputs: nixpkgs 25.05, home-manager 25.05, stylix, nvf, nix-flatpak. + - Defines system, host, profile, username; constructs nixosConfigurations via mkNixosConfig. + - Each configuration imports profiles/. +- profiles//default.nix + - Imports host and stacks: ../../hosts/${host}, ../../modules/drivers, ../../modules/core. + - Toggles drivers and VM guest services per profile; the nvidia-laptop profile consumes Bus IDs from host variables. +- hosts// + - default.nix imports hardware.nix and host-packages.nix. + - variables.nix is the primary control surface (display manager, terminal/browser defaults, waybarChoice, stylix image, 24h clock, Thunar/printing/NFS flags, intel/nvidia Bus IDs, etc.). +- modules/core + - Composes NixOS modules: boot, flatpak, fonts, hardware, network, nfs, nh, packages, printing, display manager (greetd/sddm), security, services (PipeWire/SSH/Bluetooth/fstrim; smartd conditional), steam, stylix, syncthing, system (nix settings, locales, env), thunar, user (Home Manager), virtualization, xserver. + - nh.nix enables nh and pins programs.nh.flake to ~/zaneyos. + - user.nix integrates Home Manager and creates users.${username}, passing { inputs, username, host, profile } to the home layer. +- modules/drivers + - AMD, Intel, NVIDIA, NVIDIA Prime, and VM guest services; nvidia-prime options (enable, intelBusID, nvidiaBusID) are consumed by the nvidia-laptop profile. +- modules/home + - Composes the user environment: Hyprland, Waybar (via waybarChoice), Rofi, Yazi, terminals (Kitty/WezTerm/Ghostty/Alacritty toggles), Zsh/Bash config, Git, NVF/Neovim, OBS, swaync, scripts, Stylix, optional Doom Emacs/VSCodium/Helix. + - scripts/default.nix installs zcli; zcli wraps rebuild/update/boot, cleanup, diagnostics, host management, and Doom lifecycle. +- Shell aliases (zsh) + - fr and fu are defined in modules/home/zsh/default.nix, parameterized by the active profile. + +Key development choices +- Repo location matters: nh and zcli assume ~/zaneyos; move it and adjust modules/core/nh.nix. +- Validation is via nix flake check; there is no separate unit test suite. +- Formatting is via nixfmt-rfc-style (provided in system packages). + +Useful docs in-repo +- README.md: requirements, install and upgrade overview (including the 2.3→2.4 process). +- zcli.md: full CLI docs, commands, options, and examples. +- cheatsheets/project-guide.md: quick commands, architecture summary, and common workflows. +- cheatsheets/: Hyprland and terminal/editor quick references. + +