diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..3c2391f
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,65 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Overview
+
+Personal NixOS flake-based configuration using [Numtide Blueprint](https://github.com/numtide/blueprint) for multi-host management. Manages three hosts with Home Manager for user environments.
+
+## Commands
+
+```bash
+# Rebuild and switch the current host
+sudo nixos-rebuild switch --flake .#$(hostname)
+
+# Test without applying
+sudo nixos-rebuild test --flake .#$(hostname)
+
+# Apply home-manager for a user
+home-manager switch --flake .#julien@LAPTOP-032
+home-manager switch --flake .#jhemono@gwiad
+
+# Update flake inputs
+nix flake update
+nix flake update nixpkgs-unstable   # single input
+```
+
+## Architecture
+
+Blueprint auto-discovers hosts and modules — no manual registration needed.
+
+```
+flake.nix (Blueprint orchestrator)
+modules/
+  nixos/
+    base.nix      — common system settings (bootloader, timezone, Nix store GC, system packages)
+    jhemono.nix   — jhemono user account + SSH authorized keys
+  home/
+    user.nix      — custom options: user.name, user.email
+    base.nix      — shell (Fish), editor (Helix)
+    git.nix       — Git + Jujutsu + GitHub CLI
+hosts/
+  gwiad/          — ThinkPad T14 AMD workstation, Sway/Wayland
+  sesame/         — home server (Forgejo, Nextcloud, Mailu, Nginx, sops-nix secrets)
+  LAPTOP-032/     — work laptop, GNOME
+```
+
+## Hosts
+
+**gwiad** — personal workstation
+- nixos-hardware: `lenovo-thinkpad-t14-amd-gen3`
+- Sway + Waybar, btrbk snapshots, syncthing
+
+**sesame** — home server (`*.hemono.fr` domains)
+- Services: Forgejo (`git`), Nextcloud (`suite`), Mailu (`mail`), Transmission, Syncthing
+- All HTTPS via ACME; SSH-key-only access
+- Secrets via sops-nix (private `mysecrets` repo)
+
+**LAPTOP-032** — work laptop
+- GNOME/GDM, Docker (rootless), claude-code (from `nixpkgs-unstable`), UV, Node.js
+
+## Key Conventions
+
+- `nixpkgs-unstable` overlay is used when a package isn't available or outdated in the stable channel (e.g., `claude-code`)
+- Home Manager modules receive user info via the custom `user.name` / `user.email` options defined in `modules/home/user.nix`
+- Host-specific files live entirely under `hosts/<hostname>/`; shared logic goes in `modules/`