From 1a7cfd9b0ac2e014d6a695b8311564cd2e03f4d6 Mon Sep 17 00:00:00 2001
From: Filippo Berto <filippo.berto@cern.ch>
Date: Mon, 2 Feb 2026 10:49:02 +0100
Subject: [PATCH] Readme file

---
 .markdownlint.json |   4 ++
 README.md          | 125 +++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 129 insertions(+)
 create mode 100644 .markdownlint.json
 create mode 100644 README.md

diff --git a/.markdownlint.json b/.markdownlint.json
new file mode 100644
index 0000000..e3010f0
--- /dev/null
+++ b/.markdownlint.json
@@ -0,0 +1,4 @@
+{
+  "default": true,
+  "MD013": false
+}
\ No newline at end of file
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..3b550fb
--- /dev/null
+++ b/README.md
@@ -0,0 +1,125 @@
+# bertof's NixOS Dotfiles
+
+Personal NixOS configuration repository using flake-parts for modular system management across multiple hosts.
+
+## Architecture
+
+### Structure
+
+- **`flake.nix`** - Main flake definition with flake-parts modularization
+- **`instances/`** - Host-specific configurations (thor, sif, odin, heimdall, baldur)
+- **`hm/`** - Home Manager modules and user configurations
+- **`nixos/`** - NixOS system modules and shared configurations
+- **`pkgs/`** - Custom packages and overlays
+- **`secrets/`** - Encrypted secrets managed with ragenix
+
+### Hosts
+
+- **thor** - AMD desktop system (stable channel)
+- **sif** - Intel desktop system (stable channel)
+- **odin** - Intel laptop/server hybrid
+- **heimdall** - AMD server with self-hosted services
+- **baldur** - Intel server with monitoring services
+
+## Features
+
+### System Management
+
+- **flake-parts** for modular flake structure
+- **Multi-channel support** (stable/unstable nixpkgs)
+- **Hardware-specific configurations** via nixos-hardware
+- **Secret management** with ragenix encryption
+
+### Development & Quality
+
+- **Pre-commit hooks** with nix-git-hooks:
+  - `deadnix` - Remove dead code
+  - `nixpkgs-fmt` - Format Nix code
+  - `statix` - Lint for best practices
+  - `flake-checker` - Validate flake structure
+  - `mdformat` & `markdownlint` - Markdown formatting
+  - `typos` - Spell checking
+
+### Home Manager Integration
+
+- **Modular user configurations** in `hm/`
+- **Development environments** (cpp, go, javascript, kubernetes)
+- **Desktop applications** (alacritty, neovim, browsers)
+- **Custom theming** with nix-rice
+
+### Custom Packages
+
+- `keyboard-switch` - Keyboard layout switcher
+- `wl-clipedit` - Wayland clipboard editor
+- `wl-lockscreen` - Wayland lock screen
+- `wl-update-background` - Background updater
+
+## Usage
+
+### Development Environment
+
+```bash
+nix develop
+```
+
+### Build System
+
+```bash
+nix build .#nixosConfigurations.thor.config.system.build.toplevel
+```
+
+### Deploy Configuration
+
+```bash
+sudo nixos-rebuild switch --flake .#thor
+```
+
+### System Images
+
+Generate deployment images:
+
+```bash
+nix build .#install-iso          # Installer ISO
+nix build .#raw-base-image       # RAW image
+nix build .#vmdk-base-image      # VMware image
+nix build .#aarch64-base-image    # ARM64 image
+```
+
+## Configuration Details
+
+### Channels
+
+- **Stable** (`nixpkgs-s`) - Production systems (thor, sif)
+- **Unstable** (`nixpkgs-u`) - Development and latest packages
+
+### Modules
+
+- **basic** - Core Nix configuration
+- **commonModules** - Shared system modules
+- **mainModules** - Desktop environment modules
+- **homeManagerModules** - User-level configuration
+
+### Services by Host
+
+- **heimdall**: Nextcloud, Immich, Forgejo, Garage, Ollama
+- **baldur**: Vaultwarden, Uptime Kuma, Garage
+- **thor/sif**: Steam, Ollama, Garage, Virtualization
+- **odin**: IP forwarding, Garage, Steam
+
+## Requirements
+
+- Nix with flakes enabled
+- Git for version control
+- ragenix for secret management
+
+## Workflow
+
+1. Make changes to configuration
+1. Pre-commit hooks automatically validate and format
+1. Test with `nix build`
+1. Deploy with `nixos-rebuild switch`
+1. Commit with validated changes
+
+## License
+
+Personal configuration - not intended for redistribution