From c16d189164cfe1c33e2d8c7845f0e116cbf210d2 Mon Sep 17 00:00:00 2001
From: Lucien Cartier-Tilet <lucien@phundrak.com>
Date: Thu, 5 Jun 2025 17:26:01 +0200
Subject: [PATCH] docs(README): update README

---
 README.md  | 74 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 README.org | 37 ---------------------------
 2 files changed, 74 insertions(+), 37 deletions(-)
 create mode 100644 README.md
 delete mode 100644 README.org

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..66cda97
--- /dev/null
+++ b/README.md
@@ -0,0 +1,74 @@
+# NixOS Configuration
+
+Personal NixOS configuration for my machines, using Nix Flakes for reproducible and shareable setups.
+
+## Repository Structure
+
+- **flake.nix**: Main entry point for the Nix Flake, defining NixOS and home-manager configurations
+- **hosts/**: Host-specific NixOS configurations
+- **modules/**: Custom NixOS modules reusable across different hosts
+- **programs/**: System-level programs shared across hosts
+- **secrets/**: Encrypted secrets managed with sops-nix
+- **system/**: Common system-level configurations shared across hosts
+- **users/phundrak/**: Home-manager configuration for my user
+- **users/modules/**: Custom user modules reusable across configurations
+
+## Usage
+
+### System Management
+
+Update flake dependencies:
+```bash
+nix flake update
+```
+
+Build and switch to a new system configuration:
+```bash
+sudo nixos-rebuild switch --flake .#<hostname>
+```
+
+Using the Nix Helper (nh) tool:
+```bash
+# Build and activate a new configuration, making it the boot default
+nh os switch
+
+# Build a new configuration and make it the boot default
+nh os boot
+
+# Build and activate a new configuration (without making it the boot default)
+nh os test
+
+# Just build a new configuration
+nh os build
+```
+
+### Home Configuration
+
+Update and switch to a new home configuration:
+```bash
+nh home switch
+```
+
+Format Nix files (using Alejandra):
+```bash
+nix fmt
+```
+
+## Development
+
+For development, a devShell is provided with linting tools and git hooks:
+
+```bash
+nix develop
+```
+
+This will set up an environment with:
+- alejandra (formatting)
+- commitizen (commit messages)
+- deadnix (dead code detection)
+- statix (linting)
+- Other useful git hooks
+
+## Contributing
+
+Feel free to fork this repository and make your own changes. If you have any improvements or suggestions, please open an issue or submit a pull request.
\ No newline at end of file
diff --git a/README.org b/README.org
deleted file mode 100644
index 137d833..0000000
--- a/README.org
+++ /dev/null
@@ -1,37 +0,0 @@
-#+title: NixOS Configuration
-#+author: Lucien Cartier-Tilet <lucien@phundrak.com>
-
-This repository contains the NixOS configuration for my personal
-setup. It uses Nix Flakes to manache the configuration, making it
-reproducible and easy to share across my different machines.
-
-* Repository Structure
-- =flake.nix= :: The main entry point for the Nix Flake. It defines my
-  NixOS configurations as well as a dev shell which installs the tools
-  needed for testing and building my configurations.
-- =hosts/= :: Directory containing host-specific configurations. Each
-  host has its own directory with at least a =configuration.nix= file.
-- =modules/= :: Custom NixOS modules that can be reused across different
-  hosts.
-- =programs/= :: Programs shared across hosts at the system level that
-  are not made into configurable modules.
-- =secrets/= :: Contains secret values that I cannot or will not share
-  publicly.
-- =system/= :: Common system-level configuration shared across hosts
-  that are not made into configurable modules.
-- =users/phundrak/= :: My home-manager configuration, containing
-  user-specific settings and applications.
-- =users/modules/= :: Custom user NixOS modules that can be reused
-  across different users.
-- =user/scripts/= :: Custom shell scripts shared across users.
-
-* Updating and Rebuilding the Configuration
-In this repository, there are two helper scripts:
-- =update.sh= :: Updates the Flake’s lockfile.
-- =rebuild.sh= :: Rebuilds the configuration and switch to it
-  immediately.
-
-* Contributing
-Feel free to fork this repository and make your own changes. If you
-have any improvements or suggestions, please open an issue or submit a
-pull request.