feat: update docs via LLM (#216)

certs/README.md

@@ -3,5 +3,21 @@
 This is my private Private Key Infrastructure (PKI) / Certificate Authority (CA) for my personal
 use. It is used to issue certificates for my own servers and services.
 
-All the private keys are ignored by git, and will be stored in my private secrets repo
+## Current Structure
-[../secrets](../secrets/)
+
+- **ecc-ca.crt** - ECC CA certificate file
+- **ecc-ca.srl** - CA serial number file for certificate tracking
+- **ecc-csr.conf** - OpenSSL configuration file for certificate signing requests
+- **ecc-server.crt** - Server certificate signed by the ECC CA
+- **gen-certs.sh** - Shell script to generate certificates automatically
+
+## Security Notes
+
+All private keys (`.key` files) are ignored by git and stored in a private secrets repository. The
+public certificates and configuration files are committed to this repository for reference.
+
+## Usage
+
+Run `./gen-certs.sh` to generate new certificates using the ECC CA configuration.
+
+See [../secrets](../secrets/) for the corresponding private key management.

hardening/README.md

@@ -12,14 +12,55 @@
   1. Accessing the network when they don't need to.
   1. Accessing hardware devices they don't need.
 
-## Current Status
+## Current Structure
 
-1. **System Level**:
+### 1. **System Level**
-   - [ ] AppArmor
+
-   - [ ] Kernel & System Hardening
+- **AppArmor** (`apparmor/`): AppArmor profiles and configuration
-1. **Per-App Level**:
+- **Kernel & System Hardening** (`profiles/`): System-wide hardening profiles
-   - Nixpak (Bubblewrap, running at user-level)
+
-   - Firejail (a SUID program, meaning it's running as root)
+### 2. **Per-App Level**
+
+- **Nixpak** (`nixpaks/`): Bubblewrap-based sandboxing for applications
+  - Firefox configuration
+  - QQ (Chinese messaging app) configuration
+  - Modular system with reusable components
+- **Firejail** (legacy): SUID-based sandboxing (not used)
+- **Bubblewrap** (`bwraps/`): Direct bubblewrap configurations
+  - WeChat sandboxing configuration
+
+## Current Implementation Status
+
+| Component         | Status    | Notes                          |
+| ----------------- | --------- | ------------------------------ |
+| AppArmor Profiles | 🚧 WIP    | Basic structure in place       |
+| Nixpak Firefox    | ✅ Active | Firefox sandboxing via nixpak  |
+| Nixpak QQ         | ✅ Active | QQ application sandboxing      |
+| Bubblewrap WeChat | ✅ Active | WeChat specific sandboxing     |
+| System Profiles   | 🚧 WIP    | Hardened system configurations |
+
+## Directory Structure
+
+```
+hardening/
+├── README.md
+├── apparmor/           # AppArmor security profiles
+│   └── default.nix
+├── bwraps/            # Direct bubblewrap configurations
+│   ├── default.nix
+│   └── wechat.nix
+├── nixpaks/           # Nixpak application sandboxing
+│   ├── default.nix
+│   ├── firefox.nix
+│   ├── firefox-desktop-item.nix
+│   ├── qq.nix
+│   ├── qq-desktop-item.nix
+│   └── modules/       # Reusable nixpak modules
+│       ├── gui-base.nix
+│       └── network.nix
+└── profiles/          # System hardening profiles
+    └── default.nix
+```
 
 ## Kernel Hardening
 

home/README.md

@@ -1,5 +1,49 @@
 # Home Manager's Submodules
 
-1. `base`: The base module that is suitable for both Linux and macOS.
+This directory contains all Home Manager configurations organized by platform and functionality.
-2. `linux`: Linux-specific configuration.
+
-3. `darwin`: macOS-specific configuration.
+## Current Structure
+
+```
+home/
+├── base/              # Cross-platform home manager configurations
+│   ├── core/          # Essential applications and settings
+│   │   ├── editors/   # Editor configurations (Neovim, Helix)
+│   │   ├── shells/    # Shell configurations (Nushell, Zellij)
+│   │   └── ...
+│   ├── gui/           # GUI applications and desktop settings
+│   │   ├── terminal/  # Terminal emulators (Kitty, Alacritty, etc.)
+│   │   └── ...
+│   ├── tui/           # Terminal/TUI applications
+│   │   ├── editors/   # TUI editors and related tools
+│   │   ├── encryption/ # GPG, password-store, etc.
+│   │   └── ...
+│   └── home.nix       # Main home manager entry point
+├── linux/             # Linux-specific home manager configurations
+│   ├── base/          # Linux base configurations
+│   ├── gui/           # Linux GUI applications
+│   │   ├── hyprland/  # Hyprland window manager
+│   │   ├── niri/      # Niri window manager
+│   │   └── ...
+│   ├── editors/       # Linux-specific editors
+│   └── ...
+└── darwin/            # macOS-specific home manager configurations
+    ├── aerospace/     # macOS window manager
+    ├── proxy/         # Proxy configurations
+    └── ...
+```
+
+## Module Overview
+
+1. **base**: The base module suitable for both Linux and macOS
+   - Cross-platform applications and settings
+   - Shared configurations for editors, shells, and essential tools
+
+2. **linux**: Linux-specific configuration
+   - Desktop environments (Hyprland, Niri)
+   - Linux-specific GUI applications
+   - System integration tools
+
+3. **darwin**: macOS-specific configuration
+   - macOS applications and services
+   - Platform-specific integrations (Aerospace, Squirrel, etc.)

hosts/README.md

@@ -1,22 +1,81 @@
 # Hosts
 
-1. `idols`
+This directory contains all host-specific configurations for my NixOS and macOS systems.
-   1. `ai`: My main computer, with NixOS + I5-13600KF + RTX 4090 GPU, for gaming & daily use.
-   2. `aquamarine`: Kubevirt Virtual Machine.
-      - Monitoring(prometheus, grafana, exporters), CI/CD(gitea, runner), homepage, file browser,
-        and other services.
-   3. `ruby`: Not used now.
-   4. `kana`: Not used now.
-1. `k8s`: My Kubevirt & Kubernetes Clusters
-1. `darwin`(macOS)
-   1. `fern`: MacBook Pro 2022 13-inch M2 16G, mainly for personal use.
-   1. `frieren`: MacBook Pro 2024 14-inch M4Pro 48G, mainly for work.
-1. `12kingdoms`:
-   1. `shoukei`: NixOS on MacBook Pro 2022 M2.
-1. Other aarch64/riscv64 SBCs:
-   [ryan4yin/nixos-config-sbc](https://github.com/ryan4yin/nixos-config-sbc)
 
-## How to add a new host
+## Current Host Inventory
+
+### Physical Machines
+
+#### `idols` - Main Workstations
+
+Named after characters from "Oshi no Ko":
+
+| Host         | Platform    | Hardware              | Purpose               | Status      |
+| ------------ | ----------- | --------------------- | --------------------- | ----------- |
+| `ai`         | NixOS       | i5-13600KF + RTX 4090 | Gaming & Daily Use    | ✅ Active   |
+| `aquamarine` | KubeVirt VM | Virtual               | Monitoring & Services | ✅ Active   |
+| `kana`       | NixOS       | Virtual               | Reserved              | ⚪ Not Used |
+| `ruby`       | NixOS       | Virtual               | Reserved              | ⚪ Not Used |
+
+#### `darwin` - macOS Systems
+
+Named after characters from "Frieren: Beyond Journey's End":
+
+| Host      | Platform | Hardware                   | Purpose      | Status    |
+| --------- | -------- | -------------------------- | ------------ | --------- |
+| `fern`    | macOS    | MacBook Pro M2 13" 16GB    | Personal Use | ✅ Active |
+| `frieren` | macOS    | MacBook Pro M4Pro 14" 48GB | Work Use     | ✅ Active |
+
+#### `12kingdoms` - Homelab Servers & Apple Silicon Linux
+
+Named after "Twelve Kingdoms":
+
+| Host      | Platform | Hardware                               | Purpose                    | Status    |
+| --------- | -------- | -------------------------------------- | -------------------------- | --------- |
+| `shoukei` | NixOS    | MacBook Pro M2                         | NixOS on Apple Silicon     | ✅ Active |
+| `shoryu`  | NixOS    | MoreFine S500Plus (AMD Ryzen 9 5900HX) | KubeVirt Host & K3s Master | ✅ Active |
+| `shushou` | NixOS    | MinisForum UM560 (AMD Ryzen 5 5625U)   | KubeVirt Host & K3s Master | ✅ Active |
+| `youko`   | NixOS    | MinisForum HX99G (AMD Ryzen 9 6900HX)  | KubeVirt Host & K3s Master | ✅ Active |
+
+### Virtual Machines & Clusters
+
+#### `k8s` - Kubernetes Infrastructure
+
+- **KubeVirt Cluster**: 3 physical mini PCs (shoryu, shushou, youko) running all VMs
+- **K3s Production**: 3 masters + 3 workers for production workloads
+- **K3s Testing**: 3 masters for testing and development
+
+#### KubeVirt Host Systems
+
+- **kubevirt-shoryu** - Physical mini PC running KubeVirt/K3s cluster
+- **kubevirt-shushou** - Physical mini PC running KubeVirt/K3s cluster
+- **kubevirt-youko** - Physical mini PC running KubeVirt/K3s cluster
+
+### External Systems
+
+- **SBCs**: aarch64/riscv64 single-board computers managed in
+  [ryan4yin/nixos-config-sbc](https://github.com/ryan4yin/nixos-config-sbc)
+
+## Naming Conventions
+
+- **idols**: Characters from "Oshi no Ko" anime/manga
+- **12kingdoms**: Characters from "Twelve Kingdoms" anime/novel series
+- **darwin**: Characters from "Frieren: Beyond Journey's End" anime/manga
+- **k8s**: Kubernetes-related systems follow standard naming patterns
+
+## How to Add a New Host
+
+The easiest way to add a new host is to copy and adapt an existing similar configuration. All host
+configurations follow similar patterns but are customized for specific hardware and use cases.
+
+### General Process
+
+1. **Identify a similar existing host** from the directory structure above
+2. **Copy the entire directory** and rename it for your new host
+3. **Adapt the configuration files** for your specific hardware and requirements
+4. **Update references** in the flake outputs and networking configuration
+
+### Essential Steps
 
 1. Under `hosts/`
    1. Create a new folder under `hosts/` with the name of the new host.
@@ -36,13 +95,22 @@
    1. Add the new host's static IP address.
    1. Skip this step if the new host is not in the local network or is a mobile device.
 
-## idols - Oshi no Ko
+### File Templates
 
-These four servers are named after the four main characters of the mange/anime Oshi no Ko.
+Use existing hosts as templates. The key files typically include:
 
-## rolling girls
+- `default.nix` - Main host configuration
+- `hardware-configuration.nix` - Auto-generated hardware settings
+- Platform-specific files (e.g., `nvidia.nix`, `apple-silicon.nix`, etc.)
 
-My All RISCV64 hosts.
+### Examples to Reference
+
+- **Desktop systems**: See `idols-ai/` for gaming/workstation setup
+- **Server systems**: See `kubevirt-shoryu/` for K8s/KubeVirt hosts
+- **macOS systems**: See `darwin-fern/` for macOS configurations
+- **Apple Silicon**: See `12kingdoms-shoukei/` for ARM Linux setup
+
+All my riscv64 hosts:
 
 ![](/_img/nixos-riscv-cluster.webp)
 

infra/README.md

@@ -1,6 +1,65 @@
 # Infrastructure as Code
 
-Home for my infra-as-code - terraform configs.
+This directory contains Infrastructure as Code (IaC) configurations using Terraform, primarily for
+managing storage and backend services.
 
-Kubernetes's yaml are stored in a separate repo:
+## Current Structure
-[ryan4yin/k8s-gitops](https://github.com/ryan4yin/k8s-gitops).
+
+```
+infra/
+├── README.md
+└── minio/                    # MinIO S3-compatible storage configurations
+    ├── loki/                 # Loki log storage buckets
+    │   ├── README.md
+    │   ├── loki.tf          # Loki-specific bucket configuration
+    │   ├── main.tf          # Main Terraform configuration
+    │   └── run.sh           # Deployment script
+    └── tf-s3-backend/        # Terraform S3 backend setup
+        ├── README.md
+        ├── main.tf          # Main configuration
+        ├── run.sh           # Deployment script
+        └── tf-s3-backend.tf # Backend bucket configuration
+```
+
+## Services Overview
+
+### MinIO Storage
+
+- **Loki Buckets**: Dedicated storage for Grafana Loki log aggregation
+- **Terraform Backend**: Centralized state management for all Terraform configurations
+
+### External Resources
+
+- **Kubernetes YAML**: Managed in separate repository
+  [ryan4yin/k8s-gitops](https://github.com/ryan4yin/k8s-gitops)
+- **Secrets Management**: Handled via agenix in [../secrets](../secrets/)
+
+## Usage
+
+Each subdirectory contains its own Terraform configuration:
+
+1. **Navigate to specific service**:
+
+   ```bash
+   cd infra/minio/loki
+   ```
+
+2. **Deploy configuration**:
+
+   ```bash
+   ./run.sh
+   ```
+
+3. **Manual deployment**:
+   ```bash
+   terraform init
+   terraform plan
+   terraform apply
+   ```
+
+## Security Considerations
+
+- All storage buckets are configured with appropriate access policies
+- State files are encrypted at rest
+- Access credentials are managed through environment variables
+- Network access is restricted to necessary hosts only

lib/README.md

@@ -1,13 +1,42 @@
 # Library
 
-Some helper functions, used by `flake.nix` to reduce code duplication and make it easier to add new
+This directory contains helper functions used by `flake.nix` to reduce code duplication and make it
-machines:
+easier to add new machines.
 
-1. `attrs.nix`: A set of functions to manipulate attribute sets.
+## Current Functions
-1. `macosSystem.nix`: A function to generate config(attribute set) for
+
-   macOS([nix-darwin](https://github.com/LnL7/nix-darwin)).
+### Core System Generators
-1. `nixosSystem.nix`: A function to generate config(attribute set) for NixOS.
+
-1. `colmenaSystem.nix`: A function that generate config(another function) for remote deployment
+1. **`attrs.nix`** - Attribute set manipulation utilities
-   using [colmena](https://github.com/zhaofengli/colmena).
+2. **`macosSystem.nix`** - macOS configuration generator for
-1. `default.nix`: import all the above functions, and some custom useful functions, and export them
+   [nix-darwin](https://github.com/LnL7/nix-darwin)
-   as a single attribute set.
+3. **`nixosSystem.nix`** - NixOS configuration generator
+4. **`colmenaSystem.nix`** - Remote deployment configuration for
+   [colmena](https://github.com/zhaofengli/colmena)
+
+### Specialized Module Generators
+
+5. **`genK3sAgentModule.nix`** - K3s agent node configuration generator
+6. **`genK3sServerModule.nix`** - K3s server node configuration generator
+7. **`genKubeVirtGuestModule.nix`** - KubeVirt guest VM configuration generator
+8. **`genKubeVirtHostModule.nix`** - KubeVirt host configuration generator
+
+### Entry Point
+
+9. **`default.nix`** - Main entry point that imports all functions and exports them as a single
+   attribute set
+
+## Usage
+
+These functions are designed to:
+
+- Generate consistent configurations across different architectures
+- Provide type-safe configuration for complex systems
+- Enable easy scaling of the infrastructure
+- Support both local development and production deployments
+
+## Architecture Support
+
+- **x86_64-linux**: Primary desktop systems
+- **aarch64-linux**: ARM64 Linux systems (Apple Silicon, SBCs)
+- **aarch64-darwin**: Apple Silicon macOS systems

modules/README.md

@@ -1,5 +1,108 @@
 # NixOS / Nix-Darwin's Submodules
 
-1. `darwin`: macOS-specific configuration.
+This directory contains modular NixOS and Nix-Darwin configurations organized by platform and
-2. `nixos`: NixOS-specific configuration.
+functionality.
-3. `base`: Common configuration for both NixOS and Nix-Darwin.
+
+## Current Structure
+
+```
+modules/
+├── README.md
+├── base/                    # Common configuration for all platforms
+│   ├── default.nix
+│   ├── fonts.nix           # System font configuration
+│   ├── nix.nix            # Nix package manager settings
+│   ├── overlays.nix       # Package overlays
+│   ├── security.nix       # Basic security settings
+│   ├── system-packages.nix # Essential system packages
+│   └── users.nix          # User management
+├── darwin/                  # macOS-specific modules
+│   ├── README.md
+│   ├── apps.nix           # macOS applications
+│   ├── broken-packages.nix # Package compatibility fixes
+│   ├── default.nix
+│   ├── nix-core.nix       # Core Nix configuration
+│   ├── security.nix       # macOS security settings
+│   ├── ssh.nix           # SSH configuration
+│   ├── system.nix        # System-level settings
+│   └── users.nix         # macOS user management
+└── nixos/                   # NixOS-specific modules
+    ├── base/               # Base NixOS configuration
+    │   ├── btrbk.nix      # Backup configuration
+    │   ├── core.nix       # Core system settings
+    │   ├── default.nix
+    │   ├── i18n.nix       # Internationalization
+    │   ├── monitoring.nix # System monitoring
+    │   ├── networking.nix # Network configuration
+    │   ├── nix.nix        # Nix settings
+    │   ├── packages.nix   # System packages
+    │   ├── remote-building.nix # Remote build setup
+    │   ├── ssh.nix        # SSH daemon configuration
+    │   ├── user-group.nix # User and group management
+    │   └── zram.nix       # ZRAM swap configuration
+    ├── desktop.nix         # Desktop environment configuration
+    ├── desktop/            # Desktop-specific modules
+    │   ├── default.nix
+    │   ├── fhs.nix        # FHS environment
+    │   ├── fonts.nix      # Desktop fonts
+    │   ├── guix.nix       # GNU Guix integration
+    │   ├── misc.nix       # Miscellaneous desktop settings
+    │   ├── networking/    # Network-related desktop configs
+    │   │   ├── clash-verge.nix
+    │   │   ├── default.nix
+    │   │   ├── remote-desktop.nix
+    │   │   └── tailscale.nix
+    │   ├── peripherals.nix # Peripheral device configuration
+    │   ├── security.nix   # Desktop security settings
+    │   ├── virtualisation.nix # Virtualization support
+    │   └── xdg.nix       # XDG base directory settings
+    └── server/             # Server-specific modules
+        ├── kubevirt-hardware-configuration.nix
+        ├── server-aarch64.nix
+        ├── server-riscv64.nix
+        └── server.nix
+```
+
+## Module Categories
+
+### 1. **Base Modules** (`base/`)
+
+Common configuration shared between NixOS and macOS:
+
+- System fonts and localization
+- Essential packages and tools
+- Basic security settings
+- User management
+- Package overlays
+
+### 2. **macOS Modules** (`darwin/`)
+
+macOS-specific configuration:
+
+- macOS applications and system settings
+- Security configurations tailored for macOS
+- SSH and system-level settings
+- Package compatibility fixes
+
+### 3. **NixOS Modules** (`nixos/`)
+
+Platform-specific NixOS configuration:
+
+- **Base**: Core system settings and services
+- **Desktop**: Desktop environment and GUI applications
+- **Server**: Server-specific optimizations and services
+
+## Usage
+
+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

overlays/README.md

@@ -5,7 +5,46 @@ Overlays for both NixOS and Nix-Darwin.
 If you don't know much about overlays, it is recommended to learn the function and usage of overlays
 through [Overlays - NixOS & Flakes Book](https://nixos-and-flakes.thiscute.world/nixpkgs/overlays).
 
-1. `default.nix`: the entrypoint of overlays, it execute and import all overlay files in the current
+## Current Structure
-   directory with the given args.
+
-2. `fcitx5`: fcitx5's overlay, add my customized Chinese input method -
+```
-   [小鹤音形输入法](https://flypy.com/)
+overlays/
+├── README.md
+├── default.nix          # Entrypoint for all overlays
+└── fcitx5/              # Chinese input method configuration
+    ├── README.md
+    ├── default.nix      # fcitx5 overlay definition
+    └── rime-data-flypy/ # Custom rime data for 小鹤音形输入法
+        └── share/
+            └── rime-data/
+                ├── build/
+                ├── default.custom.yaml
+                ├── default.yaml
+                ├── flypy.schema.yaml
+                ├── flypy_full全码字.txt
+                ├── flypy_sys.txt
+                ├── flypy_top.txt
+                ├── flypy_user.txt
+                ├── lua/
+                │   └── calculator_translator.lua
+                ├── rime.lua
+                ├── squirrel.custom.yaml
+                └── squirrel.yaml
+```
+
+## Components
+
+### 1. `default.nix`
+
+The entrypoint of overlays, it execute and import all overlay files in the current directory with
+the given args.
+
+### 2. `fcitx5`
+
+fcitx5's overlay, add my customized Chinese input method - [小鹤音形输入法](https://flypy.com/)
+
+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

vars/README.md

@@ -1,3 +1,47 @@
 # Variables
 
-Some common variables that I use in my NixOS configuration.
+Common variables and configuration used across my NixOS and nix-darwin configurations.
+
+## Current Structure
+
+```
+vars/
+├── README.md
+├── default.nix         # Main variables entry point
+└── networking.nix      # Network configuration and host definitions
+```
+
+## Components
+
+### 1. `default.nix`
+
+Contains user information, SSH keys, and password configuration:
+
+- User credentials (username, full name, email)
+- Initial hashed password for new installations
+- SSH authorized keys (main and backup sets)
+- Public key references for system access
+
+### 2. `networking.nix`
+
+Comprehensive network configuration including:
+
+- **Gateway settings**: Main router and proxy gateway configurations
+- **DNS servers**: IPv4 and IPv6 name servers
+- **Host inventory**: Complete mapping of all hosts with their network interfaces and IP addresses
+- **SSH configuration**: Remote builder aliases and known hosts configuration
+- **Network topology**: Physical machines, VMs, Kubernetes clusters, and SBCs
+
+## Host Categories
+
+The networking configuration covers:
+
+- **Physical machines**: Desktop PCs, Apple Silicon systems, SBCs
+- **Virtual machines**: KubeVirt guests, K3s nodes
+- **Kubernetes clusters**: Production and testing environments
+- **Network infrastructure**: Routers, gateways, and DNS configuration
+
+## Usage
+
+These variables are imported and used throughout the configuration to ensure consistency across all
+hosts and maintain centralized network and security settings.