# 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`.