docs: refresh stale docs after the VM and backup refactors

BACKUP.md

@@ -32,12 +32,12 @@ How this fleet is backed up, where the data lives, and how to restore it.
 
 Two independent repository passwords, deliberately not shared:
 
-| Group       | Secret                        | Recipients    | Decrypts             |
+| Group       | Secret                        | Recipients              | Decrypts             |
-| ----------- | ----------------------------- | ------------- | -------------------- |
+| ----------- | ----------------------------- | ----------------------- | -------------------- |
-| desktop     | `restic-password-desktop.age` | desktops      | desktop repositories |
+| desktop     | `restic-password-desktop.age` | desktops                | desktop repositories |
-| homelab     | `restic-password-homelab.age` | homelab hosts | homelab repositories |
+| homelab     | `restic-password-homelab.age` | homelab hosts           | homelab repositories |
-| REST access | `restic-rest-credentials.age` | desktops      | nothing (auth only)  |
+| REST access | `restic-rest-credentials.age` | desktops                | nothing (auth only)  |
-| REST access | `restic-rest-htpasswd.age`    | all hosts     | nothing (auth only)  |
+| REST access | `restic-rest-htpasswd.age`    | the REST server (youko) | nothing (auth only)  |
 
 Consequences worth remembering:
 
@@ -62,7 +62,6 @@ collisions.
 | 01:30 + 15m      | desktops push to youko              |
 | 02:30 + 15m      | youko backs itself up               |
 | 03:45:20 Tue/Sat | btrbk local snapshots               |
-| other slots      | other homelab hosts, before 03:30   |
 | 06:00 (planned)  | youko copies homelab repos to cloud |
 
 Set per host via `modules.restic-backup.onCalendar` and `randomizedDelaySec`.
@@ -156,4 +155,4 @@ Restoring a btrbk snapshot (offline; stop writers first):
 | `hosts/12kingdoms-youko/default.nix`                                             | the REST server and youko's own backup               |
 | `hosts/12kingdoms-youko/homelab-services/caddy.nix`                              | the `restic.writefor.fun` vhost                      |
 | `secrets/nixos.nix`                                                              | which secret is defined on which host                |
-| `hosts/<host>/restic.nix`                                                        | per-host backup configuration                        |
+| `hosts/idols-ai/restic.nix`, `hosts/12kingdoms-youko/default.nix`                | per-host backup configuration                        |

hardening/README.md

@@ -24,6 +24,7 @@
 - **Nixpak** (`nixpaks/`): Bubblewrap-based sandboxing for applications
   - Firefox configuration
   - QQ (Chinese messaging app) configuration
+  - Telegram Desktop configuration
   - Modular system with reusable components
 - **Firejail** (legacy): SUID-based sandboxing (not used)
 - **Bubblewrap** (`bwraps/`): Direct bubblewrap configurations
@@ -36,6 +37,7 @@
 | AppArmor Profiles | 🚧 WIP    | Basic structure in place       |
 | Nixpak Firefox    | ✅ Active | Firefox sandboxing via nixpak  |
 | Nixpak QQ         | ✅ Active | QQ application sandboxing      |
+| Nixpak Telegram   | ✅ Active | Telegram Desktop sandboxing    |
 | Bubblewrap WeChat | ✅ Active | WeChat specific sandboxing     |
 | System Profiles   | 🚧 WIP    | Hardened system configurations |
 
@@ -53,7 +55,9 @@ hardening/
 │   ├── default.nix
 │   ├── firefox.nix
 │   ├── qq.nix
+│   ├── telegram-desktop.nix
 │   └── modules/       # Reusable nixpak modules
+│       ├── custom-policy.nix
 │       ├── gui-base.nix
 │       └── network.nix
 └── profiles/          # System hardening profiles

home/README.md

@@ -9,7 +9,7 @@ home/
 ├── base/              # Cross-platform home manager configurations
 │   ├── core/          # Essential applications and settings
 │   │   ├── editors/   # Editor configurations (Neovim, Helix)
-│   │   ├── shells/    # Shell configurations (Nushell, Zellij)
+│   │   ├── shells/    # Shell configurations (bash, Nushell)
 │   │   └── ...
 │   ├── gui/           # GUI applications and desktop settings
 │   │   ├── terminal/  # Terminal emulators (Kitty, Alacritty, etc.)
@@ -25,10 +25,9 @@ home/
 │   │   ├── i3/        # i3 — headless computer-use session (see i3/README.md)
 │   │   ├── niri/      # Niri window manager
 │   │   └── ...
-│   ├── editors/       # Linux-specific editors
 │   └── ...
 ├── hosts/             # Host-specific home manager entry modules
-│   ├── linux/         # Linux host home modules (ai, shoukei, k3s-*, etc.)
+│   ├── linux/         # Linux host home modules (ai, shoukei, kana, ruby, k3s-*, etc.)
 │   └── darwin/        # macOS host home modules (fern, frieren)
 └── darwin/            # macOS-specific home manager configurations
     ├── proxy/         # Proxy configurations

home/base/README.md

