docs: README audit fixes and de-duplication (#371)

README.md

@@ -116,8 +116,6 @@ hardening, and [./WORKAROUNDS.md](./WORKAROUNDS.md) for temporary exceptions and
 > [ryan4yin/nix-secrets](https://github.com/ryan4yin/nix-secrets) to deploy. You
 > may use this repo as a reference to build your own configuration.
 
-Run `just --list` to see every recipe.
-
 Updating flake inputs and rolling the result out safely is a procedure, not a single command. Follow
 [`.agents/skills/nix-config-update/SKILL.md`](./.agents/skills/nix-config-update/SKILL.md).
 

agents/README.md

@@ -37,13 +37,9 @@ the Home Manager module [`home/base/tui/agents/`](../home/base/tui/agents/README
 ## Deployment
 
 [`home/base/tui/agents/rules.nix`](../home/base/tui/agents/rules.nix) links `AGENTS.md` into every
-supported agent config directory as an out-of-store symlink, so edits apply without a rebuild:
+supported agent config directory as an out-of-store symlink, so edits apply without a rebuild. The
-
+per-agent target list lives in that module's
-- Codex: `AGENTS.md` -> `${CODEX_HOME:-~/.codex}/AGENTS.md`
+[README](../home/base/tui/agents/README.md#deployed-rule-targets).
-- OpenCode: `AGENTS.md` -> `${XDG_CONFIG_HOME:-~/.config}/opencode/AGENTS.md`
-- Pi: `AGENTS.md` -> `~/.pi/agent/AGENTS.md`
-- OMP: `AGENTS.md` -> `~/.omp/agent/AGENTS.md`
-- Generic cross-tool (read by Kimi Code): `AGENTS.md` -> `~/.agents/AGENTS.md`
 
 The module is imported through `home/base/tui`, so it covers the hosts that import
 `home/linux/gui.nix` or the macOS `home/darwin` stack; core-only servers are unchanged.

certs/README.md

@@ -13,8 +13,9 @@ use. It is used to issue certificates for my own servers and services.
 
 ## Security Notes
 
-All private keys (`.key` files) are ignored by git and stored in a private secrets repository. The
+Private keys (`.key`) and certificate signing requests (`.csr`) are ignored by git; the keys are
-public certificates and configuration files are committed to this repository for reference.
+stored in a private secrets repository. The public certificates and configuration files are
+committed to this repository for reference.
 
 ## Usage
 

hardening/README.md

@@ -94,10 +94,9 @@ hardening/
 
 ## NOTE
 
-**Running untrusted code is never safe, kernel hardening & sandboxing cannot change this**.
+**Running untrusted code is never safe, kernel hardening & sandboxing cannot change this**; run
-
+untrusted code in a VM on an isolated network. The threat model lives in
-If you want to run untrusted code, please use a VM & an isolated network environment, which will
+[`SECURITY.md`](../SECURITY.md).
-provide a much higher level of security.
 
 ## References
 
@@ -110,5 +109,3 @@ provide a much higher level of security.
 - apparmor configs:
   - https://github.com/zramctl/dotfiles/blob/4fe177f6984154960942bb47d5a375098ec6ed6a/modules/nixos/security/apparmor.nix#L4
   - https://git.grimmauld.de/Grimmauld/grimm-nixos-laptop/src/branch/main/hardening
-- Others:
-  - Directly via `buildFHSUserEnvBubblewrap`:

home/README.md

@@ -6,20 +6,7 @@ This directory contains all Home Manager configurations organized by platform an
 
 ```
 home/
-├── base/              # Cross-platform home manager configurations
+├── base/              # Cross-platform home manager configurations (see base/README.md)
-│   ├── core/          # Essential applications and settings
-│   │   ├── editors/   # Editor configurations (Neovim, Helix)
-│   │   ├── shells/    # Shell configurations (bash, Nushell)
-│   │   └── ...
-│   ├── gui/           # GUI applications and desktop settings
-│   │   ├── terminal/  # Terminal emulators (Ghostty, Kitty, etc.)
-│   │   └── ...
-│   ├── tui/           # Terminal/TUI applications
-│   │   ├── agents/    # AI coding agents (rules deployment, CLIs, env)
-│   │   ├── editors/   # Heavy editor/tooling pkgs only (`packages.nix`; core editors live under `core/editors`)
-│   │   ├── encryption/ # Encryption and security tooling
-│   │   └── ...
-│   └── home.nix       # Main home manager entry point
 ├── linux/             # Linux-specific home manager configurations
 │   ├── base/          # Linux base configurations
 │   ├── gui/           # Linux GUI applications
@@ -28,7 +15,7 @@ home/
 │   │   └── ...
 │   └── ...
 ├── hosts/             # Host-specific home manager entry modules
-│   ├── linux/         # Linux host home modules (ai, shoukei, kana, ruby, k3s-*, etc.)
+│   ├── linux/         # Linux host home modules (idols-ai, 12kingdoms-shoukei, idols-kana, idols-ruby, k3s-test-1-worker-*, etc.)
 │   └── darwin/        # macOS host home modules (fern, frieren)
 └── darwin/            # macOS-specific home manager configurations
     ├── proxy/         # Proxy configurations
@@ -43,7 +30,7 @@ home/
 
 2. **linux**: Linux-specific configuration
    - Desktop environments (Noctalia Shell, Niri compositor)
-   - Headless computer-use session (`gui/i3`, Xvfb + i3; see `gui/i3/README.md`)
+   - Headless computer-use session (see `gui/i3/README.md`)
    - Linux-specific GUI applications
    - System integration tools
 

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

@@ -109,19 +109,19 @@ normal-mode remaps: **`Ctrl+Shift+o`** → jump backward (leaving `Ctrl+o` free
 | Replace selected chars | `r<char>`                                                                            |
 | Indent / format        | `>` / `<`; `=` format (LSP)                                                          |
 | Increment / decrement  | `Ctrl-a` / `Ctrl-x` on selected numbers                                              |
-| Case                   | `~` toggle; lower/upper case via grave / `Alt-grave` (see Alt caveat above)          |
+| Case                   | `~` toggle; lower/upper case via grave / `Alt-grave`                                 |
-| Join lines             | `J`; `Alt-J` join keeping space (see Alt caveat above)                               |
+| Join lines             | `J`; `Alt-J` join keeping space                                                      |
 | Toggle line comment    | `Ctrl-c`                                                                             |
 | Macro record / replay  | `Q` start/stop recording; `q` replay from the default `@` register                   |
 
 ### Search
 
-| Action               | Keys                                                            |
+| Action               | Keys                                     |
-| -------------------- | --------------------------------------------------------------- |
+| -------------------- | ---------------------------------------- |
-| Search / reverse     | `/` / `?`                                                       |
+| Search / reverse     | `/` / `?`                                |
-| Next / prev match    | `n` / `N`                                                       |
+| Next / prev match    | `n` / `N`                                |
-| Selection as pattern | `*` (word bounds); `Alt-*` raw selection (see Alt caveat above) |
+| Selection as pattern | `*` (word bounds); `Alt-*` raw selection |
-| Split on newlines    | `Alt-s`                                                         |
+| Split on newlines    | `Alt-s`                                  |
 
 Use **extend mode** (`v`) with `n` / `N` to add matches to multi-cursors
 ([keymap](https://docs.helix-editor.com/keymap.html#select--extend-mode)).

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

@@ -27,17 +27,9 @@ Neovim and vim share the motions below.
 
 ### Terminal related
 
-tuios shortcuts used often (leader is `Ctrl + B`):
+For the common **tuios** pane shortcuts, see the table in
-
+[`../helix/README.md`](../helix/README.md#terminal-related). To run a shell command from Vim, use
-| Action              | tuios shortcut             |
+`:!<command>`.
-| ------------------- | -------------------------- |
-| New pane            | `n` (window mode)          |
-| Floating terminal   | `Ctrl + B`, then `Alt + F` |
-| Split horizontal    | `Ctrl + B`, then `-`       |
-| Split vertical      | `Ctrl + B`, then `\`       |
-| Command palette     | `Ctrl + P`                 |
-| Detach              | `Ctrl + B`, then `d`       |
-| Run a shell command | `!xxx`                     |
 
 ### File management
 

home/base/tui/agents/README.md

@@ -10,8 +10,8 @@ Nix dependency; this module only wires it into place.
 ## Files
 
 - `rules.nix`: links the global rules to every agent's config location.
-- `packages.nix`: agent CLIs (`codex`, `opencode2`, `kimi-code`, `pi`, `omp`) and the Grafana MCP
+- `packages.nix`: agent CLIs (`codex`, `opencode2`, `kimi-code`, `pi`, `omp`) from the `llm-agents`
-  server, from the `llm-agents` flake input.
+  flake input, plus `pkgs.mcp-grafana` for the Grafana MCP server.
 - `env.nix`: telemetry and auto-update opt-outs for the agents.
 
 ## Deployed rule targets

home/base/tui/encryption/README.md

@@ -22,8 +22,8 @@ recommended, as it use KMS for key management.
 
 ## Symmetric Encryption
 
-Both age & GnuPG provide symmetric encryption, which is useful for encrypting files for a specific
+Both age & GnuPG provide symmetric encryption, where a passphrase encrypts and decrypts the file
-user.
+instead of a recipient key.
 
 As described in [age Format v1][age Format v1], age use scrypt to encrypt and decrypt the file key
 with a provided passphrase, which is more secure than GnuPG's symmetric encryption.

home/base/tui/gpg/README.md

@@ -498,7 +498,7 @@ gpg --delete-secret-keys ryan4yin@linux.com
 rm ~/.gnupg/openpgp-revocs.d/C8D84EBC5F82494F432ACEF042E49B284C30A0DA.rev
 
 # import our subkeys back
-age --decrypt -o ryan4yin-primary-key.priv ryan4yin-primary-key.priv.age
+age --decrypt -o ryan4yin-gpg-subkeys.priv ryan4yin-gpg-subkeys.priv.age
 gpg --import ryan4yin-gpg-subkeys.priv
 ```
 

home/linux/README.md

@@ -16,7 +16,7 @@ cases.
 
 - **gui/**: Desktop environment configurations
   - **niri/**: Niri compositor configuration
-  - **i3/**: Headless X11 computer-use session (Xvfb + i3)
+  - **i3/**: Headless computer-use session (see `gui/i3/README.md`)
   - **base/**: Common desktop applications and services
 
 ### Available Entry Points

home/linux/gui/README.md

@@ -15,9 +15,8 @@ Manager.
 ### Base Desktop Environment
 
 - **base**: Common desktop configurations shared across all environments, including:
-  - **Noctalia**: native (v5) all-in-one Wayland desktop shell (replaces gammastep, swaylock,
+  - **Noctalia**: native (v5) all-in-one Wayland desktop shell; see
-    anyrun, mako, waybar, wallpaper-switcher, grim/slurp/satty, and other desktop tools; `wlogout`
+    [`base/README.md`](./base/README.md) for the components it replaces
-    stays as an emergency session-menu fallback)
   - Creative tools and media applications
   - Development tools
   - Fcitx5 input method framework

home/linux/gui/base/README.md

@@ -75,7 +75,8 @@ Noctalia consolidates functionality that previously required multiple tools:
 
 ### Input & Localization
 
-- **[`fcitx5/`](./fcitx5/)**: Fcitx5 input method with Mozc (Japanese input)
+- **[`fcitx5/`](./fcitx5/)**: Fcitx5 input method with Rime (Chinese), Mozc (Japanese), and Hangul
+  (Korean) engines
 
 ### Applications
 

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

@@ -1,5 +1,9 @@
 # fcitx5 - IME
 
+fcitx5 is enabled in `default.nix` with the [flypy](https://flypy.com/) Rime schema (Chinese),
+`fcitx5-mozc-ut` (Japanese), and `fcitx5-hangul` (Korean), alongside the US keyboard layouts. The
+Rime data ships in the [`overlays/fcitx5`](../../../../../overlays/fcitx5/) overlay.
+
 ## Available Configurations
 
 - `profile` → Symlink will be created at: `~/.config/fcitx5/profile`

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

@@ -6,6 +6,8 @@
 2. https://grafana.com/grafana/dashboards/9578-alertmanager/
 3. `smartctl.json` — drive/SSD SMART health (wear, spare, media errors, temperature). Custom, built
    on the `smartctl_exporter` metrics.
+4. `gpu.json` — GPU utilization, VRAM, and temperature.
+5. `nut-exporter.json` — UPS status (battery, load, runtime) from the NUT exporter.
 
 ## Kubernetes
 
@@ -25,7 +27,8 @@ mixin provides a comprehensive package for monitoring Loki in production.
 ## Databases
 
 1. PostgreSQL: https://grafana.com/grafana/dashboards/9628-postgresql-database/
-   - Requires Prometheus PostgreSQL exporter metrics. See: wrouesnel/postgres_exporter
+   - Requires Prometheus PostgreSQL exporter metrics. See:
+     <https://github.com/prometheus-community/postgres_exporter>
 1. CloudNative-PG:
    - Instance:
      https://github.com/cloudnative-pg/grafana-dashboards/blob/main/charts/cluster/grafana-dashboard.json

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

@@ -13,7 +13,7 @@ document is the agreed design and the rationale.
 
 - Scheduled phone background backup (the mobile app is used for manual uploads).
 - Multi-user / family accounts and public share links.
-- Off-host/off-site copy — deferred to the planned cloud backup (see Backup).
+- Off-host/off-site copy (see Backup).
 
 ## Decisions
 
@@ -34,7 +34,7 @@ document is the agreed design and the rationale.
 - `services.immich.database.enable = true` and `createDB = true`: the module adds `pgvector` +
   `vectorchord` to `services.postgresql`, sets `shared_preload_libraries = [ "vchord.so" ]`, and
   creates the `immich` database/user. Confirmed present in this flake's nixpkgs: PG 16.15,
-  `pgvector` 0.8.6, `vectorchord` 1.1.1, `immich` 3.2.2.
+  `pgvector` 0.8.6, `vectorchord` 1.1.1, `immich` 3.2.4.
 - `services.immich.redis.enable = false` with `host = "127.0.0.1"` and `port = 6379`: Immich uses
   the shared Valkey instance (`../valkey.nix`) over loopback TCP; the module then passes
   `REDIS_HOSTNAME`/`REDIS_PORT`.

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

@@ -1,11 +1,11 @@
 # Monitoring & Alerting
 
-## Alert Rules & Recoding Rules
+## Alert Rules & Recording Rules
 
 - [awesome-prometheus-alerts](https://github.com/samber/awesome-prometheus-alerts)
   - Collection of Prometheus alerting rules.
 - [victoria-metrics-k8s-stack/files/rules](https://github.com/VictoriaMetrics/helm-charts/tree/master/charts/victoria-metrics-k8s-stack/files/rules/generated)
-  - Alert Rules & Recoding Rules used by kube-prometheus-stack.
+  - Alert Rules & Recording Rules used by kube-prometheus-stack.
 
 ## TODO
 

hosts/12kingdoms-youko/homelab-services/monitoring/alert.nix

@@ -21,8 +21,8 @@
       rule = [
         "${./alert_rules}/*.yml"
         "${./alert_rules}/*.yaml"
-        "${./recoding_rules}/*.yml"
+        "${./recording_rules}/*.yml"
-        "${./recoding_rules}/*.yaml"
+        "${./recording_rules}/*.yaml"
       ];
       # https://docs.victoriametrics.com/victoriametrics/vmalert/#link-to-alert-source
       # Set this two args to generate the correct `.GeneratorURL`

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

@@ -6,3 +6,8 @@ met for a specific resource within its scope, the system generates a triggered a
 actual instance of the condition being met. These rules specify the data to monitor, the trigger
 threshold, and the resulting actions, like sending notifications to specific receivers or performing
 automated tasks.
+
+## How these files are loaded
+
+[`../alert.nix`](../alert.nix) passes every `*.yml` and `*.yaml` in this directory to `vmalert` as a
+rule file; other extensions are ignored. One rule group per file is easiest to review.

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

@@ -5,3 +5,8 @@ evaluated periodically to create new, pre-computed time series metrics.
 
 These rules store the results in a metric backend, significantly speeding up queries for dashboards
 and other alerts, and reducing system load by avoiding the re-computation of data.
+
+## How these files are loaded
+
+[`../alert.nix`](../alert.nix) passes every `*.yml` and `*.yaml` in this directory to `vmalert` as a
+rule file; other extensions are ignored. One rule group per file is easiest to review.

hosts/README.md

@@ -54,9 +54,8 @@ disks.
 #### `k8s` - Kubernetes Infrastructure
 
 - **VM Cluster**: 3 physical mini PCs (shoryu, shushou, youko) running all VMs
-- **K3s Testing**: `k3s-test-1-master-{1,2,3}` (control plane; one per host) +
+- **K3s Testing**: `k3s-test-1` control plane and workers, running as microVMs; placement and
-  `k3s-test-1-worker-{1,2,3}` (workloads; `worker-1` on `shoryu`, `worker-2` on `youko`, `worker-3`
+  rollout are documented in [`k8s/README.md`](./k8s/README.md)
-  on `shushou`), running as microVMs
 
 ### External Systems
 
@@ -65,7 +64,7 @@ disks.
 
 All my riscv64 hosts:
 
-![](/_img/2023-08-16_nixos-riscv-cluster.webp)
+![](../_img/2023-08-16_nixos-riscv-cluster.webp)
 
 ## Naming Conventions
 
@@ -118,22 +117,22 @@ various changes under the hood, so I need to build much more packages than usual
 the reasons why the cluster was originally built, and another reason is distributed building is
 cool!
 
-![](/_img/2023-06-17_nix-distributed-building.webp)
+![](../_img/2023-06-17_nix-distributed-building.webp)
 
-![](/_img/2023-06-17_nix-distributed-building-log.webp)
+![](../_img/2023-06-17_nix-distributed-building-log.webp)
 
 ## References
 
 [Oshi no Ko 【推しの子】 - Wikipedia](https://en.wikipedia.org/wiki/Oshi_no_Ko):
 
-![](/_img/idols-famaily.webp) ![](/_img/idols-ai.webp)
+![](../_img/idols-famaily.webp) ![](../_img/idols-ai.webp)
 
 [The Rolling Girls【ローリング☆ガールズ】 - Wikipedia](https://en.wikipedia.org/wiki/The_Rolling_Girls):
 
-![](/_img/rolling_girls.webp)
+![](../_img/rolling_girls.webp)
 
 [List of Twelve Kingdoms characters](https://en.wikipedia.org/wiki/List_of_Twelve_Kingdoms_characters)
 
-![](/_img/12kingdoms-1.webp) ![](/_img/12kingdoms-Youko-Rakushun.webp)
+![](../_img/12kingdoms-1.webp) ![](../_img/12kingdoms-Youko-Rakushun.webp)
 
 [List of Frieren characters](https://en.wikipedia.org/wiki/List_of_Frieren_characters)

hosts/idols-ai/README.md

@@ -1,7 +1,7 @@
 # Host - AI
 
 Desktop (NixOS + preservation, LUKS + btrfs on nvme). Disk layout is declarative via
-[disko](./disko-fs.nix) (target device: **nvme1n1**).
+[disko](./disko-fs.nix) (target device: the KINGBANK NVMe by `/dev/disk/by-id/`, set in that file).
 
 Related:
 

hosts/idols-akane/README.md

@@ -14,7 +14,7 @@ nixos-install --root /mnt --flake .#akane --no-root-password --show-trace --verb
 
 # enter into the installed system, check password & users
 # `su ryan` => `sudo -i` => enter ryan's password => successfully login
-# if login failed, check the password you set in install-1, and try again
+# if login failed, check the initial password you set in vars/default.nix, and try again
 nixos-enter
 
 reboot

hosts/idols-kana/README.md

@@ -1,3 +1,7 @@
 # Idols - Kana
 
-Run AI Agents
+NixOS VM running under libvirt on `shoryu`, used to run AI agents. It imports the agent and
+computer-use modules from [`idols-ruby`](../idols-ruby/).
+
+- Deploy from the VM with `just local`.
+- Host inventory and role context: [`../README.md`](../README.md).

hosts/idols-ruby/README.md

@@ -1,3 +1,8 @@
 # Idols - Ruby
 
-Run AI Agents
+NixOS VM running under libvirt on `shoryu`, used to run AI agents. It owns the shared agent and
+computer-use modules (`packages.nix`, `computer-use.nix`, `oci-containers/`) that
+[`idols-kana`](../idols-kana/) imports, and is the only host with a `*-nixos-tests` output.
+
+- Deploy from the VM with `just local`.
+- Host inventory and role context: [`../README.md`](../README.md).

hosts/k8s/disko-config/README.md

@@ -3,14 +3,16 @@
 ## Partition the SSD & install NixOS via disko
 
 ```bash
-# enter an shell with git/vim/ssh-agent/gnumake available
+# enter a shell with git/vim/ssh/gnumake available
-nix-shell -p git vim gnumake
+nix-shell -p git vim gnumake openssh
 # clone this repository
 git clone https://github.com/ryan4yin/nix-config.git
 
 cd nix-config
 
 ## 1. partition & format the disk via disko
+# WARNING: `destroy,format,mount` wipes the target disk. host-disko-fs.nix
+# defaults to /dev/nvme0n1; review and edit that device first if the target differs.
 # 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/host-disko-fs.nix
 ## 2. setup the automatic unlock via the tpm2 chip
@@ -21,7 +23,7 @@ sudo nixos-install --root /mnt --no-root-password --show-trace --verbose --flake
 
 # enter into the installed system, check password & users
 # `su ryan` => `sudo -i` => enter ryan's password => successfully login
-# if login failed, check the password you set in install-1, and try again
+# if login failed, check the initial password you set in vars/default.nix, and try again
 nixos-enter
 
 # NOTE: DO NOT skip this step!!!

infra/rustfs/README.md

@@ -4,6 +4,12 @@ RustFS replaced the retired MinIO at `s3.writefor.fun` (console: `s3-console.wri
 service is declared in nix-config on the youko host; this directory manages its buckets/lifecycle
 and documents the IAM setup.
 
+## Installing `rc`
+
+`rc` is RustFS's S3-compatible CLI ([rustfs/cli](https://github.com/rustfs/cli)); it is not in
+nixpkgs. Download the Linux release archive from <https://github.com/rustfs/cli/releases> and put
+the `rc` binary on `PATH`.
+
 ## Credentials
 
 RustFS has no separate "root user" name: the root **access key** acts as the user and the **secret

lib/README.md

@@ -7,25 +7,24 @@ reduce code duplication and make it easier to add new machines.
 
 ### Core System Generators
 
-1. **`attrs.nix`** - Attribute set manipulation utilities
+1. **`macosSystem.nix`** - macOS configuration generator for
-2. **`macosSystem.nix`** - macOS configuration generator for
    [nix-darwin](https://github.com/LnL7/nix-darwin)
-3. **`nixosSystem.nix`** - NixOS configuration generator
+2. **`nixosSystem.nix`** - NixOS configuration generator
-4. **`colmenaSystem.nix`** - Remote deployment configuration for
+3. **`colmenaSystem.nix`** - Remote deployment configuration for
    [colmena](https://github.com/nix-community/colmena)
 
 ### Specialized Module Generators
 
-5. **`genK3sServerModule.nix`** - K3s server node configuration generator
+4. **`genK3sServerModule.nix`** - K3s server node configuration generator
-6. **`genK3sAgentModule.nix`** - K3s agent/worker node configuration generator
+5. **`genK3sAgentModule.nix`** - K3s agent/worker node configuration generator
-7. **`genVmHostModule.nix`** - physical VM host (bridge + libvirt) configuration generator
+6. **`genVmHostModule.nix`** - physical VM host (bridge + libvirt) configuration generator
-8. **`genMicrovmGuestModule.nix`** - NixOS microVM guest configuration generator
+7. **`genMicrovmGuestModule.nix`** - NixOS microVM guest configuration generator
-9. **`genLibvirtDomainXml.nix`** - libvirt domain XML generator (imported directly by host configs)
+8. **`genLibvirtDomainXml.nix`** - libvirt domain XML generator (imported directly by host configs)
 
 ### Entry Point
 
-10. **`default.nix`** - Main entry point that imports the generators and exports them as a single
+9. **`default.nix`** - Main entry point that imports the generators and exports them as a single
-    attribute set, plus the `relativeToRoot` and `scanPaths` helpers
+   attribute set, plus the `relativeToRoot` and `scanPaths` helpers
 
 ## Usage
 

modules/README.md

@@ -64,7 +64,7 @@ modules/
         ├── qemu-guest.nix  # VM guest base module (libvirt/QEMU guests)
         ├── remote-building.nix # Remote build setup
         ├── server-aarch64.nix
-        ├── server-riscv64.nix
+        ├── server-riscv64.nix # module only; the riscv64 output is disabled
         └── server.nix
 ```
 
@@ -107,10 +107,3 @@ Modules are imported based on platform detection:
 - **NixOS Systems**: Import `nixos/` modules
 - **macOS Systems**: Import `darwin/` modules
 - **All Systems**: Import `base/` modules for shared configuration
-
-## Architecture Support
-
-- **x86_64-linux**: Desktop and server configurations
-- **aarch64-linux**: ARM64 Linux systems
-- **aarch64-darwin**: Apple Silicon macOS systems
-- **server-riscv64**: RISC-V server configurations

modules/nixos/desktop/networking/sunshine/README.md

@@ -21,7 +21,7 @@ minor GPU and memory overhead.
 Options:
 
 ```text
--u USER       session user (defaults to SUDO_USER)
+-u USER       session user (defaults to $SUDO_USER, else ryan)
 -t TTY        tty device, for example /dev/tty2
 -c COMMAND    Wayland session command (defaults to niri --session)
 -f, --force   replace an existing Niri session without confirmation

nixos-installer/README.md

@@ -23,13 +23,17 @@ partitioning is no longer needed.
 ## Steps to deploy
 
 1. Create a USB install medium from the official NixOS ISO and boot from it.
+2. Review
+   [`../hosts/idols-ai/hardware-configuration.nix`](../hosts/idols-ai/hardware-configuration.nix)
+   against the target machine before installing; after the disk is mounted, regenerate it with
+   `nixos-generate-config --root /mnt` if the hardware differs.
 
 ### 1. Partition and mount with disko (recommended)
 
-Layout is defined in [../hosts/idols-ai/disko-fs.nix](../hosts/idols-ai/disko-fs.nix): **nvme1n1**,
+Layout is defined in [../hosts/idols-ai/disko-fs.nix](../hosts/idols-ai/disko-fs.nix): the KINGBANK
-ESP (~600M) + LUKS + btrfs (subvolumes: `/` at `/btr_pool`, `@nix`, `@persistent`, `@snapshots`,
+NVMe selected by `/dev/disk/by-id/`, ESP (~600M) + LUKS + btrfs (subvolumes: `/` at `/btr_pool`,
-`@tmp`, `@swap`). Root is tmpfs; [preservation](https://github.com/nix-community/preservation) uses
+`@nix`, `@persistent`, `@snapshots`, `@tmp`, `@swap`). Root is tmpfs;
-`/persistent`.
+[preservation](https://github.com/nix-community/preservation) uses `/persistent`.
 
 ```bash
 git clone https://github.com/ryan4yin/nix-config.git
@@ -38,7 +42,7 @@ cd nix-config/nixos-installer
 sudo su
 
 # encrypt the root partition with luks2 and argon2id, will prompt for a passphrase, which will be used to unlock the partition.
-# WARNING: destroys all data on nvme1n1. Layout is mounted at /mnt by default.
+# WARNING: destroys all data on the target disk. Layout is mounted at /mnt by default.
 nix run github:nix-community/disko -- --mode destroy,format,mount ../hosts/idols-ai/disko-fs.nix
 
 # Mount only (e.g. after first format, without wiping):
@@ -83,8 +87,8 @@ umount -R /mnt
 reboot
 ```
 
-After reboot, set the boot order in firmware so the system boots from nvme1n1. The old disk (e.g.
+After reboot, set the boot order in firmware so the system boots from the newly installed NixOS
-nvme0n1) can be reused for something else.
+disk. The old disk can be reused for something else.
 
 ### Optional: use a cache mirror
 

outputs/README.md

@@ -46,10 +46,10 @@ suite passes when every `expr` equals its `expected`.
 Some tests iterate over every configuration, so a new host is covered automatically and must satisfy
 them. Others name specific hosts and only cover a new host if you add it.
 
-| Kind                | Tests                                                                                                                                                             |
+| Kind                | Tests                                                                                                                                                                                                      |
-| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Every configuration | `hostname`, `kernel`, `nix-system-features`, `security-apparmor`, `security-container-groups`, `security-firewall`, `security-k3s-kubeconfig`, `security-ssh-x11` |
+| Every configuration | `hostname`, `kernel`, `nix-system-features`, `security-apparmor`, `security-container-groups`, `security-exporters`, `security-firewall`, `security-k3s-kubeconfig`, `security-kernel`, `security-ssh-x11` |
-| Named hosts only    | `btrbk`, `home-manager`, `home-manager-xdg`, `computer-use-headless`, `k3s-master-home-manager`, `idols-ai-gpu`, `youko-metrics`, `ups-metrics`, `shoukei-logind` |
+| Named hosts only    | `btrbk`, `home-manager`, `home-manager-xdg`, `computer-use-headless`, `k3s-api-endpoint`, `k3s-master-home-manager`, `idols-ai-gpu`, `youko-metrics`, `ups-metrics`, `shoukei-logind`                      |
 
 `hostname` expects each configuration's `networking.hostName` to equal its name. Niri desktop
 configurations are the exception (`ai-niri` → `ai`, `shoukei-niri` → `shoukei`) and are listed in
@@ -71,7 +71,7 @@ Problems:
       agenix secrets.
   - [ ] Maybe it's better to test every service separately, not the whole host?
 
-How to run NixOS tests for every host:
+How to run a host's NixOS tests:
 
 ```bash
 # Format: nix build .#<name>-nixos-tests
@@ -79,6 +79,8 @@ How to run NixOS tests for every host:
 nix build .#ruby-nixos-tests
 ```
 
+Only `ruby` currently defines a `*-nixos-tests` output.
+
 ## Overview
 
 All the outputs of this flake are defined here.

secrets/README.md

@@ -17,8 +17,9 @@ In this way, all secrets are still encrypted when transmitted over the network a
 In addition, we further improve the security of secret files by storing them in a separate private
 repository.
 
-This directory contains this `README.md`, and a `nixos.nix`/`darwin.nix` file that is used to
+This directory contains this `README.md`, the `Justfile` with the agenix recipes, and the
-decrypt all my secrets via `agenix`. Then, I can use them in this flake.
+`nixos.nix`/`darwin.nix` files that decrypt all my secrets via `agenix`. Then, I can use them in
+this flake.
 
 ## Which Keys Go on a Secret
 
@@ -36,7 +37,8 @@ The one exception is the desktop's own restic repository password (`restic-passw
 
 ## Decrypted File Permissions
 
-`secrets/nixos.nix` and `secrets/darwin.nix` give every secret one of three presets:
+Most secrets in `secrets/nixos.nix` and `secrets/darwin.nix` use one of three shared presets; a few
+set `mode`/`owner` inline:
 
 | Preset          | Mode / owner    | Use for                                          |
 | --------------- | --------------- | ------------------------------------------------ |
@@ -55,7 +57,9 @@ every local account. Always set `user` together with `mode`. nix-darwin ignores
 
 ## Adding or Updating Secrets
 
-> All the operations in this section should be performed in my private repository: `nix-secrets`.
+> The encrypted `.age` files and `secrets.nix` live in my private `nix-secrets` repository. The
+> `Justfile` referenced below lives in this repository and runs its recipes with `working-directory`
+> set to a local `~/codes/nix-secrets` checkout, so invoke it from this repository's root.
 
 This task is accomplished using the [agenix](https://github.com/ryantm/agenix) CLI tool with the
 `./secrets.nix` file, so you need to have it installed first:
@@ -107,7 +111,7 @@ in
 }
 ```
 
-3. Create the secret file `xxx.age` from the repository root with the [`Justfile`](./Justfile)
+3. Create the secret file `xxx.age` from this repository's root with the [`Justfile`](./Justfile)
    `replace` recipe, piping the plaintext on stdin:
 
 ```shell
@@ -199,7 +203,7 @@ Then, create `./secrets/nixos.nix` (or `./secrets/darwin.nix` on macOS) with the
     # whether secrets are symlinked to age.secrets.<name>.path
     symlink = true;
     # target path for decrypted file
-    path = "/etc/xxx/";
+    path = "/etc/xxx";
     # encrypted file path
     file =  "${mysecrets}/xxx.age";  # refer to ./xxx.age located in `mysecrets` repo
     mode = "0400";

vars/README.md

@@ -35,12 +35,8 @@ Comprehensive network configuration including:
 
 ## Host Categories
 
-The networking configuration covers:
+`networking.nix` maps each host to its LAN address and interface. The authoritative inventory is
-
+[`../hosts/README.md`](../hosts/README.md); this file holds only the addresses.
-- **Physical machines**: Desktop PCs, servers, and SBCs
-- **Virtual machines**: VM guests, K3s nodes
-- **Kubernetes clusters**: the `k3s-test-1` testing cluster
-- **Network infrastructure**: Routers, gateways, and DNS configuration
 
 ## Usage