From 9622d60ff93c577eed8717d7267cf972e19f39e1 Mon Sep 17 00:00:00 2001
From: Thomas Dehaeze <dehaeze.thomas@gmail.com>
Date: Mon, 9 Mar 2026 09:27:31 +0100
Subject: [PATCH] Add CLAUDE.md with repository guidance

---
 CLAUDE.md | 98 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 98 insertions(+)
 create mode 100644 CLAUDE.md

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..5157eaa
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,98 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Overview
+
+This is a **literate dotfiles** repository. All configuration is written in Org-mode files (`.org`), which are then **tangled** (extracted) into actual config files placed at their target paths on the filesystem (e.g., `~/.bashrc`, `~/.config/doom/config.el`).
+
+## How Tangling Works
+
+Each `.org` file contains source code blocks like:
+
+```org
+#+begin_src bash :tangle ~/.bashrc :comments both :mkdirp yes
+# shell code here
+#+end_src
+```
+
+The `:tangle <path>` header arg specifies the destination file. When tangled from Emacs, the code blocks are extracted and written to those paths.
+
+**To tangle a single file** (from within Emacs):
+```
+M-x org-babel-tangle  (or C-c C-v t)
+```
+
+**To tangle all files** (from the command line):
+```bash
+emacs --batch --eval "(require 'org)" --eval '(org-babel-tangle-file "file.org")'
+```
+
+## Key Conventions
+
+- **`#+SETUPFILE: ./setup/org-setup-file.org`** — shared HTML export settings, included at the top of most files
+- **`:noweb yes`** — some blocks use noweb references like `<<get-password(passname="...")>>` which calls named blocks from `emacs-library-babel.org` to fetch passwords from `pass`
+- **`:tangle-mode (identity #o600)`** — some sensitive files (e.g., `~/.netrc`, `~/.smbcredentials`) are tangled with restricted permissions
+- **`:mkdirp yes`** — automatically creates the target directory if missing
+- **`:comments both`** — inserts org link comments into the tangled output so you can navigate back to the source
+
+## Library of Babel (`emacs-library-babel.org`)
+
+Defines reusable named blocks:
+- `get-password` — retrieves a secret from `pass` (the password store)
+- `pdf2svg` — converts PDF figures to SVG/PNG
+- `addhdr` — adds hline to org tables
+
+This file must be loaded in Emacs (via `org-babel-lob-ingest`) for noweb calls to `<<get-password(...)>>` to work during tangling.
+
+## HTML Documentation (`docs/`)
+
+The `.org` files can also be exported to HTML (stored in `docs/`). The `setup/org-setup-file.org` configures the HTML theme. Pre-built HTML is already present; regenerate with `M-x org-export-dispatch` → HTML in Emacs.
+
+## File Map
+
+Each `.org` file corresponds to a tool/topic and tangles to one or more config files:
+
+| File | Tangles to |
+|------|-----------|
+| `applications.org` | `~/.config/mimeapps.list`, `~/.local/share/applications/*.desktop` |
+| `bash.org` | `~/.bashrc`, `~/.bash_profile`, `~/.profile`, `~/.config/readline/inputrc` |
+| `binaries.org` | Scripts in `~/.local/bin/` |
+| `binaries-private.org` | Private/work scripts in `~/.local/bin/` |
+| `calendar-contact.org` | `~/.config/vdirsyncer/`, `~/.config/khal/`, `~/.config/khard/` |
+| `compositor.org` | `~/.config/picom/picom.conf` |
+| `config.org` | `~/.ssh/config`, `~/.XCompose`, `~/.config/fontconfig/`, `~/.netrc`, `~/.smbcredentials`, etc. |
+| `doom.org` | `~/.config/doom/config.el`, `init.el`, `packages.el` |
+| `emacs-snippets.org` | `~/.config/doom/snippets/` |
+| `git.org` | `~/.config/git/config`, `~/.config/pass-git-helper/` |
+| `homelab.org` | Remote files on homelab via TRAMP (`/ssh:thomas@homelab:…`) |
+| `i3.org` | `~/.config/i3/config` |
+| `image.org` | `~/.config/nsxiv/exec/key-handler` |
+| `kitty.org` | `~/.config/kitty/kitty.conf` |
+| `mail.org` | `~/.config/isync/`, `~/.config/msmtp/`, `~/.config/neomutt/` |
+| `matlab.org` | `~/.config/matlab/startup.m`, `~/.config/matlab/setup.m` |
+| `music.org` | `~/.config/mopidy/`, `~/.config/ncmpcpp/` |
+| `polybar.org` | `~/.config/polybar/config.ini`, `~/.config/polybar/scripts/` |
+| `qutebrowser.org` | `~/.config/qutebrowser/config.py`, `~/.config/qutebrowser/userscripts/` |
+| `ranger.org` | `~/.config/ranger/` |
+| `sxhkd.org` | `~/.config/sxhkd/sxhkdrc` |
+| `systemd.org` | `~/.config/systemd/user/` units and associated scripts in `~/.local/bin/` |
+| `tablet.org` | Xournal++ toolbar, Huion tablet setup scripts |
+| `tmux.org` | `~/.config/tmux/tmux.conf` |
+| `torrent.org` | `~/.config/stig/rc`, `~/.config/aria2/` |
+| `vim.org` | `~/.config/nvim/init.vim` |
+| `xconfig.org` | `~/.Xresources`, `~/.config/X11/xinitrc`, `~/.xprofile` |
+| `yazi.org` | `~/.config/yazi/` |
+| `android.org` | Documentation only (no tangle) |
+| `backup.org` | Documentation only (no tangle) |
+| `maintenance.org` | Documentation only (no tangle) |
+| `router.org` | Documentation only (no tangle) |
+| `squeezelite.org` | Documentation only (no tangle) |
+
+## Doom Emacs Notes
+
+When modifying `doom.org` (which tangles `init.el` or `packages.el`), after tangling run:
+```bash
+doom sync
+```
+Then restart Emacs with `SPC q r`.