[refactor] update README docs

README.md

@@ -1,19 +1,23 @@
 # Custom environment
 
-My personal development environment and dotfiles. The repository contains the
+My personal NixOS configuration and dotfiles for user `hhhh` on host `nixos`
-configuration I use to keep the terminal, editor, shell history, and Git
+(`x86_64-linux`). The desktop uses Hyprland, Kitty, Neovim, and Bash, with
-workflow consistent across machines.
+Home Manager linking application settings directly to this repository.
 
 ## Toolset
 
 | Tool | Purpose |
 | --- | --- |
+| [Hyprland](https://hypr.land/) | Wayland desktop compositor |
+| Waybar / Wofi / Mako | Status bar, application launcher, and notifications |
+| SDDM / Hyprlock | Login screen and session locking |
 | [Kitty](https://sw.kovidgoyal.net/kitty/) | Terminal emulator |
 | [Neovim](https://neovim.io/) | Editor and development environment |
 | [Starship](https://starship.rs/) | Fast, minimal shell prompt |
 | [direnv](https://direnv.net/) | Per-project environment variables |
 | [zoxide](https://github.com/ajeetdsouza/zoxide) | Smarter directory navigation |
 | [Atuin](https://atuin.sh/) | Searchable shell history |
+| ble.sh | Interactive Bash editing and completion |
 | [fzf](https://github.com/junegunn/fzf) | Fuzzy finding from the command line |
 | [eza](https://github.com/eza-community/eza) | Modern replacement for `ls` |
 | [GitUI](https://github.com/gitui-org/gitui) | Terminal UI for Git |
@@ -26,13 +30,17 @@ sanitizer-assisted test runs, `perf`, FlameGraph, and systemd user scopes.
 ```text
 .
 ├── flake.nix             # Reproducible NixOS entry point
+├── flake.lock            # Pinned dependency revisions
 ├── nixos/                # Host and reusable NixOS modules
 ├── bash/                 # Bash environment, aliases, and helper functions
 ├── atuin/                # Atuin configuration
+├── git/                  # Git settings and aliases
 ├── gitui/                # GitUI key bindings
 ├── kitty/                # Kitty settings and color themes
+├── hypr/                 # Hyprland Lua config, monitors, wallpapers, and locking
+├── sddm/                 # Custom Qt 6 login theme
 ├── mako/                 # Notification settings
-├── nvim/                 # Neovim configuration and plugin lockfile
+├── nvim/                 # Neovim Lua configuration, plugins, LSP, and themes
 ├── waybar/               # Compact Hyprland status bar and power menu
 ├── wofi/                 # Application launcher with icons
 └── wallpapers/           # Desktop wallpapers
@@ -46,15 +54,21 @@ configuration directories tracked in this repository.
 The flake exposes the `nixos` host. Its machine-specific configuration lives
 in `nixos/hosts/nixos`, while reusable settings are grouped by purpose in
 `nixos/modules`. Packages are split into desktop, development, shell, and
-general utility modules under `nixos/modules/packages`.
+general utility modules under `nixos/modules/packages`. The main Nixpkgs input
+uses `nixos-26.05`; Home Manager uses `release-26.05` and follows that input.
+The configuration enables NVIDIA graphics, PipeWire audio, NetworkManager,
+OpenSSH, Podman, and Throne with TUN support.
 
 From the repository root, check and apply the configuration with:
 
 ```bash
-nix flake check
+nix flake check --no-build
 sudo nixos-rebuild switch --flake .#nixos
 ```
 
+Use `nix flake check` for a full check including builds; `--no-build` checks
+configuration evaluation without building the checks.
+
 On the first run, if flakes are not enabled in the currently booted system,
 pass the feature flags explicitly:
 
@@ -64,7 +78,7 @@ sudo nixos-rebuild switch \
   --flake .#nixos
 ```
 
-Update the pinned Nixpkgs revision and rebuild with:
+Update all pinned flake inputs and rebuild with:
 
 ```bash
 nix flake update
@@ -85,9 +99,42 @@ logs in and listens on the local Unix socket. Connect with
 `systemctl --user status codex-background-server` and view its logs with
 `journalctl --user -u codex-background-server`.
 
-Before using this configuration on another machine, regenerate or replace
+Before applying this configuration on another machine, replace
-`nixos/hosts/nixos/hardware-configuration.nix` and adjust the host name,
+`nixos/hosts/nixos/hardware-configuration.nix` with that machine's configuration
-user, graphics driver, and `system.stateVersion` as appropriate.
+and review the host name, user, graphics driver, and monitor settings.
+`nixos/hosts/nixos/default.nix` also copies Windows EFI files from a specific
+partition to `/boot/EFI/` during bootloader installation; adapt or remove that
+hook if the target machine does not use this dual-boot layout.
+
+Keep `system.stateVersion` and `home.stateVersion` at their initial setup
+versions when updating packages. Ordinary package additions do not require
+updating `flake.lock`.
+
+## Hyprland desktop
+
+The active configuration is `hypr/hyprland.lua`, which loads `monitors.lua`.
+The neighboring `monitors.conf` and `workspaces.conf` are not loaded by it.
+Workspaces 1–10 belong to `DP-3`; `HDMI-A-2` has a dedicated named workspace.
+Monitor modes and positions live in `monitors.lua`, and wallpaper assignments
+live in `hypr/hyprpaper.conf`.
+
+Hyprland starts Hyprpaper, Waybar, and the Home Manager `udiskie` service.
+Udiskie automatically mounts removable media without a tray icon.
+
+| Shortcut | Action |
+| --- | --- |
+| `Super+T` | Open Kitty |
+| `Super+R` | Open Wofi |
+| `Super+C` | Close the active window |
+| `Super+L` | Lock the session |
+| `Super+Shift+S` | Copy a region screenshot to the clipboard |
+| `Super+1` … `Super+0` | Select workspace 1–10 |
+| `Super+Shift+1` … `Super+Shift+0` | Move a window to workspace 1–10 |
+| `Alt+H` / `Alt+L` | Cycle primary-monitor workspaces |
+| `Ctrl+Space` | Switch English/Russian keyboard layouts |
+
+Waybar settings are in `waybar/config.jsonc` and `waybar/style.css`;
+`waybar/power-menu.sh` provides lock, suspend, reboot, and power-off actions.
 
 ## Screen locking
 
@@ -100,8 +147,10 @@ login. Avoid restarting the display manager during an active session.
 
 Hyprlock uses `hypr/hyprlock.conf` and the existing wallpaper assets for a
 blurred, two-column lock screen with ProFont, a clock, and live system status.
-Press `Super+L` or choose **Lock** in the Waybar power menu. Hypridle handles
+Press `Super+L` or choose **Lock** in the Waybar power menu.
-session lock requests and locks before suspend; no idle timeout is configured.
+`hypr/hypridle.conf` defines session locking and a lock request before suspend,
+with no idle timeout. Hypridle is not currently installed or started by the
+tracked configuration; these hooks require installing and running it.
 The NixOS Hyprlock module supplies its PAM authentication configuration.
 
 ## Home Manager
@@ -131,39 +180,60 @@ used when first enabling Home Manager.
 ## Installation
 
 On NixOS, clone the repository into the location expected by Home Manager,
-then apply the flake:
+review the machine-specific settings described above, then check and apply
+the flake:
 
 ```bash
 git clone git@github.com:Claucdan/Custom-environment.git ~/Git/Custom-environment
 cd ~/Git/Custom-environment
+nix flake check --no-build
 sudo nixos-rebuild switch --flake .#nixos
 ```
 
 On other distributions, install the tools using your system package manager
-and link the configuration directories manually:
+and link the configuration directories manually. Inspect existing settings
+and move conflicting files or directories aside before creating links:
 
 ```bash
-git clone git@github.com:Claucdan/Custom-environment.git
+git clone git@github.com:Claucdan/Custom-environment.git ~/Git/Custom-environment
-cd Custom-environment
+cd ~/Git/Custom-environment
+mkdir -p "$HOME/.config"
 
-ln -sfn "$PWD/nvim" "$HOME/.config/nvim"
+for config in atuin gitui hypr kitty mako nvim waybar wofi; do
-ln -sfn "$PWD/kitty" "$HOME/.config/kitty"
+    ln -s "$PWD/$config" "$HOME/.config/$config"
-ln -sfn "$PWD/mako" "$HOME/.config/mako"
+done
-ln -sfn "$PWD/atuin" "$HOME/.config/atuin"
-ln -sfn "$PWD/gitui" "$HOME/.config/gitui"
-ln -sfn "$PWD/waybar" "$HOME/.config/waybar"
-ln -sfn "$PWD/wofi" "$HOME/.config/wofi"
 ```
 
-Review `.bashrc` before sourcing or linking it: some aliases, paths, and helper
+## Bash and Git
-functions are tailored to my local development setup.
+
+Home Manager does not manage `bash/` or `git/`. Review their settings and back
+up any existing `~/.bashrc` and `~/.gitconfig` before linking them separately:
+
+```bash
+cd ~/Git/Custom-environment
+ln -s "$PWD/bash/.bashrc" "$HOME/.bashrc"
+ln -s "$PWD/git/.gitconfig" "$HOME/.gitconfig"
+```
+
+Link the Bash entry point rather than copying it: it resolves the `~/.bashrc`
+symlink to locate `env.bash`, `aliases.bash`, `build.bash`, `perf.bash`,
+`systemd.bash`, and `tools.bash`. Machine-specific additions belong in
+`bash/local.*.bash`, which is ignored by Git. Start a new interactive Bash
+session after changing the links.
+
+The Git configuration includes `~/Git/Custom-environment/git/aliases.gitconfig`,
+uses Neovim as its editor, and enables pull rebase with automatic stashing.
+Adjust the include path if you keep the repository elsewhere.
 
 ## Notes
 
-- A [Nerd Font](https://www.nerdfonts.com/) is recommended for Kitty,
+- NixOS installs ProFont Nerd Font, Font Awesome, and Noto fonts. Kitty uses
-  Starship, and terminal icons.
+  `ProFontWindows Nerd Font Mono`; install it separately on other distributions.
 - Neovim plugins are managed with
   [lazy.nvim](https://github.com/folke/lazy.nvim); open Neovim after linking the
-  configuration to install them.
+  configuration to install them. The entry point is `nvim/init.lua`, plugin
+  specifications are in `nvim/lua/plugins/`, and settings are in
+  `nvim/lua/configs/`. `nvim/lazy-lock.json` is currently ignored by Git, so
+  plugin versions are not pinned by this repository.
 - This is a personal setup rather than a universal bootstrap script. Feel free
   to copy or adapt any part of it.