@@ -9,14 +9,16 @@ systems.
 
 - **core/**: Essential cross-platform configurations
   - **core.nix**: Minimal home-manager configuration
-  - **shells/**: Shell configurations (bash, zsh, fish, nu)
+  - **shells/**: Shell configurations (bash, Nushell; zsh is Darwin-only under `home/darwin/`)
   - **editors/**: Helix + Neovim (Home Manager) and usage docs (`README.md` per editor)
   - **btop.nix**: System monitoring tools
   - **git.nix**: Git configuration and aliases
   - **npm.nix**: Node.js package management
   - **pip.nix**: Python package management
+  - **privacy.nix**: Cross-app telemetry opt-out (`DO_NOT_TRACK`)
   - **starship.nix**: Cross-shell prompt configuration
   - **theme.nix**: Color schemes and theming
+  - **xdg.nix**: XDG base-directory configuration
   - **yazi.nix**: Terminal file manager configuration
   - **zellij/**: Terminal multiplexer with custom layouts
 
@@ -25,24 +27,27 @@ systems.
 - **gui/**: Cross-platform GUI applications and configurations
   - **dev-tools.nix**: Development tools and IDEs
   - **media.nix**: Media players and utilities
+  - **zed-editor.nix**: Zed editor configuration (primary GUI editor)
   - **terminal/**: Terminal emulator configurations
     - **alacritty/**: Alacritty terminal
-    - **kitty/**: Kitty terminal
+    - **kitty.nix**: Kitty terminal
-    - **foot/**: Foot terminal (Linux)
+    - **foot.nix**: Foot terminal (Linux)
-    - **ghostty/**: Ghostty terminal
+    - **ghostty.nix**: Ghostty terminal
 
 ### Terminal Interface
 
 - **tui/**: Terminal-based interface configurations
+  - **agent-env.nix**: Telemetry/auto-update opt-outs for AI coding agents
   - **cloud/**: Cloud development tools (Terraform, etc.)
   - **container.nix**: Container tools (Docker, Podman)
   - **dev-tools.nix**: Terminal-based development tools
   - **editors/**: Extra terminal editor Nix (see `core/editors/` for docs and baseline enables)
   - **encryption/**: Encryption and security tools
   - **gpg/**: GPG key management
+  - **herdr.nix**: Herdr agent terminal-multiplexer configuration
   - **password-store/**: Password management with pass
-  - **shell.nix**: Shell environment configurations
+  - **shell/**: Shell environment configurations
-  - **ssh/**: SSH configuration and management
+  - **ssh.nix**: SSH configuration and management
   - **zellij/**: Terminal workspace management
 
 ### System Management

home/base/core/editors/helix/README.md

@@ -49,9 +49,10 @@ Zellij shortcuts used often (same idea as in the Neovim notes):
 
 In Helix, `|` / `!` and variants pipe or insert shell output on selections (see **Changes**).
 
-This flake’s Helix Home Manager module keeps **almost all default keys**; the only remap is
+This flake’s Helix Home Manager module keeps **almost all default keys** but adds several
-**`Ctrl+Shift+o`** → jump backward, because Zellij uses **`Ctrl+o`** for Session (see
+normal-mode remaps: **`Ctrl+Shift+o`** → jump backward (because Zellij uses **`Ctrl+o`** for
-`home/base/core/editors/helix/default.nix`).
+Session), `Space Space` → `:reload-all`, `Space w` / `Space q` → `:w` / `:q`, `Esc` → collapse
+selection, and `$` / `0` line jumps (see `home/base/core/editors/helix/default.nix`).
 
 ### Command mode (`:`)
 

home/base/gui/terminal/README.md

@@ -18,6 +18,8 @@ My current terminal emulators are:
    1. It's really suitable for tiling window manager or zellij users!
 3. alacritty: A cross-platform, GPU-accelerated terminal emulator.
    1. alacritty is really fast, I use it as a backup terminal emulator on all my desktops.
+4. ghostty: A cross-platform, GPU-accelerated terminal emulator with native platform UI.
+   1. ghostty is the newest addition, configured in `ghostty.nix`.
 
 ## 'xterm-kitty': unknown terminal type when `ssh` into a remote host or `sudo xxx`
 

home/base/tui/gpg/README.md

@@ -8,7 +8,7 @@ features a versatile key management system as well as access modules for all kin
 directories.
 
 > In the following content, we will use GPG to refer to GnuPG tool, and PGP to refer to various
-> concepts defined in the OepnPGP standard(e.g. PGP key, PGP key server).
+> concepts defined in the OpenPGP standard(e.g. PGP key, PGP key server).
 
 Key functions of GnuPG:
 
@@ -602,7 +602,7 @@ But in OpenPGP:
   the keypair. But OpenPGP standard **DO NOT provide a way to distribute this certificate to
   others**.
   - Not to mention some key status query protocol like OCSP in Web PKI.
-  - Users has to pulish their revocation certificate to their blog, github profile or somewhere
+  - Users has to publish their revocation certificate to their blog, github profile or somewhere
     else, and others has to check it and run `gpg --import <revocation-certificate>` to revoke the
     keypair manually.
 

home/darwin/README.md

@@ -8,6 +8,7 @@ This directory contains macOS-specific Home Manager configurations for Darwin sy
 
 - **default.nix**: Entry point that imports all Darwin configurations
 - **shell.nix**: Shell configurations and environment settings
+- **terminal.nix**: Sets a 15px font size across Alacritty, Ghostty, and Kitty
 - **rime-squirrel.nix**: [Rime Squirrel](https://github.com/rime/squirrel) input method
   configuration
 

home/linux/README.md

@@ -16,8 +16,8 @@ cases.
 
 - **gui/**: Desktop environment configurations
   - **niri/**: Niri compositor configuration
+  - **i3/**: Headless X11 computer-use session (Xvfb + i3)
   - **base/**: Common desktop applications and services
-  - **editors/**: Text editor configurations for desktop environments
 
 ### Available Entry Points
 

home/linux/gui/README.md

@@ -9,6 +9,8 @@ Manager.
 
 - **niri**: Niri compositor configuration with custom settings, keybindings, spawn-at-startup rules,
   and window rules
+- **i3**: Headless X11 session for the computer-use VMs (`idols-ruby`, `idols-kana`); see
+  [`i3/README.md`](./i3/README.md)
 
 ### Base Desktop Environment
 
@@ -25,19 +27,15 @@ Manager.
   - Wayland applications
   - XDG desktop configurations
 
-### Editor Configurations
-
-- **editors**: Text editor configurations and integrations
-
 ## Why install Desktop Environments in Home Manager instead of NixOS Module?
 
 1. **Configuration Location**: Desktop environment configuration files are located in `~/.config`,
    which can be easily managed by Home Manager.
 
-2. **User-specific Services**: User-specific systemd services (noctalia, fcitx5, hypridle, etc.) can
+2. **User-specific Services**: User-specific systemd services (fcitx5, hypridle, etc.) can be easily
-   be easily managed by Home Manager. If desktop environments were configured via NixOS Module,
+   managed by Home Manager. If desktop environments were configured via NixOS Module, these
-   these user-level services might fail to start automatically. With Home Manager modules, we can
+   user-level services might fail to start automatically. With Home Manager modules, we can control
-   control systemd service dependency order more effectively.
+   systemd service dependency order more effectively.
 
 3. **System Benefits**: By minimizing package installation through NixOS Module:
    - Makes the NixOS system more secure and stable

home/linux/gui/base/fcitx5/README.md

@@ -3,6 +3,6 @@
 ## Available Configurations
 
 - `profile` → Symlink will be created at: `~/.config/fcitx5/profile`
-- `config1.db` (Mozc config) → Symlink will be created at: `~/.config/mozc/config1.db`
+- `mozc-config1.db` (Mozc config) → Symlink will be created at: `~/.config/mozc/config1.db`
   - Main changes from the defaults: use half-width for all alphabets, numbers, and punctuation.
   - https://github.com/google/mozc/blob/2.30.5544.102/docs/configurations.md

home/linux/gui/i3/README.md

@@ -20,8 +20,9 @@ is XWayland/X11-based, so a native X11 session is simpler and better supported t
   services: `xvfb` → `i3` → (`x11vnc`, `cua-driver serve`).
 - `modules/nixos/desktop/computer-use.nix` provides the system side (`linger`, AT-SPI, fonts, Mesa,
   Clash Verge proxy, proxy-region timezone).
-- `computer-use-init.sh` (exec'd by i3) publishes `DISPLAY`/`XDG_SESSION_TYPE` to the systemd user
+- the generated `computer-use-init` script (exec'd by i3) publishes `DISPLAY`/`XDG_SESSION_TYPE` to
-  manager, clears any stale `WAYLAND_DISPLAY`, and enables the AT-SPI bridge via a gsettings key.
+  the systemd user manager, clears any stale `WAYLAND_DISPLAY`, and enables the AT-SPI bridge via a
+  gsettings key.
 - Drivers live in `overlays/cua-driver.nix` and `overlays/computer-use-linux.nix`.
 - Host wiring: `home/hosts/linux/idols-ruby.nix`, `home/hosts/linux/idols-kana.nix`.
 
@@ -32,7 +33,7 @@ The generated config is intentionally minimal:
 - `font pango:monospace 10`
 - `default_border normal` — keeps title bars, so the client area is slightly smaller than the
   screen. That matches a real desktop and avoids a full-screen-sized viewport.
-- `exec --no-startup-id .../computer-use-init.sh` — one-time session setup, see above.
+- `exec --no-startup-id .../computer-use-init` — one-time session setup, see above.
 
 There are no keybindings, bars or autostarted apps: agents drive the session through the drivers,
 not the keyboard. Manual inspection is done over VNC (`x11vnc`, bound to `127.0.0.1`; reach it

hosts/12kingdoms-youko/homelab-services/README.md

@@ -1,23 +1,25 @@
-# Idols - Aquamarine
+# Youko - Homelab Services
 
-Storage, operation and maintenance related services are running on this host:
+Storage, operation and maintenance related services are running on this host (migrated here from the
+retired `idols-aquamarine` guest):
 
-1. Storage such as git server, file server/browser, torrent downloader,, etc.
+1. Storage such as a git server, file server, torrent downloader, etc.
-1. Backup or sync my personal data to cloud or NAS.
+1. Back up my personal data with restic; the data is encrypted on the client.
-   - For safety, those data should be encrypted before sending to the cloud or my NAS.
+1. Collect and monitor the metrics of my homelab.
-1. Collect and monitor the metrics/logs of my homelab.
 
 ## Features
 
 Services:
 
-1. prometheus + alertmanager + grafana + loki: Monitor the metrics/logs of my homelab.
+1. caddy: Reverse proxy / TLS front end and the `file.writefor.fun` file server.
-1. restic: Backup my personal data to cloud or NAS.
-1. synthing: Sync file between android/macbook/PC and NAS.
 1. gitea: Self-hosted git service.
-1. sftpgo: SFTP server.
+1. sftpgo: SFTP / WebDAV server.
-1. transmission & AriaNg: Torrent downloader and HTTP downloader
+1. transmission: BitTorrent client.
-1. alist/filebrower: File browser for local/SMB/Cloud
+1. postgresql: Database for the homelab services.
+1. v2ray: HTTP/SOCKS proxy for the homelab.
+1. restic: Encrypted backups; hosts the REST server the desktops push to.
+1. victoriametrics + vmalert + alertmanager + grafana: Monitor the metrics of my homelab.
+1. homepage + uptime-kuma: Service dashboard and uptime checks.
 
 All the services assumes a reverse proxy to be setup in the front, they are all listening on
 localhost, and a caddy service is listening on the local network interface and proxy the requests to

hosts/12kingdoms-youko/homelab-services/grafana/dashboards/README.md

@@ -13,10 +13,6 @@
 
 1. https://github.com/istio/istio/tree/1.23.0/manifests/addons/dashboards
 
-## Kubevirt
-
-1. https://github.com/kubevirt/monitoring/tree/main/dashboards/grafana
-
 ## Loki Mixin
 
 An opinionated set of dashboards, alerts, and recording rules to monitor your Loki cluster. The

hosts/12kingdoms-youko/homelab-services/monitoring/README.md

@@ -16,6 +16,6 @@
   Alertmanager.
 - **Backup freshness**: nothing alerts on "no recent successful backup". The systemd `failed` state
   only catches crashes, not a job that never ran or a backup that is silently stale. Export the last
-  successful backup timestamp (restic prometheus exporter; btrfs snapshot time via the node-exporter
+  successful backup timestamp (the restic rest-server already exposes Go/promhttp metrics; btrfs
-  textfile collector) and alert when it exceeds the SLO, and add an off-host btrbk `target` so local
+  snapshot time via the node-exporter textfile collector) and alert when it exceeds the SLO.
-  snapshots are not the only copy.
+  Off-host copies are already restic's job (see `BACKUP.md`), so no btrbk `target` is needed.

hosts/README.md

@@ -10,12 +10,16 @@ This directory contains all host-specific configurations for my NixOS and macOS
 
 Named after characters from "Oshi no Ko":
 
-| Host         | Platform    | Hardware              | Purpose               | Status      |
+| Host         | Platform        | Hardware              | Purpose               | Status      |
-| ------------ | ----------- | --------------------- | --------------------- | ----------- |
+| ------------ | --------------- | --------------------- | --------------------- | ----------- |
-| `ai`         | NixOS       | i5-13600KF + RTX 4090 | Gaming & Daily Use    | ✅ Active   |
+| `ai`         | NixOS           | i5-13600KF + RTX 4090 | Gaming & Daily Use    | ✅ Active   |
-| `aquamarine` | VM | Virtual               | Monitoring & Services | ✅ Active   |
+| `aquamarine` | NixOS (libvirt) | Virtual               | Monitoring & Services | ⚪ Not Used |
-| `kana`       | NixOS       | Virtual               | Reserved              | ⚪ Not Used |
+| `kana`       | NixOS (libvirt) | Virtual               | Run AI Agents         | ✅ Active   |
-| `ruby`       | NixOS       | Virtual               | Reserved              | ⚪ Not Used |
+| `ruby`       | NixOS (libvirt) | Virtual               | Run AI Agents         | ✅ Active   |
+| `akane`      | NixOS (aarch64) | Virtual (UTM)         | aarch64 test VM       | ✅ Active   |
+
+`aquamarine` is retired; its services now run directly on `youko`
+(`hosts/12kingdoms-youko/homelab-services/`).
 
 #### `darwin` - macOS Systems
 
@@ -30,19 +34,19 @@ Named after characters from "Frieren: Beyond Journey's End":
 
 Named after "Twelve Kingdoms":
 
-| Host      | Platform | Hardware                               | Purpose                    | Status    |
+| Host      | Platform | Hardware                               | Purpose                | Status    |
-| --------- | -------- | -------------------------------------- | -------------------------- | --------- |
+| --------- | -------- | -------------------------------------- | ---------------------- | --------- |
-| `shoukei` | NixOS    | MacBook Pro M2                         | NixOS on Apple Silicon     | ✅ Active |
+| `shoukei` | NixOS    | MacBook Pro M2                         | NixOS on Apple Silicon | ✅ Active |
-| `shoryu`  | NixOS    | MoreFine S500Plus (AMD Ryzen 9 5900HX) | VM Host | ✅ Active |
+| `shoryu`  | NixOS    | MoreFine S500Plus (AMD Ryzen 9 5900HX) | VM Host                | ✅ Active |
-| `shushou` | NixOS    | MinisForum UM560 (AMD Ryzen 5 5625U)   | VM Host | ✅ Active |
+| `shushou` | NixOS    | MinisForum UM560 (AMD Ryzen 5 5625U)   | VM Host                | ✅ Active |
-| `youko`   | NixOS    | MinisForum HX99G (AMD Ryzen 9 6900HX)  | VM Host | ✅ Active |
+| `youko`   | NixOS    | MinisForum HX99G (AMD Ryzen 9 6900HX)  | VM Host                | ✅ Active |
 
 ### Virtual Machines & Clusters
 
 #### `k8s` - Kubernetes Infrastructure
 
 - **VM Cluster**: 3 physical mini PCs (shoryu, shushou, youko) running all VMs
-- **K3s Testing**: 3 masters + 3 workers for testing and development
+- **K3s Testing**: `k3s-test-1-master-{1,2,3}`, running as microVMs on those hosts
 
 ### External Systems
 
@@ -104,15 +108,15 @@ Use existing hosts as templates. The key files typically include:
 ### Examples to Reference
 
 - **Desktop systems**: See `idols-ai/` for gaming/workstation setup
-- **Server systems**: See `shoryu/` for K8s/VM hosts
+- **Server systems**: See `12kingdoms-shoryu/` for VM hosts
 - **macOS systems**: See `darwin-fern/` for macOS configurations
 - **Apple Silicon**: See `12kingdoms-shoukei/` for ARM Linux setup
 
 ## Deploying VM Hosts
 
-The three VM hosts (`shoryu`, `shushou`, `youko`) put their VMs'
+The three VM hosts (`shoryu`, `shushou`, `youko`) attach their VMs (microVM taps and libvirt
-secondary network on the Linux bridge `br0` (attached by the `bridge` CNI plugin); the pod network
+domains) to the Linux bridge `br0`, with the physical NIC as a bridge port. The `k3s-test-1` cluster
-is Cilium (flannel disabled).
+runs as microVMs on top, using Cilium as its pod network (flannel disabled).
 
 - `switch` is fine for changes that don't touch the network stack (e.g. journald or other service
   settings). Deploy serially (`-p 1`) and re-check VM reachability afterwards.

hosts/idols-ai/README.md

@@ -5,7 +5,7 @@ Desktop (NixOS + preservation, LUKS + btrfs on nvme). Disk layout is declarative
 
 Related:
 
-- [nixos-installer README](/nixos-installer/README.md) – install from ISO using disko
+- [nixos-installer README](../nixos-installer/README.md) – install from ISO using disko
 - [disko-fs.nix](./disko-fs.nix) – main disk layout (ESP + LUKS + btrfs). From
   `nix-config/nixos-installer`:  
   `nix run github:nix-community/disko -- --mode destroy,format,mount ../hosts/idols-ai/disko-fs.nix`
@@ -17,153 +17,6 @@ Related:
 
 ## Info
 
-Current disk status and mountpoints (example; after migration layout is on nvme1n1):
+The disk layout is fully declarative — see [disko-fs.nix](./disko-fs.nix) for the root disk and
-
+[disko-fs-data.nix](./disko-fs-data.nix) for the data disk. Run `df -Th` / `lsblk` on the host if an
-```bash
+up-to-date snapshot of the current mounts is needed.
-› df -Th
-Filesystem                Type      Size  Used Avail Use% Mounted on
-devtmpfs                  devtmpfs  1.6G     0  1.6G   0% /dev
-tmpfs                     tmpfs      16G  8.0K   16G   1% /dev/shm
-tmpfs                     tmpfs     7.8G  7.9M  7.8G   1% /run
-tmpfs                     tmpfs      16G  1.1M   16G   1% /run/wrappers
-tmpfs                     tmpfs      16G   87M   16G   1% /
-/dev/mapper/crypted-nixos btrfs     1.9T  630G  1.3T  34% /persistent
-/dev/mapper/crypted-nixos btrfs     1.9T  630G  1.3T  34% /nix
-tmpfs                     tmpfs     4.0M     0  4.0M   0% /sys/fs/cgroup
-efivarfs                  efivarfs  256K  108K  144K  43% /sys/firmware/efi/efivars
-/dev/mapper/crypted-nixos btrfs     1.9T  630G  1.3T  34% /snapshots
-/dev/mapper/crypted-nixos btrfs     1.9T  630G  1.3T  34% /swap
-/dev/nvme0n1p1            vfat      597M  108M  490M  19% /boot
-tmpfs                     tmpfs     3.2G   48K  3.2G   1% /run/user/1000
-//192.168.5.194/Downloads cifs      3.7T  3.0T  699G  82% /home/ryan/SMB-Downloads
-tmpfs                     tmpfs     100K     0  100K   0% /var/lib/lxd/shmounts
-tmpfs                     tmpfs     100K     0  100K   0% /var/lib/lxd/devlxd
-/dev/mapper/crypted-nixos btrfs     1.9T  630G  1.3T  34% /tmp
-
-~
-› lsblk
-NAME              MAJ:MIN RM  SIZE RO TYPE  MOUNTPOINTS
-nvme0n1           259:0    0  1.8T  0 disk
-├─nvme0n1p1       259:1    0  598M  0 part  /boot
-└─nvme0n1p2       259:2    0  1.8T  0 part
-  └─crypted-nixos 254:0    0  1.8T  0 crypt /swap/swapfile
-                                            /gnu/store
-                                            /swap
-                                            /tmp
-                                            /snapshots
-                                            /gnu
-                                            /btr_pool
-                                            /var/log
-                                            /var/lib/qemu
-                                            /var/lib/tailscale
-                                            /var/lib/systemd
-                                            /var/lib/private
-                                            /var/lib/nixos
-                                            /var/lib/lxd
-                                            /var/lib/netbird-homelab
-                                            /var/lib/lxc
-                                            /var/lib/libvirt
-                                            /var/lib/iwd
-                                            /var/lib/flatpak
-                                            /var/lib/containers
-                                            /var/lib/cni
-                                            /var/lib/NetworkManager
-                                            /var/lib/bluetooth
-                                            /home/ryan/work
-                                            /home/ryan/nix-config
-                                            /home/ryan/tmp
-                                            /home/ryan/go
-                                            /home/ryan/codes
-                                            /home/ryan/Videos
-                                            /home/ryan/Pictures
-                                            /home/ryan/Music
-                                            /home/ryan/Games
-                                            /home/ryan/Downloads
-                                            /home/ryan/.zoom
-                                            /home/ryan/Documents
-                                            /home/ryan/.wakatime
-                                            /home/ryan/.var
-                                            /home/ryan/.terraform.d/plugin-cache
-                                            /home/ryan/.steam
-                                            /home/ryan/.ssh
-                                            /home/ryan/.pulumi
-                                            /home/ryan/.pki
-                                            /home/ryan/.npm
-                                            /home/ryan/.mozilla
-                                            /home/ryan/.m2
-                                            /home/ryan/.local/state/wireplumber
-                                            /home/ryan/.local/state/nvim
-                                            /home/ryan/.local/state/home-manager
-                                            /home/ryan/.local/share/uv
-                                            /home/ryan/.local/state/Heroic
-                                            /home/ryan/.local/state/nix/profiles
-                                            /home/ryan/.local/share/zoxide
-                                            /home/ryan/.local/share/umu
-                                            /home/ryan/.local/share/tiled
-                                            /home/ryan/.local/share/steel
-                                            /home/ryan/.local/share/remmina
-                                            /home/ryan/.local/share/password-store
-                                            /home/ryan/.local/share/opencode
-                                            /home/ryan/.local/share/nvim
-                                            /home/ryan/.local/share/zed
-                                            /home/ryan/.local/share/nix
-                                            /home/ryan/.local/share/krita
-                                            /home/ryan/.local/share/lutris
-                                            /home/ryan/.local/share/keyrings
-                                            /home/ryan/.local/share/k9s
-                                            /home/ryan/.local/share/jupyter
-                                            /home/ryan/.local/share/flatpak
-                                            /home/ryan/.local/share/io.github.clash-verge-rev.clash-verge-rev
-                                            /home/ryan/.local/share/feral-interactive
-                                            /home/ryan/.local/share/direnv
-                                            /home/ryan/.local/share/clash-verge
-                                            /home/ryan/.local/share/containers
-                                            /home/ryan/.local/share/atuin
-                                            /home/ryan/.local/share/Steam
-                                            /home/ryan/.local/share/StardewValley
-                                            /home/ryan/.local/share/GOG.com
-                                            /home/ryan/.local/bin
-                                            /home/ryan/.kube
-                                            /home/ryan/.gradle
-                                            /home/ryan/.gnupg
-
-
-                                            /home/ryan/.ipython
-
-                                            /home/ryan/.docker
-                                            /home/ryan/.config/sunshine
-                                            /home/ryan/.context7
-                                            /home/ryan/.config/remmina
-                                            /home/ryan/.config/pulse
-                                            /home/ryan/.config/opencode
-                                            /home/ryan/.config/obs-studio
-                                            /home/ryan/.config/mozc
-                                            /home/ryan/.config/nushell
-                                            /home/ryan/.config/zed
-                                            /home/ryan/.config/lutris
-                                            /home/ryan/.config/joplin
-                                            /home/ryan/.config/heroic
-                                            /home/ryan/.config/google-chrome
-                                            /home/ryan/.config/gcloud
-                                            /home/ryan/.config/freerdp
-                                            /home/ryan/.config/blender
-                                            /home/ryan/.config/chromium
-                                            /home/ryan/.config/LDtk
-                                            /home/ryan/.config/Joplin
-                                            /home/ryan/.conda
-                                            /home/ryan/.cargo
-                                            /home/ryan/.codex
-                                            /home/ryan/.cache
-                                            /home/ryan/.aws
-                                            /home/ryan/.aliyun
-                                            /etc/ssh
-                                            /etc/secureboot
-                                            /etc/nix/inputs
-                                            /etc/NetworkManager/system-connections
-                                            /etc/agenix
-                                            /etc/netbird-homelab
-                                            /nix/store
-                                            /etc/machine-id
-                                            /persistent
-                                            /nix
-```

hosts/k8s/README.md

@@ -9,14 +9,13 @@ full featured(see [what-have-k3s-removed-from-upstream-kubernetes] for details).
 
 ## VM Cluster
 
-The VM cluster is running on physical machines, all my virtual machines are running on this cluster,
+The VM cluster is running on physical machines; all my virtual machines run on these hosts,
-including other Kubernetes clusters.
+including the `k3s-test-1` cluster.
 
 ## K3s Clusters
 
-The control plane runs as NixOS **microVMs** ([microvm.nix]) on the physical hosts, not as KubeVirt
+The control plane runs as NixOS **microVMs** ([microvm.nix]) on the physical hosts. Each guest keeps
-VMs. Each guest keeps its state in three sparse ext4 images under the host's
+its state in three sparse ext4 images under the host's `/var/lib/microvms/<name>/`:
-`/var/lib/microvms/<name>/`:
 
 - `etc.img` (64M) — the ssh host key (also the agenix age identity) and `machine-id`
 - `var.img` (20G) — k3s state (`/var/lib/rancher/k3s`) and the NixOS uid/gid maps
@@ -29,16 +28,15 @@ bridged onto `br0`, and its name is derived from the guest IP (e.g. `192.168.5.1
 
 To move an existing VM over in place, copy the host key and `machine-id` from its disk into
 `etc.img`, and `/var/lib/rancher/k3s/server` into `var.img`, **before the first boot** — then it
-keeps its identity and etcd membership instead of bootstraping a new cluster.
+keeps its identity and etcd membership instead of bootstrapping a new cluster.
 
 1. `k3s-test-1-master-{1,2,3}` — running as microVMs
-1. `k3s-test-1-worker-{1,2,3}` — to be re-added as microVMs
 
 ## TODO / Known issues
 
-- **The USB HDD bridge is flaky.** aquamarine's two HDDs sit behind a JMicron JMS567 USB-SATA bridge
+- **The USB HDD bridge is flaky.** youko's two HDDs sit behind a JMicron JMS567 USB-SATA bridge that
-  that keeps resetting (`dmesg` on `youko`). Find out how often it resets and how much it matters
+  keeps resetting (`dmesg` on `youko`). Find out how often it resets and how much it matters before
-  before putting anything critical (e.g. an NFS export) on it.
+  putting anything critical (e.g. an NFS export) on it.
 
 ## Kubernetes Resources
 

hosts/k8s/disko-config/README.md

@@ -12,7 +12,7 @@ cd nix-config
 
 ## 1. partition & format the disk via disko
 # encrypt the root partition with luks2 and argon2id, will prompt for a passphrase, which will be used to unlock the partition.
-sudo nix --experimental-features "nix-command flakes" run github:nix-community/disko -- --mode destroy,format,mount hosts/k8s/disko-config/kubevirt-disko-fs.nix
+sudo nix --experimental-features "nix-command flakes" run github:nix-community/disko -- --mode destroy,format,mount hosts/k8s/disko-config/host-disko-fs.nix
 ## 2. setup the automatic unlock via the tpm2 chip
 systemd-cryptenroll --tpm2-device=auto --tpm2-pcrs=0+7 /dev/<encrypted-disk-part-path>
 

infra/minio/tf-s3-backend/README.md

@@ -1,5 +1,5 @@
 # Terraform's S3 Backend
 
-This terraform workspace will be used only once, and we will not save the terrform.tfstate file.
+This terraform workspace will be used only once, and we will not save the terraform.tfstate file.
 
 It's used to create a minio bucket to store all other tfstate files.

lib/README.md

@@ -1,7 +1,7 @@
 # Library
 
-This directory contains helper functions used by `flake.nix` to reduce code duplication and make it
+This directory contains helper functions used by `outputs/default.nix` (and the installer flake) to
-easier to add new machines.
+reduce code duplication and make it easier to add new machines.
 
 ## Current Functions
 
@@ -16,13 +16,15 @@ easier to add new machines.
 
 ### Specialized Module Generators
 
-5. **`genK3sAgentModule.nix`** - K3s agent node configuration generator
+5. **`genK3sServerModule.nix`** - K3s server node configuration generator
-6. **`genK3sServerModule.nix`** - K3s server node configuration generator
+6. **`genVmHostModule.nix`** - physical VM host (bridge + libvirt) configuration generator
+7. **`genMicrovmGuestModule.nix`** - NixOS microVM guest configuration generator
+8. **`genLibvirtDomainXml.nix`** - libvirt domain XML generator (imported directly by host configs)
 
 ### Entry Point
 
-9. **`default.nix`** - Main entry point that imports all functions and exports them as a single
+9. **`default.nix`** - Main entry point that imports the generators and exports them as a single
-   attribute set
+   attribute set, plus the `relativeToRoot` and `scanPaths` helpers
 
 ## Usage
 

modules/README.md

@@ -13,8 +13,8 @@ modules/
 │   ├── fonts.nix           # System font configuration
 │   ├── nix.nix            # Nix package manager settings
 │   ├── overlays.nix       # Package overlays
+│   ├── packages.nix       # Essential system packages
 │   ├── security.nix       # Basic security settings
-│   ├── system-packages.nix # Essential system packages
 │   └── users.nix          # User management
 ├── darwin/                  # macOS-specific modules
 │   ├── README.md
@@ -29,36 +29,39 @@ modules/
 └── nixos/                   # NixOS-specific modules
     ├── base/               # Base NixOS configuration
     │   ├── btrbk.nix      # Local btrfs snapshots
-    │   ├── restic-backup.nix # Encrypted off-host backups (see ./BACKUP.md)
     │   ├── core.nix       # Core system settings
     │   ├── default.nix
     │   ├── i18n.nix       # Internationalization
+    │   ├── kernel-hardening.nix # Kernel hardening (module blacklisting)
     │   ├── monitoring.nix # System monitoring
-    │   ├── networking.nix # Network configuration
+    │   ├── networking/    # Network configuration
     │   ├── nix.nix        # Nix settings
     │   ├── packages.nix   # System packages
     │   ├── remote-building.nix # Remote build setup
+    │   ├── restic-backup.nix # Encrypted off-host backups (see ../BACKUP.md)
     │   ├── ssh.nix        # SSH daemon configuration
+    │   ├── trash.nix      # Trash retention cleanup
     │   ├── user-group.nix # User and group management
     │   └── zram.nix       # ZRAM swap configuration
     ├── desktop.nix         # Desktop environment configuration
     ├── desktop/            # Desktop-specific modules
+    │   ├── computer-use.nix # Headless X11/i3 session for AI agents
     │   ├── default.nix
     │   ├── fhs.nix        # FHS environment
     │   ├── fonts.nix      # Desktop fonts
-    │   ├── guix.nix       # GNU Guix integration
+    │   ├── gaming.nix     # Gaming support
     │   ├── misc.nix       # Miscellaneous desktop settings
     │   ├── networking/    # Network-related desktop configs
-    │   │   ├── clash-verge.nix
+    │   ├── nix.nix        # Desktop Nix settings
-    │   │   ├── default.nix
-    │   │   ├── remote-desktop.nix
-    │   │   └── tailscale.nix
     │   ├── peripherals.nix # Peripheral device configuration
+    │   ├── power.nix      # Power management
     │   ├── security.nix   # Desktop security settings
+    │   ├── ssh.nix        # Desktop SSH configuration
     │   ├── virtualisation.nix # Virtualization support
     │   └── xdg.nix       # XDG base directory settings
     └── server/             # Server-specific modules
         ├── qemu-guest-hardware-configuration.nix
+        ├── qemu-guest.nix  # VM guest base module (libvirt/QEMU guests)
         ├── server-aarch64.nix
         ├── server-riscv64.nix
         └── server.nix

modules/nixos/base/btrbk.nix

@@ -20,7 +20,7 @@ in
   #
   # These are same-filesystem snapshots: they protect against accidental
   # deletion and bad edits, NOT against disk loss. Off-host copies are handled
-  # by restic (lib/genResticBackup.nix), which can exclude the regenerable bulk
+  # by restic (modules/nixos/base/restic-backup.nix), which can exclude the regenerable bulk
   # at the file level; btrbk works at the subvolume level, so a `target` would
   # also ship podman's overlay storage and the VM disk images. Set `target`
   # (plus `services.btrbk.sshAccess` on the receiving host) only if you want

nixos-installer/README.md

@@ -109,7 +109,7 @@ After the first boot:
    sudo mv /etc/nixos ~/nix-config
    sudo chown -R ryan:ryan ~/nix-config
    cd ~/nix-config
-   just hypr
+   just niri
    ```
 
 4. **Secure Boot**: follow

nixos-installer/README.shoukei.md

@@ -5,7 +5,7 @@
 > and documentation for reference only.**
 
 This flake prepares a Nix environment for setting my desktop
-[/hosts/12kingdoms-shoukei](/hosts/12kingdoms-shoukei)(in main flake) up on a new machine.
+[../hosts/12kingdoms-shoukei](../hosts/12kingdoms-shoukei) (in the main flake) up on a new machine.
 
 ## Steps to Deploying
 
@@ -122,7 +122,7 @@ lsblk
 # show cryptsetup's compiled in defaults
 cryptsetup --help
 
-# NOTE: `cat shoukei.md | grep luks > format.sh` to generate this script
+# NOTE: `cat README.shoukei.md | grep luks > format.sh` to generate this script
 # encrypt the root partition with luks2 and argon2id, will prompt for a passphrase, which will be used to unlock the partition.
 cryptsetup luksFormat --type luks2 --cipher aes-xts-plain64 --hash sha512 --iter-time 5000 --key-size 256 --pbkdf argon2id --use-random --verify-passphrase /dev/nvme0n1p6
 
@@ -142,7 +142,7 @@ Formatting the root partition:
 # If btrfs is not included in the liveos, run this before formatting
 nix-shell -p btrfs-progs
 
-# NOTE: `cat shoukei.md | egrep "create-btrfs"  > create-btrfs.sh` to generate this script
+# NOTE: `cat README.shoukei.md | egrep "create-btrfs"  > create-btrfs.sh` to generate this script
 # format the root partition with btrfs and label it
 # set sectorsize to match the CPU page size
 mkfs.btrfs --sectorsize 16384 -L crypted-nixos /dev/mapper/crypted-nixos  # create-btrfs
@@ -155,7 +155,7 @@ btrfs subvolume create /mnt/@persistent  # create-btrfs
 btrfs subvolume create /mnt/@snapshots  # create-btrfs
 umount /mnt  # create-btrfs
 
-# NOTE: `cat shoukei.md | grep mount-1 > create-btrfs.sh` to generate this script
+# NOTE: `cat README.shoukei.md | grep mount-1 > create-btrfs.sh` to generate this script
 # Remount the root partition with the subvolumes you just created
 #
 # Enable zstd compression to:
@@ -236,7 +236,7 @@ Then, generate the NixOS configuration:
 nixos-generate-config --root /mnt
 
 # we need to update our filesystem configs in old hardware-configuration.nix according to the generated one.
-cp /etc/nixos/hardware-configuration.nix ./nix-config/hosts/12kingdoms_shoukei/hardware-configuration-new.nix
+cp /etc/nixos/hardware-configuration.nix ./nix-config/hosts/12kingdoms-shoukei/hardware-configuration-new.nix
 vim ./nix-config
 ```
 
@@ -273,9 +273,9 @@ mv /etc/ssh /persistent/etc/
 
 # delete the generated configuration after editing
 rm -f /mnt/etc/nixos
-rm ~/nix-config/hosts/idols_ai/hardware-configuration-new.nix
+rm ~/nix-config/hosts/12kingdoms-shoukei/hardware-configuration-new.nix
 
-# NOTE: `cat shoukei.md | grep git-1 > git-1.sh` to generate this script
+# NOTE: `cat README.shoukei.md | grep git-1 > git-1.sh` to generate this script
 # commit the changes after installing nixos successfully
 git config --global user.email "ryan4yin@linux.com"   # git-1
 git config --global user.name "Ryan Yin"              # git-1
@@ -319,10 +319,10 @@ sudo chown -R ryan:ryan ~/nix-config
 cd ~/nix-config
 
 # deploy the configuration via Justfile
-just s-hypr
+just niri
 ```
 
 Finally, to enable secure boot, follow the instructions in
 [lanzaboote - Quick Start](https://github.com/nix-community/lanzaboote/blob/master/docs/QUICK_START.md)
 and
-[nix-config/ai/secure-boot.nix](https://github.com/ryan4yin/nix-config/blob/main/hosts/idols_ai/secureboot.nix)
+[nix-config/ai/secure-boot.nix](https://github.com/ryan4yin/nix-config/blob/main/hosts/idols-ai/secureboot.nix)

outputs/README.md

@@ -7,7 +7,7 @@ There is no need to do this when you have a small number of machines.
 But when you have a large number of machines, it is necessary to manage them in a fine-grained way,
 otherwise, it will be difficult to manage and maintain them.
 
-The number of my machines has grown to more than 20, and the increase in scale has shown signs of
+The number of my machines has grown past a dozen, and the increase in scale has shown signs of
 getting out of control of complexity, so it is a natural and reasonable choice to use this
 fine-grained architecture to manage.
 
@@ -32,7 +32,7 @@ Related projects & docs:
 
 Eval Tests evaluate the expressions and compare the results with the expected results. It runs fast,
 but it doesn't build a real machine. We use eval tests to ensure that some attributes are correctly
-set for each NixOS host(not Darwin).
+set for each NixOS and nix-darwin host.
 
 How to run all the eval tests:
 
@@ -74,40 +74,30 @@ All the outputs of this flake are defined here.
 ├── default.nix       # The entry point, all the outputs are composed here.
 ├── README.md
 ├── aarch64-darwin    # All outputs for macOS Apple Silicon
-│   ├── default.nix
+│   ├── default.nix
-│   └── src           # every host has its own file in this directory
+│   ├── src           # every host has its own file in this directory
-│       ├── frieren.nix
+│   │   ├── fern.nix
-│       └── fern.nix
+│   │   └── frieren.nix
+│   └── tests         # eval tests
 ├── aarch64-linux     # All outputs for Linux ARM64
-│   ├── default.nix
+│   ├── default.nix
-│   ├── src           # every host has its own file in this directory
+│   ├── src           # every host has its own file in this directory
-│   │   ├── 12kingdoms-shoukei.nix
+│   │   ├── 12kingdoms-shoukei.nix
-│   └── tests         # eval tests
+│   │   └── idols-akane.nix
+│   └── tests         # eval tests
 └── x86_64-linux      # All outputs for Linux x86_64
     ├── default.nix
     ├── nixos-tests
     ├── src           # every host has its own file in this directory
-    │   ├── idols-ai.nix
+    │   ├── 12kingdoms-shoryu.nix
-    │   ├── idols-aquamarine.nix
+    │   ├── 12kingdoms-shushou.nix
-    │   ├── idols-kana.nix
+    │   ├── 12kingdoms-youko.nix
-    │   ├── idols-ruby.nix
+    │   ├── idols-ai.nix
+    │   ├── idols-kana.nix
+    │   ├── idols-ruby.nix
     │   ├── k3s-test-1-master-1.nix
     │   ├── k3s-test-1-master-2.nix
-    │   ├── k3s-test-1-master-3.nix
+    │   └── k3s-test-1-master-3.nix
-    │   ├── k3s-test-1-worker-1.nix
+    └── tests         # eval tests (btrbk, computer-use-headless, hostname,
-    │   ├── k3s-test-1-worker-2.nix
+                      # kernel, security-*, ups-metrics, ...)
-    │   ├── k3s-test-1-worker-3.nix
-    │   ├── shoryu.nix
-    │   ├── shushou.nix
-    │   └── youko.nix
-    └── tests         # eval tests
-        ├── home-manager
-        │   ├── expected.nix
-        │   └── expr.nix
-        ├── hostname
-        │   ├── expected.nix
-        │   └── expr.nix
-        └── kernel
-            ├── expected.nix
-            └── expr.nix
 ```

overlays/README.md

@@ -10,11 +10,14 @@ through [Overlays - NixOS & Flakes Book](https://nixos-and-flakes.thiscute.world
 ```
 overlays/
 ├── README.md
-├── default.nix          # Entrypoint for all overlays
+├── default.nix            # Entrypoint for all overlays
-└── fcitx5/              # Chinese input method configuration
+├── computer-use-linux.nix # trycua/computer-use-linux package
+├── cua-driver.nix         # trycua/cua driver (cua-driver) package
+├── openldap.nix           # OpenLDAP (skips its failing tests)
+└── fcitx5/                # Chinese input method configuration
     ├── README.md
-    ├── default.nix      # fcitx5 overlay definition
+    ├── default.nix        # fcitx5 overlay definition
-    └── rime-data-flypy/ # Custom rime data for 小鹤音形输入法
+    └── rime-data-flypy/   # Custom rime data for 小鹤音形输入法
         └── share/
             └── rime-data/
                 ├── build/
@@ -48,3 +51,9 @@ This overlay provides:
 - Custom rime data for 小鹤音形输入法 (Flypy input method)
 - Cross-platform support for both Linux (fcitx5-rime) and macOS (squirrel)
 - Pre-configured input method settings
+
+### 3. Package overlays
+
+- `computer-use-linux.nix`: packages `pkgs/computer-use-linux`.
+- `cua-driver.nix`: packages `pkgs/cua-driver` (used by the computer-use VMs).
+- `openldap.nix`: disables OpenLDAP's failing test suite.

overlays/fcitx5/README.md

@@ -5,14 +5,14 @@ Useful for Linux(fcitx5-rime) & macOS(squirrel).
 ## Linux(fcitx5-rime)
 
 1. `~/.config/fcitx5/profile` is linked to
-   [home/linux/gui/base/fcitx5/profile](/home/linux/gui/base/fcitx5/profile), which hardcode rime as
+   [home/linux/gui/base/fcitx5/profile](../../home/linux/gui/base/fcitx5/profile), which hardcode
-   the default input method, so you do not need to use fcitx-configtool to adjust fcitx5's input
+   rime as the default input method, so you do not need to use fcitx-configtool to adjust fcitx5's
-   method.
+   input method.
 
 ## macOS(squirrel)
 
 1. ` ~/Library/Rime/` is force linked to this rime-data, see
-   [home/darwin/rime-squirrel.nix](/home/darwin/rime-squirrel.nix) for details.
+   [home/darwin/rime-squirrel.nix](../../home/darwin/rime-squirrel.nix) for details.
 
 ## Docs about fcitx5
 

secrets/README.md

@@ -1,7 +1,7 @@
 # Secrets Management
 
 > For Website/App's passwords, see
-> [/home/base/tui/password-store](/home/base/tui/password-store/README.md) for more details.
+> [../home/base/tui/password-store](../home/base/tui/password-store/README.md) for more details.
 
 All my secrets are safely encrypted via agenix, and stored in a separate private GitHub repository
 and referenced as a flake input in this flake.
@@ -112,11 +112,17 @@ sub modules via `specialArgs`:
   inputs = {
     # ......
 
-    # secrets management, lock with git commit at 2023/5/15
+    # secrets management, lock with git commit at May 18, 2025
-    agenix.url = "github:ryantm/agenix/db5637d10f797bb251b94ef9040b237f4702cde3";
+    agenix = {
+      url = "github:ryantm/agenix/4835b1dc898959d8547a871ef484930675cb47f1";
+      inputs.nixpkgs.follows = "nixpkgs";
+    };
 
     # my private secrets, it's a private repository, you need to replace it with your own.
-    mysecrets = { url = "github:ryan4yin/nix-secrets"; flake = false; };
+    mysecrets = {
+      url = "git+ssh://git@github.com/ryan4yin/nix-secrets.git?shallow=1";
+      flake = false;
+    };
   };
 
   outputs = inputs@{ self, nixpkgs, ... }: {
@@ -131,7 +137,7 @@ sub modules via `specialArgs`:
           # ......
 
           # import & decrypt secrets in `mysecrets` in this module
-          ./secrets/default.nix
+          ./secrets/nixos.nix
         ];
       };
     };
@@ -139,7 +145,7 @@ sub modules via `specialArgs`:
 }
 ```
 
-Then, create `./secrets/default.nix` with the following content:
+Then, create `./secrets/nixos.nix` (or `./secrets/darwin.nix` on macOS) with the following content:
 
 ```nix
 # import & decrypt secrets in `mysecrets` in this module

vars/README.md

@@ -38,7 +38,7 @@ The networking configuration covers:
 
 - **Physical machines**: Desktop PCs, Apple Silicon systems, SBCs
 - **Virtual machines**: VM guests, K3s nodes
-- **Kubernetes clusters**: Production and testing environments
+- **Kubernetes clusters**: the `k3s-test-1` testing cluster
 - **Network infrastructure**: Routers, gateways, and DNS configuration
 
 ## Usage